@winspan/claude-forge 8.41.0 → 8.51.0

package/docs/design/tasks-list-filter-pagination-spec-20260518-0930.md

@@ -0,0 +1,208 @@
+# Tasks 列表筛选 + 分页 — 设计 Spec
+
+**日期**: 2026-05-18
+**状态**: Draft（待用户 review）
+
+---
+
+## 工作流路径
+
+**hybrid-feature-with-safety**
+
+**理由**：`src/web/routes/` 有 19 个路由文件，`tests/unit/web/` 仅 6 个测试文件，覆盖率约 **32%**（低于 50% 阈值）。实现阶段每个后端改动文件均需配套新增/扩展测试用例。前端为单 HTML 文件无组件测试，route + storage 层必须达到 80% 分支覆盖。
+
+---
+
+## 1. 目标 + 成功标准
+
+让 `GET /api/tasks` 支持完整服务端筛选与分页；前端 tasks 视图新增筛选栏 + 分页组件，URL 同步状态。
+
+### 验收用例
+
+| # | 场景 | 期望 |
+|---|------|------|
+| A1 | `GET /api/tasks?limit=10&offset=0` | `{ items: [...10], total, has_more }` |
+| A2 | `GET /api/tasks?project=/path/foo` | 仅返回该 project_path 的 tasks |
+| A3 | `?project=a&project=b` | 两个项目 OR 关系 |
+| A4 | `?from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z` | start_time 范围过滤 |
+| A5 | `?search=重构` | title LIKE `%重构%` |
+| A6 | `?limit=201` | clamp 到 200 |
+| A7 | 前端选「24h」+ 搜索「build」 | URL: `?range=24h&search=build&page=1`，刷新保留 |
+| A8 | 点「下一页」 | offset 递增，total 不变 |
+
+**非目标**：FTS5 全文检索、status 多选、修改 `/api/tasks/:taskId` 详情接口。
+
+---
+
+## 2. 后端设计
+
+### 2.1 Route 层 `src/web/routes/tasks.ts`
+
+**已有**：`limit`（默认 20）、`session`
+**待加**：`offset`、`project`（多值）、`from`、`to`、`search`，返回结构升级
+
+```
+QueryParams (Zod):
+  limit:   number, default 50, max 200, min 1
+  offset:  number, default 0, min 0
+  project: string | string[]    // 多值
+  from/to: ISO 8601 string, optional
+  search:  string, optional, maxLength 100
+  session: string, optional     // 保留
+```
+
+返回从 `Task[]` 升级为 `{ items, total, has_more }`。**破坏性变更**：内部 dashboard 无外部消费者，可接受。
+
+### 2.2 Storage 层 `src/core/storage/tasks.ts`
+
+**关键挑战**：`tasks` 表无 `project_path` 字段，需 JOIN `sessions` 表。
+
+```sql
+-- 数据查询
+SELECT t.*, s.project_path
+FROM tasks t
+JOIN sessions s ON t.session_id = s.session_id
+WHERE
+  [t.session_id = ?]
+  [AND s.project_path IN (?, ?)]
+  [AND t.start_time >= ?]
+  [AND t.start_time <= ?]
+  [AND t.title LIKE ?]
+ORDER BY t.start_time DESC
+LIMIT ? OFFSET ?;
+
+-- 总数查询：复用相同 WHERE，不带 LIMIT/OFFSET
+SELECT COUNT(*) FROM tasks t JOIN sessions s ON t.session_id = s.session_id WHERE [...];
+```
+
+`TaskRecord` 新增可选字段 `project_path?: string`。
+
+### 2.3 索引评估
+
+| 查询 | 现有 | 是否够 |
+|------|------|--------|
+| `ORDER BY start_time DESC` | `idx_tasks_start_time` | ✅ |
+| `WHERE session_id = ?` | `idx_tasks_session` | ✅ |
+| `WHERE s.project_path IN (...)` | `idx_sessions_project` | ✅ |
+| `WHERE t.title LIKE '%xxx%'` | 无 | ❌ 全表扫描，但数据量 <10k，可接受 |
+| `WHERE start_time BETWEEN ?` | `idx_tasks_start_time` | ✅ 范围扫描 |
+
+**新增**：`CREATE INDEX idx_tasks_start_time_session ON tasks(start_time DESC, session_id)`。
+**不引入 FTS5**（复杂度不值）。
+
+### 2.4 新 Endpoint `GET /api/tasks/projects`
+
+前端项目下拉需要"所有项目"列表：
+
+```sql
+SELECT DISTINCT s.project_path FROM sessions s JOIN tasks t ON t.session_id = s.session_id;
+```
+
+---
+
+## 3. 前端设计
+
+### ⚠️ 重要发现
+
+调研显示前端是**原生 HTML + Vanilla JS**（`src/web/static/index.html` 单文件），不是 CLAUDE.md 描述的 React/Vite。当前页面切换通过 `nav(pageName)` + `id="page-xxx"` div 控制。
+
+> **请用户确认**：(a) spec 按 Vanilla JS 实施（与现状一致）；(b) 顺手迁移到 React（额外大改）；(c) CLAUDE.md 该改技术栈描述
+
+### 3.2 新增 `#page-tasks` 视图
+
+Sidebar 加 "Tasks" 导航项。
+
+```
+page-tasks
+├── .toolbar
+│   ├── #tasks-project-filter   (多选 select)
+│   ├── #tasks-range-filter     (1h/24h/7d/自定义)
+│   ├── #tasks-date-from/to     (datetime-local，自定义时显示)
+│   └── #tasks-search           (300ms 防抖)
+├── <table id="tasks-table">    时间 / 标题 / 项目 / 状态 / 事件数
+└── .pagination-bar
+    ├── "共 N 条，第 X-Y"
+    ├── 每页 [20/50/100]
+    └── [上一页] [下一页]
+```
+
+### 3.3 URL 状态同步
+
+`URLSearchParams` + `history.pushState`：
+
+| URL | 控件 |
+|-----|------|
+| `project` | 多选下拉（可重复） |
+| `range` | 1h/24h/7d/custom |
+| `from`/`to` | 自定义时间 |
+| `search` | 搜索框 |
+| `page` | offset = (page-1) * limit |
+| `size` | 20/50/100 |
+
+### 3.4 防抖
+
+搜索框 `oninput` → setTimeout 300ms → `loadTasks()`，每次键入重置。
+
+---
+
+## 4. 改动文件清单
+
+| 文件 | 改动 | 行数 |
+|------|------|------|
+| `src/core/storage/tasks.ts` | 扩展 filter + COUNT + project_path | +40 |
+| `src/core/storage/schema.sql` | 加复合索引 | +2 |
+| `src/web/routes/tasks.ts` | Zod 解析 + 多参数 + 返回结构 + `/projects` 子路由 | +50 |
+| `src/web/static/index.html` | `#page-tasks` 视图 + JS 函数 + URL 同步 + 防抖 | +200 |
+| `tests/unit/web/routes-tasks.test.ts` | 扩展参数组合用例 | +80 |
+
+---
+
+## 5. 风险点
+
+| 风险 | 缓解 |
+|------|------|
+| tasks 无 project_path，需 JOIN sessions | `TaskRecord` 加可选 `project_path?` |
+| 项目下拉数据来源 | 新增 `/api/tasks/projects` |
+| project_path 太长（绝对路径） | 截断显示最后 2 段，title 属性放完整 |
+| 返回结构破坏性变更 | 搜 index.html 所有 `/api/tasks` 调用点同步更新 |
+| LIKE 性能 | <10k 行可接受，不引入 FTS5 |
+| 前端无组件测试 | 仅 route 集成测试，前端 E2E 手工 |
+
+---
+
+## 6. 测试策略
+
+### 单元测试 `tests/unit/web/routes-tasks.test.ts`
+
+- `project` 单值/多值（OR）
+- `from`/`to` 边界
+- `search` LIKE 匹配（SQLite ASCII 不区分大小写）
+- `limit` clamp
+- `offset` 分页 + `has_more` 准确
+- 返回结构 schema
+- `GET /api/tasks/projects` 去重
+
+### 集成测试
+
+新建 `tests/integration/tasks-filter.test.ts`，真实 SQLite 验证 JOIN + COUNT。
+
+### 前端 E2E
+
+按 A1-A8 在 dashboard 手工验证 + 截图。
+
+---
+
+## 7. 执行步骤（自底向上）
+
+1. `schema.sql` — 加索引 `idx_tasks_start_time_session`
+2. `storage/tasks.ts` — 扩 filter / JOIN / COUNT / project_path
+3. Storage 单元测试
+4. `routes/tasks.ts` — Zod + 多参数 + 返回结构 + `/projects`
+5. Route 单元测试
+6. `index.html` — `#page-tasks` 视图 + JS + URL 同步 + 防抖
+7. `npm test` + `npx tsc --noEmit`
+8. 按 A1-A8 手工验收
+
+---
+
+**Hybrid-feature-with-safety 工作流**：先 safety-net（扩展 routes-tasks 现有测试，锁定旧 `Task[]` 返回行为）→ design → implement → test → review

