@huicai/cli 0.5.1

package/src/repl.js

@@ -0,0 +1,203 @@
+// 交互式 REPL + 一次性(print)模式。用同一个 readline 处理「主输入」与「工具授权」（顺序进行，不冲突）。
+// 斜杠命令走 commands.js 统一注册表（与 ink TUI 共用）；支持 @文件 引用与 !命令 直通。
+
+import readline from 'node:readline';
+import { c } from './colors.js';
+import { createPermissions } from './permissions.js';
+import { runTurn } from './agent.js';
+import { createSession, saveSession, turnCount } from './session.js';
+import { loadMcpTools, closeMcp } from './mcp.js';
+import { makeSubagentTool } from './subagent.js';
+import { runSlash } from './commands.js';
+import { expandAtMentions, runBangCommand, loadHistory, appendHistory } from './input.js';
+import { makeSkillTools } from './skills.js';
+
+/** 汇集动态工具：本地技能（load_skill）+ 本地 MCP 工具 + dispatch_agent 子智能体。返回 {extraTools, clients}。 */
+export async function buildExtraTools(config, cwd) {
+  let mcp = { tools: [], clients: [] };
+  try {
+    mcp = await loadMcpTools();
+  } catch (e) {
+    process.stdout.write(c.yellow('MCP 初始化失败（忽略）：' + e.message) + '\n');
+  }
+  // 本地技能工具（.huicai/skills 与 ~/.huicai/skills；无技能时为空数组，零开销）
+  const extraTools = [...makeSkillTools(cwd), ...mcp.tools];
+  const dispatch = makeSubagentTool({ config, cwd, extraTools: mcp.tools, depth: 0 });
+  if (dispatch) extraTools.push(dispatch);
+  return { extraTools, clients: mcp.clients };
+}
+
+function banner(config, cwd, permissions) {
+  process.stdout.write(c.bold(c.magenta('\n  huicai')) + c.gray(' · 终端智能体') + '\n');
+  const platform = /^(agent|workflow|datahuman)-/.test(String(config.model || ''));
+  process.stdout.write(
+    c.gray(`  ${platform ? '目标' : '模型'} ${config.model || '(未设置, /model 设置)'}`
+      + `${platform ? ' · 平台编排（分享页同款对话，无本机工具）' : ''} · 目录 ${cwd}`) + '\n',
+  );
+  process.stdout.write(
+    c.gray(
+      `  ${permissions.isYolo() ? '⚠ 自动放行(yolo) 已开 · ' : ''}` +
+      '/help 命令 · @文件 引用 · !命令 直通 shell · Ctrl+C 中断本回合',
+    ) + '\n',
+  );
+}
+
+export async function startRepl({ config, cwd, yolo, initialPrompt, session, version }) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    history: loadHistory(cwd).reverse(), // readline 的 history 最近的在前
+    historySize: 200,
+  });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+  const permissions = createPermissions({ yolo, ask, cwd });
+  const usage = { prompt: 0, completion: 0 };
+  const todoState = { list: [] };
+  let currentAbort = null;
+  // ctx 持有可变的 session（/clear 会替换为新会话），各处统一读 ctx.session
+  const ctx = { config, cwd, permissions, usage, session, version };
+
+  rl.on('SIGINT', () => {
+    if (currentAbort) currentAbort.abort();
+    else process.stdout.write('\n' + c.gray('输入 /exit 退出。') + '\n');
+  });
+
+  banner(config, cwd, permissions);
+  echoResumed(session);
+  const { extraTools, clients } = await buildExtraTools(config, cwd); // 连接 MCP（若已配置）
+
+  const doTurn = async (text) => {
+    const { text: expanded, mentions } = expandAtMentions(text, cwd);
+    if (mentions.length) process.stdout.write(c.gray('  · 已展开引用：' + mentions.join('、')) + '\n');
+    ctx.session.messages.push({ role: 'user', content: expanded });
+    currentAbort = new AbortController();
+    if (!ctx.session.compaction) ctx.session.compaction = {};
+    config.sessionId = ctx.session.id; // 对话落库审计：当前会话号（/clear 换新会话后随之更新）
+    const r = await runTurn({
+      config,
+      messages: ctx.session.messages,
+      permissions,
+      cwd,
+      signal: currentAbort.signal,
+      extraTools,
+      todoState,
+      compaction: ctx.session.compaction,
+    });
+    if (r?.usage) {
+      usage.prompt += r.usage.prompt;
+      usage.completion += r.usage.completion;
+    }
+    if (r?.lastPromptTokens) ctx.session.lastPromptTokens = r.lastPromptTokens;
+    currentAbort = null;
+    saveSession(ctx.session); // 每轮结束自动保存，可随时 --resume 恢复
+  };
+
+  const cmdCtx = () => ({
+    ...ctx,
+    session: ctx.session,
+    extraTools,
+    print: (t) => process.stdout.write(String(t).endsWith('\n') ? String(t) : String(t) + '\n'),
+  });
+
+  if (initialPrompt) {
+    process.stdout.write(c.cyan('\nhuicai> ') + initialPrompt + '\n');
+    await doTurn(initialPrompt);
+  }
+
+  while (true) {
+    let input;
+    try {
+      input = (await ask(c.cyan('\nhuicai> '))).trim();
+    } catch {
+      break; // stdin 关闭
+    }
+    if (input === '') continue;
+    appendHistory(cwd, input);
+    if (input === '/exit' || input === '/quit') break;
+
+    if (input.startsWith('!') && input.length > 1) {
+      // shell 直通：本机执行，输出加入上下文（不消耗模型调用）
+      const command = input.slice(1).trim();
+      const { output, record } = await runBangCommand(command, cwd);
+      process.stdout.write(c.gray(output.split('\n').map((l) => '  ' + l).join('\n')) + '\n');
+      ctx.session.messages.push({ role: 'user', content: record });
+      saveSession(ctx.session);
+      continue;
+    }
+
+    if (input.startsWith('/')) {
+      const r = await runSlash(input, cmdCtx());
+      if (r.action === 'exit') break;
+      if (r.action === 'clear') {
+        ctx.session = createSession({ cwd, model: config.model, messages: [ctx.session.messages[0]] });
+        todoState.list = [];
+        process.stdout.write(c.gray('已开启新会话（旧会话已保存，可用 huicai --resume 恢复）。\n'));
+      }
+      if (r.prompt) await doTurn(r.prompt);
+      continue;
+    }
+    await doTurn(input);
+  }
+  rl.close();
+  closeMcp(clients);
+  process.stdout.write(c.gray('\n再见。\n'));
+}
+
+/** 恢复会话时的提示：标题 + 轮数 + 上一条助手回复摘要，帮用户续上下文。 */
+function echoResumed(session) {
+  const turns = turnCount(session.messages);
+  if (turns === 0) return;
+  process.stdout.write(c.gray(`  已恢复会话「${session.title || ''}」（${turns} 轮）`) + '\n');
+  const lastAssistant = [...session.messages].reverse().find((m) => m.role === 'assistant' && m.content);
+  if (lastAssistant) {
+    const text = String(lastAssistant.content).trim();
+    const snippet = text.length > 400 ? text.slice(0, 400) + '…' : text;
+    process.stdout.write(c.gray('  上次回复：') + snippet.replace(/\n/g, '\n  ') + '\n');
+  }
+}
+
+/**
+ * 一次性（非交互）模式：跑一个指令即退出。无 ask → 写/执行需 --yolo 才放行。
+ * persist=true（配合 --continue/--resume）时把本轮追加保存回会话，供后续续接。
+ * outputFormat='json' 时静默过程输出，最后打印一行结构化 JSON（脚本/CI 集成）。
+ */
+export async function runOnce({ config, cwd, yolo, prompt, session, persist, outputFormat, maxTurns }) {
+  if (!prompt) {
+    process.stderr.write('用法: huicai -p "你的指令"\n');
+    process.exit(1);
+  }
+  const json = outputFormat === 'json';
+  const permissions = createPermissions({ yolo, ask: null, cwd });
+  const { extraTools, clients } = await buildExtraTools(config, cwd);
+  const { text: expanded } = expandAtMentions(prompt, cwd);
+  session.messages.push({ role: 'user', content: expanded });
+  if (!session.compaction) session.compaction = {};
+  config.sessionId = session.id; // 对话落库审计：会话号
+  const r = await runTurn({
+    config,
+    messages: session.messages,
+    permissions,
+    cwd,
+    extraTools,
+    maxIters: maxTurns,
+    compaction: session.compaction,
+    io: json ? { write: () => {} } : undefined,
+  });
+  if (r?.lastPromptTokens) session.lastPromptTokens = r.lastPromptTokens;
+  if (persist) saveSession(session);
+  closeMcp(clients);
+  if (json) {
+    const lastAssistant = [...session.messages].reverse().find((m) => m.role === 'assistant' && m.content);
+    process.stdout.write(JSON.stringify({
+      type: 'result',
+      is_error: !!r?.error,
+      ...(r?.error ? { error: r.error } : {}),
+      result: lastAssistant ? String(lastAssistant.content) : '',
+      usage: { input_tokens: r?.usage?.prompt ?? 0, output_tokens: r?.usage?.completion ?? 0 },
+      session_id: session.id,
+      model: config.model,
+      num_turns: turnCount(session.messages),
+    }) + '\n');
+  }
+  if (r?.error) process.exit(1);
+}

