@fanchao8609/agent_brain_sync 1.20.1 → 1.21.0

package/src/brain/shape.js

@@ -0,0 +1,102 @@
+// src/brain/shape.js — .brain/ 三个受管文件的标准形状 + 结构核对。
+// 从 store.js 拆出（2026-11-01）：init 与 load 共用同一份形状表，
+// 单独立文件避免二者互相 import。
+import { promises as fs } from 'node:fs';
+import { brainPath } from '../index.js';
+import { editFile, SKIP } from '../lock.js';
+import { enforceBrainFormat, ensureStateMark } from '../todo.js';
+import { clip } from '../text.js';
+
+/** 标准形状表（与 indexTemplate/logTemplate/todoTemplate 同源）。
+ * 标记不一致 = 直接改成标准（“能自己处理的先处理”）。
+ * 只按**整行精确匹配**改标题，绝不动正文 —— 不做模糊替换，否则正文里提到的旧名会被误改。 */
+// sources/ 堆积阀值：超过就是「采了没消化」。lint 报 SOURCES-PILED-UP，load 顶部同步提示。
+// 两处共用同一常量 —— 阀值只有一个真源（SOURCES_MAX 在 lint.js 定义，此处导入使用）。
+
+export const BRAIN_SHAPE = {
+  'todo.md': {
+    h1: '# 📋 Todo Board',
+    order: ['## Todo', '## Done'],
+  },
+  'log.md': {
+    h1: '# 🗒 Activity Log',
+    order: [],   // log 无固定分区（条目行自带时间，倒序）
+  },
+  'index.md': {
+    h1: '# 🗂 Graph Index',
+    order: ['## Rules', '## Concepts', '## Entities', '## Sources', '## Syntheses', '## Sessions'],
+  },
+};
+
+/** 旧标记 → 标准标记。load 发现就改（幂等）。含 H1 与分区/分组标题的旧名。 */
+export const LEGACY_MARKS = [
+  ['# 🗂 图谱索引', '# 🗂 Graph Index'],
+  ['# 🗒 操作日志', '# 🗒 Activity Log'],
+  ['# 📋 Todo 看板', '# 📋 Todo Board'],
+  ['# 操作日志', '# 🗒 Activity Log'],
+  ['# 图谱索引', '# 🗂 Graph Index'],
+  ['# Todo 看板', '# 📋 Todo Board'],
+  // 四区 → 两区（2026-09-13 用户定）。**这条路径是 load 走的**（rebuildStructure），
+  // 与 todo.js 的 LEGACY_SECTION_RENAMES（normalizeTodo 用）是两条独立迁移路径 ——
+  // 只改一处会导致另一条认不出旧区名，把它们当"非标准分区"原样留末尾（未完成任务
+  // 留在文件里但不再被当 TODO）。测试 'load 也要能迁移' 钉住这一点。
+  ['## Backlog', '## Todo'],
+  ['## Today / In Progress', '## Todo'],
+  ['## Blocked', '## Todo'],
+  ['## Done（只留近期，旧的迁 log.md/快照）', '## Done'],
+  ['### 归档', '### Archived'],
+  ['### （未标日期）', '### Undated'],
+];
+
+/** 全套旧标记 → 标准标记（含 H1）。shape 核对与 gate 写入两处共用，故放在这里。 */
+export const legacyRenames = () => LEGACY_MARKS;
+
+/**
+ * 核对 index/log/todo 的结构，不符就按标准重建（B 档：重排分区 + 内容按归属回填）。
+ * 它每次 load 都跑，所以改动立即生效，不必等额外命令。
+ *
+ * 边界（内容安全）：
+ *   - 只动**标题行位置**与缺失分区的空位，已有内容行按原归属搬运，不改写；
+ *   - **非标准分区原样留在末尾**（人自加的区不合入，机器不猜语义）；
+ *   - log.md 不做重排（无固定分区，条目自带时间倒序）；
+ *   - 锁内重算 + “改了才写盘”，幂等。
+ *
+ * 不抛错（load 不能因核对失败而挂）。返回 { fixed:[描述], warn:[描述] }。
+ */
+export async function checkBrainShape(root) {
+  const fixed = [];
+  const warn = [];
+  for (const [file, spec] of Object.entries(BRAIN_SHAPE)) {
+    const p = brainPath(root, file);
+    let text;
+    try { text = await fs.readFile(p, 'utf8'); } catch { continue; }
+    if (!text.trim()) continue;
+    const l1 = (text.split('\n')[0] || '').trim();
+    const knownH1 = l1 === spec.h1 || LEGACY_MARKS.some(([o]) => o === l1 && o.startsWith('# '));
+    let changed = [];
+    await editFile(p, (cur) => {
+      if (cur === null) return SKIP;
+      // 格式闸门收口在一处（见 todo.js enforceBrainFormat）：样式/空行/无头 三条规则
+      // 与写入侧共用同一实现，写盘前顺手把破坏格式的部分整理回标准形态。
+      // 走 normalizeTodo 的语义（Blocked → [滞留中]）由 enforceBrainFormat 内部保证。
+      const r = enforceBrainFormat(cur, { ...spec, renames: legacyRenames() });
+      // 兜底：仍无状态标记的未完成任务补默认值（新格式文件本就有标记，此处不触发）。
+      const next2 = file === 'todo.md'
+        ? r.text.split('\n').map((l) => (l.startsWith('- [ ] ') ? ensureStateMark(l, '进行中') : l)).join('\n')
+        : r.text;
+      if (next2 === cur) return SKIP;
+      changed = r.fixed.length ? r.fixed : ['结构按标准重排'];
+      return { text: next2 };
+    }).catch((e) => {
+      // 不能吞：load 是开机第一入口，静默跳过会让人以为库是健康的。
+      // 典型触发：文件里有孤儿子任务（真错，不修而报）。
+      // 只报**具体问题行**（以 `·` 开头的那些），不把整个错误头拼进去。
+      const msg = e && e.message ? e.message : '未知错误';
+      const detail = msg.split('\n').filter((x) => x.trim().startsWith('·')).map((x) => x.trim().slice(1).trim());
+      warn.push(`${file}: 未能自动归一 —— ${detail.length ? detail.join('; ') : msg.split('\n')[0]}`.slice(0, 200));
+    });
+    if (changed.length) fixed.push(`${file}: ${changed.join('; ')}`);
+    if (!knownH1) warn.push(`${file}: 标题非标准（读到 "${clip(l1, 24) || '(空)'}"）`);
+  }
+  return { fixed, warn };
+}

