用 TypeScript CDK 和 cargo-ai…

当你要把整个 Cargo workspace 的连接器、模型、agents、tools、MCP servers、workers、apps 等作为可提交、可 diff、可重复部署的代码来管理时使用。

适用场景

解决思路

1. 先区分 workspace 与 project：workspace 是你登录的 Cargo tenant，持有 models、connectors、agents、mailboxes、credits，由 `login --workspace-name` 选择、由 `whoami` 报告；project 是声明资源并部署到 workspace 的 repo，由 `project init` 脚手架生成、由 `cargo.state.json` 指向、由 `--dir` 定位。一个 project 同时只部署到一个 workspace；workspace guard 会在 state 的 workspace 不是当前选中时拒绝 deploy。同一 project 通过不同 deploy state 进入 dev 和 prod。repo 叫 project，不要把项目目录命名为 `my-workspace`。
2. 尚未登录时安装并登录：`npm install -g @cargo-ai/cli`，没有全局安装则每个命令前加 `npx @cargo-ai/cli`；`cargo-ai login --email you@company.com` 使用邮件验证码、无浏览器，也可用 `--oauth` 或 `--token <api-token>`；首次使用会创建账号；用 `cargo-ai whoami` 在任何写入前确认 active workspace；运行 `cargo-ai project --help`，若出现 `unknown command` 说明 CLI 太旧，重装 `@cargo-ai/cli@latest`。
3. project 需要把 `@cargo-ai/cdk` 作为依赖，以便导入 `define*` builder；`cargo-ai project init` 会脚手架生成带该依赖的 `package.json`，然后运行 `npm install`；`cargo-ai project` 域随 CLI 本身提供。
4. 所有命令向 stdout 打印 JSON；失败时非零退出并输出 `{"errorMessage": "..."}`。任何创建 run 或 batch 的操作都是异步的，传 `--wait-until-finished` 或轮询对应的 `get`。当完整 skill bundle 安装时，`../cargo/references/prerequisites.md` 提供 CLI 版本 pin、token scopes 和 admin-only surface。
5. 当用户把资源作为 artifact 管理时使用声明式 CDK：搭建/启动/bootstrap 整个 workspace（as code / from template）、要求可复现/版本控制/进 git/跨环境重复、把 connectors + models + agents 等多资源依赖图一起部署、任何应可重复运行和 diff、丢失定义会成为问题的事情。
6. 当用户做一次性操作或探索时使用匹配的 capability skill（命令式 `cargo-ai <domain>`）：创建一个 connector、给 model 加一列、列出 connectors、运行 workflow、查询 storage、读取 agent memory、任何 read、ad-hoc query 或不需要留在代码中的单个 mutation。
7. 不确定时问结果是否应该被提交并可重新部署：是则用 CDK；快速操作或读取则用 capability skill，并用 `cargo` router 选择正确域。
8. 生命周期：`cargo-ai project init <dir>` 从 `getcargohq/cargo-manifest` 脚手架，资源放在 `infra/`；`cargo-ai project types` 为 typed config 生成 per-workspace 类型（可选）；编写 `define*` 文件，导入一个 `.ts` 文件就是注册，不需要 manifest；`cargo-ai project plan` 离线编译图并与 deploy state diff；`cargo-ai project deploy` 按依赖顺序创建/更新资源并写 state；`cargo-ai project destroy` 拆除 state 中记录的资源。
9. 用 `define*` builder 声明每个 Cargo 资源，builder 返回 handle；通过把 handle 传给彼此来连接资源；依赖图就是你的变量图。
10. 对超过 3 个节点的 `definePlay`/`defineTool` 图，在 `plan` 旁边展示 Mermaid flowchart；routing、fallbacks、哪些节点在每次 scheduled run 计费，是 reviewer 审批重点。首次部署后从 deployed release 生成，或编写时从 node array 生成，参考 `../cargo-orchestration/references/node-diagram.md`。
11. 使用侧分支命令：`cargo-ai project check` 校验树，无 state、无 API 调用，是 CI/editor 用的 `plan` 子集；`cargo-ai project info` 查看这里有什么：每个声明资源、声明文件、是否已部署；`cargo-ai project refresh` 只读 drift 报告；`deploy --refresh` 用代码重新应用覆盖 out-of-band 编辑；`deploy --prune` 删除从代码移除的资源；`cargo-ai project import <id> <uuid>` 把现有 live 资源绑定进 state；`cargo-ai project pull` 从 live workspace 生成 `define*` 源码并 adopt；`cargo-ai project rollback` 恢复 pre-deploy state snapshot；`cargo-ai project state` 检查并重指向 deploy state。
12. 区分 `plan` 和 `info`：`plan` 回答 deploy 会做什么，单位是 change，并会非零退出以便 CI gate；`info` 回答这里有什么，单位是 resource，永不失败；`check` 是 `plan` 减去 diff，不需要 state，适合 editor 或 pre-commit hook。运行 `cargo-ai project` 无参数时，在 project 内执行 `info`，在 project 外执行 `init`。
13. 按文档层级使用资料：Level 1 是 `SKILL.md`（决策模型、生命周期、关键规则、路由）；Level 2 是 `guides/authoring-resources.md`、`guides/deploy-and-state.md`、`guides/typed-config.md`；Level 2.5 是 `recipes/*.md`，作为执行计划逐步遵循；References 是 `references/resources.md`、`references/commands.md`、`references/troubleshooting.md`、`references/examples/full-workspace.md`。
14. 按任务匹配并先读文档：写 `define*` 文件、连接资源、`secret()`/`env()`、`defineWorkflow` bodies（tool/play logic）读 `guides/authoring-resources.md`；`plan`/`deploy`/`destroy`、state file、drift、adopting existing resources、CI 读 `guides/deploy-and-state.md`；typed config、`cargo-ai project types`、tsconfig wiring、workflow bodies 中的 `integrations.*` 读 `guides/typed-config.md`；具体 builder 的 field/spec/output 读 `references/resources.md`；确切命令 flags 读 `references/commands.md`；deploy 错误或 footgun 读 `references/troubleshooting.md`；已知 GTM outcome、在编写前读 `references/cookbooks.md`。
15. 编写常见 GTM outcome 前先看 cookbook 菜单 `references/cookbooks.md`；`getcargohq/gtm-skills` 中有 cookbooks，带 worked CDK resources，把同一 job 作为会持续产生结果的 deployed pipeline，每个文件夹自包含：自己的 models、connectors 和 folders，无共享 foundation，无 requires graph；菜单由 gtm-skills 的 `catalog.json` 生成，不会漂移。
16. 把 cookbook 当作 worked example，不是填空模板；每个 cookbook 在其 `SKILL.md` 中声明哪些可以重塑、哪些必须保持否则失效、哪些无论如何都要回答，并携带自己的 procedure。
17. 在 CDK project 内用 `cargo-ai project add cookbook/tam-building` 复制 cookbook；还没有 project 时用 `cargo-ai project init my-project --cookbook tam-building` 同时完成两者。该操作把资源写到 `infra/tam-building/`，把 procedure 写到 `.claude/skills/tam-building/`，跳过任何会覆盖的文件。
18. 复制 cookbook 后从 skill 的 Adapt 章节开始，不要从顶部按步骤执行；顶部步骤是给从 GitHub 发现文件夹、仍需放置它的人写的，照做会再脚手架一个 project 并再次复制文件夹。
19. 复制后剩下只有你能做的部分：与已有声明 reconcile，原地适配复制文件到 project 的真实形状（不要从 skill 的文字重新生成，安全性在 TypeScript 中），`plan` 后停下，得到 yes 再 deploy，走其 `Done when`。
20. 如果 mid-task 且 skill 不在本 session，`npx skills add getcargohq/gtm-skills/<slug>` 只获取 procedure，随后读 `.agents/skills/<slug>/SKILL.md`；不安装只读则用 `npx skills use getcargohq/gtm-skills@<slug>` 打印它。两者都不带 CDK 资源，需要资源仍要用 `project add`。
21. 路由规则 one-off 还是 standing：今天要列表的用户想要 `cargo-gtm` 或 gtm-skills 的一次性 `build-tam-list`；要持续产生该结果的 pipeline 的用户想要 `tam-building`。同样的话可能描述两者（如 build our TAM），要听结果是否要持续到达。cookbook 匹配则安装并遵循；不匹配则从 recipes 编写。
22. 绝不对非空目录运行 `cargo-ai project init --force`。它会替换项目 `package.json` 并回退已适配代码，而 `cargo.state.json` 仍存在，所以下一次 `plan` 会把 live workspace 与没人写的代码 diff。应把 skill 文件夹作为 sibling 复制进去。
23. Cookbook caveat：示例能 typecheck，但尚未针对 live workspace deploy-verified，且每个都是 `to-be-approved`。把每个 skill 的 `Done when` 当作 acceptance test，并始终在 deploy 前 review `cargo-ai project plan`。
24. 当 recipe 匹配时逐步执行：`recipes/scaffold-a-project.md` 用于从零搭新 project（`init` → types → plan → deploy）；`recipes/add-connector-and-model.md` 用于添加数据源和来源于它的 model，并按 handle 连接；`recipes/build-an-agent.md` 用于组合 model + tool + agent（带 `uses` / `models` / `tools`）并 deploy；`recipes/migrate-existing-workspace.md` 用于通过 `project import` 把已 live workspace 纳入 project；`recipes/deploy-from-ci.md` 用于从 CI 非交互 deploy（token auth + committed state）。
25. 提交 `cargo.state.json`；它现在是指针，不是 state。deploy state 在 workspace 中；repo 只提交 `{"stateUuid": "8f2c…"}`。`project init` 创建 state 并写该指针，所以它落在 scaffold commit 中。必须提交：没有 uuid，fresh checkout 找不到 state，deploy 不会悄悄创建替代品，因为那会 orphan 旧 state 跟踪的一切。state 只记录 uuids、hashes 和 outputs，绝不记录 secret values。它仍是已部署 play、agent、alert 的唯一 handle（它们没有 slug）；丢失链接用 `project state bind <uuid>` 恢复，或按资源用 `cargo-ai project import` 恢复。
26. Git-ignore 工作文件：`.cargo-ai/`、`cargo.state.lock`、`cargo.state.bak.json`、`cargo.state.cache.json`、`cargo.state.audit.jsonl`。一个 repo 一个 state，一个 workspace 最多 10 个 live states。用 `cargo-ai project state list` 查看这里每个 state 及当前 project 用哪个；`cargo-ai project state create` 为此 project 创建一个并写指针；`cargo-ai project state bind <uuid>` 重指向已有 state。
27. 对 states 迁移到 workspace 之前 scaffold 的 project：resource map 仍内联在 `cargo.state.json`，只要你保留在那里，它就继续对该文件 deploy，不会有任何背后迁移。`state create` 才会迁移：map 移到新 state，文件变成指针，然后你提交它。不要不告诉团队就迁移，因为 teammate 在 pull 新指针前 deploy 会从一个已不存在的 state 部署。删除 state 的 `state remove` 在 CDK README 中有，但不在 CLI 1.0.96，下一版发布。
28. 三种传值方式不可互换：`secret("ENV_VAR")` 在 deploy 时从你的环境读取，排除在 content hash 和 state 之外；deploy 前 export 该 env var；缺失会以 unresolved `${ENV_VAR}` placeholder 失败。`env("ENV_VAR")` 在 load 时从你的环境读取，其值进入 spec 并因此进入 content hash，所以改变会显示为 drift；用于想被跟踪的非 secret config。`workspaceEnv("NAME")` 是指向 workspace env-var catalog 条目的 pointer；本地不读任何东西，也不会失败；值留在 server-side 且每次使用重新读取，所以在 workspace 中轮换后无需 redeploy 就到达资源；用 `cargo-ai workspaceManagement envVar` 管理 catalog。
29. `secret()` 和 `workspaceEnv()` 只在 secret-typed schema 位置被接受；`cargo-ai project types` 恰好在那些位置打印 union。资源自己的 `env` block 接受 `env()` 或 `secret()`，拒绝 pointer，因为 worker、app、agent 或 script 已经继承整个 workspace catalog；在那里放 pointer 只能重述它本来就能读取的变量。
30. 轮换 `secret()` 需要不止普通 deploy 才能落地：把值排除在 content hash 外，是 rotation 不显示为 drift 的原因，也是 `deploy` 不推送新值的原因：hash 没变，资源不会重新 apply。用 `deploy --refresh` 或对该资源做任何其他编辑来滚动。`workspaceEnv()` 没有这个步骤；这是它大部分吸引力所在。
31. 按 handle 连接，绝不用 `.uuid`：直接传 `define*` handle（如 `dataset: hubspot`、`tools: [enrich]`），或对未在代码中定义的资源用 `xxRef("uuid")`（如 `connectorRef`、`modelRef`、`folderRef`、`toolRef`、`agentRef` 等）。当引用需要 per-call options 时，包成 `{ ref, …options }`（例如 `models: [{ ref: contacts, readOnly: true }]`）。
32. workspace integrations 变化后运行 `cargo-ai project types`；它重新生成 `.cargo-ai/`，使 `defineConnector`/`defineModel` config（以及 workflow bodies 中的 `integrations.*`）针对真实 schemas type-check。typing 是 bonus，绝不是 gate：没有它 deploy 也能工作。
33. repo 的任意子目录都可以（CLI ≥ 1.0.83）。命令会向上走到声明 `@cargo-ai/cdk` 的 package root，再向下到 resource directory（脚手架 repo 中是 `infra/`），因此从 project 内任何位置运行，`.cargo-ai/` 和 `cargo.state.json` 都会落在正确位置。`--dir <path>` 仍可覆盖。这也是资源放在 `infra/` 而不是 root 的原因：loader 会 import 给定目录下每个 `.ts`，而 repo root 还会有 `scripts/`，其文件在 import 时运行；把命令指向 root 会执行它们。
34. CI 中使用 `--yes`。`deploy` 和 `destroy` 会提示确认；非交互运行必须传 `--yes`。
35. 带付费节点的 `definePlay`/`defineTool` graph 在铺开前先做 sample run。Deploying 不是 running，但第一个运行 deployed play 的东西通常是针对整个 segment 的 batch，且 scheduled play 每次 run 都会重新计费每个节点。在把全部资源 enroll（或启用 schedule）前，对 deployed workflow 跑 10–20 records：`cargo-ai orchestration batch create --data '{"kind":"filter","modelUuid":"…","filter":…,"limit":15}'`，或用 `batch create --file ./plays/x.ts` 在不 deploy 的情况下 test-run 该 module。然后向用户展示 record count 和 credit estimate，并请求批准 full enrollment。阅读 provider playbook `../cargo-gtm/provider-playbooks/<slug>.md`，尤其其 Recurring use 部分，以及 `../cargo-gtm/references/cost-discipline.md` 中的 gate。
36. `defineAlert` 的 actions 调用付费节点时，每次 breach 都会重新计费。alert 的 actions 作为真实 runs 触发，所以 threshold 大小不当加上紧凑 schedule 可能每 tick breach 并计费。deploy 前用 `cargo-ai observability alert preview` 设定 threshold；优先便宜的 notification actions（一个发帖的 agent、一个 connector notification），而不是任何会 fan-out 的东西；当 action 调用 credits-based provider 时应用同样的 cost gate。Scope/threshold 和 firing semantics 见 `../cargo-observability/SKILL.md`。
37. `defineMailbox` 按月计费，`defineDomain` 会重写 DNS zone。Mailbox 只要存在就每月 100–160 credits（用 `cargo-ai mailboxManagement pricing get` 获取实时数字），所以 plan 中的 `+ create mailbox:…` 行是用户批准的 recurring charge，不是一次性费用。其 `domain`、`username` 和 `type` 是 create-only：改其中任何一个都是 destroy + recreate，即一个全新 inbox 回到 45 天 warm-up ramp 的底部。deploy 会轮询 `refreshStatus` 最多 5 分钟等待 `active`。对 `defineDomain`，`dnsRecords` 是整个 zone，不是 patch：声明它会替换每条 live record（包括 registrar 在购买时写的记录），省略它则 zone 保持不变。`redirectUrl`、`dmarcEmail` 和 `dmarcPolicy` 是 additive，是配置 zone 而不替换它的受支持方式，所以只有当你确实想拥有每条 record 时才用 `dnsRecords`。对在 UI 购买的 domain 或 mailbox 使用 `adopt: true`。Ramp、suppression 和 sending 见 `../cargo-mailbox-management/SKILL.md`。
38. 将 CDK 管理的资源路由到清晰标记的 folder。在每个 builder 上设置 `folder:`，使 CDK 拥有的一切落在专用 folder 中，其名称向 UI 中任何人表明 owned by code — don't hand-edit（手动 UI 编辑会在下一次 `plan` 中读作 drift）。Folders 按 kind 区分，所以每种 kind 给它自己的 folder，但共享一个短、可识别的前缀；推荐 **`🔒 CDK`**（例如 `🔒 CDK Models`、`🔒 CDK Agents`）。名称保持短（长标签在 folder tree 中截断）；lock emoji 是 don't touch 提示。见 `guides/authoring-resources.md`。
39. 用 `cargo-ai project --help` 和 `cargo-ai project <subcommand> --help` 查看实时 flag surface。
40. 当文档中的命令、flag 或 response 与你观察到的不同，提交报告：`cargo-ai workspaceManagement report create`（见 `../cargo-workspace-management/SKILL.md`）。

适用边界 · 注意事项

• 一次性操作、读取或 ad-hoc 查询时不要用；改用匹配的 capability skill（命令式 `cargo-ai <domain>`）。
• 没有 Cargo 账号/workspace、无法安装 `@cargo-ai/cli`，或项目无法依赖 `@cargo-ai/cdk` 时不要用。
• 不要对非空目录运行 `cargo-ai project init --force`；也不要把项目目录命名为 `my-workspace`，因为那是 workspace 名字。