@fanchao8609/agent_brain_sync 1.5.7 → 1.6.0

package/README.md

@@ -120,7 +120,7 @@ npm uninstall -g @fanchao8609/agent_brain_sync
 ## 开发
 
 ```bash
-npm test           # 110+ 单测（node:test，零外部测试依赖）
+npm test           # 全部单测（node:test，零外部测试依赖）
 npm run pack:check # 预览 npm 发布产物
 ```
 
@@ -130,9 +130,8 @@ npm run pack:check # 预览 npm 发布产物
 agent_brain_sync/
 ├── bin/abs.js      CLI 入口
 ├── bin/mcp.js      MCP server (stdio)
-├── src/index.js    图谱定位（只认当前目录的 .brain/）
+├── src/index.js    图谱定位（只认当前目录的 .brain/）+ 全局技术日志目录
 ├── src/lock.js     并发写保护（原子锁 + 排队 + SKIP）
-├── src/brainio.js  统一读写收口
 ├── src/todo.js     todo.md 分区读写
 ├── src/store.js    CLI 命令实现
 ├── src/hosts.js    四宿主接入定义

package/bin/abs.js

@@ -2,12 +2,14 @@
 // bin/abs.js — abs CLI 入口。
 // abs <cmd> [args]
 // 命令: init / board / status / load / task / install / uninstall / help
