# @constal/sdk 中文文档

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

版本：6\.11\.0
npm 元数据更新时间：2026-10-31T08:15:50.110Z
中文译文更新时间：2026-11-10T16:08:00.860Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40constal/sdk
原文对照：https://npmcn.com/package/%40constal/sdk/?lang=original
项目主页：https://constal.ai/

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

- 包体积（解压后）：775 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-25T07:10:22.311Z
- 最新版本发布：2026-10-31T08:15:49.946Z
- 近 30 天下载量：3757（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

用于编写 Constal 代理、集成、政策、渠道和证书提供者的公共类型SDK

## 安装

```sh
npm install @constal/sdk
```

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

## README

# `@constal/sdk`

在Constal上建造的公用TypeScript SDK.

```sh
npm install @constal/sdk
```

软件包有一个支持的导入路径 :

```ts
import { agent, gateway, credentialProvider } from "@constal/sdk";
```

深进口不属于API.

## 公众表面

根导出包含作者所需的合同 :

-   代理、子任务、工具、耐用状态、等待、阶段和分类账视图
-   频道和 Auth 提供者
-   政策和治理方面的制约因素
-   连接软件包通过 `gateway(...)`包括模式、MCP和培训提供者连接
-   认证提供者包通过 `credentialProvider(...)`
-   Evals,分数器,训练食谱,内存操作和沙盒手柄
-   CRN、选择器、资源要求、计划、散列和复原意识错误

收到连接代码 `GatewayContext`编号 :`IntegrationContext`: 已申报的证书、受限的进取、包裹状态、不可改变的文物储存和审计排放。 认证提供者代码通过 `CredentialProviderContext`。 。 。 .

`gateway(...)` 财务报告和审定财务报表 `credentialProvider(...)` 返回验证的、适合有管理的部署的软件包。 用户执行包合同;Constal提供其执行环境.

## 示例连接

```ts
import { gateway } from "@constal/sdk";

export default gateway({
  id: "ticket-connection",
  version: "1.0.0",
  kind: "service",
  displayName: "Ticket connection",
  description: "Read tickets from the configured account.",
  credentialSlots: { account: { title: "Account Credential" } },
  capabilities: [{
    id: "example.ticket-read",
    version: "1",
    hash: "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  }],
  billing: { upstreamPayer: "tenant" },
  configSchema: { type: "object", additionalProperties: false },
  egress: { rules: [{
    operations: ["ticket.get"],
    origin: "https://api.example.com",
    pathPrefix: "/tickets/",
    methods: ["GET"],
  }] },
  catalog: () => [{
    op: "ticket.get",
    description: "Read one ticket.",
    schema: { type: "object" },
    resultSchema: { type: "object" },
    effect: "read-only",
    recovery: { kind: "repeat" },
    async: false,
    usage: { meter: "none", priceTable: null },
  }],
  async invoke(request, context) {
    const credential = await context.secret("account");
    return context.egress({
      url: `https://api.example.com/tickets/${encodeURIComponent(String((request.args as { id: string }).id))}`,
      method: "GET",
      headers: { authorization: `Bearer ${credential.value}` },
      maximumResponseBytes: 1_048_576,
      maximumRedirects: 0,
    });
  },
});
```

## 资源合同

```ts
const bindings = Object.keys(ctx.resources);
const model = await ctx.describeResource("model");
const operations = (await ctx.describeResource("api"))?.operations;
```

访问者记录对一个被接受的资源绑定的局部步骤的观察. 它不需要资源或提供者查询。 重放该位置返回 同样的观察;以后的呼叫可以观察到安全点绑定的更新.

成果包括公共运营合同、证书档名和广告 标注模型的元数据。 他们省略了证书参考/材料,私人 配置 控制飞机操作 返回对象是独立的 副本。 配置的操作不是授权的保证: 政策仍然 被援引时适用.

对于模型选择的操作,添加可选 `resourceTools` 给探员的 普通工具目录 :

```ts
import { resourceTools } from "@constal/sdk";

