Back to Details

cargo-project

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cargo project — a Cargo workspace, declared in a repo

Cargo project — 在仓库中声明的Cargo工作区

Use this skill to define a Cargo workspace in TypeScript (
define*
builders from 
@cargo-ai/cdk
) and reconcile it to live infrastructure with 
cargo-ai project deploy
. It is the declarative counterpart to the imperative capability skills: instead of running one CLI command per resource, you write the whole graph once and deploy it repeatably, with a deploy state — held in your workspace, pointed at by a committed 
cargo.state.json
— linking your code to what Cargo created.
"Project" and "workspace" are two different things — keep them apart. A workspace is the Cargo tenant you sign into: it holds the models, connectors, agents, mailboxes and credits, and it is what 
login --workspace-name
selects and what 
whoami
reports. A project is the repo that declares resources and deploys them into a workspace: it is what 
project init
scaffolds, what 
cargo.state.json
points from, and what 
--dir
locates. One project deploys into one workspace at a time — the workspace guard refuses a deploy when the state's workspace isn't the selected one — and the same project reaches a dev and a prod workspace through a different deploy state each. Say "project" for the repo, and don't name a project directory 
my-workspace
.
使用此技能在TypeScript中定义Cargo工作区（使用 
@cargo-ai/cdk
的 
define*
构建器），并通过 
cargo-ai project deploy
将其与实时基础设施对齐。它是命令式能力技能的声明式对应物：不是为每个资源运行一条CLI命令，而是编写一次整个资源图并重复部署，并带有一个部署状态——保存在你的工作区中，由一个提交的 
cargo.state.json
指向——将你的代码与Cargo创建的内容关联起来。
“Project”和“workspace”是两回事——请区分它们。 workspace 是你登录的Cargo租户：它包含模型、连接器、Agent、邮箱和积分，是 
login --workspace-name
选择的对象，也是 
whoami
报告的内容。project 是仓库，它声明资源并将它们部署到workspace中：它是 
project init
脚手架生成的对象，是 
cargo.state.json
指向的源，也是 
--dir
定位的对象。一个project一次部署到一个workspace中——当状态的workspace不是当前选中的workspace时，workspace guard会拒绝部署——同一个project通过不同的部署状态分别到达开发和生产workspace。说“project”指仓库，不要将项目目录命名为 
my-workspace
。

Bootstrap

引导（Bootstrap）

Already signed in (
cargo-ai whoami
returns a workspace)? Skip to the next section.
bash
npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # 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
cargo-ai project --help                     # `unknown command` = CLI too old; reinstall @cargo-ai/cli@latest
Two CDK-specific extras: the project needs 
@cargo-ai/cdk
as a dependency for the 
define*
builders you import (
cargo-ai project init
scaffolds a 
package.json
with it — then 
npm install
), and the 
cargo-ai project
domain ships with the CLI itself.
Every command prints JSON to stdout; failures exit non-zero with 
{"errorMessage": "..."}
. Anything that creates a run or a batch is async — pass 
--wait-until-finished
or poll the matching 
get
. When the full skill bundle is installed, 
../cargo/references/prerequisites.md
 adds the CLI version pin, token scopes, and the admin-only surface.
已登录（
cargo-ai whoami
返回一个workspace）？跳到下一节。
bash
npm install -g @cargo-ai/cli            # 没有全局安装？在每个命令前加 `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # 邮件发送验证码，无需浏览器；首次使用创建账户
                                        # 备选：--oauth（浏览器）· --token <api-token>（CI）
cargo-ai whoami                         # 在任何写入前确认活动workspace
cargo-ai project --help                     # `unknown command` = CLI太旧；重新安装 @cargo-ai/cli@latest
两个CDK专属附加项：project需要将 
@cargo-ai/cdk
作为依赖，用于你导入的 
define*
构建器（
cargo-ai project init
会生成包含它的 
package.json
——然后运行 
npm install
），并且 
cargo-ai project
域随CLI本身一起提供。
每个命令向stdout输出JSON；失败以非零退出码和 
{"errorMessage": "..."}
退出。任何创建运行或批处理的操作都是异步的——传递 
--wait-until-finished
或轮询对应的 
get
。当完整技能包安装后，
../cargo/references/prerequisites.md
 会添加CLI版本固定、token作用域和管理员专用表面。

1) What this skill governs

1) 此技能管辖什么

  • Authoring every Cargo resource with a 
    define*
    builder that returns a handle; wiring resources by passing handles to each other (the dependency graph is your variable graph).
  • Deploying the graph: 
    plan
    (offline diff) → 
    deploy
    (create/update, write state) → 
    destroy
    (tear down). Plus drift (
    refresh
    ), adoption (
    import
    ), and recovery (
    rollback
    ).
  • Typing the config against your workspace's real integration schemas (
    cargo-ai project types
    ).
