@liangjie559567/ultrapower 7.5.2 → 7.6.0

package/docs/prd/bugs-pain-points-audit-dag.md

@@ -0,0 +1,297 @@
+# DAG 依赖图: ultrapower v7.5.2 Bug 审计
+
+> **状态**: ACTIVE
+> **创建日期**: 2026-03-16
+> **来源**: bugs-pain-points-audit-manifest.md
+> **总任务数**: 42 个原子任务
+
+---
+
+## 全局依赖关系图
+
+```mermaid
+graph TD
+    %% ========== Phase 1: P0 任务 ==========
+
+    %% FR-01: 路径遍历防护
+    T001[T-001: 路径遍历扫描<br/>2h] --> T002[T-002: assertValidMode 实现<br/>3h]
+    T002 --> T003[T-003: 全局替换<br/>4h]
+    T003 --> T004[T-004: ESLint 规则<br/>3h]
+
+    %% FR-02: 敏感数据保护
+    T005[T-005: 敏感数据清单<br/>2h] --> T006[T-006: 敏感数据扫描<br/>2h]
+    T006 --> T007[T-007: 加密工具实现<br/>4h]
+    T007 --> T008[T-008: 状态文件加密<br/>3h]
+    T008 --> T009[T-009: CI 密钥检测<br/>2h]
+
+    %% FR-03: 状态一致性
+    T010[T-010: 直接写入扫描<br/>2h] --> T011[T-011: 原子写入替换<br/>4h]
+    T011 --> T012[T-012: 并发压力测试<br/>3h]
+    T011 --> T013[T-013: 跨会话污染测试<br/>3h]
+
+    %% FR-04: SubagentStop 推断
+    T014[T-014: success 字段扫描<br/>1h] --> T015[T-015: 推断逻辑替换<br/>2h]
+
+    %% FR-05: 并发度上限
+    T016[T-016: 并发度检查<br/>3h] --> T017[T-017: 并发度测试<br/>2h]
+
+    %% FR-06: Windows 命令注入
+    T018[T-018: 命令执行扫描<br/>2h] --> T019[T-019: 安全命令替换<br/>3h]
+    T019 --> T020[T-020: Windows CI<br/>2h]
+
+    %% ========== Phase 2: P1 任务 ==========
+
+    %% FR-07: 死锁检测
+    T021[T-021: 死锁检测 POC<br/>4h] --> T022[T-022: 死锁检测实现<br/>4h]
+
+    %% FR-08: 测试覆盖
+    T023[T-023: 并发场景测试<br/>6h] --> T026[T-026: 覆盖率报告<br/>2h]
+    T024[T-024: 状态污染测试<br/>4h] --> T026
+    T025[T-025: 安全关键路径测试<br/>6h] --> T026
+
+    %% FR-09: 文档同步
+    T027[T-027: 文档差异修复<br/>3h] --> T028[T-028: 反模式示例<br/>6h]
+    T028 --> T029[T-029: 术语表和调试指南<br/>4h]
+    T029 --> T030[T-030: 文档同步 CI<br/>3h]
+
+    %% FR-10: 超时阈值
+    T031[T-031: 超时常量提取<br/>2h] --> T032[T-032: 两阶段超时测试<br/>3h]
+
+    %% FR-11: 级联失败
+    T033[T-033: 级联失败策略<br/>3h] --> T034[T-034: 级联失败测试<br/>4h]
+
+    %% FR-12: 结构化日志
+    T035[T-035: StructuredLogger<br/>4h] --> T036[T-036: 关键路径日志<br/>4h]
+
+    %% ========== Phase 3: P2 任务 ==========
+
+    %% FR-13: 技术债务
+    T037[T-037: 技术债务分级<br/>3h] --> T038[T-038: P0/P1 债务清理<br/>8h]
+    T038 --> T039[T-039: 清理报告<br/>2h]
+
+    %% FR-14: 开发体验
+    T040[T-040: omc repair 命令<br/>6h] --> T041[T-041: 错误信息改进<br/>4h]
+    T041 --> T042[T-042: 开发体验文档<br/>3h]
+
+    %% ========== 跨阶段依赖 ==========
+
+    %% Phase 1 → Phase 2
+    T011 -.->|状态管理基础| T023
+    T011 -.->|状态管理基础| T024
+    T003 -.->|安全修复完成| T025
+    T008 -.->|加密集成完成| T025
+
+    %% Phase 2 → Phase 3
+    T026 -.->|测试基线建立| T037
+    T030 -.->|文档规范建立| T042
+
+    %% ========== 样式定义 ==========
+
+    classDef critical fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px,color:#fff
+    classDef p0 fill:#ffa94d,stroke:#fd7e14,stroke-width:2px
+    classDef p1 fill:#4dabf7,stroke:#1971c2,stroke-width:2px
+    classDef p2 fill:#51cf66,stroke:#2f9e44,stroke-width:2px
+
+    %% 关键路径标注
+    class T001,T002,T003,T010,T011 critical
+
+    %% P0 任务
+    class T004,T005,T006,T007,T008,T009,T012,T013,T014,T015,T016,T017,T018,T019,T020 p0
+
+    %% P1 任务
+    class T021,T022,T023,T024,T025,T026,T027,T028,T029,T030,T031,T032,T033,T034,T035,T036 p1
+
+    %% P2 任务
+    class T037,T038,T039,T040,T041,T042 p2
+```
+
+---
+
+## 关键路径详解
+
+### 🔴 Critical Path 1: 路径遍历防护 (12h)
+
+```
+T-001 (2h) → T-002 (3h) → T-003 (4h) → T-004 (3h)
+```
+
+**为什么是关键路径**:
+- 阻塞所有安全测试 (T-025)
+- 阻塞 ESLint CI 集成
+- 影响 v7.5.3 发布时间
+
+**优化建议**:
+- T-001 和 T-002 可部分并行（边扫描边实现）
+- T-003 可分批修复（按风险等级）
+
+---
+
+### 🔴 Critical Path 2: 状态一致性保护 (9h)
+
+```
+T-010 (2h) → T-011 (4h) → T-012/T-013 (3h 并行)
+```
+
+**为什么是关键路径**:
+- 阻塞所有并发测试 (T-023, T-024)
+- 影响状态管理模块稳定性
+- 高风险修复（需充分测试）
+
+**优化建议**:
+- T-012 和 T-013 完全并行执行
+- T-011 完成后立即启动测试
+
+---
+
+## 并行执行策略
+
+### Phase 1 并行组 (Week 1)
+
+**Day 1** - 启动 5 个独立扫描任务:
+```mermaid
+graph LR
+    T001[T-001: 路径遍历扫描]
+    T005[T-005: 敏感数据清单]
+    T010[T-010: 直接写入扫描]
+    T014[T-014: success 字段扫描]
+    T018[T-018: 命令执行扫描]
+
+    style T001 fill:#ffa94d
+    style T005 fill:#ffa94d
+    style T010 fill:#ffa94d
+    style T014 fill:#ffa94d
+    style T018 fill:#ffa94d
+```
+
+**Day 2-3** - 3 条并行实现链:
+```mermaid
+graph TD
+    subgraph Chain_A[链 A: 路径遍历]
+        T002A[T-002] --> T003A[T-003]
+    end
+
+    subgraph Chain_B[链 B: 敏感数据]
+        T006B[T-006] --> T007B[T-007]
+    end
+
+    subgraph Chain_C[链 C: 状态一致性]
+        T011C[T-011]
+    end
+```
+
+---
+
+### Phase 2 并行组 (Week 1-2)
+
+**完全独立的 6 条并行链**:
+```mermaid
+graph TD
+    subgraph G[组 G: 死锁检测]
+        T021 --> T022
+    end
+
+    subgraph H[组 H: 测试覆盖]
+        T023 --> T026
+        T024 --> T026
+        T025 --> T026
+    end
+
+    subgraph I[组 I: 文档同步]
+        T027 --> T028 --> T029 --> T030
+    end
+
+    subgraph J[组 J: 超时阈值]
+        T031 --> T032
+    end
+
+    subgraph K[组 K: 级联失败]
+        T033 --> T034
+    end
+
+    subgraph L[组 L: 结构化日志]
+        T035 --> T036
+    end
+```
+
+---
+
+## 任务优先级矩阵
+
+| 任务 ID | 优先级 | 工时 | 依赖数 | 被依赖数 | 关键路径 |
+|---------|--------|------|--------|----------|----------|
+| T-001 | P0 | 2h | 0 | 1 | ✅ |
+| T-002 | P0 | 3h | 1 | 1 | ✅ |
+| T-003 | P0 | 4h | 1 | 2 | ✅ |
+| T-010 | P0 | 2h | 0 | 1 | ✅ |
+| T-011 | P0 | 4h | 1 | 4 | ✅ |
+| T-004 | P0 | 3h | 1 | 0 | ❌ |
+| T-005 | P0 | 2h | 0 | 1 | ❌ |
+| T-023 | P1 | 6h | 2 | 1 | ❌ |
+| T-028 | P1 | 6h | 1 | 1 | ❌ |
+
+---
+
+## 风险依赖分析
+
+### 高风险依赖
+
+**T-011 (原子写入替换)** 被 4 个任务依赖:
+- T-012 (并发压力测试)
+- T-013 (跨会话污染测试)
+- T-023 (并发场景测试)
+- T-024 (状态污染测试)
+
+**缓解措施**:
+- 优先完成 T-011
+- 增加 T-011 的测试覆盖
+- 准备回滚方案
+
+---
+
+### 跨阶段依赖
+
+**Phase 1 → Phase 2**:
+```
+T-003 (路径遍历修复) ──┐
+                        ├──> T-025 (安全关键路径测试)
+T-008 (敏感数据加密) ──┘
+
+T-011 (原子写入) ──┬──> T-023 (并发场景测试)
+                   └──> T-024 (状态污染测试)
+```
+
+**Phase 2 → Phase 3**:
+```
+T-026 (覆盖率报告) ───> T-037 (技术债务分级)
+T-030 (文档同步 CI) ───> T-042 (开发体验文档)
+```
+
+---
+
+## 执行时间线
+
+### Phase 1 时间线 (10 天)
+
+```
+Day 1  |████████| T-001, T-005, T-010, T-014, T-018 (并行扫描)
+Day 2  |████████| T-002, T-006, T-016 (工具实现)
+Day 3  |████████| T-003, T-007, T-011, T-015, T-019 (核心修复)
+Day 4  |████████| T-004, T-008, T-012, T-017 (集成测试)
+Day 5  |████████| T-009, T-013, T-020 (CI 集成)
+Day 6-8|████████| 回归测试 + Bug 修复
+Day 9  |████████| 发布准备
+Day 10 |████████| v7.5.3 发布
+```
+
+### Phase 2 时间线 (20 天)
+
+```
+Week 1-2 |████████████████| T-023, T-024, T-025, T-026 (测试覆盖)
+Week 3   |████████| T-027→T-030 (文档), T-031→T-032 (超时)
+Week 4   |████████| T-021→T-022, T-033→T-034, T-035→T-036
+```
+
+---
+
+**生成时间**: 2026-03-16
+**下一步**: 结合 Manifest 清单开始执行

