@liangjie559567/ultrapower 5.5.2 → 5.5.3

package/docs/reviews/documentation-system/summary.md

@@ -0,0 +1,149 @@
+# 评审摘要: ultrapower v5.5.15 文档体系重构
+
+**评审完成时间**: 2026-03-05
+**参与专家**: Tech Lead, Product Director, UX Director, Domain Expert, Critic
+**最终文档**: `docs/prd/documentation-system-rough.md`
+
+---
+
+## 1. 关键决策
+
+### 决策 1: 示例数量（技术可行性优先）
+- **冲突**: Draft (71 完整) vs Tech (50 分级) vs Product (30 核心)
+- **仲裁**: Tech Lead 解决 → **50 个分级示例**
+  - P0 (20 个): 完整端到端 + 错误处理
+  - P1 (30 个): 标准用法
+  - P2 (21 个): API 签名
+- **理由**: 技术可行性（硬性约束）> 战略建议
+
+### 决策 2: 时间目标（用户体验优先）
+- **冲突**: Draft (15 分钟) vs UX (20 分钟)
+- **仲裁**: UX Director 解决 → **20 分钟**
+- **理由**: 避免用户因无法达成目标产生挫败感
+
+### 决策 3: 文档层级（认知负荷优先）
+- **冲突**: Draft (9 层) vs UX (6 层)
+- **仲裁**: UX Director 解决 → **6 层结构**
+- **理由**: 9 层超过认知极限（7±2 原则）
+
+### 决策 4: 里程碑规划（战略对齐优先）
+- **冲突**: Draft (4 周) vs Product (3+1 周) vs Tech (3 周)
+- **仲裁**: Product Director 解决 → **3 周 + 1 周 buffer**
+- **理由**: 快速验证 + 风险缓冲
+
+### 决策 5: Phase 4 延期（战略聚焦优先）
+- **冲突**: Draft (包含 advanced/) vs Product (延期)
+- **仲裁**: Product Director 解决 → **延期到 v5.5.16**
+- **理由**: 聚焦核心路径（新用户体验 > 高级功能）
+
+---
+
+## 2. 范围变更
+
+### 移除项
+- ❌ 71 个完整示例 → 50 个分级示例（降低 30% 工作量）
+- ❌ 9 层文档结构 → 6 层结构（合并 workflows/ 和 scenarios/）
+- ❌ 15 分钟目标 → 20 分钟目标
+- ❌ Phase 4 高级内容 → 延期到 v5.5.16
+
+### 新增项（P0 安全/质量修复）
+- ✅ 示例代码安全规范（Critic P0）
+  - 禁止泄露 API keys/路径/用户数据
+  - CI 正则扫描
+- ✅ 名称一致性校验规则（Critic P0）
+  - 处理废弃别名
+  - 跨文件引用校验
+- ✅ 示例可运行性三级标准（Critic P0）
+  - Level 1: 无依赖
+  - Level 2: 环境依赖
+  - Level 3: 外部依赖
+- ✅ 文档版本管理策略（Domain P0）
+  - Docusaurus 版本功能
+  - Front Matter 版本标注
+- ✅ 示例代码测试策略（Domain P0）
+  - 提取为 `docs/__tests__/examples.test.ts`
+  - CI 自动化测试
+- ✅ API 文档重构（Domain P0）
+  - 按模块拆分（agents/skills/tools）
+
+### 优化项（P1 建议）
+- ✅ 反馈机制（UX P1）
+  - 每个文档底部"👍/👎"按钮
+- ✅ 快速跳转目录（UX P1）
+  - features/skills.md 按类别分组
+- ✅ 检查点机制（UX P1）
+  - quickstart.md 进度可视化
+- ✅ 资源分配表（Critic P1）
+  - Technical Writer: 40h
+  - DevOps Engineer: 16h
+  - QA Reviewer: 16h
+
+---
+
+## 3. 冲突仲裁优先级应用
+
+按照 **安全 > 技术 > 战略 > 逻辑 > 体验** 层级：
+
+| 优先级 | 角色 | 解决的冲突 | 决策结果 |
+|--------|------|-----------|---------|
+| 🔴 安全 | Critic | 示例代码泄露风险 | 新增安全规范 + CI 扫描 |
+| 🔧 技术 | Tech Lead | 示例数量维护成本 | 71 → 50 分级 |
+| 👔 战略 | Product Director | Phase 4 范围 | 延期到 v5.5.16 |
+| 💰 逻辑 | Domain Expert | 文档版本管理 | 补充版本策略 |
+| ✨ 体验 | UX Director | 文档层级过深 | 9 层 → 6 层 |
+
+---
+
+## 4. 专家评分汇总
+
+| 专家角色 | 评分 | 结论 | 关键贡献 |
+|---------|------|------|---------|
+| Tech Lead | 7.4/10 | Pass with Recommendations | 技术可行性验证、工作量评估 |
+| Product Director | 8.5/10 | Approved with Recommendations | 战略对齐、ROI 分析 |
+| UX Director | 7.5/10 | Optimizable | 用户旅程优化、认知负荷分析 |
+| Domain Expert | 7.8/10 | Modification Required | 行业标准合规、维护策略 |
+| Critic | 6.95/10 | Conditional Pass | 安全审计、边缘场景分析 |
+
+**综合评分**: 7.6/10
+
+---
+
+## 5. 最终交付物
+
+### Rough PRD 路径
+`docs/prd/documentation-system-rough.md`
+
+### 关键变更
+- 文档结构：9 层 → 6 层
+- 示例数量：71 → 50（分级）
+- 时间目标：15 分钟 → 20 分钟
+- 里程碑：4 周 → 3 周 + 1 周 buffer
+- 新增：6 个 P0 安全/质量修复
+
+### 通过条件
+所有 P0 问题已整合到 Rough PRD：
+- ✅ 示例代码安全规范
+- ✅ 名称一致性校验规则
+- ✅ 示例可运行性三级标准
+- ✅ 文档版本管理策略
+- ✅ 示例代码测试策略
+- ✅ API 文档重构
+
+---
+
+## 6. 下一步行动
+
+**用户确认门禁**：
+> 专家评审已完成。这是最终的粗设 PRD：`docs/prd/documentation-system-rough.md`
+>
+> 是否进入任务拆解阶段？（调用 `axiom-system-architect`）
+
+**如果确认**：
+- 调用 `axiom-system-architect` 进行任务拆解
+- 生成 `docs/prd/documentation-system-manifest.md`
+- 创建实施计划
+
+**如果需要修改**：
+- 说明需要调整的部分
+- 重新评审相关章节
+