The CDK spans every resource kind — so it overlaps every imperative capability skill (
cargo-connection
, 
cargo-storage
, 
cargo-ai
, 
cargo-orchestration
, 
cargo-content
, 
cargo-hosting
, …). Which to reach for is the first decision:
  • 编写每个Cargo资源，使用返回句柄的 
    define*
    构建器；通过将句柄传递给彼此来连接资源（依赖图就是你的变量图）。
  • 部署资源图：
    plan
    （离线差异）→ 
    deploy
    （创建/更新，写入状态）→ 
    destroy
    （拆除）。还有漂移（
    refresh
    ）、采纳（
    import
    ）和恢复（
    rollback
    ）。
  • 类型化配置，针对你的工作区的真实集成模式（
    cargo-ai project types
    ）。
CDK涵盖每一种资源类型——因此它与每个命令式能力技能（
cargo-connection
、
cargo-storage
、
cargo-ai
、
cargo-orchestration
、
cargo-content
、
cargo-hosting
等）重叠。选哪个是第一个决定：

2) CDK or the CLI? — the routing decision

2) CDK还是CLI？——路由决策

Declarative (this skill) vs imperative (a capability skill).
Use the CDK when the user is managing resources as an artifact:
  • "Set up / stand up / bootstrap a whole workspace (as code / from a template)."
  • "Make this reproducible / version-controlled / in git / repeatable across environments (dev → prod)."
  • "Deploy these connectors + models + agents together" (a multi-resource graph wired by dependency).
  • Anything that should be re-runnable and diffable, where losing the definition would be a problem.
Use the matching capability skill (imperative 
cargo-ai <domain>
) when the user is doing a one-off operation or exploring:
  • "Create one connector", "add a column to this model", "list connectors", "run this workflow", "query storage", "read this agent's memory."
  • Any read, ad-hoc query, or single mutation that doesn't need to live in code.
When unsure, ask whether the result should be committed and re-deployable. If yes → CDK. If it's a quick action or a read → the capability skill (see the 
cargo
router to pick the right domain).
声明式（此技能） vs 命令式（能力技能）。
当用户是将资源作为工件管理时，使用CDK：
  • “设置/搭建/引导整个workspace（作为代码/从模板）。”
  • “使这个可复现/版本控制/在git中/跨环境（dev → prod）可重复。”
  • “一起部署这些连接器+模型+Agent”（一个按依赖连接的多资源图）。
  • 任何应该可重新运行和可差异化的东西，丢失定义将是一个问题。
当用户正在进行一次性操作或探索时，使用匹配的能力技能（命令式 
cargo-ai <domain>
）：
  • “创建一个连接器”、“向此模型添加列”、“列出连接器”、“运行此工作流”、“查询存储”、“读取此Agent的记忆”。
  • 任何读取、临时查询或不需要存在于代码中的单个变更。
不确定时，询问结果是否应该提交并重新部署。如果是→CDK。如果是一次快速操作或读取→能力技能（参见 
cargo
router 以选择正确的域）。

3) The lifecycle

3) 生命周期

cargo-ai project init <dir>     scaffold from getcargohq/cargo-manifest; resources in infra/
        │
cargo-ai project types          generate per-workspace types for typed config (optional)
        │
   (author define* files)   importing a .ts file IS registration — no manifest
        │
cargo-ai project plan           offline: compile the graph, diff against the deploy state
        │
cargo-ai project deploy         create/update resources in dependency order, write state
        │
cargo-ai project destroy        tear down resources recorded in state
project plan
says what resources change; it doesn't show what a play does. For a 
definePlay
/ 
defineTool
graph past three nodes, present a Mermaid flowchart of the node graph alongside the plan — routing, fallbacks, and which nodes bill on every scheduled run are what the reviewer is approving. Generate it from the deployed release after the first deploy, or from the node array while authoring: 
../cargo-orchestration/references/node-diagram.md
.
Side branches: 
cargo-ai project check
(validate the tree, no state, no API calls — the CI/editor subset of 
plan
) · 
cargo-ai project info
(what is here: every declared resource, the file that declared it, whether it is deployed) · 
cargo-ai project refresh
(read-only drift report) · 
deploy --refresh
(re-apply code over out-of-band edits) · 
deploy --prune
(delete resources removed from code) · 
cargo-ai project import <id> <uuid>
(bind an existing live resource into state) · 
cargo-ai project pull
(generate 
define*
source from a live workspace and adopt it) · 
cargo-ai project rollback
(restore the pre-deploy state snapshot) · 
cargo-ai project state
(inspect and repoint the deploy state).
plan
and 
info
answer different questions. 
plan
answers what will deploy do — its unit is the change, and it exits non-zero so CI can gate on it. 
info
answers what is here — its unit is the resource, and it never fails. 
check
is 
plan
minus the diff: it needs no state, so it is what an editor or a pre-commit hook runs. Running 
cargo-ai project
with no arguments does 
info
inside a project and 
init
outside one.
cargo-ai project init <dir>     从 getcargohq/cargo-manifest 脚手架；资源在 infra/ 中
        │
