@fanchao8609/agent_brain_sync 1.5.5 → 1.5.6

package/bin/abs.js

@@ -69,8 +69,11 @@ function parseArgv(args) {
     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; }
@@ -95,7 +98,9 @@ const usage = `abs — agent-brain-sync 记忆工具
   abs todo add     <id> [--note ..] [--section ..]  登记任务 (start 同义)
   abs todo note    <id> --note "断点/进度"   实时落 ↳ 断点 行
   abs todo blocked <id> --note "卡点原因"    移入 Blocked 区
-  abs todo done    <id>                      完成并归位 Done
+  abs todo done    <id> [--as 落地|否决|仅方案]    完成；结语标明到底"做成了没有"
+                               默认 落地。否决=评估后不做(含做了又撤)；仅方案=只设计过
+                               不加结语或结语失真会让下一个会话把"想过"当成"做完了"。
   abs log "完成 X：…"         记一行工作成果 (无参=查看)
   abs note "经验一句话" [--tags 坑,docker]    经验实时暂存 → sources/
 
@@ -115,6 +120,47 @@ const usage = `abs — agent-brain-sync 记忆工具
 注: abs wrapup / abs teardown-check 是 hook 内部命令, 不需手动调用。
 `;
 
+/** 子命令级用法（abs <cmd> --help 时打印）。 */
+const subUsage = {
+  install: [
+    'abs install — 把 MCP + hook + skill 安装到 AI 编码宿主',
+    '',
+    '用法:',
+    '  abs install [--agent <宿主>] [--yes] [--no-mcp] [--no-skill]',
+    '',
+    '参数:',
+    '  --agent <宿主>   只装一个宿主: claude-code | codex | opencode | pi',
+    '                   (不传则在 TTY 下交互多选; 非 TTY / --yes 时为全部)',
+    '  --yes            不交互，直接装全部宿主（自动化用）',
+    '  --no-mcp         不注册 MCP server',
+    '  --no-skill       不装 skill',
+    '',
+    '说明:',
+    '  • 幂等: 重复安装不会叠加，也不会覆盖宿主的其它配置',
+    '  • 配置文件解析失败时会中止（不会清空你的配置）',
+    '  • 安装前会备份原配置（同日多份保留最近 5 份）',
+    '',
+    '例:',
+    '  abs install                    交互选择',
+    '  abs install --yes              全部宿主',
+    '  abs install --agent pi --yes   只装 pi',
+  ].join('\n'),
+  uninstall: [
+    'abs uninstall — 从 AI 编码宿主移除 abs 的 MCP / hook / skill',
+    '',
+    '用法:',
+    '  abs uninstall [--agent <宿主>] [--yes]',
+    '',
+    '参数:',
+    '  --agent <宿主>   只卸一个宿主: claude-code | codex | opencode | pi（不传=全部）',
+    '  --yes            不交互',
+    '',
+    '说明:',
+    '  • 只删 abs 自己装的东西，保留你其它的 hook / MCP / 配置字段',
+    '  • 配置文件无法解析时会跳过该文件（不覆盖）但仍清理 abs 的脚本与 skill',
+  ].join('\n'),
+};
+
 /**
  * 拒绝多余的未知位置参数。
  * 坑: 以前只读命令(如 abs todo)会静默忽略多余词 —— `abs todo add x` 照样打印看板、
@@ -201,17 +247,29 @@ async function main() {
             `  登记任务: abs todo add <id> --note "做什么"`,
           );
         }
-        rejectExtra(rest2, `abs todo ${sub} <id>${action === 'done' ? '' : ' --note "…"'}`);
-        if (!id) throw new Error(`✗ 缺 <id>\n  用法: abs todo ${sub} <id>${action === 'done' ? '' : ' --note "…"'}`);
-        console.log(await cmdTask({ dir: opts.dir, action, id, section: opts.section, note: opts.note }));
+        rejectExtra(rest2, `abs todo ${sub} <id>${action === 'done' ? ' [--as 落地|否决|仅方案]' : ' --note "…"'}`);
+        if (!id) throw new Error(`✗ 缺 <id>\n  用法: abs todo ${sub} <id>${action === 'done' ? ' [--as 落地|否决|仅方案]' : ' --note "…"'}`);
+        console.log(await cmdTask({ dir: opts.dir, action, id, section: opts.section, note: opts.note, as: opts.as }));
         break;
       }
       case 'note': {
         console.log(await cmdNote({ dir: opts.dir, text: opts._.join(' '), tags: opts.tags }));
         break;
       }
-      case 'install':  await runInstall({ agent: opts.agent, mcp: opts.mcp !== false, skill: opts.skill !== false, yes: opts.yes }); break;
-      case 'uninstall': await runUninstall({ agent: opts.agent, yes: opts.yes }); break;
+      case 'install':
+      case 'uninstall': {
+        // 子命令级 --help: 打印用法后直接返回。
+        // 坑(INSTALL-HELP-FOOTGUN): 以前 --help 只在顶层命令被识别，跟在 install 后面时
+        // 落到 parseArgv 的通用分支，而 install 分支根本不读它 → 用户想看帮助，
+        // 实际执行了全量安装（幂等不炸，但确实改了四宿主配置，写了 15 个文件）。
+        if (opts.help) { console.log(subUsage[cmd]); break; }
+        if (cmd === 'install') {
+          await runInstall({ agent: opts.agent, mcp: opts.mcp !== false, skill: opts.skill !== false, yes: opts.yes });
+        } else {
+          await runUninstall({ agent: opts.agent, yes: opts.yes });
+        }
+        break;
+      }
       case 'agents':   console.log(installSummary()); break;
       case 'query': {
         console.log(await cmdQuery({ dir: opts.dir, terms: opts._ }));

package/hooks/abs.opencode.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 走收尾循环。
+ */
+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: 永不阻塞宿主
+  }
+
+  // 定位当前项目的 .brain/：只看 cwd 本身，不向上搜索（防爬到家目录图谱）
+  async function findBrain(cwd) {
+    const d = cwd || process.cwd()
+    try { const st = await stat(join(d, ".brain")); return st.isDirectory() ? join(d, ".brain") : null } catch { return null }
+  }
+
+  // 判定"今天是否收尾过": 必须匹配 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 {} // 注入失败不阻塞宿主
+    },
+  }
+}
+
+export default {
+  id: "abs",
+  server,
+}
+@@MARK@@

package/hooks/abs.pi.ts

@@ -0,0 +1,130 @@
+/**
+ * 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 = "@@ABS_BIN@@"
+
+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
+}
+
+/** 定位当前项目的 .brain/：只看 cwd 本身，不向上搜索（防爬到家目录图谱）。 */
+async function findBrain(cwd: string): Promise<string | null> {
+  const d = cwd || process.cwd()
+  try { const st = await stat(join(d, ".brain")); return st.isDirectory() ? join(d, ".brain") : null } catch { return null }
+}
+
+/**
+ * .brain/log.md 今天有记录吗? 有=已收尾, 不再打扰。
+ * 必须匹配条目头 '## [YYYY-MM-DD HH:MM]' —— 裸日期 substring 会被正文里任意一处
+ * 今天的日期误命中, 导致"已收尾"误判、nudge 永不触发。
+ */
+async function loggedToday(brain: string): Promise<boolean> {
+  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)
+  }
+  return out
+}
+@@MARK@@

package/package.json

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

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 { /* 清理失败不影响主流程 */ }
+}
+
+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；` +
+      `或备份后移走该文件重跑。`,
+    );
+  }
 }
 
