在 Kapso 上构建、调试和部署 WhatsApp…

适用于在 Kapso 平台上创建或调试 WhatsApp 自动化工作流、触发器、Project Events、函数和执行。

适用场景

解决思路

1. 优先使用本地源码编辑路径：安装 Kapso CLI `npm install -g @kapso/cli`，安装 `@kapso/workflows` `npm install --save-dev @kapso/workflows`，执行 `kapso login`，执行 `kapso link --project <project-id>`，执行 `kapso pull`。
2. 在 `workflows/<workflow-slug>/workflow.js` 或 `workflow.ts` 中用 `@kapso/workflows` 编辑工作流：从 `@kapso/workflows` 导入 `START, Workflow`，用 `new Workflow("inbound-support", { name: "Inbound Support", status: "draft" })` 创建工作流，用 `workflow.addTrigger({ type: "inbound_message", phoneNumberId: "<phone-number-id>" })` 添加触发器，用 `workflow.addNode(START, { position: { x: 100, y: 100 } })` 加开始节点，用 `workflow.addNode("reply", { type: "send_text", message: "Thanks for reaching out." })` 加发送文本节点，用 `workflow.addEdge(START, "reply")` 连边，并导出 `Workflow` 实例。
3. 构建并推送：`kapso build`，`kapso push --dry-run`，`kapso push workflow <workflow-slug>`；`kapso push` 用于推送所有本地函数和工作流；详见 `references/local-workflow-source.md`，其中包含仓库布局、源文件行为和仅 JSON 编辑。
4. 如果无法用本地源码路径，则回退到环境变量：设置 `KAPSO_API_BASE_URL`（仅主机，不带 `/platform/v1`）和 `KAPSO_API_KEY`。
5. 先发现电话号码：优先执行 `kapso status`，再执行 `kapso whatsapp numbers list --output json`，需要时执行 `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json`；回退为 `node scripts/list-whatsapp-phone-numbers.js`。
6. 通过 API 脚本编辑工作流图时，优先本地源码同步；这些脚本作为调试、直接图检查或仅 API 环境的回退：1) `node scripts/get-graph.js <workflow_id>` 并记录 `lock_version`；2) 编辑 JSON；3) `node scripts/validate-graph.js --definition-file <path>`；4) `node scripts/update-graph.js <workflow_id> --expected-lock-version <n> --definition-file <path>`；5) 重新拉取确认。小改动用 `edit-graph.js --old-file` 和 `--new-file`。若遇 lock_version 冲突：重新拉取、重新应用更改、用新 lock_version 重试。
7. 管理触发器：列出 `node scripts/list-triggers.js <workflow_id>`；创建 `node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>`；切换 `node scripts/update-trigger.js --trigger-id <id> --active true|false`；删除 `node scripts/delete-trigger.js --trigger-id <id>`。
8. 对 `inbound_message` 触发器，优先用 `kapso whatsapp numbers resolve --phone-number "<display-number>" --output json` 取得精确 `phone_number_id`；CLI 不可用时回退到 `node scripts/list-whatsapp-phone-numbers.js`。
9. 对 `project_event` 触发器，若用户正在定义事件类型/schema，先注册或更新 Project Event 定义：`node scripts/project-event-definitions.js create --name conversation.csat_scored --description "Customer satisfaction score for a conversation" --property-schema '{"score":{"type":"number"},"reason":{"type":"string"}}'`；然后创建触发器：`node scripts/create-trigger.js <workflow_id> --trigger-type project_event --triggerable-attributes '{"event_name":"conversation.csat_scored","property_key":"score","operator":"gte","property_value":4}'`。定义只是元数据；除非用户明确接受副作用，不要仅为注册名称而发出示例事件。
10. 管理 Project Event 定义：定义用于事件名称、描述和扁平标量属性 schema；发出的事件是独立记录，由 `POST /platform/v1/events`、`emit_event` 节点、Function 节点 `project_events` 或 Agent 节点 `emit_event` 创建。列出 `node scripts/project-event-definitions.js list`；按名称创建/更新 `node scripts/project-event-definitions.js create --name <event.name> [--description <text>] [--property-schema <json>]`；按 ID 更新 `node scripts/project-event-definitions.js update --definition-id <id> [--name <event.name>] [--description <text>] [--property-schema <json>]`。
11. 当工作流需要记住或响应持久业务事实时，按 Project Events 清单构建：1) 引入新事件名或 schema 时先定义事件；2) 工作流应响应已发出事件时用 `project_event` 触发器；3) 确定性工作流步骤发出用 `emit_event` 节点；4) 发出依赖函数代码输出时用 Function 节点 `project_events`；5) 仅当 Agent 应决定是否/何时记录事实时用 Agent 节点 `emit_event`，并启用 `emit_event` 默认工具、在依赖前配置允许的事件定义。由 Project Event 触发的工作流是观察者，不能发出 Project Events；不要给从 Project Event 触发器启动的工作流添加事件发出。
12. 调试执行：有 execution ID 时先搜索工作流日志：`kapso logs search --query "<execution-id>" --source flow_event --filter flow_execution_id=<execution-id> --period 7d --limit 20 --output json`；列出 `node scripts/list-executions.js <workflow_id>`；检查 `node scripts/get-execution.js <execution-id>`；获取值 `node scripts/get-context-value.js <execution-id> --variable-path vars.foo`；列出事件 `node scripts/list-execution-events.js <execution-id>`。
13. 创建和部署函数：1) 按 handler 签名写代码；2) `node scripts/create-function.js --name <name> --code-file <path> [--public-endpoint true]`；3) `node scripts/deploy-function.js --function-id <id>`；4) `node scripts/get-function.js --function-id <id>`。当函数应无需 `X-API-Key` 通过 Kapso 托管 invoke URL 调用时用 `--public-endpoint true`；仅 Cloudflare 函数支持。新函数默认 `invoke_response_mode=passthrough`，成功 invoke 时直接返回函数体；旧 wrapped 函数可稍后用 `update-function.js` 迁移。
14. 为 Agent 节点配置远程 sandbox 仓库：1) 阅读 `references/agent-remote-sandbox.md`；2) 查找模型 `node scripts/list-provider-models.js`；3) 复制 `assets/agent-remote-sandbox-github-repo-example.json` 作为起点，或编辑 `data.config` 下的 agent 节点；4) 设置 `sandbox_enabled: true`；5) 设置 `sandbox_network_mode` 为 `allow_all` 或 `allow_list`；6) 若用 `allow_list`，在 `sandbox_allowed_outbound_hosts` 加额外出站主机；7) 向 `flow_agent_resources` 添加 GitHub 仓库，含 `resource_type: "github_repository"`、`repo_url`、`branch`、`pat`；8) 写系统提示，明确先读取 `/workspace/repos/<repo-slug>` 再做更改；9) 验证并更新图。注意：远程 sandbox 是 beta 且 beta 期间免费；`sandbox_enabled` 控制远程工作区和 sandbox 工具是否可用；之后关闭 sandbox 访问时仓库资源配置仍保留；v1 仅支持 GitHub 仓库；使用仓库根 URL，不用 GitHub 文件 URL 或 `tree/...` URL；仓库挂载到远程 sandbox 内 `/workspace/repos/<repo-slug>`；精确形状用 `references/agent-remote-sandbox.md` 和 `references/node-types.md`。
15. 遵守图规则：恰好一个开始节点且 `id`=`start`；绝不更改现有节点 ID；新节点 ID 用 `{node_type}_{timestamp_ms}`；非 decide 节点有 0 或 1 条出向 `next` 边；decide 边标签必须匹配 `conditions[].label`；边键用 `source`/`target`/`label`（不是 `from`/`to`）。完整 schema 见 `references/graph-contract.md`。
16. 遵守函数规则：使用 `async function handler(request, env) { ... }`；用 `const body = await request.json();` 解析输入；按需使用 `env.KV` 和 secrets；返回 `new Response(JSON.stringify({ result: "ok" }))`；不要使用 `export`、`export default` 或箭头函数；必须返回 `Response` 对象。
17. 使用执行上下文结构：`vars` 用户定义变量；`system` 系统变量；`context` 渠道数据；`metadata` 请求元数据。
18. 工作流脚本：`list-workflows.js` 列出工作流（仅元数据）；`get-workflow.js` 获取工作流元数据；`create-workflow.js` 创建工作流；`update-workflow-settings.js` 更新工作流设置。
19. 图脚本：`get-graph.js` 获取工作流图和 `lock_version`；`edit-graph.js` 通过字符串替换补丁图；`update-graph.js` 替换整个图；`validate-graph.js` 本地验证图结构。
20. 触发器脚本：`list-triggers.js` 列出工作流触发器；`create-trigger.js` 创建触发器；`update-trigger.js` 启用/禁用触发器；`delete-trigger.js` 删除触发器；`list-whatsapp-phone-numbers.js` 列出用于触发器设置的电话号码。
21. Project Events 脚本：`project-event-definitions.js` 列出、创建或更新 Project Event 定义。
22. 执行脚本：`list-executions.js` 列出执行；`get-execution.js` 获取执行详情；`get-context-value.js` 从执行上下文读取值；`update-execution-status.js` 强制执行状态；`resume-execution.js` 恢复等待中的执行；`list-execution-events.js` 列出执行事件。
23. 函数脚本：`list-functions.js` 列出项目函数；`get-function.js` 获取函数详情和代码；`create-function.js` 创建函数，可选带公共 invoke 端点；`update-function.js` 更新函数代码、公共端点设置，或将旧 wrapped 函数迁移到 passthrough；`deploy-function.js` 部署函数到运行时；`invoke-function.js` 用 payload 调用函数；`list-function-invocations.js` 列出函数调用。
24. OpenAPI 脚本：`openapi-explore.mjs` 探索 OpenAPI（search/op/schema/where）；一次性安装依赖 `npm i`；示例 `node scripts/openapi-explore.mjs --spec workflows search "variables"`；`node scripts/openapi-explore.mjs --spec workflows op getWorkflowVariables`。
25. 注意：优先使用文件路径而非内联 JSON（`--definition-file`、`--code-file`）；调试工作流同时涉及 API 调用、Meta 事件或 webhook 投递时，用 `observe-whatsapp` 做跨源 Logs 搜索；变量 CRUD（`variables-set.js`、`variables-delete.js`）被阻止，Platform API 不支持。
26. 按正在更改的操作阅读 references：本地工作流源编辑和 CLI 同步读 `references/local-workflow-source.md`；图编辑 schema、计算字段 vs 可编辑字段、lock_version 读 `references/graph-contract.md`；添加或更改节点配置读 `references/node-types.md`；执行行为、状态变化、恢复读 `references/workflow-overview.md`。仅函数工作时读函数 references；若工作流也变则需图/源码 references。其他任务特定 references：执行上下文读 `references/execution-context.md`；触发器类型和设置读 `references/triggers.md`；远程 sandbox 行为、仓库资源、挂载路径读 `references/agent-remote-sandbox.md`；函数管理读 `references/functions-reference.md`；函数 payload 形状读 `references/functions-payloads.md`。
27. 使用 assets：`workflow-linear.json` 最小线性工作流；`workflow-decision.json` 最小分支工作流；`workflow-agent-simple.json` 最小 agent 工作流；`workflow-customer-support-intake-agent.json` 客户支持受理；`workflow-interactive-buttons-decide-function.json` 交互按钮 + decide（函数）；`workflow-interactive-buttons-decide-ai.json` 交互按钮 + decide（AI）；`workflow-api-template-wait-agent.json` API 触发器 + 模板 + agent；`function-decide-route-interactive-buttons.json` 按钮路由函数；`agent-remote-sandbox-github-repo-example.json` 带远程 sandbox + GitHub 仓库资源的 agent 节点。

适用边界 · 注意事项

• 没有 Kapso 账号、项目、CLI 登录态或 API Key 时不要使用。
• 不要把它当作非 Kapso 平台的通用 WhatsApp 自动化或直接 Meta Graph API 集成指南。
• 不要用 `variables-set.js` / `variables-delete.js` 做变量 CRUD，Platform API 不支持。