@liangjie559567/ultrapower 7.5.2 → 7.6.0

package/docs/dev-experience/troubleshooting-guide.md

@@ -0,0 +1,280 @@
+# 开发体验故障排除指南
+
+本指南帮助开发者快速诊断和解决 ultrapower 常见问题。
+
+## 常见问题
+
+### 1. 状态污染（State Pollution）
+
+**症状**
+- 执行 agent 任务时出现 "State already exists" 错误
+- 多个 session 之间状态相互干扰
+- `.omc/state/` 目录下存在多个过期的状态文件
+
+**原因**
+- 前一个 session 异常中断，状态文件未清理
+- 多个 worktree 共享同一个 `.omc/state/` 目录
+- 并发执行多个 agent 导致状态冲突
+
+**解决方案**
+
+使用 `omc repair` 命令清理污染状态：
+
+```bash
+# 交互式向导（推荐）
+omc repair
+
+# 直接清理状态污染
+omc repair --fix-state-pollution
+
+# 预览将要删除的文件（不执行）
+omc repair --fix-state-pollution --dry-run
+
+# 清理所有问题
+omc repair --fix-state-pollution --fix-orphan-agents --validate-state
+```
+
+**预防措施**
+- 使用独立的 worktree 进行并发工作
+- 正常退出 session 时调用 `/ultrapower:cancel`
+- 定期运行 `omc repair --validate-state` 检查状态完整性
+
+---
+
+### 2. 孤儿 Agent（Orphan Agents）
+
+**症状**
+- Agent 进程在后台持续运行，占用资源
+- 无法启动新的 agent 任务
+- `.omc/agents/` 目录下存在陈旧的 agent 目录
+
+**原因**
+- Agent 执行超时或被强制中断
+- 网络连接中断导致 agent 无法正常关闭
+- 系统崩溃或进程被杀死
+
+**解决方案**
+
+```bash
+# 清理超过 24 小时的孤儿 agent
+omc repair --fix-orphan-agents
+
+# 预览将要清理的 agent
+omc repair --fix-orphan-agents --dry-run
+
+# 手动清理特定 agent
+rm -rf .omc/agents/<agent-id>
+```
+
+**预防措施**
+- 为长时间运行的任务设置合理的超时时间
+- 使用 `--run-in-background` 时监控 job 状态
+- 定期检查 `.omc/agents/` 目录大小
+
+---
+
+### 3. 状态验证失败（State Validation Failure）
+
+**症状**
+- 错误信息：`Invalid JSON in <state-file>`
+- 状态文件损坏或格式错误
+- 无法读取或写入状态
+
+**原因**
+- 磁盘写入中断导致文件不完整
+- 并发写入导致 JSON 格式破坏
+- 文件权限问题
+
+**解决方案**
+
+```bash
+# 验证所有状态文件
+omc repair --validate-state
+
+# 手动修复损坏的状态文件
+cat .omc/state/<mode>-state.json | jq . > /tmp/backup.json
+# 检查 /tmp/backup.json 内容，然后恢复
+cp /tmp/backup.json .omc/state/<mode>-state.json
+```
+
+**预防措施**
+- 使用原子写入操作（atomic-write）
+- 避免在状态文件写入时强制关闭进程
+- 定期备份 `.omc/state/` 目录
+
+---
+
+## omc repair 命令使用指南
+
+### 交互式向导
+
+无参数运行 `omc repair` 启动交互式向导：
+
+```bash
+$ omc repair
+Interactive Repair Wizard
+1. Fix state pollution
+2. Fix orphan agents
+3. Validate state files
+
+Select action (1-3, or "all"): all
+Dry run? (y/n): y
+```
+
+**选项说明**
+- `1`: 清理跨 session 的状态污染
+- `2`: 移除超过 24 小时的孤儿 agent
+- `3`: 验证所有状态文件的 JSON 格式
+- `all`: 执行全部三项检查
+
+### 子命令
+
+#### 清理状态污染
+
+```bash
+omc repair --fix-state-pollution [--dry-run]
+```
+
+- 扫描 `.omc/state/` 目录
+- 识别非活跃的状态文件
+- 删除过期状态（保留活跃 session 的状态）
+
+#### 清理孤儿 Agent
+
+```bash
+omc repair --fix-orphan-agents [--dry-run]
+```
+
+- 扫描 `.omc/agents/` 目录
+- 检查 agent 目录的修改时间
+- 删除超过 24 小时未更新的 agent
+
+#### 验证状态文件
+
+```bash
+omc repair --validate-state
+```
+
+- 逐个检查 `.omc/state/` 中的 JSON 文件
+- 报告格式错误和损坏的文件
+- 输出验证统计信息
+
+### 干运行模式
+
+所有修复操作都支持 `--dry-run` 标志：
+
+```bash
+omc repair --fix-state-pollution --dry-run
+```
+
+输出示例：
+```
+[DRY RUN] Cleaning state pollution...
+[DRY RUN] Removing inactive state: autopilot-state.json
+[DRY RUN] Cleaned 1 state file(s)
+```
+
+---
+
+## 最佳实践
+
+### 状态管理
+
+1. **定期清理**
+   ```bash
+   # 每周运行一次验证
+   omc repair --validate-state
+   ```
+
+2. **监控状态大小**
+   ```bash
+   du -sh .omc/state/
+   ```
+
+3. **备份重要状态**
+   ```bash
+   cp -r .omc/state .omc/state.backup
+   ```
+
+### Agent 生命周期
+
+1. **正常退出**
+   ```bash
+   # 不要直接 Ctrl+C，使用 cancel 命令
+   /ultrapower:cancel
+   ```
+
+2. **超时处理**
+   - 为后台任务设置合理的超时时间
+   - 使用 `check_job_status` 监控长时间运行的任务
+
+3. **资源清理**
+   ```bash
+   # 定期检查孤儿 agent
+   ls -lh .omc/agents/
+   omc repair --fix-orphan-agents --dry-run
+   ```
+
+### 错误处理
+
+1. **捕获详细错误信息**
+   ```bash
+   # 启用详细日志
+   export OMC_LOG_LEVEL=debug
+   omc repair --validate-state
+   ```
+
+2. **逐步诊断**
+   - 先运行 `--dry-run` 预览
+   - 确认无误后执行实际修复
+   - 检查修复后的状态
+
+3. **恢复策略**
+   - 保留 `.omc/state.backup` 作为恢复点
+   - 记录修复前的状态快照
+   - 必要时使用 git 恢复历史版本
+
+---
+
+## 故障排除流程图
+
+```
+遇到问题
+  ↓
+检查错误信息
+  ├─ "State already exists" → 状态污染 → omc repair --fix-state-pollution
+  ├─ "Agent timeout" → 孤儿 agent → omc repair --fix-orphan-agents
+  ├─ "Invalid JSON" → 状态损坏 → omc repair --validate-state
+  └─ 其他错误 → 查看日志 → 手动诊断
+  ↓
+运行 omc repair --dry-run 预览
+  ↓
+确认修复内容无误
+  ↓
+执行实际修复
+  ↓
+验证问题已解决
+```
+
+---
+
+## 常用命令速查
+
+| 场景 | 命令 |
+|------|------|
+| 快速诊断 | `omc repair` |
+| 预览修复 | `omc repair --fix-state-pollution --dry-run` |
+| 清理所有问题 | `omc repair --fix-state-pollution --fix-orphan-agents --validate-state` |
+| 仅验证状态 | `omc repair --validate-state` |
+| 查看状态大小 | `du -sh .omc/state/` |
+| 列出活跃 agent | `ls -lh .omc/agents/` |
+| 手动清理 agent | `rm -rf .omc/agents/<id>` |
+
+---
+
+## 获取帮助
+
+- 查看 repair 命令帮助：`omc repair --help`
+- 查看日志：`cat .omc/logs/*.log`
+- 检查状态文件：`cat .omc/state/<mode>-state.json | jq .`
+- 提交 issue：https://github.com/anthropics/ultrapower/issues

