@liangjie559567/ultrapower 5.6.6 → 5.6.8

package/docs/reviews/ultrapower-standards/review_critic.md

@@ -32,9 +32,11 @@ PRD 未要求规范中包含输入校验或路径白名单策略。这是一个
 
 `hooks.json` 中所有 hook 均以 `async: false` 同步执行，且 matcher 为空字符串（匹配所有工具调用）。PRD 的 Hook 执行顺序规范中没有要求定义：
 
-- hook 脚本的执行权限边界
-- hook 输入数据的消毒（sanitization）策略
-- 恶意或损坏的 hook 脚本导致整个 Claude 会话阻塞的降级方案
+* hook 脚本的执行权限边界
+
+* hook 输入数据的消毒（sanitization）策略
+
+* 恶意或损坏的 hook 脚本导致整个 Claude 会话阻塞的降级方案
 
 `bridge-normalize.ts` 中提到了"严格白名单过滤"，但 PRD 没有要求将此策略形式化为规范，也没有要求覆盖所有 hook 类型（当前仅覆盖 permission-request、setup、session-end 三类）。
 
@@ -42,9 +44,11 @@ PRD 未要求规范中包含输入校验或路径白名单策略。这是一个
 
 `.omc/state/` 下的 `agent-replay-*.jsonl` 文件包含完整的 agent 对话历史，可能含有代码、密钥片段、用户指令等敏感信息。PRD 的"状态文件读写规范"仅关注并发锁，未要求规范中包含：
 
-- 敏感字段识别和脱敏策略
-- 文件权限设置（如 chmod 600）
-- 数据保留期限和清理策略
+* 敏感字段识别和脱敏策略
+
+* 文件权限设置（如 chmod 600）
+
+* 数据保留期限和清理策略
 
 ---
 
@@ -54,9 +58,11 @@ PRD 未要求规范中包含输入校验或路径白名单策略。这是一个
 
 PRD 的 Hook 执行顺序规范（P0-1）定义了正常时序，但完全没有覆盖以下场景：
 
-- `PreToolUse` hook 超时或崩溃 → Claude 是否继续执行工具调用？
-- `PostToolUse` hook 写状态文件失败 → 状态是否回滚？下次读取会得到什么？
-- `Stop` hook 执行中 Claude 进程被强制终止 → 临时状态文件是否泄漏？
+* `PreToolUse` hook 超时或崩溃 → Claude 是否继续执行工具调用？
+
+* `PostToolUse` hook 写状态文件失败 → 状态是否回滚？下次读取会得到什么？
+
+* `Stop` hook 执行中 Claude 进程被强制终止 → 临时状态文件是否泄漏？
 
 实际的 `hooks.json` 中没有超时配置，没有重试策略，没有 fallback。PRD 要求制定的规范如果不覆盖这些场景，规范本身就是不完整的。
 
@@ -64,9 +70,11 @@ PRD 的 Hook 执行顺序规范（P0-1）定义了正常时序，但完全没有
 
 PRD 提到"状态文件并发读写冲突"是已知问题，但规范要求仅停留在"禁止并发写入"这一预防层面。没有要求定义：
 
-- 检测到损坏 JSON 时的恢复流程
-- 部分写入（写到一半进程崩溃）的检测和修复
-- 状态文件版本不兼容时的迁移路径
+* 检测到损坏 JSON 时的恢复流程
+
+* 部分写入（写到一半进程崩溃）的检测和修复
+
+* 状态文件版本不兼容时的迁移路径
 
 当前 `.omc/state/` 下存在 `last-tool-error.json`，说明错误状态已经在被持久化，但没有对应的清理和恢复规范。
 
@@ -81,17 +89,21 @@ ERROR --> SHUTDOWN : 错误处理完成
 
 问题：如果"错误处理"本身也失败了，状态机卡在 `ERROR` 状态，没有强制退出路径。这是一个死状态（dead state）。此外：
 
-- `WAITING` 状态没有超时转换，agent 可以永久等待用户输入
-- `IDLE` 状态没有最大存活时间，资源永不释放
-- 没有定义 `ZOMBIE` 状态（进程已退出但状态文件未清理）
+* `WAITING` 状态没有超时转换，agent 可以永久等待用户输入
+
+* `IDLE` 状态没有最大存活时间，资源永不释放
+
+* 没有定义 `ZOMBIE` 状态（进程已退出但状态文件未清理）
 
 ### [HIGH] 并发写入"禁止"策略的执行机制缺失
 
 P0-2 要求"禁止并发写入同一状态文件"，但 PRD 没有说明这个禁止是如何被强制执行的：
 
