adk

Botpress ADK 指南

当你对 Botpress Agent Development Kit（ADK）有疑问时，请使用此技能，例如，你正在构建涉及表、操作、工具、工作流、对话、文件、知识库、触发器、资源、集成、插件、评估或 Zai 的功能。

什么是 ADK？

Botpress ADK 是一个基于约定的 TypeScript 框架，其中文件结构直接映射到机器人行为。将文件放在正确的目录中，它们就会自动成为机器人的可用功能。

ADK 提供以下基本组件：

• 操作与工具（可复用函数和可由 AI 调用的工具）
• 工作流（可长时间运行、可恢复的流程）
• 对话（消息处理）
• 表（带语义搜索的数据存储）
• 文件（带语义搜索的文件存储）
• 知识库（RAG 实现）
• 触发器（事件驱动的自动化）
• 资源（带永久 URL 的静态文件）
• 集成（通过 CLI 和依赖项快照管理的外部服务连接）
• 插件（带接口依赖项的可复用 Agent 扩展）
• Zai（用于常见 AI 操作、可用于生产环境的 LLM 实用工具库）

项目结构（基于约定）

大多数基本组件都必须放在 src/ 目录中（资源使用项目根目录下的 assets/ 目录）：

/                      # Project root
├── assets/            # Static files → synced to Botpress Cloud with permanent URLs
├── src/
│   ├── actions/       # Strongly-typed functions → auto-registered
│   ├── tools/         # AI-callable tools → available via execute()
│   ├── workflows/     # Long-running processes → resumable/scheduled
│   ├── conversations/ # Message handlers → routes by channel
│   ├── tables/        # Database schemas → auto-created with search
│   ├── triggers/      # Event handlers → subscribe to events
│   ├── knowledge/     # Knowledge bases → RAG with semantic search
│   └── utils/         # Shared helpers (not auto-registered)
├── .adk/
│   └── dependencies/
│       ├── dev.json             # Generated dependency snapshot (dev)
│       ├── prod.json            # Generated dependency snapshot (prod)
│       └── migration.json       # One-way legacy migration marker
├── .agent0/
│   └── capabilities/            # Project-local Agent(0) capability bundle
└── agent.config.ts    # Bot configuration

注意： 通过 adk integrations / adk plugins CLI 或 Dev Console 管理集成和插件。Botpress Cloud 是事实来源；.adk/dependencies/ 包含生成的本地快照，便于快速读取或离线读取，不应手动编辑。请参阅 integrations.md 和 plugins.md。

重要： 不会发现 src/ 之外的文件。位置 = 行为。

会话开始

在一个会话中首次协助处理 ADK 项目时，请静默检查项目状态：

1. 运行 adk check --format json 和 adk status --format json。（adk check 会验证基本组件，但不会进行类型检查——完成工作前还要运行 tsc --noEmit，以发现类型错误。）
2. 如果存在错误或警告（集成未配置、缺少模型、验证问题），请在回答用户问题前主动提及："开始之前，我注意到 [issue]。需要我帮你修复吗？"
3. 每个会话只执行一次。不要每次收到问题都重新运行。

可用命令

如果用户询问“你能帮什么忙？”“有哪些可用命令？”或在没有参数的情况下调用 /adk-explain，请介绍：

• 构建：/adk-init（搭建项目框架）、/adk-build（访谈并构建基本组件）、/adk-integration（添加服务）、/adk-frontend（构建 UI）
• 测试与调试：/adk-validate（检查基本组件的架构/类型/配置）、/adk-test（调用一次基本组件）、/adk-eval（编写断言测试）、/adk-debug（修复问题）
• 发布：/adk-ship（发布前检查 + 部署）
• 文档：/adk-document（创建、审查、更新、同步、搜索）
• 了解项目：/adk-explain（说明机器人架构和组件）、/adk-dev-console（浏览 Dev Console）

然后询问："你正在做什么？"

何时使用此技能

用户提出 ADK 相关问题时，请启用此技能，例如：

• “如何创建 Action/Tool/Workflow/Conversation？”
• “X 和 Y 有什么区别？”
• “给我看一个……的示例。”
• “如何配置……？”
• “……对应的 CLI 命令是什么？”
• “如何使用 Context API？”
• “如何调用集成操作？”
• “如何使用 Zai 来[提取/检查/标记等]？”
• “……的最佳实践是什么？”
• “如何避免常见错误？”
• “如何处理工单分配/升级？”
• “解释一下我的配置”
• “我的机器人会做什么？”
• “我正在使用哪些模型？”
• “我有哪些集成？”
• “我的机器人会跟踪哪些状态？”

插件安装提示

