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

{nexforge_cli-0.2.17 → nexforge_cli-0.3.0}/.gitignore

@@ -1,30 +1,38 @@
-# Python
-__pycache__/
-*.py[cod]
-*.egg-info/
-build/
-dist/
-.eggs/
-
-# venv
-.venv/
-venv/
-env/
-
-# 测试 / 缓存
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-
-# 会话与本地配置(不入库)
-.nexforge/
-*.jsonl
-
-# 生成的图标位图
-assets/icons/*.png
-
-# IDE / OS
-.idea/
-.vscode/
-.DS_Store
-PyPI-*.txt
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# venv
+.venv/
+venv/
+env/
+
+# 测试 / 缓存
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# 会话与本地配置(不入库)
+.nexforge/
+*.jsonl
+
+# 生成的图标位图
+assets/icons/*.png
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# 凭据 / 恢复码(永不入库)
+PyPI-*.txt
+*recovery-code*
+*recovery_code*
+credentials*.env
+*.pem
+id_rsa*
+

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.2.17
+Version: 0.3.0
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge
@@ -51,7 +51,14 @@ Description-Content-Type: text/markdown
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.17** · PyPI: `pip install nexforge-cli`
+> 当前版本:**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.17 → nexforge_cli-0.3.0}/README.md

@@ -8,7 +8,14 @@
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.17** · PyPI: `pip install nexforge-cli`
+> 当前版本:**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.17 → 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-10-fails-loud/345/210/206/347/272/247.md

@@ -0,0 +1,41 @@
+# 决策：Fails Loud 分级（危险不得降级为警告）
+
+> 日期：2026-09-10 · 状态：生效
+
+## 背景
+
+项目的病根是"静默失败 / 危险降级"：
+
+- 插件目录消失 → **一声不吭**（用户遇到"语音播报凭空没了"，完全无从排查）
+- 配置写错字段名 → Pydantic 默认忽略 → **静默无效果**
+- `config.py` 有 4 处 `except Exception: pass` → **吞掉校验错误**，静默回退默认值
+
+更具讽刺意味的是：修复过程中，`hygiene` gate 自己把"敏感凭据躺在工作区"降级成**不拦人的提示**——
+gate 自己干了它要根治的事。
+
+## 决策
+
+1. **危险项默认失败**：敏感文件、残留目录、配置校验失败 → `[FAIL]` + 非 0 退出。
+2. **例外只能走显式 allowlist**（`.hygiene-allow`），且**每次放行必须在输出中可见**。
+3. **禁止"默认静默降级为警告"的路径**。
+4. **能力缺失时**：要么报错（含修复指引），要么显式声明"降级/跳过"并可见。
+5. **容错可以保留，但必须留痕**：如配置读失败 → 保留原文件 + 明确警告（而非覆盖）。
+
+## 理由
+
+- 危险与错误**必须可见**，且**不允许被降级为提示**——降级等于没检查。
+- **否决"敏感文件只警告"**：那正是要根治的"看见了风险却放行"。
+- **否决"用空 dict 覆盖损坏的配置"**：会丢失用户手写的注释与字段（数据丢失 > 启动失败）。
+- **否决"能力缺失静默跳过"**：用户无法区分"没配"与"坏了"。
+
+## 代价与边界
+
+- 失败必须**可定位**（文件:行、期望 vs 实际），否则等于没报。
+- 分级要克制：只有"用户期待的功能失败"才必须可见；清理/关闭类失败保持静默是合理的
+  （源码中仍有约 101 处 `except: pass`，经分类后判定多为合理防御）。
+- 单点探测异常不得中断整体（如能力列举、插件加载）。
+
+## 关联
+
+`scripts/gates/hygiene.py`、`config.py`（ConfigIssue）、`core/plugin.py`、`core/capability.py`、
+`plugin_speech_summary/`、`docs/session-invariant.md`

nexforge_cli-0.3.0/docs/decisions/2026-09-10-/344/274/232/350/257/235/344/270/215/345/217/230/351/207/217.md

@@ -0,0 +1,40 @@
+# 决策：会话不变量（model-visible ⟺ logged）
+
+> 日期：2026-09-10 · 状态：生效
+> 详规见 [`docs/session-invariant.md`](../session-invariant.md)
+
+## 背景
+
+"恢复/切换会话后行为异常""输入丢失/错位"是历史高频抱怨，但一直说不清根因。
+D8 审计用真实探针把它钉成了铁证：**构造含工具链的会话，`save → load` 后 5 条只剩 2 条**——
+工具调用、工具结果、思考内容、注入的上下文**全部丢失**。
+
+即：**模型看到的历史 ≠ 磁盘记录的历史**。
+
+## 决策
+
+1. 确立不变量：**凡是进入模型请求的内容，必须能由落盘数据重建**；
+   不能重建的，必须显式声明为"运行时派生"并给出补偿方式。**不允许无声地丢。**
+2. 内容分三类：**P1 原始事实**（必须可逐项重建）、**P2 外部状态快照**（必须留痕）、
+   **P3 运行时派生**（不落盘，但须显式标记 + 恢复时补偿）。
+   判据核心：**事后能否重算**。
+3. 落盘引入**结构化标记** `<!-- nf-msg <base64 JSON> -->` 作为**重建的唯一权威**；
+   人读 Markdown 保持不变（截断只影响展示，不影响重建）。
+4. 注入的上下文（记忆/地图/知识库/工具清单）另存 `<id>.ctx.md` 快照留痕。
+
+## 理由
+
+- **否决"增强人读 Markdown 的解析"**：内容里出现 `### ❯ 用户`、`## ` 等会破坏解析
+  （实测已踩：注入内容里的 `## 标题` 被误判为轮次边界）→ 标记法无此歧义。
+- **否决"抽独立 JSONL 存储"**：两套文件需同步，且旧会话迁移复杂；内嵌标记向后兼容（无标记即回退人读解析）。
+- **否决"把注入内容混进会话消息"**：它们源自会变的项目文件，混入会让会话文件成倍膨胀且语义不清。
+
+## 代价与边界
+
+- 文件体积约 2 倍（人读部分 + 标记）。
+- 标记是"机器真相"，人读部分是"展示"——**二者不一致时以标记为准**（规则写死）。
+- 派生项（如 `DEFAULT_SYSTEM`）**不进会话文件**，靠恢复时重放补偿；其定义处必须有显式标记说明。
+
+## 关联
+
+`store/session_store.py`、`core/session.py`、`ui/screens/chat.py`、`tests/test_session_invariant.py`

nexforge_cli-0.3.0/docs/decisions/2026-09-10-/344/276/235/350/265/226/344/270/200/350/207/264/346/200/247.md

@@ -0,0 +1,46 @@
+# 决策：依赖一致性（只用已声明的依赖）
+
+> 日期：2026-09-10 · 状态：生效
+
+## 背景
+
+健康体检时发现一个**真实可用性缺陷**：
+
+```
+tools/image_tools.py:  import requests   ← 3 处
+pyproject.toml 依赖:    httpx, openai, pydantic, ...
+                        ↑ 没有 requests
+```
+
+**本机恰好装了 `requests`**（所以测试全绿），但**全新用户 `pip install nexforge-cli` 后**，
+识图/生图会因 `ImportError` 被 `except` 吞掉 → **静默失败**。
+
+这既是一个可用性缺陷，也是"静默失败"病根的又一个实例。
+
+## 决策
+
+1. HTTP 客户端**统一为 httpx**（`pyproject` 已声明），全仓库不再使用 `requests`。
+2. 新增 `tests/test_deps.py` 三条防线：
+   - **未声明的第三方 import**（AST 扫描全仓库，与 pyproject 声明比对）
+   - `image_tools` 具体回归（不得用 requests）
+   - HTTP 客户端一致性（全仓库不得 `import requests`）
+3. 新增第三方依赖时，必须**同时**更新 `pyproject.toml`，否则测试会失败。
+
+## 理由
+
+- **本机环境 ≠ 用户环境**：依赖缺失类缺陷在本机不可见，只有"声明一致性检查"能提前发现。
+- **否决"把 requests 加进依赖"**：项目已有 httpx，再加一个等价 HTTP 客户端徒增体积与维护面；
+  统一为 httpx 还能让超时/重试策略一致。
+- **否决"只在代码里 try/except ImportError 静默降级"**：那会把缺陷藏得更深。
+
+## 代价与边界
+
+- httpx 与 requests 的 API 相近但不完全相同（本项目用到的 `post/get/.json()/.text/.status_code` 均一致）。
+- 检查基于**顶层 import 的模块名**；通过 `importlib.import_module("字符串")` 的动态导入不在覆盖范围。
+- 插件（`~/.nexforge/plugins/`）不受此检查约束——它们的额外依赖由插件的安装器负责（如
+  `plugin_gui_auto/requirements.txt`）。
+
+## 关联
+
+`tests/test_deps.py`、`src/nexforge/tools/image_tools.py`、`pyproject.toml`、
+`docs/evidence/health_report.md`

nexforge_cli-0.3.0/docs/decisions/2026-09-10-/345/233/236/346/224/276/350/214/203/345/233/264/351/207/215/345/256/232/344/271/211.md

@@ -0,0 +1,46 @@
+# 决策：D（回放测试）范围重定义
+
+> 日期：2026-09-10 · 状态：**生效**
+> 关联：D12 侦察（`docs/evidence/D12_audit.md`）、C 工程（`docs/session-invariant.md`）
+> 说明：本文同时作为 **F（决策留痕）的首条记录**，确立 `docs/decisions/` 作为决策留痕位置。
+
+---
+
+## 背景
+
+D 工程原定目标：**"把目标模式四轮审查暴露的 12 个 bug 固化成回归网"**。
+
+## 侦察结论（D12）
+
+从 `.nexforge/kb/` 四份审查记录重建出 **11 条** bug（总监所述 12 条，差 1 条来源无法确认，未凑数）：
+
+| 覆盖状态 | 条数 | 说明 |
+|---|---|---|
+| 早已有既有测试 | 7 | 远早于 C 工程 |
+| 由 C4 吸收 | 1 | 会话序列完整性（`test_session_invariant.py`）|
+| 代码已删 | 1 | 无需回归 |
+| **未覆盖** | 1 | #9 Esc 忙态判断 |
+| **部分覆盖** | 1 | #10 停止后迟到回复 |
+
+→ **原目标实际已完成**；再建回放网属于重复劳动（收敛原则点名的"反复磨同一模块、无新增价值"）。
+
+## 决策
+
+1. **原 D 目标记为"已由既有测试 + C 工程吸收"，不再单独建网。**
+2. **D 重定义为"最小端到端回放"**：仅一条链路（提目标 → 出方案 → 确认 → 分解 → 执行 → 验收 → 停止），
+   在**每一步之后**校验会话不变量。独立价值在于覆盖 **D9/D10 才引入的重建链**，而非重测单点。
+3. **刻意不建"框架"**：一条链路 + 复用既有夹具，避免为测试而测试。
+4. **补齐仅存真缺口**：#9 / #10（D13 任务 1 已完成，含对照用例）。
+
+## 理由
+
+- **收敛原则**：反复磨同一模块、无新增价值即停。
+- **侦察前置的收益**：避免约 2 天的重复劳动。这与 D8→D10 的教训同源——**先查证，再动工**。
+
+## 影响
+
+| 项 | 结果 |
+|---|---|
+| D 工程 | **完成（重定义后）** |
+| F 工程 | 本文为首条决策记录，确立 `docs/decisions/` 位置 |
+| 会话不变量 | 端到端回放成为其**跨组件验证入口**（`docs/session-invariant.md` §7）|

nexforge_cli-0.3.0/docs/decisions/2026-09-10-/345/256/241/350/256/241/344/273/245/350/260/203/347/224/250/351/223/276/344/270/272/345/207/206.md

@@ -0,0 +1,38 @@
+# 决策：审计以调用链为准（覆盖性结论须逐点附证）
+
+> 日期：2026-09-10 · 状态：生效
+
+## 背景
+
+C1 审计（D8）产出了"模型可见输入点 14 处、类型 A 共 7 处未落盘"的结论。后续实践中发现**其中两处是错的**：
+
+- 判"总监会话不落盘" → 实际 `chat.py:908` 早已每轮落盘（我只顺着内存对象查，没搜落盘调用链）
+- 判"插话完全不记录" → 实际已随总监会话落盘（`chat.py:897` `add_user`）
+
+同期还出现一次**方法错误**：用 `grep` 统计"裸 `except: pass`"得到 **0 处**（跨行匹配失效），
+改用 AST 精确扫描后是 **101 处**。
+
+## 决策
+
+1. **结论以调用链为准**：判断"某内容是否落盘/是否执行"必须搜到实际调用点（`file:line`），
+   **不得只看对象形态或凭记忆**。
+2. **凡下"共 N 处"这类覆盖性结论，每一点都须附证据**（调用链或工具输出）。
+3. **工具给出的结论，必须先验证工具本身是否可靠**（grep 会说谎，AST 更可信）。
+4. 清单**无法完整重建时如实声明缺项**，不得凑数（如"12 个 bug"实查为 11 条，差额来源无法确认）。
+
+## 理由
+
+- 覆盖性结论比单点结论**更容易出错**，却更常被当作事实引用——错一处会误导整条决策链
+  （D12 的"D 记已吸收"决定，正是建立在"7 条已覆盖"之上；若其中有假绿，决定就不成立）。
+- **否决"凭记忆/凭印象下结论"**：本项目的记忆已多次被证伪。
+
+## 代价与边界
+
+- 审计更慢（要搜调用链、要写脚本实证）——但与"带着错误结论改错方向"相比，这个成本极低。
+- 不要求每个细节都附证；**要求的是"覆盖性/否定性结论"必须有证据**。
+- 实证脚本应落盘（`docs/evidence/`），便于复核。
+
+## 关联
+
+`docs/evidence/D8_audit.md`（含被后续修正的结论）、`D10`/`D14` 报告、
+`scripts/gates/*`（gate 本身也遵守"失败必须可定位"）

nexforge_cli-0.3.0/docs/decisions/2026-09-10-/350/203/275/345/212/233/345/217/257/347/224/250/346/200/247/344/270/212/346/212/245.md

@@ -0,0 +1,43 @@
+# 决策：能力可用性上报（Capability 协议 + 注册制）
+
+> 日期：2026-09-10 · 状态：生效
+
+## 背景
+
+E 工程审计发现：**多实现/可选能力**（识图、语音、搜索）在缺失时表现不一——
+
+- 识图：**通道级静默**（单通道不可用不吭声，要等两路全废才报错）
+- 语音：**全程静默**（引擎不可用/缺 SDK/非 Windows 一律无声）
+- provider：**已达标**（注册制 + 缺什么报什么），可直接当模板
+
+用户无法回答"这个功能现在能不能用、为什么不能用"。
+
+## 决策
+
+1. 定义统一契约 `Capability`：`name` / `title` / `available()` / `unavailable_reason()`。
+2. **注册制**：`register_capability(impl)`，与 `provider.register_provider` 同构。
+3. 提供 `get_capability(name)`（未登记返回 `None`，调用方决定报错还是降级）、
+   `describe_capabilities()` / `format_capabilities()`。
+4. 新增 `/capabilities` 命令展示各能力状态与原因。
+5. **只登记真正多实现/可替换的能力**（search / vision / tts）；单实现无替换需求者
+   （kb / map / memory）**不登记**。
+
+## 理由
+
+- **三性**：可插拔（新增实现不改调用方分支）、可降级（先问 `available()` 再决定）、
+  可诊断（一条命令看清"哪个能力为何不可用"）。
+- **否决"给所有工具都套一层能力"**：单实现者套上去纯属过度抽象，徒增维护面。
+- **否决"能力探测发真实请求"**：探测必须**只读、无副作用**（不发网络、不写文件），否则启动变慢且会打扰服务。
+- **搜索引擎改为注册制**（原 if/elif 硬编码）：新增引擎只需 `register_engine()`；
+  各引擎自带"配置就绪检查"，被能力上报**复用**（单一真相，不重复实现判据）。
+
+## 代价与边界
+
+- 能力探测是**配置级**判断（"有没有路"），不等于"请求一定成功"——文档已注明。
+- 插件（如语音）登记能力时，需容忍旧版主程序无该模块（`except ImportError`）。
+- 单个能力探测抛异常**不得**中断整体列举（记为该能力不可用 + 异常说明）。
+
+## 关联
+
+`core/capability.py`、`tools/search.py`、`tools/image_tools.py`、
+`plugin_speech_summary/speech_summary.py`、`ui/slash_handler.py`、`tests/test_capability.py`

nexforge_cli-0.3.0/docs/decisions/2026-09-10-/350/264/250/351/207/217gate/344/275/223/347/263/273.md

@@ -0,0 +1,33 @@
+# 决策：质量 Gate 体系（机器强制取代人肉提醒）
+
+> 日期：2026-09-10 · 状态：生效
+
+## 背景
+
+此前所有质量约定都靠人记：改完记得跑 pytest、记得同步手册版本号、记得别提交凭据。
+**人一忘，问题就漏**——曾出现版本号漂移、手册与代码脱节、敏感文件躺在工作区无人察觉。
+对比 dsh（DeepSeek Harness）的做法：每条约定都配一个可执行 gate 并在 push 前强制运行。
+
+## 决策
+
+1. 建立聚合入口 `scripts/check.py`（`--fast` 秒级 / `--full` 含全量测试 / `--only` / `--list`）。
+2. 每个校验项一个模块（`scripts/gates/`），**自动发现，新增无需注册**。
+3. 提供 `scripts/install_hooks.py` 安装 **git 原生 pre-push 钩子**，失败即拦截；保留 `--no-verify` 逃生舱。
+
+## 理由
+
+- **把"我记得"变成"机器强制"**：纪律只有被执行才叫纪律。
+- **否决了"为 gate 化而重构既有测试"**：`tests/test_manual_consistency.py` 是 212 行已验证的 pytest 用例，
+  重构成独立函数风险大于收益 → 改为**子进程包装 + 解析结果**（单一真相，不复制断言逻辑）。
+- **否决引入 lefthook/ruff 等第三方**：项目约定"优先标准库"；git 原生 hook + sh 脚本已足够。
+- **否决"改错就静默通过"**：未发现任何 gate 本身也判失败（静默通过是最危险的失败模式）。
+
+## 代价与边界
+
+- pre-push 会拖慢推送 → fast gate 严格控制在秒级，全量测试只在 `--full` 或 CI。
+- hook 装在本机（`.git/hooks/` 不入库）→ 换机器需重跑安装脚本；README/手册已说明。
+- gate 只覆盖**已知**约定；新增约定需同步新增 gate。
+
+## 关联
+
+`scripts/check.py`、`scripts/gates/`、`scripts/install_hooks.py`、`manual/11-开发校验.md`

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 能力探测同源）