# @cantelop/sdk 中文文档

规范地址：https://npmcn.com/package/%40cantelop/sdk/

版本：1\.7\.0
npm 元数据更新时间：2026-10-23T21:44:34.710Z
中文译文更新时间：2026-11-09T12:32:32.722Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cantelop/sdk
原文对照：https://npmcn.com/package/%40cantelop/sdk/?lang=original
项目主页：https://github.com/stepandel/cantelop-sdk#readme
源码仓库：https://github.com/stepandel/cantelop-sdk

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

- 包体积（解压后）：25.7 MB，281 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：5 个
- 首次发布：2026-08-13T17:19:19.957Z
- 最新版本发布：2026-10-23T21:44:34.200Z
- 近 30 天下载量：2703（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 60 个）

## 中文简介

Cantelop 应用程序的后端集成和会话运行时间 SDK

## 安装

```sh
npm install @cantelop/sdk
```

也可以使用：`pnpm add @cantelop/sdk`、`yarn add @cantelop/sdk`、`bun add @cantelop/sdk`

## README

# 罐头 SDK

Cantelop 运行代理 用于您的应用 在孤立的 Sandboxs 中 具有持久工作空间 . `@cantelop/sdk` 您的后端如何和它们交谈, 您如何定义每个会话内部的运行 。 它包括了被包装的克洛德代码(Claude Code)吊带,所以一个工作代理App是一个简短的定义文件.

-   **应用 :** a 已部署的代理,带有名称、会话运行时间及其配置.
-   **工作空间 :** 耐用文件和数据库,一般每个客户或用户一个. 每个工作区的会议都分享.
-   **会话 :** 一个谈话或任务。 它的 Sandbox 被闲置并被下个消息所重新启动时会被放出;会话身份仍然可以重新使用.

