文档导航技能Skill docs-navigation

文档导航技能

在层次化的文档系统中导航，以最小化的令牌使用量找到相关上下文。

变量

变量	默认值	描述
START_LEVEL	auto	auto, root, category, library, section, page
KEYWORD_MATCH	fuzzy	fuzzy (语义) 或 exact 匹配用于索引导航

指令

强制性 - 总是从适当的索引级别开始。

• 在加载页面之前阅读 _index.toon 文件
• 将任务关键词与索引关键词匹配
• 加载特定页面，而不是整个上下文
• 注意索引中的 priority 和 when_to_use 字段

红旗 - 停止并重新考虑

如果你即将：

• 为一个简单的问题加载 full-context.md
• 猜测文件路径而不是阅读索引
• 跳过索引直接去页面
• 加载一切“以防万一”

停止 -> 按照下面的导航协议 -> 然后继续

工作流程

1. [ ] 检查点: 确定你知道什么（库？部分？主题？）
2. [ ] 从适当的索引级别开始
3. [ ] 阅读索引，将关键词与你的任务匹配
4. [ ] 钻取到特定页面
5. [ ] 只加载你需要的页面
6. [ ] 检查点: full-context.md 合理吗？（很少）

菜谱

级别选择

• 如果：不确定在层次结构中从哪里开始
• 那么：阅读 cookbook/level-selection.md
• 结果：基于你所知道的，从正确的级别开始

关键词匹配

• 如果：按主题搜索文档
• 那么：阅读 cookbook/keyword-matching.md
• 结果：通过索引关键词找到相关页面

高效页面加载

• 如果：加载多个页面或管理令牌预算
• 那么：阅读 cookbook/page-loading.md
• 结果：在获得所需上下文的同时最小化令牌使用

层次结构

ai-docs/
├── _root_index.toon              # 级别 0：所有类别
├── libraries/
│   ├── _index.toon               # 级别 1：所有库
│   ├── {library}/
│   │   ├── _index.toon           # 级别 2：库部分
│   │   ├── {section}/
│   │   │   ├── _index.toon       # 级别 3：部分页面
│   │   │   └── pages/
│   │   │       └── {page}.toon   # 级别 4：页面摘要
│   │   └── full-context.md       # 一切（紧急出口）

导航协议

第 1 步：从正确的级别开始

你知道什么	从这里开始
无	ai-docs/_root_index.toon
类别（库/框架）	ai-docs/{category}/_index.toon
库名称	ai-docs/libraries/{lib}/_index.toon
库 + 部分	ai-docs/libraries/{lib}/{section}/_index.toon
确切页面	ai-docs/libraries/{lib}/{section}/pages/{page}.toon

第 2 步：阅读索引，匹配关键词

每个索引包含：

• description 或 purpose - 这个级别包含什么
• keywords - 用于匹配你任务的术语
• when_to_use - 何时深入钻取的指导
• 子路径 - 下一步导航的位置

将你的任务与关键词匹配：

任务："处理 LLM 重试失败"
关键词查找：重试、错误、失败、回退、超时

导航：
1. libraries/_index.toon -> "baml" 有 "llm|structured-output"
2. baml/_index.toon -> 常见任务提到 "错误处理"
3. baml/guide/_index.toon -> "错误处理" 页面有 "重试|回退"
4. baml/guide/pages/error-handling.toon -> 需要的确切信息

第 3 步：只加载所需的内容

做：

@ai-docs/libraries/baml/guide/pages/error-handling.toon  # ~400 令牌

不要：

@ai-docs/libraries/baml/full-context.md  # ~15,000 令牌

第 4 步：如果需要，加载多个页面

对于复杂任务，加载几个特定页面：

@ai-docs/libraries/baml/guide/pages/error-handling.toon
@ai-docs/libraries/baml/guide/pages/timeouts.toon
@ai-docs/libraries/baml/reference/pages/retry-policy.toon

仍然比 full-context.md 便宜得多。

第 5 步：谨慎使用 full-context.md

仅用于：

• 编写全面的教程
• 主要迁移
• 图书馆的初步深入学习

索引文件结构

类别索引 (_index.toon)

meta:
  level: category
  name: libraries
  count: 5

items[5]{id,name,description,path,keywords,priority}:
baml,BAML,结构化 LLM 输出与类型安全,./baml/_index.toon,llm|types|prompts,high
mcp,MCP,AI 助手的工具集成,./mcp/_index.toon,tools|servers|context,high

库索引 ({lib}/_index.toon)

meta:
  level: library
  name: BAML
  version: 0.70.0
  homepage: https://docs.boundaryml.com

overview: |
  这个库做什么以及何时使用它的简短描述。

sections[3]{id,name,path,page_count,when_to_use}:
guide,Guide,./guide/_index.toon,15,学习概念和教程
reference,Reference,./reference/_index.toon,25,确切的语法和 API 细节
examples,Examples,./examples/_index.toon,8,工作代码样本

common_tasks[5]{task,section,page}:
Define output types,reference,types
Handle errors,guide,error-handling
Stream responses,guide,streaming

部分索引 ({lib}/{section}/_index.toon)

meta:
  level: section
  library: baml
  section: guide
  page_count: 15

pages[15]{id,title,path,priority,purpose,keywords}:
introduction,Introduction,./pages/introduction.toon,core,概述和基本概念,basics|overview|start
error-handling,Error Handling,./pages/error-handling.toon,important,重试和回退策略,retry|error|fallback

页面摘要 ({lib}/{section}/pages/{page}.toon)

meta:
  level: page
  library: baml
  section: guide
  page: error-handling
  source_url: https://docs.boundaryml.com/guide/error-handling
  content_hash: abc123

summary:
  purpose: |
    这个页面教授的内容的一两句话。

  key_concepts[5]: concept1|concept2|concept3|concept4|concept5

  gotchas[3]: warning1|warning2|warning3

code_patterns[2]:
  - lang: baml
    desc: 这个模式展示了什么
    code: |
      // 代码示例被截断

related_pages[2]: ../pages/timeouts.toon|../../reference/pages/retry-policy.toon

导航示例

示例 1：特定功能

任务："配置 BAML 流"

1. @ai-docs/libraries/baml/_index.toon
   -> 常见任务："流响应" -> guide/streaming

2. @ai-docs/libraries/baml/guide/pages/streaming.toon
   -> 获取流配置

令牌：~600

示例 2：未知库

任务："在 TypeScript 中进行类型安全的数据库访问"

1. @ai-docs/libraries/_index.toon
   -> 扫描关键词："prisma" 有 "database|orm|typescript"

2. @ai-docs/libraries/prisma/_index.toon
   -> 导航到相关部分

令牌：~400 + 下一级

示例 3：全面知识

任务："将整个代码库从 X 迁移到 BAML"

1. @ai-docs/libraries/baml/full-context.md
   -> 加载一切（这里正确的选择）

令牌：~15,000（迁移时合理）

反模式

坏	好	为什么
为简单问题加载 full-context.md	导航到特定页面	95% 令牌浪费
猜测文件路径	从索引开始，逐步深入	索引显示了什么存在
加载一切“以防万一”	加载任务所需的内容	浪费上下文窗口
跳过索引，直接去页面	先阅读索引	可能错过更好的页面