-- 是文件系统锁（flock）？
-- 是应用层乐观锁（版本号 CAS）？
-- 是进程间信号量？
+* 是文件系统锁（flock）？
+
+* 是应用层乐观锁（版本号 CAS）？
+
+* 是进程间信号量？
 
 在 Windows 平台（当前开发环境为 Windows 11）上，`flock` 语义与 Unix 不同，Node.js 的文件锁行为存在已知差异。PRD 完全没有提及跨平台兼容性。
 
@@ -99,10 +111,11 @@ P0-2 要求"禁止并发写入同一状态文件"，但 PRD 没有说明这个
 
 AC-02 要求新用户 5 分钟内选出正确 skill，但决策树（图 4.1）没有覆盖：
 
-- 用户输入同时匹配多个 skill 触发词时的优先级
-- 用户输入不匹配任何分支时的 fallback 路径
-- `autopilot` 和 `ultrapilot` 互斥规则在决策树中没有体现
+* 用户输入同时匹配多个 skill 触发词时的优先级
 
+* 用户输入不匹配任何分支时的 fallback 路径
+
+* `autopilot` 和 `ultrapilot` 互斥规则在决策树中没有体现
 
 ---
 
@@ -114,10 +127,13 @@ AC-02 要求新用户 5 分钟内选出正确 skill，但决策树（图 4.1）
 
 以 P0-2"状态文件读写规范"为例，PRD 只说"明确读写锁策略，禁止并发写入"，但没有回答：
 
-- 用什么锁机制？（文件锁 / 内存锁 / 数据库事务）
-- 锁的粒度是什么？（文件级 / 字段级）
-- 锁超时时间是多少？
-- 死锁检测和解除策略是什么？
+* 用什么锁机制？（文件锁 / 内存锁 / 数据库事务）
+
+* 锁的粒度是什么？（文件级 / 字段级）
+
+* 锁超时时间是多少？
+
+* 死锁检测和解除策略是什么？
 
 这意味着实现者拿到这份 PRD 后，仍然需要自行设计所有关键决策。PRD 没有减少任何歧义。
 
@@ -133,10 +149,13 @@ AC-04："三类 BUG 来源均有对应规范" — 验证方法是"逐一映射
 
 "新用户 5 分钟内选出正确 skill，准确率 ≥ 80%"需要用户测试。但 PRD 没有定义：
 
-- "新用户"的定义（完全没用过 ultrapower？还是没用过 v5.x？）
-- "正确 skill"由谁判定？（存在主观性）
-- 3 个典型场景是哪 3 个？（不同场景难度差异极大）
-- 测试在什么环境下进行？（有无文档辅助？）
+* "新用户"的定义（完全没用过 ultrapower？还是没用过 v5.x？）
+
+* "正确 skill"由谁判定？（存在主观性）
+
+* 3 个典型场景是哪 3 个？（不同场景难度差异极大）
+
+* 测试在什么环境下进行？（有无文档辅助？）
 
 这个 AC 在当前形式下无法被客观验证，也无法被重复执行。
 
@@ -162,9 +181,11 @@ PRD 没有分析这两个目标之间的张力，也没有提供解决方案。
 
 实际上，从 hooks 目录结构来看，还存在以下未被 P0 覆盖的运行时风险：
 
-- `recovery` hook：崩溃恢复逻辑的规范缺失
-- `pre-compact` / `preemptive-compaction`：上下文压缩时序的规范缺失
-- `subagent-tracker`：子 agent 追踪状态的一致性规范缺失
+* `recovery` hook：崩溃恢复逻辑的规范缺失
+
+* `pre-compact` / `preemptive-compaction`：上下文压缩时序的规范缺失
+
+* `subagent-tracker`：子 agent 追踪状态的一致性规范缺失
 
 ---
 
@@ -174,9 +195,11 @@ PRD 没有分析这两个目标之间的张力，也没有提供解决方案。
 
 P2 要求制定 Skill、Agent、Hook 三类标准模板。但当前系统规模是：
 
-- 49 个 agent
-- 35 个 hook
-- 20+ 个 skill
+* 49 个 agent
+
+* 35 个 hook
+
+* 20+ 个 skill
 
 制定模板需要先对现有实现进行全面审计，提炼共性，识别差异，处理例外情况。这不是"写几个模板文件"的工作量，而是一次系统性的架构梳理。PRD 将其列为 P2（可选），但实际上它是 P0 规范能否落地的前提条件。
 
