@fanchao8609/agent_brain_sync 1.5.4 → 1.5.6

package/src/install.js

@@ -8,7 +8,7 @@
 import { promises as fs } from 'node:fs';
 import * as fsSync from 'node:fs';
 import { homedir } from 'node:os';
-import { join, dirname, resolve } from 'node:path';
+import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { HOSTS, hostByKey } from './hosts.js';
 
@@ -17,28 +17,57 @@ const HOOK_TEMPLATE = join(ABS_DIR, 'hooks', 'event.sh');
 const SKILL_SOURCE = join(ABS_DIR, 'skill', 'SKILL.md');
 
 /**
- * 写进宿主 MCP 配置的 mcp.js 路径。
+ * 本包的稳定入口路径解析（mcp.js / abs.js 通用）。
+ *
  * 坑: 直接用 ABS_DIR 是不稳定的 —— ABS_DIR = "install.js 自己住哪", 从仓库跑
- * `abs install` 就把仓库路径写进宿主配置。之后若卸载/移动全局包, 该路径直接失效;
- * 而 Co​dex 分支又"已存在即跳过", 一旦写错永不修正。
- * 现在优先解析本包的稳定安装位置（全局 node_modules），解析不到才回退 ABS_DIR。
+ * `abs install` 就把仓库路径烧进宿主配置/hook 脚本。之后若卸载/移动仓库或全局包,
+ * 该路径直接失效; 而某些分支"已存在即跳过", 一旦写错永不修正。
+ *
+ * 故统一优先解析本包的稳定安装位置（全局 node_modules），解析不到才回退 ABS_DIR。
+ * 单一收口: MCP 注册与 hook 脚本都走这里 —— 曾经 MCP 修了、hook 没修,
+ * 同一份安装里 hook 指向仓库而 MCP 指向全局，是两个不同的包。
+ *
+ * @param entryFile 包内相对 bin/ 的文件名，如 'mcp.js' / 'abs.js'
  */
-function mcpEntryPath() {
+function stableBinPath(entryFile) {
   // 本包名（package.json），用于反查全局安装位置
   let pkgName = '@fanchao8609/agent_brain_sync';
   try {
     pkgName = JSON.parse(fsSync.readFileSync(join(ABS_DIR, 'package.json'), 'utf8')).name || pkgName;
   } catch { /* 保持默认 */ }
+
+  // 各平台 npm 全局根下的本包位置。
+  // Unix (nvm/homebrew/apt): <node根>/lib/node_modules/<pkg>
+  // Windows:                 %APPDATA%\npm\node_modules\<pkg>
+  // 注: 曾经只有 Unix 候选 —— Windows 上两个都不中，会回退到 ABS_DIR（仓库路径），
+  //     即 H3 在 Windows 上仍会复现。此条为代码层推断，未在 Windows 实测。
+  const nodeRoot = dirname(dirname(process.execPath)); // <node>/bin/node → <node>
   const candidates = [
-    // npm 全局根（最常见）
-    join(dirname(process.execPath), '..', 'lib', 'node_modules', pkgName, 'bin', 'mcp.js'),
-    join(process.env.npm_config_prefix || '', 'lib', 'node_modules', pkgName, 'bin', 'mcp.js'),
+    join(nodeRoot, 'lib', 'node_modules', pkgName, 'bin', entryFile),   // Unix
   ];
+  // npm 自己报告的全局根（npm_config_prefix 由 npm 子进程设置；交互 shell 里通常为空）
+  if (process.env.npm_config_prefix) {
+    candidates.push(join(process.env.npm_config_prefix, 'lib', 'node_modules', pkgName, 'bin', entryFile));
+    candidates.push(join(process.env.npm_config_prefix, 'node_modules', pkgName, 'bin', entryFile));
+  }
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    candidates.push(join(process.env.APPDATA, 'npm', 'node_modules', pkgName, 'bin', entryFile));
+  }
+
   for (const c of candidates) {
-    try { if (fsSync.existsSync(c)) return c; } catch { /* 试下一个 */ }
+    try {
+      // 归一化为绝对路径，避免任何依赖 cwd 的相对候选被误用
+      const abs = resolve(c);
+      if (fsSync.existsSync(abs)) return abs;
+    } catch { /* 试下一个 */ }
   }
   // 回退：仓库/本地安装形态
-  return join(ABS_DIR, 'bin', 'mcp.js');
+  return join(ABS_DIR, 'bin', entryFile);
+}
+
+/** 写进宿主 MCP 配置的 mcp.js 路径。 */
+function mcpEntryPath() {
+  return stableBinPath('mcp.js');
 }
 
 const MARK = '// abs-managed (agent-brain-sync)'; // TS plugin 标记