cargo-ai project types           为类型化配置生成按workspace的类型（可选）
        │
   (编写 define* 文件)        导入 .ts 文件即注册——无需manifest
        │
cargo-ai project plan            离线：编译资源图，与部署状态差异对比
        │
cargo-ai project deploy          按依赖顺序创建/更新资源，写入状态
        │
cargo-ai project destroy         拆除状态中记录的资源
project plan
说明哪些资源会变化；它不显示剧本做什么。 对于超过三个节点的 
definePlay
/ 
defineTool
图，在计划旁边呈现节点图的 Mermaid 流程图——路由、回退以及哪些节点在每次计划运行中计费，是审查者要批准的。在首次部署后从已部署的发布生成，或在编写时从节点数组生成： 
../cargo-orchestration/references/node-diagram.md
。
侧分支：
cargo-ai project check
（验证树，无状态，无API调用——CI/编辑器子集的 
plan
）· 
cargo-ai project info
（这里有什么：每个声明的资源、声明它的文件、是否已部署）· 
cargo-ai project refresh
（只读漂移报告）· 
deploy --refresh
（将代码重新应用到带外编辑上）· 
deploy --prune
（删除从代码中移除的资源）· 
cargo-ai project import <id> <uuid>
（将现有实时资源绑定到状态中）· 
cargo-ai project pull
（从实时workspace生成 
define*
源码并采纳它）· 
cargo-ai project rollback
（恢复部署前状态快照）· 
cargo-ai project state
（检查和重新指向部署状态）。
plan
和 
info
回答不同的问题。 
plan
回答deploy将会做什么——其单位是变更，它非零退出，因此CI可以据此门禁。
info
回答这里有什么——其单位是资源，它从不失败。
check
是去掉差异的 
plan
：它不需要状态，因此编辑器或pre-commit钩子运行它。无参数运行 
cargo-ai project
在project内执行 
info
，在project外执行 
init
。

4) Documentation hierarchy

