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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.3.0
+Version: 0.4.1
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge
@@ -51,14 +51,14 @@ Description-Content-Type: text/markdown
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.3.0** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.4.1** · 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` 次）。
+**v0.4.1 要点（重要修复）**：会话重建时，**内容里出现的 `<!-- nf-msg … -->` 不再被当成消息边界**。
+此前若工具结果 dump 过会话文件（或粘贴过会话内容），加载时那些标记会被解码成额外消息、
+插进工具块中间，导致**每轮请求 400、项目再也打不开**。
+修法：读侧标记识别改为**行首锚定**，写侧对内容里的标记前缀做转义；同时把工具序列修复
+从"只修尾部"升级为"修全序列"（中段违规也能纠正）。
+另含 0.4.0 推出的：本机 TTS 优先/回退、模型随 nf 常驻、`/voice full|brief`、配置残留值自动收敛。
 
 ---
 

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

@@ -8,14 +8,14 @@
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**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` 次）。
+> 当前版本:**v0.4.1** · PyPI: `pip install nexforge-cli`
+
+**v0.4.1 要点（重要修复）**：会话重建时，**内容里出现的 `<!-- nf-msg … -->` 不再被当成消息边界**。
+此前若工具结果 dump 过会话文件（或粘贴过会话内容），加载时那些标记会被解码成额外消息、
+插进工具块中间，导致**每轮请求 400、项目再也打不开**。
+修法：读侧标记识别改为**行首锚定**，写侧对内容里的标记前缀做转义；同时把工具序列修复
+从"只修尾部"升级为"修全序列"（中段违规也能纠正）。
+另含 0.4.0 推出的：本机 TTS 优先/回退、模型随 nf 常驻、`/voice full|brief`、配置残留值自动收敛。
 
 ---
 

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

@@ -14,7 +14,7 @@ flash = "deepseek-flash"                  # 原生多模态(文本+读图), 取
 default_tier = "flash"                     # 档位只剩 flash(pro/auto/vision 均已移除)
 thinking = true                            # 思考模式,默认开
 reasoning_effort = "high"                  # high | max
-max_output_tokens = 8192                   # 上限 384K
+max_output_tokens = 32768                  # 含思考 token; 别写 8192(思考会吃满 → 正文截断秒停)
 
 # 定价(每百万 token,USD)—— 已核实
 [models.pricing.flash]
@@ -28,3 +28,14 @@ show_thinking = true
 icons = "auto"                             # auto | image | glyph | ascii
 accent = "#6D5EF5"
 accent2 = "#22D3EE"
+
+# 语音播报(需安装内置示例插件 speech_summary)
+[tts]
+enabled = true                             # 总开关
+engine = "auto"                            # auto(本机 TTS 优先→微软回退) | cosyvoice | local | qianwen
+cosyvoice_url = "http://127.0.0.1:9880"    # 本机 CosyVoice 常驻服务(其 local_deploy/service)
+cosyvoice_voice = "default"                # 本机服务音色 id
+cosyvoice_timeout_s = 90                   # 冷启动约 20s, 留足余量
+cosyvoice_resident = true                  # nf 在跑就让模型常驻显存; nf 全退出后由服务立即卸载
+max_chars = 0                              # 播报文本上限(0=不限; 配合下面的 mode)
+mode = "full"                              # 播报范围: full=全量播报最终报告(默认) | brief=只播第一段(/voice 切换)

nexforge_cli-0.4.1/docs/decisions/2026-09-11-/351/205/215/347/275/256/346/256/213/347/225/231/345/200/274/346/262/273/347/220/206.md