package/docs/prd/bugs-pain-points-audit-draft.md

@@ -0,0 +1,154 @@
+# PRD: ultrapower v7.5.2 BUG 与痛点审计 - Draft
+
+> **状态**: DRAFT
+> **作者**: Product Design Expert (Axiom)
+> **版本**: 0.1
+> **创建日期**: 2026-03-16
+> **项目**: ultrapower v7.5.2 多 Agent 编排系统
+
+---
+
+## 1. 背景与目标
+
+### 1.1 背景
+ultrapower v7.5.2 是一个复杂的多 Agent 编排系统，包含：
+- **规模**: 1198 个 TypeScript 源文件，49 agents，71 skills，43 hooks，35 tools
+- **技术栈**: TypeScript + Node.js + Vitest + ESLint
+- **核心功能**: 多模式编排（autopilot、ralph、team、pipeline 等）
+- **已知技术债务**: 51 个 TODO/FIXME/HACK 标记
+
+### 1.2 审计目标
+- **全面性**: 覆盖代码质量、稳定性、开发体验、用户体验、架构五大维度
+- **优先级**: 识别 P0（阻塞性）、P1（严重）、P2（改进）问题
+- **可执行性**: 提供根因分析和具体修复建议
+
+### 1.3 审计范围
+- ✅ 安全漏洞（路径遍历、输入验证）
+- ✅ 状态管理缺陷（并发、一致性）
+- ✅ Agent 生命周期问题（超时、孤儿、死锁）
+- ✅ 测试覆盖率和质量
+- ✅ 文档与代码不一致
+- ✅ 开发体验痛点
+
+---
+
+## 2. 用户故事
+
+| 角色 | 目标 | 收益 |
+| --- | --- | --- |
+| 开发者 | 修复已知安全漏洞和反模式 | 提升系统安全性和稳定性 |
+| 贡献者 | 清理技术债务，改善代码质量 | 降低维护成本，提升开发效率 |
+| 用户 | 获得更稳定可靠的多 Agent 编排体验 | 减少运行时错误和意外行为 |
+| 架构师 | 识别架构层面的设计缺陷 | 为 v8.0 重构提供决策依据 |
+
+---
+
+## 3. 高层需求（MVP）
+
+### 3.1 P0 问题修复（阻塞性）
+1. **安全加固**: 修复所有路径遍历漏洞和输入验证缺陷
+2. **状态一致性**: 解决并发写入和跨会话状态污染问题
+3. **Agent 生命周期**: 修复超时、孤儿检测和死锁处理逻辑
+
+### 3.2 P1 问题修复（严重）
+1. **测试质量**: 补充边界用例测试，提升覆盖率
+2. **文档同步**: 修复文档与代码不一致的差异点
+3. **错误处理**: 改善错误信息和异常处理机制
+
+### 3.3 P2 改进（优化）
+1. **开发体验**: 优化构建速度和调试工具
+2. **代码质量**: 清理技术债务标记
+3. **性能优化**: 识别并优化性能瓶颈
+
+---
+
+## 4. 业务流程
+
+```mermaid
+graph TD
+    A[开始审计] --> B[收集问题清单]
+    B --> C{按优先级分类}
+
+    C --> D[P0: 阻塞性问题]
+    C --> E[P1: 严重问题]
+    C --> F[P2: 改进项]
+
+    D --> G[根因分析]
+    E --> G
+    F --> G
+
+    G --> H[生成修复建议]
+    H --> I[评估影响范围]
+
+    I --> J{需要架构变更?}
+    J -->|是| K[标记为 v8.0 重构项]
+    J -->|否| L[标记为 v7.5.x 修复项]
+
+    K --> M[生成审计报告]
+    L --> M
+
+    M --> N[交付修复计划]
+```
+
+---
+
+## 5. 暂不包含（v2 延期）
+
+以下内容不在本次审计范围内：
+- ❌ 新功能开发（仅修复现有问题）
+- ❌ 大规模架构重构（留待 v8.0）
+- ❌ 性能基准测试（需要独立专项）
+- ❌ 用户体验调研（需要用户反馈数据）
+
+---
+
+## 6. 下一步行动
+
+1. **专家评审**: 调用 `/ax-review` 进行 5 专家并行评审
+2. **问题分类**: 生成结构化问题清单（按优先级和类别）
+3. **修复计划**: 为每个问题生成可执行的修复任务
+4. **验收标准**: 定义每个修复项的完成标准
+
+---
+
+## 附录 A: 已知问题快照
+
+### A.1 安全反模式（来源: anti-patterns.md）
+- **AP-S01**: 未校验 mode 参数直接拼接路径（路径遍历风险）
+- **AP-S02**: 直接读取 SubagentStopInput.success（已废弃字段）
+- **AP-S03**: 在状态文件中存储敏感信息
+
+### A.2 状态管理反模式
+- **AP-ST01**: 混淆 agent stale（5分钟）和 mode stale（1小时）阈值
+- **AP-ST02**: 跨会话误清理状态文件
+- **AP-ST03**: 在 ~/.claude/ 中存储 OMC 状态（应在 worktree）
+
+### A.3 Agent 生命周期反模式
+- **AP-AL01**: 向孤儿 Agent 发送 SHUTDOWN 信号（应批量清除）
+- **AP-AL02**: 混淆超时阈值（5分钟警告 vs 10分钟自动终止）
+- **AP-AL03**: 忽略 DEADLOCK_CHECK_THRESHOLD 常量
+
+### A.4 并发反模式
+- **AP-C01**: 绕过原子写入保护（已知技术债务 TD-4）
+- **AP-C02**: 不使用防抖直接写入高频状态
+
+### A.5 技术债务统计
+- **TODO/FIXME/HACK 标记**: 51 个
+- **源文件数量**: 1198 个 TypeScript 文件
+- **测试文件**: 需要补充边界用例测试
+
+---
+
+## 附录 B: 参考文档
+
+| 文档 | 路径 | 用途 |
+| --- | --- | --- |
+| 反模式清单 | docs/standards/anti-patterns.md | 已知反模式和正确替代方案 |
+| Agent 生命周期 | docs/standards/agent-lifecycle.md | 边界情况矩阵和处理策略 |
+| 运行时保护 | docs/standards/runtime-protection.md | 安全防护规范 |
+| 状态机规范 | docs/standards/state-machine.md | 状态转换和阈值定义 |
+
+---
+
+**生成时间**: 2026-03-16T05:38:21.594Z
+**下一步**: 调用 axiom-review-aggregator 进行专家评审