@liangjie559567/ultrapower 5.5.2 → 5.5.3

package/docs/reviews/draft-prd-memory-evolution-optimize/review_product.md

@@ -0,0 +1,140 @@
+# Product Director 评审报告
+
+**评审者**: axiom-product-director
+**评审时间**: 2026-03-02
+**评审对象**: PRD v0.2 - Axiom 记忆与进化系统 Token 使用效率优化
+
+---
+
+## 总体评分
+
+**8 / 10**
+
+理由：问题定义精准、数据驱动、MVP 边界克制，T4 的工程安全设计亮眼；但 v1/v2 双方案并存制造了路线图歧义，缺少业务层 KPI，"73% 降幅"仍是技术指标而非产品成功信号。
+
+---
+
+## 评审意见
+
+### 1. 产品价值主张
+
+**评价：High**
+
+**[VP-01] 问题是真实的、可量化的。**
+三个文件的当前行数（learning_queue 326 行、knowledge_base 177 行）均有实测依据，不是估算。"只增不减"的设计缺陷在 PRD 中被清晰命名。这是"症状 + 根因"双到位的表述，产品价值主张成立。
+
+**[VP-02] 目标用户定义过于单一。**
+U1/U2/U4 全部是"Axiom 系统（自动化）"，即系统自身作为主用户。只有 U3 是真实开发者。这意味着绝大多数价值由系统内循环消化，对"开发者是否感知到优化效果"缺乏描述。建议补充：开发者在 token 降低后能感受到的具体体验变化（响应延迟、会话成本、上下文窗口余量）。
+
+**[VP-03] 竞品/行业参照物的引用方式存在定性风险。**
+PRD 引用了 MemGPT（21K⭐）、claude-mem（27.2K⭐）、OpenClaw（242K⭐）等项目，但这些参照数据主要用于证明方案可行性，而非证明"我们的问题足够重要、足够紧迫"。竞品佐证应服务于优先级排序，而非仅作为技术合法性背书。
+
+**[VP-04] 产品目标句表述可进一步收敛。**
+当前目标句（"在不损失知识完整性的前提下降低每会话 token 消耗"）完整但偏实现视角。建议补充一个用户价值句："让 Axiom 系统在项目持续演进 6 个月后，仍能保持与第 1 天相同的响应质量和上下文利用效率。"
+
+---
+
+### 2. 优先级与 MVP 边界
+
+**评价：Med-High，总体合理，有两处值得复议**
+
+**[PRI-01] T1 是绝对的 P0，无异议。**
+learning_queue 全量 326 行载入、30 条全部 done 的问题是最直接的浪费，且实现成本最低（纯文件移动，无新依赖）。这是 MVP 里投入产出比最高的一项，排在第一位正确。
+
+**[PRI-02] T4（SessionEnd 自动触发）是否应进 MVP 值得复议。**
+T4 解决的是"队列积压"问题，但在 T1 实现后，队列积压的影响已大幅降低。T4 涉及 hook 机制、状态标记、无限循环防护，是四个任务中工程复杂度最高的。若 MVP 目标是"用最小成本验证 token 降幅效果"，T4 的必要性在 MVP 阶段存疑，可延至 v1.1 专门做 hook 安全性验证后再上线。建议将 T4 标记为 P1-Should Have，而非 P0-Must Have。
+
+**[PRI-03] T3 v2 进入 MVP 的边界条件缺失。**
+PRD 同时列出了 T3 v1（基础过滤）和 T3 v2（MiniSearch + 时间衰减），但没有明确 v2 进入 MVP 的触发条件。这导致执行时对"本期交付 v1 还是 v2"存在歧义。建议明确：v1 作为 MVP 必交付项，v2 作为 stretch goal，触发条件为"v1 上线后 token 降幅未达 60%"。
+
+**[PRI-04] MVP 的总体范围克制，值得肯定。**
+将 workflow_metrics.md、向量化检索、跨会话 token 预算全部推出 v2，体现了良好的范围控制意识。PRD 作者对 MVP 边界的判断整体成熟。
+
+---
+
+### 3. 成功指标
+
+**评价：Med，技术指标完整，业务指标缺位**
+
+**[KPI-01] 73% token 降幅目标可测量，但测量方案未定义。**
+PRD 给出了每个文件的行数降幅预估，但没有定义"如何在真实会话中测量 token 消耗"。Claude Code 的 token 计费来自上下文窗口而非文件行数，两者有转换系数。建议增加：在 usage_metrics.json 中记录"每次会话加载三文件的估算 token 数"，作为 before/after 的对比基准。
+
+**[KPI-02] 缺少业务层 KPI，只有技术层指标。**
+当前成功指标全部是"文件行数"和"token 降幅百分比"。这是实现指标，不是产品成功指标。建议补充至少一个业务层 KPI，例如：
+- "在项目运行第 3 个月时，ax-evolve 的平均处理速度与第 1 个月保持一致（不因文件膨胀而退化）"
+- "knowledge_base 检索精准率（召回相关条目 / 返回条目总数）在引入时间衰减后 >= 80%"
+
+**[KPI-03] reflection_log 的 41% 降幅目标设置过于保守，且缺乏解释。**
+681 行 → 400 行仅为 41%，而其他两个文件分别是 82% 和 85%。这个数字对应"20 条完整反思"的设计约束——但这是工程选择，不是业务约束。PRD 应解释为何"20 条"是合理的窗口大小（例如：20 条覆盖约 4 周的反思，足够捕捉近期模式），而不仅仅呈现结果数字。
+
+---
+
+### 4. 路线图风险
+
+**评价：Med，T3 的双方案设计是主要风险源**
+
+**[RR-01] T3 v1/v2 双方案并存是路线图的最大歧义点。**
+PRD 在同一个 T3 任务中同时描述了两个技术方案，但没有定义选择机制。这在产品路线图层面制造了"既要也要"的模糊性：如果 v1 已满足需求，v2 的投入是否合理？如果决定做 v2，v1 的生命周期是什么？建议将 v1 和 v2 拆成两个独立任务，分别定义验收标准和上线时机。
+
+**[RR-02] MiniSearch 引入时机与知识库格式迁移的顺序依赖未充分说明。**
+T3 v2 需要知识库条目升级为 YAML front-matter 格式，这是一次不可逆的数据迁移。风险矩阵中提到"迁移脚本随 T3 v2 发布"，但没有说明：若迁移失败或部分成功，v1 基础方案是否能正确处理混合格式文件。这是一个隐性的路线图阻断风险。
+
+**[RR-03] T4 的"跳过条件"检测机制有状态一致性风险。**
+T4 通过读取 active_context.md 中的 `auto_evolve_done: true` 标记来判断是否跳过。但 active_context.md 是会话级文件，其写入时机和读取时机之间存在竞态窗口（例如：manual ax-evolve 执行后崩溃，标记未写入，导致 SessionEnd hook 重复触发）。PRD 风险矩阵未涵盖此场景。
+
+**[RR-04] v2 延期项中"归档文件自动清理策略"缺失是增长定时炸弹。**
+T1/T2 将大量历史数据移入归档文件，但归档文件本身的增长策略被推出了 v2。若系统持续运行 6 个月，归档文件将同样无限膨胀，重蹈主文件的覆辙。建议至少在 MVP 中定义归档文件的容量上限策略（例如：归档文件 > 5000 行时警告，不自动清理，人工介入）。
+
+---
+
+### 5. 暂不包含合理性
+
+**评价：Med-High，整体合理，有一处需要复议**
+
+**[OOS-01] 排除 workflow_metrics.md 优化——合理。**
+用户已明确排除，且该文件非核心上下文消耗来源。合理。
+
+**[OOS-02] 排除向量化检索——合理且正确。**
+当前知识库 62 条，不足以支撑向量化检索的成本收益比。MiniSearch 是当前规模的正确选择。
+
+**[OOS-03] 排除归档文件清理策略——存在隐患（见 RR-04）。**
+这条"暂不包含"与 RR-04 对应。建议将其从"排除"调整为"MVP 中做简单的容量监控，不做自动清理"——即使是只读的 warning log 也比完全不管更好。
+
+**[OOS-04] 遗漏一个高价值项：knowledge_base.md 的语义去重检测（轻量版）。**
+当前 knowledge_base 有 62 条，但随着 ax-evolve 持续运行，重复或近似条目的写入是可预见的质量问题。语义去重是高成本操作，但"基于精确 Title 匹配的重复写入检测"（5 行逻辑）成本极低，且能防止知识库质量退化。建议在 MVP 中将此作为 ax-evolve 写入 knowledge_base 时的守卫逻辑。
+
+**[OOS-05] 跨会话 token 预算追踪排除合理，但未说明替代方案。**
+用户可能会问"优化是否真的生效了"。在缺少 token 追踪的情况下，这个问题无法回答。建议至少提供一个轻量替代方案：在 usage_metrics.json 中记录三文件在每次会话开始时的行数快照，作为 token 消耗的代理指标。
+
+---
+
+## 差异点（Diff Points）
+
+| ID | 描述 | 严重程度 | 建议 |
+|----|------|----------|------|
+| D-01 | T3 v1/v2 双方案在同一任务中并存，无选择机制，制造路线图歧义 | HIGH | 将 v1 和 v2 拆为独立任务，分别定义触发条件和验收标准 |
+| D-02 | T4 进入 MVP 的必要性与工程复杂度不匹配，投入产出比偏低 | HIGH | 将 T4 标记为 P1-Should Have，移至 v1.1，先验证 T1-T3 的降幅效果 |
+| D-03 | 归档文件无增长策略，是长期运营的定时炸弹 | HIGH | 在 MVP 中至少定义归档文件容量监控（warning threshold），即使不自动清理 |
+| D-04 | 成功指标缺少业务层 KPI，73% 降幅是技术指标而非产品成功信号 | MEDIUM | 增加"系统运行 3 个月后处理速度不退化"等可观测业务指标 |
+| D-05 | T4 的 auto_evolve_done 标记写入存在竞态窗口，风险矩阵未覆盖 | MEDIUM | 在风险矩阵中补充此场景，并在实现层增加幂等写入保护 |
+| D-06 | reflection_log 41% 降幅的"20 条"窗口选择缺乏业务解释 | MEDIUM | 补充"20 条 ≈ 4 周工作记忆"的定性说明，让阈值选择有业务依据 |
+| D-07 | knowledge_base 条目格式迁移（YAML front-matter）的回滚策略不清晰 | MEDIUM | 明确迁移前备份路径和混合格式的降级处理逻辑 |
+| D-08 | 遗漏轻量级重复写入检测守卫（知识库长期质量保障） | MEDIUM | 在 ax-evolve 写入 knowledge_base 时增加精确 Title 去重检测（不需要语义） |
+| D-09 | U3 是唯一真实开发者用户故事，缺少"开发者感知层"的体验描述 | LOW | 补充开发者在优化后能感受到的具体变化（响应速度、上下文余量可见性） |
+| D-10 | token 降幅测量缺少基准定义和测量方法（行数 != token 数） | LOW | 在 usage_metrics.json 中增加"会话开始时文件估算 token"快照字段 |
+
+---
+
+## 总结
+
+这份 PRD 展现了成熟的技术产品思维：问题有实测数据支撑、方案有开源验证依据、风险有明确缓解措施、向后兼容性设计周全。这不是一份需要大改的 PRD。
+
+核心需要处理的是三个优先级问题：
+
+1. **D-01（HIGH）**：T3 v1/v2 必须在评审通过前拆开，这是路线图执行的明确性问题。
+2. **D-02（HIGH）**：T4 是否进 MVP 需要与工程负责人对齐，避免因 hook 安全性复杂度拖慢整体交付。
+3. **D-03（HIGH）**：归档文件的增长策略不能等到 v2——哪怕是一个 warning，也应在 MVP 中占位。
+
+建议处理完以上三点后，PRD 可进入 **ax-decompose** 阶段。
+
+**最终结论**: P0 - Must Have（主体功能），T4 降为 P1 - Should Have 待进一步对齐。