@@ -0,0 +1,90 @@
+# 决策：配置残留值治理（自动收敛 + 必须可见）
+
+> 日期：2026-09-11 · 状态：生效
+
+## 背景
+
+这个软件会**把自己的状态写回配置**：`save_config()` 会把 UI 模式、当前 provider、
+档位、已验证名单等写进 `config.toml`/项目级配置。于是当**代码侧删掉或改名一个取值**
+（档位、provider、字段）后，用户机器上那份由旧版本写下的值就成了**残留值**——
+它在下一次启动时会被读到，然后：
+
+- 要么**让启动直接失败**（用户被挡在门外，只能手改 TOML），
+- 要么被**静默忽略**（配置写了却没效果，是"最难查"的那类困惑），
+- 要么**让软件对自己的文件报假警**（检查器不认识自己写的字段）。
+
+2026-09-11 一天内实际踩到三类，都不是理论推演：
+
+| # | 残留值 | 现场后果 | 证据 |
+|---|---|---|---|
+| 1 | `models.default_tier = "pro"`（旧版 `/model pro` 持久化） | **启动中止**（exit 2）：`Input should be 'flash'` | 第三轮复核；实验 exit 2 → 修复后 exit 0 |
+| 2 | `provider.default = "deepseek-v41"`（该 provider 已从 models.toml 移除） | TUI `初始化失败`，并**连带报出误导性的"缺少 API Key"** | 用户截图 + 本轮复盘 |
+| 3 | `[provider] verified = [...]`（nf 自己写的字段） | 未知字段检查**误报**："未知字段 'verified'(已忽略, 请检查拼写)" | 用户启动告警 |
+
+## 决策
+
+**残留值一律"自动收敛 + 可见告警"，并按下述判据分级；静默迁移不再允许。**
+
+### 判据（新增一条收敛规则前先回答这两个问题）
+
+1. **这个值的意图是否唯一可知？**
+   - 唯一可知（已移除的档位只剩 `flash`；不存在的 provider → 回退内置 `deepseek`）
+     → **自动收敛**为唯一合理值，并给 `warning`（**不阻断启动**）。
+   - 不可知（拼写错误 `flsh`、类型错误、TOML 损坏）
+     → **仍然 `error`**，照旧中止启动。**不许猜**。
+2. **用户看到告警后能否知道去哪儿改？**
+   告警的 `source` 必须是**真正写了该值的文件路径**（用户级 vs 项目级要分清），
+   文案要给出下一步动作（改哪个键 / 用哪条命令）。
+
+### 三类处置（现有实现，作为范式）
+
+| 类别 | 例子 | 处置 | 实现位置 |
+|---|---|---|---|
+| 已知移除的**取值** | `default_tier = "pro"/"auto"/"vision"` | 收敛为 `flash` + warning | `config.py:_migrate_removed_tier()`（`REMOVED_TIERS`）|
+| **悬空引用** | `provider.default` 不在 provider 列表里 | 收敛为内置 `deepseek` + warning（指名文件）| `config.py:load_config()` 收尾校验 |
+| **未知字段/段** | `defualt`、`[router]` | warning + 忽略（**保留**：可能只是拼错，也可能是新版本字段）| `config.py:_check_unknown_fields()` |
+| 不可知错误 | TOML 损坏、枚举/类型不合法 | `error` + 中止（exit 2）| `load_config()` / `cli.py:has_config_errors()` |
+
+### 纪律
+
+- **禁止静默迁移**。历史上的 `ui.mode: review → supervised` 是无告警迁移，属遗留；
+  新增迁移一律带 `ConfigIssue("warning", ...)`。（判据：用户必须能知道"我写的值被改了"。）
+- **软件自己写的字段，必须在 schema 里声明**。写入方（`save_config`）与
+  校验器（`_check_unknown_fields`）之间的契约靠 `model_fields` 维系；
+  漏声明就会"自己对自己报假警"（上表 #3）。
+- **错误文案不许误导**。例：agent 建不起来时，有 Key 要说"provider 初始化失败"，
+  只有确实没 Key 才说"缺少 API Key"（`ChatScreen._not_initialized_message()`）。
+- **每条收敛规则都要成对测试**：正例（收敛 + 告警存在 + 不阻断）与
+  反例（真错误仍然报错 / 合法值不被改动）。
+
+## 理由
+
+- **不让用户被挡在门外**：残留值是"旧版本写下的合法值"，用户无从预知；让它中止启动
+  等于把升级成本转嫁给用户，而语义其实唯一（只能回退内置/唯一档位）。
+- **但也不能悄悄改**：静默收敛会让用户"以为配置生效了"，与
+  `ADR-2026-09-10-fails-loud分级` 冲突——那里只允许**清理/关闭类**失败静默，
+  而配置变更属于"用户期待的功能"。
+- **否决"只报错、不收敛"**：三种残留都是**旧版本自动写入**的，惩罚用户不合理。
+- **否决"只收敛、不告警"**：用户无法察觉配置被改，也无法修正源头。
+- **否决"把 unknown field 也自动收敛"**：拼写错误与"未来字段"无法区分，猜错更糟。
+
+## 代价与边界
+
+- 收敛会让"用户显式写的无效值"被覆盖（如 `default_tier = "flsh"` 仍报错，
+  但 `"pro"` 被改成 `"flash"`）。判据是**语义唯一**：仅对"代码侧已知移除/改名"的值生效，
+  清单必须显式维护（`REMOVED_TIERS`），不能靠模糊匹配。
+- 悬空 `provider.default` 收敛到内置 `deepseek` 后，用户若本意是用某个自定义 provider，
+  需自己改回（告警已指名文件与键名）。
+- 项目级配置与用户级配置都可能持有残留值：**分别检查、分别归属**（告警要指出是哪一个）。
+- 每次删除/改名一个"会被写回配置"的取值时，**必须同日补一条收敛规则 + 测试**，
+  否则下一位用户就会以"启动失败"或"假警报"的形式替你发现它。
+
+## 相关
+
+- `src/nexforge/config.py`：`REMOVED_TIERS`/`_migrate_removed_tier()`、`load_config()` 收尾校验、
+  `_check_unknown_fields()`、`save_config()`（写入方）、`ProviderConfig.verified`（自己写的字段）
+- `src/nexforge/ui/screens/chat.py`：`_not_initialized_message()`（文案不许误导）
+- `src/nexforge/provider/__init__.py`：`ProviderError` 的修复指引
+- 测试：`tests/test_config.py`（档位迁移/悬空 provider/verified 已知字段/反例）
+- ADR-2026-09-10-fails-loud分级（可见性分级的上位规则）
+- ADR-2026-09-11-档位简化为单档flash、ADR-2026-09-11-deepseek档位简化（残留值的来源）

nexforge_cli-0.4.1/docs/decisions/2026-09-12-/345/206/205/345/256/271/351/207/214/347/232/204/346/240/207/350/256/260/344/270/215/345/276/227/345/275/223/346/210/220/346/266/210/346/201/257/350/276/271/347/225/214.md

