@huicai/cli 0.5.1

package/src/colors.js

@@ -0,0 +1,22 @@
+// 极简 ANSI 颜色工具（零依赖）。尊重 NO_COLOR 与非 TTY（管道/重定向时自动关闭颜色）。
+
+const enabled = process.env.NO_COLOR == null && process.env.TERM !== 'dumb' && process.stdout.isTTY;
+
+const wrap = (code) => (s) => (enabled ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+export const c = {
+  reset: '\x1b[0m',
+  bold: wrap('1'),
+  dim: wrap('2'),
+  italic: wrap('3'),
+  underline: wrap('4'),
+  red: wrap('31'),
+  green: wrap('32'),
+  yellow: wrap('33'),
+  blue: wrap('34'),
+  magenta: wrap('35'),
+  cyan: wrap('36'),
+  gray: wrap('90'),
+};
+
+export const colorEnabled = enabled;

package/src/commands.js

@@ -0,0 +1,266 @@
+// 斜杠命令注册表：REPL 与 ink TUI 共用同一套实现（消除两处各自为政的命令清单）。
+// 另支持自定义命令：
+//   <cwd>/.huicai/commands/*.md 与 ~/.huicai/commands/*.md，文件名即命令名，
+//   内容为提示词模板，$ARGUMENTS 占位符替换为命令参数；可选 frontmatter 提供 description。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import { saveConfig } from './config.js';
+import { listModels } from './api.js';
+import { listSessions, relTime, turnCount } from './session.js';
+import { compactNow } from './compaction.js';
+import { loadAllowRules } from './settings.js';
+
+/** /init 的智能体式提示词：让模型实际调研项目后生成/完善 HUICAI.md（而非套静态模板）。 */
+export const INIT_PROMPT =
+  '请为当前项目生成或完善 HUICAI.md（给终端智能体看的项目说明）：'
+  + '先用 list_files/glob/read_file 快速调研项目（技术栈、目录结构、构建/测试/运行命令、代码约定），'
+  + '再用 write_file 创建或更新 HUICAI.md（若已存在则保留人工撰写的内容，增量完善）。'
+  + '内容包含：项目简介、关键目录、常用命令（构建/测试/运行）、代码风格与注意事项。'
+  + '控制在 100 行以内，用中文。';
+
+/**
+ * 内置命令表。run(ctx, arg) 返回：
+ *   undefined            —— 已处理（纯输出）
+ *   {action:'exit'}      —— 退出
+ *   {action:'clear'}     —— 调用方开启新会话
+ *   {prompt:string}      —— 作为用户消息发起一个回合
+ * ctx：{version, config, cwd, usage, permissions, extraTools, session, setSession, print}
+ */
+const BUILTINS = [
+  {
+    name: 'help', desc: '显示可用命令（含自定义命令）',
+    run(ctx) {
+      const rows = BUILTINS.map((b) => [`/${b.name}${b.args ? ' ' + b.args : ''}`, b.desc]);
+      for (const c of loadCustomCommands(ctx.cwd)) rows.push([`/${c.name}`, `${c.desc}（自定义）`]);
+      rows.push(['! <命令>', '直接执行 shell 命令并把输出加入上下文']);
+      rows.push(['@<文件路径>', '在消息中引用文件内容（自动展开给模型）']);
+      const w = Math.min(24, Math.max(...rows.map(([k]) => k.length)) + 2);
+      ctx.print(rows.map(([k, v]) => '  ' + k.padEnd(w) + v).join('\n'));
+    },
+  },
+  {
+    name: 'model', args: '[名称]', desc: '查看或切换模型（带参数切换并保存）',
+    run(ctx, arg) {
+      if (arg) {
+        ctx.config.model = arg;
+        saveConfig({ model: arg });
+        ctx.print('已切换模型：' + arg);
+      } else {
+        ctx.print('当前模型：' + (ctx.config.model || '(未设置)'));
+      }
+    },
+  },
+  {
+    name: 'models', desc: '列出平台可用模型',
+    async run(ctx) {
+      try {
+        const m = await listModels(ctx.config.baseUrl, ctx.config.apiKey);
+        ctx.print(m.map((x) => '  ' + x.id).join('\n') || '(无)');
+      } catch (e) {
+        ctx.print('拉取失败：' + e.message);
+      }
+    },
+  },
+  {
+    name: 'clear', desc: '开启新会话（旧会话仍可 --resume 恢复）',
+    run() {
+      return { action: 'clear' };
+    },
+  },
+  {
+    name: 'compact', desc: '立即压缩上下文（摘要独立存储，不影响页面与会话原文）',
+    async run(ctx) {
+      if (!ctx.session.compaction) ctx.session.compaction = {};
+      const n = await compactNow(ctx.session.messages, ctx.config, { state: ctx.session.compaction });
+      ctx.print(n > 0
+        ? `已压缩：${n} 条较早消息已摘要（原对话完整保留，仅发给模型的上下文变小）`
+        : '暂无可压缩的中段历史（会话较短或摘要失败）');
+    },
+  },
+  {
+    name: 'memory', args: '[clear]', desc: '查看本项目长期记忆（clear 清空）',
+    async run(ctx, arg) {
+      const { loadMemory, clearMemory, memoryPath } = await import('./memory.js');
+      if (arg === 'clear') {
+        ctx.print(clearMemory(ctx.cwd) ? '已清空本项目长期记忆。' : '本项目暂无长期记忆。');
+        return;
+      }
+      const mem = loadMemory(ctx.cwd);
+      ctx.print(mem
+        ? mem + `\n（文件：${memoryPath(ctx.cwd)} · /memory clear 清空）`
+        : '本项目暂无长期记忆（模型会经 memory_write 自动记录值得跨会话记住的信息；配置 memory:false 可关闭）。');
+    },
+  },
+  {
+    name: 'cost', desc: '查看本次运行累计 token 用量',
+    run(ctx) {
+      ctx.print(`token 用量：输入 ${ctx.usage.prompt} / 输出 ${ctx.usage.completion}`
+        + (ctx.session.lastPromptTokens ? ` · 当前上下文 ~${ctx.session.lastPromptTokens} tok` : ''));
+    },
+  },
+  {
+    name: 'status', desc: '显示运行状态（版本/模型/目录/会话/MCP/权限规则）',
+    run(ctx) {
+      const s = ctx.session;
+      const mcpNames = [...new Set(
+        (ctx.extraTools || [])
+          .map((t) => t.spec?.function?.name || '')
+          .filter((n) => n.startsWith('mcp__'))
+          .map((n) => n.split('__')[1]),
+      )];
+      let branch = '';
+      try {
+        branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: ctx.cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+          .toString().trim();
+      } catch { /* 非 git 仓库 */ }
+      const rules = loadAllowRules(ctx.cwd);
+      const lines = [
+        `版本      huicai ${ctx.version || ''}`,
+        `模型      ${ctx.config.model}`,
+        `平台      ${ctx.config.baseUrl}`,
+        `目录      ${ctx.cwd}${branch ? `（git:${branch}）` : ''}`,
+        `会话      ${s.id} · ${turnCount(s.messages)} 轮${s.lastPromptTokens ? ` · 上下文 ~${s.lastPromptTokens} tok` : ''}`,
+        `token     输入 ${ctx.usage.prompt} / 输出 ${ctx.usage.completion}`,
+        `审批      ${ctx.permissions?.isYolo?.() ? '⚠ yolo 自动放行' : '写/执行需授权'} · 允许规则 ${rules.length} 条`,
+        `MCP       ${mcpNames.length ? mcpNames.join(', ') : '(未配置)'}`,
+      ];
+      ctx.print(lines.join('\n'));
+    },
+  },
+  {
+    name: 'sessions', desc: '列出当前目录的历史会话',
+    run(ctx) {
+      const list = listSessions(ctx.cwd);
+      if (!list.length) {
+        ctx.print('该目录暂无历史会话。');
+        return;
+      }
+      const lines = list.slice(0, 15).map((s) => {
+        const mark = s.id === ctx.session.id ? ' ← 当前' : '';
+        return `  ${relTime(s.updatedAt).padStart(8)}  ${s.title}  ${s.turns}轮 · ${s.id}${mark}`;
+      });
+      lines.push('（退出后 huicai --resume 可选择恢复）');
+      ctx.print(lines.join('\n'));
+    },
+  },
+  {
+    name: 'yolo', desc: '切换「自动放行写/执行」模式',
+    run(ctx) {
+      const on = !ctx.permissions.isYolo();
+      ctx.permissions.setYolo(on);
+      ctx.print('自动放行(yolo)：' + (on ? '开（谨慎）' : '关'));
+    },
+  },
+  {
+    name: 'cwd', desc: '显示当前工作目录',
+    run(ctx) {
+      ctx.print(ctx.cwd);
+    },
+  },
+  {
+    name: 'init', desc: '让智能体调研项目并生成/完善 HUICAI.md',
+    run() {
+      return { prompt: INIT_PROMPT };
+    },
+  },
+  {
+    name: 'skills', desc: '列出本地技能（Agent Skills；pull/push 用终端命令 huicai skills）',
+    async run(ctx) {
+      const { loadLocalSkills } = await import('./skills.js');
+      const skills = loadLocalSkills(ctx.cwd);
+      if (!skills.length) {
+        ctx.print('暂无本地技能（.huicai/skills 或 ~/.huicai/skills）。可用 huicai skills pull 从平台拉取。');
+        return;
+      }
+      ctx.print(skills.map((s) =>
+        `  ${s.name}${s.version ? ' v' + s.version : ''}（${s.scope === 'project' ? '项目' : '全局'}`
+        + `${s.files.length ? ` · ${s.files.length} 附件` : ''}）${s.description ? ' ' + s.description.slice(0, 60) : ''}`,
+      ).join('\n') + '\n（模型会按描述经 load_skill 按需载入；本会话启动时已注入目录）');
+    },
+  },
+  {
+    name: 'mcp', desc: '列出已连接的 MCP 工具',
+    run(ctx) {
+      const mcpTools = (ctx.extraTools || []).filter((t) => (t.spec?.function?.name || '').startsWith('mcp__'));
+      if (!mcpTools.length) {
+        ctx.print('未连接 MCP 服务。配置 ~/.huicai/mcp.json（通用 mcpServers 格式）后重启生效。');
+        return;
+      }
+      ctx.print(mcpTools
+        .map((t) => `  ${t.spec.function.name}${t.readOnly ? '（只读）' : ''}`)
+        .join('\n'));
+    },
+  },
+  {
+    name: 'exit', desc: '退出',
+    run() {
+      return { action: 'exit' };
+    },
+  },
+];
+
+/** 读取自定义命令：项目 .huicai/commands/*.md 优先于全局同名。 */
+export function loadCustomCommands(cwd) {
+  const dirs = [
+    cwd ? path.join(cwd, '.huicai', 'commands') : null,
+    path.join(os.homedir(), '.huicai', 'commands'),
+  ].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 name = f.replace(/\.md$/, '').trim();
+      if (!name || byName.has(name) || BUILTINS.some((b) => b.name === name)) continue;
+      try {
+        const raw = fs.readFileSync(path.join(dir, f), 'utf8');
+        const { desc, body } = parseCommandFile(raw);
+        byName.set(name, { name, desc: desc || '自定义命令', template: body });
+      } catch {
+        /* 跳过坏文件 */
+      }
+    }
+  }
+  return [...byName.values()];
+}
+
+function parseCommandFile(raw) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(raw);
+  if (!m) return { desc: '', body: raw.trim() };
+  const fm = m[1];
+  const dm = /^description:\s*(.+)$/m.exec(fm);
+  return { desc: dm ? dm[1].trim() : '', body: raw.slice(m[0].length).trim() };
+}
+
+/**
+ * 处理一条以 / 开头的输入。返回 {handled, action?, prompt?}。
+ * 未知命令也算 handled（打印提示），避免误当普通消息发给模型。
+ */
+export async function runSlash(input, ctx) {
+  const parts = input.slice(1).split(/\s+/);
+  const cmd = (parts[0] || '').trim();
+  const arg = parts.slice(1).join(' ').trim();
+  if (cmd === 'quit') return { handled: true, action: 'exit' }; // /quit 别名
+
+  const builtin = BUILTINS.find((b) => b.name === cmd);
+  if (builtin) {
+    const r = await builtin.run(ctx, arg);
+    return { handled: true, ...(r || {}) };
+  }
+  const custom = loadCustomCommands(ctx.cwd).find((c) => c.name === cmd);
+  if (custom) {
+    let prompt = custom.template;
+    if (prompt.includes('$ARGUMENTS')) prompt = prompt.replaceAll('$ARGUMENTS', arg);
+    else if (arg) prompt = prompt + '\n\n' + arg;
+    return { handled: true, prompt };
+  }
+  ctx.print('未知命令。/help 查看可用命令。');
+  return { handled: true };
+}

