@winspan/claude-forge 8.39.0 → 8.50.6

package/docs/design/refactor-phase2-spec-20260515-1700.md

@@ -0,0 +1,424 @@
+# claude-forge 渐进式重构 - 第 2 迭代实施方案
+
+**版本**: v1.0  
+**创建时间**: 2026-05-15 17:00  
+**迭代周期**: 2 周（10 个工作日）  
+**前置条件**: 第 1 迭代已完成（P0 安全漏洞修复 + P1 基础设施改进 + 测试覆盖率 40%）
+
+---
+
+## 1. 目标与范围
+
+### 1.1 迭代目标
+
+**主要目标**：
+1. 消除代码重复，提升可维护性（P1-3, P1-4, P1-5）
+2. 统一命名风格，提升代码可读性（P1-6, P1-7）
+3. 优化数据库查询性能（P2-6, P2-7）
+4. 防护内存泄漏风险（P2-8）
+5. 提升测试覆盖率至 60%
+
+**量化指标**：
+- 代码重复率：从 ~15% 降至 <8%
+- 测试覆盖率：从 40% 提升至 60%
+- 数据库查询性能：N+1 查询减少 80%
+- 内存泄漏风险：InvocationGuard 增加 TTL 机制
+
+### 1.2 包含的问题
+
+**P1 级问题**（必须完成）：
+- ✅ P1-3: 时间戳归一化逻辑重复（3 处）
+- ✅ P1-4: 错误日志模式重复（5 处）
+- ✅ P1-5: Session ID 截断逻辑重复（4 处）
+- ✅ P1-6: 文件命名风格混乱（kebab-case vs camelCase）
+- ✅ P1-7: 函数命名不一致（get vs query vs list）
+
+**P2 级问题**（部分完成）：
+- ✅ P2-6: 数据库查询未使用预编译语句（部分文件）
+- ✅ P2-7: 缺少连接池（SQLite WAL 模式优化）
+- ✅ P2-8: 内存泄漏风险（InvocationGuard 无 TTL）
+
+### 1.3 不包含的问题
+
+**留到第 3 迭代**：
+- P2-1: 类型断言滥用（需要更大范围的类型系统重构）
+- P2-2: 错误处理不一致（需要统一错误处理策略）
+- P2-3: 配置验证缺失（需要 Zod schema 设计）
+- P2-4: 日志级别混乱（需要日志策略重新设计）
+- P2-5: 魔法数字（需要常量提取策略）
+- P2-9: 事件监听器泄漏（需要生命周期管理重构）
+
+---
+
+## 2. 改动文件清单
+
+### 2.1 新增文件（6 个）
+
+| 文件路径 | 用途 | 预计行数 |
+|---------|------|---------|
+| `src/core/utils/time.ts` | 时间戳归一化工具 | 50 |
+| `src/core/utils/session.ts` | Session ID 处理工具 | 40 |
+| `src/core/utils/format.ts` | 通用格式化工具（日志、错误） | 80 |
+| `tests/unit/utils/time.test.ts` | 时间工具测试 | 100 |
+| `tests/unit/utils/session.test.ts` | Session 工具测试 | 80 |
+| `tests/unit/utils/format.test.ts` | 格式化工具测试 | 120 |
+
+### 2.2 修改文件（18 个）
+
+| 文件路径 | 改动类型 | 预计改动行数 | 改动原因 |
+|---------|---------|-------------|---------|
+| `src/daemon/event-parser.ts` | 重构 | 20 | 使用 `normalizeTimestamp` |
+| `src/daemon/handlers/stop.ts` | 重构 | 30 | 使用 `truncateSessionId` + `formatError` |
+| `src/daemon/handlers/user-prompt.ts` | 重构 | 25 | 使用 `truncateSessionId` |
+| `src/daemon/handlers/history-exporter.ts` | 重构 | 20 | 使用 `normalizeTimestamp` |
+| `src/daemon/services/task-segmenter.ts` | 重构 | 30 | 使用 `normalizeTimestamp` |
+| `src/claudemd/resume-manager.ts` | 重构 | 25 | 使用 `normalizeTimestamp` + `truncateSessionId` |
+| `src/core/storage/events.ts` | 优化 | 40 | 预编译语句 + 批量插入 |
+| `src/core/storage/sessions.ts` | 优化 | 30 | 预编译语句优化 |
+| `src/core/storage/routing.ts` | 优化 | 35 | 预编译语句 + 索引优化 |
+| `src/core/storage/tasks.ts` | 优化 | 25 | 预编译语句优化 |
+| `src/core/storage/injections.ts` | 优化 | 20 | 预编译语句优化 |
+| `src/core/storage/token-usage.ts` | 优化 | 20 | 预编译语句优化 |
+| `src/core/storage/skills.ts` | 优化 | 30 | 预编译语句 + N+1 查询优化 |
+| `src/core/storage/base.ts` | 优化 | 40 | WAL 模式优化 + 连接池配置 |
+| `src/skills/invocation-guard.ts` | 增强 | 50 | 增加 TTL 机制 + 自动清理 |
+| `src/daemon/router.ts` | 重构 | 15 | 使用 `formatError` |
+| `src/daemon/server.ts` | 重构 | 20 | 使用 `formatError` |
+| `src/web/server.ts` | 重构 | 15 | 使用 `formatError` |
+
+### 2.3 重命名文件（0 个）
+
+**说明**：文件命名风格混乱问题（P1-6）通过代码审查和新文件命名规范解决，不涉及现有文件重命名（避免 git 历史混乱）。
+
+---
+
+## 3. 实施步骤
+
+### Step 1: 抽取重复逻辑（3 天）
+
+**目标**：消除时间戳、日志、ID 截断的重复代码。
+
+#### 3.1.1 创建工具函数
+
+**文件**: `src/core/utils/time.ts`
+
+```typescript
+/**
+ * 时间戳归一化工具
+ * 
+ * 统一处理 ISO 8601 时间戳的 Z 后缀问题，确保所有时间戳都带 Z。
+ */
+
+/**
+ * 归一化时间戳，确保带 Z 后缀
+ */
+export function normalizeTimestamp(timestamp: string): string {
+  if (!timestamp) return new Date().toISOString();
+  return timestamp.endsWith('Z') ? timestamp : timestamp + 'Z';
+}
+
+/**
+ * 将时间戳转换为 Unix 毫秒数
+ */
+export function timestampToMs(timestamp: string): number {
+  return new Date(normalizeTimestamp(timestamp)).getTime();
+}
+
+/**
+ * 计算两个时间戳之间的毫秒差
+ */
+export function timeDiff(start: string, end: string): number {
+  return timestampToMs(end) - timestampToMs(start);
+}
+```
+
+**文件**: `src/core/utils/session.ts`
+
+```typescript
+/**
+ * Session ID 处理工具
+ */
+
+/**
+ * 截断 Session ID 到指定长度（用于日志显示）
+ */
+export function truncateSessionId(sessionId: string, length: number = 8): string {
+  if (!sessionId) return 'unknown';
+  return sessionId.slice(0, length);
+}
+
+/**
+ * 验证 Session ID 格式（UUID v4）
+ */
+export function isValidSessionId(sessionId: string): boolean {
+  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidV4Regex.test(sessionId);
+}
+```
+
+**文件**: `src/core/utils/format.ts`
+
+```typescript
+/**
+ * 通用格式化工具
+ */
+
+/**
+ * 格式化错误信息（用于日志）
+ */
+export function formatError(context: string, error: unknown): string {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : undefined;
+  return `${context}: ${errorMessage}${errorStack ? `\n${errorStack}` : ''}`;
+}
+
+/**
+ * 格式化文件大小（字节 → 人类可读）
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${(bytes / Math.pow(k, i)).toFixed(1)} ${sizes[i]}`;
+}
+```
+
+#### 3.1.2 替换重复代码
+
+**改动文件**：
+- `src/daemon/event-parser.ts`：使用 `normalizeTimestamp`
+- `src/daemon/handlers/stop.ts`：使用 `truncateSessionId` + `formatError`
+- `src/daemon/handlers/user-prompt.ts`：使用 `truncateSessionId`
+- `src/daemon/handlers/history-exporter.ts`：使用 `normalizeTimestamp`
+- `src/daemon/services/task-segmenter.ts`：使用 `normalizeTimestamp`
+- `src/claudemd/resume-manager.ts`：使用 `normalizeTimestamp` + `truncateSessionId`
+
+**验证方法**：
+1. 运行单元测试：`npx vitest run tests/unit/utils/`
+2. 运行集成测试：`npx vitest run tests/integration/`
+3. 手动测试：启动 daemon，触发各类事件，检查日志格式
+
+**回滚方案**：
+- Git revert 到 Step 1 开始前的 commit
+
+---
+
+### Step 2: 统一命名风格（2 天）
+
+**目标**：统一文件命名和函数命名风格。
+
+#### 3.2.1 文件命名规范
+
+**规范**：
+- 所有新文件使用 `kebab-case.ts`（如 `time-utils.ts`）
+- 现有文件保持不变（避免 git 历史混乱）
+- 在 `CLAUDE.md` 中明确规范
+
+**改动**：
+- 更新 `CLAUDE.md`，添加文件命名规范章节
+
+#### 3.2.2 函数命名规范
+
+**规范**：
+- 查询单条记录：`get*`（如 `getSession`）
+- 查询多条记录：`query*`（如 `querySessions`）
+- 列出所有记录：`list*`（如 `listSkills`）
+- 写入记录：`write*`（如 `writeEvent`）
+- 更新记录：`update*`（如 `updateTask`）
+
+**说明**：经过检查，现有函数命名已基本符合规范，无需大规模重命名。
+
+**验证方法**：
+1. 代码审查：检查所有新增函数是否符合规范
+2. 文档审查：检查 `CLAUDE.md` 是否明确规范
+
+---
+
+### Step 3: 优化数据库查询（3 天）
+
+**目标**：使用预编译语句，消除 N+1 查询，优化连接池。
+
+#### 3.3.1 预编译语句优化
+
+**改动示例**（`src/core/storage/events.ts`）：
+
+**Before**:
+```typescript
+const sql = `SELECT * FROM events ${where} ORDER BY timestamp DESC LIMIT ${limit} OFFSET ${offset}`;
+const rows = this.db.prepare(sql).all(...params);
+```
+
+**After**:
+```typescript
+const sql = `SELECT * FROM events ${where} ORDER BY timestamp DESC LIMIT ? OFFSET ?`;
+params.push(limit, offset);
+const rows = this.db.prepare(sql).all(...params);
+```
+
+#### 3.3.2 连接池优化
+
+**改动文件**：`src/core/storage/base.ts`
+
+```typescript
+// Before
+this.db.pragma('busy_timeout = 5000');
+this.db.pragma('cache_size = -2000'); // 2MB
+
+// After
+this.db.pragma('busy_timeout = 10000'); // 增加到 10 秒
+this.db.pragma('cache_size = -8000'); // 增加到 8MB
+this.db.pragma('temp_store = MEMORY'); // 临时表使用内存
+this.db.pragma('mmap_size = 30000000000'); // 启用 mmap（30GB）
+```
+
+**验证方法**：
+1. 性能测试：并发写入 1000 条事件，测量延迟
+2. 内存测试：监控 daemon 内存占用（应 <100MB）
+
+---
+
+### Step 4: 内存泄漏防护（1 天）
+
+**目标**：为 `InvocationGuard` 增加 TTL 机制。
+
+**改动文件**：`src/skills/invocation-guard.ts`
+
+**改动方案**：
+
+```typescript
+export interface SessionInvocations {
+  total: number;
+  depth: number;
+  calledSkills: Set<string>;
+  lastAccessTime: number; // 新增：最后访问时间
+}
+
+export class InvocationGuard {
+  private sessions = new Map<string, SessionInvocations>();
+  private readonly TTL_MS = 30 * 60 * 1000; // 30 分钟
+  private cleanupInterval: NodeJS.Timeout | null = null;
+
+  constructor() {
+    // 启动定时清理任务（每 5 分钟）
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupExpiredSessions();
+    }, 5 * 60 * 1000);
+  }
+
+  private cleanupExpiredSessions(): void {
+    const now = Date.now();
+    const expired: string[] = [];
+    
+    for (const [sessionId, session] of this.sessions.entries()) {
+      if (now - session.lastAccessTime > this.TTL_MS) {
+        expired.push(sessionId);
+      }
+    }
+    
+    for (const sessionId of expired) {
+      this.sessions.delete(sessionId);
+    }
+  }
+
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+}
+```
+
+**验证方法**：
+1. 单元测试：模拟 30 分钟后清理过期 session
+2. 内存测试：运行 daemon 24 小时，监控内存占用
+
+---
+
+### Step 5: 提升测试覆盖率（1 天）
+
+**目标**：将测试覆盖率从 40% 提升至 60%。
+
+**新增测试文件**：
+- `tests/unit/utils/time.test.ts`（100 行）
+- `tests/unit/utils/session.test.ts`（80 行）
+- `tests/unit/utils/format.test.ts`（120 行）
+- `tests/unit/skills/invocation-guard-ttl.test.ts`（150 行）
+
+**验证方法**：
+1. 运行覆盖率报告：`npx vitest run --coverage`
+2. 确保覆盖率 ≥ 60%
+
+---
+
+## 4. 风险点
+
+### 4.1 高风险改动
+
+| 风险点 | 影响范围 | 降低措施 |
+|-------|---------|---------|
+| 数据库查询优化 | 所有存储操作 | 1. 保留原查询作为备份<br>2. 性能测试验证<br>3. 灰度发布 |
+| InvocationGuard TTL | Skill 调用链路 | 1. TTL 设置为 30 分钟<br>2. 单元测试覆盖<br>3. 监控内存占用 |
+| 时间戳归一化 | 所有时间相关逻辑 | 1. 单元测试覆盖<br>2. 集成测试验证<br>3. 保留原逻辑备份 |
+
+---
+
+## 5. 验收标准
+
+### 5.1 功能验收
+
+- ✅ 所有现有功能正常
+- ✅ daemon 启动正常
+- ✅ Web 仪表盘正常访问
+- ✅ CLI 命令正常执行
+
+### 5.2 性能验收
+
+- ✅ 数据库查询性能提升（对比修改前后）
+- ✅ 内存占用稳定（<100MB）
+- ✅ N+1 查询消除
+
+### 5.3 测试验收
+
+- ✅ 单元测试覆盖率 ≥ 60%
+- ✅ 所有测试通过
+- ✅ 代码重复率 <8%
+
+---
+
+## 6. 时间估算
+
+| 步骤 | 工作量（天） | 依赖 |
+|---|---|---|
+| Step 1: 抽取重复逻辑 | 3 | 无 |
+| Step 2: 统一命名风格 | 2 | 无 |
+| Step 3: 优化数据库查询 | 3 | 无 |
+| Step 4: 内存泄漏防护 | 1 | 无 |
+| Step 5: 提升测试覆盖率 | 1 | Step 1-4 完成后 |
+| **总计** | **10 天** | - |
+
+**总工作量**：10 天（2 周）
+
+---
+
+## 7. 里程碑
+
+| 日期 | 里程碑 | 交付物 |
+|---|---|---|
+| 2026-05-20 | 重复逻辑抽取完成 | 3 个工具模块 + 测试 |
+| 2026-05-22 | 命名风格统一完成 | 更新 CLAUDE.md |
+| 2026-05-27 | 数据库优化完成 | 性能测试报告 |
+| 2026-05-28 | 内存泄漏防护完成 | TTL 机制 + 测试 |
+| 2026-05-29 | 第 2 迭代验收 | 覆盖率 ≥ 60% |
+
+---
+
+## 8. 下一步
+
+**Phase 2.5: User Review**
+
+请 review 本方案后回复：
+- **"批准"** / **"approve"** → spawn coder 开始实施
+- **"修改 [意见]"** → 调整 spec
+- **"取消"** → 停止任务

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