@liangjie559567/ultrapower 5.5.2 → 5.5.3

package/docs/reviews/user_guide/summary.md

@@ -0,0 +1,129 @@
+# 评审摘要: ultrapower 用户使用指南
+
+**评审时间**: 2026-03-05
+**评审结果**: 4/5 REVISE, 1/5 APPROVE WITH MINOR REVISIONS
+
+---
+
+## 1. 关键决策
+
+### 冲突仲裁：REVISE vs APPROVE
+
+**冲突**:
+- Tech Lead: APPROVE WITH MINOR REVISIONS
+- Product Director, UX Director, Domain Expert, Critic: REVISE
+
+**仲裁决定**: **REVISE**
+
+**理由**:
+按照优先级层级（安全 > 技术 > 战略 > 业务 > 用户体验），虽然 Tech Lead 认为技术可行，但其他 4 位专家指出了更高优先级的问题：
+
+1. **Domain Expert (P0 阻塞项)**: 4 个事实性错误必须修正
+   - Skills 数量错误（71 → 70）
+   - Agents 分类错误（领域专家 16 → 15）
+   - 安装步骤错误（命令不正确）
+   - 遗漏关键功能（MCP、Axiom 进化系统、Team 流水线）
+
+2. **Product Director (战略对齐)**: 目标用户定位过窄，成功指标缺乏量化基线
+3. **UX Director (用户体验)**: 5 分钟目标不现实，缺少前置条件检查
+4. **Critic (风险缓解)**: 文档维护机制缺失，示例验证策略不足
+
+---
+
+## 2. 范围变更
+
+### 移除
+- ❌ 交互式教程（Phase 3）改为静态教程（Tech Lead 建议，降低实现复杂度）
+- ❌ 5 分钟上手目标 → 调整为 10 分钟（UX Director 建议）
+
+### 修正
+- ✅ Skills 数量：71 → 70
+- ✅ Agents 分类：领域专家 16 → 15，新增协调 2 个
+- ✅ 安装步骤：分离两种安装方式，修正插件命令
+- ✅ 示例命令：使用自然语言触发方式
+
+### 新增
+- ✅ 前置条件检查（Claude Code >= v1.0.0, Node.js >= 18.0.0）
+- ✅ 安装验证步骤（/ultrapower:omc-doctor）
+- ✅ MCP 服务器功能说明
+- ✅ Axiom 自我进化系统说明
+- ✅ Team 流水线说明
+- ✅ 文档同步机制（CI 验证 + 文档生成脚本）
+- ✅ 版本兼容性策略
+- ✅ 故障排查指南
+- ✅ 商业目标章节
+- ✅ 用户分层（初学者/进阶/专家）
+
+---
+
+## 3. 优先级调整
+
+### 原计划
+```
+Phase 1 (P0): 快速开始
+Phase 2 (P1): 完整手册
+Phase 3 (P1): 交互式教程
+Phase 4 (P2): 补充文档
+```
+
+### 修订后
+```
+Phase 0 (P0 - 前置条件): 质量基线（4-6 周）
+├─ 安全加固
+├─ Hook 超时
+└─ 测试覆盖率 85%+
+
+Phase 1 (P0): 快速开始（1 周）
+Phase 2 (P1): 核心功能文档（2 周）
+Phase 3 (P1): 进阶功能文档（2 周）
+Phase 4 (P2): 静态教程（1 周）
+```
+
+**关键变化**: 文档发布必须等待 Phase 0 完成，避免文档与代码不一致。
+
+---
+
+## 4. 工作量估算
+
+| Phase | 原估算 | 修订后 | 变化 |
+|-------|--------|--------|------|
+| Phase 1 | 2-3h | 3-4h | +33% (新增前置条件) |
+| Phase 2 | 6-8h | 8-10h | +25% (新增 MCP/Axiom/Team) |
+| Phase 3 | 8-12h | 4-6h | -50% (改为静态教程) |
+| Phase 4 | 4-6h | 6-8h | +33% (新增故障排查) |
+| **总计** | 20-29h | **21-28h** | 持平 |
+
+**修订后时间线**: 5-6 个工作日
+
+---
+
+## 5. 专家共识问题
+
+所有 5 位专家都提到的问题：
+
+1. **文档维护机制缺失** (5/5)
+   - 需要 CI 自动化验证
+   - 需要文档生成脚本
+   - 需要版本同步机制
+
+2. **示例代码验证不足** (4/5)
+   - 需要 E2E 测试覆盖
+   - 需要多环境测试
+
+3. **安装步骤不清晰** (4/5)
+   - 需要前置条件说明
+   - 需要验证步骤
+   - 需要故障排查指南
+
+---
+
+## 6. 下一步行动
+
+1. ✅ 生成 Rough PRD（当前步骤）
+2. ⏳ 用户确认 Rough PRD
+3. ⏳ 进入任务拆解阶段（/ax-decompose）
+
+---
+
+**聚合完成时间**: 2026-03-05T13:47:00Z
+**下一步**: 展示 Rough PRD 给用户确认

