pi-workflow v1.1.0：普通个人如何用 Pi Agent 把日常工作流变成可复用的自动化流水线

pi-workflow v1.1.0: How Ordinary Individuals Build Reusable Automated Pipelines with Pi Agent

Tech-Experiment #Pi Agent#工作流编排#AI自动化#OpenRath#个人效率#DAG#开源工具#subagent#研究工作流#代码评审
更新于
🇨🇳 中文

pi-workflow：AgwaB/pi-workflow · npm: @agwab/pi-workflow · v1.1.0 · MIT
OpenRath：Rath-Team/OpenRath · PyPI: openrath · BSD-3-Clause · arXiv: 2606.19409
平台：macOS / Linux（WSL 可用）· 需要 Node.js ≥22.19.0

先说清楚两个东西的关系

OpenRath 是底层框架——把多 Agent 多 Session 运行时变成像 PyTorch 一样的可组合 Python 对象：Session（对话状态流）、Sandbox（执行环境）、Memory（持久记忆）、Tool（工具调用）、Agent（Session 变换层）、Workflow（Agent 组合容器）、Selector（运行时路由器）。

pi-workflow 是建在这套架构之上、专门给 Pi Agent 用的工作流编排扩展：一键安装，自然语言调度，4 个开箱即用的预制流程，支持 JSON 自定义 DAG，全本地缓存，可断点续跑。

普通人用 pi-workflow，不需要理解 OpenRath 的底层设计——但理解它的设计哲学，能帮你想清楚”我的工作流该怎么拆”。

OpenRath 的核心比喻：把 PyTorch 的方式用在 Agent 上

PyTorch 概念OpenRath 对应含义
TensorSession流动的运行时值：有序 chunk、执行位置、lineage
DeviceSandbox工具真正运行的地方：本地进程、云沙箱
ParameterMemory跨次运行持久化的 Agent 状态
FunctionTool模型可见 schema + 运行时行为的可调用操作
nn.LinearAgent把一个 Session 映射到另一个 Session 的可复用层
nn.ModuleWorkflowAgent、工具、Session 变换的可嵌套组合容器
控制流SelectorLLM 驱动的路由器，实现动态 if / while

关键洞察：大多数框架的核心是”Agent 循环”，OpenRath 的核心是”Session”。当一个应用需要多 Agent、多分支、持久记忆、沙箱执行、可追溯 lineage 时，“从 Session 出发”比”从循环出发”更容易扩展。

pi-workflow 安装

# 一键安装（自动安装 /workflow 面板 + workflow-guide skill + execution-router skill）
pi install npm:@agwab/pi-workflow

# 重新加载 Pi
# （安装完按提示 reload 即可）

# 后续更新
pi update npm:@agwab/pi-workflow

4 个开箱即用的预制流程

1. deep-research（深度调研）

最常用。给一个主题或仓库，自动多步骤调研并汇总架构、权衡、核心设计。

# 自然语言方式
Use the bundled deep-research workflow to research this repository and summarize the architecture tradeoffs.

# 精确控制
/workflow run deep-research "研究 Redis 的 Cluster 模式和 Sentinel 模式的架构差异"

个人用法：

  • 学一个新技术栈：/workflow run deep-research "调研 Rust async 运行时 Tokio vs async-std 的设计差异"
  • 评估一个开源项目：/workflow run deep-research "调研 Helix 编辑器和 Neovim 的插件生态差异"
  • 准备一次讨论：/workflow run deep-research "总结 RAG vs Fine-tuning 的适用场景和成本差异"

2. deep-review（深度代码评审）

从多个角度审查当前 diff，不只看表面，会查并发安全、错误处理、测试覆盖等。

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

/workflow run deep-review "审查这次 PR 的 API 设计和错误处理"

个人用法：

  • 提交前自检：/workflow run deep-review "检查我今天的改动有没有安全问题"
  • 学习他人代码：/workflow run deep-review "分析这个开源库的事务处理逻辑"

3. spec-review（规范比对）

把文档/API SPEC 和实现代码、测试对比，找出不一致的地方。

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

/workflow run spec-review "比较 openapi.yaml 和现有接口实现"

个人用法：

  • 接口对齐检查：/workflow run spec-review "对比 PRD 文档和现有功能实现的差距"
  • 文档维护：/workflow run spec-review "检查 README 的快速开始步骤是否还能跑通"

