# @agwab/pi-workflow 中文文档

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

版本：0\.16\.4
npm 元数据更新时间：2026-10-16T12:58:35.838Z
中文译文更新时间：2026-11-09T23:01:41.712Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：53.4 MB，8814 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-06-25T13:06:33.157Z
- 最新版本发布：2026-10-16T12:58:35.440Z
- 近 30 天下载量：1700（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 37 个）

## 中文简介

Pi子剂的工作流程管弦乐.

## 安装

```sh
npm install @agwab/pi-workflow
```

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

## README

![pi-workflow](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/logo.svg)

# pi 工作流程

**工作流为皮作曲.**

[![npm](https://img.shields.io/npm/v/@agwab/pi-workflow.svg)](https://www.npmjs.com/package/@agwab/pi-workflow)

`pi-workflow` 让 Pi 运行命名,可重复的多步工作流程:研究,代码审查,相符合性检查,影响审查,以及项目特定团队的常规.

建造在 [`@agwab/pi-subagent`](https://github.com/AgwaB/pi-subagent),它协调Pi子代理工人跨工作流程步骤,在他们之间传递结果,并记录运行情况,以便检查、停止或恢复运行.

您选择工作流程并用自然语言描述任务 .

## 安装

安装软件包 :

```bash
pi install npm:@agwab/pi-workflow
```

然后重新装入皮.

此安装 :

-   页:1 `/workflow` 扩展
-   捆绑 `workflow-guide` 技能
-   捆绑 `execution-router` 技能

稍后更新:

```bash
pi update npm:@agwab/pi-workflow
```

需要节点.js `>=22.19.0` 在macOS或Linux。 原生Windows不支持;使用WSL2.

## 用法:自然问

安装后,请 Pi 按名称使用捆绑或工程工作流程,并描述您要处理的任务. 如果您不确定要使用哪个工作流程, 请 Pi 列出或选择可用的工作流程 .

捆绑的工作流程使用本地第一代理搜索,并返回到 Pi-workflow 捆绑的普通代理,例如 `scout` 财务报告和审定财务报表 `researcher`。工具级引用细节 [`docs/usage.md`](https://npmcn.com/package/%40agwab/pi-workflow/docs/usage.md)。 。 。 .

```text
Use the bundled deep-research workflow to research this repository and summarize the architecture tradeoffs.
```

```text
Use the deep-review workflow to review the current diff from multiple perspectives.
```

```text
Use the spec-review workflow to compare docs/API_SPEC.md against the implementation and tests.
```

如果您想要确定手动控制, 请使用斜线命令表 :

```text
/workflow run deep-research "Research this repository and summarize the architecture tradeoffs."
```

对于一次性的适应性工作流程,在不选择被保存的工作流程的情况下,应进行规划,扇出并合成,使用:

```text
/workflow dynamic "Research this repository and summarize the architecture tradeoffs."
```

当您想要推荐而不是自己选择路径时, 请使用边框比较命令 :

```text
/workflow auto "Review the current diff for reliability and test coverage."
```

`/workflow auto` 只比较动态和可发现的命名工作流程;它不提供当前对话的选择. 在TUI中,在开始工作流程之前,它需要候选人选择和单独的最终确认;在打印/RPC/无头模式中,它只打印建议和后续命令. `/workflow run` 总是开始命名的工作流程和 `/workflow dynamic` 总是启动直接动态运行时间.

交互式斜线命令发射使用 Pi 的可切换前置加载器,同时验证并完成初始调度传出; `/workflow auto` 在比较候选人时使用它。 命令返回和 Pi 显示一个 `Active workflows` 编辑器下方的部件加紧凑的页脚状态 。 部件不包括发射/准备状态和 Stale `running` 没有运行任务的记录, 跟踪顶级运行进度, 幸存会话重新加载从 `.pi/workflows`,当没有工作流程仍然活动时消失。 打开 `/workflow` 整个板子.

### 执行概况

使用 `/workflow profile [workflow]` 在 Pi 的 TUI 中预览并私下保存 Codex, Codex High, Claude, Mixed, 或每个阶段的自定义模型/思维设置. 没有工作流程参数, picker 显示每个工作流程保存的配置文件 而不是它的路径;预览使用有色相相/作用/模型/思维列. 相同的精确工作流程定义可以重复使用,从而有利于各个项目; 其后交互、无头、自动确认 `workflow_run` 发射捕获 运行时的有效值。 缺少模型能力或陈旧 工作流程定义块带有解释而不是沉默地取而代之.

一个工作流程可以单独声明自定义名称 `executionProfiles` (单位:千美元) `defaultExecutionProfile`明确 `/workflow run --profile <name> ...` (或 `workflow_run.profile`)胜过已保存的用户配置文件。 两者皆无,前一个 交互选择器/默认/Base行为不变. 作者添加语义 `profileRole` 与代理文本无关的值 `role`; 见 [执行概况参考文献](https://npmcn.com/package/%40agwab/pi-workflow/docs/usage.md#execution-profiles) 联 合 国 确切的角色矩阵、持久性合同、优先权和分批限制.

## 用法: 选择执行模式

使用捆绑 `execution-router` 当您想就一项任务是否应当直接处理提出建议时,由目标核查人/核查人、现有工作流程或通过单独的工作流程授权请求。 技能是咨询性的:它不会启动、验证、编写或重定向工作流程.

```text
/skill:execution-router decide whether this repository review should use a single-agent pass, deep-review, or a targeted verifier.
```

## 用法: 创建自己的工作流程

使用捆绑 `workflow-guide` 技能,用于创建、调整或审查工作流程定义。 它包括验证的用于常见图形的脚手架捆绑,因此在定制和验证前,新的工作流程可以从已知的好结构开始:

```text
/skill:workflow-guide create a workflow for weekly release readiness.
It should inspect docs, tests, recent changes, package metadata, and produce a final checklist.
Save it as a reusable project workflow.
```

```text
/skill:workflow-guide customize deep-review for frontend accessibility and UX review.
Save it as a reusable project workflow.
```

```text
/skill:workflow-guide create a backend API review workflow.
It should check concurrency, transaction safety, error handling, observability, and test risk.
```

当呼叫者已经固定了一个小文档目录时 `fixed-inventory` 脚手架可以用静态代码来捆绑它,而不是花一个模型舞台来重现已知的ID和路径. 见 [使用量](https://npmcn.com/package/%40agwab/pi-workflow/docs/usage.md#authoring-workflows) 仅用于编辑边界和初始化.

## 工作流程结构

一个工作流程是一个通过可重复使用的过程执行一种自然语言任务的决定性阶段图.

`pi-workflow` 分为三个部分:

1.  **工作流程** ——图和运行生命周期:存在什么阶段,何时运行,产出如何前进.
2.  **任务** ——代理后置工作:有焦点的提示,有动态的扇出,扇入合成,并有限定的回路.
3.  **支助** ——定型地铁:助行码,验证,正常化,文物,恢复友好运行状态.

简言之:工作流程定义了过程,任务要求Pi代理来完成工作,支持保持过程的结构化和可重复性.

一个小的工作流程定义是这样的:

```json
{
  "schemaVersion": 1,
  "defaults": {
    "agent": "researcher",
    "readOnly": true,
    "tools": ["read", "grep", "find", "ls"]
  },
  "artifactGraph": {
    "stages": [
      {
        "id": "plan",
        "type": "single",
        "profileRole": "planning",
        "prompt": "Put machine-readable JSON in <control> with an items array."
      },
      {
        "id": "inspect",
        "type": "foreach",
        "profileRole": "research-execution",
        "from": { "source": "plan", "path": "$.items" },
        "each": { "prompt": "Inspect this item: ${item}" }
      },
      {
        "id": "prepare",
        "from": "inspect",
        "sourcePolicy": "partial",
        "support": { "uses": "./helpers/prepare.mjs" }
      },
      {
        "id": "report",
        "type": "reduce",
        "profileRole": "synthesis",
        "from": ["plan", "prepare"],
        "prompt": "Use upstream workflow artifacts to write the final report."
      }
    ]
  }
}
```

## 支持的阶段模式

工作流定义由一小组相位图案和图形组成.

| 图案 | 用它来 | 运行时形状 |
| --- | --- | --- |
| `single` | 重点步骤 | 一个提示 - > 一个子代理 |
| `foreach` | 动态扇出 | 上游控制文物中的JSON阵列 - > 每件1个子剂 |
| `reduce` | 范仁/综合 | 上游工作流程文物 - > 1个合成子剂 |
| `loop` | 违反规定重复 | 儿童复发阶段直至确定停止状态 |
| `dag` | 嵌入式图形容器 | 子阶段降低到命名空格任务; 下游显示选中输出 |
| `dynamic` | 适应性管弦乐 | 信任的捆绑本地控制器代码可以创建正式的工作流程任务 `ctx.agent()` |

![Core workflow stage shapes: single, foreach, reduce, loop, dag, and dynamic](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/stage-types.png)

## 预定义的工作流程

该软件包包括用于共同研究和审查工作的四个捆绑工作流程。 它们是可运行的默认和作者示例,而不是完整的工作流程目录.

| 工作流程 | 最好还是 | 它会做什么 |
| --- | --- | --- |
| `deep-research` | 在广度、核查和援引建议时,进行深入、以来源为基础的研究. | 按深度排列计划研究问题,粉丝们先出题研究,使索赔正常化并排出等级,根据证据核实选定的索赔,并出具证据合格的完成情况摘要并审计 `final-report.md`;并列任务保留简洁的比较快照. |
| `deep-review` | 当一个审查员通过还不够时进行代码或设计审查. | Triage 选择审查镜片,审查员得出结果,确定性帮助者将其复制,挑战性通过测试幸存者,确定性帮助者分区判决,并作出只结果完成摘要+ `final-report.md`; 遗产 `review.md` 字节不变. |
| `spec-review` | 现有规格、API合同或接受标准的要求到执行的可追踪性. | 摘录可测试的要求、地图执行情况和测试、核实候选人差距、保留每一最终/投放/需要 -- -- 人的处置,并编制注重合规的完成情况摘要加 `final-report.md`。 。 。 . |
| `impact-review` | 对拟议或适用的修改进行副作用和风险审查. | 地图改变范围和受影响的地表,合并合同、回归和船事准备分类账,使注重风险的完成情况摘要加起来 `final-report.md`。 。 。 . |

![Deep research workflow flow](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/deep-research-flow.png)

![Deep review workflow flow](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/deep-review-flow.png)

![Spec review workflow flow](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/spec-review-flow.png)

![Impact review workflow flow](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/impact-review-flow.png)

计划增加正式工作流程。 多数团队应根据其模式建立针对具体项目的工作流程.

## 工作流程板

启动运行后, 打开 `/workflow` 在只读的TUI中检查它。 浏览运行,钻入阶段和任务,并预览任务输出而不离开 Pi.

从运行列表开始 .

![Workflow board: runs list](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/workflow-board-runs.png)

钻入阶段进展.

![Workflow board: stages view](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/workflow-board-stages.png)

考察任务级粉丝出道.

![Workflow board: task list](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/workflow-board-tasks.png)

以其文物输出打开任务细节视图 .

![Workflow board: task detail](https://npmcn.com/package/%40agwab/pi-workflow/docs/assets/readme/workflow-board-task-detail.png)

## 再来

-   [`docs/usage.md`](https://npmcn.com/package/%40agwab/pi-workflow/docs/usage.md) ——指令参考,工作流程解析,运行文物,以及作者规则.
-   [`workflows/README.md`](https://npmcn.com/package/%40agwab/pi-workflow/workflows/README.md) ——捆绑的工作流程说明.

## 运行时间依赖关系

`pi-workflow` 捆绑它需要的运行时间块 :

-   [`@agwab/pi-subagent`](https://github.com/AgwaB/pi-subagent) 启动和跟踪工作流程中所使用的 Pi 子代理工人.
-   [`pi-web-access`](https://github.com/nicobailon/pi-web-access) 提供 `web_search`, (中文(简体) ), `fetch_content`,以及 `get_search_content`; pi- workflow 单独保存仅读的遗产 `code_search` 兼容性.

提供商的兼容性、缓存、拨号以及直接的安保细节 [`docs/usage.md`](https://npmcn.com/package/%40agwab/pi-workflow/docs/usage.md)。 。 。 .

## 常见问题

### @agwab/pi-workflow 是什么？

Pi子剂的工作流程管弦乐\.

### 如何安装 @agwab/pi-workflow？

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

### @agwab/pi-workflow 支持 TypeScript 吗？

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

### @agwab/pi-workflow 支持 ESM 还是 CommonJS？

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

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

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

### @agwab/pi-workflow 可以商用吗？

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

### @agwab/pi-workflow 的下载量有多少？

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

### @agwab/pi-workflow 还在维护吗？

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