# @cleocode/agents 中文文档

规范地址：https://npmcn.com/package/%40cleocode/agents/

版本：2026\.11\.1
npm 元数据更新时间：2026-11-12T05:55:21.843Z
中文译文更新时间：2026-11-12T05:57:37.920Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cleocode/agents
原文对照：https://npmcn.com/package/%40cleocode/agents/?lang=original
项目主页：https://github.com/kryptobaseddev/cleo#readme
源码仓库：https://github.com/kryptobaseddev/cleo

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

- 包体积（解压后）：46.5 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.16\.0
- 运行依赖：0 个
- 首次发布：2026-03-19T05:29:38.620Z
- 最新版本发布：2026-11-12T05:55:21.436Z
- 近 30 天下载量：13083（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：410（近 12 个月 410 个）

## 中文简介

CLEO代理协议和模板

## 安装

```sh
npm install @cleocode/agents
```

也可以使用：`pnpm add @cleocode/agents`、`yarn add @cleocode/agents`、`bun add @cleocode/agents`

## README

# @ cleocode/ 代理服务器

> 部分 [平等机会委员会](https://github.com/kryptobaseddev/cleo#readme)。从 root README 开始;运行 `cleo <command> --help` 对于任何命令.

通用亚剂协议、罐装工人模板和元剂 CLEO生态系统.

## 范围(ADR-068-v2026.5.30和以后)

人数 [ADR-068 (英语)](https://npmcn.com/package/%40cleocode/agents/.cleo/adrs/ADR-068-canonical-agent-system.md),这个包裹船 完全有三个表面:

1.  **`cleo-subagent.cant`** - 通用协议基础 每一个代理.
2.  **`templates/`** - 5个有名的工人模板 `{{variable}}` 占位符 . 已声明的文件名基准名等同 `agent <name>:` 按安装验证合同计算.
3.  **`meta/`** 从项目背景中合成出其他物剂的元剂.

CleoCode-team 狗食品个人(前者) `cleo-prime`, (中文(简体) ), `cleo-dev`, (中文(简体) ), `cleo-historian`, (中文(简体) ), `cleo-rust-lead`, (中文(简体) ), `cleo-db-lead`, (中文(简体) ), `cleoos-opus-orchestrator`(中文(简体) ) 住在这里 `.cleo/cant/agents/` 在 Cleocode 仓库中,不运入 用户.

## 软件包树

```
packages/agents/
├── package.json
├── README.md                                 # this file
├── cleo-subagent.cant                        # universal protocol base
├── templates/
│   ├── project-orchestrator.cant             # coordinates the starter team
│   ├── project-dev-lead.cant                 # decides HOW, reviews workers
│   ├── project-code-worker.cant              # writes code within globs
│   ├── project-docs-worker.cant              # writes/edits documentation
│   └── project-security-worker.cant          # security review and audits
└── meta/
    ├── README.md
    ├── agent-architect.cant                  # meta-agent: synthesizes agents
    └── playbook-architect.cant               # meta-agent: synthesizes playbooks
```

## 普遍议定书基础: `cleo-subagent.cant`

每一个 CLEO 代理扩展 `cleo-subagent.cant`定义:

-   **RFC 2119 限制** (BASE-001.BASE-007)——表列附件,无内容载于 答复, `cleo complete` 作为终端,输出前 明显订购, 工作前的焦点,没有捏造,研究联系.
-   **LOM 生命周期** ——接吻 ——执行 ——产出 ——返回,明确 在产卵时注入的相位特定导体.
-   **返回格式合同** ——三个允许响应字符串,其他一切 转到文件和清单.
-   **处理错误** ——状态分类,可复试出站代码,站岗 和证据规则(ADR-051).

## Canonical 工人模板

这五个工人模板是参数化的蓝图,其中 `{{variable}}` 占位符 。 它们必须保持项目不可知性——没有CLEO-内部参考, 除模板明确参数外,没有任何工具链假设.

| 模板 | 作用 | 目的 |
| --- | --- | --- |
| `project-orchestrator.cant` | 乐团 | 读取任务,去向dev-lead的路线,综合结果. 不执行代码 . |
| `project-dev-lead.cant` | 牵头 | 分解工作,审查产出,决定技术方向. 只有调度权限;没有编辑/写入/Bash(TEAM-002). |
| `project-code-worker.cant` | 劳动者 | 将代码写入已宣布的词汇中 。 运行 `{{test_command}}` 财务报告和审定财务报表 `{{build_command}}`。持有编辑/写入/纸面. |
| `project-docs-worker.cant` | 劳动者 | 将文档(README、TSDoc、向导)写入文档。 Holds 编辑/ Write/ Bash 范围到文件 . |
| `project-security-worker.cant` | 劳动者 | 安全审查,OWASP威胁建模,依赖性审计. 只读——使发现升级. |

这五个人组成一个完整的启动团队:一个管弦乐手+一个领跑手+三个 工人们 对于需要更丰富地貌的项目 `agent-architect` 元剂(见下文)合成了额外的人称.

### 命名合同(ADR-068 第1号决定)

每个 `.cant` 文件名基准名 MUST 等于 `agent <name>:` 内部声明 这个 模板使用 `project-<role>` 匹配分类器输出的前缀 (单位:千美元)`packages/core/src/orchestration/classify.ts`) (中文(简体) ). 这由安装执行 验证器在 `packages/core/src/store/agent-install.ts`。 。 。 .

## 变量如何工作

CLEO 使用胡子 `{{var}}` 模板替换语法,每 [ARDR-055 D033 (英语)](https://npmcn.com/package/docs/adr/ADR-055-agents-architecture-and-meta-agents.md)。 。 。 .

### 语法

-   `{{name}}` ——简单变量
-   `{{object.key}}` ——嵌入值的点标注
-   `{{inputs.taskId}}` ——已用于启动器 `.cantbook` 游戏本

### 解决链(ADR-068决定5)

变量在 **产卵时间** (没有安装时间):

1.  **步骤绑定** 最高优先事项;职级 `bindings:` 阴影游戏本装订 .
2.  **游戏本绑定** ——上层 `bindings:` 字段.
3.  **会话背景** —— 说 `playbook_runs.bindings`,任务+史诗标识符,用户.
4.  **项目背景** —— 说 `.cleo/project-context.json`,通过点评转出.
5.  **环境变量** —— 说 `CLEO_*` 或者说 `CANT_*` 前缀.
6.  **默认值** 何时 `SubstitutionOptions.defaultValue` 已经设定.
7.  **失踪** ——严格模式抛出 `E_TEMPLATE_RESOLUTION`。 。 。 .

### 为什么懒惰?

模板安装方式 `{{...}}` 占位器完好无损。 分辨率发生在内部 `orchestrateSpawnExecute` 刚刚 `composeSpawnPayload`,这意味着:

-   同一个模板在不同的约束下可以产生不同的产物.
-   BRAIN 提供的上下文(精神模型切片、内存查询)可以输入 解决者.
-   下个产卵上会发现项目上下文的变化,而不进行重新计时.

## 自动安装 `cleo init`

第3项决定: `cleo init` (没有旗帜)自动行走 `@cleocode/agents/templates/` 和电话 `installAgentFromCant()` 用于每个 5个工人模板。 每个模板都在 `signaldock.db.agents` 与 `tier='project'`。 。 。 .

新鲜的 `cleo init` 接下来是 `cleo orchestrate spawn` 5个工人中的任何一个 角色成功没有 `E_AGENT_NOT_FOUND`。 。 。 .

这个 `--install-seed-agents` 旗被保留为已贬值的无名别名 折旧通知.

## 正在撰写新代理

### 1\. 从模板开始或从 `cleo-subagent.cant`

```bash
cp packages/agents/templates/project-code-worker.cant \
   my-project/.cleo/cant/agents/my-worker.cant
```

编辑代理名称, 调谐描述 + 技能 + 工具列表, 替换 `{{variable}}` 占位符,有字面值(如果是特定项目)或 让他们在产卵时懒散解析.

### 2\. 验证CANT语法

```bash
cleo cant validate my-project/.cleo/cant/agents/my-worker.cant
```

### 3\. 安装入登记册

```bash
cleo agent install my-project/.cleo/cant/agents/my-worker.cant
```

### 4\. 核查解决者覆盖范围

```bash
cleo agent doctor --json
```

## 分级优先级(溶链)

产卵时的代理分辨率按顺序排列(ADR-055 / ADR-068):

1.  **项目** —— 说 `{projectRoot}/.cleo/cant/agents/{agentId}.cant`
2.  **全球** —— 说 `~/.local/share/cleo/cant/agents/{agentId}.cant`
3.  **包装** —— 说 `packages/agents/templates/{agentId}.cant`
4.  **倒计时** ——磁盘上没有注册行的种子文件
5.  **普遍** —— 说 `cleo-subagent.cant` 综合信封(ADR-068 第6号决定)

`E_AGENT_NOT_FOUND` 仅在 `cleo-subagent.cant` 本身是 无法到达,显示一个腐败的装置.

## 合同保证

-   **原子安装** —— 说 `packages/core/src/store/agent-install.ts` 覆盖 `.cant` 抄写:, `agents` 向上划一行,然后 `agent_skills` 交叉重写于 a 单人 `BEGIN IMMEDIATE TRANSACTION`。 。 。 .
-   **安装代号:** —— 说 `packages/core/src/agents/seed-install.ts` 比较 `.seed-version` 对抗捆绑的 `package.json` 版本和 匹配时提前返回.
-   **医生漂流报告** —— 说 `packages/core/src/store/agent-doctor.ts` 发射 D-001... D-010 孤儿文件编码, SHA 错配, 遗留路径, 缺失 和遗留的JSON登记册.

## 另见

-   [ADR-055 — 代理架构 + Meta - 代理](https://npmcn.com/package/docs/adr/ADR-055-agents-architecture-and-meta-agents.md) (部分被ADR-068所取代)
-   [ADR-068 — Canonical Agent System (英语)](https://npmcn.com/package/%40cleocode/agents/.cleo/adrs/ADR-068-canonical-agent-system.md) (主动语法参考)
-   [包件边界合同](https://npmcn.com/package/AGENTS.md) – 每一CLEO包的犬类分层

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 常见问题

### @cleocode/agents 是什么？

CLEO代理协议和模板

### 如何安装 @cleocode/agents？

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

### @cleocode/agents 支持 TypeScript 吗？

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

### @cleocode/agents 支持 ESM 还是 CommonJS？

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

### @cleocode/agents 需要什么版本的 Node\.js？

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

### @cleocode/agents 可以商用吗？

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

### @cleocode/agents 的下载量有多少？

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

### @cleocode/agents 还在维护吗？

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