export const tools = { ...resourceTools };
```

`resource_list` 返回已接受的绑定名称和 CNN,而不装入每张 目录. `resource_describe` 带 `{ binding }` 返回资源 公共运营. `resource_invoke` 接受描述的操作及其 参数 :

```ts
await resourceTools.resource_invoke.run({
  binding: "tickets",
  operation: "tool.find",
  arguments: { query: "Open support requests" },
}, ctx);
```

这些工具使用正常的引用、授权和同步处理 合同。 结果和错误得到保留。 他们不安装软件包, 创建资源、 更改约束、 获取证书本身或重试 操作失败 。 使用 Constal API 资源进行安装并重新组合; 被接受的再组合收件不能证明当前框架有新接头.

## 技能

一个技能资源是一个代理技能库,通过部署一个 保存的归档 `constal.skills.json`。 。 。 . `skills(binding, sandbox)` 返回时 3个工具在库里 代理绑定为 `binding` (默认) `skills`, (中文(简体) ), 从绑定中取出 `.` 财务报告和审定财务报表 `-` 作为 `_`数字 :

```ts
import { agent, skills } from "@constal/sdk";

const library = skills("skills", "sandbox");

export default agent({
  id: "maintainer", version: "1.0.0", model: "model",
  tools: library,
  async onMessage(request, ctx) {
    return ctx.turn({ system: "You maintain the project's software.", context: { request }, tools: Object.keys(library) });
  },
});
```

`skills_find` 财务报告和审定财务报表 `skills_read` 是图书馆的 `find` 财务报告和审定财务报表 `read` 操作; 他们的策略和描述来自部署时的目录. `skills_run` 捆绑技能,每捆复制一次文件夹 沙盒池的工作空间 `sandbox` (默认) `sandbox`页:1 `/workspace/skills/<ref>`,然后运行一个命令;它回答文件夹的 路径和命令的结果。 它需要图书馆的 `bundle` 和游泳池的吗 `exec` 财务报告和审定财务报表 `putFile`在游泳池自己的政策下 打电话 `skills()` 单次 绑定的图书馆 .

## 编辑地址和交付

一个分类账地址名 一个会话的主要分类账, `agent:<agent>/session:<session>`或者一个产出回路的, `agent:<agent>/session:<session>/spawn:<handle>`在Run的房客内部, 名称空间,和客户. `ctx.run.ledger` 是当前运行的自己的地址( 否) 对于操作分支, eval分叉, 补偿, 或循环其中之一 并运行一个现有会议,其编号为 `/` 或控制器 字符或超过 256 个字符, 入侵者不再接受 一个新的,和处理 `ctx.spawn` 返回其循环中的名称 `ledger`,同样跨过产卵 重试. 运行省略 `of` 财务报告和审定财务报表 `to` 用于自己的分类账; `session:<id>` 实值 拒绝.

```ts
const notes = await ctx.ledger.view("notes", { of: "agent:memory/session:team" });
await ctx.commit({ text: "Fix the failing build", data: { issue: 7 } },
  { to: "agent:task/session:fix-7", deliver: "live", delegate: true });