-import { cmdInit, cmdBoard, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdShow, cmdRepair, cmdWrapup, cmdTeardownCheck, cmdTodoArchive } from '../src/store.js';
-import { runInstall, runUninstall, installSummary } from '../src/install.js';
+import { cmdInit, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdShow, cmdRepair, cmdWrapup, cmdTeardownCheck, cmdTodoArchive } from '../src/store.js';
+import { setUser, getUser, userConfigPath } from '../src/userconfig.js';
+import { runInstall, runUninstall } from '../src/install.js';
 import { readFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
 
 const ABS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -60,28 +62,76 @@ async function cmdUpdate({ yes }) {
 
 const [,, cmd, ...rest] = process.argv;
 
+// 所有 flag 集中声明。parseArgs 只负责「把 argv 切成键值」，形状转换（keep-days → keepDays，
+// no-mcp → mcp:false）在下面一处收口。曾手写了 117 行 if-else 逐 flag 分支。
+const FLAG_SPEC = {
+  'dir': { type: 'string' },
+  'agent': { type: 'string' },
+  'id': { type: 'string' },
+  'section': { type: 'string' },
+  'note': { type: 'string' },
+  'as': { type: 'string' },
+  'payload': { type: 'string' },
+  'tags': { type: 'string' },
+  'keep-days': { type: 'string' },
+  'help': { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  'yes': { type: 'boolean' },
+  'repair': { type: 'boolean' },
+  'no-mcp': { type: 'boolean' },
+  'no-skill': { type: 'boolean' },
+};
+
 function parseArgv(args) {
-  const o = { _: [] };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === '--dir') { o.dir = args[++i]; }
-    else if (a === '--agent') { o.agent = args[++i]; }
-    else if (a === '--id') { o.id = args[++i]; }
-    else if (a === '--section') { o.section = args[++i]; }
-    else if (a === '--note') { o.note = args[++i]; }
-    else if (a === '--as') { o.as = args[++i]; }
-    else if (a === '--payload') { o.payload = args[++i]; }
-    else if (a === '--keep-days') { o.keepDays = args[++i]; }
-    else if (a === '--tags') { o.tags = args[++i]; }
-    else if (a === '--help') { o.help = true; }
-    else if (a === '--dry-run') { o.dryRun = true; }
-    else if (a === '--yes') { o.yes = true; }
-    else if (a === '--repair') { o.repair = true; }
-    else if (a === '--no-mcp') { o.mcp = false; }
-    else if (a === '--no-skill') { o.skill = false; }
-    else if (a.startsWith('--')) { o[a.slice(2)] = true; }
-    else o._.push(a);
+  // 坑: parseArgs 会把**任何** `-` 开头的 token 当选项，连正文一起吃：
+  // `abs note "-X 是个坑"` → values={X:true,' ':true,是:true,…}，正文全丢（旧手写版只认 `--` 长选项）。
+  // 也不能简单地把所有非 `--` token 剔走 —— 那样 `--dir /x` 的值 `/x` 会被误剔。
+  // 解法: 先用 tokens 看清每个 token 的 kind，只把「`--` 开头且 name 在 FLAG_SPEC 里」当真选项，
+  // 其余（包括 `-x` 与 `--unknown`）一律按原序交回位置参数，复刻旧手写逻辑。
+  const { values: rawValues, tokens } = parseArgs({
+    args,
+    options: FLAG_SPEC,
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const values = {};
+  const positionals = [];
+  const seenIdx = new Set(); // 同一个 argv 下标可能因 `-X 是个坑` 被拆出多个 token，只收一次
+  // tokens 会把 `-X 是个坑` 拆成 5 个短选项（一个字符一个），但原始 argv 里它只是一个 token。
+  // 而 token.index 就是原始 argv 的下标 → 直接按下标取回原串，才能拿回未拆的正文。
+  for (const t of tokens) {
+    const known = t.kind === 'option' && FLAG_SPEC[t.name] !== undefined && t.rawName.startsWith('--');
+    if (known) {
+      // 同名重复出现时后者胜（旧手写版行为）
+      values[t.name] = t.value === undefined ? true : t.value;
+    } else if (t.kind === 'positional') {
+      positionals.push(t.value);
+    } else {
+      // `-x` / `--unknown` / 未知长选项: 都不是我们声明的 flag。
+      // 旧手写版里 `-x` 落位置参数（→ 被 rejectExtra 拦），`--unknown` 静默收下。
+      // 区分: `--` 开头的按旧的「静默收下」当布尔（不进位置参数），其余按 argv 原值整体回位置参数
+      // （**不拆**，否则 note 正文会被切成碎片；同一 index 只收一次）。
+      if (t.rawName && t.rawName.startsWith('--')) values[t.name] = true;
+      else if (!seenIdx.has(t.index)) { seenIdx.add(t.index); positionals.push(args[t.index]); }
+    }
+  }
+  // 坑: parseArgs 对「声明的 string 选项缺值」不报错（值会变 true），
+  // 于是 `abs init --dir` 一路传到 resolve(true) 才抛裸栈。在此拦下并给清晰用法。
+  const missing = Object.entries(values)
+    .filter(([k, v]) => FLAG_SPEC[k]?.type === 'string' && typeof v !== 'string')
+    .map(([k]) => `--${k}`);
+  if (missing.length) {
+    throw new Error(`✗ ${missing.join('、')} 缺少值\n  用法: --<flag> <值>（如 --dir /path/to/project）`);
   }
+  const o = {
+    ...values,
+    _: positionals,
+    keepDays: values['keep-days'],
+    dryRun: values['dry-run'],
+  };
+  if (values['no-mcp']) o.mcp = false;
+  if (values['no-skill']) o.skill = false;
   return o;
 }
 
@@ -110,6 +160,10 @@ const usage = `abs — agent-brain-sync 记忆工具
                             归档 Done 区旧日期组 → sessions/<日期>-todo归档.md
                             (默认保留近 3 天; 任一天有未完成则整天不归档)
   abs lint                   图谱体检 (死链/孤岛/超尺寸/堆积)
+  abs config [show]          查看使用者姓名 (标记作者用)
+  abs config set user <名字> 设置使用者姓名 → ~/.abs/config.json
+                             未设置时写操作(todo/log/note)会报错要求先设置
+                             临时覆盖: ABS_USER=<名字> abs ...
   abs init [--repair]        建 .brain/ 图谱; 结构不完整时报明细, --repair 只补缺不覆盖
   abs install [--agent <宿主>]   安装 MCP+hook+skill (宿主: claude-code/codex/opencode/pi)
   abs uninstall [--agent <...>]  卸载
@@ -189,9 +243,31 @@ const TODO_ACTIONS = {
   done: 'done',
 };
 
+/** abs config —— 读/写用户设置（目前只有 user）。 */
+async function cmdConfig({ sub, value }) {
+  const p = userConfigPath();
+  if (!sub || sub === 'show' || sub === 'get') {
+    const u = await getUser();
+    return u
+      ? `user = ${u}\n  (来源: ${process.env.ABS_USER ? 'ABS_USER 环境变量' : p})`
+      : `user 未设置\n  设置: abs config set user <你的名字>\n  (或临时: ABS_USER=<名字> abs ...)`;
+  }
+  if (sub === 'set') {
+    const [key, ...rest] = String(value || '').split(/\s+/).filter(Boolean);
+    if (key !== 'user') throw new Error(`✗ abs config set 目前只支持 user\n  用法: abs config set user <你的名字>`);
+    // 名字含空格时不该静默只取第一个词（会被 setUser 的字符校验拒）。
+    // 拼接后交给 setUser 统一判定，报错文案里能看到完整输入。
+    const name = rest.join(' ');
+    if (rest.length > 1) throw new Error(`✗ 姓名不能含空格（收到 "${name}"）\n  @标记无法解析带空格的姓名`);
+    const u = await setUser(name);
+    return `✓ user = ${u}\n  → ${p}`;
+  }
+  throw new Error(`✗ 未知子命令 "${sub}"\n  用法: abs config [show] / abs config set user <名字>`);
+}
+
 async function main() {
-  const opts = parseArgv(rest);
   try {
+    const opts = parseArgv(rest);
     if (RENAMED[cmd]) throw new Error(RENAMED[cmd]());
     switch (cmd) {
       case 'init': {
@@ -270,7 +346,10 @@ async function main() {
         }
         break;
       }
-      case 'agents':   console.log(installSummary()); break;
+      case 'config': {
+        console.log(await cmdConfig({ sub: opts._[0], value: opts._.slice(1).join(' ') }));
+        break;
+      }
       case 'query': {
         console.log(await cmdQuery({ dir: opts.dir, terms: opts._ }));
         break;

package/bin/mcp.js

@@ -9,17 +9,16 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { appendFile, mkdir } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { findBrainRoot } from '../src/index.js';
+import { findBrainRoot, absLogDir } from '../src/index.js';
 import { cmdBoard, cmdLoad, cmdStatus, cmdTask, cmdQuery, cmdLint, cmdNote, cmdWrapup } from '../src/store.js';
 
 // ---------- 技术日志: MCP 请求跟踪（调试用, 与图谱 log.md 完全分开） ----------
 // 落 ~/.abs/log/mcp.log: 每次工具调用一行 [时间] tool cwd 参数摘要 → 耗时/结果摘要。
 // 关闭: ABS_LOG=0。stderr 不用（stdio transport 会污染协议）。
 const MCP_LOG = process.env.ABS_LOG !== '0';
-const LOG_DIR = process.env.ABS_LOG_DIR || join(homedir(), '.abs', 'log');
+const LOG_DIR = absLogDir();
 async function tlog(line) {
   if (!MCP_LOG) return;
   try {

package/package.json

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

package/skill/SKILL.md

@@ -58,6 +58,29 @@ Obsidian 可直接打开的 Markdown 图谱（`.brain/`）做统一落点。
 > 为什么：方案先过目能省掉整轮返工；登记让跨会话可续；"问开工"把决定权留在用户手里。
 > **这不是拖延** —— 总结方案本身就是工作，做完再问。
 
+## 使用者姓名（作者标记）
+
+图谱需要知道「谁登记的」。写操作（`todo add/note/blocked/done`、`log`、`note`）会检查：
+**未设置姓名则报错并给设置命令**，不默默落盘无名条目。
+
+```bash
+abs config set user <你的名字>     # 写入 ~/.abs/config.json，一次即可
+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）
+- `sources/`：frontmatter `author: fanchao`
+
+**只读命令不检查**（`load`/`todo`/`status`/`lint`/`query`/`index`/`log` 无参）——
+hook 在会话结束时非交互调 `abs wrapup`/`abs teardown-check`，那儿拦人会卡断收尾。
+
+> `index.md` **不加**作者：index 行是覆盖式更新的，作者会从"创建者"漂成"最后改的人"，
+> 语义不固定。要查谁写的，看该页自己的 `author`。
+> 历史条目**不回填**（原文/现场已不在，回填等于编造）。
+
 ## 图谱定位（一个项目一个 `.brain/`，abs 自动定位不用手工指定路径）
 
 `.brain/` 放项目根，一个项目只建一份。所有 `abs` 命令（`abs load/todo/note/task/query/lint...`）
@@ -204,11 +227,12 @@ monorepo 若多个子包各自独立交付，可各建一份 `.brain/`。`abs st
 
 ## 知识页格式（concepts/entities/syntheses）
 
-所有页统一 frontmatter 三项：`tags / updated / status`（无额外字段）。
+所有页统一 frontmatter：`tags / author / updated / status`。
 
 ```markdown
 ---
 tags: [concept, 领域]   # 首标签 ∈ entity|concept|source|synthesis|session-log
+author: fanchao         # 作者（abs note 自动写；手写页也须填）
 updated: YYYY-MM-DD
 status: draft           # 或 reviewed（仅指知识冲突裁决结案）
 ---

package/src/hosts.js

@@ -2,59 +2,48 @@
 // 关键事实（来自 ai-memory 学习）：
 //   - Claude Code / Codex: JSON hooks 配置，可指向 shell 脚本 → 纯 shell hook 可行
 //   - OpenCode / Pi:       只吃 TS plugin/extension，无 shell-hook 配置 → 需生成 TS
-// 本文件集中每个宿主的：home 目录、MCP 注册 schema、hook 配置方式、skill 落点。
+// 本文件集中每个宿主的：config 根、skill 落点、生命周期事件。
+// hook 形态（shell-json / codex-hooks / ts-plugin / ts-extension）不在此声明 ——
+// 装/卸分支靠 key 字符串判断（install.js 每个宿主一个 installer 函数）。
+// 曾有一份 hookKind 字段四处写死却无人读；settingsPath 同样零调用者，均已删。
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 const HOME = homedir();
 
-// MCP 注册：我们的 MCP server 由 `node <abs>/bin/mcp.js` 启动（stdio transport）。
-export function mcpServerEntry(absDir) {
-  return {
-    command: process.execPath, // node
-    args: [join(absDir, 'bin', 'mcp.js')],
-  };
-}
-
 export const HOSTS = [
   {
     key: 'claude-code',
     label: 'Claude Code',
-    // 配置文件: ~/.claude/settings.json（config 根可经 env 覆盖，用于测试/自定义）
+    // 配置文件: ~/.claude/settings.json 的 hooks 对象（config 根可经 env 覆盖，用于测试/自定义）
     configRoot: () => process.env.CLAUDE_CONFIG_DIR || join(HOME, '.claude'),
     skillSub: 'skills', // 相对 configRoot 的 skill 目录
-    settingsPath: () => join(process.env.CLAUDE_CONFIG_DIR || join(HOME, '.claude'), 'settings.json'),
     // 事件 → 我们的 shell hook 脚本（从 hooks/ 拷到 .claude 侧后执行）
     events: ['SessionStart', 'UserPromptSubmit', 'Stop', 'SessionEnd'],
-    hookKind: 'shell-json',   // settings.json 的 hooks 对象
   },
   {
     key: 'codex',
     label: 'Codex (OpenAI)',
+    // 配置: ~/.codex/hooks.json: { hooks: [...] }
     configRoot: () => process.env.CODEX_HOME || join(HOME, '.codex'),
     skillSub: 'skills', // 相对 configRoot 的 skill 目录
-    settingsPath: () => join(process.env.CODEX_HOME || join(HOME, '.codex'), 'hooks.json'),
     events: ['SessionStart', 'UserPromptSubmit', 'Stop'],
-    hookKind: 'codex-hooks',  // ~/.codex/hooks.json: { hooks: [...] }
   },
   {
     key: 'opencode',
     label: 'OpenCode',
-    // 只吃 TS plugin：~/.config/opencode/plugins/abs.ts（config 根可经 env 覆盖，用于测试）
+    // 只吃 TS plugin：<configRoot>/plugins/abs.ts（config 根可经 env 覆盖，用于测试）
     configRoot: () => process.env.ABS_OPENCODE_HOME || join(HOME, '.config', 'opencode'),
     skillSub: 'skills', // 相对 configRoot 的 skill 目录
-    settingsPath: () => join(process.env.ABS_OPENCODE_HOME || join(HOME, '.config', 'opencode')),
     events: ['SessionStart', 'UserPromptSubmit', 'Stop'],
-    hookKind: 'ts-plugin',
   },
   {
     key: 'pi',
     label: 'Pi',
+    // 落盘: <configRoot>/agent/extensions/abs.ts
     configRoot: () => process.env.ABS_PI_HOME || join(HOME, '.pi'),
     skillSub: join('agent', 'skills'), // pi 用户级 skill 在 ~/.pi/agent/skills (非 ~/.pi/skills)
-    settingsPath: () => join(process.env.ABS_PI_HOME || join(HOME, '.pi'), 'agent', 'extensions'),
     events: ['SessionStart', 'UserPromptSubmit', 'Stop'],
-    hookKind: 'ts-extension',
   },
 ];
 

package/src/index.js

@@ -2,7 +2,8 @@
 // 只看给定目录本身有没有 `.brain/`，不向上搜索。
 // 这是唯一"项目定位"逻辑，被 CLI / MCP / hook 共用，代码确定、不靠猜。
 import { promises as fs } from 'node:fs';
-import { join, resolve, basename } from 'node:path';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
 
 export const BRAIN_DIR = '.brain';
 
@@ -37,4 +38,9 @@ export async function requireBrain(startDir) {
   return root;
 }
 
-export { basename };
+/** 全局技术日志目录 (~/.abs/log)。ABS_LOG_DIR 可覆盖（测试/自定义隔离）。
+ * JS 侧的单一收口：mcp.log / wrapup.log / teardown mark 共用同一语义。
+ * 注: hooks/*.sh、*.ts 是单独安装的产物，无法 import 本函数，各自读 ABS_LOG_DIR —— 改此处不影响它们。 */
+export function absLogDir() {
+  return process.env.ABS_LOG_DIR || join(homedir(), '.abs', 'log');
+}

package/src/store.js

@@ -2,11 +2,11 @@
 // 命令: init / board / status / load / task / query / lint
 import { promises as fs } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
-import { homedir } from 'node:os';
-import { requireBrain, findBrainRoot, brainPath, BRAIN_DIR } from './index.js';
+import { requireBrain, brainPath, absLogDir, BRAIN_DIR } from './index.js';
+import { requireUser, atTag } 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, wrapupLogPath } from './wrapup.js';
+import { appendWrapup, strandedFor } from './wrapup.js';
 
 // ---------- init: 建 .brain/ 骨架 ----------
 const BRAIN_DIRS = ['entities', 'concepts', 'sources', 'syntheses', 'sessions'];
@@ -97,8 +97,10 @@ export async function cmdRepair({ dir }) {
 }
 
 function resolveProjectDir(dir) {
-  if (!dir) return process.cwd();
-  return resolve(dir);
+  // 必须显式回退 cwd: resolve(undefined) 会抛 ERR_INVALID_ARG_TYPE，
+  // 并不像看上去那样「自动回退」。曾误删此分支为 resolve(dir)，把 abs init/load/board
+  // 不带 --dir 全部变成裸栈崩溃。
+  return resolve(dir || process.cwd());
 }
 
 export function indexTemplate() {
@@ -308,7 +310,7 @@ export async function cmdTeardownCheck({ dir, payload }) {
     //    绝不"无节流"——否则一旦宿主张不到 id, decision:block 就会无限自激。
     const sid = String(ev.session_id || ev.sessionId || '').replace(/[^\w-]/g, '');
     const key = sid || 'nosession-' + day + '-' + root.replace(/[^\w]/g, '_');
-    const mark = join(homedir(), '.abs', 'log', `teardown-${key}.mark`);
+    const mark = join(absLogDir(), `teardown-${key}.mark`);
     try {
       await fs.access(mark);
       return '{}'; // 本会话(或本项目今日)已推过
@@ -382,12 +384,15 @@ function slugOf(text, n = 24) {
 // ---------- log: 追加工作成果沉淀摘要（用户/AI 主动 abs log "..." 记, 不收工具动作流水） ----------
 export async function cmdLog({ dir, title, kind = 'dev' }) {
   const root = await requireBrain(dir || process.cwd());
+  const who = await requireUser(); // 写操作守卫
   const p = brainPath(root, 'log.md');
   const stamp = localStamp();
   // 不硬切: log.md 是人类读的成果摘要, 也是 abs load 的开机入口。600 码点够一条完整小结,
   // 超出才在语义边界收口（曾 slice(0,100) → 34/85 条断在词中间）
   const clean = clip(String(title || '').replace(/\n/g, ' '), 600);
-  const line = `## [${stamp}] ${kind} | ${clean}`;
+  // 作者前置于 kind：`## [时间] @name dev | 内容`。
+  // 一眼先看到谁做的（与 todo 行 `ID @name — 说明` 排版对齐）。
+  const line = `## [${stamp}] ${atTag(who)} ${kind} | ${clean}`;
   await editFile(p, (cur) => {
     const text = cur ?? '# 🗒 操作日志\n';
     // 倒序：新行插在标题后（若已是模板占位行则替换它）
@@ -404,13 +409,14 @@ export async function cmdLog({ dir, title, kind = 'dev' }) {
 // log.md 是「工作成果沉淀摘要」(用户/AI 主动 abs log "..." 记), 不收工具动作流水。
 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();
   if (action === 'start') {
-    const text = `${id}${note ? ' — ' + note : ''}`;
     const r = await upsertTask(root, {
       section: section || 'Today / In Progress',
-      text: `${text} (认领 ${today()})`,
+      text: `${id} ${atTag(who)}${note ? ' — ' + note : ''} (认领 ${today()})`,
     });
-    return `✓ 任务${r.updated ? '更新(幂等)' : '登记'} → ${brainPath(root, 'todo.md')}\n  ${id}${note ? ' — ' + note : ''}`;
+    return `✓ 任务${r.updated ? '更新(幂等)' : '登记'} → ${brainPath(root, 'todo.md')}\n  ${id} ${atTag(who)}${note ? ' — ' + note : ''}`;
   }
   if (action === 'blocked') {
     const r = await moveBlocked(root, { id, reason: note });
@@ -546,6 +552,7 @@ export async function cmdNote({ dir, text, tags }) {
   } catch {
     return `未找到 .brain/ 图谱。先在项目根运行: abs init`;
   }
+  const who = await requireUser(); // 写操作守卫
   const srcDir = brainPath(root, 'sources');
   await fs.mkdir(srcDir, { recursive: true });
   // 幂等: 同文本 60s 内只落一份
@@ -564,6 +571,7 @@ export async function cmdNote({ dir, text, tags }) {
   const body = [
     '---',
     `tags: [${fmTags}]`,
+    `author: ${who}`,
     `updated: ${today()}`,
     'status: draft',
     '---',
@@ -599,7 +607,7 @@ export async function cmdNote({ dir, text, tags }) {
     return { text: next };
   });
   await cmdLog({ dir: root, title: clean, kind: 'note' });
-  return `✓ 经验暂存 → sources/${file}\n  ${clean}`;
+  return `✓ 经验暂存 → sources/${file}\n  ${clean} ${atTag(who)}`;
 }
 // ---------- lint: 体检（与 scripts/lint.sh 同规则的 Node 版，供 CLI/MCP 直调） ----------
 export async function cmdLint({ dir }) {

package/src/todo.js

@@ -390,10 +390,12 @@ export async function upsertTask(brainRoot, { section, text }) {
     // 在所有分区中找该 id 对应的未完成任务行（Done 的已完成行不重复动）；全等比对
     const idx = findTaskLine(lines, id);
     if (idx !== -1) {
-      // 原位更新：保留断点附属行，只换任务行本体
+      // 原位更新：保留断点附属行 + 原@作者，只换任务行本体
+      const author = extractAuthor(lines[idx].replace(/^- \[ \] /, ''));
       const oldNote = extractNote(lines[idx].replace(/^- \[ \] /, ''));
       const merged = note && oldNote && oldNote.startsWith(note) ? `${note}${oldNote.slice(note.length)}` : note || oldNote;
-      const newLine = `- [ ] ${id}${merged ? ' — ' + merged : ''} (认领 ${today()})`;
+      const at = author ? ` @${author}` : '';
+      const newLine = `- [ ] ${id}${at}${merged ? ' — ' + merged : ''} (认领 ${today()})`;
       lines[idx] = newLine;
       return { text: lines.join('\n'), updated: true };
     }
@@ -410,10 +412,18 @@ export function extractId(text) {
   return m ? m[1] : null;
 }
 
-/** 提取 " — " 后的 note 部分。 */
+/** 提取 " — " 后的 note 部分（剥掉紧跟在 id 后的 `@author` 标记及尾部 `(认领 ...)`）。
+ * 格式: `<id> @author — <note> (认领 date)`。@author 可选（旧行/未设置姓名时无）。 */
 export function extractNote(text) {
   const i = String(text).indexOf(' — ');
-  return i === -1 ? '' : String(text).slice(i + 3).replace(/\s*\(认领[^)]*\)\s*$/, '');
+  if (i === -1) return '';
+  return String(text).slice(i + 3).replace(/\s*\(认领[^)]*\)\s*$/, '').trim();
+}
+
+/** 提取 id 后的 `@author` 标记（无则空）。供 upsertTask 原位重建行时保留作者。 */
+export function extractAuthor(text) {
+  const m = String(text).match(/^\S+\s+@([\w\u4e00-\u9fff.-]+)/);
+  return m ? m[1] : '';
 }
 
 /**

package/src/userconfig.js

@@ -0,0 +1,68 @@
+// src/userconfig.js — 用户身份（作者名）配置。
+// 用途：todo/log/生成的文档标 @name，让跨会话图谱能看出"谁登记的"。
+//
+// 配置源（后者优先）：
+//   1. ~/.abs/config.json 的 { "user": "fanchao" }  —— abs config set user <name> 写入
+//   2. 环境变量 ABS_USER                          —— 临时/CI 覆盖，不改落盘配置
+//
+// 纪律：**只在写操作检查**。hook 会在会话结束时非交互调 abs wrapup / abs teardown-check，
+// 只读命令若也拦人，hook 路径会卡住或报错。故 requireUser 只被写命令调用。
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** 配置文件路径（ABS_CONFIG_DIR 可覆盖，测试隔离用）。 */
+export function userConfigPath() {
+  const dir = process.env.ABS_CONFIG_DIR || join(homedir(), '.abs');
+  return join(dir, 'config.json');
+}
+
+/** 读配置的 user 字段（不存在/坏 JSON 一律返回 null，不抛）。 */
+export async function getUser() {
+  const env = String(process.env.ABS_USER || '').trim();
+  if (env) return env; // 环境变量优先：临时覆盖不必改落盘配置
+  try {
+    const raw = await fs.readFile(userConfigPath(), 'utf8');
+    const u = JSON.parse(raw).user;
+    return typeof u === 'string' && u.trim() ? u.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 写配置的 user 字段（保留其它键）。 */
+export async function setUser(name) {
+  const clean = String(name || '').trim();
+  if (!clean) throw new Error('✗ 姓名不能为空');
+  // 合法性：允许字母数字中文下划线连字符点，禁空白（空白会破坏 @name 标记的解析）
+  if (!/^[\w\u4e00-\u9fff.-]+$/.test(clean)) {
+    throw new Error(`✗ 姓名 "${clean}" 含不支持的字符（只允许字母/数字/中文/._-，且不含空格）`);
+  }
+  const p = userConfigPath();
+  await fs.mkdir(join(p, '..'), { recursive: true });
+  let cfg = {};
+  try { cfg = JSON.parse(await fs.readFile(p, 'utf8')); } catch { /* 首次或坏 JSON → 重建 */ }
+  cfg.user = clean;
+  await fs.writeFile(p, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  return clean;
+}
+
+/**
+ * 写操作入口守卫：拿到作者名，拿不到就抛带指引的错误。
+ * 错误文案给出两条路（持久设置 / 临时覆盖），别让用户猜。
+ */
+export async function requireUser() {
+  const u = await getUser();
+  if (u) return u;
+  throw new Error(
+    '✗ 尚未设置使用者姓名 —— 图谱需要标记每条记录的作者。\n' +
+    '  请任选其一设置后重试:\n' +
+    '    abs config set user <你的名字>     (写入 ~/.abs/config.json, 一次即可)\n' +
+    '    ABS_USER=<你的名字> abs ...        (仅本次生效)'
+  );
+}
+
+/** 标记串：`@name`。用于 todo 行 / log 行 / 页面 frontmatter。 */
+export function atTag(name) {
+  return `@${name}`;
+}

package/src/wrapup.js

@@ -7,12 +7,11 @@
 // wrapup.log 是全局技术日志(~/.abs/log/), 跨项目共用, 故每块带 proj=<root> 归属。
 import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { brainPath } from './index.js';
+import { brainPath, absLogDir } from './index.js';
 import { readTodo, localStamp } from './todo.js';
 
 export function wrapupLogPath() {
-  return join(process.env.ABS_LOG_DIR || join(homedir(), '.abs', 'log'), 'wrapup.log');
+  return join(absLogDir(), 'wrapup.log');
 }
 
 // 同项目两次快照的最小间隔(秒)。agent_end 会逐 turn 触发, 无变化时不刷屏。

package/src/brainio.js

@@ -1,66 +0,0 @@
-// src/brainio.js — .brain 文档统一读写收口。
-// 目的：所有需读写 .brain 文档的地方(todo/log/index/source/…)都走这一个方法，
-//       调用方不必各自拼 brainPath + lock.editFile/裸 readFile，也天然带上防重复/防并发锁。
-//   - readBrain(brainRoot, rel)     读 .brain/<rel> 文本（文件不存在返回 null）
-//   - writeBrain(brainRoot, rel, transform) 锁内读改写（自动 lock.editFile 防并发）；transform 返回新文本或 null=不改
-//   - appendBrain(brainRoot, rel, lines)    锁内追加多行到文末
-// 纯 IO 封装：路径由 brainPath 统一算，写由 lock.editFile 统一带锁。无业务逻辑。
-import { promises as fs } from 'node:fs';
-import { brainPath } from './index.js';
-import { editFile, SKIP } from './lock.js';
-
-/** 读 .brain/<rel> 全文。不存在返回 null。读不经锁（读旧内容无害）。 */
-export async function readBrain(brainRoot, rel) {
-  const p = brainPath(brainRoot, rel);
-  try {
-    return await fs.readFile(p, 'utf8');
-  } catch {
-    return null; // 尚未建该页
-  }
-}
-
-/** 锁内读-改-写 .brain/<rel>。transform(currentText) 返回新文本；返回 null/undefined 表示不改(不落盘)。
- * 返回：落盘后的新文本(transform 不改时返回原文本)。自动防并发(同文件多进程同时写不覆盖)。
- * 注：本方法写的是「整体新文本」；若文件不存在 currentText 传 null。 */
-export async function writeBrain(brainRoot, rel, transform) {
-  const p = brainPath(brainRoot, rel);
-  const out = await editFile(p, (current) => {
-    const next = transform(current);
-    if (next === null || next === undefined) return SKIP; // 不改 → 不落盘
-    const text = typeof next === 'string' ? next : next.text;
-    return text === current ? SKIP : text; // 与当前相同也不落盘(editFile 幂等)
-  });
-  // out 是 editFile 返回的字符串(新文本)或 SKIP(未改)。未改时返回读到的当前文本。
-  if (out === SKIP) return currentTextOf(brainPath(brainRoot, rel));
-  return out;
-}
-
-/** 读文件文本(不经锁); 供 writeBrain 未改时回读当前值。 */
-async function currentTextOf(p) {
-  try {
-    return await fs.readFile(p, 'utf8');
-  } catch {
-    return null;
-  }
-}
-
-/** 锁内往 .brain/<rel> 文末追加若干行(自动补换行)。若文件不存在则创建。 */
-export async function appendBrain(brainRoot, rel, lines) {
-  const arr = Array.isArray(lines) ? lines : [lines];
-  return writeBrain(brainRoot, rel, (cur) => {
-    const base = cur == null ? '' : cur.replace(/\s*$/, '');
-    const body = arr.join('\n');
-    return base ? `${base}\n${body}\n` : `${body}\n`;
-  });
-}
-
-/** 原子建新 .brain/<rel>(tmp+rename, 不经锁——新文件写唯一内容无并发读者竞争)。 */
-export async function createBrainFile(brainRoot, rel, content) {
-  const p = brainPath(brainRoot, rel);
-  const { dirname } = await import('node:path');
-  await fs.mkdir(dirname(p), { recursive: true });
-  const tmp = `${p}.abs-tmp-${process.pid}-${Date.now()}`;
-  await fs.writeFile(tmp, content, 'utf8');
-  await fs.rename(tmp, p);
-  return p;
-}