@fanchao8609/agent_brain_sync 1.19.4 → 1.19.6

package/package.json

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

package/src/lock.js

@@ -15,22 +15,17 @@ export class LockTimeout extends Error {}
 let formatGate = null;
 export function setFormatGate(fn) { formatGate = fn; }
 
-/** 三个受管文件名 —— 它们存在就是为了当“数据库表”，格式必须恒定。 */
-const MANAGED = new Set(['index.md', 'log.md', 'todo.md']);
-
 /** 懒加载闸门：**漏了 setFormatGate 就等于没闸门**，而注册是 import 副作用，
  *  谁少 import 一次 store.js 就静默裂开（2026-10-18 实测：只 import lock.js 时
  *  裸散文直接写进了 index.md）。故这里不信任外部注册，缺失时自己补上。
  *
- * 补不上（= store.js 没调 setFormatGate）就对受管文件硬拒：宁可写失败也不要格崩坏
- * ——写不进去能重试，写脏了没人知道。 */
-async function gateFor(file) {
+ * 返回 null 表示「该文件不归闸门管」（非受管文件，或闸门自己说不管）—— 原样写盘。
+ * 依赖：`store.js` 顶层无条件调 `setFormatGate`（见那里）。若那行被删，受管文件
+ * 会退回静默直写 —— 这是已知的单点，防它靠 review 不靠代码（加守卫就是给不可能发生的
+ * 情况多写 6 行，2026-10-18 审查定）。 */
+async function gateFor() {
   if (!formatGate) await import('./store.js'); // 它的模块顶层会调 setFormatGate
-  if (formatGate) return formatGate;
-  if (MANAGED.has(basename(file))) {
-    throw new Error(`✗ ${basename(file)} 是受管文件，但格式闸门未注册 —— 拒绝写入（防止格崩坏）`);
-  }
-  return null;
+  return formatGate;
 }
 const LOCK_WAIT_BASE_MS = 15;  // 指数退避起始重试间隔
 const LOCK_WAIT_MAX_MS = 150;  // 指数退避上限
@@ -99,7 +94,7 @@ export async function editFile(file, mutator) {
     //   闸门缺失时以前会静默跳过（直写盘），现在改为自己补加载；补不上就硬拒，
     //   宁可写失败也不要格崩坏——写不进去能重试，写脏了没人知道。
     if (write) {
-      const gate = await gateFor(file);
+      const gate = await gateFor();
       if (gate) write = gate(file, write, current) ?? write;
     }
     if (write && write !== current) {

package/src/note.js

@@ -27,11 +27,16 @@ export async function cmdNote({ dir, text, tags, when, impact, type }) {
   await ensurePersonPage(root, who); // 首次写操作即建人页（已存在不动）
   const srcDir = brainPath(root, 'sources');
   await fs.mkdir(srcDir, { recursive: true });
-  // 幂等: 同文本已落过就不再落一份（判据是内容包含，不看时间）
+  // 幂等: 同文本已落过就不再落一份。
+  // ★ 判据必须是**整条相等**，不是 `body.includes(clean)`（2026-10-19 实测修正）：
+  //   子串判据会把「新经验恰好是某条旧经验的子串」当成重复丢掉 —— 实测已落
+  //   "load 慢的根因在 matchPage 缓存" 后再 `note "缓存"`，直接被判「已落过」跳过，
+  //   内容永久丢失且只报一句「跳过重复」。比对落盘时写下的 `TITLE: <原文>` 整行。
+  const titleLine = `TITLE: ${clean}`;
   const existing = (await fs.readdir(srcDir).catch(() => [])).filter((f) => f.endsWith('.md'));
   for (const f of existing) {
     const body = await fs.readFile(join(srcDir, f), 'utf8').catch(() => '');
-    if (body.includes(clean)) {
+    if (body.split('\n').some((l) => l.trim() === titleLine)) {
       return `• 已落过同文本 → ${f} (跳过重复)`;
     }
   }
@@ -261,13 +266,19 @@ export async function cmdLog({ dir, title, kind = 'dev' }) {
   // 作者前置于 kind：`## [时间] @name dev | 内容`。
   // 一眼先看到谁做的（与 todo 行 `ID @name — 说明` 排版对齐）。
   const line = `## [${stamp}] ${atTag(who)} ${kind} | ${clean}`;
-  await editFile(p, (cur) => {
+  const res = await editFile(p, (cur) => {
     const text = cur ?? '# 🗒 Activity Log\n';
     // 倒序：新行插在标题后（若已是模板占位行则替换它）
     const lines = text.split('\n');
     const headerIdx = lines.findIndex((l) => l.startsWith('#'));
+    // ★ 幂等（2026-10-19 实测补）：同一分钟内同文重复调（cmdNote 结尾自动写一条 -
+    //   收尾又写一条 / 重试）会落成多行一模一样的流水。时间戳只到分钟，同段重写
+    //   就是完全意义上的重复记录。判据用整行相等，不靠计数。
+    if (lines.slice(headerIdx + 1).some((l) => l === line)) return SKIP;
     lines.splice(headerIdx + 1, 0, line);
     return { text: lines.join('\n') };
   });
+  // 重复时不报「✓ 已写入」—— 那是在说假话（用户会以为多了一条）。
+  if (res === SKIP) return `• 同一分钟已有同一内容，已跳过 → ${p}\n  ${line}`;
   return `✓ log → ${p}\n  ${line}`;
 }

package/src/store.js

@@ -13,24 +13,28 @@ import { clip, slugOf } from './text.js';
 export { clip, slugOf } from './text.js';
 
 // 页面生命周期已拆到 page.js（2026-10-05）。
-// 必须【先 import 再 export】—— 只写 `export {x} from` 只是转发，本文件作用域里
-// 拿不到 x，内部调用会 ReferenceError（拆完先跑测试就抓到了这个）。
-import {
-  idOfPage, backfillPageId, statusOfPage, supersededByOf,
-  cmdSupersede, resolvePage, cmdReview, cmdResolve, collapseIndex,
-} from './page.js';
+// ★ 只用 `export {x} from` 转发 —— 本文件内部**不再**调用它们（2026-10-19 核对：
+//   11 个符号在 store.js 里除了 import/export 两行之外零出现）。
+//   历史注释说「必须先进 import 再 export」，那是拆分当时 idOfPage 等还在内部用的写法；
+//   现在它们已全部只在 page.js/note.js 内部使用，多留一份 import 就是死代码。
+//   若将来本文件又要内部调用某个符号，再单独 import 它（单独 import 才不触发 lint）。
 export {
   idOfPage, backfillPageId, PAGE_STATUS, statusOfPage, supersededByOf,
   cmdSupersede, resolvePage, cmdReview, cmdResolve, collapseIndex,
 } from './page.js';
+// 本文件内部真在调用的两个，必须**另行 import**（`export {x} from` 不建立本地绑定）。
+// 两者既转发又内部用，所以 export 行与 import 行各留一份——这不是冗余。
+import { collapseIndex } from './page.js';
 
-// 经验暂存/知识页脚手架已拆到 note.js（2026-10-05）—— 同样先 import 再 export。
-import { cmdLog, cmdNote, cmdConcept, ensurePersonPage, registerInIndex } from './note.js';
+// 经验暂存/知识页脚手架已拆到 note.js（2026-10-05）—— 同样转发。
 export { cmdLog, cmdNote, cmdConcept, ensurePersonPage, registerInIndex } from './note.js';
+import { ensurePersonPage } from './note.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, foldSameKind } from './lint.js';
-import { SOURCES_MAX, PAGE_DIRS, listPages } from './lint.js';
+// SOURCES_MAX / listPages 本文件内部真在用（load 的 sources 提醒 + queryHint），
+// 必须单独 import；PAGE_DIRS 内部零使用，已在上一行转发，不重复 import。
+import { SOURCES_MAX, listPages } from './lint.js';
 
 // ---------- init: 建 .brain/ 骨架 ----------
 const BRAIN_DIRS = ['entities', 'concepts', 'sources', 'syntheses', 'sessions'];
@@ -259,7 +263,14 @@ export async function checkBrainShape(root) {
       if (next2 === cur) return SKIP;
       changed = r.fixed.length ? r.fixed : ['结构按标准重排'];
       return { text: next2 };
-    }).catch(() => {});
+    }).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) || '(空)'}"）`);
   }
@@ -315,7 +326,10 @@ export async function cmdLoad({ dir }) {
       ...shape.fixed.map((a) => `  ✓ 已补: ${a}`),
       ...shape.warn.map((a) => `  ⚠ ${a}`),
     ];
-    if (shape.warn.length) rows.push('  （无头文件不自动改：结构可能整体脱轨，请手工对齐 .brain/ 模板）');
+    // 那句提示只适用于「标题非标准」：其他 warn（如格式不合规）说这句会误导。
+    if (shape.warn.some((a) => a.includes('标题非标准'))) {
+      rows.push('  （无头文件不自动改：结构可能整体脱轨，请手工对齐 .brain/ 模板）');
+    }
     sections.push('--- 文件形状核对 ---', ...rows, '');
   }
   // 未设姓名/姓名是占位名时开场就提醒 —— load 是开机第一屏，不在这里提，