package/src/brain/summon-cmd.js

@@ -0,0 +1,62 @@
+// src/brain/summon-cmd.js — `abs summon` 命令族：会话总结的托底扫描。
+//
+// 定位：正常路径是收尾时 `abs capture` / `abs log`。这条路被跳过时，本命令把
+// 「有实质内容但还没总结」的会话提出来。它是托底，不是替代。
+//
+// 三个动作：
+//   abs summon            扫当前项目，列出未总结 / 有更新的会话（只读，不写盘）
+//   abs summon --mark     把本次列出的记为「已提取」，下次不再列
+//   abs summon --status   看账本统计
+import { resolve } from 'node:path';
+import { findBrainRoot } from '../index.js';
+import {
+  scanProject, renderScan, readLedger, writeLedger, markSummarized, ledgerPath,
+} from './summon.js';
+
+/** 解析项目根：显式 --dir 优先，否则用当前目录的图谱根。 */
+async function resolveRoot(dir) {
+  if (dir) {
+    const r = await findBrainRoot(resolve(dir));
+    if (!r) throw new Error(`✗ ${resolve(dir)} 下没有 .brain/ 图谱`);
+    return r;
+  }
+  const here = await findBrainRoot(process.cwd());
+  if (!here) throw new Error('✗ 当前目录没有 .brain/ 图谱（用 --dir 指定，或先 abs init）');
+  return here;
+}
+
+export async function cmdSummon({ dir, mark = false, full = false, limit = 15, status = false } = {}) {
+  const path = ledgerPath();
+
+  if (status) {
+    const book = await readLedger(path);
+    const n = Object.keys(book.files).length;
+    const days = new Set(Object.values(book.files).map((r) => r.day).filter(Boolean));
+    return [
+      `📒 总结账本: ${path}`,
+      `已记录 ${n} 个会话，跨 ${days.size} 天`,
+      n ? `最近一条: ${Object.entries(book.files).sort((a, b) => (b[1].summarizedAt || '').localeCompare(a[1].summarizedAt || ''))[0].map((x) => Array.isArray(x) ? JSON.stringify(x).slice(0, 90) : x).join(' · ')}` : '',
+    ].filter(Boolean).join('\n');
+  }
+
+  let root;
+  try { root = await resolveRoot(dir); } catch (e) { return e.message; }
+
+  const book = await readLedger(path);
+  const result = await scanProject(root, { ledger: book });
+
+  const pending = [...result.fresh, ...result.changed];
+  if (!mark) return renderScan(result, { full, limit });
+
+  // --mark：记为已提取。不写知识页 —— 那是人的判断，不是本命令的。
+  if (!pending.length) return '✓ 没有待提取的会话，账本未改动。';
+  markSummarized(book, pending);
+  await writeLedger(book, path);
+  return [
+    `✓ 已记账 ${pending.length} 个会话（下次不再列出）`,
+    `  账本: ${path}`,
+    '',
+    '注意：这一步只记「这些会话我提过了」，**没有写任何知识页**。',
+    '要沉淀的仍要显式落: abs capture --layer N "…" / abs log "…"',
+  ].join('\n');
+}

