# @cargo-ai/cdk 中文文档

规范地址：https://npmcn.com/package/%40cargo-ai/cdk/

版本：1\.0\.140
npm 元数据更新时间：2026-11-09T02:21:21.462Z
中文译文更新时间：2026-11-09T03:06:15.403Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cargo-ai/cdk
原文对照：https://npmcn.com/package/%40cargo-ai/cdk/?lang=original
项目主页：https://www.getcargo.ai/
源码仓库：https://github.com/getcargohq/cargo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，486 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：14 个
- peer 依赖：zod ^4\.4\.3
- 首次发布：2026-07-02T20:51:23.589Z
- 最新版本发布：2026-11-09T02:21:21.237Z
- 近 30 天下载量：101309（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：129（近 12 个月 129 个）

## 中文简介

货物项目——在代码中定义所有货物资源(连接器、模型、剧作、工具、代理、MCP服务器、文件夹、文件、工人、应用软件、发送域、邮箱),并公开部署:计划、应用、刷新、进口和销毁

## 安装

```sh
npm install @cargo-ai/cdk
```

也可以使用：`pnpm add @cargo-ai/cdk`、`yarn add @cargo-ai/cdk`、`bun add @cargo-ai/cdk`

## README

# @cargo-ai/cdk-货物项目

在代码中定义整个货运工作空间——连接器,模型,游戏,工具, 代理, MCP 服务器, 上下文, 片段, 容量, 领地, 文件夹, 文件, 工人, 应用程序, 发送域和邮箱—— 并部署 宣示性地,同样的方式,你管理云 基础设施与普鲁米或 AWS CDK (英语). A 类 **项目** 是声明它的文件夹。 对于一个完整的概述, 见 [项目文件](https://docs.getcargo.ai/get-started/project-layout)。 。 。 .

## 所需资源

-   节点.js 22.x
-   货物 API 令牌( 在您的工作空间中创建 ) **设置 – API**(中文(简体) )

## 安装

`@cargo-ai/cdk` 是货物项目背后的库: `define*` 建设你 导入您的资源文件,以及部署它们的引擎。 开车吧 货物CLI:

```bash
npm install -g @cargo-ai/cli          # the Cargo CLI — `cargo-ai login` + `cargo-ai project`
cargo-ai login --oauth                # browser sign-in
# …or, for CI / non-interactive:
export CARGO_API_TOKEN=<your-api-token>
```

登录写入 `~/.config/cargo-ai/credentials.json`,每个工程命令 读取(与 `CARGO_API_TOKEN` 编号 : `CARGO_WORKSPACE_UUID` (原始内容存档于2018-10-21). env vars. 运行 命令为 **`cargo-ai project <command>`**,或作为 **`npm run <script>`** 页:1 日常的(脚手架项目) `types` 编号 : `info` 编号 : `plan` 编号 : `deploy`) (中文(简体) ).

包裹还运送了一个项目-当地 `cargo-cdk` 宾 (`npx @cargo-ai/cdk <command>`),以及 `cargo-ai cdk` 保留为 `cargo-ai project`这样 旧的脚本继续运行. 不要在全球安装软件包:一个全球 `cargo-cdk` 在你身边 `PATH` 将会与AWS CDK相冲突.

## 项目布局

工程是文件夹控件 `cargo.json`路边 `package.json` 标记 a 节点软件包 :

```text
my-workspace/
  cargo.json          { "resources": "infra" }
  cargo.state.json    the pointer to this project's deploy state — commit it
  infra/              the resource files; every .ts in it is loaded
  outputs/            executions (runs and batches), when the project has any
```

`resources` 名称文件夹 `.ts` 资源文件,相对于 `cargo.json`; 可选 `executions` 数组替换默认值 `outputs/`,以及 (单位:千美元) `*` 匹配任意文件夹名称( i)`"outputs/*/executions"`) (中文(简体) ). `cargo.state.json` 财务报告和审定财务报表 `outputs/` 坐在旁边 `cargo.json`。每个命令都向前走 从它运行到最近的 `cargo.json` 并且从那里工作, 指定添加一行的行,当没有,而不是猜测 从文件夹所持位置创建项目。 一个存储库可以保存多个项目, 一个 `cargo.json` 每一个.

