@liangjie559567/ultrapower 5.0.4

package/skills/pipeline/SKILL.md

@@ -0,0 +1,430 @@
+---
+name: pipeline
+description: 将 agent 串联成顺序或分支工作流，支持数据传递
+---
+
+# Pipeline Skill
+
+## 概述
+
+pipeline skill 允许将多个 agent 串联成定义好的工作流，前一个 agent 的输出成为下一个 agent 的输入。这创建了强大的 agent 流水线，类似于 Unix 管道，但专为 AI agent 编排设计。
+
+## 核心概念
+
+### 1. 顺序流水线
+
+最简单的形式：Agent A 的输出流向 Agent B，再流向 Agent C。
+
+```
+explore -> architect -> executor
+```
+
+**流程：**
+1. explore agent 搜索代码库并产出发现
+2. architect 接收发现并产出分析/建议
+3. executor 接收建议并实施更改
+
+### 2. 分支流水线
+
+根据输出条件路由到不同 agent。
+
+```
+explore -> {
+  if "complex refactoring" -> architect -> executor-high
+  if "simple change" -> executor-low
+  if "UI work" -> designer -> executor
+}
+```
+
+### 3. 并行后合并流水线
+
+并行运行多个 agent，合并其输出。
+
+```
+parallel(explore, document-specialist) -> architect -> executor
+```
+
+## 内置流水线预设
+
+### Review 流水线
+**用途：** 全面代码审查和实施
+
+```
+/pipeline review <task>
+```
+
+**阶段：**
+1. `explore` - 查找相关代码和模式
+2. `architect` - 分析架构和设计影响
+3. `critic` - 审查和批评分析
+4. `executor` - 在完整上下文下实施
+
+**适用于：** 主要功能、重构、复杂更改
+
+---
+
+### Implement 流水线
+**用途：** 带测试的计划实施
+
+```
+/pipeline implement <task>
+```
+
+**阶段：**
+1. `planner` - 创建详细实施计划
+2. `executor` - 执行计划
+3. `tdd-guide` - 添加/验证测试
+
+**适用于：** 需求明确的新功能
+
+---
+
+### Debug 流水线
+**用途：** 系统化调试工作流
+
+```
+/pipeline debug <issue>
+```
+
+**阶段：**
+1. `explore` - 定位错误位置和相关代码
+2. `architect` - 分析根本原因
+3. `build-fixer` - 应用修复并验证
+
+**适用于：** Bug、构建错误、测试失败
+
+---
+
+### Research 流水线
+**用途：** 外部研究 + 内部分析
+
+```
+/pipeline research <topic>
+```
+
+**阶段：**
+1. `parallel(document-specialist, explore)` - 外部文档 + 内部代码
+2. `architect` - 综合发现
+3. `writer` - 记录建议
+
+**适用于：** 技术决策、API 集成
+
+---
+
+### Refactor 流水线
+**用途：** 安全、经过验证的重构
+
+```
+/pipeline refactor <target>
+```
+
+**阶段：**
+1. `explore` - 查找所有用法和依赖
+2. `architect-medium` - 设计重构策略
+3. `executor-high` - 执行重构
+4. `qa-tester` - 验证无回归
+
+**适用于：** 架构更改、API 重新设计
+
+---
+
+### Security 流水线
+**用途：** 安全审计和修复
+
+```
+/pipeline security <scope>
+```
+
+**阶段：**
+1. `explore` - 查找潜在漏洞
+2. `security-reviewer` - 审计并识别问题
+3. `executor` - 实施修复
+4. `security-reviewer-low` - 重新验证
+
+**适用于：** 安全审查、漏洞修复
+
+---
+
+## 自定义流水线语法
+
+### 基本顺序
+
+```
+/pipeline agent1 -> agent2 -> agent3 "task description"
+```
+
+**示例：**
+```
+/pipeline explore -> architect -> executor "add authentication"
+```
+
+### 指定模型
+
+```
+/pipeline explore:haiku -> architect:opus -> executor:sonnet "optimize performance"
+```
+
+### 带分支
+
+```
+/pipeline explore -> (
+  complexity:high -> architect:opus -> executor-high:opus
+  complexity:medium -> executor:sonnet
+  complexity:low -> executor-low:haiku
+) "fix reported issues"
+```
+
+### 带并行阶段
+
+```
+/pipeline [explore, document-specialist] -> architect -> executor "implement OAuth"
+```
+
+## 数据传递协议
+
+流水线中每个 agent 从上一阶段接收结构化上下文：
+
+```json
+{
+  "pipeline_context": {
+    "original_task": "用户的原始请求",
+    "previous_stages": [
+      {
+        "agent": "explore",
+        "model": "haiku",
+        "findings": "...",
+        "files_identified": ["src/auth.ts", "src/user.ts"]
+      }
+    ],
+    "current_stage": "architect",
+    "next_stage": "executor"
+  },
+  "task": "此 agent 的具体任务"
+}
+```
+
+## 错误处理
+
+### 重试逻辑
+
+当 agent 失败时，流水线可以：
+
+1. **重试** - 重新运行同一 agent（最多 3 次）
+2. **跳过** - 以部分输出继续到下一阶段
+3. **中止** - 停止整个流水线
+4. **回退** - 路由到备用 agent
+
+**配置：**
+
+```
+/pipeline explore -> architect -> executor --retry=3 --on-error=abort
+```
+
+### 错误恢复模式
+
+**模式 1：回退到更高级别**
+```
+executor-low -> on-error -> executor:sonnet
+```
+
+**模式 2：咨询 architect**
+```
+executor -> on-error -> architect -> executor
+```
+
+**模式 3：人工介入**
+```
+any-stage -> on-error -> pause-for-user-input
+```
+
+## 流水线状态管理
+
+流水线在 `.omc/pipeline-state.json` 中维护状态：
+
+```json
+{
+  "pipeline_id": "uuid",
+  "name": "review",
+  "active": true,
+  "current_stage": 2,
+  "stages": [
+    {
+      "name": "explore",
+      "agent": "explore",
+      "model": "haiku",
+      "status": "completed",
+      "output": "..."
+    },
+    {
+      "name": "architect",
+      "agent": "architect",
+      "model": "opus",
+      "status": "in_progress",
+      "started_at": "2026-01-23T10:30:00Z"
+    },
+    {
+      "name": "executor",
+      "agent": "executor",
+      "model": "sonnet",
+      "status": "pending"
+    }
+  ],
+  "task": "原始用户任务",
+  "created_at": "2026-01-23T10:25:00Z"
+}
+```
+
+## 验证规则
+
+流水线完成前，验证：
+
+- [ ] 所有阶段成功完成
+- [ ] 最终阶段的输出解决了原始任务
+- [ ] 所有阶段无未处理错误
+- [ ] 所有修改的文件通过 lsp_diagnostics
+- [ ] 测试通过（如适用）
+
+## 高级功能
+
+### 条件分支
+
+根据 agent 输出路由到不同路径：
+
+```
+explore -> {
+  if files_found > 5 -> architect:opus -> executor-high:opus
+  if files_found <= 5 -> executor:sonnet
+}
+```
+
+### 循环结构
+
+重复阶段直到满足条件：
+
+```
+repeat_until(tests_pass) {
+  executor -> qa-tester
+}
+```
+
+### 合并策略
+
+并行 agent 完成时：
+
+- **concat**：连接所有输出
+- **summarize**：使用 architect 汇总发现
+- **vote**：使用 critic 选择最佳输出
+
+## 使用示例
+
+### 示例 1：功能实施
+```
+/pipeline review "add rate limiting to API"
+```
+→ 触发：explore → architect → critic → executor
+
+### 示例 2：Bug 修复
+```
+/pipeline debug "login fails with OAuth"
+```
+→ 触发：explore → architect → build-fixer
+
+### 示例 3：自定义链
+```
+/pipeline explore:haiku -> architect:opus -> executor:sonnet -> tdd-guide:sonnet "refactor auth module"
+```
+
+### 示例 4：研究驱动的实施
+```
+/pipeline research "implement GraphQL subscriptions"
+```
+→ 触发：parallel(document-specialist, explore) → architect → writer
+
+## 取消
+
+停止活跃流水线：
+
+```
+/pipeline cancel
+```
+
+或使用通用取消命令，它会自动检测活跃流水线。
+
+## 与其他 Skill 集成
+
+流水线可在其他 skill 中使用：
+
+- **Ralph**：循环流水线直到验证完成
+- **Ultrawork**：并行运行多个流水线
+- **Autopilot**：将流水线作为构建块
+
+## 最佳实践
+
+1. **从预设开始** - 在创建自定义流水线之前使用内置流水线
+2. **模型与复杂度匹配** - 不要在简单任务上浪费 opus
+3. **保持阶段专注** - 每个 agent 应有一个明确的职责
+4. **使用并行阶段** - 同时运行独立工作
+5. **在检查点验证** - 使用 architect 或 critic 验证进度
+6. **记录自定义流水线** - 保存成功的模式以便复用
+
+## 故障排除
+
+### 流水线挂起
+
+**检查：** `.omc/pipeline-state.json` 中的当前阶段
+**修复：** 使用 `/pipeline resume` 恢复或取消后重启
+
+### Agent 反复失败
+
+**检查：** 重试次数和错误消息
+**修复：** 路由到更高级别 agent 或添加 architect 咨询
+
+### 输出未传递
+
+**检查：** agent 提示中的数据传递结构
+**修复：** 确保每个 agent 都收到 `pipeline_context`
+
+## 技术实现
+
+流水线编排器：
+
+1. **解析流水线定义** - 验证语法和 agent 名称
+2. **初始化状态** - 创建 pipeline-state.json
+3. **顺序执行阶段** - 使用 Task 工具生成 agent
+4. **在阶段间传递上下文** - 为下一个 agent 结构化输出
+5. **处理分支逻辑** - 评估条件并路由
+6. **管理并行执行** - 生成并发 agent 并合并
+7. **持久化状态** - 每个阶段后更新状态文件
+8. **强制验证** - 完成前运行检查
+
+## 完成时清理状态
+
+**重要：完成时删除状态文件——不要只是设置 `active: false`**
+
+当流水线完成（所有阶段完成或已取消）时：
+
+```bash
+# 删除流水线状态文件
+rm -f .omc/state/pipeline-state.json
+```
+
+这确保未来会话的状态干净。不应留下 `active: false` 的陈旧状态文件。
+
+## Skill 调用
+
+此 skill 在以下情况激活：
+
+- 用户输入 `/pipeline` 命令
+- 用户提到"agent chain"、"workflow"、"pipe agents"
+- 检测到模式："X then Y then Z"（包含 agent 名称）
+
+**显式调用：**
+```
+/ultrapower:pipeline review "task"
+```
+
+**自动检测：**
+```
+"First explore the codebase, then architect should analyze it, then executor implements"
+```
+→ 自动创建流水线：explore → architect → executor

