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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge
@@ -51,14 +51,13 @@ Description-Content-Type: text/markdown
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.3.0** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.4.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.0 要点**：语音播报接入**本机 TTS**（如本地部署的 CosyVoice）——本机优先、
+失败自动回退微软 Windows 语音；用 nf 时让本机模型**常驻显存**、nf 全部退出即释放
+（租约机制，被强杀也能自愈回收）。新增 `/voice full|brief` 切换播报范围（默认**全量播报**）。
+另修：配置里的残留值（失效 provider / 旧档位）自动收敛并给出可定位告警，
+不再让启动失败或报假警。
 
 ---
 

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

@@ -8,14 +8,13 @@
 
 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.0** · PyPI: `pip install nexforge-cli`
+
+**v0.4.0 要点**：语音播报接入**本机 TTS**（如本地部署的 CosyVoice）——本机优先、
+失败自动回退微软 Windows 语音；用 nf 时让本机模型**常驻显存**、nf 全部退出即释放
+（租约机制，被强杀也能自愈回收）。新增 `/voice full|brief` 切换播报范围（默认**全量播报**）。
+另修：配置里的残留值（失效 provider / 旧档位）自动收敛并给出可定位告警，
+不再让启动失败或报假警。
 
 ---
 

{nexforge_cli-0.3.0 → nexforge_cli-0.4.0}/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.0/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.3.0 → nexforge_cli-0.4.0}/docs/decisions/README.md

@@ -65,3 +65,4 @@
 | 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) | 生效 |

nexforge_cli-0.4.0/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.3.0 → nexforge_cli-0.4.0}/manual/01-/345/256/211/350/243/205/344/270/216/351/205/215/347/275/256.md

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

{nexforge_cli-0.3.0 → nexforge_cli-0.4.0}/manual/02-/347/225/214/351/235/242/344/270/216/345/277/253/346/215/267/351/224/256.md

@@ -82,6 +82,7 @@
 | `/provider [<name>]` | 无参数列出提供者;带参数切换 |
 | `/model flash` | 切换模型档位(仅 DeepSeek) |
 | `/think on|off` | 开关思考模式(仅 DeepSeek) |
+| `/voice full|brief` | 语音播报范围(full=**全量播报**最终报告, 默认; brief=只播报第一段) |
 | `/balance` | 查询账户余额(仅 DeepSeek) |
 | `/cost` | 显示累计费用 |
 

{nexforge_cli-0.3.0 → nexforge_cli-0.4.0}/manual/08-/350/207/252/345/256/232/344/271/211/351/205/215/347/275/256.md

@@ -54,11 +54,17 @@ base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"  # 可选, 图片
 global_path = "~/.nexforge/kb"  # 全局知识库位置(可自定义到其他硬盘, 如 D:/NexKB)
 
 [tts]
+# 语音播报(需安装 speech_summary 插件): 默认 auto = 本机 CosyVoice 优先 → 微软 Windows 语音回退
 api_key = ""                    # 千问平台 TTS key(留空回退 [image])
 model = "qwen-audio-3.0-tts-flash"  # 千问 TTS 模型
-voice = "loongmary"             # 音色(flash 用 loong 系列: loongmary/loongeva/loongJohn 等)
-engine = "auto"                 # auto | qianwen | local
-max_chars = 100                 # 简报最大字符数
+voice = "loongmary"             # 千问音色(flash 用 loong 系列: loongmary/loongeva/loongJohn 等)
+engine = "auto"                 # auto | cosyvoice | local(微软, 别名 microsoft) | qianwen
+cosyvoice_url = "http://127.0.0.1:9880"  # 本机 CosyVoice 服务(见其 local_deploy/service)
+cosyvoice_voice = "default"     # 本机服务音色 id(GET /voices 可查)
+cosyvoice_timeout_s = 90        # 本机服务超时(空闲卸载后冷启动约 20s, 留足余量)
+cosyvoice_resident = true       # nf 运行期间让本机模型常驻显存(退出后服务端立即卸载)
+max_chars = 0                   # 播报文本上限(0=不限, 默认; 配合全量播报)
+mode = "full"                   # 播报范围: full=全量播报最终报告(默认) | brief=只播第一段
 enabled = true                  # 语音播报总开关
 
 [search]

{nexforge_cli-0.3.0 → nexforge_cli-0.4.0}/manual/09-/345/270/270/350/247/201/351/227/256/351/242/230.md

