# @emiliosp/pi-maestro 中文文档

规范地址：https://npmcn.com/package/%40emiliosp/pi-maestro/

版本：0\.21\.0
npm 元数据更新时间：2026-11-12T11:05:37.391Z
中文译文更新时间：2026-11-13T15:38:49.025Z
软件包许可：AGPL-3\.0-or-later

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

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

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

- 包体积（解压后）：3.2 MB，98 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=26\.0\.0
- 运行依赖：0 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-10-05T21:30:00.440Z
- 最新版本发布：2026-11-12T11:05:37.194Z
- 近 30 天下载量：4454（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 53 个）

## 中文简介

为Pi开发的 Spec-驱动多剂开发工作流程.

## 安装

```sh
npm install @emiliosp/pi-maestro
```

也可以使用：`pnpm add @emiliosp/pi-maestro`、`yarn add @emiliosp/pi-maestro`、`bun add @emiliosp/pi-maestro`

## README

# 皮-大师

[![Coverage](https://img.shields.io/codecov/c/github/emiliosp/pi-maestro?logo=codecov)](https://codecov.io/gh/emiliosp/pi-maestro)

写入的 Pi 扩展名 `spec` 并且通过一个光谱驱动的多代理工作流程,可选择地执行.

![Maestro workflow](https://npmcn.com/package/%40emiliosp/pi-maestro/docs/maestro.png)

## 这个想法

读取 [皮·梅斯特罗宣言](https://npmcn.com/package/%40emiliosp/pi-maestro/MANIFESTO.md) 因为项目背后的动机.

`Maestro` 有两个目标:

1.  帮助 `owner` 编写和核准a `specification` (单位:千美元)`spec`一个可逆的变化.
2.  执行核定数 `spec` 通过多代理工作流程.

这个 `owner` 可使用 `Maestro` 仅写和批准 a `spec`,将执行留给另一个工作流程,或者写入 `spec` 并在内部执行 `Maestro`。 。 。 . `Spec` 需要准备和批准。 整个执行阶段是可选的,每个阶段也是可选的:

1.  这个 `builder` 执行核准的 `spec`。 。 。 .
2.  独立 `verifier` 检查每个 `acceptance criterion`。 。 。 .
3.  这个 `simplifier` 重构器接受代码而不改变行为.

破坏 `builder` 跳过整个执行阶段。 与 `builder` 启用,则 `verifier` 财务报告和审定财务报表 `simplifier` 可独立禁用。 三个都是 当其旗帜从现有配置中删除时启用。 初始设置只允许选择角色 。 见 [阶段选择](https://npmcn.com/package/%40emiliosp/pi-maestro/docs/configuration.md#phase-selection)。 。 。 .

这个 `owner` 进行最后审查.

五项原则将工作流程结合在一起:

1.  核定数 `spec` 定义为 `builder` 财务报告和审定财务报表 `verifier`。 。 。 .
2.  没有代理批准自己的工作.
3.  启用时 `verifier` 检查每个 `acceptance criterion` 独立.
4.  这个 `owner` 决定要求、范围和未决问题.
5.  每个特工只有一个角色 具体且有明确指导.

[https://github.com/user-attachments/assets/dffa8bc7-6c79-491f-95df-2ee95b6447aa 互联网档案馆的存檔,存档日期2013-12-2](https://github.com/user-attachments/assets/dffa8bc7-6c79-491f-95df-2ee95b6447aa)

## 许可证

版权 (c) 2026 Emilio Spatola. 许可证根据 [AGPL-3.0- 或- 后期](https://npmcn.com/package/%40emiliosp/pi-maestro/LICENSE)。 。 。 .

## 灵感

皮大师的灵感来自 [打开Spec](https://github.com/Fission-AI/OpenSpec) 财务报告和审定财务报表 [GitHub 光谱套件](https://github.com/github/spec-kit)它适应这些 概念到相继的 Pi 多代理工作流程.

以下官方来源记录了概念参考。 链接指向固定的修订,因此所引用的内容仍然可以检查.

1.  **这个 `specification` 驱动代码.** [Spec Kit的哲学](https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/spec-driven.md) 治疗 `specification` 作为小学 `artifact` 和代码作为它的表达. 单位 `Maestro`,已核准 `spec` 界定工作合同 `builder` 财务报告和审定财务报表 `verifier`。 。 。 .
2.  **描述行为,而不是常规的执行选择.** [OpenSpec 的计划](https://github.com/Fission-AI/OpenSpec/blob/6d04a1b58dedc95729d34e4f223d9d483aae210a/schemas/spec-driven/schema.yaml) 定义 a `specification` 作为行为契约,而不是执行 计划. `Maestro` 记录需要行为、约束和批准的建筑决定 `spec`,将例行执行选择留给 `builder`。 。 。 .
3.  **采用具体,可检验的情景.** [OpenSpec 的计划](https://github.com/Fission-AI/OpenSpec/blob/6d04a1b58dedc95729d34e4f223d9d483aae210a/schemas/spec-driven/schema.yaml) 与设想情况挂钩的要求; [Spec Kit 模板](https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/spec-template.md) 用途 假定/何时/随后接受。 每个 `Maestro` `acceptance criterion` 包含a `GIVEN`页:1 `WHEN`页:1 `THEN`和具体的例子.
4.  **逐步明确要求.** [Spec Kit 的澄清命令](https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/clarify.md) 一次问一个问题,并将接受的答案纳入 `specification`。 。 。 . `Maestro` 也问一个重点问题,等待主人的回答,更新 `spec` 在问下一个问题之前.
5.  **审查要求与测试代码分开.** [Spec Kit 的核对表命令](https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/checklist.md) 评估完整性、清晰度、一致性、, 和可衡量性,而不是执行正确。 在批准前, `Maestro` 审查《公约》执行情况 `spec` 一致性、缺失的决定、可衡量的结果、 可复制的情景。 后一个 `verifier` 独立检查执行情况.
6.  **不同的动机、行为和设计.** [OpenSpec 的计划](https://github.com/Fission-AI/OpenSpec/blob/6d04a1b58dedc95729d34e4f223d9d483aae210a/schemas/spec-driven/schema.yaml) 将这些问题分开,并呼吁 `design.md` 仅在重大技术 决策需要记录,包括原因、替代办法和风险.
7.  **明确要求修改.** [OpenSpec 的计划](https://github.com/Fission-AI/OpenSpec/blob/6d04a1b58dedc95729d34e4f223d9d483aae210a/schemas/spec-driven/schema.yaml) 区分添加、修改、删除和重新命名的要求. `Maestro` 调整此选项 一个概念 `Delta` 每个要求的字段: `added`, (中文(简体) ), `modified`,或 `removed`。每个要求标题说明要求的结果,并指定一个行为者 `MUST`。 。 。 .
8.  **使要求的覆盖范围能够追踪.** [Spec Kit 分析命令](https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/analyze.md) 绘制执行任务的要求图并找出覆盖面差距. `Maestro` 对核查适用相关原则: `Verified by` 连接到它的字段 `acceptance criteria`,包含精确 假设,或两者兼有。 绘图将要求与核查联系起来.

## 作用

| 作用 | 责任 |
| --- | --- |
| `Owner` | 带来问题,批准 `spec`,决定问题和 `findings`,并审查最终代码. |
| `Maestro` | 直接与 `owner`,准备 `spec`,运行其他代理,记录决定,并总结结果. |
| `Builder` | 执行核定数 `spec` 并检查每个 `acceptance criterion`。 。 。 . |
| `Verifier` | 对项目文件进行独立检查 `spec` 并报告技术问题. |
| `Simplifier` | 重构者接受代码以明晰而不改变行为或引入检查失败. |

一个 `escalation` 询问 `owner` 决定一个执行问题。 A 类 `finding` 报告的技术问题 `verifier`编辑 `owner` 讨论两者 `Maestro`,不直接与 `builder` 或者说 `verifier`。 。 。 .

## 先决条件

1.  节点.js 26或后.
2.  皮一分五分五分左右.
3.  获得允许代理的模型.

## 安装

这个 `owner` 安装 `Maestro`数字 :

```bash
pi install npm:@emiliosp/pi-maestro
```

## 使用量

这个 `owner` 从项目目录开始 Pi :

```bash
cd /path/to/project
pi
```

启动 `Maestro`数字 :

```text
/maestro
```

在激活期间, `Maestro` 检查启用代理的配置和模型可用性。 模型可用性来自皮的模型注册. 如果支票失败, `Maestro` 继续禁用并报告问题.

这个 `owner` 遵循该工作流程:

1.  描述一个更改为 `Maestro`。 。 。 .
2.  审查 `spec`,包括委员会 `acceptance criteria` 和具体的例子.
3.  答复 `GREEN FLAG` 何时 `Maestro` 请求批准. `Maestro` 记录批准并开始选定的阶段.
4.  检查每个当前 `builder` `escalation` 并给出 `Maestro` 每个问题的答案和理由.
5.  审查 `verifier` `findings` 选择每个 `finding`。 。 。 .
6.  阅读大师摘要 `candidate-ready` 并进行最后审查.

`Maestro` 启动 `verifier`,当启用时,在成功之后 `builder` `run`. 被选中的特工使用 Pi 的 SDK,并在前台一次运行一个. 皮伊等每个人 `run` 结束,和 `Maestro` 显示 Pi 状态的当前阶段.

当一个保存的本地儿童会议存在时, `Maestro` 显示完成或失败时的路径。 这个 `owner` 能够直接检查该文件或将其导出到 HTML :

```bash
pi --export /sessions/weather/subagents/child.jsonl conversation.html
```

这个 `owner` 工作流程运行时不得编辑产品文件. `Maestro` 可以进行临时实验 `owner` 协议期间 `spec` 筹备和 允许的修订。 见 [工作流程](https://npmcn.com/package/%40emiliosp/pi-maestro/docs/workflow.md#spec-approval)。 。 。 .

一个 `escalation` 询问 `owner` 执行问题的决定,以及 `finding` 报告的技术问题 `verifier`编辑 `owner` 讨论两者 与 `Maestro`,从不直接与 `builder` 或者说 `verifier`。 。 。 . `Maestro` 记录全部当前 `escalation` 答复或 `finding` a. 现行机构的决定 `handoff` 在此之前 改变阶段.

如果任何决定要求 `spec` 更改,工作流程返回到 `drafting-spec` 之前 `owner` 财务报告和审定财务报表 `Maestro` 修改为: `spec`编辑 `owner` 审查经修订的 `spec` 和答复 `GREEN FLAG` 再来一次. `Maestro` 在另一个之前分别核准 `builder` `run`。 。 。 .

当启用时, `Maestro` 启动 `simplifier` 在成功核实后,拒绝所有 `findings`,或 `builder` 完成, 无法校验 。 只有这个 步骤需要 Git 。 如果吉特准备状态无法确认, `Maestro` 警告和跳过简化。 这个 `simplifier` 选择所有未承诺的代码更改,包括 先前存在的分级,未分级,和未跟踪的文件.

工作流程结束于 `candidate-ready`。拒绝 `findings` 保留其理由,公认的失败可能仍然存在。 大师总结 独立核查 从后来的简化报告。 最后总结成功完成后, `Maestro` 自动关闭。 这个 `owner` 后期审查、承诺、拉动 请求和合并.

一样 `/maestro` 命令禁用 `Maestro` 并保留项目文件不变。 残疾 `Maestro`,重新启动 Pi ,或使用 `/resume` 清除现场状态。 已保存 文件不会自动恢复或恢复不完整的工作流程。 这个 `owner` 手动操作.

## 配置

若为 `.pi/maestro.json` 不存在, `/maestro` 启动 Pi 互动终端的引导设置 。 你,那个 `owner`,选择模型和思维水平 `builder`,则 `verifier`,则 `simplifier`。您选择的代理已启用,配置在之前保存 `Maestro` 启动。 如果你不选探员, `Maestro` 只准备 `spec`。 。 。 .

没有默认模型。 如果配置文件已经存在,它必须为每个启用相设定模型. 开始前,您可以编辑文件以更改 `spec` 目录,模型,思维水平,或相相旗. 如果有的话 `required` 旗在已存在的文件中缺失, 它被当作 `true`。不修改 工作流程运行时的配置 .

若为 `builder.required` 实值 `false`,在核准后结束 `spec` 在别的地方执行 否则,你可以关闭 `verifier` 编辑 `simplifier` 分别。 任何被跳过的工作都列在最后摘要中,而且从来没有像现在这样报告。 见 [配置](https://npmcn.com/package/%40emiliosp/pi-maestro/docs/configuration.md#phase-selection)。 。 。 .

## 文档

阅读顺序为:

1.  [词汇表](https://npmcn.com/package/%40emiliosp/pi-maestro/docs/glossary.md): 所用术语和标识符 `specs`报告,和 `Maestro` 留言。 在第一个工作流程之前读一下这个.
2.  [工作流程](https://npmcn.com/package/%40emiliosp/pi-maestro/docs/workflow.md):批准、决定和如何决定 `run` 生产 `artifacts`。 。 。 .
3.  [配置](https://npmcn.com/package/%40emiliosp/pi-maestro/docs/configuration.md): 项目路径,模型,和思维水平.
4.  [分剂整合](https://npmcn.com/package/%40emiliosp/pi-maestro/docs/subagent-integration.md): 代理上下文、执行和活动跟踪.

## 项目章程

1.  [特派团](https://npmcn.com/package/%40emiliosp/pi-maestro/MISSION.md)目标、范围、和 `owner` 责任.
2.  [技术堆栈](https://npmcn.com/package/%40emiliosp/pi-maestro/TECH_STACK.md):运行时间技术和开发工具.
3.  [路线图](https://npmcn.com/package/%40emiliosp/pi-maestro/ROADMAP.md):完成的成果和保存在存储处的计划工作.
4.  [更改日志](https://npmcn.com/package/%40emiliosp/pi-maestro/CHANGELOG.md):有意义的代码库更改并打破更改.
5.  [结构决定记录](https://npmcn.com/package/%40emiliosp/pi-maestro/ADR.md):建筑选择,背景,后果,和证据.

## 常见问题

### @emiliosp/pi-maestro 是什么？

为Pi开发的 Spec-驱动多剂开发工作流程\.

### 如何安装 @emiliosp/pi-maestro？

在项目目录运行 npm install @emiliosp/pi-maestro，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-ai（\*）、@earendil-works/pi-coding-agent（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @emiliosp/pi-maestro 支持 TypeScript 吗？

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

### @emiliosp/pi-maestro 支持 ESM 还是 CommonJS？

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

### @emiliosp/pi-maestro 需要什么版本的 Node\.js？

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

### @emiliosp/pi-maestro 可以商用吗？

@emiliosp/pi-maestro 使用 AGPL-3\.0-or-later 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @emiliosp/pi-maestro 的下载量有多少？

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

### @emiliosp/pi-maestro 还在维护吗？

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