mingdao-harness 0.2.6 → 0.2.8

package/docs/CONFIG.md

@@ -57,9 +57,9 @@ MingDao 先用 executor 模型（路由关闭时为当前模型）把被裁段
 ## 会话检索索引（P3-2）
 
 `mingdao sessions search <关键词>` 与 WebUI 历史会话搜索走增量词表索引
-（`~/.mingdao/sessions-index.json`）：中文按 bigram+单字、英文按词，多词 AND 匹配；
-只有内容变化（mtime/size）的会话才重新分词，删除的会话自动清出索引。索引文件可随时
-删除（下次搜索自动重建）。
+（`~/.mingdao/sessions-index/` 分片目录，v0.2.8 起按会话名 sha1 前 2 位分 256 片）：
+中文按 bigram+单字、英文按词，多词 AND 匹配；只有内容变化（mtime/size）的会话才重新
+分词，删除的会话自动清出索引。索引目录可随时删除（下次搜索自动重建）。
 
 ## 会话级工作空间（P3-4）
 
@@ -169,7 +169,7 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 { "costGuard": { "dailyLimitYuan": 10, "warnAtYuan": 8, "action": "block" } }
 ```
 
-- `action: "warn"`（默认）超限仅提醒；`"block"` 到达上限暂停执行（明天自动恢复）；
+- `action: "warn"`（默认）超限仅提醒；`"block"` 到达上限暂停执行（明天自动恢复）；`"downgrade"` 触顶后自动切换到同服务商更便宜模型（如 flash）继续执行并提示（已是 flash 则按 block 处理）；
 - `/cost` 与 WebUI 头部费用徽标实时显示「今日费用 / 上限百分比」。
 
 ## 战略省钱：Batch 半价 + 避峰调度
@@ -182,7 +182,7 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
   ——高峰时段（北京时间工作日 9:00–12:00、14:00–18:00 两段）自动顺延到最近闲时（12:00 / 18:00）执行；**周末与午间 12:00–14:00 按闲时计价**
   · `pricing.peakWindows`：高峰窗口覆盖（[[起,止],...] 北京时间整点）；`pricing.timezone`：计价时区
   · `pricing.source`：官方价格 JSON 地址（`mingdao update --pricing` 拉取，TTL 默认 7 天，`pricing.ttlDays` 可调）；`pricing.overrides`：按模型覆盖价格
-  · `reasoningEffort`：思考强度 low/high/max（默认模型内置 high；REPL `/think` 切换）
+  · `reasoningByModel`：思考强度按模型独立覆盖，`{ "deepseek-v4-pro": "low" }`（`off`/`low`/`high`/`max`，默认模型内置 high；`off` 显式关闭思考省推理 token；REPL `/think` 或 WebUI 设置「模型与密钥」→ 思考模式开关 + 推理等级）；旧版全局 `reasoningEffort` 仍兼容，优先级低于 `reasoningByModel`
   · `routing.upgradeSteps` / `routing.upgradeTruncated`：粘滞 flash 会话累计步数/截断超过阈值自动升 planner（默认 10 / 2）
   （DeepSeek 官方邮件确认），不触发避峰等待。WebUI 调度面板勾选「🌙 避峰执行」。
 

package/docs/QA-REPORT.md

@@ -5,6 +5,8 @@
 > 版本：0.1.54（历史归档；现行 0.1.x 口径见根 README 与各版本 tag。纯 ESM，零 npm 依赖，Node.js ≥ 18.17）
 > 质检方式：全量源码走读 + 冒烟/端到端测试 + 针对性缺陷验证脚本
 
+> **当前测试规模快照（v0.2.8，随版本持续增长）**：smoke **61 组** · e2e-local **16 项** · e2e-web **21 项** · e2e-schedule **8 项** · api-contracts **8 项** · bench **194 条断言**（tokenizer 16 + routing 118 + compaction 46 + cost 14）。下文 2026-08-18 的「14 组断言」为当时历史口径，已过时——以本快照为准。
+
 ---
 
 ## 一、总体评价

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {
@@ -49,7 +49,7 @@
   "scripts": {
     "start": "node src/cli.js",
     "test": "node test/run-all.mjs",
-    "typecheck": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.full.json",
     "prepublishOnly": "node test/smoke.js && node test/e2e-local.js && node test/e2e-schedule.js",
     "desktop": "npm --prefix desktop start",
     "desktop:dist": "node scripts/sync-versions.mjs && npm --prefix desktop run dist:dir",

package/skills/release-checklist/SKILL.md

@@ -11,13 +11,14 @@ description: 准备发布新版本、打包交付前使用
 2. **版本**：版本号统一（package.json / 配置 / 文档互相一致），遵循语义化版本。
 3. **变更说明**：changelog 用用户语言描述新增/修复/破坏性变更。
 4. **构建验证**：实际构建/打包一次，并在干净环境验证产物可安装可运行。
-5. **桌面版打包冒烟（0.2.2 事故护栏，发版必经）**：主进程模块求值必须真实跑通打包产物——
+5. **发布前自检（常设步骤，2026-09-02 起）**：不依赖外部评估报告，纯代码审查主动找 bug——重点覆盖本次改动的调用链、锁/并发、权限/安全、跨平台与「打包期无声、运行期爆炸」类边界；每一条发现必须给出**文件+行号证据并按严重度排序**（高危优先修，不可带着已知高危发布）。历史战例：v0.2.6 自检一次捞出 6 条（含外部六份评估全漏的 `schedule stop` 双守护进程 bug）与 2 条自改回归。
+6. **桌面版打包冒烟（0.2.2 事故护栏，发版必经）**：主进程模块求值必须真实跑通打包产物——
    - CI 已内置：desktop.yml 在 Linux 腿用 xvfb 运行 `dist/linux-unpacked/mingdao --no-sandbox`（`MINGDAO_DESKTOP_SMOKE=1`），模块求值通过输出 `MINGDAO_DESKTOP_SMOKE_OK` 并退出 0，否则 workflow 失败；
    - 本地有显示器时可加验：`cd desktop && MINGDAO_DESKTOP_SMOKE=1 dist/linux-unpacked/mingdao --no-sandbox`（AppImage 加 `--appimage-extract-and-run`）；
    - 教训：0.2.2 三平台启动即崩（main.js 顶层调用 createLogWriter 漏导入），打包期不报错、运行期才炸——静态护栏（test/smoke.js「桌面主进程静态护栏」组）与打包冒烟双保险。
-6. **敏感信息**：密钥、token、内网地址、个人信息不得进入仓库与产物（`grep -rE 'sk-[A-Za-z0-9]{20,}' .`）。
-7. **回滚方案**：明确如何回退到上一版本（旧包/旧 tag 可恢复）。
-8. **发布后冒烟**：发布完成后立即做一次端到端验证。
+7. **敏感信息**：密钥、token、内网地址、个人信息不得进入仓库与产物（`grep -rE 'sk-[A-Za-z0-9]{20,}' .`）。
+8. **回滚方案**：明确如何回退到上一版本（旧包/旧 tag 可恢复）。
+9. **发布后冒烟**：发布完成后立即做一次端到端验证。
 
 ## 桌面版发布流水线（官网分发 + 镜像 + 转运附件回收）
 

package/src/agent.js

@@ -28,7 +28,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   const budget = cfg.contextBudget || preset.budgetTokens || 128000;
   const maxOutput = cfg.maxOutputTokens || preset.maxOutputTokens || 8192;
   const temperature = cfg.temperature ?? preset.temperature ?? 0.6;
-  const reasoningEffort = cfg.reasoningEffort ?? preset.reasoningEffort?.default ?? undefined;
+  const reasoningEffort = cfg.reasoningByModel?.[modelName] ?? cfg.reasoningEffort ?? preset.reasoningEffort?.default ?? undefined;
   const hooks = createHooks(cfg.hooks, workingDir);
   const todos = /** @type {any[]} */ ([]);
   // 会话级共享：调用方传入则复用（/model 切换、子代理均共享，undo 不丢失）
@@ -359,6 +359,16 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       }
 
       if (res.toolCalls?.length) {
+        // v0.2.8 步数上限收尾（对齐 DSH）：末轮仍返回工具调用（无视收尾指令）时不再执行工具——
+        // 有正文直接收尾，无正文跳出循环进入兜底总结，避免再次跑满步数后静默结束。
+        if (steps === stepLimit) {
+          io.endTurn();
+          if (res.text) {
+            messages.push({ role: 'assistant', content: res.text });
+            return { text: res.text, reasoning: res.reasoning || '', usage, steps, finish, truncated: false, aborted: false, durationMs: Date.now() - startedAt, perf: perf() };
+          }
+          break;
+        }
         io.endTurn();
         const assistantMsg = {
           role: 'assistant',
@@ -553,6 +563,15 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             }
           }
         }
+        // v0.2.8 步数预留收尾（对齐 DSH）：仅剩最后一轮时，工具结果回填后追加收尾指令，
+        // 让模型在末轮输出「总结文字 + 交付物清单」，而非跑满步数后静默结束。
+        if (steps === stepLimit - 1) {
+          messages.push({
+            role: 'user',
+            content:
+              '（系统提示）已达到工具调用步数上限，请停止调用工具，直接输出最终总结：① 已完成的工作；② 交付物清单（文件路径）；③ 遗留问题与后续建议。',
+          });
+        }
       } else {
         io.endTurn();
         // 最终纯文本回复回填消息历史（会话持久化与多轮上下文依赖它）；
@@ -626,6 +645,38 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     io.endTurn();
     // 步数上限：清掉未执行的 tool_calls，避免下一轮/恢复后 API 400
     stripOrphanCalls();
+    // v0.2.8 兜底总结（对齐 DSH）：跑满步数/末轮无正文且未中断时，补一次 no-tool 小输出请求，
+    // 让任务以「总结文字 + 交付物清单」收尾，而非静默结束；失败则回退旧行为（text:null）。
+    if (!aborted && messages.length) {
+      try {
+        // stripOrphanCalls 残留的空 assistant（无 tool_calls 且 content 为空）回传会触发 API 400，先清掉
+        const lastMsg = messages[messages.length - 1];
+        if (lastMsg.role === 'assistant' && !lastMsg.content && !Array.isArray(lastMsg.tool_calls)) messages.pop();
+        const wrapReq = [
+          ...trimMessages(messages, budget, count),
+          { role: 'user', content: '（系统提示）任务已执行完毕。请用一段话总结刚才完成的工作，列出交付物（文件路径），并说明遗留问题与后续建议。' },
+        ];
+        currentAc = new AbortController();
+        const wrapRes = await provider.chat({
+          model: activeModel,
+          messages: wrapReq,
+          tools: [],
+          temperature,
+          maxTokens: Math.min(maxOutput, 2048),
+          reasoningEffort: modelPreset(activeModel)?.supportsReasoning ? 'low' : undefined,
+          signal: currentAc.signal,
+          onDelta(/** @type {any} */ d) {
+            if (d.text) io.writeText(d.text);
+          },
+        });
+        if (wrapRes.usage) {
+          usage.prompt_tokens += wrapRes.usage.prompt_tokens || 0;
+          usage.completion_tokens += wrapRes.usage.completion_tokens || 0;
+        }
+        if (wrapRes.text) messages.push({ role: 'assistant', content: wrapRes.text });
+        return { text: wrapRes.text || null, reasoning: wrapRes.reasoning || '', usage, steps, finish, truncated: false, aborted: false, durationMs: Date.now() - startedAt, perf: perf() };
+      } catch {}
+    }
     return { text: null, reasoning: '', usage, steps, finish, truncated: true, aborted: false, durationMs: Date.now() - startedAt, perf: perf() };
     } finally {
       currentAc = null;

package/src/cli.js

@@ -257,8 +257,16 @@ async function main() {
     const { readTask } = await import('./tasks.js');
     const handled = new Set();
     const supervising = new Set(); // 本 daemon 正在监督的任务（防崩溃恢复误判正在执行的任务）
+    const nonce = String(opts.prompt[1] || '');
     try {
       for (;;) {
+        // 守护进程租约自检（2026-09-03，防双 daemon）：pidfile 不再等于「我的 pid nonce」
+        // 即视为已被 stop 或已被新 daemon 取代——立即退出，绝不与新 daemon 并跑重复执行任务
+        try {
+          if (fs.readFileSync(daemonPidFile(home0), 'utf8').trim() !== `${process.pid} ${nonce}`) break;
+        } catch {
+          break; // pidfile 被删 = 已被 stop
+        }
         const jobs = listSchedules(home0);
         if (!jobs.some((j) => j.status === 'pending' || j.status === 'running')) break;
         for (const j of jobs) {
@@ -295,8 +303,12 @@ async function main() {
         await new Promise((r) => setTimeout(r, 2000));
       }
     } finally {
+      // 只删除「仍指向自己」的 pidfile：租约被改写/被新 daemon 取代而退出时，
+      // 绝不误删新 daemon 的 pidfile（否则新 daemon 下一次租约检查会连锁退出，双守护全灭）
       try {
-        fs.rmSync(daemonPidFile(home0), { force: true });
+        if (fs.readFileSync(daemonPidFile(home0), 'utf8').trim() === `${process.pid} ${nonce}`) {
+          fs.rmSync(daemonPidFile(home0), { force: true });
+        }
       } catch {}
     }
     return;
@@ -368,11 +380,14 @@ async function main() {
     },
   };
   if (cfg.mcpServers && Object.keys(cfg.mcpServers).length) {
-    // A2：预热——await 连接（6s 超时）；超时本会话冻结工具集（不再中途注入，保护前缀缓存）
+    // A2：预热——await 连接（6s 超时）；超时本会话冻结工具集（不再中途注入，保护前缀缓存）。
+    // 超时后输家 promise 仍在跑：迟到就绪的 manager 立即 stop，防 detached 子进程成孤儿（自查 #2）
+    const mcpStartP = startMcpServers(cfg.mcpServers, workingDir).catch(() => null);
     mcpManager = await Promise.race([
-      startMcpServers(cfg.mcpServers, workingDir).catch(() => null),
+      mcpStartP,
       new Promise((/** @type {any} */ r) => setTimeout(() => r(null), 6000)),
     ]);
+    if (!mcpManager) mcpStartP.then((/** @type {any} */ m) => { if (m) m.stop(); });
     if (mcpManager) {
       const ready = mcpManager.status().filter((/** @type {any} */ s) => s.ok).length;
       if (io && !opts.prompt.length) {

package/src/commands/repl.js

@@ -318,13 +318,16 @@ export async function runRepl(ctx) {
         await switchToModel(target);
       } else if (cmd === '/think') {
         const vals = ['low', 'high', 'max'];
+        const cur = cfg.reasoningByModel?.[modelName] ?? cfg.reasoningEffort ?? '跟随模型默认';
         if (!arg) {
-          io.print(`用法：/think low|high|max|off（当前：${cfg.reasoningEffort || '跟随模型默认 high'}）`);
+          io.print(`用法：/think low|high|max|off（当前：${cur}）`);
           continue;
         }
-        if (arg === 'off') cfg.reasoningEffort = 'off'; // 显式禁用（provider 转 thinking:{type:'disabled'}）
-        else if (vals.includes(arg)) cfg.reasoningEffort = arg;
-        else { io.print(style('无效取值：low|high|max|off', C.red)); continue; }
+        if (arg === 'off' || vals.includes(arg)) {
+          cfg.reasoningByModel = cfg.reasoningByModel || {};
+          cfg.reasoningByModel[modelName] = arg; // 按模型独立：只改当前模型（off 转 thinking:{type:'disabled'}）
+          saveConfig(cfg);
+        } else { io.print(style('无效取值：low|high|max|off', C.red)); continue; }
         agent = createAgent({
           provider, permission, io, modelName, workingDir, cfg,
           undoStore: sessionUndoStore, mcp: mcpFacade, sessionRef,
@@ -333,7 +336,7 @@ export async function runRepl(ctx) {
             tuiState.persisted = msgs.length;
           },
         });
-        io.print(style(`✓ 思考强度：${cfg.reasoningEffort || 'off（模型默认）'}`, C.green));
+        io.print(style(`✓ 思考强度（${modelName}）：${cfg.reasoningByModel[modelName]}`, C.green));
       } else if (cmd === '/plan') {
         planMode = !planMode;
         io.print(style(`✓ 计划模式：${planMode ? '开' : '关'}${planMode ? '（先出计划，确认后执行）' : ''}`, C.green));

package/src/log-writer.js

@@ -9,7 +9,9 @@ export function createLogWriter(/** @type {string} */ file, { maxBytes = 512 * 1
     try {
       fs.mkdirSync(path.dirname(file), { recursive: true });
       const line = new Date().toISOString() + ' ' + String(msg) + '\n';
-      fs.appendFileSync(file, line);
+      // 自查 #5：日志可能含工具参数等敏感信息——创建与轮转一律 600（多用户机器防同机读取）
+      if (!fs.existsSync(file)) fs.appendFileSync(file, line, { mode: 0o600 });
+      else fs.appendFileSync(file, line);
       const st = fs.statSync(file);
       if (st.size > maxBytes) {
         const raw = fs.readFileSync(file, 'utf8');
@@ -17,8 +19,9 @@ export function createLogWriter(/** @type {string} */ file, { maxBytes = 512 * 1
         const nl = raw.indexOf('\n', cut);
         const keep = nl === -1 ? raw.slice(cut) : raw.slice(nl + 1); // 行对齐保留尾部
         const tmp = file + '.' + process.pid + '.' + crypto.randomBytes(3).toString('hex') + '.tmp';
-        fs.writeFileSync(tmp, keep);
+        fs.writeFileSync(tmp, keep, { mode: 0o600 }); // 轮转重建保持 600
         fs.renameSync(tmp, file);
+        try { fs.chmodSync(file, 0o600); } catch {} // rename 后兜底收权（历史 644 日志迁移）
       }
     } catch {
       // 日志失败绝不抛错（best-effort）

package/src/pricing.js

@@ -42,9 +42,18 @@ export function pricingDataStale() { return externalPricing().stale; }
 export async function refreshPricingFromSource(cfg) {
   const src = String(cfg?.pricing?.source || '').trim();
   if (!src) return { ok: false, lines: ['未配置 pricing.source（config.json 的 pricing.source 填官方价格 JSON 地址后重试）'] };
+  // 自查 #4：与 sync/自定义模型同类的第三外联入口——协议白名单 + 响应大小上限（防误配/恶意源灌内存）
+  try {
+    const u = new URL(src);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, lines: ['价格源仅支持 http/https 地址'] };
+  } catch {
+    return { ok: false, lines: ['价格源必须是合法的 http(s) URL'] };
+  }
   const res = await fetch(src, { signal: AbortSignal.timeout(15000) });
   if (!res.ok) return { ok: false, lines: ['价格源请求失败：HTTP ' + res.status] };
-  const d = await res.json();
+  const buf = await res.arrayBuffer();
+  if (buf.byteLength > 512 * 1024) return { ok: false, lines: ['价格源响应超过 512KB 上限，已拒绝'] };
+  const d = JSON.parse(Buffer.from(buf).toString('utf8'));
   const models = d && typeof d === 'object' && !Array.isArray(d) ? /** @type {any} */ (d).models : null;
   if (!models || typeof models !== 'object' || Array.isArray(models)) {
     return { ok: false, lines: ['价格源格式不符：应为 {"models": {"模型名": {"input":…,"output":…,"cacheHit":…,"peak":{…}}}}'] };

package/src/prompts.js

@@ -14,7 +14,7 @@ const BASE = `你是 MingDao Harness，一个由 MingDao Harness 驱动的 AI
 2. 精准修改：优先用 edit 做小步精确替换；新建文件用 write；保持改动最小化；改错可用 undo 撤销。
 3. 大内容分批写：单个 write 的参数总长控制在 6000 字符以内；大文件先写核心骨架，再分多次 write/edit 逐步补充——单次输出超限会被截断并导致参数解析失败。
 4. 任务管理：多步骤任务先建 todo 清单并逐项更新；与技能（skill）相关的任务先加载对应 SKILL.md。
