@liangjie559567/ultrapower 5.5.2 → 5.5.3

package/docs/reviews/draft-prd-three-directions/review_tech.md

@@ -0,0 +1,135 @@
+# Tech Feasibility Review: Draft PRD 三方向高价值开发规划
+
+**评审时间**: 2026-03-02
+**评审人**: axiom-tech-lead
+**基于代码库版本**: v5.5.9 (dev branch)
+
+---
+
+## 1. Architecture Impact (架构影响)
+
+| 方向 | Schema Changes | API Changes | 新依赖 |
+|------|---------------|-------------|--------|
+| 方向一：Axiom 进化引擎完整化 | No | No | No |
+| 方向二：Agent 可观测性平台 | Yes (SQLite metrics.db) | Yes (trace-query 工具) | better-sqlite3 (已有) |
+| 方向三：Plugin 生态系统完善 | Yes (plugin.json 新增 dependencies 字段) | Yes (omc plugin 子命令) | No |
+
+---
+
+## 2. 方向一：Axiom 进化引擎完整化
+
+### 技术评分：8/10
+
+**优势**：
+- 纯新增模块，不触碰现有核心逻辑（hook pipeline、state machine）
+- pattern-scanner.ts 本质是 markdown 文件解析 + 正则匹配，复杂度低
+- knowledge-transfer.ts 是 JSON 序列化/反序列化，无外部依赖
+- axiom-auto-evolve hook 可复用现有 PostToolUse hook 框架（参考 axiom-boot/）
+
+**风险点**：
+- pattern-scanner 扫描代码库时若项目较大（>1000 文件），同步 I/O 会阻塞 hook 执行
+- ax-status Dashboard 的"增长曲线"需要历史数据，但 pattern_library.md 是纯文本，无时间序列存储，需要额外设计数据结构
+- knowledge-transfer 的"合并去重"逻辑需要定义明确的冲突解决策略（同名条目以哪个为准）
+
+**估算**：~8 个原子任务，评估合理。实际工作量约 3-4 天。
+
+---
+
+## 3. 方向二：Agent 可观测性平台
+
+### 技术评分：6/10
+
+**优势**：
+- better-sqlite3 已在项目依赖中，无需引入新包
+- 现有 trace-tools.ts 已有 session replay 基础，可复用 JSONL 读取逻辑
+- span 数据结构（traceId/spanId/duration_ms）设计清晰
+
+**风险点（HIGH）**：
+- **PostToolUse hook 性能瓶颈**：trace-collector hook 在每次工具调用后触发，若写入 SQLite 是同步操作，会直接增加每次工具调用的延迟。需要异步写入或批量缓冲策略
+- **traceId 注入问题**：Claude Code 的 hook 输入不携带 agent 层级信息，无法自动构建 orchestrator→subagent 的父子 span 树。需要通过状态文件传递 parentSpanId，增加实现复杂度
+- **token 数据来源**：Claude Code hook 的 tool_response 不直接暴露 input_tokens/output_tokens，需要解析响应内容或依赖 Claude API 的 usage 字段——这在 hook 上下文中不一定可用
+
+**估算**：~10 个原子任务，但实际难度被低估。token 数据获取问题可能需要 POC 验证，建议调整为 12-14 个任务，工期 5-7 天。
+
+---
+
+## 4. 方向三：Plugin 生态系统完善
+
+### 技术评分：7/10
+
+**优势**：
+- plugin-registry.ts 已有完整的版本管理基础（installPath、version、gitCommitSha）
+- plugin-rollback.ts 的备份逻辑可直接复用 atomic-write.ts 的原子写入模式
+- plugin-dependency.ts 的拓扑排序是经典算法（Kahn's algorithm），实现稳定
+
+**风险点**：
+- **Marketplace 数据源**：marketplace.json 从哪里获取？若是远程 URL，需要处理网络超时、离线场景；若是本地文件，需要定义更新机制。PRD 未明确
+- **SHA-256 checksum 验证链**：checksum 本身存储在哪里？若存在 marketplace.json 中，则 marketplace.json 本身的完整性如何保证？存在信任链缺口
+- **危险模式扫描的误报率**：`rm -rf` 等模式扫描容易误报（如注释、文档中的示例），需要定义扫描范围（仅扫描 hook 脚本的可执行部分）
+
+**估算**：~12 个原子任务，评估合理。实际工作量约 5-6 天。
+
+---
+
+## 5. Risk Assessment (风险评估)
+
+| 方向 | Complexity Score (1-10) | POC Required | 主要风险 |
+|------|------------------------|--------------|---------|
+| 方向一 | 4 | No | pattern-scanner 大文件性能 |
+| 方向二 | 7 | **Yes** | token 数据获取、hook 性能影响 |
+| 方向三 | 5 | No | marketplace 数据源设计 |
+
+---
+
+## 6. 关键技术差异点
+
+- [D-TL-01] HIGH: 方向二的 token 数据在 hook 上下文中不可直接获取 → 建议先做 POC，验证 Claude Code hook 的 tool_response 结构是否包含 usage 字段，再决定是否推进完整实现
+
+- [D-TL-02] HIGH: trace-collector PostToolUse hook 同步写 SQLite 会增加每次工具调用延迟 → 建议使用内存缓冲 + 会话结束时批量写入（session-end hook 触发 flush）
+
+- [D-TL-03] MEDIUM: 方向一的 ax-status Dashboard 需要时间序列数据，但 pattern_library.md 无历史快照 → 建议在 evolution/ 目录下新增 `snapshots/` 存储每次 ax-evolve 后的状态快照（JSON），Dashboard 读取快照生成曲线
+
+- [D-TL-04] MEDIUM: 方向三的 marketplace.json 信任链未定义 → 建议明确数据源为 GitHub Release Asset（通过 HTTPS + 官方仓库 URL 保证来源可信），checksum 与 marketplace.json 分离存储
+
+- [D-TL-05] MEDIUM: 方向一的 pattern-scanner 若使用同步 fs.readdirSync 遍历大型代码库会阻塞 → 建议限制扫描范围为 `.omc/` 和 `src/` 目录，或使用 glob 白名单
+
+- [D-TL-06] LOW: 方向三的 plugin-dependency.ts 拓扑排序需处理循环依赖 → 建议在 Kahn's algorithm 中检测剩余节点（入度不为 0）并抛出明确错误信息
+
+---
+
+## 7. Implementation Plan (大致实现计划)
+
+### 方向一（推荐 P0 执行）
+- Backend: pattern-scanner.ts（glob 扫描 + 正则匹配）→ knowledge-transfer.ts（JSON 序列化 + 合并策略）→ axiom-auto-evolve hook（复用 PostToolUse 框架）
+- Frontend: ax-status SKILL.md 增强（读取 snapshots/ 生成文本曲线）
+
+### 方向二（建议先 POC）
+- POC: 验证 hook tool_response 中 token 数据可用性（1 天）
+- Backend: tracer.ts → cost-aggregator.ts → trace-query.ts（SQLite 查询）→ trace-collector hook（异步缓冲写入）
+
+### 方向三（P1 执行）
+- Backend: plugin-marketplace.ts（本地 JSON + 远程 fetch）→ plugin-dependency.ts（拓扑排序）→ plugin-sandbox.ts（SHA-256 + 模式扫描）→ plugin-rollback.ts（备份 + 恢复）
+
+---
+
+## 8. 测试策略
+
+| 模块 | 测试重点 | 难点 |
+|------|---------|------|
+| pattern-scanner | 模式匹配准确率、大文件性能 | mock 文件系统 |
+| knowledge-transfer | 合并去重逻辑、冲突解决 | 边界条件覆盖 |
+| tracer / cost-aggregator | SQLite 写入/读取、并发安全 | 需要 in-memory SQLite |
+| plugin-dependency | 拓扑排序正确性、循环依赖检测 | 图结构 fixture |
+| plugin-sandbox | checksum 验证、危险模式误报率 | 需要真实插件 fixture |
+
+---
+
+## Conclusion (结论)
+
+| 方向 | 结论 | Estimated Effort |
+|------|------|-----------------|
+| 方向一：Axiom 进化引擎完整化 | **Pass** | 3-4 天 |
+| 方向二：Agent 可观测性平台 | **POC Required**（token 数据可用性验证） | 1 天 POC + 5-7 天实现 |
+| 方向三：Plugin 生态系统完善 | **Pass**（需明确 marketplace 数据源） | 5-6 天 |
+
+**执行建议**：方向一立即启动；方向二先用 1 天 POC 验证 token 数据可获取性，通过后再排期；方向三与方向二并行或串行均可。