@@ -0,0 +1,65 @@
+# 决策：内容里的 `<!-- nf-msg … -->` 不得被当成消息边界
+
+> 日期：2026-09-12 · 状态：生效
+
+## 背景
+
+会话重建的权威是每行消息末尾的结构化标记 `<!-- nf-msg <base64> -->`（`docs/session-invariant.md` §4.1）。
+但解析用的是**全文 `findall`**，于是"内容里出现的标记"与"真正的消息边界"无法区分。
+
+触发链（实测，NexForgeCLI 自己的 `session-122357`）：
+
+1. 工具结果 dump 了某个会话 `.md` 文件（`read_file .nexforge/sessions/session-…md`），
+   被 dump 的标记行作为**内容**落进新会话文件；
+2. 下次加载时，这些"内容里的标记"被解码成**额外消息**，且插在
+   `assistant(tool_calls)` 与它的 `tool` 响应之间（实测多出 10 份重复助手消息）；
+3. 请求违反 OpenAI/DeepSeek 规则——"带 tool_calls 的 assistant 后必须紧跟覆盖全部
+   tool_call_id 的 tool 消息"——返回 400
+   `insufficient tool messages following tool_calls message`；
+4. `_repair_incomplete_tail` 只修**尾部**，看不见中段违规 → 每轮请求都 400。
+   用户侧现象：**"项目再也打不开"**（打开后说什么都报错）。
+
+## 决策
+
+三层一起上（缺任一层都有残留口子）：
+
+1. **写侧转义**（`_escape_marker_prefix`）：人读部分里出现的 `<!-- nf-msg` 一律插入零宽空格
+   `\u200b` 转义。标记内的 base64 负载不受影响 → 重建权威无损
+   （§4.1 本就允许人读部分变形/截断）。
+2. **读侧锚定**（`_MARKER_RE` 加 `re.M` 与行首 `^`）：只有**独立成行**的标记才是边界。
+   真标记必然在行首（所有人类可读块都以换行结尾），全仓库历史会话文件实测零反例。
+3. **全序列修复**（`_repair_incomplete_tail` → `_repair_tool_sequence`，旧名保留为别名）：
+   修复**整条序列**而不是尾部 —— 夹层消息**保序后移**、缺响应的 tool_call 补"已取消"、
+   重复响应与无主孤儿 tool 删除。修复后的序列对 API **恒合法**。
+   配套：`agent.py` 的防死循环提示改为在整块工具响应**之后**追加，不再插进 tool 之间。
+
+## 理由
+
+- **只修尾部不够**：违规可能在中段（本次实测），尾部修复完全看不到。
+- **只加读侧锚定不够**：不带行号前缀的内容（用户把会话文件整段粘进对话、shell 直接
+  `type` 出文件）仍能伪造出行首标记。
+- **只加写侧转义不够**：修复前落盘的历史文件里已有的镶嵌标记仍会被解码 → 需要读侧 +
+  全序列修复兜底（已用真机 `session-122357` 验证：修复后非法点 0）。
+- **否决"按人读格式严格比对，再判定某个标记是否可信"**：人读格式一旦演进，旧文件会被
+  整段判成伪标记 → **静默丢历史**，代价远高于收益（不变量只禁止一件事：无声地丢失）。
+
+## 代价与边界
+
+- 人读部分与原始内容有肉眼不可见的差异（零宽空格）；工具结果原文仍由标记负载精确重建。
+- 夹层消息只"后移"不删除：已积累的重复消息仍占上下文（必要时人工清理）。
+- **复用注意**：`_repair_tool_sequence` 为兼容旧行为会弹出**尾部未配对 user**；因此它之后必须
+  紧跟 `add_user`（app 的 `run_turn` 顺序）。若单独调用后直接发请求，列表会以 assistant 结尾，
+  thinking 模式下会触发另一条 400 `reasoning_content ... must be passed back`
+  （见 `docs/evidence/session-marker-boundary_report.md` §5 坑 1）。
+- **已知未覆盖（本次不改，另行决策）**：`save_session` 不清理"陈旧分段"（列表变短时，
+  旧的高编号分段文件仍会被 `load_session` 追加 → 陈旧内容混入 + 可能非法序列）。
+  机制已在证据脚本里复现（3 条被加载成 130 条）；全序列修复能兜住 400，但内容冗余仍在。
+
+## 关联
+
+- 模块：`store/session_store.py`（`_MARKER_RE` / `_escape_marker_prefix` / `_format_message`）、
+  `core/session.py`（`_repair_tool_sequence`）、`core/agent.py`（提示位置）
+- 文档：`docs/session-invariant.md` §4.1
+- 测试：`tests/test_session_store.py`（往返）、`tests/test_session_repair.py`（全序列）、
+  `tests/test_session_invariant.py`
+- 证据：`docs/evidence/session-marker-boundary_report.md` / `.log`

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

@@ -65,3 +65,5 @@
 | 2026-09-11 | [档位简化为单档 flash](2026-09-11-档位简化为单档flash.md) | 生效 · 破坏性 |
 | 2026-09-11 | [终端状态兜底恢复 + 退出看门狗](2026-09-11-终端状态兜底恢复.md) | 生效 |
 | 2026-09-11 | [重试只归一层](2026-09-11-重试归一层.md) | 生效 |
+| 2026-09-11 | [配置残留值治理（自动收敛 + 必须可见）](2026-09-11-配置残留值治理.md) | 生效 |
+| 2026-09-12 | [内容里的标记不得被当成消息边界](2026-09-12-内容里的标记不得当成消息边界.md) | 生效 |

nexforge_cli-0.4.1/docs/evidence/release-0.3.0.log

