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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.4.1
+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.4.1** · 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.4.1 → nexforge_cli-0.7.0}/README.md

@@ -8,14 +8,15 @@
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.4.1** · 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.4.1 → nexforge_cli-0.7.0}/config.example.toml

@@ -16,6 +16,14 @@ thinking = true                            # 思考模式,默认开
 reasoning_effort = "high"                  # high | max
 max_output_tokens = 32768                  # 含思考 token; 别写 8192(思考会吃满 → 正文截断秒停)
 
+# 上下文窗口(压缩预算的依据)。**默认不写 = 自动跟随当前模型**:
+#   用户声明(models.toml 的本项 / config.toml 的 context_window)> 实测学习
+#   (上游报错里的窗口数字 / 失败请求体量 / 成功响应的 prompt_tokens)> 内置表
+#   > 未知模型兜底(1,000,000)。
+# 只有需要**强制覆盖**自动判断时才在这里写(>0 即视为声明, 优先级最高;
+# 但上游若用报错证明窗口更小, 实测值仍会压低它 —— 物理事实优先)。
+# context_window = 1000000
+
 # 定价(每百万 token,USD)—— 已核实
 [models.pricing.flash]
 input_cache_hit = 0.0028
@@ -37,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.4.1 → nexforge_cli-0.7.0}/doc//351/241/271/347/233/256/346/200/273/347/233/221/345/276/252/347/216/257-/345/274/200/345/217/221/350/256/241/345/210/222.md

