# @cef-ai/cli 中文文档

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

版本：4\.2\.0
npm 元数据更新时间：2026-10-29T18:41:52.187Z
中文译文更新时间：2026-11-09T07:35:08.788Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：1.2 MB，205 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- 首次发布：2026-04-08T09:05:43.854Z
- 最新版本发布：2026-10-29T18:41:51.861Z
- 近 30 天下载量：3918（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 60 个）

## 中文简介

`cef` ——建设,打字,检查指挥线的特务. 镜像代理Runtime合同(ADR-001):捆绑安装平面处理器地图 `globalThis.__handlers`,列表中标有管弦乐手读取的路由表.

## 安装

```sh
npm install @cef-ai/cli
```

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

## README

# @cef-ai/ cli (英语)

`cef` ——建设,打字,检查指挥线的特务. 镜像 agent Runtime合同(ADR-001):捆绑安装平面处理器地图于 `globalThis.__handlers`,列表中标注了管弦乐手的路由表 读取.

## 安装

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

这增加了 `cef` 二进制为 `node_modules/.bin`在一个工作空间项目中, 通过它引用 `pnpm exec cef <subcommand>`。 。 。 .

## 子命令

| 子命令 | 状态 | 说明 |
| --- | --- | --- |
| `cef init [dir]` | 已运出 | 脚手架,一个Hello-world代理项目(代理+cubby+部件+测试),取决于发布内容 `@cef-ai/*` 软件包。 与 `--yes`/flags; 撰写方便AI的文件, 自动连接 `cef` Claude 代码插件 (`--no-ai` 跳过). |
| `cef deploy` | 已运出 | 让代理人活下来: 应用 repo 的 `deployments/` 文件夹(或单个集文件)到平台. `--endpoint <url>` (或 `$CEF_ENDPOINT`; 默认为 dev , `--deployments <file|dir>`, (中文(简体) ), `--version`, (中文(简体) ), `--as-pubkey`, (中文(简体) ), `--dry-run`. 要求部署记录+可到达端点. |
| `cef build` | 已运出 | 打开代理条目, 装入 Esbuild (捆绑导入 SDK 运行时间 shims并安装) `globalThis.__handlers`),发射 `dist/<agentId>/{bundle.js,manifest.json}`。 。 。 . |
| `cef typegen` | 已运出 | 生成 `.cef/generated.d.ts` (声明合并) `KnownEventTypes`)并刷新 `cef.lock.json`。 。 。 . |
| `cef inspect <agentDir>` | 已运出 | 读取已建 `manifest.json`,运行捆绑 `node:vm`,并报告打开的处理器名称 `__handlers` 加上任何路由 目标显示的参考 但捆绑不暴露. |
| `cef publish` | 已运出 | POST 已建代理卡到市场API(`--as-pubkey`, (中文(简体) ), `--access-token`编号 :`$CEF_ACCESS_TOKEN` ——同一CLI访问符 `cef deploy` (a) 使用. |
| `cef push` | 已运出 | 上传代理到 DDC . `--kind internal` (默认)上传已建代理 `bundle.js` (+ 部件 dirs) 和盖章 货单的捆绑回放 —— 直接装入你控制的桶中 (`--bucket`),或者通过"金库-api"进入组织"金库范围"("金库")`--vault <id> --vault-scope <scope>`) (中文(简体) ). `--kind external` 注册运行的代理 **外部** 平台,从其 [A2A 对](https://agent2agent.info/) 代理卡:取出卡片,获得一张清单(`kind: "external"`, (中文(简体) ), `a2aCard: <url>`,没有捆绑)并写到同一个桶注册处. 外部旗帜 : `--card <url>`, (中文(简体) ), `--alias`, (中文(简体) ), `--agent-version`, (中文(简体) ), `--scope`, (中文(简体) ), `--idle-timeout`。 。 。 . |
| `cef eval <sub>` | 已运出 | 工作流程评价,一次一个工作流程`--workflow`默认值: `cef.config.ts` 或者说 `dist/` 声明). `datasets`, (中文(简体) ), `create <dataset>`, (中文(简体) ), `pull <dataset>` 编号 : `push <dataset>` (雷波语) `datasets/<dataset>/` - 保险库; `push --cut`, (中文(简体) ), `--force`, (中文(简体) ), `--prune`, (中文(简体) ), `--restore`· ; `pull --force`, (中文(简体) ), `run <dataset>` (单位:千美元)`--workflow-version`, (中文(简体) ), `--dataset-version`, (中文(简体) ), `--repeats`, (中文(简体) ), `--baseline`, (中文(简体) ), `--resume`, (中文(简体) ), `experiments [dataset]`, (中文(简体) ), `compare <a> <b>`工作流程(包括:`--vault`编号 :`$CEF_VAULT_ID`,默认钱包本身),其范围(`--scope`,默认其 `requiredScopes`); 需要钱包(`--keystore`编号 :`--password` 或者说 `--secret-phrase`)或(或) `--access-token`编号 :`$CEF_ACCESS_TOKEN`和金库的拨款 在那个范围. `run` 需求 `--as-pubkey`编号 :`$CEF_AS_PUBKEY`。见 [`@cef-ai/eval`](https://npmcn.com/package/%40cef-ai/eval/README.md)。 。 。 . |
| `cef test` | 树枝 | 占位符 - 使用 `vitest` 直接与 `@cef-ai/testing` 直至综合跑道降落. |
| `cef dev` | 树枝 | 占位符——待被打包的平台图像. |

`cef build` 每个已声明代理撰写一个目录 :

```
dist/
  <agentId>/
    bundle.js      # IIFE that installs globalThis.__handlers — a flat map
                   # of handler functions the runtime dispatches as
                   # __handlers[name](event, context). Event handlers are
                   # keyed "<engagementId>::<method>"; lifecycle hooks under
                   # the fixed keys onStart / onClose.
    manifest.json  # AgentManifest body — bundle embedded inline; each
                   # engagement carries handles{eventType -> handlerName}
                   # (namespaced) and hooks[] ("start"/"close"). Identity /
                   # signature fields are blank until `cef publish` signs.
```

处理器名称命名间隔( E)`<engagementId>::<method>`) 保持平地状态 `__handlers` 当多个任务宣布某一方法时,地图无相撞 名称; 乐团从 `HandlerFor`,所以AR直接检查。 生命周期钩子不是 名称空格——管弦乐手硬码 `onStart` 编号 : `onClose` - 如此的方法 - 对 - so a method 名称可以重复使用,作为跨业务约定的活动处理器,但只有一个 每个代理商可能拥有每个生命周期钩(`cef build` a 的错误 碰撞).

