cargo-cdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo CDK — declarative workspace-as-code

Cargo CDK — 声明式工作区即代码

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 cdk 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 committed

cargo.state.json

linking your code to what Cargo created.

使用此技能在TypeScript中定义Cargo工作区（来自

@cargo-ai/cdk

的

define*

构建器），并通过

cargo-ai cdk deploy

将其与实时基础设施同步。它是命令式功能技能的声明式替代方案：无需为每个资源运行一条CLI命令，只需编写一次完整的资源关系图，即可重复部署，同时通过已提交的

cargo.state.json

将代码与Cargo创建的资源关联起来。

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 cdk 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 cdk 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：

"搭建/启动整个工作区（以代码形式/基于模板）。"
"实现可复现/版本控制/存入Git/跨环境重复部署（开发→生产）。"
"同时部署这些连接器+模型+Agent"（通过依赖关系连接的多资源关系图）。
任何需要可重复运行、可差异对比的操作，丢失定义会造成问题的场景。

当用户执行一次性操作或探索性操作时，使用对应的功能技能（命令式

cargo-ai <domain>

）：

"创建一个连接器"、"为该模型添加一列"、"列出连接器"、"运行此工作流"、"查询存储"、"读取此Agent的内存"。
任何读取、临时查询或无需存入代码的单次修改操作。

若不确定，可询问用户结果是否需要提交并可重新部署。如果是→使用CDK。如果是快速操作或读取→使用功能技能（请查看

cargo

路由选择合适的领域）。

3) The lifecycle

3) 生命周期

cargo-ai cdk init <dir>     scaffold a project from a template (blank | full)
        │
cargo-ai cdk types          generate per-workspace types for typed config (optional)
        │
   (author define* files)   importing a .ts file IS registration — no manifest
        │
cargo-ai cdk plan           offline: compile the graph, diff against cargo.state.json
        │
cargo-ai cdk deploy         create/update resources in dependency order, write state
        │
cargo-ai cdk destroy        tear down resources recorded in state

Side branches:

cargo-ai cdk refresh

(read-only drift report) ·

deploy --refresh

(re-apply code over out-of-band edits) ·

deploy --prune

(delete resources removed from code) ·

cargo-ai cdk import <id> <uuid>

(bind an existing live resource into state) ·

cargo-ai cdk rollback

(restore the pre-deploy state snapshot).

cargo-ai cdk init <dir>     从模板搭建项目（空白 | 完整）
        │
cargo-ai cdk types          为工作区生成专属类型以实现类型化配置（可选）
        │
   (编写define*文件)   导入.ts文件即完成注册——无需清单文件
        │
cargo-ai cdk plan           离线：编译资源关系图，与cargo.state.json对比差异
        │
cargo-ai cdk deploy         按依赖顺序创建/更新资源，写入状态
        │
cargo-ai cdk destroy        销毁状态记录中的资源

分支操作：

cargo-ai cdk refresh

（只读漂移报告）·

deploy --refresh

（在外部编辑之上重新应用代码）·

deploy --prune

（删除代码中移除的资源）·

cargo-ai cdk import <id> <uuid>

（将现有实时资源绑定到状态中）·

cargo-ai cdk rollback

（恢复部署前的状态快照）。

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 cdk

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 cdk

