@fanchao8609/agent_brain_sync 1.6.0 → 1.7.0

package/bin/abs.js

@@ -260,7 +260,17 @@ async function cmdConfig({ sub, value }) {
     const name = rest.join(' ');
     if (rest.length > 1) throw new Error(`✗ 姓名不能含空格（收到 "${name}"）\n  @标记无法解析带空格的姓名`);
     const u = await setUser(name);
-    return `✓ user = ${u}\n  → ${p}`;
+    // 立即建人页（用户说"两者都行"：配置时建一份，首次写操作也会兜底建）。
+    // 没 .brain/ 就跳过 —— 全局配置不该强绑某个项目。
+    let extra = '';
+    try {
+      const { requireBrain } = await import('../src/index.js');
+      const { ensurePersonPage } = await import('../src/store.js');
+      const root = await requireBrain(process.cwd());
+      const r = await ensurePersonPage(root, u);
+      if (r === 'created') extra = `\n  人页: .brain/entities/${u}.md (已登记 index)`;
+    } catch { /* 无图谱 / 建页失败都不影响配置生效 */ }
+    return `✓ user = ${u}\n  → ${p}${extra}`;
   }
   throw new Error(`✗ 未知子命令 "${sub}"\n  用法: abs config [show] / abs config set user <名字>`);
 }

package/package.json

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

package/skill/SKILL.md

@@ -69,17 +69,24 @@ abs config                        # 查看当前姓名
 ABS_USER=<名字> abs todo add ...   # 临时覆盖（CI/多身份），不改落盘配置
 ```
 
-设置后自动标记：
-- `todo.md`：`- [ ] TASK-ID @fanchao — 说明 (认领 2026-09-12)`（作者紧跟 id，扫板先看到人）
-- `log.md`：`## [2026-09-12 13:17] @fanchao dev | 完成 X`（作者前置于 kind）
+设置后自动标记（**作者是人页的 wikilink，点得进去看技术栈/特点**）：
+- `todo.md`：`- [ ] TASK-ID [[fanchao]] — 说明 (认领 2026-09-12)`（作者紧跟 id，扫板先看到人）
+- `log.md`：`## [2026-09-12 13:17] [[fanchao]] dev | 完成 X`（作者前置于 kind）
 - `sources/`：frontmatter `author: fanchao`
 
+同时自动建人页 `.brain/entities/<name>.md`（含「技术栈 / 特点·工作习惯 / 名下踩过的坑」三个空槽），
+并登记进 `index.md` 的 Entities 区。**已存在则一律不动** —— 里面的内容是人工沉淀的，机器不许覆盖。
+
+> **沉淀时顺手填人页**：经验提炼进 concepts/ 时，若观察到工程师的技术栈或判断倾向，
+> 写进 `entities/<name>.md`。这页是可积累的画像，不是一次性标签。
+
 **只读命令不检查**（`load`/`todo`/`status`/`lint`/`query`/`index`/`log` 无参）——
 hook 在会话结束时非交互调 `abs wrapup`/`abs teardown-check`，那儿拦人会卡断收尾。
 
-> `index.md` **不加**作者：index 行是覆盖式更新的，作者会从"创建者"漂成"最后改的人"，
-> 语义不固定。要查谁写的，看该页自己的 `author`。
-> 历史条目**不回填**（原文/现场已不在，回填等于编造）。
+> `index.md` 的**经验行不加作者**：index 行是覆盖式更新的，作者会从"创建者"漂成"最后改的人"，
+> 语义不固定。要查谁写的，看该页自己的 `author`，或 `abs query` 输出（带每页 author）。
+> 历史条目**不回填**：旧行的裸 `@name` 只在原位更新时按原形态保留，不批量改写（原文/现场已不在，
+> 回填等于编造）。
 
 ## 图谱定位（一个项目一个 `.brain/`，abs 自动定位不用手工指定路径）
 
@@ -232,12 +239,14 @@ monorepo 若多个子包各自独立交付，可各建一份 `.brain/`。`abs st
 ```markdown
 ---
 tags: [concept, 领域]   # 首标签 ∈ entity|concept|source|synthesis|session-log
