@liangjie559567/ultrapower 7.5.2 → 7.7.0

package/docs/audit/direct-write-scan.md

@@ -0,0 +1,88 @@
+# 直接写入点扫描报告
+
+## 扫描摘要
+- 发现直接写入点: 3
+- 需要修复: 3
+- 测试代码中的写入: 已排除（测试环境可接受）
+
+## 发现的直接写入点
+
+### 1. src/lib/file-lock.ts:66
+```typescript
+const meta: LockMeta = { pid: process.pid, timestamp: Date.now() };
+fs.writeFileSync(lockFile, JSON.stringify(meta), 'utf8');
+```
+**问题**: 未使用原子写入
+**影响**: 并发写入可能导致锁元数据损坏
+**严重性**: 高 - 锁机制本身需要可靠性
+**修复方案**: 替换为 atomicWriteJsonSyncWithRetry
+
+### 2. src/features/state-manager/wal.ts:57
+```typescript
+const walPath = path.join(this.walDir, `${id}.wal`);
+fs.writeFileSync(walPath, JSON.stringify(entry, null, 2));
+```
+**问题**: WAL 日志未使用原子写入
+**影响**: WAL 损坏会导致状态恢复失败
+**严重性**: 高 - WAL 是数据恢复的关键
+**修复方案**: 替换为 atomicWriteJsonSyncWithRetry
+
+### 3. src/features/state-manager/wal.ts:69
+```typescript
+entry.committed = true;
+const walPath = path.join(this.walDir, `${id}.wal`);
+fs.writeFileSync(walPath, JSON.stringify(entry, null, 2));
+```
+**问题**: WAL commit 标记未使用原子写入
+**影响**: commit 状态不一致可能导致重复执行
+**严重性**: 高 - 影响事务完整性
+**修复方案**: 替换为 atomicWriteJsonSyncWithRetry
+
+### 4. src/security/audit-logger.ts:70
+```typescript
+fs.writeFileSync(this.logPath, JSON.stringify(this.events, null, 2));
+```
+**问题**: 审计日志未使用原子写入
+**影响**: 日志损坏可能导致审计追踪丢失
+**严重性**: 中 - 影响安全审计能力
+**修复方案**: 替换为 atomicWriteJsonSyncWithRetry
+
+## 修复清单
+
+### 高优先级（P0）
+1. src/lib/file-lock.ts:66 - acquireLock()
+2. src/features/state-manager/wal.ts:57 - begin()
+3. src/features/state-manager/wal.ts:69 - commit()
+
+### 中优先级（P1）
+4. src/security/audit-logger.ts:70 - save()
+
+## 修复模板
+
+```typescript
+// 修复前
+fs.writeFileSync(filePath, JSON.stringify(data));
+
+// 修复后
+import { atomicWriteJsonSyncWithRetry } from '../../lib/atomic-write.js';
+atomicWriteJsonSyncWithRetry(filePath, data);
+```
+
+## 已排除项
+
+以下文件中的 writeFileSync 调用已排除（测试代码）：
+- tests/**/*.test.ts
+- src/**/__tests__/**/*.test.ts
+- benchmarks/run.ts
+
+测试代码中的直接写入是可接受的，因为：
+1. 测试环境不涉及生产并发
+2. 测试需要快速失败以发现问题
+3. 测试数据可重建
+
+## 验证建议
+
+修复后应执行：
+1. 单元测试：验证原子写入行为
+2. 并发测试：模拟多进程写入场景
+3. 故障注入：测试写入中断恢复能力

package/docs/audit/subagent-stop-scan.md

