索引查询（index-lookup）

概述

目的：让消费方（code-review / debug / product-manager / expert-team / code-survey …）用一次读表拿到"这段代码该查哪个索引、是否新鲜、接下来查哪张表"，把"选前端还是后端索引"从判断变成确定性的路径匹配。

功能（纯文档 skill：本 skill 没有脚本，"判定"= 按下面的工作流读登记表）：

• 登记表驱动：读 .fe-index/INDEX.md（唯一事实源，前端 + 后端各一行）→ 拿代码路径与各行「根目录」做最长前缀匹配 → 得到查哪端、哪个 slug
• 新鲜度粗判：比对条目 meta.json 的 commit 与该仓库 HEAD；不一致不代表过期 → 指向该端 provider 的 --check 做精确判定
• 查询入口路由：按类型指出查哪张表（前端 apis/ pages/；后端 tables.md modules/）
• 缺失即降级：无登记表 / 路径未命中 / git 不可用 → 明确告知并回退原流程（grep / 读码），不阻塞、不臆造

使用场景：

• 接到改动任务（review / debug / 影响分析）时，先确认"要不要查索引、查哪个"——不要先猜
• 新会话接手仓库，想知道"这个仓库有没有索引、覆盖哪些范围、是否新鲜"
• 用户问"改这个接口影响哪些页面"、"改这张表影响哪些模块"（← 本 skill 路由，查表在 provider 产物里）

---

定位

邻接能力	它做什么	本 skill 做什么
frontend-index / backend-index	provider：建库 / 校验 / 查询自己那一端（产物格式、退出码、查询口径的 SSOT）	消费侧门面：只做"选哪个 + 指向查询入口"；查询口径一律引用 provider 文档，不复制
expert-lookup / solution-lookup / ki-memory-lookup	资产复用家族（专家包 / 方案 / 记忆）	同一模式的代码结构层门面
grep / LSP	随机访问（搜到什么算什么）	索引 = 穷举反查的缓存（被依赖 / 表反查 / 接口反查）；本 skill 负责把"要不要用这个缓存"判明白

---

核心原则

1. 登记表是唯一事实源：所有应用都在 .fe-index/INDEX.md 里（前端 + 后端各一行）；"选哪个"= 路径最长前缀匹配，不靠猜、不靠调用方各自实现
2. 新鲜度不擅下结论：只比对 meta.commit 与 HEAD；不一致不代表过期（可能只是范围外提交）→ 说"需 --check 确认"并指向该端命令；精确判定归 provider（带 scope 的 diff）
3. 缺失即降级：无登记表 / 路径未命中 / git 不可用 → 明确告知 + 回退原流程，绝不臆造结论
4. 口径不复制：查询入口、退出码、产物结构由两个 provider 的文档维护；本 skill 只回答"去哪张表"

---

工作流

四步，全部是读文档，不跑任何脚本（唯一该跑的是第 3 步里的 provider --check——它需要 git 做范围 diff）：

1. 找登记表：{项目根}/.fe-index/INDEX.md——项目根 = git rev-parse --show-toplevel（非 git 仓库则逐级向上找 .git）；落点约定固定在这里，不是应用子目录。找不到再向上 ≤3 层兜底（兼容旧布局）
2. 选条目：拿"要改的路径"与表里每行的「根目录」做最长前缀匹配 → 得到 类型（frontend / backend）与 slug
   • 相对根目录的基准 = .fe-index/ 的上一级（即仓库根）——该口径由两个 provider 的登记表规范维护，此处仅为消费方的读数提示
   • 多个路径（review 的 diff 常有几十个文件）：逐个匹配即可；同一端命中多条时选前缀最长的那条