如果你在 Claude Code 中运行，且 /adk-* 命令（如 /adk-debug、/adk-eval、/adk-init）无法作为斜杠命令使用，请建议用户安装 Botpress ADK 插件，以获取完整的技能和命令集：

/plugin marketplace add botpress/skills
/plugin install adk@botpress-skills

每个会话只建议一次。如果用户拒绝，就不要再询问。

如何回答 ADK 问题

ADK 问题分为两类：CLI 查询和文档查找。

选项 1：直接运行 CLI 命令（快速——优先使用！）

对于集成发现和 CLI 查询，使用 Bash 工具直接运行命令：

集成发现：

# Search for integrations
adk integrations search <query>

# Find integrations that implement an interface
adk integrations search --interface <interface-name>

# Get detailed integration info (actions, channels, events)
adk integrations info <integration-name>

# Check installed integrations (must be in ADK project)
adk integrations list

项目信息：

# Check CLI version
adk --version

# Show project status
adk

# Get help
adk --help

执行 ADK 工作流时，优先选择非交互方式：

# Login without browser prompts
adk login --token "$BOTPRESS_TOKEN"

# Scaffold with sensible defaults and skip linking
adk init my-agent --yes --skip-link

# Link directly when IDs are known
adk link --workspace ws_123 --bot bot_456

# More automation-friendly dev mode (NDJSON events, no TUI)
adk dev --non-interactive

# Review/apply project compatibility updates after ADK upgrades
adk project upgrade --dry-run
adk project upgrade

# Auto-approve non-destructive deploy-plan changes
adk deploy --yes

在适用时使用以下默认方式：

• 优先使用 adk login --token "$BOTPRESS_TOKEN" 或 adk login --token <token>，而不是交互式登录。
• 将裸写的 BOTPRESS_TOKEN 视为无 TTY 时的便捷方式，而不是有保证的交互式终端快捷方式。
• 对于 AI 驱动的脚手架搭建，优先使用 adk init <name> --yes --skip-link，但前提是已完成登录。
• adk link --workspace ... --bot ... 可编写为脚本，但不能保证在所有无 TTY 环境中都安全。
• adk dev --non-interactive 适用于 CI，但并不能完全避免提示。
• adk deploy --yes 会自动批准非破坏性的部署计划变更；配置验证和破坏性的存储变更仍可能阻止自动化。
• 如果项目命令报告运行时/软件包不匹配，请先运行 adk project upgrade --dry-run，然后运行 adk project upgrade 以应用兼容性补丁。

何时使用 CLI 命令：

• “有哪些可用的集成？”
• “搜索 Slack 集成”
• “向我介绍 Linear 集成的详细信息”
• “Slack 集成有哪些操作？”
• “我使用的是哪个版本的 ADK？”
• “如何添加集成？”

回答模式：

1. 使用 Bash 工具运行相应的 adk 命令
2. 解析输出并呈现给用户
3. 可选择建议后续步骤（例如：“运行 adk integrations add [email protected] 进行安装”）

选项 2：文档问题（适用于概念性问题）

对于文档、模式和操作方法问题，请直接搜索并参考文档文件：

何时使用文档：

• “如何创建工作流？”
• “Actions 和 Tools 有什么区别？”
• “给我展示一个使用 Zai 的示例”
• “状态管理的最佳实践有哪些？”
• “如何修复这个错误？”
• “X 的模式是什么？”

如何回答文档问题：