package/docs/reviews/draft-prd-three-directions/review_ux.md

@@ -0,0 +1,88 @@
+# UX Review: Draft PRD 三方向评审
+
+## 方向一 UX 评分：7/10
+
+### 流程分析
+
+**F1 Pattern Promotion Pipeline（自动模式晋升）**
+- 用户心智模型匹配度高——"模式被自动提升"符合进化引擎的核心隐喻。
+- 风险：晋升是静默发生的，用户不知道"什么被提升了、为什么"。缺乏可见的确认节点。
+- 建议：晋升时输出一行摘要 `[axiom] pattern promoted: "error-retry-pattern" (confidence: 87%)`，让用户感知系统在学习。
+
+**F2 跨项目知识迁移（ax-export/ax-import）**
+- 命令命名直觉化，符合 CLI 惯例。
+- 问题：`ax-import` 时若目标项目已有同名 pattern，冲突解决策略不明确。用户会困惑"是覆盖还是合并？"
+- 建议：冲突时显示 diff 并询问 `[merge/skip/overwrite]`，不要静默覆盖。
+
+**F3 进化触发自动化（PostToolUse hook + 阈值触发）**
+- 对高级用户透明，但对新用户完全不可见——他们不知道后台在做什么。
+- 建议：在 `ax-status` 中增加"上次自动触发时间"字段，让用户感知系统活跃度。
+
+**F4 Axiom Dashboard（ax-status 增强）**
+- 知识库增长曲线、队列健康度是有价值的信息，但 CLI 环境下"曲线"的呈现方式需要明确。
+- 建议：使用 sparkline 字符图（`▁▂▄▆█`）而非依赖外部渲染，保持 CLI 原生体验。
+
+---
+
+## 方向二 UX 评分：6/10
+
+### 流程分析
+
+**F1 结构化 Trace/Span 追踪**
+- 概念来自 OpenTelemetry，对熟悉分布式系统的用户直觉化，但对普通 CLI 用户是认知负担。
+- `traceId/spanId` 这类术语在 CLI 输出中直接暴露会造成信息噪音。
+- 建议：日常输出隐藏 ID，仅在 `--verbose` 或 `--trace` 模式下展示原始 span 数据。
+
+**F2 Token 成本聚合**
+- 这是用户最关心的功能之一，心智模型匹配度极高（"我花了多少钱"）。
+- 问题：按 agent/skill/会话 三个维度同时展示会造成信息过载。
+- 建议：默认展示会话级汇总，`--by agent` / `--by skill` 作为可选过滤参数。
+
+**F3 跨会话性能趋势（SQLite）**
+- `trace_summary --since 7d` 命令设计合理，符合 CLI 惯例。
+- 风险：SQLite 文件对用户是黑盒，出问题时（损坏/锁定）用户无法自救。
+- 建议：提供 `omc traces reset` 命令，并在 `omc-doctor` 中加入 SQLite 健康检查。
+
+**F4 告警与阈值**
+- token 预算告警的触发时机不明确——是每次调用后检查，还是会话结束时？
+- 实时告警在 CLI 流式输出中会打断用户阅读，体验差。
+- 建议：告警以非阻塞方式在输出末尾追加 `[warn] token budget 80% used`，不中断主流程。
+
+---
+
+## 方向三 UX 评分：8/10
+
+### 流程分析
+
+**F1 Plugin Marketplace（omc plugin search/info/list）**
+- 命令设计最符合用户心智模型，与 `npm`/`brew` 等工具高度一致，学习曲线极低。
+- 建议：`omc plugin search <keyword>` 结果需要包含"已安装"标记，避免用户重复安装。
+
+**F2 依赖自动解析（拓扑排序）**
+- 对用户完全透明（后台处理），体验好。
+- 风险：依赖冲突时的错误信息若只输出技术细节（"circular dependency detected"），用户不知道如何解决。
+- 建议：错误信息附带具体的冲突链路和建议操作，例如 `plugin-a requires plugin-b@^1.0, but plugin-c requires plugin-b@^2.0 → try: omc plugin install plugin-b@1.x`。
+
+**F3 沙箱安全验证（checksum + 危险模式扫描）**
+- 安全验证流程对用户体验影响最大——如果每次安装都有明显延迟，用户会感到不耐烦。
+- 建议：验证过程显示进度指示 `verifying... [checksum OK] [pattern scan OK]`，让用户知道系统在保护他们，而非卡住了。
+
+**F4 版本回滚（backup + rollback）**
+- `omc plugin rollback <name>` 命令直觉化。
+- 问题：用户不知道有哪些版本可以回滚到。
+- 建议：`omc plugin rollback <name>` 不带版本号时，列出可用备份版本供选择，而非报错。
+
+---
+
+## 关键 UX 差异点
+
+- [D-UX-01] HIGH: 方向一 F1 模式晋升静默发生，用户无感知 → 晋升时输出单行摘要通知，并在 ax-status 中记录最近晋升历史
+- [D-UX-02] HIGH: 方向二 F1 traceId/spanId 在日常输出中暴露，造成信息噪音 → 默认隐藏，仅 --verbose 模式展示
+- [D-UX-03] HIGH: 方向二 F4 实时告警打断 CLI 流式输出 → 改为非阻塞尾部追加，不中断主流程
+- [D-UX-04] MEDIUM: 方向一 F2 ax-import 冲突策略不明确 → 冲突时展示 diff 并提供 merge/skip/overwrite 选项
+- [D-UX-05] MEDIUM: 方向二 F2 三维度同时展示造成信息过载 → 默认会话级汇总，维度切换用参数控制
+- [D-UX-06] MEDIUM: 方向三 F2 依赖冲突错误信息技术化 → 附带冲突链路和可执行的解决建议
+- [D-UX-07] MEDIUM: 方向三 F4 rollback 不带版本号时报错 → 改为列出可用备份版本的交互式选择
+- [D-UX-08] LOW: 方向一 F4 CLI 环境下"增长曲线"渲染方式未定义 → 使用 sparkline 字符图保持 CLI 原生体验
+- [D-UX-09] LOW: 方向二 F3 SQLite 损坏时用户无法自救 → 在 omc-doctor 加入健康检查，提供 omc traces reset 命令
+- [D-UX-10] LOW: 方向三 F1 搜索结果缺少"已安装"标记 → 已安装插件在列表中显示 [installed] 标记