@@ -213,13 +236,13 @@ PRD 在第 7 节明确将"自动化规范检查工具"和"规范合规性 CI 检
 
 1. **PRD 没有定义规范内容，只定义了规范的名称** — 实现者无法从这份 PRD 推导出任何具体的规范条目。必须在 PRD 中至少给出每个规范文档的核心条目草稿。
 
-2. **状态文件安全边界完全缺失** — 路径遍历风险、敏感数据明文存储、hook 命令注入面均未被识别，规范体系不能在安全问题上留白。
+1. **状态文件安全边界完全缺失** — 路径遍历风险、敏感数据明文存储、hook 命令注入面均未被识别，规范体系不能在安全问题上留白。
 
-3. **验收标准不可验证** — AC-01 和 AC-04 是存在性检查而非质量检查；AC-02 缺乏可重复执行的测量方法。必须重写所有 AC，使其具备明确的通过/失败判定条件。
+1. **验收标准不可验证** — AC-01 和 AC-04 是存在性检查而非质量检查；AC-02 缺乏可重复执行的测量方法。必须重写所有 AC，使其具备明确的通过/失败判定条件。
 
-4. **Agent 生命周期状态机存在死状态** — `ERROR` 状态没有强制退出路径，`WAITING` 状态没有超时，这是会在生产环境中触发的设计缺陷，不能进入实现。
+1. **Agent 生命周期状态机存在死状态** — `ERROR` 状态没有强制退出路径，`WAITING` 状态没有超时，这是会在生产环境中触发的设计缺陷，不能进入实现。
 
-5. **跨平台兼容性（Windows）完全未考虑** — 文件锁策略在 Windows 上的行为与 Unix 不同，这是当前开发环境的直接风险，必须在 P0 规范中明确处理。
+1. **跨平台兼容性（Windows）完全未考虑** — 文件锁策略在 Windows 上的行为与 Unix 不同，这是当前开发环境的直接风险，必须在 P0 规范中明确处理。
 
 ### 修复建议（按优先级）
 

package/docs/reviews/ultrapower-standards/review_domain.md

@@ -55,16 +55,23 @@ PRD 的三分类遗漏了：SubagentStart/Stop、PreCompact、PermissionRequest
 PRD 提到"并发保护"，实际代码中已有实现，但实现细节比 PRD 描述的更复杂，规范需要准确反映这些细节。
 
 已实现的并发保护机制（`src/lib/atomic-write.ts`）：
-- 使用 `temp file + atomic rename` 模式（`wx` 标志确保独占创建）
-- 写入前 `fsync` 确保数据落盘
-- rename 后尝试目录级 `fsync`（Windows 上可能失败，代码已处理）
-- 同步版本（`atomicWriteJsonSync`）和异步版本（`atomicWriteJson`）均已实现
+
+* 使用 `temp file + atomic rename` 模式（`wx` 标志确保独占创建）
+
+* 写入前 `fsync` 确保数据落盘
+
+* rename 后尝试目录级 `fsync`（Windows 上可能失败，代码已处理）
+
+* 同步版本（`atomicWriteJsonSync`）和异步版本（`atomicWriteJson`）均已实现
 
 **已知问题的根因**（Race Condition，2026-02-12）：
 subagent-tracker 的并发写入问题实际上已有专门的缓解机制（`src/hooks/subagent-tracker/index.ts`）：
-- `pendingWrites` Map 实现写入防抖（100ms debounce）
-- `flushInProgress` Set 防止重复并发 flush
-- `mergeTrackerStates` 函数实现确定性状态合并（Math.max 计数器 + 时间戳仲裁）
+
+* `pendingWrites` Map 实现写入防抖（100ms debounce）
+
+* `flushInProgress` Set 防止重复并发 flush
+
+* `mergeTrackerStates` 函数实现确定性状态合并（Math.max 计数器 + 时间戳仲裁）
 
 但规范中需要明确：**这套机制只保护 subagent-tracking.json，其他状态文件（team-state.json、ralph-state.json 等）使用的是 atomicWriteJsonSync，没有 debounce 层**。这是一个不一致性，规范应该统一说明各类状态文件的保护级别差异。
 