@@ -34,6 +34,16 @@ DeepSeek：https://platform.deepseek.com/api_keys
 
 ## 模型与连接
 
+**Q：启动后提示「provider 'xxx' 未在配置中定义」/「未初始化，无法对话」？**
+
+`config.toml` 的 `[provider] default` 指向的 provider 已不在 `models.toml` 里（被删除或改名，
+例如早期版本的 `deepseek-v41`）。这类**悬空值**会让初始化失败，并连带报出误导性的"缺少 API Key"。
+
+- **当前版本会自动回退**到内置 `deepseek`，并打印一条 `[配置警告]`（不阻断启动）。
+- 若你仍看到"初始化失败"，说明 nf 是旧版本 → `pip install -U nexforge-cli`。
+- 想继续用某个 provider：把 `[provider] default` 改成它在 `models.toml` 中的 `name`；
+  用 `F6` 侧栏点选 provider 也会自动写回。
+
 **Q：切换模型后没有反应？**
 
 1. 先按 F6，在侧边栏点击「验证」测试连通性
@@ -87,6 +97,29 @@ DeepSeek：https://platform.deepseek.com/api_keys
 
 浏览器打开 http://localhost:8899，可查看会话/计划/消息、发送消息（仅本机可访问）。
 
+## 语音播报
+
+**Q：播报变成微软的声音了（或干脆没声音）？**
+
+语音默认走 **本机 CosyVoice 服务优先 → 失败自动回退微软 Windows 语音**（`[tts] engine = "auto"`）。
+播报成微软的声音，说明本机服务当时没响应。排查顺序：
+
+```bat
+:: 1) 服务在不在（该"服务"是常驻守护进程, 模型按需加载）
+D:\DevelopProject\CosyVoice\local_deploy\service\service.bat status
+D:\DevelopProject\CosyVoice\local_deploy\service\service.bat start
+
+:: 2) 看 nf 里的实时状态与原因（会主动探测本机服务）
+/capabilities
+```
+
+- **服务空闲会自动卸载模型**（默认 300s，见 CosyVoice 的 `service/config.json` 里 `idle_timeout_s`）。
+  下一句播报会**冷启动约 20s**：这段时间没声音是正常的（nf 的超时给了 90s，会等它）。
+  想避免冷启动：把 `idle_timeout_s` 设为 `0`（常驻）或调大。
+- **固定用某个引擎**：`[tts] engine = "cosyvoice"`（只用本机，不静默换声音）、
+  `"local"`（只用微软）、`"qianwen"`（云端，需 dashscope 与 Key）。
+- 本机服务不可用而回退微软时，**首次会提示一次**（带原因），不会悄悄换声音。
+
 ## 终端
 
 **Q：终端标签显示乱码？**

{nexforge_cli-0.3.0 → nexforge_cli-0.4.0}/manual/10-/346/217/222/344/273/266/345/274/200/345/217/221.md

@@ -71,8 +71,9 @@ def register(api):
 源码在仓库 **`plugin_speech_summary/`**（含 `install_plugin.py` 安装器与自检），
 安装后位于 `~/.nexforge/plugins/speech_summary.py` —— 每轮任务结束用 TTS 播报简报：
 
-- **引擎**：千问语音合成（qwen-audio-3.0-tts-flash，官方 dashscope SDK WebSocket 方式）优先，失败自动回退 Windows 本地语音（SAPI）
-- **配置**（config.toml `[tts]` 段）：`engine=auto|qianwen|local`、`voice`、`api_key`（留空用 [image] 按量 key）、`ws_url`、`max_chars`、`enabled`
+- **引擎**：**本机 CosyVoice 服务优先**（HTTP `127.0.0.1:9880`，见 CosyVoice 项目的 `local_deploy/service`），失败自动回退微软 Windows 本地语音（SAPI）；千问 TTS 保留为显式选项（`engine="qianwen"`）
+- **配置**（config.toml `[tts]` 段）：`engine=auto|cosyvoice|local(别名 microsoft)|qianwen`、`cosyvoice_url`/`cosyvoice_voice`/`cosyvoice_timeout_s`/`cosyvoice_resident`、`voice`、`api_key`（留空用 [image] 按量 key）、`ws_url`、`max_chars`（0=不限，默认）、`mode`（`full`=全量播报最终报告，默认 / `brief`=只播第一段）、`enabled`
+- **模型常驻**（`cosyvoice_resident = true`，默认开）：nf 启动即向本机 TTS 服务登记"租约"，模型随预热加载并**常驻显存**（首句播报不用等约 20s 冷启动）；**所有 nf 退出后服务端立即卸载**。客户端被强杀也不会把显存占住——服务端按 PID 存活 + 心跳超时回收租约。
 - **不阻塞**：合成+播放在后台线程，回合结束流程零延迟
 - **简报内容**：项目名 + 工具调用次数 + AI 最终总结摘要（自动清理 Markdown 符号）
 