package/docs/reviews/draft-prd-agent-observability/review_critic.md

@@ -0,0 +1,71 @@
+# Critic Review: Draft PRD — Agent 可观测性平台
+
+## 1. Security Audit (安全审计 - **Fail**)
+
+- **[P0 - CRITICAL] 路径遍历风险**：`.omc/observability.db` 的路径拼接若依赖外部传入的 `worktree` 参数，必须经过 `assertValidMode()` 或等效的路径白名单校验。PRD 未提及任何路径消毒机制。攻击者可通过构造 `../../etc/passwd` 形式的路径读写任意文件。
+
+- **[P0 - CRITICAL] .db 文件未在 .gitignore 中排除**：当前 `.gitignore` 仅排除了 `.omc/state/`、`.omc/logs/`、`.omc/prompts/`，**未覆盖 `.omc/*.db`**。`observability.db` 极可能被意外 `git add` 提交，导致：
+  - agent 运行历史、token 消耗、工具调用序列等敏感运营数据泄露到版本库
+  - 二进制 SQLite 文件污染 git 历史，无法 diff，难以清除
+
+- **[P1] 无访问控制**：SQLite 文件权限未定义。多用户共享机器场景下，其他用户可直接读取 `.omc/observability.db`，获取完整的 agent 执行历史和 cost 数据。
+
+- **[P1] cost_records 表的数据敏感性**：token 消耗 + 时间戳 + agent 类型的组合，可反推用户的工作模式和业务内容，属于需要保护的运营元数据。PRD 未定义数据保留策略（retention policy）。
+
+---
+
+## 2. Edge Case Analysis (边缘场景分析)
+
+- **[P0] 多 worktree 并发写入**：`better-sqlite3` 是同步 API，但 SQLite 的 WAL 模式下多进程并发写入仍会产生 `SQLITE_BUSY` 错误。PRD 未说明：
+  - 是否启用 WAL 模式（默认 journal 模式并发性极差）
+  - 写入失败时的重试策略
+  - 同一 repo 的两个 worktree 同时运行 agent 时，它们是共享同一个 `.db` 还是各自独立？路径 `.omc/observability.db` 在 worktree 中是相对路径，**每个 worktree 会有独立的 `.omc/` 目录**，数据天然隔离——但这意味着跨 worktree 的聚合查询无法实现，与"可观测性平台"的定位矛盾。
+
+- **[P0] token 估算降级策略缺失**：PRD 声称记录 cost，但 Claude API 的真实 token 数只在响应头中返回，agent 内部无法直接获取。PRD 未定义：
+  - 降级方案（如字符数 / 4 的粗估）
+  - 估算值与真实值的误差范围（实测可达 ±30%）
+  - `cost_records` 表是否区分 `estimated` vs `actual` 字段，防止误导性数据
+
+- **[P1] 数据库文件损坏场景**：agent 进程被 SIGKILL 中断时，SQLite 写入可能产生损坏的 `.db` 文件。`better-sqlite3` 同步 API 在进程崩溃时无法保证事务完整性。PRD 未定义损坏检测和自动修复（`PRAGMA integrity_check`）流程。
+
+- **[P1] 磁盘空间无上限**：长期运行的项目中，`tool_calls` 表会无限增长。PRD 未定义：
+  - 自动清理策略（如保留最近 N 天）
+  - 文件大小告警阈值
+
+- **[P2] 表结构迁移**：PRD 定义了 3 张表的初始结构，但未说明 schema 版本管理机制。未来字段变更时，已有用户的 `.db` 文件如何迁移？
+
+---
+
+## 3. Logical Consistency (逻辑一致性)
+
+- **[P0] worktree 隔离 vs 平台定位矛盾**：PRD 将其定位为"可观测性**平台**"，暗示跨 agent、跨会话的聚合视图。但将 `.db` 放在 worktree 根目录下，数据天然按 worktree 分片，无法实现跨 worktree 的统一查询。正确的架构应选择其一：
+  - 选项 A：集中存储（`~/.claude/observability.db`），支持全局聚合，但引入跨进程并发问题
+  - 选项 B：分散存储（per-worktree），放弃跨 worktree 聚合，定位降级为"本地运行日志"
+
+- **[P1] 测试 mock 策略未定义**：PRD 要求 ≥15 个测试用例，但未说明如何隔离测试环境。`better-sqlite3` 同步 API 的常见 mock 方案有两种，各有取舍：
+  - 方案 A：使用 `:memory:` 数据库（`new Database(':memory:')`）——无需 mock，但无法测试文件路径相关逻辑
+  - 方案 B：`jest.mock('better-sqlite3')`——可测试路径逻辑，但 mock 维护成本高，且容易与真实 API 行为脱节
+  PRD 未选择，导致测试策略不明确，15 个用例的质量无法保证。
+
+- **[P2] `agent_runs` 与 `tool_calls` 的关联完整性**：PRD 未定义外键约束。若 `agent_runs` 记录被删除，对应的 `tool_calls` 是否级联删除？SQLite 默认不启用外键（需 `PRAGMA foreign_keys = ON`），PRD 未提及。
+
+- **[P2] `tsc 0 errors` 验收标准过弱**：类型检查通过不等于运行时正确。`better-sqlite3` 的 TypeScript 类型定义（`@types/better-sqlite3`）对 `prepare().run()` 的返回值类型较宽松，类型检查无法捕获 SQL 语句错误或字段名拼写错误。
+
+---
+
+## Conclusion (结论)
+
+**判定：Reject**
+
+**严重阻碍 (Major Blockers)：**
+
+1. `.omc/*.db` 未加入 `.gitignore`，敏感运营数据面临版本库泄露风险（P0 安全）
+2. 多 worktree 并发写入无保护机制，`SQLITE_BUSY` 会导致数据丢失（P0 可靠性）
+3. worktree 分散存储与"可观测性平台"的跨会话聚合定位根本矛盾，架构方向未决（P0 逻辑）
+4. token 估算降级策略缺失，`cost_records` 数据可信度无法保证（P0 数据质量）
+
+**建议在进入实现前明确：**
+- 存储位置：集中（`~/.claude/`）还是分散（per-worktree）
+- `.gitignore` 补充 `.omc/*.db`
+- WAL 模式 + 写入重试策略
+- token 估算字段区分 `estimated` / `actual`

