@winspan/claude-forge 8.41.0 → 8.51.0

package/docs/design/h1-storage-aggregation-spec-20260518-1121.md

@@ -0,0 +1,299 @@
+# H1: Storage 层 SQL 聚合改造 Spec
+
+## 目标
+
+把 `web/routes/{rules,skill-stats,tasks}.ts` 里的"全表 SELECT + JS GROUP BY"模式下沉为 SQL 聚合，消除单进程内存放大（最大 100k 行 × 2），同时把 `tasks/:taskId` 的 5000 行二段全扫改为 PK 直查 + JOIN。纯增量改动，旧 API 不动。
+
+## 涉及文件
+
+- 改动 storage：`src/core/storage/routing.ts`、`src/core/storage/skills.ts`、`src/core/storage/tasks.ts`、`src/core/storage/sqlite.ts`（facade 转发）
+- 改动 routes：`src/web/routes/rules.ts`、`src/web/routes/skill-stats.ts`、`src/web/routes/tasks.ts`
+- 索引：`src/core/storage/schema.sql` + `src/core/storage/base.ts`（runMigrations）
+- 测试新增：`tests/unit/storage/routing-aggregates.test.ts`、`tests/unit/storage/skills-aggregates.test.ts`、`tests/unit/storage/tasks-getById.test.ts`
+- 测试保留契约：`tests/unit/web/routes-skill-stats.test.ts`、`tests/unit/web/routes-tasks.test.ts`
+- 测试缺口：rules 路由无测试 → spec 标注需补 `tests/unit/web/routes-rules.test.ts`
+
+## 现状分析
+
+| 文件:行 | 问题 | 行为 |
+|---|---|---|
+| `rules.ts:24,34` | `limit: 100000` ×2 | 全表 routing/skill 拉进内存后 JS reduce |
+| `skill-stats.ts:19,44,65,113` | 5 个 `limit: 10000` | 4 个聚合 + 1 个 trend by-day |
+| `skill-stats.ts:94` | `limit: 1000` invocations | by-skill 频次聚合 |
+| `tasks.ts:63-64` | 拉 5000 tasks 再 `.find(id)` | 应 PK 直查 |
+| `tasks.ts:71-75` | 拉 5000 events 后 `Set.has` 过滤 | 应 JOIN `task_events` |
+
+## 设计方案
+
+### 1. 新增 storage 方法
+
+**命名约定**：聚合方法用 `aggregate` 前缀（CLAUDE.md 未明确，spec 明确为硬约束）。
+
+#### `RoutingOperations` (`src/core/storage/routing.ts`)
+
+```ts
+// 一次返回 rules.ts 和 skill-stats.ts 共用的 routing 汇总
+aggregateRoutingStats(filter: { since_ts: number; project_path?: string }): {
+  total: number;
+  obeyed: number;       // obeyed = 1
+  refused: number;      // obeyed = 0
+  unknown: number;      // obeyed IS NULL
+  by_type: Array<{ type: 'agent' | 'skill' | 'none'; count: number }>;
+  by_agent: Array<{ agent: string; count: number }>;       // obeyed=1 AND routed_to_name NOT NULL
+  by_skill_routed: Array<{ skill: string; count: number }>; // routed_to_type='skill' (for frequency)
+}
+```
+
+SQL（在事务里跑 4 个独立聚合，全部走 `idx_routing_events_ts` / `idx_routing_events_obeyed_ts` / `idx_routing_events_agent`）：
+
+```sql
+-- total + obeyed counts
+SELECT COUNT(*) AS total,
+       SUM(CASE WHEN obeyed=1 THEN 1 ELSE 0 END) AS obeyed,
+       SUM(CASE WHEN obeyed=0 THEN 1 ELSE 0 END) AS refused,
+       SUM(CASE WHEN obeyed IS NULL THEN 1 ELSE 0 END) AS unknown
+FROM routing_events WHERE ts >= @since AND (@project IS NULL OR project_path = @project);
+
+-- by_type (distribution)
+SELECT COALESCE(routed_to_type,'none') AS type, COUNT(*) AS count
+FROM routing_events WHERE ts >= @since [...] GROUP BY type;
+
+-- by_agent
+SELECT routed_to_name AS agent, COUNT(*) AS count
+FROM routing_events
+WHERE ts >= @since AND obeyed=1 AND routed_to_name IS NOT NULL [...]
+GROUP BY routed_to_name ORDER BY count DESC;
+
+-- by_skill_routed (frequency)
+SELECT routed_to_name AS skill, COUNT(*) AS count
+FROM routing_events
+WHERE ts >= @since AND routed_to_type='skill' AND routed_to_name IS NOT NULL [...]
+GROUP BY routed_to_name ORDER BY count DESC;
+```
+
+```ts
+// trend by day（skill-stats.ts:62）— SQLite 用 strftime
+aggregateRoutingTrendByDay(filter: { since_ts: number }): Array<{
+  day: string;       // 'YYYY-MM-DD'
+  total: number;
+  skill: number;
+}>
+```
+
+SQL：
+
+```sql
+SELECT strftime('%Y-%m-%d', ts/1000, 'unixepoch') AS day,
+       COUNT(*) AS total,
+       SUM(CASE WHEN routed_to_type='skill' THEN 1 ELSE 0 END) AS skill
+FROM routing_events WHERE ts >= @since
+GROUP BY day ORDER BY day ASC;
+```
+
+调用方：`rules.ts`（hit-rate）、`skill-stats.ts`（distribution / frequency / trend / routing-stats）
+
+#### `SkillOperations` (`src/core/storage/skills.ts`)
+
+```ts
+aggregateSkillInvocationsBySkill(filter: { since: number; limit?: number }): Array<{
+  skill_id: string;
+  total: number;
+  success: number;   // success = 1
+  failed: number;    // success = 0
+}>
+```
+
+SQL（走 `idx_skill_invocations_timestamp` + group）：
+
+```sql
+SELECT skill_id,
+       COUNT(*) AS total,
+       SUM(CASE WHEN success=1 THEN 1 ELSE 0 END) AS success,
+       SUM(CASE WHEN success=0 THEN 1 ELSE 0 END) AS failed
+FROM skill_invocations
+WHERE timestamp >= @since
+GROUP BY skill_id ORDER BY total DESC;
+```
+
+调用方：`rules.ts`（per-skill）、`skill-stats.ts:91`（invocations）
+
+#### `TaskOperations` (`src/core/storage/tasks.ts`)
+
+```ts
+getTask(taskId: string): TaskRecord | null;
+queryEventsByTaskId(taskId: string, opts?: { limit?: number }): ForgeEvent[];
+queryInjectionsByTaskId(taskId: string): Injection[];
+querySkillInvocationsByTaskWindow(taskId: string): SkillInvocationRow[]; // 用 task 的 start_time / end_time 直接 SQL 过滤
+```
+
+SQL：
+
+```sql
+-- getTask
+SELECT t.*, s.project_path FROM tasks t
+LEFT JOIN sessions s ON s.session_id = t.session_id
+WHERE t.id = ?;
+
+-- queryEventsByTaskId
+SELECT e.* FROM events e
+JOIN task_events te ON te.event_id = e.event_id
+WHERE te.task_id = ?
+ORDER BY e.timestamp ASC
+LIMIT ?;
+
+-- queryInjectionsByTaskId
+SELECT i.* FROM injections i
+JOIN task_events te ON te.event_id = i.event_id
+WHERE te.task_id = ?
+ORDER BY i.timestamp ASC;
+
+-- querySkillInvocationsByTaskWindow（避免 detail 路由再做时间过滤）
+SELECT si.* FROM skill_invocations si
+JOIN tasks t ON t.session_id = si.session_id
+WHERE t.id = ?
+  AND si.timestamp >= CAST(strftime('%s', t.start_time) AS INTEGER) * 1000
+  AND si.timestamp <= COALESCE(CAST(strftime('%s', t.end_time) AS INTEGER) * 1000, @now_ms)
+ORDER BY si.timestamp ASC;
+```
+
+调用方：`tasks.ts:59` detail route
+
+> **决策**：`querySkillInvocationsByTaskWindow` 把 `now` 通过参数传入而不是 SQL 端拿，便于测试时 mock 时间。
+
+### 2. 索引调整
+
+**复查现状**：
+- `idx_routing_events_ts` ✓ — 覆盖 `since_ts`
+- `idx_routing_events_agent (routed_to_name, obeyed)` ✓ — 覆盖 by_agent
+- `idx_routing_events_obeyed_ts` ✓ — 覆盖 obeyed group
+- `idx_skill_invocations_timestamp` ✓ — 覆盖 since filter
+- `idx_skill_invocations_skill` ✓ — 覆盖 by skill_id group（不一定需要）
+- `idx_task_events_task` ✓ — 覆盖 JOIN
+- `tasks.id` 是 PK ✓
+
+**新增（一处）**：
+
+```sql
+-- routing_events: routed_to_type 走 distribution 分组高频用
+CREATE INDEX IF NOT EXISTS idx_routing_events_type_ts ON routing_events(routed_to_type, ts DESC);
+```
+
+放置：`schema.sql` 末尾 + `base.ts` runMigrations 末段（与 Phase 1 indexes 同样的 try/catch 块）。**不要重复放两份**——H4 已记录"schema.sql 与 base.ts 索引重复"问题。本 spec 决定：**只加在 schema.sql，base.ts 的 runMigrations 也加同一条 idempotent CREATE INDEX**（已有先例），不算重复。其它索引保持原样。
+
+### 3. Routes 改造
+
+#### `rules.ts` (hit-rate)
+
+```ts
+// before: queryRoutingEvents({limit:100000}) + querySkillInvocations({limit:100000}) + JS reduce
+// after:
+const routing = storage.aggregateRoutingStats({ since_ts: since });
+const skillsAgg = storage.aggregateSkillInvocationsBySkill({ since });
+const totalPrompts = routing.total;
+const agentDelegations = routing.obeyed;
+const skills = skillsAgg.map(s => ({...s, rate: pct(s.total, totalPrompts)}));
+const agents = routing.by_agent.map(a => ({...a, rate: pct(a.count, totalPrompts)}));
+const triggered = new Set(skillsAgg.map(s => s.skill_id));
+const neverTriggered = skillRegistry?.getAll().map(s=>s.id).filter(id=>!triggered.has(id)) ?? [];
+```
+
+#### `skill-stats.ts`
+
+| Endpoint | 旧 | 新 |
+|---|---|---|
+| `/distribution` | `queryRoutingEvents{limit:10000}` + JS group | `aggregateRoutingStats(...).by_type` |
+| `/frequency` | 同上 | `aggregateRoutingStats(...).by_skill_routed` |
+| `/trend` | 同上 + by-day JS group | `aggregateRoutingTrendByDay({since_ts})` 再 JS map 成 `{day, skillRate}` |
+| `/invocations` | `querySkillInvocations{limit:1000}` + JS group | `aggregateSkillInvocationsBySkill({since})` |
+| `/api/routing/stats` | `queryRoutingEvents{limit:10000}` + JS filter | `aggregateRoutingStats` 中 `obeyed/total/by_agent` |
+
+#### `tasks.ts:/:taskId`
+
+```ts
+// before:
+//   const allTasks = storage.queryTasks({limit:5000}); task = allTasks.find(...)
+//   const eventIds = new Set(storage.getTaskEventIds(taskId));
+//   const allEvents = storage.queryEvents({session_id, limit:5000}); filter by eventIds
+//   const allInjections = storage.queryInjections({session_id, limit:500}); filter by eventIds
+//   const allSkillInvocations = storage.querySkillInvocations({session_id, limit:200}); JS time filter
+// after:
+const task = storage.getTask(taskId); if (!task) return 404;
+const taskEvents = storage.queryEventsByTaskId(taskId, { limit: 5000 });
+const allInjections = storage.queryInjectionsByTaskId(taskId);
+const skillInvocations = storage.querySkillInvocationsByTaskWindow(taskId);
+// 后续 timeline / artifacts / userPrompts 逻辑不变
+```
+
+## 关键决策
+
+1. **聚合方法用 `aggregate` 前缀**（CLAUDE.md 未规定，本 spec 固化）— `aggregateRoutingStats` / `aggregateSkillInvocationsBySkill` / `aggregateRoutingTrendByDay`。理由：与 `query*` / `list*` / `get*` 区分语义，调用方一眼能看出"这是 SQL 端 GROUP BY"。
+2. **新方法挂在各自 Operations 类**，sqlite.ts facade 仅做转发。理由：保持职责拆分，不在 facade 写 SQL。
+3. **不合并 routing 4 个聚合到单条 SQL**。理由：SQLite 无 GROUPING SETS / CUBE，强行 UNION ALL 反而难读；分 4 条 prepared statement 各走自己的索引更快。
+4. **trend by-day 用 `strftime('%Y-%m-%d', ts/1000, 'unixepoch')`**，已验证 better-sqlite3 完全支持。
+5. **`queryEventsByTaskId` 保留 `limit` 参数**（默认 5000）— 防御过大 task；前端不分页，但要有上限。
+6. **`task_events` PK 是 `(task_id, event_id)`**，但 `task_events(event_id)` 的反向 JOIN 已有 `idx_task_events_event`；正向 `idx_task_events_task` 也存在，JOIN 性能 OK。
+
+## 测试策略
+
+### 单元测试（必加）
+
+- `tests/unit/storage/routing-aggregates.test.ts`
+  - 空表返回 `{total:0, obeyed:0, refused:0, unknown:0, by_type:[], ...}`
+  - 混合 `obeyed=1/0/NULL` 计数正确
+  - `since_ts` 过滤边界（等于 / 小于）
+  - `by_agent` 排除 `obeyed≠1` 和 `routed_to_name IS NULL`
+  - `aggregateRoutingTrendByDay` 跨日聚合 + 时区一致性（UTC）
+- `tests/unit/storage/skills-aggregates.test.ts`
+  - `success=1/0` 分别计数；按 total 降序
+  - `since` 过滤
+- `tests/unit/storage/tasks-getById.test.ts`
+  - `getTask` 命中 / null
+  - `queryEventsByTaskId` JOIN 正确性 + 排序
+  - `querySkillInvocationsByTaskWindow` 时间窗包含/排除（含 end_time IS NULL 取 now）
+  - `queryInjectionsByTaskId` event_id 关联
+
+### 集成 / 路由测试
+
+- `tests/unit/web/routes-skill-stats.test.ts` — 保留现有契约（响应字段不变），跑过即可
+- `tests/unit/web/routes-tasks.test.ts` — 保留，detail 路由响应结构不变
+- `tests/unit/web/routes-rules.test.ts` — **缺口，本任务新增**：空数据、混合数据下 totalPrompts / agentDelegations / skills / agents / neverTriggered 均符合预期
+
+### 性能基准（可选，给 coder agent）
+
+写一个 `scripts/bench/h1-aggregation.ts`（不入 git CI）：
+- 灌 100k routing_events + 10k skill_invocations
+- 测 `aggregateRoutingStats` vs 旧 `queryRoutingEvents({limit:100000})` + JS reduce 的耗时
+- 目标：新 ≤ 旧 / 10，内存峰值下降 ≥ 90%
+
+## 风险与回滚
+
+| 风险 | 应对 |
+|---|---|
+| `strftime('%Y-%m-%d', ts/1000, 'unixepoch')` 在 ts=0 / 负值时返回 NULL | 聚合前 WHERE `ts > 0` 兜底；测试覆盖 |
+| `routed_to_type` 历史值含 NULL | `COALESCE(routed_to_type,'none')`，与旧逻辑 `e.routed_to_type \|\| 'none'` 一致 |
+| 新索引 `idx_routing_events_type_ts` 与 H4 索引重复隐患 | 检查 `base.ts` 已存在的 5 类索引前缀，确认未重复；只在 schema.sql + base.ts 的 Phase 1 块各加一处 idempotent CREATE |
+| `getTask` 响应字段需要包含 `project_path`（旧 detail 路由没用到，但 list 用了） | 用 LEFT JOIN sessions，缺失时返回 undefined，detail 路由对此字段无依赖 |
+| 测试缺口：rules 路由 0 测试 → 改造时可能行为漂移 | **强制先补 routes-rules.test.ts，再改 route**（TDD 顺序） |
+
+**回滚**：纯增量，新方法 + 新索引 + route 内部实现替换。回滚 = revert route 改动（storage 新方法保留无害）。
+
+## 实施顺序（给 coder agent）
+
+1. **Storage 层先**
+   - a. 新增 3 个 aggregate 方法 + 4 个 task 方法 + sqlite.ts facade 转发
+   - b. 新增索引（schema.sql + base.ts 同步）
+   - c. 跑 `npx vitest run tests/unit/storage/ --reporter=verbose`
+2. **补 routes-rules.test.ts**（基于旧实现先建立行为基线）
+3. **一次改一个 route，每改完跑对应测试**
+   - rules.ts → routes-rules.test.ts
+   - skill-stats.ts → routes-skill-stats.test.ts
+   - tasks.ts → routes-tasks.test.ts
+4. **`npx tsc --noEmit` + 全量测试**
+5. **可选基准脚本验证**
+
+## 命名遵循（CLAUDE.md 约束 + 本 spec 扩展）
+
+- 单条查询：`getTask(id)` ✓
+- 列表/查询：`queryEventsByTaskId`、`queryInjectionsByTaskId`、`querySkillInvocationsByTaskWindow` ✓
+- 聚合（**本 spec 固化**）：`aggregate*` — `aggregateRoutingStats`、`aggregateRoutingTrendByDay`、`aggregateSkillInvocationsBySkill`
+- 写入：本任务无新增

