@huicai/cli 0.5.1

package/src/markup-filter.js

@@ -0,0 +1,85 @@
+// 模型「文本化工具调用」防泄漏过滤器（与平台侧 huicai-agent 的 ToolMarkupFilter 同款状态机）。
+//
+// 部分模型（如 DeepSeek 系）在长上下文/上下文压缩后会格式退化：不走 function calling 特殊通道，
+// 而把工具调用以纯文本标记写进正文（如 <｜｜DSML｜｜tool_calls>…、<｜tool▁calls▁begin｜>…）。
+// 这种「调用」不会出现在 tool_calls 里、也不会被执行；若照原样显示，终端/扩展面板会出现成片协议乱码，
+// 且答非所问。CLI 直连原始模型（平台 /v1 为透明代理，不代过滤），须在客户端做同样的拦截。
+//
+// 流式状态机：正常文本原样放行；遇疑似起始符 <| / <｜ 先持有，在确认窗口内命中工具标记特征
+// （dsml / tool_call / tool▁call / function_call…）→ 进入吞噬模式，本轮剩余内容全部丢弃
+// （此类输出一旦开始，其后即整段协议块，无用户价值）；窗口内未命中 → 原样放行
+// （不误杀正文中的 <|x|> 字面量）。每轮模型输出使用独立实例。
+
+/** 起始符确认窗口：起始符后至多累计这么多字符仍未命中特征则放行。 */
+const CONFIRM_WINDOW = 48;
+
+/** 工具标记特征（起始符后窗口内匹配）：DSML / tool_calls / tool▁calls / function_call 等变体。 */
+const MARKUP_RE = /dsml|tool[_▁]?call|function[_▁]?call/i;
+
+/** 找到最早的疑似起始符（<| 或 <｜）下标，无则 -1。 */
+function markerStart(s) {
+  for (let i = 0; i < s.length - 1; i++) {
+    if (s[i] === '<' && (s[i + 1] === '|' || s[i + 1] === '｜')) return i;
+  }
+  return -1;
+}
+
+export class MarkupFilter {
+  constructor() {
+    this.held = '';
+    this.swallowing = false;
+    /** 本轮是否检出过文本化工具标记。 */
+    this.sawMarkup = false;
+  }
+
+  /** 喂入一段增量，返回可安全下发的文本（可能为空串）。 */
+  feed(delta) {
+    if (!delta || this.swallowing) return '';
+    this.held += delta;
+    let out = '';
+    for (;;) {
+      const idx = markerStart(this.held);
+      if (idx < 0) {
+        // 无疑似起始：保留可能被增量边界截断的尾部 '<'，其余放行
+        const keep = this.held.endsWith('<') ? 1 : 0;
+        out += this.held.slice(0, this.held.length - keep);
+        this.held = keep ? '<' : '';
+        return out;
+      }
+      out += this.held.slice(0, idx);
+      this.held = this.held.slice(idx);
+      // held 现以 <| 或 <｜ 开头：在确认窗口内判定
+      if (MARKUP_RE.test(this.held.slice(0, CONFIRM_WINDOW))) {
+        this.swallowing = true;
+        this.sawMarkup = true;
+        this.held = '';
+        return out;
+      }
+      if (this.held.length < CONFIRM_WINDOW) return out; // 证据不足：持有等待更多增量
+      // 窗口已满仍非标记：放行起始两字符，继续扫描其后内容
+      out += this.held.slice(0, 2);
+      this.held = this.held.slice(2);
+    }
+  }
+
+  /** 流结束：放行仍在持有的未确认内容（吞噬中则丢弃）。 */
+  flush() {
+    if (this.swallowing) {
+      this.held = '';
+      return '';
+    }
+    const rest = this.held;
+    this.held = '';
+    return rest;
+  }
+}
+
+/**
+ * 一次性清洗全量文本（等价于流式 feed+flush）。
+ * @returns {{text:string, sawMarkup:boolean}} text 为清洗后的安全文本（null/空入参返回空串）
+ */
+export function stripMarkup(content) {
+  if (!content) return { text: '', sawMarkup: false };
+  const f = new MarkupFilter();
+  return { text: f.feed(content) + f.flush(), sawMarkup: f.sawMarkup };
+}

package/src/mcp.js