{nexforge_cli-0.3.0 → nexforge_cli-0.4.0}/manual/11-/345/274/200/345/217/221/346/240/241/351/252/214.md

@@ -27,6 +27,8 @@ python scripts/check.py --only version-sync   # 只跑一项
 | `manual-consistency` | 手册与代码一致性（工具、命令、快捷键、配置字段、引用路径、链接）| 具体用例名与断言消息 |
 | `registry-consistency` | 工具 / 斜杠命令 / 快捷键 与手册**双向**匹配 | 缺失项与幽灵项（手册写了但代码没有）|
 | `hygiene` | 临时残留目录、敏感文件、异常大文件 | 路径与命中规则名 |
+| `eof-newline` | 跟踪的文本文件必须以换行结尾（防「黏行」损坏）| 缺换行的文件路径 + 补换行提示 |
+| `example-config` | `config.example.toml` 的每个值必须等于代码默认值 | 偏离字段（示例值 vs 默认值）|
 
 ## 端到端冒烟(需真实 API Key)
 

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

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

nexforge_cli-0.4.0/plugin_speech_summary/README.md

@@ -0,0 +1,127 @@
+# NexForgeCLI 插件：任务简报语音播报
+
+每轮任务结束后，用 TTS 播报一句简报（项目名 + 工具调用次数 + AI 总结摘要）。
+
+> 这是 NexForgeCLI 的**内置示例插件**，源码随仓库提供，可作插件开发的参考实现。
+
+---
+
+## 安装
+
+```bash
+# 方式 A：用安装脚本（推荐）
+python install_plugin.py             # 装到用户级 ~/.nexforge/plugins/
+python install_plugin.py --project   # 装到当前项目 .nexforge/plugins/
+python install_plugin.py --check     # 只自检，不安装
+python install_plugin.py --uninstall # 卸载
+
+# 方式 B：手动复制
+cp speech_summary.py ~/.nexforge/plugins/
+```
+
+装好后**重启 nf** 生效 —— 本插件注册的是 **UI 特性**（`register/on_mount` 生命周期钩子），
+而 `/plugins reload` 只重载**工具/技能**（nf 自己也会提示「新特性需重启」）。
+`/plugins` 可查看插件加载状态。
+
+---
+
+## 配置（`config.toml` 的 `[tts]` 段）
+
+```toml
+[tts]
+enabled   = true                       # 总开关
+engine    = "auto"                     # auto | cosyvoice | local(微软, 别名 microsoft) | qianwen
+# —— 本机 CosyVoice 服务(推荐; 见 CosyVoice 项目的 local_deploy/service) ——
+cosyvoice_url       = "http://127.0.0.1:9880"   # 仅回环, 无需鉴权
+cosyvoice_voice     = "default"                 # 音色 id(GET /voices 可查)
+cosyvoice_timeout_s = 90                        # 空闲会卸载模型 → 冷启动约 20s, 留足余量
+cosyvoice_resident  = true                     # nf 在跑就让模型常驻; nf 全退出后服务端立即卸载
+# —— 千问 TTS(可选) ——
+voice     = "loongmary"                # 千问音色(loong 系列)
+model     = "qwen-audio-3.0-tts-flash"
+api_key   = ""                         # 留空回退 [image] 段 / DASHSCOPE_API_KEY / dashscope.key
+ws_url    = ""                         # 留空用官方默认 WebSocket 端点
+max_chars = 0                          # 播报文本上限(0=不限, 默认)
+mode      = "full"                     # 播报范围: full=全量播报最终报告 | brief=只播第一段
+```
+
+## 引擎
+
+| engine | 行为 | 依赖 |
+|---|---|---|
+| `cosyvoice` | **本机 CosyVoice 服务**（HTTP `POST /tts`）| 本机服务在跑（`service.bat start`）|
+| `local`（别名 `microsoft`） | 微软 Windows 语音（SAPI，优先选中文音色）| Windows |
+| `qianwen` | 千问语音合成（WebSocket）| `pip install dashscope` + 控制台开通 qwen-audio-3.0-tts-flash |
+| `auto`（默认） | **本机 CosyVoice 优先 → 失败回退微软 Windows 语音** | 见上 |
+
+> 优先级按"本机优先"设计：本机服务可用时不出网、不产生云端费用；它没起来时自动退到
+> 微软语音，**并在首次回退时提示一次**（否则用户只会觉得"声音变了"却查不出原因）。
+> 千问不在 auto 链里 —— 它是要花钱的云端服务，需显式 `engine = "qianwen"` 才用。
+
+---
+
+## 播报范围（`/voice` 切换）
+
+| mode | 播报内容 |
+|---|---|
+| `full`（默认） | **全量播报**最终报告 —— 本机合成本来就不花 token，没必要截断 |
+| `brief` | 只播报最终报告的**第一段**（若首段是代码块，自动跳到下一段，避免念代码）|
+
+两种模式都会带上"项目名 + 本轮调用工具次数"的前缀；`max_chars`（默认 0=不限）可作兜底上限。
+
+```
+/voice            # 查看当前范围
+/voice full       # 全量播报(默认)
+/voice brief      # 只播第一段
+```
+
+> 在 nf 里直接输入 `/voice brief` 即可，切换会**写回项目配置**（重启后仍生效）。
+
+**两条容易踩的细节**（都已按「尊重你的显式操作」实现）：
+
+- **只有启动时预热一次**，之后只续租（`warm=false`）。所以你手动
+  `service.bat unload` 释放显存后，模型**不会被 nf 抢着加载回来** ——
+  下次真正播报时按需加载，之后照常常驻。
+- **重复挂载也安全**：起续租线程前先问服务端「我这个 pid 已在租约里了吗」，
+  已登记就直接返回 —— 不会出现多个线程重复续租。
+
+## 模型常驻(租约)
+
+默认 **`cosyvoice_resident = true`**：nf 一启动就向本机服务登记一个**租约**，模型随即在后台加载并**常驻显存**，
+于是播报不用每次等 20s 冷启动；**nf 全部退出后服务端立即卸载**（不等空闲超时）。
+
+- 为什么这么做：用 nf 的时候基本不跑别的 GPU 活，常驻换来"随叫随到"；不用了立刻还显存。
+- **强杀也不怕**：nf 被 `taskkill /F` / 崩溃时不会自己注销租约，服务端按 **PID 存活 + 心跳超时**
+  自愈回收（否则 3.7GB 显存会被无声占住）。
+- 其他软件调用本机服务的行为**不变**：没租约时仍是"按需加载 + 空闲卸载"。
+- 不想要常驻：`cosyvoice_resident = false`；想立刻释放：`service.bat unload`。
+- 查看租约：`service.bat leases` 或 `status` 里的 `leases` / `resident` 字段。
+
+---
+
+## 设计要点
+
+1. **不阻塞**：合成 + 播放在后台线程，回合结束流程零延迟。
+2. **不可用原因可见**（E 审计改进）：引擎不可用 / 缺 SDK / 平台不支持时，会明确告知原因
+   （如「未安装 dashscope(pip install dashscope)」），**同一原因只提示一次**（防刷屏）。
+   仅"播报过程内"的异常才静默——不影响主流程。
+3. **目标模式跳过**：多轮循环下单轮结束 ≠ 任务完成，播报会误导，故跳过。
+4. **简报内容**：自动清理 Markdown 符号（代码块/加粗/链接等），只留可朗读正文。
+5. **能力登记**：向主程序登记 `tts` 能力，`/capabilities` 可查看其状态与不可用原因
+   （旧版主程序没有该模块时会自动跳过，不影响插件本身）。
+6. **回退要说话**（本机 TTS 接入新增）：auto 模式里本机服务不可用而退到微软语音时，
+   **首次会提示一次**（带原因）——否则用户只会觉得“声音变了”却查不出原因。
+7. **只认真正的 wav**：本机服务返回的响应必须带 `RIFF` 魔数才拿去播，
+   避免把错误页/空响应当音频播出去。
+8. **探测有缓存、上报则现探**：每轮播报前的就绪检查走 30s 缓存（不卡 UI），
+   而 `/capabilities` 每次都实时探测 —— 避免“上报说可用、实际跑不通”。
+
+---
+
+## 自检
+
+```bash
+python install_plugin.py --check
+```
+
+会报告：dashscope SDK 是否安装、当前平台、各 engine 的可用性判定。