## 快开始

脚手架项目:

```bash
cargo-ai project init my-workspace
# pick a cookbook in the wizard, or afterwards:
#   cargo-ai project add cookbook/<name>
cd my-workspace && npm install
```

`init` 脚手架 货物模板([`getcargohq/cargo-manifest`](https://github.com/getcargohq/cargo-manifest): 上下文、下下文和表层,a `cargo.json` 在根部,和 **页:1 资源文件在 `infra/`**从项目内任何地方运行命令—— 他们发现 `cargo.json` 装入 `infra/` 从它.

或者自己添加资源文件——导入文件 **实值** 注册,有 没有表明:

```ts
// my-workspace/infra/contacts.ts
import { defineConnector, defineModel, secret } from "@cargo-ai/cdk";

// `secret()` reads the value at deploy time and keeps it out of state and the
// content hash — use it for credentials. The config shape is per-integration
// (HubSpot takes a Private App token or an OAuth refresh token); run
// `cargo-ai project types` to have it type-checked (see Typed config below).
export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});

// Pass the connector handle as `connector` — the model depends on it, so the
// deploy creates the connector first and injects its dataset uuid.
export const contacts = defineModel("contacts", {
  connector: hubspot,
  extractSlug: "fetchRecords",
});
```

```bash
export HUBSPOT_API_KEY=...        # secret() reads this at deploy time
npm run info                      # what the project declares — no API calls
npm run plan                      # diff the code against the deploy state
npm run deploy                    # create everything, record it in the deploy state
```

(脚手架) `package.json` 电线 `npm run types` 编号 : `info` 编号 : `plan` 编号 : `deploy`。 。 。 . 或者直接使用 `cargo-ai project <command>`. ) (中文(简体) )

重运行 `deploy` 仅更改已改变的内容; 一个不变的工作空间是无操作.

## 已输入配置

`defineConnector` 财务报告和审定财务报表 `defineModel` 配置被输入到您的工作空间 实际的融合计划。 一次生成类型 :

```bash
npm run types          # or: cargo-ai project types
```

他们降落在 `.cargo-ai/`添加到您的 tsconfig 中 `include` 明确 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}光着身子 `.cargo-ai` (一个点- dir) 被 TypeScript 忽略 :

```jsonc
// tsconfig.json
"include": ["*.ts", ".cargo-ai/**/*.d.ts"]
```

在那之后,我们.., `config` 对照集成计划检查,例如HubSpot 是一个受歧视的结合, 所以编辑完成 `method` 并且要求 匹配证书,以及 `secret()` 任何证明文件 预期。 uuid- reference 配置字段(例如提取器) `modelUuid` 编号 : `relatedModelUuid`键入为 `In<string>`资源 手柄的 uuid 直接 (`modelUuid: accounts.uuid`(d) 将依赖线线线接通——否 铸造——或用字形的uuid字符串. `defineAgent`是因为 `languageModel` 输入 同一方式:通过 `defineConnector` 操作和它是模型的结合 整合的连接器暴露。 重新运行 `npm run types` 添加或更改后 工作空间集成,或者当连接器的模型发生变化时.

打字是奖金,从来不是门:没有同步的集成(或自定义) 一) 回到松散的记录或平地 `string`,则a `connectorRef` 输入时不能输入。 API 拒绝连接器的一击 不公开,当发布 写,同样的方式拒绝 不匹配集成的连接器配置 .

## 界定资源

