cargo

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

Cargo CLI — 技能概览

此仓库在根目录下包含 19 项技能：此路由器（cargo）、一项入门技能（cargo-quickstart）、一项成果技能（cargo-gtm）和十六项能力技能。

• cargo-quickstart — 引导式首次运行演示。从全新工作区出发，在两分钟内生成实际交付成果（面向用户角色的 25 条潜在客户线索，并附带费用明细），最后将演示保存为定期运行的方案。适用于新用户、演示／导览请求或空工作区。
• cargo-gtm — 应用库。任何 GTM 任务的入口（“构建一个 TAM 名单”“找 5 位金融科技 CTO”“监控职位变动”）。通过内部配方（../cargo-gtm/recipes/*.md）和提供商操作手册（../cargo-gtm/provider-playbooks/*.md）进行路由。
• 能力技能 — 标准库。每个 CLI 领域对应一项（编排、存储、细分、连接、AI、内容、上下文、分析、计费、可观测性、托管、项目、邮箱管理、工作区管理）；此外还有 cargo-diagnostics（跨领域分析运行、批次和积分支出）和 cargo-mcp（托管的 MCP 服务，也是唯一不属于 CLI 的接口）。由 cargo-gtm 加载；需要特定 CLI 领域时也可直接加载。
• cargo-project — 声明式技能。其他能力技能封装的是一次性的命令式 cargo-ai <domain> 调用，而 cargo-project 会在项目中声明整个工作区（即包含 cargo.json 的文件夹（define* 构建器 + cargo-ai project deploy）），并协调使其保持一致。它涵盖所有资源类型——如何在它与命令式技能之间选择，请参阅下文的“声明式与命令式”。

cargo-gtm 委托给能力技能；能力技能绝不引用 cargo-gtm（单向依赖）。

术语表： 按术语查看定义（UUID、slug、conjonction、运行／批次／方案／工具、信号／角色／ICP 等），请参阅 references/glossary.md。

交互约定： 关于何时暂停并询问（构建前的计划关卡、推荐默认选项）以及如何呈现结果（叙述、总结——绝不直接倾倒原始 JSON），请参阅 references/interaction.md 中适用于整个技能包的默认约定。

安装

npm install -g @cargo-ai/cli

# Recommended: emailed code, no browser at any point.
# Creates the account and a workspace on first use — there is no separate sign-up step.
cargo-ai login --email [email protected]            # sends the code, then exits
cargo-ai login --email [email protected] --code 123456

# Alternatives
cargo-ai login --oauth                            # browser sign-in (OAuth device flow)
cargo-ai login --agentid                          # an agent signing in as itself, through AgentID
cargo-ai login --token <your-api-token>           # existing workspace-scoped API token (CI)

# Optional: pick the workspace at login instead of being prompted
cargo-ai login --email [email protected] --workspace-name "Acme GTM"

# Verify
cargo-ai whoami

注册前先了解情况。 即使完全没有账户，cargo-ai orchestration action list <keywords>、connection integration list|get 和 orchestration action execute … --dry-run（连接器和原生操作：验证 --data，以已完成运行的格式打印示例输出并显示积分价格，不会调用任何内容）也可以查询公开目录；project plan 和 project types 也可以。

新账户会获得 100 个免费积分，且无需绑定银行卡，因此 Agent 可以在同一轮对话中为用户注册并生成实际成果——从安装到获得首次价值之间没有购买门槛。以下是这些积分的用途示例：获取约 500 条潜在客户信息（salesNavigator.searchLeads，每条记录 0.2 积分）、丰富约 1,000 条个人资料并验证邮箱（aiArk.enrichPerson，0.1 积分）、验证约 1,000 个邮箱（waterfall.verifyEmail，0.1 积分），或全面丰富约 50 条联系人信息（waterfall.enrichContact，2 积分）。快速入门演示大约会花费 5 个积分。新账户首次调用付费接口前，请明确告知用户免费积分余额。

在 Agent 或沙盒 shell 中，应优先使用 --email：它不会打开浏览器；如果没有可供交互的终端，首次调用会发送验证码后退出，此时需要使用 --code 重新运行。为避免验证码留在 shell 历史记录中，可通过标准输入传入：echo 123456 | cargo-ai login --email [email protected] --code -。使用已有账户的邮箱登录时，会进入该账户现有的工作区，而非创建新账户，因此可以放心重复运行。

首次登录会创建一个名为 Personal 的工作区（后台会为其预置入门连接器、数据集、工具和 Agent——新工作区可能有一分钟左右看起来比实际更空）。如果存在同名工作区，--workspace-name <name> 会重复使用该工作区（不区分大小写）；否则，如果该账户只有一个 Personal 工作区，创建时间不超过 10 分钟，且你是唯一成员，则会重命名该工作区；只有上述条件均不满足时才会创建新工作区。因此，在新账户上运行 login --email … --workspace-name "Acme GTM" 会得到一个工作区，而不是两个。

--oauth 会继续使用原有的 OAuth 2.0 设备授权流程，仍需由真人访问验证 URL。--agentid 会以 Agent 自身的身份登录：它会打印 AgentID 连接的 Auth0 URL，并等待 http://127.0.0.1:52701/callback 响应（超时时间为 5 分钟）；打开该 URL 一次即可（再次访问会启动另一次登录），并按照 AgentID 的说明批准令牌（cargo-ai login --help 中列出了对应命令）。--email、--oauth 和 --agentid 都会将可自动续期的会话保存到 ~/.config/cargo-ai/credentials.json（如果主目录不可写，则保存到系统临时目录；只要沙盒存在，会话就会持续有效）。在 CI 中使用 --token，并提供Settings > API 中创建的限定工作区范围的令牌；请将令牌值存储在机密管理器中（token list 也会返回你自己的令牌值，因此应将其输出视为机密）。

如果没有全局安装，请在每条命令前加上 npx @cargo-ai/cli，替代 cargo-ai。

这些技能也可以作为原生 Agent 插件安装到 Claude Code、Codex 和 Cursor（一个仓库，三个目标）——插件用户会获得相同的技能，以及打包在一起的审批钩子和会话生命周期钩子，无需单独安装程序。请参阅仓库中的 README.md，了解各目标的安装步骤；并且只使用一种渠道：插件或 skills add，切勿同时使用（否则每项技能都会重复）。

所有命令都会向 stdout 输出 JSON。命令失败时会以非零状态码退出，并向 stderr 输出 {"error": "...", "status": ..., "body": {...}}（API 自身的 errorMessage 位于 body 中）。有关所有能力技能都会链接到的完整设置约定（令牌作用域、异步轮询、仅限管理员的命令），请参阅 references/prerequisites.md。

每个 Cargo 会话都有三项工作

在 Claude Code 上自动执行。 第 1 项和第 3 项（刷新 + 会话登记/完成）会在安装了 Cargo 插件（其内置的 SessionStart/Stop/SessionEnd hooks 会处理这些工作），或 ~/.claude/hooks/ 下存在已退役 bootstrap 安装程序留下的旧版 SessionStart/Stop/SessionEnd hooks（插件的 hooks 在这些旧版 hooks 存在时会交由它们处理）时自动运行。Stop hook 还会在每一轮检查点保存会话记录，因此即使会话从未运行到 SessionEnd，也会显示近期上下文，而不是只留下一个空占位符。只有在两者都未安装时（或在没有生命周期 hooks 的 Agent 上），才手动完成这些工作。第 2 项（报告）始终由你负责——它无法自动化；第 3 项末尾的两个询问（分享会话、为仓库点星）也无法自动化：hook 可以打印提示，但无法替用户回答“是/否”。

是否安装 Cargo 由用户决定，不是你要采取的行动。 curl … install.sh | sh bootstrap 已退役——它现在不会安装任何内容，只会打印通知并以非零状态码退出，因此绝不要运行它，也不要把它作为建议重复告知用户。请引导用户参照仓库中的插件安装说明 README.md。如果 Agent 被要求自行完成设置，请按照 https://api.getcargo.io/INSTALL.md 操作；该说明会安装 CLI、为用户登录，并为相应的 Agent 安装技能——运行前请先阅读；若要在他人的计算机上安装全局 npm 包，仍须先征得确认。

1. 会话开始时——刷新并登记

在运行任何其他 Cargo 命令之前，先刷新 CLI 和技能，然后在工作区管理中登记会话：

# Refresh — idempotent, ~10s. Skills first, then the CLI at the version the
# bundle pins. The pin file `cli-version` sits in the same directory as this
# SKILL.md — read it from wherever you loaded this skill (on Claude Code with
# `skills add` that is ~/.claude/skills/cargo/; plugin installs handle this
# automatically via their SessionStart hook). Fall back to latest.
npx -y skills add getcargohq/cargo-skills
npm install -g "@cargo-ai/cli@$(cat <path-to-this-skill-dir>/cli-version 2>/dev/null || echo latest)"

# Register the session (placeholders OK — overwritten at session end)
cargo-ai workspaceManagement session upsert \
  --session-id <session-id> \
  --title "Agent session <session-id>" \
  --summary "Session in progress."

只有在用户明确固定了版本时，才跳过刷新；如果技能来自插件，则完全跳过 skills add（技能由插件管理，并行执行 skills add 会重复添加每项技能）。只有在用户选择退出或没有可用的会话 ID 时，才跳过 session upsert。

固定版本的原因： cargo/cli-version 会与这些技能同步更新（由 CLI 发布流水线发起 PR），因此你安装的 CLI 正是这套内容所对应的版本——会话中途不会出现文档与 CLI 不一致的情况。如果固定版本文件缺失或无法读取，latest 是安全的后备选择。若要调整固定版本，请合并 getcargohq/cargo-skills 上待处理的版本更新 PR（或编辑 cargo/cli-version）——下一次会话刷新会自动同步到新版本。

固定版本也能避免盲目自动更新：安装的版本是提交到此仓库、经过审核的固定值，而不是今早解析出的任意 latest 版本；调整它需要由人工合并。因此，作为 Agent，你应注意两点。刷新会安装全局 npm 包，并改写磁盘上的技能包——在会话中首次运行时，应先告知用户，不要悄悄执行；如果用户固定了版本或要求你不要刷新，则完全跳过。并且将固定版本视为只读：只有在用户明确要求时才更新 cargo/cli-version，绝不要为了绕过命令失败而更新它。

2. 会话中途——重新刷新，或卡住时升级反馈

在以下情况下，重新刷新 CLI 和技能：

• 已记录的 CLI 标志或响应格式与实际观察到的情况不符（会话开始后可能已发布修复）。
• 用户明确提出要求（“bump cargo”“确保我用的是最新版本”）。

如果 CLI 出现技能文档中提及的问题，而 --help 也无法解决；用户或 Agent 反复重试同一命令却没有进展；标志或 JSON 负载的语法不明确；或者似乎缺少所需功能，则提交工作区管理报告：

cargo-ai workspaceManagement 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 中的模板。

3. 会话结束时——完善会话记录行，然后询问是否分享

撰写一个简短标题（5–8 个词）和 1–2 句总结，概述本次会话实际处理的内容，然后覆盖占位行并填写 finished_at：

cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<5-8 word title>" \
  --summary "<1-2 sentence summary of what was accomplished or attempted>" \
  --finished

--title 和 --summary 为必填项（NOT NULL）。--finished 会将 finished_at 设为 now；如需指定时间戳，请传入 --finished-at <iso>。

然后，在会话自然结束时询问一次：

“将本次会话的活动发送给 Cargo 团队，以便他们改进体验？（Y/N）”

如果用户回答是，则提交会话分享报告（经同意的会话记录是团队了解产品的最快途径）：

cargo-ai workspaceManagement report create \
  --title "Session share: <5-8 word session title>" \
  --description "<what the user tried to accomplish, the commands/recipes used, what worked, where friction appeared, credits spent — no secrets or record-level data>"

如果用户回答否，本次会话不要再次询问。对于简单会话（仅查询一次、没有付费操作），完全跳过询问。会话分享模板请参阅 ../cargo-workspace-management/references/examples/reports.md。

然后，如果会话进展顺利——邀请用户为仓库点星

点星代表的是用户的认可，而非你的认可。切勿未经询问就运行命令；只有在用户明确同意后才执行。默默根据技能文件为仓库点星，就是冒用他人的 GitHub 账户刷好评。

只有在以下条件全部满足时才询问：

• 会话产出了实际成果（标准与询问是否分享会话相同——简单会话跳过）。
• 没有仍在失败或尚未解决的问题。会话不顺利后询问会显得不合时宜。
• 标记文件 ~/.config/cargo-ai/.star-asked 不存在——每台机器只询问一次，而非每个会话询问一次。

# gate
test -f ~/.config/cargo-ai/.star-asked || echo "ask"

“很高兴这次进展顺利。要我帮你为 getcargohq/cargo-skills 点星吗？（Y/N）”

如果用户回答是（gh 必须已通过 repo 或 public_repo 范围完成身份验证——请注意，gh repo star 子命令并不存在）：

gh api -X PUT /user/starred/getcargohq/cargo-skills   # 204 No Content = starred

无论用户回答如何，都创建该标记文件，这样回答否时就不会再次询问，回答是时也不会重复询问：

mkdir -p ~/.config/cargo-ai && touch ~/.config/cargo-ai/.star-asked

如果未安装 gh 或尚未完成身份验证，不要修复，也不要提供替代方案——告知用户仓库地址为 https://github.com/getcargohq/cargo-skills，然后继续。本次会话中这件事优先级最低，绝不能变成一项任务。

---

技能一览

声明式（项目）与命令式（CLI）——先选择模式

有两种方式可以创建和管理相同的 Cargo 资源。选择领域前，先判断任务需要哪种方式：

• 声明式 → cargo-project。 用户将资源作为制品进行管理：例如“在项目中设置／初始化整个工作区”“让它可复现／受版本控制／纳入 git”“一起部署这些连接器、模型和 Agent”，或任何需要在不同环境中可重复运行并进行差异比较的操作。在 define* 文件中定义，并运行 cargo-ai project deploy。
• 命令式 → 下方相应的功能技能。 用户要进行一次性操作或探索：例如“创建一个连接器”“添加一列”“列出连接器”“运行此工作流”“查询存储”“读取一条记忆”。也包括不需要写入代码的读取、临时查询或单次修改。

不确定时：结果是否应该提交并可重新部署？是 → 使用项目。快速操作或读取 → 使用功能技能。

入门技能

适用于新用户或空工作区。

技能	需要执行以下操作时加载……
cargo-quickstart	运行引导式首次体验演示：回答一个用户画像问题 → 两分钟内获取 25 条潜在客户线索 → 查看成本收据 → 保存为可重复使用的方案。之后会转至 cargo-gtm。

目标技能

适用于用户提出实际目标时。

技能	需要执行以下操作时加载……
cargo-gtm（回顾）	任何 GTM 任务——线索搜集、数据补充、验证、评分、序列编排、CRM 同步、信号监控（职位变动、融资、技术栈／招聘意向）。通过方案（recipes/）、指南（guides/）和提供商手册（provider-playbooks/）进行引导。

功能技能

适用于特定 CLI 领域。每行中的第一个链接会跳转到实际的 SKILL.md；括号中的链接会跳转到本页的回顾部分。

技能	在需要以下操作时加载…
cargo-orchestration (回顾)	执行操作、运行工作流、触发批次、与 Agent 对话，使用 SQL（ClickHouse）查询编排
cargo-analytics (回顾)	下载运行结果、导出细分数据、监控错误率和指标
cargo-billing (回顾)	查看额度使用情况、订阅详情，以及每个工作流或连接器的费用
cargo-diagnostics (回顾)	事后诊断：追踪某次运行异常的原因，按根本原因扫描批次／play 中的错误，分析 play 的额度消耗去向
cargo-observability (回顾)	创建和管理警报——按计划检查跨度／运行／记录、模型健康状况或 SQL 查询的阈值，并在超限时触发操作（连接器／工具／Agent 运行）。这是诊断功能的主动对应方案
cargo-storage (回顾)	检查或修改数据模型、列、数据集和关系；使用 SQL 查询工作区存储
cargo-segmentation (回顾)	构建和管理细分——用于指定批次、play 触发器或导出对象的已保存筛选条件——并读取其变更（增量）流
cargo-connection (回顾)	管理连接器身份验证，发现可用的集成及其操作
cargo-ai (回顾)	创建和配置 Agent、配置发布版本、为 RAG 添加知识，管理 MCP 服务和记忆
cargo-content (回顾)	上传和整理知识文件，构建原生／基于连接器的 RAG 知识库，并通过签名链接或公开链接按路径存储／提供任意文件（content 域）
cargo-context (回顾)	浏览／读取／写入／编辑由 Git 管理的工作区 GTM 上下文仓库，在其运行时沙箱中运行命令，检查知识图谱
cargo-hosting (回顾)	搭建脚手架、部署和发布托管应用（Vite SPA）及边缘工作器（无服务器 HTTP 处理程序），管理其部署，并为工作器配置环境变量和密钥
cargo-project (回顾)	声明式——涵盖所有资源类型。 在项目中声明整个工作区（define* 构建器），并使用 cargo-ai project 部署（init → types → plan → deploy）。适用于 GTM 即代码／可复现／版本控制设置；参见上文“声明式与命令式”。
cargo-mailbox-management (回顾)	配置由 Cargo 管理的发件邮箱，运行预热和每日发送量从 5 封提升至 40 封的流程，使用 sendEmail 操作发送邮件，并读取会话、回复、投递事件和抑制记录
cargo-workspace-management (回顾)	邀请用户、创建 API 令牌、整理文件夹、管理角色，并向管理团队报告 CLI 问题
cargo-mcp (回顾)	无需安装 CLI，即可通过托管的 MCP 服务 https://mcp.getcargo.io/mcp 操作 Cargo——连接客户端、发现并估算操作费用、执行单条记录或批次、轮询状态、读取模型；并在 MCP 工具与 CLI 之间进行路由

用于 RAG 的 Agent 知识： 文件 + 库位于 content 域 → cargo-content；它们如何关联到 Agent → cargo-ai。（文件/库已从旧版 CLI 的 ai file … 路径移出，适用于 ≥ 1.0.19。）

这些技能与 MCP 服务

这里有三种截然不同的东西都叫 MCP。 它们的答案互不相通，因此回复前 请先确认指的是哪一种：

	它是什么	技能
托管服务	Cargo 自己的端点，位于 https://mcp.getcargo.io/mcp。包含 17 个固定的平台工具（发现、定价、执行、轮询、读取模型、读取上下文、用量）。工作区精选的服务通过 /v1/ai/mcpServers/<uuid>/mcp 单独提供。这是在未安装 CLI 的情况下驱动 Cargo 的方式。	cargo-mcp
工作区服务	此工作区发布的一组精选工具（ai mcp-server create --actions … --resources …），通过 cargo-ai mcp 提供给任何 stdio 客户端。	cargo-ai
Agent MCP 客户端	附加到 Cargo Agent 上的其他人的 MCP 服务（release update-draft --mcp-clients）。	cargo-ai

第一种是新推出的；如今“Cargo 有 MCP 服务吗？”指的就是它。它通过自身的 401 质询发现 OAuth 进行身份验证，或使用工作区范围的 bearer token：

claude mcp add --transport http cargo https://mcp.getcargo.io/mcp

第二种是精选工具的路径；当工作区想要公开一个获准的工具，而非整个 平台时，它仍是正确的选择：

claude mcp add cargo -- cargo-ai mcp                    # the platform MCP
claude mcp add cargo -- cargo-ai mcp --server <uuid>    # a curated server instead

如果没有 --server，桥接程序会在设置了 CARGO_MCP_SERVER_UUID 时使用该值， 否则使用平台的 /mcp。（较旧的 CLI 则会回退到“工作区唯一的 MCP 服务”， 若不存在唯一服务则直接失败。）

根据请求的特点，在 CLI 与任一 MCP 接口之间选择：

	这些技能（CLI）	MCP 服务
它是什么	完整的 CLI 接口，涵盖所有领域	平台运行时工具，以及工作区选择公开的工具
最适合	构建可复用内容的一切：工作流、plays、架构变更、项目部署、诊断、导出、数据仓库 SQL	对话中执行：查找此记录、丰富此列表、运行这个获准的工具
成本控制	完整的试运行 → 审批 → 收据流程（../cargo-gtm/references/cost-discipline.md）	按调用计费；search_actions 会在运行前返回每个操作的积分成本
可复现	是 — 命令、plays 和项目文件都是产物	否 — 工具调用不会留下任何产物

经验法则：凡是用户之后想要重跑或进行版本管理的内容，都应放在 CLI 中。 切勿针对列表中的每条记录分别调用 MCP 工具 — 为此已有 execute_action_batch（以及 CLI 上的 orchestration action execute-batch），成本更低且过程可观测。反过来，如果工作区已经为某项任务精选了工具，直接调用它总比用原始操作手动拼装同样的内容更好。

尚无专用技能的 CLI 领域

CLI 还提供了若干尚无能力技能封装的领域。任务需要时可直接使用（cargo-ai <domain> --help）；如果不清楚其功能范围，请提交一份 workspaceManagement report：

CLI 领域	涵盖内容
expression	用于编写节点配置的模板／JS 表达式。eval evaluate --expression '<json>' --variables '<json>' 会用示例变量解析表达式（这是运行前检查 {{…}} 的最快方法）；eval generate --prompt "…" --variables '<json>' 则可根据纯英文内容起草表达式。配方是已保存、可重复使用的表达式：recipe list、recipe get <uuidOrShortId> [version]、recipe create --name … --kind jsExpression|templateExpression --expression … [--instruct-to ai|none] [--placeholders '<json>']、recipe create-new-version、recipe archive <uuid>；favorite-recipe create|delete 可为工作区固定一个配方。
system-of-record	工作区存储所在的数据仓库（bigQuery 或 snowflake）。sor list|get|create --kind … --config '<json>'|update|remove；sor migrate <uuid> 会按顺序将 Cargo 尚未执行的架构迁移应用到该数据仓库；遇到失败的迁移时会停止；sor cutover <uuid> 会将工作区切换到该记录系统，并在后台复制其表（每个工作区一次只能进行一项切换）。这两项都是针对实时存储的管理员操作，运行前请先确认。client query "<sql>"、client fetch、client download 和 client get-documentation <slug> 可直接与数据仓库交互；log list／log get-metrics 可读取其同步日志。若要日常对模型执行 SQL，正确入口是 storage query execute（cargo-storage）。
revenue-organization	销售团队的区域和容量规划：member list|get|update|archive|unarchive 和 member sync --connector-uuid <crm-connector>（从 CRM 拉取销售代表），territory list|get|create|update|remove，capacity list|get|create|update|remove，以及 allocation list|get|remove——当工作流将记录分配给销售代表时，本机 allocate 操作（{"kind":"native","actionSlug":"allocate"}，"choose members of your team"）会写入这些分配记录。
user-management	不需要工作区上下文的当前用户操作。

所有领域之外的顶级命令

CLI 根目录下有 5 个命令，而不是归属某个领域，也没有技能封装这些命令。 这里列出这些命令，是为了让你在用户提到其中某个命令时能够识别它——而不是将其作为路由目标：

命令	说明
cargo-ai doctor	在一个 JSON 对象中诊断设置：已安装版本与最新版本、技能包固定版本、凭据和 API 可访问性。遇到最严重的故障时退出。在开始阅读技能之前，这是回答“为什么这个命令无法正常工作”的最快方法。
cargo-ai start (alias onboard)	如有需要，先让用户登录，然后继续执行以下操作之一：启动编码 Agent（--continue claude|cursor|codex|gemini）、使用 code 搭建项目、使用 cli 打开调色板，或使用 demo 开始导览。支持 --email/--code/--oauth、--workspace-name、--directory、--icp。
cargo-ai ask	在终端中聊天。默认使用此机器上的 Claude Code，并针对工作目录（--dir）；--agent-uuid 会将工作区 Agent 连接到同一会话。--print 会以 JSON 格式将一轮对话输出到 stdout，--continue 会重新打开上次的聊天。也可以通过 cargo-ai --chat 使用。
cargo-ai book-demo	打开日历，预约 Cargo 销售演示。--no-open 会改为打印 URL。
cargo-ai (bare)	当终端支持渲染时，打开交互式调色板。直接运行 cargo-ai project 会打印该分组的帮助信息；不会运行 info 或 init。

其中两个命令与技能手动描述的操作有所重叠：doctor 比手动检查固定版本更适合作为第一步，而 start --continue demo 则是 CLI 自带的 cargo-quickstart 导览。如果你想控制资源消耗，优先使用技能；如果用户只想直接完成操作，则优先使用命令。

---

技能之间的关系

            ┌─────────────────────────────────────┐
            │              cargo-gtm              │
            │   Outcome / front door for GTM      │
            │   Recipes, guides, provider-playbks │
            └─────────────────┬───────────────────┘
                              │ delegates to ↓ (one-way)
       ┌──────────────────────┴──────────────────────┐
       │                                             │
┌──────────────────────────────────────────────────────────────┐
│              cargo-workspace-management                      │
│         Authentication, users, tokens, folders               │
└──────────────────────────────────────────────────────────────┘

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

             ┌───────────────────────────────────────┐
             │             cargo-context             │
             │  Git-backed GTM markdown knowledge:   │
             │  personas, plays, proof, signals…     │
             └───────────────────────────────────────┘
           (orthogonal: not part of the workflow flow)

             ┌───────────────────────────────────────┐
             │               cargo-project               │
             │  Declarative authoring layer: define  │
             │  connectors/models/plays/agents/… as  │
             │  code, deploy with `cargo-ai project`.    │
             └───────────────────────────────────────┘
    (cross-cutting: PRODUCES the same resources the imperative
     skills manage — an alternative mode, not a workflow stage)

             ┌───────────────────────────────────────┐
             │        cargo-mailbox-management       │
             │  Sending inboxes Cargo owns: warm-up, │
             │  send ramp, threads, replies, events, │
             │  suppressions. The send itself is the │
             │  `sendEmail` orchestration action.    │
             └───────────────────────────────────────┘
   (owns the mailbox; orchestration owns the send — and every
    send is gated by cargo-gtm's acceptable-use checks)

             ┌───────────────────────────────────────┐
             │           cargo-observability         │
             │  Scheduled threshold alerts over the  │
             │  telemetry above (spans/runs/records), │
             │  a model's health, or a SQL query —    │
             │  fire actions as runs on breach.       │
             └───────────────────────────────────────┘
     (watches orchestration/storage; fires orchestration
      actions — proactive counterpart to cargo-diagnostics)

实际依赖规则：

• cargo-gtm 通过相对路径（../cargo-orchestration/...）调用能力技能。能力技能不会引用 cargo-gtm。
• cargo-workspace-management 为每项技能提供身份验证上下文——请先完成设置。
• cargo-storage、cargo-connection 和 cargo-ai 是同级技能，负责向 cargo-orchestration 提供 UUID。它们互不依赖。
• cargo-content 管理工作区的文件和库（content 域）。它会生成供 cargo-ai 用作 Agent 发布 resources（RAG）的文件/库 UUID，同时也是文件存储：可通过 CLI、worker（createCargoObjects）、play（writeFile/readFile/getFileUrl 节点）或 Agent（可写文件夹）按路径写入和读取文件、列出文件夹，以及提供签名链接或公开链接。mirrorToContext: true 的文件（上传和 defineFile 的默认设置，按路径写入时除外）也会提交到上下文仓库的 .files/ 下，并由 cargo-context 运行时以只读方式访问。
• cargo-mailbox-management 管理发送邮箱（mailboxManagement 域）——包括配置、预热、发送量递增、线程、事件和工作区抑制列表。它刻意不负责发送：投递由 cargo-orchestration 下的原生操作 sendEmail 执行，因此发送会沿用 orchestration 的节奏控制、重试和额度核算。也可以通过项目中的 defineMailbox 声明邮箱（发送域使用 defineDomain）。
• cargo-project 是一项横切能力：它是一种声明式创作模式，能够创建命令式能力技能逐个管理的连接器、模型、play、Agent 等资源。若任务是“通过项目管理工作区”（GTM as Code：可复现、纳入 git、多资源），则使用它；若是一次性操作、读取和临时查询，则使用命令式领域技能。参见“快速了解各项技能”中的“声明式与命令式”。
• cargo-context 与工作流执行流程正交。它操作由 git 支持的 GTM 知识库（markdown/MDX），而非存储或工作流运行。使用它来记录/编辑工作区的文本上下文——角色、play、证明、异议、信号——以及检查类型化知识图谱。
• 对存储执行 SQL 查询时，使用 cargo-ai storage query execute "<sql>"（表名格式为 <datasetSlug>.<modelSlug>）。加载 cargo-storage 以查找数据集和模型 slug，并在需要列类型或 SQL 方言时获取 DDL。
• 对 orchestration 运行时表（runs、batches、spans、records）执行 SQL 查询，以查看错误率、各节点失败情况和时间序列时，使用 cargo-ai orchestration query execute "<sql>"。工作区范围会自动限定；引用表时无需添加 schema 前缀。
• 构建工作流节点图之前，先加载 cargo-connection 以获取 connectorUuid 和 actionSlug。如果有任何节点调用基于额度的服务商操作，还要加载 cargo-gtm，并阅读该服务商的 playbook（../cargo-gtm/provider-playbooks/<slug>.md）。如果工作流是定时工具或 play，还必须阅读其中的重复使用部分，因为错误的配置或频率会导致每次运行都再次扣费。即使任务直接通过 cargo-orchestration 或 cargo-project 提出，而没有 GTM 背景，也同样适用。
• 执行使用 Agent 节点的工作流之前，加载 cargo-ai 以获取 agentUuid。
• 运行完成后，加载 cargo-analytics 以下载结果或衡量性能。获取操作输出时，优先使用 cargo-ai orchestration run download-outputs，而不是 run download——前者返回一个带签名 URL 的 CSV/JSON，其中仅包含输出节点的数据。
• 加载 cargo-billing 以了解上述任一操作的额度消耗情况。
• 如果运行失败、运行“成功但结果看起来不对”、批次出错或 play 成本过高，请加载 cargo-diagnostics——它会将 run get、orchestration SQL 和计费数据整合成取证操作手册（追踪单次运行、扫描批次、分析额度支出）。
• 如果希望在问题发生时就收到通知，而不是主动查找——例如错误率飙升、达到成本上限、节点运行缓慢、同步停滞或工作流停止运行——请加载 cargo-observability。它会创建警报：针对相同遥测数据（spans/runs/records）、模型运行状况或 SQL 查询定时检查阈值，并在超出阈值时触发操作。Diagnostics 是被动响应（解释发生了什么）；observability 是主动监控（持续关注问题）。也可以通过项目中的 defineAlert 声明警报。

---

各技能的关键规则

每项技能中不那么显而易见的规则——猜错时可能悄无声息地失败或造成开销的事项。每项技能自己的 SKILL.md 都包含完整说明；以下是你在选择前值得了解的内容。

cargo-gtm

附带的操作指南：

操作指南	适用场景……
recipes/source-planning.md	在投入成本前决定数据来源：探查候选来源，了解每次命中的成本。
recipes/prospecting.md	端到端完成查找 → 丰富数据 → 验证 → 同步（P1/P2/P3 变体）。
recipes/build-tam.md	大规模构建总潜在市场名单（100–10,000 家公司）。
recipes/linkedin-url-lookup.md	根据姓名和公司查找 LinkedIn URL，并进行严格验证。
recipes/portfolio-prospecting.md	投资者 / 加速器 → 投资组合公司 → 联系人。
recipes/job-change-monitoring.md	对联系人分群使用 waterfall.detectJobChange（cargo 独有）。
recipes/funding-watch.md	跟踪近期获得融资的公司。
recipes/tech-intent.md	根据技术栈或招聘意向信号查找公司。
recipes/icp-discovery.md	对比 Closed-Won 与 Closed-Lost 分群，发掘 ICP 信号。
recipes/custom-datapoints.md	设计要收集的自定义属性和实时信号；须以真实数据来源和成本为依据。
recipes/outreach-activation.md	将信号分群转化为可直接发送的外联名单（丰富数据 → 验证 → 个性化 → 移交给序列工具）。
recipes/ads-audience-activation.md	将分群推送到 Google Ads Customer Match / LinkedIn Matched Audiences。
recipes/review-and-iterate.md	对判断结果进行人工审核；修正内容会成为永久规则。
recipes/re-engagement.md	仅在触发新信号（职位变动、融资、技术意向）时重新激活过时联系人。
recipes/lost-deal-revival.md	根据 lost_reason（关键支持者离职、预算、时机）分支，重新激活 CRM 中 Closed-Lost 的交易。
recipes/account-expansion.md	深入拓展客户账户——寻找新买家，并与 Contacts 模型去重。

优先服务商组合（操作指南优先介绍这些服务）：salesNavigator（数据来源）、aiArk（以 LinkedIn 为锚点的数据丰富，以及目录中成本最低的公司数据丰富与搜索）、waterfall（多来源数据丰富 + 邮箱验证 + 职位变动）、FullEnrich（高级联系人查找）、apolloio（1 个积分的细分覆盖数据丰富）、theirStack（技术栈 + 招聘意向）、peopleDataLabs（重度补充数据）。**已经有 LinkedIn URL（或活动 URL）？**无需查找来源——直接使用 aiArk.enrichPerson（0.1，可获取个人资料 + 已验证邮箱，没有邮箱时不计费），或者在不需要邮箱时使用 linkedin（enrichProfile/enrichCompany 0.25、extractEventAttendees）；这些是成本最低的 URL 锚定数据丰富方式，但很容易被忽略，因为上面的组合优先从数据来源入手。 关键规则：

• 所有涉及人员的步骤都必须符合可接受使用规则（../cargo-gtm/references/acceptable-use.md）：只能使用获许可提供商提供的 B2B 专业身份信息；在任何外联步骤之前，必须先完成三项免费的拦截检查（依据、抑制、相关性）；并遵守拒绝清单——无差别地批量触达、针对消费者、来源不明的名单、联系已抑制的记录、规避筛选条件或身份验证、自动拨号、批量执行 LinkedIn 互动操作，以及从用户的 X 账号（xAccount）批量或自动发帖／回复／点赞／发送私信。此工具包绝不发送消息：外联流程止于准备好可供用户自己的序列工具使用的变量。
• 所有配方都使用按积分计费的操作——目录公开的 594 项操作中有 190 项，价格列于 ../cargo-gtm/references/credits-cost-table.md，该表由 cargo-ai orchestration action list --kind connector / --kind native 重新生成（免费，只读取目录）；每项计费操作都会返回一个 credits 数组。其余 404 项操作没有 提供商 价格——但工作流中运行的任何内容都不是免费的：每次节点执行都会扣除 0.01 积分（每 100 次扣 1 积分），包括结构型原生操作（branch、filter、switch、variables）。成本表列出的是操作价格，而非步骤价格；请参阅 ../cargo-billing/SKILL.md →“执行费用”。
• 操作结构：{"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>"}——顶层操作中不能有 config，并且 connectorUuid 绝不会嵌套在其中；它位于节点的顶层。
• 输出获取：cargo-ai orchestration run download-outputs --output-node-slug <slug>（不是 run download）。
• peopleDataLabs 筛选器结构：searchX 使用 cargo 的 {conjonction, groups, conditions} 结构；queryX 接受 PDL SQL 字符串，绝不可使用 Elasticsearch。

cargo-orchestration

关键规则：

• 何时使用 action execute、run create 还是 batch create，请参阅 ../cargo-orchestration/SKILL.md 顶部的决策流程图。
• 首次尝试时，绝不要让整个批次加入处理。 batch create / action execute-batch 会对来源中的每条记录执行操作。先抽样 10–20 条记录，报告观察到的成本和命中率，然后请用户批准处理全部记录——同时注明记录数和预计积分数。操作方法：../cargo-orchestration/SKILL.md →「创建批次」；支出规则：../cargo-gtm/references/cost-discipline.md §1。
• 搜索操作，不要在目录中浏览查找。 cargo-ai orchestration action list <keywords> [--kind connector|native|tool|agent] [--integration-slug <slug>] [--limit 20] 通过一次免费的调用，涵盖集成目录、Cargo 原生操作、工作区工具和 Agent，并返回可直接粘贴的 action 对象（已解析 connectorUuid）以及该操作的积分成本。它的同类命令 cargo-ai connection action search <keywords> 仅搜索连接器，但额外提供了 --credits-only 筛选项，这是 action list 唯一缺少的筛选项。二者都优于分页浏览 connection integration list；只有在选定操作并需要完整输入架构时，才使用 integration get <slug>。
• 在 action execute / action execute-batch 中省略 config——输入应放在 --data / --records 中。这与 action list 返回的格式一致，因此可以直接粘贴其结果。action get-output-schema 使用相同格式（如果架构取决于输入，则通过 --data 提供输入）。工作流节点、警报 --actions、play healthAlertActions，以及 Agent / MCP 服务的 --actions 仍需携带 config。错误地将输入放在 config 中时，这些输入会被删除，且不会出现指出 config 的错误，因此输入永远不会到达：如果操作有必填输入，系统会在运行前因缺少该字段而拒绝执行；如果没有必填输入，则会在没有任何输入的情况下运行。拼写错误或未声明的输入键会在创建运行前被拒绝（invalidData、Unknown field: <key>，包括嵌套键；在批次中，一条记录出错就会拒绝整个批次）——但工具操作、多余的顶层批次列以及工作流节点内部的情况除外；这些场景中的未知键仍会被静默丢弃。
• 运行操作时，默认使用 action execute；node execute 仅用于调试。 仅在测试你正在编写的工作流中的单个节点时使用 node execute——它需要 --workflow-uuid、--release-uuid、--node、--computed-config 和 --context（全部五项）。其他所有操作——丰富记录、调用连接器操作、调用工具或 Agent——都应通过 action execute / action execute-batch 执行。
• 按以下顺序，使用专用操作 + 表达式构建节点图： (1) 专用操作，先用 orchestration action list <keywords> 查找（连接器操作，以及 agent、modelUpsert、branch、group 等原生操作）；(2) 用表达式处理衔接逻辑，因为表达式是在需要该值的字段中内联编写的 JavaScript；(3) 仅当该 API 没有对应操作时才使用 HTTP；(4) 仅当逻辑无法用表达式实现时，才使用 script / python 节点。请参阅 ../cargo-orchestration/references/node-selection.md。
• 展示节点图，不要用文字描述。 部署草稿前，以及用户询问工作流或 play 的执行方式时，请运行 cargo-ai orchestration node diagram --workflow-uuid <uuid> --raw（免费，不会运行任何操作，CLI ≥ 1.0.54；references/node-diagram.md）。路由、回退边以及哪些节点会产生费用，都是审批内容。让命令绘制图表，而不要手动转述——节点 slug 在同一发布版本中会重复，因此按 slug 手绘图表会合并并非同一节点的节点。
• 筛选 JSON 使用 conjonction（而非 conjunction）。这是必填键，拼写错误会被以 400 错误拒绝。
• 使用 cargo-ai orchestration query execute "<sql>" 查询编排运行时表（ClickHouse）：runs、batches、spans、records（不带架构前缀；工作区范围会自动应用）。
• 对工作区存储（Companies、Contacts 等）执行 SQL 时，使用 cargo-ai storage query execute "<sql>"——相关文档位于 cargo-storage。
• 所有操作均为异步——请轮询，或传入 --wait-until-finished。请参阅异步轮询。

cargo-analytics

关键规则：

• segment download 需要 --model-uuid，而不是 --segment-uuid。
• 要下载批次结果，请从 release get <release-uuid> → nodes[].slug 获取 output-node-slug。
• 要查询账单和额度使用情况，请改用 cargo-billing。
• Analytics 回答“发生了什么”（指标、计数、导出）。如果问题是为什么——某次运行失败、批次中满是错误、成本出乎意料——请转交给 cargo-diagnostics；其排查运行手册会从 analytics 的错误计数处继续排查。

cargo-billing

关键规则：

• 需要具有管理员权限的令牌。
• 发票金额以美分为单位——除以 100 即为美元。
• subscription get（.subscription 下）的 subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount = 剩余额度。
• 每次节点执行计费 0.01 个额度（每 100 次计 1 个）——包括结构性原生节点，也包括执行出错的情况。此费用不归属于任何节点（executions[].creditsUsedCount 仅表示提供方成本），因此任何未计入此项的估算或逐节点分析都会低估。只有 usage get-metrics --unit orchestration.executions 才会显示此项；--unit 只能取 billing.credits / orchestration.executions / storage.records / hosting.events，不指定 --unit 时，这四类数据会以不同的 count 含义交错出现在同一个 items[] 数组中。

cargo-diagnostics

关键规则：

• 不知道该检查哪次运行时，从全面排查开始；排查结束时会提供用于追踪的示例 UUID。完全没有 UUID 时，orchestration trace list --started-after <iso> --statuses error,degraded 会列出失败项，每次触发（包括子运行中的触发）占一行；span list / span count 无需 SQL，即可按批次、提供方、操作或错误文本筛选节点执行记录。两者都需要开始日期（--started-after / --execution-started-after）。
• degraded 表示回退机制吸收了一次故障——运行成功了，但某个节点出错。排查时要与 error 一起检查。
• runContext 是节点产出内容的事实来源；执行记录的 title 是截断后的摘要，绝不能作为证据。
• 归因额度（billing …）需要管理员令牌；SQL 和 run get 步骤不需要。
• 任何会重新运行付费节点的修复，都必须通过 ../cargo-gtm/references/cost-discipline.md 中的试点门槛。
• Diagnostics 负责解释，不负责导出。诊断后如需批量检索（run download-outputs、batch download、segment download），请返回 cargo-analytics。
• 先给出结论，再用简洁的表格列出证据——遵循 cargo 路由器技能中的 references/interaction.md。

cargo-observability

关键规则：

• 先运行 preview，再运行 create。 alert preview --scope … --threshold … [--window-minutes 60] 会立即评估，但不会触发告警——这是根据实际情况设定阈值，并在无效的作用域与阈值组合（outcome: "notComputed"）变成每个周期都会报错的计划任务之前发现问题的唯一方法。
• 作用域和阈值必须匹配。 遥测指标（errorRate、duration+聚合方式、credits+聚合方式、count）需要 spans/runs/records；query 需要查询作用域；recordsCount/recordsShare/freshness/syncDuration 需要 model。完整对照表和单位见 references/scopes-and-thresholds.md。
• 空窗口不等于真实的零值。 大多数指标会将无活动的窗口报告为 empty（状态正常，不触发告警）。只有 count 和 recordsCount 会返回真实的 0——搭配 lte 0 可实现失联告警（在工作流停止运行或模型变为空时触发告警）。
• 触发最多执行一次，并会消耗积分。 操作会作为运行触发（事件中包含 runUuids）；如果违规状态持续，每个仍满足条件的周期都会再次触发，但绝不会对相同的行重复触发。如果操作调用了收费的服务商，请遵循 ../cargo-gtm/references/cost-discipline.md——计划告警每次违规都会再次计费。
• --enabled 严格区分（仅允许 true/false）；模型作用域的 filter 使用拼写为 conjonction 的分组格式。
• 权限为 observability:read / observability:write（并非仅限管理员）。声明式等效功能是项目的 defineAlert——参见 cargo-project。

cargo-storage

关键规则：

• 使用 <datasetSlug>.<modelSlug> 表名（例如 default.companies），通过 cargo-ai storage query execute "<sql>" 查询（完整导出则使用 storage query download --query "<sql>"）。model get-ddl 为可选命令，可用于查看列类型和 SQL 方言。
• 查询编排运行时表（runs/batches/spans/records）时，请使用 cargo-ai orchestration query execute "<sql>"——相关文档见 cargo-orchestration。
• 执行高级记录查询（筛选、排序、分页）时，请使用 segmentation segment fetch——相关文档见 cargo-segmentation。
• storage relationship set 会替换数据集的整个关系集——载荷中未包含的关系都会被删除。请先运行 list，再发送完整数组。

cargo-segmentation

关键规则：

• 筛选器 JSON 使用 conjonction（而不是 conjunction）。筛选器和分组层级都必须包含该字段，因此拼写错误会导致请求被拒绝并返回 400；conditions: [] 的分组也会被拒绝。
• 花钱之前先确认规模。 segment fetch --fetching-limit 1 可免费统计内联筛选器的数量（读取 count；--limit 会限制成员本身，因此 --limit 1 会报告 1）；已保存分群的 recordsCount 是权威规模。在为受众提出任何付费运行方案之前，请先报出该数量。
• segment download 需要 --model-uuid 和筛选器，绝不能使用 --segment-uuid。
• change list 需要 --segment-uuid；change fetch 需要变更 UUID 和 --kinds（added/updated/removed/unchanged）。
• 除非创建分群时指定了 --tracking-column-slugs，否则 updatedRecordsCount 始终为 0——这些列决定了“已更新”的含义。
• 名为 GENERATED_PLAY_SEGMENT（fromPlay: true）的分群由 play 所有。切勿手动编辑或删除。

cargo-connection

关键概念：

• 集成 = 外部服务类型（HubSpot、Clearbit、Salesforce 等）
• 连接器 = 某个集成经过身份验证的实例（通过节点中的 connectorUuid 引用）

cargo-ai

关键规则：

• 用于 RAG 的知识通过版本的 resources 关联到 Agent：文件 + 知识库来自 cargo-content。使用 release update-draft --resources … 将其接入，然后运行 release deploy-draft。
• 不带 --server 的 cargo-ai mcp 现在会桥接第一方平台 MCP（mcp.getcargo.io/mcp），而不是“工作区唯一的 MCP 服务”。ai mcp-server 仍会构建一个精选服务；传入其 uuid 作为 --server。请参阅上文“这些技能与 Cargo 的 MCP 接入面”。
• 编码 Agent（在版本或新聊天中使用 --harness-slug + --repository）会以 Cargo GitHub 应用的身份推送，因此必须在仓库中安装该应用；其令牌仅限于该仓库，它会在 cargo/<name> 分支上工作，绝不会推送到默认分支，并且在其 PR 上提及它会继续该聊天。创建聊天时，Harness 和仓库即固定；使用 --chat-uuid 时传入它们会被拒绝。
• **CLI ≥ 1.0.19：**文件和知识库已从 ai 域移至顶层 content 域（现在是 cargo-content 技能）。旧的 cargo-ai ai file … 命令已不存在。

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

请参阅 ../cargo-ai/SKILL.md，了解按使用场景划分的模型和温度建议。

cargo-content

关键规则：

• CLI ≥ 1.0.19 中新增顶层 content 域：cargo-ai content file … / cargo-ai content library …。旧的 cargo-ai ai file … 路径已移除（出现 unknown command → 说明你使用的是旧路径；请升级 CLI）。
• 文件或知识库只有关联到 Agent 已部署版本的 resources 后才会生效——这项接入配置位于 cargo-ai。
• upload 和 put 的默认行为不同。upload（以及 defineFile）会为 Agent 搜索建立文件索引，并将文件镜像到上下文仓库的 .files/ 目录下（会提交并推送）；content file put 和其他所有写入路径则只会存储文件——除非使用 --index vectorStore 写入，否则 Agent 无法搜索到该文件；文件也不会进入 git。
• 链接无需身份验证。content file url 会返回一个签名链接，任何人都可以在链接过期前打开（默认 1 h，最长 3 h）；public 文件则有一个稳定的免验证链接，直到文件被设为私有。只有在用户要求分享该文件时，才分享这两种链接。
• 对于批量运行的输入文件（用于驱动批量任务的 CSV），请使用 cargo-ai workspaceManagement file upload（这是另一个接入面）——请参阅 cargo-workspace-management。

cargo-context

关键概念：

• 上下文仓库 = 为工作区上下文提供支持的 GitHub 仓库。典型示例：getcargohq/cargo-workspaces。文件使用 kebab-case.md 命名，包含必填的 title + description YAML frontmatter，以及 domain/slug 交叉引用（不带 .md）。
• 运行时沙箱 = 已检出且可执行的上下文仓库副本。runtime write 和 runtime edit 会推送到默认分支；runtime execute 不会推送。
• 知识图谱 = 覆盖每个 md/mdx 文件的类型化图谱，每个节点包含 frontmatter 和出站交叉引用。通过 cargo-ai context graph get 构建。

关键规则：

• runtime write / runtime edit 会提交并推送。runtime execute 是临时的——可用于 grep/ls/检查，切勿用于持久性更改。
• runtime edit --old-string 必须与文件内容完全匹配一次（除非使用 --replace-all）。先读取文件，再原样复制空白字符。
• 为每个 .md/.mdx 文件设置 title + description frontmatter——这是强烈建议的惯例，但不会强制执行：缺失或格式错误的 frontmatter 仍会由 runtime write/edit 提交，只是索引效果较差（图谱会回退到文件名 + 第一段，并读取 summary，而非 description）。在项目中声明的上下文（defineContext）要求更严格：若 frontmatter 无法解析，或 references: 条目、[[wikilink]] 或相对 .md 链接与任何已声明文件都不匹配，则 project check/plan/deploy 会失败（缺少 title/description 仍可通过）。
• 图谱边仅由 frontmatter 中的 references:、Markdown 链接或 wikilink 生成——正文中的裸路径不会创建边。请在 references: 中引用源文件。
• 有关域、惯例和各域模板，请参阅 ../cargo-context/references/conventions.md。

生命周期：

• 有关从某个域（ICP、人物角色、证明、信号）为全新工作区引导上下文的说明（幂等，会跳过已播种的域），请参阅 ../cargo-context/references/examples/bootstrap-from-domain.md。
• 有关完整的引导 + 持续按调用驱动的刷新操作手册（阶段 1 + 阶段 2 + 执行频率），请参阅 ../cargo-context/references/examples/lifecycle.md。

cargo-hosting

生命周期： init（本地脚手架）→ create（创建槽位和工作区内唯一的 slug）→ deployment create（构建并上传）→ deployment promote（上线）。

关键规则：

• --slug 在每个工作区内唯一；线上主机地址为 <slug>-<workspace prefix>.<root>，应用和工作进程使用不同的根域名。不要自行拼接 URL，应从 get 读取 url。因此，应用调用工作进程属于跨源调用：工作进程必须响应 CORS。
• 默认情况下不会注入 CARGO_API_TOKEN。没有该变量时，createCargoApi 会抛出错误。唯一例外是：设置了服务用户的工作进程（hosting worker update --uuid <uuid> --run-as-user-uuid <service-user-uuid>）在每次发布时都会获得该用户的临时令牌，并将其作为 CARGO_API_TOKEN，除非工作进程或工作区环境中已设置该键。否则，请生成令牌并将其存储为密钥环境变量：通过 workspaceManagement envVar create --secret 设置整个工作区范围的变量，或通过 hosting worker env set --worker-uuid <uuid> --key CARGO_API_TOKEN --secret 为单个工作进程设置（从标准输入传入 --value -，或使用同名本地变量中的值），也可以在项目中使用 defineWorker({ env })。环境变量在 promote 时绑定，因此任何更改后都必须重新部署并 promote。
• 工作进程中的 catch 若要返回经过清理的错误，必须先执行 console.error(err)。只有未捕获的错误才会连同堆栈信息写入日志。
• 部署不等于上线。 deployment create 负责构建；只有执行 deployment promote，URL 才会切换。deployment get-promoted 可查看当前线上版本。
• --source 指的是包根目录，而不是 dist/；构建在服务端运行：如果应用的 package.json 声明了 build 脚本，则运行该脚本（由它负责整个构建）；否则，使用检测到的框架默认命令（vite build、next build 等）；工作进程则会进行打包。
• 应用环境变量必须带有公开前缀（VITE_、NEXT_PUBLIC_ 等），会被编译进公开包中，且不能设为密钥（secretNotSupportedForApp）。
• Cargo 所有的主机会发送 X-Robots-Tag: noindex；应用只有部署到自定义域名（POST /v1/hosting/custom-domains）并提供预渲染 HTML 时，才能被搜索引擎索引。
• 构建是异步的；promote 前应轮询 deployment get，直到构建进入终态。
• 部署命令中的 --app-uuid 和 --worker-uuid 互斥；remove 会级联删除部署。
• 文件夹来自 cargo-workspace-management；--folder-uuid null 会将其移至根目录。

cargo-project

在项目中声明整个 Cargo 工作区。项目是存放 cargo.json 的文件夹，使用 TypeScript（defineConnector/defineModel/defineAgent/ definePlay/defineTool/defineMcpServer/defineContext/defineSegment/ defineFolder/defineFile/defineWorker/defineApp/defineCapacity/defineTerritory/ defineMember/defineRole/defineUser/defineRelationship/defineCustomIntegration/ defineScript/defineAlert/defineDomain/ defineMailbox，以及仅运行一次的 defineBatch/defineRun 执行），并通过 cargo-ai project 将其与线上基础设施协调一致。它涵盖所有资源类型，因此与每项命令式能力技能都有重叠——请参照上文“声明式与命令式”进行选择。

生命周期： project init（搭建 Cargo 模板 getcargohq/cargo-manifest：包含上下文、节奏和评估；在根目录创建 cargo.json 和 cargo.state.json，所部署的资源放在 infra/ 中）→ project types（针对工作区配置类型）→ 编写 define* 文件 → project plan（与工作区保存的状态进行差异比对；不会创建任何内容）→ project deploy（创建或更新资源，并写入状态）→ project destroy。此外还有 refresh（检查漂移并指出字段）、import（接管现有资源）、pull（根据线上工作区生成 define* 并接管资源）、rollback、check（离线验证，不读取状态）、info（查看当前内容）、graph（生成线上工作区的 Mermaid 图，或离线运行 --project [--plan]）、state（检查、重定向或移除状态；可通过 connect 从 GitHub 部署）。即使已登出，project plan 仍可基于上次缓存的状态运行。

关键规则：

• 提交 cargo.state.json——但要知道它是一个指针（{"stateUuid": "…"}）， 而不是状态本身。部署状态存放在工作区中，它是访问已部署的流程/Agent/警报的 唯一凭据（没有 slug）；丢失指针可通过 project state bind 找回，丢失状态则 会使它们成为孤立对象。project state list|create|bind|remove。
• 项目是存放 cargo.json 的文件夹（{ "resources": "infra" }）。每条 命令都会向上查找最近的项目（最远到仓库根目录），找不到就停止，并输出 echo '{ "resources": "infra" }' > cargo.json。cargo.state.json 与 cargo.json 放在一起，绝不能放进 infra/；如果遗留的 infra/cargo.state.json 存在，命令会停止并提示执行 mv。一个包含多个项目的 仓库中，每个项目各有一个 cargo.json。
• 按句柄连线，而不是按 .uuid——传入 define* 句柄或 xxRef("uuid")。
• 有三个值助手函数，而不是一个。 secret("ENV_VAR") 会在部署时读取你 的环境变量，并且不会写入状态或内容哈希（因此轮换密钥后，需要执行 deploy --refresh 才会真正生效）；env("ENV_VAR") 会按预期纳入哈希； workspaceEnv("NAME") 是一个指针，服务每次使用时都会重新读取，因此在工作区中 轮换它无需重新部署。
• 非交互式执行 deploy/destroy 时必须使用 --yes（CI）。
• 工作区集成变更后运行 cargo-ai project types，以便配置通过类型检查； 类型检查是额外保障，没有它也能部署。
• **使用基于额度的连接器操作的 definePlay/defineTool 图：**在执行 project deploy 前，先阅读提供商的操作手册 ../cargo-gtm/provider-playbooks/（尤其是其中的 Recurring use 部分）——已部署的流程每次按计划运行时都会对其节点重复计费。
• defineBatch / defineRun 只会在下一次部署时运行一次，且无法撤销。 outputs/ 下的文件会声明执行任务，这些任务会在资源应用后启动真实批次或运行； 工作区中保存的状态账本会确保每个 ID 只运行一次（不会重试——换一个新 ID 就会再次运行）。 对某个细分群体或筛选条件执行的任务属于完整批次：部署前必须按照 ../cargo-gtm/references/cost-discipline.md 进行试点并获批。指南： ../cargo-project/guides/executions.md。
• 通过连接仓库从 GitHub 部署，不要在 Actions 中使用令牌。 cargo-ai project state connect 会在评论中为每个 PR 制定计划，并为生产分支上的每次 推送部署——连接时也会部署该分支的最新提交。如果合并内容超过 100 次同类发送、 5,000 个受众添加或 2,500 个额度，则会因 Needs approval: large impact 而失败， 直到为 PR 添加 cargo:approve-impact 标签；该标签只能由用户明确同意后添加。 同时运行 Actions 部署也会失败（stateAutoDeployed）。操作方法： ../cargo-project/recipes/deploy-from-ci.md。

附带的操作指南： recipes/scaffold-a-project.md、add-connector-and-model.md、 build-an-agent.md、migrate-existing-workspace.md、deploy-from-ci.md。

实用手册： 大约 20 个预先编写的 GTM 成果方案（TAM 构建、 账户评分、通话记录、入站线索资格判定、CRM 丰富化等）位于 getcargohq/gtm-skills，与其中的单次使用 技能并列。菜单位于本地： ../cargo-project/references/cookbooks.md。 从头编写常见 GTM 成果方案前，先查看此菜单。

路由判断的关键在于区分一次性需求与持续性需求。“构建我们的 TAM”在用户今天 只想要一份名单时对应 cargo-gtm；在用户想要一条持续产出名单的流水线时对应 tam-building。措辞相同；要留意用户是否希望结果持续产出。每个实用手册都是一个 完整的示例，由安装它的 Agent 复制到项目中并进行调整，而不是需要填写的模板： npx skills add getcargohq/gtm-skills/<name>。注意事项和 --force 警告请参阅 ../cargo-project/SKILL.md 中的相关章节。

cargo-mailbox-management

关键规则：

• 邮箱是按月、定期扣费的额度，而不是按记录扣费——每个邮箱每月 100–125 个额度（共享邮箱和私人邮箱为 100，google 为 125；实时价格请运行 mailboxManagement pricing get），只要邮箱存在就会持续扣费。只有 mailbox remove 可以停止扣费；没有暂停功能。在首次执行 create 前，请说明邮箱总数和每月的额度估算，并征得明确同意。
• 此域不会发送邮件。 发送邮件的原生操作是 sendEmail（{"kind":"native","actionSlug":"sendEmail"}，输入项放在 --data 中），每次发送消耗 0.1 个额度，通过 cargo-orchestration 运行。调用该操作的 play 每次运行都会再次计费，并再次联系收件人。
• 发送量是逐步提升的过程，不是一个设置项。 实际发送量会从 warmupStartedAt 起，在 45 天内从每天 5 封线性增长到每天 40 封。未运行过 start-warmup 的邮箱会永远固定在每天 5 封；stop-warmup 会将起始时间重置到第 0 天；dailySendLimit 只能收紧增长曲线，不能放宽。
• 每次发送都必须遵守 ../cargo-gtm/references/acceptable-use.md §3（依据、抑制、相关性）。抑制名单在整个工作区范围内生效，每次发送前都会检查，且没有移除命令；List-Unsubscribe 会自动将地址写入名单。提高发送量，或将同一营销活动分散到更多邮箱以达到相同发送量，属于 §2 所述的规避行为，必须拒绝。
• 这里没有任何异步操作——没有需要轮询的运行。看起来像例外的情况是：mailbox create 会返回 status: "pending"，需通过 mailbox refresh-status 清除，而不是通过 run get。
• --type outlook 虽然被该标志接受，但始终会失败（transportNotSupported——Graph 投递功能尚未发布）。--statuses/--kinds/--reasons 的值需用逗号分隔，且不能包含空格。mailbox list 是唯一不支持 count 的列表命令；mailbox/suppression 列表没有默认限制（上限为 1000），而 message/thread/event 列表的默认上限为 50。
• 目前没有任何内容会生成 bounced——没有解析投递状态通知的功能，因此退信不会生成事件，也不会自动加入抑制名单。退信计数为空时，绝不能报告为列表状态正常。
• 命令行界面没有发送域的相关功能。 mailbox create --domain-uuid 是必需参数，而 domainManagement 没有 cargo-ai 命令——请从 Web 应用或项目的 defineDomain 中获取 UUID。所需权限为 mailboxManagement:read / :write（并非仅管理员可用）。

cargo-workspace-management

关键规则：

• 大多数命令都需要具有管理员访问权限的令牌。
• 自动化以服务用户身份运行，而非以个人身份运行。 服务用户（kind: "service"）通过 API、Web 应用或 defineUser 创建——CLI 中的 user create 只会邀请个人用户。将服务用户指定为 worker 或编码 Agent 的运行身份时，你的权限必须涵盖该服务用户自身的所有权限（否则会出现 runAsUserNotPermitted）。
• workspaceManagement token create 必须带上 --name（旧版 --from-user 标志已移除）。名称应能清楚说明令牌用途，以便之后在 token list 中识别。
• 令牌值属于机密信息；token list 不仅会返回 token create 创建的令牌，还会返回你自己的令牌（管理员还可查看服务用户令牌）。请将其存入机密管理器（GitHub Secrets、AWS Secrets Manager 等），切勿粘贴 token list 的输出。
• CLI 报错、使用方式不正确，或你（用户或 Agent）在 CLI 任务中难以取得进展时，务必提交 workspaceManagement report create——请参阅本文件开头的部分以及 ../cargo-workspace-management/references/examples/reports.md。

cargo-mcp

关键规则：

• 每次会话都先运行 whoami。 令牌会将会话绑定到唯一一个工作区，且无法覆盖。会话若绑定到错误的工作区，就会返回属于他人的真实记录，看起来像是成功了。
• 切勿对列表循环调用 execute_action——execute_action_batch 成本更低、过程可观测，并且会返回一个对象和一个输出 CSV。
• search_actions 会返回每个操作的 credits[].cost，因此运行前先报出价格，并在全面扇出前抽样 10–20 条记录。
• query_models 会运行一条只读 SQL SELECT（允许联接、聚合和 CTE），并限制返回行数（默认 20 条，最多 50 条）：应在 SQL 中进行聚合，而不是分页读取所有行。完整导出请使用 cargo-storage。
• 平台端点会向每个工作区提供同一组固定工具列表。通过 defineMcpServer / ai mcp-server create 发布的服务是独立端点（cargo-ai mcp --server <uuid>）。

异步轮询

所有操作都是异步的。传入 --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 流转

请参阅 references/uuid-flow.md——该文档提供跨技能边界传递的每种 UUID 和 slug（workflowUuid、modelUuid、connectorUuid、actionSlug 等）的生产者/消费者表、运行任何工作流前的标准发现流程，以及在 UI 中解析 UUID 的 app.getcargo.io URL 模式。

---

端到端用例

请参阅 references/use-cases.md——其中包含 8 个完整示例（单条记录补充信息、批量处理 + CRM 同步、AI 潜在客户评分、从头创建自定义工作流、错误监控、新工作区初始化、带筛选 + 排序的细分导出、GTM 上下文审计），展示每种情况下要加载哪些技能，以及对应的命令顺序。

---

常见陷阱

请参阅 references/gotchas.md——其中介绍容易导致静默失败的问题，以及经常混淆的命令对（conjonction 拼写、run create 与 batch create、--model-uuid 与 --segment-uuid、存储查询表命名、令牌值是机密、发票金额以美分计、第三方连接器速率限制、context runtime execute 与 write / edit 等）。