@fanchao8609/agent_brain_sync 1.5.5 → 1.5.7

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.7",
   "description": "agent-brain-sync: 跨会话 AI 编码记忆 — hook 纯触发 + CLI/MCP 读写 .brain markdown 图谱, 防并发写保护。",
   "type": "module",
   "license": "MIT",