# @cleocode/playbooks 中文文档

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

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

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

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

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

- 包体积（解压后）：461 kB，49 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.16\.0
- 运行依赖：4 个
- 首次发布：2026-04-18T00:24:39.081Z
- 最新版本发布：2026-11-12T05:57:15.010Z
- 近 30 天下载量：10707（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：296（近 12 个月 296 个）

## 中文简介

CLEO的游戏本 DSL + 运行时间 — T889 管弦乐一致性 v3

## 安装

```sh
npm install @cleocode/playbooks
```

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

## README

# @ cleocode/ 游戏本

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

**Playbook DSL + CLEO的运行时间 — T889 管弦乐一致性 v3.**

游戏本是 `.cantbook` YAML 文档,将多步代理工作流程描述为由打出边连接的节点(代理,决定和批准门)的DAG. 此软件包解析它们, 持续执行状态为 `tasks.db`,评价HITL自动政策,并管理HMAC签注的"人入"门的审批标志.

## 状态

| 挥手 | 关切 | 状态 |
| --- | --- | --- |
| W4-6号 | Drizzle 表+类型 | 已运出 |
| W4-7型导弹 | `.cantbook` YAML 解析器 | 已运出 |
| W4-8型导弹 | 状态层 CRUD | 已运出 |
| W4-9型导弹 | HITL 自动政策评价员 | 已运出 |
| W4-10号 | 国家机器运行时间 | 待处理 |
| W4-16号 | 批准恢复令牌(HMAC) | 已运出 |

运行时间执行器( E)`runtime.ts`)是下一艘飞船——已经具备了parser + state + 政策 + 批准原始.

## 安装

这是一个内部的单发包。 消费者通过工作空间依赖使用:

```jsonc
// package.json
{
  "dependencies": {
    "@cleocode/playbooks": "workspace:*"
  }
}
```

## 这算什么 `.cantbook` 看起来像

```yaml
version: "1.0"
name: release-cut
description: Cut a CalVer release and publish to npm

inputs:
  - name: version
    required: true
    description: Target version (e.g. 2026.4.90)

nodes:
  - id: build
    type: deterministic
    command: pnpm
    args: [run, build]

  - id: test
    type: deterministic
    command: pnpm
    args: [run, test]
    depends: [build]

  - id: review
    type: approval
    prompt: "Build + tests green. Publish {{ version }} to npm?"
    depends: [test]

  - id: publish
    type: agentic
    skill: release-publisher
    depends: [review]

edges:
  - from: build
    to: test
    contract:
      requires: [dist-exists]
      ensures: [tests-passed]
  - from: test
    to: review
  - from: review
    to: publish

error_handlers:
  - on: test-failed
    action: abort
    message: "Tests failed — aborting release."
```

解析器执行的验证规则 :

-   `version` 必须 `"1.0"`。 。 。 .
-   `name` 须是非空.
-   节点 `id`s必须独一无二.
-   每个 `edges[].from` 编号 : `edges[].to` MUST 引用一个已知的节点ID.
-   节点+边缘 MUST 形成 DAG(无周期).
-   `agentic` 节点必须 `skill` 或 `agent` (至少一个).
-   `deterministic` 节点必须 `command` + 键 `args`。 。 。 .
-   `approval` 节点必须 `prompt`。 。 。 .
-   `depends[]` 条目 MUST 是有效的节点编号.
-   `iteration_cap` 编号 : `max_iterations` 必须在 `0..10` (硬限制).

## 快速 API

```typescript
import {
  parsePlaybook,
  createPlaybookRun,
  updatePlaybookRun,
  evaluatePolicy,
  createApprovalGate,
  approveGate,
  rejectGate,
  DEFAULT_POLICY_RULES,
} from '@cleocode/playbooks';

// 1. Parse a .cantbook file
const { playbook, hash } = parsePlaybook(yamlSource);

// 2. Create a persisted run
const run = createPlaybookRun(tasksDb, {
  runId: 'run_abc123',
  playbookName: playbook.name,
  playbookHash: hash,
  bindings: { version: '2026.4.90' },
  epicId: 'T889',
  sessionId: 'ses_xyz',
});

// 3. Evaluate auto-policy at an approval node
const { autoPassed, reason } = evaluatePolicy(node, DEFAULT_POLICY_RULES, context);

// 4. Create an approval gate (pending) or auto-pass it
const approval = createApprovalGate(tasksDb, {
  runId: run.runId,
  nodeId: 'review',
  autoPassed,
});

// 5. Resolve the gate (human approves via the resume token)
approveGate(tasksDb, approval.token, { approver: 'keaton', reason: 'LGTM' });
```