package/docs/standards/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-02-27 | Updated: 2026-02-27 -->
+<!-- Generated: 2026-03-02 | Updated: 2026-03-02 -->
 
 # docs/standards/
 

package/docs/standards/README.md

@@ -1,11 +1,11 @@
 # ultrapower 全链路规范体系
 
-> **ultrapower-version**: 5.0.22
+> **ultrapower-version**: 5.5.5
 > **状态**: 正式发布
-> **最后更新**: 2026-02-26
+> **最后更新**: 2026-03-02
 > **真理之源**: `docs/standards/audit-report.md`
 
-ultrapower v5.0.22 具备 49 个 agents、70 个 skills、35 个 hooks 的完整体系。本规范体系从现有代码反向提取，覆盖运行时防护、Hook 执行顺序、状态机、Agent 生命周期、用户使用指南和贡献规范，使 ultrapower 从"能用"升级为"可靠、易用、可扩展"。
+ultrapower v5.5.5 具备 49 个 agents、70 个 skills、35 个 hooks 的完整体系。本规范体系从现有代码反向提取，覆盖运行时防护、Hook 执行顺序、状态机、Agent 生命周期、用户使用指南和贡献规范，使 ultrapower 从"能用"升级为"可靠、易用、可扩展"。
 
 ---
 

package/docs/standards/agent-lifecycle.md

@@ -1,6 +1,6 @@
 # Agent 生命周期规范
 
-> **ultrapower-version**: 5.0.21
+> **ultrapower-version**: 5.5.5
 > **优先级**: P0（必须遵守）
 > **真理之源**: `docs/standards/audit-report.md`
 > **覆盖范围**: T-06（Agent 边界情况矩阵 + SubagentStopInput.success 废弃说明 + 孤儿 Agent 检测）
