# pi-workflow-hub：面向Pi的Ticket驱动工作流管理终端仪表盘 > 一个专为Pi设计的终端工作流管理扩展，以YAML格式的feature文件为唯一数据源，整合tmux会话管理、Skills/MCP状态追踪，提供统一的ticket-first开发体验。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-06-01T06:15:48.000Z - 最近活动: 2026-06-01T06:24:24.854Z - 热度: 154.9 - 关键词: Pi, 工作流管理, tmux, AI辅助开发, Ticket驱动, YAML配置, MCP, Skills, 终端工具, Agent工作流 - 页面链接: https://www.zingnex.cn/forum/thread/pi-workflow-hub-piticket - Canonical: https://www.zingnex.cn/forum/thread/pi-workflow-hub-piticket - Markdown 来源: ingested_event --- ## 原作者与来源 - **原作者/维护者**: masta-g3 - **来源平台**: GitHub - **原始标题**: pi-workflow-hub - **原始链接**: https://github.com/masta-g3/pi-workflow-hub - **发布时间**: 2026年6月 --- ## 背景：AI辅助开发的组织困境 随着大模型编程助手（如Pi、Claude Code、GitHub Copilot Workspace等）的普及，开发者与AI协作的工作模式正在发生深刻变革。传统的项目管理工具——Jira的看板、Linear的issue列表、GitHub Projects的卡片——都是为人类设计的，它们假设任务的执行者是能够自主阅读文档、理解上下文、做出决策的人。 但在AI辅助开发的新范式下，执行者变成了"Agent"——一个需要明确指令、依赖特定上下文、在受控环境中运行的自动化实体。这种转变带来了新的组织挑战： 首先是**上下文碎片化**。一个feature的开发可能涉及多个Pi会话：一个用于初步探索，一个用于具体实现，一个用于代码审查，还有一个用于文档编写。这些会话散落在不同的tmux窗口或终端标签中，难以追踪哪个会话对应哪个任务阶段。 其次是**状态不一致**。项目计划可能记录在Notion或Linear中，实际代码在GitHub上，而AI会话的历史又保存在本地。当计划发生变更时，如何确保所有相关的AI会话都能获得最新上下文？ 第三是**技能漂移**。不同的feature可能需要启用不同的Skills（如数据库迁移Skill、测试生成Skill）或MCP服务器（如PostgreSQL MCP、Stripe MCP）。手动管理这些配置既繁琐又容易出错。 pi-workflow-hub正是为解决这些问题而生。 --- ## 核心理念：Ticket-First工作流 pi-workflow-hub的设计哲学可以用一句话概括：**以YAML为唯一数据源，以Ticket为工作单元，以tmux为执行环境**。 ### YAML作为唯一数据源 项目的所有feature定义存储在`agent-work/features.yaml`中，格式如下： ```yaml - id: docs-001 status: pending description: Document the workflow priority: 1 depends_on: [] created_at: 2026-05-31 completed_at: null epic: docs ``` 每个ticket包含唯一ID、状态、描述、优先级、依赖关系、创建/完成时间戳以及所属的epic。这种设计有几个优势： - **版本可控**：YAML文件可以纳入Git管理，变更历史一目了然 - **人类可读**：开发者可以直接编辑文件，无需学习特定UI - **机器可解析**：CLI工具可以快速读取和更新 - **去中心化**：不依赖任何外部服务，完全本地运行 ### Ticket作为工作单元 每个feature对应一个ticket，每个ticket对应一个（或一组）tmux会话。这种一对一的映射关系解决了上下文碎片化问题——你想继续某个feature的工作？只需`wf-pi open-ticket `，就能自动attach到对应的Pi会话。 ### tmux作为执行环境 选择tmux而非自建守护进程有几个考量： - **成熟稳定**：tmux是历经十几年考验的终端复用器，会话恢复、窗口管理、远程attach等功能开箱即用 - **可观测性**：开发者可以随时attach到会话查看AI的实时输出，也可以随时detach让AI在后台继续 - **可恢复性**：即使系统重启，tmux的session persistence机制也能帮助恢复工作状态 - **生态丰富**：tmux的插件生态、配置选项、快捷键体系都是现成的 --- ## 架构概览 pi-workflow-hub由三个核心组件构成： ### 1. CLI工具（wf-pi） 这是用户的主要交互界面，提供以下功能： | 命令 | 作用 | |------|------| | `wf-pi` | 创建或attach到dashboard tmux会话 | | `wf-pi tui` | 在当前终端直接运行TUI界面 | | `wf-pi doctor` | 诊断项目配置、tmux/Pi可用性、会话状态 | | `wf-pi open-ticket ` | 打开或attach到指定ticket的Pi会话 | | `wf-pi restart-ticket resume/new` | 重启ticket会话（保留历史/全新开始） | | `wf-pi dispatch ` | 向运行中的ticket会话发送工作流指令 | | `wf-pi send ''` | 发送自定义prompt到ticket会话 | ### 2. TUI Dashboard 基于终端的交互式界面，是pi-workflow-hub的"控制中心"。Dashboard按epic分组展示所有ticket，支持键盘导航和快捷操作： | 按键 | 功能 | |------|------| | `↑↓` / `j` / `k` | 在epic内移动选择 | | `←→` | 切换epic | | `c` | 切换已完成ticket的显示/隐藏 | | `p` | 向选中ticket的会话发送单行prompt | | `s` / `m` | 打开Skills/MCP选择器 | | `?` | 显示帮助和状态图例 | | `q` / `Ctrl-C` | 退出dashboard | ### 3. Pi Extension 当通过`pi install npm:pi-workflow-hub --local`安装后，Pi会获得`/wf`命令，可以在Pi会话内部直接调用工作流功能。这实现了"内环"（在Pi里）和"外环"（在terminal里）的无缝切换。 --- ## 工作流阶段设计 pi-workflow-hub定义了一套标准化的工作流阶段（workflow stages），对应软件开发的典型生命周期： - **prime**：初始化阶段，理解需求，建立上下文 - **plan**：制定实施计划，通常输出markdown格式的plan文件 - **execute**：执行计划，编写代码 - **review**：代码审查，检查实现质量 - **reflect**：回顾总结，提取经验教训 - **commit**：提交变更（受保护的操作，需要`--yes`确认） - **blocked**：标记为阻塞，等待外部依赖 - **done**：完成 这些阶段不是强制的，而是提供了一套共享的词汇表。当开发者说"这个ticket在review阶段"时，团队成员都能理解这意味着代码已写但还在审查中。 `wf-pi dispatch`命令允许向运行中的ticket会话发送特定阶段的指令。例如： ```bash wf-pi dispatch feature-123 execute ``` 这会在feature-123对应的Pi会话中触发execute阶段的prompt模板，引导AI继续编码工作。 --- ## Skills与MCP状态管理 一个独特的设计是pi-workflow-hub对Skills和MCP服务器的管理方式。 ### Project-Scoped配置 不同于全局安装Skills/MCP，pi-workflow-hub采用项目级配置。每个项目可以有自己需要的Skills集合和MCP服务器列表。当你打开一个ticket时，系统会自动： 1. 读取项目当前的Skills/MCP配置 2. 将配置快照保存到ticket registry 3. 启动Pi会话时注入这些配置 这意味着不同的ticket可以有不同的能力集。一个处理数据库迁移的ticket可能启用PostgreSQL MCP和SQL Skill，而一个前端feature的ticket则可能启用React Skill和Figma MCP。 ### 配置变更检测 Dashboard会监控项目级Skills/MCP配置的变化。如果检测到变更，会显示"restart to apply"提示。这是因为运行中的Pi会话不会热重载配置——需要重启ticket会话才能生效。这种设计避免了配置漂移带来的不确定性。 --- ## 会话生命周期管理 pi-workflow-hub对tmux会话的管理体现了几项工程智慧： ### 会话持久化 每个ticket的会话数据保存在`agent-work/tickets//`目录下，包括： - 心跳/状态数据 - Pi会话历史（如果配置了持久化） - Skills/MCP配置快照 即使tmux会话意外终止，registry中的元数据也能帮助恢复状态。 ### 会话恢复策略 `restart-ticket`命令提供两种恢复模式： - **resume**：保留之前的Pi会话历史，适合短暂中断后的继续工作 - **new**：全新会话，适合需要重新建立上下文的场景 这种灵活性很重要——有时你想接着上次聊，有时你想"重启试试"。 ### 会话隔离 每个ticket的tmux会话是独立的，这意味着： - 一个ticket的崩溃不会影响其他ticket - 可以并行处理多个ticket（只要你的机器撑得住） - 资源使用可追踪——你可以看到哪个ticket的会话占用了大量内存 --- ## 诊断与可观测性 `wf-pi doctor`命令提供全面的项目健康检查： - **Feature文件有效性**：检查features.yaml的语法和必填字段 - **包文件完整性**：验证pi-workflow-hub自身的安装状态 - **tmux可用性**：确认tmux已安装且功能正常 - **Pi可用性**：检查Pi CLI是否可访问 - **会话状态一致性**：检测registry中有记录但tmux中已不存在的"孤儿"会话 这种自检能力对于维护长期运行的项目至关重要——问题越早发现，修复成本越低。 --- ## 与现有工具的对比 | 维度 | pi-workflow-hub | 传统项目管理工具 | |------|-----------------|----------------| | 数据源 | 本地YAML文件 | 云端数据库 | | 执行环境 | 本地tmux | 无（纯管理） | | AI集成 | 原生支持Pi | 需插件/集成 | | 离线能力 | 完全可用 | 受限 | | 学习曲线 | 中（需了解tmux） | 低（Web UI） | | 可定制性 | 高（代码即配置） | 中（配置界面） | | 协作能力 | 低（单用户） | 高（多用户） | pi-workflow-hub的定位不是替代Jira/Linear，而是填补一个空白：**个人或小团队的AI辅助开发工作流管理**。当你主要与AI协作而非人类同事时，轻量级的本地工具往往比重型云端系统更合适。 --- ## 潜在改进方向 虽然pi-workflow-hub已经实现了核心功能，仍有几个方向值得探索： ### 协作增强 当前设计明显偏向单用户场景。未来的版本可以考虑： - Git-based协作：通过分支和合并解决features.yaml的冲突 - 会话共享：允许团队成员attach到同一个ticket会话（需谨慎处理并发） - 评论/备注：在ticket级别添加人类注释 ### 集成扩展 - **GitHub Integration**：自动同步GitHub Issues与features.yaml - **Linear/Notion Sync**：双向同步，让非技术团队成员也能参与规划 - **CI/CD Hooks**：在ticket状态变更时触发自动化测试或部署 ### AI能力增强 - **智能拆分**：AI自动将大feature拆分为小ticket - **依赖建议**：基于代码分析建议ticket间的依赖关系 - **工作量估算**：结合历史数据估算ticket完成时间 ### 可视化改进 - **Burndown Chart**：在dashboard中显示sprint进度 - **依赖图**：可视化ticket间的依赖网络 - **Heatmap**：显示哪些epic/ticket最近最活跃 --- ## 总结 pi-workflow-hub是一个精心设计的AI辅助开发工作流管理工具。它没有试图成为全能的项目管理平台，而是专注于解决一个具体问题：**如何让开发者在与Pi等AI助手协作时保持条理和效率**。 通过YAML数据源、ticket-first组织、tmux执行环境的三位一体设计，pi-workflow-hub提供了一个轻量级但功能完整的解决方案。对于习惯命令行工作流、重视数据主权、主要与AI而非人类协作的开发者来说，这是一个值得尝试的工具。 项目的文档也非常完善，User Guide、Dashboard Reference、Developer Guide、Structure文档覆盖了从使用到开发的各个层面，体现了维护者对用户体验的重视。