@fanchao8609/agent_brain_sync 1.8.1 → 1.8.3

package/README.md

@@ -32,7 +32,11 @@ abs install --agent pi --no-mcp   # 只装 hook + skill，不要 MCP
 | claude-code | `~/.claude/settings.json` hooks | `mcpServers.abs` (stdio) | `~/.claude/skills/abs-agent-brain-sync/` |
 | codex | `~/.codex/hooks.json` | config.toml `[mcp_servers.abs]` | `~/.codex/skills/` |
 | opencode | `~/.config/opencode/plugins/abs.ts` | opencode.json mcp.abs | skills/ |
-| pi | `~/.pi/agent/extensions/abs.ts` | extension 内桥接 | skills/ |
+| pi | `~/.pi/agent/extensions/abs.ts` | `~/.pi/agent/mcp.json` `mcpServers.abs` | `~/.pi/agent/skills/` |
+
+> **skill 规则**：`skill/` 下每个含 `SKILL.md` 的子目录 = 一个 skill，
+> **目录名即安装名**（须与 frontmatter `name` 一致，否则 pi 会告警）。
+> 新增 skill 只需建目录，无需改代码。
 
 - **幂等**：重复安装 = 更新，写入前自动备份
 - **共存**：追加式合并，不会顶掉你这个事件上的其它 hook