package/skills/plan/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: plan
+description: 通过可选访谈工作流进行战略规划
+---
+
+<Purpose>
+Plan 通过智能交互创建全面、可执行的工作计划。它自动检测是否需要访谈用户（宽泛请求）或直接规划（详细请求），并支持共识模式（迭代 Planner/Architect/Critic 循环）和审查模式（Critic 对现有计划的评估）。
+</Purpose>
+
+<Use_When>
+- 用户想在实施前规划——"plan this"、"plan the"、"let's plan"
+- 用户想对模糊想法进行结构化需求收集
+- 用户想审查现有计划——"review this plan"、`--review`
+- 用户想对计划进行多视角共识——`--consensus`、"ralplan"
+- 任务宽泛或模糊，需要在编写代码前确定范围
+</Use_When>
+
+<Do_Not_Use_When>
+- 用户想要自主端到端执行——改用 `autopilot`
+- 用户想立即开始编码且任务明确——改用 `ralph` 或委托给 executor
+- 用户提出可以直接回答的简单问题——直接回答即可
+- 任务是范围明显的单一修复——跳过规划，直接执行
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+在不理解需求的情况下直接编码会导致返工、范围蔓延和遗漏边界情况。Plan 提供结构化的需求收集、专家分析和质量把关的计划，使执行从坚实的基础开始。共识模式为高风险项目增加了多视角验证。
+</Why_This_Exists>
+
+<Execution_Policy>
+- 根据请求的具体程度自动检测访谈模式与直接模式
+- 访谈期间每次只问一个问题——绝不批量提问
+- 在询问用户之前，先通过 `explore` agent 收集代码库事实
+- 计划必须满足质量标准：80%+ 的声明引用文件/行号，90%+ 的标准可测试
+- 共识模式在进入实施前需要用户明确批准
+</Execution_Policy>
+
+<Steps>
+
+### 模式选择
+
+| 模式 | 触发条件 | 行为 |
+|------|---------|----------|
+| 访谈 | 宽泛请求的默认模式 | 交互式需求收集 |
+| 直接 | `--direct` 或详细请求 | 跳过访谈，直接生成计划 |
+| 共识 | `--consensus`、"ralplan" | Planner -> Architect -> Critic 循环直至达成一致 |
+| 审查 | `--review`、"review this plan" | Critic 对现有计划的评估 |
+
+### Interview Mode（访谈模式，宽泛/模糊请求）
+
+1. **Classify the request**：宽泛（动词模糊、无具体文件、涉及 3+ 个领域）触发访谈模式
+2. **Ask one focused question**，使用 `AskUserQuestion` 询问偏好、范围和约束
+3. **Gather codebase facts first**：在问"你的代码使用什么模式？"之前，先派遣 `explore` agent 查找，再提出有针对性的后续问题
+4. **基于答案深入**：每个问题基于上一个答案
+5. **咨询 Analyst**（Opus）了解隐藏需求、边界情况和风险
+6. **当用户表示准备好时创建计划**："create the plan"、"I'm ready"、"make it a work plan"
+
+### Direct Mode（直接模式，详细请求）
+
+1. **Quick Analysis**：可选的简短 Analyst 咨询
+2. **Create plan**：立即生成全面的工作计划
+3. **审查**（可选）：如有需要，进行 Critic 审查
+
+### Consensus Mode（`--consensus` / "ralplan"）
+
+1. **Planner** creates initial plan
+2. **User feedback**：**MUST** use `AskUserQuestion` to present the draft plan, with options:
+   - **Proceed to review** — send to Architect and Critic for evaluation
+   - **Request changes** — return to step 1 with user feedback
+   - **Skip review** — go directly to final approval (step 7)
+3. **Architect** reviews architectural soundness（优先使用 `ask_codex` 的 `architect` 角色）
+4. **Critic** evaluates against quality standards（优先使用 `ask_codex` 的 `critic` 角色）
+5. **重新审查循环**（最多 5 次迭代）：如果 Critic 拒绝，执行此闭合循环：
+   a. 收集 Architect + Critic 的所有拒绝反馈
+   b. 将反馈传递给 Planner 生成修订计划
+   c. **返回步骤 3** — Architect 审查修订计划
+   d. **返回步骤 4** — Critic 评估修订计划
+   e. 重复直到 Critic 批准或达到最多 5 次迭代
+   f. 如果达到最大迭代次数仍未获批准，通过 `AskUserQuestion` 向用户展示最佳版本，并注明未达成专家共识
+6. **应用改进**：当审查者批准并提出改进建议时，在继续之前将所有接受的改进合并到计划文件中：
+   a. 收集 Architect 和 Critic 响应中的所有改进建议
+   b. 去重并分类建议
+   c. 用接受的改进更新 `.omc/plans/` 中的计划文件
+   d. 在计划末尾的简短变更日志部分记录应用了哪些改进
+7. Critic 批准后（已应用改进）：**必须**使用 `AskUserQuestion` 展示计划，提供以下选项：
+   - **批准并执行** — 通过 ralph+ultrawork 进入实施
+   - **清除上下文并实施** — 先压缩上下文窗口（当规划后上下文较大时推荐），然后通过 ralph 使用保存的计划文件开始新的实施
+   - **请求修改** — 结合用户反馈返回步骤 1
+   - **拒绝** — 完全丢弃计划
+8. 用户通过结构化的 `AskUserQuestion` UI 选择（绝不用纯文本请求批准）
+9. 用户批准后：
+   - **批准并执行**：**MUST** invoke `Skill("ultrapower:ralph")` with the approved plan path from `.omc/plans/`. Do NOT implement directly. Do not edit source files in the planning agent. ralph skill handles execution via ultrawork parallel agents.
+   - **清除上下文并实施**：先调用 `Skill("compact")` 压缩上下文窗口（减少规划期间积累的 token 使用），然后调用 `Skill("ultrapower:ralph")`，传入 `.omc/plans/` 中的计划路径。当规划会话后上下文窗口已满 50%+ 时，推荐此路径。
+
+### Review Mode（`--review`）
+
+1. **Read plan file** from `.omc/plans/`
+2. **Evaluate via Critic**（优先使用 `ask_codex` 的 `critic` 角色）
+3. 返回裁决：APPROVED、REVISE（附具体反馈）或 REJECT（需要重新规划）
+
+### 计划输出格式
+
+每个计划包含：
+- 需求摘要
+- 验收标准（可测试）
+- 实施步骤（附文件引用）
+- 风险和缓解措施
+- 验证步骤
+
+计划保存到 `.omc/plans/`。草稿保存到 `.omc/drafts/`。
+</Steps>
+
+<Tool_Usage>
+- 首次使用 MCP 工具前，调用 `ToolSearch("mcp")` 发现延迟加载的 MCP 工具
+- 使用 `AskUserQuestion` 提问偏好问题（范围、优先级、时间线、风险承受度）——提供可点击的 UI
+- 使用纯文本提问需要具体值的问题（端口号、名称、后续澄清）
+- 使用 `explore` agent（Haiku，30s 超时）在询问用户之前收集代码库事实
+- 使用 `ask_codex` 的 `agent_role: "planner"` 对大范围计划进行规划验证
+- 使用 `ask_codex` 的 `agent_role: "analyst"` 进行需求分析
+- 使用 `ask_codex` 的 `agent_role: "critic"` 在共识和审查模式中进行计划审查
+- 如果 ToolSearch 未找到 MCP 工具或 Codex 不可用，回退到等效的 Claude agent——绝不阻塞在外部工具上
+- 在共识模式中，**必须**使用 `AskUserQuestion` 进行用户反馈步骤（步骤 2）和最终批准步骤（步骤 7）——绝不用纯文本请求批准
+- 在共识模式中，用户批准后**必须**调用 `Skill("ultrapower:ralph")` 执行（步骤 9）——绝不在规划 agent 中直接实施
+- 当用户在步骤 7 选择"清除上下文并实施"时：先调用 `Skill("compact")` 压缩积累的规划上下文，然后立即调用 `Skill("ultrapower:ralph")`，传入计划路径——compact 步骤对于在实施循环开始前释放上下文至关重要
+</Tool_Usage>
+
+<Examples>
+<Good>
+自适应访谈（先收集事实再提问）：
+```
+Planner: [派遣 explore agent："find authentication implementation"]
+Planner: [收到："Auth is in src/auth/ using JWT with passport.js"]
+Planner: "我看到你在 src/auth/ 中使用 JWT 认证和 passport.js。
+         对于这个新功能，我们应该扩展现有的 auth 还是添加单独的 auth 流程？"
+```
+为什么好：先自行回答代码库问题，再提出有针对性的偏好问题。
+</Good>
+
+<Good>
+每次只问一个问题：
+```
+Q1: "主要目标是什么？"
+A1: "提升性能"
+Q2: "对于性能，延迟和吞吐量哪个更重要？"
+A2: "延迟"
+Q3: "对于延迟，我们优化 p50 还是 p99？"
+```
+为什么好：每个问题基于上一个答案。聚焦且递进。
+</Good>
+
+<Bad>
+询问可以自己查找的事情：
+```
+Planner: "认证在你的代码库中实现在哪里？"
+User: "呃，我想是在 src/auth 里？"
+```
+为什么不好：planner 应该派遣 explore agent 查找，而不是问用户。
+</Bad>
+
+<Bad>
+批量提问：
+```
+"范围是什么？时间线呢？受众是谁？"
+```
+为什么不好：一次三个问题导致答案肤浅。每次只问一个。
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- 当需求足够清晰可以规划时停止访谈——不要过度访谈
+- 在共识模式中，经过 5 次 Planner/Architect/Critic 迭代后停止，展示最佳版本
+- 共识模式在任何实施开始前需要用户明确批准
+- 如果用户说"just do it"或"skip planning"，**必须**调用 `Skill("ultrapower:ralph")` 切换到执行模式。不要在规划 agent 中直接实施。
+- 当存在需要业务决策的不可调和权衡时，上报给用户
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] 计划有可测试的验收标准（90%+ 具体）
+- [ ] 计划在适用处引用具体文件/行号（80%+ 声明）
+- [ ] 所有风险都已识别缓解措施
+- [ ] 没有没有指标的模糊术语（"fast" -> "p99 < 200ms"）
+- [ ] 计划已保存到 `.omc/plans/`
+- [ ] 在共识模式中：用户在任何执行前明确批准
+</Final_Checklist>
+
+<Advanced>
+## 设计选项展示
+
+在访谈中展示设计选择时，分块进行：
+
+1. **概述**（2-3 句话）
+2. **选项 A** 及权衡
+3. [等待用户反应]
+4. **选项 B** 及权衡
+5. [等待用户反应]
+6. **建议**（仅在讨论完选项后）
+
+每个选项的格式：
+```
+### 选项 A：[名称]
+**方法：** [1 句话]
+**优点：** [要点]
+**缺点：** [要点]
+
+你对这个方法有什么看法？
+```
+
+## 问题分类
+
+在提出任何访谈问题之前，先对其分类：
+
+| 类型 | 示例 | 行动 |
+|------|----------|--------|
+| 代码库事实 | "存在什么模式？"、"X 在哪里？" | 先 Explore，不问用户 |
+| 用户偏好 | "优先级？"、"时间线？" | 通过 AskUserQuestion 询问用户 |
+| 范围决策 | "包含功能 Y？" | 询问用户 |
+| 需求 | "性能约束？" | 询问用户 |
+
+## 审查质量标准
+
+| 标准 | 要求 |
+|-----------|----------|
+| 清晰度 | 80%+ 声明引用文件/行号 |
+| 可测试性 | 90%+ 标准具体 |
+| 验证 | 所有文件引用存在 |
+| 具体性 | 无模糊术语 |
+
+## 废弃通知
+
+独立的 `/planner`、`/ralplan` 和 `/review` skill 已合并到 `/plan`。所有工作流（访谈、直接、共识、审查）均可通过 `/plan` 使用。
+</Advanced>