让开源，少一点语言距离。
npm包中文文档

@emiliosp/pi-maestro

中文文档
0.21.0发布于 2026/11/12AGPL-3.0-or-laterES Module零依赖近 30 天下载 4454

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

中文使用文档
中文原文
文档目录10 节
  1. 这个想法
  2. 许可证
  3. 灵感
  4. 作用
  5. 先决条件
  6. 安装
  7. 使用量
  8. 配置
  9. 文档
  10. 项目章程

皮-大师

Coverage

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

Maestro workflow

这个想法

读取 皮·梅斯特罗宣言 因为项目背后的动机.

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 可独立禁用。 三个都是 当其旗帜从现有配置中删除时启用。 初始设置只允许选择角色 。 见 阶段选择。 。 。 .

这个 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

许可证

版权 (c) 2026 Emilio Spatola. 许可证根据 AGPL-3.0- 或- 后期。 。 。 .

灵感

皮大师的灵感来自 打开Spec 财务报告和审定财务报表 GitHub 光谱套件它适应这些 概念到相继的 Pi 多代理工作流程.

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

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

pi install npm:@emiliosp/pi-maestro

使用量

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

cd /path/to/project
pi

启动 Maestro数字 :

/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 :

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

这个 owner 工作流程运行时不得编辑产品文件. Maestro 可以进行临时实验 owner 协议期间 spec 筹备和 允许的修订。 见 工作流程。 。 。 .

一个 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 分别。 任何被跳过的工作都列在最后摘要中,而且从来没有像现在这样报告。 见 配置。 。 。 .

文档

阅读顺序为:

  1. 词汇表: 所用术语和标识符 specs报告,和 Maestro 留言。 在第一个工作流程之前读一下这个.
  2. 工作流程:批准、决定和如何决定 run 生产 artifacts。 。 。 .
  3. 配置: 项目路径,模型,和思维水平.
  4. 分剂整合: 代理上下文、执行和活动跟踪.

项目章程

  1. 特派团目标、范围、和 owner 责任.
  2. 技术堆栈:运行时间技术和开发工具.
  3. 路线图:完成的成果和保存在存储处的计划工作.
  4. 更改日志:有意义的代码库更改并打破更改.
  5. 结构决定记录:建筑选择,背景,后果,和证据.

版本与发布记录

@emiliosp/pi-maestro 共发布 53 个版本，首次发布于 2026/10/06；过去 12 个月发布了 53 个版本。

版本发布日期距今
0.21.0latest2026/11/121 天前
0.20.02026/11/121 天前
0.19.22026/11/103 天前
0.19.12026/11/094 天前
0.18.72026/11/094 天前
0.18.62026/11/094 天前

关于 @emiliosp/pi-maestro 的常见问题

@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 和提交记录判断。