mingdao-harness 0.6.2 → 0.6.4

package/docs/PROVIDERS.md

@@ -80,6 +80,28 @@ export async function createProvider(cfg) {
 
 规则：`provider` 名不在内置预设中且存在同名模块文件时，优先加载该模块；否则按 OpenAI 兼容方式使用 `baseUrl`。
 
+### 声明能力（可选，v0.6.3 起）
+
+模块可以**静态声明**能力，内核据此决定界面行为（目前用于图片输入门控）：
+
+```js
+// ~/.mingdao/providers/dify.mjs
+export const supportsVision = true;        // 或 export const capabilities = { vision: true }
+export async function createProvider(cfg) { /* … */ }
+```
+
+- 只读**静态导出**，不调用 `createProvider()`（后者可能有副作用：起进程、建连接）；按文件 mtime 缓存。
+- 声明缺失时该 Provider 视为不支持图片——**门控保守**，不会把图发给看不懂的端点。
+- 为什么需要它：**为了打开图片门控而往 `config.customModels` 里加条目，会改变"请求发给谁"**。
+  自 v0.6.3 起 `customModels` 的条目分两类，只有写了传输字段的才算自定义端点：
+
+  | 条目内容 | 含义 | 效果 |
+  | --- | --- | --- |
+  | 含 `baseUrl` / `apiKey` / `envKey` / `headers` / `path` / `kind` | **声明式端点** | 走 `custom:<模型名>` 的 OpenAI 兼容直连（优先于内置预设，原行为） |
+  | 只含 `vision` / `tokenizer` / `contextWindow` / `maxOutputTokens` / `local` / `provider` | **纯能力覆盖** | **不改变 transport**；`provider` 字段只作路由提示（可指向你的自定义模块） |
+
+  也就是说：「打开一个能力开关」不再改变「请求发给谁」。
+
 ## 模型预设（src/models.js）
 
 每个模型预设定义：`provider` / `contextWindow` / `budgetTokens`（默认注入预算）/ `maxOutputTokens` / `temperature` / `supportsReasoning`。自定义模型名没有预设时使用安全默认值（预算 128k、输出 8k、温度 0.6），都可以在 `config.json` 用 `contextBudget` / `maxOutputTokens` / `temperature` 覆盖。

package/docs/RELEASE-CHECKLIST.md

@@ -266,8 +266,13 @@ git push <mirror> refs/tags/v<版本>:refs/tags/v<版本>
 
 ```bash
 # 采集：用脚本，别再手写 /tmp/harvest-<版本>.sh（手写漏过 mac zip，见 ①）
-#   scp MingDao-Harness-Site/scripts/harvest-release.mjs mingdao-server:/tmp/
-ssh mingdao-server 'MINGDAO_GITHUB_TOKEN=xxx node /tmp/harvest-release.mjs <版本> /opt/1panel/www/sites/mingdao-site/downloads'
+scp MingDao-Harness-Site/scripts/harvest-release.mjs mingdao-server:/tmp/
+# ⚠ token **不要**写进 ssh 的命令串（那等于放进 argv，本地与服务器的 ps 都能读到几小时，
+#   与 §3.22 修掉的是同一个毛病）。经 stdin 落到 umask 077 的临时文件，用完即删：
+umask 077; printf 'MINGDAO_GITHUB_TOKEN=%s\n' "$MINGDAO_GITHUB_TOKEN" > /tmp/hr.env
+ssh mingdao-server 'umask 077; cat > /tmp/harvest.env' < /tmp/hr.env && rm -f /tmp/hr.env
+ssh mingdao-server 'set -a; . /tmp/harvest.env; set +a; rm -f /tmp/harvest.env; \
+  node /tmp/harvest-release.mjs <版本> /opt/1panel/www/sites/mingdao-site/downloads'
 #   · 采安装包 + *.blockmap + latest.yml/latest-linux.yml，跳过 latest-mac.yml 与 builder-debug.yml
 #   · 每个文件按 GitHub 的 sha256(digest) + size 双校验，不符即删并退出非 0
 #   · 末尾会打印「差量更新素材」自查（缺哪个平台的 .blockmap 会直接点名）
@@ -379,6 +384,12 @@ node scripts/verify-release.mjs <版本>  # 四个渠道逐项核对，任一缺
 - [ ] `node scripts/verify-release.mjs <版本>` **退出 0**
 - [ ] 若输出 `⚠ npm/dist-tags.latest` 不是本版本，确认这是有意的回填（否则 latest 需要修正）
 
+> **v0.6.2 发布实测**：该脚本第一次跑报 `✗ GitHub/main 取不到`，第二次即通过——
+> 是一次 `git ls-remote` 的瞬时失败。**一次网络抖动不该在发版收尾时喊狼来了**：
+> 误报会训练人忽略这条告警，而它恰恰是防半发布的最后一道闸。现已加**三次有界重试**，
+> 并把「取不到」（网络/限流）与「读到了但不一样」（真的没推）在输出里区分开。
+> 若仍显示「取不到」，先确认网络与额度再重跑，**不要**跳过这一步。
+
 ### 3.3 Gitee / GitCode 同步发行（含附件）
 
 ```bash

package/package.json

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

package/src/agent.js

@@ -33,6 +33,57 @@ const SUBAGENT_MAX_STEPS = 24;
 // 导致基准测的不是真实只读档。导出后基准与实现共用同一集合。
 export const READONLY_TIER_SET = new Set(['read', 'ls', 'glob', 'grep', 'skill', 'todo', 'git', 'fetch', 'task']);
 
+// ---------------------------------------------------------------------------
+// 写意图 / 疑问句 / 未达成意图的判定（v0.6.3）
+//
+// 这几个判定决定「本回合暴露哪些工具」，因此**放到模块级并导出**：判定错一次，
+// 用户看到的就是"模型说做不到"而完全不知道原因（下游 Deyi-TCM 随访的「回访」正是如此）。
+// ---------------------------------------------------------------------------
+const WRITE_INTENT_RE = /写|建|创|改|修|删|装|加|添|增|补|换|移|部署|执行|运行|实现|重构|生成|迁移|安装|更新|升级|发布|调整|优化|修复|提交|推送|打包|编译|测试|implement|fix|create|modify|update|delete|deploy|build|make|generate|install|write|refactor|migrate|test|run|commit|push|remove|add|change|patch/i;
+const hasWriteIntent = (/** @type {any} */ text) => WRITE_INTENT_RE.test(String(text || ''));
+// v0.6.3（下游 Deyi-TCM 随访实测的上游缺口）：只读档的**判定方向必须反过来**。
+//
+// 原逻辑：命中写意图关键词 → 给全量工具；否则整回合只读（write/edit/bash 对模型**不可见**）。
+// 但域内任务用的是**域内动词/名词**——「回访」「排班」「盘点」「对账」「随访」「归档」……
+// 这是**开集**，永远枚举不完。下游实测：「请生成回访看板」命中"生成"→✅ 能用；
+// 而「回访」不命中任何关键词 → 只读档 → 工具不可见 → ❌ 高频入口直接废掉。
+//
+// 现在改为：**只有"看起来是纯提问、且不含写意图"才进只读档**，其余一律给全量工具。
+// 省 token 的初衷不变（真正的问答仍然是只读档），但默认从"任务态"出发——
+// 少省一点 token 远好过"任务做不了且用户看不出原因"。
+const QUESTION_RE = /[?？]|什么|怎么|怎样|如何|为何|为什么|是否|能否|可否|多少|几个|哪些|哪个|哪里|哪个|谁|何时|吗$|吗[。！!]|呢[。！!]?$/i;
+const QUESTION_RE_EN = /\b(what|how|why|is|are|does|do|can|could|should|when|where|which|who)\b/i;
+const looksLikeQuestion = (/** @type {any} */ text) => {
+  const t = String(text || '').trim();
+  if (!t) return false;
+  return QUESTION_RE.test(t) || QUESTION_RE_EN.test(t);
+};
+// 自愈信号：只读档下模型"想做但做不了 / 要用户来做"时的典型措辞（中英）。
+const UNMET_INTENT_RE = /无法|不能|没法|做不到|没有权限|未提供|需要你|需要先|请先|建议你|请确认|请提供|如需|无法直接|不能直接|请告知|需要我|我可以帮你|unable to|can'?t|cannot|need you|need to know|please confirm|please provide/i;
+const looksLikeUnmetIntent = (/** @type {any} */ text) => UNMET_INTENT_RE.test(String(text || ''));
+
+/**
+ * 本回合是否从「只读档」起步。
+ *
+ * **判定方向是故意反的**：原实现要命中写意图关键词才给全量工具，而域内任务用的是
+ * **开集**动词/名词——「回访」「排班」「盘点」「对账」……永远枚举不完。下游实测：
+ * 「请生成回访看板」命中"生成"→能用；「回访」不命中→只读档→write/edit/bash 不可见→废掉。
+ * 现在只有"看起来是纯提问且不含写意图"才进只读档（真正的问答照样省 token），其余一律全量。
+ *
+ * 另外两条防线（都写在这里，保证判定只有一处）：
+ *   · **域内 Pack 在场时不进只读档**：这类部署的价值在"任务能做"，不在省 schema token；
+ *   · 只读档若以纯文本收尾且透出"做不到/需要…"，`runTurn` 会**自愈**放开一次（与词表无关）。
+ *
+ * @param {any} cfg @param {any} lastUserText @param {boolean} packActive
+ * @returns {boolean}
+ */
+export function startsInReadOnlyPhase(cfg, lastUserText, packActive) {
+  if (cfg?.schemaTier === false) return false;
+  if (packActive) return false;
+  const t = lastUserText;
+  return !hasWriteIntent(t) && looksLikeQuestion(t);
+}
+
 /**
  * 创建 Agent 循环（调用方只需传 provider/permission/io/modelName/workingDir，其余可选）
  * @param {{ provider: any, permission: any, io: any, modelName: any, workingDir: any,
@@ -121,8 +172,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   // （readOnly 子代理只读，权限引擎仍门控写操作，无越权）。
   // 只读档工具集：单一来源见模块顶部导出的 READONLY_TIER_SET
   // 中英双语写意图（CodeArts 报告：纯中文正则让英文会话整回合只读死锁）
-  const WRITE_INTENT_RE = /写|建|创|改|修|删|装|加|添|增|补|换|移|部署|执行|运行|实现|重构|生成|迁移|安装|更新|升级|发布|调整|优化|修复|提交|推送|打包|编译|测试|implement|fix|create|modify|update|delete|deploy|build|make|generate|install|write|refactor|migrate|test|run|commit|push|remove|add|change|patch/i;
-  const hasWriteIntent = (/** @type {any} */ text) => WRITE_INTENT_RE.test(String(text || ''));
+
   // A1（前缀稳定）：剥描述集合按「回合冻结快照」——回合内恒定（至多两态：只读档/全量档），
   // 新使用的工具只在下一回合才进入剥描述集合；回合边界本身就有新 user 消息，schema 变化免费。
   // v0.4.0 Agent Preset：cfg.presetTools 白名单恒生效（在只读档过滤之后收紧——预设只减不增）。
