docs-search

文档搜索 — 官方库文档导航方法

对 Agent 查阅某个库的官方文档时常用方法的提炼。这不是针对某个库的技能，而是一个技能加上共享知识图谱中的一份精简库记录（/knowledge/libraries/），因为无论搜索哪个库，90% 的工作都相同。

这是与 library-reference-distillation 并列的导航层。当你有时间提炼惯用法时，该技能用于编写完整的库参考规则包；而当你没时间提炼，只是查找信息时，则使用本技能——这是更轻量、编写更快的替代方案，其增长单位是一份约 30 行的概览记录，而不是完整的规则包。

何时应用

在以下情况下使用本技能：

• Agent 需要从某个库的官方文档中找到具体答案，下一步是“搜索文档”
• 用户询问“我应该在 <library> 文档的哪里找 X？”或“<library> 最近更改了 Y 吗？”
• 文档看起来与当前情况相符，但生产环境中的行为却不一致
• Agent 正准备通过 Google 搜索库相关问题，而先访问该库自己的站内搜索、llms.txt 或更新日志会更有帮助
• 之前用过某个库，且 registry/ 中已有概览记录——导航前先阅读
• 用过某个库，但尚无记录——应用本方法，然后将发现记入 registry/<library>.md，以便下次更快查找

本技能不适用于：

• 编写库参考规则包——如果你想提炼惯用法和失效差距规则，制作精简技能，请改用 library-reference-distillation。一旦库 X 有了完整的库参考技能，X 的注册表条目就会变得多余，应当删除。
• 一般网页搜索——如果问题与某个特定库的官方文档无关（例如“整个生态系统中 X 的最佳实践是什么？”），本工具就不适用。
• 阅读内部／专有文档——没有 llms.txt、公开更新日志或公开问题。此方法假设文档是公开的、带版本的、采用 OSS 风格。

使用方法

这四类操作彼此独立。根据症状选择操作：

症状	选择	首先阅读的规则
问题很模糊——“在文档中搜索 X”	选择来源	src-decision-tree
准备抓取 HTML；还没检查是否有适用于 AI 的规范格式	选择来源（llms.txt）	src-llms-txt-first
准备扫描 knowledge/libraries/，却还没阅读指定条目	选择来源（限定范围的读取）	src-bounded-knowledge-read
正在阅读最新文档，但用户可能在使用较旧版本	匹配版本	ver-find-selector
问题是“升级后 X 有变化吗？”	匹配版本（更新日志）	ver-changelog-first
文档看起来符合，但生产环境中的行为不符	回退方案	fall-known-issues
问题是“怎样才能按照惯用方式组织这段代码？”	回退方案（示例）	fall-samples-over-prose
已找到规范入口点，准备继续下一步	留存以供复用	capture-registry-record

类别概览和排序理由请参阅 references/_sections.md。

规则类别

#	类别	前缀	操作	规则
1	选择来源	src	分类问题；检查 llms.txt；有界读取知识	3
2	匹配版本	ver	锁定用户使用的版本；查阅参考资料前先看变更日志	2
3	回退	fall	文档与实际情况矛盾时查看已知问题；处理惯用写法时优先看示例而非文字说明	2
4	留存以供复用	capture	将资料布局记录到 registry/，加快下次查找	1

快速参考

1. 选择来源

• src-decision-tree — 选择章节前先对问题分类（API 行为 / 变更日志 / 惯用写法 / 已知缺陷 / 迁移）；“搜索文档”不是计划
• src-llms-txt-first — 抓取 HTML 前先检查 <docs-root>/llms.txt 或 /llms-full.txt；如果存在，就使用面向 AI 的规范格式
• src-bounded-knowledge-read — 文件名就是索引：只读取 knowledge/libraries/<slug>.md，绝不扫描目录；每次调用的令牌成本都有上限，不受知识库大小影响

2. 匹配版本

• ver-find-selector — 阅读任何参考页面前先找到版本选择器；询问用户或读取 package.json 来锁定版本
• ver-changelog-first — 问题中出现“升级后”或“X 是否有变化”时，先阅读变更日志，再看参考资料

3. 回退

• fall-known-issues — 文档与用户代码相符但实际情况不符时，重新阅读文档前先查看 GitHub issues、状态页和 Discord/论坛，了解已知缺陷
• fall-samples-over-prose — 遇到“我应该如何组织这个？”这类问题时，先查看 examples/ 目录或示例仓库；惯用结构体现在代码中，而不是文字说明里

4. 留存以供复用

• capture-registry-record — 首次成功查阅某个库后，填写 knowledge/libraries/<library>.md 中的 docs: 部分，让后续查找跳过发现阶段

知识库

每个库的布局记录存放在仓库根目录下共享知识图谱的 /knowledge/libraries/ 中。 code-distill 也会写入相同的文件——每项技能各自负责一个部分（本技能负责 docs:，code-distill 负责 code:），绝不覆盖另一部分。合并后的架构、Wiki 链接约定和合并规范，请参阅 knowledge/README.md。

知识库在 v0.1.0 中刻意留空。只有实际查找需要时才添加第一条记录，而不是提前添加。如果你发现自己要为尚未实际查询过的库添加记录，请停下来——等确有需要时再添加。

读取规范：用户提到某个库时，只执行 read knowledge/libraries/<slug>.md。绝不扫描 knowledge/libraries/ 来“看看有哪些内容”——文件名就是索引，按需访问才能确保每次调用的令牌成本都有上限，不受知识库大小影响。

相关技能

• library-reference-distillation — 完整库参考规则包的编写手册（更重量级的同类技能）；当库 X 发布完整的库参考技能时，移除 X 的注册表条目
• radical-simplification — 位于本技能之上的思考层；本技能本身就是将“约束 → 命名不变量”这一做法应用于“如何查找？”这一问题的实例
• init（及类似技能）— 如果查找内容涉及你自己的代码库，那就是另一个问题；本技能面向外部库文档

编写说明

这些规则至关重要，并非装饰。每条规则都指出了 Agent 查阅文档时常见的错误默认行为：把所有问题都当作“搜索文档”、忽略 llms.txt、用户使用旧版本时却阅读最新的参考页面、现实情况与文档矛盾时仍继续重读文档、偏爱叙述而非代码，以及下次查找时重复做已经完成的工作。如果某条规则只是重述了有能力的模型在收到提示后本就能正确做到的事，就删掉它。是否涵盖充分，要通过对真实文档查找提示运行 /dev-skill:eval 来验证，而不是看规则数量。注册表会随着实际查找需求逐步扩充。