cargo-analytics

Cargo CLI — 分析

测量与导出：监控运行指标、下载运行和批次结果，以及导出细分数据。

完整的 JSON 响应结构请参阅 references/response-shapes.md。 常见错误及其修复方法请参阅 references/troubleshooting.md。 运行指标和错误监控示例请参阅 references/examples/run-analytics.md。 数据导出和下载示例请参阅 references/examples/exports.md。 如需了解账单、使用指标和订阅，请使用 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 命令。安装完整技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定、令牌作用域和仅限管理员使用的功能。

范围 — 测量与导出，而非解释

此技能回答**“发生了什么”和“给我数据”：指标、计数、下载和导出。一旦问题变成“为什么”**——为什么这次运行失败、为什么输出错误或为空、哪个根本原因导致这些错误、为什么这个 play 成本这么高——就切换到 cargo-diagnostics 技能；其运行手册会按顺序整理原始数据，得出诊断结果。

问题听起来像……	加载
“错误率是多少？”/“本周有多少次运行失败？”/“导出结果 / 细分数据”	此技能
“这次运行为什么失败？”/“运行成功了，但输出看起来不对”	cargo-diagnostics → references/run-trace.md
“这个批次为什么有错误？哪个节点一直失败？这是一个原因还是多个原因？”	cargo-diagnostics → references/batch-error-sweep.md
“这个 play 为什么成本这么高？额度都花在哪了？”	cargo-diagnostics → references/play-optimize-credits.md

这两种技能可以自然衔接：分析负责发现（错误率飙升、批次报告失败），诊断负责解释（20 次失败中有 18 次有同一个根本原因），问题修复并重新执行运行后，分析再负责获取干净的结果。

先发现资源

大多数分析命令都需要 UUID。请先发现资源，再进行查询。

cargo-ai orchestration play list            # all plays (name, workflowUuid)
cargo-ai orchestration tool list            # all tools (name, workflowUuid)
cargo-ai orchestration workflow list        # all workflows (uuid only — no name)
cargo-ai ai agent list                     # all agents (uuid, name)
cargo-ai connection connector list          # all connectors (uuid, name, integrationSlug)
cargo-ai storage model list                # all models (uuid, name, slug)

快速参考

cargo-ai orchestration run get-metrics --workflow-uuid <uuid>
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished
cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai orchestration query execute "SELECT status, count() FROM runs GROUP BY status"
cargo-ai segmentation segment download --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

如何选择合适的命令：

• run get-metrics / run count — 按工作流统计的预定义聚合指标。已知 workflowUuid 时最适用。
• orchestration query execute — 使用临时 SQL 查询整个工作区（runs、batches、spans、records）。最适合跨工作流分析、按节点细分和时间序列分析。
• run download / run download-outputs — 获取单条记录的输出。
• segment download / storage query execute — 获取存储数据（Companies、Contacts、……）。

工作流运行指标

工作流运行的聚合指标（成功率 / 错误率、各节点的额度）。

# Metrics for a workflow
cargo-ai orchestration run get-metrics --workflow-uuid <uuid>

# Scoped to a release, batch, or date range
cargo-ai orchestration run get-metrics --workflow-uuid <uuid> --release-uuid <uuid>
cargo-ai orchestration run get-metrics --workflow-uuid <uuid> --batch-uuid <uuid>
cargo-ai orchestration run get-metrics --workflow-uuid <uuid> \
  --created-after <start-date> --created-before <end-date>

运行计数

统计符合特定条件的运行次数——适用于监控。

cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai orchestration run count --workflow-uuid <uuid> --is-finished \
  --created-after <start-date> --created-before <end-date>
cargo-ai orchestration run count --workflow-uuid <uuid> --batch-uuid <uuid>

支持：--statuses、--batch-uuid、--release-uuid、--is-finished、--created-after、--created-before、--record-id、--record-title。

对于跨工作流分析，或 run count 未提供的数据形式（按节点统计失败情况、p95 时长、随时间变化的错误率），请使用 orchestration query execute——参见临时执行分析（orchestration query）一节。