@@ -0,0 +1,48 @@
+# SubagentStop 推断扫描报告
+
+## 扫描摘要
+- 发现使用点: 1
+- 需要修复: 0
+- 状态: ✅ 全部合规
+
+## 发现的使用点
+
+### src/hooks/subagent-tracker/index.ts:683
+```typescript
+// SDK does not provide `success` field, so default to 'completed' when undefined (Bug #1 fix)
+const succeeded = input.success !== false;
+```
+
+**状态**: ✅ 正确
+**推断规则**: `input.success !== false` 正确处理三种情况：
+- `undefined` (SDK 默认) → `true` (视为成功)
+- `true` → `true` (明确成功)
+- `false` → `false` (明确失败)
+
+## 扫描范围
+
+| 扫描目标 | 结果 |
+| -------- | ---- |
+| TypeScript 源代码 | 1 个使用点 |
+| 编译后 JS | 1 个使用点（同源） |
+| 文档/注释 | 多处规范说明 |
+
+## 修复清单
+
+无需修复。代码已遵循规范：
+- ✅ 使用 `input.success !== false` 而非直接读取
+- ✅ 包含设计意图注释
+- ✅ 符合 CLAUDE.md 安全规则
+
+## 规范验证
+
+| 规范文档 | 验证结果 |
+| -------- | -------- |
+| CLAUDE.md (L130) | ✅ 遵循 |
+| docs/FEATURES.md (L973-981) | ✅ 遵循 |
+| docs/standards/anti-patterns.md (L48-58) | ✅ 遵循 |
+| docs/standards/agent-lifecycle.md (L191-233) | ✅ 遵循 |
+
+## 结论
+
+代码库中 `input.success` 的使用已完全合规，无需进行修复操作。

package/docs/dev-experience/README.md