package/docs/reviews/draft-prd-memory-evolution-optimize/review_tech.md

@@ -0,0 +1,240 @@
+# Tech Lead 评审报告
+
+**评审者**: axiom-tech-lead
+**评审时间**: 2026-03-02
+**评审对象**: PRD v0.2 - Axiom 记忆与进化系统 Token 使用效率优化
+
+---
+
+## 总体评分
+
+**6.5 / 10**
+
+PRD 方向正确，问题定义清晰，但存在两个阻断级缺陷：(1) T1/T2 的解析方案与实际文件格式完全不匹配（格式假设错误），(2) T4 的 30 秒时间预算在实际 ax-evolve 链路下极度紧张。此外 T3 v2 的 YAML front-matter 迁移代价被严重低估。建议在进入实现前完成格式调研和 POC 验证。
+
+---
+
+## 评审意见
+
+### 1. 技术可行性
+
+#### T1: learning_queue.md done 条目自动归档
+
+**严重问题：格式假设与现实不符。**
+
+PRD 描述的归档逻辑（"解析条目 → 统计 done 数量 → 超出10条则归档"）隐含了对 `learning_queue.md` 格式的假设。实际调查如下：
+
+- **代码层（`learning-queue.ts`）** 的 `loadItems()` 方法解析**表格格式**（`| ID | sourceType | ... | status |`），基于 `|` 分隔符和 `| ID |` 表头行检测。
+- **实际文件（`.omc/axiom/evolution/learning_queue.md`）** 使用**多行块格式**：
+  ```
+  ### LQ-030: getRuntimePackageVersion() 返回 'unknown'...
+  - 优先级: P2
+  - 来源类型: session
+  - 状态: done
+  - 添加时间: 2026-02-28
+  - 内容: ...
+  - 元数据: ...
+  - 知识产出: k-062
+  ```
+
+这意味着：
+- `learning-queue.ts` 的现有解析器**无法读取**实际文件，`loadItems()` 将始终返回空数组。
+- 实际文件共有 30 条 done 条目（LQ-001 ~ LQ-030），全部 `done`，零 `pending`，**但现有 TypeScript 代码完全感知不到这些条目**。
+- T1 若基于现有解析器直接实现归档逻辑，会因感知不到任何条目而静默失败——不报错，但不做任何事。
+
+**实现路径必须做出明确选择**，二选一：
+- 路径 A：重写解析器以支持实际的多行块格式（正则解析 `### LQ-XXX:` 块）。
+- 路径 B：迁移 `learning_queue.md` 文件至表格格式，与现有解析器对齐。
+
+路径 B 的代价更低但会破坏现有文件可读性；路径 A 需要编写健壮的多行块解析器，存在边界情况（多行内容字段、缺失字段、特殊字符）。
+
+**空条目判断边界（独立风险）：** 多行块格式下，"空条目"的定义需要精确化。PRD 仅描述为"内容仅有标题行或空白行"，但实际文件中可能出现：标题行存在但所有字段为空、字段存在但内容为空字符串、字段行缺失等情况。正则方案需要为每种情况编写测试用例。
+
+#### T2: reflection_log.md 历史噪音清理 + 滚动窗口
+
+`reflection_log.md` 格式为带有人工撰写内容的多段结构（`## 反思 - 日期（会话名）`），内部含多个子节（统计、做得好的、待改进、学到了什么、Action Items）。
+
+**一次性清理风险高：** PRD 标记"空条目"（仅标题行或空白行的反思块）为清理目标。但实际文件前 80 行检查显示，现有有效条目格式统一且内容丰富，不存在明显的空条目。问题是"空条目"的边界判断需要精确到：何为"有效内容"？仅有 `## 反思 - xxx` 标题 + 空行是空条目，但如果标题下有 `### 本次会话统计` 子节但子节内容也为空呢？
+
+**滚动窗口的"条目"计数单位需要明确：** PRD 说"保留最近 20 条完整反思记录"，一条记录 = 一个 `## 反思 - ...` 块，每块实际约 30-50 行。20 条 × 40 行均值 = ~800 行，与 PRD 声称的"优化后主文件上限 ~400 行"（预期 token 降幅 41%）**数字矛盾**——当前681行，若保留20条×40行=800行，主文件反而会比当前更大。此处估算有误，需要重新核算。
+
+**归档时的块边界切割：** 基于正则将 `## 反思 - ...` 块从文件中切出并追加到归档文件，需要处理：块末尾的 `---` 分隔符是否归属该块、多个连续空行的处理、文件末尾的边界情况。
+
+#### T3: knowledge_base.md 按需读取
+
+**v1 方案（LLM 执行 grep 过滤）可行性存疑：** SKILL.md 层描述过滤逻辑、LLM 执行 grep 这种方案的可靠性依赖 LLM 对指令的忠实执行，存在不一致性。建议 v1 直接在 TypeScript 层实现关键词过滤（遍历行、字符串匹配），而非依赖 LLM grep。
+
+**v2 的 YAML front-matter 迁移代价被严重低估：** 当前 `knowledge_base.md` 是纯索引表格格式（62条，每条一行表格行）。若要支持 MiniSearch，每条需要增加 YAML front-matter。问题在于：
+- 知识库的**实际内容**不在 `knowledge_base.md` 中——该文件是索引（ID、Title、Category、Confidence、Created、Status），不含完整 `content` 字段。
+- MiniSearch 需要的 `content` 字段在哪里？如果是 `title`（列标题）+ `category` 的组合，检索价值有限；如果需要从 `learning_queue.md` 对应条目中拼接 `内容` 字段，则迁移工作量 ×5。
+- 迁移脚本需要将62条表格行转换为带 YAML front-matter 的独立条目块，这是格式的根本性重构，而非小改动。
+
+**时间衰减公式的实现前提：** `e^(-0.023 × ageInDays)` 需要 `created_at` 字段，而当前 `knowledge_base.md` 已有 `Created` 列（日期格式 `YYYY-MM-DD`），这个字段可以复用。公式本身实现无障碍（Math.exp）。
+
+#### T4: SessionEnd hook 自动触发
+
+**30 秒时间限制充裕性分析：**
+
+实际的 `session-end/index.ts` 已经执行的操作链（按顺序）：
+1. `recordSessionMetrics` — 同步文件读取
+2. `exportSessionSummary` — 同步写文件
+3. `cleanupTransientState` — 同步文件删除
+4. `cleanupModeStates` — 同步文件操作
+5. `extractPythonReplSessionIdsFromTranscript` — **异步 readline 流处理**（I/O 密集）
+6. `reflectOnSessionEnd` — 调用 `EvolutionOrchestrator.reflect()`（有 **3 秒超时**）
+7. `handleNexusSessionEnd` — nexus 数据推送
+8. `triggerStopCallbacks`
+9. `notify`
+10. Session registry cleanup
+
+在此基础上，T4 要追加：读取 `active_context.md`（I/O）+ 读取 `learning_queue.md`（I/O）+ 执行 ax-evolve 处理（3 条 LQ 条目的完整知识提取/入库流程，涉及 `KnowledgeHarvester`、`PatternDetector`、`ConfidenceEngine` 多个组件链式调用，以及写 `knowledge_base.md` + 写 `learning_queue.md`）。
+
+**关键数字：** `reflectOnSessionEnd` 已有 3 秒超时，说明进化引擎操作在复杂会话下可能需要 2-3 秒。ax-evolve 处理 3 条条目的实际耗时估算：每条需要读取 LQ 条目 → 分析内容 → 写入知识库 → 更新状态，预计 5-10 秒（依赖 I/O 速度）。累计现有链路 + 新增 ax-evolve，总耗时可能超过 15-20 秒，留给失败重试的余量极小。
+
+PRD 的"预估 10-15 秒"需要通过实际测量验证，而不是估算。POC 必须在真实环境中计时。
+
+---
+
+### 2. 架构完整性
+
+#### 归档操作的原子性
+
+PRD 描述的原子性方案："先备份临时文件，操作完成后删临时文件"。实际上这是**伪原子性**：
+
+```
+步骤1: 读取主文件
+步骤2: 将超出条目写入归档文件（追加）
+步骤3: 重写主文件（去掉已归档条目）
+步骤4: 删除临时备份
+```
+
+崩溃窗口分析：
+- 步骤2完成、步骤3崩溃：条目同时存在于归档和主文件（重复，可检测可修复）
+- 步骤3进行中崩溃：主文件损坏（最危险）
+- PRD 要求的"幂等操作"在重复归档场景下需要通过条目 ID 去重，但 PRD 未描述归档文件的去重机制
+
+正确的原子性方案是：主文件使用 write-to-tmp-then-rename 模式（`fs.rename` 在同文件系统下是原子的）。PRD 中的临时文件方案描述不够精确，实现时容易误用。
+
+#### MiniSearch 索引的冷启动问题
+
+每次 ax-knowledge 调用都需要重建 MiniSearch 索引（读取文件 → 解析 → 建索引），无持久化。对于 62 条、8KB 的数据集：
+
+- 建索引耗时：< 10ms（MiniSearch 在此规模下极快）
+- 内存占用：< 2MB
+- **冷启动开销可接受，无需持久化索引**
+
+但如果知识库增长到 500 条（3 年后的合理预估），每次冷启动建索引的开销仍然可接受（< 50ms）。持久化索引带来的复杂度（索引失效、版本兼容）远大于收益，**不建议在 v1 中持久化**。
+
+#### v1/v2 双方案共存的代码复杂度
+
+降级路径（MiniSearch 失败 → grep 过滤）需要在同一代码路径中维护两套逻辑，增加了约 40% 的代码体积，且两套逻辑的行为在边界情况下可能不一致（模糊匹配 vs 精确字符串匹配）。建议：
+- v2 发布后，v1 作为降级路径而非并行路径
+- 在单元测试中专门覆盖降级触发场景
+
+---
+
+### 3. 实现风险与成本
+
+#### 各任务难度排序（从高到低）
+
+**T3 v2（难度 8/10，预估 3-5 天）**
+- YAML front-matter 格式迁移（编写迁移脚本 + 验证 62 条数据完整性）
+- MiniSearch 集成（依赖安装 + TypeScript 类型 + 索引构建逻辑）
+- 时间衰减评分实现
+- 降级路径实现
+- 单元测试覆盖降级场景
+- CI 门禁（tsc + build + test 全部通过）
+
+**T1（难度 7/10，预估 2-3 天）**
+- 必须先解决格式不一致问题（选择路径 A 或 B）
+- 若选路径 A，多行块解析器的正确实现需要大量边界情况测试
+- 原子写入的正确实现
+- 归档去重逻辑
+
+**T4（难度 6/10，预估 1-2 天）**
+- SessionEnd hook 集成（改动已有的 `processSessionEnd`）
+- `active_context.md` 读写（手动触发标记的写入和检测）
+- 30 秒超时实测验证
+- 必须通过 CI 门禁
+
+**T2（难度 5/10，预估 1-2 天）**
+- 一次性清理（相对直接，但需要人工确认）
+- 滚动窗口逻辑（块解析 + 计数 + 归档）
+- 先修复行数估算错误（20条×40行 > 当前681行）
+
+#### CI 门禁覆盖率要求
+
+PRD 仅要求 `tsc --noEmit && npm run build && npm test` 通过，未明确新增代码的单元测试覆盖率要求。建议补充：
+- T1/T2 的解析逻辑必须有单元测试（覆盖边界情况）
+- T3 降级路径必须有单元测试（故意让 MiniSearch import 失败）
+- T4 的 `stop_hook_active` 守卫必须有单元测试
+
+---
+
+### 4. 性能影响
+
+#### 对现有流程的影响
+
+- **ax-evolve**：T1 在处理完成后追加一次文件 I/O（读归档、追加写、重写主文件），耗时 < 50ms，可接受。
+- **ax-reflect**：T2 在写入新条目后追加一次块计数和条件归档，耗时 < 20ms，可接受。
+- **ax-knowledge**：T3 v2 引入 MiniSearch 建索引（< 10ms for 62 条），相比原来的全量文件读取变化不大，可接受。
+- **SessionEnd hook**：T4 是性能风险最高的任务（见上方 T4 分析）。
+
+#### MiniSearch 对 8KB/62 条知识库的检索性能
+
+- 建索引：< 5ms（实测参考：MiniSearch 官方 benchmark 在 1000 文档下 < 20ms）
+- 单次检索：< 1ms
+- 内存：< 1MB（索引内存约为原始数据 1.5-2x，8KB × 2 = ~16KB）
+
+在当前规模下，MiniSearch 的性能开销可以忽略不计。真正的性能风险在于**格式迁移后的文件解析**（从表格行解析升级到 YAML front-matter 解析），YAML 解析比正则解析慢约 5-10x，但对 62 条数据仍在毫秒级。
+
+---
+
+## 差异点（Diff Points）
+
+| ID | 描述 | 严重程度 | 建议 |
+|----|------|----------|------|
+| D-01 | `learning_queue.md` 实际使用多行块格式（`### LQ-XXX:` + 字段行），而 `learning-queue.ts` 的现有解析器期望表格格式，双方完全不兼容。T1 实现前必须做出格式选择并验证 | HIGH | 在 T1 实现前召开格式对齐讨论，明确选择路径 A（重写解析器）或路径 B（迁移文件格式），并补充说明到 PRD 约束中 |
+| D-02 | T2 行数估算矛盾：保留 20 条完整反思（每条 ~30-50 行 = ~800 行上限）与 PRD 声称的"优化后主文件 ~400 行"不一致，当前 681 行的场景下保留 20 条实际上可能增大文件 | HIGH | 重新核算行数估算：要么降低保留条目数（如 10 条），要么重新定义 token 降幅目标 |
+| D-03 | T3 v2 的 `knowledge_base.md` 只是索引表（Title、Category、Confidence 等），不含实际 `content` 字段，MiniSearch 的 `content` 字段来源不明确 | HIGH | 明确 T3 v2 的 MiniSearch 文档结构：content 字段是索引行的 Title 还是从对应 LQ 条目中提取？如果是后者，需要说明跨文件数据关联方案 |
+| D-04 | T4 的 30 秒时间预算基于估算（"预计 10-15 秒"），缺乏实测数据。现有 `session-end` 链路已有 7+ 个异步操作，追加 ax-evolve（3条）的实际耗时未知 | HIGH | T4 实现前必须做 POC：在真实环境中计时 3 条 LQ 处理的端到端耗时，验证30秒预算是否充裕 |
+| D-05 | T1 归档的幂等性保证依赖于条目 ID 去重，但 PRD 未描述归档文件的去重检查机制。重复执行归档操作时，条目可能被重复写入归档文件 | MEDIUM | 在 T1 实现规格中明确：归档前检查归档文件中是否已存在相同 ID，若存在则跳过（或在归档文件中维护已归档 ID 的索引） |
+| D-06 | PRD 原子性方案（"先备份临时文件，操作完成后删临时文件"）描述不精确，实际应使用 write-to-tmp-then-rename 模式（`fs.rename` 在同文件系统下原子）才能防止主文件损坏 | MEDIUM | 将 T1/T2 的原子写入规格明确为：将新内容写入 `*.tmp` 文件，然后用 `fs.renameSync` 替换原文件；归档文件使用追加写（append）|
+| D-07 | `session-end/index.ts` 中 `reflectOnSessionEnd` 已有 3 秒硬超时，若 T4 的 ax-evolve 逻辑集成到同一 `processSessionEnd` 函数，则 T4 的超时控制与现有超时机制的关系未明确 | MEDIUM | 明确 T4 的超时机制：是在 ax-evolve 逻辑外单独套 30 秒 `Promise.race`，还是依赖 SessionEnd hook 的全局超时？建议前者，隔离超时控制 |
+| D-08 | T3 v1（SKILL.md 层描述过滤逻辑、LLM 执行 grep）的可靠性依赖 LLM 行为一致性，不是确定性实现 | MEDIUM | T3 v1 应在 TypeScript 层直接实现关键词过滤（字符串 includes / indexOf），而非依赖 LLM 执行 grep；SKILL.md 层只需声明参数语法 |
+| D-09 | PRD 要求 CI 门禁覆盖，但未明确新增代码的单元测试要求。T1/T2 的解析逻辑和 T4 的守卫逻辑若无专项单元测试，CI 覆盖率形同虚设 | LOW | 在验收标准中补充：T1/T2 解析逻辑单元测试（含边界情况）、T4 `stop_hook_active` 守卫单元测试，作为 CI Gate 的通过条件之一 |
+| D-10 | `active_context.md` 的读写用于 T4 的手动触发检测（`auto_evolve_done: true`），但该文件是 Markdown 格式，字段读写需要正则解析；若文件不存在或字段缺失，需要明确降级行为 | LOW | 明确 T4 的标记读写实现：推荐使用文件顶部的 YAML front-matter 块（与现有格式一致），并明确文件不存在 / 字段缺失时的默认值（视为未手动触发，继续执行自动触发）|
+
+---
+
+## 总结
+
+### 可以直接进入实现的任务
+
+- **T2**：风险最低，主要是正则解析工作。但需要先修正行数估算（D-02），并在实现前备份文件。
+
+### 需要 POC 或格式决策后才能实现的任务
+
+- **T1**：必须先解决格式不一致（D-01）。建议 POC 验证解析器后再开工。
+- **T3 v2**：必须先明确 `content` 字段来源（D-03），再实施迁移脚本。建议先实现 T3 v1（纯 TypeScript 关键词过滤），再迭代到 v2。
+- **T4**：必须先通过实测验证 30 秒预算（D-04）。
+
+### 总体建议
+
+**实现顺序**：T2（最安全，先交付） → T3 v1（低风险，立即降低 token 消耗） → T1（格式决策后） → T4（POC 验证后） → T3 v2（最后，格式迁移代价最高）
+
+**Estimated Effort（保守估算）**：
+- T1：2-3 天（含格式决策）
+- T2：1-2 天
+- T3 v1：1 天
+- T3 v2：3-5 天（含迁移脚本和单元测试）
+- T4：1-2 天（含 POC）
+
+**合计：8-13 个工作天（无并行化）**
+
+### 结论
+
+- **T2、T3 v1**：Pass，可直接实现
+- **T1**：POC Required（格式不一致阻断，需先决策）
+- **T3 v2**：POC Required（content 字段来源需明确，迁移代价需评估）
+- **T4**：POC Required（30 秒预算需实测验证）

