@liangjie559567/ultrapower 5.0.4

package/docs/partials/agent-tiers.md

@@ -0,0 +1,160 @@
+# Agent 层级参考
+
+这是所有 agent 层级信息的唯一权威来源。所有 skill 文件和文档应引用此文件，而非重复其中的表格。
+
+## 层级矩阵
+
+| 领域 | LOW (Haiku) | MEDIUM (Sonnet) | HIGH (Opus) |
+|--------|-------------|-----------------|-------------|
+| **分析** | architect-low | architect-medium | architect |
+| **执行** | executor-low | executor | executor-high |
+| **深度工作** | - | - | deep-executor |
+| **搜索** | explore | - | explore-high |
+| **研究** | - | document-specialist | - |
+| **前端** | designer-low | designer | designer-high |
+| **文档** | writer | - | - |
+| **视觉** | - | vision | - |
+| **规划** | - | - | planner |
+| **评审** | - | - | critic |
+| **预规划** | - | - | analyst |
+| **测试** | - | qa-tester | - |
+| **安全** | security-reviewer-low | - | security-reviewer |
+| **构建** | - | build-fixer | - |
+| **TDD** | tdd-guide-low | tdd-guide | - |
+| **代码审查** | - | - | code-reviewer |
+| **数据科学** | - | scientist | scientist-high |
+
+## 模型路由指南
+
+| 任务复杂度 | 层级 | 模型 | 使用时机 |
+|-----------------|------|-------|-------------|
+| 简单 | LOW | haiku | 快速查询、简单修复、"X 返回什么？" |
+| 标准 | MEDIUM | sonnet | 功能实现、标准调试、"添加验证" |
+| 复杂 | HIGH | opus | 架构决策、复杂调试、"重构系统" |
+
+## 按任务类型选择 Agent
+
+| 任务类型 | 最佳 Agent | 层级 |
+|-----------|------------|------|
+| 快速代码查询 | explore | LOW |
+| 查找文件/模式 | explore | LOW |
+| 复杂架构搜索 | explore-high | HIGH |
+| 简单代码修改 | executor-low | LOW |
+| 功能实现 | executor | MEDIUM |
+| 复杂重构 | executor-high | HIGH |
+| 调试简单问题 | architect-low | LOW |
+| 调试复杂问题 | architect | HIGH |
+| UI 组件 | designer | MEDIUM |
+| 复杂 UI 系统 | designer-high | HIGH |
+| 编写文档/注释 | writer | LOW |
+| 研究文档/API | document-specialist | MEDIUM |
+| 分析图片/图表 | vision | MEDIUM |
+| 战略规划 | planner | HIGH |
+| 审查/评审计划 | critic | HIGH |
+| 预规划分析 | analyst | HIGH |
+| 交互式 CLI 测试 | qa-tester | MEDIUM |
+| 安全审查 | security-reviewer | HIGH |
+| 快速安全扫描 | security-reviewer-low | LOW |
+| 修复构建错误 | build-fixer | MEDIUM |
+| 简单构建修复 | build-fixer (model=haiku) | LOW |
+| TDD 工作流 | tdd-guide | MEDIUM |
+| 快速测试建议 | tdd-guide-low | LOW |
+| 代码审查 | code-reviewer | HIGH |
+| 快速代码检查 | code-reviewer (model=haiku) | LOW |
+| 数据分析/统计 | scientist | MEDIUM |
+| 快速数据检查 | scientist (model=haiku) | LOW |
+| 复杂 ML/假设验证 | scientist-high | HIGH |
+| 查找符号引用 | explore-high | HIGH |
+| 获取文件/工作区符号概览 | explore | LOW |
+| 结构化代码模式搜索 | explore | LOW |
+| 结构化代码转换 | executor-high | HIGH |
+| 全项目类型检查 | build-fixer | MEDIUM |
+| 检查单文件错误 | executor-low | LOW |
+| 数据分析/计算 | scientist | MEDIUM |
+| 复杂自主工作 | deep-executor | HIGH |
+| 深度目标导向执行 | deep-executor | HIGH |
+
+## 使用方法
+
+委派任务时，始终显式指定模型：
+
+```
+Task(subagent_type="ultrapower:executor",
+     model="sonnet",
+     prompt="...")
+```
+
+为节省 token，在任务允许时优先使用较低层级：
+- 简单查询和快速修复使用 `haiku`
+- 标准实现工作使用 `sonnet`
+- 复杂推理任务保留 `opus`
+
+## MCP 工具与 Agent 能力
+
+### 工具清单
+
+| 工具 | 类别 | 用途 | 是否分配给 Agent？ |
+|------|----------|---------|---------------------|
+| `lsp_hover` | LSP | 获取代码位置的类型信息和文档 | 否（orchestrator 直接使用） |
+| `lsp_goto_definition` | LSP | 跳转到符号定义处 | 否（orchestrator 直接使用） |
+| `lsp_find_references` | LSP | 查找符号在代码库中的所有用法 | 是（仅 `explore-high`） |
+| `lsp_document_symbols` | LSP | 获取文件中所有符号的概览 | 是 |
+| `lsp_workspace_symbols` | LSP | 按名称在工作区中搜索符号 | 是 |
+| `lsp_diagnostics` | LSP | 获取文件的错误、警告和提示 | 是 |
+| `lsp_diagnostics_directory` | LSP | 项目级类型检查（tsc --noEmit 或 LSP） | 是 |
+| `lsp_prepare_rename` | LSP | 检查符号是否可以重命名 | 否（orchestrator 直接使用） |
+| `lsp_rename` | LSP | 在整个项目中重命名符号 | 否（orchestrator 直接使用） |
+| `lsp_code_actions` | LSP | 获取可用的重构和快速修复 | 否（orchestrator 直接使用） |
+| `lsp_code_action_resolve` | LSP | 获取代码操作的完整编辑详情 | 否（orchestrator 直接使用） |
+| `lsp_servers` | LSP | 列出可用的语言服务器及安装状态 | 否（orchestrator 直接使用） |
+| `ast_grep_search` | AST | 基于 AST 的模式化结构代码搜索 | 是 |
+| `ast_grep_replace` | AST | 基于模式的结构化代码转换 | 是（仅 `executor-high`） |
+| `python_repl` | Data | 用于数据分析和计算的持久化 Python REPL | 是 |
+
+### Agent 工具矩阵（仅 MCP 工具）
+
+| Agent | LSP Diagnostics | LSP Dir Diagnostics | LSP Symbols | LSP References | AST Search | AST Replace | Python REPL |
+|-------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+| `explore` | - | - | doc + workspace | - | yes | - | - |
+| `explore-high` | - | - | doc + workspace | yes | yes | - | - |
+| `architect-low` | yes | - | - | - | - | - | - |
+| `architect-medium` | yes | yes | - | - | yes | - | - |
+| `architect` | yes | yes | - | - | yes | - | - |
+| `executor-low` | yes | - | - | - | - | - | - |
+| `executor` | yes | yes | - | - | - | - | - |
+| `executor-high` | yes | yes | - | - | yes | yes | - |
+| `deep-executor` | yes | yes | - | - | yes | yes | - |
+| `build-fixer` | yes | yes | - | - | - | - | - |
+| `tdd-guide` | yes | - | - | - | - | - | - |
+| `tdd-guide-low` | yes | - | - | - | - | - | - |
+| `code-reviewer` | yes | - | - | - | yes | - | - |
+| `qa-tester` | yes | - | - | - | - | - | - |
+| `scientist` | - | - | - | - | - | - | yes |
+| `scientist-high` | - | - | - | - | - | - | yes |
+
+### 未分配工具（Orchestrator 直接使用）
+
+以下 7 个 MCP 工具未分配给任何 agent，需要时直接使用：
+
+| 工具 | 直接使用时机 |
+|------|---------------------|
+| `lsp_hover` | 对话中快速查询类型 |
+| `lsp_goto_definition` | 分析过程中导航到符号定义 |
+| `lsp_prepare_rename` | 在决定方案前检查重命名可行性 |
+| `lsp_rename` | 安全重命名操作（返回编辑预览，不自动应用） |
+| `lsp_code_actions` | 发现可用的重构操作 |
+| `lsp_code_action_resolve` | 获取特定代码操作的详情 |
+| `lsp_servers` | 检查语言服务器可用性 |
+
+对于需要实现的复杂重命名或重构任务，委派给 `executor-high`，它可以使用 `ast_grep_replace` 进行结构化转换。
+
+### 工具选择指南
+
+- **需要文件符号概览或工作区搜索？** 通过 `explore` 或 `explore-high` 使用 `lsp_document_symbols`/`lsp_workspace_symbols`
+- **需要查找符号的所有用法？** 通过 `explore-high` 使用 `lsp_find_references`（唯一拥有此工具的 agent）
+- **需要结构化代码模式？**（如"查找所有匹配 X 形状的函数"）通过 `explore` 系列、`architect`/`architect-medium` 或 `code-reviewer` 使用 `ast_grep_search`
+- **需要结构化代码转换？** 通过 `executor-high` 使用 `ast_grep_replace`（唯一拥有此工具的 agent）
+- **需要全项目类型检查？** 通过 `architect`/`architect-medium`、`executor`/`executor-high` 或 `build-fixer` 使用 `lsp_diagnostics_directory`
+- **需要单文件错误检查？** 通过多个 agent 使用 `lsp_diagnostics`（参见矩阵）
+- **需要数据分析/计算？** 通过 `scientist` 或 `scientist-high` 使用 `python_repl`
+- **需要快速类型信息或定义查询？** 直接使用 `lsp_hover`/`lsp_goto_definition`（orchestrator 直接工具）