@@ -1,172 +1,187 @@
-# 项目总监循环 开发计划
-
-> 版本: v1.0 · 创建: 2026-07-16 · 状态: 设计完成,待实现
-
----
-
-## 概述
-
-在目标模式(`/goal`)下,引入"项目总监 + 开发者"双角色架构。项目总监负责制定计划、审核进展、分发任务;开发者负责具体执行。目标是让 AI 能够自主完成复杂的多轮开发任务,同时保证质量和可追溯性。
-
----
-
-## 角色定义
-
-### 项目总监 (Director)
-
-- **职责**:审核开发者报告 → 判断进展 → 发布下一条指令
-- **审核维度**:代码质量、性能瓶颈、稳定性、用户体验、逻辑流程
-- **防僵局策略**:当开发者反复说"任务完成"时,从以下方向主动寻找新工作:
-  - 边界情况覆盖
-  - 测试补充
-  - 性能优化
-  - 文档/代码注释
-  - 代码重构整理
-  - 是否真正满足核心需求
-- **停止判断**:若目标已达成,回复 `GOAL_ACHIEVED` 关键词
-
-### 开发者 (Developer)
-
-- **职责**:执行项目总监的指令 → 完成后提交总结报告
-- **行为约束**:专注执行指令,不做多余的事
-
----
-
-## 启动流程 (二步确认)
-
-```
-用户输入 /goal
-  → Step 1: 弹出风险警告弹窗(GoalModeModal)
-  → Step 2: 弹出多行输入框,用户输入目标描述
-  → Step 3: 显示目标预览,提示"回复确认开始"
-  → Step 4: 用户回复"确认"/"开始"/"ok"/"yes"
-  → Step 5: 正式启动
-```
-
-### 启动时操作
-1. `self.config.ui.goal_mode = True`
-2. `self.config.ui.mode = "auto"` (强制全自动)
-3. 保存到项目级 `config.toml`
-4. 创建 `.nexforge/goal/nfgoal.md` (记录最终目标)
-5. 发送首轮指令给 AI:"[项目总监] 制定开发计划并发布第一条指令"
-
----
-
-## 循环流程
-
-```
-每个 AI 回合结束 (TURN_DONE)
-  → 如果 goal_mode == True:
-      → 调用 _goal_cycle_continue(last_response)
-      → 检查停止条件
-      → 显示项目总监金色消息
-      → 构造总监 prompt(包含目标+计划+开发者报告)
-      → 启动下一轮 AI
-```
-
-### 停止条件 (任一满足即停止)
-
-| 条件 | 检测方式 | 操作 |
-|------|---------|------|
-| 余额耗尽 | `_balance == "0.00"` | 显示"账户余额耗尽",退出目标模式 |
-| 总监判断达成 | `last_response` 含 `GOAL_ACHIEVED` | 显示"项目总监判断目标达成" |
-| 达到最大轮数 | `current >= max_rounds` (默认 100,可通过 `/max N` 设置) | 显示"达到最大轮数" |
-
----
-
-## UI 显示
-
-### 项目总监消息 (金色)
-```python
-class DirectorNote(Static):
-    """👔 项目总监: 消息内容 (金色 #FFD700 加粗)"""
-```
-
-- 每轮开始前在聊天区显示金色提示条
-- 格式:`第 N/M 轮:项目总监审核`
-
-### 状态栏
-- 目标模式开启时显示 `🎯 目标`
-- 运维模式开启时显示 `🔧 运维`
-
----
-
-## 快捷键
-
-| 快捷键 | 功能 |
-|--------|------|
-| F7 | 切换运维模式 |
-| F8 | 切换目标模式(开启时强制全自动) |
-| Esc | 目标模式三级停止:停总监 → 停开发者 → 退出 |
-
-### Esc 三级停止逻辑
-```
-Esc 第1次:停止项目总监(goal_mode=False,开发者继续当前工作)
-Esc 第2次:取消开发者 worker
-Esc 第3次:弹出退出确认
-```
-
----
-
-## 文件体系 (项目隔离,仅目标模式)
-
-```
-<项目>/.nexforge/goal/
-├── nfgoal.md           ← 最终目标
-├── plan.md             ← 项目总监编写的计划
-└── rounds/
-    ├── 001.md           ← 第1轮:开发者报告 + 总监审核
-    ├── 002.md           ← 第2轮
-    └── ...
-```
-
-- 非目标模式不创建此目录
-- 离开目标模式后不自动清理(保留历史)
-
----
-
-## 配置项
-
-| 配置 | 默认 | 说明 |
-|------|------|------|
-| `ui.goal_mode` | `false` | 是否处于目标模式 |
-| `ui.ops_mode` | `false` | 是否处于运维模式 |
-| `ui.max_rounds` | `100` | 目标模式最大轮数,通过 `/max N` 修改 |
-| `ui.mode` | `review` | 审批模式(review/auto) |
-
----
-
-## 涉及文件
-
-| 文件 | 改动 |
-|------|------|
-| `src/nexforge/core/goal_manager.py` | **已创建** — GoalManager 类 |
-| `src/nexforge/ui/screens/chat.py` | 加 `_start_goal_mode`、`_confirm_goal_start`、`_goal_cycle_continue` |
-| `src/nexforge/ui/widgets/messages.py` | **已创建** — DirectorNote 金色组件 |
-| `src/nexforge/ui/widgets/mode_warning.py` | 已有 GoalModeModal、OpsModeModal |
-| `src/nexforge/config.py` | goal_mode/ops_mode/max_rounds 字段 |
-| `src/nexforge/store/session_store.py` | 会话保存过滤系统消息(已实现) |
-
----
-
-## 实现注意事项
-
-1. **不要用 heredoc/多行字符串替换编辑 chat.py**——该文件已因反复编辑损坏多次
-2. **使用 `edit_file` 工具逐个精准替换**,每次编辑后编译验证
-3. **`_goal_cycle_continue` 必须独立为类方法**,不能嵌入其他方法中
-4. **字符串拼接用 `+` 而非 f-string 跨行**,避免语法错误
-5. **`save_config` 按项目保存**(`<cwd>/.nexforge/config.toml`),不污染全局
-6. **系统消息不保存到会话文件**(已在 session_store.py 实现)
-
----
-
-## 测试验证
-
-- [ ] `/goal` → 弹窗 → 输入目标 → "确认" → 项目总监启动
-- [ ] F8 一键切换目标模式
-- [ ] F7 一键切换运维模式
-- [ ] Esc 三级停止(目标模式)
-- [ ] `GOAL_ACHIEVED` 自动停止
-- [ ] `/max 50` 修改轮数上限
-- [ ] 不同项目独立模式状态
-- [ ] 余额耗尽自动停止
+# 项目总监循环 开发计划
+
+> 版本: v1.0 · 创建: 2026-07-16 · 状态: 设计完成,待实现
+
+---
+
+## 概述
+
+在目标模式(`/goal`)下,引入"项目总监 + 开发者"双角色架构。项目总监负责制定计划、审核进展、分发任务;开发者负责具体执行。目标是让 AI 能够自主完成复杂的多轮开发任务,同时保证质量和可追溯性。
+
+---
+
+## 角色定义
+
+### 项目总监 (Director)
+
+- **职责**:审核开发者报告 → 判断进展 → 发布下一条指令
+- **审核维度**:代码质量、性能瓶颈、稳定性、用户体验、逻辑流程
+- **防僵局策略**:当开发者反复说"任务完成"时,从以下方向主动寻找新工作:
+  - 边界情况覆盖
+  - 测试补充
+  - 性能优化
+  - 文档/代码注释
+  - 代码重构整理
+  - 是否真正满足核心需求
+- **停止判断**:若目标已达成,回复 `GOAL_ACHIEVED` 关键词
+
+### 开发者 (Developer)
+
+- **职责**:执行项目总监的指令 → 完成后提交总结报告
+- **行为约束**:专注执行指令,不做多余的事
+
+---
+
+## 启动流程 (二步确认)
+
+```
+用户输入 /goal
+  → Step 1: 弹出风险警告弹窗(GoalModeModal)
+  → Step 2: 弹出多行输入框,用户输入目标描述
+  → Step 3: 显示目标预览,提示"回复确认开始"
+  → Step 4: 用户回复"确认"/"开始"/"ok"/"yes"
+  → Step 5: 正式启动
+```
+
+### 启动时操作
+1. `self.config.ui.goal_mode = True`
+2. `self.config.ui.mode = "auto"` (强制全自动)
+3. 保存到项目级 `config.toml`
+4. 创建 `.nexforge/goal/nfgoal.md` (记录最终目标)
+5. 发送首轮指令给 AI:"[项目总监] 制定开发计划并发布第一条指令"
+
+---
+
+## 循环流程
+
+```
+每个 AI 回合结束 (TURN_DONE)
+  → 如果 goal_mode == True:
+      → 调用 _goal_cycle_continue(last_response)
+      → 检查停止条件
+      → 显示项目总监金色消息
+      → 构造总监 prompt(包含目标+计划+开发者报告)
+      → 启动下一轮 AI
+```
+
+### 停止条件 (任一满足即停止)
+
+| 条件 | 检测方式 | 操作 |
+|------|---------|------|
+| 余额耗尽 | `_balance == "0.00"` | 显示"账户余额耗尽",退出目标模式 |
+| 总监判断达成 | `last_response` 含 `GOAL_ACHIEVED` | 显示"项目总监判断目标达成" |
+| 达到最大轮数 | `current >= max_rounds` (默认 100,可通过 `/max N` 设置) | 显示"达到最大轮数" |
+
+---
+
+## UI 显示
+
+### 项目总监消息 (金色)
+```python
+class DirectorNote(Static):
+    """👔 项目总监: 消息内容 (金色 #FFD700 加粗)"""
+```
+
+- 每轮开始前在聊天区显示金色提示条
+- 格式:`第 N/M 轮:项目总监审核`
+
+### 状态栏
+- 目标模式开启时显示 `🎯 目标`
+- 运维模式开启时显示 `🔧 运维`
+
+---
+
+## 快捷键
+
+| 快捷键 | 功能 |
+|--------|------|
+| F7 | 切换运维模式 |
+| F8 | 切换目标模式(开启时强制全自动) |
+| Esc | 目标模式三级停止:停总监 → 停开发者 → 退出 |
+
+### Esc 三级停止逻辑
+```
+Esc 第1次:停止项目总监(goal_mode=False,开发者继续当前工作)
+Esc 第2次:取消开发者 worker
+Esc 第3次:弹出退出确认
+```
+
+---
+
+## 文件体系 (项目隔离,仅目标模式)
+
+```
+<项目>/.nexforge/goal/
+├── nfgoal.md           ← 最终目标
+├── plan.md             ← 项目总监编写的计划
+└── rounds/
+    ├── 001.md           ← 第1轮:开发者报告 + 总监审核
+    ├── 002.md           ← 第2轮
+    └── ...
+```
+
+- 非目标模式不创建此目录
+- 离开目标模式后不自动清理(保留历史)
+
+---
+
+## 配置项
+
+| 配置 | 默认 | 说明 |
+|------|------|------|
+| `ui.goal_mode` | `false` | 是否处于目标模式 |
+| `ui.ops_mode` | `false` | 是否处于运维模式 |
+| `ui.max_rounds` | `100` | 目标模式最大轮数,通过 `/max N` 修改 |
+| `ui.mode` | `review` | 审批模式(review/auto) |
+
+---
+
+## 涉及文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/nexforge/core/goal_manager.py` | **已创建** — GoalManager 类 |
+| `src/nexforge/ui/screens/chat.py` | 加 `_start_goal_mode`、`_confirm_goal_start`、`_goal_cycle_continue` |
+| `src/nexforge/ui/widgets/messages.py` | **已创建** — DirectorNote 金色组件 |
+| `src/nexforge/ui/widgets/mode_warning.py` | 已有 GoalModeModal、OpsModeModal |
+| `src/nexforge/config.py` | goal_mode/ops_mode/max_rounds 字段 |
+| `src/nexforge/store/session_store.py` | 会话保存过滤系统消息(已实现) |
+
+---
+
+## 实现注意事项
+
+1. **不要用 heredoc/多行字符串替换编辑 chat.py**——该文件已因反复编辑损坏多次
+2. **使用 `edit_file` 工具逐个精准替换**,每次编辑后编译验证
+3. **`_goal_cycle_continue` 必须独立为类方法**,不能嵌入其他方法中
+4. **字符串拼接用 `+` 而非 f-string 跨行**,避免语法错误
+5. **`save_config` 按项目保存**(`<cwd>/.nexforge/config.toml`),不污染全局
+6. **系统消息不保存到会话文件**(已在 session_store.py 实现)
+
+---
+
+## 测试验证
+
+- [ ] `/goal` → 弹窗 → 输入目标 → "确认" → 项目总监启动
+- [ ] F8 一键切换目标模式
+- [ ] F7 一键切换运维模式
+- [ ] Esc 三级停止(目标模式)
+- [ ] `GOAL_ACHIEVED` 自动停止
+- [ ] `/max 50` 修改轮数上限
+- [ ] 不同项目独立模式状态
+- [ ] 余额耗尽自动停止
+
+---
+
+## 实现现状补充(2026-09-12)
+
+本节记录与上面设计稿**不一致**的最终实现，避免后来者按设计稿误判代码。
+
+| 设计稿 | 实现现状 | 原因 |
+|------|---------|------|
+| Esc 三级停止(停总监 → 停开发者 → 退出) | **一次 Esc 停整个目标模式**(停总监循环 + 取消开发者 worker + 关双栏 + 关 goal_mode)；空闲时才是退出确认 | 三级停止需记"第几次 Esc"状态，实际使用中用户按第一次没停住会反复按；一次停干净更可预期 |
+| 离开目标模式不自动清理(保留历史) | 停止/关闭/切换时把现场**归档**到 `.nexforge/goal_archive/<时间戳>-<标签>/`，现场清空 | "保留现场"会让下次开启把旧目标误判为"插话"(note_20260825_214722)；归档同时满足可回看与不误判 |
+| 余额耗尽检测 `_balance == "0.00"` | `parse_balance()` 数值化，`<=0` 才算耗尽；解析不出则不停止 | 子串匹配会把 `¥100.00`/`¥20.00`/`¥1,000.00` 误判为耗尽 |
+| 总监/开发者回合失败无约定 | 失败必可见：开发者异常结束补"失败回执"交总监决策；总监回合失败重试一次后**暂停**(保留现场，回一句话即续跑) | 失败没有回执通道时，循环停在 `await _wake_event.wait()`，用户看到的是"AI 不动了" |
+
+详见 ADR `docs/decisions/2026-09-12-目标模式失败可见与历史保全.md`。