package/src/compaction.js

@@ -0,0 +1,140 @@
+// 上下文压缩（非破坏式）：不再删除/改写原始消息——摘要独立存放在 state（随会话持久化），
+// 仅在「发给模型」时用 buildModelMessages() 组装视图：system + 摘要占位 + 未压缩的近期消息。
+// 因此 UI 已显示的对话、落盘会话、分享页/扩展/CLI 的正文都保持完整，压缩只影响送入模型的上下文。
+//
+// state 形状：{ upTo: number, summary: string }
+//   messages[1..upTo) 已被摘要覆盖（0 号是 system）；messages[upTo..] 原样发送。
+// 触发条件（满足其一）：有效上下文字符超阈值；上一轮真实 prompt_tokens 超限。compactNow 手动强制。
+// 切割边界永远取 user 消息下标，天然不拆 assistant(tool_calls) 与其 tool 结果的配对。
+
+import { streamChat } from './api.js';
+import { DEFAULT_MODEL } from './config.js';
+import { stripMarkup } from './markup-filter.js';
+
+const DEFAULT_THRESHOLD_CHARS = 48000; // ≈ 16k tokens
+const DEFAULT_AUTOCOMPACT_TOKENS = 80000; // 上一轮 prompt_tokens 超此值触发（多数模型 128k 窗口的 ~60%）
+const KEEP_RECENT_USER_TURNS = 3;
+
+function totalChars(messages) {
+  let n = 0;
+  for (const m of messages) {
+    if (m.content) n += String(m.content).length;
+    if (m.tool_calls) n += JSON.stringify(m.tool_calls).length;
+  }
+  return n;
+}
+
+/** 组装实际发给模型的消息视图（原 messages 不动）。state 为空/无摘要时原样返回。
+ *  首条消息（通常是 system）永不被摘要覆盖，始终原样保留。 */
+export function buildModelMessages(messages, state) {
+  if (!state || !state.summary || !(state.upTo > 1) || state.upTo > messages.length) return messages;
+  return [
+    ...messages.slice(0, 1),
+    {
+      role: 'user',
+      content: '【上下文压缩】以下是此前多轮对话与工具执行的摘要（原始对话仍完整保留在会话中，仅为节省上下文而摘要）：\n'
+        + state.summary,
+    },
+    ...messages.slice(state.upTo),
+  ];
+}
+
+/**
+ * 若超阈值则把较早回合摘要进 state（原地更新 state，不动 messages）。
+ * @param {any[]} messages 完整消息（含已被摘要覆盖的部分，永不被修改）
+ * @param {object} config baseUrl/apiKey/model/autoCompactTokens
+ * @param {object} [opts] {state, thresholdChars, keepRecent, force, lastPromptTokens}
+ * @returns {Promise<number>} 本次新增被摘要覆盖的消息条数（0=未压缩）
+ */
+export async function compactIfNeeded(messages, config, opts = {}) {
+  const state = opts.state || {};
+  const threshold = opts.thresholdChars || DEFAULT_THRESHOLD_CHARS;
+  const keep = opts.keepRecent || KEEP_RECENT_USER_TURNS;
+  if (!messages || messages.length < 6) return 0;
+
+  const effective = buildModelMessages(messages, state);
+  if (!opts.force) {
+    const tokenLimit = Number(config?.autoCompactTokens) || DEFAULT_AUTOCOMPACT_TOKENS;
+    const overTokens = Number(opts.lastPromptTokens) > tokenLimit;
+    const overChars = totalChars(effective) > threshold;
+    if (!overTokens && !overChars) return 0;
+  }
+
+  // 候选切点：位于当前 upTo 之后的 user 消息下标；保留最近 keep 个用户轮
+  const from = Math.max(Number(state.upTo) || 1, 1);
+  const userIdx = [];
+  for (let i = from; i < messages.length; i++) if (messages[i].role === 'user') userIdx.push(i);
+  if (userIdx.length <= keep) return 0; // 新增部分轮数太少，无可压
+  const newUpTo = userIdx[userIdx.length - keep];
+  if (newUpTo - from < 2) return 0;
+
+  const slice = messages.slice(from, newUpTo);
+  let summary;
+  try {
+    summary = await summarize(slice, config, state.summary);
+  } catch {
+    return 0; // 摘要失败：不压缩（宁可上下文长，也不丢历史）
+  }
+  if (!summary || !summary.trim()) return 0;
+
+  state.summary = summary.trim();
+  state.upTo = newUpTo;
+  return newUpTo - from;
+}
+
+/** 手动强制压缩（/compact）：忽略阈值。返回本次被摘要覆盖的消息条数。 */
+export function compactNow(messages, config, opts = {}) {
+  return compactIfNeeded(messages, config, { ...opts, force: true });
+}
+
+// 伪模型（agent-/workflow-/datahuman-）在服务端走完整编排（RAG/工具/计费）。
+// 摘要是纯内部辅助调用，必须与用户的业务对话彻底分离：绝不能用伪模型跑摘要，
+// 否则每次压缩都会额外触发一次智能体执行（副作用+计费），且人格会污染摘要内容。
+const PSEUDO_MODEL_RE = /^(agent|workflow|datahuman)-/;
+
+/** 摘要专用模型：显式 compactModel 优先；当前模型为伪模型时回退内置默认原始模型。 */
+function summaryModel(config) {
+  if (config?.compactModel) return config.compactModel;
+  const m = config?.model || '';
+  return PSEUDO_MODEL_RE.test(m) ? DEFAULT_MODEL : m;
+}
+
+async function summarize(slice, config, prevSummary) {
+  const parts = [];
+  if (prevSummary && prevSummary.trim()) parts.push('【先前的摘要（需并入新摘要）】\n' + prevSummary.trim());
+  parts.push(renderForSummary(slice));
+  const r = await streamChat({
+    baseUrl: config.baseUrl,
+    apiKey: config.apiKey,
+    model: summaryModel(config),
+    messages: [
+      {
+        role: 'system',
+        content:
+          '你是对话/执行记录压缩器。把下面的记录（含可能存在的先前摘要）压缩成一份简洁但信息完整的中文摘要：'
+          + '保留已完成的关键步骤、工具得到的重要事实/数据/结论、涉及的文件路径、尚未解决的问题与下一步线索。'
+          + '只依据记录、不要臆造、不要寒暄。',
+      },
+      { role: 'user', content: parts.join('\n\n') },
+    ],
+  }); // 无 handlers：非流式收集
+  // 摘要会注入后续上下文：清洗文本化工具标记，防止协议乱码经摘要回流、继续诱发模型格式退化
+  return stripMarkup(r.content).text;
+}
+
+function renderForSummary(messages) {
+  const lines = [];
+  for (const m of messages) {
+    if (m.role === 'assistant' && m.tool_calls?.length) {
+      const calls = m.tool_calls
+        .map((tc) => `${tc.function?.name}(${String(tc.function?.arguments || '').slice(0, 200)})`)
+        .join(' ');
+      lines.push(`[助手调用工具] ${calls}${m.content ? ' ｜ ' + m.content : ''}`);
+    } else if (m.role === 'tool') {
+      lines.push(`[工具结果] ${String(m.content || '').slice(0, 800)}`);
+    } else if (m.content) {
+      lines.push(`[${m.role}] ${m.content}`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/config.js

@@ -0,0 +1,64 @@
+// 配置读写：~/.huicai/config.json（含 baseUrl / apiKey / model），环境变量优先覆盖。
+// apiKey 敏感：写入时置文件权限 0600。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const CONFIG_DIR = path.join(os.homedir(), '.huicai');
+export const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+
+/** 平台默认地址（内置，用户无需输入网关地址；可用 HUICAI_BASE_URL / --base 覆盖，供自建/联调）。 */
+export const DEFAULT_BASE_URL = 'https://huicai-ai.sjht.com';
+
+/** 内置默认模型（用户未设置时用它；登录时若账号有它则优先，否则回退到账号的第一个原始模型）。 */
+export const DEFAULT_MODEL = 'deepseek-v4-flash';
+
+function readFileConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 解析生效配置：环境变量 > 配置文件 > 缺省。
+ * @returns {{baseUrl:string, apiKey:string, model:string}}
+ */
+export function loadConfig() {
+  const file = readFileConfig();
+  const cfg = {
+    // 网关地址内置默认，用户无需输入；仍可用环境变量/配置文件覆盖（自建或联调）
+    baseUrl: (process.env.HUICAI_BASE_URL || file.baseUrl || DEFAULT_BASE_URL).trim(),
+    apiKey: (process.env.HUICAI_API_KEY || file.apiKey || '').trim(),
+    model: (process.env.HUICAI_MODEL || file.model || DEFAULT_MODEL).trim(),
+    // 单回合最大工具轮数（0/缺省 = 用内置默认 60）；可被 --max-turns 覆盖
+    maxTurns: Number(process.env.HUICAI_MAX_TURNS || file.maxTurns) || 0,
+    // 自动压缩触发的 prompt_tokens 上限（缺省用 compaction 内置默认 80000）
+    autoCompactTokens: Number(file.autoCompactTokens) || 0,
+    // 压缩摘要专用模型（缺省：当前模型；当前为伪模型时 compaction 内部回退 DEFAULT_MODEL——摘要绝不经智能体编排）
+    compactModel: (process.env.HUICAI_COMPACT_MODEL || file.compactModel || '').trim(),
+    // 长期记忆（memory_write + 系统提示词注入）：默认开；配置 memory:false 或 HUICAI_MEMORY=0 关闭
+    memoryEnabled: process.env.HUICAI_MEMORY === '0' ? false : file.memory !== false,
+    // 思考过程流式展示：默认开；配置 showReasoning:false 或 HUICAI_REASONING=0 关闭
+    showReasoning: process.env.HUICAI_REASONING === '0' ? false : file.showReasoning !== false,
+    // 客户端来源标识（对话落库审计用）：默认 cli；VSCode 扩展进程内置 HUICAI_CLIENT=vscode
+    client: (process.env.HUICAI_CLIENT || 'cli').trim().toLowerCase(),
+  };
+  cfg.baseUrl = cfg.baseUrl.replace(/\/+$/, ''); // 去尾斜杠
+  return cfg;
+}
+
+/** 合并写入配置文件（0600），返回合并结果。 */
+export function saveConfig(partial) {
+  const merged = { ...readFileConfig(), ...partial };
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(merged, null, 2) + '\n', { mode: 0o600 });
+  try {
+    fs.chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    // 非 POSIX 忽略
+  }
+  return merged;
+}

package/src/context.js

@@ -0,0 +1,144 @@
+// 组装系统提示词：人格 + 工作准则 + 运行环境（cwd/OS/git/顶层文件）
+// + 项目说明文件（HUICAI.md/AGENTS.md/CLAUDE.md）+ 全局用户说明（~/.huicai/HUICAI.md）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import { loadMemory } from './memory.js';
+import { skillCatalog } from './skills.js';
+
+function git(cwd) {
+  const run = (cmd) => execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  try {
+    const branch = run('git rev-parse --abbrev-ref HEAD');
+    let status = '';
+    try {
+      status = run('git status --short');
+    } catch {
+      /* ignore */
+    }
+    return { branch, status };
+  } catch {
+    return null;
+  }
+}
+
+function topLevel(cwd) {
+  try {
+    return fs
+      .readdirSync(cwd, { withFileTypes: true })
+      .filter((e) => e.name !== '.git' && e.name !== 'node_modules')
+      .slice(0, 60)
+      .map((e) => (e.isDirectory() ? e.name + '/' : e.name))
+      .join('  ');
+  } catch {
+    return '';
+  }
+}
+
+function projectDoc(cwd) {
+  for (const name of ['HUICAI.md', 'AGENTS.md', 'CLAUDE.md']) {
+    try {
+      const s = fs.readFileSync(path.join(cwd, name), 'utf8');
+      if (s.trim()) return { name, content: s.slice(0, 8000) };
+    } catch {
+      /* next */
+    }
+  }
+  return null;
+}
+
+/** 全局用户说明（~/.huicai/HUICAI.md）：跨项目的个人偏好/约定。 */
+function globalDoc() {
+  try {
+    const s = fs.readFileSync(path.join(os.homedir(), '.huicai', 'HUICAI.md'), 'utf8');
+    return s.trim() ? s.slice(0, 4000) : null;
+  } catch {
+    return null;
+  }
+}
+
+const GUIDELINES = [
+  '- 先了解现状再动手：并行使用 read_file/glob/grep/list_files 收集信息（一轮可同时调多个只读工具），不要臆测文件内容。',
+  '- read_file 输出的「行号→」前缀仅供定位，不是文件内容；写 edit_file 的 old_string/new_string 时绝不能包含行号前缀。',
+  '- 多步骤任务先用 todo_write 列出计划，并随进度更新状态（同一时刻至多一项 in_progress）；单步小事不必用。',
+  '- 改代码优先用 edit_file 做最小精确改动；新建文件才用 write_file。遵循项目既有风格与命名。',
+  '- 用 run_bash 执行构建/测试/git 等；改动后尽量运行测试或构建自检，失败要定位修复而不是忽略。',
+  '- 需要在线资料（文档/API 说明）可用 fetch_url；带明确目的使用，不要漫游。',
+  '- 破坏性或不可逆操作（删除、强推、重置等）前先说明意图；写/执行类工具会请用户授权，被拒绝时据反馈调整方案。',
+  '- 不要把密钥、令牌等敏感值回显到输出或写进代码。',
+  '- 简洁直接，用中文回答；完成后用一两句话总结改了什么、如何验证的。',
+];
+
+/**
+ * 组装系统提示词。
+ * @param {string} cwd 工作目录
+ * @param {{persona?:string, append?:string}} [opts]
+ *   persona 非空时以该智能体人格领衔（--agent 模式），但保留本机工具/环境说明；
+ *   append 追加在末尾（--append-system-prompt）。
+ */
+export function buildSystemPrompt(cwd, opts = {}) {
+  const g = git(cwd);
+  const doc = projectDoc(cwd);
+  const gdoc = globalDoc();
+  let p = '';
+  if (opts.persona && opts.persona.trim()) {
+    p += '# 你的角色设定\n' + opts.persona.trim() + '\n\n';
+    p += '# 运行方式\n';
+    p += '你现在运行在用户终端里，可通过工具在用户本机的项目里读写文件、搜索、执行 shell 命令来真正完成任务。请在保持上述角色设定的前提下遵循以下准则：\n';
+  } else {
+    p += '你是 huicai，一个运行在用户终端里的专业自治编码与自动化智能体。\n';
+    p += '你能通过工具在用户本机的项目里读写文件、搜索、执行 shell 命令，从而真正完成任务，而不仅是给建议。\n\n';
+    p += '# 工作准则\n';
+  }
+  p += GUIDELINES.join('\n') + '\n\n';
+  p += '# 运行环境\n';
+  p += `- 工作目录: ${cwd}\n`;
+  p += `- 操作系统: ${os.platform()} ${os.release()} (${os.arch()})\n`;
+  p += `- 日期: ${new Date().toISOString().slice(0, 10)}\n`;
+  if (g) {
+    p += `- Git 分支: ${g.branch}\n`;
+    if (g.status) {
+      const lines = g.status.split('\n').slice(0, 30).map((l) => '    ' + l).join('\n');
+      p += `- 未提交改动:\n${lines}\n`;
+    }
+  }
+  const top = topLevel(cwd);
+  if (top) p += `- 顶层条目: ${top}\n`;
+  const editor = editorContext();
+  if (editor) p += '\n# 编辑器上下文（来自 IDE 集成）\n' + editor;
+  if (gdoc) p += `\n# 全局用户说明（~/.huicai/HUICAI.md）\n${gdoc}\n`;
+  if (doc) p += `\n# 项目说明（${doc.name}）\n${doc.content}\n`;
+  // 本地技能目录（渐进披露：仅名称+描述常驻，正文经 load_skill 按需载入）
+  const skills = skillCatalog(cwd);
+  if (skills) p += `\n# 可用技能（本地 Agent Skills）\n${skills}\n`;
+  if (opts.memory !== false) {
+    const mem = loadMemory(cwd);
+    if (mem) {
+      p += `\n# 长期记忆（此前会话经 memory_write 记录，跨会话生效）\n${mem}\n`;
+      p += '（发现新的、值得跨会话记住的稳定事实/偏好/结论时，用 memory_write 记录。）\n';
+    }
+  }
+  if (opts.append && String(opts.append).trim()) p += '\n# 附加指示\n' + String(opts.append).trim() + '\n';
+  return p;
+}
+
+/** VS Code 等 IDE 扩展经环境变量注入的当前编辑上下文：正在编辑的文件 + 选中片段 + 诊断（Problems）。 */
+function editorContext() {
+  const file = process.env.HUICAI_IDE_FILE;
+  const selection = process.env.HUICAI_IDE_SELECTION;
+  const diagnostics = process.env.HUICAI_IDE_DIAGNOSTICS;
+  if (!file && !selection && !diagnostics) return '';
+  let s = '';
+  if (file) s += `- 用户当前正在编辑的文件: ${file}\n`;
+  if (selection) {
+    const clipped = selection.length > 4000 ? selection.slice(0, 4000) + '\n…(选区已截断)' : selection;
+    s += '- 用户当前选中的代码片段：\n```\n' + clipped + '\n```\n';
+  }
+  if (diagnostics) {
+    const clipped = diagnostics.length > 4000 ? diagnostics.slice(0, 4000) + '\n…(诊断已截断)' : diagnostics;
+    s += '- 编辑器诊断（错误/警告，来自 Problems 面板）：\n```\n' + clipped + '\n```\n';
+  }
+  return s;
+}