cargo-analytics

Cargo CLI — 分析

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

完整的 JSON 响应结构请参见 references/response-shapes.md。
常见错误及修复方法请参见 references/troubleshooting.md。
运行指标和错误监控示例请参见 references/examples/run-analytics.md。
数据导出和下载示例请参见 references/examples/exports.md。
关于账单、用量指标和订阅，请使用 cargo-billing 技能。

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

本技能回答 "发生了什么" 和 "给我数据"：指标、计数、下载、导出。当问题变成 "为什么" — 为什么这个运行失败，为什么输出错误或为空，哪个根本原因解释了这些错误，为什么这个 play 如此昂贵 — 请切换到 cargo-diagnostics 技能；其 runbook 将原始表面序列化为诊断。

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

这两个技能自然衔接：分析 检测（错误率飙升，批次报告失败），诊断 解释（18/20 的失败共享一个根本原因），然后分析 检索 干净的结果（一旦原因修复并重新执行运行）。

前提条件

安装、登录（--oauth / --token）、JSON 输出约定和错误形状请参见 ../cargo/references/prerequisites.md。在运行以下任何命令之前，请使用 cargo-ai whoami 验证会话。

首先发现资源

大多数分析命令需要 UUID。在查询之前先发现它们。

cargo-ai orchestration play list            # 所有 play（名称, workflowUuid）
cargo-ai orchestration tool list            # 所有 tool（名称, workflowUuid）
cargo-ai orchestration workflow list        # 所有 workflow（仅 uuid — 无名称）
cargo-ai ai agent list                     # 所有 agent（uuid, 名称）
cargo-ai connection connector list          # 所有 connector（uuid, 名称, integrationSlug）
cargo-ai storage model list                # 所有 model（uuid, 名称, 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 — 在整个工作区（runs, batches, spans, records）上执行临时 SQL。最适合跨工作流分析、按节点细分和时间序列。
• run download / run download-outputs — 按记录检索输出。
• segment download / storage query execute — 存储数据（公司、联系人等）。

工作流运行指标

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

# 工作流的指标
cargo-ai orchestration run get-metrics --workflow-uuid <uuid>

# 限定到某个发布、批次或日期范围
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，用于固定指标命令未覆盖的分析。表引用时不带模式前缀；工作区范围自动确定。模式和限制请参见 cargo-orchestration/references/examples/queries.md。

# 过去一天工作区的错误率
cargo-ai orchestration query execute \
  "SELECT countIf(status='error') / count() AS error_rate FROM runs WHERE created_at > now() - INTERVAL 1 DAY"

# 本周每个工作流的失败运行
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"

# 按节点失败计数（过去 24 小时）
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"

# 本月每个工作流的信用额度支出
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"

只读且有限制：执行时间 30 秒，结果行数 10,000，扫描行数 10,000,000。使用 created_at/execution_started_at 谓词缩小范围，以保持在行扫描上限以下。

下载运行结果

两个不同的命令 — 根据任务选择正确的命令。

run download — 完整运行记录（元数据 + 每个节点的 runContext）

将每个运行作为 JSON 对象返回，包含状态、时间、执行和包含每个节点输出的 runContext.<nodeSlug>。最适合调试或需要完整执行历史时。

# 所有已完成的运行
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished

# 日期范围
cargo-ai orchestration run download --workflow-uuid <uuid> \
  --created-after <start-date> --created-before <end-date>

# 特定状态
cargo-ai orchestration run download --workflow-uuid <uuid> --statuses success,error

# 来自特定批次
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": "..."} — 一个签名 URL，指向包含输出节点数据及输入/输出上下文的 CSV（默认）或 JSON 文件。当您只需要结果时，比下载整个运行记录更快更省。

# 必需：--workflow-uuid + --output-node-slug
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --output-node-slug <slug> \
  --format json \
  --is-finished

# 按批次和状态过滤
cargo-ai orchestration run download-outputs \
  --workflow-uuid <uuid> \
  --output-node-slug <slug> \
  --batch-uuid <uuid> \
  --statuses finished

要查找 output-node-slug：cargo-ai orchestration release get <release-uuid> → 查看 nodes[].slug。终端输出节点通常命名为 output 或 end。

下载批次结果

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

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

处理部分批次失败

状态为 status: "success" 的批次仍可能包含个别运行失败。在将结果视为完整之前，始终检查批次中的错误。

步骤 1 — 检查批次摘要：

cargo-ai orchestration batch get <batch-uuid>
# → .runsCount          = 提交的记录总数
# → .executedRunsCount  = 达到终端状态（成功或错误）的记录数
# → .failedRunsCount    = 出错的记录数

步骤 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 — 仅重新运行失败的记录：

在诊断并修复根本问题（连接器凭据、错误输入数据、速率限制）后：

# 从失败的运行下载中提取记录 ID，然后：
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"recordIds","recordIds":["id1","id2","id3"]}'

按节点输出 slug 过滤：

要从批次中仅下载特定节点的输出（例如仅富化节点，而非完整运行）：

# 1. 从批次获取发布 UUID
cargo-ai orchestration batch get <batch-uuid>
# → .releaseUuid

# 2. 查找节点 slug
cargo-ai orchestration release get <release-uuid>
# → nodes[].slug

# 3. 下载该节点的输出
cargo-ai orchestration batch download \
  --uuid <batch-uuid> \
  --output-node-slug <node-slug>

分段数据导出

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

# 完整导出（所有记录）
cargo-ai segmentation segment download \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[]}'

# 带排序和限制
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。

对于带富化的实时分页查询，请使用 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