nexforge_cli-0.7.0/docs/decisions/2026-09-12-/347/233/256/346/240/207/346/250/241/345/274/217/345/244/261/350/264/245/345/217/257/350/247/201/344/270/216/345/216/206/345/217/262/344/277/235/345/205/250.md

@@ -0,0 +1,176 @@
+# 决策：目标模式的失败必须可见，历史必须保全
+
+> 日期：2026-09-12 · 状态：生效
+
+## 背景
+
+目标模式（总监 + 开发者双角色循环）在"正常路径"上已经跑通，但**失败路径**有三类
+用户侧完全看不见的故障，且所有停止路径都会把历史记录删掉。
+
+1. **开发者回合异常结束 → 总监循环静默挂起**。开发者的"完成"信号只有一条通道：
+   `TURN_DONE` → `on_turn_done`（`ui/screens/chat.py`）。而 `ProviderError` 只 yield
+   `ERROR`（`core/agent.py:189`）、单轮超时走 `asyncio.timeout`、worker 被取消（切会话/
+   Esc/退出）都没有该事件 → `_dev_done_flag` 永远为 False → 循环停在
+   `await self._wake_event.wait()`（`features/mode_features.py`）。用户看到的是"AI 不动了，
+   也没有任何提示"，只有再插一句话才可能被唤醒（而插话只是响应，不会重新派发任务）。
+2. **总监回合失败 → 同款静默挂起**。`_run_director_safe` 只接 `TimeoutError`；其它异常
+   冒泡到 `_director_loop` 最外层，提示一句"已跳过"后循环继续 `await`，而已经没有人
+   会再派发任务。
+3. **余额耗尽判定是子串匹配**。`"0.00" in _balance`，而余额文案是 `f"¥{v:,.2f}"`
+   （`provider/balance.py`）—— 整元余额 `¥100.00` / `¥20.00` / `¥1,000.00` 都含子串
+   `"0.00"`（实测），于是开发者回合刚结束就被判"余额耗尽"，**并连带清掉全部轮次存档**。
+4. **所有停止路径都 `rmtree` 目标目录**（完成 / 失败 / 会话切换 / Esc / F8），轮次复盘
+   记录永久消失。这与 `doc/项目总监循环-开发计划.md`（"离开目标模式后不自动清理，保留
+   历史"）相矛盾；但反过来"直接保留现场"又会让下次开启时旧目标被误判为"插话"
+   （知识库 note_20260825_214722 实测过）。
+
+## 决策
+
+**失败路径**（三层：回执 → 重试 → 暂停，逐级兜底）：
+
+1. **失败回执通道**：`GoalModeFeature.notify_dev_turn_aborted(reason)`，由
+   `ChatScreen._run_agent` 的 `finally` 触发（仅当 `dev_log=True` 且 `_dev_busy` 仍为 True，
+   即"确实在跑开发者、且没走正常完成回调"）。语义是"本轮没有产出报告"，交总监按审核框架
+   决定重试/换策略/结束。连续 `DEV_FAIL_LIMIT=3` 轮无报告（上游持续故障）→ 停止目标模式并
+   明确告知，避免无限派发空转烧 token。
+2. **总监回合**：异常在 `_run_director_safe` 统一收口为 `None` → 退避重试一次
+   （`DIRECTOR_RETRY_DELAY`）→ 仍失败则 `_pause_director(stage)`：**暂停循环但不关闭
+   `goal_mode`、不删目标/方案/轮次**，给出含原因的可见提示。用户下一句话即从暂停点续跑
+   （`_resume_from_pause` → `_director_loop(resume=stage)`；`review` 阶段用保留的报告重跑
+   复盘，不重新分解）。用户插话失败时消息**放回队首**，不静默丢弃。
+3. **余额**：`parse_balance()` 数值化解析；解析出 `<= 0` 才算耗尽，解析不出（如
+   "(无法获取)"、"(千问: 控制台查看)"）一律视为不确定、**不得据此停止**。
+
+**历史**：归档替代删除。
+
+4. `GoalManager.archive(label)` 把现场（`nfgoal.md`/`plan.md`/`rounds/`）移动到
+   `.nexforge/goal_archive/<YYYYmmdd-HHMMSS>-<label>/`；现场清空 → 下次开启不会被旧目标
+   误判。`archive_rounds()` 只归档轮次（保留目标/方案现场），用于"重启后恢复重跑"——
+   否则新的 `001.md` 会**覆盖**旧轮次（静默丢内容）。
+5. 待确认态下输入分流：`is_plan_question()` 判为提问 → `ask_about_plan()` 只答疑
+   （不动目标、不重新规划、不动工）；其余仍走 `amend_plan()`。
+
+## 理由
+
+- **只做"失败就停模式"不够**：会清掉用户刚输入的长目标（误伤），且上游抖动本可自愈。
+- **只做"无限重试"不够**：上游持续故障时无法收敛，用户看不到进展，token 白烧。
+- **否决"保留现场、停止时不清理"**：会让下次开启把旧目标当成插话（note_20260825_214722）。
+  归档同时满足"历史可查"与"现场干净"。
+- **否决继续用子串判余额**：整元金额必然误判（实测三例），且误判会连带删档。
+- **否决"解析不出余额就当作 0"**：平台不支持余额查询（千问）时会立刻误停 —— 误停代价
+  远高于多跑一轮。
+- **提问判据取保守**：误判成提问会让真正的修改意见被当闲聊（用户以为改了、实际没改，
+  且无任何迹象）；误判成意见只是多展开一轮重规划。两者代价不对称，故只认"明显疑问"
+  （疑问符号 / 疑问尾词 / 疑问开头词）。
+- **暂停后按阶段续跑而非重新分解**：复盘失败时现场有报告和已完成的轮次，重新分解等于
+  让之前的轮次白跑。
+
+## 代价与边界
+
+- 余额查不到（平台无余额 API、网络失败）时，失去"耗尽自动停止"保护 —— 有意取舍。
+- 归档目录随使用增长（每场目标一次），需用户自行清理；不参与会话不变量，也不自动清理。
+- `_dev_fail_streak` / `_director_paused` 是内存态，重启后清零。
+- 暂停恢复是"按阶段续跑"，不重放历史上下文；分解阶段（rounds=0）失败恢复会重新分解
+  （此时无已完成轮次，无损失）。
+- 归档是"移动"，不是"复制"：若用户在同一秒内连续开关目标模式，序号后缀避免覆盖
+  （`-1`/`-2`）。
+- **多进程**：目标文件写入已原子化（读不到半截），但**没有跨进程互斥** —— 同一项目
+  同时跑两个目标模式会互相覆盖 goal/plan/rounds。属于已知边界：目标模式语义本就
+  "一个项目一个目标"，需要时再评估加锁（Windows 无 fcntl，需锁文件方案）。
+
+## 追加（同日）：开发者角色约定与总监上下文治理
+
+同一轮打磨里还修了两处"目标模式跑久了自己坏掉"的隐患：
+
+1. **开发者角色约定**：`DEV_PROMPT`（执行报告格式 / `[BLOCKED]` / `[DUPLICATE]`）
+   此前是死代码 —— 总监复盘 prompt 要求"按报告框架审核"，开发者却从未被告知报告
+   格式，总监拿不到结构化报告就容易误判"未完成"并重复派发。现在随每轮开发者指令
+   注入（`_dispatch_dev` 前置 DEV_PROMPT）。
+2. **总监会话治理**：总监会话只写不读、从未压缩，长目标模式下必然超出上下文窗口 →
+   之后每轮总监回合都失败（进入"暂停"），整体停摆。现在 `trim_director_history()`
+   在每轮 `add_user` 前折叠更早的沟通：保留 system + 最近 30 条 + 一条可见说明
+   （省略了多少条）。可以直接丢早期原文的理由：每轮 ctx 已自带目标/计划/开发者报告。
+
+## 追加（同日）：P2 一致性小项
+
+3. **停止标记必须独立成行**：`_check_director_stop` 原本是**全文搜索** —— 总监提示词里
+   就写着判定词，复盘时复述规则（"尚未达到 GOAL_ACHIEVED 的条件"）会被误判为停止。
+   现在 `_stop_marker()` 只认**行首**标记（容忍 `#`/`-`/`>` 等装饰符），与
+   `2026-09-12-内容里的标记不得当成消息边界` 同源。总监答复用户时也用同一判据收束
+   （避免"嘴上说完成、模式不结束"）。
+4. **轮次展示与判定统一**：`_mx_label()`（0 → `∞`，修掉界面与提示词里的"第1/0轮"）、
+   `_round_limit_hit()`（统一 `round_count() >= max_r` 判定，去掉两处易误读的条件表达式）。
+5. **与 plan/json 模式互斥**：开目标模式时自动关闭 `plan_mode`（API 层 `tool_choice=none`
+   + 只读白名单 → 开发者改不了文件，空转）与 `json_mode`（强制 `response_format=json_object`
+   → 报告/指令/停止标记全变成 JSON 字段），并在界面提示。
+6. **目标文件原子写**：`set_goal` / `set_plan` / `save_round` 改走 `_atomic_write`
+   （临时文件 + `os.replace`）—— 同一项目多进程时读方不会读到半截文件（判据
+   "目标非空/方案非空"不再瞬时误判）。跨进程**互斥锁**仍未做（见"代价与边界"）。
+7. **验收客观证据**：复盘前自动采集工作区改动摘要附到总监 ctx，并明确"与开发者报告
+   冲突时以客观证据为准"。此前总监只能看开发者的**自述报告**（可虚报/漏报）。
+   证据采集走 `asyncio.to_thread`（子进程/树扫描不得阻塞事件循环），失败静默降级为空串。
+
+   实测校准（2026-09-12 真实目标模式运行，被测项目 12 轮 / 12 个里程碑）：
+   - **只靠 git 不够**：被测项目**根本不是 git 仓库**（AI 从零创建的项目常无 git init），
+     `git status/diff` 恒为空 → "以客观证据为准"成空话（会话里"客观证据"出现 38 次，
+     全是规则文本，没有一次真实证据）。**决策：证据源 = git + 文件树快照**——
+     `_snapshot_tree()` 扫描项目树（排除 `.nexforge`/`__pycache__`/`logs`/`node_modules` 等噪音），
+     每轮复盘 diff 出"新增/修改/删除"清单；git 可用时再叠加"未提交改动 + 最近一次提交"
+     （开发者若规范地每轮 commit，只有 `git log -1 --stat` 有信息）。
+   - **总监会话按条数裁剪是无效设计**：该会话 28 条消息 = **请求体量 11.4 万字符**
+     （总监的复盘/指令单条最长 3.8 万字符）；实测 `DIRECTOR_HISTORY_LIMIT=30` 从未触发
+     （28 < 31）。**决策：改为"条数 + 体量"双约束**（`DIRECTOR_CHAR_BUDGET = 60_000` 字符，
+     最新 ctx 无论如何必须完整保留）。真实数据验证：该会话 28 条/11.4 万 → 16 条/6.1 万。
+
+   > 注：会话文件显示 53.2 万字符是**人读格式里结构标记 base64 负载**造成的膨胀，
+   > 不等于发给模型的大小 —— 判据要落到"请求体量"（`director_load` 实测），不要看文件字节数。
+8. **总监只读工具**（`[ui] director_tools`，默认开）：总监回合从 `provider.complete`
+   改为 `AgentLoop.run_turn`，带 `tool_filter=DIRECTOR_READONLY_TOOLS`（9 个只读工具：
+   read_file / list_dir / search_content / search_files / git_status / git_diff /
+   inspect_text / read_csv / query_sqlite）与 `max_iters=8`（核验不是通读仓库）。
+   理由：总监此前只能看开发者自述 + 预采证据，无法"自己看一眼"就下判断。
+   硬边界（不靠提示词自律）：目标模式是 auto 免审批 → 写/删/执行类工具**在 API 层
+   不下发**（顺带把工具 schema 从 39 个压到 9 个，省约 7.7k tokens/次）。
+   代价与开关：每用一次工具就多一轮往返、工具结果进上下文（成本上升），因此留开关；
+   **`tool_filter=set()`（空集）= 一个工具都不给，`None` = 不限制** —— 关开关时传空集，
+   避免把全部工具连同写权限放开（这是实现时真实踩到的坑，已用测试钉住）。
+9. **`max_iters` 不得被目标模式放大**：目标模式会把普通工具轮数上限提到 500，
+   受限角色显式传入的 `max_iters` 优先（`AgentLoop._iter_limit()`），否则一次核验
+   可能把整个仓库读完。
+10. **会话分段容量 200 → 500 行，切分改用真实行数**（`_SEGMENT_MAX_LINES`、
+    `_msg_line_count` 精确化）：
+    - 实测（2026-09-12 目标模式会话）：943 条消息 / 21,141 行 → 200 行/段 =
+      **111 个文件/会话**（现场观测 121 个），而每次保存都全量重写它们；改成 500 行后
+      **43 个**（-61%）。旧会话无需迁移：下次保存即按新容量重写并 prune 多余段。
+    - 连带修掉一个真问题：`_msg_line_count` 原为**估算**（漏算标题行、思考折叠标签、
+      工具调用块、结构标记行与空行）→ 按"≤500 行"切出的段实际可达 **744 行**，
+      容量约束形同虚设。改成直接量 `_format_message()` 的真实行数（切分本来就要
+      格式化，总成本不变）。
+    - 否决"增量写分段"：收益只是省 IO（3MB 写入在 SSD 上是几十毫秒），代价是要处理
+      压缩导致的段前缀变化、旧段被手改等失败模式 —— 复杂度/风险不成比例。真痛点是
+      **文件数**（会话列表、孤儿清理、备份都要扫它们），故只解决它。
+11. **归档查看/清理入口**（`/goal archive`、`/goal archive clean [N]`）：归档只增不减
+    （每场目标一次，实测 12 轮 ≈ 75KB），需要"看得见、能决定删哪些"的入口。
+    `GoalManager.list_archives()` 按目录名（时间戳+标签，同秒带序号）降序 → 新的在前，
+    并统计轮数与体积；`clean_archives(keep)` 保留最近 keep 场（0 = 全删）。
+    **删除必须过确认弹窗**：归档是轮次复盘记录的唯一副本，不可逆 —— 与"不允许无声
+    丢失"同一条纪律（不禁止删除，但必须由用户明确确认）。keep 大于实际场数时一个
+    都不删（参数越界不得造成误删，测试钉住）。
+
+   > 完整的"总监只读工具"（总监自己调 read_file/git_status 等）**未做**：
+   > 需要给 `AgentLoop` 加工具白名单并让总监回合走工具循环，会改变 token 消耗与
+   > 行为，需真机验证后再上。当前用"预采证"拿同等价值的信息，零行为风险。
+
+## 关联
+
+- 模块：`features/mode_features.py`（回执/重试/暂停/恢复/提问/开发者约定）、
+  `ui/screens/chat.py`（`_run_agent` finally 回执、待确认态分流、总监会话裁剪）、
+  `ui/screens/chat_actions.py`（Esc 停止改为归档）、
+  `core/goal_manager.py`（`parse_balance` / `archive` / `archive_rounds` /
+  `trim_director_history`）
+- 文档：`manual/06-权限与模式.md`（目标模式一节）、`doc/项目总监循环-开发计划.md`
+- 测试：`tests/test_goal_stability.py`（28 例：余额判据 / 失败回执 / 暂停恢复 / 归档 /
+  提问分流 / 开发者角色约定 / 总监会话裁剪）、
+  `tests/test_goal_confirm.py`（Esc 归档断言）、`tests/test_director_loop.py`（停止归档断言）
+- 知识库：note_20260824_124256（P1 常驻循环）、note_20260825_214722 / note_20260825_215306、
+  note_20260907_025446