@@ -134,9 +141,11 @@ PRD 的 CLAUDE.md 描述与此基本一致，但遗漏了一个关键约束：`t
 
 PRD 描述的 Hook 系统是 ultrapower 特有的架构，不对应任何通用行业标准。这本身没有问题，但规范需要清晰定义：
 
-- Hook 的输入/输出契约（`HookInput` / `HookOutput` 接口）
-- Hook 的执行超时保证（当前代码未见明确超时限制）
-- Hook 失败时的降级行为（当前实现：大多数 hook 失败时返回 `{ continue: true }`，即静默降级）
+* Hook 的输入/输出契约（`HookInput` / `HookOutput` 接口）
+
+* Hook 的执行超时保证（当前代码未见明确超时限制）
+
+* Hook 失败时的降级行为（当前实现：大多数 hook 失败时返回 `{ continue: true }`，即静默降级）
 
 **静默降级是一个重要的领域决策**，规范应该明确这是设计选择而非疏漏，并说明其理由（hook 不应阻塞用户工作流）。
 
@@ -217,7 +226,7 @@ Windows 上 `rename` 不是真正的原子操作（目标文件被持有时会
 ### 评分明细
 
 | 维度 | 得分 | 说明 |
-|------|------|------|
+| ------ | ------ | ------ |
 | 技术规范完整性 | 5/10 | Hook 类型分类不完整，遗漏 8 个类型 |
 | Hook 时序设计准确性 | 6/10 | Stop 阶段优先级规则缺失，是核心遗漏 |
 | 状态文件并发保护方案 | 7/10 | 原子写入方案可行，但各状态文件保护级别不一致未说明 |
@@ -234,9 +243,9 @@ Windows 上 `rename` 不是真正的原子操作（目标文件被持有时会
 
 ### 建议修复的问题（可在迭代中处理）
 
-5. 说明各状态文件的并发保护级别差异（subagent-tracker 有 debounce，其他没有）
-6. 在决策树中增加"orchestrator 直接处理"分支
-7. 记录 Windows 平台的 rename 语义差异
+1. 说明各状态文件的并发保护级别差异（subagent-tracker 有 debounce，其他没有）
+2. 在决策树中增加"orchestrator 直接处理"分支
+3. 记录 Windows 平台的 rename 语义差异
 
 ### 与 Product Review 的交叉验证
 

package/docs/reviews/ultrapower-standards/review_product.md

@@ -15,18 +15,18 @@
 
 ## 1. Strategic Fit (战略匹配: High)
 
-- Alignment: ultrapower 已迭代至 v5.0.21，拥有 49 个 agents、70 个 skills、35 个 hooks，系统复杂度已到达"规范真空"临界点。从 CHANGELOG 可见，v5.0.9~v5.0.14 的主要工作都是修复文档不一致、数量对不上、缓存嵌套等"规范缺失"导致的问题。这份 PRD 的战略时机是对的——不是超前，而是已经有点滞后。
+* Alignment: ultrapower 已迭代至 v5.0.21，拥有 49 个 agents、70 个 skills、35 个 hooks，系统复杂度已到达"规范真空"临界点。从 CHANGELOG 可见，v5.0.9~v5.0.14 的主要工作都是修复文档不一致、数量对不上、缓存嵌套等"规范缺失"导致的问题。这份 PRD 的战略时机是对的——不是超前，而是已经有点滞后。
 
-- Differentiation: 规范体系本身不是差异化来源，但它是差异化能力（多 agent 编排）能被用户稳定使用的前提。没有规范，用户无法信任框架，贡献者无法安全扩展。
+* Differentiation: 规范体系本身不是差异化来源，但它是差异化能力（多 agent 编排）能被用户稳定使用的前提。没有规范，用户无法信任框架，贡献者无法安全扩展。
 
-- Roadmap Fit: 与 Q1/Q2 目标高度契合。框架已从"能用"阶段进入"可靠用"阶段，规范体系是这个跃迁的基础设施。
+* Roadmap Fit: 与 Q1/Q2 目标高度契合。框架已从"能用"阶段进入"可靠用"阶段，规范体系是这个跃迁的基础设施。
 
 ---
 
 ## 2. Prioritization Matrix (优先级矩阵)
 
 | 维度 | P0 运行时防护 | P1 用户使用规范 | P2 开发贡献规范 |
-|------|-------------|--------------|--------------|
+| ------ | ------------- | -------------- | -------------- |
 | Impact | 5 | 4 | 3 |
 | Effort | 3 | 2 | 2 |
 | Score | 1.67 | 2.00 | 1.50 |
@@ -42,7 +42,7 @@ P0（Hook执行顺序、状态文件读写、Agent生命周期）是内部运行
 ## 3. Success Metrics (成功指标评估)
 
 | 指标 | 可量化性 | 问题 |
-|------|---------|------|
+| ------ | --------- | ------ |
 | 并发场景覆盖率 100% | 中 | "并发场景"边界未定义，谁来认定"覆盖"？ |
 | 新用户选出正确 skill ≤ 5分钟 | 高 | 需要用户测试数据，当前无基线，无法验证改善 |
 | 新增 skill 检查清单覆盖 100% | 高 | 可通过 CI 门禁自动验证，这是最强的指标 |
@@ -52,23 +52,28 @@ P0（Hook执行顺序、状态文件读写、Agent生命周期）是内部运行
 
 **最弱指标**：三类 BUG 来源全覆盖——需要先定义这三类是什么，否则无法验证。
 
-- Primary KPI: 新增 skill/agent/hook 的检查清单覆盖率（目标 100%，可 CI 验证）
-- Secondary KPI: 用户首次选出正确 skill 的时间（需建立基线测量）
+* Primary KPI: 新增 skill/agent/hook 的检查清单覆盖率（目标 100%，可 CI 验证）
+
+* Secondary KPI: 用户首次选出正确 skill 的时间（需建立基线测量）
 
 ---
 
 ## 4. 战略遗漏分析
 
 ### 遗漏 1：规范的"执行机制"缺失（高优先级）
+
 PRD 定义了规范内容，但没有说明规范如何被执行。文档规范如果没有 CI 门禁或 lint 规则支撑，会退化为"参考文档"而非"约束机制"。建议明确：哪些规范通过自动化工具强制执行，哪些依赖人工审查。
 
 ### 遗漏 2：规范的版本化策略缺失（中优先级）
+
 ultrapower 迭代速度快（v5.0.9 到 v5.0.21 在短期内完成），规范文档如何随版本演进？没有版本化策略，规范会很快过时，反而增加混乱。
 
 ### 遗漏 3：现有反模式的来源分析缺失（中优先级）
+
 PRD 提到"三类 BUG 来源有对应规范"，但没有基于真实 issue/bug 数据来定义这三类。从 CHANGELOG 看，实际高频问题是：缓存嵌套、文档数量不一致、plugin 发布失败。规范应从真实痛点反推，而非自上而下设计。
 
 ### 遗漏 4：用户分层缺失（低优先级）
+
 P1 和 P2 面向不同用户群（终端用户 vs 贡献者），但 PRD 没有区分这两类用户的使用场景和需求差异，导致规范设计可能混淆受众。
 
 ---
@@ -80,8 +85,10 @@ P1 和 P2 面向不同用户群（终端用户 vs 贡献者），但 PRD 没有
 三个优先级（P0/P1/P2）同时在 MVP 中，实际上是三个独立的产品交付物。真正的 MVP 应该是：
 
 **建议 MVP（最小可验证版本）：**
-- Skill 调用决策树（P1）——直接解决用户最高频痛点
-- 新增 skill 标准模板 + 检查清单（P2 子集）——可立即通过 CI 验证，形成闭环
+
+* Skill 调用决策树（P1）——直接解决用户最高频痛点
+
+* 新增 skill 标准模板 + 检查清单（P2 子集）——可立即通过 CI 验证，形成闭环
 
 P0 的运行时规范（Hook执行顺序、状态文件读写）更适合作为内部技术文档，不需要作为用户可见的产品功能交付。
 

package/docs/reviews/ultrapower-standards/review_tech.md

@@ -9,10 +9,13 @@
 
 ## 1. Architecture Impact (架构影响)
 
-- Schema Changes: No（纯文档工程，不涉及数据模型变更）
-- API Changes: No（不修改任何运行时接口）
-- Runtime Impact: No（仅新增 docs/ 文件，修改 README.md 和 CLAUDE.md）
-- Build Pipeline Impact: No（无需修改 tsconfig.json、vitest.config.ts）
+* Schema Changes: No（纯文档工程，不涉及数据模型变更）
+
+* API Changes: No（不修改任何运行时接口）
+
+* Runtime Impact: No（仅新增 docs/ 文件，修改 README.md 和 CLAUDE.md）
+
+* Build Pipeline Impact: No（无需修改 tsconfig.json、vitest.config.ts）
 
 **关键发现**：本 PRD 的 Impact Scope 定义为"纯文档工程"，但存在一个隐性架构影响被忽略——CLAUDE.md 的修改会直接影响所有 agent 的运行时行为（CLAUDE.md 在每次会话启动时被注入为系统上下文）。这不是普通文档修改，属于**运行时配置变更**，需要单独的回归测试策略。
 
@@ -20,10 +23,13 @@
 
 ## 2. Risk Assessment (风险评估)
 
-- Complexity Score (1-10): **3**
-- POC Required: No
-- Regression Risk: Medium（CLAUDE.md 修改影响 agent 行为）
-- Consistency Risk: High（规范文档与现有代码实现存在潜在不一致）
+* Complexity Score (1-10): **3**
+
+* POC Required: No
+
+* Regression Risk: Medium（CLAUDE.md 修改影响 agent 行为）
+
+* Consistency Risk: High（规范文档与现有代码实现存在潜在不一致）
 
 ### 风险明细
 
@@ -48,7 +54,7 @@ PRD P0 提到"禁止并发写入同一状态文件"，但 `mode-registry/index.t
 ### PRD 已列出文件（合理）
 
 | 文件 | 评估 |
