nexforge-cli 0.2.18__tar.gz → 0.3.0__tar.gz

{nexforge_cli-0.2.18 → nexforge_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.2.18
+Version: 0.3.0
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge
@@ -51,11 +51,14 @@ Description-Content-Type: text/markdown
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.18** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.3.0** · PyPI: `pip install nexforge-cli`
 
-**v0.2.18 要点**：新增 `/capabilities`（一眼看清各能力是否可用、为何不可用）；
-会话可重建（恢复/切换后模型看到的历史与当初一致，工具链不再丢失）；
-插件与配置的静默失败治理（出错必可见）；敏感文件硬拦截；push 前质量门禁。
+**v0.3.0 要点**（**含破坏性变更**）：档位简化为单档 `flash`——`/model pro`、`/model auto`、
+`/model vision` 不再可用（`pro` 档与 `vision` 档模型均已下线；`deepseek-flash` 原生多模态，
+文本与读图一档搞定）；旧配置里的档位值会自动迁移为 `flash` 并给出可见提醒。
+另含：终端状态兜底恢复 + 退出看门狗（进程被硬中断时不再留下被鼠标序列刷屏的终端）、
+模型侧边栏绿点恒为一个（只标当前在用的模型）、历史归档不再静默丢批次、
+两层重试放大修复（429 时由最多 12 次请求降为 `1 + max_retries` 次）。
 
 ---
 

{nexforge_cli-0.2.18 → nexforge_cli-0.3.0}/README.md

@@ -8,11 +8,14 @@
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.18** · PyPI: `pip install nexforge-cli`
-
-**v0.2.18 要点**：新增 `/capabilities`（一眼看清各能力是否可用、为何不可用）；
-会话可重建（恢复/切换后模型看到的历史与当初一致，工具链不再丢失）；
-插件与配置的静默失败治理（出错必可见）；敏感文件硬拦截；push 前质量门禁。
+> 当前版本:**v0.3.0** · PyPI: `pip install nexforge-cli`
+
+**v0.3.0 要点**（**含破坏性变更**）：档位简化为单档 `flash`——`/model pro`、`/model auto`、
+`/model vision` 不再可用（`pro` 档与 `vision` 档模型均已下线；`deepseek-flash` 原生多模态，
+文本与读图一档搞定）；旧配置里的档位值会自动迁移为 `flash` 并给出可见提醒。
+另含：终端状态兜底恢复 + 退出看门狗（进程被硬中断时不再留下被鼠标序列刷屏的终端）、
+模型侧边栏绿点恒为一个（只标当前在用的模型）、历史归档不再静默丢批次、
+两层重试放大修复（429 时由最多 12 次请求降为 `1 + max_retries` 次）。
 
 ---
 

{nexforge_cli-0.2.18 → nexforge_cli-0.3.0}/config.example.toml

@@ -1,42 +1,30 @@
-# NexForgeCLI 配置示例。
-# 复制到 ~/.nexforge/config.toml 后按需修改;所有字段都有内置默认值,可只写要覆盖的项。
-# DeepSeek V4 参数已核实自 api-docs.deepseek.com(2026-04)。
-
-[provider]
-base_url = "https://api.deepseek.com"     # OpenAI 格式;Anthropic 格式加 /anthropic
-api_key_env = "DEEPSEEK_API_KEY"           # 优先从此环境变量读 key
-# api_key = "sk-..."                       # 次选:直接写这里(不建议入库)
-timeout = 120.0
-max_retries = 2
-
-[models]
-flash = "deepseek-v4-flash"
-pro = "deepseek-v4-pro"
-default_tier = "auto"                      # flash | pro | auto
-thinking = true                            # 思考模式,默认开
-reasoning_effort = "high"                  # high | max
-max_output_tokens = 8192                   # 上限 384K
-
-# 定价(每百万 token,USD)—— 已核实
-[models.pricing.flash]
-input_cache_hit = 0.0028
-input_cache_miss = 0.14
-output = 0.28
-
-[models.pricing.pro]
-input_cache_hit = 0.003625
-input_cache_miss = 0.435
-output = 0.87
-
-[router]                                   # auto 档位的客户端路由
-entry = "flash"                            # auto 默认从 flash 起步
-escalate_to = "pro"
-escalate_on_tool_failures = 2
-escalate_context_tokens = 200000
-
-[ui]
-theme = "dark"                             # dark | light
-show_thinking = true
-icons = "auto"                             # auto | image | glyph | ascii
-accent = "#6D5EF5"
-accent2 = "#22D3EE"
+# NexForgeCLI 配置示例。
+# 复制到 ~/.nexforge/config.toml 后按需修改;所有字段都有内置默认值,可只写要覆盖的项。
+# DeepSeek V4 参数已核实自 api-docs.deepseek.com(2026-04)。
+
+[provider]
+base_url = "https://api.deepseek.com"     # OpenAI 格式;Anthropic 格式加 /anthropic
+api_key_env = "DEEPSEEK_API_KEY"           # 优先从此环境变量读 key
+# api_key = "sk-..."                       # 次选:直接写这里(不建议入库)
+timeout = 120.0
+max_retries = 2
+
+[models]
+flash = "deepseek-flash"                  # 原生多模态(文本+读图), 取代原 v4-flash + vision 双档位
+default_tier = "flash"                     # 档位只剩 flash(pro/auto/vision 均已移除)
+thinking = true                            # 思考模式,默认开
+reasoning_effort = "high"                  # high | max
+max_output_tokens = 8192                   # 上限 384K
+
+# 定价(每百万 token,USD)—— 已核实
+[models.pricing.flash]
+input_cache_hit = 0.0028
+input_cache_miss = 0.14
+output = 0.28
+
+[ui]
+theme = "dark"                             # dark | light
+show_thinking = true
+icons = "auto"                             # auto | image | glyph | ascii
+accent = "#6D5EF5"
+accent2 = "#22D3EE"

nexforge_cli-0.3.0/docs/decisions/2026-09-11-deepseek/346/241/243/344/275/215/347/256/200/345/214/226.md

@@ -0,0 +1,42 @@
+# 决策：DeepSeek 档位简化为 flash / vision（移除 pro 与 auto）
+
+> 日期：2026-09-11 · 状态：生效 · **破坏性变更**
+
+## 背景
+
+DeepSeek 调整模型阵容后，`pro` 档基本无用；而 `auto` 档的唯一作用是"命中升级信号时自动升到 pro"。
+用户要求简化 DS 的模型列表（"只保留 flash，包括 pro 在内全部删掉"）。
+
+同期实测（`docs/evidence/model_rename_check.log`）：官方 `GET /models` 只剩 `deepseek-flash` 与 `deepseek-v4-pro`。
+
+## 决策
+
+1. `Tier` 从 `flash / pro / auto / vision` 简化为 **`flash / vision`**。
+2. 删 `ModelsConfig.pro` 与其计价项。
+3. **删除 `RouterConfig` 与整个 `core/router.py`**（`Router` 类）——
+   `agent.py` 改为直接按用户选定档位构造 `RouteDecision`。
+4. `vision` **保留**：识图与贴图直达模型的必需档位。
+
+## 理由
+
+- **pro 已无用**（用户判断 + 实测支持），保留只会增加配置面与认知负担。
+- **auto 是死逻辑**：它存在的意义是"升级到 pro"，没有 pro 就无从升级。
+- **否决"保留 auto 但降级为 flash"**：那等于给一个不存在的选择留按钮，纯误导。
+- **否决"保留 pro 但改指向别的模型"**：用户诉求就是删掉它。
+
+## 代价与边界
+
+- **破坏性**：`/model pro` 与 `/model auto` 不再可用（会提示未知档位）；
+  配置文件里残留的 `[router]` 段与 `models.pro` 将被"未知字段"检查提示（见 B 工程）。
+  已写入的 `models.default_tier = "pro"/"auto"` 会自动迁移为 `flash` 并告警（见下一条 ADR）。
+- **恢复成本**：若 DeepSeek 未来重启 pro/推理档，需要重新加档位 + 计价，
+  并视情况恢复路由机制。
+  （数据载体 `RouteDecision` 仍在，但已内联到 `core/agent.py` 并退化为"固定档位"记录；
+  `Router` 与 `core/router.py` 已随单档化删除 —— 恢复路由需重写，不是改开关。）
+- `reasoning_effort` / `thinking` 仍由 `[models]` 控制，效果不变——**只是不再自动切换**。
+
+## 关联
+
+`src/nexforge/config.py`、`src/nexforge/core/agent.py`（`router.py` 已删）、
+`ui/widgets/model_sidebar.py`、`ui/widgets/statusbar.py`、`ui/slash_handler.py`、`cli.py`、`web/server.py`、
+`manual/02`、`manual/03`、`manual/08`、`config.example.toml`

nexforge_cli-0.3.0/docs/decisions/2026-09-11-/346/241/243/344/275/215/347/256/200/345/214/226/344/270/272/345/215/225/346/241/243flash.md

@@ -0,0 +1,90 @@
+# ADR: 档位简化为单档 flash
+
+- 日期: 2026-09-11
+- 状态: 已采纳
+- 类型: **破坏性变更**
+
+## 背景
+
+DeepSeek 于 2026-09 调整模型阵容：
+
+1. `deepseek-v4-pro` 处于更新前的尴尬期，实际可用性差 → 此前（2026-09）已删除 `pro` 与 `auto` 档位。
+2. 当时保留 `vision` 档位（模型 `deepseek-v4-flash-vision-exp`）用于识图。
+3. 现在官方新模型 **`deepseek-flash`** 已**原生多模态**（实测可准确读图），而原 flash 档位模型 `deepseek-v4-flash` **不支持读图**。
+
+实测证据（`docs/evidence/model_rename_check.log`）：
+
+| 模型 | 文本 | 读图 |
+|---|---|---|
+| `deepseek-v4-flash-vision-exp` | OK | 蓝圆 + 红三角 |
+| `deepseek-flash` | OK | 蓝圆、红 |
+| `deepseek-v4-flash` | OK | 空（不支持） |
+
+## 决策
+
+**档位从 `flash / vision` 简化为单一 `flash`**，且 `flash` 档位模型由 `deepseek-v4-flash` 改为 `deepseek-flash`。
+
+具体改动：
+
+1. `Tier = Literal["flash"]`；删除 `ModelsConfig.vision` 与 `pricing.vision`。
+2. `models.flash` 默认值 → `deepseek-flash`（原生多模态）。
+3. 删除 F6 侧边栏的档位子按钮渲染与 `ms-tier-*` 分支（只剩单档，子选项失去意义）。
+4. 识图能力探测（`VisionCapability`）与 `_provider_vision_channel` 不再回退 `cfg.models.vision`，改为当前档位模型。
+5. CLI / 斜杠命令 / web 的档位白名单只保留 `flash`。
+
+## 理由
+
+- **避免静默失败**（核心）：若只删 vision 档位而不改 flash 模型名，用户切到 flash 后贴图会因 `deepseek-v4-flash` 不支持读图而**静默失败**——正是本项目持续根治的病（见 ADR-2026-09-10-fails-loud分级）。
+- **消除冗余**：`deepseek-flash` 一档同时覆盖文本与读图，独立视觉档位不再必要。
+- **代价可控**：旧档位名（`pro`/`vision`）写错会被明确拒绝，而非静默降级到错误模型。
+
+## 复盘：改名漏改一处判定，贴图静默退化（2026-09-11 第五轮复核）
+
+**症状**：默认档位下贴图只发出 `[图片附件: 路径]` **文本占位符**，模型根本看不到图；
+识图工具通道报"模型 deepseek-flash 不支持图片输入"（与实测相反）；而 `/capabilities`
+**又报"可用"** —— 三者互相矛盾。
+
+**根因**：多模态判定只有两条规则 —— ①模型名含 `"vision"`；②`models.toml` 里该
+provider 显式 `multimodal = true`。而内置 deepseek **没有 pdef**（不在 `providers` 表里），
+新档位模型 `deepseek-flash` 名字里**也没有 "vision"**（旧档位模型
+`deepseek-v4-flash-vision-exp` 靠名字就能过）→ 判定为纯文本。
+`/capabilities` 之所以说"可用"，是因为它的判据里有个 `or cfg.model_id()`，而
+`model_id()` 恒非空 —— 于是"上报与实际"分叉。
+
+**修法**：
+1. `provider/deepseek.py` 增加显式名单 `NATIVE_MULTIMODAL_MODELS = {"deepseek-flash"}`
+   （与既有 `"vision"` 名字规则并列）；
+2. 抽出 `image_tools.vision_channel(cfg)` 作为**唯一**判定，供贴图通道、识图工具
+   与 `VisionCapability` 三处共用（消除"上报说可用、实际跑不通"）。
+
+**为什么不用"配置开关"代替名单**：若让 `models.flash` 一律视为多模态，用户把它改成
+纯文本模型（如 `deepseek-v4-flash`）时会被错误放行 → 又把图片发给看不懂的模型。
+名单式规则与既有 `"vision"` 规则同构，代价小。
+
+**维护纪律**：**DeepSeek 再次改名时，`NATIVE_MULTIMODAL_MODELS` 必须与本文同步更新。**
+这也解释了为什么"档位模型名"不是一个纯配置项 —— 它同时是多模态判定的输入。
+
+## 代价与边界
+
+- **破坏性**：`/model pro`、`/model auto`、`/model vision` 不再可用。
+- 用户 `config.toml` 若残留 `models.vision` 或 `[models.pricing.vision]`，启动时会有"未知字段"提示（这是 B 工程配置校验在提醒），删掉即可。
+- **升级残留的档位值会自动迁移**（2026-09-11 三轮复核补充）：旧版本的 `/model pro`
+  会把 `default_tier = "pro"` **写进 config.toml**（`slash_handler` 的持久化），
+  若不处理，升级后会在校验阶段直接中止启动（exit 2）——用户被挡在门外、只能手改 TOML。
+  现按既有 `mode: review → supervised` 的迁移先例处理：`pro`/`auto`/`vision` 三个**已知被移除**
+  的档位名 → 自动改为 `flash` 并**发出可见告警**；真正的拼写错误（如 `flsh`）仍照常报错中止。
+  实现在 `config.py:_migrate_removed_tier()`（用户级与项目级两条路径都覆盖）。
+- `supports_model_multimodal` 仍保留 `"vision" in 模型名` 判定——用于**兼容外部显式传入的 vision 系模型名**（如用户自挂的 exp 模型），不属档位概念。
+
+## 备选方案（未采纳）
+
+| 方案 | 未采纳原因 |
+|---|---|
+| 保留 vision 档位，仅改 flash 模型名 | 两档模型实际相同（都是多模态），用户需无谓切换 |
+| flash 仍用 `deepseek-v4-flash` | 该模型不支持读图，会引入静默失败 |
+| 用 `deepseek-v4-flash-vision-exp` 作 flash | exp 为实验版、名字带过期语义，非长期选择 |
+
+## 相关
+
+- ADR-2026-09-11-deepseek档位简化（本轮，pro/auto 删除）
+- ADR-2026-09-10-能力可用性上报（vision 能力探测同源）

nexforge_cli-0.3.0/docs/decisions/2026-09-11-/347/273/210/347/253/257/347/212/266/346/200/201/345/205/234/345/272/225/346/201/242/345/244/215.md

@@ -0,0 +1,91 @@
+# 决策：终端状态兜底恢复 + 退出看门狗
+
+> 日期：2026-09-11 · 状态：生效
+
+## 背景
+
+**现象**：nf TUI 非正常结束后，命令行被持续刷屏——移动鼠标就喷出 `[555;x;yM`
+之类的原始转义序列，终端看起来"坏掉了"。
+
+**已查证的事实**（源码级 + 本机实测）：
+
+1. 那串字符是**鼠标追踪的 SGR 上报**（`ESC[<b;x;yM`）。终端一旦停在"鼠标追踪开启"
+   状态，鼠标一动就会把上报序列当普通字符打进命令行。
+2. Textual 只在**正常退出 / 被捕获的异常**路径恢复终端
+   （`textual/app.py:3495-3514` 的 `finally: driver.stop_application_mode()`）。
+3. **硬杀无人收尾**：Windows `CTRL_BREAK_EVENT` → Python `SIGBREAK` 默认动作是直接
+   终止进程；`taskkill /F`、直接关闭控制台窗口同理。Textual 在 Windows 下
+   **不安装任何信号处理器**（只给 Linux 驱动装了 SIGTSTP/SIGCONT/SIGWINCH）。
+4. 本机 `WT_SESSION` 存在（Windows Terminal）→ `_mouse_enabled()` 为 True
+   → 鼠标追踪**确实处于开启状态**，泄漏条件成立
+   （`docs/evidence/terminal-leak-conditions.log`）。
+
+**直接触发**：一次复现脚本用 `CTRL_BREAK_EVENT` 结束子进程，却没有建独立进程组 ——
+Windows 控制台事件是**按进程组**投递的，于是这次 CTRL_BREAK 同时打中了宿主 TUI 自己，
+TUI 被硬杀，终端留在鼠标追踪模式。
+
+**被实测否掉的假设**（不是推测，每条都有数据）：
+
+| 假设 | 实测结论 | 证据 |
+|---|---|---|
+| 余额轮询卡在网络 → 退出卡住 | **否**：挂起定时器（可取消 / 不可取消）与基线**同量级**（0.6～1.5s，随负载浮动；关键是相对结论） | `docs/evidence/exit-cost.log` |
+| `Timer._stop_all` 会等待定时器回调 | 会 `await timer._task`，但 `cancel()` 立即打断 await（线程在后台继续） | `scripts/exit_cost_probe.py` |
+| `Ctrl+Q`（App 级 priority 绑定）绕过清理 | **否**：`on_unmount` 兜底已覆盖该路径 | 两条退出路径的清理钩子均被调用 |
+| 正常退出会漏清理 | **否**：作业/会话/隧道清理都执行了 | 同上 |
+
+结论：**不存在"退出卡住"缺陷**；真实缺口是"非 Python 异常路径缺少终端兜底恢复"。
+
+## 决策
+
+新增 `src/nexforge/terminal_guard.py`，提供三层保护：
+
+1. `restore_terminal()`：幂等写入"关鼠标（4 种模式）/ 关括号粘贴 / 关 kitty 键盘协议 /
+   退备用屏 / 显示光标 / 复位 SGR"，与 Textual 的 `stop_application_mode()` 对齐；
+   非 TTY 默认不写，`force=True` 无条件写，且**绝不抛异常**。
+2. `install_signal_guard()`：Windows 下接管 `SIGBREAK`，恢复终端后再退出
+   （这正是本次事故缺的那一环）。
+3. **退出看门狗**：`run_tui` 运行期开启闸门；出现退出请求（`App.exit()`）即开始计时，
+   超时（默认 8s，`NEXFORGE_EXIT_TIMEOUT` 可调）则恢复终端并 `os._exit(0)` ——
+   把"卡退"从"用户只能强杀、终端报废"降级为"最多等 8 秒、终端自动恢复"。
+4. **能力缺失不静默**：`SIGBREAK` 接管失败时向 stderr 显式告警（含逃生舱指引），
+   不允许"用户以为有保护、实际没有" —— 直接适用
+   `ADR-2026-09-10-fails-loud分级` 第 4 条。
+
+`run_tui` 另加：崩溃路径 `force` 恢复后**继续抛出原异常**（不吞错）；返回路径兜底恢复一次。
+
+## 理由
+
+- 只靠 Textual 的 `finally` 覆盖不到硬杀，而用户遇到的正是硬杀后的坏终端。
+- 三层里任一层单独都不够：看门狗管"退不掉"，信号兜底管"被打断"，
+  返回路径兜底管"异常/正常都补一刀"。
+- 全部标准库实现，非 Windows 平台自动降级为空操作。
+
+## 代价与边界
+
+- **闸门是必须的**：无头测试 / 嵌入式调用 / 探针脚本都不走 `run_tui`，若 `App.exit()`
+  无条件武装看门狗，就没人取消它 → 8 秒后 `os._exit()` 会把该进程直接带走。
+  这个坑是**真踩到的**：`scripts/exit_cost_probe.py` 曾在打印结论前被截断。
+  现在闸门关闭时 `arm_exit_watchdog()` 完全不动进程（有回归测试锁定）。
+- **不可恢复场景**：`taskkill /F`（TerminateProcess）无法在进程内做任何事，
+  只能靠终端自身；逃生舱为 `NEXFORGE_MOUSE=0`（跨平台强制关闭鼠标追踪）。
+- 看门狗兜底 8 秒是宽限值；正常退出实测 0.6～1.5s（随机器负载浮动），留着充足余量。
+- 兜底序列与 Textual 自身的恢复序列一致；在**未开启 VT 处理**的老式 conhost 上
+  它们可能显示为可见字符（与 Textual 行为同源）。不过那种终端本来就不会启用鼠标
+  追踪（`_mouse_enabled()` 已按此判定），所以实际影响可忽略。
+
+## 纪律（写给后续）
+
+> **在 Windows 上向其他进程发控制台事件（CTRL_C / CTRL_BREAK）之前，必须
+> `CREATE_NEW_PROCESS_GROUP`；若要独立控制台再加 `CREATE_NEW_CONSOLE`。
+> 否则事件按进程组投递，会打中调用者自己。**
+
+`scripts/exit_smoke.py` 里对这两个标志做了断言式自检，作为可执行的纪律。
+
+## 相关
+
+- `src/nexforge/terminal_guard.py`、`src/nexforge/app.py`（`run_tui` / `NexForgeApp.exit`）
+- ADR-2026-09-10-fails-loud分级（本模块的静默/可见边界按其裁定）
+- `tests/test_terminal_guard.py`（19 项：恢复序列 / 看门狗 / 闸门 / 信号 / 可见降级 / run_tui 集成）
+- `scripts/exit_cost_probe.py`（退出耗时对照探针）、`scripts/exit_smoke.py`（真实进程退出冒烟）
+- 证据：`docs/evidence/exit-cost.log`、`docs/evidence/terminal-leak-conditions.log`
+- 既有相关修复：`ad1fac6`（conhost 禁用鼠标追踪）、`25304a4`（VS Code 终端保留鼠标）

nexforge_cli-0.3.0/docs/decisions/2026-09-11-/351/207/215/350/257/225/345/275/222/344/270/200/345/261/202.md

@@ -0,0 +1,62 @@
+# 决策：重试只归一层（包装器负责，SDK 归零）
+
+> 日期：2026-09-11 · 状态：生效
+
+## 背景
+
+`provider/_retry.py` 的 `retry_on_rate_limit()` 包住 `chat.completions.create`，
+同时 openai SDK 客户端构造时也配了 `max_retries`（来自 `config.provider.max_retries`，
+默认 2）。两层各自重试，于是**放大**：
+
+用 `httpx.MockTransport` 实测（持续 429，退避打桩为瞬时）：
+
+| 层 | 次数 |
+|---|---|
+| 包装器 `retry_on_rate_limit`（调用点未传参 → 默认 3） | 4 次调用 |
+| 每次调用内 SDK 自己重试（`max_retries=2`） | 3 次尝试 |
+| **合计 HTTP 请求** | **12** |
+
+副作用：
+1. **配额与限流**：一次用户提问在 429 下打出 12 次请求 —— 既浪费，也可能加重限流；
+2. **配置失真**：`provider.max_retries` 只影响 SDK 层，对包装器**无效**，
+   用户调它看不到预期效果；
+3. **最坏等待**：若每次都耗到 `timeout`（120s），上限是 12×120s（远超合理范围）。
+
+## 决策
+
+**重试只保留一层，且以我们的包装器为准**：
+
+1. 包装器内用 `self._client.with_options(max_retries=0)` 调 SDK，
+   **关掉 SDK 的内层重试**；
+2. 包装器显式接收 `pdef.max_retries or config.provider.max_retries` ——
+   配置项成为唯一权威；
+3. 三个走包装器的 provider（deepseek / openai / qianwen）一致处理。
+   （anthropic 不走该包装器，仍由自身 SDK 重试，不在本次范围。）
+
+修后实测：**3 次请求**（= 1 + `max_retries`），配置改动可观察。
+
+## 理由
+
+- **单一职责**：重试是策略，属于我们可观测、可配置、可测试的那一层；
+  两层叠加等价于"把重试次数相乘"，而没人会期望这个乘法。
+- **可测**：MockTransport 计数让"到底打了几次 API"变成可断言的事实，
+  而不是靠读代码推断（本决策的证据即由此而来）。
+- **否决"保留两层、只把配置传下去"**：那只是让乘法变得可配置，放大依旧。
+- **否决"关掉包装器、只信 SDK"**：包装器提供了显式的 429/5xx 集合与
+  统一的错误包装（`ProviderError` 便于上层显示），且我们能在其中加观测。
+
+## 代价与边界
+
+- SDK 层原生的 `Retry-After` 处理随之失效 —— 退避改由包装器的
+  指数退避 + 抖动（上限 15s）承担。若将来需要尊重 `Retry-After`，
+  应加在包装器里（并在测试中覆盖）。
+- 非流式调用（`models.list` 等）不走包装器，仍用 SDK 重试 —— 这属于
+  "另一条路径"，本次未动；若要统一，需把这些调用也纳入包装器。
+- 退避等待用 `await asyncio.sleep`（**可取消**），因此"停止/退出"不会被
+  退避拖住 —— 与 `terminal_guard` 的退出兜底同源关切。
+
+## 验证
+
+- `tests/test_retry_policy.py`（12 项）：可重试/不可重试状态码、
+  `1 + max_retries` 次数、配置权威性、**两层不放大**（实测计数）、退避可取消。
+- 复盘脚本证据：12 次 → 3 次。

{nexforge_cli-0.2.18 → nexforge_cli-0.3.0}/docs/decisions/README.md

@@ -61,3 +61,7 @@
 | 2026-09-10 | [能力可用性上报](2026-09-10-能力可用性上报.md) | 生效 |
 | 2026-09-10 | [审计以调用链为准](2026-09-10-审计以调用链为准.md) | 生效 |
 | 2026-09-10 | [依赖一致性](2026-09-10-依赖一致性.md) | 生效 |
+| 2026-09-11 | [DeepSeek 档位简化（删除 pro/auto）](2026-09-11-deepseek档位简化.md) | 已取代 → 见下行 |
+| 2026-09-11 | [档位简化为单档 flash](2026-09-11-档位简化为单档flash.md) | 生效 · 破坏性 |
+| 2026-09-11 | [终端状态兜底恢复 + 退出看门狗](2026-09-11-终端状态兜底恢复.md) | 生效 |
+| 2026-09-11 | [重试只归一层](2026-09-11-重试归一层.md) | 生效 |

nexforge_cli-0.3.0/docs/evidence/exit-cost.log

@@ -0,0 +1,9 @@
+=== TUI exit cost probe (headless) ===
+  [A baseline] quit->shutdown =   1.32s
+  [B cancellable hang] quit->shutdown =   1.49s
+  [C blocking call] quit->shutdown =   1.06s
+
+A baseline        : 1.32s
+B cancellable hang: 1.49s  (delay +0.17s)
+C blocking call   : 1.06s  (delay -0.26s)
+>>> 无拖慢: 退出耗时与是否挂起无关

nexforge_cli-0.3.0/docs/evidence/final_check_fulltest.log

@@ -0,0 +1,7 @@
+........................................................................ [ 16%]
+................sss..................................................... [ 33%]
+........................................................................ [ 50%]
+........................................................................ [ 66%]
+........................................................................ [ 83%]
+......................................................................   [100%]
+427 passed, 3 skipped in 107.39s (0:01:47)

nexforge_cli-0.3.0/docs/evidence/final_check_pypi.log

@@ -0,0 +1,11 @@
+=== 发布产物可用性验证 ===
+=== 11) 从 PyPI 真实安装 nexforge-cli==0.2.18 ===
+  pip 退出码: 0
+  安装顶层条目: ['bin', 'nexforge', 'nexforge_cli-0.2.18.dist-info']
+  nexforge.__version__ = 0.2.18
+=== 12) 本版新增模块可用性 ===
+  capability OK
+engines: ['bing', 'duckduckgo', 'google', 'searxng']
+config-issue API OK
+  (临时安装目录已清理)
+exit=0