package/docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md

@@ -0,0 +1,191 @@
+# H2: getDatabase 越权 SQL 收敛到 Operations 层 Spec
+
+## 目标
+
+消除 `web/routes/`、`web/analytics/`、`cli/commands/`、`daemon/handlers/` 中对 `storage.getDatabase().prepare()` 的直写，按"查询动词 + 资源"命名下沉到对应 `*Operations` 类，以 `SQLiteStorage` facade 为唯一对外入口，便于后续 schema 重构。
+
+## 调研结果
+
+### 越权 SQL 清单（主线程封闭性扫描后修订：27 处）
+
+| 位置 | SQL 用途 | 表 | 应归属 |
+|---|---|---|---|
+| `daemon/handlers/stop.ts:154-158` | 按 session 统计 tool_name 调用 | events | EventOperations |
+| `daemon/handlers/stop.ts:163-168` | 按 session 统计 Agent/Task subagent_type 调用 | events | EventOperations |
+| `daemon/handlers/stop.ts:176-178` | 按 session 计数 skill 调用 | skill_invocations | SkillOperations |
+| `web/routes/stats.ts:13` | 全局 events 计数 | events | EventOperations |
+| `web/routes/stats.ts:14` | 全局 sessions 计数 | sessions | SessionOperations |
+| `web/routes/stats.ts:17-21` | Top 15 tool 使用分布 | events | EventOperations |
+| `web/routes/stats.ts:28-33` | 最近 7 天每日事件数 | events | EventOperations |
+| `web/routes/stats.ts:35-40` | 最近 7 天每日会话数 | sessions | SessionOperations |
+| `web/routes/stats.ts:50` | 全局 skill 调用计数 | skill_invocations | SkillOperations |
+| `web/routes/trace.ts:106-109` | 按 session 聚合 hook_type 分布 | events | EventOperations |
+| `web/routes/trace.ts:111-116` | 按 session 聚合 subagent_type 分布 | events | EventOperations |
+| `web/routes/trace.ts:118-120` | 按 session 列出 distinct skill_id | skill_invocations | SkillOperations |
+| **`cli/commands/trace.ts:115`** | hook_type 分布（CLI 版） | events | EventOperations |
+| **`cli/commands/trace.ts:124`** | subagent_type 分布（CLI 版） | events | EventOperations |
+| **`cli/commands/trace.ts:135`** | distinct skill_id（CLI 版） | skill_invocations | SkillOperations |
+| `web/analytics/drift-detector.ts:125-128` | 时间窗内 distinct skill 数 | skill_invocations | SkillOperations |
+| `web/analytics/drift-detector.ts:154-157` | 最近 7 天有事件的活跃日数 | events | EventOperations |
+| `web/analytics/drift-detector.ts:185-187` | 时间窗内 session 计数 | sessions | SessionOperations |
+| `web/analytics/drift-detector.ts:190-192` | 时间窗内 task 计数 | tasks | TaskOperations |
+| `web/analytics/weekly-report.ts:100-109` | 周内 events overview | events | EventOperations |
+| `web/analytics/weekly-report.ts:111-116` | 周内 distinct project_path | events | EventOperations |
+| `web/analytics/weekly-report.ts:118-122` | 周内 task 计数 | tasks | TaskOperations |
+| `web/analytics/weekly-report.ts:214-222` | 周内 PreToolUse top tools | events | EventOperations |
+| `web/analytics/weekly-report.ts:228-244` | 周内 PostToolUse 失败/总数 | events | EventOperations |
+| `web/analytics/weekly-report.ts:261-268` | 周内 file edit tool_input | events | EventOperations |
+| `web/analytics/anti-pattern-detector.ts:83-86` | 时间窗内全字段 events | events | EventOperations |
+| `web/analytics/anti-pattern-detector.ts:104-114` | 时间窗内 session 概览 | sessions | SessionOperations |
+
+**关键修订**：`cli/commands/trace.ts` 有 3 段与 web/routes/trace.ts 同模式的 SQL，调用同一组聚合方法。
+
+### Operations 类现状
+
+| 类 | 文件 | 现有方法（节选） |
+|---|---|---|
+| EventOperations | `core/storage/events.ts` | writeEvent / queryEvents / countEvents / searchEvents |
+| SessionOperations | `core/storage/sessions.ts` | upsertSession / querySessions |
+| TaskOperations | `core/storage/tasks.ts` | writeTask / queryTasks / queryTasksFiltered |
+| SkillOperations | `core/storage/skills.ts` | writeSkillInvocation / aggregateSkillInvocationsBySkill |
+| RoutingOperations | `core/storage/routing.ts` | aggregateRoutingStats / aggregateRoutingTrendByDay |
+
+H1 已固化 `aggregate*` 命名模式。
+
+### `getDatabase()` 调用方现状
+
+| 调用方 | 类型 | 处理 |
+|---|---|---|
+| `web/routes/{stats,trace}.ts` | 越权 | 消除 |
+| `web/analytics/*` | 越权 | 消除 |
+| `cli/commands/trace.ts` | 越权 | 消除 |
+| `daemon/handlers/stop.ts` | 越权 | 消除 |
+| 测试 fixture / migration | 合法 | 保留 |
+
+### 测试覆盖现状
+
+| 模块 | 现有测试 | safety-net 评级 |
+|---|---|---|
+| `web/routes/stats.ts` | 无 | **必补** |
+| `web/routes/trace.ts` | 无 | **必补** |
+| `cli/commands/trace.ts` | 无 | 可补（跑得到的话） |
+| `web/analytics/*` | `tests/integration/web-analytics.integration.test.ts`（仅 200 + shape） | 增强字段值断言 |
+| `daemon/handlers/stop.ts` behavior summary | 无 | **必补**（fixture + 断言摘要） |
+| Operations 新增方法 | 无 | 每个新方法配单测 |
+
+## 方案选择
+
+**方案 A（推荐）**：所有越权 SQL 下沉到 `*Operations`，作为聚合/计数方法暴露给 facade，调用方改用 facade。
+
+`getDatabase()` 处理：**保留 public** + jsdoc `@internal — Operations 子类使用。Routes/Handlers/Analytics 禁止调用，请使用 facade 方法。` 不改 protected（架构非继承）。
+
+## 新增 Operations 方法清单
+
+```ts
+// EventOperations（11 个）
+countAllEvents(): number;
+aggregateToolUsage(opts: { since?: string; limit?: number; hook_type?: 'PreToolUse' | 'PostToolUse' }): Array<{ tool_name: string; count: number }>;
+aggregateDailyEventCounts(opts: { since: string; until?: string }): Array<{ date: string; count: number }>;
+aggregateHookTypeBySession(session_id: string): Array<{ hook_type: string; count: number }>;
+aggregateAgentTypeBySession(session_id: string): Array<{ agent_type: string | null; count: number }>;
+aggregateToolUsageBySession(session_id: string): Array<{ tool_name: string; count: number }>;
+countActiveDays(opts: { since: string; until?: string }): number;
+aggregateOverviewByRange(opts: { since: string; until: string }): { event_count: number; session_count: number; day_count: number };
+queryDistinctProjects(opts: { since: string; until: string }): string[];
+aggregateToolFailureRate(opts: { since: string; until: string }): { post_total: number; failed: number };
+queryFileEditInputs(opts: { since: string; until: string; tool_names: string[] }): Array<{ tool_input: string }>;
+queryEventsByTimeRange(opts: { since: string; until?: string }): ForgeEvent[];
+
+// SessionOperations（4 个）
+countAllSessions(): number;
+aggregateDailySessionCounts(opts: { since: string; until?: string }): Array<{ date: string; count: number }>;
+querySessionsByTimeRange(opts: { since: string; until?: string }): SessionSummary[];
+countSessionsByRange(opts: { since: string; until?: string }): number;
+
+// TaskOperations（1 个）
+countTasksByRange(opts: { since: string; until?: string }): number;
+
+// SkillOperations（4 个）
+countAllSkillInvocations(): number;
+countSkillInvocationsBySession(session_id: string): number;
+countDistinctSkillsSince(since_ms: number): number;
+queryDistinctSkillIdsBySession(session_id: string): string[];
+```
+
+**总计：~20 个新增方法**。命名 `count*` / `aggregate*` / `query*`。
+
+## safety-net 设计
+
+| 测试文件 | 覆盖目标 | 状态 |
+|---|---|---|
+| `tests/integration/web-stats.integration.test.ts` | GET `/api/stats` 200 + totalEvents/totalSessions/toolUsage/dailyActivity/skillInvocations 字段 | **新增** |
+| `tests/integration/web-trace.integration.test.ts` | GET `/api/trace/:commit` 多分支（无 project / 非 git / 无 note / 有 note）+ sessions[] shape | **新增**（用 tmp git repo 或 mock） |
+| `src/tests/stop-handler-behavior-summary.test.ts` | StopHandler.generateBehaviorSummary 输出字符串断言 | **新增** |
+| `tests/integration/web-analytics.integration.test.ts` | 现有 shape + 加 fixture 数据断言关键字段值 | **增强** |
+| `src/tests/event-operations-aggregates.test.ts` | EventOperations 11 个新方法 | **新增** |
+| `src/tests/session-operations-aggregates.test.ts` | SessionOperations 4 个 | **新增** |
+| `src/tests/skill-operations-counts.test.ts` | SkillOperations 4 个 | **新增** |
+
+## 改造范围
+
+| 文件 | 改动点 | 行数估计 |
+|---|---|---|
+| `core/storage/events.ts` | +11 方法 | +200 |
+| `core/storage/sessions.ts` | +4 方法 | +80 |
+| `core/storage/tasks.ts` | +1 方法 | +20 |
+| `core/storage/skills.ts` | +4 方法 | +60 |
+| `core/storage/sqlite.ts` | facade 转发 | +60 |
+| `daemon/handlers/stop.ts` | 删 db.prepare → facade | -25 / +15 |
+| `web/routes/stats.ts` | 全文重写无 SQL | -50 / +30 |
+| `web/routes/trace.ts` | SQL 段改 facade | -25 / +12 |
+| `cli/commands/trace.ts` | 3 段 SQL 改 facade | -20 / +10 |
+| `web/analytics/drift-detector.ts` | 4 段 SQL 改 facade | -25 / +15 |
+| `web/analytics/weekly-report.ts` | 6 段 SQL 改 facade | -55 / +30 |
+| `web/analytics/anti-pattern-detector.ts` | 2 段 SQL 改 facade | -30 / +12 |
+| **新增测试 7 文件** | safety-net + 聚合单测 | +600 |
+
+**总计：~13 文件改 + 7 文件新增，净 +750 / -230 ≈ 980 行**
+
+## 风险与回滚
+
+| 风险 | 应对 |
+|---|---|
+| GROUP BY/ORDER BY/NULL 处理细节不一致 | safety-net 字段值断言；逐方法 diff 旧 SQL |
+| `LIKE '%error%'` 失败检测被新方法弱化 | weekly-report 失败率单测覆盖原 SQL 3 个 OR 条件 |
+| `date('now', '-7 days')` 与传入 since 字符串语义差异 | 新方法统一接收 ISO 字符串，调用方负责 now() 计算 |
+| 周报 file edit `IN ?` placeholders | `queryFileEditInputs({ tool_names })` 内部展开 |
+| 改动量大致命合并冲突 | 分多 commit，每 commit 独立可 revert |
+
+## 实施顺序（refactor-safe 5 phase）
+
+### Phase 1: safety-net（commit 1）
+1. `tests/integration/web-stats.integration.test.ts` 新增
+2. `tests/integration/web-trace.integration.test.ts` 新增（tmp git repo）
+3. `src/tests/stop-handler-behavior-summary.test.ts` 新增
+4. 增强 `web-analytics.integration.test.ts`
+5. 跑全量确认 baseline 通过
+
+### Phase 2: Operations 新方法（commit 2）
+1. 4 个 Operations 类加方法
+2. 4 个单测文件加 fixture + 断言
+3. sqlite.ts facade 转发
+4. 不删旧 SQL，并行存在
+
+### Phase 3: 替换调用方（每文件独立 commit，共 7 commit）
+1. stats.ts → 跑 stats 集成测试
+2. trace.ts (web) → 跑 trace 集成测试
+3. trace.ts (cli) → 同样断言（如有测试）
+4. stop.ts → 跑 stop handler 单测
+5. drift-detector.ts → 跑 web-analytics
+6. weekly-report.ts → 同上
+7. anti-pattern-detector.ts → 同上
+
+### Phase 4: 收尾（commit 3）
+1. `getDatabase()` 加 jsdoc 警告
+2. `npx tsc --noEmit` + `npm test` 全量
+3. 可选：CLAUDE.md 「常见陷阱」补 1 条
+
+## 命名遵循
+
+- 计数 `count*` / 聚合 `aggregate*` / 列表 `query*`
+- 遵循 H1 已固化的 `aggregateRoutingStats` 等模式