-author: fanchao         # 作者（abs note 自动写；手写页也须填）
+author: fanchao         # 作者（abs note 自动写；手写页也须填，且与 entities/<name>.md 同名）
 updated: YYYY-MM-DD
 status: draft           # 或 reviewed（仅指知识冲突裁决结案）
 ---
 ```
 
+作者名同时是**人页 slug**：`[[fanchao]]` → `entities/fanchao.md`（技术栈 / 特点 / 名下踩过的坑）。
+
 - **关联连接区**：每页必须有 `## 关联连接`，用 `[[页面名]]` 链相关页。严禁孤岛页。
 - **知识冲突**：与旧页矛盾不静默覆盖。加 `## 知识冲突` 两版都留、标来源时间，交人工裁决。
 - **命名即链接**：`[[Docker]]` 落 entities/Docker.md；`[[docker-prisma-429]]` 落 concepts/。别建别名层。

package/src/store.js

@@ -3,7 +3,7 @@
 import { promises as fs } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { requireBrain, brainPath, absLogDir, BRAIN_DIR } from './index.js';
-import { requireUser, atTag } from './userconfig.js';
+import { requireUser, atTag, getUser } from './userconfig.js';
 import { addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, moveBlocked, insertDoneGrouped, idOfTaskLine, archiveDoneInText, renderArchivePage, renderArchiveBody, DONE_KINDS, withDoneKind, doneKindOf } from './todo.js';
 import { editFile, SKIP } from './lock.js';
 import { appendWrapup, strandedFor } from './wrapup.js';
@@ -35,7 +35,11 @@ async function createSkeleton(root, brain) {
   await fs.writeFile(join(brain, 'index.md'), indexTemplate(), 'utf8');
   await fs.writeFile(join(brain, 'log.md'), logTemplate(), 'utf8');
   await fs.writeFile(join(brain, 'todo.md'), todoTemplate(), 'utf8');
-  return `✓ 已建图谱 ${brain}\n  (模板见 SKILL.md「文件标准」)`;
+  // 建完就提示设姓名 —— 否则用户一路到第一次 todo add 才撞墙，
+  // 中间 init/load 都不提，根本不知道该设。
+  const who = await getUser();
+  const hint = who ? '' : `\n  ⚠ 尚未设置使用者姓名，写操作(todo add/log/note)会先报错。\n    请先设置: abs config set user <你的名字>`;
+  return `✓ 已建图谱 ${brain}\n  (模板见 SKILL.md「文件标准」)${hint}`;
 }
 
 /** 结构体检：6 目录 + 3 文件逐一核对。ok=false 时 problems 列出缺失项。 */