{nexforge_cli-0.3.0 → nexforge_cli-0.4.0}/plugin_speech_summary/install_plugin.py

@@ -46,25 +46,49 @@ def uninstall() -> None:
 
 
 def check() -> bool:
-    """环境自检: SDK / 平台 / 各引擎可用性。"""
+    """环境自检: 本机 TTS 服务 / SDK / 平台 / 引擎链可用性。"""
     print("== 环境自检 ==")
     ok = True
 
+    # 本机 CosyVoice 服务(auto 链的首选引擎)
+    sys.path.insert(0, str(HERE))
+    try:
+        import speech_summary as ss
+
+        cfg_tts = None
+        try:
+            from nexforge.config import load_config
+
+            cfg_tts = load_config().tts
+        except Exception:
+            pass
+        if cfg_tts is not None:
+            url = ss._cosy_url(cfg_tts)
+            if ss._cosyvoice_ready(cfg_tts, timeout=2.5):
+                print(f"  本机 TTS 服务: 在跑({url}) → auto 将优先用它")
+            else:
+                print(f"  本机 TTS 服务: 未响应({url})")
+                print("                 启动: CosyVoice\\local_deploy\\service\\service.bat start")
+                print("                 (未启动时 auto 会回退微软 Windows 语音)")
+        plugin_import_ok = True
+    except Exception as exc:
+        print(f"  插件导入: 失败! {exc}")
+        ok = False
+        plugin_import_ok = False
+
     try:
         import dashscope  # noqa: F401
 