package/docs/design/h3-fallback-removal-spec-20260518-1245.md

@@ -0,0 +1,76 @@
+# H3: 删除 schema.sql inline fallback Spec
+
+## 目标
+消除 `SQLiteBase.initSchema()` 中残缺的 inline fallback，schema.sql 缺失时 fail-fast，杜绝静默降级导致的生产数据写炸。
+
+## 涉及文件
+- `src/core/storage/base.ts`（主改）
+- `package.json`（build script 加 postbuild 校验）
+- `tests/unit/storage/schema-missing.test.ts`（新增）
+- `src/core/storage/index.ts` / `sqlite.ts` 类导出（无需改，构造签名不变）
+
+## 现状分析
+- inline fallback 位置：`src/core/storage/base.ts:61-84`（`initSchema` 的 else 分支，70-82 行）
+- fallback 内容：仅建 `events` 1 张表 + 4 个旧索引（idx_events_session/project/timestamp/distilled）
+- schema.sql 真实：8 张活表（events / sessions / injections / tasks / task_events / routing_events / token_usage / skill_invocations）+ 33 个 CREATE TABLE/INDEX 语句，含 FK ON DELETE CASCADE 与若干复合索引
+- 缺漏表：sessions / injections / tasks / task_events / routing_events / token_usage / skill_invocations 全部缺失 — 一旦走 fallback，所有 routing/skill/task/token 路径首次 prepared statement 即报 `no such table`
+- npm 发布拷贝：`package.json:13` 的 build script —
+  `cp src/core/storage/schema.sql dist/core/storage/schema.sql`（裸 `cp`，无失败检测，且依赖前置 `tsc` 已创建 `dist/core/storage/` 目录）
+
+## 方案选择
+
+| 方案 | 改动量 | 优点 | 缺点 |
+|------|------|------|------|
+| A 删 fallback + fail-fast | 小（~15 行） | 简单；schema 缺失立即抛错 | 单点失败：发布翻车一次即生产 daemon 起不来（但 silent corruption 更糟） |
+| B 嵌入 schema 为 TS 常量 | 中（新增构建步骤 + 1 文件） | 彻底脱离运行时文件依赖；npm 安装零拷贝 | tsc 无 raw-loader；要么手写常量易漂移，要么加 prebuild 脚本生成 `schema-embedded.ts` |
+| C A + postbuild 校验 | 小（~20 行 + 1 行脚本） | 删 fallback 防 silent failure；postbuild 校验防发布事故；不引入构建复杂度 | 仍依赖运行时 fs（开发期问题不大） |
+
+**推荐：C**
+
+理由：B 的常量化听起来最干净，但本项目用 `tsc` 直接编译，引入 codegen 脚本会增加 prebuild 链路（且 schema.sql 改动频率不高，收益不匹配复杂度）。A 解决了核心问题（不再 silent），但发布事故仍可能爆。C 用一行 `test -f` 把发布事故拦截在 `npm run build` 阶段，是性价比最高的组合。
+
+## 设计细节（方案 C）
+
+**改动 1：`src/core/storage/base.ts` `initSchema()` 重写**
+- 删除 70-82 行 inline fallback
+- 删除 `existsSync(schemaPath)` 分支判断；改为：若文件不存在或读取失败，抛 `Error(`[SQLiteStorage] schema.sql not found at ${schemaPath}. ...`)`
+- 错误信息示例：
+  ```
+  [SQLiteStorage] schema.sql not found at /path/to/dist/core/storage/schema.sql.
+  This indicates a broken build/install. Run `npm run build` or reinstall the package.
+  ```
+- 更新文件头注释：删 "或 inline fallback"
+
+**改动 2：`package.json` build script**
+- 在 build 命令末尾追加 `&& test -f dist/core/storage/schema.sql || (echo "[build] FATAL: dist/core/storage/schema.sql missing" && exit 1)`
+- 拷贝命令保留原样（一次失败立即被 test -f 抓出来）
+
+**改动 3：注释清理**
+- `base.ts` 行 6 注释更新为"加载 schema.sql（缺失则抛错）"
+- 文件头注释列表同步
+
+## 测试策略
+
+新增 `tests/unit/storage/schema-missing.test.ts`：
+
+| case | 输入 | 预期 |
+|------|------|------|
+| 1 | 正常环境（schema.sql 存在）| `new SQLiteStorage(tmpDb)` 成功，`sqlite_master` 有 `sessions` 表 |
+| 2 | 临时 rename `dist/core/storage/schema.sql` 或 mock `readFileSync` 抛错 | 构造抛 Error，message 含 `schema.sql not found`；**断言不存在 events 表**（确认未走旧 fallback） |
+
+实现要点：
+- case 2 不能真改 dist/（影响其他测试），用 `vi.mock('node:fs', ...)` 截 `existsSync` 返回 false
+- 现有 `tests/unit/storage/migration-idempotent.test.ts` 不变，验证回归（schema.sql 存在路径仍 idempotent）
+- 跑 `npx vitest run tests/unit/storage --reporter=verbose` + `npx tsc --noEmit`
+
+## 风险与回滚
+
+- **风险 1（开发期）**：开发者本地未跑 `npm run build`，直接 `node src/cli/index.js` 这种从 src 启动？— 实际启动路径都从 `dist/` 走（`bin` 指向 `dist/cli/index.js`），不存在 src 直跑场景；vitest 跑测试用的是源码路径下的 schema.sql（`src/core/storage/schema.sql`），同样存在，无影响
+- **风险 2（首次升级）**：旧版本用户残留 dist 缺 schema.sql？— 升级走 `npm i`，`prebuild` 已 `rm -rf dist`，必然重 build；新 postbuild 校验拦截
+- **回滚**：纯增量改动；revert 单 commit 即可恢复旧 fallback 行为
+
+## 命名遵循
+
+- 测试文件 `schema-missing.test.ts`：kebab-case ✓
+- 不引入新函数/常量；保留 `initSchema()` 私有方法名 ✓
+- 错误信息以 `[SQLiteStorage]` 前缀（与现有 logger 调用一致）✓