Back to Details

cargo-diagnostics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cargo CLI — Diagnostics

Cargo CLI — 诊断功能

Forensic runbooks for workflow behavior: trace one run, sweep a batch for errors, profile a play's credit spend. This skill is the interpretation layer — the raw surfaces (
run get
, orchestration SQL, billing metrics) are documented in 
cargo-orchestration
and 
cargo-billing
; each runbook here tells you which of them to pull, in what order, and what each output shape means.
工作流行为的取证指南：追踪单次运行、批量扫描错误、分析Play的credits消耗。该技能是解释层——原始数据接口（
run get
、编排SQL、计费指标）记录在
cargo-orchestration
和
cargo-billing
中；本指南中的每个手册都会告诉你应调用哪些接口、调用顺序以及各输出格式的含义。

Which runbook?

选择哪个手册？

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
Rule of thumb: start with the sweep when you don't yet know which run to look at — it ends by handing you exemplar run UUIDs to feed into the trace.
Boundary with 
cargo-analytics
: analytics measures and exports ("what's the error rate?", "download the batch results", "export this segment"); this skill explains ("why is the error rate up?", "why is this record's output empty?"). A diagnosis often starts from an analytics signal (error count spiked, batch reports 
failedRunsCount > 0
) and ends back in analytics — once the cause is fixed and runs re-executed, bulk retrieval goes through 
run download-outputs
/ 
batch download
/ 
segment download
, all documented in 
../cargo-analytics/SKILL.md
. This skill's evidence surfaces (
run get
, orchestration SQL, billing metrics) are for diagnosis, not bulk export.
你要诊断什么问题？
│
├── 单次运行/单条记录（「这条记录为什么失败？」、
│   「运行成功但输出错误/为空」）
│   └── references/run-trace.md
│
├── 多次运行（「批量任务存在错误」、「错误率飙升」、
│   「哪个节点持续失败？」）
│   └── references/batch-error-sweep.md
│
└── 成本问题（「这个Play成本过高」、「credits消耗去向？」、
    「降低成本」）
    └── references/play-optimize-credits.md
经验法则：当你还不确定要查看哪个运行实例时，先从批量扫描开始——它最终会为你提供可用于追踪的示例运行UUID。
与
cargo-analytics
的边界： analytics负责测量与导出（「错误率是多少？」、「下载批量任务结果」、「导出该分段数据」）；本技能负责解释原因（「错误率为什么上升？」、「这条记录的输出为什么为空？」）。诊断通常从analytics的信号（错误计数飙升、批量任务报告
failedRunsCount > 0
）开始，最终又回到analytics——一旦问题修复并重新运行任务，批量检索需通过
run download-outputs
/ 
batch download
/ 
segment download
完成，这些操作均记录在
../cargo-analytics/SKILL.md
中。本技能涉及的证据接口（
run get
、编排SQL、计费指标）仅用于诊断，不用于批量导出。

References

参考文档

DocWhat it covers
references/run-trace.md
Walk one run end-to-end: per-node executions, 
runContext
outputs, branch routing, per-node credits and timing.
references/batch-error-sweep.md
Find errored runs across a batch/play/workspace, group failures by root cause, pick exemplars, decide fix vs report.
references/play-optimize-credits.md
Attribute credit spend to workflows and nodes, then apply the cost levers in priority order.
文档涵盖内容
references/run-trace.md
端到端追踪单次运行：逐节点执行记录、
runContext
输出、分支路由、逐节点credits消耗及耗时。
references/batch-error-sweep.md
在批量任务/Play/工作区中查找错误运行实例，按根本原因分组失败案例，选取示例，决定修复还是上报。
references/play-optimize-credits.md
将credits消耗归因到工作流和节点，然后按优先级应用成本优化手段。

Prerequisites

前置条件