package/src/session.js

@@ -0,0 +1,140 @@
+// 会话持久化：把对话（含系统提示词 + 各轮消息）落盘到 ~/.huicai/sessions/<id>.json，
+// 支持列出、恢复、删除。按项目目录(cwd)归属，使 --continue/--resume 只看当前项目的会话。
+// 所有磁盘操作 best-effort：失败仅告警，绝不让保存/读取异常中断对话本身。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_DIR } from './config.js';
+
+export const SESSIONS_DIR = path.join(CONFIG_DIR, 'sessions');
+
+function ensureDir() {
+  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+}
+
+function fileOf(id) {
+  return path.join(SESSIONS_DIR, id + '.json');
+}
+
+function genId() {
+  return Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 6);
+}
+
+/** 由首条用户消息派生标题（截断）。 */
+function deriveTitle(messages) {
+  const firstUser = (messages || []).find((m) => m.role === 'user');
+  if (!firstUser || !firstUser.content) return '(空会话)';
+  return String(firstUser.content).replace(/\s+/g, ' ').trim().slice(0, 60) || '(空会话)';
+}
+
+/** 会话中的用户轮数（对话往返次数的近似）。 */
+export function turnCount(messages) {
+  return (messages || []).filter((m) => m.role === 'user').length;
+}
+
+/**
+ * 新建会话对象（内存态）；messages 需已含 system 消息。落盘发生在首次 saveSession。
+ */
+export function createSession({ cwd, model, messages }) {
+  const now = Date.now();
+  return {
+    id: genId(),
+    cwd,
+    model,
+    createdAt: now,
+    updatedAt: now,
+    title: '',
+    messages: messages || [],
+    // 非破坏式上下文压缩状态（摘要独立存储，messages 永远保留全量原文）
+    compaction: {},
+  };
+}
+
+/** 保存会话（覆盖写，0600）。best-effort。 */
+export function saveSession(session) {
+  if (!session || !session.id) return;
+  try {
+    ensureDir();
+    session.updatedAt = Date.now();
+    if (!session.title) session.title = deriveTitle(session.messages);
+    fs.writeFileSync(fileOf(session.id), JSON.stringify(session), { mode: 0o600 });
+  } catch (e) {
+    process.stderr.write(`（会话保存失败，不影响对话：${e.message}）\n`);
+  }
+}
+
+/** 读取会话；不存在或损坏返回 null。 */
+export function loadSession(id) {
+  if (!id) return null;
+  try {
+    const j = JSON.parse(fs.readFileSync(fileOf(id), 'utf8'));
+    if (!j || !Array.isArray(j.messages)) return null;
+    if (!j.id) j.id = id;
+    if (!j.compaction || typeof j.compaction !== 'object') j.compaction = {}; // 旧会话兼容
+    return j;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 列出会话（按更新时间倒序）。cwd 非空时仅列该项目目录的会话。
+ * @returns {{id,title,cwd,model,updatedAt,turns}[]}
+ */
+export function listSessions(cwd) {
+  let files;
+  try {
+    ensureDir();
+    files = fs.readdirSync(SESSIONS_DIR).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const f of files) {
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, f), 'utf8'));
+      if (cwd && j.cwd !== cwd) continue;
+      out.push({
+        id: j.id || f.replace(/\.json$/, ''),
+        title: j.title || deriveTitle(j.messages),
+        cwd: j.cwd,
+        model: j.model,
+        updatedAt: j.updatedAt || 0,
+        turns: turnCount(j.messages),
+      });
+    } catch {
+      // 跳过损坏文件
+    }
+  }
+  out.sort((a, b) => b.updatedAt - a.updatedAt);
+  return out;
+}
+
+/** 当前项目最近一次会话的 id；无则 null。 */
+export function mostRecent(cwd) {
+  const list = listSessions(cwd);
+  return list.length ? list[0].id : null;
+}
+
+/** 删除会话文件。 */
+export function deleteSession(id) {
+  try {
+    fs.unlinkSync(fileOf(id));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 相对时间（如「3 分钟前」）。 */
+export function relTime(ts) {
+  if (!ts) return '未知时间';
+  const s = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+  if (s < 60) return s + ' 秒前';
+  const m = Math.floor(s / 60);
+  if (m < 60) return m + ' 分钟前';
+  const h = Math.floor(m / 60);
+  if (h < 24) return h + ' 小时前';
+  const d = Math.floor(h / 24);
+  return d + ' 天前';
+}

package/src/skills.js

@@ -0,0 +1,237 @@
+// 本地技能（Agent Skills）：发现/读取 <cwd>/.huicai/skills 与 ~/.huicai/skills 下的技能包
+// （<技能名>/SKILL.md + references/scripts 等文本附件），并提供两个动态工具：
+//   load_skill       —— 按需载入技能正文（渐进披露：系统提示词只常驻「名称：描述」目录）
+//   read_skill_file  —— 按需读取技能附件
+// 与平台 skills 表经 /v1/skills 双向同步（huicai skills pull/push），平台即云端技能库。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/** 附件允许的文本扩展名（与平台 SkillFile.TEXT_EXTS 对齐；二进制不收） */
+const TEXT_EXTS = new Set([
+  '.md', '.markdown', '.txt', '.json', '.yaml', '.yml', '.py', '.js', '.mjs', '.cjs', '.ts',
+  '.sh', '.sql', '.csv', '.html', '.css', '.xml', '.toml',
+]);
+const MAX_FILE_BYTES = 256 * 1024;   // 单附件读取上限
+const MAX_FILES = 50;                // 单技能附件数上限
+const MAX_BODY_CHARS = 64 * 1024;    // 载入正文回填上限
+
+/** 解析 SKILL.md 的 YAML frontmatter（零依赖轻量解析：仅顶层 key: value 的 name/description/version）。 */
+export function parseFrontmatter(raw) {
+  const out = { name: '', description: '', version: '', body: (raw || '').trim() };
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(out.body);
+  if (!m) return out;
+  out.body = out.body.slice(m[0].length).trim();
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^(name|description|version)\s*:\s*(.*)$/.exec(line.trim());
+    if (!kv) continue;
+    out[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+/** 技能根目录（项目级优先于全局；不存在的目录由调用方容错）。 */
+export function skillDirs(cwd) {
+  const dirs = [];
+  if (cwd) dirs.push(path.join(cwd, '.huicai', 'skills'));
+  dirs.push(path.join(os.homedir(), '.huicai', 'skills'));
+  return dirs;
+}
+
+/** 递归收集技能目录下 SKILL.md 之外的文本附件（相对路径，深度≤3，数量受限）。 */
+function collectFiles(dir, base = '', depth = 0, out = []) {
+  if (depth > 3 || out.length >= MAX_FILES) return out;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (out.length >= MAX_FILES) break;
+    if (e.name.startsWith('.')) continue;
+    const rel = base ? `${base}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      collectFiles(path.join(dir, e.name), rel, depth + 1, out);
+    } else if (e.isFile() && rel !== 'SKILL.md' && TEXT_EXTS.has(path.extname(e.name).toLowerCase())) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * 发现本地技能（项目级同名覆盖全局）。
+ * @returns {{name:string,description:string,version:string,dir:string,scope:'project'|'global',files:string[]}[]}
+ */
+export function loadLocalSkills(cwd) {
+  const byName = new Map();
+  const dirs = skillDirs(cwd);
+  dirs.forEach((base, i) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const dir = path.join(base, e.name);
+      let raw;
+      try {
+        raw = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8');
+      } catch {
+        continue;
+      }
+      const fm = parseFrontmatter(raw);
+      const name = (fm.name || e.name).trim();
+      if (!name || byName.has(name)) continue;   // 先扫项目级，同名时项目级生效
+      byName.set(name, {
+        name,
+        description: fm.description || '',
+        version: fm.version || '',
+        dir,
+        scope: i === 0 && dirs.length > 1 ? 'project' : 'global',
+        files: collectFiles(dir),
+      });
+    }
+  });
+  return [...byName.values()];
+}
+
+/** 读取技能正文（SKILL.md 全文）；找不到返回 null。 */
+export function readSkillBody(cwd, name) {
+  const skill = loadLocalSkills(cwd).find((s) => s.name === name);
+  if (!skill) return null;
+  try {
+    const raw = fs.readFileSync(path.join(skill.dir, 'SKILL.md'), 'utf8');
+    return { skill, raw: raw.length > MAX_BODY_CHARS ? raw.slice(0, MAX_BODY_CHARS) + '\n…(正文已截断)' : raw };
+  } catch {
+    return null;
+  }
+}
+
+/** 读取技能附件（限制在技能目录内，防路径穿越）；返回文本或抛出可读错误。 */
+export function readSkillFileContent(cwd, skillName, relPath) {
+  const skill = loadLocalSkills(cwd).find((s) => s.name === skillName);
+  if (!skill) throw new Error(`本地技能不存在：${skillName}`);
+  const cleaned = String(relPath || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+  const abs = path.resolve(skill.dir, cleaned);
+  if (!abs.startsWith(path.resolve(skill.dir) + path.sep)) throw new Error(`路径越界：${relPath}`);
+  const stat = fs.statSync(abs);
+  if (stat.size > MAX_FILE_BYTES) throw new Error(`附件过大（>${MAX_FILE_BYTES / 1024}KB）：${cleaned}`);
+  return fs.readFileSync(abs, 'utf8');
+}
+
+/** 技能目录文本（系统提示词注入）；无技能返回空串。 */
+export function skillCatalog(cwd) {
+  const skills = loadLocalSkills(cwd);
+  if (!skills.length) return '';
+  const lines = skills.map((s) => {
+    const desc = (s.description || '（无描述）').replace(/\s+/g, ' ').slice(0, 300);
+    return `- ${s.name}：${desc}`;
+  });
+  return '以下本地技能可用 load_skill(name) 载入其操作指引后遵循执行（描述含「何时使用」，据此判断是否载入；无关任务不要载入）：\n'
+    + lines.join('\n');
+}
+
+/** 构造 load_skill / read_skill_file 动态工具（extraTools 形态：{spec,run,readOnly}）；无本地技能返回 []。 */
+export function makeSkillTools(cwd) {
+  const skills = loadLocalSkills(cwd);
+  if (!skills.length) return [];
+  const tools = [
+    {
+      readOnly: true,
+      spec: {
+        type: 'function',
+        function: {
+          name: 'load_skill',
+          description: '载入一个本地技能的操作指引（系统提示词「可用技能」目录中的名称）。载入后严格遵循其流程执行。',
+          parameters: {
+            type: 'object',
+            properties: { name: { type: 'string', description: '技能名（见「可用技能」目录）' } },
+            required: ['name'],
+          },
+        },
+      },
+      run: async (args) => {
+        const name = String(args?.name || '').trim();
+        const r = readSkillBody(cwd, name);
+        if (!r) {
+          const names = loadLocalSkills(cwd).map((s) => s.name).join(', ');
+          return `本地技能不存在：${name}（可用：${names || '无'}）`;
+        }
+        let text = r.raw;
+        if (r.skill.files.length) {
+          text += `\n\n---\n本技能附带 ${r.skill.files.length} 个资源文件，需要时用 read_skill_file(skill="${name}", path=...) 读取：\n`
+            + r.skill.files.map((f) => `- ${f}`).join('\n');
+        }
+        return text;
+      },
+    },
+  ];
+  if (skills.some((s) => s.files.length)) {
+    tools.push({
+      readOnly: true,
+      spec: {
+        type: 'function',
+        function: {
+          name: 'read_skill_file',
+          description: '读取本地技能附带的资源文件（先 load_skill 查看其文件清单，再按 path 读取）。',
+          parameters: {
+            type: 'object',
+            properties: {
+              skill: { type: 'string', description: '技能名' },
+              path: { type: 'string', description: '资源文件相对路径（技能载入结果中列出）' },
+            },
+            required: ['skill', 'path'],
+          },
+        },
+      },
+      run: async (args) => {
+        try {
+          const content = readSkillFileContent(cwd, String(args?.skill || '').trim(), args?.path);
+          return `文件 ${args?.path}：\n${content}`;
+        } catch (e) {
+          return `读取失败：${e.message}`;
+        }
+      },
+    });
+  }
+  return tools;
+}
+
+/** 把平台技能详情写入本地目录（pull 落盘）：baseDir/<name>/SKILL.md + 附件。返回技能目录路径。 */
+export function writeSkillToDir(baseDir, item) {
+  const name = String(item?.name || '').trim();
+  if (!name || !item?.content) throw new Error('技能数据不完整（缺 name 或 content）');
+  const dir = path.join(baseDir, name.replace(/[^a-zA-Z0-9_-]/g, '-'));
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'SKILL.md'), item.content, 'utf8');
+  for (const f of item.files || []) {
+    const rel = String(f?.path || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+    if (!rel || rel.includes('..')) continue;   // 非法附件路径直接跳过
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, f.content ?? '', 'utf8');
+  }
+  return dir;
+}
+
+/** 读取一个本地技能目录为 push 载荷：{content, filename, files:[{path,content}]}。 */
+export function readSkillDirForPush(dir) {
+  const skillMd = path.join(dir, 'SKILL.md');
+  const content = fs.readFileSync(skillMd, 'utf8');
+  const files = [];
+  for (const rel of collectFiles(dir)) {
+    try {
+      const abs = path.join(dir, rel);
+      if (fs.statSync(abs).size > MAX_FILE_BYTES) continue;
+      files.push({ path: rel, content: fs.readFileSync(abs, 'utf8') });
+    } catch {
+      /* 跳过读不了的附件 */
+    }
+  }
+  return { content, filename: path.basename(dir), files };
+}

package/src/subagent.js

@@ -0,0 +1,81 @@
+// 客户端子智能体（对应平台 dispatch_agent）：
+// 一个内置工具 dispatch_agent，把明确子任务交给「隔离上下文 + 只读工具」的子智能体自主完成，只回传结论。
+// 让主线程上下文保持精简，适合并行/发散的调研、检索、分析类子任务。
+
+import { runTurn } from './agent.js';
+import { createPermissions } from './permissions.js';
+
+const MAX_DEPTH = 2; // 顶层 depth=0；到达上限不再提供 dispatch_agent，防无限递归
+
+/**
+ * 构造 dispatch_agent 工具。达到深度上限返回 null（不暴露委派）。
+ * @param {object} p
+ * @param {object} p.config 运行配置（闭包引用，读时取最新 model）
+ * @param {string} p.cwd 工作目录
+ * @param {{spec:object,run:Function,readOnly:boolean}[]} [p.extraTools] 可传给子智能体的外部工具（仅其只读子集会被采用，通常为 MCP 工具，不含 dispatch 自身）
+ * @param {number} p.depth 当前深度
+ */
+export function makeSubagentTool({ config, cwd, extraTools = [], depth = 0 }) {
+  if (depth >= MAX_DEPTH) return null;
+
+  const spec = {
+    type: 'function',
+    function: {
+      name: 'dispatch_agent',
+      description:
+        '把一个明确、独立、自足的子任务委派给子智能体：它在隔离上下文中自主使用（只读）工具完成后只回传结论。'
+        + '适合可并行的调研/检索/分析类子任务，让主线程上下文保持精简。可多次调用以分解复杂任务。',
+      parameters: {
+        type: 'object',
+        properties: {
+          objective: { type: 'string', description: '要子智能体完成的单一、明确、自足的子任务' },
+          context: { type: 'string', description: '可选：完成该子任务所需的背景信息' },
+        },
+        required: ['objective'],
+      },
+    },
+  };
+
+  // 子智能体只用只读外部工具（如只读 MCP）；内置读工具由 runTurn 默认提供，写/执行被其非交互权限拒绝
+  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 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,
+      io: { write: () => {} }, // 静默：子智能体过程不刷主终端
+    });
+    if (r?.error) return `子智能体执行失败：${r.error}`;
+    const last = [...messages].reverse().find((m) => m.role === 'assistant' && m.content);
+    return last ? last.content : '(子智能体未产出结论)';
+  };
+
+  return { readOnly: true, spec, run };
+}
+
+function subagentPrompt(cwd, context) {
+  let p =
+    '你是一个专注的子智能体，只负责完成主智能体委派的单一子任务。要求：聚焦目标；'
+    + '用可用的只读工具（读文件 / 搜索 / 列目录等）收集信息；直接输出结构清晰、可被主智能体直接复用的最终结论，'
+    + '不要寒暄，也不要复述任务本身。\n工作目录：' + cwd + '\n';
+  if (context && String(context).trim()) p += '\n## 主智能体提供的背景\n' + context + '\n';
+  return p;
+}