@@ -436,6 +436,85 @@ function writeTrackingStateImmediate(directory: string, state: SubagentTrackingS
 
 ---
 
+## 7. 并行任务依赖管理
+
+**来源**: v5.5.18 P0 修复会话反思 (2026-03-05)
+
+### 7.1 显式依赖声明
+
+Team 模式中，任务依赖通过 `TaskUpdate` 的 `addBlockedBy` 参数显式声明：
+
+```typescript
+// 任务 2 依赖任务 1 完成
+TaskUpdate({ taskId: "2", addBlockedBy: ["1"] });
+
+// 任务 4 依赖任务 2 和 3 完成
+TaskUpdate({ taskId: "4", addBlockedBy: ["2", "3"] });
+```
+
+**规范要求**：
+- 依赖关系必须在任务创建后立即声明
+- 禁止隐式依赖（agent 内部轮询其他任务状态）
+- 依赖图必须是 DAG（无环图），循环依赖会导致死锁
+
+### 7.2 反模式：Agent 内部轮询
+
+**❌ 禁止**：
+```typescript
+// agent 内部轮询其他任务状态
+while (true) {
+  const task1 = TaskGet({ taskId: "1" });
+  if (task1.status === "completed") break;
+  await sleep(1000);
+}
+```
+
+**✅ 正确**：
+```typescript
+// 使用 addBlockedBy 声明依赖
+TaskUpdate({ taskId: "2", addBlockedBy: ["1"] });
+// 系统自动在任务 1 完成后解锁任务 2
+```
+
+### 7.3 分阶段解锁策略
+
+对于复杂依赖图，使用分阶段解锁：
+
+```
+阶段 1（并行）：任务 1, 2, 3（无依赖）
+阶段 2（并行）：任务 4, 5（依赖阶段 1）
+阶段 3（顺序）：任务 6（依赖阶段 2）
+```
+
+实现：
+```typescript
+// 阶段 1：无依赖，立即可执行
+TaskCreate({ taskId: "1", subject: "..." });
+TaskCreate({ taskId: "2", subject: "..." });
+TaskCreate({ taskId: "3", subject: "..." });
+
+// 阶段 2：依赖阶段 1
+TaskCreate({ taskId: "4", subject: "..." });
+TaskUpdate({ taskId: "4", addBlockedBy: ["1", "2"] });
+
+TaskCreate({ taskId: "5", subject: "..." });
+TaskUpdate({ taskId: "5", addBlockedBy: ["3"] });
+
+// 阶段 3：依赖阶段 2
+TaskCreate({ taskId: "6", subject: "..." });
+TaskUpdate({ taskId: "6", addBlockedBy: ["4", "5"] });
+```
+
+### 7.4 预期收益
+
+| 场景 | 时间节省 | 证据 |
+|------|---------|------|
+| P0 修复（6 任务） | 70% | v5.5.18 (20h → 2h) |
+| 文档项目（10 任务） | 99.4% | v5.5.18 用户指南 (28h → 10min) |
+| 代码审查（5 维度） | 80% | v5.5.18 综合审查 |
+
+---
+
 ## 差异点说明
 
 | 差异点 | 描述 | 当前状态 | 规范要求 |

package/docs/standards/anti-patterns.md

@@ -1,6 +1,6 @@
 # 反模式清单
 
-> **ultrapower-version**: 5.0.21
+> **ultrapower-version**: 5.5.5
 > **优先级**: P0（必须遵守）
 > **真理之源**: `docs/standards/audit-report.md`
 > **覆盖范围**: T-09（已知反模式 + 正确替代方案）

package/docs/standards/audit-report.md

@@ -1,8 +1,8 @@
 # ultrapower 全链路规范体系 — 现有实现审计报告
 
 > **状态**: 完成
-> **版本**: ultrapower v5.0.22
-> **审计日期**: 2026-02-26
+> **版本**: ultrapower v5.5.5
+> **审计日期**: 2026-03-02
 > **审计范围**: T-01a（Hook/Bridge）+ T-01b（Mode/Agent/State）
 > **产出用途**: 作为 T-02 至 T-09 所有 P0 规范文档的真理之源
 

package/docs/standards/contribution-guide.md

@@ -1,6 +1,6 @@
 # 贡献规范
 
-> **ultrapower-version**: 5.0.21
+> **ultrapower-version**: 5.5.5
 > **优先级**: P1（推荐遵守）
 > **真理之源**: `docs/standards/audit-report.md`
 > **覆盖范围**: T-10（贡献者工作流 + 质量门禁）
@@ -142,9 +142,51 @@ npm test        # 所有测试通过
 
 ---
 
-## 5. 文档更新要求
+## 5. ADR 要求
 
-### 5.1 新增执行模式
+### 5.1 何时需要 ADR
+
+以下情况必须创建 ADR：
+
+- **重大架构变更**: 影响多个模块或系统设计的决策
+- **长期技术方向**: 可能影响未来 6 个月以上的决策
+- **权衡决策**: 需要在多个方案间做出选择
+- **性能优化**: 引入新的性能优化策略
+
+**不需要 ADR 的情况**:
+- Bug 修复
+- 小型功能增强
+- 文档更新
+- 依赖升级
+
+### 5.2 ADR 编号规则
+
+- 格式: `ADR-XXX: [决策名称]`
+- 编号递增，从 001 开始
+- 位置: `docs/adr/ADR-XXX.md`
+- 模板: 参考 `docs/adr/template.md`
+
+### 5.3 ADR 审查流程
+
+1. **创建**: 在 PR 中包含新 ADR
+2. **审查**: 至少 2 名 reviewer 批准
+3. **合并**: ADR 状态改为 "接受"
+4. **发布**: 在 CHANGELOG 中记录
+
+### 5.4 ADR 内容要求
+
+每个 ADR 必须包含：
+
+- **背景**: 问题陈述、约束条件
+- **决策**: 选择的方案、实施方式
+- **后果**: 正面影响、负面影响、权衡
+- **替代方案**: 至少 2 个未采用的方案及原因
+
+---
+
+## 6. 文档更新要求
+
+### 6.1 新增执行模式
 
 新增 mode 时必须同步更新：
 
@@ -154,7 +196,26 @@ npm test        # 所有测试通过
 4. `docs/CLAUDE.md` — 更新 `state_write` 支持的模式列表
 5. `AGENTS.md` — 更新执行模式表
 
-### 5.2 新增 Skill 或 Init/Setup 命令
+### 5.2 重大架构变更
+
+重大架构变更必须附带 ADR：
+
+1. 创建 `docs/adr/ADR-XXX.md`（使用下一个编号）
+2. 在 PR 描述中引用 ADR
+3. ADR 必须在 PR 合并前完成审查
+
+**示例**:
+```markdown
+## 架构决策
+
+本 PR 实现 ADR-001 中的 WorkerStateAdapter 抽象层。
+
+- 创建 `src/workers/` 目录
+- 实现 SQLite 和 JSON 适配器
+- 详见 `docs/adr/001-worker-state-adapter.md`
+```
+
+### 5.3 新增 Skill 或 Init/Setup 命令
 
 新增 skill 或 init/setup 类命令时，必须包含可执行指令：
 
@@ -173,7 +234,7 @@ npm test        # 所有测试通过
 初始化 Axiom 记忆系统。
 ```
 
-### 5.3 新增 Agent
+### 5.4 新增 Agent
 
 新增 agent 时必须同步更新：
 
@@ -182,7 +243,7 @@ npm test        # 所有测试通过
 3. `docs/REFERENCE.md` — agent 列表
 4. `AGENTS.md` — agent 概览表
 
-### 5.3 差异点记录
+### 5.5 差异点记录
 
 发现代码与规范不一致时：
 
@@ -241,38 +302,3 @@ git branch -a | grep feat/my-feature  # 应无输出
 - 禁止在已合并的特性分支上继续开发
 - 发布完成后：`dev` → `main`（tag + push），然后 `main` → `dev`（同步）
 
----
-
-## 7. PR 提交流程
-
-```bash
-# 1. 确保基于最新 dev
-git fetch origin
-git rebase origin/dev
-
-# 2. 运行质量门禁
-tsc --noEmit && npm run build && npm test
-
-# 3. 创建 PR（目标分支必须是 dev）
-gh pr create --base dev \
-  --title "feat(scope): description" \
-  --body "## 变更说明\n\n## 测试验证\n\n## 文档更新"
-```
-
-**PR 描述模板**：
-
-```markdown
-## 变更说明
-<!-- 简述本次变更的目的和内容 -->
-
-## 测试验证
-<!-- 列出运行的测试命令和结果 -->
-- [ ] `tsc --noEmit` 通过
-- [ ] `npm run build` 通过
-- [ ] `npm test` 通过
-
-## 文档更新
-<!-- 列出同步更新的文档 -->
-- [ ] 相关规范文档已更新
-- [ ] AGENTS.md 已更新（如适用）
-```

package/docs/standards/hook-execution-order.md

@@ -1,6 +1,6 @@
 # Hook 执行顺序规范
 
-> **ultrapower-version**: 5.0.21
+> **ultrapower-version**: 5.5.5
 > **优先级**: P0（必须遵守）
 > **真理之源**: `docs/standards/audit-report.md`
 > **覆盖范围**: T-04a（HookType 枚举与路由）+ T-04b（执行顺序与优先级）

package/docs/standards/runtime-protection.md

@@ -1,6 +1,6 @@
 # 运行时防护规范
 
-> **ultrapower-version**: 5.0.21
+> **ultrapower-version**: 5.5.5
 > **优先级**: P0（必须遵守）
 > **真理之源**: `docs/standards/audit-report.md`
 > **覆盖范围**: T-03a（Hook 输入防护）+ T-03b（State/Mode 防护）
@@ -231,6 +231,47 @@ try {
 - 在 Windows 上，如果目标文件被其他进程持有，`renameSync` 会失败
 - 所有涉及文件操作的代码必须考虑 Windows 平台行为差异
 
+#### 2.3.1 Windows 命令注入防护（SEC-H02）
+
+**来源**: v5.5.18 P0 修复 (2026-03-05)
+
+**安全边界（不可协商）**: Windows 平台的命令执行必须使用 `execFile` 而非 `execSync` 字符串拼接。
+
+**反模式（已修复）**:
+```typescript
+// ❌ 不安全：字符串拼接
+const args = ['/T', '/PID', String(pid)];
+execSync(`taskkill ${args.join(' ')}`);
+```
+
+**正确实现**:
+```typescript
+// ✅ 安全：使用 execFile，参数不经过 shell
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+
+async function killProcessTreeWindows(pid: number, force: boolean): Promise<boolean> {
+  const args = force
+    ? ['/F', '/T', '/PID', String(pid)]
+    : ['/T', '/PID', String(pid)];
+
+  await execFileAsync('taskkill', args, {
+    timeout: 5000,
+    windowsHide: true
+  });
+}
+```
+
+**规范要求**:
+- 所有 Windows 命令执行必须使用 `execFile` 或 `spawn`
+- 禁止使用 `execSync` 或 `exec` 进行字符串拼接
+- 参数必须通过数组传递，不经过 shell 解释
+- 必须设置 `timeout` 防止挂起
+- 必须设置 `windowsHide: true` 避免弹窗
+
+**参考实现**: `src/platform/process-utils.ts:31-47`
+
 ### 2.4 路径安全：mode 参数白名单
 
 **安全边界（不可协商）**：`mode` 参数必须通过白名单校验，禁止直接拼接到文件路径。

package/docs/standards/state-machine.md

@@ -1,6 +1,6 @@
 # 状态机规范
 
-> **ultrapower-version**: 5.0.21
+> **ultrapower-version**: 5.5.5
 > **优先级**: P0（必须遵守）
 > **真理之源**: `docs/standards/audit-report.md`
 > **覆盖范围**: T-05（Agent 状态机 + Team Pipeline 转换矩阵）

package/docs/standards/user-guide.md

@@ -1,6 +1,6 @@
 # 用户指南：Skill 决策树与 Agent 路由
 
-> **ultrapower-version**: 5.0.21
+> **ultrapower-version**: 5.5.5
 > **优先级**: P1（推荐遵守）
 > **真理之源**: `docs/standards/audit-report.md`
 > **覆盖范围**: T-08（Skill 决策树 + Agent 路由指南）
@@ -285,6 +285,59 @@ Task(subagent_type="ultrapower:architect", model="opus", prompt="设计状态机
 
 ---
 
+## 5. Team 模式决策树
+
+**来源**: v5.5.18 P0 修复会话反思 (2026-03-05)
+
+### 5.1 何时使用 Team 模式
+
+```
+任务评估
+  │
+  ├─ 任务数量 >= 3 个？
+  │   ├─ 否 → 使用单 agent 或顺序执行
+  │   └─ 是 → 继续
+  │
+  ├─ 每个任务耗时 > 30 分钟？
+  │   ├─ 否 → 并行开销不值得，使用顺序执行
+  │   └─ 是 → 继续
+  │
+  ├─ 任务间依赖关系清晰？
+  │   ├─ 否 → 先用 planner 分析依赖
+  │   └─ 是 → 继续
+  │
+  ├─ 问题域明确（可分配专业 agent）？
+  │   ├─ 否 → 使用通用 executor
+  │   └─ 是 → ✅ 使用 Team 模式
+  │
+  └─ 任务间是否共享状态？
+      ├─ 是 → ⚠️ 需要额外协调，考虑顺序执行
+      └─ 否 → ✅ 使用 Team 模式
+```
+
+### 5.2 Team 模式适用场景
+
+**✅ 适用**:
+- P0 修复（3+ 个独立 Critical 问题）
+- 多维度代码审查（质量 + 安全 + 性能）
+- 文档项目（多个独立文档并行编写）
+- 多模块功能开发（前端 + 后端 + 测试）
+
+**❌ 不适用**:
+- 高度耦合的顺序任务（重构 → 测试 → 文档）
+- 单个任务 <30 分钟
+- 任务间共享全局状态
+
+### 5.3 预期收益
+
+| 场景 | 时间节省 | 证据 |
+|------|---------|------|
+| P0 修复（6 任务） | 70% | v5.5.18 (20h → 2h) |
+| 文档项目（10 任务） | 99.4% | v5.5.18 用户指南 (28h → 10min) |
+| 代码审查（5 维度） | 80% | v5.5.18 综合审查 |
+
+---
+
 ## 差异点说明
 
 本文档无新增差异点。所有路由规则均来自 `docs/CLAUDE.md` 和 `docs/standards/audit-report.md` 的已确认内容。