package/docs/reviews/draft-prd-memory-evolution-optimize/review_ux.md

@@ -0,0 +1,121 @@
+# UX Director 评审报告
+
+**评审者**: axiom-ux-director
+**评审时间**: 2026-03-02
+**评审对象**: PRD v0.2 - Axiom 记忆与进化系统 Token 使用效率优化
+
+---
+
+## 总体评分
+
+**5.5 / 10**
+
+理由：技术方案扎实、指标清晰，但 PRD 几乎完全从"系统视角"书写，缺乏"开发者视角"——用户在整个归档、清理、查询流程中的感知、反馈和干预路径均未被充分设计，属于典型的"工程优先、体验后置"草稿。
+
+---
+
+## 评审意见
+
+### 1. 用户体验流程
+
+**1.1 归档是"静默发生"还是"显式告知"，PRD 未定义**
+
+T1 和 T2 的触发时机描述为"自动检查"，但没有说明用户在执行 `ax-evolve` 或 `ax-reflect` 时是否会看到任何归档发生的迹象。如果归档完全无感知，用户在找不到某条 done 条目时会产生困惑——"我的数据丢了吗？"。自动化的幕后行为需要最低限度的透明输出，例如一行 `[归档] 已将 18 条 done 条目移入 learning_queue_archive.md`。
+
+**1.2 "最近 10 条 done"的保留策略与用户实际需求存在错位**
+
+用户在 `ax-evolve` 执行完成后，最常见的后续动作是"回顾本次处理了什么"。保留"最近 10 条 done"本意良好，但 10 这个数字是系统假设，而非用户研究结论。如果一批处理了 15 条，用户只能看到其中 10 条，5 条立刻消失到归档中，这会破坏"刚完成的操作结果可见"这一基本可用性原则。建议保留规则改为"最近一批 + 最近 N 天内的 done 条目"。
+
+**1.3 T4 SessionEnd 自动触发对用户的心理模型有冲击**
+
+用户关闭会话时，心理预期是"结束了"。此时系统在后台静默地处理 3 条 pending 条目，用户毫不知情。若处理失败或时间超限，用户没有任何机会干预。建议在会话结束时输出一条轻量通知，例如 `[Axiom] 会话结束，已后台处理 2 条学习队列条目`，让用户知道系统在做什么。
+
+**1.4 三个文件的"主文件 + 归档文件"二分结构增加了心理负担**
+
+用户现在需要理解：主文件是活跃窗口，归档文件是历史仓库，两者都可能包含自己关心的内容。PRD 未定义统一的"查所有"入口——如果用户想找一条三个月前的反思记录，应该去哪里找？缺少跨主文件 + 归档的联合查询路径。
+
+---
+
+### 2. 可见性与可控性
+
+**2.1 归档触发阈值（10 条 done、20 条反思）对用户完全不透明**
+
+用户无法从任何界面得知"当前距离下一次归档还有几条"。这种隐藏状态会导致用户在某次操作后突然发现文件结构变了，产生意外感。建议在文件头部维护一行元数据注释，例如 `<!-- done: 7/10，pending: 3 -->`，让用户在打开文件时即可感知当前状态。
+
+**2.2 缺少手动触发归档的命令**
+
+PRD 只定义了自动触发路径，没有提供 `/ax-archive` 或类似的手动触发指令。对于有洁癖的开发者用户，无法主动控制"何时归档"是一种剥夺感。手动触发是自动化系统的必要逃生阀。
+
+**2.3 归档后是否可以"撤销"或"查看差异"，PRD 完全空白**
+
+归档是一种破坏性操作（从主文件中移除内容）。PRD 中没有定义任何回滚或差异查看机制。如果用户不小心在归档后修改了主文件，archive 文件可能成为唯一历史来源，一旦用户不知道去 archive 中找，数据在用户心理上等同于"丢失"。
+
+**2.4 T3 知识库的"按需读取"结果对用户不可验证**
+
+当用户用 `--filter` 或 MiniSearch 查询知识库时，返回的是过滤后的子集。用户无法感知"总共有多少条"和"本次过滤了多少条"，无法判断是否有遗漏。建议查询结果末尾附加 `显示 8/62 条，使用 --all 查看全部`。
+
+---
+
+### 3. 学习曲线
+
+**3.1 v1（grep 过滤）和 v2（MiniSearch）并存，用户需要学习两套心智模型**
+
+PRD 将两个方案作为"基础"和"进阶"并列，但没有定义用户在什么场景下应该选择哪个，也没有说明 v1 何时会被废弃。这给用户带来了不必要的决策成本：我现在应该用 `--filter` 还是用 MiniSearch 语法？建议明确两套方案的生命周期关系，或将其设计为"内部实现差异"而非"用户可见的两种模式"。
+
+**3.2 MiniSearch 查询参数（fuzzy 0.2、prefix true、时间衰减）对开发者用户暴露了过多内部参数**
+
+"30 天半衰期""score × e^(-0.023×ageInDays)"是实现细节，不是用户需要理解的概念。如果这些参数出现在用户文档或命令行帮助中，会让用户觉得"这个系统很复杂，我需要先读完原理才能用"。建议将这些参数完全内化为系统默认值，用户侧只呈现"越近的记录权重越高"这一直觉概念。
+
+**3.3 T4 的"skip 条件：本会话已手动执行 ax-evolve"对用户是隐藏逻辑**
+
+用户不知道系统在记录"本会话是否执行过 ax-evolve"。这个 skip 逻辑是合理的，但完全不透明。如果用户期望 SessionEnd 触发自动处理，但因为本会话执行过手动 ax-evolve 而被 skip，用户无法得知原因。建议在 skip 时输出一条调试级别的日志，例如 `[Axiom/SessionEnd] 跳过自动处理：本会话已执行手动 ax-evolve`。
+
+**3.4 三个独立 T 之间的联动关系对用户不可见**
+
+T1、T2、T3、T4 是四个独立功能描述，但用户的实际工作流是一体的。例如，T4 自动处理 learning_queue 条目后，可能立刻触发 T1 的归档阈值，两个操作在用户感知中是"一次会话结束动作"的结果。PRD 没有描述用户视角下的端到端流程，建议补充一个"用户旅程图"章节。
+
+---
+
+### 4. 错误恢复体验
+
+**4.1 MiniSearch 降级至 grep 的降级提示缺失**
+
+PRD 提到"MiniSearch 失败自动回退至 grep"，但没有定义用户是否会被告知发生了降级。静默降级意味着用户可能拿到了精度更低的 grep 结果，却误以为是 MiniSearch 的结果。这会导致用户对系统结果产生错误信任。建议降级时输出 `[警告] MiniSearch 不可用，已切换至 grep 模式，结果精度可能降低`。
+
+**4.2 T4 "30 秒内完成"的超时处理，PRD 未定义用户侧行为**
+
+若 SessionEnd 处理超时，处于半处理状态的 pending 条目如何处理？是回滚到 pending？还是保留为 in-progress？用户在下次会话开始时会看到什么状态？这个边缘场景直接影响用户对系统可靠性的信任，必须定义。
+
+**4.3 归档文件写入失败（如磁盘空间、权限问题）时，用户会丢失数据吗？**
+
+PRD 没有定义 T1/T2 归档操作的原子性保证。如果归档文件写入失败但主文件的删除操作已执行，用户面临的是数据丢失，而不是可恢复的错误。这是 UX 层面的最高优先级风险——用户永远不应该因为一次自动化操作而丢失数据，必须采用"先写 archive，再删主文件"的原子性策略，并在失败时提供明确的错误信息。
+
+**4.4 缺少"dry-run 模式"以供用户在首次使用前预览归档结果**
+
+对于第一次触发归档的用户，系统会直接修改文件，用户无法事先知道哪些内容会被移走。建议提供 `--dry-run` 标志，输出"本次归档将移动以下 N 条记录"，让用户在确认前有一次预览机会，降低首次使用的心理门槛。
+
+---
+
+## 差异点（Diff Points）
+
+| ID | 描述 | 严重程度 | 建议 |
+|----|------|----------|------|
+| D-01 | 归档操作完全静默，无任何用户侧输出 | HIGH | 每次归档触发时，在命令行输出一行简洁的归档摘要，例如 `[归档] learning_queue: 移动了 18 条 done 条目` |
+| D-02 | 归档操作缺乏原子性保证，存在数据丢失风险 | HIGH | 明确定义"先写 archive 文件，验证写入成功后再修改主文件"的操作顺序；归档失败时主文件保持不变并输出错误 |
+| D-03 | MiniSearch 降级时不通知用户，导致结果精度误判 | HIGH | 降级时输出警告信息，明确告知用户当前处于 grep 模式，结果精度有所降低 |
+| D-04 | T4 超时或失败后的条目状态未定义 | HIGH | 明确 30 秒超时后的条目状态（回滚至 pending）及下次会话的恢复策略 |
+| D-05 | 缺少手动触发归档的命令（逃生阀缺失） | MEDIUM | 新增 `/ax-archive [--dry-run]` 命令，支持用户主动触发并预览 |
+| D-06 | "最近 10 条 done"保留策略与"刚完成的操作结果可见"原则冲突 | MEDIUM | 调整为保留"最近一批处理的全部 done 条目 + 最近 N 天内的 done 条目"，确保刚完成的操作始终可见 |
+| D-07 | 文件头部无状态元数据，用户无法感知归档阈值接近 | MEDIUM | 在主文件头部维护元数据注释行，例如 `<!-- done: 7/10, pending: 3, last_archived: 2026-03-01 -->` |
+| D-08 | T3 查询结果未显示总量，用户无法判断是否有遗漏 | MEDIUM | 查询结果末尾附加 `显示 X/Y 条` 统计，并提示用户使用 `--all` 查看全集 |
+| D-09 | v1 grep 与 v2 MiniSearch 作为用户可见的双模式并存，增加认知负担 | MEDIUM | 将两者设计为"内部实现"而非"用户选项"，对用户只暴露一套统一的查询语法；或明确定义 v1 的弃用时间表 |
+| D-10 | MiniSearch 的内部参数（fuzzy、时间衰减公式）不应出现在用户文档中 | LOW | 将技术参数移入实现注释或内部文档，用户侧只呈现直觉化的描述，如"近期记录优先" |
+| D-11 | T4 skip 逻辑（本会话已手动执行则跳过）对用户完全不透明 | LOW | skip 时输出调试级日志，让有兴趣的用户可以追踪原因 |
+| D-12 | 缺少跨主文件 + 归档文件的联合查询入口 | LOW | 定义 `--include-archive` 参数或 `/ax-search` 命令，支持用户在需要时检索完整历史 |
+| D-13 | PRD 缺少用户视角的端到端旅程描述 | LOW | 补充"用户旅程"章节，描述一个典型会话从开始到结束时用户所见、所感、所做的完整路径 |
+
+---
+
+## 总结
+
+该 PRD 在技术指标（73% token 降幅）和工程实现路径（原子性操作、SessionEnd hook 防循环）上研究充分，工程师视角完整。但作为面向开发者的 CLI 工具，其核心体验问题在于：**自动化行为缺乏透明度**，用户在整个归档、滚动、查询流程中扮演的是"被动接受者"而非"知情的协作者"。最高优先级需要解决的是数据安全感（D-02 原子性）和操作可见性（D-01 归档反馈），其次是补全逃生阀机制（D-05 手动触发）。建议在 v0.3 版本中专门增加"用户反馈设计"章节，将每个自动化操作的通知策略明确定义为 PRD 的一等公民。

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