-|------|------|
+| ------ | ------ |
 | `docs/standards/runtime-protection.md` | 合理，对应 P0 Hook/状态规范 |
 | `docs/standards/user-guide.md` | 合理，对应 P1 决策树/路由规范 |
 | `docs/standards/contribution-guide.md` | 合理，对应 P2 贡献检查清单 |
@@ -83,26 +89,35 @@ PRD P1 包含"常见反模式清单"，但 Impact Scope 中未列出对应文件
 
 从现有代码反向提取规范，确保文档与实现一致：
 
-- 从 `src/hooks/bridge-normalize.ts` 提取 Hook 字段白名单规范
-- 从 `src/hooks/mode-registry/index.ts` 提取状态机转换规则和 stale marker 阈值
-- 从 `src/agents/definitions.ts` 提取 Agent 生命周期规范
-- 从 `src/hooks/guards/pre-tool.ts`、`post-tool.ts` 提取 Hook 执行顺序
+* 从 `src/hooks/bridge-normalize.ts` 提取 Hook 字段白名单规范
+
+* 从 `src/hooks/mode-registry/index.ts` 提取状态机转换规则和 stale marker 阈值
+
+* 从 `src/agents/definitions.ts` 提取 Agent 生命周期规范
+
+* 从 `src/hooks/guards/pre-tool.ts`、`post-tool.ts` 提取 Hook 执行顺序
 
 撰写文件：`runtime-protection.md`、`hook-execution-order.md`、`state-machine.md`、`agent-lifecycle.md`
 
 ### 阶段二：规范扩展（2-3天）
 
