wicttor/pwrl

PWRL 计划 — 纯技能编排器

创建可持久化的实施计划，供后续执行。编排一个确定性的微技能管道：范围界定 → 研究 → 设计 → 生成。无代理依赖，无回退路径。

目的

计划在执行前捕捉决策、结构和实现方法。它们能够实现：

• 清晰的范围和成功标准
• 已识别的风险和依赖关系
• 具体的实施单元及验收标准
• 通过相关学习实现知识重用
• 确保工作不会偏离轨道的信心

核心工作流：四阶段管道

输入（任务描述）
  ↓
阶段 1：范围界定 (pwrl-plan-scope)
  → 收集上下文，验证领域，引导需求
  → 输出：已界定范围的上文工件
  ↓
阶段 2：研究 (pwrl-plan-research)
  → 发现模式，识别风险，推荐外部研究
  → 输出：研究发现工件
  ↓
阶段 3：设计 (pwrl-plan-design)
  → 分解为单元，映射依赖关系，评估复杂度
  → 输出：带有单元分解的设计工件
  ↓
阶段 4：生成 (pwrl-plan-generate)
  → 选择层级，渲染计划，嵌入学习内容，保存至 docs/plans/
  → 输出：保存到文件的最终计划文档
  ↓
输出（可供执行的计划文件）

阶段详情

阶段 1：范围界定 (pwrl-plan-scope)

目的： 规划工作流的入口点。收集上下文，检查现有计划和学到的知识，验证领域，并返回一个已界定范围的上文对象。

微技能： pwrl-plan-scope

输入：

• 用户提供任务描述、需求文档或目标
• 空输入提示用户：“你想计划什么？”

处理过程：

1. 在 docs/plans/ 中检查现有计划；建议继续/审查/存档/删除/新建
2. 验证领域（软件 vs. 非软件）
3. 引导问题框架、预期行为、成功标准
4. 搜索 docs/learnings/INDEX.md 以寻找相关学习
5. 搜索 docs/requirements/ 和 docs/brainstorms/ 以查找匹配文档
6. 向用户确认上下文
7. 询问交互模式
   • 详细模式： 每个阶段逐步交互（审查、确认、调整）
   • Yolo 模式： 从阶段 1 到阶段 4 全自动，仅在最后确认
8. 生成带有交互模式的界定了范围的上文工件

输出： 已界定范围的上文工件，包含：

• 问题框架、预期行为、成功标准
• 相关学习内容（高相关性）
• 识别出的学习缺口
• 已找到的需求
• 交互模式（详细或 yolo）

参见： 详细工作流请参考 pwrl-plan-scope/SKILL.md

阶段 2：研究 (pwrl-plan-research)

目的： 发现本地模式、技术栈和高风险区域。如有需要，推荐外部研究。

微技能： pwrl-plan-research

输入： 来自阶段 1 的已界定范围的上文工件

处理过程：

1. 从 package.json、Dockerfile、代码库结构中检测技术栈
2. 发现本地模式（架构、异步风格、测试、组织）
3. 识别高风险区域（安全、性能、迁移、分布式系统、合规）
4. 为高风险区域推荐外部研究（可选）
5. 整合来自相关学习内容的见解
6. 编译研究发现

输出： 研究工件，包含：

• 技术栈检测
• 识别出的本地模式
• 风险区域及建议
• 外部研究发现（如果已执行）
• 学习内容整合说明

参见： 详细工作流请参考 pwrl-plan-research/SKILL.md

阶段 3：设计 (pwrl-plan-design)

目的： 将工作分解为实施单元，识别依赖关系和风险，评估复杂度。

微技能： pwrl-plan-design

输入： 已界定范围的上文工件 + 研究发现

处理过程：

1. 根据成功标准和风险区域识别工作单元
2. 映射单元间的依赖关系（拓扑排序）
3. 检测循环依赖；提示重构
4. 创建风险缓解单元
5. 为复杂工作流（5 个单元以上）生成 Mermaid 图表
6. 评估复杂度（低/中/高）
7. 预估工作量
8. 向用户确认分解方案

输出： 设计工件，包含：

• 实施单元（U1, U2, ..., UX），附带测试场景和验收标准
• 依赖关系图和拓扑顺序
• 风险缓解措施
• Mermaid 图表（如果复杂）
• 复杂度评估和工作量预估

参见： 详细工作流请参考 pwrl-plan-design/SKILL.md

阶段 4：生成 (pwrl-plan-generate)

目的： 选择层级（快速/标准/深度），使用层级模板渲染计划，嵌入学习内容，保存至 docs/plans/。

微技能： pwrl-plan-generate

输入： 设计工件（来自阶段 3）+ 范围界定工件（来自阶段 1）

处理过程：

1. 根据复杂度/单元数/工作量自动选择层级；若不明确则提示用户
   • 快速： 低复杂度，1-3 个单元，<5 小时
   • 标准： 中等复杂度，4-8 个单元，5-20 小时
   • 深度： 高复杂度，9 个以上单元，20 小时以上
2. 使用层级特定模板渲染计划
3. 从范围中嵌入排名前 3-5 的高相关性学习内容
4. 生成唯一文件名：YYYY-MM-DD-NNN-<slug>.md
5. 处理文件名冲突（递增序号或更新现有文件）
6. 将计划保存到 docs/plans/

输出： 计划文档保存到文件，包含：

• 问题与范围
• 成功标准
• 实施单元（层级特定详细程度）
• 风险分析（标准/深度）
• 相关学习内容（标准/深度）
• 学习缺口（深度）
• 发布说明（标准/深度）

参见： 详细工作流请参考 pwrl-plan-generate/SKILL.md

规划层级