@@ -330,6 +380,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   async function runTurn(/** @type {any} */ messages) {
     let steps = 0;
     let finish = null;
+    /** v0.6.3（M-16）：本回合是否出现过"上游提前关流"（回答可能不完整）。
+     * 刻意不叫 truncated——既有 `truncated` 的含义是"步数兜底总结也失败了"，两者必须分开。 */
+    let upstreamTruncated = false;
     // v0.3.1 自动续跑（长程执行）：跑满 stepLimit 步后不再直接中断，而是注入进度摘要再续跑，
     // 最多 maxRounds 轮（默认 3，可用 cfg.maxRounds 调）；审计/重构等大任务不再「一步中断」。
     const maxRounds = Math.max(1, Number(cfg.maxRounds) || 3);
@@ -401,11 +454,14 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     // 省钱 B1：本回合只读阶段判定——最新用户消息无写意图则先只发只读工具，
     // 模型明确表达写意图后（下一轮）注入全量。cfg.schemaTier=false 可关。
     let readOnlyPhase = true;
-    if (cfg.schemaTier !== false) {
+    // 自愈只允许一次（否则与 stepLimit 形成"放开→再收起"的循环）
+    let readOnlyHealed = false;
+    {
       const lastUser = [...messages].reverse().find((m) => m?.role === 'user');
-      readOnlyPhase = !hasWriteIntent(lastUser?.content);
-    } else {
-      readOnlyPhase = false;
+      // 域内 Pack 在场时**不进只读档**（域内词是开集，靠关键词判定必然漏）
+      const packCtx0 = getActivePackContext();
+      const packActive = Array.isArray(packCtx0?.mounted) && packCtx0.mounted.length > 0;
+      readOnlyPhase = startsInReadOnlyPhase(cfg, String(lastUser?.content ?? ''), packActive);
     }
     // A1：本回合的剥描述冻结快照（会话级 usedToolNames 的副本）——回合内 schema 字节不变
     const turnStrippedSet = new Set(usedToolNames);
@@ -535,6 +591,11 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
               windowPressure = false;
               pressureWarned = false;
             }
+            // v0.6.3（M-1）：压缩把早期消息（含文件正文）换成了摘要，但**读取去重缓存**还记着
+            // "这个文件你看过（mtime+size 未变）"——模型随后再读同一文件只会拿到「内容与上次读取一致」
+            // 的占位串，而正文已经不在上下文里了，于是它可能凭残缺信息继续改文件。
+            // 压缩是"上下文被替换"的事件，缓存必须跟着失效（代价只是重新读一次文件）。
+            agentReadCache.clear();
             try {
               onCompact?.(messages);
             } catch {}
@@ -708,6 +769,15 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       }
 
       finish = res.finish ?? finish;
