@huicai/cli 2026.710.97950 → 2026.711.0

package/src/permissions.js

@@ -4,16 +4,37 @@
 
 import { c } from './colors.js';
 import { toolLabel, renderEditDiff, indent } from './render.js';
-import { loadAllowRules, matchAllowRules, suggestRule, addProjectAllowRule, riskWarning } from './settings.js';
+import { loadAllowRules, loadDenyRules, matchAllowRules, suggestRule, addProjectAllowRule, riskWarning } from './settings.js';
+
+// 计划模式下写/执行类工具被拒绝时的统一说明（REPL 与 TUI 共用同一文案）。
+export const PLAN_DENY_REASON =
+  '当前处于计划模式：只做只读调研，不执行任何改动。请先产出完整方案交用户确认；'
+  + '用户 /plan 关闭计划模式后再执行改动。';
+
+// 沙箱模式下 run_bash / fetch_url 被拒绝时的统一说明。
+export const SANDBOX_DENY_REASON =
+  '当前处于沙箱模式：禁止执行 shell 命令（run_bash）与联网（fetch_url）。'
+  + '可继续读写本地文件；如需执行/联网，请用户 /sandbox off 关闭沙箱。';
 
 export function createPermissions({ yolo = false, ask = null, cwd = null } = {}) {
   const sessionAllowed = new Set();
   let autoAll = !!yolo;
-  // 仅在给定 cwd 时读取 settings 允许规则（测试等场景不受用户本机全局配置影响）
+  let planMode = false;
+  let sandbox = false;
+  // 仅在给定 cwd 时读取 settings 规则（测试等场景不受用户本机全局配置影响）
   let rules = cwd ? loadAllowRules(cwd) : [];
+  let denyRules = cwd ? loadDenyRules(cwd) : [];
 
   // readOnly 由调用方判定（内置工具查 READONLY_TOOLS；MCP 工具看 readOnlyHint；子智能体只读）
   async function request(name, args, _cwd, readOnly = false) {
+    // 拒绝规则优先于一切（含只读；可用于挡住读取密钥文件等）
+    if (denyRules.length && matchAllowRules(denyRules, name, args)) {
+      return { allow: false, reason: '该操作被拒绝规则阻止（/permissions 查看或移除）。' };
+    }
+    // 计划模式：只放行只读，写/执行一律拦下并回灌原因（模型据此改为产出方案）
+    if (planMode && !readOnly) return { allow: false, reason: PLAN_DENY_REASON };
+    // 沙箱模式：禁 shell 与联网（仍可读写本地文件）
+    if (sandbox && (name === 'run_bash' || name === 'fetch_url')) return { allow: false, reason: SANDBOX_DENY_REASON };
     if (readOnly) return { allow: true };
     if (autoAll || sessionAllowed.has(name)) return { allow: true };
     if (rules.length && matchAllowRules(rules, name, args)) return { allow: true };
@@ -59,6 +80,23 @@ export function createPermissions({ yolo = false, ask = null, cwd = null } = {})
     isYolo() {
       return autoAll;
     },
+    setPlanMode(v) {
+      planMode = !!v;
+    },
+    isPlanMode() {
+      return planMode;
+    },
+    setSandbox(v) {
+      sandbox = !!v;
+    },
+    isSandbox() {
+      return sandbox;
+    },
+    /** 规则文件被 /permissions 修改后重新加载（本会话即时生效）。 */
+    reloadRules() {
+      rules = cwd ? loadAllowRules(cwd) : [];
+      denyRules = cwd ? loadDenyRules(cwd) : [];
+    },
   };
 }
 

package/src/render.js

@@ -13,6 +13,8 @@ export function toolLabel(name, args = {}) {
       return `glob ${args.pattern ?? ''}`;
     case 'grep':
       return `grep ${JSON.stringify(args.pattern ?? '')}${args.path ? ' in ' + args.path : ''}`;
+    case 'search_code':
+      return `search_code ${JSON.stringify(args.query ?? '')}`;
     case 'write_file':
       return `write_file ${args.path ?? ''}`;
     case 'edit_file':
@@ -27,6 +29,8 @@ export function toolLabel(name, args = {}) {
       const o = String(args.objective ?? '').split('\n')[0];
       return `dispatch_agent: ${o.length > 60 ? o.slice(0, 60) + '…' : o}`;
     }
+    case 'dispatch_agents':
+      return `dispatch_agents（并行 ${Array.isArray(args.tasks) ? args.tasks.length : '?'} 个子任务）`;
     default:
       return `${name}(${Object.keys(args).join(', ')})`;
   }