3. 看新鲜度：读该条目 meta.json 的 commit，与 git rev-parse HEAD 比——不同不代表过期（可能只是范围外提交）→ 有疑问就跑该端 provider 的 --check 定论
4. 查表：按类型读对应产物（后端 tables.md / modules/*.md；前端 apis/*.md / pages/*.md）

命中之后（按 kind 走两条路，细节见 provider 文档）

kind	校验（必做）	查什么	典型问题
frontend	scan_frontend.py --check --index …	apis/*.md → 页面（接口反查）｜pages/*.md → 接口 / 依赖组件	改这个接口影响哪些页面
backend	scan_backend.py --check --index …	tables.md → 模块（表反查）｜modules/*.md → 被依赖 / 事件命令耦合	改这张表影响哪些模块

跨端问题（两端索引都在册时）

"后端改接口 → 前端哪些页面在用"： 后端 index.md 的「模块 → 挂载前缀」 × 前端 apis/*.md 的接口路径（前缀包含匹配，@Controller() 无前缀的模块用「方法路径」提示）——口径见 backend-index/SKILL.md 的「被其它 skill 集成」。

降级链（按序执行，绝不硬撑）

1. 无登记表 → grep / 读码按原流程；若这类问题会反复出现，再决定建索引
2. 命中但 --check 报过期（退出码 6） → 先问用户是否重建（一条命令）；不重建则读表时明确说明"基于旧 commit"
3. 路径未命中 → 该仓库确实没覆盖这段代码（范围外）→ 扩大 --include 重建，或直接 grep

---

反模式

• ❌ 不看登记表就断言"这个仓库没索引"：.fe-index/ 是隐藏目录，必须读 INDEX.md（含向上 ≤3 层）
• ❌ 拿"commit 不一致"直接说过期：范围外提交也会不一致 → 以 provider 的 --check 为准
• ❌ 把本 skill 当查询器：它只负责"选哪端 + 指向入口"；真正的查表在 provider 产物里
• ❌ 索引命中就不读代码：索引给"去哪看"，最终结论仍要回源码——provider 文档同样要求
• ❌ 在消费方（review/debug 等）里复制"选哪端"的逻辑：会让口径漂移 → 统一调本 skill

---

行为边界

• 只读、无脚本：不改索引、不改代码、不产生产物（建库与校验都由 provider 完成）
• 只认 .fe-index/（向上 ≤3 层查找，与 provider 同口径）；索引放在自定义位置时按同一约定人工确认
• 不做语义判断（不知道"这次改动是否只影响某页面"），只做路径 → 条目匹配
• 不替代 provider 的 --check：commit 粗判 ≠ 精确判定

---

集成（消费方清单 · SSOT）

消费方	接入点	用法
code-review / bug-impact-analysis	拿到 diff 后、判影响面前	读 INDEX.md 匹配改动文件 → 按类型查被依赖 / 表反查 / 页面反查
debug	定位根因前	用索引缩小搜索域（模块 / 页面），再在命中范围内读码
product-manager	M2 体验走查 / M3 缺功能推演前	用索引拿页面地图（前端）或模块地图（后端）作基线
expert-team	建专家前 + 建完后	建前拿模块边界 / 依赖；建后重跑 provider 的 --emit-tree（专家列会自动出现）
expert-lookup	未命中专家资产时	用索引拿模块边界 / 依赖 / 数据表作兜底线索（专家资产未覆盖的模块）
code-survey / 设计前调研	调研开始时	登记表命中则消费，未命中再决定是否建库
module-teach	讲解某模块前	读 modules/{slug}.md（后端）或 pages/*.md（前端）锁定范围与依赖
frontend-walkthrough	阶段 1 入口穷举	直接拿 pages/*.md（页面清单 + 接口/组件），省一次全站搜索
e2e-testing	阶段 1 拆解旅程	用「页面 → 接口」与「模块 → 表」挑关键路径与跨组件终态校验点

集成方必须自行降级：无索引时按原流程走，不阻塞、不报错。

---

更多资源

• 查询口径与产物结构（SSOT）：frontend-index/SKILL.md、backend-index/SKILL.md —— 本 skill 不复制它们的规则
• 登记表列结构：应用 | 类型 | slug | 根目录 | 规模 | commit | 生成日期（两个 provider 共同维护）