@@ -986,7 +1000,6 @@ async function markDone(file, id, kind = '落地', conclusion, bySid = '') {
     let changed = false;
     let moved = null;
     const kept = [];
-    const leftBehind = [];
     const wantId = String(id).replace(/\u200b/g, '');
     for (let i = 0; i < lines.length; i++) {
       const l = lines[i];
@@ -1012,15 +1025,9 @@ async function markDone(file, id, kind = '落地', conclusion, bySid = '') {
         const head = withDoneKind(`${base}${tail} ${parts.join(' ')}`, kind);
         const bp = [];
         const leftover = [];
-        // 子项搬运：已勾选的随任务进 Done；**未勾选的不搬**，留在 Todo 区。
-        //
-        // 为何（2026-10-18 实测）：Done 区被 collapseDone 折叠成计数，搬进去即「看板里
-        // 消失」。实测 factory-docs-slim 就带着「待做六链」的 `- [ ]` 落地，那条待办
-        // 此后无处可寻，同时父任务盖着【落地】——看板与事实矛盾。
-        //
-        // 为何不是硬拦（A 方案被否）：`abs todo note` 写的子项与断点记录**同形**（都是
-        // `  - [ ] …`），无法从字段上区分「待办」与「过程记录」；硬拦会把所有带断点的
-        // 任务一起拦住（实测弄挂两条既有测试）。改为「不搬 + 点名」，信息不丢且不误伤。
+        // 子项搬运：**已勾选**的随任务进 Done；未勾选的不搬（下方直接拒）。
+        // 已勾的必须搬：否则任务进 Done 了、子项剩在原区，就是无主孤儿行，
+        // 重建分区时会被清掉（历史上就是这么丢过数据）。
         while (i + 1 < lines.length) {
           const nx = lines[i + 1];
           if (!nx.trim()) break;
@@ -1068,15 +1075,11 @@ async function markDone(file, id, kind = '落地', conclusion, bySid = '') {
     }
     if (!changed || !moved) return SKIP;
     // 归位 + 按日期分组：insertDoneGrouped 一次重建 Done 区（新日期在前，未标日期归尾）
-    return { text: insertDoneGrouped(kept.join('\n'), moved), leftBehind };
+    return { text: insertDoneGrouped(kept.join('\n'), moved) };
   });
   return res === SKIP
     ? `[NO_MATCH] 未找到含 "${id}" 的未完成任务行`
-    : `✓ 已完成并归位 Done: ${id} 【${kind}】` +
-        (res.leftBehind?.length
-          ? `\n  ⚠ ${res.leftBehind.length} 条未勾子项留在 Todo 区（未跟入 Done，仍可在看板看到）：\n` +
-            res.leftBehind.map((p) => `    - [ ] ${p}`).join('\n')
-          : '');
+    : `✓ 已完成并归位 Done: ${id} 【${kind}】`;
 }
 
 // ---------- show: 查看 index/todo/log（只读面） ----------

package/src/text.js

@@ -10,8 +10,13 @@
  * 用户与后续会话看到的天然是半句 —— "摘要读起来抽象"的真因在写入口, 不在表述能力。 */
 export function clip(text, n) {
   const s = String(text || '').trim();
-  if (s.length <= n) return s;
-  const head = s.slice(0, n);
+  // 按**码点**切，不按 UTF-16 下标（2026-10-19 实测修正）：emoji 等星平面字符
+  // 占两个 code unit，s.slice 会把它拦腰切开 → 写出半个代理对（实测
+  // clip('😀😀😀😀😀😀', 3) 得 "😀\ud83d…"，落到 readme 里就是乱码）。
+  // Array.from 按码点拆，再逐步长度判断。
+  const cps = Array.from(s);
+  if (cps.length <= n) return s;
+  const head = cps.slice(0, n).join('');
   // 优先在标点处断开（中文句读 + 英文句读），其次空格，最后才硬切
   const cut = Math.max(
     head.lastIndexOf('。'), head.lastIndexOf('；'), head.lastIndexOf('！'), head.lastIndexOf('？'),
@@ -19,16 +24,18 @@ export function clip(text, n) {
     head.lastIndexOf('.'), head.lastIndexOf(' '),
   );
   // 边界太靠前（< 一半）说明这一段本就是长句，宁可硬切也不留个残破的短头
-  const keep = cut > n / 2 ? cut : n;
-  return `${s.slice(0, keep).replace(/[\s,，、;；.。]+$/, '')}…`;
+  const keep = cut > n / 2 ? head.slice(0, cut) : head;
+  return `${keep.replace(/[\s,，、;；.。]+$/, '')}…`;
 }
 
 /** slug：取前 n 码点 → 非词字符折叠为 '-'。只用于**文件名**，完整标题另存 TITLE 行。
  * 在标点/空格边界收口，不在字中间切断（否则出 `...-硬切-不` 这种残尾）。 */
 export function slugOf(text, n = 24) {
   const s = String(text || '').trim();
-  let head = s.slice(0, n);
-  if (s.length > n) {
+  // 同 clip：按码点切，避免把 emoji 切成半个代理对（见 clip 注释）。
+  const cps = Array.from(s);
+  let head = cps.slice(0, n).join('');
+  if (cps.length > n) {
     const cut = Math.max(head.lastIndexOf('，'), head.lastIndexOf('。'), head.lastIndexOf('、'),
       head.lastIndexOf('：'), head.lastIndexOf(','), head.lastIndexOf('.'), head.lastIndexOf(' '));
     if (cut > n / 2) head = head.slice(0, cut);

package/src/todo/spec.js

@@ -84,12 +84,16 @@ export const ENTRY_SHAPES = {
         // 摘要里不许带 Markdown 结构符（实测污染就是摘要取了页面正文开头）
         if (/^\s*-\s*\[\[[^\]]+\]\]\s*[—-]\s*#+\s/.test(l)) return '摘要不能带 `## ` 标题前缀（取页面首行标题了）';
         // ★ 2026-10-18 补：摘要正文本身必须是**纯文本一句话**。
-        //   原规则只拦了 `## ` 前缀，实测下列全放行：摘要写成 `- 列表项`（变成嵌套列
-        //   表）、```js（开代码围栏，把后面所有条目吞进去）、`| a | b |`（表格）。
-        //   index 是表，摘要是一列纯文本，不能携带任何块级结构。
+        //   原规则只拦了 `## ` 前缀，实测下列全放行：摘要写成 `- 列表项`（看着就像
+        //   另一条条目）、```js（开代码围栏把后面全吞）、`| a | b |`（表格）。
+        //   index 是表，摘要是一列纯文本。
+        //
+        //   但别拦过头：摘要位置在 `- [[页名]] — ` 之后，是**一行中间**，
+        //   `+ ` / `* ` / `> ` / `1. ` 在这里不会真渲染成块级结构，都是人话开头
+        //   （实测放过一次「+ 一点补充」被误拒）。只拦真正会破坏解析的几种。
         const desc = l.replace(/^\s*-\s*\[\[[^\]]+\]\]\s*[—-]\s*/, '');
-        if (/^(?:[-*+]\s|```|~~~|\||>\s|#{1,6}\s)/.test(desc)) {
-          return '摘要必须以文字开头（不能是列表项/代码围栏/表格/引用/标题）';
+        if (/^(?:-\s|```|~~~|\|)/.test(desc) || /^#{1,6}\s/.test(desc)) {
+          return '摘要必须以文字开头（不能是列表项/代码围栏/表格/标题）';
         }
         if (desc.includes('```')) return '摘要不能含代码围栏 ```（会吞掉后续所有条目）';
         return null;