4. impact-review（变更影响评估）

分析一次变更会影响哪些下游模块、测试、调用方。

/workflow run impact-review "评估删除 legacy_auth 模块的影响范围"

个人用法：

  • 重构前评估：/workflow run impact-review "重命名 UserService 会影响多少地方"
  • 依赖升级：/workflow run impact-review "升级 React 18 到 19 的变更影响"

自适应模式：不知道用哪个流程时

# 让 Pi 自己规划、分发、汇总
/workflow dynamic "帮我分析这个项目的技术债，给出优先级排序和改善建议"

动态模式会自动规划任务图、并行分发子任务、汇总结果——适合开放性问题，不需要预先定好阶段。

自定义 JSON DAG：把你的日常流程固化下来

这是 pi-workflow 最有价值的功能：把反复做的工作流写成 JSON，以后一句话触发。

6 种标准阶段类型

类型用途示例
single单步执行，一个 Agent 处理计划、总结、分析
parallel多角度并行，互不依赖同时从安全/性能/可读性审查代码
loop循环直到条件满足反复改进直到通过质量门槛
batch批量分发同类任务对 N 个文件各自做同样的处理
fan-in汇总多路结果合并并行阶段的结论
adaptive动态编排，Pi 自己决定不确定需要几步时

示例：个人周报生成工作流

{
  "schemaVersion": 1,
  "name": "weekly-report",
  "description": "从 Git log、任务记录、Notes 生成周报",
  "defaults": {
    "agent": "researcher",
    "readOnly": true,
    "tools": ["read", "grep", "find", "bash"]
  },
  "artifactGraph": {
    "stages": [
      {
        "id": "collect",
        "type": "parallel",
        "tasks": [
          { "prompt": "汇总本周 git log，按模块分组，提取关键变更", "tools": ["bash"] },
          { "prompt": "读取本周任务记录，提取已完成和未完成项" },
          { "prompt": "读取本周的学习笔记和技术调研记录" }
        ]
      },
      {
        "id": "synthesize",
        "type": "single",
        "dependsOn": ["collect"],
        "prompt": "整合上面三路内容，生成结构化周报：本周完成、下周计划、风险和阻塞、技术沉淀。格式清晰，可直接发给团队。"
      }
    ]
  }
}

保存为项目里的 .pi/workflows/weekly-report.json，以后直接：

/workflow run weekly-report "生成本周技术周报"

示例：发布前检查工作流

{
  "name": "release-check",
  "description": "版本发布前的标准化检查清单",
  "artifactGraph": {
    "stages": [
      {
        "id": "docs-check",
        "type": "single",
        "prompt": "检查 CHANGELOG、README、版本号是否更新，找出不一致"
      },
      {
        "id": "test-check",
        "type": "single",
        "prompt": "检查测试覆盖率，找出最近改动但没有对应测试的部分"
      },
      {
        "id": "dependency-check",
        "type": "single",
        "prompt": "检查 package.json / pyproject.toml 依赖有无已知漏洞，版本是否 pinned"
      },
      {
        "id": "final-verdict",
        "type": "fan-in",
        "dependsOn": ["docs-check", "test-check", "dependency-check"],
        "prompt": "汇总三路检查结果，给出 Go/No-go 决策和必须修复的问题列表"
      }
    ]
  }
}

执行路由决策：不确定用什么方式时

# 让 Pi 帮你决定：直接处理 / 单 Agent / 某个已有 workflow / 新建 workflow
/skill:execution-router decide whether this repository review should use a single-agent pass, deep-review, or a targeted verifier.

workflow-guide 技能帮你创建和验证新工作流定义：

# 创建工作流
/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.

# 自定义已有流程
/skill:workflow-guide customize deep-review for frontend accessibility and UX review.

断点续跑：长任务不怕中断

pi-workflow 的所有执行记录全本地缓存，任务中断后可以恢复：

# 查看当前运行状态
/workflow status

# 恢复中断的运行
/workflow resume <run-id>

# 查看历史运行和产物
/workflow list

个人日常场景地图

