GamesAI-v0.7.2.mcdr

GamesAI 0.7.2

本次更新把上下文管理从"看不见"变成"看得见"，并修掉了三个真实缺陷。

🔍 上下文查看：三条只读指令

• !!ask context [玩家] — 窗口多大、来源是哪一层（配置覆盖 / 模型表 / 默认值）、上下文占了多少、距离压缩还有多少余量、逐轮规模与缓存命中率。不填玩家即查看自己。悬停可看三条触发线的具体数值、逐轮 token、上次请求用量与最近一次压缩。
• !!ask context --all — 按模型汇总全服用量，零用量的模型不列出；悬停显示自插件加载以来的累计消耗与缓存命中率（0.1% 精度）。累计值不会因压缩而减少。
• !!ask compact — 忽略触发线，立即压缩较早的历史；延迟到下次提问的预检执行，指令本身不阻塞。

🔧 修复

• !!ask stop it. 不再被丢弃 — 以前 stop 是独立命令节点，带多余文字会被 MCDR 判为未知参数并整条不执行；!!ask switch it. 则把 it. 当模型名。现在 !!ask 由命令分发器解析，只有恰好是那个词才当子指令，任何句子都会落到 AI。顺带修好 !!ask -n（缺内容）与 !!ask contextual 被前缀吞掉的问题。
• 两次 !!gamesai reload 并发会把假人功能关掉 — 后者的端口探测把前者未退出的 Node 当成外来程序，进而把 mineflayer_bot.enabled 写成 false。现在重载单飞（重入直接拒绝），端口探测会先等待停机完成。
• mineflayer_bot.enabled 被误关闭 — 写 config.json 前先确保目录存在；stop_mineflayer_bot 补上缺失的 @register_bot_tool()。

🧹 卸载与停机不再被假人拖住

• Node 停机从"逐级升级、最多串行等 21 秒"改为一次终止 + 有限等待，实测 5 毫秒；
• 卸载把停机搬到独立后台线程，on_unload 只同步等 1.5 秒；该线程只用纯 Python 对象，不碰 MCDR 状态；
• 首次连接退避（新配置项 first_connect_interval，默认 0.5 秒），不再因为 Node 还在启动就白等 10 秒。

🧵 线程可观测

• 新增 !!gamesai debug thread：列出插件持有的线程（id、名称、daemon、native=）；
• 全部线程统一命名 games_ai@...；卸载后残留的旧控制器线程会在下次加载时被中止，而不是与新实例并存。

📚 文档重写与新增

• 原「工具与 Skills」一页拆分为独立的工具与技能，并按当前实现重写：补齐权限与 Bot 可见性两列、修正与代码不符的参数说明（如 delegate_to_bot 的 username、bot_call_action 的可选参数）、说明 tools.py 中无装饰器的公开函数会被拒绝加载；
• 新增**范例**：一台真实服务器从配置、六个技能、44 个自定义工具到一轮实操的完整实例，含踩坑表与取舍分析；
• 技术文档现为九个页面，随插件一起打包。

升级提示

• 版本号由 0.7.2-SNAPSHOT-4 定为 0.7.2；旧配置里的历史长度键（如 max_history）会被忽略，无需改动。
• 新增可选配置 mineflayer_bot.websocket.first_connect_interval（默认 0.5），不填也会按此默认值工作。

完整说明见 docs/zh_cn/changelog.md。

---

GamesAI 0.7.2

This release makes context management visible instead of invisible, and fixes three real defects.

🔍 Context Inspection: three read-only commands

• !!ask context [player] — the window size, which layer it comes from (config override / model table / default), how much context is in use, how many tokens are left before compression, the per-round sizes and the cache hit rate. Without a player name it shows your own. The hover adds the exact trigger lines, the per-round tokens, the last request's usage and the last compression.
• !!ask context --all — the whole server summed up per model, with models that have zero usage left out; the hover shows the totals since the plugin was loaded plus the cache hit rate (0.1% resolution). Those totals never shrink when a history is compressed.
• !!ask compact — compress the older history now, ignoring the triggers; it is deferred to the preflight of your next question, so the command itself never blocks.

🔧 Fixes

• !!ask stop it. is no longer dropped — stop used to be its own command node, so extra text made MCDR reject the whole line as an unknown argument and execute nothing; !!ask switch it. instead took it. as a model name. !!ask is now parsed by a command dispatcher where only exactly that word acts as a subcommand, so any sentence reaches the model. A bare !!ask -n and words like !!ask contextual are fixed along the way.
• Two concurrent !!gamesai reload used to switch the bot off — the second one's port probe saw the first one's dying Node process as a foreign program and wrote mineflayer_bot.enabled = false. Reloads are now single-flight (a re-entry is rejected), and the port probe waits for a running teardown first.
• mineflayer_bot.enabled switched off by mistake — the directory is created before config.json is written, and stop_mineflayer_bot got its missing @register_bot_tool().

🧹 Unload and shutdown no longer held hostage by the bot

