cargo-skills

██████    ████    █████    ██████   ██████
██    ░  ██  ██░  ██  ██   ██    ░  ██  ██░
██       ██████░  █████ ░  ██ ███   ██  ██░
██       ██  ██░  ██ ██    ██  ██░  ██  ██░
██████   ██  ██░  ██  ██   ██████░  ██████░
 ░░░░░░   ░░  ░░   ░░  ░░   ░░░░░░   ░░░░░░

Cargo CLI — 技能概览

此仓库包含七项技能，适用于 Cargo AI 原生收入基础设施。每项技能涵盖一个不同的领域。本文件将说明在不同任务中应加载哪项技能，以及如何组合使用。

安装

npm install -g @cargo-ai/cli
cargo-ai login --token <your-api-token>
# Optional: target a specific workspace
cargo-ai login --token <your-api-token> --workspace-uuid <uuid>
# Verify
cargo-ai whoami

如果未进行全局安装，请在每条命令前加上 npx @cargo-ai/cli，而不是 cargo-ai。

所有命令都会将 JSON 输出到标准输出。命令执行失败时会以非零状态码退出，并返回 {"errorMessage": "..."}。

CLI 执行失败或遇到困难时——提交工作区管理报告

每当 CLI 出现技能中提及且 --help 无法解决的问题、用户或 Agent 反复重试同一条命令却毫无进展、标志或 JSON 负载的语法不明确，或者似乎缺少所需功能时，请提交报告并升级至工作区管理：

cargo-ai workspace report create \
  --title "<one-line summary of the problem>" \
  --description "<exact command(s) tried, errorMessage, expected vs actual, UUIDs involved>"

触发条件（满足任意一项即可）：

• 同一任务中，某条命令连续失败 ≥ 2 次，且原因不明显。
• CLI 使用有误，且无法从技能、示例或 --help 中找到正确用法。
• 文档中描述的行为与实际观察到的情况相矛盾。
• 某项功能似乎完全缺失。

这是官方反馈渠道——每份报告都会由 Cargo 团队审核，并用于改进 CLI 和这些技能。**不要悄无声息地放弃——请提交报告。**请参阅 cargo-workspace-management/SKILL.md（Reports 部分）和 cargo-workspace-management/references/examples/reports.md 中的模板。

---

技能一览

技能	在以下情况下加载……
cargo-orchestration	执行操作、运行工作流、触发批处理、与 Agent 聊天、查询数据仓库
cargo-analytics	下载运行结果、导出细分数据、监控错误率和指标
cargo-billing	查看额度使用情况、订阅详情，追踪每个工作流或连接器的成本
cargo-storage	检查或修改数据模型、列、数据集和关系
cargo-connection	管理连接器身份验证，发现可用集成及其操作
cargo-ai	创建和配置 Agent、上传用于 RAG 的文件、管理 MCP 服务
cargo-workspace-management	邀请用户、创建 API 令牌、整理文件夹、管理角色、向管理团队报告 CLI 问题

---

技能之间的关系

┌──────────────────────────────────────────────────────────────┐
│                  cargo-workspace-management                  │
│             Authentication, users, tokens, folders           │
└──────────────────────────────────────────────────────────────┘

  ┌─────────────────┐   ┌────────────────────┐   ┌─────────────────┐
  │  cargo-storage  │   │  cargo-connection  │   │    cargo-ai     │
  │ Models, columns,│   │ Connectors,        │   │ Agents, files,  │
  │ datasets        │   │ integration actions│   │ MCP servers     │
  └────────┬────────┘   └─────────┬──────────┘   └────────┬────────┘
           │                      │  (UUIDs flow down)    │
           └──────────────────────┼───────────────────────┘
                                  ▼
             ┌───────────────────────────────────────┐
             │          cargo-orchestration          │
             │   Runs, batches, plays, tools, SoR    │
             └───────────────┬───────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
 ┌────────────────────────┐  ┌───────────────────────────┐
 │    cargo-analytics     │  │       cargo-billing       │
 │  Results, metrics,     │  │    Credit usage, costs    │
 │  exports               │  │                           │
 └────────────────────────┘  └───────────────────────────┘

依赖规则的实际应用：

• cargo-workspace-management 为所有技能提供身份验证上下文——请先进行设置。
• cargo-storage、cargo-connection 和 cargo-ai 是同级技能，为 cargo-orchestration 提供 UUID。它们之间互不依赖。
• 在通过 system-of-record 查询之前，先加载 cargo-storage 以获取 DDL（准确的表名）。
• 在构建工作流节点图之前，先加载 cargo-connection 以获取 connectorUuid 和 actionSlug。
• 在执行使用 Agent 节点的工作流之前，先加载 cargo-ai 以获取 agentUuid。
• 运行完成后，加载 cargo-analytics 以下载结果或衡量性能。
• 加载 cargo-billing 以了解上述任意操作的额度消耗情况。