@@ -0,0 +1,65 @@
+# 发布 0.3.0 记录(2026-09-11)
+
+## 时间线
+
+| 步骤 | 结果 |
+|---|---|
+| 版本升级 | 0.2.18 → **0.3.0**(5 处同步: pyproject / `__version__` / README / 手册索引 / 手册第 1 章) |
+| 全量测试 | **518 passed, 3 skipped** |
+| 质量 gate | **4/4 PASS**(含 version-sync) |
+| 构建 | `python -m build` → `nexforge_cli-0.3.0-py3-none-any.whl`(290 KB) + `.tar.gz`(435 KB) |
+| 产物自检 | `twine check` → **两个包 PASSED** |
+| 本地预装 | 干净目录 `pip install --no-deps` → rc=0; `__version__ = 0.3.0`; 新模块可导入 |
+| 上传 | `twine upload`(带 `PYTHONIOENCODING=utf-8`)→ 成功 |
+| PyPI URL | https://pypi.org/project/nexforge-cli/0.3.0/ |
+
+## 上传后验证(记录一个反复出现的坑)
+
+twine 报成功后, **立刻**查 PyPI API 仍是 `最新版本: 0.2.18`、`0.3.0 文件数: 0`,
+`pip install nexforge-cli==0.3.0` 也报 `No matching distribution found` —— 这是
+**PyPI 的 CDN 传播延迟**(0.2.18 发布时遇到过同样现象), 不是上传失败。
+
+约 40 秒后复验:
+
+```
+0.3.0 文件数 = 2
+pip install(从 PyPI) rc = 0
+导入路径: pypi_inst_030        ← 确认真的是从 PyPI 安装的目录, 不是本机 editable 包
+__version__ = 0.3.0
+terminal_guard: True
+vision_channel ok
+```
+
+**教训(第二次踩)**: 上传后的验证必须
+1) 看**顶层** `/pypi/<name>/json` 的 `releases`(单版本 URL 会 404);
+2) **等传播**(几十秒到几分钟), 期间不要判定失败;
+3) 安装验证要打印**导入路径**, 否则可能误用本机已装的同名包而得出假结论
+   (本次第一次检查就犯了这个错, 已修正)。
+
+## 发布后深度核验(独立 venv + 逐文件比对)
+
+```
+独立 venv 从 PyPI 全量安装(含依赖) rc=0
+nf --version  → NexForgeCLI 0.3.0                    ← 真实控制台脚本可用(不只是 import)
+nf --help     → "-m, --model MODEL 模型档位(flash)…"
+                "--resume 兼容参数:启动时已自动恢复最近一次会话…"
+源码逐文件比对 → 共同文件 108 个, 内容不一致 0 个, 无缺失/无多余
+                ⇒ 发出去的包 == 仓库 HEAD(审过的就是发出的)
+升级模拟       → 旧配置 default_tier="pro": 退出码 0 + 可见迁移告警
+                "[models] 档位 'pro' 已移除(现只有 flash), 已自动改用 flash"
+```
+
+## 发布卫生: 补打 v0.3.0 标签
+
+仓库原有轻量标签 `v0.2.12` / `v0.2.13`，之后 0.2.14–0.2.18 与本次 0.3.0 **均未打标签**
+（约定中途断了）。本次补打 **v0.3.0 → 56d314e**（版本提交；构建用的树与它一致，
+之后只加过 docs/evidence，不入包）。历史版本不追溯补打，避免猜测各自对应的提交。
+
+## 本版内容(摘要)
+- **破坏性**: 档位简化为单档 `flash`(`/model pro|auto|vision` 移除; 旧配置值自动迁移并告警)
+- 模型名更新为官方 `deepseek-flash`(原生多模态, 文本+读图一档)
+- 终端状态兜底恢复 + 退出看门狗(SIGBREAK 接管 / 超时强制退出)
+- 模型侧边栏绿点恒为一个; 侧栏列表左对齐修复
+- 会话落盘原子写; 历史归档不再静默丢批次; 归档/保存失败均可见
+- 识图通道判定修复(默认档位贴图真的发图, 能力上报与实际同源)
+- 重试归一层(429 时由最多 12 次请求降为 `1 + max_retries`)

nexforge_cli-0.4.1/docs/evidence/release-0.4.0.log

