@liangjie559567/ultrapower 5.0.4

package/docs/shared/mode-hierarchy.md

@@ -0,0 +1,120 @@
+# 执行模式层级
+
+本文档定义了执行模式之间的关系，并提供模式选择指南。
+
+## 模式继承树
+
+```
+autopilot（自主端到端）
+├── 包含：ralph（持久化）
+│   └── 包含：ultrawork（并行化）
+├── 包含：ultraqa（QA 循环）
+└── 包含：plan（战略思考）
+
+ultrapilot（并行 autopilot）
+├── 包含：文件所有权分区
+├── 包含：worker 协调（最多 20 个 worker）
+└── 回退到：autopilot（如果不可并行化）
+
+swarm（N-agent 协调）
+├── 包含：SQLite 任务认领
+├── 包含：心跳监控
+└── 与 autopilot/ultrapilot 正交（不同范式）
+
+ （仅 token 效率）
+└── 修改：agent 层级选择（优先 haiku/sonnet）
+    （不包含持久化——那是 ralph 的职责）
+
+ralph（持久化包装器）
+└── 包含：ultrawork（并行化引擎）
+    （新增：循环直到完成 + architect 验证）
+
+ultrawork（并行化引擎）
+└── 仅作为组件——并行 agent 生成
+    （无持久化，无验证循环）
+```
+
+## 模式关系
+
+| 模式 | 类型 | 包含 | 互斥 |
+|------|------|----------|------------------------|
+| autopilot | 独立模式 | ralph、ultraqa、plan | ultrapilot |
+| ultrapilot | 独立模式 | 文件所有权、workers | autopilot |
+| swarm | 独立模式 | SQLite 认领 | - |
+| ralph | 包装器 | ultrawork | - |
+| ultrawork | 组件 | - | - |
+|  | 修饰符 | - | - |
+| ultraqa | 组件 | - | - |
+
+## 决策树
+
+```
+想要自主执行？
+├── 是：任务是否可拆分为 3 个以上独立组件？
+│   ├── 是：ultrapilot（带文件所有权的并行 autopilot）
+│   └── 否：autopilot（带 ralph 阶段的顺序执行）
+└── 否：想要并行执行并保持手动监督？
+    ├── 是：是否需要成本优化？
+    │   ├── 是： + ultrawork
+    │   └── 否：单独使用 ultrawork
+    └── 否：需要持久化直到验证完成？
+        ├── 是：ralph（持久化 + ultrawork + 验证）
+        └── 否：标准编排（直接委派给 agent）
+
+有许多类似的独立任务（如"修复 47 个错误"）？
+└── 是：swarm（N 个 agent 从任务池中认领）
+```
+
+## 模式差异矩阵
+
+| 模式 | 最适合 | 并行化 | 持久化 | 验证 | 文件所有权 |
+|------|----------|-------------|-------------|--------------|----------------|
+| autopilot | "帮我构建 X" | 通过 ralph | 是 | 是 | 不适用 |
+| ultrapilot | 多组件 | 20 个 worker | 是 | 是 | 分区 |
+| swarm | 同质任务 | N 个 worker | 按任务 | 按任务 | 按任务 |
+| ralph | "不要停" | 通过 ultrawork | 是 | 强制 | 不适用 |
+| ultrawork | 仅并行 | 是 | 否 | 否 | 不适用 |
+|  | 节省成本 | 修饰符 | 否 | 否 | 不适用 |
+
+## 快速参考
+
+**只想构建某个东西？** → `autopilot`
+**构建多组件系统？** → `ultrapilot`
+**修复许多类似问题？** → `swarm`
+**想控制执行过程？** → `ultrawork`
+**需要验证完成？** → `ralph`
+**想节省 token？** → ``（与其他模式组合使用）
+
+## 组合模式
+
+有效组合：
+- `eco ralph` = 使用更便宜 agent 的 ralph 循环
+- `eco ultrawork` = 使用更便宜 agent 的并行执行
+- `eco autopilot` = 带成本优化的完整自主执行
+
+无效组合：
+- `autopilot ultrapilot` = 互斥（两者都是独立模式）
+- `` 单独使用 = 无意义（需要一个执行模式）
+
+## 状态管理
+
+### 标准路径
+所有模式状态文件使用标准化位置：
+- 主路径：`.omc/state/{name}.json`（本地，按项目）
+- 全局备份：`~/.omc/state/{name}.json`（全局，session 连续性）
+
+### 模式状态文件
+| 模式 | 状态文件 |
+|------|-----------|
+| ralph | `ralph-state.json` |
+| autopilot | `autopilot-state.json` |
+| ultrapilot | `ultrapilot-state.json` |
+| ultrawork | `ultrawork-state.json` |
+|  | `-state.json` |
+| ultraqa | `ultraqa-state.json` |
+| pipeline | `pipeline-state.json` |
+| swarm | `swarm-summary.json` + `swarm-active.marker` |
+
+**重要：** 永远不要将 OMC 状态存储在 `~/.claude/` 中——该目录保留给 Claude Code 本身使用。
+
+旧版位置在读取时自动迁移。

