@liangjie559567/ultrapower 7.5.2 → 7.7.0

package/docs/dev-experience/quick-reference.md

@@ -0,0 +1,114 @@
+# 快速参考卡片
+
+快速查找常用命令和解决方案。
+
+## 命令速查
+
+### omc repair 命令
+
+```bash
+# 交互式向导
+omc repair
+
+# 清理状态污染
+omc repair --fix-state-pollution
+
+# 清理孤儿 agent
+omc repair --fix-orphan-agents
+
+# 验证状态文件
+omc repair --validate-state
+
+# 预览修复（不执行）
+omc repair --fix-state-pollution --dry-run
+
+# 执行所有修复
+omc repair --fix-state-pollution --fix-orphan-agents --validate-state
+```
+
+### 状态管理
+
+```bash
+# 查看活跃状态
+ls -la .omc/state/
+
+# 查看状态内容
+cat .omc/state/autopilot-state.json | jq .
+
+# 备份状态
+cp -r .omc/state .omc/state.backup
+
+# 清理特定状态
+rm .omc/state/autopilot-state.json
+```
+
+### Agent 管理
+
+```bash
+# 列出活跃 agent
+ls -lh .omc/agents/
+
+# 检查 agent 大小
+du -sh .omc/agents/
+
+# 清理特定 agent
+rm -rf .omc/agents/<agent-id>
+
+# 查看后台任务
+list_jobs --status_filter=active
+```
+
+## 问题速查
+
+| 错误信息 | 原因 | 解决方案 |
+|---------|------|--------|
+| State already exists | 状态污染 | `omc repair --fix-state-pollution` |
+| Agent timeout | 执行超时 | 增加超时或分解任务 |
+| Invalid JSON | 状态损坏 | `omc repair --validate-state` |
+| Permission denied | 权限不足 | 检查 `.omc/` 目录权限 |
+| Orphan agent | 孤儿进程 | `omc repair --fix-orphan-agents` |
+
+## 工作流速查
+
+```bash
+# 快速诊断
+omc repair
+
+# 预览修复
+omc repair --fix-state-pollution --dry-run
+
+# 执行修复
+omc repair --fix-state-pollution
+
+# 验证完成
+omc repair --validate-state
+```
+
+## 日志查看
+
+```bash
+# 查看最新日志
+tail -f .omc/logs/*.log
+
+# 查看特定日志
+cat .omc/logs/repair.log
+
+# 搜索错误
+grep -r "ERROR" .omc/logs/
+```
+
+## 紧急恢复
+
+```bash
+# 1. 备份当前状态
+cp -r .omc/state .omc/state.emergency
+
+# 2. 清理所有状态
+rm -rf .omc/state/*
+
+# 3. 验证恢复
+omc repair --validate-state
+
+# 4. 如需回滚
+cp -r .omc/state.emergency/* .omc/state/
+```

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/getting-started/quickstart.md

@@ -1,4 +1,4 @@
-# 🚀 15 分钟快速上手指南
+# 🚀 15 分钟快速上手指南 - v7.6.0
 
 完整的 ultrapower 入门教程，从安装到第一个自主执行任务。