@ cleocode/ 游戏本
部分 平等机会委员会。从 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 + 政策 + 批准原始.
安装
这是一个内部的单发包。 消费者通过工作空间依赖使用:
// package.json
{
"dependencies": {
"@cleocode/playbooks": "workspace:*"
}
}
这算什么 .cantbook 看起来像
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须是非空.- 节点
ids必须独一无二. - 每个
edges[].from编号 :edges[].toMUST 引用一个已知的节点ID. - 节点+边缘 MUST 形成 DAG(无周期).
agentic节点必须skill或agent(至少一个).deterministic节点必须command+ 键args。 。 。 .approval节点必须prompt。 。 。 .depends[]条目 MUST 是有效的节点编号.iteration_cap编号 :max_iterations必须在0..10(硬限制).
快速 API
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)数字 :
CLEO_PLAYBOOK_SECRET(首选)CLEO_SECRET(倒计时)- 如果两者都没有设置,那么硬错误——没有秘密就无法创建批准节点.
托肯斯编码 {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) 根据命令列表匹配批准节点 PolicyRules. 第一条匹配的规则决定: 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)着陆.
测试
pnpm --filter @cleocode/playbooks test
烟雾、分析器、计划、状态、政策和批准测试套房覆盖了装运的地表.