@winspan/claude-forge 8.53.2 → 8.54.3

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

@@ -1,424 +0,0 @@
-# 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
-- **"取消"** → 停止任务