---

技能详情

cargo-orchestration

执行中心。 执行动作、运行工作流、与 AI Agent 聊天、查询数据仓库，以及获取分群记录。

主要命令：

# Single actions (no workflow needed)
cargo-ai orchestration action execute --action '{"kind":"tool","toolUuid":"<uuid>","config":{}}' --data '{...}'
cargo-ai orchestration action execute-batch --action '{"kind":"connector","integrationSlug":"...","actionSlug":"...","config":{}}' --records '[{...},{...}]'

# Workflows (chain multiple actions)
cargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'
cargo-ai orchestration run create --data '{...}' --nodes '[...]'
cargo-ai orchestration batch create --workflow-uuid <uuid> --data '{"kind":"segment","segmentUuid":"..."}'

# AI agents
cargo-ai ai message create --chat-uuid <uuid> --parts '[{"type":"text","text":"..."}]'

# Data
cargo-ai system-of-record client query "SELECT * FROM <table> LIMIT 10"
cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

关键规则：

• 何时使用 action execute、run create 或 batch create，请参阅 cargo-orchestration/SKILL.md 顶部的决策流程图。
• 筛选 JSON 使用 conjonction（而不是 conjunction）——拼写错误时不会报错，但会导致操作失败。
• 查询系统记录源前，务必先获取 DDL：cargo-ai storage model get-ddl <model-uuid>。
• 所有操作都是异步的——请轮询，或传入 --wait-until-finished。请参阅异步轮询。

参考： cargo-orchestration/SKILL.md

---

cargo-analytics

衡量与导出。 用于下载运行结果、导出分群数据，以及监控错误率和成功指标。

主要命令：

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 segmentation segment download --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

关键规则：

• segment download 需要 --model-uuid，而不是 --segment-uuid。
• 下载批处理结果时，从 release get <release-uuid> → nodes[].slug 获取 output-node-slug。
• 如需查询账单和点数使用情况，请改用 cargo-billing。

参考： cargo-analytics/SKILL.md

---

cargo-billing

成本与点数管理。 用于跟踪各工作流、连接器或 Agent 的点数消耗，查看订阅状态和账单。

主要命令：

cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD>
cargo-ai billing usage get-metrics --from <date> --to <date> --group-by workflow_uuid
cargo-ai billing subscription get
cargo-ai billing subscription get-invoices

关键规则：

• 需要具有管理员访问权限的令牌。
• 账单金额以美分为单位——除以 100 即为美元。
• subscription get 返回的 subscriptionAvailableCreditsCount - subscriptionCreditsUsedCount 即为剩余点数。

参考： cargo-billing/SKILL.md

---

cargo-storage

数据架构管理。 用于检查模型、创建或更新列、浏览数据集，以及了解工作区的数据结构。

主要命令：

cargo-ai storage model list
cargo-ai storage model get-ddl <model-uuid>   # always run before SoR queries
cargo-ai storage column list --model-uuid <uuid>
cargo-ai storage relationship set --from-model-uuid <uuid> --to-model-uuid <uuid>

关键规则：

• 通过系统记录源查询前，务必先运行 model get-ddl——其中包含准确的表名（例如 datasets_default.models_companies）。
• 如需执行高级记录查询（筛选、排序、分页），请使用 cargo-orchestration 中的 segmentation segment fetch。

参考： cargo-storage/SKILL.md

---

cargo-connection

连接器与集成管理。 用于验证外部服务、了解其支持的操作，以及获取工作流节点图所需的 connectorUuid 和 actionSlug 值。

主要命令：

cargo-ai connection connector list
cargo-ai connection integration list
cargo-ai connection integration get <slug>          # third-party actions (HubSpot, Salesforce, etc.)
cargo-ai connection native-integration get          # built-in Cargo actions only (NOT third-party)

关键概念：

• 集成 = 外部服务类型（HubSpot、Clearbit、Salesforce 等）
• 连接器 = 集成的已认证实例（在节点中通过 connectorUuid 引用）

参考： cargo-connection/SKILL.md

---

cargo-ai

Agent 资源管理。 用于创建和配置 Agent、上传文档以进行检索增强生成（RAG），以及连接 MCP 服务。

如需_使用_ Agent（发送消息、多轮聊天、轮询），请使用 cargo-orchestration。

