# pi-workflows：为AI编程助手pi添加工作流编排能力 > pi-workflows是一个扩展插件，为AI编程助手pi带来了工作流编排功能，让开发者可以用简单的JavaScript脚本定义多步骤智能体流水线，并通过TUI界面运行和监控。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-05-16T18:15:40.000Z - 最近活动: 2026-05-16T18:23:04.377Z - 热度: 150.9 - 关键词: AI编程助手, 工作流编排, pi扩展, 智能体流水线, TUI工具, JavaScript工作流, 代码自动化, 多步骤任务 - 页面链接: https://www.zingnex.cn/forum/thread/pi-workflows-aipi - Canonical: https://www.zingnex.cn/forum/thread/pi-workflows-aipi - Markdown 来源: ingested_event --- # pi-workflows：为AI编程助手pi添加工作流编排能力\n\n## AI编程助手的进化：从单轮对话到复杂工作流\n\nAI编程助手已经从简单的代码补全工具，发展成为能够理解项目上下文、执行多步骤任务的智能伙伴。然而，大多数AI助手仍然以"单轮对话"的模式工作——用户提出一个请求，AI给出回应，对话结束。\n\n当面对复杂的开发任务时，这种模式显得力不从心。比如，你可能希望AI能够：\n\n- 先分析代码库结构\n- 然后识别所有需要修改的文件\n- 对每个文件进行分析和修改\n- 最后运行测试验证结果\n\n这种多步骤、有依赖关系的任务，需要一种更结构化的方式来编排AI智能体的执行流程。\n\npi-workflows正是为了解决这一问题而诞生的。\n\n## 项目概述：pi的工作流编排扩展\n\npi（由earendil-works开发）是一个终端UI（TUI）风格的AI编程助手。pi-workflows是它的一个扩展插件，为pi添加了完整的工作流编排能力。\n\n这个扩展的核心价值在于：它让开发者可以用简单的JavaScript（或TypeScript）脚本定义复杂的多步骤AI流水线，然后直接从TUI界面运行、监控和调试这些工作流。\n\n## 核心概念与设计理念\n\npi-workflows的设计遵循几个关键原则：\n\n**阶段化（Phases）**：每个工作流被分解为多个逻辑阶段，如"发现"、"处理"、"报告"。每个阶段代表一个高层次的业务逻辑单元。\n\n**可追踪性**：工作流的每一步执行都会被记录，包括状态（运行中、已完成、失败）、耗时、输出结果等。这让调试和审计变得容易。\n\n**结构化输出**：AI智能体的输出可以通过JSON Schema进行结构化，后续步骤可以直接使用这些结构化数据。\n\n**并发与流水线**：支持在单个阶段内并发处理多个项目，同时保持阶段间的顺序执行。\n\n## 运行时API详解\n\npi-workflows为工作流脚本提供了一个丰富的运行时对象，包含以下核心函数：\n\n### agent(prompt, opts)\n\n这是最基本的智能体调用函数。它会在pi中启动一个子智能体，该智能体拥有完整的工具访问权限（读写文件、执行bash命令、代码搜索等）。\n\n通过可选的schema参数，可以要求智能体返回结构化的JSON输出：\n\n```javascript\nconst files = await agent(\"找出src目录下所有TypeScript文件\", {\n schema: { type: \"array\", items: { type: \"string\" } }\n});\n```\n\n### pipeline(items, ...stages)\n\n流水线函数用于批量处理数据。它将输入数组中的每个项目依次通过多个处理阶段，同一阶段内的项目并行执行，阶段之间顺序执行。\n\n```javascript\nconst results = await pipeline(\n files,\n (file) => agent(`分析 ${file}`),\n (file) => agent(`重构 ${file}`)\n);\n```\n\n### step(name, phase, fn)\n\n对于不需要调用AI智能体的纯本地计算（如数据聚合、格式化），使用step函数包装。这确保了非AI阶段也能被追踪和记录。\n\n```javascript\nconst report = await step(\"生成报告\", \"Report\", async () => {\n return { summary: computeSummary(data) };\n});\n```\n\n### log(message)\n\n在工作流执行过程中显示通知消息，用于向用户反馈进度。\n\n## 工作流定义示例\n\n一个完整的工作流定义包含两部分：元数据（meta）和执行函数。\n\n```javascript\n// .pi/workflows/test-plan.js\nexport const meta = {\n name: \"test-plan\",\n description: \"分析源文件并决定测试策略\",\n phases: [\n { title: \"Discover\", detail: \"发现文件\" },\n { title: \"Analyze\", detail: \"分析每个文件\" },\n ],\n};\n\nexport default async function ({ agent, pipeline, log }) {\n // 阶段1：发现文件\n const files = await agent(\"列出src/目录下所有源文件\", {\n phase: \"Discover\",\n schema: { type: \"array\", items: { type: \"string\" } },\n });\n\n log(`发现 ${files.length} 个文件`);\n\n // 阶段2：分析每个文件\n const plans = await pipeline(\n files,\n (file) => agent(\n `分析 ${file} 并决定：应该测试什么？测试类型？优先级？`,\n {\n phase: \"Analyze\",\n schema: {\n type: \"object\",\n properties: {\n file: { type: \"string\" },\n tests: {\n type: \"array\",\n items: {\n type: \"object\",\n properties: {\n description: { type: \"string\" },\n type: { type: \"string\", enum: [\"unit\", \"integration\"] },\n priority: { type: \"string\", enum: [\"high\", \"medium\", \"low\"] },\n },\n },\n },\n },\n },\n }\n )\n );\n\n return plans;\n}\n```\n\n## 工作流发现与执行\n\npi-workflows支持从多个位置自动发现工作流：\n\n1. `.pi/workflows/` —— 项目本地（向上遍历到git根目录）\n2. `.agents/workflows/` —— 替代位置\n3. `.pi-workflows/` —— 另一个替代位置\n4. `~/.pi/agent/workflows/` —— 全局用户目录\n\n执行工作流非常简单：\n\n```\n/workflow test-plan\n/workflow my-workflow {\"dir\": \"./src\"}\n/workflow list\n```\n\n支持的命令包括：\n- `start` —— 执行工作流（默认）\n- `list` —— 列出可用工作流和最近运行\n- `status` —— 检查运行状态\n- `cancel` —— 取消正在运行的工作流\n\n## 可视化仪表板\n\npi-workflows提供了一个本地Web仪表板，通过运行`/dashboard`命令启动。仪表板以树状结构可视化展示工作流的执行过程：\n\n- 实时显示每个阶段的进度\n- 展示步骤之间的依赖关系\n- 显示每个步骤的状态和输出\n- 支持查看历史运行记录\n\n这种可视化对于理解复杂工作流的执行流程、定位性能瓶颈非常有帮助。\n\n## 技术实现细节\n\npi-workflows的代码结构清晰，分为几个核心模块：\n\n**index.ts**：扩展入口点，注册工具和命令\n**loader.ts**：工作流发现和模块加载\n**runtime.ts**：运行时对象创建（agent、pipeline、log等）\n**store.ts**：运行持久化（JSON文件存储在`.pi-workflows/.runs/`）\n**types.ts**：TypeScript类型定义\n\n项目使用Bun作为运行时，包含39个单元测试，确保核心功能的稳定性。\n\n## 设计约束与最佳实践\n\npi-workflows对工作流的编写有一些约束，这些约束确保了工作流的可追踪性和一致性：\n\n**阶段必须被使用**：在meta.phases中声明的每个阶段，都必须在代码中被引用（通过agent或step）。\n\n**非AI阶段使用step**：如果某个阶段只涉及本地计算，必须用step包装，不能是裸代码。\n\n**阶段名称必须精确匹配**：agent和step中的phase参数必须与meta.phases中的title完全匹配（区分大小写）。\n\n**从运行时解构step**：函数签名应该是`export default async function ({ agent, pipeline, step, log, args })`。\n\n**每个逻辑单元一个阶段**：不要在单个agent或step调用中混合多个阶段。\n\n## 应用场景\n\npi-workflows特别适合以下场景：\n\n**批量代码重构**：分析代码库、识别模式、批量应用修改、运行测试验证。\n\n**测试生成**：分析源文件、确定测试策略、生成测试代码、验证覆盖率。\n\n**文档生成**：扫描代码、提取API信息、生成文档、更新README。\n\n**依赖分析**：分析项目依赖、检查漏洞、生成报告、提出升级建议。\n\n**代码审查**：对PR中的每个文件进行分析、检查风格、提出建议。\n\n## 与类似工具的对比\n\n相比其他AI工作流工具（如LangChain、AutoGPT等），pi-workflows有几个独特之处：\n\n**紧密集成的TUI体验**：作为pi的扩展，它与编程工作流无缝集成，不需要切换上下文。\n\n**简单性**：使用普通JavaScript/TypeScript定义工作流，没有复杂的DSL或配置格式。\n\n**可追踪性**：每个步骤都被记录，便于调试和审计。\n\n**结构化输出**：原生支持JSON Schema，让AI输出可以被后续步骤可靠地使用。\n\n## 局限性与未来方向\n\n目前pi-workflows还处于相对早期的阶段，一些功能有待完善：\n\n- 工作流之间的依赖和组合\n- 更丰富的可视化选项\n- 工作流模板和分享机制\n- 与CI/CD系统的集成\n\n但即使如此，它已经为pi用户提供了一个强大的工具，将AI助手的应用从单轮对话扩展到复杂的多步骤工作流。\n\n## 结语\n\npi-workflows代表了AI编程助手发展的一个重要方向：从被动的问答工具，进化为主动的任务执行伙伴。通过结构化的工作流编排，开发者可以更可靠、更可复现地利用AI能力处理复杂的开发任务。\n\n对于那些已经在使用pi的开发者来说，pi-workflows是一个值得尝试的扩展。它不仅提升了AI助手的实用性，更重要的是，它展示了AI如何以更结构化、更可控的方式融入软件开发流程。\n\n项目地址：https://github.com/umutbasal/pi-workflows