package/docs/implementation/fix-skills-data-and-set-leak-changelog-20260516-1300.md

@@ -0,0 +1,104 @@
+# Changelog: Official Skills 数据分离 + UserPromptHandler Set 内存泄漏修复
+
+**日期**: 2026-05-16
+**Spec**: `docs/design/fix-skills-data-and-set-leak-spec-20260516-1300.md`
+
+---
+
+## 实际改动文件清单
+
+### 新建文件
+
+| 文件路径 | 行数 | 说明 |
+|----------|------|------|
+| `src/skills/official/official-harness-engineering.md` | 91 | Harness Engineering 方法论 |
+| `src/skills/official/official-spec-driven-design.md` | 28 | Spec-Driven Design |
+| `src/skills/official/official-architecture-decision.md` | 22 | ADR 模板（截断版，与原始 content 一致）|
+| `src/skills/official/official-api-design.md` | 19 | API 设计规范（截断版）|
+| `src/skills/official/official-db-schema-design.md` | 19 | DB Schema 设计（截断版）|
+| `src/skills/official/official-pr-review.md` | 32 | PR 审查清单（截断版）|
+| `src/skills/official/official-debug.md` | 18 | 调试工作流（截断版）|
+| `src/skills/official/official-performance-optimization.md` | 30 | 性能优化 |
+| `src/skills/official/official-security-hardening.md` | 27 | 安全加固（截断版）|
+| `src/skills/official/official-release-checklist.md` | 30 | 发布清单 |
+| `src/skills/official/official-doc-driven.md` | 28 | 文档驱动开发 |
+| `src/skills/official/planning-with-files.md` | 35 | Manus 风格任务规划（截断版）|
+| `src/skills/official/code-simplifier.md` | 17 | 代码简化（截断版）|
+| `src/skills/official/find-skills.md` | 24 | 技能发现（截断版）|
+| `src/skills/official/webapp-testing.md` | 12 | Web 应用测试（截断版）|
+| `src/skills/official/ui-ux-pro-max.md` | 19 | UI/UX 设计工具（截断版）|
+| `src/skills/official/official-bmad.md` | 90 | BMAD 方法论 |
+| `tests/unit/skills/official-skills-loader.test.ts` | 113 | loadOfficialSkills 单元测试（7 个 case）|
+
+### 修改文件
+
+| 文件路径 | 改动 | 说明 |
+|----------|------|------|
+| `src/skills/official-skills.ts` | -700行 +73行 | 删除 OFFICIAL_SKILLS 数组；保留 OfficialSkill 接口和 OFFICIAL_SKILL_KEYWORDS；新增 loadOfficialSkills(builtinDir) |
+| `src/skills/registry.ts` | +30行 | 新增 resolveBuiltinDir(); scan() 第 1 段改用 loadOfficialSkills; import 更新 |
+| `src/cli/commands/skills.ts` | +7行 | 移除 OFFICIAL_SKILLS import；新增 resolveBuiltinDir(); syncSkills 改用 loadOfficialSkills |
+| `src/daemon/handlers/user-prompt.ts` | +40行 | Set 改 Map<string,number>; 新增 MAX_INJECTION_KEYS=1000; hasInjected/markInjected 私有方法; clearSession 公共方法 |
+| `src/daemon/handlers/stop.ts` | +15行 | import UserPromptHandler 类型; 构造函数增加可选参数 userPromptHandler; Step 5 调用 clearSession |
+| `src/daemon/index.ts` | +5行 | 将 userPromptHandler 实例传入 StopHandler 构造函数 |
+| `package.json` | +1行 | build 脚本追加 `mkdir -p dist/skills/official && cp src/skills/official/*.md dist/skills/official/` |
+| `tests/unit/skill-registry.test.ts` | +2行 | 断言数量从 >= 16 改为 >= 17（两处） |
+| `tests/unit/handlers.test.ts` | +92行 | 新增 3 个 UserPromptHandler 测试 case |
+
+---
+
+## 与 Spec 的偏差
+
+### 偏差 1：Skill 数量是 17，不是 19
+Spec 说"共 19 个 skill"，但 `OFFICIAL_SKILLS` 数组实际只有 17 个条目（缺少 `official-tdd` 和 `official-refactor`，这两个仅在 `OFFICIAL_SKILL_KEYWORDS` 中有 keyword 映射但没有对应的 skill 定义）。实际创建了 17 个 `.md` 文件。测试断言改为 `>= 17`。
+
+### 偏差 2：部分 skill 内容截断
+原始 `OFFICIAL_SKILLS` 数组中有 11 个 skill 的 `content` 字段以 `\`` 结尾（截断的 template literal）。这是源码的现有状态（非本次引入）。`.md` 文件完整保留了这些截断内容，与原有行为一致。这些截断是原始数据的一部分，不影响 skill 加载逻辑。
+
+### 偏差 3：registry.ts 中 skill 的 path 字段构造
+Spec 建议使用 `resolveBuiltinDir() + '/' + officialSkill.name + '.md'` 作为路径。实际实现中每次调用 `resolveBuiltinDir()` 会重新计算，考虑到这是纯计算无副作用，对性能无影响。若有性能顾虑可缓存该值（已注释在代码中作为 TODO）。
+
+### 偏差 4：loadOfficialSkills content 字段包含完整文件（含 frontmatter）
+Spec 中未明确 `content` 字段是否包含 frontmatter。registry 的现有用户 skill 逻辑（`body.trim()`）只包含 body。为保持与原有 OFFICIAL_SKILLS 行为一致（原 content 字段包含 frontmatter），`loadOfficialSkills` 返回的 `content` 字段设为完整文件内容（`raw`），而非仅 body。这样 skill 注入时内容与之前完全一致。
+
+---
+
+## 测试结果
+
+### 执行的测试
+```
+npx vitest run tests/unit/skill-registry.test.ts --reporter=verbose
+npx vitest run tests/unit/skills/ --reporter=verbose
+npx vitest run tests/unit/handlers.test.ts --reporter=verbose
+npx tsc --noEmit
+npm test -- --reporter=dot
+```
+
+### 结果汇总
+
+| 测试文件 | 状态 | 测试数 |
+|----------|------|--------|
+| `tests/unit/skill-registry.test.ts` | 全部通过 | 6/6 |
+| `tests/unit/skills/registry-multiformat.test.ts` | 全部通过 | 27/27 |
+| `tests/unit/skills/official-skills-loader.test.ts` | 全部通过 | 7/7 |
+| `tests/unit/handlers.test.ts` | 全部通过 | 7/7（新增 3 个）|
+| `tests/unit/skills/invocation-guard-ttl.test.ts` | 全部通过 | — |
+| TypeScript (`tsc --noEmit`) | 无错误 | — |
+| 全量测试 (`npm test`) | 291/294 通过 | 2 文件失败 |
+
+### 预存在的失败（与本次改动无关）
+- `tests/unit/web/routes-tasks.test.ts`（2 个 case 失败）：UUID 格式验证错误，与 storage 层有关
+- `tests/unit/storage/sqlite-refactor-harness.test.ts`（1 个 case 失败）：`linkEventToTask` 相关，与 storage 层有关
+
+注：这两个测试文件在本次改动前就已失败（baseline 状态：3 文件 / 10 个 case 失败；本次改动后：2 文件 / 3 个 case 失败，即我们的改动无意中修复了 skill-registry 相关的计数断言问题）。
+
+---
+
+## 已知风险 / TODO
+
+1. **content 字段含 frontmatter**：registry 的用户 skill 加载使用 `body.trim()`（不含 frontmatter），而 official skill 的 `content` 现在是完整文件内容（含 frontmatter）。两者行为不一致，但与原始 OFFICIAL_SKILLS 数组保持了向后兼容。如需统一，可在后续 PR 中对齐。
+
+2. **部分 skill 内容截断**：11 个 skill 的 body 内容被截断（原始代码如此）。这不是本次引入的问题。如需完整内容，需要重新补全对应的 `.md` 文件。
+
+3. **syncSkills 命令的 version 比较**：`skills sync` 命令从 `.md` frontmatter 读取版本号做比较。对于截断的 skill，version 字段在 frontmatter 中完整保留，此功能不受影响。
+
+4. **resolveBuiltinDir 每次重新计算**：scan() 中多次调用 resolveBuiltinDir()，可以在 scan 开始时缓存到局部变量（低优先级优化）。