• Node shutdown went from an escalating ladder that could wait up to 21 s in series to one terminate plus a bounded wait — measured at 5 ms;
• the unload hands the slow half to a detached background thread and waits 1.5 s synchronously; that thread only touches plain Python objects, never MCDR state;
• first-connect backoff (new option first_connect_interval, default 0.5 s) instead of sleeping 10 s merely because Node is still booting.

🧵 Threads are observable

• New !!gamesai debug thread: lists the threads the plugin holds (id, name, daemon flag, native=);
• every thread is named games_ai@...; a controller thread that survived an unload is aborted on the next load instead of running next to the new instance.

📚 Documentation rewritten and extended

• The former "Tools & Skills" page was split into separate Tools and Skills pages and rewritten against the current implementation: a permission and a bot-visibility column were added, parameter descriptions that did not match the code were corrected (delegate_to_bot's username, bot_call_action's optional params), and the loader's behaviour of rejecting undecorated public functions in tools.py is now documented;
• a new Example page walks through a real server end to end: its configuration, six skills, 44 custom tools, one actual round of use, and the pitfalls;
• the technical documentation is now nine pages and ships inside the plugin archive.

Upgrade notes

• The version is 0.7.2 (was 0.7.2-SNAPSHOT-4); a history-length key left over from an older config (such as max_history) is ignored, so no config change is required.
• New optional option mineflayer_bot.websocket.first_connect_interval (default 0.5); leaving it out uses that default.

Full details: docs/en_us/changelog.md.

---

GamesAI 0.7.2

本次更新把上下文管理從「看不見」變成「看得見」，並修掉三個真實缺陷。

🔍 上下文檢視：三條唯讀指令

• !!ask context [玩家] — 視窗多大、來源是哪一層（設定覆寫 / 模型表 / 預設值）、上下文佔了多少、距離壓縮還剩多少餘量、逐輪規模與快取命中率。不填玩家即查看自己。懸停可看三條觸發線的具體數值、逐輪 token、上次請求用量與最近一次壓縮。
• !!ask context --all — 按模型彙總全服用量，零用量的模型不列出；懸停顯示自插件載入以來的累計消耗與快取命中率（0.1% 精度）。累計值不會因壓縮而減少。
• !!ask compact — 忽略觸發線，立即壓縮較早的歷史；延後到下次提問的預檢執行，指令本身不阻塞。

🔧 修復

• !!ask stop it. 不再被丟棄 — 以前 stop 是獨立指令節點，帶多餘文字會被 MCDR 判為未知參數並整條不執行；!!ask switch it. 則把 it. 當模型名。現在 !!ask 由指令分派器解析，只有恰好是那個詞才當子指令，任何句子都會落到 AI。順帶修好 !!ask -n（缺內容）與 !!ask contextual 被前綴吞掉的問題。
• 兩次 !!gamesai reload 並行會把假人功能關掉 — 後者的連接埠探測把前者未結束的 Node 當成外來程式，進而把 mineflayer_bot.enabled 寫成 false。現在重載單飛（重入直接拒絕），連接埠探測會先等待停機完成。
• mineflayer_bot.enabled 被誤關閉 — 寫 config.json 前先確保目錄存在；stop_mineflayer_bot 補上缺失的 @register_bot_tool()。

🧹 卸載與停機不再被假人拖住

• Node 停機從「逐級升級、最多串行等 21 秒」改為一次終止 + 有限等待，實測 5 毫秒；
• 卸載把停機搬到獨立背景執行緒，on_unload 只同步等 1.5 秒；該執行緒只用純 Python 物件，不碰 MCDR 狀態；
• 首次連線退避（新設定項 first_connect_interval，預設 0.5 秒），不再因為 Node 還在啟動就白等 10 秒。

🧵 執行緒可觀測

• 新增 !!gamesai debug thread：列出插件持有的執行緒（id、名稱、daemon、native=）；
• 全部執行緒統一命名 games_ai@...；卸載後殘留的舊控制器執行緒會在下次載入時被中止，而不是與新實例並存。

📚 文件重寫與新增

• 原「工具與 Skills」一頁拆分為獨立的工具與技能，並按當前實作重寫：補齊權限與 Bot 可見性兩欄、修正與程式碼不符的參數說明（如 delegate_to_bot 的 username、bot_call_action 的可選參數）、說明 tools.py 中無裝飾器的公開函式會被拒絕載入；
• 新增**範例**：一台真實伺服器從設定、六個技能、44 個自訂工具到一輪實操的完整實例，含踩坑表與取捨分析；
• 技術文件現為九個頁面，隨插件一起打包。

升級提示

• 版本號由 0.7.2-SNAPSHOT-4 定為 0.7.2；舊設定裡的歷史長度鍵（如 max_history）會被忽略，無需改動。
• 新增可選設定 mineflayer_bot.websocket.first_connect_interval（預設 0.5），不填也會按此預設值運作。

完整說明見 docs/zh_tw/changelog.md。