-const ABS_HOOK_MARK = '/.abs/hooks/';
-/** 判断一个 hook 数组元素是不是 abs 装的(command 指向 ~/.abs/hooks/)。卸载/幂等去重用。 */
+/**
+ * 判断一个 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,128 +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: 永不阻塞宿主
+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}`);
   }
-
-  // 定位当前项目的 .brain/：只看 cwd 本身，不向上搜索（防爬到家目录图谱）
-  async function findBrain(cwd) {
-    const d = cwd || process.cwd()
-    try { const st = await stat(join(d, ".brain")); return st.isDirectory() ? join(d, ".brain") : null } catch { return null }
+  if (process.env.OPENCODE_CONFIG) {
+    hints.push(`OPENCODE_CONFIG=${process.env.OPENCODE_CONFIG} 会覆盖全局配置路径（优先级高于上面两者）`);
   }
 
-  // 判定"今天是否收尾过": 必须匹配 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 (!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");
 }
 
-export default {
-  id: "abs",
-  server,
-}
-${MARK}
-`;
+// ============================ Opencode / Pi (TS 插件) ============================
+function opencodePluginSource() {
+  // 模板已外置到 hooks/abs.opencode.ts（真文件，非字符串）。
+  // 为什么外置: ①改一处逻辑不用在模板里再改一遍(曾漏改导致行为不一致)
+  //            ②生成产物能被测试直接 import 断言, 不再解析字符串产物(间接测试的税)
+  // 转义坑已消除: 以前模板嵌在模板字符串里，\n / \" / \` 双层转义极易写错(代码注释亦踩过)。
+  return renderPluginTemplate('abs.opencode.ts', { '@@MARK@@': MARK });
 }
 
 // ============================ Pi (TS extension) ============================
@@ -403,137 +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
-}
-
-/** 定位当前项目的 .brain/：只看 cwd 本身，不向上搜索（防爬到家目录图谱）。 */
-async function findBrain(cwd: string): Promise<string | null> {
-  const d = cwd || process.cwd()
-  try { const st = await stat(join(d, ".brain")); return st.isDirectory() ? join(d, ".brain") : null } catch { return null }
+  // 模板已外置到 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 }) {
@@ -542,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);
@@ -564,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} 移除`);
@@ -612,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} 移除`);
@@ -634,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" 续接。');
 }
 
