核心功能
pi-workflow 是专为复杂任务设计的结构化工作流编排系统，核心定位在于解决 AI 辅助开发中的三大痛点：上下文窗口污染、重复犯错、质量把控缺失。
显著优点
1. 计划优先机制：强制在3步以上任务或架构决策前进入规划模式，显著降低返工率；遇到偏差立即停止并重新规划，避免"沉没成本谬误"。
2. 子代理策略：通过 liberal 使用 subagents 保持主上下文干净，将研究、探索、并行分析任务外派，用计算资源换认知带宽——这对长上下文模型尤为关键。
3. 自我改进闭环：建立 tasks/lessons.md、tasks/errors.md、tasks/feature_requests.md 三层知识管理，每次用户纠正后自动结构化记录（含 Priority、Status、Area、Pattern-Key 元数据），并通过 Recurrence-Count 追踪模式重复≥3次时自动升优先级。
4. 验证门禁：完成任务前必须证明其工作——对比 diff、运行测试、检查日志、自问"Staff Engineer 会批准吗？"，杜绝"看起来对了"式交付。
5. 优雅性检查（平衡版）：非平凡变更强制暂停反思是否有更优雅方案，但跳过简单修复，防止过度工程。
6. 自主 Bug 修复：接收 bug 报告后直接定位日志/错误/失败测试并解决，零用户上下文切换，甚至主动修复 CI 失败。
潜在局限
- 启动成本：简单任务强制规划可能显得冗余，需用户判断"非平凡"阈值。
- 文件管理负担：
tasks/和memory/目录结构要求自律维护，否则沦为垃圾堆。 - 元数据开销：结构化 lesson 格式字段较多，紧急修复场景下可能被视为阻碍。
- 同步摩擦：workspace → skill 的 lessons 同步需手动执行脚本，易遗忘。
适合人群
- 构建中大型项目的开发者（尤其是架构决策频繁场景）
- 追求"可复盘"开发过程的团队
- 希望降低 AI 助手"重复犯错"频率的重度用户
- 重视代码审查标准、厌恶临时 hack 的工程师
常规风险
- 形式主义陷阱：过度追求 lesson 记录而减缓迭代速度。
- 规划瘫痪：计划阶段过度设计导致迟迟不进入实施。
- 子代理爆炸：未合理控制 subagent 数量导致总成本激增。
- 自检盲区："自问是否优雅"缺乏外部视角，可能陷入确认偏误。
使用建议
建议配合 openclaw hooks enable pi-workflow 开启会话启动提醒，自动提示 lesson/error/feature 记录时机，降低认知负荷。对于2小时内的快速任务，可酌情跳过完整流程，保留核心验证门禁即可。