@@ -0,0 +1,46 @@
+# 发布 0.4.0 记录(2026-09-11)
+
+## 内容(相对 0.3.0)
+
+0.3.0 之后共 **10 个提交 / 23 文件(+1827 / −125)**：
+
+- **feat** 语音播报接入**本机 TTS**(如本地部署的 CosyVoice)：本机优先、失败自动回退
+  微软 Windows 语音(`122481f`)；
+- **feat** 用 nf 时让本机模型**常驻显存**、nf 全部退出即释放 —— 租约机制 + PID 存活/
+  心跳超时自愈，被强杀也能归还显存(`c4f033a`、`67b33bc`)；
+- **feat** 新增 `/voice full|brief` 切换播报范围，默认**全量播报**最终报告
+  (`max_chars` 默认 100 → 0)(`0d62b3d`)；
+- **fix** 配置残留值治理：失效 provider 自动回退内置 deepseek(不再让 TUI 初始化失败、
+  不再连带报误导性的"缺少 API Key")；`[provider] verified` 不再被当成未知字段误报
+  (`3f95873`、`660e27e`)；
+- **test** 新增两条门禁：`eof-newline`(防"黏行"损坏)、`example-config`
+  (示例配置必须等于代码默认值 —— 它当场抓出两处漂移，其中 `max_output_tokens=8192`
+  会误导用户复现"正文截断")(`84a7f5f`、`efad92c`)；
+- **docs** ADR《配置残留值治理》+ 插件/服务文档修正(`4001050`、`d99e3e5`)。
+
+## 发布流程与结果
+
+| 步骤 | 结果 |
+|---|---|
+| 版本 | 0.3.0 → **0.4.0**(5 处同步: pyproject / `__version__` / README / 手册索引 / 手册第 1 章) |
+| 全量测试 | **567 passed, 3 skipped** |
+| 质量 gate | **6/6 PASS**(含 version-sync、example-config、eof-newline) |
+| 构建 | whl 292 KB + tar.gz 461 KB |
+| 产物自检 | `twine check` → **两个包 PASSED** |
+| 上传前本地安装 | rc=0；新装环境版本 0.4.0、`tts.mode/resident/max_chars` 齐全、`/voice` 在包内 |
+| 上传 | `twine upload`(带 `PYTHONIOENCODING=utf-8`)→ 成功 |
+| PyPI | https://pypi.org/project/nexforge-cli/0.4.0/ |
+
+## 又一次踩到"传播延迟"，且这次是**两个不同的缓存**
+
+1. 上传后立刻查**顶层 JSON API** → 先显示 `最新版本: 0.3.0`，**约 40 秒后**变为 0.4.0、
+   文件数 2 ✔；
+2. 但 **pip 用的 `/simple` 索引是另一个缓存**：JSON 已经更新时，`pip install
+   nexforge-cli==0.4.0` 仍报 `No matching distribution found (available: … 0.3.0)`，
+   **约 20 秒后**才可见。
+
+**差点产生的假绿**：pip 失败后，我的校验脚本 `import nexforge` 回退到了**本地仓库包**，
+却照样打印出 `0.4.0`（因为仓库里就是 0.4.0）—— 是"**打印导入路径**"这一步把它揭穿的
+(显示 `src` 而不是安装目录)。**教训**：发布后验证必须
+(1) 分别等待 JSON 与 `/simple` 两个缓存的传播，
+(2) 打印导入路径确认来源。

nexforge_cli-0.4.1/docs/evidence/session-marker-boundary.log

