Codebase Index

---
name: codebase-index
description: 代码库速查索引库 —— docs/code-index/ 下每个 crate 一个速查表文件，把「我想做什么」映射到具体文件、入口函数与一句话关键逻辑。当用户想定位或修改某个行为（"怎么改 compact 的触发阈值"、"keepgoing 判定在哪"、"加个 deferred 工具改哪里"、"事件链路怎么走"）、想快速了解某个模块的结构、或要求重建/更新代码索引时使用。用户没提"索引"二字但任务是找代码位置、改某个逻辑、理清调用链时，也应先查索引，而不是直接全库搜索。
---

# Codebase Index

## 索引是什么

- 位置：`docs/code-index/<crate>.md`，跨模块链路在 `docs/code-index/cross-crate.md`
- 本质：**行为 → 文件** 的速查表。查询者带着「我想改 X 的 Y」进来，带着文件路径和入口函数出去
- 原则：只给定位信息 + 一句话关键逻辑；不解释原理、不复制规范正文、不替代设计文档
- 体积：每个文件 100–200 行，全部读入没有负担。索引存在的意义就是让"找文件"这一步从几十次搜索变成一次读表

## 查找流程（查询者视角，最常用）

1. 判断行为落在哪个 crate；不确定就 Glob `docs/code-index/*.md` 并全部读入
2. 在速查表里按行为关键词匹配条目（compact / keepgoing / is_direct / cancel / middleware / prompt …）
3. 打开主文件，跳转到入口函数
4. 索引里的一句话关键逻辑只用于导航；行为细节一律以代码为准
5. 跨模块链路看各索引的「跨模块契约」节或 cross-crate.md，那里指向 `docs/standards/architecture-contracts.md` 的 ARC 编号（不复制正文）

## 构建/更新流程（构建者视角）

触发时机：索引缺失、行为变更后索引过期、用户要求重建/扩充。

输入：目标 crate 源码 + 该 crate 的 `CLAUDE.md` + `docs/standards/architecture-contracts.md`（跨模块契约）+ 相关 `docs/design/` 文档 + `spec/issues/` 中最近的相关 issue。

步骤：

1. 读 crate 的 `CLAUDE.md`，Scope / 数据流 / 稳定不变量直接进「架构速览」
2. **用 Grep 验证每个文件路径、函数名、常量真实存在**（记行号）；禁止凭记忆写路径
3. 逐子系统列条目；每条覆盖：功能 | 文件 | 入口/关键函数 | 一句话关键逻辑
4. 关键逻辑写行为契约（阈值、顺序、条件、边界），一句话讲清，不复制文档正文
5. **标注事实源关系**：`re-export` / 配置事实源 / 注册面要写清归属（例：`compact_v2/config.rs` 仅 re-export `peri-acp-types::compact::CompactConfig`，注册面是 middleware `collect_tools()` 而非工具模块本体）
6. **doc comment 与代码不一致时以代码为准**（本仓库出现过 mod.rs 顶部 doc 描述的触发语义与实际判断条件不符），并在索引里写实际行为
7. 跨 crate 链路（事件、cancel、工具可见性、prompt frozen 等）进「跨模块契约」节，指向 ARC 编号；涉及多个 crate 的链路同时在相关 crate 的索引里互相可见
8. TUI / UI 类 crate 额外列「关键控件/组件」表（kit 组件、widget 等）
9. 自检：每条路径存在、函数名存在、行为描述与代码一致

## 索引文件格式（当前 canonical，经两轮检索实验验证）

```markdown
# <crate> 代码索引

> 速查表：把「我想做什么」映射到文件。细节以代码为准。更新：YYYY-MM-DD
> 依据：<crate>/CLAUDE.md、docs/standards/architecture-contracts.md、源码

## 架构速览
- 数据流 / 循环入口 / 稳定不变量（来自 crate CLAUDE.md）

## 速查表
| 我想做什么 | 主文件 | 入口/关键函数 | 关键逻辑 |
| --- | --- | --- | --- |
| （行为/修改意图，如"改 compact 触发阈值"） | （路径；事实源/re-export 关系标清） | （真实函数名 + 行号） | （一句话行为契约：阈值/顺序/条件） |

## 子系统
### <子系统名>
| 功能 | 文件 | 入口/关键点 |
| --- | --- | --- |

## 跨模块契约
- ARC-XXX-001：一句话要点 → `docs/standards/architecture-contracts.md`
```

实验结论（为什么是这个结构）：

- 「我想做什么」列直接匹配查询意图，subagent 检索时零推理成本命中（variant-b 模块卡片也准确但需自行提取，效率等价、推理略多）
- 每行带**真实入口函数名 + 行号**，检索者打开文件即可跳转，不必再全库搜函数
- 一句话行为契约（阈值/顺序/条件）让检索者先判断"这是不是我改的点"，再读代码
- 「跨模块契约」节 + ARC 编号指针足以支撑跨 crate 查询（事件链路等），无需复制契约正文
- 索引错误会被"以代码为准"验证兜住，但构建时写对（标注 re-export/事实源关系、doc 与代码冲突时信代码）能避免误导

## 质量红线

- 路径、函数名必须真实存在（构建时逐一验证），行号要准确
- 行为描述与代码一致；与文档冲突时以代码为准，并在条目里标注
- 不复制规范正文、不写设计理由；跨模块内容只指向 ARC 编号
- 索引过期比没有索引更危险：行为变更后（阈值、顺序、入口改名）必须同步更新对应条目