场景推荐工作流示例命令
学新技术deep-research/workflow run deep-research "调研 Rust 异步运行时"
写技术文章deep-research + 自定义先调研，再用 custom workflow 写作
提交代码前deep-review/workflow run deep-review "审查今天的改动"
重构评估impact-review/workflow run impact-review "删除旧模块的影响"
写周报自定义 weekly-report/workflow run weekly-report "生成本周报告"
版本发布自定义 release-check/workflow run release-check "v2.1.0 发布前检查"
接手老项目deep-research/workflow run deep-research "调研这个项目的架构和历史决策"

核心判断

pi-workflow 解决的是一个常见的低效问题：每次做类似的事（调研、评审、周报），都要手动拆步骤、粘贴上下文、等结果、再整合——工作的”脚手架”被反复重建。

把这个脚手架固化成 JSON 工作流，每次用一句话触发，结果可复查、可恢复、可改进。这不是”自动化替代思考”，而是”把重复的执行层外包出去，把精力留给判断层”。

对普通个人来说，最实用的起点是：先用 deep-research 和 deep-review 两个开箱即用流程感受效果，然后用 workflow-guide 把自己最频繁的一个重复流程写成 JSON，固化下来。

参考资源

© 2026 Author: Mycelium Protocol

🇬🇧 English

pi-workflow: AgwaB/pi-workflow · npm: @agwab/pi-workflow · v1.1.0 · MIT
OpenRath: Rath-Team/OpenRath · PyPI: openrath · BSD-3-Clause · arXiv: 2606.19409
Platform: macOS / Linux (WSL supported) · Requires Node.js ≥22.19.0

1. Clarifying the Relationship Between the Two

OpenRath is the underlying framework — it turns a multi-Agent, multi-Session runtime into composable Python objects in the style of PyTorch: Session (conversation-state stream), Sandbox (execution environment), Memory (persistent memory), Tool (tool calls), Agent (Session transformation layer), Workflow (Agent composition container), and Selector (runtime router).

pi-workflow is the workflow orchestration extension built on top of this architecture, designed specifically for Pi Agent: one-command install, natural-language scheduling, 4 ready-to-use prebuilt pipelines, JSON-defined custom DAGs, full local caching, and resumable execution.

Ordinary users of pi-workflow don’t need to understand OpenRath’s underlying design — but understanding its design philosophy helps you think clearly about “how should I decompose my workflow.”

2. OpenRath’s Core Metaphor: Applying PyTorch’s Approach to Agents

PyTorch ConceptOpenRath EquivalentMeaning
TensorSessionFlowing runtime value: ordered chunks, execution position, lineage
DeviceSandboxWhere tools actually run: local process, cloud sandbox
ParameterMemoryAgent state persisted across runs
FunctionToolA callable with model-visible schema + runtime behavior
nn.LinearAgentA reusable layer that maps one Session to another
nn.ModuleWorkflowNestable composition container for Agents, tools, and Session transforms
Control flowSelectorLLM-driven router implementing dynamic if / while

Key insight: Most frameworks center on the “Agent loop”; OpenRath centers on “Session.” When an application requires multiple Agents, multiple branches, persistent memory, sandboxed execution, and traceable lineage, “starting from Session” scales better than “starting from a loop.”

3. Installing pi-workflow

# One-command install (auto-installs /workflow panel + workflow-guide skill + execution-router skill)
pi install npm:@agwab/pi-workflow

# Reload Pi
# (follow the prompt to reload after installation)

# Future updates
pi update npm:@agwab/pi-workflow

4. The 4 Ready-to-Use Prebuilt Pipelines

1. deep-research

The most commonly used pipeline. Give it a topic or repository; it automatically conducts multi-step research and summarizes architecture, tradeoffs, and core design.

# Natural language
Use the bundled deep-research workflow to research this repository and summarize the architecture tradeoffs.

# Precise control
/workflow run deep-research "研究 Redis 的 Cluster 模式和 Sentinel 模式的架构差异"

Personal use cases:

  • Learning a new tech stack: /workflow run deep-research "调研 Rust async 运行时 Tokio vs async-std 的设计差异"
  • Evaluating an open-source project: /workflow run deep-research "调研 Helix 编辑器和 Neovim 的插件生态差异"
  • Preparing for a discussion: /workflow run deep-research "总结 RAG vs Fine-tuning 的适用场景和成本差异"

2. deep-review

Reviews the current diff from multiple perspectives — not just surface-level, but also concurrency safety, error handling, test coverage, and more.

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