package/docs/reviews/draft-prd-agent-observability/review_domain.md

@@ -0,0 +1,100 @@
+# Domain Expert Review: Draft PRD - Agent 可观测性平台
+
+## 1. Logic Validation (逻辑验证)
+
+### SQLite 同步写入阻塞问题
+- **结论**: Adjustment Needed
+- better-sqlite3 是同步 API，每次 `INSERT` 会在 Node.js 主线程上阻塞。对于 agent 执行追踪（高频写入），这会直接延迟 agent 响应。
+- 现有 `job-state-db.ts` 已启用 `PRAGMA journal_mode = WAL`，WAL 模式允许并发读，但**写入仍然是串行阻塞的**。
+- 实际影响：单次 SQLite 同步写入约 0.1–2ms，在 agent 热路径上累积可达数十毫秒。
+- 缓解方案（不需要改变技术选型）：
+  1. 写入操作放入内存队列，用 `setImmediate` 异步 flush，避免阻塞调用方。
+  2. 对非关键路径（tool_calls 详情）使用批量写入而非逐条写入。
+  3. 加 `PRAGMA synchronous = NORMAL`（WAL 模式下安全，减少 fsync 次数）。
+
+### P95 计算在 SQLite 中的实现
+- **结论**: Adjustment Needed
+- SQLite 没有内置 `PERCENTILE_CONT` 函数（PostgreSQL/DuckDB 有）。
+- 正确实现方式：
+  ```sql
+  -- 需要 ORDER BY + LIMIT/OFFSET 模拟
+  SELECT duration_ms FROM tool_calls
+  WHERE tool_name = ?
+  ORDER BY duration_ms
+  LIMIT 1 OFFSET (
+    SELECT CAST(COUNT(*) * 0.95 AS INTEGER) FROM tool_calls WHERE tool_name = ?
+  );
+  ```
+- 这个查询在数据量大时性能差（全表扫描）。PRD 未说明数据量预期，需要在 `duration_ms` 上建索引，并限制查询窗口（如最近 1000 条）。
+- 替代方案：在应用层用 JavaScript 计算 P95，从 SQLite 取原始数据后排序，更灵活且无 SQL 复杂度。
+
+### 成本追踪字段完整性
+- **结论**: Adjustment Needed
+- PRD 仅提到 haiku/sonnet/opus 单价，但现有 `cost-estimator.ts` 已实现四个维度：`inputCost`、`outputCost`、`cacheWriteCost`、`cacheReadCost`。
+- agent_runs 表如果只存 `total_cost`，会丢失 cache 节省信息，无法做成本优化分析。
+- 必须存储：`input_tokens`、`output_tokens`、`cache_creation_tokens`、`cache_read_tokens`，而非仅存金额。
+
+---
+
+## 2. Industry Standard Check (标准合规)
+
+### Token 成本估算准确性
+- **结论**: Pass（有条件）
+- 现有 `types.ts` 中的 PRICING 硬编码值与 Anthropic 官方定价（截至 2026-03）对比：
+  | 模型 | PRD/代码 Input/MTok | PRD/代码 Output/MTok | 官方 Input/MTok | 官方 Output/MTok |
+  |------|---------------------|----------------------|-----------------|------------------|
+  | Haiku 4 | $0.80 | $4.00 | $0.80 | $4.00 |
+  | Sonnet 4.x | $3.00 | $15.00 | $3.00 | $15.00 |
+  | Opus 4.x | $15.00 | $75.00 | $15.00 | $75.00 |
+- 数值准确。但 `cacheWriteMarkup: 0.25` 表示 cache write 价格 = input × 1.25，实际 Anthropic 定价是 cache write = input × **1.25**（即 +25%），正确。
+- `cacheReadDiscount: 0.90` 表示 cache read = input × 0.10（节省 90%），正确。
+- 风险：硬编码定价会随 Anthropic 调价而过时。代码已有 `tokscale-adapter.ts` 动态定价路径，PRD 应明确优先使用动态路径，硬编码仅作 fallback。
+
+### 可观测性行业标准对比
+- **结论**: Adjustment Needed
+- 行业标准可观测性三支柱：Metrics（指标）、Traces（追踪）、Logs（日志）。
+- PRD 当前覆盖：Metrics（P95 耗时、成本）+ 部分 Traces（agent_runs、tool_calls）。
+- 缺失：结构化 Logs（错误详情、agent 决策链）、Span 关联（parent_run_id 将 tool_call 关联到 agent_run）。
+- 不是造轮子：OpenTelemetry 是标准，但对 CLI 工具引入 OTEL SDK 过重。SQLite 方案合理，但 schema 设计应参考 OTEL Span 模型（trace_id、span_id、parent_span_id）。
+
+---
+
+## 3. Value Proposition (价值主张)
+
+### 开发者用户
+- **收益**: 能看到哪个 agent/tool 最慢、最贵，直接指导优化决策。P95 耗时可识别长尾问题。
+- **风险**: 如果同步写入拖慢 agent，用户会关掉这个功能，价值归零。性能影响必须 < 1ms/写入。
+
+### 成本敏感用户
+- **收益**: cache token 分解（write vs read）能量化 prompt caching 的实际节省，这是现有工具普遍缺失的。
+- **前提**: 必须存储四维 token 数据，而非仅存总成本。
+
+---
+
+## 4. 遗漏的可观测性维度
+
+以下维度在 PRD 中未提及，但对 agent 系统有实际价值：
+
+| 维度 | 说明 | 优先级 |
+|------|------|--------|
+| `parent_run_id` | tool_call 关联到 agent_run，支持调用链追踪 | P0 |
+| `error_type` / `error_message` | 区分超时、API 错误、用户取消 | P0 |
+| `agent_model` | 记录实际使用的模型（含 fallback 后的模型） | P1 |
+| `retry_count` | tool 重试次数，识别不稳定工具 | P1 |
+| `context_window_usage` | input_tokens / max_context，识别接近上限的 agent | P2 |
+
+---
+
+## Conclusion (结论)
+
+**Modification Required**
+
+### Critical Domain Gaps (关键领域缺陷)
+
+1. **同步写入阻塞**：必须在热路径上使用异步队列 flush，否则会降低 agent 执行性能，与可观测性的"零侵入"原则相悖。
+
+2. **P95 实现未定义**：SQLite 无原生百分位函数，PRD 需明确实现策略（SQL 模拟 vs 应用层计算），并指定查询窗口大小以保证性能。
+
+3. **token 存储粒度不足**：必须存储四维 token 数据（input/output/cache_write/cache_read），仅存总成本会丢失 cache 优化分析能力。
+
+4. **缺少 `parent_run_id`**：没有 span 关联，tool_calls 表是孤立数据，无法重建 agent 执行链，可观测性价值大幅降低。

