@liangjie559567/ultrapower 7.5.2 → 7.7.0

package/docs/standards/cascade-failure.md

@@ -0,0 +1,324 @@
+# 级联失败策略规范
+
+> **ultrapower-version**: 7.5.2
+> **优先级**: P0（必须遵守）
+> **真理之源**: `docs/standards/agent-lifecycle.md`
+> **覆盖范围**: T-035（级联失败策略文档）
+
+---
+
+## 目录
+
+1. [失败传播策略](#1-失败传播策略)
+2. [依赖链中断处理](#2-依赖链中断处理)
+3. [决策树](#3-决策树)
+4. [实现指南](#4-实现指南)
+
+---
+
+## 1. 失败传播策略
+
+### 1.1 失败类型分类
+
+| 失败类型 | 严重程度 | 默认传播策略 | 示例 |
+| -------- | -------- | ------------ | ---- |
+| `CRITICAL` | P0 | 立即停止所有依赖 Agent | 安全漏洞检测失败、数据损坏 |
+| `BLOCKING` | P1 | 停止强依赖 Agent，继续弱依赖 | 编译失败、API 不可用 |
+| `DEGRADED` | P2 | 继续执行（降级模式） | 性能优化失败、文档生成失败 |
+| `WARNING` | P3 | 继续执行（记录警告） | 代码风格问题、非关键测试失败 |
+
+### 1.2 Agent 优先级定义
+
+基于 `agent-lifecycle.md` 的 Agent 分类：
+
+| Agent 类型 | 优先级 | 失败影响 |
+| ---------- | ------ | -------- |
+| `architect`, `planner`, `analyst` | P0（关键） | 失败 → 停止所有下游 Agent |
+| `executor`, `debugger`, `build-fixer` | P1（核心） | 失败 → 停止强依赖 Agent |
+| `verifier`, `test-engineer` | P1（核心） | 失败 → 触发 fix 循环 |
+| `code-reviewer`, `security-reviewer` | P2（重要） | 失败 → 降级继续或人工介入 |
+| `style-reviewer`, `writer` | P3（辅助） | 失败 → 记录警告，继续执行 |
+
+### 1.3 传播决策因素
+
+**立即停止条件**（满足任一即触发）：
+
+1. **关键 Agent 失败**：`architect`、`planner`、`analyst` 失败
+2. **安全风险**：`security-reviewer` 检测到 P0 漏洞
+3. **数据完整性**：状态文件损坏、依赖图循环
+4. **资源耗尽**：成本超限（`COST_LIMIT_USD`）、超时（10 分钟自动终止）
+
+**继续执行条件**（满足所有条件）：
+
+1. **非关键 Agent**：P2/P3 优先级 Agent
+2. **无强依赖**：下游 Agent 不依赖失败 Agent 的输出
+3. **降级可行**：存在备用方案或默认行为
+
+---
+
+## 2. 依赖链中断处理
+
+### 2.1 依赖类型定义
+
+基于 `agent-lifecycle.md` 第 7 节（并行任务依赖管理）：
+
+| 依赖类型 | 定义 | 上游失败处理 |
+| -------- | ---- | ------------ |
+| **强依赖**（Hard Dependency） | 下游 Agent 必须使用上游输出 | 上游失败 → 下游跳过（`SKIPPED` 状态） |
+| **弱依赖**（Soft Dependency） | 下游 Agent 可选使用上游输出 | 上游失败 → 下游继续（降级模式） |
+| **顺序依赖**（Sequential Dependency） | 仅要求执行顺序，无数据依赖 | 上游失败 → 下游继续 |
+
+### 2.2 强依赖中断处理
+
+**场景**：任务 2 强依赖任务 1 的输出
+
+```typescript
+// 任务依赖声明
+TaskUpdate({ taskId: "2", addBlockedBy: ["1"] });
+```
+
+**失败处理流程**：
+
+```
+1. 任务 1 失败（status: "failed"）
+2. 系统检测到任务 2 的 blockedBy 包含任务 1
+3. 任务 2 自动标记为 SKIPPED
+4. 任务 2 的下游任务递归检查依赖链
+5. 记录失败原因：`skipped_reason: "Upstream task 1 failed"`
+```
+
+### 2.3 弱依赖降级处理
+
+**场景**：任务 3 弱依赖任务 1 的优化结果
+
+```typescript
+// 弱依赖通过元数据标记
+TaskCreate({
+  taskId: "3",
+  metadata: { weakDependencies: ["1"] }
+});
+```
+
+**降级处理流程**：
+
+```
+1. 任务 1 失败（例如：性能优化失败）
+2. 任务 3 检测到弱依赖失败
+3. 任务 3 使用默认配置继续执行
+4. 记录降级信息：`degraded: true, reason: "Weak dependency 1 failed"`
+```
+
+### 2.4 依赖链循环检测
+
+基于 `agent-lifecycle.md` 第 1.4 节（死锁检测）：
+
+```typescript
+// 常量定义（来自 subagent-tracker/index.ts）
+export const DEADLOCK_CHECK_THRESHOLD = 3;
+
+// 循环依赖检测伪代码
+function detectCircularDependency(tasks: Task[]): boolean {
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  for (const task of tasks) {
+    if (hasCycle(task.taskId, visited, recursionStack, tasks)) {
+      return true; // 检测到循环
+    }
+  }
+  return false;
+}
+```
+
+**循环依赖处理**：
+
+1. 检测到循环 → 立即标记为 `CRITICAL` 失败
+2. 停止所有涉及循环的 Agent
+3. 生成 `AgentIntervention`：`type: "deadlock"`
+4. 通知用户并提供依赖图可视化
+
+---
+
+## 3. 决策树
+
+### 3.1 失败传播决策流程
+
+```mermaid
+graph TD
+    A[Agent 失败] --> B{Agent 优先级?}
+    B -->|P0 关键| C[立即停止所有依赖 Agent]
+    B -->|P1 核心| D{依赖类型?}
+    B -->|P2/P3 辅助| E[继续执行]
+
+    D -->|强依赖| F[停止强依赖 Agent]
+    D -->|弱依赖| G[降级模式继续]
+    D -->|顺序依赖| E
+
+    C --> H[标记下游为 SKIPPED]
+    F --> H
+    G --> I[标记下游为 DEGRADED]
+    E --> J[记录警告]
+
+    H --> K[生成失败报告]
+    I --> K
+    J --> K
+
+    K --> L{是否触发 fix 循环?}
+    L -->|是| M[进入 team-fix 阶段]
+    L -->|否| N[终止执行]
+```
+
+### 3.2 依赖链中断决策流程
+
+```mermaid
+graph TD
+    A[上游 Agent 失败] --> B{检查下游依赖}
+    B --> C{依赖类型?}
+
+    C -->|强依赖| D[标记下游为 SKIPPED]
+    C -->|弱依赖| E{降级方案可用?}
+    C -->|顺序依赖| F[继续执行下游]
+
+    E -->|是| G[使用降级方案]
+    E -->|否| D
+
+    D --> H[递归检查下游的下游]
+    G --> I[标记为 DEGRADED]
+    F --> J[正常执行]
+
+    H --> K{还有未处理的下游?}
+    K -->|是| B
+    K -->|否| L[完成失败传播]
+```
+
+### 3.3 常见失败场景决策
+
+| 场景 | Agent 类型 | 失败类型 | 决策 |
+| ---- | ---------- | -------- | ---- |
+| 架构设计失败 | `architect` | `CRITICAL` | 停止所有，通知用户 |
+| 编译失败 | `build-fixer` | `BLOCKING` | 停止强依赖，触发 fix 循环 |
+| 单元测试失败 | `test-engineer` | `BLOCKING` | 触发 fix 循环（最多 3 次） |
+| 代码审查警告 | `code-reviewer` | `WARNING` | 继续执行，记录警告 |
+| 文档生成失败 | `writer` | `DEGRADED` | 继续执行，跳过文档 |
+| 性能优化失败 | `performance-reviewer` | `DEGRADED` | 降级为默认配置 |
+| 超时（10 分钟） | 任意 Agent | `CRITICAL` | 自动终止（`auto_execute: true`） |
+| 成本超限（$1.0） | 任意 Agent | `WARNING` | 警告但不终止（`auto_execute: false`） |
+
+---
+
+## 4. 实现指南
+
+### 4.1 失败状态定义
+
+```typescript
+// 扩展 AgentIntervention 接口（基于 agent-lifecycle.md 第 5 节）
+export interface AgentFailure extends AgentIntervention {
+  type: "timeout" | "deadlock" | "excessive_cost" | "file_conflict" | "execution_error";
+  severity: "CRITICAL" | "BLOCKING" | "DEGRADED" | "WARNING";
+  propagation_strategy: "stop_all" | "stop_hard_deps" | "degrade" | "continue";
+  affected_agents: string[]; // 受影响的下游 Agent ID
+}
+```
+
+### 4.2 依赖链遍历算法
+
+```typescript
+// 递归标记下游 Agent
+function propagateFailure(
+  failedAgentId: string,
+  tasks: Task[],
+  strategy: "stop_all" | "stop_hard_deps" | "degrade"
+): string[] {
+  const affected: string[] = [];
+
+  for (const task of tasks) {
+    if (task.blockedBy?.includes(failedAgentId)) {
+      // 检查依赖类型
+      const isHardDep = !task.metadata?.weakDependencies?.includes(failedAgentId);
+
+      if (strategy === "stop_all" || (strategy === "stop_hard_deps" && isHardDep)) {
+        task.status = "skipped";
+        task.metadata.skipped_reason = `Upstream agent ${failedAgentId} failed`;
+        affected.push(task.taskId);
+
+        // 递归处理下游
+        affected.push(...propagateFailure(task.taskId, tasks, strategy));
+      } else if (strategy === "degrade") {
+        task.metadata.degraded = true;
+        task.metadata.degraded_reason = `Weak dependency ${failedAgentId} failed`;
+      }
+    }
+  }
+
+  return affected;
+}
+```
+
+### 4.3 Team Pipeline 集成
+
+基于 `CLAUDE.md` 的 `<team_pipeline>` 规范：
+
+```typescript
+// team-verify 阶段失败处理
+function handleVerificationFailure(
+  verificationResult: VerificationResult,
+  teamState: TeamState
+): TeamPhase {
+  if (verificationResult.severity === "CRITICAL") {
+    // 关键失败 → 直接终止
+    return "failed";
+  } else if (verificationResult.severity === "BLOCKING") {
+    // 阻塞失败 → 进入 fix 循环
+    teamState.fix_loop_count++;
+    if (teamState.fix_loop_count > MAX_FIX_ATTEMPTS) {
+      return "failed"; // 超过最大尝试次数
+    }
+    return "team-fix";
+  } else {
+    // 降级/警告 → 继续完成
+    teamState.metadata.degraded = true;
+    return "complete";
+  }
+}
+```
+
+### 4.4 监控与日志
+
+```typescript
+// 失败事件记录
+interface FailureEvent {
+  timestamp: string;
+  agent_id: string;
+  agent_type: string;
+  failure_type: string;
+  severity: string;
+  propagation_strategy: string;
+  affected_agents: string[];
+  recovery_action: "retry" | "skip" | "degrade" | "abort";
+}
+
+// 写入审计日志
+function logFailureEvent(event: FailureEvent): void {
+  const logPath = path.join(directory, ".omc", "logs", "cascade-failures.json");
+  appendJsonLog(logPath, event);
+}
+```
+
+---
+
+## 5. 参考规范
+
+| 规范文档 | 相关章节 |
+| -------- | -------- |
+| `agent-lifecycle.md` | 第 1 节（Agent 边界情况矩阵） |
+| `agent-lifecycle.md` | 第 7 节（并行任务依赖管理） |
+| `state-machine.md` | Team Pipeline 状态转换 |
+| `CLAUDE.md` | `<team_pipeline>` 阶段路由 |
+
+---
+
+## 6. 版本历史
+
+| 版本 | 日期 | 变更内容 |
+| ---- | ---- | -------- |
+| 1.0.0 | 2026-03-16 | 初始版本（T-035） |

package/docs/standards/runtime-protection.md

@@ -308,6 +308,13 @@ try {
 
 * 所有涉及文件操作的代码必须考虑 Windows 平台行为差异
 
+* 使用 `maxRetries` 参数在 `atomicWriteJsonSyncWithRetry` 中提高鲁棒性
+
+**测试覆盖**：
+
+* Windows 平台兼容性测试：`tests/platform/windows-atomic-write.test.ts`
+* 测试在非 Windows 平台自动跳过（`skipIf(process.platform !== 'win32')`）
+
 #### 2.3.1 Windows 命令注入防护（SEC-H02）
 
 **来源**: v5.5.18 P0 修复 (2026-03-05)

package/docs/tech-debt/classification.md

@@ -0,0 +1,190 @@
+# 技术债务分级报告
+
+**生成日期**: 2026-03-16
+**扫描范围**: ultrapower v7.5.2 代码库
+**扫描方法**: 全代码库 TODO/FIXME/HACK 标记扫描
+
+---
+
+## 执行摘要
+
+| 指标 | 数量 |
+|------|------|
+| **总标记数** | 2 |
+| **P0 (高优先级)** | 0 |
+| **P1 (中优先级)** | 1 |
+| **P2 (低优先级)** | 1 |
+| **过期标记** | 0 |
+
+**结论**: 代码库技术债务管理良好，仅存在 2 个待处理标记，均为功能增强类型，无安全或稳定性风险。
+
+---
+
+## P0: 高优先级 (影响安全/稳定性/核心功能)
+
+**数量**: 0
+
+✅ 无 P0 级别技术债务
+
+---
+
+## P1: 中优先级 (影响性能/可维护性/用户体验)
+
+### 1. Claude Code Task API 集成缺失
+
+**文件**: `src/hud/progress-indicator.ts`
+**行号**: 50
+**标记类型**: TODO
+**代码上下文**:
+```typescript
+/**
+ * Get task list from Claude Code's task system
+ * TODO: Integrate with Claude Code Task API
+ */
+function getTaskList(cwd: string): TaskStatus[] {
+  const tasksDir = join(cwd, '.claude', 'tasks');
+  if (!existsSync(tasksDir)) return [];
+  // ... 当前返回空数组
+}
+```
+
+**影响分析**:
+- **功能**: HUD 进度指示器无法显示 Claude Code 原生任务状态
+- **用户体验**: 用户无法在 HUD 中看到完整的任务进度
+- **可维护性**: 当前实现为占位符，功能未完成
+
+**建议行动**:
+1. 调研 Claude Code Task API 的官方接口
+2. 实现任务状态读取逻辑
+3. 添加单元测试覆盖
+4. 更新 HUD 显示逻辑
+
+**预估工时**: 4-6 小时
+
+---
+
+## P2: 低优先级 (代码质量改进/优化建议)
+
+### 1. MCP 工具 Schema 自定义预留
+
+**文件**: `src/mcp/job-management.ts`
+**行号**: 865
+**标记类型**: TODO
+**代码上下文**:
+```typescript
+// TODO: _provider parameter reserved for future per-provider schema customization
+export function getJobManagementToolSchemas(_provider?: 'codex' | 'gemini') {
+  return [
+    {
+      name: 'wait_for_job',
+      description: '...',
+      // ... 统一的 schema 定义
+    }
+  ];
+}
+```
+
+**影响分析**:
+- **功能**: 当前所有 MCP 提供商使用统一 schema
+- **扩展性**: 未来可能需要针对不同提供商定制 schema
+- **当前状态**: 参数已预留但未使用，不影响现有功能
+
+**建议行动**:
+1. 评估是否真正需要 per-provider schema 差异化
+2. 如不需要，移除 `_provider` 参数和 TODO 注释
+3. 如需要，设计 provider-specific schema 映射机制
+
+**预估工时**: 2-3 小时
+
+---
+
+## 过期标记分析
+
+**数量**: 0
+
+✅ 未发现已修复但未删除的标记
+
+---
+
+## 测试文件中的标记 (不计入技术债务)
+
+以下标记出现在测试文件中，用于测试场景构造，不属于技术债务：
+
+1. `src/__tests__/installer.test.ts:557-558` - 测试 TODO 模式匹配
+2. `src/hooks/comment-checker/__tests__/index.test.ts:7` - 测试注释检查
+3. `src/hooks/workflow-gate/__tests__/quality-gate-sync.test.ts` - 多处测试用例
+
+---
+
+## 文档中的标记 (不计入技术债务)
+
+以下标记出现在文档和研究文件中，用于说明或示例：
+
+1. `.omc/research/review-tech.md:319` - 历史审计记录
+2. `.omc/research/pain-points.md:342-344` - 示例代码片段
+3. `docs/reviews/bugs-pain-points-audit/review_ux.md:132` - 功能建议示例
+
+---
+
+## 清理优先级清单
+
+### 立即处理 (本周)
+- 无
+
+### 短期处理 (2 周内)
+- [ ] **P1-001**: 实现 Claude Code Task API 集成 (`src/hud/progress-indicator.ts:50`)
+
+### 长期处理 (1 个月内)
+- [ ] **P2-001**: 评估并处理 MCP provider schema 预留参数 (`src/mcp/job-management.ts:865`)
+
+---
+
+## 代码质量评估
+
+### 优势
+1. ✅ **技术债务控制优秀**: 仅 2 个待处理标记
+2. ✅ **无安全风险**: 无 P0 级别债务
+3. ✅ **无过期标记**: 代码维护及时
+4. ✅ **测试覆盖良好**: 测试文件中标记用于测试场景，非实际债务
+
+### 改进建议
+1. 完成 HUD Task API 集成，提升用户体验
+2. 明确 MCP schema 定制需求，避免过度设计
+
+---
+
+## 附录: 扫描方法
+
+### 搜索模式
+```bash
+# 源代码扫描
+grep -rn "// TODO:\|// FIXME:\|// HACK:" src --include="*.ts"
+
+# 排除项
+- node_modules/
+- dist/
+- .git/
+- 测试文件 (__tests__/, *.test.ts)
+```
+
+### 分级标准
+
+**P0 (高优先级)**:
+- 影响安全性 (路径遍历、注入漏洞、权限绕过)
+- 影响稳定性 (崩溃、数据丢失、死锁)
+- 阻塞核心功能 (关键路径失败)
+
+**P1 (中优先级)**:
+- 影响性能 (明显延迟、内存泄漏)
+- 影响可维护性 (代码重复、耦合过高)
+- 影响用户体验 (功能缺失、交互不佳)
+
+**P2 (低优先级)**:
+- 代码质量改进 (命名、注释、格式)
+- 优化建议 (非关键性能提升)
+- 未来扩展预留 (当前不影响功能)
+
+---
+
+**报告生成者**: ultrapower Team
+**审核状态**: ✅ 已完成

package/docs/tech-debt/cleanup-report.md

@@ -0,0 +1,172 @@
+# 技术债务清理报告
+
+**生成日期**: 2026-03-16
+**报告周期**: T-037 分级 → T-038 清理 → T-039 总结
+**报告状态**: ✅ 已完成
+
+---
+
+## 执行摘要
+
+| 指标 | 清理前 | 清理后 | 变化 |
+|------|-------|-------|------|
+| **总标记数** | 2 | 1 | ↓ 50% |
+| **P0 (高优先级)** | 0 | 0 | — |
+| **P1 (中优先级)** | 1 | 0 | ✅ 已清理 |
+| **P2 (低优先级)** | 1 | 1 | — |
+
+**结论**: P1 级别技术债务已成功清理，代码库技术债务管理进一步优化。剩余 P2 标记为低优先级扩展预留，不影响现有功能。
+
+---
+
+## 清理前后对比
+
+### 清理前状态 (T-037)
+
+**P1 标记**:
+- `src/hud/progress-indicator.ts:50` - Claude Code Task API 集成缺失
+
+**P2 标记**:
+- `src/mcp/job-management.ts:865` - MCP 工具 Schema 自定义预留
+
+### 清理后状态 (T-038)
+
+**已清理**:
+- ✅ `src/hud/progress-indicator.ts:50` - P1 标记已移除
+
+**保留**:
+- ⏸️ `src/mcp/job-management.ts:865` - P2 标记保留
+
+---
+
+## 已清理债务详情
+
+### P1-001: Claude Code Task API 集成
+
+**文件**: `src/hud/progress-indicator.ts`
+**行号**: 50
+**原始问题**: HUD 进度指示器无法显示 Claude Code 原生任务状态
+
+**解决方案**:
+- 实现了任务状态读取逻辑
+- 集成 Claude Code Task API
+- 添加了单元测试覆盖
+- 更新了 HUD 显示逻辑
+
+**影响范围**:
+- ✅ 用户体验提升：HUD 现可显示完整任务进度
+- ✅ 功能完整性：占位符实现已替换为完整功能
+- ✅ 可维护性：代码不再为未完成状态
+
+**验证方式**:
+- 单元测试通过
+- 集成测试验证
+- 手动功能测试
+
+---
+
+## 保留债务说明
+
+### P2-001: MCP 工具 Schema 自定义预留
+
+**文件**: `src/mcp/job-management.ts`
+**行号**: 865
+**标记类型**: TODO
+**当前状态**: 参数已预留但未使用
+
+**保留原因**:
+
+1. **低优先级**: 当前所有 MCP 提供商使用统一 schema，功能完整
+2. **未来扩展**: 参数预留为潜在的 per-provider schema 差异化做准备
+3. **零影响**: 不影响现有功能，不阻塞任何用户场景
+4. **设计灵活性**: 保留参数便于未来快速扩展
+
+**影响评估**:
+- **功能**: 无影响，当前实现完全可用
+- **性能**: 无影响
+- **安全**: 无影响
+- **用户体验**: 无影响
+
+**何时处理**:
+- 当需要针对不同 MCP 提供商定制 schema 时
+- 或明确确认不需要此功能时移除
+
+---
+
+## 后续清理建议
+
+### 短期建议 (1-2 周)
+
+**评估 P2-001 需求**:
+1. 调研是否真正需要 per-provider schema 差异化
+2. 如不需要，移除 `_provider` 参数和 TODO 注释
+3. 如需要，设计 provider-specific schema 映射机制
+
+**预估工时**: 2-3 小时
+
+### 中期建议 (1 个月)
+
+**代码质量持续改进**:
+1. 定期扫描新增 TODO/FIXME/HACK 标记
+2. 建立技术债务审查流程
+3. 在 sprint 规划中预留 10-15% 时间用于债务清理
+
+### 长期建议 (持续)
+
+**技术债务管理体系**:
+1. 建立技术债务分级标准
+2. 定期生成技术债务报告
+3. 在架构决策中考虑长期债务影响
+4. 鼓励团队在代码审查中识别潜在债务
+
+---
+
+## 代码质量评估
+
+### 优势
+
+✅ **技术债务控制优秀**: 清理后仅 1 个待处理标记
+✅ **无安全风险**: 无 P0 级别债务
+✅ **清理效率高**: P1 标记 100% 清理率
+✅ **代码维护及时**: 无过期标记
+
+### 改进空间
+
+- P2 标记需要定期评估，避免长期堆积
+- 建议建立自动化扫描机制，定期检测新增标记
+
+---
+
+## 附录: 清理工作流
+
+### 执行流程
+
+```
+T-037: 分级扫描
+  ↓
+  发现 2 个标记 (1 P1, 1 P2)
+  ↓
+T-038: 清理执行
+  ↓
+  P1 标记: 实现功能 → 测试验证 → 标记移除
+  P2 标记: 评估 → 决策保留
+  ↓
+T-039: 报告总结
+  ↓
+  生成清理报告 ✅
+```
+
+### 验证清单
+
+- [x] 分类报告已读取
+- [x] 清理前后对比已统计
+- [x] 已清理债务已验证
+- [x] 保留债务已评估
+- [x] 后续建议已制定
+- [x] 报告已生成
+
+---
+
+**报告生成者**: ultrapower Team
+**审核状态**: ✅ 已完成
+**下次审查**: 2026-04-16 (30 天后)