# @cef-ai/agent-sdk 中文文档

规范地址：https://npmcn.com/package/%40cef-ai/agent-sdk/

版本：5\.12\.1
npm 元数据更新时间：2026-10-29T07:47:03.951Z
中文译文更新时间：2026-11-09T08:56:21.844Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40cef-ai/agent-sdk
原文对照：https://npmcn.com/package/%40cef-ai/agent-sdk/?lang=original

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

- 包体积（解压后）：983 kB，89 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-04-29T18:21:32.933Z
- 最新版本发布：2026-10-29T07:47:03.732Z
- 近 30 天下载量：3213（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

Cere Element Fabric的作者代理:由装饰和类型组成的小表面,直接映射到运行时间合同.

## 安装

```sh
npm install @cef-ai/agent-sdk
```

也可以使用：`pnpm add @cef-ai/agent-sdk`、`yarn add @cef-ai/agent-sdk`、`bun add @cef-ai/agent-sdk`

## README

# @cef-ai/代理服务器

Cere Enterpress Fabric 的作者代理: 装饰器的小表面 和直接映射到运行时间合同的类型.

## 安装

```sh
pnpm add @cef-ai/agent-sdk
```

为了进行测试,还安装了吊带:

```sh
pnpm add -D @cef-ai/testing
```

## 快速启动

代理是具有装饰方法的默认出口类. `@OnEvent` 将事件类型与处理器绑定; `@OnStart` 财务报告和审定财务报表 `@OnClose` 是生命周期 钩子. `Context` 是单个对象,运行时线程穿过每个 电话.

```ts
import {
  OnClose,
  OnEvent,
  OnStart,
  type Context,
  type Event,
  type OnCloseReason,
} from "@cef-ai/agent-sdk";

interface UserMessage {
  text: string;
}

export default class Echo {
  @OnStart
  async onStart() {
    // Logging + HTTP are plain Web globals, not ctx members:
    console.info("started");
  }

  @OnEvent("user_message")
  async onMessage(event: Event<UserMessage>, ctx: Context) {
    await ctx
      .cubby("history")
      .exec("INSERT INTO messages(text, ts) VALUES (?, ?)", [
        event.payload.text,
        Date.now(),
      ]);
    await ctx.publish("ack", { for: event.eventId });
  }

  @OnClose
  async onClose(_ctx: Context, reason: OnCloseReason) {
    console.info("closing", { reason });
  }
}
```

`ctx` 仅搭载CEF专用平台调用. 对于普通能力, 直接使用沙盒全局 : **`console.*`** 记录(运行时间) 抓住它)和 **`fetch`** 给HTTP的.

与班级对等 `cef.config.ts`数字 :

```ts
import { defineAgent } from "@cef-ai/agent-sdk/config";

export default defineAgent({
  id: "echo",
  version: "1.0.0",
  entry: "./agent.ts",
  cubbies: [{ alias: "history", migrations: "./migrations/history" }],
});
```

## API 摘要

| 仁爱 | 符号 | 页:1 |
| --- | --- | --- |
| 装饰 | `@OnEvent(type)` | 将事件类型(字符串字符表)绑入处理器. |
| 装饰 | `@OnStart` | 标出起用生轮钩. |
| 装饰 | `@OnClose` | 标出近生轮钩. |
| 类型 | `Context` | CEF专用平台只呼叫—— `cubby`, (中文(简体) ), `models`, (中文(简体) ), `publish`, (中文(简体) ), `settings`, (中文(简体) ), `close`. (Log/HTTP是全球数据) `console` 编号 : `fetch`. ) (中文(简体) ) |
| 类型 | `Event<P>` | `{ id, type, ts, from, payload: P }`。 。 。 . |
| 类型 | `CubbyHandle` | `query(sql, params)` 编号 : `exec(sql, params)` 超过异形存储. |
| 类型 | `ModelHandle<I,O>` | `infer(input)` 编号 : `stream(input)` 每个申报的模型别名. |
| 类型 | `OnCloseReason` | `"revoked" | "idle_timeout" | "closed_by_agent" | "failed"`。 。 。 . |
| 接口 | `KnownEventTypes` | 由类型源组成的宣布-相并事件类地图. |
| 函数 | `defineAgent(config)` | 保护字面类型 `AgentConfig`。 。 。 . |
| 类型 | `AgentConfig` | 顶级配置 : `id`, (中文(简体) ), `version`, (中文(简体) ), `entry`, (中文(简体) ), `cubbies`, (中文(简体) ), `models`, (中文(简体) ), `settings`, (中文(简体) ), `fetch`, (中文(简体) ), `publishes`, (中文(简体) ), `lifecycle`。 。 。 . |