@@ -658,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('选择要安装的智能体 (逗号分隔, 回车=全部):');

package/src/store.js

@@ -4,7 +4,7 @@ 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 { addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, moveBlocked, insertDoneGrouped, idOfTaskLine, archiveDoneInText, renderArchivePage, renderArchiveBody } from './todo.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';
 
@@ -402,7 +402,7 @@ export async function cmdLog({ dir, title, kind = 'dev' }) {
 // ---------- task: 登记/推进（幂等键 = 行首 id；hook 也调这个） ----------
 // 纪律: task 过程动作(start/done/note/blocked)只改 todo.md, 不写 log.md。
 // log.md 是「工作成果沉淀摘要」(用户/AI 主动 abs log "..." 记), 不收工具动作流水。
-export async function cmdTask({ dir, action, id, section, note }) {
+export async function cmdTask({ dir, action, id, section, note, as }) {
   const root = await requireBrain(dir || process.cwd());
   if (action === 'start') {
     const text = `${id}${note ? ' — ' + note : ''}`;
@@ -423,13 +423,17 @@ export async function cmdTask({ dir, action, id, section, note }) {
   }
   if (action === 'done') {
     // 找到匹配 id 的行，勾选并归位 Done（简化：若行在某 section 则标记完成）
-    const res = await markDone(brainPath(root, 'todo.md'), id);
+    // --as 结语：落地(默认) / 否决 / 仅方案 —— 让 [x] 可被信任（见 todo.js DONE_KINDS）
+    if (as && !DONE_KINDS.includes(as)) {
+      throw new Error(`✗ --as 只接受: ${DONE_KINDS.join(' | ')}（收到 "${as}"）`);
+    }
+    const res = await markDone(brainPath(root, 'todo.md'), id, as || '落地');
     return res;
   }
   throw new Error(`unknown task action: ${action}`);
 }
 
-async function markDone(file, id) {
+async function markDone(file, id, kind = '落地') {
   const res = await editFile(file, (text) => {
     const lines = text.split('\n');
     let changed = false;
@@ -440,7 +444,10 @@ async function markDone(file, id) {
       const l = lines[i];
       if (!moved && idOfTaskLine(l) === wantId) {
         changed = true;
-        const head = l.replace('- [ ]', '- [x]').replace(/\(认领[^)]*\)/, '') + ` (完成 ${today()})`;
+        const head = withDoneKind(
+          l.replace('- [ ]', '- [x]').replace(/\(认领[^)]*\)/, '') + ` (完成 ${today()})`,
+          kind,
+        );
         const bp = [];
         while (i + 1 < lines.length && lines[i + 1].trimStart().startsWith('↳')) bp.push(lines[++i]);
         moved = [head, ...bp];
@@ -454,7 +461,7 @@ async function markDone(file, id) {
   });
   return res === SKIP
     ? `(未找到含 "${id}" 的未完成任务行)`
-    : `✓ 已完成并归位 Done: ${id}`;
+    : `✓ 已完成并归位 Done: ${id} 【${kind}】`;
 }
 
 // ---------- show: 查看 index/todo/log（只读面） ----------
@@ -669,6 +676,20 @@ export async function cmdLint({ dir }) {
     if (doneLines > DONE_MAX) {
       issues.push(`DONE-PILED-UP: Done 区 ${doneLines} 行 > ${DONE_MAX}; 跑 \`abs todo archive\` 迁出旧日期组`);
     }
+
+    // 结语契约：Done 的 [x] 必须带【落地/否决/仅方案】。
+    // 为什么钉死: 无结语的 [x] 同时意味着"真做完了"和"只想过"，读的人无法区分。
+    // 实测翻车: 把"跑通后又被撤销"的 daemon 条当成已落地 → 得出错误结论。
+    // 只查 Done 区（含历史归档前的旧条目也算），不做自动改写（改记录属内容决策，不该由 lint 代劳）。
+    const doneBody = todoTxt.split('\n').slice(di + 1);
+    const noKind = doneBody.filter((l) => /^\s*- \[x\]/.test(l) && !doneKindOf(l));
+    if (noKind.length) {
+      const sample = (noKind[0].match(/- \[x\] (\S+)/) || [, '?'])[1];
+      issues.push(
+        `DONE-NO-KIND: Done 区 ${noKind.length} 条缺结语（如 ${sample}）。` +
+        `逐条补 \`--as 落地|否决|仅方案\`（新条目：abs todo done <id> --as …）`,
+      );
+    }
   }
 
   const n = issues.length;

package/src/todo.js

@@ -93,6 +93,28 @@ export function doneDateOf(line) {
   return m ? m[1] : '';
 }
 
+// ---------- Done 结语契约 ----------
+// 为什么需要: `[x]` 原本同时表示「真落地」「评估后不做」「仅设计过」三种完全不同的状态，
+// 读的人(下一个会话/未来的自己)无法区分。实测翻车: 读 daemon 条的 [x] 当成已落地，
+// 实际它跑通后被撤销、代码全删 —— 基于假记录得出「daemon 是过配项」的错误结论。
+// 结论: 图谱的价值取决于「可被信任」，一条状态失真的记录比一百条冗长记录的危害大一个量级。
+export const DONE_KINDS = ['落地', '否决', '仅方案'];
+
+/** 从 Done 任务行提取结语标记；无标记返回 ''。 */
+export function doneKindOf(line) {
+  const m = String(line).match(/【(落地|否决|仅方案)】/);
+  return m ? m[1] : '';
+}
+
+/** 追写结语到任务行：插在 `(完成 …)` 之前，幂等（已有则原位替换）。 */
+export function withDoneKind(line, kind) {
+  if (!kind) return line;
+  const base = String(line).replace(/【(落地|否决|仅方案)】/g, '').replace(/\s{2,}/g, ' ').trimEnd();
+  const i = base.lastIndexOf(' (完成 ');
+  if (i === -1) return `${base} 【${kind}】`;
+  return `${base.slice(0, i)} 【${kind}】${base.slice(i)}`;
+}
+
 /** 判断一行是否为任务行（- [x] / - [ ]，允许缩进）。 */
 function isTaskLine(l) {
   return /^\s*- \[[ x]\]/.test(l);