| name | code-rag |
| description | 为任意代码仓库构建结构化知识库（code wiki），并通过 frozen snapshot 机制启动即问即答的 expert agent。
当你需要深入理解一个大型代码仓库、构建可复用的代码知识库、或为其他 agent 提供代码专家服务时使用此技能。
|
| metadata | {"goclaw":{"emoji":"🏗️","requires":{"bins":["ai"]}}} |
Code RAG — 构建代码仓库的结构化知识库
将大型代码仓库的源码知识编译成结构化的 wiki 页面，再通过 frozen snapshot 机制把 wiki 全量加载到 expert agent 上下文中，实现零延迟 RAG。
核心思想：编译一次，反复使用。 不是每次从源码重新检索，而是预先系统性提炼知识，之后即问即答。
When to Use
- 面对一个不熟悉的大型代码仓库，需要系统性理解其架构和设计
- 需要构建一个可长期维护、可反复查询的代码知识库
- 需要为其他 agent 提供某个项目的代码专家服务（作为 subagent）
- 需要理解跨模块的调用链、设计决策、隐性约束
- 项目有设计文档需要和源码知识整合
不要用于：
- 小项目（< 50 个源文件）—— 直接读源码更高效
- 纯使用问题（不是源码层面的问题）
- 一次性问题（不值得构建整个 wiki）
已建项目
以下项目已构建好 wiki，可直接启动 expert agent 使用：
| 项目 | Wiki 路径 | 源码路径 | 子系统数 | 大小 |
|---|
| OceanBase | ~/project/oceanbase-code-RAG/ | ~/project/oceanbase/ | 9 | 321KB |
| TiDB | ~/project/tidb-code-RAG/ | ~/project/tidb/ | 10 | 558KB |
| CSE | ~/project/cloud-storage-engine/wiki | ~/project/cloud-storage-engine/ | 11 子系统 + 6 流程 + 13 特性 | ~33 页面 |
使用方式：进入 wiki 目录，执行 wiki/snapshot/snapshot.sh start，然后用 ask 提问。
详见下方 Phase 3 章节。
Architecture
~/project/<project>-code-RAG/ ← 项目 wiki 仓库
├── README.md ← 构建记录和维护指南
├── wiki/
│ ├── index.md ← 总索引（所有页面清单 + 分类）
│ ├── architecture.md ← 顶层架构（组件图 + 跨模块数据流）
│ ├── subsystems/ ← 子系统页面（主线）
│ │ ├── <subsystem-1>.md
│ │ └── <subsystem-2>.md
│ ├── features/ ← 特性页面（辅线，可选）
│ │ ├── <feature-1>.md
│ │ └── <feature-2>.md
│ └── snapshot/
│ ├── frozen/ ← 🔒 冻结镜像（只读）
│ ├── runtime/ ← 🔧 工作副本（可脏）
│ ├── bootstrap.md ← Agent 加载指令（freeze 时使用）
│ ├── system-prompt.md ← Expert agent 的 system prompt（start 时使用）
│ └── snapshot.sh ← 管理脚本
完整工作流
Phase 1: Init — 初始化
1. 确定目标项目
- 项目名、源码路径、主要语言
- 是否有设计文档（docs/design/ 等）
- 是否有官方技术文档
2. 创建 wiki 目录
mkdir -p ~/project/<project>-code-RAG/wiki/{subsystems,features,snapshot}
3. 生成 snapshot.sh（从模板，填入项目名）
cp <skill-dir>/templates/snapshot.sh ~/project/<project>-code-RAG/wiki/snapshot/
# 编辑 PROJECT_NAME 和 EXPERT_LABEL
4. 生成 bootstrap.md（从模板，Phase 2 结束后再填入子系统列表）
cp <skill-dir>/templates/bootstrap.md ~/project/<project>-code-RAG/wiki/snapshot/
5. 生成 system-prompt.md（Expert agent 的行为约束）
cp <skill-dir>/templates/system-prompt.md ~/project/<project>-code-RAG/wiki/snapshot/
Phase 2: Build — 构建 wiki 内容
构建是分轮次进行的，每轮用 subagent 并行探索。
Round 0: 架构探索 + 子系统划分
agent 扫描项目结构后自主决定子系统划分。
输入：README、入口文件（main/lib.rs/go.mod）、目录结构、Makefile/Cargo.toml
输出：
- wiki/architecture.md — 顶层架构图、组件关系、核心数据流
- wiki/index.md — 子系统清单 + features 清单（占位）
- 子系统划分方案（供 Round 1 使用）
子系统识别策略（agent 自主判断）：
- 优先按项目的
components/ 或 pkg/ 目录划分
- 如果项目是单模块，按职责域划分（如 parser/planner/executor）
- 合并太小或关系紧密的模块（< 5 个核心文件的模块应合并到相邻模块）
- 目标粒度：每个子系统 15-40KB wiki 页面
- 子系统数量：通常 5-15 个
- agent 自行决定哪些文件值得读、哪些跳过（测试、生成代码、vendor 等）
Round 1: 子系统探索（并行 subagent）
每个 subsystem 分配一个 subagent，并行探索。
subagent 数量 = min(子系统数量, 5-6) # 每个 subagent 负责 1-3 个子系统
每个 subagent 任务：
1. 读源码核心文件（每个子系统 ≥ 10 个文件）
2. 读已有的 agents/design 文档（如果有）
3. 输出标准格式的 wiki 页面
Subagent Prompt 模板（见下方 Templates 章节）
Round 2: 设计文档整合（可选）
如果项目有设计文档（docs/design/、RFC 等），用 subagent 按主题分组阅读：
1. 列出所有设计文档，按子系统分组
2. 每个 subagent 负责一组设计文档
3. 为对应的 subsystem 页面补充「设计决策与取舍」段落
Round 3: 特性/官方文档整合（可选）
如果项目有官方用户文档，提炼出特性级别的知识：
1. 列出官方文档，按特性分组
2. 每个 subagent 负责一组
3. 输出 features/ 页面
Round 4: 交叉链接 + Lint
1. 检查所有 [[wikilinks]] 是否指向存在的页面
2. 补充跨子系统的「相关子系统」链接
3. 更新 index.md 为最终版
4. 确认每个页面都有 frontmatter（tags, date）
5. 检查 wiki 总大小（目标 < 200KB，超出则考虑精简或拆分）
Phase 3: Serve — 启动 Expert Agent
cd ~/project/<project>-code-RAG
wiki/snapshot/snapshot.sh freeze
wiki/snapshot/snapshot.sh start
wiki/snapshot/snapshot.sh ask "你的问题"
wiki/snapshot/snapshot.sh stop
wiki/snapshot/snapshot.sh clean
Expert Agent 的源码搜索能力（semble）
Expert agent 预装了 wiki 知识，但遇到 wiki 未覆盖的细节时，可以用 semble 搜索源码补充。
semble 是语义代码搜索引擎（~250ms 索引，~1.5ms 查询），在 bootstrap.md 中配置搜索指令。
Expert agent 自行判断何时需要搜索——调用方无需关心。
wiki 有答案 → 直接回答（秒级）
wiki 不够 → semble 搜索源码 → 补充回答（多几秒）
前提：semble 已通过 mcporter config add semble --command semble --scope home 配置为 MCP 服务（expert agent 通过 mcporter call 调用，索引缓存不重复构建）。
在 bootstrap.md 的「源码搜索工具」章节中配置：
- 按子系统子目录搜索（避免搜整个项目，太慢）
- 语义搜索 + 符号搜索 + find-related
- 子系统目录对应关系复用 wiki/index.md 中的映射
作为 subagent 服务（推荐）
在其他 agent 中通过 ai send 调用：
cd ~/project/<project>-code-RAG
bash wiki/snapshot/snapshot.sh start
EXPERT_ID=$(cat wiki/snapshot/expert.id)
ai send --id "$EXPERT_ID" --wait --timeout 10m "你的问题"
bash wiki/snapshot/snapshot.sh stop
echo "$EXPERT_ID" >> ~/.ai/runs/$RUN_ID/subagent
超时建议：expert agent 遇到 wiki 未覆盖的问题时会用 semble 搜源码补充，
这需要额外时间。建议统一使用 --timeout 10m，避免深度问题被截断。
长回答技巧：如果预期回答会很长（如"全面梳理 XX 的全部资料"），
让 expert 写入文件而不是流式输出，避免截断：
ai send --id "$EXPERT_ID" --wait --timeout 10m \
"请将完整回答写入 /tmp/ob-answer.md，写完后输出'已写入'即可"
ai send --id "$EXPERT_ID" --wait --timeout 10m \
"请基于你刚才搜到的信息，将完整回答写入 /tmp/ob-answer.md"
Phase 4: Maintain — 维护更新
1. 拉取最新源码
2. git diff / git log --stat 评估受影响的子系统
3. 用 subagent 重新探索受影响的子系统，更新 wiki
4. wiki/snapshot/snapshot.sh freeze — 重建冻结镜像
5. wiki/snapshot/snapshot.sh clean && wiki/snapshot/snapshot.sh start
更新频率：
| 变更规模 | 操作 |
|---|
| bug fix / 小重构 | 不需要更新 |
| 功能迭代 | 更新对应的 subsystems 页面 |
| 新特性 | 新建 features 页面，更新 index |
| 大版本升级 | 全面重新评估 |
Templates
Wiki 页面标准格式
每个 wiki 页面包含以下段落：
---
tags: [subsystem, keyword1, keyword2]
date: YYYY-MM-DD
sources: [source-file-slug]
---
# <子系统/特性名>
> 一句话概述
## 概述
本节在全系统中的位置、核心职责、对外接口。
## 原理与数据结构
核心数据结构、算法、设计模式。包含关键 struct/class 的关系图。
## 关键流程
主要操作的生命周期/状态机/调用链。
## 源码导航
关键文件路径列表（相对项目根目录），每个文件一行注释说明职责。
## 配置与变量
相关的配置项、环境变量、命令行参数。
## 设计决策与取舍
为什么这样设计，考虑过哪些替代方案，各自 trade-off。
（从设计文档、PR review、commit message 中提炼）
## 使用场景与最佳实践
典型用法、推荐配置、性能考量。
## 隐性知识 / 踩坑指南
源码中不明显但重要的约束、常见陷阱、调试技巧。
## 相关子系统
- [[other-subsystem]] — 说明关联关系
## 参考
- [设计文档链接]
- [RFC 链接]
Subagent Prompt 模板
你是 <PROJECT_NAME> 源码 wiki 的构建者。请探索以下子系统，输出结构化 wiki 页面。
## 探索范围
[列出需要阅读的源码目录]
[列出可参考的设计文档]
## 源码位置
<SOURCE_PATH>
## 输出要求
写入文件 <wiki/subsystems/xxx.md>，包含以下段落：
1. 概述 2. 原理与数据结构 3. 关键流程 4. 源码导航
5. 配置与变量 6. 设计决策与取舍(★) 7. 使用场景与最佳实践
8. 隐性知识/踩坑指南 9. 相关子系统 + 参考
## 注意事项
- 源码导航中的路径用相对项目根目录的路径
- 关键流程要画出调用链（A → B → C）
- 设计决策要说清楚「为什么」而不只是「是什么」
- 踩坑指南从代码注释、TODO、已知问题中提炼
- 自行判断哪些文件值得深入、哪些可以跳过（测试/生成代码/vendor 等）
Frozen ↔ Runtime 设计
frozen/ (只读) runtime/ (可变)
N 条消息, ~100-200KB 随提问增长
│ │
│ start = cp │ ask × N
│ ──────────────► │ ──────────► session 越来越大
│ │
│ clean = rm │
│ ◄──────────────── │
│ │
▼ ▼
永远干净 用脏了就扔
关键原则：frozen 只读，runtime 随便脏。
- freeze：启动临时 agent，让它读完所有 wiki 页面，保存 session 为冻结镜像
- start：从 frozen 复制到 runtime，启动 expert agent（使用
system-prompt.md 约束行为）
- ask：向 agent 提问，消息追加到 runtime
- clean：丢弃 runtime，下次 start 重新 fork
为什么需要 system-prompt.md？
ai serve 默认使用 coder role 的 system prompt，这会让 agent 倾向于读写代码、运行测试。
但 code RAG expert 的职责是「基于 wiki 知识回答问题」，不应该主动修改代码或运行构建。
system-prompt.md 覆盖默认行为，确保 agent 专注于知识问答。
Commands Reference
| 命令 | 用途 |
|---|
snapshot.sh freeze | 重建冻结镜像（wiki 更新后执行） |
snapshot.sh start | Fork frozen → runtime，启动 expert |
snapshot.sh ask "Q" | 提问（等回答） |
snapshot.sh stop | 停止（保留 runtime，可 resume） |
snapshot.sh clean | 清除 runtime（下次重新 fork） |
snapshot.sh reset | 清除一切（frozen + runtime） |
snapshot.sh status | 查看状态 |
Troubleshooting
| 问题 | 解决 |
|---|
frozen/ 不存在 | 先执行 snapshot.sh freeze |
| agent 启动但无响应 | tmux attach -t <project>-expert 检查 |
| 回答质量下降 | snapshot.sh clean && snapshot.sh start |
| wiki 内容过时 | 更新 wiki 后 snapshot.sh freeze |
ai ls 看不到 agent | snapshot.sh stop && snapshot.sh start |
| 构建冻结镜像超时 | 检查 wiki 总大小，可能需要拆分 bootstrap.md |
| wiki 超过 200KB | 合并小模块或精简内容 |
References
- TiDB Code RAG（完整实例）：
~/project/tidb-code-RAG/
- 10 个子系统页面、15 个特性页面
- 从 TiDB 源码 + 109 篇设计文档 + 106 篇官方文档中提炼约 558KB
- 构建过程记录在
README.md 的「构造方法」章节
- Wiki 技能（通用 wiki 维护方法论）：
~/.ai/skills/wiki/SKILL.md