package/docs/partials/features.md

@@ -0,0 +1,153 @@
+# 功能参考（v3.1 - v3.4）
+
+## Session Notepad（短期记忆）
+
+位于 `.omc/notepad.md` 的抗压缩记忆系统，分为三个层级：
+
+| 区块 | 行为 | 用途 |
+|---------|----------|---------|
+| **Priority Context** | 每次 session 启动时始终加载（最多 500 字符） | 关键信息：如"项目使用 pnpm"、"API key 在 .env 中" |
+| **Working Memory** | 带时间戳的条目，7 天后自动清理 | 调试线索、临时发现 |
+| **MANUAL** | 永不自动清理 | 团队联系人、部署信息、永久笔记 |
+
+**用户 skill：** `/ultrapower:note`
+- `/ultrapower:note <content>` - 添加到 Working Memory
+- `/ultrapower:note --priority <content>` - 添加到 Priority Context
+- `/ultrapower:note --manual <content>` - 添加到 MANUAL 区块
+- `/ultrapower:note --show` - 显示 notepad 内容
+
+**自动捕获：** Task agent 输出中的 `<remember>` 标签会被自动捕获：
+- `<remember>content</remember>` → 带时间戳写入 Working Memory
+- `<remember priority>content</remember>` → 替换 Priority Context
+
+**API：** `initNotepad()`、`addWorkingMemoryEntry()`、`setPriorityContext()`、`addManualEntry()`、`getPriorityContext()`、`getWorkingMemory()`、`formatNotepadContext()`、`pruneOldEntries()`
+
+## Notepad Wisdom 系统（计划范围）
+
+按计划范围捕获学习成果、决策、问题和挑战。
+
+**位置：** `.omc/notepads/{plan-name}/`
+
+| 文件 | 用途 |
+|------|---------|
+| `learnings.md` | 技术发现和模式 |
+| `decisions.md` | 架构和设计决策 |
+| `issues.md` | 已知问题和解决方案 |
+| `problems.md` | 阻塞项和挑战 |
+
+**API：** `initPlanNotepad()`、`addLearning()`、`addDecision()`、`addIssue()`、`addProblem()`、`getWisdomSummary()`、`readPlanWisdom()`
+
+## 委派类别
+
+语义化任务分类，自动映射到模型层级、温度和思考预算。
+
+| 类别 | 层级 | 温度 | 思考 | 用途 |
+|----------|------|-------------|----------|---------|
+| `visual-engineering` | HIGH | 0.7 | high | UI/UX、前端、设计系统 |
+| `ultrabrain` | HIGH | 0.3 | max | 复杂推理、架构、深度调试 |
+| `artistry` | MEDIUM | 0.9 | medium | 创意解决方案、头脑风暴 |
+| `quick` | LOW | 0.1 | low | 简单查询、基本操作 |
+| `writing` | MEDIUM | 0.5 | medium | 文档、技术写作 |
+
+**自动检测：** 类别根据 prompt 关键词自动识别。
+
+## 目录诊断工具
+
+通过 `lsp_diagnostics_directory` 工具进行项目级类型检查。
+
+**策略：**
+- `auto`（默认）- 自动选择最佳策略，存在 tsconfig.json 时优先使用 tsc
+- `tsc` - 快速，使用 TypeScript 编译器
+- `lsp` - 备用方案，通过 Language Server 逐文件检查
+
+**用途：** 在提交前或重构后检查整个项目的错误。
+
+## Session Resume
+
+后台 agent 可通过 `resume-session` 工具携带完整上下文恢复执行。
+
+## Ultrapilot（v3.4）
+
+并行 autopilot，最多支持 20 个并发 worker，执行速度提升 3-5 倍。
+
+**触发词：** "ultrapilot"、"parallel build"、"swarm build"
+
+**工作原理：**
+1. 任务分解引擎将复杂任务拆分为可并行的子任务
+2. 文件所有权协调器为 worker 分配不重叠的文件集
+3. Worker 并行执行，协调器管理共享文件
+4. 结果整合时进行冲突检测
+
+**最适合：** 多组件系统、全栈应用、大规模重构
+
+**状态文件：**
+- `.omc/state/ultrapilot-state.json` - Session 状态
+- `.omc/state/ultrapilot-ownership.json` - 文件所有权
+
+## Swarm（v3.4）
+
+N 个协调 agent，从共享任务池中原子性地认领任务。
+
+**用法：** `/swarm 5:executor "fix all TypeScript errors"`
+
+**特性：**
+- 共享任务列表，包含 pending/claimed/done 状态
+- 每个任务 5 分钟超时，超时后自动释放
+- 所有任务完成后干净退出
+
+## Pipeline（v3.4）
+
+顺序 agent 链，各阶段之间传递数据。
+
+**内置预设：**
+| 预设 | 阶段 |
+|--------|--------|
+| `review` | explore -> architect -> critic -> executor |
+| `implement` | planner -> executor -> tdd-guide |
+| `debug` | explore -> architect -> build-fixer |
+| `research` | parallel(document-specialist, explore) -> architect -> writer |
+| `refactor` | explore -> architect-medium -> executor-high -> qa-tester |
+| `security` | explore -> security-reviewer -> executor -> security-reviewer-low |
+
+**自定义 pipeline：** `/pipeline explore:haiku -> architect:opus -> executor:sonnet`
+
+## 统一取消（v3.4）
+
+智能取消，自动检测当前活跃模式。
+
+**用法：** `/cancel` 或直接说 "cancelomc"、"stopomc"
+
+自动检测并取消：autopilot、ultrapilot、ralph、ultrawork、ultraqa、swarm、pipeline
+使用 `--force` 或 `--all` 清除所有状态。
+
+## 验证模块（v3.4）
+
+可复用的工作流验证协议。
+
+**标准检查项：** BUILD、TEST、LINT、FUNCTIONALITY、ARCHITECT、TODO、ERROR_FREE
+
+**证据验证：** 5 分钟新鲜度检测，通过/失败追踪
+
+## 状态管理（v3.4）
+
+标准化的状态文件位置。
+
+**所有模式状态文件的标准路径：**
+- 主路径：`.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/partials/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/partials/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/partials/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...")
+```