@@ -0,0 +1,103 @@
+# Product Strategy Review: Draft PRD 三方向高价值开发规划
+
+**评审时间**：2026-03-02
+**评审人**：Product Director (axiom-product-director)
+**PRD 版本**：2026-01-21 Draft
+
+---
+
+## 1. Strategic Fit（战略匹配）
+
+### 方向一：Axiom 进化引擎完整化
+- Alignment: **High** — 直接强化 ultrapower 的核心差异化能力（自学习 AI 编排层）。Pattern Promotion Pipeline 和跨项目知识迁移是竞争对手（Cursor、Copilot）尚未提供的能力，属于护城河级功能。进化触发自动化将系统从"被动工具"升级为"主动学习伙伴"，与 Q1 目标（提升 agent 编排质量）高度一致。
+
+### 方向二：Agent 可观测性平台
+- Alignment: **Medium** — Token 成本透明化是用户高频痛点，但当前 ultrapower 已有基础 trace 工具。结构化 Trace/Span 和 SQLite 持久化属于基础设施投资，短期内对用户感知价值有限。与 Q1/Q2 路线图的契合度中等，更适合作为 Q2 的基础设施准备。
+
+### 方向三：Plugin 生态系统完善
+- Alignment: **Medium** — Plugin Marketplace 和沙箱验证对生态扩展有战略价值，但当前插件生态规模尚小，Marketplace 的网络效应尚未形成。在插件数量不足时，Marketplace 是"空货架"问题。安全验证（F3）是真实需求，但其余功能的战略时机尚未成熟。
+
+---
+
+## 2. Prioritization Matrix（优先级矩阵）
+
+| 方向 | Impact (1-5) | Effort (1-5) | ROI Score | 推荐优先级 |
+|------|-------------|-------------|-----------|-----------|
+| 方向一：Axiom 进化引擎完整化 | 5 | 2 | **2.5** | P0 |
+| 方向二：Agent 可观测性平台 | 3 | 4 | **0.75** | P2 |
+| 方向三：Plugin 生态系统完善 | 3 | 4 | **0.75** | P1 |
+
+> ROI Score = Impact / Effort，越高越优先。
+
+**方向一**：Impact 5 — 直接提升核心产品能力，用户每次会话都能感知；Effort 2 — 纯新增逻辑，不触碰现有核心路径，风险极低。
+
+**方向二**：Impact 3 — 解决真实痛点但属于"锦上添花"；Effort 4 — SQLite 集成、hook 埋点、跨会话查询涉及多层改动，风险中等。
+
+**方向三**：Impact 3 — 生态价值依赖插件数量，当前规模下边际收益有限；Effort 4 — 依赖解析、沙箱验证、回滚机制均为复杂工程。F3（安全验证）单独拆出 Impact 可达 4，建议优先。
+
+---
+
+## 3. Success Metrics（成功指标）
+
+### 方向一
+- Primary KPI：知识库条目增长率（目标：每 10 次会话新增 ≥ 3 条 active 模式）
+- Secondary KPI：ax-evolve 自动触发率（目标：≥ 80% 的 implement 完成后自动触发）
+- 风险指标：pattern_library.md 中 active 模式占比（当前接近 0%，目标 Q1 末 ≥ 30%）
+
+### 方向二
+- Primary KPI：用户主动查询 `ax-status --cost` 的频率
+- Secondary KPI：token 超限告警触发后用户调整行为的比例
+- 注意：若无用户行为数据收集机制，此 KPI 难以度量
+
+### 方向三
+- Primary KPI：通过 Marketplace 安装的插件数量
+- Secondary KPI：checksum 验证拦截率（安全价值证明）
+- 风险：Marketplace 冷启动问题——插件数 < 10 时用户体验差
+
+---
+
+## 4. Risk Assessment（范围风险）
+
+### 方向一风险
+- **低风险**：F1/F2/F3 均为新增模块，不修改现有 hook 路径
+- 潜在蔓延：F4 Dashboard 如果追求"增长曲线可视化"可能演变为复杂 UI 工程，建议 MVP 仅输出文本摘要，不做图形化
+
+### 方向二风险
+- **中风险**：PostToolUse hook 埋点覆盖所有 agent 调用，若实现不当会影响所有 agent 性能
+- 功能蔓延警告：SQLite + P50/P95 + 跨会话查询 + 告警 = 实际上是一个完整的 APM 系统，远超"可观测性增强"的范畴
+- 建议：MVP 仅做 F2（Token 成本聚合），F1/F3/F4 推迟
+
+### 方向三风险
+- **中风险**：依赖解析（拓扑排序）+ 沙箱验证 + 版本回滚 = 实际上是一个完整的包管理器
+- 冷启动风险：Marketplace 在插件生态未成熟前是负担而非资产
+- 建议：仅做 F3（沙箱安全验证）作为 MVP，F1/F2/F4 推迟至生态成熟后
+
+---
+
+## Conclusion（结论）
+
+### 方向一：P0 - Must Have
+**评分：8/10**
+完整的进化引擎闭环是 ultrapower 的核心差异化能力，ROI 最高，风险最低，立即执行。唯一建议：F4 Dashboard 限制在文本输出 MVP，避免 UI 工程蔓延。
+
+### 方向二：P2 - Nice to Have（MVP 降级）
+**评分：5/10**
+全量实现是过度投资。建议将 F2（Token 成本聚合）单独提取为 P1 小功能，其余 F1/F3/F4 推迟。Token 透明化是真实痛点，但不需要完整 APM 平台来解决。
+
+### 方向三：P1 - Should Have（范围收窄）
+**评分：6/10**
+F3（沙箱安全验证：SHA-256 + 危险模式扫描）是真实安全需求，应优先实现。F1 Marketplace 推迟至插件数 ≥ 20 后再做。F2 依赖解析和 F4 版本回滚可作为后续迭代。
+
+---
+
+## 关键产品差异点
+
+- [D-PD-01] HIGH: 方向二全量实现存在严重功能蔓延风险 → 建议仅提取 F2（Token 成本聚合）作为独立小功能，其余推迟；完整 APM 平台不是当前阶段的正确投资
+
+- [D-PD-02] HIGH: 方向三 Marketplace 存在冷启动陷阱 → 建议将 F3（沙箱安全验证）单独提取为 P1，Marketplace（F1）推迟至生态成熟；安全是刚需，Marketplace 是时机问题
+
+- [D-PD-03] MEDIUM: 方向一 F4 Dashboard 有 UI 工程蔓延风险 → MVP 限定为 `ax-status` 文本输出增强，明确禁止图形化 UI，避免范围膨胀
+
+- [D-PD-04] MEDIUM: 三个方向的 PRD 均缺乏明确的"不做什么"边界定义 → 建议每个方向补充 Out of Scope 章节，防止实现阶段范围蔓延
+
+- [D-PD-05] LOW: 方向二 F3 跨会话性能趋势依赖 SQLite，引入新的基础设施依赖 → 评估是否可用现有 JSON 文件替代，降低技术复杂度