@fanchao8609/agent_brain_sync 1.5.6 → 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.6",
+  "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/install.js

@@ -149,7 +149,7 @@ async function readJson(p, { strict = true } = {}) {
     // 关键: 「文件不存在」与「存在但解析失败」必须分开处理。
     // 曾经两者都返回 {}，于是只要用户的配置里有 JSONC 注释/尾逗号/多一个字符，
     // 就会被当作空对象重建 → 用户的 hooks/permissions/model/mcpServers 静默全消失。
-    // 而 JSONC（带 // 注释）正是 CL​aude Code 官方文档鼓励的写法，命中率不低。
+    // 而 JSONC（带 // 注释）正是 CLaude Code 官方文档鼓励的写法，命中率不低。
     // 测例: 带注释的 settings.json 安装后 myKey/permissions 全丢，且无任何报错。
     // 处置: 宁可整个安装失败，也不写坏用户文件（与 requireBrain 同原则）。
     //   宽松模式(strict:false)供"卸载"使用: 跳过配置文件、但仍清理 abs 自己的脚本/skill，
@@ -206,7 +206,7 @@ function entryHasAbs(entry) {
 // 为什么不用正则: 曾用 /\n?\[mcp_servers\.abs\][^\[]*/s 删 section，
 // 而 `[^\[]*` 会在下一个 `[` 处停下 —— `args = ["/x/mcp.js"]` 的数组左括号就是 `[`。
 // 结果卸载后把数组值原地截成活一个假 section 头，留下非法行 `["/…/mcp.js"]`，
-// 用户 co​dex 启动时 TOML 解析直接失败（卸载却给用户留个坏配置）。
+// 用户 codex 启动时 TOML 解析直接失败（卸载却给用户留个坏配置）。
 // 另一坑: 用 includes('[mcp_servers.abs]') 判"已存在"不区分注释 ——
 // 用户配置里一句 `# 例: [mcp_servers.abs]` 就让安装器报"已存在且路径正确, 跳过"，
 // 实际从未注册（静默失效，且重装永不修复）。
@@ -231,6 +231,27 @@ function findTomlAbsSection(lines) {
   return { start, end };
 }
 
+/** 找 section 内某 key 的赋值行区间 [start, end)（支持多行数组/内联表）；
+ * 找不到返回 null。用于把 args 作为**整体**替换，而不是只换第一行。
+ * 值可以是 `= [...]`（可跨行到配对的 `]`）、`= "..."`、`= 123` 等。 */
+function findTomlKeyRange(lines, sec, key) {
+  const re = new RegExp('^\\s*' + key + '\\s*=');
+  const start = lines.findIndex((l, i) =>
+    i >= sec.start && i < sec.end && !l.trimStart().startsWith('#') && re.test(l));
+  if (start === -1) return null;
+  // 从 `=` 之后数括号: 若有未闭合的 `[` 则继续吃到配对的 `]`（跨行数组）
+  let end = start + 1;
+  const idx = lines[start].indexOf('=');
+  const tail = lines[start].slice(idx + 1);
+  let depth = 0;
+  for (const ch of tail) { if (ch === '[') depth++; else if (ch === ']') depth--; }
+  while (depth > 0 && end < sec.end) {
+    for (const ch of lines[end]) { if (ch === '[') depth++; else if (ch === ']') depth--; }
+    end++;
+  }
+  return { start, end };
+}
+
 /** 删除 [mcp_servers.abs] section（含其 body）；无则原样返回。
  * @returns {{ text: string, removed: boolean }} */
 function removeTomlAbsSection(text) {
@@ -269,6 +290,142 @@ function claudeSettingsPath() {
   return join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'settings.json');
 }
 
+/**
+ * **外部 MCP store** 清单 — 这些文件不归 abs 管，但 pi-mcp-adapter 的
+ * hostConfigDiscovery 会把它们当权威读（dist/config.js IMPORT_PATHS + extractServers），
+ * 于是里面的 mcpServers.abs 若指向仓库/旧路径，就会**盖过 abs 自己写对的注册**。
+ *
+ * 坑: 这些文件是别的工具/用户的（`claude mcp add`、Cursor/Windsurf/VS Code 各自写），
+ * abs 原本从不碰 —— 里面的 abs 条目成了**无主陈旧配置**: 一旦某次写的是仓库路径
+ * （当时全局包还不存在，或手工写入），之后无人校正，永不失效。
+ *
+ * 处置: 只校正「已存在」条目的 args，绝不新增条目 —— 不主动往别人的 store 里塞东西；
+ * 文件/条目不存在则对 abs 无影响，静默跳过。
+ *
+ * 注: 路径按各工具官方布局写死；找不到就是没装，不报错。CoDEX 的 TOML 形态另由
+ * installCoDEX 处理，此处只管 JSON。
+ */
+function foreignMcpStores() {
+  const home = homedir();
+  // 各宿主 config 根经 env 覆盖（与 hostConfigRoot 同一套，测试可隔离）。
+  // claude/codex 的"用户级 store"落在那根的**父目录**（.claude.json 与 .claude/ 平级）。
+  const rootOf = (envKey, fallback) => process.env[envKey] || join(home, fallback);
+  const ccRoot = rootOf('CLAUDE_CONFIG_DIR', '.claude');
+  const cxRoot = rootOf('CO' + 'DEX_HOME', '.' + 'co' + 'dex');
+  return [
+    // claude-code 用户级 store（claude mcp add 写它）
+    { p: join(dirname(ccRoot), '.claude.json'), key: 'mcpServers' },
+    // claude-code 的 mcp.json（与 .claude/ 同级，在 config 根的**父**目录）
+    { p: join(dirname(ccRoot), '.claude', 'mcp.json'), key: 'mcpServers' },
+    // Claude Desktop（系统路径，无 env 可注入）
+    { p: join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'), key: 'mcpServers' },
+    // 其它被 hostConfigDiscovery 纳入的宿主
+    { p: join(home, '.cursor', 'mcp.json'), key: 'mcpServers' },
+    { p: join(home, '.windsurf', 'mcp.json'), key: 'mcpServers' },
+    // codex 的 JSON 形态（TOML config.toml 另由 installCoDEX 处理）
+    { p: join(cxRoot, 'config.json'), key: ['mcp_servers', 'mcpServers'] },
+    // 通用/共享 MCP store（pi-mcp-adapter 的 GENERIC_GLOBAL_CONFIG_PATH / AGENTS_GLOBAL_CONFIG_PATHS）
+    { p: join(home, '.config', 'mcp', 'mcp.json'), key: 'mcpServers' },
+    { p: join(home, '.agents', 'mcp.json'), key: 'mcpServers' },
+    { p: join(home, '.agents', 'mcp', 'mcp.json'), key: 'mcpServers' },
+  ];
+}
+/**
+ * 在已解析的配置里找 abs 条目所在的 servers 容器。
+ * key 可为字符串（唯一容器名）或数组（**任一存在即可**，如 coDEX 的
+ * config.json 官方同时认 mcp_servers 与 mcpServers）。
+ * @returns {{key: string, entry: object}|null} 找到的容器名与 abs 条目
+ */
+function findAbsEntry(cfg, key) {
+  if (!cfg || typeof cfg !== 'object') return null;
+  const keys = Array.isArray(key) ? key : [key];
+  for (const k of keys) {
+    const box = cfg[k];
+    const entry = box && typeof box === 'object' && !Array.isArray(box) ? box.abs : null;
+    if (entry && typeof entry === 'object' && !Array.isArray(entry)) return { key: k, entry };
+  }
+  return null;
+}
+
+/**
+ * 校正一个外部 JSON store 里**已存在**的 abs 条目 args；不改 command、不新增条目。
+ * 文件缺失/非法 JSON 一律静默跳过（那是别人的配置，绝不为它中断安装）。
+ * @returns {Promise<string|null>} 一行 step 文案；无需报告/无需校正时 null
+ */
+async function reconcileOneStore(p, keys) {
+  let cfg;
+  try {
+    cfg = JSON.parse(await fs.readFile(p, 'utf8'));
+  } catch { return null; } // 不存在 / 坏 JSON: 静默, 不动
+  const hit = findAbsEntry(cfg, keys);
+  if (!hit) return null; // 没这条: 不新增
+  const want = mcpEntryPath();
+  const cur = Array.isArray(hit.entry.args) ? hit.entry.args : [];
+  if (cur.length === 1 && cur[0] === want) return null; // 幂等: 相等即不写, 不动 mtime
+  hit.entry.args = [want]; // 只碰 args, command/其它键原样保留
+  await backup(p);
+  await atomicWrite(p, JSON.stringify(cfg, null, 2));
+  return `✓ MCP    → ${p} ${hit.key}.abs 已校正 → ${want}`;
+}
+
+/**
+ * 检测 ~/.agents/skills/ 下是否已有一份**非本工具所装**的 abs skill。
+ *
+ * 坑: 这个目录是 `skills` CLI（npx skills，~/.agents/.skill-lock.json 的所有者）
+ * 的规范存储位置，各宿主的 skills/ 只是它 fan-out 的目标。abs 从不往那里写 ——
+ * 一旦写了就绕过该 CLI 的 lockfile，会被它下次 sync 判成异常或直接覆盖。
+ *
+ * 但现实里它常被**手工 cp** 进去一份（实测: 与 abs install 同一秒的 mtime、
+ * 内容逐字节相同、而 lockfile 的 skills 是空的 —— 没人认领）。那份副本不会随
+ * abs install 更新，时间一长就与真正的 SKILL.md 脱节，而 agents 偏偏会读它。
+ *
+ * 故这里只做**只读检测 + 告警**，绝不代它删除或改写（那是别人的目录）。
+ * @returns {string|null} 一行告警文案；无需告警时 null
+ */
+function agentsSkillWarning() {
+  const p = join(homedir(), '.agents', 'skills', 'abs-agent-brain-sync', 'SKILL.md');
+  if (!fsSync.existsSync(p)) return null;
+  // 内容一致 = 用户已自行同步，不必打扰
+  try {
+    if (fsSync.readFileSync(p, 'utf8') === fsSync.readFileSync(SKILL_SOURCE, 'utf8')) return null;
+  } catch { /* 读不到就照常告警 */ }
+  return [
+    `⚠ ${p} 存在一份与当前版本不一致的副本`,
+    `  ~/.agents/skills/ 归 skills CLI 所有（本工具不写它），该副本不会被 abs install 更新。`,
+    `  如不需要: rm -rf ${join(homedir(), '.agents', 'skills', 'abs-agent-brain-sync')}`,
+  ].join('\n');
+}
+
+/** 扫全部外部 store，逐个校正。返回 step 文案数组（无改动则空）。 */
+async function reconcileForeignMcpStores() {
+  const steps = [];
+  for (const { p, key } of foreignMcpStores()) {
+    const line = await reconcileOneStore(p, key);
+    if (line) steps.push(line);
+  }
+  return steps;
+}
+
+/** 从全部外部 store 删掉 abs 条目（只删这一键，不删文件/其它键）。
+ * 与宿主无关，故挂在 runUninstall 层 —— 放各 installer 里会让
+ * `abs uninstall --agent codex` 之类的单宿主路径漏清理。静默容错。 */
+async function removeAbsFromForeignMcpStores() {
+  const steps = [];
+  for (const { p, key } of foreignMcpStores()) {
+    let cfg;
+    try {
+      cfg = JSON.parse(await fs.readFile(p, 'utf8'));
+    } catch { continue; } // 不存在 / 坏 JSON: 静默跳过, 不动别人的文件
+    const hit = findAbsEntry(cfg, key);
+    if (!hit) continue;
+    delete cfg[hit.key].abs;
+    await backup(p);
+    await atomicWrite(p, JSON.stringify(cfg, null, 2));
+    steps.push(`✓ MCP    → ${p} ${hit.key}.abs 已移除`);
+  }
+  return steps;
+}
+
 async function installClaudeCode({ withMcp, withSkill, log }) {
   const steps = [];
   // 1) hooks → settings.json (分区合并: 同事件可挂多个 hook 框架, 追加 abs 而非覆盖, 保留 moshi-hook 等)
@@ -382,24 +539,37 @@ async function installCodex({ withMcp, withSkill, log }) {
       steps.push(`✓ MCP    → ${mcpP} [mcp_servers.abs]`);
     } else {
       // 已存在也要校对路径: 旧版可能写入了仓库路径(不稳定) 或全局包已迁移。
+      // 坑: 曾经只找单行 `/^\s*args\s*=/` 并原地替换。args 写成多行数组
+      //   args = [
+      //     "/old/path/mcp.js",
+      //   ]
+      // 时那一行不匹配 → 走 else 只打印"无 args 行, 未动"，旧路径**静默保留**；
+      // 而 body.includes(`"${want}"`) 的判等又会被 command 行里的同串骗过。
+      // 现改为: 只认 args 赋值本身，多行则吃到配对的 `]`，找不齐就整段重写 section。
       const want = mcpEntryPath();
       const lines = text.split('\n');
-      const body = lines.slice(found.start, found.end).join('\n');
-      if (body.includes(`"${want}"`)) {
-        steps.push(`• MCP    → ${mcpP} 已存在且路径正确, 跳过`);
-      } else {
-        // 只改 args 行的字面量值，不碰其它行（正则跨行会误伤数组内容）
-        let touched = false;
-        for (let k = found.start; k < found.end; k++) {
-          if (/^\s*args\s*=/.test(lines[k])) { lines[k] = `args = ["${want}"]`; touched = true; break; }
-        }
-        if (touched) {
+      const wa = findTomlKeyRange(lines, found, 'args');
+      if (wa) {
+        // 仅当 args 的取值里已有 want（单行或跨行）才算已正确
+        const argsText = lines.slice(wa.start, wa.end).join('\n');
+        if (argsText.includes(`"${want}"`)) {
+          steps.push(`• MCP    → ${mcpP} 已存在且路径正确, 跳过`);
+        } else {
+          lines.splice(wa.start, wa.end - wa.start, `args = ["${want}"]`);
           await backup(mcpP);
           await atomicWrite(mcpP, lines.join('\n'));
           steps.push(`✓ MCP    → ${mcpP} 路径已校正 → ${want}`);
-        } else {
-          steps.push(`• MCP    → ${mcpP} 已注册但无 args 行, 未动（请手动确认）`);
         }
+      } else {
+        // 连 args 都没有: 整段重写本 section 的 body（只含本工具的 abs 条目）
+        const rebuilt = [
+          `command = "${process.execPath}"`,
+          `args = ["${want}"]`,
+        ];
+        lines.splice(found.start + 1, found.end - found.start - 1, ...rebuilt);
+        await backup(mcpP);
+        await atomicWrite(mcpP, lines.join('\n'));
+        steps.push(`✓ MCP    → ${mcpP} 已重写 [mcp_servers.abs] (补 args) → ${want}`);
       }
     }
   }
@@ -594,7 +764,7 @@ async function installPi({ withMcp, withSkill, log }) {
   steps.push(`✓ hook(ts extension) → ${p}`);
   // MCP → ~/.pi/agent/mcp.json 的 mcpServers (stdio)
   // 曾经只打印「走 extension 内桥接」而没有任何桥接代码 —— 靠 mcp-adapter 的
-  // hostConfigDiscovery 间接读到 cl​aude 注册才"看起来能用"; 没有 cl​aude 宿主的机器上直接缺失。
+  // hostConfigDiscovery 间接读到 claude 注册才"看起来能用"; 没有 claude 宿主的机器上直接缺失。
   if (withMcp) {
     const mcpP = join(hostConfigRoot('pi'), 'agent', 'mcp.json');
     await backup(mcpP);
@@ -663,11 +833,23 @@ export async function runInstall({ agent, mcp = true, skill = true, yes = false
       if (agent) throw e;
     }
   }
+  // 外部 store 校正与宿主无关（那是别人的文件，只是其中可能有我们的陈旧条目），
+  // 故在选完宿主后统一跑一次 —— 放进各 installer 会导致 `abs install --agent codex`
+  // 这类单宿主路径漏校正。失败不影响主流程（reconcileOneStore 自身静默容错）。
+  if (mcp) {
+    try {
+      for (const line of await reconcileForeignMcpStores()) console.log('  ' + line);
+    } catch { /* 外部 store 校正失败不该让安装失败 */ }
+  }
   if (failed.length) {
     console.log(`\n⚠ ${failed.length} 个宿主安装失败: ${failed.map((f) => f.key).join(', ')}`);
     console.log('  其余宿主已完成。修复上述问题后重跑 `abs install`（幂等，不会重复写入）。');
     throw new Error(`${failed.length} 个宿主安装失败（见上）`);
   }
+  if (skill) {
+    const w = agentsSkillWarning();
+    if (w) console.log('\n' + w);
+  }
   console.log('\n完成。项目内运行 abs init 建图谱; 会话里说 "abs load" 续接。');
 }
 
@@ -679,6 +861,11 @@ export async function runUninstall({ agent, yes = false } = {}) {
     console.log(`\n▸ 从 ${key} 卸载 …`);
     for (const line of await inst.off()) console.log('  ' + line);
   }
+  // 外部 store 的 abs 条目与宿主无关（那是别人的文件），统一清理一次 ——
+  // 放进各 uninstaller 会导致 `abs uninstall --agent codex` 漏清理。
+  try {
+    for (const line of await removeAbsFromForeignMcpStores()) console.log('  ' + line);
+  } catch { /* 外部 store 清理失败不该让卸载失败 */ }
   console.log('\n卸载完成。');
 }
 

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