package/src/brain/summon.js

@@ -0,0 +1,236 @@
+// src/brain/summon.js — 会话总结的托底：扫 pi 会话目录，找出「还没总结过」的会话。
+//
+// 为何需要它（2026-11-01 实测）：pi 会话目录里本项目 63 个会话跨 26 天，
+//   而 .brain/sessions/ 只有 19 天有快照 —— 缺 12 天。正常路径是收尾时人主动总结，
+//   但这个动作会被跳过。「琐碎知识没有正常总结」是结构问题：会话发生了，没人回头提炼。
+//   本命令是**托底**，不是替代：有快照就不管，没快照才提出来。
+//
+// 判重靠 md5 账本（用户定，2026-11-01）：
+//   每条已总结的会话记录其文件 md5。下次扫描：
+//     · md5 相同 → 已总结过，跳过
+//     · md5 不同 → 会话被补写过（同一会话继续聊），要**补充总结**
+//   为何用 md5 而不是 mtime/size：mtime 会因任何触碰变化（备份、同步），
+//   size 在「改了同一长度内容」时不变。md5 是内容判据，恰好对应「会话内容变没变」。
+//   代价是读全文 —— 实测本项目 63 个文件 55MB，全读约 0.2s，可接受。
+//
+// 边界（守「已存在的人工内容一律不覆盖」）：
+//   本命令**只输出摘要给人看，不写任何 .brain/ 知识页**。
+//   账本只记「这个会话文件我提过了」，不记内容判断。
+//   要落哪一条由人确认后显式 `abs capture` / `abs log`。
+//
+// 会话文件格式（pi，2026-11-01 实测）：
+//   JSONL，每行 { type: 'session' | 'message' | ... }；message.content 是**数组**。
+//   坑：曾按 typeof content === 'string' 判断 → 用户消息恒 0 条。
+
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+
+/** 活跃会话判定：mtime 在此毫秒内 → 文件还在写，本轮跳过。
+ * 实测（2026-11-01）当前会话 0 分钟前，其余最晚 189 分钟前，30 分钟阈值安全。 */
+export const ACTIVE_MS = 30 * 60 * 1000;
+
+/** 会话根目录。ABS_PI_SESSIONS 可覆盖（测试隔离 / 别的宿主）。 */
+export function sessionsRoot() {
+  return process.env.ABS_PI_SESSIONS || join(homedir(), '.pi', 'agent', 'sessions');
+}
+
+/** 项目绝对路径 → pi 的会话目录名。
+ *
+ * 规则（2026-11-01 实测 pi 的 42 个真实目录反推，5 个样本全通过）：
+ *     `--` + 去掉开头的 `/` + 所有 `/` 换成 `-` + `--`
+ *     `/Users/fanchao/Code/agent_brain_sync`
+ *     → `--Users-fanchao-Code-agent_brain_sync--`
+ *
+ * 坑一：曾用 `replace(/[^A-Za-z0-9]/g, '-')` —— 下划线 `_` 也被换掉，
+ *   `agent_brain_sync` 变 `agent-brain-sync`，目录找不到（实测报错）。
+ *   `_` 与 `.` 必须原样保留。
+ * 坑二：这个编码**不可逆**——路径本身可能含 `-`（如 `vibe-coding-help`），
+ *   解码时无法区分哪个 `-` 原本是 `/`。实测 42 个目录只有 14 个能解码回存在的路径。
+ *   所以只能按本函数正向拼，不要试图反查。 */
+export function projectDirName(projectRoot) {
+  const body = String(projectRoot).replace(/^\/+/, '').replace(/\//g, '-');
+  return `--${body}--`;
+}
+
+/** 账本路径：和库同目录（~/.abs/summarized.json），ABS_SUMMON_LEDGER 可覆盖。 */
+export function ledgerPath() {
+  return process.env.ABS_SUMMON_LEDGER || join(homedir(), '.abs', 'summarized.json');
+}
+
+/** content 数组取纯文本。string 也兼容。 */
+function textOf(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter((c) => c && c.type === 'text').map((c) => c.text || '').join('\n');
+}
+
+/** 是否值得当成「用户真说的话」。滤掉注入块与无信息量的单句。 */
+function isRealUserText(t) {
+  const s = String(t || '').trim();
+  if (!s) return false;
+  if (s.startsWith('<')) return false;                 // 系统注入块
+  if (s.startsWith('[abs')) return false;              // abs 自己的提醒
+  if (s.startsWith('[SYSTEM')) return false;
+  if (s.length <= 4 && /^(abs|继续|好的|是的|嗯|ok|好)$/i.test(s)) return false;
+  return true;
+}
+
+/** 会话文件 md5。判「内容有没有变」的唯一可靠判据。 */
+async function md5Of(file) {
+  const buf = await fs.readFile(file).catch(() => null);
+  if (!buf) return null;
+  return createHash('md5').update(buf).digest('hex');
+}
+
+/** 解析一个会话文件 → 摘要素材。 */
+export async function digestSession(file) {
+  let raw;
+  try { raw = await fs.readFile(file, 'utf8'); } catch { return null; }
+  const out = {
+    file, start: '', endedAt: '', day: '',
+    users: [], filesEdited: new Map(), toolCalls: 0,
+  };
+  for (const l of raw.split('\n')) {
+    if (!l) continue;
+    let o;
+    try { o = JSON.parse(l); } catch { continue; }
+    if (o.type === 'session') { out.start = o.timestamp || ''; out.cwd = o.cwd; continue; }
+    if (o.type !== 'message') continue;
+    if (o.timestamp) out.endedAt = o.timestamp;
+    const m = o.message || {};
+    if (m.role === 'user') {
+      const t = textOf(m.content).trim();
+      if (isRealUserText(t)) out.users.push(t);
+    } else if (m.role === 'assistant' && Array.isArray(m.content)) {
+      for (const c of m.content) {
+        if (!c || c.type !== 'toolCall') continue;
+        out.toolCalls++;
+        const p = c.arguments && c.arguments.path;
+        if (p && typeof p === 'string' && ['edit', 'write'].includes(c.name)) {
+          out.filesEdited.set(p, (out.filesEdited.get(p) || 0) + 1);
+        }
+      }
+    }
+  }
+  out.day = (out.start || '').slice(0, 10);
+  return out;
+}
+
+/** 已有快照的日期集合（从 .brain/sessions/*.md 文件名取）。
+ *
+ * 为何要和 md5 账本并用（2026-11-01）：两条判据回答的是不同问题 ——
+ *   · 有快照         → 那天**已经总结过**（人写的，最权威）
+ *   · 账本记录 md5   → 那个**会话文件**提过了
+ * 只按 md5 判会把「已有快照的日子」全列出来当未总结（实测 15 条全是已有快照的），
+ * 那是把托底做成噪音。两条都要：有快照就跳过，没有才看账本。 */
+async function daysWithSnapshot(brainSessionsDir) {
+  const days = new Set();
+  let files;
+  try { files = await fs.readdir(brainSessionsDir); } catch { return days; }
+  for (const f of files) {
+    const m = f.match(/(\d{4}-\d{2}-\d{2})/);
+    if (m) days.add(m[1]);
+  }
+  return days;
+}
+
+/** 读账本。格式 { version, files: { "<相对文件名>": { md5, day, summarizedAt } } } */
+export async function readLedger(path = ledgerPath()) {
+  try {
+    const j = JSON.parse(await fs.readFile(path, 'utf8'));
+    if (j && typeof j.files === 'object') return j;
+  } catch { /* 不存在或坏了 → 空账本 */ }
+  return { version: 1, files: {} };
+}
+
+/** 写账本（原子：tmp + rename）。 */
+export async function writeLedger(ledger, path = ledgerPath()) {
+  await fs.mkdir(join(path, '..'), { recursive: true });
+  const tmp = `${path}.tmp-${Date.now()}`;
+  await fs.writeFile(tmp, JSON.stringify(ledger, null, 2) + '\n');
+  await fs.rename(tmp, path);
+}
+
+/**
+ * 扫一个项目，分三类：
+ *   fresh    —— 从未总结过（账本里没有）
+ *   changed  —— 总结过但 md5 变了（会话被续写，要补充）
+ *   skipped  —— md5 一致（真的总结过了）
+ * 跳过活跃会话（文件仍在写），避免把半截内容记成已总结。
+ */
+export async function scanProject(projectRoot, { ledger, now = Date.now() } = {}) {
+  const dir = join(sessionsRoot(), projectDirName(projectRoot));
+  let names;
+  try { names = (await fs.readdir(dir)).filter((f) => f.endsWith('.jsonl')); } catch {
+    return { error: `找不到会话目录: ${dir}`, fresh: [], changed: [], skipped: [], active: [] };
+  }
+  const book = ledger || await readLedger();
+  // 已有快照的日子整日跳过 —— 人已经总结过，托底不该再吵。
+  const haveSnapshot = await daysWithSnapshot(join(projectRoot, '.brain', 'sessions'));
+  const fresh = [], changed = [], skipped = [], active = [];
+
+  for (const name of names.sort()) {
+    const full = join(dir, name);
+    let st;
+    try { st = await fs.stat(full); } catch { continue; }
+    if (now - st.mtimeMs < ACTIVE_MS) { active.push({ name, reason: '会话仍在写' }); continue; }
+
+    const md5 = await md5Of(full);
+    if (!md5) continue;
+    const d = await digestSession(full);
+    if (!d || !d.users.length) { skipped.push({ name, reason: '无真实用户输入' }); continue; }
+    if (d.day && haveSnapshot.has(d.day)) { skipped.push({ name, reason: `${d.day} 已有快照` }); continue; }
+
+    const rec = book.files[name];
+    if (rec && rec.md5 === md5) { skipped.push({ name, reason: 'md5 一致' }); continue; }
+
+    const item = { name, md5, day: d.day, digest: d, sizeKB: Math.round(st.size / 1024) };
+    if (rec) changed.push({ ...item, prevMd5: rec.md5 }); else fresh.push(item);
+  }
+  return { fresh, changed, skipped, active, dir };
+}
+
+/** 记一笔：这些会话已提取（不管人是否落盘，账本只记「提过了」）。 */
+export function markSummarized(ledger, items, when = new Date().toISOString()) {
+  for (const it of items) {
+    ledger.files[it.name] = { md5: it.md5, day: it.day, summarizedAt: when };
+  }
+  return ledger;
+}
+
+/** 渲染待确认清单。不写盘。 */
+export function renderScan(result, { full = false, limit = 15 } = {}) {
+  if (result.error) return `✗ ${result.error}`;
+  const out = [
+    `会话目录: ${result.dir}`,
+    `未总结 ${result.fresh.length} 个 · 有更新 ${result.changed.length} 个 · 已总结 ${result.skipped.length} 个 · 活跃跳过 ${result.active.length} 个`,
+  ];
+  const show = (title, items, tail) => {
+    if (!items.length) return;
+    out.push('', `--- ${title} (${items.length}) ---`);
+    for (const it of items.slice(0, limit)) {
+      out.push(`${it.day}  ${it.sizeKB}KB  ${it.name.slice(0, 34)}`);
+      const sample = it.digest.users.slice(0, full ? 8 : 2);
+      for (const u of sample) {
+        out.push(`   · ${u.replace(/\s+/g, ' ').trim().slice(0, full ? 200 : 70)}`);
+      }
+      if (tail) out.push(`   ${tail}`);
+    }
+    if (items.length > limit) out.push(`  …另有 ${items.length - limit} 个`);
+  };
+  show('从未总结', result.fresh);
+  show('总结过但有更新（会话被续写，需补充）', result.changed, '↳ md5 与账本不符');
+  if (!result.fresh.length && !result.changed.length) {
+    out.push('', '✓ 所有已结束的会话都总结过了。');
+  } else {
+    out.push(
+      '',
+      '这是**待确认清单，不会自动写盘**。落哪一条由你判断：',
+      '  abs capture --layer 4 "…"   或   abs log "完成 X：…"',
+      '  abs summon --mark            记下「这些已提取」，下次不再列出',
+    );
+  }
+  return out.join('\n');
+}

package/src/note.js

@@ -12,6 +12,18 @@ import { editFile, SKIP } from './lock.js';
 import { impactOf } from './codegraph.js';
 import { clip, slugOf } from './text.js';
 
+
+/** 惰性调 autoIndex —— 断循环 import：note.js ← capture.js ← db-cmd.js ← note.js。
+ * 动态 import 只在真正写入时解析，静态加载期不受影响。失败一律吞掉（见 autoIndex 边界）。 */
+async function autoIndexLazy() {
+  try {
+    const { autoIndex } = await import('./brain/db-cmd.js');
+    return await autoIndex();
+  } catch {
+    return { ok: false, reason: '入库模块不可用' };
+  }
+}
+
 // ---------- note: 经验实时暂存（source 页，一念一落，防流失） ----------
 
 export async function cmdNote({ dir, text, tags, when, impact, type }) {
@@ -91,6 +103,8 @@ export async function cmdNote({ dir, text, tags, when, impact, type }) {
   const slug = file.replace(/\.md$/, '');
   await registerInIndex(root, 'Sources', slug, heading);
   await cmdLog({ dir: root, title: clean, kind: 'note' });
+  // 落盘即入库（库已存在时）。失败不阻断 —— 见 autoIndex 的边界说明。
+  await autoIndexLazy();
   return `✓ 经验暂存 → sources/${file}\n  ${clean} ${atTag(who)}`;
 }
 
@@ -174,6 +188,7 @@ export async function cmdConcept({ dir, slug, title, tags, desc }) {
   }
   const oneLine = String(desc || '').trim() || clip(head, 60);
   await registerInIndex(root, 'Concepts', name, oneLine);
+  await autoIndexLazy();
   // 不写 log.md（2026-10-05 用户定）：`新建概念页 x` 是**命令的副作用**不是成果 ——
   // 38 字符、零信息量，且「该页存在」已由 registerInIndex 落在 index.md 的 Concepts 区
   // （那是 index 的职责）。同件事落两处，且建 10 个页 = 10 行流水噪声自动重现，