@fanchao8609/agent_brain_sync 1.9.7 → 1.9.8

package/bin/abs.js

@@ -2,7 +2,7 @@
 // bin/abs.js — abs CLI 入口。
 // abs <cmd> [args]
 // 命令: init / board / status / load / task / install / uninstall / help
-import { cmdInit, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdConcept, cmdShow, cmdRepair, cmdWrapup, cmdRule, cmdTeardownCheck, cmdTodoArchive, cmdResolve, cmdSupersede } from '../src/store.js';
+import { cmdInit, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdConcept, cmdShow, cmdRepair, cmdWrapup, cmdRule, cmdTeardownCheck, cmdTodoArchive, cmdResolve, cmdSupersede, cmdReview } from '../src/store.js';
 import { setUser, getUser, userConfigPath } from '../src/userconfig.js';
 import { runInstall, runUninstall } from '../src/install.js';
 import { readFileSync } from 'node:fs';
@@ -76,6 +76,13 @@ const FLAG_SPEC = {
   'port': { type: 'string' },
   // note 的触发条件（何时该读这条经验）—— 供 load 的相关页推荐匹配。
   'when': { type: 'string' },
+  // note 可选：借本机 CodeGraph 带出「改某符号会影响哪些代码」。
+  'impact': { type: 'string' },
+  // note 可选：经验类型（fact/pref/constraint/event，对齐 TencentDB L1 四分类）。
+  'type': { type: 'string' },
+  // review 用：--accept / --reject 各跟一个页名列表（逗号分隔或位置参数）。
+  'accept': { type: 'string' },
+  'reject': { type: 'string' },
   // concept 骨架用: 不在 FLAG_SPEC 里的 `--title` 会被静默当布尔 true（见 parseArgv 注释），
   // 于是 `--title "一句话"` 的正文会进位置参数 → 必须在这声明。
   'title': { type: 'string' },
@@ -194,6 +201,7 @@ const usage = `abs — 跨会话记忆工具（.brain/ 图谱）
   query <词…> [--all]       检索知识页 (多词 OR)
   resolve <页名…>            反查页面路径
   supersede <页名> [--by 页] 标经验已失效
+  review [--accept 页…|--reject 页…]  待确认页队列 (draft 升 active/否决)
   lint                       图谱体检 (死链/超限)
   rule [add "一句话"]        硬规则读写
   install|uninstall [--agent <宿主>] [--no-mcp] [--no-skill]
@@ -281,11 +289,13 @@ const subUsage = {
     'abs note — 经验实时暂存 → sources/（幂等去重；先记后提炼）',
     '',
     '用法:',
-    '  abs note "一句话经验" [--tags 坑,docker] [--when "什么时候该读这条"]',
+    '  abs note "一句话经验" [--tags 坑,docker] [--when "什么时候该读这条"] [--impact 符号名] [--type fact|pref|constraint|event]',
     '',
     '说明:',
     '  • --tags 首个标签建议带类别（坑/技巧/决策…），检索按词 OR 命中',
     '  • --when 供 load 的相关页推荐匹配「何时该读」',
+    '  • --impact 借本机 CodeGraph 带出「改该符号会影响哪些代码」（未装则静默跳过）',
+    '  • --type 经验分类：fact 事实 / pref 偏好 / constraint 约束 / event 事件（默认不分类）',
     '  • sources 是暂存区: 提炼成 concept 后应清理',
   ].join('\n'),
   query: [
@@ -447,7 +457,7 @@ async function main() {
         break;
       }
       case 'note': {
-        console.log(await cmdNote({ dir: opts.dir, text: opts._.join(' '), tags: opts.tags, when: opts.when }));
+        console.log(await cmdNote({ dir: opts.dir, text: opts._.join(' '), tags: opts.tags, when: opts.when, impact: opts.impact, type: opts.type }));
         break;
       }
       case 'concept': {
@@ -496,6 +506,15 @@ async function main() {
         console.log(await cmdResolve({ dir: opts.dir, refs: opts._ }));
         break;
       }
+      case 'review': {
+        // 无 --accept/--reject → 列出全部 draft 页；有则对页名列表执行确认/否决。
+        const action = opts.accept ? 'accept' : opts.reject ? 'reject' : '';
+        const refs = action === 'accept' ? (opts.accept || '').split(',').map(s => s.trim()).filter(Boolean)
+          : action === 'reject' ? (opts.reject || '').split(',').map(s => s.trim()).filter(Boolean)
+          : opts._;
+        console.log(await cmdReview({ dir: opts.dir, refs, action }));
+        break;
+      }
       case 'lint': {
         rejectExtra(opts._, 'abs lint');
         console.log(await cmdLint({ dir: opts.dir }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanchao8609/agent_brain_sync",
-  "version": "1.9.7",
+  "version": "1.9.8",
   "description": "agent-brain-sync: 跨会话 AI 编码记忆 — hook 纯触发 + CLI/MCP 读写 .brain markdown 图谱, 防并发写保护。",
   "type": "module",
   "license": "MIT",

package/src/codegraph.js

@@ -0,0 +1,87 @@
+// src/codegraph.js — 借用本机 CodeGraph 的「代码影响面」，写回 abs 图谱。
+//
+// 为何要这个模块（而非直接塞进 cmdNote）：
+//   abs 的定位是纯 markdown 图谱、零依赖、可进 git；CodeGraph 是二进制 SQLite、
+//   不可进 git、且不是每个机器都装。两者职责不同，唯一值得打通的点是一个维度：
+//   abs 的经验页里「这个改动会影响哪些代码」是空白的，而 codegraph impact 正是干这个的。
+//
+// 融合姿势 = 借结果、不引依赖：
+//   只在「用户显式传了 --impact <符号>」时才调 codegraph CLI，
+//   把它的纯文本输出写进 .brain/ 的 markdown 页（可进 git）。
+//   codegraph 不存在 / 调用失败 / 超时 → 静默降级为「无影响面」，绝不阻断 note 落盘。
+//
+// 为什么走 child_process 调 CLI、不引 npm 包、不走 MCP：
+//   - CLI 是 codegraph 自己装的稳定接口（impact/callers/callees），零依赖；
+//   - MCP 走宿主钩子，之前实测在 pi 下报 _elicitationHandler 错（宿主 bug），CLI 稳定。
+
+import { execFile } from 'node:child_process';
+
+const CG_BIN = 'codegraph';
+const CG_TIMEOUT_MS = 3000;
+
+/**
+ * 探测本机 codegraph 是否可用（不抛错，任何失败都返回 false）。
+ * 结果只影响「要不要在 note 里带影响面」，绝不影响 note 本身落盘。
+ */
+async function codegraphAvailable() {
+  return new Promise((resolve) => {
+    execFile(CG_BIN, ['--version'], { timeout: 1500 }, (err) => resolve(!err));
+  });
+}
+
+/**
+ * 索引是否新鲜（无 pending 改动）。
+ * codegraph 有文件 watcher，但 daemon 可能没在跑 / 停了很久，索引会过期。
+ * 过期时 impact 会返回旧数据 —— 把它写进经验页等于污染 abs 图谱。
+ * 用 `codegraph status --json` 的 pendingChanges 判定：全 0 才新鲜；
+ * 任何失败（命令不在/超时/解析失败）一律当「不新鲜」，宁缺毋滥。
+ */
+async function codegraphFresh(root) {
+  return new Promise((resolve) => {
+    execFile(
+      CG_BIN,
+      ['status', '--json', root],
+      { timeout: 2000 },
+      (err, stdout) => {
+        if (err) return resolve(false);
+        try {
+          const j = JSON.parse(stdout);
+          const pc = j.pendingChanges || {};
+          const fresh = (pc.added || 0) + (pc.modified || 0) + (pc.removed || 0) === 0;
+          resolve(fresh);
+        } catch {
+          resolve(false);
+        }
+      },
+    );
+  });
+}
+
+/**
+ * 拿某符号的「影响面」：改它会波及哪些函数/文件。
+ * @param {string} symbol 符号名（如 cmdTask、requireBrain）
+ * @param {string} root 项目根（codegraph -p 参数）
+ * @returns {Promise<string|null>} 纯文本影响面，失败/不可用/索引过期返回 null
+ */
+export async function impactOf(symbol, root) {
+  const s = String(symbol || '').trim();
+  if (!s) return null;
+  if (!(await codegraphAvailable())) return null;
+  // 索引不新鲜 → 不写影响面（避免把过期结构写进经验页）。
+  // 代价：用户刚改完代码立刻 note 时拿不到影响面；收益：绝不写错数据。
+  // 新鲜度恢复只需 codegraph 的 watcher 约 1s 同步，或手动 codegraph sync。
+  if (!(await codegraphFresh(root))) return null;
+  return new Promise((resolve) => {
+    execFile(
+      CG_BIN,
+      ['impact', s, '--depth', '2', '-p', root],
+      { timeout: CG_TIMEOUT_MS },
+      (err, stdout) => {
+        if (err) return resolve(null);
+        const text = String(stdout || '').trim();
+        // codegraph 无命中时输出形如 "No ..." 或空，统一当「无影响面」。
+        resolve(text ? text : null);
+      },
+    );
+  });
+}

package/src/install.js

@@ -822,11 +822,11 @@ async function installPi({ withMcp, withSkill, log }) {
   const p = join(dir, 'abs.ts');
   await atomicWrite(p, piPluginSource()); // Pi 用专用模板, 语法与 OpenCode 不同构
   steps.push(`✓ hook(ts extension) → ${p}`);
-  // MCP → ~/.pi/agent/mcp.json 的 mcpServers (stdio)
-  // 曾经只打印「走 extension 内桥接」而没有任何桥接代码 —— 靠 mcp-adapter 的
-  // hostConfigDiscovery 间接读到 claude 注册才"看起来能用"; 没有 claude 宿主的机器上直接缺失。
+  // MCP → ~/.pi/agent/mcp-adapter.json 的 mcpServers (stdio)
+  // 坑（2026-09-30 用户实报）：曾写 mcp.json，但 pi-mcp-adapter 已不再读它
+  //   （pi 自有 mcp.json 被 adapter 忽略，adapter 改读 mcp-adapter.json）→ 写了等于没写。
   if (withMcp) {
-    const mcpP = join(hostConfigRoot('pi'), 'agent', 'mcp.json');
+    const mcpP = join(hostConfigRoot('pi'), 'agent', 'mcp-adapter.json');
     await backup(mcpP);
     const cfg = await readJson(mcpP);
     cfg.mcpServers = cfg.mcpServers || {};
@@ -845,7 +845,7 @@ async function uninstallPi() {
   await fs.rm(join(hostConfigRoot('pi'), 'agent', 'extensions', 'abs.ts'), { force: true });
   steps.push(`✓ extension 已删除`);
   steps.push(...await uninstallSkills('pi'));
-  const mcpP = join(hostConfigRoot('pi'), 'agent', 'mcp.json');
+  const mcpP = join(hostConfigRoot('pi'), 'agent', 'mcp-adapter.json');
   const cfg = await readJson(mcpP, { strict: false });
   if (cfg === null) {
     steps.push(`⚠ ${mcpP} 无法解析为 JSON，已跳过（未改动你的配置）`);

package/src/query.js

@@ -81,7 +81,13 @@ export async function cmdQuery({ dir, terms, includeSuperseded }) {
     const extra = hidden ? `（另外 ${hidden} 页已标记 superseded，用 abs query ${words.join(' ')} --all 查看）` : '';
     return `query [${words.join(', ')}]: 无命中。${extra}用 abs lint 看图谱健康；首次使用先 abs init。`;
   }
-  const lines = shown.map((h) => {
+  // 输出条数上限（2026-09-30 补）：落实 read-side-output-must-not-scale 规则。
+  // query 会把命中页全部渲染；图谱长大到几百页时一次命中 50 页会爆输出。
+  // 硬上限 10 页，超出只给计数 + 收窄提示（不给全文 —— 那不是「不静默」，是「可再查」）。
+  const MAX_SHOWN = 10;
+  const overflow = shown.length - MAX_SHOWN;
+  const displayed = shown.slice(0, MAX_SHOWN);
+  const lines = displayed.map((h) => {
     const by = h.author ? `  @${h.author}` : '';
     // id 只在≠slug 时显示 —— 相同时再印一遗就是纯噪音（绝大多数页）。
     // 目的：让 AI 拿到一个改名也不漂的引用句柄（abs resolve <id> 能反查回来）。
@@ -97,12 +103,13 @@ export async function cmdQuery({ dir, terms, includeSuperseded }) {
     return `📄 ${h.slug}${by}${id}${st}${fuzzy}  (命中: ${hitTxt}${full})${viaTag}\n    ${h.snippet}`;
   });
   // 多词且无全命中时告知降级了 —— 不静默给一堆弱相关结果。
-  const anyFull = shown.some((h) => h.kind === 'exact' && h.matched.length === words.length);
+  const anyFull = displayed.some((h) => h.kind === 'exact' && h.matched.length === words.length);
   const tail = [];
   if (words.length > 1 && !anyFull) tail.push('', `（无页同时命中全部 ${words.length} 个词，以下按命中数排序）`);
   if (fuzzySuppressed) tail.push('', `（另有 ${fuzzyHits.length} 页字形相近但字面未命中，已隐藏 —— 它们通常不相关）`);
   if (hidden) tail.push(``, `（${hidden} 页 superseded 已隐藏；--all 可看）`);
-  return [`query [${words.join(', ')}] → ${shown.length} 页:`, '', ...lines, ...tail].join('\n');
+  if (overflow > 0) tail.push(``, `（另有 ${overflow} 页未展示 —— 用更具体的词收窄：abs query <词1> <词2>）`);
+  return [`query [${words.join(', ')}] → ${shown.length} 页（展示前 ${displayed.length} 页）:`, '', ...lines, ...tail].join('\n');
 }
 
 /** 从页面正文取一段「像答案」的片段。

package/src/store.js

@@ -8,6 +8,7 @@ import { stripStateMark, ensureStateMark, normalizeTodo, addTask, upsertTask, bo
 import { editFile, SKIP } from './lock.js';
 import { appendWrapup, strandedFor } from './wrapup.js';
 import { keywords, pickRelevant, renderRelevant, recentFiles, rankPage, topicStrength } from './relevant.js';
+import { impactOf } from './codegraph.js';
 
 // Re-export lint.js symbols so external importers (e.g. bin/mcp.js, bin/abs.js) still work.
 export { cmdLint, listPages, hasTail, PAGE_DIRS } from './lint.js';
@@ -708,6 +709,71 @@ export async function resolvePage(root, idOrSlug) {
   return null;
 }
 
+// ---------- review: 待确认页队列（draft → active/superseded） ----------
+// 为何需要：abs note 落的是 status: draft（未经核实），但之前没有「确认」这一步 ——
+//   draft 只是标签，没人管，经验就永远停在「待核实」状态，从不正式化。
+// 借鉴 TencentDB 的 review/route 治理环节：提取后必经审查，防止脏知识进入正式图谱。
+// 本命令只做「把 draft 显式升为 active 或否决为 superseded」，不替人判断内容好坏。
+// 动作收口在一处（editFile 锁内），并发安全同 supersede。
+export async function cmdReview({ dir, refs, action }) {
+  let root;
+  try {
+    root = await requireBrain(dir || process.cwd());
+  } catch {
+    return `未找到 .brain/ 图谱。先在项目根运行: abs init`;
+  }
+  const act = String(action || '').toLowerCase();
+  if (act && !['accept', 'reject'].includes(act)) {
+    return '用法: abs review [--accept <页名…>] [--reject <页名…>]  — 无参数列出全部 draft 页';
+  }
+  // 无动作 → 列出所有 draft 页（待确认队列）
+  if (!act) {
+    const pages = await listPages(brainPath(root));
+    // 只扫经验/知识目录（concepts/sources）。entities 是人页、sessions 是日志，
+    // 它们不是「待核实的经验」，不该进 review 队列（拉进来会把人页/日志当经验误确认）。
+    const REVIEW_DIRS = ['concepts', 'sources'];
+    const drafts = pages.filter((p) => REVIEW_DIRS.includes(p.dir) && statusOfPage(p.body) === 'draft');
+    if (!drafts.length) return '✓ 没有待确认的 draft 页。';
+    const lines = drafts.map((p) => {
+      const t = p.body.match(/^#\s*(.+)$/m);
+      const title = t ? t[1].trim() : p.slug;
+      return `  [draft] ${p.slug} — ${title}`;
+    });
+    return [
+      `待确认 draft 页 ${drafts.length} 条：`,
+      ...lines,
+      '',
+      '确认: abs review --accept <页名> [更多…]    否决: abs review --reject <页名> [更多…]',
+    ].join('\n');
+  }
+  // 有动作 → 对每个 ref 改 status
+  const list = (refs || []).map((r) => String(r).trim()).filter(Boolean);
+  if (!list.length) return `✗ --${act} 需要至少一个页名。用法: abs review --${act} <页名…>`;
+  const target = act === 'accept' ? 'active' : 'superseded';
+  const out = [];
+  for (const r of list) {
+    const hit = await resolvePage(root, r);
+    if (!hit) { out.push(`✗ ${r}: 未找到（试 abs review 看清单）`); continue; }
+    const res = await editFile(hit.full, (cur) => {
+      if (!cur || !cur.startsWith('---\n')) return SKIP;
+      const end = cur.indexOf('\n---', 3);
+      if (end === -1) return SKIP;
+      let fm = cur.slice(0, end);
+      const curSt = statusOfPage('', fm);
+      // 幂等：已是目标状态 → 不写盘
+      if (curSt === target) return SKIP;
+      fm = STATUS_RE.test(fm)
+        ? fm.replace(STATUS_RE, `status: ${target}`)
+        : `${fm}\nstatus: ${target}`;
+      return { text: fm + cur.slice(end) };
+    });
+    out.push(res === SKIP
+      ? `= ${hit.slug}: 已是 ${target}（无变化）`
+      : `✓ ${hit.slug} → ${target}`);
+  }
+  return out.join('\n');
+}
+
 // ---------- resolve: id/slug → 页面路径（引用的反查端） ----------
 // 配合 frontmatter 的 id: 使用。页改名后 id 不变，靠本命令仍能找回来。
 export async function cmdResolve({ dir, refs }) {
@@ -1119,7 +1185,7 @@ export { cmdQuery } from './query.js';
 // ---------- note: 经验实时暂存（source 页，一念一落，防流失） ----------
 const NOTE_DEDUP_MS = 60 * 1000;
 
-export async function cmdNote({ dir, text, tags, when }) {
+export async function cmdNote({ dir, text, tags, when, impact, type }) {
   const clean = String(text || '').trim();
   if (!clean) return '用法: abs note "经验/坑/技巧一句话" [--when "何时该读它"]（落 sources/ 暂存页，实时不流失）';
   let root;
@@ -1140,6 +1206,15 @@ export async function cmdNote({ dir, text, tags, when }) {
       return `• 60s 内已落同文本 → ${f} (跳过重复)`;
     }
   }
+  // 影响面（可选）：显式传 --impact <符号> 时，借本机 CodeGraph 拿「改它波及谁」。
+  // 失败/未装 codegraph 静默降级为无，绝不阻断 note 落盘。
+  const impactText = impact ? await impactOf(impact, root) : null;
+  // 类型（可选）：借鉴 TencentDB 的 L1 四分类，把自由文本经验分成可分类的资产。
+  // 默认不强制（自由文本仍是主体）；显式 --type 时才写进 frontmatter，供检索/load 区分。
+  // 合法值对齐 L1 四类：fact 事实 / pref 偏好 / constraint 约束 / event 事件。
+  const NOTE_TYPES = ['fact', 'pref', 'constraint', 'event'];
+  const noteType = NOTE_TYPES.includes(String(type || '').trim().toLowerCase())
+    ? String(type).trim().toLowerCase() : '';
   const tagList = String(tags || '').split(',').map((t) => t.trim()).filter(Boolean);
   const fmTags = ['source', ...tagList].join(', ');
   const slugSrc = slugOf(clean);
@@ -1155,12 +1230,14 @@ export async function cmdNote({ dir, text, tags, when }) {
     `author: ${who}`,
     `updated: ${today()}`,
     'status: draft',
+    ...(noteType ? [`type: ${noteType}`] : []),
     '---',
     '',
     `# 来源：${heading}`,
     '',
     `TITLE: ${clean}`,
     ...(whenText ? ['', `WHEN: ${whenText}`] : []),
+    ...(impactText ? ['', '## 影响面（本机 CodeGraph 自动带出）', '```', impactText, '```'] : []),
     '',
     `## 记录（实时暂存，Teardown 时提炼进 concepts/ 后本页可删）`,
     `- ${clean}`,
@@ -1325,6 +1402,8 @@ export async function registerInIndex(root, section, slug, desc) {
     const next = after === -1
       ? `${index.replace(/\s*$/, '')}\n${line}\n`
       : index.slice(0, after) + `\n${line}` + index.slice(after);
-    return { text: next };
+    // 归一空行：历史手工编辑会留 3+ 空行（load 时 collapseIndex 会压掉，但文件本身没清）。
+    // 追加新条目的同时顺手压一次，既清旧债又不改内容（与 collapseIndex 同一判据）。
+    return { text: next.replace(/\n{3,}/g, '\n\n') };
   });
 }