nexforge-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{nexforge_cli-0.5.0 → nexforge_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.5.0
+Version: 0.7.0
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge
@@ -51,14 +51,15 @@ Description-Content-Type: text/markdown
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.5.0** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.7.0** · PyPI: `pip install nexforge-cli`
 
-**v0.4.1 要点（重要修复）**：会话重建时，**内容里出现的 `<!-- nf-msg … -->` 不再被当成消息边界**。
-此前若工具结果 dump 过会话文件（或粘贴过会话内容），加载时那些标记会被解码成额外消息、
-插进工具块中间，导致**每轮请求 400、项目再也打不开**。
-修法：读侧标记识别改为**行首锚定**，写侧对内容里的标记前缀做转义；同时把工具序列修复
-从"只修尾部"升级为"修全序列"（中段违规也能纠正）。
-另含 0.4.0 推出的：本机 TTS 优先/回退、模型随 nf 常驻、`/voice full|brief`、配置残留值自动收敛。
+**v0.7.0 要点（MCP 外部工具接入）**：可以用 `[[mcp.servers]]` 挂载 MCP server,
+把第三方工具(文件系统/GitHub/数据库等)接进 AI 工具箱。外部工具统一注册为
+`mcp__<server>__<tool>` —— **无法覆盖内置工具**(外部进程不能改写能力面), 也便于按来源授权;
+默认需审批(`require_approval`), 并提供 `/mcp` 查看连接状态与失败原因。工具数有闸门
+(`[mcp] max_tools` + server 级 `tools` 白名单), 防止上下文被几十个外部工具挤爆。
+(上一版 0.6.0 要点: 新增 `wait` / `wait_until` 精确等待与条件轮询, 并按参数豁免 60 秒
+单工具超时上限; `stop_job` 与退出清理改为终止整个进程树; 内置工具 39 → 41。)
 
 ---
 

{nexforge_cli-0.5.0 → nexforge_cli-0.7.0}/README.md

@@ -8,14 +8,15 @@
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.5.0** · PyPI: `pip install nexforge-cli`
-
-**v0.4.1 要点（重要修复）**：会话重建时，**内容里出现的 `<!-- nf-msg … -->` 不再被当成消息边界**。
-此前若工具结果 dump 过会话文件（或粘贴过会话内容），加载时那些标记会被解码成额外消息、
-插进工具块中间，导致**每轮请求 400、项目再也打不开**。
-修法：读侧标记识别改为**行首锚定**，写侧对内容里的标记前缀做转义；同时把工具序列修复
-从"只修尾部"升级为"修全序列"（中段违规也能纠正）。
-另含 0.4.0 推出的：本机 TTS 优先/回退、模型随 nf 常驻、`/voice full|brief`、配置残留值自动收敛。
+> 当前版本:**v0.7.0** · PyPI: `pip install nexforge-cli`
+
+**v0.7.0 要点（MCP 外部工具接入）**：可以用 `[[mcp.servers]]` 挂载 MCP server,
+把第三方工具(文件系统/GitHub/数据库等)接进 AI 工具箱。外部工具统一注册为
+`mcp__<server>__<tool>` —— **无法覆盖内置工具**(外部进程不能改写能力面), 也便于按来源授权;
+默认需审批(`require_approval`), 并提供 `/mcp` 查看连接状态与失败原因。工具数有闸门
+(`[mcp] max_tools` + server 级 `tools` 白名单), 防止上下文被几十个外部工具挤爆。
+(上一版 0.6.0 要点: 新增 `wait` / `wait_until` 精确等待与条件轮询, 并按参数豁免 60 秒
+单工具超时上限; `stop_job` 与退出清理改为终止整个进程树; 内置工具 39 → 41。)
 
 ---
 

{nexforge_cli-0.5.0 → nexforge_cli-0.7.0}/config.example.toml

@@ -45,5 +45,23 @@ cosyvoice_url = "http://127.0.0.1:9880"    # 本机 CosyVoice 常驻服务(其 l
 cosyvoice_voice = "default"                # 本机服务音色 id
 cosyvoice_timeout_s = 90                   # 冷启动约 20s, 留足余量
 cosyvoice_resident = true                  # nf 在跑就让模型常驻显存; nf 全退出后由服务立即卸载
+stream = true                              # 流式播报(首块约 2s 就开口); false = 整句合成完再播
+instruct = ""                              # 风格指令(如 "用自然亲切的语气说"); 空 = 不用指令
 max_chars = 0                              # 播报文本上限(0=不限; 配合下面的 mode)
 mode = "full"                              # 播报范围: full=全量播报最终报告(默认) | brief=只播第一段(/voice 切换)
+
+# MCP 外部工具服务(默认不启用)。下面是配置模板, 取消注释并按需修改;
+# 完整说明(命名/权限/排错/成本)见 manual/12-MCP接入.md。
+#
+# [[mcp.servers]]
+# name = "filesystem"                      # 唯一标识, 同时是工具名前缀(mcp__<name>__<tool>)
+# command = "npx"                          # stdio: 可执行文件(当前仅支持 stdio)
+# args = ["-y", "@modelcontextprotocol/server-filesystem", "D:/work"]
+# env = { SOME_TOKEN = "..." }             # 可选: 追加环境变量
+# tools = ["read_file", "list_directory"]  # 可选: 工具白名单(空 = 该 server 的全部工具)
+# require_approval = true                  # 默认 true: 每次调用需审批(外部进程与 run_background 同级)
+# enabled = true
+#
+# [mcp]
+# max_tools = 40                           # 注入工具 schema 的 MCP 工具总数上限(超出截断并提示)
+# connect_timeout = 15.0                   # 单个 server 连接/握手超时(秒)

nexforge_cli-0.7.0/docs/decisions/2026-09-12-/347/255/211/345/276/205/345/267/245/345/205/267/344/270/216/350/266/205/346/227/266/345/217/257/350/261/201/345/205/215.md

@@ -0,0 +1,127 @@
+# 决策：等待用专门的工具 + 可声明超时，不再靠 Shell 拼命令
+
+> 日期：2026-09-12 · 状态：生效
+
+## 背景
+
+实际使用中"等一会儿再执行"是高频诉求（等 dev server 起来、等构建产物落盘、
+等接口限流恢复、等 CI 回包）。但加这两个工具之前，**没有任何一种等待手段是可靠的**，
+模型只能即兴发挥，于是方法五花八门、结果时好时坏。实测（详见
+`docs/evidence/wait-tool.log`）：
+
+| 它常试的办法 | 实测结果 |
+|---|---|
+| `run_shell("sleep 30")` | cmd 无 `sleep` 命令，直接报错 |
+| `run_shell("timeout /t 30")` | 无交互控制台 → **0.03s 就返回**（以为等了 30s，实际 0s，且 rc=1） |
+| `run_shell("ping -n 30 127.0.0.1 >nul")` | 能等，但仅 Windows、1 秒粒度、污染输出 |
+| `run_shell("powershell Start-Sleep -Seconds 30")` | 能用，但更慢且带 profile 告警噪音 |
+| 反复 `job_output` / `health_check` 轮询 | 烧工具轮数（上限 300）与 token，且只能等"命令退出" |
+
+三处结构性障碍让"等待"注定失败：
+
+1. **全局 `tools.tool_timeout=60` 硬顶**（`core/agent.py` 的 `_exec_tool` 用
+   `asyncio.wait_for` 包住整个工具）→ 任何 >60s 的等待必然判"工具执行超时"。
+   而等待 5 分钟是正当需求（编译、镜像构建、限流恢复）。
+2. **超时后线程仍在跑**：`asyncio.to_thread` 里的线程不可取消（实测：asyncio 1.00s
+   放弃等待，工作线程继续跑完）。于是"停止/Esc/退出"对等待无效，用户以为停了，
+   线程还在睡。
+3. **语义错配**：真正的需求大多是"等到条件成立"（端口可连 / 文件出现 / HTTP 200 /
+   日志出现关键字），而当时唯一沾边的 `wait_for_job` 只能等"作业退出" —— 常驻的
+   dev server 永不退出，必然超时失败。
+
+## 决策
+
+1. **新增 `wait` 与 `wait_until` 两个工具**（`tools/wait_tools.py`），纯 Python 实现，
+   **不起子进程** → 跨平台一致、无编码坑：
+   - `wait(seconds, reason)`：精确计时（支持小数秒）；
+   - `wait_until(until, target, expect, timeout, interval)`：条件轮询，
+     `until ∈ {port, file, http, log}`，超时返回**最后一次探测证据**。
+2. **等待可中断**：新建 `core/waits.py`（进程级 `threading.Event` + `sleep()`），
+   每 0.05s 检查一次；UI 的停止 / Esc / 退出 / 切会话 / Web 面板停止 /
+   总监目标模式停止、删除会话（`session_feature.py`），**七处**取消路径统一调用 `waits.interrupt()`。
+   同时把 `jobs.wait()` 的 `time.sleep(0.1)` 轮询改为可中断睡眠，
+   **顺手修掉 `wait_for_job` 同款"停止无效"的暗坑**。
+3. **超时可声明，但有硬顶**：`BaseTool.timeout_for(args) -> float | None`（默认 `None`），
+   上限 = `min(max(全局 tool_timeout, 声明值), MAX_TOOL_TIMEOUT=3600s)` —— 硬顶防的是
+   “第三方/插件工具声明天文数字 → 一次调用把会话钉死”。
+   两个等待工具按 `等待秒数 + 15s 余量` 声明；`wait_for_job` 同步补上。
+4. **单次等待上限 600 秒 + 明确拒绝**：超限直接返回错误（"单次等待上限 600 秒"），
+   **不做静默截断** —— 静默截断会让模型以为自己等了 1 小时。
+5. **新一轮复位**：`AgentLoop.run_turn` 开头 `waits.reset()`，否则一次取消会永久
+   毒化后续所有等待（`wait` 永远立刻返回"已中断"）。
+6. `wait` / `wait_until` 归**只读**（`permissions.py`），等待不需要审批；
+   并加入总监只读白名单 —— 它改不了仓库、也起不了进程。
+7. **让模型用得上**：`DEFAULT_SYSTEM` 补一句需要等待/延时用 wait 或 wait_until、
+   不要用 sleep/timeout/ping/Start-Sleep 拼命令 —— 只在工具 description 里写不够，
+   系统提示才是行为纪律的落点（与“修改文件用 edit_file”同源）。
+
+## 理由
+
+- **为什么不做成"只是 sleep 一下"**：计时精确从来不是瓶颈（`time.sleep` 本身就准），
+  瓶颈是"等待被 60s 上限砍死"和"等待不可中断"。只加 sleep 工具不改机制，等于白做。
+- **为什么用进程级 Event 而不是 asyncio 事件**：工具跑在 `to_thread` 的工作线程里，
+  与事件循环不同线程；线程不可取消，只能主动查询一个线程安全的标记。
+- **为什么不让 wait 工具自己接受 `timeout` 参数**（即读取全局上限）：全局上限是
+  "防单点卡死"的产品设定，不该被单个工具绕过；用声明式钩子把"放宽多少"交回工具，
+  Agent 只做 `max` 合并，审计点唯一（`_exec_tool` 一处）。
+
+**否决的备选**：
+
+| 备选 | 否决理由 |
+|---|---|
+| 继续用 `run_shell` 拼 sleep/timeout/ping | 实测全不可靠（上表）；且 `run_shell` 属 danger 类，每次等待都要用户点审批 |
+| 调大全局 `tool_timeout` | 会一并削弱网络类工具的快速失败保护，风险外溢到所有工具 |
+| 等待超 60s 就分段返回"请再调一次" | 轮数与 token 翻倍，且模型可能忘记继续（或把它当成失败） |
+| 扩展 `wait_for_job` 支持任意条件 | 名字与语义不符，会模糊"作业"概念、伤已有用例 |
+| 靠 provider 重试层解决 | "等 CI / 等端口"是 agent 层语义，不属于 provider 的失败重试范畴 |
+| 插件 / MCP 外挂实现 | 等待是高频核心能力，不该外挂；且增加工具计数与管理成本 |
+
+## 代价与边界
+
+- **`tool_timeout = 0` = 不限额**（2026-09-12 统一语义）：此前传 0 会让
+  `asyncio.wait_for(..., 0)` 立刻判超时 —— 一个看起来像"不限额"的配置, 实际让所有工具
+  一调就失败。现在 0 转成 `timeout=None`（无限等待），与 `turn_timeout = 0` 的约定一致；
+  代价是关掉了工具级超时保护，属用户显式选择（默认仍是 60s）。
+- **Token 成本**：工具 schema 从 39 → 41 个（约 +0.2k tokens/次请求）。在"工具 schema
+  已 ~7.7k tokens"的现状下可接受，但**不再轻易加工具**这条纪律应当继续。
+- **600s 上限是产品选择**：需要更久的等待应拆成多次调用，或改用 `run_background`
+  起任务 + `wait_for_job`。上限值集中定义在 `wait_tools.MAX_WAIT_SECONDS`。
+- **`wait_until` 会产生真实探测请求**（连端口 / 发 HTTP GET / 读文件）：
+  在受限网络下 `http` 探测会慢（每次 5s 超时），此时应改用 `log` 或 `file` 观察本地信号。
+- **Esc 路径下模型看到的是会话修复层的回执**（"已取消(中断/超时)。"），而不是 wait 的
+  中断文案 —— 因为 Esc 会同时取消 worker，工具结果被丢弃（`_repair_tool_sequence` 补一条
+  合法响应防 400）。`waits.interrupt()` 的价值是**让等待线程立刻退出**，不是改文案。
+  真机结论见 `docs/evidence/wait-tool.log` 的 E 节。
+- **探测自身的耗时计入 timeout 预算**（2026-09-12 真机检查后修）：`port` / `http` 探测
+  本身也要耗时（本机对未监听端口的 connect 是 **2 秒超时**而非立即拒绝），不计入预算
+  会让 `timeout=3` 的请求实测用 **5 秒**（语义失真）。现把剩余预算交给探测函数
+  （`port` ≤2s、`http` ≤5s，且不超预算），并由 `test_wait_until_respects_timeout_budget`
+  钉住"实际耗时 ≤ timeout + 容差"。
+- **不引入新的导入负担**：`wait_tools` 顶层**不** import httpx（只有 `until=http`
+  时才延迟导入，与 `image_tools` 同做法）。httpx 的导入链在 Windows 上会拉 click
+  （硬依赖 `ctypes.windll`）—— 让“等文件/等端口”这类纯本地条件付出无谓代价，也会
+  让“无 windll 环境”的导入检查失败（已由 `test_cross_platform.py` 的模块清单钉住）。
+- **中断是"协作式"的**：只对走 `core/waits.py` 的等待生效。`run_shell` 里正在跑的长
+  命令仍然不可中断（它阻塞在 `subprocess.run`）—— 这是本次**未解决**的边界，
+  遇到需要中断的长命令，应改用 `run_background` + 停止。
+- 若将来把"回合内取消"升级为硬取消（如杀进程组），`waits` 应随之收敛为唯一入口。
+- 顺手校正了一处**既有文档漂移**：手册/投稿文档写"内置 35 个工具"，而
+  `default_registry()` 实际已 39 个（`tests/test_manual_consistency.py` 钉的是 39）。
+  本次统一为真实的 41。
+
+## 关联
+
+- 代码：`src/nexforge/tools/wait_tools.py`、`src/nexforge/core/waits.py`、
+  `src/nexforge/tools/base.py`（`timeout_for`）、`src/nexforge/core/agent.py`
+  （`_exec_tool` 上限合并、`run_turn` 复位）、`src/nexforge/core/jobs.py`（可中断等待）、`src/nexforge/core/session.py`（`DEFAULT_SYSTEM` 引导）、
+  `src/nexforge/core/permissions.py`、`src/nexforge/core/goal_manager.py`、
+  `src/nexforge/ui/screens/chat.py`、`chat_actions.py`、`ui/slash_handler.py`、`features/session_feature.py`、
+  `web/server.py`
+- 测试：`tests/test_wait_tools.py`（21 项）
+- 证据：`docs/evidence/wait-tool.log`
+- 手册：`manual/04-工具参考.md`（含"等待与条件轮询"小节）、`manual/09-常见问题.md`
+- 相关决策：[终端状态兜底恢复](2026-09-11-终端状态兜底恢复.md)（同样是"取消/退出 vs
+  线程与等待"的关切）、[Fails Loud 分级](2026-09-10-fails-loud分级.md)
+  （超限明确拒绝而非静默截断）
+- 后续：[杀进程必须杀整棵树](2026-09-12-进程树终止.md) —— 本次检查暴露的
+  "僵尸端口误报就绪"由它修复

nexforge_cli-0.7.0/docs/decisions/2026-09-12-/350/277/233/347/250/213/346/240/221/347/273/210/346/255/242.md

@@ -0,0 +1,65 @@
+# 决策：杀进程必须杀整棵树（`shell=True` 的孙进程会变孤儿）
+
+> 日期：2026-09-12 · 状态：生效
+
+## 背景
+
+`run_background` 起的长任务（dev server / 监听 / 下载）在 Windows 上是经
+`cmd.exe /c <cmd>` 启动的，真正的服务是 cmd 的**子进程**。原来的停止/退出清理用
+`Popen.terminate()`，只终结 cmd —— 真机实测：
+
+```
+run_background("python -m http.server 18234")
+stop_job(1)                     → 作业显示"已退出(code 1)"
+netstat -ano | findstr 18234
+  TCP 127.0.0.1:18234  LISTENING  22088    ← python.exe 还活着
+```
+
+影响面：
+
+1. dev server "停不掉"，端口被占，下次启动报端口冲突；
+2. 退出 nf 后进程累积（每起停一次泄漏一个）；
+3. **`wait_until(port=...)` 会对"僵尸端口"误报"服务已就绪"** —— 等到的其实是上一轮的
+   进程，给出错误结论。这一条是 2026-09-12 加等待工具后暴露出来的，也是本次决策的触发点。
+
+## 决策
+
+`core/jobs.py` 的两条停止路径（`stop()` 与 `shutdown_all()`）统一走 `_terminate_tree()`：
+
+- **Windows**：`taskkill /F /T /PID <pid>`（`/T` 递归杀子孙），带 `CREATE_NO_WINDOW`
+  （无控制台父进程 spawn 控制台程序会闪黑窗）；先杀树，再 `wait(3s)`，超时重杀一次。
+- **POSIX**：启动时 `start_new_session=True` 建独立进程组，停止时 `os.killpg(SIGTERM)`，
+  超时 `SIGKILL`。
+- **绝不杀死自己的进程组**：`_killpg` 先比较 `os.getpgid(pid) == os.getpgid(0)`，相等即放弃
+  整组杀（退回单进程终止）—— 旧作业对象或异常状态下，整组杀会**连带杀死 nf 自己**。
+- 守护测试：`tests/test_jobs_lifecycle.py`（起真实 `http.server` → 停止 → 断言端口释放）。
+
+## 理由
+
+**否决的备选**：
+
+| 备选 | 否决理由 |
+|---|---|
+| 继续用 `terminate()` + `kill()` | 就是本次要修的缺陷：杀不到孙进程 |
+| `CREATE_NEW_PROCESS_GROUP` + `CTRL_BREAK_EVENT` | 需要子进程自行处理控制台事件，对任意命令不可靠（`python -m http.server` 不会因此优雅退出）；且与 POSIX 语义不一致 |
+| Windows Job Object（`CreateJobObject` + `AssignProcessToJobObject`） | 语义最正（内核级整树管理），但要手写 ctypes 结构体 + 句柄生命周期，复杂度远超收益；将来需要"整树资源限制"时再评估 |
+| 记录子进程 PID 后逐个杀 | 孙进程可能再生孙进程（构建工具链），且 PID 记录天然不完整 |
+| 只在退出时清理 | `stop_job` 是用户显式动作，必须立即生效（否则端口一直被占） |
+
+## 代价与边界
+
+- `taskkill /F` 是**强制**终止：目标进程没有优雅退出机会（不 flush 缓冲）。对 dev server
+  这类进程可接受；若某长任务需要优雅落盘，应让它自带 graceful 停机命令。
+- `/T` 递归杀整棵子树 —— 若某作业被设计成"启动后脱离父进程独立运行"（如 `start /b`），
+  也会被一并杀掉。这是我们要的语义，但值得知道。
+- POSIX 的"整组杀"依赖 `start_new_session=True`；本项目启动的作业都有，但**外部注入的
+  Popen 对象不保证** —— 所以保留"组相同则不整组杀"的防御。
+- 极简环境里没有 `taskkill` 时会失败，退回 `proc.kill()`（杀不到孙进程），属已知降级。
+
+## 关联
+
+- 代码：`src/nexforge/core/jobs.py`（`_terminate_tree` / `_taskkill` / `_killpg` / `start`）
+- 测试：`tests/test_jobs_lifecycle.py`
+- 证据：`docs/evidence/wait-tool.log`（E 节"顺带发现的既有缺陷"）
+- 相关：[等待用专门的工具 + 可声明超时](2026-09-12-等待工具与超时可豁免.md)
+  ——"僵尸端口误报就绪"是本次的触发场景

nexforge_cli-0.7.0/docs/decisions/2026-09-13-MCP/346/216/245/345/205/245.md

@@ -0,0 +1,74 @@
+# 决策：MCP 接入 —— 配置建模 + 前缀命名 + 权限自报
+
+> 日期：2026-09-13 · 状态：生效
+
+## 背景
+
+MCP 客户端（`McpClient` / `McpTool`）在 M1 就写好了，但**从未接线**：全项目没有任何
+实例化点，配置只从 `config._raw_toml["mcp"]` 裸读。于是有三重问题：
+
+1. **配置写错静默无效**：拼错字段 / 漏 `name` / 重名，用户只会看到"没有工具"，
+   无从排查 —— 与「配置残留值治理」ADR 的取向直接冲突；
+2. **调用必然失败**（已单独修）：`McpTool.run` 在 `to_thread` 工作线程里调
+   `asyncio.get_event_loop()`，工作线程没有事件循环 → 必抛 RuntimeError；
+3. **无权限归属**：`permissions.check()` 按工具名查硬编码表，而 MCP 工具名是运行时
+   才知道的 → 一律落到 `danger`，用户既无从知晓原因，也无处按来源调整。
+
+它同时暴露了一个**更普遍**的问题：插件工具今天也是"未知 → danger → 每次弹审批"。
+
+## 决策
+
+1. **配置建模**：新增 `MCPConfig` / `McpServerDef`（pydantic）并进 `NexForgeConfig`；
+   结构校验走 `MCPConfig.validate_servers()` → `ConfigIssue`。**不抛 ValidationError**：
+   单个 server 配错不该让整份配置回退默认值（那是 provider 悬空值的代价，这里太大）。
+2. **命名强制加前缀**：外部工具一律注册为 `mcp__<server>__<tool>`
+   （非字母数字替换为 `_`，截断到 64 字符）。
+3. **权限自报 + 前缀兜底**：
+   - `McpTool.permissions_category` 按 server 的 `require_approval` 声明 `danger` / `read`；
+   - `permissions.category_of(name, declared)` 优先级：**工具自报 > 精确表 > 前缀规则 > danger**；
+   - 前缀表 `PREFIX_RULES`（`mcp__` → `danger`）兜住"没声明"的情形。
+4. **失败可见**：连接在 `on_mount` 后台进行（不阻塞开局），每个 server 的结果都出提示；
+   新增 `/mcp` 命令展示配置 / 连接状态 / 失败原因（与 `/plugins`、`/capabilities` 同构）。
+5. **成本闸门**：`[mcp] max_tools`（默认 40）+ server 级 `tools` 白名单；超出截断并提示。
+6. **生命周期**：优雅路径 `await client.disconnect()`（`on_unmount`，3s 超时兜底），
+   同步退出路径（`_safe_shutdown`）用 `terminate_now()` 尽力终止，避免留下孤儿 server。
+
+## 理由
+
+- **否决"继续裸读 `_raw_toml`"**：用户无从知道自己配错了 —— "静默无效"正是本次要消灭的问题类别。
+- **否决"裸名注册"**：外部 server 声明一个 `read_file` 就能**覆盖内置工具**，
+  这不是命名偏好而是安全边界。
+- **否决"把 MCP 工具名写进 `CATEGORIES`"**：名字运行时才知道，写不进去。
+- **否决"为 MCP 单独开后门"**：动态工具授权是通用问题（插件同样遇到），
+  用"工具自报 + 前缀兜底"一次解决，且不改动既有 41 个内置工具的分类。
+- **否决"用 capability 上报 MCP 可用性"**：「能力可用性上报」ADR 要求探测
+  **只读、无副作用（不发网络）**，而 MCP 的"可用"只有真实连接才知道 → 改用 `/mcp` 命令。
+- **否决"自动重连 / 守护进程"**：会引入看不见的后台重试，与"失败必须可见"冲突。
+- **默认 `require_approval = true`**：外部进程与 `run_background` 同级，先保守；
+  用户显式设为 `false` 才算授权。
+
+## 代价与边界
+
+- **token 成本**：每个 MCP 工具都进**每一轮**请求的 schema（内置 41 个约 7.9k tokens），
+  上游 server 动辄几十个工具 → 靠 `max_tools` + 白名单收敛；**没有做"按需注入"**
+  （那需要相关度筛选，属另一件事）。
+- **仅支持 stdio**：sse / streamable-http 配了会被明确跳过并提示（不静默）。
+- **无自动重连**：server 中途挂掉需重启 nf（后续可加 `/mcp reload`）。
+- **MCP 工具不得在事件循环线程里同步调用**：`run_coroutine_threadsafe(...).result()`
+  在 loop **自己的线程**里会自锁（loop 被这个同步调用占住，提交进去的协程永远轮不到
+  执行）。现检测到该情形直接报错（有测试钉住），Agent 的 `to_thread` 路径不受影响。
+- **审批语义**：`require_approval = false` 时 MCP 工具归"只读"，
+  但外部 server 实际仍可能写文件 —— 这是**用户显式承担**的选择，手册已注明。
+- **插件工具仍是"未知 → danger"**：本次提供了 `permissions_category` 机制但没批量改造插件；
+  有需要的插件可直接声明该属性。
+- 配置校验只覆盖结构问题（缺 name / 重名 / 缺 command / transport 未实现），
+  **不验证外部命令是否真实存在** —— 那要跑起来才知道，属连接阶段的错误（会提示）。
+
+## 关联
+
+- 代码：`config.py`、`mcp/__init__.py`、`core/permissions.py`、`core/agent.py`、
+  `ui/screens/chat.py`、`ui/slash_handler.py`、`ui/screens/chat_actions.py`、`i18n.py`
+- 测试：`tests/test_mcp_lifecycle.py`（链路）、`tests/test_mcp_integration.py`（配置→注册→权限）
+- 手册：`manual/12-MCP接入.md`、`manual/02-界面与快捷键.md`（`/mcp`）
+- 相关：[等待工具与超时可豁免](2026-09-12-等待工具与超时可豁免.md)（同一批引入的
+  `timeout_for` 机制让 MCP 也能声明超时）、[能力可用性上报](2026-09-10-能力可用性上报.md)（否决的备选）

{nexforge_cli-0.5.0 → nexforge_cli-0.7.0}/docs/decisions/README.md

@@ -68,3 +68,6 @@
 | 2026-09-11 | [配置残留值治理（自动收敛 + 必须可见）](2026-09-11-配置残留值治理.md) | 生效 |
 | 2026-09-12 | [内容里的标记不得被当成消息边界](2026-09-12-内容里的标记不得当成消息边界.md) | 生效 |
 | 2026-09-12 | [目标模式的失败必须可见，历史必须保全](2026-09-12-目标模式失败可见与历史保全.md) | 生效 |
+| 2026-09-12 | [等待用专门的工具 + 可声明超时](2026-09-12-等待工具与超时可豁免.md) | 生效 |
+| 2026-09-12 | [杀进程必须杀整棵树](2026-09-12-进程树终止.md) | 生效 |
+| 2026-09-13 | [MCP 接入（配置建模 + 前缀命名 + 权限自报）](2026-09-13-MCP接入.md) | 生效 |

nexforge_cli-0.7.0/docs/evidence/release-0.5.0.log

@@ -0,0 +1,76 @@
+# 发布 0.5.0 记录(2026-09-12)
+
+## 为什么是 minor(0.4.1 → 0.5.0)
+
+本版既含**新能力**(目标模式: 总监只读核验 / 核验折叠区 / 归档查看清理; 上下文窗口自学习),
+也含**行为修复**(停止不再删历史、失败不再静默挂起)。按语义化版本, 新增能力 → minor。
+
+兼容性: **无破坏性变更**。配置、会话文件格式、CLI 命令均保持兼容; 目标模式新增
+`.nexforge/goal_archive/` 目录(新产物), 不迁移、不回溯旧会话(下次保存自动收敛)。
+
+## 内容(相对 0.4.1, 6 个提交)
+
+| 提交 | 主题 |
+|---|---|
+| `41d9d42` | feat(context): 上下文窗口自学习(压缩预算跟随当前模型)+ 会话陈旧分段清理 |
+| `2396571` | fix(goal): 目标模式失败路径治理 + 历史归档 + 验收客观证据 |
+| `224f176` | feat(goal): 总监只读工具(自主核验)+ max_iters 不被目标模式放大 |
+| `77c9641` | fix(session): 会话分段容量 200→500 行 + 切分改用真实行数(压会话文件数) |
+| `707d49c` | feat(goal): 总监核验折叠区(核验了什么/读到了什么, 默认收起可展开) |
+| `ef44ff6` | feat(goal): 归档查看/清理入口(/goal archive [clean N]) |
+
+### 用户可感知的变化
+
+- **失败不再静默挂起**: 开发者回合异常(报错/超时/取消)→ 补失败回执交总监决策;
+  总监回合失败 → 重试一次 → 仍失败则暂停(保留目标/方案/轮次, 回一句话续跑);
+  余额耗尽改为数值判定(修掉整元余额 ¥100.00 被误判为耗尽)。
+- **停止不再删历史**: 目标/方案/轮次归档到 `.nexforge/goal_archive/`;
+  新增 `/goal archive`(列出)与 `/goal archive clean [N]`(带确认的清理)。
+- **验收有客观证据**: 复盘自动附 git(未提交改动 + 最近提交)+ 文件树快照的改动摘要,
+  并明确"与开发者报告冲突时以客观证据为准"; 总监可自主调用 9 个**只读**工具核验,
+  界面出现可展开的「总监核验」折叠区(`[ui] director_tools = false` 可关, 省 token)。
+- **会话更省文件**: 同一会话的分段文件数实测 111 → 43(-61%), 旧会话下次保存自动收敛。
+- **上下文预算跟随当前模型**(不再写死 1M): 上游报错时学到真实窗口并立刻压缩, 换模型下轮生效。
+
+### 实测依据(真机驱动, 非推测)
+
+见 ADR `docs/decisions/2026-09-12-目标模式失败可见与历史保全.md`, 关键三条:
+
+1. 目标模式跑的测试项目**不是 git 仓库** → 只靠 git 的"客观证据"是空话, 改为 git + 文件树快照;
+2. 总监会话 28 条消息 = 请求体量 11.4 万字符 → **按条数裁剪(30)永不触发**, 改为体量预算;
+3. 会话文件 53.2 万字符 ≠ 请求体量(结构标记 base64 膨胀) → 判据落到 `director_load` 实测。
+
+## 发布流程与结果
+
+| 步骤 | 结果 |
+|---|---|
+| 版本 | 0.4.1 → **0.5.0**(5 处同步: 代码 / 打包元数据 / README / 手册索引 / 手册第 1 章) |
+| 质量 gate | **6/6 PASS**(eof-newline / example-config / hygiene / manual-consistency / registry-consistency / version-sync) |
+| 全量测试 | **681 passed, 3 skipped** |
+| 构建 | whl 316 KB + tar.gz 519 KB |
+| 包检查 | `twine check` **PASSED**(whl + tar.gz) |
+| 标签 | `v0.5.0` |
+| 上传 | PyPI 上传成功: whl 323,240 B + tar.gz 531,203 B(upload 2026-09-12T13:05:10Z) |
+
+### 上传与核验细节
+
+- 上传走 `~/.pypirc` 的 `[pypi]` token(环境变量 `NEXFORGE_PYPI_TOKEN` 在本机 shell 里是空的;
+  用 `bash -c "... --password \"$VAR\""` 时 `$` 被 cmd 层转义过一次, 会变成**字面量密码** →
+  表现为"进度跑满 100% 后 403 Forbidden", 这个假象值得记住: 403 不一定是 token 失效)。
+- PyPI JSON API 核验(绕开 pip 索引缓存):
+  `https://pypi.org/pypi/nexforge-cli/0.5.0/json` → 200, `version=0.5.0`, 两个产物 size 与本地一致。
+  注意 `pip index versions` 在发布后一段时间仍显示旧版本(PyPI 索引/本地缓存延迟) —— 不要据此判定失败。
+
+### 一处未跟上的元数据(留待下次发版)
+
+README 的"要点"段落(PyPI 页面描述)在 0.5.0 上传时仍是 v0.4.1 要点 —— 上传后才发现。
+已在本地 README 更新为 0.5.0 要点, 但**元数据要下次发版才会刷新到 PyPI 页面**
+(同版本号不可重传)。影响面: PyPI 项目页顶部的"当前版本"已正确显示 v0.5.0, 仅要点段落滞后一版。
+
+
+## 已知边界(本版有意不做, 已写入 ADR)
+
+- 目标文件**无跨进程互斥锁**(写入已原子化, 读不到半截; 同一项目同时跑两个目标模式会互相覆盖);
+- 界面验收不强制截图(改以客观证据 + 提示为准; 无 GUI 会话下强制截图会卡死流程);
+- 会话分段不做增量写(只解决文件数, 不优化 IO —— 收益/复杂度不成比例);
+- 归档目录只增不减**除了**用户主动 `/goal archive clean`。

nexforge_cli-0.7.0/docs/evidence/wait-tool.log

@@ -0,0 +1,144 @@
+# wait / wait_until 实测证据
+
+> 采集：2026-09-12 · Windows 10.0.26200 · Python 3.14.3
+> 用途：在"要不要加等待工具"这件事上先拿数据，而不是凭印象决策。
+
+## A. 现存各种"等待写法"的真实行为
+
+测量方式：在 `run_shell` 的真实执行环境（`subprocess.run(shell=True, stdin=DEVNULL,
+capture_output=True)`）里跑命令，用 `time.time()` 取差值。
+
+| 命令 | 实测耗时 | 退出码 | 结论 |
+|---|---|---|---|
+| `timeout /t 2` | **0.03s** | 1 | **静默失败**：stderr `Input redirection is not supported`。以为等了 2 秒，实际 0 秒 |
+| `sleep 2` | — | 1 | cmd 无此命令：`'sleep' is not recognized as an internal or external command` |
+| `ping -n 3 127.0.0.1 >nul` | 2.03s | 0 | 能等，但仅 Windows、1 秒粒度、污染输出 |
+| `bash -c "sleep 2"` | **10.59s** | 0 | PATH 上是 WSL 存根（`WindowsApps\bash.EXE`），冷启动多花 8.5 秒 |
+| `powershell -Command Start-Sleep -Seconds 2` | 2.30s | 0 | 能用，但慢 15%，且 stderr 有 profile 加载告警 |
+| `python -c "time.sleep(2)"`（进程内） | **2.00s** | 0 | 精确 —— 等待工具据此实现（不起子进程，无编码/平台差异） |
+
+## B. 为什么"等待"必须可中断
+
+asyncio 的超时/取消只能解除 `await`，**杀不掉 `to_thread` 里的线程**：
+
+```
+asyncio.wait_for(asyncio.to_thread(work), 1)     # work 内 time.sleep(3)
+-> "asyncio 在 1.00s 放弃等待(工具被判失败)"
+-> 此后线程池线程仍在跑，直到自己的 sleep 结束
+```
+
+含义：不可中断的长等待会让"用户按了停止"变成假象，也会在退出时拖住进程。
+因此等待走 `core/waits.py` 的进程级 Event（每 0.05s 轮询一次）。
+
+同时这也是**旧 `wait_for_job` 的暗坑**：它用 `time.sleep(0.1)` 轮询作业状态，
+取消对它无效。本次一并改为可中断睡眠。
+
+## C. 新实现的自测（`tests/test_wait_tools.py`，26 项全绿，7.19s）
+
+- `wait(0.3)` 实测 **0.30s**（误差 < 10ms）
+- `wait(30)` 在 0.3s 后 `interrupt()` → **0.3s 内返回**，`ok=False`、"等待被用户中断"
+- `wait(601)` → **明确拒绝**（"单次等待上限 600 秒"），不静默截断
+- `wait` 漏传 `seconds` → 报“参数错误”（而非静默返回“已等待 0 秒”）
+- `job_manager.wait()`（等作业）在 0.5s 后 `interrupt()` → **2s 内返回**（修前要等满 20s）
+- Agent 上限 = `min(max(全局 tool_timeout, 工具声明的 timeout_for), 3600s)`：
+  - 全局压到 0.5s + 工具声明 2s（实睡 1s）→ **成功**（豁免生效）
+  - 不声明的工具（实睡 1s）→ **判超时**，报错含实际上限 `0.5`
+  - 假工具声明 1e9 → 被硬顶截到 **3600s**（防乱声明钉死会话）
+- `wait_until`：
+  - `file`：目标 0.4s 后出现 → 命中
+  - `log`：0.3s 后写入 `BUILD SUCCESS` → 命中（缺 `expect` 时明确拒绝）
+  - `port`：监听中 → 命中；关闭后 → 超时并给出"不可连接"证据
+  - `http`：状态码匹配规则（空=2xx/3xx、`404`、`200,204`、`5xx`）单测覆盖
+- 权限：`wait` / `wait_until` 归**只读**（supervised / safe 下均 `allow`，不弹审批）
+- 总监只读白名单允许等待（核验构建产物/端口是合理诉求，且改不了仓库）
+- 系统提示（`DEFAULT_SYSTEM`）含“等待用 wait / wait_until，不要用 sleep 拼命令”
+- 源码断言：5 个文件的每条取消路径都调用 `waits.interrupt()`（防漏改回归）
+
+## D. 检查中发现并修掉的导入链问题
+
+把 `nexforge.tools.wait_tools` 加进 `test_cross_platform.MODULES`（无 windll 环境导入门）
+后**立刻报错**，栈为：
+
+```
+nexforge/tools/wait_tools.py:36: import httpx
+  httpx/__init__.py -> httpx/_main.py:8: import click
+    click/_compat.py -> click/_winconsole.py:42: kernel32 = windll.kernel32
+      AttributeError: windll not available
+```
+
+即 httpx 的导入链会拉 click（Windows 分支硬依赖 `ctypes.windll`）。修法：顶层不再
+import httpx，只在 `until=http` 的探测函数内延迟导入 —— “等文件/端口/日志”不再为
+网络库付代价。修后该门禁通过（70 passed）。
+
+## E. 真机验证（重启后的新进程，2026-09-12）
+
+| 调用 | 返回 | 实测耗时 |
+|---|---|---|
+| `wait(2)` | 已等待 2.00 秒 | 2.00s |
+| `wait(65)` | **已等待 65.00 秒** | 65.00s |
+| `wait(601)` | 拒绝（单次等待上限 600 秒） | 即时 |
+| `wait_until(port, 127.0.0.1:18234)` | 命中，1 次探测 | 0.50s |
+| `wait_until(http, expect=200)` | 命中 HTTP 200，1 次探测 | 0.34s |
+| `wait_until(file, 4 秒后才生成)` | 命中 | 4.50s（10 次探测） |
+| `wait_until(file, 不存在的文件)` | 超时 + 末次证据 | 2.00s（8 次探测） |
+| `wait_until(log, expect)` | 命中 | 0.00s |
+| `wait_until(log, 缺 expect)` | 拒绝 | 即时 |
+| `wait_for_job(3, 15)` | 作业已退出(code 0) | 即时 |
+| `wait(1)`（在 Esc 取消之后的下一轮） | 已等待 1.00 秒 —— 说明中断标记已复位 | 1.00s |
+
+**`wait(65)` 是超时豁免的决定性证据**：65 秒 > 全局 `tool_timeout`(60)，若豁免失效
+这里必然返回"工具执行超时(60s)"。
+
+### Esc 中断的真实路径（重要：别误判成 bug）
+
+真机按 Esc 取消一个 `wait(60)` 后，**模型看到的是**：
+
+```
+已取消(中断/超时)。
+```
+
+这条**不是** wait 工具自己的文案，而是会话修复层补的回执（`core/session.py` 的
+`_repair_tool_sequence`：为没有响应的 tool_call 补一条合法响应，防止下次请求 400）。
+
+原因链条：Esc → `cancel_group("agent")` 取消 asyncio worker → `_exec_tool` 的
+`asyncio.wait_for` 抛 `CancelledError` → 回合终止、**工具结果被丢弃**。
+`waits.interrupt()` 同时被调用，其作用是**让等待线程立刻退出**（不留一个还在睡的线程），
+而不是改变给模型看的中断文案 —— 后者由会话修复层负责。
+
+因此 `wait` 的"等待被用户中断(已等 X 秒)"文案只在"只 interrupt、不 cancel"的时序
+（如 Web 面板停止的竞态窗口）可见；Esc 路径由修复层兜底。两者互不冲突：
+真机观察到的用户可见行为是"**立刻停止，不等满**"，这正是要保证的。
+
+### 检查中发现的实现缺陷（已修）：探测耗时未计入 timeout 预算
+
+真机实测（修复前）：
+
+| 请求 | 实际耗时 | 探测次数 | 末次探测证据 |
+|---|---|---|---|
+| `wait_until(port, timeout=2, interval=0.4)` | 2.00s | 1 | TimeoutError |
+| `wait_until(port, timeout=3, interval=1)` | **5.00s** | 2 | TimeoutError |
+| `wait_until(port, timeout=3, interval=0.5)` | **4.50s** | 2 | TimeoutError |
+
+根因：`_probe_port` 的 `socket.create_connection(timeout=2)` 耗时会受本机行为影响 ——
+对**未监听端口**这里是 **2 秒超时**（不是立即 ConnectionRefused），而这段耗时**没有计入**
+timeout 预算，于是"最多等 3 秒"的请求实际跑了 5 秒。
+
+修法：循环里先算 `budget = deadline - now` 并把预算传给探测函数 —— `port` 用
+`min(2.0, max(0.2, budget))`，`http` 用 `min(5.0, max(0.5, budget))`。
+
+修复后（子进程加载新版源码实测）：`timeout=3` → **3.00s**（原 5.00s）。
+守护测试：`test_wait_until_respects_timeout_budget`（断言实际耗时 ≤ timeout + 0.8s）。
+
+### 顺带发现的既有缺陷（均已修）
+
+1. **`stop_job` / 退出清理杀不掉孙进程**（`core/jobs.py`）：实测
+   `run_background("python -m http.server 18234")` → `stop_job` 后作业显示"退出1"，
+   但 `python.exe`(PID 22088) **仍 LISTENING 18234**。因为 `Popen(shell=True)` 在
+   Windows 上是 cmd.exe → python.exe，`proc.terminate()` 只终结 cmd.exe，孙进程成孤儿。
+   影响：dev server/长任务场景端口占用、内存泄漏；**`wait_until(port)` 可能对"僵尸端口"
+   误报就绪**。**已修**：`_terminate_tree()` —— Windows `taskkill /F /T`、POSIX
+   独立进程组 `killpg`（见 ADR「杀进程必须杀整棵树」与 `tests/test_jobs_lifecycle.py`）。
+   （本次测试产生的孤儿已手动清理。）
+2. **`web_screenshot` 内部超时 90s > 全局工具上限 60s**（`tools/screenshot_tools.py:315`）：
+   复杂页面会在 60s 被判"工具执行超时"，而线程/浏览器继续跑到 90s（结果被丢弃、白跑）。
+   **已修**：给它加了 `timeout_for()` 返回 95，内外部超时一致。

{nexforge_cli-0.5.0 → nexforge_cli-0.7.0}/docs/submission/README-/346/212/225/347/250/277/350/257/264/346/230/216.md

@@ -35,7 +35,7 @@ docs/nexforge.zh-CN.md     ← 内容取自 docs/submission/nexforge.zh-CN.md
 **README.zh-CN.md**(中文版): 同样位置(在 nanobot 之后、Oh My Pi 之前)插入:
 
 ```markdown
-| **NexForgeCLI** | 开源终端 AI 编程助手，内置 35 个工具，原生支持 DeepSeek-V4（100 万上下文）、数据分析、网络搜索与总监循环目标模式。 | [指南](./docs/nexforge.zh-CN.md) |
+| **NexForgeCLI** | 开源终端 AI 编程助手，内置 41 个工具，原生支持 DeepSeek-V4（100 万上下文）、数据分析、网络搜索与总监循环目标模式。 | [指南](./docs/nexforge.zh-CN.md) |
 ```
 
 > 注意: 按字母序插入(Ne 在 na 和 Oh 之间), 不要追加到表格末尾, 否则合并冲突概率高。

{nexforge_cli-0.5.0 → nexforge_cli-0.7.0}/docs/submission/nexforge.zh-CN.md

@@ -2,7 +2,7 @@
 
 # 接入 NexForgeCLI
 
-NexForgeCLI 是一款开源的终端 AI 编程助手，内置 35 个工具，覆盖文件编辑、Shell 执行、Git、数据分析（CSV / SQLite / 文本）、网络搜索、图片理解与运维自动化。原生对接 `api.deepseek.com`，支持 DeepSeek-V4-Pro 与 DeepSeek-V4-Flash 全 100 万 token 上下文，也可通过一份 `models.toml` 驱动任意 OpenAI 兼容或 Anthropic 兼容的端点（Kimi、GPT、Claude 等）。
+NexForgeCLI 是一款开源的终端 AI 编程助手，内置 41 个工具，覆盖文件编辑、Shell 执行、Git、数据分析（CSV / SQLite / 文本）、网络搜索、图片理解与运维自动化。原生对接 `api.deepseek.com`，支持 DeepSeek-V4-Pro 与 DeepSeek-V4-Flash 全 100 万 token 上下文，也可通过一份 `models.toml` 驱动任意 OpenAI 兼容或 Anthropic 兼容的端点（Kimi、GPT、Claude 等）。
 
 - **仓库：** <https://gitee.com/Lighthorn/nexforgecli>
 - **PyPI：** <https://pypi.org/project/nexforge-cli/>

{nexforge_cli-0.5.0 → nexforge_cli-0.7.0}/manual/01-/345/256/211/350/243/205/344/270/216/351/205/215/347/275/256.md

@@ -1,6 +1,6 @@
 # 安装与配置
 
-> NexForgeCLI v0.5.0
+> NexForgeCLI v0.7.0
 
 ## 环境要求
 

{nexforge_cli-0.5.0 → nexforge_cli-0.7.0}/manual/02-/347/225/214/351/235/242/344/270/216/345/277/253/346/215/267/351/224/256.md

@@ -121,6 +121,7 @@
 | `/map view|check|sync` | 项目地图管理 |
 | `/kb search|add|list|path` | 知识库管理(检索/添加/列出/设置路径) |
 | `/plugins [list\|reload]` | 插件管理(列出/重载第三方插件) |
+| `/mcp` | MCP 外部工具服务: 配置与连接状态(详见 [12-MCP接入](12-MCP接入.md)) |
 | `/web start|stop` | Web 管理面板(端口8899) |
 
 **系统**