@winspan/claude-forge 8.53.2 → 8.54.3

package/docs/design/refactor-phase1-spec-20260515-1600.md

@@ -1,543 +0,0 @@
-# claude-forge 渐进式重构 - 第 1 迭代实施方案
-
-**文档版本**: v1.0  
-**生成时间**: 2026-05-15 16:00  
-**迭代周期**: 2 周（2026-05-15 ~ 2026-05-29）  
-**负责范围**: P0 安全漏洞 + 部分 P1 基础设施问题
-
----
-
-## 1. 目标与范围
-
-### 1.1 迭代目标
-
-第 1 迭代聚焦于**安全加固**和**基础设施稳定性**，为后续重构奠定安全基础：
-
-1. **修复 P0 级安全漏洞**（3 个）
-   - 路径遍历漏洞（skills.ts、patch.ts）
-   - Git 命令注入漏洞（trace.ts）
-   - 类型安全缺失（storage/events.ts）
-
-2. **解决 P1 级基础设施问题**（选择 4 个）
-   - 添加缺失的数据库索引（性能优化）
-   - 补充核心模块单元测试（覆盖率从 0% → 50%）
-   - 统一错误处理（daemon 稳定性）
-   - 添加请求体大小限制（DoS 防护）
-
-3. **建立测试基础设施**
-   - 配置测试环境（Vitest + 覆盖率报告）
-   - 编写测试工具函数（mock storage、mock AI provider）
-   - 建立 CI 流程（GitHub Actions）
-
-### 1.2 不包括的内容（留到后续迭代）
-
-- ❌ 架构重构（模块拆分、依赖解耦）
-- ❌ 性能优化（N+1 查询、连接池）
-- ❌ 文档补全（API 文档、架构图）
-- ❌ P2 级问题（代码重复、命名规范）
-- ❌ 新功能开发
-
----
-
-## 2. 问题清单与优先级
-
-### 2.1 P0 级问题（必须修复）
-
-| ID | 问题 | 影响 | 文件 |
-|---|---|---|---|
-| P0-1 | 路径遍历漏洞 | 攻击者可读取任意文件 | `src/web/routes/skills.ts`, `src/web/routes/patch.ts` |
-| P0-2 | Git 命令注入 | 攻击者可执行任意命令 | `src/web/routes/trace.ts` |
-| P0-3 | 类型安全缺失 | 运行时类型错误 | `src/core/storage/events.ts` |
-
-### 2.2 P1 级问题（本迭代处理）
-
-| ID | 问题 | 影响 | 文件 |
-|---|---|---|---|
-| P1-1 | 缺失数据库索引 | 查询性能差 | `src/core/storage/schema.sql` |
-| P1-2 | 0% 测试覆盖 | 重构风险高 | 全局 |
-| P1-3 | 错误处理不统一 | daemon 崩溃 | `src/daemon/router.ts`, `src/web/routes/*.ts` |
-| P1-4 | 请求体大小无限制 | DoS 攻击风险 | `src/web/server.ts` |
-
----
-
-## 3. 改动文件清单
-
-### 3.1 安全修复（P0）
-
-| 文件 | 改动类型 | 预计行数 | 说明 |
-|---|---|---|---|
-| `src/web/routes/skills.ts` | 修改 | +15 | 添加文件名校验 |
-| `src/web/routes/patch.ts` | 修改 | +15 | 添加路径校验 |
-| `src/web/routes/trace.ts` | 修改 | +20 | 添加 projectPath 校验 |
-| `src/core/storage/events.ts` | 修改 | +30 | 添加 Zod 运行时校验 |
-| `tests/unit/security.test.ts` | 新增 | +100 | 安全漏洞回归测试 |
-
-### 3.2 基础设施改进（P1）
-
-| 文件 | 改动类型 | 预计行数 | 说明 |
-|---|---|---|---|
-| `src/core/storage/schema.sql` | 修改 | +15 | 添加复合索引 |
-| `src/daemon/router.ts` | 修改 | +30 | 添加错误边界 |
-| `src/web/server.ts` | 修改 | +5 | 添加请求体大小限制 |
-| `src/web/routes/error-handler.ts` | 新增 | +50 | 统一错误处理中间件 |
-| `tests/unit/storage.test.ts` | 新增 | +200 | Storage 单元测试 |
-| `tests/unit/router.test.ts` | 新增 | +150 | Router 单元测试 |
-| `tests/unit/type-guards.test.ts` | 新增 | +100 | 类型守卫测试 |
-| `tests/helpers/mock-storage.ts` | 新增 | +80 | 测试工具函数 |
-| `tests/helpers/mock-ai.ts` | 新增 | +60 | 测试工具函数 |
-
-### 3.3 CI/CD 配置
-
-| 文件 | 改动类型 | 预计行数 | 说明 |
-|---|---|---|---|
-| `.github/workflows/test.yml` | 新增 | +50 | CI 测试流程 |
-| `.github/workflows/security.yml` | 新增 | +40 | 安全扫描流程 |
-
-**总计**：
-- 新增文件：9 个
-- 修改文件：7 个
-- 预计改动行数：~960 行
-
----
-
-## 4. 实施步骤（按依赖顺序）
-
-### Step 1: 修复 P0-1 路径遍历漏洞（1 天）
-
-**目标**：防止攻击者通过 `../../../etc/passwd` 等路径读取任意文件
-
-**改动**：
-
-1. **修复 skills.ts**（第 33 行）
-   ```typescript
-   // 当前代码
-   const filePath = path.join(skillsDir, `${name}.md`);
-   
-   // 修复后
-   if (name.includes('/') || name.includes('\\') || name.includes('..')) {
-     return res.status(400).json({ error: 'Invalid skill name' });
-   }
-   const safeName = name.replace(/[^a-zA-Z0-9_-]/g, '_');
-   const filePath = path.join(skillsDir, `${safeName}.md`);
-   ```
-
-2. **修复 patch.ts**（第 45 行）
-   ```typescript
-   function resolvePatchTarget(targetType: string, targetName: string): string {
-     // 添加路径校验
-     if (targetName.includes('/') || targetName.includes('\\') || targetName.includes('..')) {
-       throw new Error('Invalid target name');
-     }
-     
-     if (targetType === 'skill') {
-       return path.join(getSkillsDir(), `${targetName}.md`);
-     }
-     // ...
-   }
-   ```
-
-**验证方法**：
-```bash
-# 测试恶意输入
-curl http://localhost:3456/api/skills/../../../etc/passwd
-# 预期：返回 400 错误
-
-curl -X PUT http://localhost:3456/api/skills/../../../tmp/evil \
-  -H "Content-Type: application/json" \
-  -d '{"content": "malicious"}'
-# 预期：返回 400 错误
-```
-
-**回滚方案**：
-- Git revert 到修改前的 commit
-
----
-
-### Step 2: 修复 P0-2 Git 命令注入漏洞（1 天）
-
-**目标**：防止攻击者通过恶意 projectPath 执行任意命令
-
-**改动**：
-
-1. **修复 trace.ts**（第 28 行）
-   ```typescript
-   // 当前代码
-   const projectPath = req.query.project as string | undefined;
-   
-   // 修复后
-   const projectPath = req.query.project as string | undefined;
-   
-   // 校验 projectPath
-   if (!projectPath) {
-     return res.status(400).json({ error: 'Missing project parameter' });
-   }
-   
-   if (!path.isAbsolute(projectPath)) {
-     return res.status(400).json({ error: 'Project path must be absolute' });
-   }
-   
-   if (!fs.existsSync(projectPath)) {
-     return res.status(404).json({ error: 'Project path does not exist' });
-   }
-   
-   if (!fs.existsSync(path.join(projectPath, '.git'))) {
-     return res.status(400).json({ error: 'Not a git repository' });
-   }
-   
-   // 继续执行 git 命令
-   ```
-
-**验证方法**：
-```bash
-# 测试恶意输入
-curl "http://localhost:3456/api/trace/HEAD?project=/tmp;%20rm%20-rf%20/"
-# 预期：返回 400 错误，不执行 rm 命令
-```
-
-**回滚方案**：
-- Git revert
-
----
-
-### Step 3: 修复 P0-3 类型安全缺失（2 天）
-
-**目标**：在 storage 层添加运行时类型校验，防止数据库返回异常数据导致崩溃
-
-**改动**：
-
-1. **添加 Zod schema**（`src/core/storage/events.ts`）
-   ```typescript
-   import { z } from 'zod';
-   
-   const EventRowSchema = z.object({
-     event_id: z.string(),
-     session_id: z.string(),
-     project_path: z.string(),
-     timestamp: z.string(),
-     hook_type: z.enum(['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'Stop', 'Notification']),
-     tool_name: z.string().optional(),
-     tool_input: z.string().optional(), // JSON string
-     tool_output: z.string().optional(), // JSON string
-     user_prompt: z.string().optional(),
-     ai_response: z.string().optional(),
-   });
-   
-   private rowToEvent(row: unknown): ForgeEvent {
-     // 运行时校验
-     const validated = EventRowSchema.parse(row);
-     
-     return {
-       event_id: validated.event_id,
-       session_id: validated.session_id,
-       project_path: validated.project_path,
-       timestamp: validated.timestamp,
-       hook_type: validated.hook_type,
-       tool_name: validated.tool_name,
-       tool_input: validated.tool_input ? JSON.parse(validated.tool_input) : undefined,
-       tool_output: validated.tool_output ? JSON.parse(validated.tool_output) : undefined,
-       user_prompt: validated.user_prompt,
-       ai_response: validated.ai_response,
-     };
-   }
-   ```
-
-2. **错误处理**
-   ```typescript
-   queryEvents(filter: EventFilter): ForgeEvent[] {
-     try {
-       const rows = this.db.prepare(sql).all(...params);
-       return rows.map(row => this.rowToEvent(row));
-     } catch (err) {
-       if (err instanceof z.ZodError) {
-         logger.error('[Storage] Invalid event row from database:', err.errors);
-         return []; // 返回空数组而非崩溃
-       }
-       throw err;
-     }
-   }
-   ```
-
-**验证方法**：
-```bash
-# 运行单元测试
-npx vitest run tests/unit/storage.test.ts
-
-# 手动测试：插入异常数据
-sqlite3 ~/.claude-forge/data.db "INSERT INTO events (event_id, session_id, hook_type) VALUES ('test', 'test', 'InvalidType');"
-# 预期：queryEvents 返回空数组，不崩溃
-```
-
-**回滚方案**：
-- 保留原 `rowToEvent` 为 `unsafeRowToEvent`
-- 如果 Zod 校验导致合法数据被拒绝，临时回退
-
----
-
-### Step 4: 添加缺失的数据库索引（0.5 天）
-
-**目标**：优化高频查询性能
-
-**改动**：
-
-1. **添加索引**（`src/core/storage/schema.sql`）
-   ```sql
-   -- routing_events 表：obeyed 查询优化
-   CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed_ts 
-   ON routing_events(obeyed, ts DESC);
-   
-   -- events 表：session + hook_type 复合查询优化
-   CREATE INDEX IF NOT EXISTS idx_events_session_hook 
-   ON events(session_id, hook_type, timestamp DESC);
-   
-   -- injections 表：session + handler 复合查询优化
-   CREATE INDEX IF NOT EXISTS idx_injections_session_handler 
-   ON injections(session_id, source_handler);
-   ```
-
-2. **迁移脚本**（`src/core/storage/base.ts`）
-   ```typescript
-   private runMigrations(): void {
-     // 添加索引（幂等操作）
-     this.db.exec(`
-       CREATE INDEX IF NOT EXISTS idx_routing_events_obeyed_ts ON routing_events(obeyed, ts DESC);
-       CREATE INDEX IF NOT EXISTS idx_events_session_hook ON events(session_id, hook_type, timestamp DESC);
-       CREATE INDEX IF NOT EXISTS idx_injections_session_handler ON injections(session_id, source_handler);
-     `);
-     logger.info('[SQLiteStorage] Performance indexes created');
-   }
-   ```
-
-**验证方法**：
-```bash
-# 检查索引
-sqlite3 ~/.claude-forge/data.db "SELECT name FROM sqlite_master WHERE type='index' AND name LIKE 'idx_%';"
-
-# 验证查询计划
-sqlite3 ~/.claude-forge/data.db "EXPLAIN QUERY PLAN SELECT * FROM routing_events WHERE obeyed IS NULL ORDER BY ts DESC;"
-# 预期：SEARCH routing_events USING INDEX idx_routing_events_obeyed_ts
-```
-
----
-
-### Step 5: 补充核心模块单元测试（5 天）
-
-**目标**：测试覆盖率从 0% 提升到 50%
-
-**改动**：
-
-1. **测试工具函数**（`tests/helpers/mock-storage.ts`）
-   ```typescript
-   import Database from 'better-sqlite3';
-   import { SQLiteStorage } from '../../src/core/storage/sqlite.js';
-   import { tmpdir } from 'node:os';
-   import { join } from 'node:path';
-   import { randomUUID } from 'node:crypto';
-   
-   export function createMockStorage(): SQLiteStorage {
-     const dbPath = join(tmpdir(), `test-${randomUUID()}.db`);
-     return new SQLiteStorage(dbPath);
-   }
-   
-   export function cleanupMockStorage(storage: SQLiteStorage): void {
-     const dbPath = storage.getDbPath();
-     storage.close();
-     if (fs.existsSync(dbPath)) {
-       fs.unlinkSync(dbPath);
-     }
-   }
-   ```
-
-2. **Storage 测试**（`tests/unit/storage.test.ts`）
-   - 测试 `writeEvent` / `queryEvents` / `upsertSession`
-   - 测试事务处理
-   - 测试并发写入
-   - 测试索引生效
-
-3. **Router 测试**（`tests/unit/router.test.ts`）
-   - 测试事件路由逻辑
-   - 测试类型守卫
-   - 测试错误边界
-
-4. **Type Guards 测试**（`tests/unit/type-guards.test.ts`）
-   - 测试所有类型守卫函数
-   - 测试边界情况（缺失字段、错误类型）
-
-**验证方法**：
-```bash
-# 运行测试
-npm test
-
-# 生成覆盖率报告
-npm test -- --coverage
-
-# 检查覆盖率
-cat coverage/coverage-summary.json | jq '.total.lines.pct'
-# 预期：>= 50
-```
-
----
-
-### Step 6: 统一错误处理 + 请求体限制（1 天）
-
-**目标**：提升 daemon 和 Web 服务稳定性
-
-**改动**：
-
-1. **添加错误边界**（`src/daemon/router.ts`）
-   ```typescript
-   export async function routeEvent(event: ForgeEvent, handlers: Handlers): Promise<HookResult | void> {
-     try {
-       if (isUserPromptSubmit(event)) return await handlers.UserPromptSubmit.handle(event);
-       if (isPostToolUse(event)) return await handlers.PostToolUse.handle(event);
-       if (isStop(event)) return await handlers.Stop.handle(event);
-     } catch (err) {
-       logger.error(`[Router] Handler failed for ${event.hook_type}:`, err);
-       return { allow: true }; // 默认放行，避免阻塞 Claude Code
-     }
-   }
-   ```
-
-2. **统一错误处理中间件**（`src/web/routes/error-handler.ts`）
-   ```typescript
-   export function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
-     logger.error(`[API Error] ${req.method} ${req.path}:`, err);
-     
-     const statusCode = (err as any).statusCode || 500;
-     const errorCode = (err as any).code || 'INTERNAL_ERROR';
-     
-     res.status(statusCode).json({
-       error: {
-         code: errorCode,
-         message: err.message,
-       }
-     });
-   }
-   ```
-
-3. **请求体大小限制**（`src/web/server.ts`）
-   ```typescript
-   this.app.use(express.json({ limit: '1mb' }));
-   this.app.use(express.urlencoded({ extended: true, limit: '1mb' }));
-   ```
-
-**验证方法**：
-```bash
-# 测试大请求体
-curl -X POST http://localhost:3456/api/patch/preview \
-  -H "Content-Type: application/json" \
-  -d "$(python3 -c 'print("{\"data\": \"" + "A"*2000000 + "\"}")')"
-# 预期：返回 413 Payload Too Large
-```
-
----
-
-## 5. 风险点与缓解措施
-
-### 5.1 高风险改动
-
-| 改动 | 风险 | 缓解措施 |
-|---|---|---|
-| 路径校验逻辑 | 可能拒绝合法路径 | 保留旧函数作为 fallback；充分测试 |
-| Zod 运行时校验 | 性能开销 | 仅在边界层使用；缓存 schema |
-| 错误边界 | 可能隐藏真实错误 | 详细日志记录；监控错误率 |
-
-### 5.2 回滚策略
-
-- 所有改动通过 Git 管理，可快速 revert
-- 关键改动保留旧代码为 `unsafe*` 或 `legacy*` 函数
-- 测试失败立即停止部署
-
----
-
-## 6. 测试策略
-
-### 6.1 单元测试覆盖目标
-
-| 模块 | 当前覆盖率 | 目标覆盖率 | 优先级 |
-|---|---|---|---|
-| `src/core/storage/` | 0% | 60% | P0 |
-| `src/daemon/router.ts` | 0% | 70% | P0 |
-| `src/core/types.ts` (type guards) | 0% | 80% | P0 |
-| `src/web/routes/` | 0% | 40% | P1 |
-
-### 6.2 集成测试场景
-
-1. **端到端事件流**
-   - UserPromptSubmit → Router → Handler → Storage
-   - 验证事件正确写入数据库
-
-2. **安全漏洞回归测试**
-   - 路径遍历攻击
-   - Git 命令注入
-   - 类型错误注入
-
-3. **性能测试**
-   - 索引生效验证
-   - 并发写入测试
-
----
-
-## 7. 验收标准
-
-### 7.1 功能验收
-
-- ✅ 所有现有功能正常（回归测试通过）
-- ✅ daemon 启动正常
-- ✅ Web 仪表盘正常访问
-- ✅ CLI 命令正常执行
-
-### 7.2 安全验收
-
-- ✅ 路径遍历攻击被拦截（返回 400）
-- ✅ Git 命令注入被拦截（返回 400）
-- ✅ 异常数据不导致崩溃（返回空数组或错误）
-
-### 7.3 性能验收
-
-- ✅ 索引创建成功（`EXPLAIN QUERY PLAN` 显示使用索引）
-- ✅ 查询性能提升（对比修改前后的查询时间）
-
-### 7.4 测试验收
-
-- ✅ 单元测试覆盖率 >= 50%
-- ✅ 所有测试通过
-- ✅ CI 流程正常运行
-
----
-
-## 8. 时间估算
-
-| 步骤 | 工作量（天） | 依赖 |
-|---|---|---|
-| Step 1: 路径遍历漏洞 | 1 | 无 |
-| Step 2: Git 命令注入 | 1 | 无 |
-| Step 3: 类型安全 | 2 | 无 |
-| Step 4: 数据库索引 | 0.5 | 无 |
-| Step 5: 单元测试 | 5 | Step 1-4 完成后 |
-| Step 6: 错误处理 | 1 | 无 |
-| **总计** | **10.5 天** | - |
-
-**缓冲时间**：1.5 天（应对意外问题）  
-**总工作量**：12 天（约 2 周）
-
----
-
-## 9. 里程碑
-
-| 日期 | 里程碑 | 交付物 |
-|---|---|---|
-| 2026-05-17 | P0 安全漏洞修复完成 | 3 个漏洞修复 + 回归测试 |
-| 2026-05-20 | 基础设施改进完成 | 索引 + 错误处理 + 请求体限制 |
-| 2026-05-27 | 单元测试完成 | 覆盖率 >= 50% |
-| 2026-05-29 | 第 1 迭代验收 | 所有验收标准通过 |
-
----
-
-## 10. 下一步
-
-**Phase 1.5: User Review**
-
-请 review 本方案后回复：
-- **"批准"** / **"approve"** → spawn coder 开始实施
-- **"修改 [意见]"** → 调整 spec
-- **"取消"** → 停止任务