package/src/repl.js

@@ -6,9 +6,15 @@ import { c } from './colors.js';
 import { createPermissions } from './permissions.js';
 import { runTurn } from './agent.js';
 import { createSession, saveSession, turnCount } from './session.js';
+import { createCheckpoints } from './checkpoints.js';
+import { buildSystemPrompt } from './context.js';
+import { runVerifyLoop } from './autofix.js';
 import { loadMcpTools, closeMcp } from './mcp.js';
-import { makeSubagentTool } from './subagent.js';
+import { makeSubagentTool, makeDispatchAgentsTool } from './subagent.js';
 import { makeConsultTool } from './consult.js';
+import { makeAdvisorTool } from './advisor.js';
+import { makeRecallTool, readMemoryRaw } from './memory.js';
+import { detectScanners, makeScanTool } from './scan.js';
 import { runSlash } from './commands.js';
 import { expandAtMentions, buildUserContent, runBangCommand, loadHistory, appendHistory } from './input.js';
 import { makeSkillTools } from './skills.js';
@@ -26,9 +32,18 @@ export async function buildExtraTools(config, cwd) {
   const extraTools = [...makeSkillTools(cwd), ...mcp.tools];
   const dispatch = makeSubagentTool({ config, cwd, extraTools: mcp.tools, depth: 0 });
   if (dispatch) extraTools.push(dispatch);
+  // 多智能体编排：并行批量子智能体（一次调用→N 并行→聚合）
+  const dispatchBatch = makeDispatchAgentsTool({ config, cwd, extraTools: mcp.tools, depth: 0 });
+  if (dispatchBatch) extraTools.push(dispatchBatch);
   // 混合模式：配置了 --consult 平台伪模型时，暴露 consult_platform 工具（本机驱动 + 平台编排咨询）
   const consult = makeConsultTool({ config });
   if (consult) extraTools.push(consult);
+  // 会决策：设置了顾问模型 → ask_advisor；有长期记忆 → recall_memory（跨会话经验主动召回）
+  const advisor = makeAdvisorTool({ config });
+  if (advisor) extraTools.push(advisor);
+  if (config.memoryEnabled !== false && readMemoryRaw(cwd)) extraTools.push(makeRecallTool({ cwd }));
+  // 提质：检测到可用扫描器 → security_scan（真扫描,供安全审查/提交前自检）
+  if (detectScanners(cwd).length) extraTools.push(makeScanTool({ cwd }));
   return { extraTools, clients: mcp.clients };
 }
 
@@ -51,10 +66,12 @@ export async function startRepl({ config, cwd, yolo, initialPrompt, session, ver
     historySize: 200,
   });
   const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
-  const permissions = createPermissions({ yolo, ask, cwd });
+  let permissions = createPermissions({ yolo, ask, cwd }); // /cd 换目录时会重建
   const usage = { prompt: 0, completion: 0 };
   const todoState = { list: [] };
+  const checkpoints = createCheckpoints(); // /rewind 检查点（本会话内存态）
   let currentAbort = null;
+  let loopTimer = null; // /loop 定时器
   // ctx 持有可变的 session（/clear 会替换为新会话），各处统一读 ctx.session
   const ctx = { config, cwd, permissions, usage, session, version };
 