@@ -0,0 +1,101 @@
+# 2026-09-12 会话标记边界修复 — 原始证据(诊断脚本输出, 未编辑)
+
+复现命令(诊断脚本为临时脚本, 逻辑就是"用项目自己的 load_session 加载 + 按 OpenAI/DeepSeek
+规则校验工具序列"):
+
+    python verify_real.py D:\DevelopProject\NexForge\NexForgeCLI session-122357
+    python before_after.py          # 旧行为 vs 修复后
+    python stale_seg_sim.py         # 遗留风险(陈旧分段)模拟
+
+---
+
+## [1] 内容里的标记 → 幽灵消息: 旧行为 vs 修复后(`before_after.py`)
+
+```
+【修复后】消息数 = 3  期望 = 3
+【修复后】序列: [('user', None), ('assistant', None), ('tool', 'c1')]
+
+【旧行为】消息数 = 4
+【旧行为】序列: [('user', None), ('assistant', None), ('assistant', None), ('tool', 'c1')]
+
+修复后 API 合法: True
+旧行为 API 合法: False  ← False 即 DeepSeek 400
+结论: 旧行为凭空多出消息且序列非法(400); 修复后逐项一致。
+```
+
+要点: 工具结果内容里嵌一行真标记形状, 旧行为会把它解码成**一条幽灵 assistant 消息**,
+且插在 `assistant(tool_calls)` 与 `tool` 响应之间 → 序列非法(400)。
+
+## [2] 真机会话 `session-122357`: 加载 → 全序列修复 → 校验(`verify_real.py`)
+
+```
+=== D:\DevelopProject\NexForge\NexForgeCLI :: session-122357 ===
+  加载消息数: 3785  角色分布: {'system': 1, 'user': 44, 'assistant': 2673, 'tool': 1067}
+    idx=1724 第2个 tool_call 后不是其响应 → 实际下一条 role=assistant
+    idx=1724 第3个 tool_call 后不是其响应 → 实际下一条 role=assistant
+    idx=1729 孤儿 tool(无前置 assistant) → 实际下一条 role=call_01_ntfoM5j9cu4Ee5Yx0Tyq5025
+    idx=1730 孤儿 tool(无前置 assistant) → 实际下一条 role=call_02_UWDVr1XVkUCnkmPX0HcO6758
+  修复后消息数: 3785 (净变化 +0)  非法点: 0
+  非 tool 消息丢失数: 0 (必须为 0)
+```
+
+说明:
+
+- 违规点在 **idx=1724(全长 3785 的中段)** —— 这正是旧 `_repair_incomplete_tail`(只修尾部)
+  兜不住、导致"每轮都 400"的原因;
+- 修复后非法点 0, 且**非 tool 消息一条不丢**(夹层消息只后移, 不删除);
+- 修复后加载条数比修复前少 1(3786 → 3785): 少的正是"内容里的标记"伪造出的幽灵消息,
+  被读侧行首锚定挡住。
+
+## [3] 遗留风险模拟: 陈旧分段残留(`stale_seg_sim.py`, 本次未修, 已记录)
+
+```
+第一次保存(60 轮)分段文件: 3
+第二次保存(3 条)后分段文件: 3 (旧文件仍在 → 陈旧残留)
+
+加载结果: 130 条(期望 3)
+加载后非法点: 0
+全序列修复后消息数: 130  非法点: 0
+→ 修复兜住了 400, 但陈旧内容仍混入上下文(冗余/重复)
+```
+
+说明: `save_session` 写完新分段后不清理"超出新段数的旧分段文件", 而 `load_session`
+按序号**连续**读 → 列表变短(上下文压缩等)后, 旧分段会被追加回来。
+本次修复能让请求保持合法(不再永久 400), 但内容冗余仍在; 建议后续用"文件头声明分段数"
+收口(见 ADR `docs/decisions/2026-09-12-内容里的标记不得当成消息边界.md` 的"代价与边界")。
+
+## [4] 全量测试与本机巡检
+
+- 全量 `pytest -q`: 见 `session-marker-boundary_fulltest.log`(**577 passed / 3 skipped**);
+  注: 直接把 pytest 输出重定向到文件时, `sys.__stderr__` 走 GBK 会把中文断言串编坏,
+  `test_session_save_safety` / `test_terminal_guard` 两条会假 FAIL —— 加
+  `PYTHONIOENCODING=utf-8` 即全绿(与本次改动无关, 供后来者参考);
+- 本机所有会话巡检(只读): 仅 `NexForgeCLI/.nexforge/sessions/session-122357.md` 命中非法序列,
+  修复后 0; `CosyVoice` 两个会话本就合法; 未发现真实存在的陈旧分段文件。
+
+## [5] 真机 API 验证(唯一联网步骤; 目标是用户自己配置的 deepseek)
+
+顺序复刻 app 的 `run_turn`: **修复 → add_user → 发请求**。原始输出见
+`session-marker-boundary_live.log`, 摘要:
+
+```
+--- 合成最小复现 ---
+[400 ] 修复前(只修尾部 → 中段违规保留): 400 "must be followed by tool messages responding ..."
+[OK  ] 修复后(全序列修复):               回复='我没法执行 git 命令——我目前只有 read_file ...'
+
+--- 用户真机会话切片(idx 1715..1735, 含 10 份重复消息) ---
+[400 ] 修复前: 400 "must be followed by tool messages responding ..."(与截图同款)
+[OK  ] 修复后: 回复='先做两件事并举：把截图切块放大精读…'
+
+--- 用户会话全部 3785 条端到端 ---
+[OK  ] 加载 3785 条; content 字符 896103 → 回复='好'
+       usage: prompt=980288 completion=2
+```
+
+附带发现(见报告 §5): 若自行构造的请求**以 assistant 结尾**(脱离 `run_turn` 的
+"修复 → add_user"顺序), thinking 模式会报另一条 400
+`The reasoning_content in the thinking mode must be passed back to the API.`
+app 的真实路径永远以 user 结尾, 不受影响; 排查时先看请求最后一条的 role。
+
+体量标定: 该会话 ≈ **980k prompt tokens**(按真机 usage 实测) —— 已逼近模型窗口,
+建议该项目后续工作改开新会话(详见报告 §6)。

nexforge_cli-0.4.1/docs/evidence/session-marker-boundary_fulltest.log

@@ -0,0 +1,4 @@
+..........................................................................................................................sss........................................................................................................... [ 40%]
+........................................................................................................................................................................................................................................ [ 80%]
+....................................................................................................................                                                                                                                     [100%]
+577 passed, 3 skipped in 166.00s (0:02:46)

nexforge_cli-0.4.1/docs/evidence/session-marker-boundary_live.log

@@ -0,0 +1,84 @@
+# 2026-09-12 真机 API 验证 — 原始输出
+# 说明: 唯一联网的部分。调用的是用户自己配置的 DeepSeek(极少量 token)。
+# 顺序复刻 app: run_turn = 修复(全序列) → add_user → 发请求。
+
+
+======================================================================
+[1] 合成最小复现 + 用户真机切片(修复前 400 / 修复后 OK)
+======================================================================
+
+--- 合成最小复现 (合成, 6 条) ---
+[400 ] 合成最小复现: 修复前(只修尾部 → 中段违规保留)
+       尾部形态=[('system', ''), ('user', ''), ('assistant', ''), ('tool', 'call_a'), ('assistant', ''), ('tool', 'call_b'), ('user', '')]
+       DeepSeek 请求失败:Error code: 400 - {'error': {'message': "An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. (insuff
+[OK  ] 合成最小复现: 修复后(全序列修复)
+       尾部形态=[('system', ''), ('user', ''), ('assistant', ''), ('tool', 'call_a'), ('tool', 'call_b'), ('assistant', ''), ('user', '')]
+       回复='我没法执行 git 命令——我目前只有 `read_file'
+
+--- 用户真机切片 (真机会话 idx 1715..1735, 20 条) ---
+[400 ] 用户真机切片: 修复前(只修尾部 → 中段违规保留)
+       尾部形态=[('assistant', ''), ('assistant', ''), ('assistant', ''), ('assistant', ''), ('tool', 'call_00_KUQ0QE4uHYFZR9vECKHs8585'), ('tool', 'call_01_vPwNaGPVtYL6pjDSz1Jp1970'), ('assistant', ''), ('user', '')]
+       DeepSeek 请求失败:Error code: 400 - {'error': {'message': "An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. (insuff
+[OK  ] 用户真机切片: 修复后(全序列修复)
+       尾部形态=[('assistant', ''), ('assistant', ''), ('tool', 'call_00_KUQ0QE4uHYFZR9vECKHs8585'), ('tool', 'call_01_vPwNaGPVtYL6pjDSz1Jp1970'), ('assistant', ''), ('tool', 'call_00_lGLB89578wxkRZEHAc7h3860'), ('tool', 'call_01_PSu2XcMwXvYpfFx5HyeH0236'), ('user', '')]
+       回复='先做两件事并举：把截图切块放大精读（上次裁剪被中断了），同时'
+
+
+
+======================================================================
+[2] 用户会话**全部 3785 条**端到端(修复后 → OK, 980k prompt tokens)
+======================================================================
+加载 3785 条; content 字符 896103
+OK  回复='好'
+usage: prompt=980288 completion=2 cache_hit=0 cache_miss=980288
+
+
+
+======================================================================
+[3] token 折算标定(用于估算会话体量)
+======================================================================
+样本: 10 条, content 字符 2677, 实测 prompt_tokens 1809
+折算比 ≈ 1.48 字符/token(含消息包装开销, 偏保守)
+全会话 content 字符 896103 → 估算 ≈ 605,547 tokens
+
+
+
+======================================================================
+[4] 排查过程中的一个反例(见报告 §5 解释: 请求以 assistant 结尾会触发另一条 400)
+======================================================================
+A(直接构造) 哈希: 032cb06ac43097bb [('system', '', False, False), ('user', '', False, False), ('assistant', '', True, True), ('tool', 'call_a', False, False), ('tool', 'call_b', False, False), ('assistant', '', False, False), ('user', '', False, False)]
+B(违规→修复) 哈希: 155c87cb5fdfbe12 [('system', '', False, False), ('user', '', False, False), ('assistant', '', True, True), ('tool', 'call_a', False, False), ('tool', 'call_b', False, False), ('assistant', '', False, False)]
+两者规范形态一致: False
+  A#1 OK: '我没法直接运行 git 命令'
+  A#2 OK: '我没法真正“检查 git 提'
+  A#3 OK: '好'
+  B#1 400(reasoning): DeepSeek 请求失败:Error code: 400 - {'error': {'message': 'The `reasoning_content` in the thinking mode 
+  B#2 400(reasoning): DeepSeek 请求失败:Error code: 400 - {'error': {'message': 'The `reasoning_content` in the thinking mode 
+  B#3 400(reasoning): DeepSeek 请求失败:Error code: 400 - {'error': {'message': 'The `reasoning_content` in the thinking mode 
+
+
+
+======================================================================
+[5] 同一请求连发 6 次(reasoning_content 报错与请求形态相关, 非随机)
+======================================================================
+  第1次 OK: ''
+  第2次 OK: '我手上只有读文件的能力，'
+  第3次 OK: '好'
+  第4次 OK: '好'
+  第5次 OK: ''
+  第6次 OK: '先说清楚我这边的情况，免'
+
+统计: OK=6  reasoning_content 400=0  其它 400=0
+
+
+======================================================================
+[6] 上下文窗口探针(免费/必然超长 → 用于确认窗口大小)
+======================================================================
+探针: 竟然通过(窗口 > 1.2M tokens)
+
+DEFAULT_SYSTEM 字符数: 2041
+工具 schema 字符数: 20993 (47 个工具)
+合计附加字符数 ≈ 23034 → 约 7,678 tokens
+会话本体(实测) = 980,288 tokens; max_output_tokens = 32768
+预估请求总量 ≈ 1,020,734 tokens
+

nexforge_cli-0.4.1/docs/evidence/session-marker-boundary_report.md

@@ -0,0 +1,77 @@
+# 会话"再也打不开"根因报告 — 内容里的标记被当成消息边界(2026-09-12)
+
+> 现象: nf 启动后说什么都报 `DeepSeek 400 ... insufficient tool messages following tool_calls message`(截图同款),
+> 即用户所说"项目打不开了"。本文记录完整证据链、修复与验证;**结论均有原始输出支撑**(见文末索引)。
+
+## 1. 结论(一句话)
+
+工具结果 dump 会话 `.md` 文件时, 被 dump 的 `<!-- nf-msg … -->` 标记行作为**内容**落进新会话文件;
+解析时被全文 `findall` 解码成**额外消息**, 插进 `assistant(tool_calls)` 与它的 `tool` 响应之间 →
+请求违反 API 的"tool 响应必须紧跟且覆盖全部 tool_call_id"→ 每轮 400。
+而旧的修复函数 `_repair_incomplete_tail` **只修尾部**, 看不到中段违规 → 永久失败。
+
+## 2. 定位过程(证据链)
+
+| 步骤 | 做法 | 结果 |
+|---|---|---|
+| 1 | 解出截图报错原文 | `An assistant message with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. (insufficient tool messages following tool_calls message)` |
+| 2 | 扫描本机各项目会话, 按 API 规则校验工具序列(只读) | 只有 `NexForgeCLI/.nexforge/sessions/session-122357.md` 命中: **中段 idx=1724 违规 4 例**; CosyVoice 两个会话合法 |
+| 3 | 打印违规点上下文 | `assistant(4 个 tool_calls)` 的响应被 4 条重复助手消息插开 |
+| 4 | 查重复消息来源 | 文件里存在"内容里的标记": 工具结果 `read_file .nexforge/sessions/session-…md` 的 dump 里带着真标记行 |
+| 5 | 统计幽灵消息 | 该会话多出 **10 份重复助手消息**; 修复后加载条数 3786 → 3785(少的那条正是幽灵) |
+| 6 | 用真机 API 复现 | 修复前的形态 → **400(与截图完全一致)**; 修复后 → 200 正常回复 |
+
+关键点: 违规在**中段**——这是"只修尾部"兜不住的原因, 也解释了为什么"历史会话能正常显示, 一说话就炸"。
+
+## 3. 修复
+
+| # | 位置 | 改动 |
+|---|---|---|
+| 1 | `store/session_store.py` `_escape_marker_prefix` | **写侧转义**: 人读部分里的 `<!-- nf-msg` 插零宽空格 → 内容不再具备标记形状(标记负载无损) |
+| 2 | `store/session_store.py` `_MARKER_RE` | **读侧锚定行首**(`re.M`): 只有独立成行的标记才是边界(dump 出来的标记带 ` 12 | ` 前缀, 旧正则也匹配) |
+| 3 | `core/session.py` `_repair_tool_sequence` | **全序列修复**(旧名保留为别名): 夹层消息保序后移、缺响应补"已取消"、重复/孤儿 tool 删除 → 修复后序列对 API **恒合法**; 调用点 `add_user` / `run_turn` / 回合结束 |
+| 4 | `core/agent.py` | 防死循环提示改为整块工具响应**之后**追加(原先会插进 tool 之间, 同类违规) |
+
+设计取舍与边界见 ADR: `docs/decisions/2026-09-12-内容里的标记不得当成消息边界.md`。
+
+## 4. 验证(三档)
+
+| 档 | 内容 | 结果 |
+|---|---|---|
+| 单元回归 | 新增/更新 20 项: 内容里的标记往返、锚定读入、中段违规修复、幂等、合法序列不动、add_user 恢复后合法 | `tests/test_session_store.py` `tests/test_session_repair.py` `tests/test_session_invariant.py` 全绿 |
+| 全量 + 门禁 | `pytest -q` 与 `scripts/check.py` | **577 passed / 3 skipped**;gate **6/6 PASS** |
+| 真机 API | 合成最小复现 + **用户真机会话切片** + **整会话 3785 条端到端** | 修复前 400(截图同款) → 修复后 OK(见 `session-marker-boundary_live.log`) |
+
+真机端到端最有力的一条: 用户会话**全部 3785 条**(体积 ≈ 980k prompt tokens)在修复后能正常得到回复,
+说明既不是"尾部侥幸合法", 也不是"切片合法、整体不合法"。
+
+**用户侧确认(2026-09-12)**: 该项目会话已恢复正常, 可继续对话(修复后首个回合由用户实机跑通)。
+
+## 5. 排查中的两个坑(留给后来者)
+
+1. **请求不能以 assistant 消息结尾**: thinking 模式下 DeepSeek 会报
+   `The reasoning_content in the thinking mode must be passed back to the API.`
+   `_repair_tool_sequence` 为兼容旧行为会**弹出尾部未配对 user**; 若在"修复后"自行构造请求
+   (而不是走 `run_turn` 的 `修复 → add_user` 顺序), 就会得到一个以 assistant 结尾的列表 →
+   触发这条 400, 看起来像"修复没生效"。**app 的真实路径永远以 user 结尾**, 不受影响。
+   排查时若看到这条错, 先看请求最后一条是不是 assistant。
+2. **同一请求重复 6 次全 OK**: 上面的 reasoning 报错与请求形态强相关(见坑 1), 不是服务端随机抖动;
+   排查"偶发"问题时先做 A/B 并打印规范形态哈希, 别急着下"服务端不稳定"的结论。
+
+## 6. 遗留与建议(本次未改)
+
+| 项 | 现状 | 建议 |
+|---|---|---|
+| 会话里已积累的 10 份重复助手消息 | 修复只**后移**不删除(不变量: 不允许无声丢失); 请求合法但占上下文 | 首次成功回合后 app 会重写会话文件; 重复内容如需清理请人工处理 |
+| 会话体量 ≈ 980k tokens | 实测: 会话本体 980,288 tokens; 加上 `DEFAULT_SYSTEM` + 47 个工具 schema(≈7.7k)+ `max_output_tokens`(32,768)≈ **1.02M**; 上下文窗口探针(1.25M tokens 的超长请求)通过 ⇒ 目前仍能发出, 但**已无余量** | 上下文治理只按"轮数 > 60"压缩、没有按 token 的裁剪 → 优先补"按 token 裁剪/强制压缩"; 短期内该项目建议 `/new` 开新会话 |
+| 失败的回合会丢弃那条用户消息 | 观测: 会话文件在 01:16 被(带本修复的)nf 重写, 序列已合法(非法点 0), 但尾部**没有**新用户消息与回复 → 说明那一轮以失败/中断收尾, 且 `_repair_tool_sequence` 的"弹尾部未配对 user"(沿用旧行为)把该用户消息从会话里移除了 | 若是"请求已发出但没成", `_repair_tool_sequence` 弹 user 这一步可考虑改为不弹(API 允许连续 user 消息); 需产品决策, 本次未改 |
+| 陈旧分段残留 | `save_session` 不清理"超出新段数的旧分段", 而 `load_session` 按序号连续读 → 列表变短(压缩)后旧内容被追加(已复现: 3 条被加载成 130 条)。全序列修复能兜住 400, 但内容冗余仍在 | 会话文件头声明分段数(`> 分段 N`), 加载按声明数读取, 超出的不读也不删 |
+
+## 7. 证据索引
+
+- `docs/evidence/session-marker-boundary.log` — 脚本级原始输出(旧行为 vs 修复后、真机会话校验、陈旧分段模拟)
+- `docs/evidence/session-marker-boundary_live.log` — 真机 API 原始输出(含 980k tokens 端到端)
+- `docs/evidence/session-marker-boundary_fulltest.log` — 全量测试输出
+- 回归测试: `tests/test_session_store.py::test_roundtrip_does_not_revive_marker_inside_content`、
+  `tests/test_session_store.py::test_load_ignores_marker_line_with_dump_prefix`、
+  `tests/test_session_repair.py::test_repair_mid_list_violation_keeps_responses_adjacent`