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

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

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

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

@@ -8,13 +8,14 @@
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.4.0** · PyPI: `pip install nexforge-cli`
-
-**v0.4.0 要点**：语音播报接入**本机 TTS**（如本地部署的 CosyVoice）——本机优先、
-失败自动回退微软 Windows 语音；用 nf 时让本机模型**常驻显存**、nf 全部退出即释放
-（租约机制，被强杀也能自愈回收）。新增 `/voice full|brief` 切换播报范围（默认**全量播报**）。
-另修：配置里的残留值（失效 provider / 旧档位）自动收敛并给出可定位告警，
-不再让启动失败或报假警。
+> 当前版本:**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.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.4.0 → nexforge_cli-0.4.1}/docs/decisions/README.md

@@ -66,3 +66,4 @@
 | 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.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`

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

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

{nexforge_cli-0.4.0 → nexforge_cli-0.4.1}/manual/README.md

@@ -1,4 +1,4 @@
-# NexForgeCLI 用户手册 · v0.4.0
+# NexForgeCLI 用户手册 · v0.4.1
 
 ## 这是什么
 

{nexforge_cli-0.4.0 → nexforge_cli-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nexforge-cli"
-version = "0.4.0"
+version = "0.4.1"
 description = "NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)"
 readme = "README.md"
 requires-python = ">=3.11"

{nexforge_cli-0.4.0 → nexforge_cli-0.4.1}/src/nexforge/__init__.py

@@ -3,5 +3,5 @@
 TUI(全屏交互)+ CLI(one-shot / 管道)双模式。
 """
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 __all__ = ["__version__"]

{nexforge_cli-0.4.0 → nexforge_cli-0.4.1}/src/nexforge/core/agent.py

@@ -92,10 +92,11 @@ class AgentLoop:
         self._approve = approve
 
     async def run_turn(self, user_text: str) -> AsyncIterator[AgentEvent]:
-        # 兜底:修复上次中断残留的不完整尾部(超时/取消/异常),
-        # 防止 assistant(tool_calls) 缺 tool 响应导致 DeepSeek 400 罢工
-        from nexforge.core.session import _repair_incomplete_tail
-        _repair_incomplete_tail(self.session.messages)
+        # 兜底:全序列修复 —— 上次中断残留(超时/取消/异常)与历史文件里的
+        # 非法错位都在此消除, 否则 assistant(tool_calls) 不紧跟 tool 响应
+        # → DeepSeek 400 罢工(每轮都失败)
+        from nexforge.core.session import _repair_tool_sequence
+        _repair_tool_sequence(self.session.messages)
         self.session.add_user(user_text)
         last_failed: tuple[str, str] = ("", "")
         consecutive_fails = 0
@@ -137,6 +138,10 @@ class AgentLoop:
                     yield AgentEvent(AgentEventKind.TURN_DONE, message=final_msg)
                     return
 
+                # 防死循环提示必须**整块工具响应之后**追加: 混在 tool 消息之间
+                # 会让 assistant(tool_calls) 的响应不连续(API 要求紧跟),
+                # 与 session._repair_tool_sequence 的判据同源。
+                loop_hints: list[str] = []
                 for tc in final_msg.tool_calls:
                     args = self.registry.parse_args(tc.arguments)
                     tool = self.registry.get(tc.name)
@@ -158,13 +163,11 @@ class AgentLoop:
                         if consecutive_fails >= 3:
                             # 运行地派生(D9_decision.md A5): 由失败计数重算,
                             # 属瞬态纠偏, 不随会话落盘(恢复后不再需要)。
-                            self.session.messages.append({
-                                "role": "system",
-                                "content": (
-                                    f"[防死循环] 工具 {tc.name} 已连续失败 {consecutive_fails} 次。"
-                                    "请不要重复相同调用;换一种方法或跳过当前步骤,如无法完成则向用户说明原因并结束。"
-                                ),
-                            })
+                            # 先收集, 循环结束后统一追加(见上: 不得插进 tool 之间)
+                            loop_hints.append(
+                                f"[防死循环] 工具 {tc.name} 已连续失败 {consecutive_fails} 次。"
+                                "请不要重复相同调用;换一种方法或跳过当前步骤,如无法完成则向用户说明原因并结束。"
+                            )
                             consecutive_fails = 0  # 复位,避免重复注入
                     else:
                         # 成功 → 重置失败跟踪
@@ -176,6 +179,8 @@ class AgentLoop:
                         tool_ok=result.ok,
                         tool_summary=result.summary or result.error or result.output[:60],
                     )
+                for hint in loop_hints:
+                    self.session.messages.append({"role": "system", "content": hint})
 
             yield AgentEvent(
                 AgentEventKind.ERROR,