+      // v0.6.3（M-16）：上游**提前关流**（没有 [DONE]、也没有 finish_reason）说明这次回答很可能是半截的。
+      // 此前它与正常结束完全无法区分：用户拿到半句、账本记 done、也没有任何告警。
+      // 这里至少做到"说出来"——置标记并在界面上提示，让人知道该复核输出而不是直接采信。
+      if (res.truncated) {
+        upstreamTruncated = true;
+        try {
+          io.print(style('⚠ 上游提前结束响应（未收到结束标记），本次回答可能不完整——请复核输出后再采用。', C.yellow));
+        } catch {}
+      }
       // v0.6.0 C1：模型轮次事件（耗时/首 token/用量/完成原因）——「这一步花了多少钱、等了多久」的最小依据
       turnLedger.modelRound({
         round,
@@ -716,6 +786,8 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         firstTokenMs: firstTokenAt ? firstTokenAt - llmT0 : null,
         requestStartAt: lastRequestStartAt,
         finish: res.finish ?? null,
+        // 提前关流是"这次回答不可信"的事实，必须进账本（否则事后无法区分它和正常完成）
+        ...(res.truncated ? { truncated: true } : {}),
         usage: res.usage ?? null,
       });
       // 省钱 B1：只读阶段中模型文字明确表达写意图 → 下一轮注入全量工具（多一轮，几乎无感）
