@fanchao8609/agent_brain_sync 1.5.7 → 1.5.8

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,13 @@
 // 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 { 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 +61,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;
 }
 
@@ -190,8 +239,8 @@ const TODO_ACTIONS = {
 };
 
 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 +319,6 @@ async function main() {
         }
         break;
       }
-      case 'agents':   console.log(installSummary()); 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.5.8",
   "description": "agent-brain-sync: 跨会话 AI 编码记忆 — hook 纯触发 + CLI/MCP 读写 .brain markdown 图谱, 防并发写保护。",
   "type": "module",
   "license": "MIT",

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,10 @@
 // 命令: 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 { 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 +96,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 +309,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 '{}'; // 本会话(或本项目今日)已推过

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;
-}