@winspan/claude-forge 8.51.1 → 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
-- **"取消"** → 停止任务

package/docs/design/task-active-gc-spec-20260518-1745.md

@@ -1,146 +0,0 @@
-# task active GC 修复 Spec
-
-## 目标
-
-通过周期 GC + completeCurrentTask recover fallback，消除因 ESC 中断、Stop hook 未触发、daemon 重启等场景导致的 task 永久滞留 `active` 状态。
-
-## Bug 复现路径
-
-| 场景 | 触发条件 | 为何漏掉 |
-|------|---------|---------|
-| A | 用户 ESC 中断 Claude Code，Stop hook 不触发 | completeCurrentTask 永远不被调用 |
-| B | daemon 重启后用户 ESC，Stop hook 触发但 `currentTasks` Map 为空 | completeCurrentTask 第 78 行：`const current = this.currentTasks.get(sessionId)` — Map 空直接 return |
-| C | 用户切到别的 session 后永不再 prompt 旧 session | shouldStartNewTask 从不被触发，task 无人收尾 |
-
-## 方案对比
-
-| 方案 | 修复场景 | 改动文件数 | 风险 |
-|------|---------|-----------|------|
-| A：周期 GC | A / C（idle 超阈值后兜底） | 3 | idle 阈值设太短可能误杀长任务 |
-| B：completeCurrentTask recover fallback | B | 1 | 仅修场景 B，A/C 仍漏 |
-| C：A + B 组合 | A / B / C 全覆盖 | 3 | 最全面，改动仍可控 |
-| D：新增 `auto_closed` 状态 | A / B / C + UI 语义区分 | 5+ | 改动大，可作后续优化 |
-
-**推荐：方案 C**。
-
-## 详细设计
-
-### 1. storage 新方法：`completeStaleActiveTasks`
-
-**位置**：`src/core/storage/tasks.ts`（TaskOperations 类内）
-
-```ts
-/**
- * 将 idle 超过阈值的 active task 批量转为 completed。
- * 条件：status='active' AND end_time IS NOT NULL
- *       AND (now - end_time) > idleMinutes 分钟。
- * 返回：受影响行数。
- */
-completeStaleActiveTasks(idleMinutes: number): number {
-  const result = this.db.prepare(`
-    UPDATE tasks
-    SET status = 'completed'
-    WHERE status = 'active'
-      AND end_time IS NOT NULL
-      AND (julianday('now') - julianday(end_time)) * 24 * 60 > ?
-  `).run(idleMinutes);
-  return result.changes;
-}
-```
-
-同步在 `SQLiteStorage` facade（`sqlite.ts`）暴露同名代理方法。
-
-注意：`end_time` 由 `linkEventToTask` 持续更新，作为 idle 判定基准合理。没有 `end_time` 的 task（从未 link 过事件）不纳入 GC，避免误杀刚创建的 task。
-
-### 2. TaskSegmenter.completeCurrentTask 加 recover fallback
-
-**位置**：`src/daemon/services/task-segmenter.ts:77`
-
-```ts
-completeCurrentTask(sessionId: string, timestamp: string): void {
-  const current = this.currentTasks.get(sessionId) ?? this.recoverActiveTask(sessionId);
-  if (!current) return;
-  ...
-}
-```
-
-一行改动，与 `processPrompt` / `linkEvent` 模式一致。
-
-### 3. maintenanceInterval 加 GC 调度
-
-**位置**：`src/daemon/index.ts:105-116`
-
-现有 `maintenanceInterval` 是 **24 小时**，仅清理旧 events。需新增独立的**短周期 GC interval**：
-
-```ts
-// ── 5.6. Stale task GC (every 5 minutes) ──────────────────────────
-const STALE_TASK_GC_INTERVAL = 5 * 60 * 1000; // 5 分钟
-const STALE_TASK_IDLE_MINUTES = 10;            // idle 超 10 分钟视为滞留
-
-const staleTaskGcInterval = setInterval(() => {
-  try {
-    const closed = storage.completeStaleActiveTasks(STALE_TASK_IDLE_MINUTES);
-    if (closed > 0) {
-      logger.info(`[Maintenance] Auto-completed ${closed} stale active task(s)`);
-    }
-  } catch (err) {
-    logger.error(`[Maintenance] Stale task GC failed: ${err}`);
-  }
-}, STALE_TASK_GC_INTERVAL);
-```
-
-关闭时需调用 `clearInterval(staleTaskGcInterval)`（在现有 graceful shutdown 段追加）。
-
-## 改造范围
-
-| 文件 | 改动内容 | 估算行数 |
-|------|---------|---------|
-| `src/core/storage/tasks.ts` | 新增 `completeStaleActiveTasks` 方法 | +12 |
-| `src/core/storage/sqlite.ts` | facade 代理方法 | +3 |
-| `src/daemon/services/task-segmenter.ts` | completeCurrentTask recover fallback（1 行） | +1 |
-| `src/daemon/index.ts` | 新增 GC interval + clearInterval | +12 |
-
-共 4 文件，约 28 行净增。
-
-## 配置
-
-| 参数 | 值 | 说明 |
-|------|----|------|
-| `STALE_TASK_IDLE_MINUTES` | 10 | idle 超 10 分钟视为放弃，不可配置（硬编码常量） |
-| `STALE_TASK_GC_INTERVAL` | 5 分钟 | GC 轮询间隔，独立于 24h 维护周期 |
-
-如未来需要可迁移到 `config.yaml` 的 `tasks.stale_gc_minutes` 字段。
-
-## 测试策略
-
-| 测试类型 | 测试用例 | 文件位置 |
-|---------|---------|---------|
-| 单测：`completeStaleActiveTasks` | 空表返回 0 | 新增 `tests/unit/storage/tasks-stale-gc.test.ts` |
-| | 1 idle 超阈值 + 1 未超：只关超的 | 同上 |
-| | `status='completed'` 的 task 不被改动 | 同上 |
-| | `end_time IS NULL` 的 task 不被纳入 | 同上 |
-| 单测：recover fallback | Map 为空时仍能 complete DB 中 active task | 扩展现有 task-segmenter 测试 |
-
-## 风险与回滚
-
-| 风险 | 概率 | 缓解措施 |
-|------|------|---------|
-| 误杀正在进行的长任务 | 低（idle 阈值 10 分钟，linkEvent 持续刷新 end_time） | 阈值可调大；日志可审计 |
-| 旧库一次性批量 GC | 必然发生，且是预期行为 | 无需回滚，这正是修 bug 的目的 |
-| GC interval 异常退出 | 极低（try-catch 包裹） | 日志记录，不影响主流程 |
-
-**回滚**：删除 daemon/index.ts 中的 `staleTaskGcInterval` 代码块即可完全禁用 GC，其他改动无副作用。
-
-## 实施顺序
-
-1. `tasks.ts` — 新增 `completeStaleActiveTasks` + 单测
-2. `sqlite.ts` — facade 代理方法
-3. `task-segmenter.ts` — recover fallback 单行 + 单测
-4. `daemon/index.ts` — GC interval 注册 + clearInterval
-5. 全量测试 `npm test`
-
-## 命名遵循
-
-- `completeStaleActiveTasks`：`complete` 前缀（语义清晰，优于 `write`）
-- `STALE_TASK_GC_INTERVAL` / `STALE_TASK_IDLE_MINUTES`：全大写常量
-- `staleTaskGcInterval`：camelCase 变量，与 `maintenanceInterval` 风格一致