@huicai/cli 2026.710.97950 → 2026.711.0

package/src/gitflow.js

@@ -0,0 +1,140 @@
+// Git/PR 全自动化：暂存改动 → LLM 生成规范 commit 信息 → 若在主分支先建分支 → 提交 → push → gh 开 PR。
+// 每步优雅降级：非 git 仓库/无 remote/未装 gh 都给清晰结果而非报错。绝不 force-push、绝不直接提交到 main。
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { streamChat } from './api.js';
+import { DEFAULT_MODEL } from './config.js';
+
+const PSEUDO = /^(agent|workflow|datahuman)-/;
+const DEFAULT_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
+
+function git(cwd, args) {
+  return execSync('git ' + args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+function gitQuiet(cwd, args) {
+  try {
+    return git(cwd, args);
+  } catch {
+    return '';
+  }
+}
+
+/** 仓库状态：是否 git 仓库、当前分支、是否有改动、是否有 remote、是否装了 gh。 */
+export function gitInfo(cwd) {
+  const info = { isRepo: false, branch: '', dirty: false, hasRemote: false, hasGh: false };
+  try {
+    info.isRepo = git(cwd, 'rev-parse --is-inside-work-tree').trim() === 'true';
+  } catch {
+    return info;
+  }
+  info.branch = gitQuiet(cwd, 'rev-parse --abbrev-ref HEAD').trim();
+  info.dirty = gitQuiet(cwd, 'status --porcelain').trim().length > 0;
+  info.hasRemote = gitQuiet(cwd, 'remote').trim().length > 0;
+  try {
+    execSync('gh --version', { stdio: 'ignore' });
+    info.hasGh = true;
+  } catch { /* gh 未安装 */ }
+  return info;
+}
+
+/** 由 git diff 生成一条 Conventional Commits 提交信息（直连原始模型，避开伪模型编排）。 */
+export async function generateCommitMessage(cwd, config) {
+  let diff = gitQuiet(cwd, 'diff --staged');
+  if (!diff.trim()) diff = gitQuiet(cwd, 'diff');
+  diff = diff.slice(0, 12000);
+  if (!diff.trim()) return 'chore: update';
+  const model = PSEUDO.test(String(config.model || '')) ? (config.compactModel || DEFAULT_MODEL) : config.model;
+  try {
+    const r = await streamChat({
+      baseUrl: config.baseUrl, apiKey: config.apiKey, model,
+      messages: [
+        { role: 'system', content: '你是提交信息生成器。根据 git diff 生成一条规范的 Conventional Commits 提交信息：'
+          + '第一行 `<type>(<scope>): <简述>`（简述≤50字，type 用 feat/fix/refactor/docs/test/chore/perf/style 之一）；'
+          + '改动较大可空行后加 2-4 条正文要点。只输出提交信息本身，不要解释、不要代码块围栏。' },
+        { role: 'user', content: diff },
+      ],
+    });
+    const msg = (r.content || '').trim().replace(/^```[a-z]*\n?|\n?```$/g, '').trim();
+    return msg || 'chore: update';
+  } catch {
+    return 'chore: update';
+  }
+}
+
+function slug(msg) {
+  return String(msg).split('\n')[0]
+    .replace(/^[a-z]+(\([^)]*\))?!?:\s*/i, '')
+    .replace(/[^a-zA-Z0-9一-鿿]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase()
+    .slice(0, 32) || 'change';
+}
+
+/**
+ * 执行 PR 全流程。
+ * @param {{cwd, config, emit?:(t:string)=>void, push?:boolean, openPr?:boolean}} p
+ * @returns {Promise<{ok, error?, branch?, pr?, note?, committed?, pushed?}>}
+ */
+export async function runPrFlow({ cwd, config, emit = () => {}, push = true, openPr = true }) {
+  const info = gitInfo(cwd);
+  if (!info.isRepo) return { ok: false, error: '当前目录不是 git 仓库' };
+  const onDefault = DEFAULT_BRANCHES.has(info.branch);
+
+  if (info.dirty) {
+    git(cwd, 'add -A');
+    emit('已暂存全部改动');
+  }
+  const stagedStat = gitQuiet(cwd, 'diff --staged --stat').trim();
+
+  let msg = '';
+  if (stagedStat) {
+    emit('正在生成提交信息…');
+    msg = await generateCommitMessage(cwd, config);
+    emit('提交信息：' + msg.split('\n')[0]);
+  }
+
+  // 在主分支上：先建分支，绝不直接提交到 main/master
+  let target = info.branch;
+  if (onDefault) {
+    target = 'huicai/' + slug(msg || 'change') + '-' + Date.now().toString(36).slice(-4);
+    git(cwd, `checkout -b ${target}`);
+    emit('已从 ' + info.branch + ' 创建分支 ' + target);
+  }
+
+  let committed = false;
+  if (stagedStat) {
+    const f = path.join(os.tmpdir(), 'huicai-commit-' + Date.now() + '.txt');
+    fs.writeFileSync(f, msg);
+    try {
+      git(cwd, `commit -F "${f}"`);
+      committed = true;
+      emit('已提交');
+    } finally {
+      try { fs.unlinkSync(f); } catch { /* ignore */ }
+    }
+  } else {
+    emit('无新暂存改动，跳过提交');
+  }
+
+  if (!push) return { ok: true, branch: target, committed };
+  if (!info.hasRemote) return { ok: true, branch: target, committed, note: '无 remote，未推送' };
+  try {
+    git(cwd, `push -u origin ${target}`);
+    emit('已推送 origin/' + target);
+  } catch (e) {
+    return { ok: false, error: 'push 失败：' + String(e.message).split('\n')[0], branch: target };
+  }
+
+  if (!openPr) return { ok: true, branch: target, committed, pushed: true };
+  if (!info.hasGh) return { ok: true, branch: target, committed, pushed: true, note: '未装 gh CLI，PR 请手动开' };
+  try {
+    const out = execSync('gh pr create --fill', { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    emit('已开 PR：' + out);
+    return { ok: true, branch: target, committed, pr: out };
+  } catch (e) {
+    return { ok: true, branch: target, committed, pushed: true, note: 'gh pr create 失败（可手动开）：' + String(e.message).split('\n')[0] };
+  }
+}

package/src/hooks.js

@@ -0,0 +1,207 @@
+// 工具事件钩子（对标 Claude Code hooks）：在关键节点跑用户自定义 shell 命令。
+// 配置在 settings.json（全局 ~/.huicai + 项目 .huicai）：
+//   { "hooks": {
+//       "UserPromptSubmit": [{ "command": "..." }],
+//       "PreToolUse":  [{ "matcher": "write_file|edit_file", "command": "..." }],
+//       "PostToolUse": [{ "matcher": "run_bash", "command": "npm test" }],
+//       "Stop":        [{ "command": "..." }]
+//   } }
+// matcher 为工具名正则（仅 Pre/PostToolUse 有意义；缺省匹配全部工具）。
+// 命令通过环境变量 + stdin(JSON) 拿到上下文：
+//   HUICAI_EVENT / HUICAI_CWD / HUICAI_TOOL_NAME / HUICAI_TOOL_PATH / HUICAI_TOOL_ARGS(JSON)。
+// 阻断语义：PreToolUse / UserPromptSubmit 的钩子以「非零退出码」表示阻断（stderr/stdout 作为原因回灌）；
+//   PostToolUse / Stop / SessionStart 不阻断，仅采集输出（stdout 会附加到工具结果/提示，供模型看到）。
+// 结构化控制（进阶）：钩子若把 JSON 打到 stdout，则按结构化决策处理（优先于退出码）：
+//   {"decision":"block","reason":"..."}      阻断该操作（仅阻断类事件）
+//   {"context":"..."}                          把文本作为附加上下文注入模型
+//   {"modifiedArgs":{...}}                     (PreToolUse) 覆盖该工具的调用参数
+//   多个字段可同时出现。非 JSON 输出仍按「纯文本 + 退出码」旧语义处理（向后兼容）。
+// SessionStart 事件：本会话首个用户回合前触发一次，常用于注入项目上下文（context 字段）。
+//
+// 安全：全局设置里的钩子始终生效（用户本机配置，可信）；项目 .huicai/settings.json 里的钩子默认**不执行**
+//   （克隆来的仓库可能植入恶意命令），需显式信任：环境变量 HUICAI_PROJECT_HOOKS=1，
+//   或全局设置 { "hooks": { "trustProject": true } }。/hooks 会提示被忽略的项目钩子数量。
+
+import { spawnSync } from 'node:child_process';
+import { loadRawSettings } from './settings.js';
+
+export const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'];
+const BLOCKING_EVENTS = new Set(['UserPromptSubmit', 'PreToolUse']);
+
+/** 解析钩子 stdout 为结构化控制 JSON（非 JSON 返回 null）。 */
+function parseHookJson(stdout) {
+  const t = String(stdout || '').trim();
+  if (!t.startsWith('{')) return null;
+  try {
+    return JSON.parse(t);
+  } catch {
+    return null;
+  }
+}
+const DEFAULT_TIMEOUT = 30_000;
+const MAX_HOOK_OUTPUT = 8_000;
+
+/** 项目级钩子是否被信任执行。 */
+function projectHooksTrusted(globalSettings) {
+  if (process.env.HUICAI_PROJECT_HOOKS === '1') return true;
+  return globalSettings?.hooks?.trustProject === true;
+}
+
+function normalizeHooks(rawHooks, source) {
+  const out = [];
+  if (!rawHooks || typeof rawHooks !== 'object') return out;
+  for (const event of HOOK_EVENTS) {
+    const arr = rawHooks[event];
+    if (!Array.isArray(arr)) continue;
+    for (const h of arr) {
+      const command = typeof h === 'string' ? h : h?.command;
+      if (typeof command !== 'string' || !command.trim()) continue;
+      out.push({
+        event,
+        matcher: h && typeof h.matcher === 'string' && h.matcher.trim() ? h.matcher.trim() : null,
+        command: command.trim(),
+        timeout: Number(h?.timeout) > 0 ? Number(h.timeout) : DEFAULT_TIMEOUT,
+        source,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 加载生效钩子。
+ * @returns {{ byEvent: Record<string, object[]>, all: object[], projectIgnored: number, projectTrusted: boolean }}
+ */
+export function loadHooks(cwd) {
+  const { global, project } = loadRawSettings(cwd);
+  const trusted = projectHooksTrusted(global);
+  const all = [...normalizeHooks(global.hooks, 'global')];
+  const projectHooks = normalizeHooks(project.hooks, 'project');
+  let projectIgnored = 0;
+  if (trusted) all.push(...projectHooks);
+  else projectIgnored = projectHooks.length;
+
+  const byEvent = Object.fromEntries(HOOK_EVENTS.map((e) => [e, []]));
+  for (const h of all) byEvent[h.event].push(h);
+  return { byEvent, all, projectIgnored, projectTrusted: trusted };
+}
+
+/** 该钩子是否匹配此工具名（无 matcher 或非工具事件恒真）。 */
+export function hookMatches(hook, toolName) {
+  if (!hook.matcher) return true;
+  if (!toolName) return true;
+  try {
+    return new RegExp(hook.matcher).test(toolName);
+  } catch {
+    return false; // 非法正则：视为不匹配，避免误伤全部
+  }
+}
+
+function clip(s) {
+  s = String(s || '');
+  return s.length > MAX_HOOK_OUTPUT ? s.slice(0, MAX_HOOK_OUTPUT) + '\n…（钩子输出已截断）' : s;
+}
+
+function runOne(hook, env, input) {
+  const isWin = process.platform === 'win32';
+  const r = isWin
+    ? spawnSync(process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', hook.command],
+      { cwd: env.HUICAI_CWD, env, input, encoding: 'utf8', timeout: hook.timeout, maxBuffer: 4 * 1024 * 1024, windowsVerbatimArguments: true })
+    : spawnSync(process.env.SHELL || '/bin/sh', ['-c', hook.command],
+      { cwd: env.HUICAI_CWD, env, input, encoding: 'utf8', timeout: hook.timeout, maxBuffer: 4 * 1024 * 1024 });
+  const stdout = clip(r.stdout);
+  const stderr = clip(r.stderr);
+  const timedOut = r.error && r.error.code === 'ETIMEDOUT';
+  const status = timedOut ? 124 : (r.status == null ? 1 : r.status);
+  return { stdout, stderr, status, timedOut };
+}
+
+/**
+ * 触发某事件的全部匹配钩子（同步、有序）。
+ * @param {string} event
+ * @param {{cwd:string, toolName?:string, args?:object, prompt?:string, result?:string}} payload
+ * @param {{byEvent?:object}} [loaded] 预加载的钩子（省略则按 cwd 现读）
+ * @returns {{ block:boolean, reason:string, outputs:{command:string,stdout:string}[] }}
+ */
+export function runHooks(event, payload, loaded) {
+  const cwd = payload.cwd;
+  const hooks = (loaded?.byEvent?.[event]) || loadHooks(cwd).byEvent[event] || [];
+  const matching = hooks.filter((h) => hookMatches(h, payload.toolName));
+  const result = { block: false, reason: '', outputs: [], injectContext: '', modifiedArgs: null };
+  if (!matching.length) return result;
+
+  const env = {
+    ...process.env,
+    HUICAI_EVENT: event,
+    HUICAI_CWD: cwd || process.cwd(),
+    HUICAI_TOOL_NAME: payload.toolName || '',
+    HUICAI_TOOL_PATH: payload.args && payload.args.path != null ? String(payload.args.path) : '',
+    HUICAI_TOOL_ARGS: (() => { try { return JSON.stringify(payload.args || {}); } catch { return '{}'; } })(),
+  };
+  const input = (() => { try { return JSON.stringify(payload); } catch { return '{}'; } })();
+
+  for (const hook of matching) {
+    let r;
+    try {
+      r = runOne(hook, env, input);
+    } catch (e) {
+      r = { stdout: '', stderr: String(e.message || e), status: 1, timedOut: false };
+    }
+    const json = parseHookJson(r.stdout);
+    if (json) {
+      // 结构化控制（JSON 输出优先于退出码）
+      if (typeof json.context === 'string' && json.context.trim()) {
+        result.injectContext += (result.injectContext ? '\n' : '') + json.context.trim();
+      }
+      if (json.modifiedArgs && typeof json.modifiedArgs === 'object') {
+        result.modifiedArgs = { ...(result.modifiedArgs || {}), ...json.modifiedArgs };
+      }
+      if (json.decision === 'block' && BLOCKING_EVENTS.has(event)) {
+        result.block = true;
+        result.reason = String(json.reason || '钩子决定阻断该操作');
+        break;
+      }
+      continue; // JSON 钩子不把原文当普通输出
+    }
+    // 纯文本钩子（向后兼容）：输出采集 + 非零退出码阻断
+    const text = (r.stdout || r.stderr || '').trim();
+    if (text) result.outputs.push({ command: hook.command, stdout: r.stdout.trim() || r.stderr.trim() });
+    if (r.status !== 0 && BLOCKING_EVENTS.has(event)) {
+      result.block = true;
+      result.reason = (r.timedOut ? `钩子超时（${hook.command}）` : (r.stderr.trim() || r.stdout.trim()
+        || `钩子以退出码 ${r.status} 阻断（${hook.command}）`));
+      break; // 一旦阻断即停止后续钩子
+    }
+  }
+  return result;
+}
+
+/** /hooks 列表展示：把已加载钩子渲染为可读文本。 */
+export function formatHooks(loaded) {
+  const lines = [];
+  const total = loaded.all.length;
+  if (!total) {
+    lines.push('未配置钩子。可在 ~/.huicai/settings.json 或 项目 .huicai/settings.json 的 "hooks" 中添加。');
+  } else {
+    for (const event of HOOK_EVENTS) {
+      const arr = loaded.byEvent[event];
+      if (!arr.length) continue;
+      lines.push(`${event}`);
+      for (const h of arr) {
+        const m = h.matcher ? `[${h.matcher}] ` : '';
+        lines.push(`  · ${m}${h.command}${h.source === 'global' ? '' : '（项目）'}`);
+      }
+    }
+  }
+  if (loaded.projectIgnored > 0) {
+    lines.push('');
+    lines.push(`⚠ 已忽略 ${loaded.projectIgnored} 条项目级钩子（未信任本项目）。`);
+    lines.push('  如信任本项目，设 HUICAI_PROJECT_HOOKS=1，或全局设置 hooks.trustProject=true。');
+  }
+  lines.push('');
+  lines.push('事件：SessionStart（会话开始，注入上下文）· UserPromptSubmit（提交前，注入/阻断）'
+    + '· PreToolUse（工具前，阻断/改参数）· PostToolUse（工具后，采输出）· Stop（回合结束）。');
+  lines.push('结构化控制：钩子可把 JSON 打到 stdout —— {"decision":"block","reason":..} 阻断 / '
+    + '{"context":".."} 注入上下文 / {"modifiedArgs":{..}} 改工具参数。');
+  return lines.join('\n');
+}

package/src/insights.js

@@ -0,0 +1,102 @@
+// /insights：从本机会话（~/.huicai/sessions）聚合使用洞察——数量/轮数/活跃度/按项目·模型分布。
+// 纯元数据统计（listSessions 已给出 turns/model/cwd/updatedAt），不再逐个读全文。
+
+import path from 'node:path';
+import { c } from './colors.js';
+import { relTime } from './session.js';
+
+const DAY = 24 * 60 * 60 * 1000;
+
+function topN(counts, n) {
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, n);
+}
+
+/** 由会话列表计算洞察数据。@param {{cwd?:string, now?:number}} [opts] */
+export function computeInsights(sessions, opts = {}) {
+  const now = opts.now || Date.now();
+  const list = Array.isArray(sessions) ? sessions : [];
+  const byProject = new Map();
+  const byModel = new Map();
+  let totalTurns = 0;
+  let last24 = 0;
+  let last7 = 0;
+  let last30 = 0;
+  let longest = null;
+  let mostRecent = 0;
+
+  for (const s of list) {
+    const turns = Number(s.turns) || 0;
+    totalTurns += turns;
+    const proj = s.cwd ? (path.basename(s.cwd) || s.cwd) : '(未知)';
+    byProject.set(proj, (byProject.get(proj) || 0) + 1);
+    const model = s.model || '(未知)';
+    byModel.set(model, (byModel.get(model) || 0) + 1);
+    const age = now - (s.updatedAt || 0);
+    if (age <= DAY) last24++;
+    if (age <= 7 * DAY) last7++;
+    if (age <= 30 * DAY) last30++;
+    if (!longest || turns > longest.turns) longest = { turns, title: s.title || '' };
+    if ((s.updatedAt || 0) > mostRecent) mostRecent = s.updatedAt || 0;
+  }
+
+  // 近 14 天每日活跃（会话更新计数）
+  const DAYS = 14;
+  const daily = new Array(DAYS).fill(0);
+  const startToday = new Date(now);
+  startToday.setHours(0, 0, 0, 0);
+  for (const s of list) {
+    const su = new Date(s.updatedAt || 0);
+    su.setHours(0, 0, 0, 0);
+    const ago = Math.floor((startToday.getTime() - su.getTime()) / DAY);
+    if (ago >= 0 && ago < DAYS) daily[DAYS - 1 - ago]++;
+  }
+
+  const cwdProj = opts.cwd ? (path.basename(opts.cwd) || opts.cwd) : null;
+  const currentProject = cwdProj
+    ? { name: cwdProj, sessions: list.filter((s) => s.cwd === opts.cwd).length,
+      turns: list.filter((s) => s.cwd === opts.cwd).reduce((n, s) => n + (Number(s.turns) || 0), 0) }
+    : null;
+
+  return {
+    total: list.length,
+    totalTurns,
+    avgTurns: list.length ? totalTurns / list.length : 0,
+    last24, last7, last30,
+    mostRecent,
+    longest,
+    byProject: topN(byProject, 5),
+    byModel: topN(byModel, 5),
+    currentProject,
+    daily,
+  };
+}
+
+const SPARK = '▁▂▃▄▅▆▇█';
+function sparkline(arr) {
+  const max = Math.max(1, ...arr);
+  return arr.map((v) => (v === 0 ? '·' : SPARK[Math.min(7, Math.floor((v / max) * 7))])).join('');
+}
+
+/** 渲染洞察报告文本。 */
+export function formatInsights(d) {
+  if (!d.total) return '本机还没有历史会话（对话发生后即可 /insights 查看统计）。';
+  const lines = [c.bold('会话洞察') + c.gray('（本机 ~/.huicai/sessions）')];
+  lines.push(`  总计      ${d.total} 个会话 · ${d.totalTurns} 轮对话`
+    + (d.mostRecent ? ` · 最近活跃 ${relTime(d.mostRecent)}` : ''));
+  lines.push(`  近况      24h ${d.last24} 个 · 7天 ${d.last7} 个 · 30天 ${d.last30} 个`);
+  if (d.daily && d.daily.some((x) => x > 0)) {
+    lines.push(`  近14天    ${sparkline(d.daily)}  ${c.gray('(峰值 ' + Math.max(...d.daily) + '/天)')}`);
+  }
+  lines.push(`  平均      ${d.avgTurns.toFixed(1)} 轮/会话`
+    + (d.longest ? ` · 最长 ${d.longest.turns} 轮${d.longest.title ? '（' + d.longest.title.slice(0, 24) + '）' : ''}` : ''));
+  if (d.byProject.length) {
+    lines.push('  按项目    ' + d.byProject.map(([k, v]) => `${k} ${v}`).join(' · '));
+  }
+  if (d.byModel.length) {
+    lines.push('  按模型    ' + d.byModel.map(([k, v]) => `${k.length > 20 ? k.slice(0, 20) + '…' : k} ${v}`).join(' · '));
+  }
+  if (d.currentProject) {
+    lines.push(c.gray(`  当前项目  ${d.currentProject.name}：${d.currentProject.sessions} 个会话 · ${d.currentProject.turns} 轮`));
+  }
+  return lines.join('\n');
+}

package/src/kbsync.js

@@ -0,0 +1,141 @@
+// huicai kb-sync：配合 git diff 检测变更文件，增量同步到平台知识库，让 RAG 随代码保鲜。
+// 检测策略：默认对比工作区与 HEAD（已跟踪改动 + 未跟踪新文件）；给定 ref 则 git diff --name-status <ref>。
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { syncKnowledge } from './api.js';
+import { IGNORE, MAX_FILE_BYTES } from './codeindex.js';
+
+const BATCH = 20; // 每批提交的文件数（服务端逐文件分块向量化，分批避免单请求过大/超时）
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).trim();
+}
+
+function isGitRepo(cwd) {
+  try {
+    git(cwd, ['rev-parse', '--is-inside-work-tree']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 路径是否落在被忽略目录下（node_modules/.git/dist…），避免把依赖/产物灌进知识库。 */
+function inIgnoredDir(rel) {
+  return rel.split('/').some((seg) => IGNORE.has(seg));
+}
+
+/** 空字节嗅探：判定二进制（不入库）。 */
+function isBinary(buf) {
+  const n = Math.min(buf.length, 4096);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+/**
+ * 用 git 检测变更文件。
+ * - 指定 base（ref/范围，如 origin/main、HEAD~3、abc123）：git diff --name-status <base>
+ * - 不指定：工作区相对 HEAD 的改动（已跟踪 A/M/D/R）+ 未跟踪新文件（视为新增）
+ * @returns {{changed:string[], deleted:string[]}}
+ */
+export function detectChanges(cwd, base) {
+  const changed = new Set();
+  const deleted = new Set();
+  const parse = (out) => {
+    for (const line of out.split('\n')) {
+      if (!line.trim()) continue;
+      const parts = line.split('\t');
+      const code = parts[0][0];
+      if (code === 'D') {
+        deleted.add(parts[1]);
+      } else if (code === 'R' || code === 'C') {
+        // Rxxx old new：重命名——旧路径删档、新路径入档（复制 C 只入新档）
+        const oldP = parts[1];
+        const newP = parts[2] || parts[1];
+        if (code === 'R') deleted.add(oldP);
+        changed.add(newP);
+      } else {
+        // A/M/T…：取末列为路径
+        changed.add(parts[parts.length - 1]);
+      }
+    }
+  };
+  if (base) {
+    parse(git(cwd, ['diff', '--name-status', base]));
+  } else {
+    parse(git(cwd, ['diff', '--name-status', 'HEAD']));
+    const others = git(cwd, ['ls-files', '--others', '--exclude-standard']);
+    for (const p of others.split('\n')) if (p.trim()) changed.add(p.trim());
+  }
+  // 删除后又重新出现的以变更为准
+  for (const p of changed) deleted.delete(p);
+  return { changed: [...changed], deleted: [...deleted] };
+}
+
+/**
+ * 把检测到的变更组装为同步条目（读取内容、过滤忽略目录/二进制/超大文件）。
+ * @returns {{files:Array<{path,content?,deleted?}>, skipped:number, skips:string[]}}
+ */
+export function buildEntries(cwd, changed, deleted, emit = () => {}) {
+  const files = [];
+  let skipped = 0;
+  for (const rel of changed) {
+    if (inIgnoredDir(rel)) { skipped++; continue; }
+    const abs = path.join(cwd, rel);
+    let st;
+    try {
+      st = fs.statSync(abs);
+    } catch {
+      skipped++; // 已不在（diff 后又被删）
+      continue;
+    }
+    if (!st.isFile()) { skipped++; continue; }
+    if (st.size > MAX_FILE_BYTES) {
+      emit(`跳过（过大 ${(st.size / 1024).toFixed(0)}KB）：${rel}`);
+      skipped++;
+      continue;
+    }
+    const buf = fs.readFileSync(abs);
+    if (isBinary(buf)) { skipped++; continue; }
+    files.push({ path: rel, content: buf.toString('utf8'), deleted: false });
+  }
+  for (const rel of deleted) {
+    if (inIgnoredDir(rel)) continue;
+    files.push({ path: rel, deleted: true });
+  }
+  return { files, skipped };
+}
+
+/**
+ * 执行 kb-sync：检测变更 → 组装条目 → 分批调用平台增量同步。
+ * @param {{cwd:string, config:{baseUrl:string,apiKey:string}, kbId:string|number, base?:string, dry?:boolean, emit?:(t:string)=>void}} opts
+ * @returns {Promise<{ok:boolean, empty?:boolean, dry?:boolean, added:number, removed:number, skipped:number, accepted?:number, message:string, preview?:any[]}>}
+ */
+export async function runKbSync({ cwd, config, kbId, base, dry = false, emit = () => {} }) {
+  if (!isGitRepo(cwd)) throw new Error('当前目录不是 git 仓库；kb-sync 依赖 git diff 检测变更');
+  const { changed, deleted } = detectChanges(cwd, base);
+  const { files, skipped } = buildEntries(cwd, changed, deleted, emit);
+
+  const added = files.filter((f) => !f.deleted).length;
+  const removed = files.filter((f) => f.deleted).length;
+  if (!files.length) {
+    return { ok: true, empty: true, added: 0, removed: 0, skipped, message: base ? `相对 ${base} 无可同步的变更文件` : '工作区无可同步的变更文件' };
+  }
+
+  emit(`检测到 ${added} 个新增/修改、${removed} 个删除${skipped ? `（跳过 ${skipped}）` : ''}${base ? `（相对 ${base}）` : ''}`);
+  if (dry) {
+    return { ok: true, dry: true, added, removed, skipped, message: '试运行（未提交）', preview: files.map((f) => ({ path: f.path, deleted: !!f.deleted })) };
+  }
+
+  let accepted = 0;
+  const msgs = [];
+  for (let i = 0; i < files.length; i += BATCH) {
+    const batch = files.slice(i, i + BATCH);
+    if (files.length > BATCH) emit(`同步中… ${Math.min(i + BATCH, files.length)}/${files.length}`);
+    const r = await syncKnowledge(config.baseUrl, config.apiKey, kbId, batch);
+    accepted += r?.accepted || 0;
+    if (r?.message) msgs.push(r.message);
+  }
+  return { ok: true, added, removed, skipped, accepted, message: msgs.join('；') || '同步完成' };
+}

package/src/memory.js

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { CONFIG_DIR } from './config.js';
+import { tokenize } from './codeindex.js';
 
 export const MEMORY_DIR = path.join(CONFIG_DIR, 'memory');
 const MAX_MEMORY_CHARS = 6000; // 注入系统提示词的上限（超出保留最新条目）
@@ -69,6 +70,56 @@ export function clearMemory(cwd) {
   }
 }
 
+/** 读取完整长期记忆原文（不截断），供 recall_memory 按相关性检索。 */
+export function readMemoryRaw(cwd) {
+  try {
+    return fs.readFileSync(memoryPath(cwd), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 构造 recall_memory 工具（跨会话经验主动召回）：在本项目长期记忆里按关键词检索相关条目，
+ * 连超出常驻注入预算（6k）的历史也能查到。CJK 感知分词（复用 codeindex.tokenize）。
+ */
+export function makeRecallTool({ cwd }) {
+  const spec = {
+    type: 'function',
+    function: {
+      name: 'recall_memory',
+      description:
+        '在本项目的长期记忆里按关键词检索相关的过往结论/踩坑/约定（连超出常驻注入预算的历史也能查到）。'
+        + '开始一个任务前，若怀疑「以前处理过类似问题」，可先 recall 一下，少走弯路。',
+      parameters: {
+        type: 'object',
+        properties: { query: { type: 'string', description: '关键词/概念' } },
+        required: ['query'],
+      },
+    },
+  };
+  const run = async (args) => {
+    const q = String(args?.query || '').trim();
+    if (!q) return '缺少 query';
+    const entries = readMemoryRaw(cwd).split('\n').map((l) => l.trim()).filter((l) => l.startsWith('- '));
+    if (!entries.length) return '本项目暂无可检索的长期记忆。';
+    const qt = new Set(tokenize(q));
+    if (!qt.size) return '查询词无有效 token。';
+    const scored = entries
+      .map((e) => {
+        let s = 0;
+        for (const t of new Set(tokenize(e))) if (qt.has(t)) s++;
+        return { e, s };
+      })
+      .filter((x) => x.s > 0)
+      .sort((a, b) => b.s - a.s)
+      .slice(0, 6);
+    if (!scored.length) return `未在长期记忆中找到与「${q}」相关的条目。`;
+    return '相关的历史记忆：\n' + scored.map((x) => x.e).join('\n');
+  };
+  return { readOnly: true, spec, run };
+}
+
 /**
  * 构造 memory_write 内置工具（顶层注入；记忆是机制本身，自动放行）。
  * @param {{cwd:string, emit?:(text:string)=>void}} p