每个货物资源都有 `define*` 返回 a 的构建器 **控件**线 通过将一个手柄传递到另一个手柄将资源合并起来——依赖图是 只是你的可变图表。 通过 **控件** 直接(或 `xxRef("uuid")` (单位:千美元) 您没有在代码中定义资源 ; 不 `.uuid` 在呼叫现场。 在一个 引用按调用选项,将其包装为 `{ ref, …options }`。 。 。 .

```ts
import { defineAgent, defineTool, defineWorkflow, sendEmail } from "@cargo-ai/cdk";

const flow = defineWorkflow("enrich", { input, output }, ({ input, ai }) => …);
export const enrich = defineTool("enrich", { workflow: flow, emojiSlug: "mag" });

export const sdr = defineAgent("sdr", {
  connector: openai,                              // the LLM connector (or connectorRef("…"))
  languageModel: "gpt-4o",
  systemPrompt: "Qualify inbound leads.",
  // everything the agent can call or read — one array, kind inferred per handle
  uses: [
    { ref: contacts, readOnly: true },            // a data model (handle + options)
    enrich,                                        // a tool (bare handle)
    hunter.actions.findEmail,                      // an action off a connector handle
    sendEmail,                                     // a native action (same binding a workflow body calls)
  ],
});
```

### 在工作流程内参考处理

A 类 `defineWorkflow` 尸体是从源头解析出来的 从未执行过 所以不能 在运行时读取关闭值。 装载器关闭了缺口:它扫描每个身体的 自由变量和线程文件所绑定的变量( 导入, 模块 consts) 通过SDK的 `imports` 选项。 因此可以使用构建时控件 **赤线** 在身体内部——没有锅炉板:

```ts
const accounts = defineModel("accounts", { … });

const flow = defineWorkflow(
  "tam",
  { input, output },
  ({ input, model }) =>
    // `accounts` is a module-level handle — the loader injects it for you.
    model.upsert({ modelUuid: accounts.uuid, matchingColumnSlug: "domain", matchingValue: input.domain }),
);
```

手柄 `uuid` 是一个推迟的符号,所以模型在部署时首先被订购 而它真正的uuid被替换。 常数工作方式相同(内含 页:1 有两件事要知道: 手柄的符号不能用在计算中 表达式(仅作为直接配置值——在部署之前它不是一个字符串),以及 已到达文件中定义的工作流程 **仅限** 通过中转 `import` (没有扫描为顶级资源文件)绕过此通道——那么SDK 丢出一个错误指示您通过清晰的 `imports` 选项.

见 [定义资源](https://docs.getcargo.ai/connectors/overview) 每笔 构建器(连接器、模型、游戏、工具、代理、MCP服务器、上下文、部件、, 能力、领土、文件夹、文件、工人、应用软件、域)和弹道规则.

原生对象和统一型号`kind: "native"`)和背景 仓库(`defineContext`拥有自己的指南: [对象模型](https://docs.getcargo.ai/models/object-models), (中文(简体) ), [统一](https://docs.getcargo.ai/models/unification),以及 [A. 背景情况](https://docs.getcargo.ai/context/overview)。 。 。 .

## 图标

在脚手架项目中,日常命令是 `npm run` 脚本 :

```bash
npm run types     # generate per-workspace types for typed config
npm run info      # offline: what the project declares, and any diagnostics
npm run plan      # diff the code against this project's deploy state
npm run deploy    # create/update resources, record them in the state
```

其中两个回答不同的问题,值得知道是什么. `plan` 答题 **怎么样 `deploy` 对** ——它的单位是变化,它退出 非零,所以CI可以打开它. `info` 答题 **这是什么** 它的单位是 资源,包括声明它的文件,而且它从未失败。 到达 `plan` 部署前 `info` 当一个资源没有达到它的目的时 文件已读取.

在没有命令的情况下运行, 工程本地本位( N)`npx @cargo-ai/cdk`以何者为准 其中,有道理的是: `info` 在一个项目, `init` 在一个外面.

`deploy` 是唯一一个花钱的命令: a `+ create domain:…` 线条 以工作空间信用值登记一个域,不退款(和 `destroy` 撤销). 在确认前先看计划.

运行任何命令,包括没有脚本的命令 `cargo-ai project`数字 :

```bash
cargo-ai project init                  # ask what to scaffold (a directory, and the repo or a cookbook)
cargo-ai project init <directory>      # scaffold the Cargo template
cargo-ai project info                  # the resolved project: every resource, its file, its state, diagnostics
cargo-ai project graph                 # the live workspace's resource graph, as a Mermaid flowchart (--json for CargoGraph)
cargo-ai project graph --project --plan # offline: this project's graph, coloured by what deploy would change
cargo-ai project deploy --prune        # also delete resources removed from code
cargo-ai project deploy --refresh      # re-read live resources, re-apply out-of-band changes
cargo-ai project refresh               # read-only: report resources that drifted from code
cargo-ai project import <id> <uuid>    # bind an existing live resource into state
cargo-ai project rollback              # restore the deploy state from the pre-deploy snapshot
cargo-ai project destroy --target <id> # tear down one resource
cargo-ai project destroy --all         # tear down everything in state
```

通用旗帜 : `--dir <path>`, (中文(简体) ), `--yes` (请按 CI 要求的提示), `--json`,以及 `--force` (窃取所司州锁. 见 [部署](https://docs.getcargo.ai/deploy/deploying)。 。 。 .

## 烹饪手册

Cookbook是工程项目实例——TAM管线,账号评分,CRM 浓缩——作为文件夹发表于 [`getcargohq/gtm-skills`](https://github.com/getcargohq/gtm-skills)。 。 。 . `add` 安装一个 **进入您已有的项目**,作为一个兄弟 什么在那里:

```bash
cargo-ai project cookbook list             # every cookbook
cargo-ai project cookbook search scoring   # by name, job, or the resources it declares
cargo-ai project cookbook view tam-building # what it deploys, what it will ask you for, how to adapt it
cargo-ai project add cookbook/tam-building # copy it in
```

复制就是全部 `add` 已经 接下来的是什么——将实例与 项目已经宣布, 适应真实的客户关系管理和字段, 输入 在他们被问到之前要先查清楚 - 这是烹饪手册本身的程序, 财务报告和审定财务报表 `add` 将其打印为核对表(或将其交给编码代理)而不是 结束于 `deploy`。 。 。 .

厨书 `infra/` 土地状况 `infra/<name>/`页:1 `scripts/` 下级 `scripts/<name>/`,以及所有其它的——它的 `SKILL.md`, (中文(简体) ), `references/`, (中文(简体) ), `evals/` 下 `.claude/skills/<name>/`,除了技能之外,还已经 船,和再次在 `.agents/skills/<name>/`数字 :

```text
infra/crm-enrichment/index.ts
scripts/crm-enrichment/seed.ts
.claude/skills/crm-enrichment/SKILL.md
.claude/skills/crm-enrichment/references/run.md
.claude/skills/crm-enrichment/evals/acceptance.md
.agents/skills/crm-enrichment/SKILL.md
.agents/skills/crm-enrichment/references/run.md
.agents/skills/crm-enrichment/evals/acceptance.md
```

技能的一半写了两次 因为没有一个目录被每个读取 代理 : Claude Code 仅在下面发现项目技能 `.claude/skills/`时 光标、代码和双子座读取 `.agents/skills/`。它们不是 symlinks,它不会可靠地通过一个 Windows 的检出——如果 您编辑烹饪本的程序,同时编辑两者。 这个 `infra/` 财务报告和审定财务报表 `scripts/` 半数 写入一次: 资源以路径而不是发现方式加载, a 第二副本将两次登记每个资源;脚本活在 repo 根上 所以装货者从不进口.

每块都用烹饪本来命名, 所以两本烹饪本每本都带一个CRM 连接器别挡路 参考文献留在旁边 引用他们的程序。 装载器扫描每个 `.ts` 资源项下 文件夹,所以 `infra/<name>/` 和任何其他目录一样.

`add` 永远不要碰你 `package.json` 或者说 `tsconfig.json`,报告每个文件 已经存在并跳过它(`--overwrite` 替换),运行 `check` 之后,一个重复的弹壳立即浮出水面,而且从未部署。 用这个 而不是说 `init --force`,在部署时替换工程外壳 状态幸存下来——留下下一个计划,比照代码显示一个活的工作空间 没有人写.

## 交给编码代理

当一个人运行 `init` 或者说 `add` 和编码代理(Claude Code, Cursor, 密码,双子座CLI)开机 `PATH`最后一个问题是是否打开它 新项目 :

```text
How would you like to continue?
❯ Open Claude Code   build it with the cargo-project skill loaded
  Exit               print the next steps
```

它在项目目录中打开,并附有一个简要说明 创建: 命令此工程有、 有 `cargo-project` 技术是 a. 授权 `define*` 建筑师,还有 `deploy` 信贷支出和必须 不被询问。 之后 `add`烹饪本上的要点 `.claude/skills/<name>/SKILL.md` 命令剩下的工作——开始于 适应,而不是在刚刚运行的复制步骤上; 查看这些输入, 要求这些 - 而不是重述程序 烹饪本已经上船.

## 从编码代理运行

每一个可以提问的命令都拒绝 当没有人可以 回答:没有TTY, `CI=true`,或编码代理机(Claude Code, Cursor, (原始内容存档于2018-10-25). Codex,. 而不是挂在一个快件上,它离开 `2` 并打印命令到 重运行时提供缺失参数 。 传递论据——如 脚本引用已经做了——始终是非交互路径.

## 状态漂移( D)

一个项目 **部署状态** 是从您的代码到资源 创建。 它住在你的工作空间里 反弹会指向它:

```json
{ "stateUuid": "8f2c…" }
```

`init` 创建国家并写道: `cargo.state.json`,所以指针在 脚手架上的人. **交出来** 没有uuid 新的退票 找到它的状态,部署不会悄悄地进行替换(这将 孤儿的一切 旧的轨道。 州里记录的只有 uids, hashes 和 产出——绝不是秘密价值.

每个项目一个州,每个工作区最多10个活州:

```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 and write the pointer
cargo-ai project state bind <uuid>     # repoint at an existing one
cargo-ai project state remove <uuid>   # drop a state (does not delete live resources)
cargo-ai project state connect         # plan PRs and deploy pushes from its GitHub repository
cargo-ai project state disconnect      # stop deploying from GitHub (the state stays)
```

州迁移到工作区前的脚手架工程有资源地图 本身在 `cargo.state.json`,并针对该文件持续部署时间 当你把它留在那里. `state create` 是移动它的地方: 映射到一个新的 状态,文件变成指针,然后你来执行。 没有东西迁移一个项目 在你背后——一个在拉出指针前部署的队友会 以其他方式从不再存在的国家部署.

Git- ignore 生成的类型和工作文件 部署在旁边 (但承诺) `cargo.state.json`:

```gitignore
.cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.cache.json
cargo.state.audit.jsonl
```

`cargo-ai project refresh` 在项目外更改或删除的资源 (如在《货物统一目录》中编辑); `cargo-ai project deploy --refresh` 重新应用您的 代码在他们身上。 见 [状态和漂流](https://docs.getcargo.ai/deploy/state-and-drift)。 。 。 .

## 文档

完整文档: [{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}请检查date=中的日期值 (帮助)](https://docs.getcargo.ai/get-started/project-layout)。 。 。 .

## 常见问题

### @cargo-ai/cdk 是什么？

货物项目——在代码中定义所有货物资源\(连接器、模型、剧作、工具、代理、MCP服务器、文件夹、文件、工人、应用软件、发送域、邮箱\),并公开部署:计划、应用、刷新、进口和销毁

### 如何安装 @cargo-ai/cdk？

在项目目录运行 npm install @cargo-ai/cdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.4\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 cargo-cdk，可以用 npx cargo-cdk 直接运行。

### @cargo-ai/cdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cargo-ai/cdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cargo-ai/cdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cargo-ai/cdk 可以商用吗？

@cargo-ai/cdk 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @cargo-ai/cdk 的下载量有多少？

根据 npm 官方下载统计，@cargo-ai/cdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 101,309 次，日均约 3,377 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cargo-ai/cdk 还在维护吗？

最新版本 1\.0\.140 发布于 2026/11/09（今天）；至今共发布 129 个版本，其中过去 12 个月发布了 129 个；首次发布于 2026/07/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。