@fanchao8609/agent_brain_sync 1.8.8 → 1.9.0

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

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

package/src/index.js

@@ -26,13 +26,32 @@ export function brainPath(brainRoot, ...rel) {
   return join(brainRoot, BRAIN_DIR, ...rel);
 }
 
+/**
+ * 带错误码的错（CLI/MCP 同源）。
+ *
+ * 为何要码（2026-09-16 借 Anneal 的 templateRefusal）：
+ *   MCP 侧早就有 code（err(msg,{code,fallback})，5 种），CLI 侧全是自然语言句子。
+ *   于是 hook/脚本无法区分「该静默」与「该报警」——只能靠抓字符串，改文案就碎。
+ *   约定：所有可预期的失败都带 code；调用方按码分支，不看文案。
+ * 命名：大写下划线（与 MCP 侧一致）。
+ */
+export class AbsError extends Error {
+  constructor(code, message, fallback) {
+    super(message);
+    this.name = 'AbsError';
+    this.code = code;
+    this.fallback = fallback || null;
+  }
+}
+
 /** 断言 .brain/ 存在，否则抛错（宁可失败不落错项目）。 */
 export async function requireBrain(startDir) {
   const root = await findBrainRoot(startDir);
   if (!root) {
-    throw new Error(
-      `abs: 目录 ${resolve(startDir)} 下没有 .brain/ 图谱（不向上搜索）。\n` +
-      `  请在该目录运行: abs init`
+    throw new AbsError(
+      'NO_BRAIN',
+      `abs: 目录 ${resolve(startDir)} 下没有 .brain/ 图谱（不向上搜索）。`,
+      '请在该目录运行: abs init'
     );
   }
   return root;

package/src/relevant.js

@@ -0,0 +1,244 @@
+/**
+ * 相关页推荐：按"当前在干什么"挑出该读的知识页。
+ *
+ * 为何需要它（2026-09-16 实测）：
+ *   MCP 日志里 abs_task 234 / abs_note 54 / abs_load 53，而 abs_query 只有 2 次。
+ *   写入 288 : 检索 2 = 144:1。经验写进去了，几乎从没被读回来。
+ *
+ * 根因不是"忘了查"，是【给人看目录，人不会去翻书】：
+ *   load 只给 index 的一句话清单 → 模型觉得"我记过了" → 开工 → 真需要时靠印象。
+ *   模型不知道自己不知道什么，所以永远不会主动 query。
+ *
+ * 解法：不依赖主动查询 —— load 时【被动带出】相关页正文。
+ *   匹配依据是"当前在干什么"，不是"主题词"：
+ *     · 最近改过的源文件名      → 我现在在动哪个模块
+ *     · todo 里活跃任务         → 我现在在做什么事
+ *
+ * 为何不用 git：本项目 store.js 是纯文件操作，引 git 要处理
+ *   “没装 git / 不是 repo / 子进程 27ms”三种情况，为取几个文件名不值。
+ *   改用 mtime 扫最近改动 —— 信息量相同，零依赖。
+ *
+ * 与 query 的区别：
+ *   query 需要用户/模型先想到一个词；本模块不需要 —— 输入是环境事实。
+ */
+
+/** 中文/英文都按"够长才算有效词"处理，避免 the/的/了 这类噪音。 */
+const STOP = new Set([
+  'the', 'and', 'for', 'with', 'this', 'that', 'from', 'into', 'when', 'then',
+  'abs', 'src', 'test', 'js', 'ts', 'md', 'json', 'node',
+  '的', '了', '是', '在', '和', '与', '或', '把', '被', '给', '对', '从',
+]);
+
+/** 从任意文本抽关键词：英文词(>=3) + 中文 2-gram。 */
+export function keywords(text) {
+  const out = new Set();
+  const s = String(text || '');
+  // 英文/数字/下划线词
+  for (const m of s.matchAll(/[A-Za-z][A-Za-z0-9_-]{2,}/g)) {
+    const w = m[0].toLowerCase();
+    if (!STOP.has(w)) out.add(w);
+  }
+  // 中文串 → 2-gram（中文没有词边界，2-gram 是最省事的可匹配单位）
+  for (const m of s.matchAll(/[\u4e00-\u9fa5]{2,}/g)) {
+    const seg = m[0];
+    for (let i = 0; i + 2 <= seg.length; i++) {
+      const g = seg.slice(i, i + 2);
+      if (!STOP.has(g)) out.add(g);
+    }
+  }
+  return [...out];
+}
+
+/**
+ * 给一页打分：命中多少关键词（标题权重 3，正文权重 1）。
+ * 不做 TF-IDF —— 图谱就 30 页，朴素加权够用，也更好解释。
+ */
+export function scorePage(body, pageName, kws) {
+  const title = String(pageName).toLowerCase();
+  const text = String(body).toLowerCase();
+  let score = 0;
+  const hit = [];
+  for (const k of kws) {
+    const inTitle = title.includes(k);
+    const n = text.split(k).length - 1;
+    if (!inTitle && !n) continue;
+    score += (inTitle ? 3 : 0) + Math.min(n, 3);
+    hit.push(k);
+  }
+  return { score, hit };
+}
+
+/**
+ * 挑出 top-N 相关页。
+ * @param {{name:string,body:string}[]} pages
+ * @param {string[]} kws
+ * @param {number} n
+ */
+export function pickRelevant(pages, kws, n = 3) {
+  if (!kws.length) return [];
+  return pages
+    .map((p) => {
+      const { score, hit } = scorePage(p.body, p.name, kws);
+      return { ...p, score, hit };
+    })
+    .filter((p) => p.score > 0)
+    // 同分时按名字排，保证输出稳定（否则测试会抖）
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+    .slice(0, n);
+}
+
+/**
+ * 扫最近改过的源文件名（mtime 排序，不调 git）。
+ * 跳过 .brain/（那是图谱自己）、node_modules、隐藏目录。
+ */
+export async function recentFiles(root, { n = 8, days = 3 } = {}) {
+  const fs = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const cutoff = Date.now() - days * 86400_000;
+  const found = [];
+  const SKIP = new Set(['node_modules', '.git', '.brain', 'dist', 'build']);
+  async function walk(d, depth) {
+    if (depth > 3 || found.length > 400) return;
+    let ents;
+    try { ents = await fs.readdir(d, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (e.name.startsWith('.') || SKIP.has(e.name)) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) { await walk(p, depth + 1); continue; }
+      if (!/\.(js|ts|mjs|cjs|jsx|tsx|py|go|rs|sh)$/.test(e.name)) continue;
+      try {
+        const st = await fs.stat(p);
+        if (st.mtimeMs >= cutoff) found.push({ name: e.name, path: p.replace(root + '/', ''), mtime: st.mtimeMs });
+      } catch { /* 忽略不可读 */ }
+    }
+  }
+  await walk(root, 0);
+  return found.sort((a, b) => b.mtime - a.mtime).slice(0, n);
+}
+
+/**
+ * 两级匹配：
+ *   exact  = 查询词直接出现（子串）
+ *   fuzzy  = 查询词的 2-gram 有重叠（如查 "并发写" 能中写"互斥/锁"的页）
+ *
+ * 为何需要 fuzzy（2026-09-16 实测根因）：
+ *   原 cmdQuery 只做 body.includes(word) —— 查"并发写"时页里写的是"互斥"、
+ *   查"发布流程"时页名是 npm-publish-flow，全部匹配不上。
+ *   用户看到"无命中"会以为图谱里没这条经验（静默失效）。
+ */
+export function matchPage(body, pageName, queryWords) {
+  const text = String(body).toLowerCase();
+  const name = String(pageName).toLowerCase();
+  const exact = [];
+  for (const w of queryWords) {
+    const q = w.toLowerCase();
+    if (text.includes(q) || name.includes(q)) exact.push(w);
+  }
+  // 模糊：拿查询词的字符 2-gram 去页里找，重叠度足够就算关联
+  // 坑(2026-09-16 实测): 曾用 overlap/qGrams.size >= 0.5 —— 太松。
+  //   查"zzzz不存在"时 qGrams={zz,不存,存在}, 页里恰好有"存在" → ratio=0.5 误命中。
+  //   两个修正: (1) 重复字符的 gram 不算(zz 去重); (2) 至少得命中 2 个不同 gram。
+  const qGrams = new Set(queryWords.flatMap((w) => ngrams(String(w).toLowerCase())));
+  const pGrams = new Set(ngrams(text.slice(0, 4000)).concat(ngrams(name)));
+  let overlap = 0;
+  for (const g of qGrams) if (pGrams.has(g)) overlap++;
+  const ratio = qGrams.size ? overlap / qGrams.size : 0;
+  return { exact, overlap, ratio };
+}
+
+/** 拆字符 2-gram（中英文都适用）—— 模糊匹配的最小单位。
+ *  先过 [\p{L}\p{N}] 再切，单一字符组成的 gram(如 zz) 没区分度，丢掉。 */
+function ngrams(s) {
+  const out = [];
+  const clean = s.replace(/[^\p{L}\p{N}]+/gu, '');
+  for (let i = 0; i + 2 <= clean.length; i++) {
+    const g = clean.slice(i, i + 2);
+    if (g[0] === g[1]) continue; // zz / 11 这类无信息量
+    out.push(g);
+  }
+  return out;
+}
+
+/** 模糊门槛 + 最小 gram 数（见 rankPage 注释） */
+export const FUZZY_MIN = 0.6;
+// 查询词去重后的 gram 数必须≥4：否则 "zzzz不存在" 只剩 [不存,存在] 两个 gram，
+// 两个都在任意中文页里 → ratio=100% 误命中（实测）。分母够大才拉得动比例。
+export const FUZZY_MIN_GRAMS = 4;
+
+/** 从 frontmatter 取 tags 列表。无 frontmatter / 无 tags → []。 */
+export function tagsOf(body) {
+  const m = String(body || '').match(/^tags:\s*(.+)$/m);
+  if (!m) return [];
+  return m[1]
+    .replace(/^\[|\]$/g, '')
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+/**
+ * 端到端检索：把一组查询词打成一页的分数。
+ * 返回 null = 不相关（既不精确命中，模糊重叠也不够）。
+ *
+ * 权重（tags 最高，2026-09-16 用户定）：
+ *   tags 命中  —— 人工提炼的关键词，最可靠  → 权重 8/个
+ *   标题命中  —— 页名往往就是主题          → 权重 4/个
+ *   正文命中  —— 可能出现但可能只是提一句  → 权重 1/个（封顶 3）
+ *
+ * 为何 tags 优先：实测现有页的 tags 写着大量人工词组（"静默失效"、
+ *   "双副本"、"陈旧路径"），而 firstHitLine 一直把 tags 行当噪音跳过 ——
+ *   等于把最准的检索信号丢掉了。
+ */
+export function rankPage(body, pageName, queryWords) {
+  const { exact, overlap, ratio } = matchPage(body, pageName, queryWords);
+  if (exact.length) {
+    const tags = tagsOf(body).map((t) => t.toLowerCase());
+    const name = String(pageName).toLowerCase();
+    const text = String(body).toLowerCase();
+    let score = 10 + exact.length * 5;
+    const via = { tag: [], title: [], body: [] };
+    for (const w of exact) {
+      const q = String(w).toLowerCase();
+      if (tags.some((t) => t === q || t.includes(q) || q.includes(t))) {
+        score += 8; via.tag.push(w);
+      } else if (name.includes(q)) {
+        score += 4; via.title.push(w);
+      } else if (text.includes(q)) {
+        score += 1; via.body.push(w);
+      }
+    }
+    return { kind: 'exact', matched: exact, score, overlap, ratio, via };
+  }
+  const qGramCount = new Set(queryWords.flatMap((w) => ngrams(String(w).toLowerCase()))).size;
+  if (qGramCount >= FUZZY_MIN_GRAMS && ratio >= FUZZY_MIN)
+    return { kind: 'fuzzy', matched: [], score: ratio * 10, overlap, ratio, via: { tag: [], title: [], body: [] } };
+  return null;
+}
+
+/** 取页正文的摘要：优先 frontmatter 的 description，退化到首个非标题行。 */
+export function digest(body, maxLen = 200) {
+  const lines = String(body || '').split('\n');
+  const fmEnd = lines[0] === '---' ? lines.indexOf('---', 1) : -1;
+  if (fmEnd > 0) {
+    const d = lines.slice(1, fmEnd).find((l) => /^description\s*:/.test(l));
+    if (d) return d.replace(/^description\s*:\s*/, '').trim().slice(0, maxLen);
+  }
+  // 无 description 时跳过整个 frontmatter 区 —— 否则会把 'title: X' 当正文。
+  const start = fmEnd > 0 ? fmEnd + 1 : 0;
+  const first = lines
+    .slice(start)
+    .find((l) => l.trim() && !l.startsWith('#') && !l.startsWith('---'));
+  return (first || '').trim().slice(0, maxLen);
+}
+
+/** 渲染"该读的页"段。无命中返回空串（不占 load 体积）。 */
+export function renderRelevant(picked, why = '') {
+  if (!picked.length) return '';
+  const out = [`--- 相关页（据当前改动/任务自动带出）${why ? ` [${why}]` : ''} ---`];
+  for (const p of picked) {
+    out.push(`[[${p.name}]] (${p.score}) — ${digest(p.body)}`);
+    out.push(`  命中: ${p.hit.slice(0, 8).join(' ')}`);
+  }
+  out.push('（这些页与你当前在做的事相关；不必再 query）');
+  return out.join('\n');
+}