@@ -0,0 +1,226 @@
+# 开发体验文档
+
+欢迎来到 ultrapower 开发体验文档。本目录包含帮助开发者快速诊断问题、遵循最佳实践的完整指南。
+
+## 文档导航
+
+### 📋 [故障排除指南](./troubleshooting-guide.md)
+快速诊断和解决常见问题。
+
+**包含内容**
+- 状态污染问题诊断和修复
+- 孤儿 agent 清理方法
+- 状态验证失败处理
+- `omc repair` 命令详细用法
+- 预防措施和最佳实践
+
+**快速开始**
+```bash
+omc repair                    # 交互式向导
+omc repair --dry-run          # 预览修复
+```
+
+---
+
+### 🎯 [最佳实践指南](./best-practices.md)
+提高开发效率和代码质量的核心实践。
+
+**包含内容**
+- 工作流最佳实践（任务规划、代码审查、错误处理）
+- 状态管理最佳实践（初始化、并发控制、备份）
+- Agent 生命周期管理
+- 代码质量标准（类型安全、路径安全、输入消毒）
+- 测试策略和覆盖率目标
+- 性能优化建议
+- 调试技巧
+- 提交和发布规范
+
+**核心原则**
+- 使用 Team 模式进行复杂任务
+- 为并发工作创建独立 worktree
+- 定期运行 `omc repair --validate-state`
+- 使用 `/ultrapower:cancel` 正常退出
+
+---
+
+### ⚡ [快速参考卡片](./quick-reference.md)
+常用命令和问题速查表。
+
+**包含内容**
+- omc repair 命令速查
+- 状态管理命令
+- Agent 管理命令
+- 常见错误和解决方案
+- 工作流速查
+- 日志查看命令
+- 紧急恢复步骤
+
+**快速查找**
+```bash
+# 查看活跃状态
+ls -la .omc/state/
+
+# 验证状态完整性
+omc repair --validate-state
+
+# 清理孤儿 agent
+omc repair --fix-orphan-agents
+```
+
+---
+
+## 常见场景
+
+### 我遇到了 "State already exists" 错误
+
+→ 查看 [故障排除指南 - 状态污染](./troubleshooting-guide.md#1-状态污染state-pollution)
+
+```bash
+omc repair --fix-state-pollution
+```
+
+### 我想了解如何正确管理状态
+
+→ 查看 [最佳实践指南 - 状态管理](./best-practices.md#状态管理最佳实践)
+
+### 我需要快速查找一个命令
+
+→ 查看 [快速参考卡片](./quick-reference.md)
+
+### 我的 agent 任务超时了
+
+→ 查看 [最佳实践指南 - Agent 生命周期](./best-practices.md#agent-生命周期最佳实践)
+
+### 我想了解代码质量标准
+
+→ 查看 [最佳实践指南 - 代码质量](./best-practices.md#代码质量最佳实践)
+
+---
+
+## 核心命令
+
+### 诊断和修复
+
+```bash
+# 交互式诊断向导
+omc repair
+
+# 预览修复（推荐先运行）
+omc repair --fix-state-pollution --dry-run
+
+# 执行修复
+omc repair --fix-state-pollution
+
+# 验证状态完整性
+omc repair --validate-state
+
+# 清理孤儿 agent
+omc repair --fix-orphan-agents
+```
+
+### 状态检查
+
+```bash
+# 查看活跃状态文件
+ls -la .omc/state/
+
+# 查看状态内容
+cat .omc/state/autopilot-state.json | jq .
+
+# 检查状态大小
+du -sh .omc/state/
+```
+
+### 正常退出
+
+```bash
+# 使用 cancel 命令（推荐）
+/ultrapower:cancel
+
+# 不要直接 Ctrl+C（会导致状态污染）
+```
+
+---
+
+## 工作流建议
+
+### 启动新任务
+
+1. 验证状态完整性
+   ```bash
+   omc repair --validate-state
+   ```
+
+2. 选择合适的执行模式
+   - 简单任务：`/autopilot`
+   - 复杂任务：`/team`
+   - 并行任务：`/ultrawork`
+
+3. 监控执行进度
+   ```bash
+   check_job_status <job-id>
+   ```
+
+### 完成任务
+
+1. 使用 cancel 命令正常退出
+   ```bash
+   /ultrapower:cancel
+   ```
+
+2. 验证状态已清理
+   ```bash
+   ls -la .omc/state/
+   ```
+
+3. 定期清理孤儿 agent
+   ```bash
+   omc repair --fix-orphan-agents --dry-run
+   ```
+
+---
+
+## 故障排除流程
+
+```
+遇到问题
+  ↓
+查看错误信息
+  ↓
+在快速参考卡片中查找
+  ↓
+按照故障排除指南诊断
+  ↓
+运行 omc repair --dry-run 预览
+  ↓
+执行修复
+  ↓
+验证问题已解决
+```
+
+---
+
+## 相关文档
+
+- [开发标准](../dev-standards/dev-standards.md)
+- [Hook 执行顺序](../standards/hook-execution-order.md)
+- [状态机规范](../standards/state-machine.md)
+- [Agent 生命周期](../standards/agent-lifecycle.md)
+- [运行时保护](../standards/runtime-protection.md)
+
+---
+
+## 获取帮助
+
+- **查看命令帮助**：`omc repair --help`
+- **查看日志**：`tail -f .omc/logs/*.log`
+- **检查状态**：`cat .omc/state/<mode>-state.json | jq .`
+- **提交 issue**：https://github.com/anthropics/ultrapower/issues
+
+---
+
+## 文档更新日期
+
+- 最后更新：2026-03-16
+- 版本：1.0
+- 适用于：ultrapower v7.5.2+

package/docs/dev-experience/best-practices.md

@@ -0,0 +1,364 @@
+# 开发最佳实践指南
+
+本指南提供 ultrapower 开发的核心最佳实践，帮助团队提高效率和代码质量。
+
+## 工作流最佳实践
+
+### 1. 任务规划
+
+**使用 Team 模式进行复杂任务**
+
+```bash
+# 多 agent 协调执行
+/team "实现用户认证功能"
+```
+
+Team 会自动路由到：
+- `explore` - 代码库探索
+- `planner` - 任务分解
+- `executor` - 代码实现
+- `verifier` - 质量验证
+
+**优势**
+- 自动分阶段执行
+- 并行处理独立任务
+- 内置质量检查
+
+### 2. 代码审查
+
+**使用专业审查 agent**
+
+```bash
+# 代码质量审查
+/code-review "src/hooks/handlers/post-tool-use.ts"
+
+# 安全审查
+/security-review "src/security/concurrency-control.ts"
+
+# 性能审查
+Task(subagent_type="ultrapower:performance-reviewer", prompt="...")
+```
+
+**审查清单**
+- [ ] 逻辑正确性
+- [ ] 安全漏洞
+- [ ] 性能瓶颈
+- [ ] 代码风格
+- [ ] 测试覆盖
+
+### 3. 错误处理
+
+**统一的错误处理模式**
+
+```typescript
+// ✅ 好的做法
+try {
+  const result = await operation();
+  return result;
+} catch (error) {
+  logger.error('Operation failed', { error, context });
+  throw new AppError('OPERATION_FAILED', 'User-friendly message', { cause: error });
+}
+
+// ❌ 避免
+try {
+  await operation();
+} catch (e) {
+  console.log('error'); // 不清晰
+}
+```
+
+**错误分类**
+- `ValidationError` - 输入验证失败
+- `StateError` - 状态管理问题
+- `TimeoutError` - 执行超时
+- `PermissionError` - 权限不足
+
+---
+
+## 状态管理最佳实践
+
+### 1. 状态初始化
+
+**检查清单**
+
+```bash
+# 启动前验证状态
+omc repair --validate-state --dry-run
+
+# 确保没有污染状态
+ls -la .omc/state/
+```
+
+### 2. 并发控制
+
+**使用独立 worktree**
+
+```bash
+# 为每个并发任务创建独立 worktree
+git worktree add ../work-feature-1 -b feature-1 dev
+git worktree add ../work-feature-2 -b feature-2 dev
+
+# 各自独立的 .omc/state/ 目录
+```
+
+**避免状态冲突**
+- 不要在多个 worktree 中共享 `.omc/state/`
+- 使用 `--working-directory` 指定工作目录
+- 定期清理过期状态
+
+### 3. 状态备份
+
+```bash
+# 重要操作前备份
+cp -r .omc/state .omc/state.backup.$(date +%s)
+
+# 恢复备份
+cp -r .omc/state.backup.1234567890/* .omc/state/
+```
+
+---
+
+## Agent 生命周期最佳实践
+
+### 1. 启动 Agent
+
+**使用合适的 agent 类型**
+
+| 任务类型 | 推荐 Agent | 模型 |
+|---------|-----------|------|
+| 代码库探索 | `explore` | haiku |
+| 需求分析 | `analyst` | opus |
+| 代码实现 | `executor` | sonnet |
+| 质量验证 | `verifier` | sonnet |
+| 架构设计 | `architect` | opus |
+
+### 2. 监控执行
+
+```bash
+# 检查后台任务状态
+check_job_status <job-id>
+
+# 等待任务完成（最多 1 小时）
+wait_for_job <job-id>
+
+# 列出所有活跃任务
+list_jobs --status_filter=active
+```
+
+### 3. 正常关闭
+
+```bash
+# ✅ 推荐：使用 cancel 命令
+/ultrapower:cancel
+
+# ❌ 避免：直接 Ctrl+C
+# 会导致状态污染和孤儿 agent
+```
+
+---
+
+## 代码质量最佳实践
+
+### 1. 类型安全
+
+```typescript
+// ✅ 使用严格类型
+interface AgentConfig {
+  mode: ExecutionMode;
+  timeout: number;
+  retries: number;
+}
+
+// ❌ 避免 any
+const config: any = { mode: 'autopilot' };
+```
+
+### 2. 路径安全
+
+```typescript
+// ✅ 验证 mode 参数
+import { assertValidMode } from './lib/validateMode';
+const validMode = assertValidMode(mode);
+const path = `.omc/state/${validMode}-state.json`;
+
+// ❌ 直接拼接路径
+const path = `.omc/state/${mode}-state.json`;
+```
+
+### 3. 输入消毒
+
+```typescript
+// ✅ 使用白名单过滤
+const sanitized = filterByWhitelist(input, ALLOWED_FIELDS);
+
+// ❌ 直接使用用户输入
+const config = JSON.parse(userInput);
+```
+
+---
+
+## 测试最佳实践
+
+### 1. 单元测试
+
+```bash
+# 运行单次测试（不是 watch 模式）
+npm test -- --run
+
+# 运行特定文件
+npm test -- src/hooks/__tests__/bridge-routing.test.ts --run
+
+# 生成覆盖率报告
+npm test -- --coverage --run
+```
+
+### 2. 集成测试
+
+```bash
+# 测试 repair 命令
+npm test -- src/cli/commands/repair.test.ts --run
+
+# 测试状态管理
+npm test -- src/state/__tests__/ --run
+```
+
+### 3. 测试覆盖率目标
+
+- 核心库：> 90%
+- 工具函数：> 85%
+- 集成代码：> 70%
+
+---
+
+## 性能最佳实践
+
+### 1. 并行化策略
+
+```bash
+# 使用 ultrawork 进行最大并行度
+/ultrawork "并行执行多个独立任务"
+
+# 使用 Team 进行阶段并行
+/team "多阶段任务"
+```
+
+### 2. 资源监控
+
+```bash
+# 检查状态文件大小
+du -sh .omc/state/
+
+# 检查 agent 目录大小
+du -sh .omc/agents/
+
+# 定期清理
+omc repair --fix-orphan-agents
+```
+
+### 3. 超时配置
+
+```typescript
+// 根据任务类型设置合理超时
+const TIMEOUTS = {
+  quick: 30_000,      // 30 秒
+  standard: 300_000,  // 5 分钟
+  long: 1_800_000,    // 30 分钟
+};
+```
+
+---
+
+## 调试最佳实践
+
+### 1. 启用详细日志
+
+```bash
+# 设置日志级别
+export OMC_LOG_LEVEL=debug
+
+# 查看日志
+tail -f .omc/logs/*.log
+```
+
+### 2. 状态检查
+
+```bash
+# 查看当前状态
+cat .omc/state/autopilot-state.json | jq .
+
+# 检查活跃 mode
+ls -la .omc/state/
+```
+
+### 3. 逐步诊断
+
+```bash
+# 1. 验证状态完整性
+omc repair --validate-state
+
+# 2. 检查孤儿 agent
+omc repair --fix-orphan-agents --dry-run
+
+# 3. 清理污染状态
+omc repair --fix-state-pollution --dry-run
+```
+
+---
+
+## 提交和发布最佳实践
+
+### 1. 提交规范
+
+```bash
+# 格式：type(scope): description
+git commit -m "feat(repair): add state validation command"
+git commit -m "fix(hooks): handle concurrent state writes"
+git commit -m "docs(guide): add troubleshooting section"
+```
+
+### 2. PR 检查清单
+
+- [ ] 代码通过 linter
+- [ ] 所有测试通过
+- [ ] 类型检查无错误
+- [ ] 代码审查通过
+- [ ] 文档已更新
+- [ ] 向后兼容
+
+### 3. 发布流程
+
+```bash
+# 1. 更新版本
+npm version patch|minor|major
+
+# 2. 构建
+npm run build
+
+# 3. 测试
+npm test -- --run
+
+# 4. 发布
+npm publish
+```
+
+---
+
+## 常见陷阱和解决方案
+
+| 陷阱 | 症状 | 解决方案 |
+|------|------|--------|
+| 状态污染 | "State already exists" | `omc repair --fix-state-pollution` |
+| 孤儿 agent | 资源泄漏 | `omc repair --fix-orphan-agents` |
+| 并发冲突 | 随机失败 | 使用独立 worktree |
+| 超时 | 任务中断 | 增加超时时间或分解任务 |
+| 权限错误 | 无法写入状态 | 检查 `.omc/` 目录权限 |
+
+---
+
+## 参考资源
+
+- [故障排除指南](./troubleshooting-guide.md)
+- [开发标准](../dev-standards/dev-standards.md)
+- [Hook 执行顺序](../standards/hook-execution-order.md)
+- [状态机规范](../standards/state-machine.md)