mingdao-harness 0.6.11 → 0.6.13

package/README.md

@@ -275,7 +275,7 @@ mingdao cost --by pack          # 垂域费用分账
 
 ## 配置与扩展
 
-配置字段、权限规则、Hooks、MCP、云同步、自定义 Provider 的完整说明见 [docs/CONFIG.md](docs/CONFIG.md)；架构见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)；Provider 扩展见 [docs/PROVIDERS.md](docs/PROVIDERS.md)。
+配置字段、权限规则、Hooks、MCP、云同步、自定义 Provider 的完整说明见 [docs/CONFIG.md](docs/CONFIG.md)；架构见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)；Provider 扩展见 [docs/PROVIDERS.md](docs/PROVIDERS.md)；桌面版自动更新（检查 / 下载 / 来源签名 / feed 与发版链路）见 [docs/DESKTOP-AUTO-UPDATE.md](docs/DESKTOP-AUTO-UPDATE.md)。
 
 ## 常见问题
 

package/docs/CONFIG.md

@@ -406,6 +406,161 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 { "timeout": { "firstTokenMs": 600000, "streamIdleMs": 120000, "totalMs": 1800000 } }
 ```
 
+#### 单请求超时之外的"回合级"护栏（v0.6.13）
+
+上面三个超时**都是单请求级**：一次请求最多耗到 `totalMs`。而一个回合最坏是
+`maxRounds × stepLimit` 次请求（默认 3 × 24 = 72），`task` 子代理各自还有一整套预算且可递归派生——
+真机实测出现过「本地 35B 的审计回合跑了 4 小时 20 分、界面 0 步、`web-server.log` 只有一行」的现场
+（`audit.jsonl` 里那 4 小时里有 610 次工具调用，绝大多数是**逐字重复**的失败调用）。
+所以补了一条回合级判据：
+
+```json
+{ "noProgressTimeoutMs": 3600000 }
+```
+
+- **判据**：连续 N 分钟**既没有"成功且不重复的工具结果"、也没有新的正文/推理增量** → 主动中止整个
+  回合，并如实报告「连续 N 分钟没有任何工具调用、也没有新内容，已中止」+ 已发生的模型轮次/工具调用数，
+  外加**中止时正在等待哪个工具、等了多久**，以及与 `capped`/`aborted` 的区别
+  （capped = 跑满步数上限、可续跑；aborted = 你点的停止；stalled = 再等下去也不会产出新东西）。
+  重复调用（name+args 完全相同）与失败调用**不算进展**——真机现场正是它们把时间烧光的。
+- **默认 60 分钟**的依据：现有单请求总量上限是本地 1800s；回合级阈值取它的 **2 倍**，
+  保证"一次慢 prefill"永远由更具体的请求级超时（首帧/空闲/总量各有文案）先说话，看门狗不抢答；
+  而真干活的回合每隔几秒就有工具结果或正文增量，60 分钟零增量在任何正常回合都不可能。
+- 该值**不能**用 0/负数/Infinity 关掉（一律回落默认，fail-safe）；子代理会**继承父回合的阈值**
+  （24 个并行子代理不会各跑各的几小时），且继承的**截止时刻是活的**——它随父回合的进展前移。
+- **子代理的进展算父回合的进展**（v0.6.13 真机修复）：父回合在 `await task` 期间拿不到任何中间信号，
+  所以子代理每有一次真实进展（成功且不重复的工具结果 / 新正文增量）就回调父回合，父回合据此续期，
+  并把快照挂在 `io.turnProgress.subagent` 上——`web-server.log` 的进度行与界面状态条因此能写出
+  「正在等待工具 task（已 620s）· 子代理「审计 agent.js」已跑 12 轮 / 17 次工具调用，最后进展 3s 前」，
+  "在等子代理"与"卡死"才分得开（真机现场日志里只有前者，看不出子代理是在干活还是死了）。
+- **子代理卡住由它自己的看门狗先响**：父回合在等待子代理时只多等 15s
+  （`SUBAGENT_WAIT_GRACE_MS`，相对默认 60 分钟是 0.4%——**不是**放宽阈值），
+  这样子代理的收口结论（"自己无进展"还是"父回合整轮无进展"）能原样回传父回合，
+  而不是被父回合抢先掐断、只剩一句"父回合中止"。
+- **stalled 在界面上必须有说明**：内核发一条告警 banner（内容与 `done.note` 同源），
+  前端在消息下方再留一条，并把结局（含两种 stalled 原因）写进控制台
+  ——桌面壳日志取的就是渲染进程 console，此前那里只有「回合收尾：generating=false」，
+  与内核的 `status=stalled` 对不上。
+
+#### 端点预检（v0.6.13，本地端点自动执行）
+
+对**本地端点**（baseUrl 是回环/内网，或 `customModels.<名>.local: true`）在开工前做一次轻量预检
+（结果缓存 10 分钟，只读不写你的配置）：
+
+1. 读**引擎自述上下文**（`GET /props`，见下一条）——配置的 `contextWindow` 超没超引擎能力，只有这里能知道；
+2. 发 **3 次**极小请求（1 条 user + 1 个工具声明 + `max_tokens: 256`），看 `tool_calls` 与 `finish_reason`，
+   给出三态之一：**稳定支持**（3/3）/ **不稳定**（N/3，会提示"agent 任务可能步数为 0"）/ **不支持**（0/3）；
+   被 `max_tokens` 截断的样本（`finish_reason: length`，思考型模型常见）判为**不可判定**，不当作"不支持"；
+   （引擎实际加载的模型名从 chat 响应的 `model` 字段读——**不**额外打 `GET /models`：有的端点没实现它，
+   而 llama.cpp 在流式响应里直接回完整文件路径，语义等价且少一个请求。）
+3. 再发一次 **参考 prefill**（约 2000 tokens 的提示）测耗时；
+4. 与本机历史值比对：**同一端点明显变慢**（≥3 倍）会提示"该端点可能仍在处理上一个请求，建议重启引擎"。
+
+#### 预检读「引擎自述上下文」（v0.6.13）
+
+本地端点预检时**额外读一次引擎自述**（`GET /props`，只读、不改配置）：
+
+- llama.cpp 的 `/props` 通常返回 `default_generation_settings.n_ctx`（有的版本另有顶层 `n_ctx`/`n_ctx_train`）；
+  其他引擎能读多少读多少（`max_model_len`、`context_length`、`model_info.*.context_length`），
+  **读不到就跳过并说明**（不猜、不编造、也不据此判定端点不行）。
+  `/props` 挂在根上，而 `baseUrl` 通常带 `/v1`，预检会先剥掉 `/v\d+` 再试，失败再退回原样。
+- **什么时候会去打这个请求**：只有端点**自报了模型名**才打。llama.cpp 家族（含 llama-cpp-python/
+  koboldcpp/LM Studio）总会在响应里回模型名或模型文件路径；回不了名的多半是"只实现了
+  `/v1/chat/completions`"的网关或测试桩——它们不认识 `/props`，多打一个 GET 可能把对方打断
+  （本仓 `test/e2e-web.js` 的 mock 就是这样被打挂的：它只按 `POST + JSON body` 解析）。
+  跳过时结论里会写「引擎自述上下文：跳过（该端点未自报模型名，不确认它实现 /props）」，
+  不会假装核对过。
+- 结论会与配置**并排**写出来，同时出现在界面 banner、`web-server.log`
+  （`预检 <模型> … 引擎自述上下文=… 配置=…`）与发送前的规模预告里：
+
+  ```
+  ⚠ 引擎自述上下文 32768 vs 配置 131072 —— 配置超出引擎能力，长上下文将直接被引擎拒绝
+  ```
+
+- 为什么这条必须有：真机实测配置 `contextWindow: 131072`、引擎只装了 32768，
+  15,983 tokens 的 prompt 在 prefill 阶段就被引擎拒绝（`insufficient memory: the request exceeded
+  available GPU memory … during prefill`）。此时**换预设、调小 `contextBudget`、调大 `timeout.*`
+  都无效**——它们改不了引擎的 `n_ctx`；要么在引擎侧把上下文窗口调大
+  （llama.cpp 的 `--ctx-size` / `--context-window`），要么把 `customModels.<名>.contextWindow` 改成 ≤ 引擎值。
+
+#### 发送前的规模预告由预检实测推导（v0.6.13）
+
+回合开始前的 `📏 本轮上下文 ≈ …` 预告，在**有预检实测**时按
+`参考 prefill 耗时 × 本轮 tokens ÷ 参考 tokens` 线性外推，并在文案里注明这是外推、以及
+"长上下文下引擎可能显著变慢"的实测差值（本机 16k tokens 首帧 53.7s，而按同一份预检外推只有 0.6s）——
+只报乐观值会训练用户忽略这条告警。**只有拿不到预检数据**（端点不可达 / 不可判定）时才退回
+"prefill 可能需数分钟至数十分钟"的保守文案；外推超过 60s（`PREFILL_SLOW_WARN_MS`）才告警，
+且必须写出依据（预检实测值 + 本轮 tokens + 阈值）。
+
+预检结论会出现在：回合开始时的界面 banner、`web-server.log`（`预检 <模型> …` 行）、
+以及发送前的规模预告里。并且**按实测 TTFT 自适应**超时：首帧上限 = clamp(max(实测首帧×20, 参考prefill×5),
+既有默认, 1800s)、无进展看门狗 = clamp(max(实测首帧×100, 参考prefill×20), 10min, 60min)；
+**你显式配置的 `timeout.*` / `noProgressTimeoutMs` 永远优先**（显式 > 自适应）。
+
+### 用本地模型测 harness（测试者步骤清单）
+
+> 这一段是**操作清单**，不是原理说明。按顺序做，能在几分钟内区分"端点不行"和"harness 不行"。
+
+**第 0 步：确认引擎在跑、名字对不对**
+
+```bash
+curl -s http://127.0.0.1:8081/v1/models | head -c 400      # 端口按你的部署改
+```
+
+- 返回里应当看到**配置项名**对应的模型。若引擎回的是完整文件路径/别的名字（本机实测：
+  配置 `MLocalModel3.6.2`，引擎回 `/Users/…/mLocalModel3.6.2.gguf`），预检会把两者都写出来——
+  先确认"配的就是跑的那个"，再谈性能。
+
+**第 1 步：先跑预检（一条命令看到 TTFT 与工具支持）**
+
+预检在**每轮对话开始前自动执行**（仅本地端点），界面上会出现两行：
+
+```
+🔎 本地端点预检：✅ 稳定支持工具调用（3/3） · 首帧 1.22s · 参考 prefill 2000 tokens 9.71s · 引擎加载 …gguf
+   自适应：首帧上限 600s、无进展看门狗 60 分钟（依据：预检实测 首帧 1220ms + 参考 prefill 9708ms）
+```
+
+同一条结论会落进 `~/.mingdao/logs/web-server.log`（`预检 <模型> <状态>(<toolState> N/M) ttft=… prefill2000=…`）。
+看到这些就说明通路与能力都测过了；**不要**跳过这步直接放大任务。
+
+**第 2 步：小任务验证通路**
+
+```
+帮我看看这个仓库的 README，列出三层小标题
+```
+
+验收标准：几十秒内出现正文；`web-server.log` 里有 `chat 首帧 <taskId> <秒>` 与每 30s 一行的
+`chat 进度 <taskId> 已跑 …阶段=… 模型轮次=… 工具调用=…`；界面状态条上有「工具调用 N 次」（0 也要显示为 0）。
+
+**第 3 步：按模块切分，再放大**
+
+35B 级模型 + 131k 窗口做**全量仓库审计**时：上下文越大，prefill 越久（本机实测 35B Q4_K_M
+约 4.9ms/token：2 万 tokens ≈ 1.6 分钟；13 万窗口 ≈ 10 分钟以上，且会顶满引擎内存预算）。
+所以：
+
+- 先用预设 `local-model`（`contextBudget` 65536）或自己在预设里调小 `contextBudget`；
+- 一次只做一个模块/一个目录，别一次喂整仓；
+- 真要长跑，把 `timeout.firstTokenMs` 调大（例如 900000）——但要知道**这只会让失败更晚被发现**，
+  不会让 prefill 变快。
+
+**第 4 步：认识四类"卡住"分别长什么样**
+
+| 现象 | 内核会给什么信号 |
+| --- | --- |
+| 引擎没起来 / 端口不对 | 预检 `❌ 不可达：…`；请求以 `网络请求失败` 报错（几秒内） |
+| 连上但不发首帧 | 到 `timeout.firstTokenMs` 报「首 token 等待超限（Ns，本地模型长上下文 prefill 可能很慢）——可调大 config.timeout.firstTokenMs…」 |
+| 有帧但长时间没新数据 | 到 `timeout.streamIdleMs`（默认 120s）报「流式响应空闲超限（Ns 无新数据）」 |
+| 每轮都能返回、但什么都没做成 | 到 `noProgressTimeoutMs`（默认 60min，快端点自适应到 10min）报「连续 N 分钟没有任何工具调用、也没有新内容，已中止」，并附**中止时正在等待哪个工具/等了多久**；界面另有告警 banner（与 `capped` 跑满步数、`aborted` 你点的停止**区分开**） |
+| 一直在等 `task` 子代理 | 进度行/状态条会写出**子代理自己的进度**（第几轮、几次工具调用、最后进展距今多久）；子代理有进展时父回合不会被判无进展，子代理真卡住则由**它自己的**看门狗先中止并把原因回传父回合 |
+| 引擎装不下配置的窗口 | 预检读 `GET /props` 得到引擎自述上下文，与配置并排；配置超出即告警「配置超出引擎能力，长上下文将直接被引擎拒绝」（换预设/调 `contextBudget` 都无效） |
+| 上游 4xx/5xx（模板/内存/鉴权…） | 错误里带**上游原文**并附一条可操作判断（例如"该端点的模板不接受当前 messages 形态"） |
+
+**第 5 步：模型不支持工具调用时会怎样**
+
+若预检判定 **不支持/不稳定**，或整回合 0 次工具调用：回合结束时界面会明确写出
+「⚠ 本回合 0 次工具调用（共 N 轮模型请求 / M 步）：该端点看起来不返回 tool_calls」——
+不会出现"看起来在工作、其实什么都没做"。此时换支持 function calling 的端点，或只把它用于纯问答。
+
 ### 文件访问边界（v0.4.1 P0 路径穿越防护）
 
 read/write/edit/ls/glob/grep/undo 默认限定在**工作目录**内——auto 权限模式下，模型（或被提示注入

package/docs/DEVELOPER.md

@@ -25,7 +25,13 @@
 
 1. `<项目>/.mingdao/presets/<名>.json` — 项目级（随项目走）
 2. `~/.mingdao/presets/<名>.json` — 用户级（本机全局）
-3. `presets/`（随 npm 包分发）— 内置参考（已内置 `local-audit` 示例）
+3. `presets/`（随 npm 包分发）— 内置参考，现内置两个**语义单一**的示例：
+   - `local-model` —— **只放"让本地模型跑得动"的参数**（`contextBudget`/`maxOutputTokens`/`maxRounds`）。
+     本地模型只是替换云模型 API，**功能一致**：所以它不带人格、不限制工具、不建议权限档。
+   - `readonly-audit` —— 审计人格 + 只读工具白名单（`tools`）+ `recommendedPermission: "readonly"`（只是**建议**）。
+   - 老名字 `local-audit` 保留为**别名**（指向 `local-model`）：按老名字调用仍可用，且会打印一次
+     「已更名」提示（CLI/内核日志）并在 WebUI 用 banner 说明——改名兼容，但不静默。
+     若你自己在项目级/用户级写了 `local-audit.json`，**以你的文件为准**（别名只在没找到同名预设时兜底）。
 
 ### 1.2 格式
 
@@ -37,6 +43,7 @@
   "systemPrompt": "你是代码审查员。只读审查，按严重度分级输出，每条带文件:行号证据。",
   "tools": ["read", "ls", "glob", "grep", "skill", "git", "fetch", "todo"],
   "permission": "auto",
+  "recommendedPermission": "readonly",
   "model": "deepseek-v4-flash",
   "temperature": 0.3,
   "maxOutputTokens": 4096,
@@ -49,6 +56,32 @@
 未知字段会**校验报错**（防拼写错误静默失效）。
 `model` 是**建议**：CLI 在未显式 `-m` 时采纳；WebUI 以用户当前选择的模型为准（预设不覆盖）。
 
+`permission` 与 `recommendedPermission` **不是一回事**（v0.6.14 起）：
+
+| 字段 | 语义 | 谁该用 |
+| --- | --- | --- |
+| `permission` | **覆盖**本回合的权限档（仍受反提权规则约束：只能更保守，不能更宽松） | 第三方/老预设；**内置预设不得声明** |
+| `recommendedPermission` | **建议**：只透出给界面/诊断，**不参与判定、不覆盖用户选择** | 内置预设想表达"建议只读"时用它 |
+
+只读的**硬约束**是 `tools` 白名单（不含 `write`/`edit`，模型连写工具都看不到），不是权限档。
+
+#### 参数怎么给"本地模型"用（v0.6.15）
+
+给本地部署模型写预设时，**只调参数、别加人格**——本地模型与云模型功能一致，它需要的是
+"预算合适"，不是"换个角色"：
+
+```json
+{ "name": "my-local", "label": "我的本地模型", "contextBudget": 65536, "maxOutputTokens": 4096, "maxRounds": 4 }
+```
+
+- `contextBudget` 是**最要紧的一个**：本地引擎的 prefill 时间与内存随上下文线性上涨
+  （本机 35B Q4_K_M 实测约 4.9ms/token：2 万 tokens ≈ 1.6 分钟、13 万窗口 ≈ 10 分钟以上，
+  且大上下文会顶满引擎内存预算）。给 32k–65k 通常就够单个模块级任务。
+- 模型窗口/最大输出等**能力声明**请写在 `config.customModels.<模型名>`
+  （`contextWindow`/`maxOutputTokens`/`local`），不要再写一份进预设——两处会漂移。
+- 想让"本地模型 + 只读审计"同时生效：两个预设**不能叠加**（一次只能选一个）。
+  要么用 `readonly-audit` 并自己把 `contextBudget` 调小，要么复制一份按需合并。
+
 ### 1.3 使用
 
 - CLI：`mingdao --preset code-reviewer "审查 src/ 目录"`；交互模式 `mingdao --preset code-reviewer`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/presets/local-model.json

@@ -0,0 +1,8 @@
+{
+  "name": "local-model",
+  "label": "本地模型（保守参数）",
+  "description": "给**本地部署模型**用的保守参数预设。先说清两件事：① 本地模型与云模型**功能一致**——本预设不加人格、不限制工具、不建议权限档，只把「上下文预算 / 单次最大输出 / 轮次」调到本地推理跑得动的量级；② 它**不是**代码审计预设（审计人格与只读工具白名单在另一个预设 readonly-audit 里）。为什么只调这几个数：本地引擎的瓶颈在 prefill 与显存/内存预算（本机实测 35B Q4_K_M：约 4.9ms/token，2 万 tokens 上下文的 prefill ≈ 1.6 分钟，13 万窗口 ≈ 10 分钟以上，还会把引擎的内存预算顶满）——预算给小一点，任务跑得完、也更容易看清是哪一步慢。模型窗口/最大输出等**能力声明**请写在 config.customModels.<模型名>（contextWindow/maxOutputTokens），本预设只覆盖本回合参数。",
+  "contextBudget": 65536,
+  "maxOutputTokens": 4096,
+  "maxRounds": 4
+}

package/presets/readonly-audit.json

@@ -0,0 +1,10 @@
+{
+  "name": "readonly-audit",
+  "label": "只读代码审计",
+  "description": "只读代码审计预设：审计人格 + 只读工具白名单 + 保守参数。三点先说清：① 本预设**不启用审计日志/账本**——那是 config.audit 与 `mingdao ledger`，与本预设无关，别把它当合规审计开关；② 本预设**不覆盖你的权限档**——只读效果由 tools 白名单保证（里面没有 write/edit，模型根本看不到写工具），权限档始终以你的显式选择为准（recommendedPermission=readonly 只是建议，不参与判定）；③ 它**不是**本地模型专用预设——要调本地模型的上下文/输出预算用 local-model（本预设与它相互独立）。",
+  "systemPrompt": "你是一名代码审计员。任务是对给定代码库做只读审计：先 ls/glob 摸清结构，再 read/grep 逐文件审查，可用 git 查看历史与 diff、fetch 抓取相关文档。对于大仓库可分模块派发只读子代理并行审查（task 工具传 readOnly:true，子代理同样只读：read/ls/glob/grep/skill）。输出审计报告：发现的缺陷按严重度分级，每条给出文件:行号证据；不做任何修改。若上下文紧张，先审查最关键的部分并明示未覆盖区域。",
+  "tools": ["read", "ls", "glob", "grep", "skill", "git", "fetch", "todo", "task"],
+  "recommendedPermission": "readonly",
+  "maxRounds": 4,
+  "maxOutputTokens": 4096
+}