@@ -750,7 +822,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           if (res.text) {
             const ap = await applyOutputConstraints(res.text, { messages, provider, activeModel, temperature, maxOutput, usage, signal: currentAc?.signal });
             messages.push({ role: 'assistant', content: ap.text });
-            return { text: ap.text, reasoning: res.reasoning || '', usage, steps, finish, truncated: false, aborted: false, note: ap.note || undefined, durationMs: Date.now() - startedAt, perf: perf() };
+            return { text: ap.text, reasoning: res.reasoning || '', usage, steps, finish, truncated: false, aborted: false, upstreamTruncated, note: ap.note || undefined, durationMs: Date.now() - startedAt, perf: perf() };
           }
           break;
         }
@@ -851,6 +923,25 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           // v0.5.0 A3 ①：领域约束（PreToolUse）——权限放行之后、执行之前强制。
           // 与权限引擎的分工：权限回答「用户是否允许」，约束回答「领域是否允许」；两者都通过才执行。
           const cv = checkPreTool(constraints, name, args);
+          // v0.6.3（P1-2）：confirm 类约束——权限放行之后**仍要人工确认**。
+          // 它存在的意义正是「权限档位是 auto 时也要问一次」；拿不到确认通道（非交互：
+          // -p / 调度 / 子 Agent）或用户答否，一律按阻断处理，与权限引擎在同一情形下的
+          // 「按拒绝处理」保持同一口径（fail-closed，见下方 permission.check 的 catch）。
+          let confirmFailure = /** @type {string|null} */ (null);
+          if (cv?.needsConfirm) {
+            let granted = false;
+            try {
+              granted = await io.confirm(`【领域约束】${cv.reason}。是否继续执行？(y/N)`);
+            } catch {
+              granted = false;
+            }
+            if (granted) {
+              if (auditOn) auditEntry({ confirmRequired: true, granted: true, reason: cv.reason });
+              turnLedger.permission({ name, mode: permission?.mode ?? cfg.permission ?? null, decision: 'confirm-granted', source: 'constraint.confirm', rule: cv.event?.id ?? null });
+            } else {
+              confirmFailure = `领域约束「${cv.event?.id ?? ''}」要求人工确认，未获确认（拒绝或当前环境无法交互）——已按 fail-closed 阻止执行`;
+            }
+          }
           // v0.6.0 C1：工具调用事件——参数留「脱敏明细 + 原文指纹」两份，指纹用于比对/防篡改；
           // 权限与约束**两者都记**：受监管场景要能回答「权限放行了，但领域红线拦住了」这类问题。
           turnLedger.toolCall({
@@ -860,15 +951,16 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             rawArgs: args,
             args,
             permission: { decision: 'allow', source: 'permission.check' },
-            constraint: cv?.blocked ? { blocked: true, id: cv.event?.id ?? null, kind: cv.event?.kind ?? null } : null,
+            constraint: cv?.blocked || confirmFailure ? { blocked: true, id: cv?.event?.id ?? null, kind: cv?.event?.kind ?? null } : null,
           });
