@fanchao8609/agent_brain_sync 1.21.0 → 1.23.0

package/README.md

@@ -17,14 +17,17 @@ npm install -g @fanchao8609/agent_brain_sync
 abs install
 ```
 
-`abs install` 会交互式让你勾选智能体；也可以直接指定：
+**默认只装 pi**（其余宿主 opt-in）——装到不用的宿主上会往那边配置文件塞 hook/MCP 条目。
 
 ```bash
-abs install --agent pi            # 只装 pi
-abs install                       # 全部: claude-code / codex / opencode / pi / omp
+abs install                       # 默认: 只装 pi
+abs install --all                 # 全装: claude-code / codex / opencode / pi / omp
+abs install --agent claude-code   # 只装指定宿主
 abs install --agent pi --no-mcp   # 只装 hook + skill，不要 MCP
 ```
 
+交互模式下回车 = 只装 pi；输入 `all` 才全装。
+
 装了什么：
 
 | 宿主 | hook | MCP | skill |
@@ -117,11 +120,12 @@ abs todo done    TASK-1
 abs note "一句话经验" --tags 坑,docker    # 经验暂存 → sources/
 abs log "完成 X"                          # 记一行流水；abs log 无参 = 查看
 abs query <词>                            # 检索图谱（多词 OR）；已被推翻的经验默认隐藏（--all 可看）
-abs capture [--layer 1-7] "一句话"        # 按七层判层后直接落到位（不传 = L4 认知）
+abs capture [--layer 1-7] [--kind …] "一句话"  # 按七层判层后落到位（--kind: gotcha|decision|tradeoff|howto）
 abs db rebuild                            # 扫所有登记项目 → 建图数据库（~/.abs/graph.db）
-abs db search <词>                        # 走库检索：FTS 拿种子 + 亮度扩散，L1 铁律恒在最前
+abs db search <词> [--full]              # 走库检索：默认只给摘要+token 成本，--full 才附正文
 abs db status                             # 库体检：七层分布 / 悬挂链接 / 已入库项目
 abs db add                                # 把当前项目登记进 ~/.abs/projects.json
+abs db evolve                             # 知识进化体检：被推翻/断链/主题堆积/僵化页
 abs summon [--mark|--status]              # 会话总结托底：列出未总结 / 有更新的会话（不写盘）
 abs resolve <页名或id>                    # 反查页面路径（页改名后 id 不变）
 abs supersede <页名> [--by <新页>]        # 标记经验已失效（不删文件，保留历史；query 默认不再返回）

package/bin/abs.js

@@ -3,7 +3,7 @@
 // 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, cmdReview } from '../src/store.js';
-import { cmdDbRebuild, cmdDbSearch, cmdDbStatus, addProject } from '../src/brain/db-cmd.js';
+import { cmdDbRebuild, cmdDbSearch, cmdDbStatus, cmdDbEvolve, addProject } from '../src/brain/db-cmd.js';
 import { cmdCapture } from '../src/brain/capture.js';
 import { cmdSummon } from '../src/brain/summon-cmd.js';
 import { setUser, getUser, userConfigPath } from '../src/userconfig.js';
@@ -210,6 +210,7 @@ function parseArgv(args) {
     tags: values.tags,
     limit: values.limit === undefined ? undefined : Number(values.limit),
     layer: values.layer,
+    kind: values.kind,
     mark: !!values.mark,
     status: !!values.status,
     title: values.title,
@@ -249,7 +250,7 @@ const usage = `abs — 跨会话记忆工具（.brain/ 图谱）
   summon [--mark|--status]   会话总结托底: 列出未总结/有更新的会话 (不写盘)
   concept <slug> --title …   建概念页骨架
   query <词…> [--all]       检索知识页 (多词 OR)
-  db rebuild|search|status   图数据库: 建库 / 亮度搜索 / 体检
+  db rebuild|search|status|evolve  图数据库: 建库 / 亮度搜索 / 体检 / 进化体检
   resolve <页名…>            反查页面路径
   supersede <页名> [--by 页] 标经验已失效
   review [--accept 页…|--reject 页…]  待确认页队列 (draft 升 active/否决)