临时执行分析（orchestration query）

对编排运行时表 runs、batches、spans、records 执行 SQL，进行预置指标命令无法涵盖的分析。引用表时无需添加 schema 前缀；工作区范围会自动应用。表结构和限制请参阅 cargo-orchestration/references/examples/queries.md。

# Error rate across the workspace in the last day
cargo-ai orchestration query execute \
  "SELECT countIf(status='error') / count() AS error_rate FROM runs WHERE created_at > now() - INTERVAL 1 DAY"

# Failed runs per workflow this week
cargo-ai orchestration query execute \
  "SELECT workflow_uuid, count() AS errors FROM runs WHERE status='error' AND created_at > now() - INTERVAL 7 DAY GROUP BY workflow_uuid ORDER BY errors DESC"

# Per-node failure counts (last 24h)
cargo-ai orchestration query execute \
  "SELECT node_slug, count() AS failures FROM spans WHERE execution_status='error' AND execution_started_at > now() - INTERVAL 1 DAY GROUP BY node_slug ORDER BY failures DESC"

# Credit spend by workflow this month
cargo-ai orchestration query execute \
  "SELECT workflow_uuid, sum(credits_used_count) AS credits FROM batches WHERE created_at >= toStartOfMonth(now()) GROUP BY workflow_uuid ORDER BY credits DESC"

该命令为只读，且有上限：执行时间 30s，结果行数 10 000，扫描行数 10 000 000。添加 created_at/execution_started_at 条件来缩小范围，避免超过扫描行数上限。

下载运行结果

有两个不同的命令，请根据任务选择合适的命令。

run download — 每次运行一行，每个节点一列（gzip 压缩的 CSV）

返回 {"url": "..."}，即指向gzip 压缩 CSV 的签名 URL。每行对应一次运行：包含 _uuid、_workspace_uuid、_workflow_uuid、_record_id、_record_title、_created_at、_finished_at、_status、_error_message，后面接每个节点 slug 对应的一列。

每个节点列存放的是该次执行的 title——一段经过截断的、人类可读的摘要，而不是节点输出。 此文件中没有 runContext 或 executions[]。应将其视为跨多次运行的状态面板（哪个节点出错、对应哪条记录），绝不可将其作为节点产出的依据——在其他所有场景中，cargo-diagnostics 对 title 也遵循同样的规则。

# Every run of a workflow
cargo-ai orchestration run download --workflow-uuid <uuid>

# Date range
cargo-ai orchestration run download --workflow-uuid <uuid> \
  --created-after <start-date> --created-before <end-date>

# Specific statuses (run statuses: idle, pending, running, success, error,
# cancelling, cancelled, skipped — NOT "finished"/"failed")
cargo-ai orchestration run download --workflow-uuid <uuid> --statuses success,error

# Every run that reached a terminal state. `--is-finished` is `finished_at IS
# NOT NULL`, which is wider than success+error: cancelled and skipped runs
# stamp finishedAt too, so don't substitute one for the other.
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished

# From a specific batch
cargo-ai orchestration run download --workflow-uuid <uuid> --batch-uuid <uuid>

run download-outputs — 每次运行的输入 + 输出（通过签名 URL 获取 CSV/JSON）

这是从平台获取操作结果的规范方式。 对应 API POST /v1/orchestration/runs/download-outputs。返回 {"url": "..."}，即指向 CSV（默认）或 JSON 文件的签名 URL。每行对应一次运行：包含相同的 _ 前缀运行元数据，以及 input（第一个节点解析后的配置）和 output（所选节点的上下文；省略 --output-node-slug 时默认为最后执行的节点）。

# --workflow-uuid is the only required flag
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --format json \
  --limit 20

# Pin the output node explicitly, and filter by batch
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --output-node-slug <slug> \
  --batch-uuid <uuid>

查找 output-node-slug：运行 cargo-ai orchestration release get <release-uuid> → 查看 nodes[].slug。终端输出节点通常命名为 output 或 end。如果不指定 --limit，文件会包含工作流所有匹配的运行，因此只需样本时请指定该参数。

