cargo-cdk

Cargo CDK — 声明式工作空间即代码

使用此技能在 TypeScript 中定义 Cargo 工作空间（使用 @cargo-ai/cdk 的 define* 构建器），并通过 cargo-ai cdk deploy 将其与实时基础设施协调。它是命令式能力技能的声明式对应物：不是为每个资源运行一个 CLI 命令，而是编写整个图一次并重复部署，通过提交的 cargo.state.json 将代码与 Cargo 创建的内容链接起来。

1) 此技能管理的内容

• 创作每个 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 还是 CLI？——路由决策

声明式（此技能） vs 命令式（能力技能）。

当用户将资源作为工件管理时，使用 CDK：

• "设置/搭建/引导整个工作空间（作为代码/从模板）。"
• "使其可重现/版本控制/在 git 中/跨环境可重复（开发 → 生产）。"
• "一起部署这些连接器 + 模型 + 智能体"（一个由依赖连接的多资源图）。
• 任何应该可重新运行和可差异化的内容，丢失定义将是一个问题。

当用户执行一次性操作或探索时，使用匹配的能力技能（命令式 cargo-ai <domain>）：

• "创建一个连接器"、"向此模型添加一列"、"列出连接器"、"运行此工作流"、"查询存储"、"读取此智能体的记忆。"
• 任何读取、临时查询或不需要存在于代码中的单个变更。

如果不确定，询问结果是否应该提交并可重新部署。如果是 → CDK。如果是快速操作或读取 → 能力技能（参见 cargo 路由器 以选择正确的领域）。

3) 生命周期

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) 文档层次结构

• 第 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) 读取行为——将任务匹配到文档并阅读它

当任务涉及…	首先阅读此文档	它提供的内容
编写 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/scaffold-a-workspace.md	从头搭建新工作空间（init --template full → types → plan → deploy）。
recipes/add-connector-and-model.md	添加数据源 + 从中获取数据的模型，通过句柄连接。
recipes/build-an-agent.md	组合模型 + 工具 + 智能体（使用 uses / models / tools）并部署。
recipes/migrate-existing-workspace.md	通过 cdk import 将已存在的实时工作空间纳入 CDK 管理。
recipes/deploy-from-ci.md	从 CI 非交互式部署（令牌认证 + 已提交状态）。

6) 关键规则

• 提交 cargo.state.json。 它是从代码到 Cargo 创建的资源的链接——也是已部署剧本或智能体的唯一句柄（它们没有 slug）。丢失它会导致这些资源孤立；通过 cargo-ai cdk import 恢复链接。它只记录 {hash, uuid, outputs}——从不记录秘密值。Git 忽略工作文件（cdk init 会搭建此忽略规则）：

  .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。
• 将 CDK 管理的资源路由到明确标记的文件夹中。 在每个构建器上设置 folder:，以便 CDK 拥有的所有内容都落在一个专用文件夹中，其名称向 UI 中的任何人发出信号“由代码拥有——不要手动编辑”（手动 UI 编辑会在下一次 plan 时被读回为漂移）。文件夹是按类型划分的，因此为每种类型分配一个单独的文件夹，但共享一个简短、可识别的前缀——推荐：🔒 CDK（例如 🔒 CDK Models、🔒 CDK Agents）。保持名称简短（长标签会在文件夹树中截断）；锁表情是“不要触碰”的提示。参见 guides/authoring-resources.md。

先决条件

标准 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。

帮助

• cargo-ai cdk --help 和 cargo-ai cdk <subcommand> --help 查看实时标志信息。
• 当记录的命令/标志/响应与你观察到的内容不匹配时，提交报告：cargo-ai workspaceManagement report create（参见 ../cargo-workspace-management/SKILL.md）。