package/docs/dev-standards/AGENTS.md

@@ -1,68 +1,68 @@
-<!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-03-14 | Updated: 2026-03-14 -->
-
-# docs/dev-standards/ - 开发规范体系
-
-**用途：** 编码前检查清单、充分性验证、质量审查规范。确保所有实现遵循一致的标准。
-
-**核心职责：** 定义编码流程、工具选择决策树、上下文收集协议。
-
-## 关键文件
-
-| 文件 | 描述 |
-| ------ | ------ |
-| `dev-standards.md` | 编码要求、语言规范、验证机制 |
-| `context-collection.md` | 编码前强制检索清单（7步） |
-| `sufficiency-checklist.md` | 充分性验证清单（7项必查） |
-| `workflow.md` | 工作流程、工具链顺序 |
-| `tools-integration.md` | 工具选择决策树 |
-| `quality-review.md` | 质量审查规范 |
-| `context-summary-template.md` | 上下文摘要模板 |
-
-## 强制执行点
-
-| 阶段 | 检查项 | 文档 |
-| ------ | ------ | ------ |
-| 编码前 | 7步检索清单 + 充分性验证 | context-collection.md |
-| 编码中 | 遵循项目约定、复用组件 | dev-standards.md |
-| 编码后 | 质量审查 + 本地验证 | quality-review.md |
-
-## 面向 AI 智能体
-
-### 在此目录中工作
-
-1. **执行编码前检查**
-   - 读取 `context-collection.md` 的 7 步清单
-   - 运行 `sufficiency-checklist.md` 的 7 项验证
-   - 填充 `context-summary-template.md`
-
-2. **选择工具**
-   - 查看 `tools-integration.md` 的决策树
-   - 根据任务类型选择合适工具
-   - 记录工具选择理由
-
-3. **质量审查**
-   - 遵循 `quality-review.md` 的规范
-   - 验证编码标准
-   - 检查测试覆盖率
-
-### 常见任务
-
-```typescript
-// 检查充分性
-import { SUFFICIENCY_CHECKLIST } from './sufficiency-checklist';
-const checks = SUFFICIENCY_CHECKLIST.map(c => c.verify());
-
-// 收集上下文
-import { CONTEXT_COLLECTION_STEPS } from './context-collection';
-const context = await Promise.all(
-  CONTEXT_COLLECTION_STEPS.map(s => s.execute())
-);
-```
-
-### 修改检查清单
-
-- [ ] 规范文档已更新
-- [ ] 示例代码已验证
-- [ ] 检查清单项完整
-- [ ] 工具决策树准确
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-03-14 | Updated: 2026-03-14 -->
+
+# docs/dev-standards/ - 开发规范体系
+
+**用途：** 编码前检查清单、充分性验证、质量审查规范。确保所有实现遵循一致的标准。
+
+**核心职责：** 定义编码流程、工具选择决策树、上下文收集协议。
+
+## 关键文件
+
+| 文件 | 描述 |
+| ------ | ------ |
+| `dev-standards.md` | 编码要求、语言规范、验证机制 |
+| `context-collection.md` | 编码前强制检索清单（7步） |
+| `sufficiency-checklist.md` | 充分性验证清单（7项必查） |
+| `workflow.md` | 工作流程、工具链顺序 |
+| `tools-integration.md` | 工具选择决策树 |
+| `quality-review.md` | 质量审查规范 |
+| `context-summary-template.md` | 上下文摘要模板 |
+
+## 强制执行点
+
+| 阶段 | 检查项 | 文档 |
+| ------ | ------ | ------ |
+| 编码前 | 7步检索清单 + 充分性验证 | context-collection.md |
+| 编码中 | 遵循项目约定、复用组件 | dev-standards.md |
+| 编码后 | 质量审查 + 本地验证 | quality-review.md |
+
+## 面向 AI 智能体
+
+### 在此目录中工作
+
+1. **执行编码前检查**
+   - 读取 `context-collection.md` 的 7 步清单
+   - 运行 `sufficiency-checklist.md` 的 7 项验证
+   - 填充 `context-summary-template.md`
+
+2. **选择工具**
+   - 查看 `tools-integration.md` 的决策树
+   - 根据任务类型选择合适工具
+   - 记录工具选择理由
+
+3. **质量审查**
+   - 遵循 `quality-review.md` 的规范
+   - 验证编码标准
+   - 检查测试覆盖率
+
+### 常见任务
+
+```typescript
+// 检查充分性
+import { SUFFICIENCY_CHECKLIST } from './sufficiency-checklist';
+const checks = SUFFICIENCY_CHECKLIST.map(c => c.verify());
+
+// 收集上下文
+import { CONTEXT_COLLECTION_STEPS } from './context-collection';
+const context = await Promise.all(
+  CONTEXT_COLLECTION_STEPS.map(s => s.execute())
+);
+```
+
+### 修改检查清单
+
+- [ ] 规范文档已更新
+- [ ] 示例代码已验证
+- [ ] 检查清单项完整
+- [ ] 工具决策树准确