-          if (cv?.blocked) {
-            io.renderToolDenied(name, args, cv.reason);
-            if (auditOn) auditEntry({ denied: true, reason: cv.reason });
-            auditConstraint(cv.event);
+          if (cv?.blocked || confirmFailure) {
+            const reason = confirmFailure ?? cv?.reason ?? '领域约束拦截';
+            io.renderToolDenied(name, args, reason);
+            if (auditOn) auditEntry({ denied: true, reason });
+            if (cv?.event) auditConstraint(cv.event);
             // 被约束拦下的调用不会有 tool.result，这里补一条终态，避免账本出现「只有调用没有结果」的悬空步
             turnLedger.toolResult({ callId: tc.id, name, ok: false, blocked: true, ms: 0, error: '领域约束拦截' });
-            messages.push({ role: 'tool', tool_call_id: tc.id, content: `【领域约束】${cv.reason}` });
+            messages.push({ role: 'tool', tool_call_id: tc.id, content: `【领域约束】${reason}` });
             return null;
           }
           return { tc, name, args, isMcp };
@@ -1100,6 +1192,23 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           });
           continue;
         }
+        // v0.6.3 自愈：只读档下 write/edit/bash 不可见，域内任务只会收到一段
+        // "我做不到/需要你提供…"的文字，而**根本不会进第二轮**——原释放条件
+        // （模型文字里出现写意图）因此永远等不到。这里补一条与词表无关的兜底。
+        if (readOnlyPhase && !readOnlyHealed && looksLikeUnmetIntent(finalText)) {
+          readOnlyHealed = true;
+          readOnlyPhase = false;
+          try {
+            io.print(style('⚠ 上一轮处于只读档、未暴露写入类工具；已放开工具集并重试一次', C.dim));
+          } catch {}
+          messages.push({
+            role: 'user',
+            content:
+              '（系统提示）你上一轮可能因为没有可用的写入/执行工具而未能完成任务。' +
+              '现在工具集已放开：如果用户的要求需要写文件或执行命令，**请直接调用相应工具去做**，不要只描述计划或让用户自己完成。',
+          });
+          continue;
+        }
         return {
           text: finalText,
           reasoning: res.reasoning || '',
@@ -1239,10 +1348,16 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       if (turnLedger) {
         try {
           const costDate = lastRequestStartAt ? new Date(lastRequestStartAt) : new Date();
-          const yuan = estimateCost(modelName, usage.prompt_tokens, usage.completion_tokens, cacheSplit(usage), costDate);
+          // v0.6.3（BUG-024）：计价必须用**本回合实际使用**的模型。
+          // 此前用 modelName（用户配置的模型），而成本护栏降级后请求实际发给 activeModel——
+          // 两者单价不同（flash 便宜数倍），于是账本与日费用护栏系统性偏移，
+          // 而"降级省钱"恰恰是靠这里体现的。
+          const yuan = estimateCost(activeModel, usage.prompt_tokens, usage.completion_tokens, cacheSplit(usage), costDate);
           const priced = typeof yuan === 'number' && Number.isFinite(yuan);
           turnLedger.cost({
-            model: modelName,
+            // BUG-024：归属同样要用实际计费的模型（run.start 里已记过"用户请求的模型"，
+            // 这里再写 modelName 会让"花了钱的那次调用"归属到一个没被调用的模型）
+            model: activeModel,
             usage,
             yuan: priced ? yuan : null,
             priced,
@@ -1298,5 +1413,8 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     runTurn,
     spawnTask: (/** @type {any} */ prompt, /** @type {any} */ opts) => spawnTask(prompt, opts),
     getTodos: () => todos.slice(),
+    // v0.6.3（M-1）：凡是"上下文被整体替换"的地方（/compact、/clear、手动重写历史）都要能
+    // 让读取去重缓存一起失效，否则模型会被"你已读过"的占位串误导。
+    clearReadCache: () => agentReadCache.clear(),
   };
 }