package/docs/reviews/draft-prd-agent-observability/review_product.md

@@ -0,0 +1,78 @@
+# Product Strategy Review: Agent 可观测性平台
+
+**评审日期：** 2026-03-02
+**评审人：** Product Director
+**PRD 状态：** Draft
+
+---
+
+## 1. Strategic Fit（战略匹配: Med）
+
+**Alignment 分析：**
+
+现有 trace skill（`trace_timeline` / `trace_summary`）已覆盖会话内的 agent 流程可视化，基于 JSONL 文件的 session-replay 机制。本 PRD 提出的"可观测性平台"本质上是对 trace 的持久化扩展，而非独立方向。
+
+差异化评估：
+
+| 能力 | 现有 trace skill | 本 PRD 新增 |
+|------|-----------------|------------|
+| 会话内时间线 | 已有 | 无新增 |
+| 跨会话数据保留 | 无（JSONL 临时文件） | SQLite 持久化 |
+| 成本/token 追踪 | 无 | 新增 |
+| P95 工具调用分析 | 无 | 新增 |
+| 独立 skill 入口 | /trace | /ax-observe（重复） |
+
+差异化是真实的，但 `/ax-observe` 作为独立 skill 的必要性存疑——现有 `/trace` 完全可以扩展承载这些能力，新增 skill 会造成用户认知分裂。
+
+**Roadmap Fit：**
+
+当前 Q1 重心是 Axiom 进化引擎完整化（T-01~T-08 刚完成）和 Plugin 生态。可观测性属于"基础设施增强"，不在已确认的三个高价值方向主线上，属于支撑性需求。
+
+---
+
+## 2. Prioritization Matrix（优先级矩阵）
+
+- Impact: **3 / 5**
+  - 成本追踪对重度用户有价值，但 ultrapower 用户群目前以开发者为主，成本感知需求尚未成为痛点
+  - P95 分析是高级运维需求，受众窄
+  - 跨会话持久化有实际价值，但紧迫度低
+
+- Effort: **4 / 5**
+  - SQLite 引入新依赖（better-sqlite3 或 drizzle），需处理 Windows 路径、并发写入、schema 迁移
+  - 成本估算需维护 token 定价表，随模型更新需持续维护
+  - P95 统计需要足够的数据量才有意义
+
+- Score: **3 × (5-4) / 5 = ROI 偏低**，投入产出比不理想。
+
+---
+
+## 3. Success Metrics（成功指标）
+
+- Primary KPI：跨会话 trace 查询使用率（目标：活跃用户中 >20% 每周使用一次）
+- Secondary KPI：成本追踪功能的用户留存影响（难以单独归因）
+- 不做的风险：低。现有 trace skill 已满足核心调试需求，缺失持久化是体验缺口而非功能缺口。
+
+---
+
+## 4. 范围裁剪建议
+
+当前 PRD 范围过大，建议按以下优先级拆分：
+
+**保留（MVP）：**
+- 跨会话 JSONL 归档（复用现有 file-lock + archiver 模式，无需 SQLite）
+- 在现有 `/trace` skill 上扩展 `--session <id>` 参数支持历史查询
+
+**延后（v2）：**
+- 成本/token 追踪（需定价表维护机制成熟后再做）
+- P95 工具调用分析（需积累足够数据量）
+
+**拒绝：**
+- `/ax-observe` 独立 skill——合并到 `/trace` 扩展，避免认知分裂
+
+---
+
+## Conclusion（结论）
+
+**P2 - Nice to Have**（当前形态）/ **P1 - Should Have**（裁剪后 MVP）
+
+**Note：** 本 PRD 的核心价值点（跨会话持久化）值得做，但实现路径应是扩展现有 trace skill，而非新建独立平台。SQLite + 成本追踪的完整方案在当前阶段 effort 过高，建议先用 JSONL 归档方案（与 Axiom 进化引擎的 archiver 模式一致）验证需求，再决定是否引入数据库层。优先级低于 Plugin 生态方向。

