Index Lookup

---
name: index-lookup
description: 代码索引（.fe-index/）的统一查询入口：按代码路径自动判定该查前端页面索引还是后端模块索引，给出新鲜度校验与查询入口；无索引自动降级。触发："查索引"、"这段代码有索引吗"、"改这个要查哪个索引"、"index lookup"。
---

# 索引查询（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` / `code-change-impact` | 拿到 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 入口穷举；阶段 1.5 挖隐藏缺陷 | 拿 `pages/*.md`（页面清单 + 接口/组件）省一次全站搜索；拿 `apis/*.md` 反查页面依赖的接口充当"异步源"清单 |
| `e2e-testing` | 阶段 1 拆解旅程 | 用「页面 → 接口」与「模块 → 表」挑关键路径与跨组件终态校验点 |

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

---

## 更多资源

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