package/docs/implementation/h1-storage-aggregation-changelog-20260518-1121.md

@@ -0,0 +1,82 @@
+# H1 实施 Changelog
+
+**Date**: 2026-05-18 11:21
+**Spec**: `docs/design/h1-storage-aggregation-spec-20260518-1121.md`
+**Status**: 完成
+
+## 完成清单
+
+- [x] Storage 新方法（7 个）：
+  - `aggregateRoutingStats({ since_ts, project_path? })` → `RoutingOperations`
+  - `aggregateRoutingTrendByDay({ since_ts })` → `RoutingOperations`
+  - `aggregateSkillInvocationsBySkill({ since, limit? })` → `SkillOperations`
+  - `getTask(taskId)` → `TaskOperations`
+  - `queryEventsByTaskId(taskId, opts?)` → `TaskOperations`
+  - `queryInjectionsByTaskId(taskId)` → `TaskOperations`
+  - `querySkillInvocationsByTaskWindow(taskId, now_ms?)` → `TaskOperations`
+- [x] sqlite.ts facade 转发已加（7 个方法）
+- [x] 索引新增：`idx_routing_events_type_ts` (schema.sql + base.ts runMigrations 同步)
+- [x] Storage 单元测试（3 文件）：
+  - `tests/unit/storage/routing-aggregates.test.ts`
+  - `tests/unit/storage/skills-aggregates.test.ts`
+  - `tests/unit/storage/tasks-getById-aggregates.test.ts`
+- [x] Routes 改造（3 文件）：
+  - `src/web/routes/rules.ts` — hit-rate 改用 `aggregateRoutingStats` + `aggregateSkillInvocationsBySkill`
+  - `src/web/routes/skill-stats.ts` — 5 个 endpoint 全部下沉到 SQL 聚合
+  - `src/web/routes/tasks.ts` — `/:taskId` PK 直查 + JOIN
+- [x] 路由测试新增：`tests/unit/web/routes-rules.test.ts`（之前缺口）
+
+## 关键代码定位
+
+### Storage 新方法
+- `src/core/storage/routing.ts` — `aggregateRoutingStats`、`aggregateRoutingTrendByDay`（4 条独立 prepared statement 走索引；trend 用 `strftime('%Y-%m-%d', ts/1000, 'unixepoch')`）
+- `src/core/storage/skills.ts` — `aggregateSkillInvocationsBySkill`（按 `total DESC`）
+- `src/core/storage/tasks.ts` — `getTask` / `queryEventsByTaskId` / `queryInjectionsByTaskId` / `querySkillInvocationsByTaskWindow`（后者用 `task_events` JOIN + `tasks.start_time/end_time` 转 ms 做窗口过滤）
+- `src/core/storage/sqlite.ts` — facade 转发 7 个方法
+- `src/core/storage/schema.sql` 末尾 + `src/core/storage/base.ts` runMigrations — `idx_routing_events_type_ts ON routing_events(routed_to_type, ts DESC)`
+
+### Route 改造点
+- `src/web/routes/rules.ts` — `queryRoutingEvents{limit:100000}` + `querySkillInvocations{limit:100000}` JS reduce → `aggregateRoutingStats` + `aggregateSkillInvocationsBySkill`
+- `src/web/routes/skill-stats.ts:16` — `/distribution`：`agg.by_type` + 三桶兜底
+- `src/web/routes/skill-stats.ts:33` — `/frequency`：`agg.by_skill_routed.map(...)`
+- `src/web/routes/skill-stats.ts:43` — `/trend`：`aggregateRoutingTrendByDay` + JS skillRate 计算
+- `src/web/routes/skill-stats.ts:59` — `/invocations`：`aggregateSkillInvocationsBySkill`，`total` 改为 sum 行 total
+- `src/web/routes/skill-stats.ts:76` — `/api/routing/stats`：`agg.obeyed/total/by_agent`
+- `src/web/routes/tasks.ts:59` — `/:taskId`：`getTask` + `queryEventsByTaskId` + `queryInjectionsByTaskId` + `querySkillInvocationsByTaskWindow` 取代旧四段全表扫
+
+## 测试结果
+
+| 维度 | 数值 |
+|------|------|
+| storage + web unit | 171 通过 / 1 失败（pre-existing） |
+| 全量 `npm test` | **417 通过 / 1 失败 / 418 总** |
+| `npx tsc --noEmit` | **0 errors** |
+
+### Pre-existing failure（与 H1 无关，main 分支既有）
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > Task Operations > linkEventToTask associates events with tasks`
+  - 报错：`Invalid event data: ... event_id Invalid uuid`
+  - 原因：测试中传入的 `event_id` 不是 UUID 格式，与 `events.ts:73` 的 zod 校验不兼容
+  - 在 main 分支同样 fail，**未在本次任务范围**，未修
+
+## 超出 spec 的改动
+
+无。所有改动均严格按 spec 第 3 节执行。响应字段结构未变更（前端 React 组件契约保持）：
+- `/distribution` → `{ windowHours, distribution: [{type, count}] }` ✓
+- `/frequency` → `{ windowHours, frequency: [{name, count}] }` ✓
+- `/trend` → `{ windowHours, trend: [{day, skillRate}] }` ✓
+- `/invocations` → `{ days, total, invocations: [{skill_id, total, success, failed}] }` ✓
+- `/api/routing/stats` → `{ days, total, agentCalls, noAgent, agentRate, byAgent }` ✓
+- `/api/tasks/:taskId` → `{ task, userPrompts, injections, timeline, skillInvocations, artifacts }` ✓
+
+注：`/invocations` 的 `total` 字段语义不变（旧实现是 `invocations.length` = 原始记录数；新实现是 `sum(rows.total)` = 同样的原始记录数，因 GROUP BY skill_id 后各 group total 之和等于总行数）。
+
+## 已知问题
+
+- **Pre-existing**：`sqlite-refactor-harness.test.ts > linkEventToTask` — 与 H1 无关，main 分支同样失败。
+- 无其它已知问题。
+
+## 回滚提示
+
+纯增量改动。如需回滚：
+- revert `src/web/routes/{rules,skill-stats,tasks}.ts` 即可恢复旧行为
+- storage 新方法和索引保留无害（无人调用即无副作用）

package/docs/implementation/h2-final-changelog-20260518-1530.md

@@ -0,0 +1,61 @@
+# H2 完整实施 Changelog
+
+**Date**: 2026-05-18
+**Spec**: `docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md`
+**Status**: 全 4 Phase 完成
+**Workflow**: refactor-safe（safety-net → 新方法 → 替换 → 收尾）
+
+## 四阶段 commit 索引
+
+| Phase | Commit | 内容 |
+|---|---|---|
+| 1 | `0b494ed` | safety-net 17 test cases（web-stats / web-trace / stop-handler / web-analytics 增强） |
+| 2 | （上一 commit） | 20 个 Operations 新方法 + 44 个单测 + facade 转发 |
+| 3 | `bf3eb39` | 7 个调用方文件替换 db.prepare() → facade |
+| 4 | （本 commit） | getDatabase jsdoc 警告 + 总 changelog |
+
+## 累计影响
+
+- **改动 13 个 src 文件，新增 12 个测试文件**
+- **消除 27 处越权 SQL 直写**（spec 调研时 25 处 + 主线程封闭性扫描补 cli/commands/trace.ts 3 处）
+- **新增 20 个 Operations 方法**：EventOperations × 11 + SessionOperations × 4 + TaskOperations × 1 + SkillOperations × 4
+- **新增 61 个测试用例**：safety-net 17 + Operations 单测 44
+
+## 命名固化（H1 → H2 一致）
+
+- `aggregate*` 聚合（GROUP BY 类）
+- `count*` 计数
+- `query*` 列表查询
+- `get*` 单条查询
+
+## 关键决策
+
+1. **getDatabase 保留 public**（不改 protected）：架构非继承关系，protected 收益小风险大；改用 jsdoc `@internal` 标注 + CLAUDE.md 工作流提醒
+2. **SQL 行为零变更**：所有 SQL 直接搬入 Operations，不做"优化"，保证 safety-net 测试零回归
+3. **`LIKE '%error%'` 失败检测保留原 3 个 OR 条件**：与生产匹配
+4. **Phase 2 偏差**：`aggregateToolUsage` 缺 `until` 参数 → Phase 3 改用 `queryEventsByTimeRange + 内存聚合` 兜底，保留 `[since, until)` 语义
+
+## 测试结果（最终）
+
+- safety-net 集成测试：17/17 ✓
+- Operations 单测：44/44 ✓
+- 现有回归：541/542 通过
+- **唯一失败**：pre-existing `linkEventToTask` (Zod UUID 校验，与 H2 无关)
+- `npx tsc --noEmit`: 0 errors
+
+## 残留 `db.prepare` 检查
+
+```bash
+$ grep -rn "db\.prepare" src/web/ src/cli/commands/trace.ts src/daemon/handlers/ --include="*.ts" | grep -v ".test."
+src/web/routes/stats.ts:7: * H2 Phase 3: 替换原 db.prepare 直写 SQL 为 SQLiteStorage facade 聚合方法。
+src/web/routes/trace.ts:95:    // H2 Phase 3: 改用 facade 聚合方法，消除 db.prepare 直写。
+src/daemon/handlers/stop.ts:151:      // H2 Phase 3: 改用 facade 聚合方法，消除 db.prepare 直写。
+```
+
+**3 处均为注释**，无 SQL 直写。
+
+## 后续 follow-up
+
+- **可选**：补完 `aggregateToolUsage` 的 `until` 参数支持，weekly-report 改回单条 SQL
+- **可选**：ESLint 规则禁止 `web/routes/` `web/analytics/` `daemon/handlers/` import storage 后调用 `getDatabase()`
+- **不建议**：把 `getDatabase` 改 protected（架构非继承）

package/docs/implementation/h2-phase1-safety-net-changelog-20260518-1450.md

@@ -0,0 +1,70 @@
+# H2 Phase 1 safety-net Changelog
+
+**Date**: 2026-05-18 14:50
+**Spec**: docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md
+**Status**: Phase 1 完成（Phase 2-4 待后续）
+
+## 完成清单
+
+- [x] web-stats 集成测试 (`tests/integration/web-stats.integration.test.ts`, 4 cases)
+- [x] web-trace 集成测试 (`tests/integration/web-trace.integration.test.ts`, 6 cases — 全分支覆盖)
+- [x] stop-handler-behavior-summary 单测 (`tests/unit/daemon/stop-handler-behavior-summary.test.ts`, 5 cases)
+- [x] web-analytics 集成测试增强 (+2 value-level cases)
+
+## 关键代码定位
+
+| 测试文件 | 行号 | 内容 |
+|---|---|---|
+| `tests/integration/web-stats.integration.test.ts:38` | empty database 200 shape |
+| `tests/integration/web-stats.integration.test.ts:60` | totalEvents/totalSessions/toolUsage 聚合 |
+| `tests/integration/web-stats.integration.test.ts:83` | dailyActivity 字段形状 |
+| `tests/integration/web-stats.integration.test.ts:103` | skillInvocations 计数 |
+| `tests/integration/web-trace.integration.test.ts:84-118` | 4 个 4xx 错误分支 |
+| `tests/integration/web-trace.integration.test.ts:120-130` | 200 + 空 sessions[]（无 git note）|
+| `tests/integration/web-trace.integration.test.ts:132-167` | 200 + 完整 session 详情（含 event_breakdown）|
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:69` | 无事件时不附加 summary |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:82` | tool-only summary |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:110` | Agent 委托计数 + agent 名 |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:141` | skill 调用计数 |
+| `tests/unit/daemon/stop-handler-behavior-summary.test.ts:169` | session 隔离（不串扰）|
+| `tests/integration/web-analytics.integration.test.ts:92` | weekly report value 断言 |
+| `tests/integration/web-analytics.integration.test.ts:107` | insights summary.total = patterns.length |
+
+## 测试结果
+
+- **新增/增强 safety-net 测试**: 17 passed (4 stats + 6 trace + 5 stop + 2 analytics 增强)
+- **跨 Phase 1 范围全量**:
+  - `tests/integration/` + `tests/unit/daemon/`: 33 / 33 passed
+- **tsc**: 0 errors
+- **npm test 全量**: 497 / 498 passed (1 failed = pre-existing `linkEventToTask`)
+
+## 实施决策
+
+1. **trace 测试覆盖方案**：采用方案 A（tmp git repo）。在 `os.tmpdir()` 用 `execFileSync('git', ...)` 创建真实仓库 + 两次 commit + `git notes add`，覆盖：
+   - 缺 `?project` query → 400
+   - 相对路径 → 400
+   - 非 git 目录 → 400
+   - commit 不存在 → 404
+   - HEAD 有 commit 但无 note → 200 + 空 sessions[]
+   - 有 forge-session note + storage 有对应 events → 200 + 完整 session 详情（event_breakdown 等）
+   - **覆盖度高于 spec 最低要求**（spec 只要求 commit 不存在 4xx + 无 note 空 sessions 两条），实际跑得快且稳定。
+2. **stop-handler 测试路径调整**：spec 写 `src/tests/stop-handler-behavior-summary.test.ts`，但 `vitest.config.ts` 只包含 `tests/unit/**` 与 `tests/integration/**`。如放到 `src/tests/` 会被 collect 排除导致永远不跑。改放到 `tests/unit/daemon/stop-handler-behavior-summary.test.ts` 以确保实际生效，已在测试文件顶部 NOTE 注释中说明决策。
+3. **`generateBehaviorSummary` 私有方法访问**：经由 `handle()` 入口 + mock `ResumeManager.save` 捕获最终 resume content 进行断言。比反射访问私有方法更接近生产实际路径，且更稳健。
+4. **web-analytics 增强保守原则**：只加 2 个新 case（weekly value + insights consistency），不重写既有 shape 断言。所有原 case 仍保留并通过。
+5. **fixture 时间戳策略**：weekly-report 按 ISO week 范围过滤事件，所以 fixture 用 `new Date().toISOString()`（当下时间）确保进入 `weekOffset: 0` 窗口；stats endpoint 用 `date('now', '-7 days')`，同样满足。
+
+## 待 Phase 2 处理
+
+下一步 Phase 2（新增 ~20 个 Operations 方法）的提示：
+
+- Phase 2 应在 `src/core/storage/{events,sessions,tasks,skills}.ts` 加方法，**不删旧 SQL**，并行存在。
+- Phase 2 同时增加 4 个新单测文件：`tests/unit/storage/{event,session,skill}-operations-aggregates.test.ts`（spec 表 116 行所列）。
+- Phase 3 才会替换调用方（每文件 1 commit），届时本 Phase 1 的 safety-net 会兜底回归。
+- Phase 4 给 `getDatabase()` 加 jsdoc `@internal` 警告。
+- 改造涉及 `daemon/handlers/stop.ts` 时，本次新加的 `stop-handler-behavior-summary.test.ts` 5 个 case 是关键回归依据。
+- trace 测试包含一次真实 `git init`，单测耗时 ~600ms，未来 Phase 2/3 增加新测试时不必再做 git 操作。
+
+## 已知问题
+
+- **pre-existing 失败**：`SQLiteStorage - Characterization Tests (Pre-Refactor) > Task Operations > linkEventToTask associates events with tasks` —— Zod uuid 校验失败，与本 Phase 1 改动无关，按纪律不修。
+- **未覆盖**：`cli/commands/trace.ts` 3 段 SQL 暂无对应集成测试（spec 第 71 行已标注"可补"）。Phase 2/3 替换 CLI trace 时可考虑加 CLI smoke test，或先依赖 web-trace 同模式断言间接保护。

package/docs/implementation/h2-phase2-operations-changelog-20260518-1450.md

@@ -0,0 +1,120 @@
+# H2 Phase 2 Operations 新方法 Changelog
+
+**Date**: 2026-05-18 14:50 (Phase 2)
+**Spec**: docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md
+**Status**: Phase 2 完成（Phase 3 待替换调用方）
+
+## 完成清单
+
+- [x] EventOperations 11 方法（events.ts）
+- [x] SessionOperations 4 方法（sessions.ts）
+- [x] TaskOperations 1 方法（tasks.ts）
+- [x] SkillOperations 4 方法（skills.ts）
+- [x] sqlite.ts facade 转发（20 个方法）
+- [x] 4 文件单测（44 个 case 全过）
+- [x] tsc 通过 0 errors
+- [x] 旧 SQL 并行存在（Phase 3 才替换）
+
+## 新增方法清单
+
+### EventOperations（src/core/storage/events.ts:179-358）
+
+| 方法 | SQL 来源 |
+|---|---|
+| `countAllEvents()` | stats.ts:13 |
+| `aggregateToolUsage({ since?, limit?, hook_type? })` | stats.ts:17-21 + weekly-report.ts:214-222 |
+| `aggregateDailyEventCounts({ since, until? })` | stats.ts:28-33 |
+| `aggregateHookTypeBySession(session_id)` | trace.ts:106-109 + cli/trace.ts:115 |
+| `aggregateAgentTypeBySession(session_id)` | trace.ts:111-116 + cli/trace.ts:124 + stop.ts:163-168 |
+| `aggregateToolUsageBySession(session_id)` | stop.ts:154-158 |
+| `countActiveDays({ since, until? })` | drift-detector.ts:154-157 |
+| `aggregateOverviewByRange({ since, until })` | weekly-report.ts:100-109 |
+| `queryDistinctProjects({ since, until })` | weekly-report.ts:111-116 |
+| `aggregateToolFailureRate({ since, until })` | weekly-report.ts:228-244（保留 3 OR LIKE 分支） |
+| `queryFileEditInputs({ since, until, tool_names })` | weekly-report.ts:261-268（内部 IN 展开） |
+| `queryEventsByTimeRange({ since, until? })` | anti-pattern-detector.ts:83-86 |
+
+### SessionOperations（src/core/storage/sessions.ts:107-178）
+
+| 方法 | SQL 来源 |
+|---|---|
+| `countAllSessions()` | stats.ts:14 |
+| `aggregateDailySessionCounts({ since, until? })` | stats.ts:35-40 |
+| `querySessionsByTimeRange({ since, until? })` | anti-pattern-detector.ts:104-114 |
+| `countSessionsByRange({ since, until? })` | drift-detector.ts:185-187 |
+
+### TaskOperations（src/core/storage/tasks.ts:120-131）
+
+| 方法 | SQL 来源 |
+|---|---|
+| `countTasksByRange({ since, until? })` | drift-detector.ts:190-192 + weekly-report.ts:118-122 |
+
+### SkillOperations（src/core/storage/skills.ts:203-232）
+
+| 方法 | SQL 来源 |
+|---|---|
+| `countAllSkillInvocations()` | stats.ts:50 |
+| `countSkillInvocationsBySession(session_id)` | stop.ts:176-178 |
+| `countDistinctSkillsSince(since_ms)` | drift-detector.ts:125-128 |
+| `queryDistinctSkillIdsBySession(session_id)` | trace.ts:118-120 + cli/trace.ts:135 |
+
+### sqlite.ts facade（src/core/storage/sqlite.ts:94-160）
+
+20 个方法签名严格按 spec，全部 `delegate to this.events / this.sessions / this.tasks / this.skills`。
+
+## 关键代码定位
+
+- `src/core/storage/events.ts:179-358` — EventOperations 11 新方法
+- `src/core/storage/sessions.ts:107-178` — SessionOperations 4 新方法
+- `src/core/storage/tasks.ts:120-131` — TaskOperations countTasksByRange
+- `src/core/storage/skills.ts:203-232` — SkillOperations 4 新方法
+- `src/core/storage/sqlite.ts:94-160` — facade 转发段
+
+## 测试结果
+
+- 新增单测: **44 passed / 44**
+  - event-operations-aggregates.test.ts: 23 tests
+  - session-operations-aggregates.test.ts: 9 tests
+  - task-operations-counts.test.ts: 3 tests
+  - skill-operations-counts.test.ts: 9 tests
+- 旧 storage 测试回归: 通过（除 pre-existing failure）
+- tsc: **0 errors**
+- npm test: **541 passed / 542**（仅 pre-existing `linkEventToTask` 失败）
+
+## 实施决策
+
+1. **LIKE '%error%' 失败检测保持原 SQL 三个 OR 分支**
+   - `tool_output LIKE '%"error"%' OR LIKE '%"is_error":true%' OR LIKE '%"isError":true%'`
+   - 测试覆盖三种 tool_output JSON 形态，确认全部命中
+
+2. **时间区间统一 `[since, until)` 半开半闭语义**
+   - 调用方负责 ISO 字符串构造（`new Date(since).toISOString()`）
+   - until 一律 `<`（与 weekly-report.ts 原 `start_time < ?` 一致）
+   - 与 stats.ts 原 `date('now', '-7 days')` 语义不同：新方法不再隐含 now()，调用方计算
+
+3. **`queryFileEditInputs` 内部展开 placeholders**
+   - tool_names 通过参数注入，避免外部拼 SQL
+   - 空 list 直接返回空数组（避免 `IN ()` SQL 错误）
+
+4. **`aggregateToolUsage` 合并 stats / weekly-report 两个用例**
+   - 通过 `hook_type` 可选过滤 + `since` 可选过滤兼顾两种调用
+   - `tool_name IS NOT NULL AND tool_name != ''` 始终生效（stats.ts 原行为）
+
+5. **`aggregateAgentTypeBySession` 与 `aggregateToolUsageBySession` 分离**
+   - 前者 `tool_name IN ('Agent','Task')` + json_extract subagent_type（stop.ts:163 / trace.ts:111）
+   - 后者纯 `tool_name IS NOT NULL`（stop.ts:154）
+   - 两段语义不同，分别封装
+
+## 待 Phase 3 处理
+
+- 替换 src/web/routes/stats.ts（5 段 SQL）
+- 替换 src/web/routes/trace.ts（3 段 SQL）
+- 替换 src/cli/commands/trace.ts（3 段 SQL）
+- 替换 src/daemon/handlers/stop.ts:154-178（3 段 SQL）
+- 替换 src/web/analytics/drift-detector.ts（4 段 SQL）
+- 替换 src/web/analytics/weekly-report.ts（6 段 SQL）
+- 替换 src/web/analytics/anti-pattern-detector.ts（2 段 SQL）
+
+## 已知问题
+
+- `tests/unit/storage/sqlite-refactor-harness.test.ts > linkEventToTask` pre-existing 失败（与 Phase 2 改动无关，event_id 未传 UUID 导致 zod schema 拒收）