kapso-automation

Kapso 自动化

适用场景

使用此技能构建和运行 Kapso 自动化：工作流的增删改查、图编辑、触发器、执行、函数管理以及 D1 数据库操作。

设置

环境变量：

• KAPSO_API_BASE_URL（仅主机名，不含 /platform/v1）
• KAPSO_API_KEY

使用方法

编辑工作流图

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 重试。

管理触发器

1. 列出：node scripts/list-triggers.js <workflow_id>
2. 创建：node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>
3. 切换：node scripts/update-trigger.js --trigger-id <id> --active true|false
4. 删除：node scripts/delete-trigger.js --trigger-id <id>

对于 inbound_message 触发器，先运行 node scripts/list-whatsapp-phone-numbers.js 获取 phone_number_id。

调试执行

1. 列出：node scripts/list-executions.js <workflow_id>
2. 检查：node scripts/get-execution.js <execution-id>
3. 获取值：node scripts/get-context-value.js <execution-id> --variable-path vars.foo
4. 事件：node scripts/list-execution-events.js <execution-id>

创建并部署函数

1. 使用处理函数签名编写代码（参见下方的函数规则）
2. 创建：node scripts/create-function.js --name <name> --code-file <path>
3. 部署：node scripts/deploy-function.js --function-id <id>
4. 验证：node scripts/get-function.js --function-id <id>

设置带应用集成的 Agent 节点

1. 查找模型：node scripts/list-provider-models.js
2. 查找账户：node scripts/list-accounts.js --app-slug <slug>（使用 pipedream_account_id）
3. 查找操作：node scripts/search-actions.js --query <word> --app-slug <slug>（action_id = key）
4. 创建集成：node scripts/create-integration.js --action-id <id> --app-slug <slug> --account-id <id> --configured-props <json>
5. 通过 flow_agent_app_integration_tools 向 Agent 节点添加工具

数据库增删改查

1. 列出表：node scripts/list-tables.js
2. 查询：node scripts/query-rows.js --table <name> --filters <json>
3. 使用行脚本创建、更新和删除

图规则

• 必须恰有一个起始节点，其 id = start
• 不要更改现有节点 ID
• 新节点 ID 使用 {node_type}_{timestamp_ms}
• 非 decide 节点有 0 或 1 条出边 next
• Decide 边标签必须与 conditions[].label 匹配
• 边的键为 source/target/label（不是 from/to）

完整的架构详情请参见 references/graph-contract.md。

函数规则

async function handler(request, env) {
  // Parse input
  const body = await request.json();
  // Use env.KV and env.DB as needed
  return new Response(JSON.stringify({ result: "ok" }));
}

• 不要使用 export、export default 或箭头函数
• 返回一个 Response 对象

执行上下文

始终使用以下结构：

• vars - 用户定义的变量
• system - 系统变量
• context - 渠道数据
• metadata - 请求元数据

脚本

工作流

脚本	用途
list-workflows.js	列出工作流（仅元数据）
get-workflow.js	获取工作流元数据
create-workflow.js	创建工作流
update-workflow-settings.js	更新工作流设置

图

脚本	用途
get-graph.js	获取工作流图和 lock_version
edit-graph.js	通过字符串替换修补图
update-graph.js	替换整个图
validate-graph.js	在本地验证图结构

触发器

脚本	用途
list-triggers.js	列出工作流的触发器
create-trigger.js	创建触发器
update-trigger.js	启用／禁用触发器
delete-trigger.js	删除触发器
list-whatsapp-phone-numbers.js	列出用于设置触发器的电话号码

执行

脚本	用途
list-executions.js	列出执行记录
get-execution.js	获取执行详情
get-context-value.js	读取执行上下文中的值
update-execution-status.js	强制更改执行状态
resume-execution.js	恢复等待中的执行
list-execution-events.js	列出执行事件

函数

脚本	用途
list-functions.js	列出项目函数
get-function.js	获取函数详情和代码
create-function.js	创建函数
update-function.js	更新函数代码
deploy-function.js	将函数部署到运行时
invoke-function.js	使用负载调用函数
list-function-invocations.js	列出函数调用记录

应用集成

脚本	用途
list-apps.js	搜索集成应用
search-actions.js	搜索操作（action_id = key）
get-action-schema.js	获取操作的 JSON 架构
list-accounts.js	列出已连接的账户
create-connect-token.js	创建 OAuth 连接链接
configure-prop.js	解析属性的 remote_options
reload-props.js	重新加载动态属性
list-integrations.js	列出已保存的集成
create-integration.js	创建集成
update-integration.js	更新集成
delete-integration.js	删除集成

数据库

脚本	用途
list-tables.js	列出 D1 表
get-table.js	获取表架构和示例行
query-rows.js	使用筛选条件查询行
create-row.js	创建行
update-row.js	更新行
upsert-row.js	插入或更新行
delete-row.js	删除行

注意事项

• 优先使用文件路径，而不是内联 JSON（--definition-file、--code-file）
• action_id 与 search-actions 返回的 key 相同
• --account-id 使用 list-accounts 返回的 pipedream_account_id
• 变量的增删改查（variables-set.js、variables-delete.js）不可用——Platform API 不支持
• Platform API 不支持执行原始 SQL

参考资料

编辑前请阅读：

• references/graph-contract.md - 图结构架构、计算字段与可编辑字段、lock_version
• references/node-types.md - 节点类型和配置结构
• references/workflow-overview.md - 执行流程和状态

其他参考资料：

• references/execution-context.md - 上下文结构和变量替换
• references/triggers.md - 触发器类型和设置
• references/app-integrations.md - 应用集成和 variable_definitions
• references/functions-reference.md - 函数管理
• references/functions-payloads.md - 函数的负载结构
• references/databases-reference.md - 数据库操作

资源

文件	说明
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-app-integration-example.json	带有应用集成的 Agent 节点

相关技能

• whatsapp-messaging - WhatsApp 消息和模板
• whatsapp-flows - WhatsApp Flows
• kapso-api - 平台 API 和客户