在 Botpress ADK 项目中开发/调试/解释/部署…

当你需要构建、查询、调试、解释或部署 Botpress ADK Bot 的 actions/tools/workflows/conversations/tables/integrations/plugins/Zai 等功能时使用。

适用场景

解决思路

1. 遵循约定式 TypeScript 结构，将大多数 primitives 放在 `src/` 目录：`src/actions/`（强类型函数，自动注册）、`src/tools/`（AI 可调用工具，可通过 `execute()` 使用）、`src/workflows/`（长时间运行、可恢复/可调度流程）、`src/conversations/`（消息处理器，按 channel 路由）、`src/tables/`（数据库 schema，自动创建并带搜索）、`src/triggers/`（事件处理器，订阅事件）、`src/knowledge/`（知识库，RAG 语义搜索）、`src/utils/`（共享辅助，不自动注册）；`assets/` 放在项目根目录，同步到 Botpress Cloud 并提供永久 URL；`.adk/dependencies/` 包含生成的 `dev.json`、`prod.json`、`migration.json`；`.agent0/capabilities/` 是项目本地 Agent(0) capability bundle；`agent.config.ts` 是 bot 配置。
2. 注意 `src/` 之外的文件不会被发现；位置=行为。
3. 通过 `adk integrations` / `adk plugins` CLI 或 Dev Console 管理 integrations 和 plugins；Botpress Cloud 是 source of truth；`.adk/dependencies/` 是生成的本地快照，用于快速/离线读取，不要手动编辑。
4. 首次在 session 中帮助 ADK 项目时，静默运行 `adk check --format json` 和 `adk status --format json` 检查项目健康。
5. `adk check` 验证 primitives 但不做类型检查，所以还要运行 `tsc --noEmit` 捕获类型错误。
6. 如果检查发现错误或警告（未配置 integrations、缺失 models、验证问题），在回答用户前主动说：“Before we start — I noticed [issue]. Want me to help fix that?”
7. 每个 session 只做一次健康检查，不要每个问题都重跑。
8. 如果用户问 “what can you help with?”、“what commands are available?” 或调用 `/adk-explain` 无参数，展示命令：Build: `/adk-init`、`/adk-build`、`/adk-integration`、`/adk-frontend`；Test & Debug: `/adk-validate`、`/adk-test`、`/adk-eval`、`/adk-debug`；Ship: `/adk-ship`；Document: `/adk-document`；Understand: `/adk-explain`、`/adk-dev-console`。然后问：“What are you working on?”
9. 如果在 Claude Code 中 `/adk-*` 命令不可用为 slash commands，建议安装 Botpress ADK plugin：`/plugin marketplace add botpress/skills` 和 `/plugin install adk@botpress-skills`；每个 session 只建议一次，用户拒绝后不再问。
10. 对于 integration discovery 和 CLI 查询，用 Bash tool 直接运行：`adk integrations search <query>`；`adk integrations search --interface <interface-name>`；`adk integrations info <integration-name>`；`adk integrations list`（必须位于 ADK 项目）。
11. 项目信息查询运行：`adk --version`；`adk`（显示项目状态）；`adk --help`。
12. 驱动 ADK 工作流时优先使用非交互路径：`adk login --token "$BOTPRESS_TOKEN"`；`adk init my-agent --yes --skip-link`；`adk link --workspace ws_123 --bot bot_456`；`adk dev --non-interactive`；`adk project upgrade --dry-run`；`adk project upgrade`；`adk deploy --yes`。
13. 优先 `adk login --token "$BOTPRESS_TOKEN"` 或 `adk login --token <token>` 而不是交互式登录。
14. 将裸 `BOTPRESS_TOKEN` 视为 no-TTY convenience，不是保证的交互式终端捷径。
15. 优先 `adk init <name> --yes --skip-link` 用于 AI 驱动脚手架，但仅在登录完成后。
16. 将 `adk link --workspace ... --bot ...` 视为可脚本化，但不保证在每个 no-TTY 环境安全。
17. 将 `adk dev --non-interactive` 视为 CI-friendly，不是完全无提示。
18. 将 `adk deploy --yes` 视为自动批准非破坏性 deploy-plan changes；config validation 和 destructive storage changes 仍可能阻止自动化。
19. 如果项目命令报告 runtime/package mismatch，先运行 `adk project upgrade --dry-run`，再运行 `adk project upgrade` 应用兼容补丁。
20. CLI 查询响应模式：用 Bash tool 运行合适的 `adk` 命令；解析并呈现输出；可选建议下一步，例如 “Run `adk integrations add slack@3.0.0` to install”。
21. 对于文档、模式和 how-to 问题，搜索并直接引用文档文件：用 Glob 发现文档，pattern 为 `**/references/*.md`。
22. 用 Grep 找相关关键词，pattern 为 `<keyword from user question>`，path 为 `<path to references directory from step 1>`，output_mode 为 `files_with_matches`。
23. 用 Read 加载相关文档。
24. 提供答案时包含：简洁解释；来自 references 的代码示例；文件引用带行号，例如 “From references/actions.md:215”；相关时给常见陷阱；相关主题供进一步阅读。
25. 对于配置解释问题，运行 `adk status --format json` 获取结构化项目概览；读取 `agent.config.ts` 获取完整配置细节；遵循 `references/explain-config.md` 中的解释模式；生成结构化解释，覆盖 metadata、models、integrations、state 和 primitives；标记任何问题（未配置 integrations、缺失 models、硬编码 secrets）。
26. 如果触及任何前端代码，安装 `adk-frontend` skill：`npx skills add botpress/skills --skill adk-frontend`；它涵盖 `@botpress/client`、调用 actions、类型生成和认证。
27. 对于测试和评估，安装 `adk-evals` skill：`npx skills add botpress/skills --skill adk-evals`；它涵盖编写 evals、断言类型、测试工作流和 CLI 用法，通常总是需要。
28. 使用运行时导入模式：始终从 `@botpress/runtime` 导入 `Action`、`Autonomous`、`Workflow`、`Conversation`、`z`、`actions`、`adk`、`user`、`bot`、`conversation`、`configuration`、`context`。
29. 状态管理：使用 `bot.state.maintenanceMode = true`、`bot.state.lastDeployedAt = new Date().toISOString()`；使用 `user.state.preferredLanguage = 'en'`、`user.state.onboardingComplete = true`；用 `user.tags.email` 访问用户元数据。
30. 调用 actions：使用 `await actions.fetchUser({ userId: '123' })`、`await actions.processOrder({ orderId: '456' })`；调用 integration actions：`await actions.slack.sendMessage({ channel: '...', text: '...' })`、`await actions.linear.issueList({ teamId: '...' })`；将 action 转为 tool：`tools: [fetchUser.asTool()]`。
31. Context API：使用 `context.get('client')` 获取 Botpress client；`context.get('cognitive')` 获取 AI model client；`context.get('citations')` 获取 Citation manager。
32. 文件命名：Actions/Tools/Workflows 用 `myAction.ts`、`searchDocs.ts`（camelCase）；Tables 用 `Users.ts`、`Orders.ts`（PascalCase）；Conversations/Triggers 用 `chat.ts`、`slack.ts`（lowercase）。
33. 包管理：支持所有包管理器：`bun install`（推荐，最快）、`npm install`、`yarn install`、`pnpm install`；ADK 根据 lock files 自动检测：`bun.lockb` → bun；`package-lock.json` → npm；`yarn.lock` → yarn；`pnpm-lock.yaml` → pnpm。
34. 导入正确性：始终从 `@botpress/runtime` 导入；不要从 `zod` 或 `@botpress/sdk` 导入。
35. 导出模式：`export const myAction = new Action({ ... });` 推荐；`export default new Action({ ... });` 也有效；用 `export const` 支持直接导入 `import { myAction } from "./actions/myAction"`，并可传给 `execute()`：`tools: [myAction.asTool()]`。
36. Actions handler 正确写法：handler 接收 `{ input, client }`，从 props 解构；然后从 `input` 解构字段；不要直接解构 input 字段，例如 `handler({ userId })` 是错误写法。
37. Tools handler 正确写法：Tools 可以直接解构：`handler: async ({ query, maxResults }) => { ... }`。
38. Conversations 正确写法：使用 `conversation.send({ type: "text", payload: { text: "Hello!" } });`；不要直接使用 `client.createMessage()`。
39. Conversation handler 类型：handler 根据事件类型接收 typed context：`type: "message" | "event" | "workflow_request" | "workflow_callback"`；如果 `type === "workflow_request"`，用 `await request.workflow.provide("email", { email: "..." });`；如果 `type === "workflow_callback"`，用 `console.log(completion.status);`，状态为 `"completed" | "failed" | "canceled" | "timed_out"`；不要用已弃用的 `isWorkflowDataRequest()` 和 `isWorkflowCallback()`，改用 `type === "workflow_request"` / `type === "workflow_callback"`。
40. 响应深度匹配问题深度：概念问题（“what is X?”、“what's the difference between X and Y?”）只给一句话定义 + 一个短代码示例。
41. How-To 问题：简要解释 + 工作代码示例 + 仅在常见陷阱时提一个关键陷阱。
42. Implementation 问题（“implement X in my project”、“add X to my bot”）：先读用户已有文件（`src/actions/`、`src/tools/`、`src/tables/`、`agent.config.ts`）；生成使用他们实际名称、模式和约定的代码；只提他们特定代码可能遇到的陷阱。
43. Architecture 问题（“explain my bot”、“how does X work in my project?”）：完整结构化响应：读 `adk status --format json`、`agent.config.ts` 和相关源文件；映射数据流并识别 bot 的 archetype（RAG assistant、support agent、automation 等）。
44. Troubleshooting 问题（“X is broken”、“why is X failing?”）：不要用文档回答；运行 `adk check --format json` 和 `adk logs error --format json`；展示证据并指出根因；遵循 `adk-debugger` skill 的 debug loop。
45. 默认规则：如果答案能放在一句话和代码片段中，不要加 headers、pitfall sections 或 related topics；更多结构 ≠ 更有帮助。
46. 回答文档问题时，在 `./references/` 中查找这些文档：actions.md、tools.md、autonomous-execution.md、workflows.md、workflow-steps.md、conversations.md、conversation-lifecycle.md、triggers.md、messages.md、custom-components.md、zai-agent-reference.md、zai-complete-guide.md、tables.md、files.md、knowledge-bases.md、assets.md、agent-config.md、explain-config.md、model-configuration.md、context-api.md、integration-actions.md、tags.md、cli.md、mcp-server.md、desk.md、integrations.md、interfaces.md、plugins.md、advanced-patterns.md、patterns-mistakes.md。

适用边界 · 注意事项

• 不适用于非 Botpress ADK 项目。
• 不适用于无法使用 Botpress Cloud 或无法登录 Botpress 账号的场景。
• 不适用于要求所有命令完全无提示且无法处理 no-TTY 环境限制的场景；某些 ADK 命令不保证完全无提示，破坏性 storage changes 仍可能阻止自动化。