您定义会话运行时间 。 SDK生成App的边缘API,Cantelop同时部署. 应用软件的使用 [项目计划 3](https://npmcn.com/package/%40cantelop/sdk/schemas/app-v3.json)。 。 。 .

对于一个本地编辑 远程特工执行, [`workspace.sync()`](https://npmcn.com/package/%40cantelop/sdk/docs/workspace-sync.md) 将本地目录与工作空间对齐 `project/` 文件夹。 SDK包括它的本土文件系统适配器;消费者应用程序不需要Cantelop CLI或Go. Hosted write 仍然被封口等待存储资格.

## 开始吧

你需要的就是: 爱丽丝

-   22号节点或更新
-   Cantelop CLI 0.15.2或更新型: `brew install stepandel/tap/cantelop` (与 `cantelop version`(中文(简体) )
-   嵌入器为 `linux/amd64` 建立支持
-   Claude 订阅( Pro 或 Max) 在
-   部署时的 Cantelop 账户

### 1\. 界定应用程序

在空目录中 :

```sh
npm init -y
npm pkg set type=module
npm install @cantelop/sdk
```

添加 `cantelop.json`,将 CLI 指向您的 App 定义:

```json
{ "schema_version": 3, "definition": "src/cantelop.ts" }
```

添加 `src/cantelop.ts`数字 :

```ts
import { CantelopClient } from "@cantelop/sdk";
import {
  createClaudeRuntime, claudeAuth, claudeDockerfile,
  type ClaudeSessionCommand, type ClaudeSessionEvent,
  type ClaudeSessionReply, type ClaudeSessionView,
} from "@cantelop/sdk/harnesses/claude";

const cantelop = new CantelopClient();

export const agent = cantelop.app<ClaudeSessionCommand, ClaudeSessionEvent, ClaudeSessionReply, ClaudeSessionView>({
  name: "hello",
  runtime: createClaudeRuntime(),
  auth: claudeAuth,
  dockerfile: claudeDockerfile,
});
```

这是整个App. `createClaudeRuntime` 运行股票 Claude Code CLI,为正在进行的工作提供新的投入,并保持持久的对话观点。 当闲置时,如果检查点可用,新输入会恢复已保存的本地对话. `claudeAuth` 让每个工作空间用用户自己的克洛德订阅签名. `claudeDockerfile` 是安装了 CLI 的 SDK 维护的 Sandbox 图像 . `name` 是App的部署弹.

### 2\. 在当地运行

```sh
cantelop dev --container
```

此构建 Sandbox 图像, 为 App 服务 `http://127.0.0.1:8787`并记录了SDK的证书 `local` 简介。 Claude的CLI和它的登录助手 都生活在这个形象中 所以请使用 `--container`编辑后重新启动 `src/cantelop.ts`。 。 。 .

在第二个终端中,编译后端客户端. 它保留了App的出口和类型,但是没有它的Sandbox代码,因此后端可以导入它:

```sh
node --input-type=module -e 'import { buildBackendClient } from "@cantelop/sdk/build"; await buildBackendClient({ definition: "src/cantelop.ts", outdir: ".cantelop/client" })'
```

`cantelop build` 财务报告和审定财务报表 `cantelop deploy` 也写这个客户端. 修改 App 定义时重建它 .

### 3\. 签署和发出迅速通知

保存此后端脚本为 `try.mjs`数字 :

```js
import { createInterface } from "node:readline/promises";
import { agent } from "./.cantelop/client/client.mjs";
import { applyClaudeSessionChange } from "@cantelop/sdk/harnesses/claude/protocol";

const workspace = agent.workspace({ slug: "ada" });

// Sign the Workspace in to Claude once. The credentials stay in the Workspace.
const auth = workspace.auth();
const login = await auth.login();
if (!login.authenticated) {
  console.log(`Sign in to Claude: ${login.url}`);
  const terminal = createInterface({ input: process.stdin, output: process.stdout });
  const code = await terminal.question("Paste the code: ");
  terminal.close();
  if (!await auth.submitCode({ attemptId: login.attemptId, code })) throw new Error("Sign-in failed");
}

const session = workspace.session();
const id = crypto.randomUUID();
const reply = await session.request({ type: "input", id, text: "Summarize the files in this directory" });
if (reply.type === "error") throw new Error(reply.code);

const snapshot = await session.view();
let state = snapshot.state;
console.log(state);
const finished = () => state.inputs.some(input => input.id === id &&
  ["completed", "failed", "cancelled", "interrupted"].includes(input.status));
if (!finished()) for await (const event of session.stream({ after: snapshot.cursor })) {
  if (event.data.type !== "session.changed") continue;
  state = applyClaudeSessionChange(state, event.data);
  console.log(state);
  if (finished()) break;
}
```

```sh
CANTELOP_PROFILE=local node try.mjs
```

第一个运行打印 克劳德签入链接。 打开,签入,并粘贴页面显示的代码. 之后运行重用工作空间的证书. 在第一个提示前签入一个工作空间:没有证书,控制带不能运行克洛德,而早前发送的提示失败而不输出.

`dispatch()` 返回信件被永久承认时,而不是代理完成时. `stream()` 中继代理的事件.

### 4\. 部署

```sh
cantelop login
cantelop deploy --create-app
cantelop app credentials --app hello   # backend configuration, in dotenv form
```

`deploy` 构建和上传 App 并刷新 `.cantelop/client/`。将打印的证书存储在您的后端的秘密仓库中;参见 [应用程序配置](https://npmcn.com/package/%40cantelop/sdk/docs/app-configuration.md)。然后,每个用户的工作空间一次通过同一程序签名 `login()` 财务报告和审定财务报表 `submitCode()` 电话,从你的后端.

运行时逻辑或类型的任何更改都会给 App 新的运行时身份, 所以每次部署 App 时都会重建并重新部署您的后端; 查看 [在 App 中部署后端](https://npmcn.com/package/%40cantelop/sdk/docs/runtime-definitions.md#deploy-the-backend-with-the-app)。 。 。 .

## 从后端使用 App

```ts
import { agent } from "./.cantelop/client/client.mjs";

const workspace = agent.workspace({ slug: "customer-123" });
// Or: agent.workspace({ id: canonicalWorkspaceId });
const session = workspace.session({ id: "conversation-456" });

const message = await session.dispatch({ type: "input", id: "issue-123", text: "Investigate this issue" });
const status = await message.status();
```

后端导入已编译客户端,或将 App 定义与 Cantelop 编译器插件捆绑,该插件会去除 Sandbox 唯一的依赖性 。 导入 `src/cantelop.ts` 未变形的加载了吊带及其依赖性. 见 [运行时间汇编](https://npmcn.com/package/%40cantelop/sdk/docs/runtime-definitions.md)。 。 。 .

`CantelopClient` 供应共享连接上下文,可选择选择配置文件。 每个 `cantelop.app({ name, runtime })` 宣告一个名为 App 的自打运行时间和工作空间命名空间 。 一个客户端可以定义多个App. App名称为部署 satters,独立于JavaScript导出名称. 连接和范围化的证书自动解决每个 App;构建这些对象不会提供资源. 见 [应用程序配置](https://npmcn.com/package/%40cantelop/sdk/docs/app-configuration.md)。 。 。 .

交通情况如下 `backend → SDK → protocol-managed App Edge Worker → outbound Worker/broker → Session runtime`。所有 App 操作都使用该版本 `{ protocolVersion, id, workspace, session, command }` 信封,每个在自己的 `POST /commands/{type}` 路径( r)`/commands/dispatch`, (中文(简体) ), `/commands/view`),所以请求日志和Cantelop控制台显示SDK调用每个请求是哪个. Edge QQ Sandbox是独立版本的演员协议. 见 [命令和持久视图合同](https://npmcn.com/package/%40cantelop/sdk/docs/integration-foundation.md)。 。 。 .

工作空间和会话参考文献都很懒. 选择会话 ID 立即生成会话 . `dispatch()` 懒散地解决/ 提供工作空间弹片, 并在需要时激活 Sandbox 。 警犬工作室的ID从不提供替代。 清晰的分辨率和数据库访问权限共享工作空间参考的缓存元数据。 会话ID是App-scope,即使引用被嵌入到工作空间下.

接受意味着持久的信息接纳,而不是代理完成. 声明回复类型的运行时间,例如 `createClaudeRuntime` 或自定义控制器,也支持 `session.request(message, { timeoutMs })`等待一个JSON的答复。 超时或断开结束等待, 不证明执行已停止 。 失败的请求会通过 : `RemoteAppError`; 重用该ID进行模棱两可的重试。 SDK 不自动重放写入 .

## 引导、 取消和停止

```ts
await session.steer({ type: "steer", id: "focus-auth", text: "Focus on the authentication module" });
await session.cancel(); // { state: "requested" | "idle" }
await session.stop();   // release the Sandbox; the Session identity stays reusable
```

发送并引导接受相同的消息类型并返回一个ID/状态引用 。 都接受可选 `{ id, keepAliveSeconds, signal }`从方法选项返回到会话引用到配置的 App 默认值。 耐用克洛德运行时间在闲暇时开始输入,在繁忙时指导进行中的工作. 工厂的运行时间 代表发送到绳子 `queue` 方法与方向 `steer` 方法;这些工具确定了自己的投入政策.

`session.cancel({ id?, signal? })` 没有目标消息ID。 它表示积极管理的活动 或代表工厂的吊带 `cancel()` 方法. `requested` 承认中断, 清理未完成; 在清理结算前, 执行仍然为所有 。 闲置时取消不影响后期输入. 重试同一平台命令ID重用其结果,不能中断后续运行.

提交ID服务于收据、重试和输出相关性。 信件状态描述接收, 这样活动的工作可以超过其信件的 `handled` 状态.

`stop()` 释放当前 Sandbox 并关闭流, 可能打断工作 。 下一个消息在新的 Sandbox 上激活相同的会话 。 工作空间保存耐用的文件和数据库;会话内存,调用内存和临时文件属于一个Sandbox化身. 多会话可能共享一个工作空间,因此应用程序拥有共享状态的协调.

## 流出

```ts
for await (const event of session.stream({ signal })) {
  console.log(event.data, event.cursor, event.messageId);
}
```

`stream()` 是一个对会话 SSE 输出的同步执行器。 元数据包括光标 `{ streamId, sequence }`,会话ID,信件ID,和创建时间. 明确恢复 `session.stream({ after: savedCursor })`。重放被绑定;光标过期后流重置时保留其远程错误代码。 SDK不自动重接.

中断迭代或中止订阅只会关闭其流. 它不会取消代理工作或者让沙盒保持温暖. 浏览器-快取路由仍然是应用程序自身授权后端的一部分.

克洛德的电源 克洛德代码的原生 `stream-json` 对象。 超过48个基 B 的框架以 `native.fragment` 事件; 合并它们 `json` 内 `index` 命令并分析结果.

## 在工作空间中签名

声明 `auth` 让每个工作空间在用户自己订阅的股票CLI上签名. 土著证书留在工作区,所以每个会议都分享这些证书。 仅在属于单一已验证用户的工作空间上使用认证,并从该用户的身份中获取选择器.

`app.workspace(selector).auth()` 暴露了登录方法. 供货商 `codeLogin` 适配器,例如 `claudeAuth`, (中文(简体) ), `login()` 返回时 `{authenticated:true}` 或者说 `{authenticated:false,attemptId,url,expiresAt}`。 。 。 . `submitCode({attemptId,code})` 返回本地认证状态或稳定状态 `code_rejected` 错误,以及 `cancelLogin({attemptId})` 停止尝试. `login({force:true})` 在开始新登录前确认本地登录 。 SDK拥有尝试,即时解析,限定私人输出,到期和流程清理. 应用程序授权和账户偏好保留在您的后端 .

低级 `terminal()`编号 :`close()` 服务于有意暴露CLI自身终端的集成. 主机Cantelop尚未将终端转发给浏览器. 见 [本地认证](https://npmcn.com/package/%40cantelop/sdk/docs/native-auth.md)。 。 。 .

## 配置 Claude 带

为每个会话通过选择模型、工具、快取和限制的选项:

```ts
export const agent = cantelop.app<ClaudeMessage, ClaudeEvent>({
  name: "hello",
  runtime: {
    create: (context) => createClaudeHarness(context, {
      model: "sonnet",
      permissionMode: "dontAsk",
      allowedTools: ["Read", "Grep", "Glob"],
      systemPrompt: "Investigate issues and report your findings.",
      maxTurns: 24,
    }),
  },
  auth: claudeAuth,
  dockerfile: claudeDockerfile,
});
```

选项也涵盖 `tools`, (中文(简体) ), `settingSources`, (中文(简体) ), `mcps` (单位:千美元) `conversation` 种子 。 当工厂运行时,它们会被快照;SDK上下文提供犬科会话的特性. 没有选项, 吊带保持 CLI 的本土配置, 带有 `CLAUDE_MODEL` 财务报告和审定财务报表 `CLAUDE_PATH` 从App宣布的环境读取.

`createClaudeRuntime(options)` 提供本土流入和持久观测. `{type:"input",id,text}` 在闲暇时启动跑步,在繁忙时引导同样的跑道; `{type:"steer",...}` 有着同样的本土行为。 在出版之前,一直坚持接受投入、尝试提供、本土观察和结果. `session.view()` 返回已承诺的投影; `applyClaudeSessionChange` 后续应用 `session.changed` 事件是一流的。 没有后续队列 。 设置可以在运行之间更改;运行返回时不兼容的更改 `active_settings_conflict`。其协议类型为 `@cantelop/sdk/harnesses/claude/protocol`编辑 [Claude 代码示例](https://npmcn.com/package/%40cantelop/sdk/examples/anthropic/README.md) 包括两个,加上自定义图像和 `NativeClaude` 用于定制建筑.

## 其他运行时间

库存CLI 用于 [代码](https://npmcn.com/package/%40cantelop/sdk/examples/codex/README.md) 财务报告和审定财务报表 [打开代码](https://npmcn.com/package/%40cantelop/sdk/examples/opencode/README.md) 采用与克洛德机具相同的模式,作为例子而不是包装出口. [Pi](https://npmcn.com/package/%40cantelop/sdk/examples/pi/README.md) 财务报告和审定财务报表 [OpenAI 代理服务器](https://npmcn.com/package/%40cantelop/sdk/examples/openai/README.md) 显示框架集成.

要写你自己的,还一把从 `runtime.create`数字 :

```ts
// src/agent.ts — the harness factory compiled into the Sandbox.
import type { SessionHarness, SessionHarnessContext } from "@cantelop/sdk/session";
import type { Message, Event, Reply } from "./contracts.js";
import { createHarness } from "./harness.js";

export function create(context: SessionHarnessContext): SessionHarness<Message, Event, Reply> {
  return createHarness(context); // Implements queue(message, work), steer(message, work), cancel().
}
```

工厂运行一次每会场运行时间化身,在第一个牵引指令或恢复上. 它返回一个执行工具 `queue(message, work)`, (中文(简体) ), `steer(message, work)`,以及 `cancel()`。每个执行系统拥有命令、引导行为、中断和清理。 SDK直接调用这些方法,并让摄入量在承诺仍未兑现时作出反应. `queue` 在所提交的作业及其清理之后解决;其返回价值用品 `session.request()` 答复. `steer` 解决执行的完成边界:可以立即接受本地输入,而中断和重续执行则可以等转向.

工作收到信号,打出输出/视图,提交身份和会话资源. SDK在不选择提供者调度行为的情况下跟踪操作寿命,归属和最后期限. `cancel()` 返回当前操作是否被标记,并保存等待输入。 编译器将工厂及其附属物捆绑入"沙盒",同时将它们排除在后端和"边缘"的文物外.

自定义运行时间可以使用 `runtime: { receive, onActivate?, onRecover?, redelivery? }`。其摄入量按序列排列;将长期工作移入 `context.activity` 与 `activity.start`, (中文(简体) ), `queue`, (中文(简体) ), `steer`,以及 `cancel`,并通过活动选项登记提供者方法 `onSteer` 财务报告和审定财务报表 `onCancel`。 。 。 .

申请拥有持久工作、检查站和公正无私。 可选 `onActivate` 钩子每个化身恢复一次状态;可选 `onRecover` 钩选入替换-桑德克回收. 重新交付是用于调试摄入处理器的选择。 成功 `receive` (a) 承认申请的录取; 长期状态 `/workspace` 或工作空间数据库。 输出/复制机保持其JSON和尺寸限制.

不需要自定义图像的运行时间可以本地运行 `--container`平话 `cantelop dev` 用 Bun 1.3.10 以本地方式运行会话,并在编辑时重建.

## 持久会议意见

SDK通过平台的持久取景服务承担预测. 读取最后一个承诺的视图不会激活 Sandbox .

运行时间明确承诺应用程序的读取模式:

```ts
async function receive(context: SessionContext<Message, Event, Reply, State>) {
  const state = await updateApplicationState(context.message.payload);
  await context.view.commit(state);
  context.reply(state);
}
```

`view.commit` 在平台存储投影及其原子事件边界后解决。 客户端代码拥有应用程序状态和恢复;执行视图不会取代应用程序的数据库或重放其运行时间关闭.

```ts
const snapshot = await session.view();
render(snapshot.state);
for await (const event of session.stream({ after: snapshot.cursor })) {
  apply(event.data);
}
```

监督活动也可以称为自己的 `view.commit(state)` 活动时的能力。 这种能力遵循活动信号,并在活动结束时关闭.

读取的视图从不打开工作空间或激活 Sandbox 。 缺少预测返回 `session_view_not_found`。视图幸存的停止和主机重新启动;流恢复取决于该平台的限定回放保留。 投影承诺推进流光标而不作为应用事件出现 .

## 实例

-   [克劳德代码](https://npmcn.com/package/%40cantelop/sdk/examples/anthropic/README.md): 包装的带子、链接/编码签入和耐用 `createClaudeRuntime` 生命周期.
-   [网络聊天](https://npmcn.com/package/%40cantelop/sdk/examples/web-chat/README.md): 浏览器 – 应用程序后端 – `CantelopClient` 一体化.
-   [GitHub 发行代理](https://npmcn.com/package/%40cantelop/sdk/examples/github/README.md): a App webhook,通过同一个App接口验证签名的送出和发送.
-   [多笔](https://npmcn.com/package/%40cantelop/sdk/examples/multi-app/README.md):两个App在一个客户端下.
-   [所有实例](https://npmcn.com/package/%40cantelop/sdk/examples/README.md),包括Codex,OpenCode,Pi和OpenAI代理.

[工作空间数据库](https://npmcn.com/package/%40cantelop/sdk/docs/workspace-databases.md) 包括续约、交易和计划迁移.

## 开发 SDK

```sh
pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm test:native
pnpm check:examples
pnpm check:package
pnpm test:bun
```

包资资格检查实际npm的柏油球及其被包装的文件,生成了Edge和原生跑道建造的文物,以及清洁的消费者的融合类型. 出版是一个单独的操作;参见 [发布指导](https://npmcn.com/package/%40cantelop/sdk/docs/releasing.md)。 。 。 .

定义共享应用程序 `cantelop.fleet({...})` 并通过 `fleet.instance(...)`。见 [车队和实例](https://npmcn.com/package/%40cantelop/sdk/docs/fleets.md) 使用寿命周期、打入App接入和CLI整合合同.

## 常见问题

### @cantelop/sdk 是什么？

Cantelop 应用程序的后端集成和会话运行时间 SDK

### 如何安装 @cantelop/sdk？

在项目目录运行 npm install @cantelop/sdk，或使用 pnpm add / yarn add / bun add。

### @cantelop/sdk 支持 TypeScript 吗？

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

### @cantelop/sdk 支持 ESM 还是 CommonJS？

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

### @cantelop/sdk 需要什么版本的 Node\.js？

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

### @cantelop/sdk 可以商用吗？

@cantelop/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cantelop/sdk 的下载量有多少？

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

### @cantelop/sdk 还在维护吗？

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