/workflow run deep-review "审查这次 PR 的 API 设计和错误处理"

Personal use cases:

  • Pre-commit self-check: /workflow run deep-review "检查我今天的改动有没有安全问题"
  • Learning others’ code: /workflow run deep-review "分析这个开源库的事务处理逻辑"

3. spec-review

Compares documentation/API specs against the implementation and tests to surface inconsistencies.

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

/workflow run spec-review "比较 openapi.yaml 和现有接口实现"

Personal use cases:

  • Interface alignment check: /workflow run spec-review "对比 PRD 文档和现有功能实现的差距"
  • Documentation maintenance: /workflow run spec-review "检查 README 的快速开始步骤是否还能跑通"

4. impact-review

Analyzes which downstream modules, tests, and callers are affected by a given change.

/workflow run impact-review "评估删除 legacy_auth 模块的影响范围"

Personal use cases:

  • Pre-refactor assessment: /workflow run impact-review "重命名 UserService 会影响多少地方"
  • Dependency upgrades: /workflow run impact-review "升级 React 18 到 19 的变更影响"

5. Adaptive Mode: When You’re Unsure Which Pipeline to Use

# Let Pi plan, dispatch, and aggregate on its own
/workflow dynamic "帮我分析这个项目的技术债，给出优先级排序和改善建议"

Dynamic mode automatically plans the task graph, dispatches sub-tasks in parallel, and aggregates results — suited for open-ended problems where you don’t need to define stages upfront.

6. Custom JSON DAGs: Locking Down Your Daily Workflows

This is pi-workflow’s most valuable feature: codify recurring workflows as JSON, then trigger them with a single sentence.

6 Standard Stage Types

TypePurposeExample
singleSingle-step execution, handled by one AgentPlanning, summarization, analysis
parallelMultiple perspectives in parallel, independent of each otherSimultaneously review code for security, performance, and readability
loopRepeat until a condition is metIteratively improve until a quality gate passes
batchDistribute the same task across N itemsApply the same processing to N files individually
fan-inAggregate results from multiple streamsMerge conclusions from parallel stages
adaptiveDynamic orchestration, Pi decidesWhen you’re unsure how many steps are needed

Example: Personal Weekly Report Workflow

{
  "schemaVersion": 1,
  "name": "weekly-report",
  "description": "从 Git log、任务记录、Notes 生成周报",
  "defaults": {
    "agent": "researcher",
    "readOnly": true,
    "tools": ["read", "grep", "find", "bash"]
  },
  "artifactGraph": {
    "stages": [
      {
        "id": "collect",
        "type": "parallel",
        "tasks": [
          { "prompt": "汇总本周 git log，按模块分组，提取关键变更", "tools": ["bash"] },
          { "prompt": "读取本周任务记录，提取已完成和未完成项" },
          { "prompt": "读取本周的学习笔记和技术调研记录" }
        ]
      },
      {
        "id": "synthesize",
        "type": "single",
        "dependsOn": ["collect"],
        "prompt": "整合上面三路内容，生成结构化周报：本周完成、下周计划、风险和阻塞、技术沉淀。格式清晰，可直接发给团队。"
      }
    ]
  }
}

Save it as .pi/workflows/weekly-report.json in your project, then trigger it anytime with:

/workflow run weekly-report "生成本周技术周报"

Example: Pre-Release Check Workflow

{
  "name": "release-check",
  "description": "版本发布前的标准化检查清单",
  "artifactGraph": {
    "stages": [
      {
        "id": "docs-check",
        "type": "single",
        "prompt": "检查 CHANGELOG、README、版本号是否更新，找出不一致"
      },
      {
        "id": "test-check",
        "type": "single",
        "prompt": "检查测试覆盖率，找出最近改动但没有对应测试的部分"
      },
      {
        "id": "dependency-check",
        "type": "single",
        "prompt": "检查 package.json / pyproject.toml 依赖有无已知漏洞，版本是否 pinned"
      },
      {
        "id": "final-verdict",
        "type": "fan-in",
        "dependsOn": ["docs-check", "test-check", "dependency-check"],
        "prompt": "汇总三路检查结果，给出 Go/No-go 决策和必须修复的问题列表"
      }
    ]
  }
}

7. Execution Routing: When You’re Unsure Which Approach to Use