子命令+参数）、

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 first	What 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 cdk types` , tsconfig wiring, `integrations.*` in workflow bodies	`guides/typed-config.md`	What `cdk 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 cdk` subcommand and its flags.
A deploy error / footgun	`references/troubleshooting.md`	The known failure modes and fixes.

当任务涉及…	首先阅读	能获得什么
编写 `define*` 文件、连接资源、 `secret()` / `env()` 、 `defineWorkflow` 主体（工具/剧本逻辑）	`guides/authoring-resources.md`	构建器目录、句柄/引用模型、密钥管理，以及工作流主体的编译方式。
`plan` / `deploy` / `destroy` 、状态文件、漂移检测、纳入现有资源、CI集成	`guides/deploy-and-state.md`	部署生命周期、 `cargo.state.json` 语义、漂移/导入/回滚、异步构建。
类型化配置、 `cargo-ai cdk types` 、tsconfig配置、工作流主体中的 `integrations.*`	`guides/typed-config.md`	`cdk types` 生成的内容，以及如何将其集成到项目中。
特定构建器的字段/规范/输出	`references/resources.md`	每个构建器→规范字段→接受的引用类型→输出内容。
精确的命令参数	`references/commands.md`	所有 `cargo-ai cdk` 子命令及其参数。
部署错误/陷阱	`references/troubleshooting.md`	已知故障模式及修复方案。

Recipes — follow step-by-step when one matches

操作手册 — 当有匹配场景时按步骤执行

Recipe	Use when…
`recipes/scaffold-a-workspace.md`	Standing up a new workspace from scratch ( `init --template full` → 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 CDK management via `cdk import` .
`recipes/deploy-from-ci.md`	Deploying non-interactively from CI (token auth + committed state).

操作手册	适用场景…
`recipes/scaffold-a-workspace.md`	从头搭建新工作区（ `init --template full` → 生成类型 → 计划 → 部署）。
`recipes/add-connector-and-model.md`	添加数据源+基于该数据源的模型，通过句柄连接。
`recipes/build-an-agent.md`	组合模型+工具+Agent（通过 `uses` / `models` / `tools` ）并部署。
`recipes/migrate-existing-workspace.md`	通过 `cdk import` 将已上线的工作区纳入CDK管理。
`recipes/deploy-from-ci.md`	从CI非交互式部署（令牌认证+已提交的状态）。

6) Critical rules

6) 关键规则

Commit
cargo.state.json
. It is the link from your code to the resources Cargo created — and the only handle on a deployed play or agent (they have no slug). Lose it and those resources orphan; recover a link with
```
cargo-ai cdk import
```
. It records only
```
{hash, uuid, outputs}
```
— never secret values. Git-ignore the working files (
```
cdk init
```
scaffolds this):
gitignore
```
.cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.audit.jsonl
```
Secrets: wire credentials with
```
secret("ENV_VAR")
```
(often
```
secret("HUBSPOT_API_KEY")
```
). The value is read from the environment at deploy time, kept out of the content hash and out of state, so rotating a token doesn't read as drift. Export the env var before deploying — a missing one fails the deploy with an unresolved
```
${ENV_VAR}
```
placeholder.
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 cdk 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.
Run
cdk
commands from the project root.
```
npx
```
/
```
cargo-ai
```
resolve from the nearest
```
package.json
```
; run elsewhere and
```
.cargo-ai/
```
and
```
cargo.state.json
```
land in the wrong directory. Use
```
--dir <path>
```
to be explicit.
--yes
in CI.
```
deploy
```
and
```
destroy
```
prompt for confirmation; non-interactive runs must pass
```
--yes
```
.

提交
cargo.state.json
。它是代码与Cargo创建的资源之间的链接——也是已部署剧本或Agent的唯一句柄（它们没有别名）。丢失该文件会导致这些资源成为孤立资源；可通过
```
cargo-ai cdk import
```
恢复链接。它仅记录
```
{hash, uuid, outputs}
```
——绝不会存储密钥值。将工作文件加入Git忽略（
```
cdk init
```
会自动生成该配置）：
gitignore
```
.cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.audit.jsonl
```
密钥管理：使用
```
secret("ENV_VAR")
```
（通常为
```
secret("HUBSPOT_API_KEY")
```
）连接凭证。值会在部署时从环境变量读取，不会纳入内容哈希或状态，因此令牌轮换不会被识别为漂移。部署前需导出环境变量——缺失环境变量会导致部署失败，并提示未解析的
```
${ENV_VAR}
```
占位符。
通过句柄连接，绝不要使用
.uuid
。直接传递
```
define*
```
句柄（
```
dataset: hubspot
```
、
```
tools: [enrich]
```
），或对未在代码中定义的资源使用
```
xxRef("uuid")
```
（
```
connectorRef
```
、
```
modelRef
```
、
```
folderRef
```
、
```
toolRef
```
、
```
agentRef
```
……）。当引用需要每次调用的选项时，将其包装为
```
{ ref, …options }
```
（例如
```
models: [{ ref: contacts, readOnly: true }]
```
）。
工作区集成变更后运行
cargo-ai cdk types
——它会重新生成
```
.cargo-ai/
```
，使
```
defineConnector
```
/
```
defineModel
```
配置（以及工作流主体中的
```
integrations.*
```
）能针对实际架构进行类型校验。类型校验是附加功能，并非强制要求：即使不使用也可正常部署。
从项目根目录运行
cdk
命令。
```
npx
```
/
```
cargo-ai
```
会从最近的
```
package.json
```
解析；在其他目录运行会导致
```
.cargo-ai/
```
和
```
cargo.state.json
```
存放在错误位置。可使用
```
--dir <path>
```
明确指定路径。
CI中使用
--yes
。
```
deploy
```
和
```
destroy
```
会提示确认；非交互式运行必须传入
```
--yes
```
。

Prerequisites

前置条件

Standard Cargo CLI setup (install, login, output conventions) is shared across all skills — see

../cargo/references/prerequisites.md

Two CDK-specific extras:

The project needs
@cargo-ai/cdk
as a dependency (for the
```
define*
```
builders you import).
```
cargo-ai cdk init
```
scaffolds a
```
package.json
```
with it — then run
```
npm install
```
.

The
cargo-ai cdk
domain ships with the CLI. Confirm with

cargo-ai cdk --help

; an

unknown command

means the CLI is too old —

npm install -g @cargo-ai/cli@latest

标准Cargo CLI设置（安装、登录、输出约定）为所有技能共享——请查看

../cargo/references/prerequisites.md

。

CDK专属的两个额外条件：

项目需要
@cargo-ai/cdk
作为依赖（用于导入
```
define*
```
构建器）。
```
cargo-ai cdk init
```
会生成包含该依赖的
```
package.json
```
——之后运行
```
npm install
```
。
cargo-ai cdk
域随CLI一同发布。通过
```
cargo-ai cdk --help
```
确认；若提示
```
unknown command
```
则说明CLI版本过旧——运行
```
npm install -g @cargo-ai/cli@latest
```
更新。

Help

帮助

cargo-ai cdk --help

and

cargo-ai cdk <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 cdk --help

和

cargo-ai cdk <subcommand> --help

可查看实时参数说明。

当文档中的命令/参数/响应与实际不符时，提交报告：
```
cargo-ai workspaceManagement report create
```
（请查看
```
../cargo-workspace-management/SKILL.md
```
）。