cargo-diagnostics

Cargo CLI — 诊断

用于分析工作流行为的取证操作手册：追踪一次运行、批量扫描错误、分析一个 play 的积分消耗。本技能是解读层——原始数据面（run get、编排 SQL、计费指标）记录在 cargo-orchestration 和 cargo-billing 中；此处的每份操作手册都会告诉你要获取哪些数据、按什么顺序获取，以及每种输出格式的含义。

初始化

已登录（cargo-ai whoami 返回了工作区）？请跳到下一节。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

每条命令都会将 JSON 输出到 stdout；失败时以非零状态码退出，并返回 {"errorMessage": "..."}。任何会创建运行或批次的操作都是异步的——请传入 --wait-until-finished，或轮询对应的 get。信用归属步骤（billing usage get-metrics、billing subscription get）需要具有管理员权限的令牌；其他操作使用标准令牌即可。安装完整技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定要求、令牌作用域和仅限管理员使用的数据面。

该看哪份操作手册？

What are you diagnosing?
│
├── One run / one record ("why did this record fail?",
│   "run succeeded but the output is wrong/empty")
│   └── references/run-trace.md
│
├── Many runs ("the batch has errors", "error rate spiked",
│   "which node keeps failing?")
│   └── references/batch-error-sweep.md
│
└── Cost ("this play is expensive", "where do the credits go?",
    "make this cheaper")
    └── references/play-optimize-credits.md

经验法则：如果还不知道要查看哪次运行，就先从扫描开始——扫描结束时会给出示例运行 UUID，供你传给追踪操作手册。

完全没有运行 UUID（“看看最近一次运行”“acme.com 的那次运行”“我的 play 在编辑器里做了什么”）？请查看 references/run-trace.md § 0，该部分会根据症状找到 UUID。请注意，不带 --workflow-uuid 的 orchestration run list 需要指定 --created-after，且时间范围最多为 30 天，因此仅靠它无法回答“最近一次运行”是什么；对 runs 执行的编排 SQL 则无需筛选条件。切勿因为 run list 拒绝执行，就断定无法访问运行的输入和输出。

与 cargo-analytics 的边界： analytics 用于衡量和导出（“错误率是多少？”“下载批次结果”“导出此细分群体”）；本技能用于解释原因（“为什么错误率上升了？”“为什么这条记录的输出为空？”）。诊断通常从 analytics 信号开始（错误数激增，批次报告 failedRunsCount > 0），并回到 analytics 结束——修复原因并重新执行运行后，批量获取数据请使用 run download-outputs / batch download / segment download，相关说明均见 ../cargo-analytics/SKILL.md。本技能的数据面（run get、编排 SQL、计费指标）用于诊断，而非批量导出。

参考资料

文档	内容
references/run-trace.md	在没有 UUID 时根据症状查找运行（§ 0），然后端到端追踪运行：逐节点执行情况、runContext 输出、分支路由、各节点积分和耗时。
references/batch-error-sweep.md	在批次、play 或工作区中查找出错的运行，按根本原因对失败分组，挑选示例，并决定修复还是报告。
references/play-optimize-credits.md	将积分消耗归因到工作流和节点，然后按优先级应用成本优化手段。另行归因执行费用（§ 2b）——每次节点执行消耗 0.01 积分，creditsUsedCount 不包含该费用，因此按节点进行的归因会遗漏这部分。

每次运行手册都会用到的界面

界面	命令	可获取的信息
运行详情	cargo-ai orchestration run get <run-uuid>	run.executions[]（逐节点跟踪记录）、runContext（按 nodeSlug 键控的各节点输出）、runComputedConfigs（每个节点实际调用时使用的配置）
跟踪记录	cargo-ai orchestration trace list --started-after <iso> [--statuses error,degraded] [--workflow-uuid <uuid>] · trace count（使用相同筛选条件） · trace get <trace-uuid>	每条跟踪记录一行，包含一次触发在整个运行链路中引发的所有内容（工具和 Agent 子运行、托管工作器调用、聊天中的助手轮次）：status（pending/error/degraded/success）、rootRunUuid、rootRecordTitle、spansCount、failedSpansCount、creditsUsedCount、workerUuid、chatUuid。--started-after 为必填项。trace get 仅返回聚合结果，不包含跨度
跨度	cargo-ai orchestration span list --execution-started-after <iso> [filters] · span count（使用相同筛选条件，但不含 --search/--limit）	无需 SQL 即可查看节点执行记录。筛选条件：--batch-uuid、--run-uuid、--parent-run-uuid、--workflow-uuid、--execution-statuses pending,success,error、--node-action-slug、--node-integration-slug、--node-slug、--node-kind native|connector|tool|agent|worker、--execution-title-or-error-message <ilike>、--record-title-or-id、--search（仅限 list：记录标题/ID、执行标题或错误）。--execution-started-after 为必填项
编排 SQL	cargo-ai orchestration query execute "<sql>"	对 runs、batches、spans、records 进行聚合查询（ClickHouse；不带架构前缀；按工作区限定）。按 ID 列出跟踪记录跨度的唯一方法：WHERE trace_uuid = '<uuid>'
计费指标	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 边到达的步骤，这意味着提供商返回了错误，而不是没有返回结果——诊断方式不同，修复方法也不同。标志和 ASCII 图例：../cargo-orchestration/references/node-diagram.md。

degraded 不等于 success。 根运行节点出错，而 fallbackOnFailure / fallback 边使运行得以完成时，跟踪记录状态为 degraded——运行报告成功，但失败的跨度仍为 error。error 表示根运行节点出错且没有后续节点，因此运行停止。子运行失败不会决定跟踪记录的状态；pending 表示任意深度的跨度仍在运行。请同时扫描 --statuses error,degraded：degraded 跟踪记录表示图形吸收了提供商故障，其根本原因通常与错误相同。

完整的查询语法、表格列和上限：../cargo-orchestration/references/examples/queries.md。调试字段语义：../cargo-orchestration/references/troubleshooting.md。

呈现调查结果

遵循 ../cargo/references/interaction.md：先给出结论（“20 次失败中有 18 次是同一个原因：连接器的令牌已过期”），再用简短的表格概述证据，切勿在对话中贴出原始 run get JSON 或完整查询结果。任何需要重新运行付费节点的修复，都必须经过试点审核：先重新运行 10–20 条记录，报告实际成本和命中率，然后询问用户是否批准其余部分，并注明记录数和预计积分消耗——诊断结果不代表已获准为产生该结果的批次再次计费。完整的支出规则见 ../cargo-gtm/references/cost-discipline.md。

诊断陷入僵局时

如果证据与文档描述的行为相矛盾（run get 中缺少字段、查询上限与文档不符，或错误信息毫无道理），请提交报告——这是官方渠道，团队会阅读每一份报告：

cargo-ai workspaceManagement report create \
  --title "<one-line summary>" \
  --description "<commands run, errorMessage verbatim, expected vs actual, UUIDs>"