-- 撰写 `user-guide.md`（Skill 调用决策树 + Agent 路由规范）
-- 撰写 `anti-patterns.md`（常见反模式清单）
-- 撰写 `contribution-guide.md`（贡献检查清单）
-- 撰写 3 个模板文件（skill/agent/hook）
-- 撰写 `docs/standards/README.md`（目录索引）
+* 撰写 `user-guide.md`（Skill 调用决策树 + Agent 路由规范）
+
+* 撰写 `anti-patterns.md`（常见反模式清单）
+
+* 撰写 `contribution-guide.md`（贡献检查清单）
+
+* 撰写 3 个模板文件（skill/agent/hook）
+
+* 撰写 `docs/standards/README.md`（目录索引）
 
 ### 阶段三：集成与验证（1天）
 
-- 更新 `README.md` 指向新规范
-- 审慎修改 `CLAUDE.md`（仅追加，不删除现有规则）
-- 人工验证：用新模板创建一个 demo skill，确认模板可用
+* 更新 `README.md` 指向新规范
+
+* 审慎修改 `CLAUDE.md`（仅追加，不删除现有规则）
+
+* 人工验证：用新模板创建一个 demo skill，确认模板可用
 
 ---
 
@@ -124,9 +139,11 @@ P0 规范"禁止并发写入同一状态文件"目前仅靠约定，`mode-regist
 
 ## Conclusion (结论)
 
-- **结论**: Pass（条件通过）
-- **Estimated Effort**: 6-8 天（1 名工程师）
-- **综合评分**: 7/10
+* **结论**: Pass（条件通过）
+
+* **Estimated Effort**: 6-8 天（1 名工程师）
+
+* **综合评分**: 7/10
 
 **通过理由**：技术可行性高，纯文档工程，无运行时风险，团队具备完整技术栈。
 
@@ -137,6 +154,9 @@ P0 规范"禁止并发写入同一状态文件"目前仅靠约定，`mode-regist
 4. TD-4（并发写入原子性）建议在本次迭代中一并解决，避免规范与实现脱节
 
 **扣分项（-3分）**：