@@ -65,12 +82,14 @@ export async function startRepl({ config, cwd, yolo, initialPrompt, session, ver
 
   banner(config, cwd, permissions, version);
   echoResumed(session);
-  const { extraTools, clients } = await buildExtraTools(config, cwd); // 连接 MCP（若已配置）
+  let { extraTools, clients } = await buildExtraTools(config, cwd); // 连接 MCP（若已配置）；/cd 换目录时会重建
 
   const doTurn = async (text) => {
     const { text: expanded, mentions, images } = await expandAtMentions(text, cwd, config);
     if (mentions.length) process.stdout.write(c.gray('  · 已展开引用：' + mentions.join('、')
       + (images.length ? `（含 ${images.length} 张图片）` : '')) + '\n');
+    // 回合前记录检查点（对话位置 + 本回合文件原文经 fileJournal 累积），供 /rewind 回滚
+    const journal = checkpoints.snapshot({ session: ctx.session, label: text });
     ctx.session.messages.push({ role: 'user', content: buildUserContent(expanded, images) });
     currentAbort = new AbortController();
     if (!ctx.session.compaction) ctx.session.compaction = {};
@@ -84,6 +103,7 @@ export async function startRepl({ config, cwd, yolo, initialPrompt, session, ver
       extraTools,
       todoState,
       compaction: ctx.session.compaction,
+      fileJournal: journal,
     });
     if (r?.usage) {
       usage.prompt += r.usage.prompt;
@@ -92,12 +112,14 @@ export async function startRepl({ config, cwd, yolo, initialPrompt, session, ver
     if (r?.lastPromptTokens) ctx.session.lastPromptTokens = r.lastPromptTokens;
     currentAbort = null;
     saveSession(ctx.session); // 每轮结束自动保存，可随时 --resume 恢复
+    return r;
   };
 
   const cmdCtx = () => ({
     ...ctx,
     session: ctx.session,
     extraTools,
+    checkpoints,
     print: (t) => process.stdout.write(String(t).endsWith('\n') ? String(t) : String(t) + '\n'),
   });
 
@@ -133,13 +155,57 @@ export async function startRepl({ config, cwd, yolo, initialPrompt, session, ver
       if (r.action === 'clear') {
         ctx.session = createSession({ cwd, model: config.model, messages: [ctx.session.messages[0]] });
         todoState.list = [];
+        checkpoints.list.length = 0;
         process.stdout.write(c.gray('已开启新会话（旧会话已保存，可用 huicai --resume 恢复）。\n'));
       }
+      if (r.action === 'refresh') echoResumed(ctx.session); // /rewind 回退对话后重新回显，帮助对齐
+      if (r.action === 'cd') {
+        // 切换工作目录：重建权限/工具/会话（在新目录开启新会话，旧会话已保存）
+        cwd = r.cwd;
+        ctx.cwd = cwd;
+        permissions = createPermissions({ yolo: permissions.isYolo(), ask, cwd });
+        ctx.permissions = permissions;
+        closeMcp(clients);
+        ({ extraTools, clients } = await buildExtraTools(config, cwd));
+        ctx.session = createSession({
+          cwd, model: config.model,
+          messages: [{ role: 'system', content: buildSystemPrompt(cwd, { memory: config.memoryEnabled !== false }) }],
+        });
+        todoState.list = [];
+        checkpoints.list.length = 0;
+        config.sessionId = ctx.session.id;
+        process.stdout.write(c.gray('已切换到 ' + cwd + '（新会话，旧会话已保存）。\n'));
+      }
+      if (r.action === 'autofix') {
+        // 修到通过闭环：跑验证命令，失败自动让智能体修复后重跑
+        await runVerifyLoop({
+          command: r.command,
+          maxIters: r.maxIters,
+          cwd,
+          runTurnOnce: (p) => doTurn(p),
+          emit: (t) => process.stdout.write(c.gray(t) + '\n'),
+        });
+      }
+      if (r.action === 'loop') {
+        if (loopTimer) {
+          clearInterval(loopTimer);
+          loopTimer = null;
+        }
+        if (r.stop) {
+          process.stdout.write(c.gray('已停止循环。\n'));
+        } else {
+          process.stdout.write(c.gray(`已开始循环：每 ${r.seconds}s 运行「${r.prompt}」（/loop off 停止）。\n`));
+          loopTimer = setInterval(() => {
+            if (!currentAbort) void doTurn(r.prompt);
+          }, r.seconds * 1000);
+        }
+      }
       if (r.prompt) await doTurn(r.prompt);
       continue;
     }
     await doTurn(input);
   }
+  if (loopTimer) clearInterval(loopTimer);
   rl.close();
   closeMcp(clients);
   process.stdout.write(c.gray('\n再见。\n'));

package/src/scan.js

@@ -0,0 +1,84 @@
+// 真扫描工具集成（提质）：自动检测并运行本项目适用、且本机已安装的安全/质量扫描器
+// （依赖漏洞 / SAST / 密钥泄漏），把「发现」交给智能体去修——从「发提示词」变「真扫描 + 修复」。
+// 暴露为 security_scan 工具（智能体可在安全审查/提交前自检时调用）+ /scan 命令。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { captureCommand } from './autofix.js';
+
+function has(cwd, file) {
+  try {
+    return fs.existsSync(path.join(cwd, file));
+  } catch {
+    return false;
+  }
+}
+
+/** 命令是否可用（本机已安装）。 */
+function cmdExists(cmd) {
+  try {
+    execSync(process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 检测本项目适用且已安装的扫描器。返回 [{name, command, why}]。 */
+export function detectScanners(cwd) {
+  const s = [];
+  if (has(cwd, 'package.json') && cmdExists('npm')) {
+    s.push({ name: 'npm audit', command: 'npm audit --audit-level=high', why: 'Node 依赖漏洞' });
+  }
+  if ((has(cwd, 'requirements.txt') || has(cwd, 'pyproject.toml')) && cmdExists('pip-audit')) {
+    s.push({ name: 'pip-audit', command: 'pip-audit', why: 'Python 依赖漏洞' });
+  }
+  if (has(cwd, 'go.mod') && cmdExists('govulncheck')) {
+    s.push({ name: 'govulncheck', command: 'govulncheck ./...', why: 'Go 漏洞' });
+  }
+  if (has(cwd, 'Cargo.toml') && cmdExists('cargo-audit')) {
+    s.push({ name: 'cargo audit', command: 'cargo audit', why: 'Rust 依赖漏洞' });
+  }
+  if (cmdExists('semgrep')) {
+    s.push({ name: 'semgrep', command: 'semgrep --config auto --error -q .', why: '代码静态安全(SAST)' });
+  }
+  if (cmdExists('gitleaks')) {
+    s.push({ name: 'gitleaks', command: 'gitleaks detect --no-banner -r /dev/stdout', why: '密钥泄漏' });
+  }
+  if (cmdExists('trivy')) {
+    s.push({ name: 'trivy fs', command: 'trivy fs --scanners vuln,secret -q .', why: '依赖漏洞+密钥' });
+  }
+  return s;
+}
+
+/** 依次运行扫描器（各限时 3 分钟）。返回 [{name, why, code, output}]（code!==0 视为有发现/高危）。 */
+export async function runScanners(cwd, scanners) {
+  const results = [];
+  for (const sc of scanners) {
+    const { code, output } = await captureCommand(cwd, sc.command, 180000);
+    results.push({ name: sc.name, why: sc.why, command: sc.command, code, output });
+  }
+  return results;
+}
+
+/** 构造 security_scan 工具（智能体可调用）：自动检测+运行，返回发现。 */
+export function makeScanTool({ cwd }) {
+  const spec = {
+    type: 'function',
+    function: {
+      name: 'security_scan',
+      description:
+        '自动检测并运行本项目适用的安全/质量扫描器（npm audit / semgrep / trivy / gitleaks / 依赖体检等，仅跑本机已装的），返回发现的问题。'
+        + '用于安全审查或提交前自检；发现问题后你应逐条修复再重扫确认。',
+      parameters: { type: 'object', properties: {}, required: [] },
+    },
+  };
+  const run = async () => {
+    const scanners = detectScanners(cwd);
+    if (!scanners.length) return '未检测到可用的扫描器（可安装 semgrep/trivy/gitleaks，或项目含 package.json 等）。';
+    const results = await runScanners(cwd, scanners);
+    return results.map((r) => `## ${r.name}（${r.code === 0 ? '无高危' : '有发现'}）\n${r.output.slice(0, 4000)}`).join('\n\n');
+  };
+  return { readOnly: true, spec, run };
+}

package/src/schedule.js

@@ -0,0 +1,48 @@
+// /schedule：管理定时任务（持久化到 ~/.huicai/schedule.json），并生成交给系统 cron 运行的 crontab 行。
+// 不自带调度器——把定时职责交给成熟的系统 cron；本模块负责登记 + 生成可粘贴的 crontab 条目。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const SCHEDULE_FILE = path.join(os.homedir(), '.huicai', 'schedule.json');
+
+function read() {
+  try {
+    const j = JSON.parse(fs.readFileSync(SCHEDULE_FILE, 'utf8'));
+    return Array.isArray(j) ? j : [];
+  } catch {
+    return [];
+  }
+}
+
+function write(list) {
+  fs.mkdirSync(path.dirname(SCHEDULE_FILE), { recursive: true });
+  fs.writeFileSync(SCHEDULE_FILE, JSON.stringify(list, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function listTasks() {
+  return read();
+}
+
+/** 添加定时任务。@param {{cron:string, prompt:string, cwd:string}} t */
+export function addTask({ cron, prompt, cwd }) {
+  const list = read();
+  const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 4);
+  list.push({ id, cron, prompt, cwd, created: Date.now() });
+  write(list);
+  return { id };
+}
+
+export function removeTask(id) {
+  const list = read();
+  const next = list.filter((t) => t.id !== id);
+  write(next);
+  return next.length < list.length;
+}
+
+/** 生成一条 crontab 行（供 crontab -e 粘贴）。 */
+export function crontabLine(t, bin = 'huicai') {
+  return `${t.cron} cd ${JSON.stringify(t.cwd)} && ${bin} -p ${JSON.stringify(t.prompt)} --yolo --plain `
+    + `>> ${JSON.stringify(path.join(os.homedir(), '.huicai', 'schedule-' + t.id + '.log'))} 2>&1`;
+}

package/src/subagent.js

@@ -2,11 +2,81 @@
 // 一个内置工具 dispatch_agent，把明确子任务交给「隔离上下文 + 只读工具」的子智能体自主完成，只回传结论。
 // 让主线程上下文保持精简，适合并行/发散的调研、检索、分析类子任务。
 
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
 import { runTurn } from './agent.js';
 import { createPermissions } from './permissions.js';
+import { parseFrontmatter } from './skills.js';
 
 const MAX_DEPTH = 2; // 顶层 depth=0；到达上限不再提供 dispatch_agent，防无限递归
 
+/**
+ * 加载已定义的子智能体人格：<cwd>/.huicai/agents/*.md 与 ~/.huicai/agents/*.md
+ * （frontmatter name/description + 正文=该子智能体的系统提示词）。项目级优先于全局同名。
+ * @returns {{name:string, description:string, prompt:string}[]}
+ */
+export function loadAgents(cwd) {
+  const dirs = [
+    cwd ? path.join(cwd, '.huicai', 'agents') : null,
+    path.join(os.homedir(), '.huicai', 'agents'),
+  ].filter(Boolean);
+  const byName = new Map();
+  for (const dir of dirs) {
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      const base = f.replace(/\.md$/, '').trim();
+      if (!base || byName.has(base)) continue;
+      try {
+        const raw = fs.readFileSync(path.join(dir, f), 'utf8');
+        const fm = parseFrontmatter(raw);
+        byName.set(base, { name: (fm.name || base).trim(), description: fm.description || '', prompt: fm.body || raw });
+      } catch {
+        /* 跳过坏文件 */
+      }
+    }
+  }
+  return [...byName.values()];
+}
+
+/** 有序有限并发 map（并发≤limit，结果按输入下标回填）。 */
+async function mapLimit(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await fn(items[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+  return results;
+}
+
+/** 跑一个子智能体子任务（隔离上下文 + 只读工具），返回结论文本。dispatch_agent 与 dispatch_agents 共用。 */
+async function dispatchSubtask({ config, cwd, readOnlyExtras, depth, objective, context, agentDef }) {
+  if (!objective) return '未提供子任务目标 objective';
+  const sys = agentDef
+    ? agentDef.prompt.trim() + '\n\n工作目录：' + cwd + (context && String(context).trim() ? '\n\n## 背景\n' + context : '')
+    : subagentPrompt(cwd, context);
+  const messages = [{ role: 'system', content: sys }, { role: 'user', content: objective }];
+  const permissions = createPermissions({ yolo: false, ask: null });
+  const nested = makeSubagentTool({ config, cwd, extraTools: readOnlyExtras, depth: depth + 1 });
+  const subExtra = nested ? [...readOnlyExtras, nested] : readOnlyExtras;
+  const r = await runTurn({
+    config, messages, permissions, cwd, extraTools: subExtra,
+    depth: depth + 1, maxIters: 50, io: { write: () => {} },
+  });
+  if (r?.error) return `子智能体执行失败：${r.error}`;
+  const last = [...messages].reverse().find((m) => m.role === 'assistant' && m.content);
+  return last ? last.content : '(子智能体未产出结论)';
+}
+
 /**
  * 构造 dispatch_agent 工具。达到深度上限返回 null（不暴露委派）。
  * @param {object} p
@@ -18,6 +88,7 @@ const MAX_DEPTH = 2; // 顶层 depth=0；到达上限不再提供 dispatch_agent
 export function makeSubagentTool({ config, cwd, extraTools = [], depth = 0 }) {
   if (depth >= MAX_DEPTH) return null;
 
+  const agents = loadAgents(cwd); // 已定义的子智能体人格（可选指定）
   const spec = {
     type: 'function',
     function: {
@@ -30,6 +101,14 @@ export function makeSubagentTool({ config, cwd, extraTools = [], depth = 0 }) {
         properties: {
           objective: { type: 'string', description: '要子智能体完成的单一、明确、自足的子任务' },
           context: { type: 'string', description: '可选：完成该子任务所需的背景信息' },
+          ...(agents.length ? {
+            agent: {
+              type: 'string',
+              enum: agents.map((a) => a.name),
+              description: '可选：使用某个已定义的子智能体人格 — '
+                + agents.map((a) => a.name + (a.description ? `(${a.description.slice(0, 40)})` : '')).join('；'),
+            },
+          } : {}),
         },
         required: ['objective'],
       },
@@ -40,35 +119,57 @@ export function makeSubagentTool({ config, cwd, extraTools = [], depth = 0 }) {
   const readOnlyExtras = extraTools.filter((t) => t.readOnly);
 
   const run = async (args) => {
-    const objective = String(args?.objective || '').trim();
-    if (!objective) return '未提供子任务目标 objective';
-
-    const messages = [
-      { role: 'system', content: subagentPrompt(cwd, args?.context) },
-      { role: 'user', content: objective },
-    ];
-    // 只读、非交互：读工具自动放行，写/执行被拒并把原因回灌（子智能体不产生副作用）
-    const permissions = createPermissions({ yolo: false, ask: null });
+    const agentDef = args?.agent ? agents.find((a) => a.name === args.agent) : null;
+    return dispatchSubtask({ config, cwd, readOnlyExtras, depth, objective: String(args?.objective || '').trim(), context: args?.context, agentDef });
+  };
 
-    // 允许有限层级的再委派
-    const nested = makeSubagentTool({ config, cwd, extraTools: readOnlyExtras, depth: depth + 1 });
-    const subExtra = nested ? [...readOnlyExtras, nested] : readOnlyExtras;
+  return { readOnly: true, spec, run };
+}
 
-    const r = await runTurn({
-      config,
-      messages,
-      permissions,
-      cwd,
-      extraTools: subExtra,
-      depth: depth + 1,
-      maxIters: 50, // 子智能体是聚焦的只读子任务：显式收敛轮数，不随顶层上限（120）放大，控成本与时延
-      io: { write: () => {} }, // 静默：子智能体过程不刷主终端
+/**
+ * 构造 dispatch_agents（并行批量）工具：一次调用把多个独立子任务并行委派给多个子智能体，聚合返回。
+ * 是多智能体编排的核心——把一个大目标拆成可并行子任务同时推进，显著提速。达深度上限返回 null。
+ */
+export function makeDispatchAgentsTool({ config, cwd, extraTools = [], depth = 0 }) {
+  if (depth >= MAX_DEPTH) return null;
+  const agents = loadAgents(cwd);
+  const readOnlyExtras = extraTools.filter((t) => t.readOnly);
+  const taskProps = {
+    objective: { type: 'string', description: '单一、明确、自足的子任务' },
+    context: { type: 'string', description: '可选：完成该子任务所需背景' },
+    ...(agents.length ? { agent: { type: 'string', enum: agents.map((a) => a.name), description: '可选：指定子智能体人格' } } : {}),
+  };
+  const spec = {
+    type: 'function',
+    function: {
+      name: 'dispatch_agents',
+      description:
+        '一次性把多个**独立、可并行**的子任务同时委派给多个子智能体（隔离上下文、只读工具），并行执行后聚合各自结论。'
+        + '适合把一个较大目标拆成 2-6 个可并行的调研/检索/分析子任务同时推进，显著减少串行等待。每个子任务需自足。',
+      parameters: {
+        type: 'object',
+        properties: {
+          tasks: {
+            type: 'array',
+            description: '并行子任务数组（建议 2-6 个，上限 8）',
+            items: { type: 'object', properties: taskProps, required: ['objective'] },
+          },
+        },
+        required: ['tasks'],
+      },
+    },
+  };
+  const run = async (args) => {
+    const tasks = Array.isArray(args?.tasks) ? args.tasks.slice(0, 8) : [];
+    if (!tasks.length) return '未提供 tasks（需要一个子任务数组）';
+    const results = await mapLimit(tasks, 4, async (t) => {
+      const agentDef = t?.agent ? agents.find((a) => a.name === t.agent) : null;
+      const out = await dispatchSubtask({ config, cwd, readOnlyExtras, depth, objective: String(t?.objective || '').trim(), context: t?.context, agentDef });
+      return { objective: String(t?.objective || '').replace(/\s+/g, ' ').slice(0, 80), agent: t?.agent, out };
     });
-    if (r?.error) return `子智能体执行失败：${r.error}`;
-    const last = [...messages].reverse().find((m) => m.role === 'assistant' && m.content);
-    return last ? last.content : '(子智能体未产出结论)';
+    return results.map((r, i) =>
+      `【子任务 ${i + 1}${r.agent ? ' · ' + r.agent : ''}】${r.objective}\n${r.out}`).join('\n\n---\n\n');
   };
-
   return { readOnly: true, spec, run };
 }
 

package/src/tools.js

@@ -1,6 +1,7 @@
 // 本机工具的 OpenAI 函数规格（随请求透传给平台模型）+ 名称→执行器分发。
 
 import * as ex from './executors.js';
+import { searchCode } from './codeindex.js';
 
 const obj = (properties, required) => ({ type: 'object', properties, required: required || [] });
 const str = (description) => ({ type: 'string', description });
@@ -38,6 +39,19 @@ export const TOOL_SPECS = [
       parameters: obj({ pattern: str('glob 模式') }, ['pattern']),
     },
   },
+  {
+    type: 'function',
+    function: {
+      name: 'search_code',
+      description:
+        '按「概念/功能」检索最相关的代码块（BM25 相关性排序，比 grep 更懂「哪段代码在做这件事」）。'
+        + '适合「登录逻辑在哪」「哪里处理支付回调」这类找相关实现；要找精确字符串仍用 grep。返回 文件:行范围 + 代码块。',
+      parameters: obj(
+        { query: str('要找的功能/概念（自然语言或关键词组合，多写几个相关词更准）'), k: int('可选：返回块数，默认 8，上限 20') },
+        ['query'],
+      ),
+    },
+  },
   {
     type: 'function',
     function: {
@@ -107,25 +121,26 @@ export const TOOL_SPECS = [
 ];
 
 /** 只读工具（默认自动放行，无需审批）。fetch_url 涉及外发请求，需用户授权。 */
-export const READONLY_TOOLS = new Set(['read_file', 'list_files', 'glob', 'grep']);
+export const READONLY_TOOLS = new Set(['read_file', 'list_files', 'glob', 'grep', 'search_code']);
 
 const EXECUTORS = {
   read_file: ex.readFile,
   list_files: ex.listFiles,
   glob: ex.glob,
   grep: ex.grep,
+  search_code: searchCode,
   write_file: ex.writeFile,
   edit_file: ex.editFile,
   run_bash: ex.runBash,
   fetch_url: ex.fetchUrl,
 };
 
-/** 执行一个本机工具，返回文本结果（回填给模型）。抛错转为可读文本，保证循环不中断。 */
-export async function runTool(name, args, cwd) {
+/** 执行一个本机工具，返回文本结果（回填给模型）。config 传入供个别工具用（如 search_code 的向量重排）。抛错转为可读文本，保证循环不中断。 */
+export async function runTool(name, args, cwd, config) {
   const fn = EXECUTORS[name];
   if (!fn) return `未知工具：${name}`;
   try {
-    return await fn(cwd, args || {});
+    return await fn(cwd, args || {}, config);
   } catch (e) {
     return `工具执行失败：${e.message}`;
   }