superplane-monitor

SuperPlane Monitor

检查、调试和管理工作流执行。

快速参考

任务	命令
列出应用的运行记录	superplane runs list --app-id <id>
查看运行记录（节点执行情况）	superplane runs describe <run-id> --app-id <id>
列出节点执行记录	superplane executions list --app-id <id> --node-id <nid>
取消执行	superplane executions cancel --app-id <id> --execution-id <eid>
列出排队项	superplane queue list --app-id <id> --node-id <nid>
删除排队项	superplane queue delete --app-id <id> --node-id <nid> --item-id <iid>

确认 CLI 已安装

开始任何调试前，请确认 CLI 二进制文件可用，且无需网络访问：

command -v superplane

如果没有输出路径，请停止并告知用户从 https://docs.superplane.com/installation/cli 安装 CLI。调试需要使用 CLI 检查运行记录、执行记录和队列。

然后验证当前会话：

superplane whoami

如果 whoami 因身份验证、DNS、超时或连接问题而失败，说明 CLI 已安装，但当前会话尚不可用。请告知用户在通过 CLI 调试前，先连接、修正上下文，或根据需要允许网络访问。

如果调试需要编辑画布，请暂存更改并提交，或使用 --message 直接应用：

superplane apps staging update --file canvas.yaml
superplane apps staging commit --message "Fix canvas"
# or:
superplane apps canvas update -f canvas.yaml --message "Fix canvas"

调试工作流

1. 查找应用

superplane apps list

2. 列出最近的运行记录

superplane runs list --app-id <app_id>

每条运行记录都表示一次触发器沿完整画布执行的过程。

3. 检查运行记录

superplane runs describe <run_id> --app-id <app_id>

查找以下节点执行记录：

• Failed — 出错的节点
• Pending/Running — 可能卡住的节点
• Skipped — 被分支（If/Filter）绕过的节点

4. 检查节点的历史记录和负载

superplane executions list --app-id <app_id> --node-id <node_id> -o yaml

检查故障是否反复发生。对于表达式错误，请检查实际负载结构：

• rootEvent.data.data — 触发器的实际事件负载（双层 .data 是包裹 webhook 负载的事件信封）
• input — 节点从上游节点接收的内容（同样包含 { data, timestamp, type } 信封）
• resultMessage — 完整错误信息，包括值为 nil 的表达式字段

请使用这些实际负载修正表达式路径，而不是根据文档猜测。

对于分支／通道问题，请检查执行 YAML 中的 outputs（而不只是顶层的 result）：

• 节点可能显示 result: RESULT_PASSED，但实际路由到 failure 通道——两者相互独立（运行时健康状态与语义路由）。在将其判定为错误前，请参阅执行结果与输出通道。
• 确认 outputs 下发出的通道名称与边的连接相匹配（success、failed、default 等）
• 如果下游行为看起来与 runs describe 的结果不一致，请以节点的 outputs 块为准来判断路由

5. 修复并重新运行

更新画布，然后从 UI 触发新的运行，或通过配置了模板的 start（手动运行）触发器启动。

superplane apps staging update --file canvas.yaml
superplane apps staging commit --message "Fix canvas"
# or:
superplane apps canvas update -f canvas.yaml --message "Fix canvas"

常见故障模式

身份验证失败

节点因权限错误立即失败。请检查：

superplane integrations list
superplane secrets list

确认集成已连接且密钥有效。

表达式错误

节点因引用缺失字段而失败。请检查：

• $['Node Name'] 中的节点名称是否完全匹配（区分大小写）
• 上游节点是否实际输出了预期字段
• 根负载是否包含预期数据

队列卡住

执行项不断堆积，无法继续：

superplane queue list --app-id <id> --node-id <nid>

可能原因：节点已暂停、Approval 正在等待人工输入、Time Gate 正在阻塞，或外部服务无响应。

清除卡住的项：

superplane queue delete --app-id <id> --node-id <nid> --item-id <iid>

Merge 从未触发

Merge 会等待所有传入边。如果某个分支卡住、被筛除或失败，Merge 就会阻塞。请检查每个上游分支。

何时使用其他技能

需求	使用技能
创建或修改画布	superplane-app-builder
CLI 命令和身份验证	superplane-cli

文档

对于能够获取 URL 的 Agent，可通过适合大模型阅读的格式查看完整的 SuperPlane 文档：

• 精简索引：https://docs.superplane.com/llms.txt
• 全部内容：https://docs.superplane.com/llms-full.txt