package/docs/shared/mode-selection-guide.md

@@ -0,0 +1,82 @@
+# 模式选择指南
+
+## 快速决策
+
+| 如果你想… | 使用 | 关键词 |
+|----------------|----------|---------|
+| 从想法开始完全自主构建 | `autopilot` | "autopilot"、"build me"、"I want a" |
+| 并行自主执行（快 3-5 倍） | `ultrapilot` | "ultrapilot"、"parallel build" |
+| 持久化直到验证完成 | `ralph` | "ralph"、"don't stop" |
+| 并行执行，手动监督 | `ultrawork` | "ulw"、"ultrawork" |
+| 成本高效执行 | ``（修饰符） | "eco"、"budget" |
+| 许多类似的独立任务 | `swarm` | "swarm N agents" |
+
+## 如果你不确定
+
+**从 `autopilot` 开始** - 它能处理大多数场景，并自动过渡到其他模式。
+
+## 详细决策流程图
+
+```
+想要自主执行？
+├── 是：任务是否可拆分为 3 个以上独立组件？
+│   ├── 是：ultrapilot（带文件所有权的并行 autopilot）
+│   └── 否：autopilot（带 ralph 阶段的顺序执行）
+└── 否：想要并行执行并保持手动监督？
+    ├── 是：是否需要成本优化？
+    │   ├── 是： + ultrawork
+    │   └── 否：单独使用 ultrawork
+    └── 否：需要持久化直到验证完成？
+        ├── 是：ralph（持久化 + ultrawork + 验证）
+        └── 否：标准编排（直接委派给 agent）
+
+有许多类似的独立任务（如"修复 47 个错误"）？
+└── 是：swarm（N 个 agent 从任务池中认领）
+```
+
+## 示例
+
+| 用户请求 | 最佳模式 | 原因 |
+|--------------|-----------|-----|
+| "Build me a REST API" | autopilot | 单一连贯的交付物 |
+| "Build frontend, backend, and database" | ultrapilot | 清晰的组件边界 |
+| "Fix all 47 TypeScript errors" | swarm | 许多独立的类似任务 |
+| "Refactor auth module thoroughly" | ralph | 需要持久化 + 验证 |
+| "Quick parallel execution" | ultrawork | 偏好手动监督 |
+| "Save tokens while fixing errors" |  + ultrawork | 注重成本的并行执行 |
+| "Don't stop until done" | ralph | 检测到持久化关键词 |
+
+## 模式类型
+
+### 独立模式
+这些模式独立运行：
+- **autopilot**：自主端到端执行
+- **ultrapilot**：带文件所有权的并行自主执行
+- **swarm**：带任务池的 N-agent 协调
+
+### 包装器模式
+这些模式包装其他模式：
+- **ralph**：在 ultrawork 外层添加持久化 + 验证
+
+### 组件模式
+这些模式被其他模式使用：
+- **ultrawork**：并行执行引擎（被 ralph、autopilot 使用）
+
+### 修饰符模式
+这些模式修改其他模式的行为：
+- ****：将模型路由改为优先使用更便宜的层级
+
+## 有效组合
+
+| 组合 | 效果 |
+|-------------|--------|
+| `eco ralph` | 使用更便宜 agent 的 ralph 持久化 |
+| `eco ultrawork` | 使用更便宜 agent 的并行执行 |
+| `eco autopilot` | 带成本节省的自主执行 |
+
+## 无效组合
+
+| 组合 | 无效原因 |
+|-------------|-------------|
+| `autopilot ultrapilot` | 两者都是独立模式——选其一 |
+| `` 单独使用 | 需要一个执行模式来修饰 |