package/docs/reviews/draft-prd-agent-observability/review_tech.md

@@ -0,0 +1,66 @@
+# Tech Feasibility Review: Agent 可观测性平台
+
+## 1. Architecture Impact (架构影响)
+
+- Schema Changes: Yes — 新增 `.omc/observability.db`（SQLite），3 张新表
+- API Changes: Yes — 新增 `src/hooks/observability/` 模块 + `skills/ax-observe/SKILL.md`
+
+**关键发现：严重重复风险**
+
+PRD 提议的功能与现有代码高度重叠：
+
+| PRD 提议 | 已有实现 |
+|---------|---------|
+| `agent_runs` 表（agent_type/model/duration_ms） | `src/hooks/subagent-tracker/index.ts` — `SubagentInfo` 接口已有完整字段 |
+| `tool_calls` 表（tool_name/duration_ms/success） | `recordToolUsageWithTiming()` 已实现，存于 JSON state |
+| `cost_records` 表（token 估算/模型单价） | `src/analytics/cost-estimator.ts` — `calculateCost()` 已支持 haiku/sonnet/opus |
+| tool 聚合统计（avg/p95/failure_rate） | `getAgentPerformance()` 已计算 avg_ms/max_ms/failures |
+| query-engine | `src/analytics/query-engine.ts` 已存在 |
+
+**结论：PRD 描述的是对已有 JSON-based 追踪系统的 SQLite 迁移，而非全新功能。**
+
+---
+
+## 2. Risk Assessment (风险评估)
+
+- Complexity Score (1-10): **4**
+- POC Required: No
+
+**风险点：**
+
+1. **数据迁移**（中风险）：现有 `subagent-tracking.json` 数据需要决策——迁移还是并行运行？PRD 未说明。
+2. **并发写入**（低风险）：`better-sqlite3` 是同步 API，与现有 debounce+lock 机制兼容，但需要确认 WAL 模式开启以支持并发读。
+3. **Hook 集成点**（低风险）：`PreToolUse`/`PostToolUse`/`SubagentStart`/`SubagentStop` 已有 hook 接入点，新模块只需挂载。
+4. **p95 计算**（低风险）：SQLite 无内置 percentile 函数，需要应用层排序计算，数据量小时可接受。
+
+---
+
+## 3. Implementation Plan (大致实现计划)
+
+**Backend（约 2 天）：**
+- `src/hooks/observability/db.ts`：初始化 3 张表，开启 WAL 模式
+- `src/hooks/observability/agent-tracker.ts`：复用 `SubagentInfo` 类型，写入 `agent_runs`
+- `src/hooks/observability/tool-tracker.ts`：复用 `ToolUsageEntry`，写入 `tool_calls`
+- `src/hooks/observability/cost-estimator.ts`：调用已有 `calculateCost()`，写入 `cost_records`
+- `src/hooks/observability/query-engine.ts`：聚合查询（avg/p95/failure_rate）
+
+**Frontend/Skill（约 0.5 天）：**
+- `skills/ax-observe/SKILL.md`：调用 query-engine 输出格式化报告
+- `/ax-status` 集成：追加 observability 摘要
+
+**测试（约 1 天）：**
+- ≥15 个测试用例覆盖：表创建、写入、聚合查询、成本估算
+
+---
+
+## Conclusion (结论)
+
+- **Pass**（条件通过）
+- Estimated Effort: **3~4 天**
+
+**前置决策（需 PRD 补充）：**
+1. 是否废弃现有 JSON 追踪，完全迁移到 SQLite？还是双轨并行？
+2. `observability.db` 是否纳入 `.gitignore`？
+3. p95 计算的数据窗口定义（最近 N 条 vs 时间窗口）？
+
+建议在实现前明确第 1 点，否则会产生数据双写的维护负担。