主要命令：

cargo-ai ai agent list
cargo-ai ai agent create --name "Lead Researcher" --language-model-slug gpt-4o --temperature 0.3
cargo-ai ai file upload --file-path ./knowledge-base.pdf
cargo-ai ai mcp-server create --name "Internal Tools" --url "https://..."
cargo-ai ai memory list --agent-uuid <uuid>

请参阅 cargo-ai/SKILL.md，了解不同用例的模型和温度建议。

参考： cargo-ai/SKILL.md

---

cargo-workspace-management

工作区管理。 可用于邀请用户、创建和轮换 API 令牌、将 play/tool/Agent 整理到文件夹中、管理角色，以及在 CLI 失败或遭到误用时向工作区管理团队提交报告。

主要命令：

cargo-ai whoami
cargo-ai workspace user create --user-email [email protected] --role-slug <slug>
cargo-ai workspace token create --name "CI/CD pipeline"
cargo-ai workspace folder create --name "Q1 Campaigns" --emoji-slug "rocket" --kind "play"
cargo-ai workspace report create --title "<summary>" --description "<details>"

重要规则：

• 大多数命令都需要具有管理员访问权限的令牌。
• workspace token create 需要 --name（旧版 --from-user 标志已移除）。请选择一个能清楚说明令牌用途的名称，以便之后在 token list 中识别。
• 令牌值仅在创建时显示一次——请立即将其存储在密钥管理器中（GitHub Secrets、AWS Secrets Manager 等）。
• 当 CLI 报错、遭到误用，或你（用户或 Agent）难以推进 CLI 任务时，务必发送 workspace report create——请参阅此文件顶部的章节以及 cargo-workspace-management/references/examples/reports.md。

参考： cargo-workspace-management/SKILL.md

---

异步轮询

所有操作都是异步的。传入 --wait-until-finished 以阻塞等待，或进行轮询：

结果类型	轮询命令	间隔	终止条件
运行	cargo-ai orchestration run get <uuid>	2s	status 为 success、error 或 cancelled
批次	cargo-ai orchestration batch get <uuid>	5s	status 为 success、error 或 cancelled
Agent 消息	cargo-ai ai message get <uuid>	2s	status 为 success 或 error

action execute 会返回运行；action execute-batch 会返回批次——两者使用相同的轮询方式。

有关重试策略、错误处理和大批次指导，请参阅 cargo-orchestration/references/polling.md。

---

技能之间的 UUID 流转

大多数 cargo-orchestration 操作都需要来自其他技能的 UUID。此表列出了各 UUID 的生成技能和使用它的命令。

UUID	生成自	使用于
workflowUuid	orchestration play list / tool list	run create、batch create、run get-metrics、run download
modelUuid	storage model list	segment fetch、segment download、system-of-record query（通过 DDL）
segmentUuid	segmentation segment list	batch create --data '{"kind":"segment",...}'
agentUuid	ai agent list	ai chat create、节点图（kind: "agent"）
connectorUuid	connection connector list	节点图（kind: "connector"）、billing usage --connector-uuid
actionSlug	connection integration get <slug>（第三方）或 connection native-integration get（内置）	节点图（kind: "connector" 或 kind: "native"）
releaseUuid	orchestration batch get → .releaseUuid	orchestration release get、batch download
batchUuid	orchestration batch create	batch get、batch download、run get-metrics --batch-uuid
folderUuid	workspace folder list	play list --folder-uuid、tool list --folder-uuid
roleSlug	workspace role list	workspace user create --role-slug

运行工作流前的标准发现流程：

# 1. Confirm identity
cargo-ai whoami

# 2. Find the tool or play to run
cargo-ai orchestration tool list
cargo-ai orchestration play list

# 3. Find the model and get its DDL (if querying via SoR)
cargo-ai storage model list
cargo-ai storage model get-ddl <model-uuid>

# 4. Find connectors needed by the workflow nodes
cargo-ai connection connector list

# 5. Find agents used in workflow nodes
cargo-ai ai agent list

# 6. Find the segment to process (for plays / batch with segment data)
cargo-ai segmentation segment list

在界面中检索

Cargo 应用中的每项资源都有专属页面。使用以下 URL 模式，可将 CLI 返回的 UUID 与界面交叉引用，或从用户粘贴的 URL 中提取 UUID。

资源	URL 模式
Play	app.getcargo.io/workspaces/<WORKSPACE_UUID>/plays/<PLAY_UUID>
工具	app.getcargo.io/workspaces/<WORKSPACE_UUID>/tools/<TOOL_UUID>
Agent	app.getcargo.io/workspaces/<WORKSPACE_UUID>/agents/<AGENT_UUID>
模型	app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>

