用途:对 Cargo 工作流做事后取证式诊断,回答“这条记录为什么失败”“批次错误率为何上升”“这个 play 的额度花在哪里”。它本身是解释层,原始数据来自 cargo-orchestration(run get、编排 SQL)与 cargo-billing(用量指标);本技能说明该拉取哪些表面、以什么顺序、输出各字段含义。
主要能力分三本 runbook: 1)run-trace:没有 run UUID 时先从症状解析出 UUID(run-trace §0,注意 orchestration run list 需要 --workflow-uuid,而编排 SQL 无过滤可查询),再端到端走一遍:逐节点执行、runContext 输出、分支走向、每节点额度与耗时。 2)batch-error-sweep:跨批次/play/工作区找报错运行,按根因分组,挑选样例,决定修复还是上报。 3)play-optimize-credits:把额度消耗归因到工作流与节点,再按优先级应用成本杠杆。注意执行费单独计算:每次节点执行 0.01 额度,creditsUsedCount 不含此项,逐节点归因会漏掉。
主要数据表面与命令: cargo-ai orchestration run get <run-uuid> 给出 run.executions[]、runContext、runComputedConfigs; cargo-ai orchestration query execute "<sql>" 对 runs、batches、spans、records 做聚合(ClickHouse,无 schema 前缀,工作区范围); cargo-ai billing usage get-metrics --from <date> --to <date> 给出额度总量,可按 workflow_uuid、connector_uuid、agent_uuid、integration_slug、model_uuid 过滤与分组; cargo-ai orchestration node diagram --run-uuid <uuid> --highlight <slug> --format ascii --raw 画出运行图并标出失败节点,免费且不触发运行。解释路由问题前先画图:它能看到 run get 不明显的 on failure 边,看似跳过的步骤可能是通过 fallbackChildUuid 边到达,意味着提供方报错而非返回空,诊断与修复方式不同。
安装与使用:npm install -g @cargo-ai/cli(不装全局则命令前加 npx @cargo-ai/cli);cargo-ai login --email you@company.com(邮件验证码,无浏览器,首次登录创建账号;备选 --oauth 浏览器、--token <api-token> CI);cargo-ai whoami 确认当前工作区。所有命令向 stdout 打印 JSON,失败非零退出并返回 {"errorMessage": "..."}。创建运行或批次是异步的,需 --wait-until-finished 或轮询对应 get。额度归因步骤(billing usage get-metrics、billing subscription get)需要 admin 权限的 token,其余标准 token 可用;完整技能包还有 CLI 版本固定、token 范围与仅 admin 表面的说明。
限制与边界:与 cargo-analytics 的分工是 analytics 负责度量与导出(错误率、下载批次结果、导出分群),本技能负责解释原因;大批量获取走 run download-outputs / batch download / segment download。证据表面仅用于诊断,不用于批量导出。修复若重跑付费节点须走试点门:先重跑 10–20 条记录,报告观察到的成本与命中率,再让用户按记录数与额度预估批准其余部分;诊断本身不构成重跑并重新计费的授权。展示结论应遵循交互规范,先给结论、用短表总结证据,不要把原始 run get JSON 或完整查询结果直接倾倒进对话。若证据与文档行为矛盾(字段缺失、查询上限不符、错误无法解释),用 cargo-ai workspaceManagement report create --title "..." --description "..." 提交报告。上述 references 文件为本技能包内部文档,具体内容未在本次资料中完整提供。