`cef typegen` 读取 `cef.config.ts` (和 `publishes` 声明)和 写入 `.cef/generated.d.ts`输入 `KnownEventTypes` 所以作者们 获得字符串- 升自动补全 `@OnEvent` 财务报告和审定财务报表 `ctx.publish`编辑 `cef.lock.json` 在每次运行时都会重写快照, 所以 VCS diffs 表面 类型漂移.

### DDC 证书`cef push`, (中文(简体) ), `cef widget push`, (中文(简体) ), `cef cubby push`(中文(简体) )

向桶上写字完全由以下之一授权: 1

-   `--secret-phrase` 编号 : `$CEF_DDC_SECRET_PHRASE` - 拥有钥匙的短语 桶头.
-   `--access-token` 编号 : `$CEF_DDC_ACCESS_TOKEN` - 由DDC公司授予的DDC访问令牌 桶主来.

访问令牌要么没有标的(无记名令牌:按原样发送),要么是 发给一个钥匙,它的主体——在ROC代理服务邀请函中的标志是: 发给受邀成员。 存储节点接受标的符号 仅根据该密钥签名的请求,所以CLI也需要其短语: `--subject-phrase` 编号 : `$CEF_DDC_SUBJECT_PHRASE`。CLI检查该短语 在连接前生成对象(sr25519或ed25519),并拒绝 没有它,而不是让节点回答 `issuer doesn't match subject in parent token`。没有该短语,使用 在ROC的代理服务成员面板上的"Copy DDC sord for the CLI"——它 用你的钱包来签名,一个在您邀请下没有标出主题的标志——或者 向桶主询问一个没有标注对象的标志 .

### 装腔作势的特工

