| name | handbook-search |
| description | ai-playbook handbook (3986 行) 智能查询入口。当用户/任务提到 §NN.M 章节号、 "手册"、"playbook"、"铁律 #N"、"反模式"、"竞品" 等关键词时自动触发。 读 INDEX.md 决定该读哪段 handbook，避免每次塞 3986 行全文进上下文。
|
| user-invocable | false |
| when_to_use | 用户提到 §<数字>.<数字> 章节引用、"手册第 N 节"、"playbook 说"、"铁律 #N"、 "反模式 #N"、"按手册"、handbook.md 的具体章节查询时。
|
Handbook Search (§4 Context Engineering 实践)
handbook.md 有 3986 行 / 49 章节。把它全部塞进上下文是反 §4.1 的（attention budget 浪费）。
本 skill 提供"先读 INDEX，再读对应章节"的两段式查询。
工作流
Step 1: 读 INDEX.md
test -f playbook/INDEX.md && cat playbook/INDEX.md
INDEX.md 维护"章节 → 关键词 → 行号范围"映射。例：
§32.1 Forbidden 路径 | auth/payment/secrets/migration | L2400-2480
§35 Eval-Driven Dev | golden trajectory / CI gate / mutation | L2680-2780
§44 Deterministic Replay | trajectory jsonl / cost / replay | L3470-3570
Step 2: 按用户问题定位章节
| 用户问题模式 | 应查 |
|---|
| "§32.1 怎么说的" | 直接读 L<起>-<止> |
| "铁律 #13 是什么" | grep "铁律 #13" 后定位章节 |
| "vibe coding 反模式" | 搜 §32.5 / §33 |
| "什么是 spec-driven" | §18 |
| "Constitution 怎么写" | §37 / docs/ai-cto/CONSTITUTION.md |
| "怎么跨模型 review" | §48 |
| "怎么写 eval" | §35 / evals/golden-trajectories/ |
Step 3: 读特定章节段
用 Read 工具的 offset + limit：
Read(file_path="playbook/handbook.md", offset=2400, limit=80)
Step 4: 引用回应
用 §N.M 格式精准引用：
"按手册 §32.1（L2400-2480），forbidden 路径定义为 ..."
反模式
| 反模式 | 应当 |
|---|
直接 Read playbook/handbook.md（全文） | 先读 INDEX 定位 |
| Grep handbook 抓上下文 | INDEX 已索引，grep 是 fallback |
| 凭记忆引用 §N.M | 必须 Read 实际行号确认（铁律 #2） |
| 不引用直接说"手册说" | 必须用 §N.M 格式让用户能查证 |
当 INDEX.md 不存在
"⚠️ playbook/INDEX.md 不存在（v3.8 应有）。
fallback: 用 grep 找章节。
建议：跑 cto-audit 或手动维护 INDEX.md。"
引用
- handbook §4.1 Context Engineering（为什么不能塞全文）
playbook/INDEX.md（章节索引 SSOT）playbook/handbook.md（3986 行原文）