## 如何运行(运行时模式)

每个代理运行时间 CDR-001, Cerie网络运行时间是一个 **CEF 不可知论 捆绑执行器**:它只曝光Web平台全球(`fetch`, (中文(简体) ), `console`, (中文(简体) ), `URL`, (中文(简体) ), `crypto`, (中文(简体) ), `TextEncoder`计时器,... )加一个不透明 `globalThis.context` 对象,并发送引用为 `globalThis.__handlers[name](event, context)`。 。 。 .

`ctx` 实值 **仅针对CEF的附加** SDK代码编译为您的捆绑 `cef build`,而不是运行时间约束:

-   `ctx.publish` 编号 : `ctx.cubby` 编号 : `ctx.models[…].infer` 编号 : `ctx.close` → `fetch` 呼叫结束点 管弦乐手在 `globalThis.context` (单位:千美元)`context.endpoints.*`,与 `context.auth` (原始内容存档于2018-10-21). headers.
-   `ctx.settings` → `context.settings`。 。 。 .

普通的网络平台能力是: **没有** 镜像上 `ctx` - 使用 沙盒全局直接 : `console.*` 记录(由 运行时间)和 `fetch` 给HTTP的.

你从来不写Shim密码——你写装饰的课 嘘声 `@cef-ai/agent-sdk/runtime` subpath)自动捆绑.

**推论使用自动报告.** 每个 `ctx.models[…].infer` 调取网关的用法, SDK 折叠 a `_modelCalls` 数组 输入您的处理器返回值; 管弦乐手读来记录 每个型号的代号/GPU使用(ADR-004). `_modelCalls` 是一个保留的结果键—— 不要自己设置.

## 子路径导出

| 指定者 | 目的 |
| --- | --- |
| `@cef-ai/agent-sdk` | 装饰者, `Context`, (中文(简体) ), `Event`, (中文(简体) ), `KnownEventTypes`, (中文(简体) ), `ModelHandle`, (中文(简体) ), `CubbyHandle`, (中文(简体) ), `OnCloseReason`。 。 。 . |
| `@cef-ai/agent-sdk/config` | `defineAgent` 编辑 `AgentConfig` 形状——用于 `cef.config.ts`。 。 。 . |
| `@cef-ai/agent-sdk/runtime` | 内部建设: `ctx` him+ `registerHandlers` 那个 `cef build` 编译为捆绑。 作者从不直接导入 . |

用于测试、使用 `@cef-ai/testing` 直接 - `import { testAgent } from "@cef-ai/testing"`。 。 。 .

## 配套软件包

-   [`@cef-ai/cli`](https://npmcn.com/package/%40cef-ai/cli) —— 说 `cef build` (建设+显示), `cef typegen` (人口数) `KnownEventTypes`, (中文(简体) ), `cef inspect`。 。 。 .
-   [`@cef-ai/testing`](https://npmcn.com/package/%40cef-ai/testing) - 单元和模拟装置 综合测试.
-   [`@cef-ai/eslint-plugin`](https://npmcn.com/package/%40cef-ai/eslint-plugin) ——编辑时间倒影 建造时间检查.

## 参考资料

-   SDK Spec探员: `../../../company-memory-bank/specs/platform/03-components/agent-sdk.md`
-   运行时间整合合同 : `../../../company-memory-bank/specs/platform/03-components/sdk-runtime-integration-contract.md`
-   实施计划: `../../../company-memory-bank/plans/2026-04-27-sdk-implementation-plan.md`

这个 `../company-memory-bank/...` 路径是本地引用一个内部 兄妹重播 无法从新克隆浏览 .

## 常见问题

### @cef-ai/agent-sdk 是什么？

Cere Element Fabric的作者代理:由装饰和类型组成的小表面,直接映射到运行时间合同\.

### 如何安装 @cef-ai/agent-sdk？

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

### @cef-ai/agent-sdk 支持 TypeScript 吗？

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

### @cef-ai/agent-sdk 支持 ESM 还是 CommonJS？

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

### @cef-ai/agent-sdk 可以商用吗？

@cef-ai/agent-sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @cef-ai/agent-sdk 的下载量有多少？

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

### @cef-ai/agent-sdk 还在维护吗？

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