按记录而非按运行获取： cargo-ai orchestration record download-outputs 接受相同的 --workflow-uuid / --output-node-slug，并为每条记录输出一行。它通过 --limit 和 --offset 分页（CLI ≥ 1.0.90）——要导出大到无法放入单个文件的数据集，应按固定范围逐段获取（--limit 1000 --offset 0，然后 --offset 1000，……），而不是一次请求全部数据。run download-outputs 也采用相同方式分页，但分页对象是运行。

获取多次运行的完整 runContext

无法通过一次调用完成。每个节点的完整上下文存储在每次运行各自的 S3 对象中，只有 orchestration run get <run-uuid> 会加载该对象，而且一次只能处理一条运行。上述两种导出都是经过筛选的数据：download 会提供多次运行中各节点的 title，download-outputs 会提供多次运行中第一个节点的输入 + 一个节点的输出。若要获取两者之间的所有内容，请根据 ../cargo-diagnostics/references/run-trace.md § 0 中的发现流程，循环调用 run get 处理 UUID。

编排 SQL 在这里无法替代这些命令：runs 和 spans 包含状态、时间和额度信息，但没有节点输入/输出列。

下载批次结果

cargo-ai orchestration batch download --uuid <batch-uuid> --output-node-slug <node-slug>

查找 output-node-slug：运行 cargo-ai orchestration release get <release-uuid>（从批次获取 release UUID），并查看 nodes[].slug。

处理批次中的部分失败

批次的 status: "success" 仍可能包含单个运行失败。将结果视为完整结果前，务必检查批次是否有错误。

步骤 1 — 检查批次摘要：

cargo-ai orchestration batch get <batch-uuid>
# → .runsCount          = total records submitted
# → .executedRunsCount  = records that reached a terminal state (success or error)
# → .failedRunsCount    = records that errored

步骤 2 — 统计并下载失败的运行：

cargo-ai orchestration run count \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error

cargo-ai orchestration run download \
  --workflow-uuid <uuid> \
  --batch-uuid <batch-uuid> \
  --statuses error

步骤 3 — 诊断。 查明失败原因——按根本原因对失败进行分组、选择典型运行、读取 runContext——是 cargo-diagnostics 技能的职责：加载 ../cargo-diagnostics/references/batch-error-sweep.md，并提供批次 UUID。

步骤 4 — 仅重新运行失败的记录：

完成诊断并解决根本问题后（连接器凭据、输入数据错误、速率限制）：

# Extract record IDs from the failed run download, then:
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"recordIds","modelUuid":"<model-uuid>","ids":["id1","id2","id3"]}'

按节点输出 slug 过滤：

如需仅下载批次中特定节点的输出（例如只下载 enrichment 节点，而不是完整运行结果）：

# 1. Get the release UUID from the batch
cargo-ai orchestration batch get <batch-uuid>
# → .releaseUuid

# 2. Find the node slug
cargo-ai orchestration release get <release-uuid>
# → nodes[].slug

# 3. Download that node's output
cargo-ai orchestration batch download \
  --uuid <batch-uuid> \
  --output-node-slug <node-slug>

细分数据导出

筛选器 JSON 使用 conjonction（而非 conjunction）——这是有意为之。完整的筛选器语法请参阅 cargo-orchestration 技能中的 references/filter-syntax.md。

# Full export (all records)
cargo-ai segmentation segment download \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[]}'

# With sorting and limit
cargo-ai segmentation segment download \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[]}' \
  --sort '[{"columnSlug":"created_at","kind":"desc"}]' \
  --limit 1000

重要： segment download 需要 --model-uuid，而非 --segment-uuid。从 segment list 获取 modelUuid。

对于带有 enrichment 的实时分页查询，请使用 cargo-orchestration 技能中的 segmentation segment fetch。

帮助

每条命令都支持 --help：

cargo-ai billing usage get-metrics --help
cargo-ai orchestration run download --help
cargo-ai segmentation segment download --help