adk-docs

ADK 文档管理

在帮助用户创建、审阅、更新或维护其 ADK 项目的文档时，使用此技能。用户会为自己的机器人和功能编写指南与文档——代码示例应来自他们的项目和官方 ADK 仓库。

何时使用此技能

在用户遇到以下情况时启用此技能：

• 想为自己的机器人编写文档（“为我的订单工作流编写文档”“为我的自定义操作撰写指南”）
• 需要检查现有项目文档是否准确（“检查我的文档是否仍然正确”）
• 修改机器人后想更新文档（“我重构了结账流程，更新文档”）
• 需要检查文档是否与代码同步（“我的文档是最新的吗？”）
• 想搜索项目文档（“查找关于我的支付处理程序的文档”）
• 询问文档规范或模板
• 提及 /adk-document

可用文档

文件	描述
references/doc-standards.md	文档类型、模板、质量检查清单和健康指标

可用命令

命令（及建议的子命令）	描述
/adk-document create [topic]	为用户机器人的某项功能编写文档
/adk-document review [doc-path]	检查项目文档的准确性和完整性
/adk-document update [doc-path] [what-changed]	代码变更后更新项目文档
/adk-document sync [optional-doc-path]	检查项目文档是否与机器人的代码同步
/adk-document search [search-term]	搜索项目文档中的特定主题

通用原则

1. 面向 AI 优化的结构

• 使用清晰的章节标题（##、###、####），便于 ripgrep 查找章节
• 在顶部添加带锚点链接的目录
• 根据文档类型控制合适的篇幅（参见 doc-standards 参考文档）
• 章节名称应包含丰富的关键词，避免使用含糊的“高级主题”或“其他”

2. 代码优先的方法

• 每个概念都需要一个来自实际项目代码、可运行的代码示例
• 提供带行号的文件路径以供核实
• 示例的主要来源（按优先级排序）：
  1. 用户自己的 ADK 项目（在工作区中查找 agent.config.ts）——最佳
  2. 官方 ADK 仓库中的示例（克隆或在本地查找）
  3. ADK 运行时用法（@botpress/runtime 包）
• 切勿编造或臆测示例——所有代码都必须可验证

3. 关键区别

• ADK 基元（来自 @botpress/runtime）与 Botpress SDK 基元
• 对话中的 this.send() 与工作流中的 client.createMessage()
• 消息（持久化并存储）与事件（临时且不存储）
• 通用 API 与特定渠道的功能

4. 不作臆测

• 除非用户明确提供内容，否则不要添加“常见错误”或“最佳实践”章节
• 仅在记录实际报告的错误时使用 ❌ WRONG / ✅ CORRECT
• 工作流和示例必须根据实际代码核实，不得凭空想象

5. 写作风格

• 直接且可执行——写“使用 this.send()”，而不是“你可以考虑……”
• 技术准确——根据实际 ADK 代码测试示例
• 默认读者具备理解能力——提供背景和指导，而不是事无巨细地手把手说明
• 不写营销套话——直奔技术内容

如何回答

当用户询问文档相关问题，但未调用特定命令时：

1. 加载 adk skill（如有需要，也加载其他 skill），以获取 ADK 背景知识
2. 确定用户的需求——创建、审阅、更新、同步或搜索
3. 为用户指明合适的命令，或根据上述原则直接提供帮助
4. 参考 doc-standards，了解模板和质量指南

文档位置

文档应写入用户自己的项目。如果文档保存位置不明确，请询问用户（常见位置包括：./docs/、./guides/ 或项目根目录）。

发现代码来源

查找用户的项目和官方 ADK 仓库以获取示例：

// Find ADK projects in the workspace
Glob({ pattern: '**/agent.config.ts' })

// Find ADK runtime usage in the user's project
Grep({ pattern: 'from [\'"]@botpress/runtime', output_mode: 'files_with_matches' })

// Look for existing project documentation
Glob({ pattern: './{docs,guides}/**/*.md' })

// Find official ADK examples if available locally
Glob({ pattern: '**/adk/examples/**/*.ts' })

交叉引用

• adk skill——ADK 核心知识（操作、工作流、对话等）
• adk-evals skill——测试和评估文档
• adk-frontend skill——前端集成文档
• adk skill 的 integrations.md 参考文档——集成生命周期文档