package/docs/reviews/memory-evolution-optimize/summary.md

@@ -0,0 +1,94 @@
+# 评审摘要: Axiom 记忆与进化系统 Token 使用效率优化
+
+> **聚合时间**: 2026-03-02
+> **Rough PRD 路径**: `docs/prd/memory-evolution-optimize-rough.md`
+> **聚合者**: axiom-review-aggregator
+
+---
+
+## 1. 关键决策
+
+### 冲突仲裁结果
+
+| 冲突 | 涉及专家 | 仲裁层级 | 决策结果 |
+|------|---------|---------|---------|
+| T4 字段名 `auto_evolve` vs `auto_evolve_done` | Critic vs 草稿 | 1-安全（Critic 最高优先级） | 统一为 `auto_evolve_done: true`，两处必须一致 |
+| `stop_hook_active` 守卫描述与实现不符 | Critic vs 草稿 | 1-安全（Critic 最高优先级） | 删除守卫，改为校验 `hook_event_name === 'SessionEnd'` |
+| T4 中途崩溃无数据一致性保障 | Critic vs 草稿 | 1-安全（Critic 最高优先级） | 增加 `processing` 中间状态，三步原子化处理 |
+| MiniSearch `--filter` 正则注入 | Critic vs 草稿 | 1-安全（Critic 最高优先级） | T3-v2 强制引用 k-034 模式；T3-v1 增加 256 字符上限 |
+| T1/T2 并发归档无保护 | Critic vs 草稿 | 1-安全（Critic 最高优先级） | 强制使用 `.archive.lock` 文件锁 |
+| `learning_queue.md` 格式：表格 vs 块格式 | Tech Lead vs 现有代码 | 2-技术可行性（Tech 硬性约束） | 选择路径 A：重写解析器支持多行块格式 |
+| 保留 20 条反思（~800 行）vs 目标 ~400 行 | Tech Lead vs 草稿 | 2-技术可行性（Tech 硬性约束） | 窗口降为 10 条（~380 行），修正降幅估算 |
+| T3-v2 MiniSearch content 字段来源 | Tech Lead vs 草稿 | 2-技术可行性（Tech 硬性约束） | content = `Title + " " + Category` 组合，明确标注检索价值有限 |
+| T4 进入 MVP 的必要性 | Product Director（HIGH） vs 草稿 | 3-战略对齐 | T4 降为 P1-Should Have，移至 v1.1 |
+| T3 v1/v2 双方案并存无选择机制 | Product Director（HIGH） vs 草稿 | 3-战略对齐 | T3-v1 和 T3-v2 拆为独立任务；v2 延期至知识库 > 200 条 |
+| 归档文件无增长监控 | Product Director（HIGH） vs 草稿 | 3-战略对齐（轻量版） | 归档文件 > 5000 行时输出 warning（不自动清理） |
+| T1 触发与 ax-evolve 强耦合 | Domain Expert（HIGH） vs 草稿 | 4-业务逻辑 | 新增 `--archive-queue` 手动触发入口，解除强耦合 |
+| 归档操作静默 | UX Director（HIGH） vs 草稿 | 5-用户体验（轻量采纳） | 每次归档输出一行摘要 |
+| MiniSearch 降级无通知 | UX Director（HIGH） vs 草稿 | 5-用户体验 | T3-v2 约束中增加降级通知 |
+| T4 超时后条目状态未定义 | UX Director（HIGH） vs 草稿 | 5-用户体验 | 明确：超时后 processing 回滚至 pending |
+
+### 同一问题多专家覆盖
+
+| 问题 | 覆盖专家 | 仲裁结果 |
+|------|---------|---------|
+| T4 字段名不一致 | Critic D-C01（HIGH/BLOCKER）+ Domain Expert D-01（HIGH） | Critic 优先，结论一致：统一字段名 |
+| 归档操作原子性 | Tech Lead D-06（MEDIUM）+ UX Director D-02（HIGH）+ Critic D-C07（MEDIUM） | Tech Lead 方案（write-to-tmp-then-rename）为技术实现；UX Director 和 Critic 的关注已包含在内 |
+| T3 v1/v2 分拆 | Product Director D-01（HIGH）+ Critic D-C06（MEDIUM）+ UX Director D-09（MEDIUM） | Product Director 战略层决定分拆；Critic 和 UX 的相关要求分别在各自任务约束中体现 |
+
+---
+
+## 2. 范围变更
+
+### 移除（相比草稿 v0.2）
+
+- T4 从 MVP（P0）移除，降为 P1-Should Have，延期至 v1.1（须 POC 验证 30 秒预算）
+- T3-v2（MiniSearch）从 MVP 移除，延期至 v1.1，触发条件：知识库 > 200 条
+- `stop_hook_active` 守卫描述从 T4 规格中移除
+- 反思滚动窗口从"20 条"修正为"10 条"
+
+### 新增（相比草稿 v0.2）
+
+- T1 手动触发入口：`--archive-queue` 参数（解除与 ax-evolve 强耦合）
+- 归档文件增长监控：> 5000 行时 warning
+- T1/T2 文件锁机制（`.archive.lock`）
+- T1/T2 归档时用户输出摘要
+- T4 约束：processing 中间状态（三步原子化）
+- T4 约束：`.evolve.lock` 并发互斥
+- T4 约束：超时后 processing 状态回滚至 pending
+- T3-v1 查询结果统计（显示 X/Y 条）
+- T3-v2 约束（预留）：k-034 正则转义、降级通知、YAML 宽松解析
+
+### 修正（相比草稿 v0.2）
+
+- T2 滚动窗口：20 条 → 10 条（行数估算修正）
+- T4 字段名：`auto_evolve: true` → `auto_evolve_done: true`（两处统一）
+- T3 验收标准：v1 和 v2 分别定义独立验收标准，不再混用
+- Token 降幅估算：改为"典型场景/最优场景"区间，移除单一乐观值
+- 实现顺序：T2 → T3-v1 → T1 → T4(POC) → T3-v2（延期）
+
+---
+
+## 3. 放弃项（未采纳的建议）
+
+| 来源 | 建议内容 | 放弃原因 |
+|------|---------|---------|
+| UX Director D-05 | 新增 `/ax-archive --dry-run` 命令 | 延期至 v1.1，MVP 阶段一次性清理可人工确认 |
+| UX Director D-06 | 调整保留规则为"最近一批 + 最近 N 天" | 复杂度超出 MVP，10 条固定窗口更简单可预测 |
+| UX Director D-07 | 文件头部维护元数据注释 | 延期至 v1.1，用户反馈后评估 |
+| UX Director D-12 | 跨主文件+归档的联合查询 | 延期至 v2 |
+| Product Director D-04 | 补充业务层 KPI（处理速度不退化等） | 延期补充；MVP 以技术指标为主要验收依据 |
+| Product Director D-08 | 精确 Title 去重守卫（知识库写入时） | 延期至 v1.1，非阻断需求 |
+| Domain Expert D-03 | Token 降幅改为三值区间 | 已在 Rough PRD 5.1 节以注释形式补充说明，不改变核心验收标准 |
+| Domain Expert D-07 | 引入 knowledge_type 区分 evergreen vs temporal | 延期至 v2（与时间衰减一同）；MVP 无 MiniSearch |
+| Tech Lead D-09 | 单元测试覆盖率要求补充到验收标准 | 已在实现约束中补充，但未细化到行级覆盖率数字（工程实现时决定） |
+
+---
+
+## 4. 不确定性记录
+
+| 不确定性 | 影响 | 解决时机 |
+|---------|------|---------|
+| T4 30 秒预算实测结果 | 若实测超时，T4 需要更激进的批量限制（1 条而非 3 条） | v1.1 POC 阶段 |
+| T2 空条目数量（当前是否为零） | 若确认为零，T2 的一次性清理步骤可简化为仅建立滚动窗口机制 | 实现前实测验证 |
+| T3-v2 knowledge_base 迁移工作量 | content 仅含 Title+Category 时检索价值有限，可能需要后续补充实体内容 | v1.1 实现时决策 |