-5. 委托与专注：独立、可并行的子问题（调研、复核、独立实现）用 task 委托子代理，把结果拿回来继续主线。
+5. 委托与专注：把「互不依赖、可并行」的子问题（同时调研多个方向、复核多份文件、独立实现多模块）用 task 委托子代理；多个只读调研子代理应在同一轮一起派发（readOnly=true，自动并行，效率最高）；依赖当前对话细节的小改动自己做，不要委托。子代理返回后拿结果继续主线。
 6. 命令谨慎：执行 bash 前想清楚影响；命令失败时阅读错误输出并修复，同一问题最多重试 3 次。
 7. 回答风格：使用用户的语言（默认中文），简洁直接，先结论后说明。
 8. 诚实可靠：不编造不存在的文件、行号、API 或执行结果。

package/src/schedule.js

@@ -293,7 +293,9 @@ export function daemonAlive(/** @type {any} */ home) {
 }
 export function stopDaemon(/** @type {any} */ home) {
   try {
-    const pid = Number(fs.readFileSync(daemonPidFile(home), 'utf8'));
+    // pidfile 格式 "<pid> <nonce>"——必须取首段（此前整串 Number()=NaN，SIGTERM 永远不发，
+    // 只删 pidfile → 孤儿 daemon 继续跑，新 daemon 再被拉起 → 双守护重复执行任务）
+    const pid = Number(String(fs.readFileSync(daemonPidFile(home), 'utf8')).trim().split(/\s+/)[0]);
     if (pid) {
       try {
         process.kill(pid, 'SIGTERM');

package/src/session-index.js

@@ -1,36 +1,71 @@
 // 会话检索索引（P3-2）：词表倒排 + 增量同步，替代每次全量扫描全部会话文件。
-// 索引文件 <mingdao-home>/sessions-index.json：
-//   { files: { "<会话名>": { mtime, size, terms: {词: 次数} } } }
+// 索引分片存储（v0.2.8 B1）：<mingdao-home>/sessions-index/<2位sha1前缀>.json ——
+//   每片 { files: { "<会话名>": { mtime, size, terms: {词: 次数} } } }
+// 分片收益：>1000 会话时不再单次 JSON.parse/stringify 一个巨型索引文件；
+//   同步只重写「变脏」的分片，读/写放大与内存峰值都大幅下降（256 片，每片 ~4 个会话）。
 // 同步策略：查询前对每个会话文件做 mtime/size 对比——未变化直接用缓存词表（O(词表)），
 // 变化/新增才重新分词（增量）；已删除文件自动清理；>8MB 超大文件跳过并移除条目。
 // 分词：英文/数字/路径按词（小写），中文按 bigram + 单字，查询串同口径分词后按 AND 匹配。
 
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { mingdaoHome, ensureHome } from './config.js';
 import { atomicWriteFileSync } from './atomic-write.js';
 
 const INDEX_MAX_FILE = 8 * 1024 * 1024;
+const SHARD_HEX = 2; // sha1 前 2 个十六进制位 → 256 片
 
-export function sessionIndexFile() {
-  return path.join(mingdaoHome(), 'sessions-index.json');
+/** 分片目录（索引分片统一存放于此） */
+export function shardDir() {
+  return path.join(mingdaoHome(), 'sessions-index');
 }
 
-export function loadSessionIndex() {
+/** 会话名 → 分片名（sha1 前 2 位，稳定且均匀） */
+/** @param {any} name */
+export function shardOf(name) {
+  return crypto.createHash('sha1').update(String(name)).digest('hex').slice(0, SHARD_HEX);
+}
+
+/** @param {any} shard */
+function shardFile(shard) {
+  return path.join(shardDir(), `${shard}.json`);
+}
+
+/** @param {any} shard */
+function loadShard(shard) {
   try {
-    const j = JSON.parse(fs.readFileSync(sessionIndexFile(), 'utf8'));
+    const j = JSON.parse(fs.readFileSync(shardFile(shard), 'utf8'));
     return j && typeof j === 'object' && j.files && typeof j.files === 'object' ? j : { files: {} };
   } catch {
     return { files: {} };
   }
 }
 
-/** @param {any} idx */
-export function saveSessionIndex(idx) {
+/** @param {any} shard @param {any} idx */
+function saveShard(shard, idx) {
   try {
     ensureHome();
-    const target = sessionIndexFile();
-    atomicWriteFileSync(target, JSON.stringify(idx) + '\n'); // 质检 H4：索引原子写
+    const dir = shardDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    atomicWriteFileSync(shardFile(shard), JSON.stringify(idx) + '\n'); // 质检 H4：索引原子写
+  } catch {}
+}
+
+// 一次性迁移：旧版单文件 sessions-index.json → 分片目录（迁移后删除旧文件）
+function migrateLegacyIndex() {
+  const legacy = path.join(mingdaoHome(), 'sessions-index.json');
+  if (!fs.existsSync(legacy)) return;
+  try {
+    const j = JSON.parse(fs.readFileSync(legacy, 'utf8'));
+    const files = j && typeof j === 'object' && j.files && typeof j.files === 'object' ? j.files : {};
+    for (const [name, entry] of Object.entries(files)) {
+      const shard = shardOf(name);
+      const idx = loadShard(shard);
+      idx.files[name] = entry;
+      saveShard(shard, idx);
+    }
+    fs.unlinkSync(legacy);
   } catch {}
 }
 
@@ -81,45 +116,99 @@ export function extractSessionText(file) {
   return parts.join('\n');
 }
 
-// 增量同步索引（对比 mtime/size，只重算变化的文件；清理已删除条目）
-/** @param {any} home @param {any} sessions */
+// 增量同步索引（对比 mtime/size，只重算变化的文件；清理已删除条目）。
+// 返回合并后的 { files: {名称: 词表条目} } 供检索匹配（仍只持有所需词表，不再单次解析巨型文件）。
+/** @param {any} home @param {any} sessions
+ * @returns {{ files: Record<string, any> }} */
 export function syncSessionIndex(home, sessions) {
-  const idx = loadSessionIndex();
+  migrateLegacyIndex();
   const dir = path.join(home, 'sessions');
-  let changed = false;
+  /** @type {{ files: Record<string, any> }} */
+  const combined = { files: {} };
+  const liveShards = new Set();
+
+  // 按分片聚合存活会话：每片只 load 一次，命中/变化只写回该片
+  const byShard = new Map();
   for (const s of sessions) {
-    let st;
-    try {
-      st = fs.statSync(s.file);
-    } catch {
-      delete idx.files[s.name];
+    const k = shardOf(s.name);
+    if (!byShard.has(k)) byShard.set(k, []);
+    byShard.get(k).push(s);
+  }
+
+  for (const [k, group] of byShard) {
+    liveShards.add(k);
+    const idx = loadShard(k);
+    let changed = false;
+    for (const s of group) {
+      let st;
+      try {
+        st = fs.statSync(s.file);
+      } catch {
+        delete idx.files[s.name];
+        changed = true;
+        continue;
+      }
+      const cached = idx.files[s.name];
+      if (cached && cached.mtime === st.mtimeMs && cached.size === st.size) continue; // 未变化：直接用缓存
       changed = true;
-      continue;
+      if (st.size > INDEX_MAX_FILE) {
+        delete idx.files[s.name]; // 超大文件不索引
+        continue;
+      }
+      try {
+        idx.files[s.name] = {
+          mtime: st.mtimeMs,
+          size: st.size,
+          terms: Object.fromEntries(tokenize(extractSessionText(s.file))),
+        };
+      } catch {
+        delete idx.files[s.name];
+      }
     }
-    const cached = idx.files[s.name];
-    if (cached && cached.mtime === st.mtimeMs && cached.size === st.size) continue; // 未变化：直接用缓存
-    changed = true;
-    if (st.size > INDEX_MAX_FILE) {
-      delete idx.files[s.name]; // 超大文件不索引
-      continue;
+    // 清理本片内已删除的会话条目（防索引膨胀）
+    for (const name of Object.keys(idx.files)) {
+      if (!fs.existsSync(path.join(dir, name))) {
+        delete idx.files[name];
+        changed = true;
+      }
     }
-    try {
-      idx.files[s.name] = {
-        mtime: st.mtimeMs,
-        size: st.size,
-        terms: Object.fromEntries(tokenize(extractSessionText(s.file))),
-      };
-    } catch {
-      delete idx.files[s.name];
+    if (changed) saveShard(k, idx);
+    // 合并本片存活条目供检索
+    for (const s of group) {
+      const e = idx.files[s.name];
+      if (e) combined.files[s.name] = e;
     }
   }
-  // 清理已删除的会话条目（防索引无限膨胀）
-  for (const name of Object.keys(idx.files)) {
-    if (!fs.existsSync(path.join(dir, name))) {
-      delete idx.files[name];
-      changed = true;
+
+  // 清理「无存活会话」分片里的陈旧条目（这些片的会话全被删了）：目录扫描逐片检查，
+  // 每片都很小；空片直接删除文件，避免残留索引膨胀
+  let entries = [];
+  try {
+    entries = fs.readdirSync(shardDir());
+  } catch {
+    return combined;
+  }
+  for (const f of entries) {
+    if (!f.endsWith('.json')) continue;
+    const k = f.slice(0, -5);
+    if (liveShards.has(k)) continue;
+    const idx = loadShard(k);
+    let changed = false;
+    for (const name of Object.keys(idx.files)) {
+      if (!fs.existsSync(path.join(dir, name))) {
+        delete idx.files[name];
+        changed = true;
+      }
+    }
+    if (changed) {
+      if (Object.keys(idx.files).length) saveShard(k, idx);
+      else {
+        try {
+          fs.unlinkSync(path.join(shardDir(), f));
+        } catch {}
+      }
     }
   }
-  if (changed) saveSessionIndex(idx);
-  return idx;
+
+  return combined;
 }

package/src/tools/fs-tools.js

@@ -3,11 +3,12 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { MAX_FILE_READ_BYTES } from '../web/constants.js';
 
 const MAX_SCAN_FILES = 20000;
 const MAX_GLOB_RESULTS = 1000;
 const MAX_GREP_MATCHES = 250;
-const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_FILE_BYTES = MAX_FILE_READ_BYTES; // 单源化（v0.2.8 B2）：read/edit 单文件读取上限
 
 /**
  * @param {any} cwd

package/src/tools/index.js

@@ -83,9 +83,9 @@ const SKILL_SCHEMA = {
 const TASK_SCHEMA = {
   type: 'object',
   properties: {
-    description: { type: 'string', description: '子任务一句话描述。' },
-    prompt: { type: 'string', description: '子代理的完整任务说明。' },
-    readOnly: { type: 'boolean', description: '只读调研任务，可并行。' },
+    description: { type: 'string', description: '子任务一句话描述（用于进度展示）。' },
+    prompt: { type: 'string', description: '子代理的完整任务说明（全新上下文，需自带全部必要背景）。' },
+    readOnly: { type: 'boolean', description: '只读调研任务（不写文件不执行命令）。多个 readOnly 子任务同一轮派发会并行执行，效率最高。' },
   },
   required: ['prompt'],
 };
@@ -185,7 +185,7 @@ const TOOLS = [
     type: 'function',
     function: {
       name: 'task',
-      description: '把独立子任务委托给新上下文子代理并返回汇报；readOnly 只读任务可并行。',
+      description: '把独立、可并行的子任务委托给全新上下文子代理并返回汇报。适合：多方向调研/复核/独立实现等互不依赖的任务（多个只读调研子任务应同一轮一起派发，自动并行，效率最高）；不适合：依赖当前对话细节的小改动。',
       parameters: TASK_SCHEMA,
     },
   },