桶推( 推出)`cef push --bucket`也宣布,在水桶的幼崽 登记(`cubbies/<alias>`每立方公尺,上面写着: 尚未命名 — at `0.1.0`,该版本 `cef cubby push` 使用,与 明显是移民 这就是ROC在部署工作流程执行者时所做的 `runs` cuby; 没有它, 工作流程只能通过 CLI 失败 第一步与 `cubby: lookup schema: … Failed to get cns record`。别名 注册名称从未被触动( 用 `cef cubby push`如果登记处无法阅读,则不宣布任何内容。 A 类 在代理被推后声明未写入命令; 重试一遍. `cef push --vault` 不这样做——金库-api做 也没有宣布幼崽.

## 快速启动

```sh
pnpm add -D @cef-ai/cli
pnpm exec cef build
pnpm exec cef inspect dist/<agentId>
```

注册在别处运行的代理是同一个命令, 不同 `--kind`,而且根本不需要建设步骤——我们没有编译的代码:

```sh
pnpm exec cef push --kind external \
  --card https://ai.example/.well-known/agent-card.json \
  --bucket 1338 --as-pubkey 0x<agent-service-pubkey> --env dev
```

它和任何其他代理人一样出现在ROC的注册簿上,可以连接到一个 保险库和从沙盒发送事件.

### 出版到组织金库

一个组织金库的特工 住在金库自己的登记桶里 还有 (原始内容存档于2018-03-27) (英语). vault-api write it——而不是CLI. 命名金库和发布范围 从一桶取出 :

```sh
pnpm exec cef push --vault <vaultId> --vault-scope gtm \
  --secret-phrase "<your wallet phrase>" --as-pubkey 0x<agent-service-pubkey> --env dev
```

库- api 检查您持有在瞄准镜( 库主, 或 拥有成员一级补助金的成员),并将代理人的别名与 范围是首先公布的,因此另一个范围无法取而代之。 国家行动倡议 上传该版本的文件, 并附有未加标记的显示; 保险库- api 印出 捆绑和部件 CID 并返回存储的运算表,其中 `cef push` 写回 `dist/<id>/manifest.json`。 。 。 .

全权证书: `--secret-phrase` 编号 : `$CEF_VAULT_SECRET_PHRASE` 使用自己的符号 钱包密钥, 生成为 ed25519( 唯一的方案金库- api 接受), 或 `--vault-token` 编号 : `$CEF_VAULT_TOKEN` 发送钱包- api 令牌 . `$CEF_DDC_SECRET_PHRASE` 没有 这里使用的:它取出一个桶主的名字,而不是你. `--bucket`, (中文(简体) ), `--access-token`, (中文(简体) ), `--preset`, (中文(简体) ), `--endpoint` 财务报告和审定财务报表 `--cdn` 不适用,并被拒绝.

一个金库的答案 `REGISTRY_NOT_CONFIGURED` 直到它的主人记录 登记桶并封存登记代表团 (单位:千美元)`PUT /api/v1/vaults/<vaultId>/delegations`) (中文(简体) ). 店主这样做 在ROC的组织网页上,或与 `sdk.vault.delegations.grant` 从 `@cef-ai/vault-sdk`。 。 。 .

这些种类使用不相干旗帜——捆绑没有卡片,卡片没有 `dist/` - 所以通过一种旗帜和另一种旗帜 `--kind` 被拒绝 名称而不是被忽略。 它所防止的失败是沉默的: `--card` 无 `--kind external` 否则,会推 任何最后建造和报告 成功吗.

## 程序化 API

每个子命令都有从软件包导出的相应函数 根, 从测试和脚本中有用 :

```ts
import { cefBuild, cefTypegen, cefInspect } from "@cef-ai/cli";

const build = await cefBuild({ cwd: process.cwd(), outDir: "dist" });
for (const a of build.agents) {
  console.log(a.agentId, a.bundlePath, a.bundleBytes);
}

await cefTypegen({ configPath: "./cef.config.ts" });

const inspected = await cefInspect({
  agentDir: "dist/echo",
  print: false,
});
for (const e of inspected.engagements) {
  console.log(e.id, e.handles, e.hooks, e.exposedMethods, e.missingMethods);
}
```

## 构建时间线

`cef build` 在代理服务器的条目文件之前运行一个合成插件 捆绑. 失败以单个可操作消息中止构建 。 这个 规则反射其中 [`@cef-ai/eslint-plugin`](https://npmcn.com/package/%40cef-ai/eslint-plugin) 所以编辑器 警告与CI失败一致.

-   `@OnEvent(...)` 参数必须是字符串文字.
-   `ctx.publish(t, ...)` 第一个参数必须是字符串字元.
-   `ctx.cubby("alias")` 参数必须是文字和宣布的别名 `cef.config.ts` `cubbies[].alias`。 。 。 .
-   `ctx.models.X` 成员必须参考已宣布的模型别名.
-   导入不得针对被禁模块列表(节点内置像 `fs`, (中文(简体) ), `net`, (中文(简体) ), `http`, (中文(简体) ), `child_process`,加同步 DB / 网络 npm 软件包)。 特工们使用全球 `fetch` 用于HTTP和 `ctx.cubby` 页:1 状态; `globalThis.crypto` (网络晶体)替换 `node:crypto`。 。 。 .

完整的被禁单元清单和理由在 `agent-sdk.md` 7节.

## 配套软件包

-   [`@cef-ai/agent-sdk`](https://npmcn.com/package/%40cef-ai/agent-sdk) 装饰者们, `Context`,以及 `defineAgent` 由正在构建的代理代码消耗.
-   [`@cef-ai/testing`](https://npmcn.com/package/%40cef-ai/testing) - 模拟装置 `cef test` 一旦它着陆.
-   [`@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/...` 路径指向内部兄弟重播 并且不能从新克隆人那里浏览.

## 常见问题

### @cef-ai/cli 是什么？

cef ——建设,打字,检查指挥线的特务\. 镜像代理Runtime合同\(ADR-001\):捆绑安装平面处理器地图 globalThis\.\_\_handlers,列表中标有管弦乐手读取的路由表\.

### 如何安装 @cef-ai/cli？

在项目目录运行 npm install @cef-ai/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cef，可以用 npx cef 直接运行。

### @cef-ai/cli 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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