package/docs/reviews/draft-prd-agent-observability/review_ux.md

@@ -0,0 +1,70 @@
+# UX Review: Draft PRD - Agent 可观测性平台
+
+## 1. Flow Analysis (流程分析)
+
+**F1 /ax-observe 命令结构**
+
+PRD 设计了四个子命令：`--session`、`--agent`、`--tool`、`--cost`。问题在于这四个维度是正交的，用户实际需求往往是组合查询（"这次 session 里哪个 agent 花费最高"），但当前设计无法表达这种组合。
+
+- 现状：`/ax-observe --cost` 和 `/ax-observe --agent` 是独立命令，无法组合
+- 建议：改为主命令 + 过滤参数模式：`/ax-observe [--session <id>] [--by agent|tool|cost]`，支持组合
+
+**F2 /ax-status 集成**
+
+"可观测性摘要"区块的触发时机不明确——是每次执行 `/ax-status` 都显示，还是只在有异常时显示？
+
+- 问题：如果默认展示，会增加 `/ax-status` 的输出噪音；如果默认隐藏，用户不知道这个功能存在
+- 建议：默认显示单行摘要 `[observe] last run: 3 agents, 12.4s, ~$0.08`，`--verbose` 展开详情
+
+**F3 用户故事与命令的映射断层**
+
+用户故事"查看最近一次 ultrawork 执行中每个 agent 的耗时分布"需要几步才能完成：先找到 session id，再用 `--session` 过滤，再用 `--agent` 查看。PRD 没有提供"最近一次执行"的快捷入口。
+
+- 建议：增加 `/ax-observe --last` 作为最高频操作的零参数快捷方式
+
+---
+
+## 2. UI/Visual Feedback (视觉反馈)
+
+**耗时分布的 CLI 呈现**
+
+PRD 提到"耗时分布"但未定义输出格式。在 CLI 环境下，表格和图表的选择直接影响可读性。
+
+- 问题：如果输出原始数字列表，用户无法快速识别瓶颈
+- 建议：使用对齐表格 + 相对比例条，例如：
+  ```
+  agent          time    share
+  executor       8.2s    ████████░░  66%
+  verifier       3.1s    ███░░░░░░░  25%
+  explore        1.1s    █░░░░░░░░░   9%
+  ```
+
+**成本输出的精度问题**
+
+`--cost` 输出的数字精度未定义。`$0.001234` 和 `$0.00` 都会让用户困惑。
+
+- 建议：统一显示两位小数美元，附带 token 数：`$0.08 (input: 12,400 / output: 3,200 tokens)`
+
+**工具调用最慢的识别**
+
+用户故事"知道哪个工具调用最慢"需要一个明确的视觉标记，而不是让用户自己从列表中找。
+
+- 建议：最慢的条目自动标注 `[slowest]`，超过阈值（如 5s）标注 `[warn]`
+
+---
+
+## 3. Usability Score (1-10)
+
+**评分：5/10**
+
+Reasoning：命令结构设计存在根本性的正交维度问题，四个子命令无法组合使用，导致最常见的"跨维度查询"场景需要多次执行命令并手动关联结果。用户故事与实际命令设计之间存在明显的映射断层。输出格式完全未定义，在 CLI 环境下这是高风险遗漏——同样的数据用表格和用 JSON 输出，可用性差距极大。`/ax-status` 集成的触发逻辑不清晰，可能造成输出噪音或功能不可发现两个极端。
+
+---
+
+## Conclusion (结论)
+
+- Optimizable
+- Top 3 Changes Needed (亟待改进):
+  1. 重构子命令为组合过滤参数模式，支持 `--by agent|tool|cost` 与 `--session` 组合使用，消除正交维度断层
+  2. 明确定义 CLI 输出格式：耗时用对齐表格+比例条，成本用"$X.XX (N tokens)"格式，最慢条目自动标注
+  3. 增加 `/ax-observe --last` 零参数快捷入口，覆盖最高频的"查看上次执行"场景