## 数据库表格

两张表都住在 `tasks.db`. 移徙: `packages/core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/`。 。 。 .

### `playbook_runs`

| 栏 | 类型 | 页:1 |
| --- | --- | --- |
| `run_id` | 文本 PK | 调用程序提供运行 id |
| `playbook_name` | 文本 | 从已解析的游戏本 |
| `playbook_hash` | 文本 | SHA-256源(参数计算) |
| `current_node` | 文本 | 活动节点的编号, `null` 完成时 |
| `bindings` | json 文本 | 累积输入 + 每个节点输出绑定 |
| `error_context` | json 文本 | 居住时间 `status = 'failed'` |
| `status` | 文本 | `running | paused | failed | succeeded | cancelled` |
| `iteration_counts` | json 文本 | `{ nodeId: count }` ——针对 `iteration_cap` |
| `epic_id` | 文本 | 链接的任务史诗( 可选) |
| `session_id` | 文本 | 链接的 CLEO 会话( 可选) |
| `started_at` | 文本 | ISO-8601,默认为 `now()` |
| `completed_at` | 文本 | ISO-8601 终端时 |

### `playbook_approvals`

| 栏 | 类型 | 页:1 |
| --- | --- | --- |
| `approval_id` | 文本 PK |  |
| `run_id` | 文本 | FK – (韩语) `playbook_runs.run_id` |
| `node_id` | 文本 | 播放本中的批准节点 id |
| `token` | 文本 UNIQUE | HMAC 恢复符号 |
| `requested_at` | 文本 | ISO-8601 标准 |
| `approved_at` | 文本 | 关于批准/拒绝的ISO-8601 |
| `approver` | 文本 | 行动者 |
| `reason` | 文本 | 自由形式的理由 |
| `status` | 文本 | `pending | approved | rejected` |
| `auto_passed` | 单位 0/1 | 政策评估员制定的 |

## 批准标志(HMAC)

HMAC -SHA -256 签下解密密码 `getPlaybookSecret(env)`数字 :

1.  `CLEO_PLAYBOOK_SECRET` (首选)
2.  `CLEO_SECRET` (倒计时)
3.  如果两者都没有设置,那么硬错误——没有秘密就无法创建批准节点.

托肯斯编码 `{runId, nodeId, issuedAt}` ,并在任何 `approveGate` 编号 : `rejectGate` 电话 抵制重放: 已经决定的批准返回 `E_APPROVAL_ALREADY_DECIDED`。 。 。 .

## 错误代码

| 常数 | 含义 |
| --- | --- |
| `E_APPROVAL_NOT_FOUND` | Token 不匹配任何待批行 |
| `E_APPROVAL_ALREADY_DECIDED` | 已经批准 `approved` 或者说 `rejected` |
| `PlaybookParseError` | 被丢弃 `parsePlaybook` 附有审定问题清单 |

## 政策评价员

`evaluatePolicy(node, rules, context)` 根据命令列表匹配批准节点 `PolicyRule`s. 第一条匹配的规则决定: `autoPassed: true | false` 加一个 `reason`. 曾让低风险审批门自动通车(如"从上个绿色跑道中未变出"),而不会打扰人. `DEFAULT_POLICY_RULES` 安全保守的默认装置.

## 相关软件包

-   **`@cleocode/contracts`** —— 说 `PlaybookDefinition`, (中文(简体) ), `PlaybookRun`, (中文(简体) ), `PlaybookApproval` 合同类型在这里消耗.
-   **`@cleocode/core`** 拥有 `tasks.db` 生命周期。 Playbook迁移被核心的细管跑车所应用.
-   **`@cleocode/cleo`** ——会暴露的CLI表面 `cleo playbook run`, (中文(简体) ), `cleo playbook approve <token>` 一旦运行时间(W4-10)着陆.

## 测试

```bash
pnpm --filter @cleocode/playbooks test
```

烟雾、分析器、计划、状态、政策和批准测试套房覆盖了装运的地表.

## 常见问题

### @cleocode/playbooks 是什么？

CLEO的游戏本 DSL \+ 运行时间 — T889 管弦乐一致性 v3

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

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

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

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

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

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

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

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

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

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

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

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

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

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