# Let Pi decide: handle directly / single Agent / an existing workflow / create a new workflow
/skill:execution-router decide whether this repository review should use a single-agent pass, deep-review, or a targeted verifier.

The workflow-guide skill helps you create and validate new workflow definitions:

# Create a workflow
/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.

# Customize an existing pipeline
/skill:workflow-guide customize deep-review for frontend accessibility and UX review.

8. Checkpoint Resume: Long Tasks Survive Interruptions

All pi-workflow execution records are fully cached locally, allowing interrupted tasks to be resumed:

# Check current run status
/workflow status

# Resume an interrupted run
/workflow resume <run-id>

# View run history and artifacts
/workflow list

9. Personal Daily Scenario Map

ScenarioRecommended WorkflowExample Command
Learning a new technologydeep-research/workflow run deep-research "调研 Rust 异步运行时"
Writing a technical articledeep-research + customResearch first, then use a custom workflow for writing
Before committing codedeep-review/workflow run deep-review "审查今天的改动"
Refactoring assessmentimpact-review/workflow run impact-review "删除旧模块的影响"
Writing a weekly reportcustom weekly-report/workflow run weekly-report "生成本周报告"
Version releasecustom release-check/workflow run release-check "v2.1.0 发布前检查"
Taking over a legacy projectdeep-research/workflow run deep-research "调研这个项目的架构和历史决策"

10. Core Assessment

pi-workflow solves a common inefficiency: every time you do something similar — research, review, weekly report — you manually break it into steps, paste context, wait for results, and integrate them again. The “scaffolding” of the work gets rebuilt from scratch each time.

Codify that scaffolding into a JSON workflow, trigger it with a single sentence, and results are reviewable, resumable, and improvable. This is not “automation replacing thought” — it is “outsourcing the repetitive execution layer so your attention stays at the judgment layer.”

For ordinary individuals, the most practical starting point is: try the deep-research and deep-review out-of-the-box pipelines to feel the effect, then use workflow-guide to write your single most-repeated workflow as JSON and lock it in.

References

© 2026 Author: Mycelium Protocol

相关文章

Tech-Experiment

Humanizer-zh 拆解：中文「去 AI 味」Skill 今天整体重写，我用同一段文字跑了 12 次对照
Tech-Experiment

OpenFlowKit 拆解：一个真在维护的开源画图 SPA，能被 Claude 直接调用
Tech-Experiment

Lieflat Charts 实测：一套遵循 Agent Skills 格式的数据可视化 skill，但"开源"这个词用错了

💬 评论与讨论

使用 GitHub 账号登录后发表评论

关于本站 · 免责声明

🍄 Mushroom Research Blog 是非营利、免费公开的个人科技观察博客与公众号 XStack18，不接受商业合作、不代表任何企业或机构立场，也不谋求商业利益。我们以个人视角客观中立地记录和分析 AI、Web3 等领域的最新模型发布与技术动态——不止转述新闻标题或二手信息，而是给出有独立思考的深入分析，希望帮更多人获得有价值的一手科技认知。

⚠️ 文中介绍的开源代码与模型，仅供学习交流与技术借鉴。它们大多仍处于早期阶段，有待进一步研究和验证，请勿直接用于工作或生产环境；如需采用，请先自行充分测试，并核实其许可证与安全性。
Open-source code and models featured here are shared for learning and reference only. Most are early-stage and still need further study and verification — please don't use them directly in your work or in production. Test them thoroughly and check their licenses and security first.

  1. 本站文章均为作者基于公开信息的个人研究与观点整理，不代表文中提及的任何公司、产品、模型的官方立场，未与其构成商业关联或合作关系。
  2. 科技行业信息更新极快，我们尽力保证内容准确、及时，但不对完整性、实时性做绝对保证，具体请以相关企业/项目官方公告为准。
  3. 文中引用的第三方商标、产品名称、图片、数据等版权归原权利人所有，我们会尽量注明来源；如你认为存在版权疑问或侵权，请通过下方邮箱联系我们，收到通知后会尽快核实处理（更正、加注来源或删除）。
  4. 文章内容仅为技术科普与个人观点，不构成投资、法律或其他专业建议，据此进行任何决策的后果需自行判断和承担。

📮 侵权 / 勘误 / 合作咨询：hello@mushroom.cv