package/docs/shared/verification-tiers.md

@@ -0,0 +1,107 @@
+# 验证层级
+
+验证随任务复杂度扩展，在控制成本的同时保持质量。
+
+## 层级定义
+
+| 层级 | 标准 | Agent | 模型 | 所需证据 |
+|------|----------|-------|-------|-------------------|
+| **LIGHT** | <5 个文件，<100 行，完整测试覆盖 | architect-low | haiku | lsp_diagnostics 无错误 |
+| **STANDARD** | 默认（非 LIGHT 或 THOROUGH） | architect-medium | sonnet | diagnostics + 构建通过 |
+| **THOROUGH** | >20 个文件，或架构/安全变更 | architect | opus | 完整审查 + 所有测试 |
+
+## 选择接口
+
+```typescript
+interface ChangeMetadata {
+  filesChanged: number;
+  linesChanged: number;
+  hasArchitecturalChanges: boolean;
+  hasSecurityImplications: boolean;
+  testCoverage: 'none' | 'partial' | 'full';
+}
+
+type VerificationTier = 'LIGHT' | 'STANDARD' | 'THOROUGH';
+```
+
+## 选择逻辑
+
+```
+IF hasSecurityImplications OR hasArchitecturalChanges:
+  → THOROUGH（安全/架构变更始终使用）
+ELIF filesChanged > 20:
+  → THOROUGH（范围较大）
+ELIF filesChanged < 5 AND linesChanged < 100 AND testCoverage === 'full':
+  → LIGHT（小范围，测试完善）
+ELSE:
+  → STANDARD（默认）
+```
+
+## 覆盖触发词
+
+覆盖自动检测的用户关键词：
+
+| 关键词 | 强制层级 |
+|---------|-------------|
+| "thorough"、"careful"、"important"、"critical" | THOROUGH |
+| "quick"、"simple"、"trivial"、"minor" | LIGHT |
+| 安全相关文件变更 | THOROUGH（始终） |
+
+## 架构变更检测
+
+触发 `hasArchitecturalChanges` 的文件：
+- `**/config.{ts,js,json}`
+- `**/schema.{ts,prisma,sql}`
+- `**/definitions.ts`
+- `**/types.ts`
+- `package.json`
+- `tsconfig.json`
+
+## 安全影响检测
+
+触发 `hasSecurityImplications` 的路径模式：
+- `**/auth/**`
+- `**/security/**`
+- `**/permissions?.{ts,js}`
+- `**/credentials?.{ts,js,json}`
+- `**/secrets?.{ts,js,json,yml,yaml}`
+- `**/tokens?.{ts,js,json}`
+- `**/passwords?.{ts,js,json}`
+- `**/oauth*`
+- `**/jwt*`
+- `**/.env*`
+
+## 证据类型
+
+不同声明类型所需的证据：
+
+| 声明 | 所需证据 |
+|-------|-------------------|
+| "已修复" | 显示现在通过的测试 |
+| "已实现" | lsp_diagnostics 无错误 + 构建通过 |
+| "已重构" | 所有测试仍然通过 |
+| "已调试" | 定位到 file:line 的根本原因 |
+
+## 成本对比
+
+| 层级 | 相对成本 | 使用场景 |
+|------|---------------|----------|
+| LIGHT | 1x | 带测试的单文件 bug 修复 |
+| STANDARD | 5x | 多文件功能新增 |
+| THOROUGH | 20x | 大规模重构、安全变更 |
+
+预计节省：与始终使用 THOROUGH 相比，分层系统可减少约 40% 的验证成本。
+
+## 在模式中的使用
+
+所有持久化模式（ralph、autopilot、ultrapilot）在生成验证 agent 前应使用层级选择器：
+
+```typescript
+import { selectVerificationTier, getVerificationAgent } from '../verification/tier-selector';
+
+const tier = selectVerificationTier(changeMetadata);
+const { agent, model } = getVerificationAgent(tier);
+
+// 生成适当的验证 agent
+Task(subagent_type=`ultrapower:${agent}`, model, prompt="Verify...")
+```