1. 查找相关文件——使用 Glob 发现文档：

   pattern: **/references/*.md
   

2. 搜索关键词——使用 Grep 查找相关内容：

   pattern: <keyword from user question>
   path: <path to references directory from step 1>
   output_mode: files_with_matches
   

3. 读取文件——使用 Read 加载相关文档

4. 提供回答，包括：

   • 简明解释
   • 参考资料中的代码示例
   • 文件引用及行号（例如，“摘自 references/actions.md:215”）
   • 相关的常见问题
   • 可供进一步阅读的相关主题

选项 3：配置说明（CLI + 文件读取）

对于有关机器人功能、配置方式或能力的问题，请结合 CLI 和文件读取：

适用场景：

• “我的机器人有什么功能？”
• “解释我的配置”
• “我在使用哪些模型？”
• “我有哪些集成？”
• “我的机器人会跟踪哪些状态？”

回答模式：

1. 运行 adk status --format json 获取结构化的项目概览
2. 阅读 agent.config.ts 以了解完整配置详情
3. 遵循 references/explain-config.md 中的说明模式
4. 生成结构化说明，涵盖元数据、模型、集成、状态和原语
5. 指出任何问题（未配置的集成、缺失的模型、硬编码的密钥）

可用文档

文档应位于相对于此技能的 ./references/ 目录中。回答问题时，请搜索以下主题：

核心概念

• actions.md - 具备强类型和验证的操作
• tools.md - 可由 AI 调用的工具和 Autonomous 命名空间
• autonomous-execution.md - 高级 execute() API：对象、退出、钩子、配置
• workflows.md - 工作流和基于步骤的执行
• workflow-steps.md - 完整的工作流步骤 API 参考（step.request、step.map、step.notify 等）
• conversations.md - 对话处理器、消息路由，以及接收 chat:custom 事件
• conversation-lifecycle.md - 对话的提醒/过期生命周期管理
• triggers.md - 集成和机器人生命周期事件订阅（应用推送的自定义事件 → conversations.md）
• messages.md - 发送消息和事件
• custom-components.md - 自定义 Web 聊天组件（.bp.tsx 文件、元数据、在对话中的用法）

Zai（AI 操作）

• zai-agent-reference.md - 快速参考：所有操作、Zai 可解决的日常问题、边缘情况和注意事项
• zai-complete-guide.md - 完整开发者指南：架构、主动学习、分块、性能调优

数据和内容

• tables.md - 使用语义搜索进行数据存储
• files.md - 文件存储和管理
• knowledge-bases.md - RAG 实现
• assets.md - 具有永久 URL 和同步生命周期的静态文件

配置和集成

• agent-config.md - 机器人配置和状态管理
• explain-config.md - 如何向开发者解读和说明 Agent 的配置
• model-configuration.md - AI 模型配置参考
• context-api.md - 运行时上下文访问
• integration-actions.md - 使用集成操作
• tags.md - 机器人、用户、对话和工作流的实体标签
• cli.md - 完整的 CLI 命令参考
• mcp-server.md - 面向 AI 助手的 MCP 服务
• desk.md - 用于工单/支持工作流的 Desk 集成
• integrations.md - 集成管理概述（指向 adk-integrations 技能）
• interfaces.md - 构建于集成之上的内置接口抽象层（输入指示器、LLM、可列举）
• plugins.md - 插件使用：发现、安装、配置和使用

模式和最佳实践

• advanced-patterns.md - 防护措施、管理员身份验证、日志记录/可观测性、扩展组合
• patterns-mistakes.md - 常见错误、正确模式和上下文访问参考

前端集成

注意： 前端集成文档位于独立的 adk-frontend 技能中。使用 npx skills add botpress/skills --skill adk-frontend 安装。adk-frontend 技能涵盖 @botpress/client、调用操作、类型生成和身份验证。如果你要编写任何前端代码，就需要它。

评估

注意： 详细的评估文档位于独立的 adk-evals 技能中。使用 npx skills add botpress/skills --skill adk-evals 安装。adk-evals 技能涵盖编写评估、断言类型、测试工作流和 CLI 用法。通常你总是需要它来进行测试和评估。

运行时访问模式

访问 ADK 运行时服务的快速参考：

导入

// Always import from @botpress/runtime
import {
  Action,
  Autonomous,
  Workflow,
  Conversation,
  z,
  actions,
  adk,
  user,
  bot,
  conversation,
  configuration,
  context,
} from '@botpress/runtime'

状态管理

// Bot state (defined in agent.config.ts)
bot.state.maintenanceMode = true
bot.state.lastDeployedAt = new Date().toISOString()

// User state (defined in agent.config.ts)
user.state.preferredLanguage = 'en'
user.state.onboardingComplete = true

// User tags
user.tags.email // Access user metadata

调用操作

// Call bot actions
await actions.fetchUser({ userId: '123' })
await actions.processOrder({ orderId: '456' })

// Call integration actions
await actions.slack.sendMessage({ channel: '...', text: '...' })
await actions.linear.issueList({ teamId: '...' })

// Convert action to tool
tools: [fetchUser.asTool()]

上下文 API

// Get runtime services
const client = context.get('client') // Botpress client
const cognitive = context.get('cognitive') // AI model client
const citations = context.get('citations') // Citation manager

文件命名

• Actions/Tools/Workflows：myAction.ts、searchDocs.ts（驼峰命名）
• Tables：Users.ts、Orders.ts（帕斯卡命名）
• Conversations/Triggers：chat.ts、slack.ts（小写）

ADK 关键模式（回答时始终参考）

回答问题时，务必根据文档核实以下模式：

包管理

# All package managers are supported
bun install       # Recommended (fastest)
npm install       # Works fine
yarn install      # Works fine
pnpm install      # Works fine

# ADK auto-detects based on lock files
# - bun.lockb → uses bun
# - package-lock.json → uses npm
# - yarn.lock → uses yarn
# - pnpm-lock.yaml → uses pnpm

导入

// ✅ CORRECT - Always from @botpress/runtime
import { Action, Autonomous, Workflow, z } from '@botpress/runtime'

// ❌ WRONG - Never from zod or @botpress/sdk
import { z } from 'zod' // ❌ Wrong
import { Action } from '@botpress/sdk' // ❌ Wrong

导出模式

// ✅ Both patterns work - export const is recommended
export const myAction = new Action({ ... });  // Recommended
export default new Action({ ... });           // Also valid

// Why export const?
// - Enables direct imports: import { myAction } from "./actions/myAction"
// - Can pass to execute(): tools: [myAction.asTool()]

操作

// ✅ CORRECT - Handler receives { input, client }
export const fetchUser = new Action({
  name: "fetchUser",
  async handler({ input, client }) {  // ✅ Destructure from props
    const { userId } = input;         // ✅ Then destructure fields
    return { name: userId };
  }
});

// ❌ WRONG - Cannot destructure input fields directly
handler({ userId }) {  // ❌ Wrong - must be { input }
  return { name: userId };
}

工具

// ✅ CORRECT - Tools CAN destructure directly
export const myTool = new Autonomous.Tool({
  handler: async ({ query, maxResults }) => {
    // ✅ Direct destructuring OK
    return search(query, maxResults)
  },
})

对话

// ✅ CORRECT - Use conversation.send() method
await conversation.send({
  type: "text",
  payload: { text: "Hello!" }
});

// ❌ WRONG - Never use client.createMessage() directly
await client.createMessage({ ... });  // ❌ Wrong

对话处理器类型

// Handler receives typed context based on the event type:
// type: "message" | "event" | "workflow_request" | "workflow_callback"
async handler({ type, message, event, request, completion, conversation, execute }) {
  if (type === "workflow_request") {
    // event: WorkflowDataRequestEventType, request: WorkflowRequest
    await request.workflow.provide("email", { email: "..." });
  }
  if (type === "workflow_callback") {
    // event: WorkflowCallbackEventType, completion: WorkflowCallback
    console.log(completion.status); // "completed" | "failed" | "canceled" | "timed_out"
  }
}

// ⚠️ isWorkflowDataRequest() and isWorkflowCallback() are deprecated
// Use type === "workflow_request" / "workflow_callback" instead

此技能可回答的问题示例

初学者问题

• “什么是 Action？”
• “如何创建我的第一个工作流？”
• “Action 和工具有什么区别？”

实现问题

• “如何访问 Botpress 客户端？”
• “如何在 RAG 中使用引用？”
• “可搜索表格列的语法是什么？”
• “如何调用 Slack 集成 Action？”
• “如何使用 Zai 提取结构化数据？”
• “如何使用 Zai 验证内容？”

高级模式问题

• “如何添加护栏以防止幻觉？”
• “如何实现管理员身份验证？”
• “如何添加日志记录和可观测性？”
• “如何组合多个扩展？”
• “如何在异步工具处理程序中管理上下文？”

故障排除问题

• “为什么我会收到 ‘Cannot destructure property’ 错误？”
• “如何修复导入错误？”
• “工作流状态访问有什么问题？”

最佳实践问题

• “有哪些常见错误需要避免？”
• “我应该如何组织项目？”
• “X 的推荐模式是什么？”

回复格式

回复的详略程度应与问题的深度相匹配。 并非每个问题都需要完整的逐步讲解。

概念性问题（“X 是什么？”、“X 和 Y 有什么区别？”）

一句话定义 + 一个简短的代码示例。仅此而已。

Knowledge bases add RAG to your bot — place markdown or PDF files in `src/knowledge/` and they become queryable with semantic search.

import { Autonomous } from '@botpress/runtime'
export default new Autonomous.Tool({
  handler: async ({ query }) => adk.knowledgeBase.search({ query }),
})

操作指南类问题（“如何创建 X？”、“如何使用 X？”）

简要说明 + 可运行的代码示例；只有在存在常见陷阱时，才指出一个关键注意事项。

实现问题（“在我的项目中实现 X”、“将 X 添加到我的机器人”）

先阅读用户现有的文件（src/actions/、src/tools/、src/tables/、agent.config.ts）。生成使用其实际名称、模式和约定的代码。仅提及根据其特定代码，他们可能遇到的注意事项。

架构问题（“解释我的机器人”、“X 在我的项目中如何运作？”）

给出完整的结构化回复：读取 adk status --format json、agent.config.ts 和相关源文件。梳理数据流，并识别机器人的类型（RAG 助手、客服 Agent、自动化等）。

故障排除问题（“X 出问题了”、“为什么 X 失败了？”）

不要用文档内容来回答。运行 adk check --format json 和 adk logs error --format json，展示证据，并指出根本原因。按照 adk-debugger 技能中的调试循环操作。

默认规则

如果一句话和一个代码片段就能回答问题，就不要添加标题、注意事项部分或相关主题。结构更多 ≠ 更有帮助。