@@ -110,7 +114,7 @@ npm i -g @fanchao8609/agent_brain_sync@latest
 abs install    # 重新刷 hook/skill
 ```
 
-> ⚠️ 改完源码（尤其 `skill/SKILL.md`、`src/`）后**必须 `abs install --yes` 重扇出**，否则宿主还在跑旧副本 —— 版本号与代码会脱节。发布用 `npm version patch`（自动打 tag），别手改 `package.json` 的 version；发布后 `npm view` 有缓存延迟，必要时 `npm cache clean --force` 再验。
+> ⚠️ 改完源码（尤其 `skill/*/SKILL.md`、`src/`）后**必须 `abs install --yes` 重扇出**，否则宿主还在跑旧副本 —— 版本号与代码会脱节。发布用 `npm version patch`（自动打 tag），别手改 `package.json` 的 version；发布后 `npm view` 有缓存延迟，必要时 `npm cache clean --force` 再验。
 
 ---
 
@@ -150,7 +154,7 @@ agent_brain_sync/
 ├── src/userconfig.js  使用者姓名配置（作者标记）
 ├── src/wrapup.js   Stop 收尾快照/归档
 ├── hooks/event.sh  hook 模板
-├── skill/SKILL.md  技能（装到各智能体）
+├── skill/<名称>/SKILL.md  技能（每个子目录 = 一个 skill，装到各智能体）
 └── test/           单测
 ```
 

package/package.json

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

package/skill/{SKILL.md → abs-agent-brain-sync/SKILL.md}

@@ -1,6 +1,6 @@
 ---
 name: abs-agent-brain-sync
-description: abs (agent-brain-sync) 跨会话 AI 编码记忆与任务续接。开场续接状态(abs load/MCP abs_load)，干活中任务/经验实时落盘(abs_task/abs_note)，每轮结束走收尾循环(读todo→判未登记→沉淀→更新index/log)。解决会话无状态：经验/进度/坑碎片化、重开失忆。
+description: abs (agent-brain-sync) 跨会话 AI 编码记忆与任务续接。开场续接状态(abs load/MCP abs_load)，干活中任务/经验实时落盘(abs_task/abs_note)，每轮结束走收尾循环(读todo→判未登记→沉淀→更新index/log)。解决会话无状态：经验/进度/坑碎片化、重开失忆。遇 bug 排查时配合挂载 bug-hunter skill。
 ---
 
 # abs — 跨会话记忆 (agent-brain-sync)
@@ -313,3 +313,6 @@ abs supersede <页名> --by <取代它的新页>   # 不写 --by 也行 = 单纯
 - 只读写 `.brain/` 与目标代码，不动全局配置（一次性接入除外）。
 - 只写真实发生的事实；遵守容量纪律，宁缺毋滥。
 - 双链/frontmatter/index 必须自洽 —— 坏链 = 掰断接力棒。
+- **排查 bug 时挂载 `bug-hunter` skill**（随 abs 一并安装，在 `skills/bug-hunter/`）：
+  完整排查流程（列假设 → 复现 → 定位改动 → 打印 → 顺藤摸瓜 → 根因 → 验证）
+  与「给结论要明确」都在那份里。**排查方法不写在本文件**（两份维护必漂）。

package/skill/abs-bug-hunter/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: abs-bug-hunter
+description: 按流程论排查 bug，先定位改动 → 日志打印 → 顺藤摸瓜逐层排查
+---
+
+# Bug 排查方法论
+
+## 核心原则
+
+**Bug 多数由新增或修改的功能引起。不凭空猜测，用数据说话。但数据不是终点——先复现，再定位，再理解根因。**
+
+常见的失败模式是把"能复现的问题"当成"已定位的 bug"，跳过理解直接下结论。定位到错误位置 ≠ 找到根因。改对症状而不改根因，换一批数据又会复发。
+
+## 排查流程
+
+### 第 -1 步：列假设 —— 方向错了怎么办（不能跳过）
+
+**触发**：用户报了症状（“打不开”“报错了”“不对”），但没给一手错误信息。
+
+**最大坑（真实案例）**：只有一个假设时，它要么被证实要么思路断掉 —— 于是**自己造一个输入**去测：
+编了个接口名 `app.init` → curl 测出 404 → “我测出来的，是事实” → 推出“nginx 没配 PATH_INFO”
+→ 用户纠正后**重跑同一实验、得到同一 404** → 坚信自己没错。
+
+> 假证据最毒之处：**下游全程都是真的**（404 真、命令真跑过）。唯一假的那环
+> （输入名）在最上游，且已消失在过程里 → 所以“再验证一次”救不了，
+> 他会重跑同假输入得同真输出。
+> 下面第 0 步“先复现”在拿不到报错时反而会逼出造假 —— 所以本步在它之前。
+
+1. **开局列 ≥2 个假设**（代码层 / 配置层 / 构建产物 / 缓存 / 第三方后台）。
+   只列一个 = 逼自己去证实它 = 造证据的动力。
+2. **每个假设配反证条件**：什么现象出现就认它错。
+   > 例：“假设 nginx 没配 PATH_INFO；反证条件：用**从代码里读到的真实接口名**
+   > 测出也是 404 → 接口本身不存在，与 nginx 无关 → 弃此假设。”
+   > 反证条件里写明“真实接口名”，`app.init` 这种编造的就自动不能用了。
+3. **卡住两轮就换假设**，不是在同一假设上加细节。
+4. **领域外的先声明无取证能力**（构建产物在不在 / 缓存 / 微信等第三方后台行为），
+   要用户提供事实，**不要脑补**。
+
+**结论所依据的每个具体名字（接口/字段/报错文本/路径）必须指得出处（文件:行）。**
+指不出的，只能标“推测”二字，**不得当证据用**。
+
+> **为什么多假设能防造假**：单假设必须被证实，否则思路断 → 有动机造。
+> 多假设下，“支持了 A” 不等于 “就是 A”（B/C/D 还没排除）→ **假证据推不出结论，造它就没意义了**。
+
+### 第 0 步：复现 — 先让 Bug 稳定出现
+
+没有稳定复现，后面全是猜。先确定：
+- 复现的必要条件是什么？哪个输入/操作/环境触发？
+- 是 100% 复现，还是偶发？偶发问题先找触发模式（特定数据、特定时机、特定顺序）。
+- 日志里有没有现成的错误栈？错误信息 + 行号是最便宜的定位入口。
+
+**给 Bug 起个名字**（一句话描述 + 触发条件）。排查卡住时，回去核对是否还在同一个 Bug 上。
+
+### 第一步：定位范围 — 改动了什么
+
+Bug 不会凭空出现。先查最近的代码改动：
+
+```bash
+git diff HEAD~3 --stat          # 看改了哪些文件
+git log --oneline -5            # 看最近提交
+git diff <commit> -- <file>     # 看具体改了什么
+git log -p -S '可疑字段/函数名'  # 谁改过这段代码
+git blame <file> -L <行号,行号>  # 定位到具体某行是谁写的
+```
+
+问自己：
+- 这次新增/修改了什么功能？
+- 改动涉及哪些文件？
+- 哪个改动最可能影响到出问题的地方？
+
+**不要排查无关代码，把精力集中在改动范围。**
+
+### 第二步：日志打印 — 让数据说话
+
+不要猜，打印出来看。根据技术栈选择打印方式：
+
+| 技术栈 | 打印方式 | 日志位置 |
+|--------|----------|----------|
+| PHP (ThinkPHP) | `\think\Log::error($data)` 或 `trace($data)` | `runtime/log/` |
+| PHP (Laravel) | `Log::info($data)` 或 `logger($data)` | `storage/logs/` |
+| Vue / JS | `console.log(data)` | 浏览器控制台 |
+| Node.js | `console.log(data)` 或 `logger.debug(data)` | 终端 / 日志文件 |
+| SQL | `\think\Db::getLastSql()` 或开启 SQL 日志 | runtime/log 或控制台 |
+
+**打印要打印关键数据，不要只打印 "到了这里"，要打印实际的变量值。**
+
+```php
+// ❌ 没用
+\Log::error('进入方法');
+
+// ✅ 有用 — 打印入参、中间态、出参
+\Log::error('goods detail', ['id' => $id, 'goods' => $goods, 'type' => gettype($goods)]);
+```
+
+**二分法打印**：在可疑链路上隔几层就插一个日志点，先跑一遍看哪段有数据、哪段没数据，把范围砍半，再往里面加日志。比一次打满所有层更快收敛。
+
+**加分技巧**：
+- 给每个日志点带唯一前缀（如 `[BUG-01]`、`[BUG-02]`），日志里 grep 一次就能看到全链路顺序。
+- 打印耗时和调用来源：怀疑并发/时序时，打上时间戳与 `debug_backtrace()` 或请求 ID。
+
+### 第三步：顺藤摸瓜 — 按调用链逐层排查
+
+从用户操作出发，沿着调用链一层层往下查：
+
+```
+用户操作（点击/请求）
+  → 路由（routes / pages.json / url）
+    → 门面/中间件（facade / middleware）
+      → 控制器（controller）
+        → 服务层（service）
+          → 模型（model）
+            → 数据库（SQL）
+```
+
+每一层都打印关键数据，确认数据在哪一层开始出错：
+
+```php
+// 控制器 — 打印接收到的参数
+\Log::error('controller input', ['params' => $params]);
+
+// 服务层 — 打印处理中的数据
+\Log::error('service process', ['data' => $data, 'result' => $result]);
+
+// 模型 — 打印查询结果
+\Log::error('model query', ['sql' => $this->getLastSql(), 'result' => $result]);
+```
+
+**找到数据从正确变为错误的那一层，bug 就在那一层。**
+
+### 第四步：找到根因，不只修症状
+
+改对症状 = 换一批数据又复发。修复前回答：
+- 为什么数据在这一层变错了？是**逻辑错误**（判断写反/字段取错），**类型错误**（null/数组/对象混用），还是**数据本身脏**（上游写入时就错了）？
+- 根因若在上游（写入方/历史数据），这里 patch 只是挡一下，应该去修上游或在入口统一兜底。
+
+**修一层，不改所有调用点**：如果多个地方都调用同一函数，只在出问题的那个调用点打补丁，其他调用点照样坏。在共享函数里修一次，是所有调用点的最小修复。
+
+### 第五步：验证修复 — 逐行打印确认
+
+修复 bug 后，不要凭空验证。**先拿第 0 步的复现条件重跑**，确认错误消失、结果正确，再用打印验证每一步符合预期：
+
+```php
+// 修复后验证
+\Log::error('step1: fetch', ['data' => $data]);
+$data = transform($data);
+\Log::error('step2: transform', ['data' => $data]);
+$result = save($data);
+\Log::error('step3: save', ['result' => $result]);
+```
+
+验证包括三层：
+- **修好了**：复现路径不再报错，输出正确。
+- **没修坏**：相关正常路径仍正常（回归）。
+- **边界还在**：尝试边缘输入（空值、超大值、并发、重复提交），确认修复没引入新洞。
+
+确认无误后，再删除调试日志。
+
+## 实战示例
+
+**场景：** 商品详情页报 `Call to a member function toArray() on array`
+
+**第 0 步：复现**
+- 访问 `/shopro/goods/goods/detail/id/31` 稳定复现
+- 日志：`[error] 致命错误: Call to a member function toArray() on array [/var/www/html/.../GoodsMemberPrice.php:50]`
+
+**第一步：定位范围**
+- 最近新增了会员系统，改了 Goods 控制器和新增了 GoodsMemberPrice 模型
+- 怀疑新增代码有问题
+
+**第二步：查看日志**
+- 日志直接告诉出错文件和行号
+
+**第三步：顺藤摸瓜**
+- 路由：`/shopro/goods/goods/detail/id/31`
+- 控制器：`Goods::detail()` → 调用了 `GoodsMemberPriceModel::getByGoods()`
+- 模型：`getByGoods()` 第50行 `select()->toArray()` → `select()` 返回数组，不是 Collection
+
+**第四步：找根因**
+- 为什么 id=31 出错而别的正常？查数据：31 这件商品有会员价记录 → 触发 `select()` 返回多行场景。可能是 `find()`/`select()` 返回值混用的历史问题。若只是个别记录脏，应清理数据或给方法加统一返回类型。
+
+**第五步：修复验证**
+```php
+// 修复前
+return self::where('goods_id', $goodsId)->select()->toArray();
+
+// 修复后
+$result = self::where('goods_id', $goodsId)->select();
+return $result instanceof \think\Collection ? $result->toArray() : (array)$result;
+```
+- 重跑 id=31（不再报错）+ 跑一个无会员价记录的 id（确认没回归）
+
+## 常见陷阱
+
+| 陷阱 | 正确做法 |
+|------|----------|
+| 凭经验猜测 bug 位置 | 先复现 + 看日志/打印，用数据定位 |
+| 只看代码不运行 | 打印实际运行时的数据 |
+| 一次改很多地方再测试 | 改一处、验证一处 |
+| 修症状不修根因 | 追问"为什么这层数据变了"，确认根因 |
+| 只验证出错的路径 | 重跑复现 + 回归正常路径 + 边界输入 |
+| 忘记删除调试代码 | 修复确认后清理所有 `console.log` / `\Log::error` |
+| 只在本地验证 | 确认服务器代码是否同步部署，数据是否一致 |
+| 排查卡住还硬扛 | 回去核对第 0 步的 Bug 描述，确认是否在同一个问题上；必要时换数据/换触发角度重看 |
+| 偶发当成必然 | 偶发先找触发模式，别用单个样本下结论 |
+
+## 兜底：卡住时做什么
+
+排查 >20 分钟没进展，不硬扛，回到流程检查：
+1. **Bug 描述还准吗？** 是否有新的观察改变了问题定义。
+2. **复现还稳定吗？** 换一个触发样本还出现吗。
+3. **有没有漏看的日志？** grep 全量日志（不只最近的），可能早期就报过错。
+4. **改动范围查全了吗？** 只看 HEAD~3 可能漏了分支合并、配置文件、部署差异。
+5. **要不要跟同事确认？** 这条功能最近谁改的、改动意图是什么，可能一句话点醒。
+6. **向上游看一层。** 数据/配置来源方是否也变了，不只是消费方的问题。
+
+## 收尾：给结论要明确，不要模糊
+
+**不许**："可能是 X，也可能是 Y，建议排查一下" —— 这是把判断推回给用户。
+
+**必须**：明确给出
+1. **当前结论**（是什么 / 或者"未定位"）
+2. **置信度与依据**（哪来的证据 / 还是只是推测）
+3. **下一步具体动作**（跑什么命令、看什么输出、要用户提供什么）
+
+"未定位"是合法输出，但必须配一句"**需要你提供 X**"（具体到要什么都），
+不能只说"无法确定"就结束。
+
+> 与第 -1 步同一根因：模糊化是逃避判断。要么给结论 + 依据，要么明确索取证据。

package/src/install.js

@@ -14,7 +14,63 @@ import { HOSTS, hostByKey } from './hosts.js';
 
 const ABS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const HOOK_TEMPLATE = join(ABS_DIR, 'hooks', 'event.sh');
-const SKILL_SOURCE = join(ABS_DIR, 'skill', 'SKILL.md');
+
+// ---- skill 包规则（单一规则，无特例）----
+// skill/ 下**每个含 SKILL.md 的子目录**就是一个 skill，随包发布。
+// 目录名 = 宿主 skills/ 下的安装目录名 = frontmatter 的 name（三者必须一致：
+// pi 在目录名与 name 不一致时会告警）。
+//
+// 为什么全带 abs- 前缀:
+//   1. 归属可辨 —— 带前缀才敢判「这是 abs 装的、可随 install 更新/卸载」；
+//      不带前缀的副本可能是用户自己放的，卸载时不敢动。
+//   2. 避开同名冲突 —— pi 同时扫 ~/.pi/agent/skills 与 ~/.agents/skills
+//      （pi 文档 Locations 一节），后者常有同名副本。两份同名实文件 → pi 报
+//      skill 冲突（实测: 曾装成 bug-hunter，与 ~/.agents/skills/bug-hunter 相撞）。
+//
+// 新增 skill: 建 skill/<名称>/SKILL.md 即可，无需改代码（原先写死一条，见旧注释 ponytail）。
+const SKILL_ROOT = join(ABS_DIR, 'skill');
+const ALL_SKILLS = (() => {
+  const out = [];
+  let entries = [];
+  try { entries = fsSync.readdirSync(SKILL_ROOT, { withFileTypes: true }); } catch { /* 无 skill/ 目录: 无 skill 可装 */ }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const src = join(SKILL_ROOT, e.name, 'SKILL.md');
+    if (!fsSync.existsSync(src)) continue; // 只认含 SKILL.md 的子目录
+    out.push({ name: e.name, src });
+  }
+  return out;
+})();
+// 主 skill（会话开场加载的那个）。它也只是 ALL_SKILLS 的一员，此处仅用于告警比对。
+const SKILL_SOURCE = join(SKILL_ROOT, 'abs-agent-brain-sync', 'SKILL.md');
+
+/** 安装全部 skill 到该宿主。收口在此：四处安装点共用 —— 新增 skill 只改
+ *  skill/ 目录，本函数与调用方都不动（避免「改一份不算改」）。返回步骤行。 */
+async function installSkills(agentKey) {
+  const steps = [];
+  const root = join(hostSkillDir(agentKey), '..');
+  for (const s of ALL_SKILLS) {
+    const t = join(root, s.name, 'SKILL.md');
+    await atomicWrite(t, await fs.readFile(s.src, 'utf8'));
+    steps.push(`✓ skill  → ${t}`);
+  }
+  return steps;
+}
+
+/** 卸载该宿主的全部 skill（主 + 附带）。与 installSkills 同源同规则。
+ *  曾经的坑: 只有 claude-code 删了附带 skill，其余三宿主留下 abs-bug-hunter/ 残留。
+ */
+async function uninstallSkills(agentKey) {
+  const steps = [];
+  const root = join(hostSkillDir(agentKey), '..');
+  for (const s of ALL_SKILLS) {
+    const d = join(root, s.name);
+    await fs.rm(d, { recursive: true, force: true });
+    steps.push(`✓ skill 已删除 → ${d}`);
+  }
+  return steps;
+}
+
 
 /**
  * 本包的稳定入口路径解析（mcp.js / abs.js 通用）。
@@ -455,9 +511,7 @@ async function installClaudeCode({ withMcp, withSkill, log }) {
 
   // 3) skill → <configRoot>/skills/abs-agent-brain-sync/SKILL.md (config 根 = CLAUDE_CONFIG_DIR)
   if (withSkill) {
-    const target = join(hostSkillDir('claude-code'), 'SKILL.md');
-    await atomicWrite(target, await fs.readFile(SKILL_SOURCE, 'utf8'));
-    steps.push(`✓ skill  → ${target}`);
+    steps.push(...await installSkills('claude-code'));
   }
   return steps;
 }
@@ -492,9 +546,7 @@ async function uninstallClaudeCode() {
   await fs.rm(join(homedir(), '.abs', 'hooks', 'claude-code'), { recursive: true, force: true });
   steps.push(`✓ ~/.abs/hooks/claude-code/ (本 agent hook 脚本) 已删除`);
   // skill
-  const skillDir = hostSkillDir('claude-code');
-  await fs.rm(skillDir, { recursive: true, force: true });
-  steps.push(`✓ skill 已删除`);
+  steps.push(...await uninstallSkills('claude-code'));
   return steps;
 }
 
@@ -574,9 +626,7 @@ async function installCodex({ withMcp, withSkill, log }) {
     }
   }
   if (withSkill) {
-    const target = join(hostSkillDir('codex'), 'SKILL.md');
-    await atomicWrite(target, await fs.readFile(SKILL_SOURCE, 'utf8'));
-    steps.push(`✓ skill  → ${target}`);
+    steps.push(...await installSkills('codex'));
   }
   return steps;
 }
@@ -621,8 +671,7 @@ async function uninstallCodex() {
       steps.push(`✓ MCP 已从 ${mcpP} 移除`);
     }
   } catch {}
-  await fs.rm(hostSkillDir('codex'), { recursive: true, force: true });
-  steps.push(`✓ skill 已删除`);
+  steps.push(...await uninstallSkills('codex'));
   return steps;
 }
 
@@ -726,9 +775,7 @@ async function installOpenCode({ withMcp, withSkill, log }) {
     steps.push(`✓ MCP → ${mcpP} (mcp.abs local)`);
   }
   if (withSkill) {
-    const target = join(hostSkillDir('opencode'), 'SKILL.md');
-    await atomicWrite(target, await fs.readFile(SKILL_SOURCE, 'utf8'));
-    steps.push(`✓ skill → ${target}`);
+    steps.push(...await installSkills('opencode'));
   }
   return steps;
 }
@@ -751,8 +798,7 @@ async function uninstallOpenCode() {
     await atomicWrite(mcpP, JSON.stringify(cfg, null, 2));
     steps.push(`✓ MCP 已从 ${mcpP} 移除`);
   }
-  await fs.rm(hostSkillDir('opencode'), { recursive: true, force: true });
-  steps.push(`✓ skill 已删除`);
+  steps.push(...await uninstallSkills('opencode'));
   return steps;
 }
 
@@ -775,9 +821,7 @@ async function installPi({ withMcp, withSkill, log }) {
     steps.push(`✓ MCP    → ${mcpP} (mcpServers.abs, stdio)`);
   }
   if (withSkill) {
-    const target = join(hostSkillDir('pi'), 'SKILL.md');
-    await atomicWrite(target, await fs.readFile(SKILL_SOURCE, 'utf8'));
-    steps.push(`✓ skill → ${target}`);
+    steps.push(...await installSkills('pi'));
   }
   return steps;
 }
@@ -786,8 +830,7 @@ async function uninstallPi() {
   const steps = [];
   await fs.rm(join(hostConfigRoot('pi'), 'agent', 'extensions', 'abs.ts'), { force: true });
   steps.push(`✓ extension 已删除`);
-  await fs.rm(hostSkillDir('pi'), { recursive: true, force: true });
-  steps.push(`✓ skill 已删除`);
+  steps.push(...await uninstallSkills('pi'));
   const mcpP = join(hostConfigRoot('pi'), 'agent', 'mcp.json');
   const cfg = await readJson(mcpP, { strict: false });
   if (cfg === null) {