@@ -534,7 +535,7 @@ async function main() {
         break;
       }
       case 'capture': {
-        console.log(await cmdCapture({ dir: opts.dir, text: opts._.join(' '), layer: opts.layer, tags: opts.tags, title: opts.title }));
+        console.log(await cmdCapture({ dir: opts.dir, text: opts._.join(' '), layer: opts.layer, tags: opts.tags, title: opts.title, kind: opts.kind }));
         break;
       }
       case 'note': {
@@ -556,7 +557,7 @@ async function main() {
       case 'uninstall': {
         // --help 已在 switch 前统一拦截（subUsage）。
         if (cmd === 'install') {
-          await runInstall({ agent: opts.agent, mcp: opts.mcp !== false, skill: opts.skill !== false, yes: opts.yes });
+          await runInstall({ agent: opts.agent, all: !!opts.all, mcp: opts.mcp !== false, skill: opts.skill !== false, yes: opts.yes });
         } else {
           await runUninstall({ agent: opts.agent, yes: opts.yes });
         }
@@ -579,14 +580,15 @@ async function main() {
         const sub = opts._[0];
         const rest = opts._.slice(1);
         if (sub === 'rebuild') { console.log(await cmdDbRebuild({ dir: opts.dir })); break; }
-        if (sub === 'search') { console.log(await cmdDbSearch({ query: rest.join(' '), limit: Number(opts.limit) || 8 })); break; }
+        if (sub === 'search') { console.log(await cmdDbSearch({ query: rest.join(' '), limit: Number(opts.limit) || 8, full: !!opts.full })); break; }
         if (sub === 'status') { console.log(await cmdDbStatus()); break; }
+        if (sub === 'evolve') { console.log(await cmdDbEvolve({ staleDays: Number(opts['stale-days']) || 90 })); break; }
         if (sub === 'add') {
           const r = await addProject(opts.dir || process.cwd());
           console.log(`✓ 已登记项目: ${r}\n  建库: abs db rebuild`);
           break;
         }
-        console.log('用法: abs db rebuild | search <词> | status | add [--dir <项目根>]');
+        console.log('用法: abs db rebuild | search <词> | status | evolve | add [--dir <项目根>]');
         break;
       }
       case 'query': {

package/package.json

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

package/skill/abs-agent-brain-sync/SKILL.md

@@ -19,7 +19,7 @@ description: "USE FOR abs / agent-brain-sync 跨会话记忆与任务续接。
 abs load                          # 开机读状态
 abs query <词>                    # 检索；abs resolve <页名> 反查路径
 abs todo add <id> --note "做什么"   # 登记；note/memo/state/done 见「进行中」
-abs capture [--layer 1-7] "…"    # 按七层判定落点后直接写入（不传=L4）
+abs capture [--layer 1-7] [--kind …] "…"   # 按七层判定落点后写入（--kind 分作用）
 abs note "经验" [--tags a,b]      # 暂存经验（一律 L7 混沌层）
 abs concept <slug> --title "…"    # 建概念页骨架
 abs rule add "一句话"             # 加 Rules；abs lint 体检；abs init 建图谱
@@ -110,6 +110,18 @@ abs rule add "一句话"             # 加 Rules；abs lint 体检；abs init
 
 判据不明时用 L4 —— 但**知道是工具经验就写 L3**：实测算过，本仓 52 页 concepts 里 23 页其实是 L3。
 
+**`--kind` 是另一条正交轴**（借 cl​aude-mem 的 observation 类型）：`layer` 说「什么性质」，`kind` 说「起什么作用」。
+
+| kind | 含义 | 何时用 |
+|---|---|---|
+| `gotcha` | 关键坑 | 踩了会白干、想不到的那种 |
+| `decision` | 决策 | 记「当时为什么这么选」 |
+| `tradeoff` | 权衡 | A 好但 B 也有理，最后选了哪个 |
+| `howto` | 做法 | 这类事该怎么做 |
+
+不传就不写（旧页留空，不强制补）。实测只有 `gotcha` 能靠 tags/标题机械识别，
+另三类判据在内容里 —— 别拿关键词瞎猜。
+
 `abs capture` 之后跑 `abs db rebuild` 让图数据库收录，否则检索拿不到它。
 
 ## 进行中：什么时候动它

package/src/brain/capture.js

@@ -19,6 +19,7 @@ import { cmdLog } from '../note.js';
 import { clip, slugOf } from '../text.js';
 import { LAYERS, layerOf, DEFAULT_LAYER } from './layers.js';
 import { autoIndex } from './db-cmd.js';
+import { summonTail } from './summon.js';
 
 /** 层 → 落点目录。L1/L6 不立页，由下面的分支单独处理。 */
 const LAYER_DIR = {
@@ -51,13 +52,13 @@ export function layerGuide() {
   ].join('\n');
 }
 
-export async function cmdCapture({ dir, text, layer, tags, title }) {
+export async function cmdCapture({ dir, text, layer, tags, title, kind }) {
   const clean = String(text || '').trim();
   const layerArg = String(layer || '').trim();
 
   if (!clean) {
     return [
-      '用法: abs capture [--layer 1-7] "一句话" [--tags a,b] [--title "页标题"]',
+      '用法: abs capture [--layer 1-7] [--kind gotcha|decision|tradeoff|howto] "一句话" [--tags a,b] [--title "页标题"]',
       '',
       layerGuide(),
     ].join('\n');
@@ -85,6 +86,16 @@ export async function cmdCapture({ dir, text, layer, tags, title }) {
     return r;
   }
 
+  // 作用分档（2026-11-02 借 clo​ude-mem）：gotcha 坑 / decision 决策 / tradeoff 权衡 / howto 做法。
+  // 与 layer 正交：layer 说「这是什么性质的知识」，kind 说「它起什么作用」。
+  const KIND = {
+    gotcha: '坑', decision: '决策', tradeoff: '权衡', howto: '做法',
+  };
+  const kindArg = String(kind || '').trim().toLowerCase();
+  if (kindArg && !KIND[kindArg]) {
+    return `✗ --kind 只认 ${Object.keys(KIND).join(' / ')}（收到 "${kind}"）`;
+  }
+
   let root;
   try {
     root = await requireBrain(dir || process.cwd());
@@ -120,6 +131,7 @@ export async function cmdCapture({ dir, text, layer, tags, title }) {
     '---',
     `tags: [${['concept', ...tagList].join(', ')}]`,
     `layer: ${L}`,
+    ...(kindArg ? [`kind: ${kindArg}`] : []),
     `author: ${who}`,
     `updated: ${today()}`,
     'status: draft',
@@ -153,18 +165,22 @@ export async function cmdCapture({ dir, text, layer, tags, title }) {
   const slug = file.replace(/\.md$/, '');
   const section = dirName === 'concepts' ? 'Concepts' : dirName === 'sessions' ? 'Sessions' : 'Sources';
   await registerInIndex(root, section, slug, head);
-  await cmdLog({ dir: root, title: clean, kind: 'note' });
+  await cmdLog({ dir: root, title: clean, kind: 'note', summon: false });
 
   // 落盘即入库 —— 否则用户以为记下了，检索却空手而归（静默失效）。
   // autoIndex 永不抛错也不阻塞：库坏了只是检索旧一点，不能让记笔记失败。
   const idx = await autoIndex();
 
+  // 每次总结都顺手查一遍会话历史，避免漏下没总结的会话（2026-11-02 用户要求）。
+  // 只给线索不写盘 —— 落哪一条仍是人的判断。
+  const tail = await summonTail(root);
+
   return [
     `✓ 已落入 L${L} ${meta.name}层 → ${dirName}/${file}`,
     `  ${clip(clean, 60)} ${atTag(who)}`,
     `  该层衰减 ${meta.decay}（${meta.note}）`,
     idx.ok ? '  已同步入库，abs db search 可查到' : `  （未入库：${idx.reason}）`,
-  ].join('\n');
+  ].join('\n') + tail;
 }
 
 export { LAYERS };

package/src/brain/db-cmd.js

@@ -6,12 +6,72 @@
 import { promises as fs } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { findBrainRoot, brainPath } from '../index.js';
-import { openDb, rebuild, search, illuminate, rulesOf, stats, ensureDbDir, dbPath } from './db.js';
+import { openDb, rebuild, search, illuminate, rulesOf, stats, ensureDbDir, dbPath, lastOpenRebuilt } from './db.js';
 import { LAYERS } from './layers.js';
 
 const PAGE_DIRS = ['concepts', 'entities', 'sources', 'syntheses', 'sessions'];
 const FLAT_FILES = ['index.md', 'todo.md', 'log.md'];
 
+/** 项目根路径 → 项目名（入库时的 project 字段）。
+ *
+ * 取路径末段。为何不引入 UUID（2026-11-02 评估）：项目名是给人看的标识，
+ * 出现在每条检索结果里；UUID 会让输出不可读。末段同名的风险用 `db status` 暴露，
+ * 不做静默处理。
+ */
+function projectNameOf(root) {
+  return String(root).split('/').filter(Boolean).pop() || 'unknown';
+}
+
+/** 给一批项目根算出**互不重名**的项目名。
+ *
+ * 为何需要（2026-11-02 实测）：项目名默认取路径末段，而机器上同时存在
+ *   ~/.agents 与 ~/Documents/软件/.agents，两者末段都是 `.agents` →
+ *   入库时撞 UNIQUE(project, dir, slug) 约束，整个 rebuild 失败。
+ *
+ * 消歧规则：重名的那些改用「父目录-末段」，仍重名就继续往上加，直到唯一。
+ * 只给重名的项目加前缀 —— 没重名的保持短名（检索结果里读起来更清楚）。
+ */
+export function uniqueProjectNames(roots) {
+  const seg = (p) => String(p).split('/').filter(Boolean);
+  const base = new Map(roots.map((r) => [r, seg(r).pop() || 'unknown']));
+  const groups = new Map();
+  for (const [r, n] of base) {
+    if (!groups.has(n)) groups.set(n, []);
+    groups.get(n).push(r);
+  }
+  const out = new Map();
+  for (const [name, list] of groups) {
+    if (list.length === 1) { out.set(list[0], name); continue; }
+    // 重名 → 逐层加父目录前缀，直到组内唯一
+    for (let depth = 2; depth <= 4; depth++) {
+      const cand = new Map();
+      for (const r of list) {
+        const s = seg(r);
+        cand.set(r, s.slice(Math.max(0, s.length - depth)).join('-'));
+      }
+      const vals = [...cand.values()];
+      if (new Set(vals).size === vals.length) {
+        for (const [r, v] of cand) out.set(r, v);
+        break;
+      }
+      if (depth === 4) for (const [r, v] of cand) out.set(r, v);  // 兜底：认了
+    }
+  }
+  return out;
+}
+
+/** 当前所在项目名。查询时用它决定「读哪几条铁律」。
+ *
+ * 为何要单独一个函数（2026-11-02）：原来只在 cmdDbSearch 里内联算，
+ * 与 rebuild 用的算法是两份代码 —— 任一边改了项目名规则，铁律就会读错项目的。
+ * 判据：项目名的算法只能有一处。 */
+async function currentProjectName(dir) {
+  if (process.env.ABS_PROJECT) return process.env.ABS_PROJECT;
+  const from = dir || process.cwd();
+  const root = await findBrainRoot(from);
+  return root ? projectNameOf(root) : '';
+}
+
 /** 扫一个项目的 .brain/ → 页面数组（含 index/todo/log 三份平铺文件）。 */
 async function scanProject(root, project) {
   const out = [];
@@ -80,14 +140,19 @@ export async function cmdDbRebuild({ dir } = {}) {
     return '✗ 没有可入的项目。先在项目根跑: abs db add   或  abs db rebuild';
   }
 
+  // 先收集所有有效根，再统一算项目名 —— 名字要去重，必须看到全局才知道谁重名
+  const found = [];
+  for (const root of roots) {
+    const r = await findBrainRoot(root);
+    if (r) found.push(r);                       // 登记了但目录没了 → 跳过，不报错
+  }
+  const names = uniqueProjectNames([...new Set(found)]);
   const pages = [];
   const used = [];
-  for (const root of roots) {
-    const found = await findBrainRoot(root);
-    if (!found) continue;                       // 登记了但目录没了 → 跳过，不报错
-    const project = found.split('/').filter(Boolean).pop() || 'unknown';
-    pages.push(...await scanProject(found, project));
-    used.push(`${project} (${found})`);
+  for (const f of [...new Set(found)]) {
+    const project = names.get(f);
+    pages.push(...await scanProject(f, project));
+    used.push(`${project} (${f})`);
   }
   if (!pages.length) return '✗ 登记的项目都没有 .brain/ 图谱，无可入库内容。';
 
@@ -111,7 +176,7 @@ export async function cmdDbRebuild({ dir } = {}) {
 }
 
 /** `abs db search <词>` —— 走库搜索：FTS 种子 → 亮度扩散。 */
-export async function cmdDbSearch({ query, limit = 8 } = {}) {
+export async function cmdDbSearch({ query, limit = 8, full = false } = {}) {
   const q = String(query || '').trim();
   if (!q) return '用法: abs db search <词>';
 
@@ -122,9 +187,7 @@ export async function cmdDbSearch({ query, limit = 8 } = {}) {
   const h = openDb(path);
   try {
     // L1 铁律永远先出 —— 「不可逾越」的代码保证，不靠读到文本才遵守
-    const project = process.env.ABS_PROJECT
-      || (await findBrainRoot(process.cwd()) || '').split('/').filter(Boolean).pop()
-      || '';
+    const project = await currentProjectName();
     const rules = rulesOf(h, project);
 
     const seeds = search(h, q, { limit: 12 });
@@ -136,17 +199,54 @@ export async function cmdDbSearch({ query, limit = 8 } = {}) {
       for (const r of rules) out.push(`- ${r}`);
     }
     if (!lit.length) {
-      out.push('', '（无命中。库可能是旧的：abs db rebuild 重扫）');
+      out.push('', lastOpenRebuilt()
+        ? '（库文件曾损坏被清空，现在没有内容：跑 abs db rebuild 重建）'
+        : '（无命中。库可能是旧的：abs db rebuild 重扫）');
       return out.join('\n');
     }
+    // --full：显式要求时才读正文。默认不给 —— 这是索引优先的核心。
+    // 实测（2026-11-02）：ABS 单页平均 824 token，8 页全带就是 6600 token，
+    // 而真正被用上的往往只有 1-2 页。让「看全文」成为一个显式动作。
+    const bodies = new Map();
+    if (full) {
+      const root = await findBrainRoot(process.cwd());
+      if (root) {
+        for (const p of lit) {
+          const body = await fs.readFile(brainPath(root, p.dir, `${p.slug}.md`), 'utf8').catch(() => '');
+          if (body) bodies.set(p.id, body);
+        }
+      }
+    }
+
     out.push('', '--- 按亮度排序 ---');
     for (const p of lit) {
-      const bar = '█'.repeat(Math.max(1, Math.round(Math.min(p.bright, 3) / 3 * 12)));
+      // 亮度现在是 0.3~1.0（不再是早期可能到 165 万的异常值），
+      // 条长按 1.0 满格算：0.3 → 4 格，1.0 → 12 格。
+      const bar = '█'.repeat(Math.max(1, Math.round(Math.min(p.bright, 1) * 12)));
       const where = [p.project, p.dir, p.slug].filter(Boolean).join('/');
       const tag = p.from === 'spread' ? ' ↝' : '';
-      out.push(`${bar} ${p.bright.toFixed(2)} L${p.layer} ${where}${tag}`);
+      // 跨项目的结果要显式标出来 —— 用户得知道「这条是别的项目的经验」，
+      // 否则会以为是自己项目的结论（判据、上下文都可能不同）。
+      const other = project && p.project && p.project !== project ? '  [跨项目]' : '';
+      // 索引优先：给摘要 + 取全文成本，让「要不要看全文」成为一个可算的决定。
+      const about = p.digest ? `\n            ${p.digest}` : '';
+      const cost = p.tokens ? `  ~${p.tokens}tok` : '';
+      // 作用分档（gotcha/decision/tradeoff/howto）—— 同层里「哪种更该先看」的线索
+      const KIND_ICON = { gotcha: '🔴坑', decision: '🟤决策', tradeoff: '⚖️权衡', howto: '🔵做法' };
+      const kind = p.kind && KIND_ICON[p.kind] ? `  ${KIND_ICON[p.kind]}` : '';
+      out.push(`${bar} ${p.bright.toFixed(2)} L${p.layer} ${where}${tag}${other}${kind}${cost}${about}`);
+      if (full && bodies.has(p.id)) {
+        // 正文缩进显示，便于与索引行区分
+        const body = bodies.get(p.id).replace(/^---[\s\S]*?---\n/, '');   // 去掉 frontmatter
+        out.push(...body.split('\n').slice(0, 60).map((l) => `      │ ${l}`));
+        if (body.split('\n').length > 60) out.push('      │ …（已截断，用 abs resolve 看全文）');
+      }
     }
     out.push('', '（L1 铁律恒在最前；↝ 表示由邻居扩散点亮，非直接命中）');
+    out.push('（只给摘要与成本；要看全文: abs db search <词> --full  或  abs resolve <页名>）');
+    if (project) {
+      out.push(`（铁律只显示本项目 "${project}" 的 —— 别的项目的铁律不外借）`);
+    }
     return out.join('\n');
   } finally {
     h.close();
@@ -161,9 +261,11 @@ export async function cmdDbStatus() {
 
   const h = openDb(path);
   try {
+    const rebuilt = lastOpenRebuilt();
     const s = stats(h);
     const out = [
       `📀 库: ${path}`,
+      ...(rebuilt ? ['⚠ 库文件曾损坏，已自动清空重建 —— 跑 abs db rebuild 恢复内容'] : []),
       `节点 ${s.nodes} | 边 ${s.edges} | 悬挂链接 ${s.dangling} | 断点词 ${s.anchors} | 铁律 ${s.rules}`,
       '',
       '--- 七层分布 ---',
@@ -231,14 +333,31 @@ async function cmdDbRebuildQuiet() {
   const here = await findBrainRoot(process.cwd());
   const roots = [...new Set([...registered, ...(here ? [here] : [])])];
   if (!roots.length) return;
-  const pages = [];
+  const found = [];
   for (const root of roots) {
-    const found = await findBrainRoot(root);
-    if (!found) continue;
-    const project = found.split('/').filter(Boolean).pop() || 'unknown';
-    pages.push(...await scanProject(found, project));
+    const r = await findBrainRoot(root);
+    if (r) found.push(r);
   }
+  const uniq = [...new Set(found)];
+  const names = uniqueProjectNames(uniq);
+  const pages = [];
+  for (const f of uniq) pages.push(...await scanProject(f, names.get(f)));
   if (!pages.length) return;
   const h = openDb(dbPath());
   try { rebuild(h, pages); } finally { h.close(); }
 }
+
+/** `abs db evolve` — 知识自我进化的体检：哪些被推翻、哪些堆积、哪些该合并。 */
+export async function cmdDbEvolve({ staleDays = 90 } = {}) {
+  const path = dbPath();
+  const exists = await fs.stat(path).then(() => true).catch(() => false);
+  if (!exists) return `库不存在: ${path}\n  先跑: abs db rebuild`;
+
+  const h = openDb(path);
+  try {
+    const { evolveSignals, renderEvolve } = await import('./evolve.js');
+    return renderEvolve(evolveSignals(h, { staleDays }), { staleDays });
+  } finally {
+    h.close();
+  }
+}