工作区 UUID 由 cargo-ai whoami 在 workspace.uuid 下返回。

---

端到端用例

1. 丰富单家公司信息（最简单的路径）

所需技能： cargo-orchestration

1. orchestration action execute            → run a connector action on one record
   --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"company_enrich","config":{}}'
   --data '{"domain":"acme.com"}' --wait-until-finished

2. 丰富公司列表信息并推送到 CRM

所需技能： cargo-storage、cargo-connection、cargo-orchestration、cargo-analytics

1. storage model get-ddl                   → get exact table name
2. connection connector list               → get enrichment + CRM connector UUIDs
3. connection integration get <slug>       → discover third-party action slugs (e.g. HubSpot, Clearbit)
4. orchestration tool list                 → find the enrichment tool
5. orchestration batch create      → run on a segment of companies
6. orchestration batch get         → poll until status is terminal
7. analytics run download          → export results

3. 使用 AI 为潜在客户评分并更新模型

所需技能： cargo-ai、cargo-orchestration、cargo-billing

1. ai agent list                   → find or create the scoring agent
2. ai agent create                 → configure instructions, model, temperature 0.0
3. orchestration play list         → find the scoring play
4. orchestration batch create      → trigger on a segment of new leads
5. orchestration batch get         → poll until status is terminal
6. billing usage get-metrics       → check credit consumption

4. 从头构建自定义信息丰富工作流

所需技能： cargo-connection、cargo-orchestration

1. connection connector list               → get connector UUID
2. connection integration get <slug>       → get actionSlug for the third-party service
3. orchestration node validate --nodes     → validate graph before running
4. orchestration run create --nodes        → run with custom node graph
5. orchestration run get                   → poll to terminal state

5. 监控工作流运行状况并在发生错误时发出提醒

所需技能： cargo-orchestration、cargo-analytics

1. orchestration tool list / play list    → discover workflowUuid
2. analytics run count --statuses error   → count errors in period
3. analytics run get-metrics              → get success/error rate breakdown
4. analytics run download --statuses error → download failed runs for inspection

6. 初始化全新的工作区

所需技能： cargo-workspace-management、cargo-storage、cargo-connection、cargo-ai

1. workspace token create --name <label>   → create a dedicated, named API token
2. workspace role list             → discover available roles
3. workspace user create           → invite team members
4. storage model create            → create Companies and Contacts models
5. storage column create           → add columns (name, domain, employee_count, etc.)
6. storage relationship set        → link Contacts → Companies
7. connection connector create     → connect enrichment and CRM integrations
8. ai agent create                 → configure an AI agent for research or scoring
9. workspace folder create         → organize plays and tools into folders

7. 导出并分析细分数据

所需技能： cargo-storage、cargo-analytics

1. storage model list              → get modelUuid
2. analytics segment download      → export with filter and sort
   --filter '{"conjonction":"and","groups":[
     {"conjonction":"and","conditions":[
       {"kind":"string","columnSlug":"country","operator":"is","values":["US"]}
     ]}
   ]}'
   --sort '[{"columnSlug":"created_at","kind":"desc"}]'

---

常见易错点

易错点	详情
conjonction 拼写错误	筛选器 JSON 使用 conjonction（而非 conjunction）。这是有意为之。这里拼错会导致静默失败——不会返回任何记录。
run create 与 batch create	run create 仅适用于 tool 工作流。使用 play 的 workflowUuid 会返回 playNotCompatible。
--model-uuid 与 --segment-uuid	segment fetch 和 segment download 需要 --model-uuid。通过 segment list → .modelUuid 获取。
先执行 DDL，再执行 SQL	切勿猜测表名。务必先运行 model get-ddl <uuid>。表名的格式类似 datasets_default.models_companies。
令牌仅显示一次	API 令牌值仅在创建时返回。请立即保存。workspace token create 需要 --name（不再需要 --from-user）。
发票金额以美分计	subscription get-invoices 返回的 amount 单位是美分。请除以 100。
Play 与工具	Play = 对数据变更作出响应（由分群驱动）。工具 = 按需触发（手动、API、cron）。
批次数据类型	Play 工作流接受：segment、change、filter、recordIds。工具工作流接受：file、records。
第三方连接器的速率限制	只有 kind: "connector" 节点（Clearbit、HubSpot 等）存在速率限制——原生节点没有。批次运行时错误会悄然增加。先从 1 条记录开始，再试 50 条、500 条，然后再进行全规模处理。为连接器节点添加带退避的 retry。