-        print("  dashscope SDK: 已安装(千问 TTS 可用)")
+        print("  dashscope SDK: 已安装(千问 TTS 可用, 需显式 engine=\"qianwen\")")
     except ImportError:
-        print("  dashscope SDK: 未安装 → 千问引擎不可用, 将回退本地语音")
+        print("  dashscope SDK: 未安装 → 千问引擎不可用(auto 链不依赖它)")
         print("                 需要时: pip install dashscope")
 
     if os.name == "nt":
-        print("  平台: Windows(本地 SAPI 可用)")
+        print("  平台: Windows(微软 SAPI 语音可用, 作 auto 的回退)")
     else:
-        print(f"  平台: {os.name}(本地 SAPI 仅 Windows 支持)")
-        try:
-            import dashscope  # noqa: F401
-        except ImportError:
+        print(f"  平台: {os.name}(微软 SAPI 仅 Windows 支持)")
+        if not _local_service_ok(cfg_tts):
             ok = False
 
     key_file = Path.home() / ".nexforge" / "dashscope.key"
@@ -72,22 +96,27 @@ def check() -> bool:
     if has_env or key_file.exists():
         print("  DashScope Key: 已检测到(环境变量或 dashscope.key)")
     else:
-        print("  DashScope Key: 未检测到(可写 config.toml [tts]/[image] 段 api_key)")
-
-    # 试导入插件本体
-    sys.path.insert(0, str(HERE))
-    try:
-        import speech_summary as ss  # noqa: F401
+        print("  DashScope Key: 未检测到(仅千问引擎需要; 可写 config.toml [tts]/[image] 段 api_key)")
 
+    if plugin_import_ok:
         print("  插件导入: OK(register 已加载)")
-    except Exception as exc:
-        print(f"  插件导入: 失败! {exc}")
-        ok = False
 
     print("== 自检通过 ==" if ok else "== 自检未通过, 按提示修复 ==")
     return ok
 
 
+def _local_service_ok(cfg_tts) -> bool:  # noqa: ANN001
+    """非 Windows 平台: 只有本机服务可用时 auto 才成立。"""
+    if cfg_tts is None:
+        return False
+    try:
+        import speech_summary as ss
+
+        return ss._cosyvoice_ready(cfg_tts, timeout=2.5)
+    except Exception:
+        return False
+
+
 def main() -> None:
     ap = argparse.ArgumentParser(description="语音播报插件安装器")
     ap.add_argument("--project", action="store_true", help="安装到项目级(默认用户级)")