# @godspeedai/cognate-runtime-api 中文文档

规范地址：https://npmcn.com/package/%40godspeedai/cognate-runtime-api/

版本：0\.10\.0
npm 元数据更新时间：2026-11-16T03:51:58.038Z
中文译文更新时间：2026-11-16T18:04:37.556Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40godspeedai/cognate-runtime-api
原文对照：https://npmcn.com/package/%40godspeedai/cognate-runtime-api/?lang=original
项目主页：https://github.com/GodSpeedAI/Cognate#readme
源码仓库：https://github.com/GodSpeedAI/Cognate

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

- 包体积（解压后）：123 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2026-10-09T02:30:58.745Z
- 最新版本发布：2026-11-16T03:51:57.710Z
- 近 30 天下载量：4354（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

独立运行的运输服务合同、代理设计表层以及服务配套包(ADR-0011).

## 安装

```sh
npm install @godspeedai/cognate-runtime-api
```

也可以使用：`pnpm add @godspeedai/cognate-runtime-api`、`yarn add @godspeedai/cognate-runtime-api`、`bun add @godspeedai/cognate-runtime-api`

## README

# @ godspideai/ cognate- runtime- api

Cognate的运输独立运行时间合同: `RuntimeService` 界面(运行、事件、续作、文物、预测、共享状态)、代理作者表面(`AgentDefinition` 编号 : `RunContext`),以及运行时间和客户端都使用的cononical share-state折叠.

**何时使用此软件包 :** 或执行 `RuntimeService`应用程序从 [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) 和一位现成的呼叫者 [`@godspeedai/cognate-client`](https://www.npmjs.com/package/@godspeedai/cognate-client)。 。 。 .

## 安装

```sh
bun add @godspeedai/cognate-runtime-api
```

要求数 [阿宝](https://bun.sh/) >= 1.4.0.

## 授权代理

一种剂是其输入和记录结果的确定性函数:

```ts
import type { AgentDefinition } from "@godspeedai/cognate-runtime-api";

export const refundAgent: AgentDefinition = {
  id: "agent.refund",
  version: "1.0.0",
  async run(input, ctx) {
    const { amount } = input as { amount: number };
    const quote = await ctx.step("quote", () => ({ total: amount * 2 }));
    await ctx.emit("message.delta", { text: `Total: ${quote.total}` });
    const decision = (await ctx.waitFor("approval", {
      type: "refund-approval",
      condition: { kind: "human_approval" },
      payload: quote,
    })) as { approved: boolean };
    return { approved: decision.approved, total: quote.total };
  },
};
```

每个 `RunContext` 方法具有耐用性和回放安全性:结果记录为运行流上的事件,中止或重启后返回记录的结果,而不是重复工作。 因此,鉴于这些结果,代理代码必须是决定性的.

-   `step(id, fn)` ——一次运行一个非决定性单元(一个模型调用,一个API读取)并记录其JSON结果.
-   `emit(eventType, payload)` ——记录了一次完全通过回放的跑入范围的事实.
-   `invoke(capability, input)` 通过政策调用内核能力 `InvocationFailedError` 输入失败.
-   `waitFor(id, spec)` - 暂停,直到永久延续问题得到解决;取消或到期延续失败 `ContinuationClosedError`。 。 。 .
-   `artifact({ name, mediaType, bytes })` ——出产耐用文物;还原其标识.
-   `state(id)` 编号 : `sharedState(id)` 编号 : `updateSharedState(id, update)` ——读取并解剖地更新了跑行和线程共享状态.
-   `recall(id, { text, k })` - 回顾先前授权的知识;返回 `{ status: "degraded" }` 当无法识别时.

## 呼叫服务

每个 `RuntimeService` 操作需要 `Caller` ——运输的认证人身份成立,从未从请求机构读出过任何内容: 1

```ts
import type { Caller } from "@godspeedai/cognate-runtime-api";

const alice: Caller = { actor: { id: "alice", kind: "user" }, tenant: "tenant-a" };

const run = await service.startRun(alice, {
  agent: "agent.refund",
  input: { amount: 21 },
  idempotencyKey: "refund-1",
});
```

失败的是 `ServiceError` 输入 `code`数字 : `not_found`, (中文(简体) ), `permission_denied`, (中文(简体) ), `invalid_argument`, (中文(简体) ), `failed_precondition`, (中文(简体) ), `unavailable`, (中文(简体) ), `deadline_exceeded`, (中文(简体) ), `already_exists`, (中文(简体) ), `unauthenticated`,或 `resource_exhausted`。 。 。 .

## 共享状态

运行状态是它的折叠 `state.changed` 事件按存储位置顺序排列 。 此套件拥有 Canonical 折叠 : `applyStateUpdate` 应用一个更新(完整) `snapshot` 或RFC 6902飞机 `patch`, (中文(简体) ), `foldState` 折叠出一系列事件,运行时间和无头客户端都使用它们——因此每个读者都获得同样的状态. 应用不匹配丢入的补丁 `StatePatchError`;在折叠代理发送事件时,此补丁被跳过而不是隐藏后期更新.

## 前端能力

`invokeFrontend(ctx, id, capability, input)` 将客户端提供的能力转变为持久的延续:运行暂停,直到注册该能力的连接客户端执行并用一个值解决续作. 它能像任何续作一样在断开和重启中幸存下来;在失败时它会抛出 `FrontendCapabilityError`。 。 。 .

## 合规子路径

`@godspeedai/cognate-runtime-api/conformance` 整个服务合同在加工过程中和任何运输过程中均保持不变——同一套货包都证明这一点。 出口 `runtimeServiceConformance` (及其剂/工具固定装置),加现成 `Caller` 身份可以在自己的测试和实例中使用:

```ts
import { alice, mallory, bob } from "@godspeedai/cognate-runtime-api/conformance";
// alice and mallory are users in tenant "tenant-a"; bob is a user in "tenant-b".
```

## 限制

-   只有合同:没有服务器,也没有电线运输。 用Bun runtime这样的执行来对等, 或者把它映射到您所选择的运输上.
-   `RunContext` 是代理代码到达外部世界的唯一支持方式;它记录的任何东西必须作为JSON进行回转.

## 相关软件包

-   [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) - 参考执行 `RuntimeService`。 。 。 .
-   [`@godspeedai/cognate-client`](https://www.npmjs.com/package/@godspeedai/cognate-client) 无头客户端在任何 `RuntimeService`。 。 。 .
-   [`@godspeedai/cognate-events`](https://www.npmjs.com/package/@godspeedai/cognate-events) ——服务被确定为与耐用商店合同相对抗的.
-   [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) ——SDK伞;为运行时间安装一款,客户端,以及本合同.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @godspeedai/cognate-runtime-api 是什么？

独立运行的运输服务合同、代理设计表层以及服务配套包\(ADR-0011\)\.

### 如何安装 @godspeedai/cognate-runtime-api？

在项目目录运行 npm install @godspeedai/cognate-runtime-api，或使用 pnpm add / yarn add / bun add。

### @godspeedai/cognate-runtime-api 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/godspeedai\_\_cognate-runtime-api 是否存在。

### @godspeedai/cognate-runtime-api 支持 ESM 还是 CommonJS？

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

### @godspeedai/cognate-runtime-api 可以商用吗？

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

### @godspeedai/cognate-runtime-api 的下载量有多少？

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

### @godspeedai/cognate-runtime-api 还在维护吗？

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

