codebase-index

# 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 ...