package/docs/glossary.md

@@ -0,0 +1,174 @@
+# ultrapower 术语表
+
+> **版本**: v5.5.33 | **更新**: 2026-03-16
+
+核心术语分类参考。
+
+---
+
+## Agent（代理）
+
+**Agent** - 专业化的 AI 角色，处理特定类型的工作。ultrapower 包含 49 个 agent，分为 6 个通道。
+
+**Executor** - 代码实现 agent（Sonnet 模型）。处理多文件实现、重构、功能开发。
+
+**Verifier** - 验证 agent（Sonnet 模型）。收集完成证据（BUILD/TEST/LINT/TODO），验证声明。
+
+**Debugger** - 调试 agent（Sonnet 模型）。根因分析、回归隔离、故障诊断。
+
+**Architect** - 架构 agent（Opus 模型）。系统设计、边界定义、接口设计、长期权衡。
+
+**Planner** - 规划 agent（Opus 模型）。任务排序、执行计划、风险标记。
+
+**Explore** - 探索 agent（Haiku 模型）。代码库发现、符号/文件映射、快速扫描。
+
+**Deep-Executor** - 深度执行 agent（Opus 模型）。复杂自主目标导向任务，包含自我验证循环。
+
+---
+
+## Skill（技能）
+
+**Skill** - 行为注入器，修改编排器的运行方式。用户通过 `/ultrapower:<name>` 调用。
+
+**Autopilot** - 全自主执行模式。从想法到可运行代码，无需人工干预。触发词："autopilot"、"build me"。
+
+**Ralph** - 持久循环模式。带 verifier 验证的自引用循环，"不停止直到完成"。触发词："ralph"、"don't stop"。
+
+**Ultrawork** - 最大并行度编排。并行 agent 编排，多个 agent 同时工作。触发词："ulw"、"ultrawork"。
+
+**Team** - 多 agent 协调模式。使用 Claude Code 原生团队，分阶段流水线（plan→prd→exec→verify→fix）。
+
+**Pipeline** - 顺序链式执行。带数据传递的顺序 agent 链。
+
+**Ultrapilot** - Team 的兼容性外观。并行 autopilot，映射到 Team 分阶段运行时。
+
+**Swarm** - 分布式任务认领。N 个协调 agents，SQLite 任务队列，动态任务认领。
+
+---
+
+## Hook（钩子）
+
+**Hook** - 事件驱动的生命周期控制。Claude Code 触发 hook 事件，ultrapower 注册处理器。
+
+**Hook Event** - Claude Code 发出的事件类型。15 种类型：UserPromptSubmit、SubagentStart/Stop、SessionStart/End、PermissionRequest 等。
+
+**Hook Handler** - Hook 事件的处理函数。位于 `src/hooks/` 目录。
+
+**Keyword Detector** - 关键词检测 hook。识别魔法关键词（"autopilot"、"ralph"、"team"），激活对应 skill。
+
+**Bridge Normalize** - Hook 输入规范化。将 Claude Code 的 snake_case 输入转换为内部 camelCase，应用安全过滤。
+
+**SENSITIVE_HOOKS** - 敏感 hook 集合。permission-request、setup-init、setup-maintenance、session-end，严格白名单过滤。
+
+---
+
+## Mode（模式）
+
+**Mode** - 执行模式。8 个有效值：autopilot、ultrapilot、team、pipeline、ralph、ultrawork、ultraqa、swarm。
+
+**Valid Modes** - 白名单模式集合。`['autopilot', 'ultrapilot', 'team', 'pipeline', 'ralph', 'ultrawork', 'ultraqa', 'swarm']`。
+
+**Mode State** - 模式执行状态。存储于 `.omc/state/{mode}-state.json`，包含 active、current_phase、iteration 等字段。
+
+**Exclusive Modes** - 互斥模式。autopilot、ultrapilot、swarm、pipeline 互斥，同时只能激活一个。
+
+**Mode Stale** - 模式过期标记。1 小时未更新的模式状态标记为 stale（不同于 agent stale 的 5 分钟）。
+
+---
+
+## State（状态）
+
+**State File** - 模式状态持久化文件。JSON 格式，存储于 `.omc/state/{mode}-state.json`。
+
+**Session State** - 会话级状态。存储于 `.omc/state/sessions/{sessionId}/{mode}-state.json`，隔离并发会话。
+
+**Atomic Write** - 原子写入。通过临时文件 + rename 保证写入原子性，防止并发损坏。
+
+**State Manager** - 状态管理器。统一的读/写接口，强制路径安全校验（assertValidMode）。
+
+**Stale Threshold** - 过期阈值。Agent stale：5 分钟（警告日志）；Mode stale：1 小时（标记过期）。
+
+**Subagent Tracking** - Agent 生命周期追踪。`.omc/state/subagent-tracking.json`，记录活跃 agents、超时、孤儿检测。
+
+---
+
+## Tool（工具）
+
+**Tool** - 可调用的功能单元。35 个自定义工具：LSP x12、AST x2、REPL x1、Notepad x6、State x5、Memory x4、Trace x2、Skills x3。
+
+**LSP Tool** - 语言服务器协议工具。lsp_hover、lsp_goto_definition、lsp_find_references、lsp_diagnostics 等。
+
+**AST Tool** - 抽象语法树工具。ast_grep_search（结构化代码搜索）、ast_grep_replace（结构化转换）。
+
+**State Tool** - 状态管理工具。state_read、state_write、state_clear、state_list_active、state_get_status。
+
+**Notepad Tool** - 会话记忆工具。notepad_read、notepad_write_priority、notepad_write_working、notepad_write_manual。
+
+**MCP Tool** - 模型上下文协议工具。ask_codex（GPT-5.3）、ask_gemini（Gemini-3-pro）。
+
+---
+
+## 核心概念
+
+**Delegation** - 委派。将工作路由到专业 agent 而非直接处理。多文件实现、复杂重构、架构决策必须委派。
+
+**Model Routing** - 模型路由。任务复杂度 → 模型层级映射：Haiku（快速）→ Sonnet（标准）→ Opus（复杂）。
+
+**Verification** - 验证。完成前收集证据（BUILD/TEST/LINT/TODO/ERROR_FREE），verifier 确认。
+
+**Boulder State** - 岩石状态。Ralph/ultrawork 的持久化状态，"岩石永不停止"直到完成。
+
+**Magic Keyword** - 魔法关键词。用户输入中的触发词，激活对应 skill 或 mode。
+
+**Context Injection** - 上下文注入。在 hook 时注入 AGENTS.md、规则文件、Axiom 记忆。
+
+**Path Traversal Guard** - 路径遍历防护。assertValidMode() 校验 mode 参数，防止 `../../etc/passwd` 攻击。
+
+**Axiom System** - Axiom 系统。需求→PRD→实现→验证→知识演化的完整工作流引擎。
+
+---
+
+## 执行流程
+
+**Team Pipeline** - Team 分阶段流水线：team-plan → team-prd → team-exec → team-verify → team-fix（循环）。
+
+**Expert Gate** - 专家评审门禁。所有新功能需求必须通过 `/ax-draft` → `/ax-review` 流程。
+
+**User Gate** - 用户确认门禁。PRD 生成完成后，显示确认提示，用户确认才能进入开发。
+
+**CI Gate** - 编译提交门禁。代码修改完成后，必须执行 `tsc --noEmit && npm run build && npm test`，无错误才允许完成。
+
+**Scope Gate** - 范围门禁。修改文件时检查是否在 manifest 定义的 Impact Scope 内，越界修改需用户确认。
+
+---
+
+## 反模式
+
+**AP-S01** - 未校验 mode 参数直接拼接路径。路径遍历风险。正确做法：先调用 assertValidMode()。
+
+**AP-ST01** - 混淆两种 stale 阈值。Agent stale（5分钟）vs Mode stale（1小时）。
+
+**AP-ST02** - 跨会话误清理状态文件。必须检查 session_id 匹配后才能清理。
+
+**AP-ST03** - 在 `~/.claude/` 中存储 OMC 状态。应存储在 worktree 根目录 `.omc/state/`。
+
+**AP-AL02** - 混淆超时阈值。5 分钟（警告）vs 10 分钟（自动终止）。
+
+**AP-MR01** - 同时激活互斥模式。autopilot、ultrapilot、swarm、pipeline 互斥。
+
+**AP-MR02** - 使用不在白名单中的 mode。只能使用 VALID_MODES 中的 8 个值。
+
+---
+
+## 文件路径
+
+**Worktree Root** - Git worktree 根目录。所有 OMC 状态存储于此，不在 `~/.claude/`。
+
+**.omc/state/** - 模式状态目录。存储 `{mode}-state.json` 和 `sessions/{sessionId}/` 子目录。
+
+**.omc/axiom/** - Axiom 系统目录。active_context.md、project_decisions.md、evolution/ 等。
+
+**.omc/notepad.md** - 会话记忆文件。7 天自动清理的 working 部分 + 永久 manual 部分。
+
+**.omc/project-memory.json** - 项目记忆。持久化的项目知识、架构决策、用户偏好。
+