# @blackbelt-technology/pi-flows 中文文档

规范地址：https://npmcn.com/package/%40blackbelt-technology/pi-flows/

版本：0\.10\.0
npm 元数据更新时间：2026-11-04T10:36:40.579Z
中文译文更新时间：2026-11-08T05:46:50.942Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：715 kB，84 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：typebox ^1\.3\.7，@earendil-works/pi-ai \>=0\.84\.1 \<2\.0\.0，@earendil-works/pi-tui \>=0\.84\.1 \<2\.0\.0，@earendil-works/pi-coding-agent \>=0\.84\.1 \<2\.0\.0
- 首次发布：2026-05-16T14:51:32.517Z
- 最新版本发布：2026-11-04T10:36:40.024Z
- 近 30 天下载量：3069（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

Pi 的流程引擎、仪表板和管线扩展

## 安装

```sh
npm install @blackbelt-technology/pi-flows
```

也可以使用：`pnpm add @blackbelt-technology/pi-flows`、`yarn add @blackbelt-technology/pi-flows`、`bun add @blackbelt-technology/pi-flows`

## README

# pi- 流量

[![CI](https://github.com/BlackBeltTechnology/pi-flows/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/BlackBeltTechnology/pi-flows/actions/workflows/ci.yml)

将多剂工作流程管弦乐添加到 pi 的 pi- package. 设计为YAML DAGs,以自动并列排程运行,并用活的TUI仪表盘观看一切——而主会话则保持完全交互.

* * *

## 概览

流动是 **可重复使用的工作流程模板** 通过结构化投入和产出协调多个AI代理商. 每个代理运行在一个孤立的会话中,带有范围化工具和文件系统访问.

**最佳做法:**

-   **研究 计划 执行 核查** 周期
-   **代码审查** 有核查/固定环路的管道
-   **文档生成** 包含多领域研究
-   **正在重构** 具有交互式分支

## 安装

```bash
pi install npm:pi-flows
```

或来自本地克隆人:

```bash
pi install /path/to/pi-flows
```

### Anthropic OAuth( 订阅) 模型

pi-flows不使用Anthropic特有的即时或电线处理. 流程代理获得pi的默认系统即时加上代理即时,工具保留其平面pi名. 当Claude订阅需要系统及时调整时, Pi-agent-dashboard 处理它: 它通过 `flow:register-agent-extension`,该扩展重写提示区域 `before_agent_start`. pi-流量不再装入 `pi-anthropic-messages`。 。 。 .

## 快速启动

1.  **创建代理** (单位:千美元)`.pi/flows/agents/reviewer.md`:
    
    ```markdown
    ---
    name: reviewer
    description: Reviews code for quality issues
    model: anthropic/claude-sonnet-4-5
    tools: read, grep, find
    inputs:
      - target_path
    ---
    Review the code for: ${{task}}
    Focus on: ${{input.target_path}}
    ```
    
2.  **创建流程** (单位:千美元)`.pi/flows/flows/review/flow.yaml`:
    
    ```yaml
    name: review
    description: Research then review code
    task_required: true
    task_prompt: "What should I review?"
    
    steps:
      - id: research
        agent: project-context-reader
        task: Investigate the codebase for ${{task}}
    
      - id: review
        agent: reviewer
        blockedBy: [research]
        inputs:
          target_path: "${{result.research.summary}}"
        task: Review based on research findings
    ```
    
3.  **运行它:**
    
    ```
    /review Fix the auth middleware
    ```
    

## 命令和密钥绑定

| 命令 | 说明 |
| --- | --- |
| `/flows` | 列出和管理流量( 运行, 删除) |
| `/skill:manage-flows` | 装入流程/代理创建和编辑参考技能 |
| `/flows:delete` | 删除流程 |
| `alt+a` | 切换自动路由( 代理自动决定分叉分支) |
| `alt+x` | 中止运行中的流程/ 丢弃流程摘要 |
| `alt+o` | 检查代理(进入仪表板/摘要导航模式) |
| `alt+t` | 在代理- 细节上切换思维 |

密钥绑定在 `alt+<letter>` 避免与 pi相撞的命名空间 `ctrl+<letter>` 默认值,可通过 `~/.pi/agent/keybindings.json`。 。 。 .

流程还登记为基于目录路径的斜线命令 : `.pi/flows/flows/review/flow.yaml` → `/review`每个流动都是自成一体的目录——它的 `flow.yaml` 加上任何位于同一地点的代码-节点处理器(`<id>.ts`) (中文(简体) ).

## 核心概念

-   **探员** —— 有 YAML 前事( 配置) 和正文( 系统提示) 的 Markdown 文件 。 在孤立的会话中运行,并带有范围工具和文件访问.
-   **流量** —— YAML 文件定义连接步骤的 DAG `blockedBy`。引擎平行地安排独立的步骤,直到 `max_concurrent`。 。 。 .
-   **模板变量** —— 说 `${{task}}`, (中文(简体) ), `${{result.step-id.summary}}`, (中文(简体) ), `${{input.name}}` 发送时台阶之间的有线数据.
-   **模型** —— 说 `model:` 是可选的:字面模型,可选 `@name` 化名(由安装的 `model:resolve` 解析器,如 pi-agent-dashboard, 命令列表, 或无。 不可解别名回落到会话模式.
-   **设置** (单位:千美元)`.pi/settings.json`,项目覆盖全球)—— `flows.modelFallback`数字 : `"session"` (违约)或 `"error"`· ; `flows.decisionAgent`: 用于不自行决定步骤的剂 `agent:` (流量) `decision_agent:` 赢得它; `flows.decider`:默认决定链,例如. `["system-one", "agent"]` (见 `docs/flows.md`) (中文(简体) ).
-   **编辑流量** 在主会话中使用 `flow_agents` 财务报告和审定财务报表 `flow_write` 工具。 这些工具默认关闭; 允许每个项目使用(`/flows:edit-mode on`,或 `flows.editFlow: true` 内 `.pi/settings.json`或全球(`~/.pi/agent/settings.json`) (中文(简体) ). 设置是每个回合重读, 并控制模型是否看到包 `manage-flows` 技术。 pi- flows 从不写入 repo, 除非您明确切换编辑模式 。 装入 `/skill:manage-flows` 格式参考.

## 写入代理

探员是 `.md` 文件在 `.pi/flows/agents/` (项目-当地), `~/.pi/agent/flows/agents/` (用户级别,所有项目;流量进入) `~/.pi/agent/flows/flows/`; 工程覆盖用户)或软件包 `agents/` 目录.

```markdown
---
name: backend-dev
description: Implements backend changes
model: anthropic/claude-sonnet-4-5
thinking: high
tools: read, write, edit, grep, bash
inputs:
  - research_context
outputs:
  - verdict
access:
  read: ["src/**"]
  write: ["src/main/**"]
  bash:
    deny: ["rm -rf"]
card:
  label: "Backend Dev"
  metric: developer
---
You are a backend developer. Task: ${{task}}
Context: ${{input.research_context}}
```

**关键字段 :** `model` (作用层次), `tools` (allolllaylast - 警卫挡住其他一切), `inputs`编号 :`outputs` (类型数据流动), `access` (文件系统沙盒), `card` (TUI仪表板渲染).

## 写入流程

### 步骤类型

每个步骤都明确宣布 `type:` (解说者不推出. 有五个: `agent`, (中文(简体) ), `fork`, (中文(简体) ), `agent-decision`, (中文(简体) ), `code`, (中文(简体) ), `code-decision`。 。 。 .

**探员** 派遣一个指定代理人,任务是:

```yaml
- id: impl
  type: agent
  agent: backend-dev
  blockedBy: [research]
  inputs:
    research_context: "${{result.research.summary}}"
```

**叉头** ——向用户(或让代理以自动路由模式决定)提出选择:

```yaml
- id: choose
  type: fork
  question: "Which approach?"
  options: [Quick fix, Full refactor]
  branches:
    Quick fix: quick-step
    Full refactor: refactor-step
  agent: flow-decision    # used when alt+a (AUTO) is active
```

**代理决定** - 代理电话 `finish({ branch })` 到路由;指向更早一步的分支是一个环(由 `max_iterations`:

```yaml
- id: verify-loop
  type: agent-decision
  agent: flow-decision
  task: "Check iteration ${{loop.verify-loop.iteration}}/${{loop.verify-loop.max}}"
  branches:
    fix: fixer        # backward target → loops
    done: done        # forward target → exits
  max_iterations: 3   # required when a branch points backward
```

**代码** ——以节点(无 LLM)方式运行决定性的 TypeScript 处理器 :

```yaml
- id: validate
  type: code
  inputs:
    invoice: "${{result.extract.canonical}}"
  outputs:
    - name: valid
  blockedBy: [extract]
```

**代码决定** a 包括: `code` 返回路线的节点 `branch` (≥2个分行):

```yaml
- id: route
  type: code-decision
  inputs:
    valid: "${{result.validate.valid}}"
  branches:
    approve: finalize
    reject: notify
```

## 输入线

步骤通过数据 `inputs` + 模板变量 :

```yaml
- id: researcher
  agent: researcher
  task: Investigate ${{task}}

- id: developer
  agent: developer
  blockedBy: [researcher]
  inputs:
    context: "${{result.researcher.summary}}"
    spec_path: specs/api-spec.md    # pass a path; the agent reads it via its `read` tool
```

代理机的快速引用输入为 `${{input.context}}`在代理前题中申报的已打入的输出(`outputs:`)可读取为: `${{result.step-id.outputName}}` 并且作为全值参考物被接线时作为真正的JSON类型交付给代码-节点处理器. 文件备份数据作为路径传递,并在运行时读取(将消耗代理给 `read` ——没有 `file://` 内容注入.

## TUI 盘

当流量运行时,在网格布局中会出现带有代理卡的活盘. 每张卡都显示状态,经过时间,以及特定域的度量标准(文件被修改,测试通过等). 以箭头键导航,扩展代理细节视图,并查看完成后的全部流量摘要.

卡片类型(`card.metric`: `developer`, (中文(简体) ), `researcher`, (中文(简体) ), `tester`, (中文(简体) ), `verifier`, (中文(简体) ), `writer`, (中文(简体) ), `default` -或通过下列方式登记自定义渲染器: `flow:register-card`。 。 。 .

## 与 Pi- agent- dashboard 合并

pi- flows 是 (pi- flows ) (pi-flows is the **引擎**。浏览器仪表板渲染流出事件 [`pi-agent-dashboard`](https://github.com/BlackBeltTechnology/pi-agent-dashboard) 作为单独的工作空间插件( e)`packages/flows-plugin/`) (中文(简体) ). 两个回放是故意分割的: pi-flows 发出 `flow:*` 事件;仪表板对此作出反应.

见 [`docs/dashboard-integration.md`](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/dashboard-integration.md) 用于架构图,线-protocol桥,以及如何添加新流事件端到端.

## 内设特工

| 探员 | 作用 | 说明 |
| --- | --- | --- |
| `flow-decision` | 路由器 | 制作分行/滚动决定叉和循环步骤 |
| `project-context-reader` | 研究员 | 阅读和总结项目结构 |

## 开发者 Docs

详细文件 `docs/` 文件夹 :

-   [参考文献](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/flows.md) – 有语法和实例的完整步骤类型参考
-   [代理人](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/agents.md) - 代理前题计划、型号等级、牌型
-   [流程写入](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/flow-authoring.md) – 代理和流程文件的完整格式引用
-   [建筑](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/architecture.md) ——内部设计:DAG执行,代理隔离,子扩展
-   [事件 API](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/events-api.md) ——注册自定义卡,工具,并收听流出事件
-   [公共 API](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/public-api.md) ——方案使用的核心类型和功能
-   [技能和扩展](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/skills-and-extensions.md) - 技能包和扩展登记
-   [工具参考](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/tools-reference.md) - 特工可用的内置工具
-   [创建软件包](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/creating-packages.md) ——用自定义代理和流量构建域包
-   [扩展 pi 流量](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/extending-pi-flows.md) - 高级定制
-   [板板集成](https://npmcn.com/package/%40blackbelt-technology/pi-flows/docs/dashboard-integration.md) – Pi- 流量和 Pi- agent- dashboard 连接方式

## 释放

释放是自动通过 `.github/workflows/publish.yml`。两种途径:

**工作流程调度(建议).** 打开 GitHub 动作 UI, 运行 `Release` 工作流程,键入版本(如. `0.2.2`) (中文(简体) ). 工作流程起伏 `package.json`,日期匹配 `## [Unreleased]` (或未注明日期) `## [X.Y.Z]`) 节入 `CHANGELOG.md` 改为 `## [vX.Y.Z] - <today>`,承诺,标签,推,然后发布到 npm [来源](https://docs.npmjs.com/generating-provenance-statements) 通过 npm 信任出版,并与 ChangeGELOG 机构起草 GitHub 发行版.

**塔克按键.** 本地键入版本 + 变换组、 承诺、 标记 `vX.Y.Z`,以及 `git push --follow-tags`。同一出版物+发布工作起火.

在第一次发布之前,确保:

1.  Npm 软件包 `@blackbelt-technology/pi-flows` 有一个 [信任的出版商](https://docs.npmjs.com/trusted-publishers) 配置指向此 repo + `publish.yml` +该 `npm-publish` 环境.
2.  一个 GitHub 仓库环境 `npm-publish` 存在(地址 = 环境)。 如果您想要在每次发布前有一个手动闸门, 请在此添加需要的审查者规则 .

准备您的更改条目 `## [Unreleased]` 在触发工作流程之前——标题定时步骤重写到位.

见 `docs/releasing.md` 操作员运行本.

## 许可证

麻省理工学院

## 常见问题

### @blackbelt-technology/pi-flows 是什么？

Pi 的流程引擎、仪表板和管线扩展

### 如何安装 @blackbelt-technology/pi-flows？

在项目目录运行 npm install @blackbelt-technology/pi-flows，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（^1\.3\.7）、@earendil-works/pi-ai（\>=0\.84\.1 \<2\.0\.0）、@earendil-works/pi-tui（\>=0\.84\.1 \<2\.0\.0）、@earendil-works/pi-coding-agent（\>=0\.84\.1 \<2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @blackbelt-technology/pi-flows 支持 TypeScript 吗？

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

### @blackbelt-technology/pi-flows 支持 ESM 还是 CommonJS？

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

### @blackbelt-technology/pi-flows 可以商用吗？

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

### @blackbelt-technology/pi-flows 的下载量有多少？

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

### @blackbelt-technology/pi-flows 还在维护吗？

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