nexforge_cli-0.3.0/docs/evidence/final_check_report.log

@@ -0,0 +1,22 @@
+=== 发布后全量检查 ===
+=== 7) 静默捕获扫描(AST) ===
+  裸 except: pass = 94 处 (体检时为 101 处)
+  注: 经体检分类, 其中绝大多数为合理防御(清理/关闭/探测/UI 元素查找)
+
+=== 8) 文档索引完整性 ===
+  ADR 文件数: 7
+  索引失效链接: 无
+  未登记 ADR: 无
+
+=== 9) 其他文档 ===
+  OK  docs/session-invariant.md
+  OK  manual/11-开发校验.md
+  OK  plugin_speech_summary/README.md
+
+=== 10) 发布产物抽检(whl) ===
+  文件数: 128
+  OK  nexforge/core/capability.py
+  OK  nexforge/tools/search.py
+  OK  nexforge/store/session_store.py
+  插件示例是否误入包: False (应为 False)
+exit=0

nexforge_cli-0.3.0/docs/evidence/model-sidebar-dot.log

@@ -0,0 +1,54 @@
+============================================================
+真实配置 / 激活 deepseek   [激活 provider = deepseek]
+============================================================
+  | deepseek                                             | 
+  |   ● deepseek-flash                                   | <-- 绿点
+  | kimi ⚪                                               | 
+  | 🔍 验证                                                 | 
+  |     kimi-k3                                          | 
+  | 🔄 刷新模型                                               | 
+  | local ⚪                                              | 
+  | 🔍 验证                                                 | 
+  |     D:\LocalModels\models\qwen2.5-14b-instruct-q4_k_m.gguf | 
+  | 🔄 刷新模型                                               | 
+  | 验证全部                                                 | 
+  合计绿点 = 1
+
+============================================================
+真实配置 / 激活 kimi   [激活 provider = kimi]
+============================================================
+  | deepseek                                             | 
+  |     deepseek-flash                                   | 
+  | kimi ⚪                                               | 
+  | 🔍 验证                                                 | 
+  |   ● kimi-k3                                          | <-- 绿点
+  | 🔄 刷新模型                                               | 
+  | local ⚪                                              | 
+  | 🔍 验证                                                 | 
+  |     D:\LocalModels\models\qwen2.5-14b-instruct-q4_k_m.gguf | 
+  | 🔄 刷新模型                                               | 
+  | 验证全部                                                 | 
+  合计绿点 = 1
+
+============================================================
+合成配置 / 激活 anthropic 类 provider   [激活 provider = claude]
+============================================================
+  | deepseek                                             | 
+  |     deepseek-flash                                   | 
+  | claude ⚪                                             | 
+  | 🔍 验证                                                 | 
+  |   ● claude-sonnet-4                                  | <-- 绿点
+  | 验证全部                                                 | 
+  合计绿点 = 1
+
+============================================================
+合成配置 / deepseek 激活, anthropic 未激活   [激活 provider = deepseek]
+============================================================
+  | deepseek                                             | 
+  |   ● deepseek-flash                                   | <-- 绿点
+  | claude ⚪                                             | 
+  | 🔍 验证                                                 | 
+  |     claude-sonnet-4                                  | 
+  | 验证全部                                                 | 
+  合计绿点 = 1
+