层级	最适合场景	文件数	风险	时间
快速	错误修复、小幅调整	1-3	低	5-15 分钟
标准	大多数功能	4-8	中	30-45 分钟
深度	架构、安全、迁移	9 以上	高	1-2 小时

参见 references/planning-tiers.md 了解完整的层级决策标准和模板示例。

核心原则

• 确定性管道： 阶段始终按顺序执行：范围界定 → 研究 → 设计 → 生成（无分支，无回退）
• 聚焦决策： 捕捉方法、结构、风险和顺序（而非模拟代码）
• 适当规模： 小任务 → 简短计划；复杂工作 → 更多结构
• 将规划与执行分离： 不要在规划期间模拟实现
• 具体明确： 使用具体的文件、组件和依赖关系
• 保持可移植性： 仅使用仓库相对路径
• 工件透明： 每个阶段为下一阶段产生明确的输出工件

错误处理与恢复

哲学： 显式失败，而非静默失败。每个阶段都有清晰的错误处理及恢复建议。

阶段 1（范围界定）错误

• 空输入： 提示用户输入任务描述；重试
• 非软件领域： 返回错误；建议使用其他工具
• 模糊输入： 提出澄清性问题；根据用户回答引导
• 未找到学习内容/需求： 继续执行（非错误）

恢复： 用户可以重试、提供澄清或中止

阶段 2（研究）错误

• 代码库分析失败： 以最少的技术栈信息继续执行
• 识别出高风险区域： 推荐外部研究；用户可以批准或跳过

恢复： 用户可以批准研究、跳过或手动调查

阶段 3（设计）错误

• 检测到循环依赖： 报告循环路径；提示用户重构
• 单元过多（15 个以上）： 警告复杂度；建议合并
• 细节不足： 提示添加测试场景或拆分单元

恢复： 用户可以重构、合并或在知情情况下继续

阶段 4（生成）错误

• 文件名冲突： 提供选项：更新、递增或取消
• 层级选择不明确： 提示用户选择层级
• 文件写入失败： 检查权限/目录；重试或建议手动保存

恢复： 用户可以选择操作或手动保存

关键输出

每个计划包含（依层级而定）：

• 问题与范围： 清晰的问题框架和预期行为
• 成功标准： 1-3 个具体的完成条件
• 实施单元： 具有依赖关系、文件、方法和验收标准的命名 U-ID
• 相关学习内容： 带有适用性说明的链接学习文件（标准/深度）
• 学习缺口： 需要实施后文档记录的领域（深度）
• 层级特定章节： 风险分析、备选方案、发布说明（标准/深度）

交互方式

• 对所有决策使用平台的 ask_user_questions 扩展
• 一次只问一个问题
• 尽可能使用多项选择题
• 如果输入为空，询问：“你想计划什么？请描述任务或项目。”
• 当出现错误时，提供清晰的恢复建议

架构：无代理路由

与之前版本的区别：

之前： 技能检测代理是否可用，然后要么委派给代理，要么运行单体回退（两条代码路径）

之后： 技能按顺序直接调用微技能——单一确定性管道，无分支：

pwrl-plan 编排器
├── 1. 调用 pwrl-plan-scope → 获取范围界定工件
├── 2. 调用 pwrl-plan-research → 获取研究工件
├── 3. 调用 pwrl-plan-design → 获取设计工件
└── 4. 调用 pwrl-plan-generate → 保存计划文件

优势：

• ✅ 更易于理解（单一代码路径）
• ✅ 更易于测试（无分支逻辑）
• ✅ 更易于维护（微技能可独立测试）
• ✅ 更易于组合（微技能可在其他工作流中重用）
• ✅ 更好的错误处理（每个阶段显式处理）

微技能参考

• pwrl-plan-scope — 上下文与范围收集
• pwrl-plan-research — 模式发现与风险识别
• pwrl-plan-design — 单元分解与依赖映射
• pwrl-plan-generate — 计划渲染与文件生成

相关文档

• references/planning-tiers.md — 层级定义与决策标准
• docs/guides/micro-skill-patterns.md — 如何通过新的微技能进行扩展
• docs/guides/skill-architecture-refactoring.md — 重构原理

测试与验证

全面的测试覆盖：

• 30 个以上用于 pwrl-plan-scope 的测试 (U1.1)
• 25 个以上用于 pwrl-plan-research 的测试 (U1.2)
• 35 个以上用于 pwrl-plan-design 的测试 (U1.3)
• 30 个以上用于 pwrl-plan-generate 的测试 (U1.4)
• 30 个以上用于完整编排管道的集成测试

向后兼容性：

• 与之前版本相同的输入/输出行为
• 现有计划成功生成
• 对用户无破坏性更改

常见问题

问：如果某个阶段失败，我可以跳过它或重试吗？

答：可以。每个阶段都有明确的错误处理及恢复建议。你可以重试、提供澄清、修改范围或中止。不会发生静默失败。

问：我能否只使用一个微技能（例如，仅从设计生成）？

答：编排器期望按顺序调用所有四个阶段。如果你想使用单个微技能，请直接通过名称调用它：/pwrl-plan-scope、/pwrl-plan-design 等。

问：为什么没有代理路由？

答：代理增加了不必要的复杂性却未带来价值。微技能管道是确定性的、可测试的且更易于理解。直接调用技能更简单且更易于维护。

问：我可以将此扩展用于其他工作流吗？

答：可以！这些微技能是可重用的。例如，pwrl-work 可以使用 pwrl-plan-design 进行单元分解。参见 docs/guides/micro-skill-patterns.md。

---

状态： 纯技能管道（无代理路由） 版本： 2.0（从依赖代理的架构重构而来） 创建时间： 2026-06-11