See 
../cargo/references/prerequisites.md
 for install, login (
--oauth
/ 
--token
), JSON output conventions, and error shapes. Verify the session with 
cargo-ai whoami
before running any of the commands below.
Credit attribution steps (
billing usage get-metrics
, 
billing subscription get
) need a token with admin access; everything else works with a standard token.
安装、登录（
--oauth
/ 
--token
）、JSON输出约定及错误格式请查看
../cargo/references/prerequisites.md
。运行以下命令前，请通过
cargo-ai whoami
验证会话有效性。
credits归因步骤（
billing usage get-metrics
、
billing subscription get
）需要拥有管理员权限的token；其他操作使用标准token即可。

The three surfaces every runbook draws on

所有手册都会用到的三类接口

SurfaceCommandGives you
Run detail
cargo-ai orchestration run get <run-uuid>
run.executions[]
(node-by-node trace), 
runContext
(per-node output keyed by 
nodeSlug
), 
runComputedConfigs
(what each node was actually called with)
Orchestration SQL
cargo-ai orchestration query execute "<sql>"
Aggregates over 
runs
, 
batches
, 
spans
, 
records
(ClickHouse; no schema prefix; workspace-scoped)
Billing metrics
cargo-ai billing usage get-metrics --from <date> --to <date>
Credit totals, filterable and groupable by 
workflow_uuid
, 
connector_uuid
, 
agent_uuid
, 
integration_slug
, 
model_uuid
Full query syntax, table columns, and caps: 
../cargo-orchestration/references/examples/queries.md
. Debugging field semantics: 
../cargo-orchestration/references/troubleshooting.md
.
接口类型命令提供内容
运行详情
cargo-ai orchestration run get <run-uuid>
run.executions[]
（逐节点追踪记录）、
runContext
（按
nodeSlug
键值对存储的逐节点输出）、
runComputedConfigs
（各节点实际调用的配置）
编排SQL
cargo-ai orchestration query execute "<sql>"
对
runs
、
batches
、
spans
、
records
进行聚合查询（基于ClickHouse；无需架构前缀；作用范围为工作区）
计费指标
cargo-ai billing usage get-metrics --from <date> --to <date>
credits总消耗量，可按
workflow_uuid
、
connector_uuid
、
agent_uuid
、
integration_slug
、
model_uuid
进行筛选和分组
完整查询语法、表格列及限制请查看
../cargo-orchestration/references/examples/queries.md
。字段语义调试请查看
../cargo-orchestration/references/troubleshooting.md
。

Presenting findings

结果呈现

Follow 
../cargo/references/interaction.md
: lead with the conclusion ("18 of 20 failures are one cause: the connector's token expired"), summarize evidence in a short table, never dump raw 
run get
JSON or full query results into the conversation. Any fix that re-runs paid nodes goes through the pilot gate in 
../cargo-gtm/references/cost-discipline.md
.
请遵循
../cargo/references/interaction.md
：先给出结论（「20次失败中有18次是同一原因：连接器token过期」），用简短表格总结证据，切勿在沟通中直接粘贴原始
run get
JSON或完整查询结果。任何需要重新运行付费节点的修复操作都需通过
../cargo-gtm/references/cost-discipline.md
中的试点审批流程。

When diagnosis dead-ends

诊断陷入僵局时

If the evidence contradicts documented behavior (a field missing from 
run get
, a query cap that doesn't match the docs, an error that makes no sense), file a report — that's the official channel and the team reads every one:
bash
cargo-ai workspaceManagement report create \
  --title "<one-line summary>" \
  --description "<commands run, errorMessage verbatim, expected vs actual, UUIDs>"
如果证据与文档描述不符（
run get
缺少字段、查询限制与文档不一致、错误无合理解释），请提交报告——这是官方渠道，团队会查看每一份报告：
bash
cargo-ai workspaceManagement report create \\
  --title "<一行摘要>" \\
  --description "<执行的命令、完整错误信息、预期与实际结果、UUIDs>"