nexforge_cli-0.3.0/docs/evidence/model_rename_check.log

@@ -0,0 +1,52 @@
+=== DeepSeek 模型名实测 ===
+=== DeepSeek 模型名可用性实测 ===
+  [不可用] deepseek-v4.1-flash  HTTP 400: The supported API model names are deepseek-flash, deepseek-v4-pro, but you passed deepseek-v4.1-flas
+  [可用] deepseek-v4.1-flash-expires-on-0910  -> 回复: ''
+exit=0
+=== DeepSeek 模型名全面探测 ===
+=== 1) GET /models (官方可用模型列表, 最权威) ===
+  HTTP 200
+    - deepseek-flash
+    - deepseek-v4-pro
+
+=== 2) 逐个 chat 实测(max_tokens=64 避免空回复) ===
+  [200] deepseek-flash                         content='好的' finish=stop
+  [200] deepseek-v4-pro                        content='好的' finish=stop
+  [400] deepseek-v4.1-flash                    The supported API model names are deepseek-flash, deepseek-v4-pro, but you passed deepseek
+  [200] deepseek-v4.1-flash-expires-on-0910    content='好的' finish=stop
+  [200] deepseek-v4-flash                      content='好的' finish=stop
+exit=0
+
+=== deepseek-flash 能力验证 ===
+=== 1) 文本能力 ===
+  HTTP 200  content=''
+
+=== 2) 读图能力(贴 base64 图片, 问它看到什么) ===
+  HTTP 200
+  回答: '这张图是纯色背景，'
+  => 支持读图: True
+exit=0
+
+=== 改名后端到端验证 ===
+Traceback (most recent call last):
+  File "D:\DevelopProject\NexForge\NexForgeCLI\.nexforge\_v41_e2e.py", line 11, in <module>
+    from nexforge.core.provider import ChunkKind  # noqa: E402
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ImportError: cannot import name 'ChunkKind' from 'nexforge.core.provider' (D:\DevelopProject\NexForge\NexForgeCLI\src\nexforge\core\provider.py)
+exit=1
+
+=== 改名后端到端验证 ===
+=== 1) 配置加载 ===
+  provider name = deepseek-v41
+  models        = ['deepseek-flash']
+  default_model = deepseek-flash
+  multimodal    = True
+
+=== 2) provider 实例化 ===
+  类型 = DeepSeekProvider
+  支持读图 = True
+
+=== 3) 真实调用 ===
+  回复 = '就绪'
+  => 端到端可用: True
+exit=0