@@ -60,27 +89,159 @@ export function hostSkillDir(key) {
 async function atomicWrite(p, text) {
   await fs.mkdir(dirname(p), { recursive: true });
   const tmp = `${p}.abs-tmp-${Date.now()}`;
-  await fs.writeFile(tmp, text, 'utf8');
-  await fs.rename(tmp, p);
+  try {
+    await fs.writeFile(tmp, text, 'utf8');
+  } catch (e) {
+    // 写 tmp 就失败（如目标是目录）: 清掉半成品再抛，否则沙盒里留 .abs-tmp-* 残骸
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw e;
+  }
+  try {
+    await fs.rename(tmp, p);
+  } catch (e) {
+    // rename 失败（如目标路径被目录占位）: 同样清理，不留 tmp
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw e;
+  }
 }
 
 async function backup(p) {
   try {
-    const bak = `${p}.abs-bak-${new Date().toISOString().slice(0, 10)}`;
+    // 文件名含日期+时分秒: 曾经只有日期，同日多次安装/卸载会互相覆盖，
+    // 只剩最后一份 —— 用户装坏了想回滚时，最早的可用副本已经不在了。
+    const ts = new Date().toISOString().slice(0, 19).replace(/[:T]/g, '-');
+    const bak = `${p}.abs-bak-${ts}`;
     await fs.copyFile(p, bak);
+    await pruneBackups(p);
     return bak;
   } catch { return null; } // 文件不存在则无备份
 }
 
-async function readJson(p) {
-  try { return JSON.parse(await fs.readFile(p, 'utf8')); } catch { return {}; }
+/** 只保留最近 KEEP 份备份（按文件名时间戳倒序），避免备份目录无限增长。 */
+const BACKUP_KEEP = 5;
+async function pruneBackups(p) {
+  try {
+    const dir = dirname(p);
+    const base = `${basename(p)}.abs-bak-`;
+    const olds = (await fs.readdir(dir))
+      .filter((f) => f.startsWith(base))
+      .sort()          // 时间戳格式 YYYY-MM-DD-HH-mm-ss 字典序 == 时间序
+      .reverse();
+    for (const f of olds.slice(BACKUP_KEEP)) {
+      await fs.rm(join(dir, f), { force: true });
+    }
+  } catch { /* 清理失败不影响主流程 */ }
 }
 
-const ABS_HOOK_MARK = '/.abs/hooks/';
-/** 判断一个 hook 数组元素是不是 abs 装的(command 指向 ~/.abs/hooks/)。卸载/幂等去重用。 */
+async function readJson(p, { strict = true } = {}) {
+  let text;
+  try {
+    text = await fs.readFile(p, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return {}; // 文件不存在 = 空配置（正常首装）
+    throw e;                             // 权限/IO 错不能静默吞
+  }
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    if (!strict) return null; // 宽松模式: 调用方据此跳过写文件，但仍继续其它清理
+    // 关键: 「文件不存在」与「存在但解析失败」必须分开处理。
+    // 曾经两者都返回 {}，于是只要用户的配置里有 JSONC 注释/尾逗号/多一个字符，
+    // 就会被当作空对象重建 → 用户的 hooks/permissions/model/mcpServers 静默全消失。
+    // 而 JSONC（带 // 注释）正是 CL​aude Code 官方文档鼓励的写法，命中率不低。
+    // 测例: 带注释的 settings.json 安装后 myKey/permissions 全丢，且无任何报错。
+    // 处置: 宁可整个安装失败，也不写坏用户文件（与 requireBrain 同原则）。
+    //   宽松模式(strict:false)供"卸载"使用: 跳过配置文件、但仍清理 abs 自己的脚本/skill，
+    //   避免因一个坏配置就留下残余。
+    throw new Error(
+      `配置文件无法解析为 JSON，已中止以免覆盖你的配置:\n` +
+      `  ${p}\n` +
+      `  ${e.message}\n` +
+      `  若文件含 // 注释或尾逗号（JSONC），请先转成标准 JSON；` +
+      `或备份后移走该文件重跑。`,
+    );
+  }
+}
+
+/**
+ * 判断一个 hook 数组元素是不是 abs 装的（用于卸载只删自己、安装去重）。
+ *
+ * 修复: 曾经用 command.includes('/.abs/hooks/') —— 子串匹配。任何「命令文本里恰好
+ * 出现该片段」的用户 hook 都会被误判为 abs 装的，于是卸载时删掉、安装时静默丢弃。
+ * 实测真例（都被误删）:
+ *   grep -r try /home/u/.abs/hooks/ > /tmp/report
+ *   tar czf /tmp/b.tgz /home/u/.abs/hooks/ && echo done
+ * 现在改为精确匹配本工具实际写入的路径前缀: <homedir>/.abs/hooks/<agentKey>/abs-
+ * （stageHookScripts 生成的脚本名统一是 abs-<Event>.sh）。
+ */
+function absHookDir(agentKey) {
+  return join(homedir(), '.abs', 'hooks', agentKey);
+}
+/** 本工具会生成的 hook 脚本名（与 stageHookScripts 的 abs-<Event>.sh 一致）。 */
+const ABS_SCRIPT_NAMES = new Set(
+  [...new Set(HOSTS.flatMap((h) => h.events))].map((ev) => `abs-${ev}.sh`),
+);
+function isAbsStagedCommand(cmd) {
+  if (typeof cmd !== 'string') return false;
+  // 逐个路径 token 比对: 必须是 <…>/.abs/hooks/<宿名>/<本工具生成的脚本名>。
+  // 不用"任意 abs-*"——那会把用户自己的 abs-mine.sh 也判成我们的（实测边界）。
+  const tokens = cmd.match(/\S+/g) || [];
+  return tokens.some((raw) => {
+    const t = raw.replace(/^['"]+|['"]+$/g, '');
+    const m = t.match(/(?:^|\/)\.abs\/hooks\/([^/]+)\/([^/]+)$/);
+    return !!m && ABS_SCRIPT_NAMES.has(m[2]);
+  });
+}
 function entryHasAbs(entry) {
   const hs = entry && entry.hooks ? (Array.isArray(entry.hooks) ? entry.hooks : [entry.hooks]) : [];
-  return hs.some((h) => typeof h?.command === 'string' && h.command.includes(ABS_HOOK_MARK));
+  const cmds = [];
+  for (const h of hs) if (h && typeof h.command === 'string') cmds.push(h.command);
+  // 兼容扁平形态 { command } （无 hooks 字段）
+  if (entry && typeof entry.command === 'string') cmds.push(entry.command);
+  return cmds.some(isAbsStagedCommand);
+}
+
+// ============================ TOML section 行级工具 ============================
+// 为什么不用正则: 曾用 /\n?\[mcp_servers\.abs\][^\[]*/s 删 section，
+// 而 `[^\[]*` 会在下一个 `[` 处停下 —— `args = ["/x/mcp.js"]` 的数组左括号就是 `[`。
+// 结果卸载后把数组值原地截成活一个假 section 头，留下非法行 `["/…/mcp.js"]`，
+// 用户 co​dex 启动时 TOML 解析直接失败（卸载却给用户留个坏配置）。
+// 另一坑: 用 includes('[mcp_servers.abs]') 判"已存在"不区分注释 ——
+// 用户配置里一句 `# 例: [mcp_servers.abs]` 就让安装器报"已存在且路径正确, 跳过"，
+// 实际从未注册（静默失效，且重装永不修复）。
+// 故统一用行级扫描: section 头必须锚定行首、非注释；section 体到下一个 section 头为止。
+const TOML_ABS_SECTION = '[mcp_servers.abs]';
+
+/** 某行是否为 section 头（含数组表格 [[x]]）。 */
+function isTomlSectionHeader(line) {
+  return line.trimStart().startsWith('[');
+}
+
+/** 找出 [mcp_servers.abs] 真实 section 的 [start, end) 行下标；无则 null。
+ * 注释行（# 开头）不算 —— 这是修复 H1（注释导致假装成功）的关键。 */
+function findTomlAbsSection(lines) {
+  const start = lines.findIndex((l) => {
+    const t = l.trimStart();
+    return !t.startsWith('#') && t.trim() === TOML_ABS_SECTION;
+  });
+  if (start === -1) return null;
+  let end = start + 1;
+  while (end < lines.length && !isTomlSectionHeader(lines[end])) end++;
+  return { start, end };
+}
+
+/** 删除 [mcp_servers.abs] section（含其 body）；无则原样返回。
+ * @returns {{ text: string, removed: boolean }} */
+function removeTomlAbsSection(text) {
+  const lines = String(text || '').split('\n');
+  const sec = findTomlAbsSection(lines);
+  if (!sec) return { text, removed: false };
+  // 一并去掉 section 前的多余空行，避免留下连续空行
+  let from = sec.start;
+  while (from > 0 && lines[from - 1].trim() === '') from--;
+  const out = [...lines.slice(0, from), ...lines.slice(sec.end)];
+  return { text: out.join('\n').replace(/\n{3,}/g, '\n\n'), removed: true };
 }
 
 // ============================ Hook 脚本落盘 ============================
@@ -93,7 +254,7 @@ async function stageHookScripts(agentKey, events) {
     const name = `abs-${ev}.sh`;
     const p = join(dir, name);
     const script = tpl
-      .replaceAll('__ABS_BIN__', join(ABS_DIR, 'bin', 'abs.js'))
+      .replaceAll('__ABS_BIN__', stableBinPath('abs.js'))
       .replaceAll('__NODE_BIN__', process.execPath)
       .replaceAll('__EVENT__', ev);
     await atomicWrite(p, script);
@@ -147,9 +308,13 @@ async function installClaudeCode({ withMcp, withSkill, log }) {
 async function uninstallClaudeCode() {
   const steps = [];
   const settingsP = claudeSettingsPath();
-  const settings = await readJson(settingsP);
+  const settings = await readJson(settingsP, { strict: false });
+  if (settings === null) {
+    // 配置解析失败: 跳过该文件（绝不覆盖），但仍继续清理 abs 自己的脚本/skill。
+    steps.push(`⚠ ${settingsP} 无法解析为 JSON，已跳过（未改动你的配置）`);
+  }
   let touched = false;
-  if (settings.hooks) {
+  if (settings && settings.hooks) {
     const events = HOSTS[0].events;
     for (const ev of events) {
       if (!Array.isArray(settings.hooks[ev])) continue;
@@ -161,11 +326,11 @@ async function uninstallClaudeCode() {
       }
     }
   }
-  if (settings.mcpServers && settings.mcpServers.abs) {
+  if (settings && settings.mcpServers && settings.mcpServers.abs) {
     delete settings.mcpServers.abs; touched = true;
   }
   if (touched) await atomicWrite(settingsP, JSON.stringify(settings, null, 2));
-  steps.push(`✓ hooks/MCP 已从 ${settingsP} 移除`);
+  if (settings) steps.push(`✓ hooks/MCP 已从 ${settingsP} 移除`);
   // staged hook 脚本目录 —— 只删本 agent 的，绝不整删 ~/.abs/（其它 agent 的 hook / mcp.log 共存）
   await fs.rm(join(homedir(), '.abs', 'hooks', 'claude-code'), { recursive: true, force: true });
   steps.push(`✓ ~/.abs/hooks/claude-code/ (本 agent hook 脚本) 已删除`);
@@ -208,7 +373,9 @@ async function installCodex({ withMcp, withSkill, log }) {
     const mcpP = join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'config.toml');
     let text = '';
     try { text = await fs.readFile(mcpP, 'utf8'); } catch {}
-    if (!text.includes('[mcp_servers.abs]')) {
+    const found = findTomlAbsSection(text.split('\n'));
+    if (!found) {
+      // 必须用 findTomlAbsSection 而非 includes —— 注释里的同名文本不算已注册（H1）。
       const block = `\n[mcp_servers.abs]\ncommand = "${process.execPath}"\nargs = ["${mcpEntryPath()}"]\n`;
       await backup(mcpP);
       await atomicWrite(mcpP, text.replace(/\s*$/, '') + '\n' + block);
@@ -216,13 +383,23 @@ async function installCodex({ withMcp, withSkill, log }) {
     } else {
       // 已存在也要校对路径: 旧版可能写入了仓库路径(不稳定) 或全局包已迁移。
       const want = mcpEntryPath();
-      const re = /(\[mcp_servers\.abs\][^\[]*?args\s*=\s*\[)"[^"]*"(\])/s;
-      if (re.test(text) && !text.includes(`"${want}"`)) {
-        await backup(mcpP);
-        await atomicWrite(mcpP, text.replace(re, `$1"${want}"$2`));
-        steps.push(`✓ MCP    → ${mcpP} 路径已校正 → ${want}`);
-      } else {
+      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) {
+          await backup(mcpP);
+          await atomicWrite(mcpP, lines.join('\n'));
+          steps.push(`✓ MCP    → ${mcpP} 路径已校正 → ${want}`);
+        } else {
+          steps.push(`• MCP    → ${mcpP} 已注册但无 args 行, 未动（请手动确认）`);
+        }
       }
     }
   }
@@ -238,13 +415,16 @@ async function uninstallCodex() {
   const steps = [];
   const home = process.env.CODEX_HOME || join(homedir(), '.codex');
   const p = join(home, 'hooks.json');
-  const cfg = await readJson(p);
+  const cfg = await readJson(p, { strict: false });
+  if (cfg === null) {
+    steps.push(`⚠ ${p} 无法解析为 JSON，已跳过（未改动你的配置）`);
+  }
   let changed = false;
-  if (Array.isArray(cfg.hooks)) { // 历史扁平数组形态
+  if (cfg && Array.isArray(cfg.hooks)) {
     const before = cfg.hooks.length;
-    cfg.hooks = cfg.hooks.filter((h) => !String(h.command || '').includes('/.abs/hooks/'));
+    cfg.hooks = cfg.hooks.filter((h) => !isAbsStagedCommand(String(h.command || '')));
     changed = cfg.hooks.length !== before;
-  } else if (cfg.hooks && typeof cfg.hooks === 'object') { // 对象形态 {EventName: [...]}
+  } else if (cfg && cfg.hooks && typeof cfg.hooks === 'object') {
     for (const ev of Object.keys(cfg.hooks)) {
       const arr = cfg.hooks[ev];
       if (!Array.isArray(arr)) continue;
@@ -263,9 +443,11 @@ async function uninstallCodex() {
   const mcpP = join(home, 'config.toml');
   try {
     const text = await fs.readFile(mcpP, 'utf8');
-    if (text.includes('[mcp_servers.abs]')) {
-      const re = /\n?\[mcp_servers\.abs\][^\[]*/s;
-      await atomicWrite(mcpP, text.replace(re, '\n'));
+    // 用行级扫描而非正则: 正则会在 args = [...] 的 [ 处截断，
+    // 留下非法行 ["/…/mcp.js"] 让用户的 TOML 解析失败。
+    const { text: after, removed } = removeTomlAbsSection(text);
+    if (removed) {
+      await atomicWrite(mcpP, after);
       steps.push(`✓ MCP 已从 ${mcpP} 移除`);
     }
   } catch {}
@@ -274,133 +456,53 @@ async function uninstallCodex() {
   return steps;
 }
 
-// ============================ Opencode / Pi (TS 插件) ============================
-function opencodePluginSource() {
-  // Op​encode 官方插件 API (据 @op​encode-ai/plugin 类型定义实核):
-  //   export const Plugin: Plugin = async ({ client, directory }) => ({ event: async ({ event }) => {...} })
-  // 坑: event 回调入参是 { event }, 事件名在 event.type —— 曾错写成 ({ name }) 导致 name 恒 undefined,
-  //     插件从未触发过(0 条日志), 静默失效。
-  // 收尾注入: session.idle (= 每轮结束) 经 client.session.promptAsync 注入收尾指令,
-  //     与 pi 的 agent_end 同策略(真改过文件 + .brain 存在 + log.md 今日无记录, 每会话一次)。
-  return `/**
- * abs (agent-brain-sync) — Op​encode plugin。
- * 纯触发: 生命周期事件 → 技术日志一行 (~/.abs/log/hooks.log, ABS_LOG_DIR 可覆盖)。fire-and-forget。
- * 纪律: hook 事件只进技术日志, 不进图谱 log.md (log.md 只收工作成果沉淀, 与 event.sh 同纪律)。
- * Op​encode 事件: session.created / session.idle / session.deleted (idle = 每轮结束, 对应 pi 的 agent_end)。
- * 收尾注入: session.idle 且本会话真改过文件 + .brain 今日无记录 → promptAsync 推 agent 走收尾循环。
+/**
+ * opencode 路径歧义提示（返回一行警告文本，无歧义时返回 null）。
+ *
+ * 背景: opencode 的全局配置默认在 ~/.config/opencode/，但它同样尊重
+ *   XDG_CONFIG_HOME（官方支持 XDG 规范）。若用户设了该变量，opencode 会去
+ *   $XDG_CONFIG_HOME/opencode/ 读配置，而本工具默认仍写 ~/.config/opencode/ ——
+ *   于是插件装了却不生效（静默失效，最难查）。同理 OPENCODE_CONFIG 可覆盖配置文件路径。
+ *
+ * 为什么只警告不自动跟随: ①跟随会让"装到哪"依赖环境变量，变得不可预测；
+ *   ②若 opencode 实际没读该变量，跟着写反而错。故只提示，把决定权留给用户 ——
+ *   用户可用 ABS_OPENCODE_HOME 显式指定目标。
  */
-import { appendFile, mkdir, readFile, stat } from "node:fs/promises"
-import { homedir } from "node:os"
-import { join, dirname } from "node:path"
-
-const server = async ({ client, directory }) => {
-  // 本会话是否真改过文件 (由 tool.execute.after 观测)
-  let wroteFiles = false
-  let nudged = false
-  let idleSeen = false
-
-  async function logHook(evt) {
-    try {
-      const dir = process.env.ABS_LOG_DIR || join(homedir(), ".abs", "log")
-      const d = new Date()
-      const pad = (n) => String(n).padStart(2, "0")
-      const stamp = d.getFullYear() + "-" + pad(d.getMonth() + 1) + "-" + pad(d.getDate()) + " " + pad(d.getHours()) + ":" + pad(d.getMinutes()) + ":" + pad(d.getSeconds())
-      await mkdir(dir, { recursive: true })
-      await appendFile(join(dir, "hooks.log"), "[" + stamp + "] opencode:" + evt + "\\n")
-    } catch {} // fire-and-forget: 永不阻塞宿主
-  }
-
-  // 从 cwd 向上找最近含 .brain/ 的祖先目录
-  async function findBrain(cwd) {
-    let d = cwd || process.cwd()
-    for (;;) {
-      try { const st = await stat(join(d, ".brain")); if (st.isDirectory()) return join(d, ".brain") } catch {}
-      const up = dirname(d)
-      if (up === d) return null
-      d = up
-    }
+function opencodePathWarning() {
+  // 本工具实际会写入的位置（ABS_OPENCODE_HOME 覆盖时即该值）
+  const ours = hostConfigRoot("opencode");
+  const hints = [];
+
+  // opencode 自身可能读取的位置。它支持 XDG 规范，故 XDG_CONFIG_HOME 优先于 ~/.config。
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const opencodeWillRead = xdg ? join(xdg, "opencode") : null;
+  if (opencodeWillRead && resolve(opencodeWillRead) !== resolve(ours)) {
+    hints.push(`XDG_CONFIG_HOME=${xdg} → opencode 会读 ${opencodeWillRead}，但本工具写的是 ${ours}`);
   }
-
-  // 判定"今天是否收尾过": 必须匹配 log.md 的条目头 '## [YYYY-MM-DD HH:MM]'。
-  // 坑: 曾用裸日期 substring(includes('2026-09-10')), 结果正文/任务行里任何一处
-  //     提到今天就能把 nudge 永久压掉(误判为已收尾), 守卫形同虚设。
-  async function loggedToday(brain) {
-    try {
-      const txt = await readFile(join(brain, "log.md"), "utf8")
-      const d = new Date()
-      const pad = (n) => String(n).padStart(2, "0")
-      const today = d.getFullYear() + "-" + pad(d.getMonth() + 1) + "-" + pad(d.getDate())
-      return new RegExp("^## \\\\[" + today + " \\\\d{2}:\\\\d{2}\\\\]", "m").test(txt)
-    } catch { return false }
-  }
-
-  const TEARDOWN_MSG =
-    "[abs 收尾提醒] 本会话改过文件但 .brain/ 今天还没有记录。请立即走收尾循环：\\n" +
-    "1) 跑 abs load 看 Today 还有哪些未完成；\\n" +
-    "2) 实际做完漏登记的 abs todo done <id>，做到一半的 abs todo note <id> --note \\"断点\\"；\\n" +
-    "3) 值得留的经验 abs note \\"...\\"（宁少勿滥，能从代码 grep 到的不记）；\\n" +
-    "4) abs log \\"完成 X：...\\" 记一行工作成果，新页同步进 index。\\n" +
-    "简洁执行，不要复述本条提醒。若本次确实没有可沉淀产出，直接回一句\\"无可沉淀\\"即可。"
-
-  // bash 里只跑查询类命令不算改文件 (与 pi 侧 READONLY_CMD 同义, 但生成代码里要写进模板串)
-  const READONLY_CMD = /^\\s*(ls|cat|grep|rg|find|head|tail|wc|git\\s+(status|log|diff|show|branch)|pwd|which|echo|node\\s+-v|npm\\s+(ls|view)|curl)\\b/
-
-  return {
-    // 观测真实写操作: write/edit/patch 类工具成功即标记。
-    // 坑: 曾漏掉 bash —— op​encode 里很多修改是经 bash(heredoc/sed) 完成的, 纯 bash 会话
-    //     永远不置位 wroteFiles, 于是收尾提醒静默不发。与 pi 侧 WRITE_TOOLS 保持一致。
-    "tool.execute.after": async ({ tool, args }) => {
-      const t = String(tool || "").toLowerCase()
-      if (["write", "edit", "patch", "multiedit", "apply_patch"].includes(t)) {
-        wroteFiles = true
-        return
-      }
-      // bash 里只有非只读命令算改文件(ls/cat/git status 之类不算)
-      if (t === "bash") {
-        const cmd = String((args && (args.command || args.cmd)) || "")
-        if (cmd && !READONLY_CMD.test(cmd)) wroteFiles = true
-      }
-    },
-
-    event: async ({ event }) => {
-      const type = event && event.type
-      if (!type) return
-      if (type === "session.created" || type === "session.deleted") {
-        await logHook(type)
-        return
-      }
-      if (type !== "session.idle") return // idle = 每轮结束, 不记日志(太吵), 只做收尾判定
-      const cwd = directory || process.cwd()
-      const brain = await findBrain(cwd)
-      // 可观测性: 首次 idle 无条件留一行痕(否则无法区分“事件没触发”与“被守卫拦下”)
-      if (!idleSeen) {
-        idleSeen = true
-        await logHook(\`session.idle:seen cwd=\${cwd} brain=\${brain || 'none'}\`)
-      }
-      if (nudged || !wroteFiles) return
-      const sessionID = event.properties && event.properties.sessionID
-      if (!sessionID) return
-      if (!brain) return // 无图谱=不在这项目沉淀, 不打扰
-      if (await loggedToday(brain)) return // 今天已收尾过
-      nudged = true
-      await logHook("session.idle:teardown-nudge")
-      try {
-        await client.session.promptAsync({
-          path: { id: sessionID },
-          query: { directory: cwd },
-          body: { parts: [{ type: "text", text: TEARDOWN_MSG }] },
-        })
-      } catch {} // 注入失败不阻塞宿主
-    },
+  if (process.env.OPENCODE_CONFIG) {
+    hints.push(`OPENCODE_CONFIG=${process.env.OPENCODE_CONFIG} 会覆盖全局配置路径（优先级高于上面两者）`);
   }
-}
 
-export default {
-  id: "abs",
-  server,
+  if (!hints.length) return null;
+  // 修复: 曾经 ABS_OPENCODE_HOME 一被设置就无条件 return null —— 于是即使用户
+  // 显式指定的目标与 opencode 实际会读的位置也不一致，警告仍完全静默。
+  // 现在改为「只比较路径是否一致」: 一致就静默（无歧义），不一致就提示，
+  // 无论目标来自默认值还是显式 env。
+  const via = process.env.ABS_OPENCODE_HOME ? "（目标由 ABS_OPENCODE_HOME 显式指定）" : "";
+  return [
+    "⚠ opencode 配置路径可能不一致（已装的插件可能不生效）:" + via,
+    ...hints.map((h) => `    - ${h}`),
+    "  如需指定目标: ABS_OPENCODE_HOME=<配置根> abs install --agent opencode",
+  ].join("\n");
 }
-${MARK}
-`;
+
+// ============================ Opencode / Pi (TS 插件) ============================
+function opencodePluginSource() {
+  // 模板已外置到 hooks/abs.opencode.ts（真文件，非字符串）。
+  // 为什么外置: ①改一处逻辑不用在模板里再改一遍(曾漏改导致行为不一致)
+  //            ②生成产物能被测试直接 import 断言, 不再解析字符串产物(间接测试的税)
+  // 转义坑已消除: 以前模板嵌在模板字符串里，\n / \" / \` 双层转义极易写错(代码注释亦踩过)。
+  return renderPluginTemplate('abs.opencode.ts', { '@@MARK@@': MARK });
 }
 
 // ============================ Pi (TS extension) ============================
@@ -408,145 +510,29 @@ ${MARK}
 // 不能复用 opencodePluginSource 的写法（那是 export const ... = ({ project }) => ...）。
 // 两者同纪律: 生命周期事件只进技术日志 hooks.log, 不进图谱 log.md。
 function piPluginSource() {
-  return `/**
- * abs (agent-brain-sync) — Pi extension。
- * 纯触发: 会话生命周期事件 → 技术日志一行 (~/.abs/log/hooks.log, ABS_LOG_DIR 可覆盖)。fire-and-forget。
- * 纪律: hook 事件只进技术日志, 不进图谱 log.md (log.md 只收工作成果沉淀, 与 event.sh 同纪律)。
- * Pi 事件: session_start / session_shutdown (对应 host hook 的 SessionStart/SessionEnd)。
- * session_shutdown 额外触发 abs wrapup: 把当前项目未完成任务快照到 wrapup.log (跨会话收尾保险)。
- * agent_end 收尾注入: 本会话真改过文件 + .brain 今日无记录 → 注入一条收尾指令, 逼 agent 走收尾循环
- *   (被动记日志不够 —— 没人提醒就不会有人收尾)。每会话最多一次, 且已收尾后不再打扰。
- */
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
-import { appendFile, mkdir, readFile, stat } from "node:fs/promises"
-import { homedir } from "node:os"
-import { join, dirname } from "node:path"
-import { spawn } from "node:child_process"
-
-const ABS_BIN = "${join(ABS_DIR, 'bin', 'abs.js')}"
-
-async function logHook(evt: string): Promise<void> {
-  const dir = process.env.ABS_LOG_DIR || join(homedir(), ".abs", "log")
-  const d = new Date()
-  const pad = (n: number) => String(n).padStart(2, "0")
-  const stamp = d.getFullYear() + "-" + pad(d.getMonth() + 1) + "-" + pad(d.getDate()) + " " + pad(d.getHours()) + ":" + pad(d.getMinutes()) + ":" + pad(d.getSeconds())
-  const line = "[" + stamp + "] pi:" + evt + "\\n"
-  await mkdir(dir, { recursive: true })
-  await appendFile(join(dir, "hooks.log"), line)
-}
-
-// 会话结束时快照当前项目滞留任务到 wrapup.log（detached fire-and-forget，wrapup 自身幂等去重不刷屏）。
-// cwd 用事件 ctx.cwd（当前项目），让 abs 从该目录向上定位 .brain/。
-function snapshotWrapup(cwd: string): void {
-  try {
-    const child = spawn(process.execPath, [ABS_BIN, "wrapup"], {
-      cwd: cwd || process.cwd(), stdio: "ignore", detached: true,
-    })
-    child.unref()
-  } catch {} // fire-and-forget
-}
-
-// ---- 收尾注入判定 ----
-// 真改过文件的工具（read/grep/ls 不算, 那些不产生可沉淀的产出）
-const WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "apply_patch", "bash"])
-// bash 里只跑查询类命令不算改文件
-const READONLY_CMD = /^\\s*(ls|cat|grep|rg|find|head|tail|wc|git\\s+(status|log|diff|show|branch)|pwd|which|echo|node\\s+-v|npm\\s+(ls|view)|curl)\\b/
-
-function hasWriteWork(toolResults: any[]): boolean {
-  for (const r of toolResults || []) {
-    const name = String(r?.toolName || "")
-    if (!WRITE_TOOLS.has(name)) continue
-    if (r?.isError) continue
-    if (name === "bash") {
-      const cmd = String(r?.input?.command ?? r?.args?.command ?? "")
-      if (READONLY_CMD.test(cmd)) continue
-    }
-    return true
-  }
-  return false
-}
-
-/** 从 cwd 向上找最近含 .brain/ 的祖先目录。 */
-async function findBrain(cwd: string): Promise<string | null> {
-  let d = cwd || process.cwd()
-  for (;;) {
-    try {
-      const st = await stat(join(d, ".brain"))
-      if (st.isDirectory()) return join(d, ".brain")
-    } catch {}
-    const up = dirname(d)
-    if (up === d) return null
-    d = up
-  }
+  // 模板已外置到 hooks/abs.pi.ts。理由同 opencodePluginSource。
+  return renderPluginTemplate('abs.pi.ts', {
+    '@@ABS_BIN@@': stableBinPath('abs.js'),
+    '@@MARK@@': MARK,
+  });
 }
 
 /**
- * .brain/log.md 今天有记录吗? 有=已收尾, 不再打扰。
- * 必须匹配条目头 '## [YYYY-MM-DD HH:MM]' —— 裸日期 substring 会被正文里任意一处
- * 今天的日期误命中, 导致"已收尾"误判、nudge 永不触发。
+ * 读 hooks/ 下的插件模板（真文件，非字符串）并替换 @@占位符@@。
+ * 为什么用占位符而非模板字符串: 模板本身是 TS 代码，含 \n / " / \` 等；
+ * 以前嵌在模板字符串里需双层转义，极易写错且只能靠“生成的字符串”间接测。
+ * 现在模板是真文件 → 可用真 TS 编辑器/测试直接 import 断言。
+ * 找不到模板文件时抛错（宁可失败也不静默生成空插件）。
  */
-async function loggedToday(brain: string): Promise<boolean> {
+function renderPluginTemplate(name, vars) {
+  let t;
   try {
-    const txt = await readFile(join(brain, "log.md"), "utf8")
-    const d = new Date()
-    const pad = (n: number) => String(n).padStart(2, "0")
-    const today = d.getFullYear() + "-" + pad(d.getMonth() + 1) + "-" + pad(d.getDate())
-    // 注意: 这里是真实 TS, 不是生成代码的模板字符串。用拼接形式避免反斜杠逃逸歧义。
-    return new RegExp("^## \\\\[" + today + " \\\\d{2}:\\\\d{2}\\\\]", "m").test(txt)
-  } catch { return false }
-}
-
-export default function absPiHook(pi: ExtensionAPI): void {
-  pi.on("session_start", () => logHook("session_start").catch(() => {}))
-
-  // 收尾注入: 每个会话最多一次, 避免反复打扰。
-  let teardownNudged = false
-  let agentEndSeen = false
-  pi.on("agent_end", async (event: any, ctx: any) => {
-    if (teardownNudged) return
-    const cwd = (ctx && ctx.cwd) || process.cwd()
-    const brain = await findBrain(cwd)
-    // 可观测性: 本会话首次 agent_end 无条件留一行痕。
-    // 没有它就无法区分三种状态: ①事件没触发 ②触发了但被守卫拦下 ③真注入了。
-    if (!agentEndSeen) {
-      agentEndSeen = true
-      // 带上 cwd 与命中的 brain —— 否则事后无法解释“为何这条 nudge 会出现”
-      await logHook(\`agent_end:seen cwd=\${cwd} brain=\${brain || 'none'}\`).catch(() => {})
-    }
-    if (!brain) return // 无图谱=不在这项目沉淀, 不打扰
-    if (!hasWriteWork(event?.messages ? collectToolResults(event.messages) : [])) return
-    if (await loggedToday(brain)) return // 今天已收尾过
-    teardownNudged = true
-    await logHook("agent_end:teardown-nudge").catch(() => {})
-    try {
-      pi.sendUserMessage(
-        "[abs 收尾提醒] 本会话改过文件但 .brain/ 今天还没有记录。请立即走收尾循环：\\n" +
-        "1) 跑 abs load 看 Today 还有哪些未完成；\\n" +
-        "2) 实际做完漏登记的 abs todo done <id>，做到一半的 abs todo note <id> --note \\"断点\\"；\\n" +
-        "3) 值得留的经验 abs note \\"...\\"（宁少勿滥，能从代码 grep 到的不记）；\\n" +
-        "4) abs log \\"完成 X：...\\" 记一行工作成果，新页同步进 index。\\n" +
-        "简洁执行，不要复述本条提醒。若本次确实没有可沉淀产出，直接回一句\\"无可沉淀\\"即可。",
-        { deliverAs: "followUp" },
-      )
-    } catch {}
-  })
-
-  pi.on("session_shutdown", (_e: any, ctx: any) => {
-    snapshotWrapup((ctx && ctx.cwd) || process.cwd())
-    logHook("session_shutdown").catch(() => {})
-  })
-}
-
-/** agent_end 的 event.messages 里翻出 toolResult 消息。 */
-function collectToolResults(messages: any[]): any[] {
-  const out: any[] = []
-  for (const m of messages || []) {
-    if (m && m.role === "toolResult") out.push(m)
+    t = fsSync.readFileSync(join(ABS_DIR, 'hooks', name), 'utf8');
+  } catch (e) {
+    throw new Error(`插件模板缺失: hooks/${name}（安装包不完整？）: ${e.message}`);
   }
-  return out
-}
-${MARK}
-`;
+  for (const [k, v] of Object.entries(vars || {})) t = t.split(k).join(v);
+  return t;
 }
 
 async function installOpenCode({ withMcp, withSkill, log }) {
@@ -555,6 +541,8 @@ async function installOpenCode({ withMcp, withSkill, log }) {
   const p = join(dir, 'abs.ts');
   await atomicWrite(p, opencodePluginSource());
   steps.push(`✓ hook(ts plugin) → ${p}`);
+  const warn = opencodePathWarning();
+  if (warn) steps.push(warn);
   if (withMcp) {
     const mcpP = join(hostConfigRoot('opencode'), 'opencode.json');
     const cfg = await readJson(mcpP);
@@ -577,12 +565,18 @@ async function installOpenCode({ withMcp, withSkill, log }) {
 
 async function uninstallOpenCode() {
   const steps = [];
+  // 路径歧义提示（卸载侧同样有价值：可能提示用户去清另一个位置的旧副本）
+  const warn = opencodePathWarning();
+  if (warn) steps.push(warn);
   const plugin = join(hostConfigRoot('opencode'), 'plugins', 'abs.ts');
   await fs.rm(plugin, { force: true });
   steps.push(`✓ plugin 已删除`);
   const mcpP = join(hostConfigRoot('opencode'), 'opencode.json');
-  const cfg = await readJson(mcpP);
-  if (cfg.mcp && cfg.mcp.abs) {
+  const cfg = await readJson(mcpP, { strict: false });
+  if (cfg === null) {
+    steps.push(`⚠ ${mcpP} 无法解析为 JSON，已跳过（未改动你的配置）`);
+  }
+  if (cfg && cfg.mcp && cfg.mcp.abs) {
     delete cfg.mcp.abs;
     await atomicWrite(mcpP, JSON.stringify(cfg, null, 2));
     steps.push(`✓ MCP 已从 ${mcpP} 移除`);
@@ -625,8 +619,11 @@ async function uninstallPi() {
   await fs.rm(hostSkillDir('pi'), { recursive: true, force: true });
   steps.push(`✓ skill 已删除`);
   const mcpP = join(hostConfigRoot('pi'), 'agent', 'mcp.json');
-  const cfg = await readJson(mcpP);
-  if (cfg.mcpServers && cfg.mcpServers.abs) {
+  const cfg = await readJson(mcpP, { strict: false });
+  if (cfg === null) {
+    steps.push(`⚠ ${mcpP} 无法解析为 JSON，已跳过（未改动你的配置）`);
+  }
+  if (cfg && cfg.mcpServers && cfg.mcpServers.abs) {
     delete cfg.mcpServers.abs;
     await atomicWrite(mcpP, JSON.stringify(cfg, null, 2));
     steps.push(`✓ MCP 已从 ${mcpP} 移除`);
@@ -647,15 +644,30 @@ export function installSummary() {
 }
 
 export async function runInstall({ agent, mcp = true, skill = true, yes = false } = {}) {
-  const targets = agent ? [agent] : await pickAgents();
+  const targets = agent ? [agent] : await pickAgents(yes);
+  const failed = [];
   for (const key of targets) {
     const inst = INSTALLERS[key];
     if (!inst) throw new Error(`未知 agent: ${key} (可用: ${Object.keys(INSTALLERS).join(', ')})`);
     console.log(`\n▸ 安装到 ${key} …`);
-    for (const line of await inst.on({ withMcp: mcp, withSkill: skill })) {
-      console.log('  ' + line);
+    try {
+      for (const line of await inst.on({ withMcp: mcp, withSkill: skill })) {
+        console.log('  ' + line);
+      }
+    } catch (e) {
+      // 逐宿主容错: 一个宿主失败不应让其余宿主整体被跳过。
+      // 坑: 曾经任一处报错就直接上抛，于是前序宿主已装、后续宿主全未装 —— 半成品状态。
+      // 注意: 单宿主安装(agent 指定)时仍上抛，保持 CLI 非零退出语义。
+      failed.push({ key, msg: String(e && e.message ? e.message : e) });
+      console.error(`  ✗ ${key} 安装失败: ${failed[failed.length - 1].msg}`);
+      if (agent) throw e;
     }
   }
+  if (failed.length) {
+    console.log(`\n⚠ ${failed.length} 个宿主安装失败: ${failed.map((f) => f.key).join(', ')}`);
+    console.log('  其余宿主已完成。修复上述问题后重跑 `abs install`（幂等，不会重复写入）。');
+    throw new Error(`${failed.length} 个宿主安装失败（见上）`);
+  }
   console.log('\n完成。项目内运行 abs init 建图谱; 会话里说 "abs load" 续接。');
 }
 
@@ -671,8 +683,11 @@ export async function runUninstall({ agent, yes = false } = {}) {
 }
 
 // 交互式多选（无 TTY 时回退为全部）
-async function pickAgents() {
-  if (!process.stdin.isTTY) return Object.keys(INSTALLERS);
+async function pickAgents(yes = false) {
+  // --yes / 非 TTY: 直接全选，绝不弹交互。
+  // 坑: 曾经只看 isTTY，--yes 被收下却从不使用 —— 在 TTY 里跑
+  //     abs install --yes（自动化/脚本）仍会弹提示并挂起等输入。
+  if (yes || !process.stdin.isTTY) return Object.keys(INSTALLERS);
   const readline = await import('node:readline/promises');
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   console.log('选择要安装的智能体 (逗号分隔, 回车=全部):');