# @sublang/playbook 中文文档

规范地址：https://npmcn.com/package/%40sublang/playbook/

版本：18\.1\.2
npm 元数据更新时间：2026-11-02T13:57:47.419Z
中文译文更新时间：2026-11-02T14:28:06.968Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：4.4 MB，157 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.6\.0
- 运行依赖：5 个
- 首次发布：2026-05-17T01:19:10.223Z
- 最新版本发布：2026-11-02T13:57:46.981Z
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

可组合的XState v5剧本运行时，编译了由GEARS规范驱动的Captain、CODE、REVIEW、DECIDE、DEV、BRANCH、PR和INSPECT工作流。

## 安装

```sh
npm install @sublang/playbook
```

也可以使用：`pnpm add @sublang/playbook`、`yarn add @sublang/playbook`、`bun add @sublang/playbook`

## README

# 剧本：可靠性是你所需要的

[![npm version](https://img.shields.io/npm/v/@sublang/playbook)](https://www.npmjs.com/package/@sublang/playbook) [![Node.js](https://img.shields.io/node/v/@sublang/playbook)](https://nodejs.org/) [![CI](https://github.com/sublang-ai/playbook/actions/workflows/ci.yml/badge.svg)](https://github.com/sublang-ai/playbook/actions/workflows/ci.yml)

_技能通过状态机和各种llm变得可靠。_

自然语言技能灵活且易于使用，但比脚本化工作流更难以预测，尤其是在长期工作中。 即使是最好的法学硕士也会犯错误，部分原因是简单的语言描述很少能消除模糊性或保证完整性。

SubLang Playbook同时解决以下两个问题：

-   的同伴 [SLC编译器](https://github.com/sublang-ai/slc) 将纯语言过程(如 `SKILL.md`，将其转化为具有确定性状态机控制流的剧本。
-   剧本可以为其步骤分配不同的代理或法学硕士，并让他们相互审查和挑战，帮助在交付之前发现错误。

![Venn diagram: Skill is flexible, Workflow is deterministic, and Playbook sits in the intersection as both.](https://npmcn.com/package/%40sublang/playbook/docs/assets/playbook-venn.svg)

词汇: **老板** 是你;这个 **队长** 协调代理是你吗 说话;一个 **角色** 剧本-本地工作是什么 `coder`;和一个 **球员** 是 一个或多个稳定的队长会话代理和提供程序会话 角色绑定。角色描述工作流程，而玩家id决定哪些工作 分享对话的连续性。

运行 `playbook` 的交互式tmux UI [cligent](https://github.com/sublang-ai/cligent)，或者 `playbook run` 对于同一个Captain会话，在脚本和CI中没有tmux。

## 快速启动

开箱即用，Playbook包括 **代码** 的实现, **审查** 对于基于提交的审查和修复， **决定** 对于独立提出和审查的规范决定， **DEV** 对于开发请求的基于存储库的规划， **分支** 用于检查GitHub问题的新分支， **公关** 通过拉取请求发布、检查和合并分支 **检查** 用于在不更改存储库的情况下解释提供的材料或运行的接口。 CODE和DECIDE调用REVIEW作为嵌套剧本；DEV调用CODE，或者DECIDE然后CODE，当请求命名GitHub问题或请求拉请求时，将它们包装在BRANCH和PR中。

共享的启动器配置选择队长和球员的适配器 当地可见的证书：克劳德首先，然后是法典，以及两者的位置 配置只 `dev.reviewer` 种子在法典上。如果两者都不是 配置好后，它会给克劳德种子，并打印一个通知。编码、评审、决策、分支和PR绑定 他们的本地角色显式地 `dev.coder` 和 `dev.reviewer`，如此嵌套而过 约定只有在绑定名称相同的情况下才共享会话 玩家ID;DEV的分析师绑定了一个不同的 `dev.analyst` player和INSPECT的 检查员结合 `inspect.inspector`.

```sh
npm install -g @sublang/playbook
npm install -g @anthropic-ai/claude-agent-sdk @openai/codex-sdk
```

自定义配置需要其提供商所需的sdk；看到 [配置代理](https://npmcn.com/package/%40sublang/playbook/docs/configuration.md). 如果SDK缺失或比客户端支持的版本老，Playbook在启动任何东西之前打印固定的安装命令；看到 [安装代理sdk](https://npmcn.com/package/%40sublang/playbook/docs/cli.md#installing-agent-sdks) 升级, `npx`，以及其他适配器。

先决条件:

-   Node.js >= 20.6.0
-   已配置适配器的凭据：authenticated [克劳德代码](https://docs.anthropic.com/en/docs/claude-code/overview) 或者 `ANTHROPIC_API_KEY` / `CLAUDE_CODE_OAUTH_TOKEN` 克劳德;身份验证 [食典委CLI](https://github.com/openai/codex) 或者 `OPENAI_API_KEY` / `CODEX_ACCESS_TOKEN` 为食品
-   [GitHub CLI](https://cli.github.com/) （`gh`)为存储库的GitHub远程认证，为 `/branch`， `/pr`, `/dev` 命名问题或请求拉取请求的请求

互动 `playbook` 另外需要tmux 3.3或更新版本 [`glow`](https://github.com/charmbracelet/glow#installation) 在 `PATH`;无头 `playbook run` 没有。

CODE在当前目录下工作，可以自主编辑和提交，所以使用一个干净的分支或工作树。

```sh
cd /path/to/your/project
playbook
```

输入一个任务，输入 `/code <task>` 要实现，请输入 `/decide <question>` 独立提出和审查的决定。

在第一次启动时，Playbook将其配置写入 `${SPEX_HOME:-$HOME/.spex}/config/playbook.config.yaml`． 一个配置留在以前的位置-根的 `playbook/playbook.config.yaml` 或者 `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml` -在下次发射时移动一次，除非一个相对的主定位器改变了目标那个案子被拒绝了，原封不动地换了一个。

相同的配置，编译船长，启用剧本，稳定的球员，和 嵌套呼叫功率无头匝。两个前端创造相同的耐用性 逻辑会话：复制上报的会话ID，重新打开交互式会话 无头或无头会话交互。 显式运行REVIEW，或者将更长的请求传递给Captain：

```sh
playbook run "/review review the latest commit"
printf '%s\n' 'Implement the approved specification, then review it.' | playbook run
# Later, either presentation can reopen the returned/reported session id:
playbook --session 4f2c0000-0000-4000-8000-000000009ab1
playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 "continue"
```

`playbook run` 将一个boss可见的Captain回复打印到stdout，并将操作状态打印到stderr；CODE和DECIDE也可以在那里完成它们嵌套的REVIEW调用。

如果某一步骤失败或在回答之前需要准备，请Captain修正前提条件并继续；看到 [准备停止的步骤](https://npmcn.com/package/%40sublang/playbook/docs/cli.md#preparing-a-stopped-step).

使用 `/inspect` 分析现有材料或解释运行界面。浏览器访问需要显式启用检查器 [浏览器功能](https://npmcn.com/package/%40sublang/playbook/docs/configuration.md#browser-capability)． 嵌入式主机可以提交便携式附件，并显示保存的本地图形 [资产和会话api](https://npmcn.com/package/%40sublang/playbook/docs/embedding.md#attachments-and-captured-evidence).

看到 [使用CLI](https://npmcn.com/package/%40sublang/playbook/docs/cli.md) 对于旗帜和持久延续， [配置代理](https://npmcn.com/package/%40sublang/playbook/docs/configuration.md) 对于共享阵容， [嵌入](https://npmcn.com/package/%40sublang/playbook/docs/embedding.md) 对于自定义主机，以及 [更新日志](https://github.com/sublang-ai/playbook/blob/main/CHANGELOG.md) 的版本。

## 创造你自己的剧本

单独的 [SLC编译器](https://github.com/sublang-ai/slc) 需要Node.js >= 23.6并编译一个纯语言 `.md` 或者 `.txt` 过程:

```sh
npm install -g @sublang/slc
slc playbook my-workflow.md
# After enabling /absolute/path/to/my-workflow.ts in the shared config:
playbook run "/my-workflow <your task>"
```

SLC写道 `my-workflow.ts`源代码旁边有一个为Playbook准备的注册表项，下面有可检查的中间体和测试 `my-workflow.playbook/`. 启用该条目并绑定它在其下声明的每个角色 `playbooks.my-workflow` 在共享配置中，然后调用 `/my-workflow`;看到 [外部的剧本](https://npmcn.com/package/%40sublang/playbook/docs/configuration.md#external-playbooks) 和 [SLC文件](https://github.com/sublang-ai/slc#quick-start).

## 如何编译

SLC的 `playbook` 管道有三个阶段：

1.  **文本→GEARS** （[slc / text2gears.md](https://npmcn.com/package/%40sublang/playbook/slc/text2gears.md))——明确每个行为的触发器、参与者、提示和结果。
2.  **齿轮→FSM** （[slc / gears2fsm.md](https://npmcn.com/package/%40sublang/playbook/slc/gears2fsm.md)) -将每个项目映射到一个XState状态，该状态调用队长、玩家、另一个剧本或本地脚本。
3.  **FSM→运行时** （[slc / link.md](https://npmcn.com/package/%40sublang/playbook/slc/link.md)) -将机器连接到独立于主机的接口，用于用户输入、代理调用、状态和遥测。

默认的传递在前两个阶段之间运行 [通过优化](https://npmcn.com/package/%40sublang/playbook/slc/optimize.md) 将符合条件的机械步骤替换为本地shell脚本，以及 [prompt-prefix通过](https://npmcn.com/package/%40sublang/playbook/slc/prefix.md) 将每个提示的中继运行时值移动到其指令之后，以便重复运行共享可缓存的提示前缀； `--no-optimize` 跳过。 检查完整 [队长](https://npmcn.com/package/%40sublang/playbook/reference/sdlc/captain.md)， [代码](https://npmcn.com/package/%40sublang/playbook/reference/sdlc/code.md)， [审查](https://npmcn.com/package/%40sublang/playbook/reference/sdlc/review.md), [决定](https://npmcn.com/package/%40sublang/playbook/reference/sdlc/decide.md) 的例子。

## 贡献

我们欢迎各种贡献。

-   🌟如果您发现Playbook有用，请点击我们的回购。
-   [打开一个问题](https://github.com/sublang-ai/playbook/issues) 针对bug或特性请求。
-   [打开PR](https://github.com/sublang-ai/playbook/pulls) 用于修复或改进。
-   讨论 [不和](https://discord.gg/XxTPjNqy9g) 寻求支持或新想法。

从资料来源:

```sh
git clone https://github.com/sublang-ai/playbook.git
cd playbook
pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm playbook   # drive a Boss turn against the source tree
```

Playbook本身是规范驱动的：编译器阶段是规范的一部分 [`slc/`](https://npmcn.com/package/%40sublang/playbook/slc)，而参考剧本则是从它们的散文来源中重新生成的。 编辑源代码，重新生成它的GEARS、FSM和运行时工件，同步测试和下游规范，直到 `pnpm test` 通过，并提交与共同作者预告片 [`specs/packages/git.md`](https://github.com/sublang-ai/playbook/blob/main/specs/packages/git.md). 齿轮↔FSM契约([剧本包](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook.md))和运行时契约([剧本-运行时包](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-runtime.md))被钉在 [`specs/packages/`](https://github.com/sublang-ai/playbook/tree/main/specs/packages) 并通过测试套件进行验证。

## 许可证

[apache - 2.0](https://npmcn.com/package/%40sublang/playbook/LICENSE)

## 常见问题

### @sublang/playbook 是什么？

可组合的XState v5剧本运行时，编译了由GEARS规范驱动的Captain、CODE、REVIEW、DECIDE、DEV、BRANCH、PR和INSPECT工作流。

### 如何安装 @sublang/playbook？

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

### @sublang/playbook 支持 TypeScript 吗？

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

### @sublang/playbook 支持 ESM 还是 CommonJS？

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

### @sublang/playbook 需要什么版本的 Node\.js？

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

### @sublang/playbook 可以商用吗？

@sublang/playbook 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @sublang/playbook 还在维护吗？

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