nexforge_cli-0.3.0/docs/evidence/provider-family-check.log

@@ -0,0 +1,42 @@
+# 非默认 provider 验证(2026-09-11 专项)
+
+> 目的: 补上"未覆盖角落——非默认 provider"。用本机真实的 `~/.nexforge/models.toml`
+> 配置(kimi → 腾讯 MaaS 网关), 走 **OpenAI 兼容 provider** 的真实链路。
+> 密钥已遮蔽, 不入库。
+
+## 1. 真实对话(走 openai.py 的流式路径)
+
+```
+$ python -m nexforge --provider kimi --no-think -p '只回复四个字:你好世界'
+你好世界
+— tokens: 6873+63 · ~$0.0010
+rc=0
+```
+
+验证点:
+- `create_provider(config)` 对非默认 provider(kimi) 正确构造;
+- **OpenAI 兼容流式路径可用** —— 且这正是本轮刚改过的地方
+  (`with_options(max_retries=0)` 消除两层重试放大), 无回归;
+- 非 deepseek provider 的**计价路径**可用(打印出 ~$0.0010)。
+
+## 2. 动态模型列表(F6「刷新模型」走的就是它)
+
+```
+provider: kimi | base_url: https://tokenhub.tencentmaas.com/v1
+耗时 2.08s, 拉到 125 个模型
+   - hy4-preview / hy3 / glm-5.3-flash / glm-5.3
+   - deepseek/deepseek-flash / deepseek-v4-flash-vision-exp / deepseek-v4-pro-0813 ...
+```
+
+验证点: `fetch_models()` 对非默认 provider 可用; 网关确实暴露了
+`deepseek/deepseek-flash` 等名字(与本项目档位改名一致)。
+
+## 3. 未能验证的部分(如实记录)
+
+| 目标 | 原因 |
+|---|---|
+| anthropic 系 provider | models.toml 未配置, 且无可用 key |
+| qianwen 型 provider(type=qianwen) | 未配置 |
+| `local` provider | 需要本机 llama.cpp 服务在 `localhost:8080` 上运行, 当前未启动 |
+
+→ 这三条属于"环境不具备", 不计入"已验证"。

nexforge_cli-0.3.0/docs/evidence/release_0218_pypi.log

@@ -0,0 +1,9 @@
+=== PyPI 发布验证 ===
+PyPI 最新版本 : 0.2.18
+releases 含 0.2.18: True
+0.2.18 文件数 : 2
+  - nexforge_cli-0.2.18-py3-none-any.whl  (279373 bytes)
+  - nexforge_cli-0.2.18.tar.gz  (389819 bytes)
+上传时间     : 2026-09-10T15:59:20.940822Z
+页面         : https://pypi.org/pypi/nexforge-cli/0.2.18/
+exit=0

nexforge_cli-0.3.0/docs/evidence/simplify_tier_fulltest.log

@@ -0,0 +1,7 @@
+........................................................................ [ 16%]
+..............sss....................................................... [ 33%]
+........................................................................ [ 50%]
+........................................................................ [ 67%]
+........................................................................ [ 84%]
+....................................................................     [100%]
+425 passed, 3 skipped in 113.04s (0:01:53)