package/docs/reviews/draft-prd-agent-observability/rough_prd.md

@@ -0,0 +1,135 @@
+---
+title: "Agent 可观测性平台 Rough PRD"
+direction: 2
+status: rough
+created: 2026-03-02
+review_verdict: "Pass with modifications (4/5 experts)"
+---
+
+# Rough PRD：Agent 可观测性平台
+
+## 1. 背景与目标
+
+ultrapower 拥有 49 个 agents、71 个 skills、47 个 hooks，缺乏统一可观测性层。
+
+**目标**：构建 Agent 可观测性平台，覆盖执行追踪、工具分析、成本追踪三个维度。
+
+## 2. 评审仲裁结论
+
+### 采纳的修改（来自专家评审）
+
+| 修改点 | 来源 | 原因 |
+|--------|------|------|
+| 存储位置改为 `~/.claude/.omc/observability.db` | Critic | 解决 gitignore 问题 + 支持跨 worktree 聚合 |
+| WAL 模式 + 内存队列异步写入 | Critic + Domain Expert | 防 SQLITE_BUSY，不阻塞主线程 |
+| schema 增加 `parent_run_id` | Domain Expert | 重建执行链，可观测性基础字段 |
+| token 四维存储（input/output/cache_write/cache_read） | Domain Expert | 对齐现有 cost-estimator.ts |
+| `/ax-observe` 合并为 `/trace --observe` 扩展 | Product Director | 降低认知分裂，复用现有入口 |
+| P95 用应用层计算（最近 1000 条 + 索引） | Domain Expert | SQLite 无原生百分位函数 |
+| 优先走 tokscale-adapter.ts 动态定价 | Domain Expert | 硬编码仅作 fallback |
+
+### 不采纳的建议
+
+| 建议 | 来源 | 原因 |
+|------|------|------|
+| 改用 JSONL 轻量路径 | Product Director | 用户已明确选择 SQLite |
+| 延迟到 Q2 实现 | Product Director | 用户已确认方向 |
+
+## 3. 功能范围（修订版）
+
+### 3.1 Agent 执行追踪
+- 记录每次 agent 调用：`agent_type`、`model`、`start_time`、`end_time`、`duration_ms`、`session_id`、`parent_run_id`
+- 支持按 session / agent_type / 时间范围查询
+
+### 3.2 工具调用分析
+- 记录每次工具调用：`tool_name`、`duration_ms`、`success`、`error_msg`、`session_id`、`parent_run_id`
+- 聚合统计：调用次数、平均耗时、P95 耗时（应用层，最近 1000 条）、失败率
+
+### 3.3 成本追踪
+- 四维 token 存储：`input_tokens`、`output_tokens`、`cache_write_tokens`、`cache_read_tokens`
+- 优先走 `tokscale-adapter.ts` 动态定价，硬编码作 fallback
+- 按模型计算成本（haiku/sonnet/opus）
+
+### 3.4 展示层
+- `/trace --observe [--session <id>] [--agent <type>] [--tool <name>] [--cost] [--last <n>]`：扩展现有 `/trace` skill
+- `/ax-status` 集成：增加「可观测性摘要」区块
+
+## 4. 技术方案（修订版）
+
+### 存储
+- 路径：`~/.claude/.omc/observability.db`（全局，跨 worktree）
+- WAL 模式：`PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL;`
+- 写入：内存队列 + `setImmediate` 异步 flush，批量写入
+
+### Schema
+
+```sql
+CREATE TABLE agent_runs (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  parent_run_id TEXT,
+  agent_type TEXT NOT NULL,
+  model TEXT NOT NULL,
+  start_time INTEGER NOT NULL,
+  end_time INTEGER,
+  duration_ms INTEGER,
+  status TEXT DEFAULT 'running'
+);
+
+CREATE TABLE tool_calls (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  parent_run_id TEXT,
+  tool_name TEXT NOT NULL,
+  start_time INTEGER NOT NULL,
+  duration_ms INTEGER,
+  success INTEGER NOT NULL DEFAULT 1,
+  error_msg TEXT
+);
+
+CREATE TABLE cost_records (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  agent_run_id TEXT,
+  model TEXT NOT NULL,
+  input_tokens INTEGER DEFAULT 0,
+  output_tokens INTEGER DEFAULT 0,
+  cache_write_tokens INTEGER DEFAULT 0,
+  cache_read_tokens INTEGER DEFAULT 0,
+  cost_usd REAL DEFAULT 0,
+  recorded_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_agent_runs_session ON agent_runs(session_id);
+CREATE INDEX idx_tool_calls_session ON tool_calls(session_id);
+CREATE INDEX idx_tool_calls_duration ON tool_calls(duration_ms);
+CREATE INDEX idx_cost_records_session ON cost_records(session_id);
+```
+
+### 核心模块
+- `src/hooks/observability/db.ts` — SQLite 初始化 + WAL + schema
+- `src/hooks/observability/write-queue.ts` — 内存队列 + 异步 flush
+- `src/hooks/observability/agent-tracker.ts` — agent run 记录
+- `src/hooks/observability/tool-tracker.ts` — tool call 记录
+- `src/hooks/observability/cost-estimator.ts` — token/cost 估算（对齐现有实现）
+- `src/hooks/observability/query-engine.ts` — 查询聚合（含 P95 应用层计算）
+- `skills/trace/SKILL.md` — 扩展 `--observe` 子命令
+- `skills/ax-status/SKILL.md` — 增加可观测性摘要区块
+
+## 5. 验收标准
+
+- [ ] `~/.claude/.omc/observability.db` 自动创建，WAL 模式，3 张表正确建立
+- [ ] agent_runs 可写入（异步队列）、可按 session 查询
+- [ ] tool_calls 可写入、P95 应用层计算正确（最近 1000 条）
+- [ ] cost_records 四维 token 存储，动态定价优先
+- [ ] `/trace --observe` 输出格式化报告（含 `--last <n>` 快捷参数）
+- [ ] `/ax-status` 显示可观测性摘要
+- [ ] 单元测试 ≥ 15 个测试用例
+- [ ] tsc --noEmit 0 errors，全量测试通过
+
+## 6. 不在范围内
+
+- 实时流式监控（WebSocket/SSE）
+- 跨项目数据聚合
+- 告警/通知系统
+- 独立 `/ax-observe` skill（合并到 `/trace`）