文档检索技能

此技能能够从层级化文档系统中高效检索文档上下文。

变量

变量	默认	描述
MAX_TOKENS	2000	上下文加载的目标令牌预算
LOAD_FULL_CONTEXT	false	使用full-context.md代替目标页面
LOCAL_FIRST	true	先检查ai-docs再进行网络搜索

指令

强制性 - 总是先检查本地文档再进行网络搜索。

从_index.toon文件开始导航
加载目标页面摘要，而不是完整上下文
使用以下格式整合多库上下文
将预加载的上下文传递给子代理

红旗 - 停止并重新考虑

如果你即将：

为一个简单的问题加载full-context.md
没有先检查本地文档就进行网络搜索
让子代理从头开始导航，而不是传递上下文
加载所有库“以防万一”

停止 -> 使用以下目标检索模式 -> 然后继续

工作流程

[ ] 检查点：你是否已经确定了需要的库？
[ ] 检查ai-docs/libraries/_index.toon以获取可用文档
[ ] 导航到特定库_index.toon
[ ] 从索引中识别相关页面
[ ] 仅加载你需要的页面摘要
[ ] 检查点：你是否在令牌预算之内？

食谱书

直接导航

IF: 你知道库和主题
THEN: 阅读cookbook/direct-navigation.md
RESULT: 到达特定信息的最快路径

关键词搜索

IF: 不确定哪个库有你需要的
THEN: 阅读cookbook/keyword-search.md
RESULT: 通过匹配关键词找到相关文档

多库收集

IF: 任务涉及多个库
THEN: 阅读cookbook/multi-library.md
RESULT: 从多个来源整合上下文

全上下文加载

IF: 需要全面理解（迁移，教程）
THEN: 阅读cookbook/full-context.md
警告：高令牌成本（5,000-15,000令牌）

何时使用此技能

在涉及外部库的功能实现之前
当调试外部依赖项中的错误时
当生成需要库上下文的子代理时
当不确定API语法或行为时

检索模式

模式1：直接导航（知道你需要什么）

当你知道库和主题时：

1. @ai-docs/libraries/{library}/_index.toon
   -> 阅读概述和常见任务

2. 找到匹配的任务或部分
   -> 记录页面路径

3. @ai-docs/libraries/{library}/{section}/pages/{page}.toon
   -> 获取详细的摘要以及注意事项和模式

示例：需要BAML重试配置

1. @ai-docs/libraries/baml/_index.toon
   -> 常见任务：“优雅地处理错误” -> guide/error-handling

2. @ai-docs/libraries/baml/guide/pages/error-handling.toon
   -> 重试策略语法，关于超时的注意事项

模式2：关键词搜索（不确定存在什么）

当你不确定哪个库或页面时：

1. @ai-docs/libraries/_index.toon
   -> 扫描库描述和关键词

2. 将你的需求与关键词匹配
   -> 确定候选库

3. 对于每个候选：
   -> @ai-docs/libraries/{lib}/_index.toon
   -> 检查是否包含相关内容

4. 从最佳匹配中加载特定页面

示例：需要“结构化输出解析”

1. @ai-docs/libraries/_index.toon
   -> BAML：“结构化LLM输出与类型安全”[匹配]
   -> MCP：“工具集成协议”[无匹配]

2. @ai-docs/libraries/baml/_index.toon
   -> 确认：类型系统，解析，验证

3. 加载相关BAML页面

模式3：多库收集（复杂任务）

当任务涉及多个库时：

1. 列出任务涉及的所有库

2. 对于每个库：
   -> 加载_index.toon
   -> 识别相关页面
   -> 加载页面摘要

3. 整合成单个上下文块

4. 或者：生成docs-context-gatherer代理

模式4：全上下文（深入工作）

当你需要全面理解时：

@ai-docs/libraries/{library}/full-context.md

慎用 - 这会加载所有内容（~5,000-15,000令牌）

适用于：

主要迁移
编写教程
架构决策
第一次深度学习

上下文整合格式

当从多个页面收集上下文时，整合为：

## 文档上下文

### {库}: {主题}
**目的**：{1-2句话的目的}
**关键点**：
- {概念1}
- {概念2}
**注意事项**：
- {警告1}
- {警告2}
**模式**：
```{语言}
{最小代码示例}

{库}: {另一个主题}

…

来源：{加载的页面路径列表} 令牌：~{估计}


## 预算管理

### 文件类型的令牌估计

| 文件类型 | 典型大小 |
|-----------|--------------|
| `_index.toon`（类别） | 100-150令牌 |
| `_index.toon`（库） | 150-250令牌 |
| `_index.toon`（部分） | 100-200令牌 |
| `pages/*.toon` | 250-450令牌 |
| `full-context.md` | 5,000-15,000令牌 |

### 预算指南

| 任务类型 | 目标预算 | 加载策略 |
|-----------|---------------|------------------|
| 快速修复 | 300-500 | 1页面摘要 |
| 单一特性 | 800-1,200 | 2-3页面摘要 |
| 集成 | 1,500-2,500 | 库索引+4-6页面 |
| 多库 | 2,000-4,000 | 多个库索引+关键页面 |
| 全上下文 | 5,000+ | full-context.md |

### 效率提示

1. **索引文件是廉价导航** - 自由阅读
2. **页面摘要是高信号** - 为此目的设计
3. **注意事项可以防止昂贵的错误** - 总是值得加载
4. **代码模式是复制粘贴就绪** - 每令牌高价值
5. **full-context.md是最后的选择** - 首先使用目标加载

## 常见检索场景

### 场景：实现功能

确定：这个功能使用哪些库？
导航：在每个库中找到相关页面
加载：页面摘要用于实现指导
注意：编写代码前注意事项
继续：加载上下文后实施


### 场景：调试错误

确定：哪个库产生了错误？
搜索：该库中与错误相关的页面
加载：错误处理和故障排除页面
检查：可能解释问题的已知注意事项
继续：带有上下文的调试


### 场景：生成子代理

分析：子代理将需要哪些文档？
收集：现在就加载相关页面
整合：格式化为上下文块
包含：添加到子代理生成提示中
生成：子代理具有预加载的上下文


### 场景：不确定哪个库

开始：@ai-docs/libraries/_index.toon
扫描：库描述和关键词
匹配：找到与你的需求相关的库
探索：检查有希望的库索引
加载：从最佳匹配库加载页面


### 场景：AI工具文档

当你需要AI工具（Claude Code, BAML, MCP, TOON等）的信息时：

首先检查本地ai-docs： @ai-docs/libraries/claude-code/_index.toon @ai-docs/libraries/baml/_index.toon @ai-docs/libraries/toon/_index.toon
使用与任何库相同的模式进行导航： -> 在_index.toon中找到部分 -> 加载相关页面摘要 -> 使用full-context.md进行全面需求
当：
- 本地文档不涵盖特定主题
- 需要时效性信息（发布日期，最新版本）
- 本地文档检查后不充分
- 用户明确要求来自网络的最新信息

为什么本地优先：

更快（无网络往返）
策划上下文（TOON格式针对LLMs优化）
预先提取的注意事项
与完整网页相比，令牌效率高

何时进行网络搜索：

在检查本地索引后找不到主题
需要最新/实时信息
用户明确要求来自网络的最新信息