@winspan/claude-forge 8.41.0 → 8.51.0

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/task-active-gc-spec-20260518-1745.md

@@ -0,0 +1,146 @@
+# 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` 风格一致