@cargo-ai/cdk-货物项目
在代码中定义整个货运工作空间——连接器,模型,游戏,工具, 代理, MCP 服务器, 上下文, 片段, 容量, 领地, 文件夹, 文件, 工人, 应用程序, 发送域和邮箱—— 并部署 宣示性地,同样的方式,你管理云 基础设施与普鲁米或 AWS CDK (英语). A 类 项目 是声明它的文件夹。 对于一个完整的概述, 见 项目文件。 。 。 .
所需资源
- 节点.js 22.x
- 货物 API 令牌( 在您的工作空间中创建 ) 设置 – API(中文(简体) )
安装
@cargo-ai/cdk 是货物项目背后的库: define* 建设你
导入您的资源文件,以及部署它们的引擎。 开车吧
货物CLI:
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
节点软件包 :
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 每一个.
快开始
脚手架项目:
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:
上下文、下下文和表层,a cargo.json 在根部,和 页:1
资源文件在 infra/从项目内任何地方运行命令——
他们发现 cargo.json 装入 infra/ 从它.
或者自己添加资源文件——导入文件 实值 注册,有 没有表明:
// 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",
});
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 配置被输入到您的工作空间
实际的融合计划。 一次生成类型 :
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 忽略 :
// 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 }。 。 。 .
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 选项。 因此可以使用构建时控件
赤线 在身体内部——没有锅炉板:
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 选项.
见 定义资源 每笔 构建器(连接器、模型、游戏、工具、代理、MCP服务器、上下文、部件、, 能力、领土、文件夹、文件、工人、应用软件、域)和弹道规则.
原生对象和统一型号kind: "native")和背景
仓库(defineContext拥有自己的指南:
对象模型, (中文(简体) ),
统一,以及
A. 背景情况。 。 。 .
图标
在脚手架项目中,日常命令是 npm run 脚本 :
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数字 :
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 (窃取所司州锁. 见
部署。 。 。 .
烹饪手册
Cookbook是工程项目实例——TAM管线,账号评分,CRM
浓缩——作为文件夹发表于
getcargohq/gtm-skills。 。 。 . add
安装一个 进入您已有的项目,作为一个兄弟 什么在那里:
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>/数字 :
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最后一个问题是是否打开它
新项目 :
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)
一个项目 部署状态 是从您的代码到资源 创建。 它住在你的工作空间里 反弹会指向它:
{ "stateUuid": "8f2c…" }
init 创建国家并写道: cargo.state.json,所以指针在
脚手架上的人. 交出来 没有uuid 新的退票
找到它的状态,部署不会悄悄地进行替换(这将
孤儿的一切 旧的轨道。 州里记录的只有 uids, hashes 和
产出——绝不是秘密价值.
每个项目一个州,每个工作区最多10个活州:
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:
.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 重新应用您的
代码在他们身上。 见 状态和漂流。 。 。 .
文档
完整文档: {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}请检查date=中的日期值 (帮助)。 。 。 .