const investigation = ctx.spawn(investigate, { issue: 7 });
await ctx.commit("Also check the flaky test", { to: investigation.ledger, deliver: "live" });
const woken = ctx.await("next", { afterRun: "delivery", timeout: 3_600_000 });
```

`ctx.ledger.view` 读另一个分类账在它的头上. `ctx.commit` 与 `to` 实值 代理代码交付到另一个分类账的一种方式: `deliver: "queue"`,则 默认, 队列项目; `"live"` 引导地址运行或启动 。 A 类 活项是非空字符串或 `{ text, data? }`和送去产卵 现场直播. `delegate: true` 使这个会话成为接收会话的主人, 它只夺走了它的主人 在它的第一个运行之前。 出席会议的代表团 live Run的取消正在等待它的驱动程序在 Run 后面等待,然后开始下一个 一;任何其他活生生的快递都引导着跑. 平台随后交付给 主人,作为一个 `RunReport`,该会话根运行的每端(`complete` 及其结果, `failed`, (中文(简体) ), `stopped`但一站店主的分类账 以物抵偿,或以物抵偿`held`)),每个都拒绝了 或放弃活动不是来自主人会的开始 (单位:千美元)`refused`) (中文(简体) ). 送达时拒绝交货 向发送者报告其届会,或永久失效 `RunReport` 有状态 `refused`。 。 。 . `ctx.await(label, { afterRun: "delivery" })` 当送货者引导等待者运行并解决 `{ seq, eventId }` 被唤醒的方向盘 交付本身留在分类账里 运行一个 发送或报告开始属于发送者的端到端运行,如同 运行开始通过 Constal API 从一个运行: 性能读取一个频道的, 一个时刻表或API的呼叫"跑" 和每一个运行它引导在一起.

政策决定对另一届会议的看法`ledger:read`; 页光标 然后读取无需进一步核对),并送交另一届届会 实施(`agent:invoke` 在接收代理人, `session:steer` 当生活, `run:cancel` 在授权时。 拒绝的视图或 递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递递件 在同一位置出错: 政策拒绝为 `PolicyDecisionFailed` 联合国 `decisionHash`,以及任何其他拒绝 `Error` 与平台的信息和 `status`。 。 。 .

## 届会时间表

安排今后援引现任代理人和届会:

```ts
await ctx.schedule("check-pr-42", {
  after: "10m",
  input: { kind: "check-pr", repository: "acme/api", pullRequest: 42 },
});
```

当前的运行可以完成 。 会议保留时间表,并交付 到期时对新运行的输入不变 。 使用 `every: "15m"` 用于固定凸起,或 `every: "day", at: "09:00", timezone: "America/Los_Angeles"` 每日检查. 经常性时间表默认保存错失的事件; 明确要求 `missed: "coalesce"` 当一次检查应涵盖累积的积压.

`ctx.listSchedules()` 页面显示自有会话的日程; 调用 `schedule()` 以同一名称取代今后的工作. `ctx.cancelSchedule(name)` 停下来 未来工作,确定已接受或未解决的交货。 使用 `ctx.await()` 因为睡在目前的运行.

见 [调度代理跟踪](https://constal.ai/docs/agents/schedules) 重复播放, 发送、授权和取消语义.

## 示范评价

`ctx.evaluate` 通过评估对打出的问题进行评分 模式,例如: `typesafe-ai/jev`。每个问题都单独回答 受限的价值和概率,从未产生出传言, 呼唤是 日记和定价 就像一个模型调用 不消耗转弯.

```ts
import { agent, noulDecision } from "@constal/sdk";

export default agent({
  id: "triage", version: "1.0.0", model: "model",
  async onMessage(ticket, ctx) {
    const { answers } = await ctx.evaluate({
      model: "judge",
      state: { ticket },
      questions: {
        team: { type: "choice", instructions: "Which team owns `ticket`?",
          criteria: { billing: "Charges, invoices, refunds", technical: { what: "Bugs and outages", not_for: "Charges" } } },
        severity: { type: "score", instructions: "How severe is the problem in `ticket`?",
          criteria: ["Cosmetic", "Degraded", "Customer is blocked"] },
        urgent: { type: "noul", instructions: "Does `ticket` convey urgency?" },
      },
    });
    if (answers.team.confidence < 0.5) return { route: "human" };
    return { route: answers.team.choice, severity: answers.severity.score, urgent: noulDecision(answers.urgent, 0.7) };
  },
});
```

与其他评价模式一样将评价模式捆绑起来(`"judge": "crn:...:model/jev"`),或 通过 `gateway` 明确 `model` 标识符. `instructions`选择选项 说明,分数级,和努尔标准都接受JSON结构. 选择 答案保留其标准的字面选项键,分数答案带有一个 `legend`,而诺尔答案是一种概率.

见 [用模型评估状态](https://constal.ai/docs/agents/evaluate) 用于完整包单、答案形状和核查步骤.

## 常见问题

### @constal/sdk 是什么？

用于编写 Constal 代理、集成、政策、渠道和证书提供者的公共类型SDK

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

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

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

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

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

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

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

@constal/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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