4) 文档层次结构

  • Level 1 — 
    SKILL.md
    (this file): the decision model, lifecycle, critical rules, and routing.
  • Level 2 — Guides: 
    guides/authoring-resources.md
    , 
    guides/deploy-and-state.md
    , 
    guides/typed-config.md
    .
  • Level 2.5 — Recipes: 
    recipes/*.md
     — step-by-step playbooks to follow as your execution plan.
  • References — 
    references/resources.md
     (the full builder catalog), 
    references/commands.md
     (every 
    cargo-ai project
    subcommand + flags), 
    references/troubleshooting.md
    , and 
    references/examples/full-workspace.md
    .
  • 第1级 — 
    SKILL.md
    （本文件）：决策模型、生命周期、关键规则和路由。
  • 第2级 — 指南： 
    guides/authoring-resources.md
    、 
    guides/deploy-and-state.md
    、 
    guides/typed-config.md
    。
  • 第2.5级 — 食谱： 
    recipes/*.md
     — 作为你的执行计划遵循的分步手册。
  • 参考资料 — 
    references/resources.md
    （完整构建器目录）、
    references/commands.md
    （每个 
    cargo-ai project
    子命令+标志）、 
    references/troubleshooting.md
     和 
    references/examples/full-workspace.md
    。

5) Read behavior — match the task to a doc and READ IT

5) 读取行为——将任务匹配到文档并阅读它

When the task involves…Read this firstWhat it gives you
Writing 
define*
files, wiring resources, 
secret()
/
env()
, 
defineWorkflow
bodies (tool/play logic)
guides/authoring-resources.md
The builder catalog, the handle/ref model, secrets, and how workflow bodies compile.
plan
/ 
deploy
/ 
destroy
, the state file, drift, adopting existing resources, CI
guides/deploy-and-state.md
The deploy lifecycle, 
cargo.state.json
semantics, drift/import/rollback, async builds.
Typed config, 
cargo-ai project types
, tsconfig wiring, 
integrations.*
in workflow bodies
guides/typed-config.md
What 
project types
generates and how to wire it into your project.
A field/spec/output for a specific builder
references/resources.md
Every builder → spec fields → which ref each takes → outputs.
Exact command flags
references/commands.md
Every 
cargo-ai project
subcommand and its flags.
A deploy error / footgun
references/troubleshooting.md
The known failure modes and fixes.
A known GTM outcome, before authoring one
references/cookbooks.md
The cookbook menu: gtm-skills that carry a worked CDK example, and the adaptations each supports.
当任务涉及…首先阅读这个它给你什么
编写 
define*
文件、连接资源、
secret()
/
env()
、
defineWorkflow
主体（tool/play逻辑）
guides/authoring-resources.md
构建器目录、句柄/引用模型、机密，以及工作流主体如何编译。
plan
/ 
deploy
/ 
destroy
、状态文件、漂移、采纳现有资源、CI
guides/deploy-and-state.md
部署生命周期、
cargo.state.json
语义、漂移/导入/回滚、异步构建。
类型化配置、
cargo-ai project types
、tsconfig接线、工作流主体中的 
integrations.*
guides/typed-config.md
project types
生成什么，以及如何将其接入你的项目。
特定构建器的字段/规范/输出
references/resources.md
每个构建器 → 规范字段 → 接受哪个引用 → 输出。
确切的命令标志
references/commands.md
每个 
cargo-ai project
子命令及其标志。
部署错误/陷阱
references/troubleshooting.md
已知失败模式和修复。
已知GTM结果，在编写一个之前
references/cookbooks.md
食谱菜单：带有可用CDK示例的gtm-skills，以及每个支持的适配。

Cookbooks — check the menu before authoring a known outcome from scratch

Cookbooks——在从头编写已知结果前检查菜单

getcargohq/gtm-skills
 holds, beside its one-off skills, cookbooks: skills that carry worked CDK resources, the same job as a deployed pipeline that keeps producing the result (TAM building, account scoring, contact sourcing, routing engine, AI SDR, rep cockpit, …). Every folder is self-contained: its own models, connectors and folders, no shared foundation, no requires graph.
The menu is local: 
references/cookbooks.md
. Read it before authoring a common GTM outcome from scratch. It is generated from gtm-skills' 
catalog.json
, so it cannot drift.
A cookbook is a worked example, not a template to fill in. Each one declares in its 
SKILL.md
what may be reshaped, what must hold or it stops working, and what has to be answered either way, and it carries its own procedure. 
project add
is the copy step in that procedure:
sh
cargo-ai project add cookbook/tam-building               # inside a CDK project
cargo-ai project init my-project --cookbook tam-building # no project yet: both at once
That writes the resources to 
infra/tam-building/
and the procedure to 
.claude/skills/tam-building/
, skipping any file it would overwrite. Then start the skill at its Adapt section — its opening steps are written for someone who found the folder on GitHub and still has to place it, so following them from the top scaffolds a second project and copies the folder in again.
What is left after the copy is the part only you can do: reconcile it with what is already declared, adapt the copied files in place to the project's real shape (do not regenerate them from the skill's prose — the safety lives in the TypeScript), plan and stop, deploy on a yes, walk its 
Done when
.
If you are mid-task and the skill is not in this session, 
npx skills add getcargohq/gtm-skills/<slug>
fetches the procedure alone and you can read 
.agents/skills/<slug>/SKILL.md
directly; no reload needed. To read one without installing, 
npx skills use getcargohq/gtm-skills@<slug>
prints it. Neither brings the CDK resources — for those you still want 
project add
.
Routing rule: one-off versus standing. A user who wants the list today wants 
cargo-gtm
(or gtm-skills' one-off 
build-tam-list
); a user who wants a pipeline that keeps producing it wants 
tam-building
. The same words describe both ("build our TAM"), so listen for whether the result is meant to keep arriving. A cookbook matches → install it and follow it. No match → author from the recipes below.
Never 
cargo-ai project init --force
into a directory that is not empty. It replaces the project's 
package.json
and reverts adapted code, while 
cargo.state.json
survives, so the next 
plan
diffs a live workspace against code nobody wrote. Copy the skill folder in as a sibling instead.
Caveat: the examples typecheck, but they are not yet deploy-verified against a live workspace, and every one is 
to-be-approved
. Treat each skill's 
Done when
as the acceptance test, and always review 
cargo-ai project plan
before deploying.
getcargohq/gtm-skills
 除了其一次性技能外，还持有 cookbooks：带有可用CDK资源的技能，与保持产生结果的已部署流水线相同的工作（TAM构建、账户评分、联系人寻找、路由引擎、AI SDR、销售代表驾驶舱等）。每个文件夹是自包含的：它自己的模型、连接器和文件夹，没有共享基础，没有requires图。
菜单是本地的：
references/cookbooks.md
。 在从头编写常见GTM结果之前阅读它。它从gtm-skills的 
catalog.json
生成，因此不会漂移。
Cookbook是一个可用示例，而不是要填写的模板。 每个cookbook在其 
SKILL.md
中声明哪些可以重塑，哪些必须保持不变否则停止工作，以及哪些无论如何都要回答，并且它带有自己的程序。
project add
是该程序中的复制步骤：
sh
cargo-ai project add cookbook/tam-building               # 在CDK project内
cargo-ai project init my-project --cookbook tam-building # 还没有project：两者同时
这将资源写入 
infra/tam-building/
，将程序写入 
.claude/skills/tam-building/
，跳过任何它会覆盖的文件。然后从其Adapt部分开始技能——其开头步骤是为在GitHub上找到文件夹并且仍需放置它的人编写的，因此从头遵循它们会脚手架第二个项目并再次复制文件夹。
复制后剩下的部分只有你能做：与已经声明的内容协调，就地将复制的文件适配到项目的真实形状（不要从技能的文字重新生成它们——安全存在于TypeScript中），计划并停止，在yes时部署，走过它的 
Done when
。
如果你正在任务中途而该技能不在本次会话中，
npx skills add getcargohq/gtm-skills/<slug>
仅获取程序，你可以直接阅读 
.agents/skills/<slug>/SKILL.md
；无需重新加载。要阅读而不安装，
npx skills use getcargohq/gtm-skills@<slug>
会打印它。两者都不带来CDK资源——对于这些你仍然需要 
project add
。
路由规则：一次性与持续。 今天想要列表的用户想要 
cargo-gtm
（或gtm-skills的一次性 
build-tam-list
）；想要持续产生列表的流水线的用户想要 
tam-building
。相同的词语描述两者（“构建我们的TAM”），因此要听结果是否旨在持续到达。 cookbook匹配→安装并遵循它。不匹配→从下面的食谱编写。
永远不要 
cargo-ai project init --force
进入非空目录。 它替换项目的 
package.json
并恢复适配后的代码，而 
cargo.state.json
幸存，因此下一个 
plan
会将实时workspace与无人编写的代码进行差异对比。而是将技能文件夹作为兄弟文件夹复制进来。
警告：示例通过类型检查，但尚未针对实时workspace进行部署验证，并且每个都是 
to-be-approved
。将每个技能的 
Done when
作为验收测试，并且始终在部署前审查 
cargo-ai project plan
。

Recipes — follow step-by-step when one matches

Recipes——当匹配时逐步遵循

RecipeUse when…
recipes/scaffold-a-project.md
Standing up a new project from scratch (
init
→ types → plan → deploy).
recipes/add-connector-and-model.md
Adding a data source + a model sourced from it, wired by handle.
recipes/build-an-agent.md
Composing a model + tool + agent (with 
uses
/ 
models
/ 
tools
) and deploying.
recipes/migrate-existing-workspace.md
Bringing an already-live workspace under a project via 
project import
.
recipes/deploy-from-ci.md
Deploying non-interactively from CI (token auth + committed state).
Recipe在以下情况下使用…
recipes/scaffold-a-project.md
从零搭建新project（
init
→ types → plan → deploy）。
recipes/add-connector-and-model.md
添加数据源+从它获取的模型，通过句柄连接。
recipes/build-an-agent.md
组合模型+工具+Agent（使用 
uses
/ 
models
/ 
tools
）并部署。
recipes/migrate-existing-workspace.md
通过 
project import
将已实时workspace纳入project下。
recipes/deploy-from-ci.md
从CI非交互式部署（token认证+提交状态）。

6) Critical rules

6) 关键规则

  • Commit 
    cargo.state.json
    — it is a pointer now, not the state.     The deploy state lives in your workspace; the repo commits only 
    {"stateUuid": "8f2c…"}
    . 
    project init
    creates the state and writes that pointer, so it lands in the scaffold commit. Commit it: without the uuid a fresh checkout can't find its state, and a deploy will not quietly create a replacement (that would orphan everything the old one tracks). The state records only uuids, hashes and outputs — never secret values. It is still the only handle on a deployed play, agent, or alert (they have no slug); recover a lost link with 
    project state bind <uuid>
    , or per-resource with 
    cargo-ai project import
    . Git-ignore the working files (
    project init
    scaffolds this):
    gitignore
    .cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.cache.json
cargo.state.audit.jsonl
    One state per repo, and at most 10 live states per workspace:
    bash
    cargo-ai project state list            # every state here, and which one this project is on
cargo-ai project state create          # create one for this project, write the pointer
cargo-ai project state bind <uuid>     # repoint at an existing one
    A project scaffolded before states moved to the workspace has the resource map inline in 
    cargo.state.json
    , and keeps deploying against that file for as long as you leave it there — nothing migrates behind your back. 
    state create
    is what moves it: the map goes onto a new state, the file becomes a pointer, and you commit it. Don't migrate without telling the team, since a teammate who deploys before pulling the new pointer is deploying from a state that no longer exists. (Deleting a state — 
    state remove
    — is in the CDK README but is not in CLI 1.0.96; it lands in the next release.)
  • Three ways to get a value in, and they are not interchangeable.
    • secret("ENV_VAR")
      — read from your environment at deploy time, excluded from the content hash and from state. Export the env var before deploying; a missing one fails the deploy with an unresolved 
      ${ENV_VAR}
      placeholder.
    • env("ENV_VAR")
      — read from your environment at load time, and its value enters the spec and therefore the content hash, so changing it shows as drift. Use it for non-secret config you want tracked.
    • workspaceEnv("NAME")
      — a pointer at a workspace env-var catalog entry. Nothing is read locally and nothing can fail; the value stays server-side and is re-read on every use, so rotating it in the workspace reaches the resource with no redeploy. Manage the catalog with 
      cargo-ai workspaceManagement envVar
      (see 
      ../cargo-workspace-management/SKILL.md
      ).
    secret()
    and 
    workspaceEnv()
    are accepted at secret-typed schema positions only — 
    cargo-ai project types
    prints the union at exactly those positions. A resource's own 
    env
    block takes 
    env()
    or 
    secret()
    and rejects a pointer, because a worker, app, agent or script already inherits the whole workspace catalog; a pointer there could only restate a variable it can read anyway.
  • A rotated 
    secret()
    needs more than a plain deploy to land.     Keeping the value out of the content hash is what stops rotation reading as drift — and it is also why 
    deploy
    won't push the new value: nothing in the hash changed, so the resource isn't re-applied. Roll it with 
    deploy --refresh
    , or any other edit to that resource. 
    workspaceEnv()
    has no such step; that is most of its appeal.
  • Wire by handle, never by 
    .uuid
    .     Pass a 
    define*
    handle directly (
    dataset: hubspot
    , 
    tools: [enrich]
    ), or 
    xxRef("uuid")
    for a resource you didn't define in code (
    connectorRef
    , 
    modelRef
    , 
    folderRef
    , 
    toolRef
    , 
    agentRef
    , …). Where a reference needs per-call options, wrap it as 
    { ref, …options }
    (e.g. 
    models: [{ ref: contacts, readOnly: true }]
    ).
  • Run 
    cargo-ai project types
    after workspace integrations change     — it regenerates 
    .cargo-ai/
    so 
    defineConnector
    /
    defineModel
    config (and 
    integrations.*
    in workflow bodies) type-check against the real schemas. Typing is a bonus, never a gate: deploy works without it.
  • Any subdirectory of the repo is fine (CLI ≥ 1.0.83). Commands walk up to the package root where 
    @cargo-ai/cdk
    is declared, then back down to the resource directory (
    infra/
    in a scaffolded repo), so 
    .cargo-ai/
    and 
    cargo.state.json
    land in the right place from anywhere inside the project. 
    --dir <path>
    still overrides it. This is why resources live in 
    infra/
    and not at the root: the loader imports every 
    .ts
    under the directory it is given, and a repo root also holds 
    scripts/
    — whose files run on import. Pointing a command at the root would execute them.
  • --yes
    in CI.     
    deploy
    and 
    destroy
    prompt for confirmation; non-interactive runs must pass 
    --yes
    .
  • A 
    definePlay
    /
    defineTool
    graph with paid nodes gets a sample run before it goes wide.     Deploying is not running, but the first thing that runs a deployed play is usually a batch over the whole segment — and a scheduled play re-bills every node on every run. Before enrolling everything (or enabling a schedule), run the deployed workflow on 10–20 records — 
    cargo-ai orchestration batch create --data '{"kind":"filter","modelUuid":"…","filter":…,"limit":15}'
    , or 
    batch create --file ./plays/x.ts
    to test-run the module without deploying — then ask the user to approve the full enrollment with the record count and credit estimate. Read the provider's playbook (
    ../cargo-gtm/provider-playbooks/<slug>.md
    , esp. its Recurring use section) and the gate in 
    ../cargo-gtm/references/cost-discipline.md
    .
  • A 
    defineAlert
    whose actions call paid nodes re-bills on every breach.     An alert's 
    actions
    fire as real runs, so a badly-sized 
    threshold
    on a tight 
    schedule
    can breach — and bill — every tick. Size the threshold with 
    cargo-ai observability alert preview
    before deploying, prefer cheap notification actions (an agent that posts, a connector notification) over anything that fans out, and apply the same cost gate above when an action calls a credits-based provider. Scope/threshold and firing semantics: 
    ../cargo-observability/SKILL.md
    .
  • defineMailbox
    bills monthly, and 
    defineDomain
    rewrites a DNS zone.     A mailbox is 100–160 credits per month for as long as it exists (
    cargo-ai mailboxManagement pricing get
    for live figures), so a 
    + create mailbox:…
    line in the plan is a recurring charge the user approves, not a one-off. Its 
    domain
    , 
    username
    and 
    type
    are create-only — changing any of them is destroy + recreate, i.e. a brand-new inbox back at the bottom of a 45-day warm-up ramp. The deploy polls 
    refreshStatus
    for up to 5 minutes waiting for 
    active
    . On 
    defineDomain
    , 
    dnsRecords
    is the whole zone, not a patch: declaring it replaces every live record (including the ones the registrar wrote at purchase), and omitting it leaves the zone untouched. 
    redirectUrl
    , 
    dmarcEmail
    and 
    dmarcPolicy
    are additive and are the supported way to configure a zone without replacing it, so reach for 
    dnsRecords
    only when you mean to own every record. Use 
    adopt: true
    for a domain or mailbox bought in the UI. Ramp, suppression and sending: 
    ../cargo-mailbox-management/SKILL.md
    .
  • Route CDK-managed resources into a clearly-labelled folder. Set 
    folder:
    on each builder so everything CDK owns lands in a dedicated folder whose name signals "owned by code — don't hand-edit" to anyone in the UI (manual UI edits read back as drift on the next 
    plan
    ). Folders are per-kind, so give each kind its own but share one short, recognizable prefix — recommended: 
    🔒 CDK
     (e.g. 
    🔒 CDK Models
    , 
    🔒 CDK Agents
    ). Keep names short (long labels truncate in the folder tree); the lock emoji is the "don't touch" cue. See 
    guides/authoring-resources.md
    .
  • 提交 
    cargo.state.json
    —— 它现在是一个指针，不是状态。     部署状态存在于你的workspace中；仓库只提交 
    {"stateUuid": "8f2c…"}
    。
    project init
    创建状态并写入该指针，因此它落在脚手架提交中。提交它：没有uuid，新的检出找不到其状态，并且部署将不会静默创建替代品（那将孤立旧状态跟踪的所有内容）。状态只记录uuid、哈希和输出——绝不记录机密值。它仍然是已部署的 play、agent 或 alert 的唯一句柄（它们没有slug）；使用 
    project state bind <uuid>
    或按资源使用 
    cargo-ai project import
    恢复丢失的链接。Git忽略工作文件（
    project init
    脚手架会生成）：
    gitignore
    .cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.cache.json
cargo.state.audit.jsonl
    每个仓库一个状态，并且每个workspace最多10个实时状态：
    bash
    cargo-ai project state list            # 这里每个状态，以及此project处于哪个
cargo-ai project state create          # 为此project创建一个，写入指针
cargo-ai project state bind <uuid>     # 重新指向现有状态
    在状态移到workspace之前脚手架生成的project在 
    cargo.state.json
    中内联资源映射，并且只要你把它留在那里就会继续针对该文件部署——没有东西会在你背后迁移。
    state create
    是移动它的操作：映射转到新状态，文件成为指针，然后你提交它。不要在没有告知团队的情况下迁移，因为先部署的队友在拉取新指针之前是从一个不再存在的状态部署的。（删除状态——
    state remove
    ——在CDK README中但在CLI 1.0.96中不可用；它将在下个版本中发布。）
  • 获取值的三种方式，它们不可互换。
    • secret("ENV_VAR")
      — 在部署时从你的环境读取，排除在内容哈希和状态之外。在部署前导出环境变量；缺少会导致部署失败，并带有未解析的 
      ${ENV_VAR}
      占位符。
    • env("ENV_VAR")
      — 在加载时从你的环境读取，其值进入规范并因此进入内容哈希，因此更改它会显示为漂移。对你想跟踪的非机密配置使用它。
    • workspaceEnv("NAME")
      — 一个指向workspace环境变量目录条目的指针。本地不读取任何内容，也不会失败；该值保留在服务端，并在每次使用时重新读取，因此在workspace中轮换它可以无需重新部署就到达资源。使用 
      cargo-ai workspaceManagement envVar
      管理目录（参见 
      ../cargo-workspace-management/SKILL.md
      ）。
    secret()
    和 
    workspaceEnv()
    仅在secret类型的模式位置被接受——
    cargo-ai project types
    在这些位置打印联合类型。资源自身的 
    env
    块接受 
    env()
    或 
    secret()
    并拒绝指针，因为worker、app、agent或script已经继承整个workspace目录；那里的指针只能重述一个它本就可以读取的变量。
  • 轮换的 
    secret()
    需要的不止一次普通部署。     将该值排除在内容哈希之外是阻止轮换读取为漂移的原因——也是 
    deploy
    不会推送新值的原因：哈希中没有变化，因此资源不会重新应用。使用 
    deploy --refresh
    或对该资源的任何其他编辑来轮换它。
    workspaceEnv()
    没有这样的步骤；这是它的大部分吸引力。
  • 通过句柄连接，绝不通过 
    .uuid
    。     直接传递一个 
    define*
    句柄（
    dataset: hubspot
    、
    tools: [enrich]
    ），或者为你在代码中未定义的资源使用 
    xxRef("uuid")
    （
    connectorRef
    、
    modelRef
    、
    folderRef
    、
    toolRef
    、
    agentRef
    等）。当引用需要每次调用的选项时，将其包装为 
    { ref, …options }
    （例如 
    models: [{ ref: contacts, readOnly: true }]
    ）。
  • 在workspace集成更改后运行 
    cargo-ai project types
     —— 它重新生成 
    .cargo-ai/
    ，使 
    defineConnector
    /
    defineModel
    配置（以及工作流主体中的 
    integrations.*
    ）针对真实模式进行类型检查。类型化是奖励，绝不是门禁：没有它部署也能工作。
  • 仓库的任何子目录都可以（CLI ≥ 1.0.83）。 命令向上走到声明了 
    @cargo-ai/cdk
    的包根目录，然后向下回到资源目录（脚手架仓库中的 
    infra/
    ），因此 
    .cargo-ai/
    和 
    cargo.state.json
    从项目内部任何位置落在正确位置。
    --dir <path>
    仍然覆盖它。这就是资源位于 
    infra/
    而不是根目录的原因：加载器导入给定目录下的每个 
    .ts
    文件，而仓库根目录还包含 
    scripts/
    ——其文件在导入时运行。将命令指向根目录会执行它们。
  • CI中的 
    --yes
    。     
    deploy
    和 
    destroy
    提示确认；非交互式运行必须传递 
    --yes
    。
  • 带有付费节点的 
    definePlay
    /
    defineTool
    图在广泛运行前要进行样本运行。     部署不是运行，但运行已部署play的第一件事通常是对整个分段的批处理——而计划内的play会在每次运行中重新计费每个节点。在注册所有内容（或启用计划）之前，在 10–20条记录 上运行已部署的工作流——
    cargo-ai orchestration batch create --data '{"kind":"filter","modelUuid":"…","filter":…,"limit":15}'
    ，或 
    batch create --file ./plays/x.ts
    来测试运行模块而不部署——然后要求用户批准完整注册，并附上记录数量和积分估算。阅读提供者的playbook（
    ../cargo-gtm/provider-playbooks/<slug>.md
    ，尤其是其 Recurring use 部分）以及 
    ../cargo-gtm/references/cost-discipline.md
     中的门禁。
  • 调用付费节点的 
    defineAlert
    的action会在每次违反时重新计费。     Alert的 
    actions
    作为真实运行触发，因此在紧张的 
    schedule
    上大小不当的 
    threshold
    可能会每个tick违反——并计费。在部署前使用 
    cargo-ai observability alert preview
    调整阈值大小，优先选择廉价的通知action（一个发布的agent、一个连接器通知）而不是任何扇出的东西，并且当action调用基于积分的提供者时应用相同的成本门禁。作用域/阈值和触发语义：
    ../cargo-observability/SKILL.md
    。
  • defineMailbox
    每月计费，
    defineDomain
    重写DNS区域。     邮箱只要存在就每月消耗100–160积分（实时数字见 
    cargo-ai mailboxManagement pricing get
    ），因此计划中的 
    + create mailbox:…
    行是用户批准的经常性费用，而不是一次性费用。其 
    domain
    、
    username
    和 
    type
    是仅创建——更改其中任何一个都是销毁+重建，即一个全新收件箱回到45天预热坡道的底部。部署会轮询 
    refreshStatus
    最多5分钟等待 
    active
    。在 
    defineDomain
    上，
    dnsRecords
    是整个区域，不是补丁：声明它会替换每条实时记录（包括注册商在购买时写入的），而省略它会使区域保持不变。
    redirectUrl
    、
    dmarcEmail
    和 
    dmarcPolicy
    是附加的，是配置区域而不替换它的受支持方式，因此只有当你打算拥有每条记录时才使用 
    dnsRecords
    。对于在UI中购买的域或邮箱使用 
    adopt: true
    。预热、抑制和发送：
    ../cargo-mailbox-management/SKILL.md
    。
  • 将CDK管理的资源路由到清晰标记的文件夹。 在每个构建器上设置 
    folder:
    ，使CDK拥有的所有内容落在一个专用文件夹中，其名称向UI中的任何人发出信号“由代码拥有——不要手动编辑”（手动UI编辑会在下一个 
    plan
    上读回为漂移）。文件夹是按类型的，因此给每个类型自己的文件夹，但共享一个简短、可识别的前缀——推荐：
    🔒 CDK
    （例如 
    🔒 CDK Models
    、
    🔒 CDK Agents
    ）。保持名称简短（长标签在文件夹树中截断）；锁表情是“不要碰”的提示。参见 
    guides/authoring-resources.md
    。

Help

帮助

  • cargo-ai project --help
    and 
    cargo-ai project <subcommand> --help
    for the live flag surface.
  • When a documented command/flag/response doesn't match what you observe, file a report: 
    cargo-ai workspaceManagement report create
    (see 
    ../cargo-workspace-management/SKILL.md
    ).
  • cargo-ai project --help
    和 
    cargo-ai project <subcommand> --help
    查看实时标志表面。
  • 当文档化的命令/标志/响应与你观察到的不匹配时，提交报告：
    cargo-ai workspaceManagement report create
    （参见 
    ../cargo-workspace-management/SKILL.md
    ）。