package/docs/testing.md

@@ -0,0 +1,303 @@
+# 测试 ultrapower Skills
+
+本文档描述如何测试 ultrapower skills，特别是针对 `subagent-driven-development` 等复杂 skill 的集成测试。
+
+## 概述
+
+测试涉及 subagent、工作流和复杂交互的 skill，需要在无头模式下运行实际的 Claude Code 会话，并通过会话转录验证其行为。
+
+## 测试结构
+
+```
+tests/
+├── claude-code/
+│   ├── test-helpers.sh                    # 共享测试工具
+│   ├── test-subagent-driven-development-integration.sh
+│   ├── analyze-token-usage.py             # Token 分析工具
+│   └── run-skill-tests.sh                 # 测试运行器（如存在）
+```
+
+## 运行测试
+
+### 集成测试
+
+集成测试使用实际 skill 执行真实的 Claude Code 会话：
+
+```bash
+# 运行 subagent-driven-development 集成测试
+cd tests/claude-code
+./test-subagent-driven-development-integration.sh
+```
+
+**注意：** 集成测试可能需要 10-30 分钟，因为它们会使用多个 subagent 执行真实的实现计划。
+
+### 前提条件
+
+- 必须从 **ultrapower 插件目录**运行（不能从临时目录运行）
+- Claude Code 必须已安装并可通过 `claude` 命令访问
+- 必须启用本地开发 marketplace：在 `~/.claude/settings.json` 中设置 `"ultrapower@ultrapower-dev": true`
+
+## 集成测试：subagent-driven-development
+
+### 测试内容
+
+集成测试验证 `subagent-driven-development` skill 是否正确：
+
+1. **计划加载**：在开始时读取一次计划
+2. **完整任务文本**：向 subagent 提供完整的任务描述（不让它们读取文件）
+3. **自我审查**：确保 subagent 在报告前进行自我审查
+4. **审查顺序**：在代码质量审查之前运行规范合规性审查
+5. **审查循环**：发现问题时使用审查循环
+6. **独立验证**：规范审查者独立读取代码，不信任实现者的报告
+
+### 工作原理
+
+1. **设置**：创建一个带有最小实现计划的临时 Node.js 项目
+2. **执行**：在无头模式下使用 skill 运行 Claude Code
+3. **验证**：解析会话转录（`.jsonl` 文件）以验证：
+   - Skill 工具被调用
+   - Subagent 被派发（Task 工具）
+   - TodoWrite 用于追踪
+   - 实现文件已创建
+   - 测试通过
+   - Git 提交显示正确的工作流
+4. **Token 分析**：按 subagent 显示 token 使用明细
+
+### 测试输出
+
+```
+========================================
+ Integration Test: subagent-driven-development
+========================================
+
+Test project: /tmp/tmp.xyz123
+
+=== Verification Tests ===
+
+Test 1: Skill tool invoked...
+  [PASS] subagent-driven-development skill was invoked
+
+Test 2: Subagents dispatched...
+  [PASS] 7 subagents dispatched
+
+Test 3: Task tracking...
+  [PASS] TodoWrite used 5 time(s)
+
+Test 6: Implementation verification...
+  [PASS] src/math.js created
+  [PASS] add function exists
+  [PASS] multiply function exists
+  [PASS] test/math.test.js created
+  [PASS] Tests pass
+
+Test 7: Git commit history...
+  [PASS] Multiple commits created (3 total)
+
+Test 8: No extra features added...
+  [PASS] No extra features added
+
+=========================================
+ Token Usage Analysis
+=========================================
+
+Usage Breakdown:
+----------------------------------------------------------------------------------------------------
+Agent           Description                          Msgs      Input     Output      Cache     Cost
+----------------------------------------------------------------------------------------------------
+main            Main session (coordinator)             34         27      3,996  1,213,703 $   4.09
+3380c209        implementing Task 1: Create Add Function     1          2        787     24,989 $   0.09
+34b00fde        implementing Task 2: Create Multiply Function     1          4        644     25,114 $   0.09
+3801a732        reviewing whether an implementation matches...   1          5        703     25,742 $   0.09
+4c142934        doing a final code review...                    1          6        854     25,319 $   0.09
+5f017a42        a code reviewer. Review Task 2...               1          6        504     22,949 $   0.08
+a6b7fbe4        a code reviewer. Review Task 1...               1          6        515     22,534 $   0.08
+f15837c0        reviewing whether an implementation matches...   1          6        416     22,485 $   0.07
+----------------------------------------------------------------------------------------------------
+
+TOTALS:
+  Total messages:         41
+  Input tokens:           62
+  Output tokens:          8,419
+  Cache creation tokens:  132,742
+  Cache read tokens:      1,382,835
+
+  Total input (incl cache): 1,515,639
+  Total tokens:             1,524,058
+
+  Estimated cost: $4.67
+  (at $3/$15 per M tokens for input/output)
+
+========================================
+ Test Summary
+========================================
+
+STATUS: PASSED
+```
+
+## Token 分析工具
+
+### 用法
+
+分析任意 Claude Code 会话的 token 使用情况：
+
+```bash
+python3 tests/claude-code/analyze-token-usage.py ~/.claude/projects/<project-dir>/<session-id>.jsonl
+```
+
+### 查找会话文件
+
+会话转录存储在 `~/.claude/projects/` 中，工作目录路径经过编码：
+
+```bash
+# 示例：/Users/jesse/Documents/GitHub/ultrapower/ultrapower
+SESSION_DIR="$HOME/.claude/projects/-Users-jesse-Documents-GitHub-ultrapower-ultrapower"
+
+# 查找最近的会话
+ls -lt "$SESSION_DIR"/*.jsonl | head -5
+```
+
+### 显示内容
+
+- **主会话使用情况**：协调者（您或主 Claude 实例）的 token 使用情况
+- **每个 subagent 明细**：每次 Task 调用，包含：
+  - Agent ID
+  - 描述（从提示词中提取）
+  - 消息数量
+  - 输入/输出 token
+  - 缓存使用情况
+  - 估算费用
+- **总计**：整体 token 使用情况和费用估算
+
+### 理解输出
+
+- **高缓存读取**：良好——表示提示词缓存正在工作
+- **主会话高输入 token**：预期——协调者拥有完整上下文
+- **每个 subagent 费用相近**：预期——每个 subagent 获得相似的任务复杂度
+- **每个任务费用**：典型范围为每个 subagent $0.05-$0.15，取决于任务
+
+## 故障排除
+
+### Skills 未加载
+
+**问题**：运行无头测试时找不到 skill
+
+**解决方案**：
+1. 确保从 ultrapower 目录运行：`cd /path/to/ultrapower && tests/...`
+2. 检查 `~/.claude/settings.json` 的 `enabledPlugins` 中是否有 `"ultrapower@ultrapower-dev": true`
+3. 验证 skill 存在于 `skills/` 目录中
+
+### 权限错误
+
+**问题**：Claude 被阻止写入文件或访问目录
+
+**解决方案**：
+1. 使用 `--permission-mode bypassPermissions` 标志
+2. 使用 `--add-dir /path/to/temp/dir` 授予对测试目录的访问权限
+3. 检查测试目录的文件权限
+
+### 测试超时
+
+**问题**：测试耗时过长并超时
+
+**解决方案**：
+1. 增加超时时间：`timeout 1800 claude ...`（30 分钟）
+2. 检查 skill 逻辑中是否存在无限循环
+3. 审查 subagent 任务复杂度
+
+### 找不到会话文件
+
+**问题**：测试运行后找不到会话转录
+
+**解决方案**：
+1. 检查 `~/.claude/projects/` 中正确的项目目录
+2. 使用 `find ~/.claude/projects -name "*.jsonl" -mmin -60` 查找最近的会话
+3. 验证测试实际运行了（检查测试输出中的错误）
+
+## 编写新的集成测试
+
+### 模板
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/test-helpers.sh"
+
+# 创建测试项目
+TEST_PROJECT=$(create_test_project)
+trap "cleanup_test_project $TEST_PROJECT" EXIT
+
+# 设置测试文件...
+cd "$TEST_PROJECT"
+
+# 使用 skill 运行 Claude
+PROMPT="Your test prompt here"
+cd "$SCRIPT_DIR/../.." && timeout 1800 claude -p "$PROMPT" \
+  --allowed-tools=all \
+  --add-dir "$TEST_PROJECT" \
+  --permission-mode bypassPermissions \
+  2>&1 | tee output.txt
+
+# 查找并分析会话
+WORKING_DIR_ESCAPED=$(echo "$SCRIPT_DIR/../.." | sed 's/\\//-/g' | sed 's/^-//')
+SESSION_DIR="$HOME/.claude/projects/$WORKING_DIR_ESCAPED"
+SESSION_FILE=$(find "$SESSION_DIR" -name "*.jsonl" -type f -mmin -60 | sort -r | head -1)
+
+# 通过解析会话转录验证行为
+if grep -q '"name":"Skill".*"skill":"your-skill-name"' "$SESSION_FILE"; then
+    echo "[PASS] Skill was invoked"
+fi
+
+# 显示 token 分析
+python3 "$SCRIPT_DIR/analyze-token-usage.py" "$SESSION_FILE"
+```
+
+### 最佳实践
+
+1. **始终清理**：使用 trap 清理临时目录
+2. **解析转录**：不要 grep 用户可见输出——解析 `.jsonl` 会话文件
+3. **授予权限**：使用 `--permission-mode bypassPermissions` 和 `--add-dir`
+4. **从插件目录运行**：skill 仅在从 ultrapower 目录运行时加载
+5. **显示 token 使用情况**：始终包含 token 分析以了解费用
+6. **测试真实行为**：验证实际创建的文件、通过的测试、提交记录
+
+## 会话转录格式
+
+会话转录是 JSONL（JSON Lines）文件，每行是一个表示消息或工具结果的 JSON 对象。
+
+### 关键字段
+
+```json
+{
+  "type": "assistant",
+  "message": {
+    "content": [...],
+    "usage": {
+      "input_tokens": 27,
+      "output_tokens": 3996,
+      "cache_read_input_tokens": 1213703
+    }
+  }
+}
+```
+
+### 工具结果
+
+```json
+{
+  "type": "user",
+  "toolUseResult": {
+    "agentId": "3380c209",
+    "usage": {
+      "input_tokens": 2,
+      "output_tokens": 787,
+      "cache_read_input_tokens": 24989
+    },
+    "prompt": "You are implementing Task 1...",
+    "content": [{"type": "text", "text": "..."}]
+  }
+}
+```
+
+`agentId` 字段链接到 subagent 会话，`usage` 字段包含该特定 subagent 调用的 token 使用情况。