@@ -0,0 +1,207 @@
+// 本地 MCP 客户端（零依赖）：按 ~/.huicai/mcp.json 启动本地 MCP 服务（stdio 传输，JSON-RPC 2.0，
+// 换行分隔），握手后拉取其工具，暴露给 Agent 循环调用。配置形状为通用 mcpServers 格式：
+//   { "mcpServers": { "<名>": { "command": "npx", "args": ["-y","@modelcontextprotocol/server-filesystem","<路径>"], "env": {} } } }
+// 未配置该文件时完全无副作用（返回空工具集）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { CONFIG_DIR } from './config.js';
+import { c } from './colors.js';
+
+export const MCP_CONFIG_PATH = path.join(CONFIG_DIR, 'mcp.json');
+
+const INIT_TIMEOUT = 20_000;
+const CALL_TIMEOUT = 120_000;
+const PROTOCOL_VERSION = '2024-11-05';
+
+/** 单个 MCP 服务的 stdio JSON-RPC 客户端。 */
+class McpStdioClient {
+  constructor(name, spec) {
+    this.name = name;
+    this.spec = spec;
+    this.child = null;
+    this.buffer = '';
+    this.nextId = 1;
+    this.pending = new Map(); // id -> {resolve, reject, timer}
+    this.closed = false;
+  }
+
+  async start() {
+    const env = { ...process.env, ...(this.spec.env || {}) };
+    this.child = spawn(this.spec.command, this.spec.args || [], {
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    this.child.on('error', (e) => this._failAll(new Error(`MCP[${this.name}] 进程错误：${e.message}`)));
+    this.child.on('exit', () => {
+      this.closed = true;
+      this._failAll(new Error(`MCP[${this.name}] 进程已退出`));
+    });
+    this.child.stdout.setEncoding('utf8');
+    this.child.stdout.on('data', (chunk) => this._onData(chunk));
+    // stderr 仅调试用，静默丢弃避免污染 TUI
+    this.child.stderr.on('data', () => {});
+
+    // 握手：initialize -> notifications/initialized
+    await this._request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'huicai-cli', version: '0.2.0' },
+    }, INIT_TIMEOUT);
+    this._notify('notifications/initialized', {});
+  }
+
+  async listTools() {
+    const res = await this._request('tools/list', {}, INIT_TIMEOUT);
+    return Array.isArray(res?.tools) ? res.tools : [];
+  }
+
+  async callTool(toolName, args) {
+    const res = await this._request('tools/call', { name: toolName, arguments: args || {} }, CALL_TIMEOUT);
+    // 结果内容为 content 数组（text/其它）；拼接 text 回填模型
+    const parts = Array.isArray(res?.content) ? res.content : [];
+    const text = parts
+      .map((p) => (p?.type === 'text' ? p.text : p?.text || JSON.stringify(p)))
+      .filter(Boolean)
+      .join('\n');
+    if (res?.isError) return `工具报错：${text || '(无详情)'}`;
+    return text || '(无输出)';
+  }
+
+  close() {
+    this.closed = true;
+    try {
+      this.child?.kill('SIGTERM');
+    } catch {
+      /* ignore */
+    }
+  }
+
+  _onData(chunk) {
+    this.buffer += chunk;
+    let idx;
+    while ((idx = this.buffer.indexOf('\n')) >= 0) {
+      const line = this.buffer.slice(0, idx).trim();
+      this.buffer = this.buffer.slice(idx + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue; // 非 JSON 行（部分服务打印日志到 stdout）忽略
+      }
+      if (msg.id != null && this.pending.has(msg.id)) {
+        const { resolve, reject, timer } = this.pending.get(msg.id);
+        clearTimeout(timer);
+        this.pending.delete(msg.id);
+        if (msg.error) reject(new Error(msg.error.message || 'MCP 错误'));
+        else resolve(msg.result);
+      }
+      // 服务端通知（无匹配 id）忽略
+    }
+  }
+
+  _request(method, params, timeoutMs) {
+    if (this.closed) return Promise.reject(new Error(`MCP[${this.name}] 已关闭`));
+    const id = this.nextId++;
+    const payload = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`MCP[${this.name}] ${method} 超时`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        this.child.stdin.write(payload);
+      } catch (e) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(e);
+      }
+    });
+  }
+
+  _notify(method, params) {
+    try {
+      this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+    } catch {
+      /* ignore */
+    }
+  }
+
+  _failAll(err) {
+    for (const { reject, timer } of this.pending.values()) {
+      clearTimeout(timer);
+      reject(err);
+    }
+    this.pending.clear();
+  }
+}
+
+/** 规整为合法 OpenAI 函数名。 */
+function sanitize(name) {
+  const s = String(name).replace(/[^a-zA-Z0-9_-]/g, '_');
+  return s.length > 60 ? s.slice(0, 60) : s;
+}
+
+function readConfig() {
+  try {
+    const j = JSON.parse(fs.readFileSync(MCP_CONFIG_PATH, 'utf8'));
+    return j?.mcpServers && typeof j.mcpServers === 'object' ? j.mcpServers : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 启动所有已配置的 MCP 服务并汇集其工具。
+ * @returns {Promise<{tools:{spec:object,run:Function,readOnly:boolean}[], clients:McpStdioClient[]}>}
+ */
+export async function loadMcpTools() {
+  const servers = readConfig();
+  const names = Object.keys(servers);
+  const tools = [];
+  const clients = [];
+  if (names.length === 0) return { tools, clients };
+
+  for (const name of names) {
+    const spec = servers[name] || {};
+    if (!spec.command) continue;
+    const client = new McpStdioClient(name, spec);
+    try {
+      await client.start();
+      const mcpTools = await client.listTools();
+      clients.push(client);
+      for (const t of mcpTools) {
+        const realName = t.name;
+        const fnName = sanitize(`mcp__${name}__${realName}`);
+        const readOnly = t.annotations?.readOnlyHint === true;
+        tools.push({
+          readOnly,
+          spec: {
+            type: 'function',
+            function: {
+              name: fnName,
+              description: `[MCP:${name}] ${t.description || realName}`,
+              parameters: t.inputSchema && typeof t.inputSchema === 'object'
+                ? t.inputSchema
+                : { type: 'object', properties: {} },
+            },
+          },
+          run: (args) => client.callTool(realName, args),
+        });
+      }
+      process.stdout.write(c.gray(`  · MCP[${name}] 已连接，工具 ${mcpTools.length} 个`) + '\n');
+    } catch (e) {
+      client.close();
+      process.stdout.write(c.yellow(`  · MCP[${name}] 加载失败，已跳过：${e.message}`) + '\n');
+    }
+  }
+  return { tools, clients };
+}
+
+/** 关闭全部 MCP 子进程。 */
+export function closeMcp(clients) {
+  for (const c2 of clients || []) c2.close();
+}

package/src/memory.js

@@ -0,0 +1,110 @@
+// 长期记忆（跨会话）：按项目目录归属，存于 ~/.huicai/memory/<hash>.md。
+// 模型经内置 memory_write 工具主动记录「值得跨会话记住的事实」（用户偏好、项目结论、约定等），
+// 每次新会话由 context.js 注入系统提示词——即「长期记忆」；「短期记忆」= 会话消息 + 非破坏式上下文压缩摘要。
+// 开关：config.memoryEnabled（默认开，配置 memory:false 或环境变量 HUICAI_MEMORY=0 关闭）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { CONFIG_DIR } from './config.js';
+
+export const MEMORY_DIR = path.join(CONFIG_DIR, 'memory');
+const MAX_MEMORY_CHARS = 6000; // 注入系统提示词的上限（超出保留最新条目）
+const MAX_ENTRY_CHARS = 1000;
+
+export function memoryPath(cwd) {
+  const h = crypto.createHash('sha1').update(String(cwd || '')).digest('hex').slice(0, 12);
+  return path.join(MEMORY_DIR, h + '.md');
+}
+
+/** 读取该项目的长期记忆（超限保尾部=最新条目）。无则空串。 */
+export function loadMemory(cwd) {
+  try {
+    const s = fs.readFileSync(memoryPath(cwd), 'utf8');
+    if (s.length <= MAX_MEMORY_CHARS) return s.trim();
+    const tail = s.slice(-MAX_MEMORY_CHARS);
+    const nl = tail.indexOf('\n');
+    return ('…（较早记忆已省略）\n' + (nl >= 0 ? tail.slice(nl + 1) : tail)).trim();
+  } catch {
+    return '';
+  }
+}
+
+/** 追加一条记忆（带日期，best-effort）。返回是否成功。 */
+export function appendMemory(cwd, content) {
+  const t = String(content || '').trim();
+  if (!t) return false;
+  try {
+    fs.mkdirSync(MEMORY_DIR, { recursive: true });
+    const entry = `- [${new Date().toISOString().slice(0, 10)}] ${t.slice(0, MAX_ENTRY_CHARS)}\n`;
+    const p = memoryPath(cwd);
+    if (!fs.existsSync(p)) {
+      fs.writeFileSync(p, `# 长期记忆（${cwd}）\n\n${entry}`, { mode: 0o600 });
+    } else {
+      fs.appendFileSync(p, entry);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 整体重写记忆（模型做记忆整理时用）。 */
+export function replaceMemory(cwd, content) {
+  try {
+    fs.mkdirSync(MEMORY_DIR, { recursive: true });
+    fs.writeFileSync(memoryPath(cwd), String(content || '').slice(0, MAX_MEMORY_CHARS * 2), { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function clearMemory(cwd) {
+  try {
+    fs.unlinkSync(memoryPath(cwd));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 构造 memory_write 内置工具（顶层注入；记忆是机制本身，自动放行）。
+ * @param {{cwd:string, emit?:(text:string)=>void}} p
+ */
+export function makeMemoryTool({ cwd, emit }) {
+  const spec = {
+    type: 'function',
+    function: {
+      name: 'memory_write',
+      description:
+        '把值得跨会话记住的信息写入本项目的长期记忆（用户偏好、项目关键事实/约定、踩坑结论等）。'
+        + '新会话会自动注入这些记忆。仅记「以后仍然有用」的稳定信息；不要记一次性细节或大段代码。'
+        + 'mode=append 追加一条（默认）；mode=replace 用整理后的全文替换（做记忆瘦身时用）。',
+      parameters: {
+        type: 'object',
+        properties: {
+          content: { type: 'string', description: '要记住的内容（简洁的一条事实/偏好/结论）' },
+          mode: { type: 'string', enum: ['append', 'replace'], description: '追加或整体替换（默认 append）' },
+        },
+        required: ['content'],
+      },
+    },
+  };
+  const run = async (args) => {
+    const content = String(args?.content || '').trim();
+    if (!content) return 'memory_write 需要非空 content';
+    const ok = args?.mode === 'replace' ? replaceMemory(cwd, content) : appendMemory(cwd, content);
+    if (ok) {
+      try {
+        emit?.(content);
+      } catch {
+        /* ignore */
+      }
+      return `已写入长期记忆（${args?.mode === 'replace' ? '整体替换' : '追加'}）。`;
+    }
+    return '长期记忆写入失败（磁盘不可写？），可忽略并继续任务。';
+  };
+  return { readOnly: true, spec, run };
+}

package/src/permissions.js

@@ -0,0 +1,82 @@
+// 权限/审批：只读工具自动放行；写/执行需授权（y 一次 / a 本会话该工具 / A 永久写入项目设置 / 否可附原因）。
+// 另支持 settings.json 允许规则（全局 ~/.huicai + 项目 .huicai，见 settings.js）。
+// yolo 模式全放行；非交互（无 ask）且非 yolo 时拒绝写/执行并把原因回灌模型，让它调整策略。
+
+import { c } from './colors.js';
+import { toolLabel, renderEditDiff, indent } from './render.js';
+import { loadAllowRules, matchAllowRules, suggestRule, addProjectAllowRule, riskWarning } from './settings.js';
+
+export function createPermissions({ yolo = false, ask = null, cwd = null } = {}) {
+  const sessionAllowed = new Set();
+  let autoAll = !!yolo;
+  // 仅在给定 cwd 时读取 settings 允许规则（测试等场景不受用户本机全局配置影响）
+  let rules = cwd ? loadAllowRules(cwd) : [];
+
+  // readOnly 由调用方判定（内置工具查 READONLY_TOOLS；MCP 工具看 readOnlyHint；子智能体只读）
+  async function request(name, args, _cwd, readOnly = false) {
+    if (readOnly) return { allow: true };
+    if (autoAll || sessionAllowed.has(name)) return { allow: true };
+    if (rules.length && matchAllowRules(rules, name, args)) return { allow: true };
+    if (!ask) {
+      return { allow: false, reason: '当前为非交互模式，未授权写/执行操作（加 --yolo 可自动放行）。' };
+    }
+    printPreview(name, args);
+    const raw = (await ask(
+      `${c.yellow('允许执行?')} [y]是 · [a]本会话该工具 · [A]永久允许(写入项目设置) · [N]否(可附原因): `,
+    )) || '';
+    const answer = raw.trim();
+    if (answer === 'a') {
+      sessionAllowed.add(name);
+      return { allow: true };
+    }
+    if (answer === 'A') {
+      sessionAllowed.add(name);
+      if (cwd) {
+        const rule = suggestRule(name, args);
+        try {
+          const p = addProjectAllowRule(cwd, rule);
+          rules = loadAllowRules(cwd);
+          process.stdout.write(c.gray(`  已写入规则 ${rule} → ${p}`) + '\n');
+        } catch (e) {
+          process.stdout.write(c.yellow(`  规则写入失败（本会话仍生效）：${e.message}`) + '\n');
+        }
+      }
+      return { allow: true };
+    }
+    const lower = answer.toLowerCase();
+    if (lower === 'y' || lower === 'yes') return { allow: true };
+    if (answer === '' || lower === 'n' || lower === 'no') {
+      return { allow: false, reason: '用户拒绝了该操作。' };
+    }
+    return { allow: false, reason: `用户拒绝并说明：${answer}` };
+  }
+
+  return {
+    request,
+    setYolo(v) {
+      autoAll = !!v;
+    },
+    isYolo() {
+      return autoAll;
+    },
+  };
+}
+
+function printPreview(name, args) {
+  process.stdout.write('\n' + c.bold(c.yellow('● 需要授权：')) + toolLabel(name, args) + '\n');
+  const risk = riskWarning(name, args);
+  if (risk) process.stdout.write('  ' + c.bold(c.red('⚠ ' + risk)) + '\n');
+  if (name === 'run_bash') {
+    process.stdout.write(c.gray('  $ ') + String(args.command ?? '') + '\n');
+  } else if (name === 'write_file') {
+    const preview = String(args.content ?? '')
+      .split('\n')
+      .slice(0, 12)
+      .join('\n');
+    process.stdout.write(c.gray(`  将写入 ${args.path}:`) + '\n' + indent(preview) + '\n');
+  } else if (name === 'edit_file') {
+    process.stdout.write(c.gray(`  编辑 ${args.path}:`) + '\n' + indent(renderEditDiff(args.old_string, args.new_string)) + '\n');
+  } else if (name === 'fetch_url') {
+    process.stdout.write(c.gray('  GET ') + String(args.url ?? '') + '\n');
+  }
+}

package/src/render.js

@@ -0,0 +1,55 @@
+// 终端渲染小工具：工具调用标签、编辑 diff。
+
+import { c } from './colors.js';
+
+/** 把一次工具调用渲染成简洁的一行标签。 */
+export function toolLabel(name, args = {}) {
+  switch (name) {
+    case 'read_file':
+      return `read_file ${args.path ?? ''}`;
+    case 'list_files':
+      return `list_files ${args.path ?? '.'}`;
+    case 'glob':
+      return `glob ${args.pattern ?? ''}`;
+    case 'grep':
+      return `grep ${JSON.stringify(args.pattern ?? '')}${args.path ? ' in ' + args.path : ''}`;
+    case 'write_file':
+      return `write_file ${args.path ?? ''}`;
+    case 'edit_file':
+      return `edit_file ${args.path ?? ''}`;
+    case 'run_bash':
+      return `run_bash: ${String(args.command ?? '').split('\n')[0]}`;
+    case 'fetch_url':
+      return `fetch_url ${args.url ?? ''}`;
+    case 'todo_write':
+      return 'todo_write（更新任务清单）';
+    case 'dispatch_agent': {
+      const o = String(args.objective ?? '').split('\n')[0];
+      return `dispatch_agent: ${o.length > 60 ? o.slice(0, 60) + '…' : o}`;
+    }
+    default:
+      return `${name}(${Object.keys(args).join(', ')})`;
+  }
+}
+
+/** edit_file 的简易 diff：old 红、new 绿。 */
+export function renderEditDiff(oldStr, newStr) {
+  const out = [];
+  for (const l of String(oldStr ?? '').split('\n')) out.push(c.red('- ' + l));
+  for (const l of String(newStr ?? '').split('\n')) out.push(c.green('+ ' + l));
+  return out.join('\n');
+}
+
+export function indent(s, pad = '    ') {
+  return String(s)
+    .split('\n')
+    .map((l) => pad + l)
+    .join('\n');
+}
+
+/** 结果摘要（首行 + 行数提示），避免把整段工具输出刷屏。 */
+export function summarize(text, maxLines = 6) {
+  const lines = String(text).split('\n');
+  if (lines.length <= maxLines) return text;
+  return lines.slice(0, maxLines).join('\n') + c.gray(`\n  …（共 ${lines.length} 行）`);
+}