@@ -163,6 +167,17 @@ export async function cmdLoad({ dir }) {
   const stranded = await strandedFor(root);
   const sections = [
     `📂 abs → 项目: ${root}`,
+  ];
+  // 未设姓名时开场就提醒 —— load 是开机第一屏，不在这里提，
+  // 用户要撞到第一次写操作才知道（init/load 一路沉默）。
+  if (!(await getUser())) {
+    sections.push(
+      '⚠ 尚未设置使用者姓名（写操作会先报错）',
+      '→ abs config set user <你的名字>    (或临时: ABS_USER=<名字> abs ...)',
+      ''
+    );
+  }
+  sections.push(
     '--- 当前路线 (index.md) ---',
     index || '(index.md 为空)',
     '',
@@ -171,15 +186,15 @@ export async function cmdLoad({ dir }) {
     '',
     '--- 最近动作 (log.md, 最新 5 条) ---',
     recentLogLines(log, 5) || '(log.md 为空)',
-  ];
+  );
   if (stranded.length) {
     const rows = stranded.map((t) => {
       const bp = t.bp.length ? `\n    ${t.bp.map((b) => `↳ 断点: ${b}`).join('\n    ')}` : '';
       return `  - ${t.body}${bp}`;
     });
+    // 插在项目行之后、其它内容之前
     sections.splice(
-      0, 1,
-      `📂 abs → 项目: ${root}`,
+      1, 0,
       '⏳ 上会话滞留（未 done，先对账）',
       rows.join('\n'),
       '→ 完成: abs todo done <id>；未完: abs todo note <id> --note 断点',
@@ -319,7 +334,12 @@ export async function cmdTeardownCheck({ dir, payload }) {
     await fs.writeFile(mark, stamp).catch(() => {});
 
     const msg = [
-      '[abs 收尾提醒] 本会话改过文件但 .brain/ 今天还没有记录。请立即走收尾循环：',
+      // 未设姓名时把设置指令插到第0条 —— 否则后续 todo add/log/note 全会被守卫拦下，
+    // 而收尾提醒本身不提这事，使用者只会看到一连串报错。
+    (await getUser() ? [] : [
+      '0) 本机尚未设置使用者姓名 —— 先跑 abs config set user <你的名字>，否则下面 2/3/4 都会被拦下；',
+    ]),
+    '[abs 收尾提醒] 本会话改过文件但 .brain/ 今天还没有记录。请立即走收尾循环：',
       '1) 跑 abs load 看 Today 还有哪些未完成；',
       '2) 实际做完漏登记的 abs todo done <id>，做到一半的 abs todo note <id> --note "断点"；',
       '3) 值得留的经验 abs note "..."（宁少勿滥，能从代码 grep 到的不记）；',
@@ -385,6 +405,7 @@ function slugOf(text, n = 24) {
 export async function cmdLog({ dir, title, kind = 'dev' }) {
   const root = await requireBrain(dir || process.cwd());
   const who = await requireUser(); // 写操作守卫
+  await ensurePersonPage(root, who); // 首次写操作即建人页（已存在不动）
   const p = brainPath(root, 'log.md');
   const stamp = localStamp();
   // 不硬切: log.md 是人类读的成果摘要, 也是 abs load 的开机入口。600 码点够一条完整小结,
@@ -411,6 +432,7 @@ export async function cmdTask({ dir, action, id, section, note, as }) {
   const root = await requireBrain(dir || process.cwd());
   // 写操作守卫：无姓名不落盘（hook 调的 wrapup/teardown-check 不经过这里，不受影响）
   const who = await requireUser();
+  await ensurePersonPage(root, who); // 首次写操作即建人页（已存在不动）
   if (action === 'start') {
     const r = await upsertTask(root, {
       section: section || 'Today / In Progress',
@@ -520,12 +542,22 @@ export async function cmdQuery({ dir, terms }) {
       const body = await fs.readFile(full, 'utf8').catch(() => '');
       const matched = words.filter((w) => body.toLowerCase().includes(w.toLowerCase()));
       if (matched.length) {
-        hits.push({ full, slug: f.replace(/\.md$/, ''), matched, snippet: firstHitLine(body, words) });
+        // 作者从本页 frontmatter 读（权威来源）。不在 index 行里重复 ——
+        // index 行是覆盖式更新的，作者会从"创建者"漂成"最后改的人"。
+        const au = body.match(/^author:\s*(.+)$/m);
+        hits.push({
+          full, slug: f.replace(/\.md$/, ''), matched,
+          author: au ? au[1].trim() : '',
+          snippet: firstHitLine(body, words),
+        });
       }
     }
   }
   if (!hits.length) return `query [${words.join(', ')}]: 无命中。用 abs lint 看图谱健康；首次使用先 abs init。`;
-  const lines = hits.map((h) => `📄 ${h.slug}  (命中: ${h.matched.join(', ')})\n    ${h.snippet}`);
+  const lines = hits.map((h) => {
+    const by = h.author ? `  @${h.author}` : '';
+    return `📄 ${h.slug}${by}  (命中: ${h.matched.join(', ')})\n    ${h.snippet}`;
+  });
   return [`query [${words.join(', ')}] → ${hits.length} 页:`, '', ...lines].join('\n');
 }
 
@@ -553,6 +585,7 @@ export async function cmdNote({ dir, text, tags }) {
     return `未找到 .brain/ 图谱。先在项目根运行: abs init`;
   }
   const who = await requireUser(); // 写操作守卫
+  await ensurePersonPage(root, who); // 首次写操作即建人页（已存在不动）
   const srcDir = brainPath(root, 'sources');
   await fs.mkdir(srcDir, { recursive: true });
   // 幂等: 同文本 60s 内只落一份
@@ -584,6 +617,7 @@ export async function cmdNote({ dir, text, tags }) {
     `- ${clean}`,
     '',
     '## 关联连接',
+    `- ${atTag(who)} — 本页沉淀者`,
     '（提炼成 concepts 规律页后，在此挂双链到该页）',
     '',
   ].join('\n');
@@ -593,22 +627,70 @@ export async function cmdNote({ dir, text, tags }) {
   await fs.writeFile(tmp, body, 'utf8');
   await fs.rename(tmp, srcFile);
   // index Sources 区登记（锁内幂等：别页已登记则跳过，防并发重复） + log 一行
-  const iP = brainPath(root, 'index.md');
   const slug = file.replace(/\.md$/, '');
-  const line = `- [[${slug}]] — ${heading}`;
+  await registerInIndex(root, 'Sources', slug, heading);
+  await cmdLog({ dir: root, title: clean, kind: 'note' });
+  return `✓ 经验暂存 → sources/${file}\n  ${clean} ${atTag(who)}`;
+}
+// ---------- person: 使用者实体页（首次需要时创建，已存在则不动） ----------
+/** 确保 entities/<name>.md 存在。已存在一律不动（里面的技术栈/特点是人工沉淀的）。
+ * 用 `wx` 独占写：并发下后到者拿到 EEXIST 就静默跳过，不覆盖。
+ * 失败不抛：建页是附带动作，不能因为它让 todo/log 写不进去。
+ * 返回 'created' | 'exists' | 'skip'。 */
+export async function ensurePersonPage(root, name) {
+  const nm = String(name || '').trim();
+  if (!nm || !/^[\w\u4e00-\u9fff.-]+$/.test(nm)) return 'skip';
+  const dir = brainPath(root, 'entities');
+  const file = join(dir, `${nm}.md`);
+  const body = [
+    '---',
+    'tags: [entity, person]',
+    `author: ${nm}`,
+    `updated: ${today()}`,
+    'status: draft',
+    '---',
+    '',
+    `# ${nm}`,
+    '',
+    '## 技术栈',
+    '<!-- 沉淀时填: 主力语言/框架/工具链。例: TypeScript + Node, 熟悉 MCP 协议与 CLI 工具链 -->',
+    '',
+    '## 特点 / 工作习惯',
+    '<!-- 沉淀时填: 决策偏好、沟通习惯、反复出现的判断倾向。例: 先要方案后动手; 质疑"这需求是否需要存在" -->',
+    '',
+    '## 名下踩过的坑',
+    '（本页被 [[todo]] / [[log]] 里的作者标记引用；沉淀经验时在此挂双链）',
+    '',
+  ].join('\n');
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(file, body, { encoding: 'utf8', flag: 'wx' });
+  } catch (e) {
+    if (e.code === 'EEXIST') return 'exists';
+    return 'skip';
+  }
+  // 只有真建成才登记 index（否则 index 指向不存在的页 → INDEX-DEAD-LINK）。
+  // 放这里而非各调用点：todo/log/note 三条写路径都要登记，抄三遍必漂。
+  await registerInIndex(root, 'Entities', nm, `${nm} — 使用者；技术栈 / 特点 / 名下踩过的坑`);
+  return 'created';
+}
+
+/** 把新页登记进 index.md 的指定分区（幂等）。供人页/其它程序建页用。 */
+export async function registerInIndex(root, section, slug, desc) {
+  const iP = brainPath(root, 'index.md');
   await editFile(iP, (index) => {
     if (!index || index.includes(`[[${slug}]]`)) return SKIP;
-    const sIdx = index.indexOf('## Sources');
+    const sIdx = index.indexOf(`## ${section}`);
     if (sIdx === -1) return SKIP;
     const after = index.indexOf('\n## ', sIdx + 1);
+    const line = `- [[${slug}]] — ${desc}`;
     const next = after === -1
       ? `${index.replace(/\s*$/, '')}\n${line}\n`
       : index.slice(0, after) + `\n${line}` + index.slice(after);
     return { text: next };
   });
-  await cmdLog({ dir: root, title: clean, kind: 'note' });
-  return `✓ 经验暂存 → sources/${file}\n  ${clean} ${atTag(who)}`;
 }
+
 // ---------- lint: 体检（与 scripts/lint.sh 同规则的 Node 版，供 CLI/MCP 直调） ----------
 export async function cmdLint({ dir }) {
   let root;

package/src/todo.js

@@ -391,10 +391,13 @@ export async function upsertTask(brainRoot, { section, text }) {
     const idx = findTaskLine(lines, id);
     if (idx !== -1) {
       // 原位更新：保留断点附属行 + 原@作者，只换任务行本体
-      const author = extractAuthor(lines[idx].replace(/^- \[ \] /, ''));
-      const oldNote = extractNote(lines[idx].replace(/^- \[ \] /, ''));
+      const raw = lines[idx].replace(/^- \[ \] /, '');
+      const author = extractAuthor(raw);
+      const legacy = isLegacyAuthorTag(raw); // 旧行保持旧形态，不静默改写
+      const oldNote = extractNote(raw);
       const merged = note && oldNote && oldNote.startsWith(note) ? `${note}${oldNote.slice(note.length)}` : note || oldNote;
-      const at = author ? ` @${author}` : '';
+      const at = author ? ` ${legacy ? '@' + author : '[['
+        + author + ']]'}` : '';
       const newLine = `- [ ] ${id}${at}${merged ? ' — ' + merged : ''} (认领 ${today()})`;
       lines[idx] = newLine;
       return { text: lines.join('\n'), updated: true };
@@ -420,10 +423,23 @@ export function extractNote(text) {
   return String(text).slice(i + 3).replace(/\s*\(认领[^)]*\)\s*$/, '').trim();
 }
 
-/** 提取 id 后的 `@author` 标记（无则空）。供 upsertTask 原位重建行时保留作者。 */
+/** 提取 id 后的作者标记（无则空）。供 upsertTask 原位重建行时保留作者。
+ * 两种形态都要认：
+ *   - 新: `- [ ] ID [[fanchao]] — note`   (wikilink 到人页)
+ *   - 旧: `- [ ] ID @fanchao — note`      (裸 at 标记, 历史行)
+ * 旧行只在原位更新时按原形态保留, 不做批量回填(原文/现场已不在, 回填等于编造)。
+ * 返回的是**纯姓名**（不含 [[ ]] 与 @），由调用方决定用什么形态重写。 */
 export function extractAuthor(text) {
-  const m = String(text).match(/^\S+\s+@([\w\u4e00-\u9fff.-]+)/);
-  return m ? m[1] : '';
+  const s = String(text);
+  const link = s.match(/^\S+\s+\[\[([^\]]+)\]\]/);
+  if (link) return link[1].trim();
+  const at = s.match(/^\S+\s+@([\w\u4e00-\u9fff.-]+)/);
+  return at ? at[1] : '';
+}
+
+/** 判断行里的作者标记是旧裸 `@name` 形态（保留旧形态，不擅自升级）。 */
+export function isLegacyAuthorTag(text) {
+  return !/^\S+\s+\[\[/.test(String(text)) && /^\S+\s+@/.test(String(text));
 }
 
 /**

package/src/userconfig.js

@@ -62,7 +62,9 @@ export async function requireUser() {
   );
 }
 
-/** 标记串：`@name`。用于 todo 行 / log 行 / 页面 frontmatter。 */
+/** 标记串：`[[name]]`（wikilink 到人页 entities/<name>.md）。
+ * 用 wiki 链接而非裸 `@name`：人是图谱实体，点得进去看技术栈/特点。
+ * 旧数据里的裸 `@name` 仍可解析（见 todo.js extractAuthor），但不回填。 */
 export function atTag(name) {
-  return `@${name}`;
+  return `[[${name}]]`;
 }