-- Impact Scope 遗漏 5 个关键文件（-1.5）
-- 未识别 CLAUDE.md 的运行时影响（-1）
-- 未规划规范与代码的同步机制（-0.5）
+
+* Impact Scope 遗漏 5 个关键文件（-1.5）
+
+* 未识别 CLAUDE.md 的运行时影响（-1）
+
+* 未规划规范与代码的同步机制（-0.5）

package/docs/reviews/ultrapower-standards/review_ux.md

@@ -14,7 +14,7 @@
 本 PRD 涉及三类核心用户，其旅程差异显著：
 
 | 用户类型 | 核心目标 | 当前 PRD 覆盖 |
-|---------|---------|-------------|
+| --------- | --------- | ------------- |
 | 新用户（首次使用） | 5 分钟内选出正确 skill | AC-02 有提及，但路径未设计 |
 | 日常使用者 | 快速决策、避免反模式 | P1 有规划，细节缺失 |
 | 贡献者 | 新增 skill/agent/hook | P2 有规划，模板未定义 |
@@ -22,20 +22,28 @@
 ### 流程问题逐项分析
 
 **Step 1 - 用户入口（发现阶段）**
-- 问题：PRD 未定义用户从哪里"进入"规范体系。是 README？是 CLAUDE.md？是 AGENTS.md？
-- 建议：明确规范体系的单一入口文档，避免用户在 49 个 agents + 70 个 skills 的海洋中迷失。
+
+* 问题：PRD 未定义用户从哪里"进入"规范体系。是 README？是 CLAUDE.md？是 AGENTS.md？
+
+* 建议：明确规范体系的单一入口文档，避免用户在 49 个 agents + 70 个 skills 的海洋中迷失。
 
 **Step 2 - 决策树（选择 skill 阶段）**
-- 问题：P1 提到"Skill 调用决策树"，但 PRD 未描述决策树的维度和深度。用户面对 70 个 skills，需要几步才能收敛到正确选择？
-- 建议：决策树不超过 3 层，每层不超过 5 个分支。第一层应基于用户意图（"我想做什么"），而非系统分类（"这是什么类型的 skill"）。
+
+* 问题：P1 提到"Skill 调用决策树"，但 PRD 未描述决策树的维度和深度。用户面对 70 个 skills，需要几步才能收敛到正确选择？
+
+* 建议：决策树不超过 3 层，每层不超过 5 个分支。第一层应基于用户意图（"我想做什么"），而非系统分类（"这是什么类型的 skill"）。
 
 **Step 3 - 执行阶段（使用 skill）**
-- 问题：PRD 未涉及执行中的用户反馈机制。用户如何知道 skill 正在运行？如何知道出错了？
-- 建议：补充"执行状态可见性"规范，定义进度提示、错误提示的标准格式。
+
+* 问题：PRD 未涉及执行中的用户反馈机制。用户如何知道 skill 正在运行？如何知道出错了？
+
+* 建议：补充"执行状态可见性"规范，定义进度提示、错误提示的标准格式。
 
 **Step 4 - 错误恢复（出错后）**
-- 问题：AC-04 提到"三类 BUG 来源均有对应规范"，但未说明用户视角的错误恢复路径。
-- 建议：合并 Step 3 & 4，设计"错误 -> 诊断 -> 恢复"的标准流程，而非仅列出 BUG 来源。
+
+* 问题：AC-04 提到"三类 BUG 来源均有对应规范"，但未说明用户视角的错误恢复路径。
+
+* 建议：合并 Step 3 & 4，设计"错误 -> 诊断 -> 恢复"的标准流程，而非仅列出 BUG 来源。
 
 ---
 
@@ -43,27 +51,35 @@
 
 ### 决策树组件
 
