# @centerforagenticai/agent-definitions 中文文档

规范地址：https://npmcn.com/package/%40centerforagenticai/agent-definitions/

版本：0\.2\.0
npm 元数据更新时间：2026-10-12T18:19:12.873Z
中文译文更新时间：2026-11-09T08:01:49.099Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40centerforagenticai/agent-definitions
原文对照：https://npmcn.com/package/%40centerforagenticai/agent-definitions/?lang=original
项目主页：https://github.com/CenterForAgenticAI/tools/tree/main/packages/agent-definitions#readme
源码仓库：https://github.com/CenterForAgenticAI/tools

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

- 包体积（解压后）：223 kB，88 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- 首次发布：2026-10-11T19:46:58.094Z
- 最新版本发布：2026-10-12T18:19:12.677Z
- 近 30 天下载量：3789（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

编码代理定义的一种文件格式: schema, parser, 兼容套件, linter和转换器.

## 安装

```sh
npm install @centerforagenticai/agent-definitions
```

也可以使用：`pnpm add @centerforagenticai/agent-definitions`、`yarn add @centerforagenticai/agent-definitions`、`bun add @centerforagenticai/agent-definitions`

## README

# 代理定义

一个编码代理定义的文件格式 。 定义是带有 YAML 前题的 Markdown 文件 。 前事说出代理人为甚么而作. 身体是它的指示.

同一文件意在装入pi-delegate,pi-fabric和pi-prompt-graph,并作为克洛德代码子代理文件工作. 转换器从其他工具导入文件并导出到它们,同时报告每个目标无法保存的内容.

此寄存器持有 schema, 解析器, 验证, 发现规则, 兼容套件, linter, 转换器和一个可持久适配器, 发布为 `@centerforagenticai/agent-definitions`。 。 。 . [文件/格式.md](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/format.md) 描述文件布局、字段、默认和诊断.

```sh
npm install @centerforagenticai/agent-definitions
```

## 最小定义

```markdown
---
name: reviewer
description: Use after a change passes its tests, to review one bounded diff for defects.
---
You review one change. Report each defect with the file, the line and a case that fails.
```

`name`, (中文(简体) ), `description` 和身体做一个完整的定义。 其他每个字段都是可选的,并有书面默认.

## 解析定义

```ts
import {
  checkIsolation,
  checkRuntime,
  parseDefinition,
} from "@centerforagenticai/agent-definitions";
import schema from "@centerforagenticai/agent-definitions/schema.json" with { type: "json" };

const parsed = parseDefinition(source, { origin: "project", file: "agents/reviewer.md" });
if (!parsed.ok) {
  for (const diagnostic of parsed.diagnostics) console.error(diagnostic.path, diagnostic.message);
} else {
  const isolation = checkIsolation({
    definition: parsed.definition.workspace.isolation,
    requested: "worktree",
  });
  const runtime = checkRuntime(parsed.definition, {
    runtime: "pi-delegate",
    knownKeys: ["defaultProgress"],
  });
  console.log(parsed.definition, parsed.diagnostics, isolation, runtime, schema.$id);
}
```

`parseDefinition` 将默认和相容的拼写规范化. 它回来了 `ok: false` 当诊断有严重性时 `error`。见 [文件/格式.md](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/format.md) 所有字段、诊断路径、政策检查和缺省.

## 命令行

软件包安装 `agent-definitions` 命令.

```sh
npx @centerforagenticai/agent-definitions lint .pi/agents
npx @centerforagenticai/agent-definitions convert --from claude-code --to agent-definitions .claude/agents/reviewer.md
```

`lint` 在运行时间加载前检查文件 . `convert` 除非您通过 `--write`,并打印出降低的报告.

## 词汇表

-   **代理定义**: 描述一个代理的可重用文件 。 不是一个"作用".
-   **简介**:呼叫者发送的输入用于一个任务.
-   **运行**:一次执行代理定义.
-   **演员**: 从定义中创建的长寿运行代理. 运行和演员使用相同的文件;呼叫者选择.
-   **示范作用**: 名称, 如 `role:reviewer` 只选择一个模式和努力。 运行时的模型配置解决了它. 总是写出"模范角色",从不露出"角色".
-   **用户角色**:对使用应用程序的人进行访问控制。 与代理人定义无关.
-   **运行时间**:一个装入定义并运行代理的程序,例如pi-delegate,Fabric或Claude Code.
-   **适配器**:将一次运行连接到此格式的代码.
-   **下调报告**: 出口商将目标格式降出或被削弱的每个字段写入列表.

## 发展

使用节点24. 运行 `npm install`,则 `npm run check`它运行 Lint、 格式检查、 类型检查、 覆盖测试、 构建测试和包烟测试。 CI执行相同的命令.

## 文档

-   [文件/格式.md](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/format.md):字段,默认,政策检查和诊断.
-   [文件/发现](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/discovery.md): 运行时查找定义文件的地方, 顺序为 .
-   [文件/遵守情况](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/conformance.md):另一个项目如何检查它如何读取相同的定义.
-   [文件/日记](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/lint.md)页:1 `lint` 命令、检查和退出状态.
-   [文件/转换](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/convert.md)页:1 `convert` 命令,以及每种外国格式所保存和损失的内容.
-   [文件/可持久文件](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/pi-durable.md): 将定义降低到可持久 `configure()` 输入.
-   [文件/决定](https://npmcn.com/package/%40centerforagenticai/agent-definitions/docs/decisions.md):每个格式的决定及其原因.
-   [固定装置/README.md](https://npmcn.com/package/%40centerforagenticai/agent-definitions/fixtures/README.md):符合性固定装置和每个复制文件的来源.

## 状态

0.1版本发运了图案,剖析器,验证,发现和符合套件. 第0.2版增加了: `agent-definitions` 命令为 `lint` 财务报告和审定财务报表 `convert`,用于 Claude 代码、 Codex 、 GitHub 副驾驶、双子CLI 、 OpenCode 和 pi-agents 的转换器,以及 `pi-durable` 子路径.

## 常见问题

### @centerforagenticai/agent-definitions 是什么？

编码代理定义的一种文件格式: schema, parser, 兼容套件, linter和转换器\.

### 如何安装 @centerforagenticai/agent-definitions？

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

### @centerforagenticai/agent-definitions 支持 TypeScript 吗？

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

### @centerforagenticai/agent-definitions 支持 ESM 还是 CommonJS？

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

### @centerforagenticai/agent-definitions 需要什么版本的 Node\.js？

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

### @centerforagenticai/agent-definitions 可以商用吗？

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

### @centerforagenticai/agent-definitions 的下载量有多少？

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

### @centerforagenticai/agent-definitions 还在维护吗？

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