-- 当前状态：仅在 MVP 范围中提及"Skill 调用决策树"，无任何结构定义。
-- 改进点：需要定义决策树的呈现形式。纯文本 Markdown 表格？流程图？交互式命令行提示？
-- 建议：对于 CLI 工具，决策树应以"意图关键词 -> skill 名称"的对照表形式呈现，配合示例命令。
+* 当前状态：仅在 MVP 范围中提及"Skill 调用决策树"，无任何结构定义。
+
+* 改进点：需要定义决策树的呈现形式。纯文本 Markdown 表格？流程图？交互式命令行提示？
+
+* 建议：对于 CLI 工具，决策树应以"意图关键词 -> skill 名称"的对照表形式呈现，配合示例命令。
 
 ### 反模式清单组件
 
-- 当前状态：P1 列出"常见反模式清单"，但未定义格式。
-- 改进点：反模式清单如果只是文字列表，用户不会在出错时主动查阅。
-- 建议：每条反模式应包含：错误现象描述 + 根因 + 正确做法 + 示例对比（Bad vs Good）。
+* 当前状态：P1 列出"常见反模式清单"，但未定义格式。
+
+* 改进点：反模式清单如果只是文字列表，用户不会在出错时主动查阅。
+
+* 建议：每条反模式应包含：错误现象描述 + 根因 + 正确做法 + 示例对比（Bad vs Good）。
 
 ### 状态文件规范组件（P0）
 
-- 当前状态：P0 包含"状态文件读写规范"，但未说明用户如何感知状态。
-- 改进点：状态文件是内部机制，但用户需要知道"系统现在在做什么"。
-- 建议：规范中应包含面向用户的状态可见性标准，不仅仅是技术读写规范。
+* 当前状态：P0 包含"状态文件读写规范"，但未说明用户如何感知状态。
+
+* 改进点：状态文件是内部机制，但用户需要知道"系统现在在做什么"。
+
+* 建议：规范中应包含面向用户的状态可见性标准，不仅仅是技术读写规范。
 
 ### 贡献检查清单组件（P2）
 
-- 当前状态：P2 提到"贡献检查清单"，格式未定义。
-- 改进点：检查清单如果条目过多，贡献者会跳过。
-- 建议：检查清单分为"必须项"（5 条以内）和"建议项"，必须项用醒目标记区分。
+* 当前状态：P2 提到"贡献检查清单"，格式未定义。
+
+* 改进点：检查清单如果条目过多，贡献者会跳过。
+
+* 建议：检查清单分为"必须项"（5 条以内）和"建议项"，必须项用醒目标记区分。
 
 ---
 
@@ -74,7 +90,7 @@
 ### 评分依据
 
 | 维度 | 得分 | 理由 |
-|------|------|------|
+| ------ | ------ | ------ |
 | 效率（Efficiency） | 4/10 | AC-02"5 分钟选出正确 skill"是好目标，但 PRD 未提供实现路径。70 个 skills 无导航，5 分钟目标难以达成。 |
 | 清晰度（Clarity） | 5/10 | P0/P1/P2 分层清晰，但每层内部的用户交互点模糊。"规范"和"用户体验"之间的桥梁缺失。 |
 | 学习曲线（Learning Curve） | 5/10 | 有 Axiom 工作流路由表作为参考，但规范体系本身的入门路径未设计。新用户仍需阅读大量文档才能上手。 |
@@ -104,7 +120,10 @@ PRD 缺少对三类用户（新用户、日常用户、贡献者）的完整旅
 
 以下痛点在当前 PRD 中未被覆盖：
 
-- **并发冲突的用户感知**：AC-01 提到并发场景处理，但用户如何感知冲突、如何手动干预未定义。
-- **规范版本升级的迁移体验**：当规范体系从 v1 升级时，已有用户如何知道哪些内容变了？
-- **错误信息的可读性**：三类 BUG 来源有规范，但错误信息本身是否对用户友好未纳入范围。
-- **规范文档的可搜索性**：70 个 skills 的规范如果分散在多个文件，用户无法快速定位。需要统一的索引或搜索入口。
+* **并发冲突的用户感知**：AC-01 提到并发场景处理，但用户如何感知冲突、如何手动干预未定义。
+
+* **规范版本升级的迁移体验**：当规范体系从 v1 升级时，已有用户如何知道哪些内容变了？
+
+* **错误信息的可读性**：三类 BUG 来源有规范，但错误信息本身是否对用户友好未纳入范围。
+
+* **规范文档的可搜索性**：70 个 skills 的规范如果分散在多个文件，用户无法快速定位。需要统一的索引或搜索入口。