@winspan/claude-forge 8.41.0 → 8.50.6

package/docs/design/architecture-review-20260516.md

@@ -0,0 +1,232 @@
+# claude-forge 架构评审报告
+
+生成时间：2026-05-16
+
+## 一、当前架构概览
+
+### 1.1 分层架构
+
+```
+claude-forge/
+├── src/
+│   ├── cli/           # CLI 命令层（用户交互入口）
+│   ├── daemon/        # 守护进程层（事件处理、生命周期管理）
+│   ├── web/           # Web API 层（Express + React Dashboard）
+│   ├── mcp/           # MCP 协议层（Model Context Protocol）
+│   ├── core/          # 核心共享层（storage、config、types、ai）
+│   ├── skills/        # Skill 匹配与注入层
+│   ├── claudemd/      # CLAUDE.md 生成器
+│   └── templates/     # 模板管理
+├── tests/
+│   └── integration/   # 集成测试（28 个测试文件）
+└── web/               # React 前端源码
+```
+
+### 1.2 核心依赖关系
+
+```
+┌─────────────────────────────────────┐
+│         CLI (用户入口)                │
+└──────────────┬──────────────────────┘
+               │
+       ┌───────┴────────┐
+       ▼                ▼
+┌──────────────┐  ┌──────────────┐
+│    Daemon    │  │     Web      │
+│  (事件处理)   │  │   (API/UI)   │
+└──────┬───────┘  └──────┬───────┘
+       │                 │
+       └────────┬────────┘
+                ▼
+        ┌───────────────┐
+        │     Core      │
+        │ (storage/ai)  │
+        └───────┬───────┘
+                │
+        ┌───────┴────────┐
+        ▼                ▼
+  ┌──────────┐    ┌──────────┐
+  │  Skills  │    │ CLAUDEmd │
+  │ (匹配器)  │    │ (生成器) │
+  └──────────┘    └──────────┘
+```
+
+### 1.3 数据流
+
+```
+Claude Code Hook
+    ↓ (Unix Socket)
+Daemon Server (router.ts)
+    ↓
+Event Handlers (user-prompt.ts / post-tool-use.ts / stop.ts)
+    ↓
+Storage (SQLite) + Services (TaskSegmenter / ResumeManager / SkillRegistry)
+    ↓
+Injection (systemMessage / additionalContext)
+    ↓
+Claude Code (返回给 AI)
+```
+
+## 二、发现的问题
+
+### 2.1 严重问题（P0）
+
+**无严重架构问题**
+
+当前架构清晰，分层合理，依赖方向正确（单向依赖 core）。
+
+### 2.2 中等问题（P1）
+
+#### 问题 1：单元测试缺失
+
+- **现状**：`src/` 目录下 0 个单元测试，仅 `tests/integration/` 有 28 个集成测试
+- **影响**：重构风险高，无法快速验证单个模块的正确性
+- **位置**：所有 `src/**/*.ts` 文件
+- **建议**：为 core 层（storage/utils/types）补充单元测试
+
+#### 问题 2：Web 层路由文件过多
+
+- **现状**：`src/web/routes/` 下有 15+ 个路由文件
+- **影响**：维护成本高，每个功能一个文件略显碎片化
+- **位置**：`src/web/routes/`
+- **建议**：考虑按功能域合并（如 stats + skill-stats + reports + insights 合并为 analytics 路由）
+
+### 2.3 轻微问题（P2）
+
+#### 问题 3：Daemon 主文件职责过多
+
+- **现状**：`src/daemon/index.ts` 包含初始化、生命周期、事件处理、维护任务等多个职责
+- **影响**：文件较长（250 行），职责边界不够清晰
+- **位置**：`src/daemon/index.ts`
+- **建议**：将维护任务（maintenance interval）抽取为独立模块
+
+#### 问题 4：Storage 层已重构但缺乏文档
+
+- **现状**：`sqlite.ts` 已从 1000+ 行单文件拆分为 9 个 Operations 类，但重构文档缺失
+- **影响**：新开发者可能不清楚如何添加新的存储操作
+- **位置**：`src/core/storage/`
+- **建议**：添加 `README.md` 说明存储层架构和扩展方式
+
+#### 问题 5：类型系统可以更严格
+
+- **现状**：`ForgeEvent` 使用可选字段（`tool_name?`），需要运行时检查
+- **影响**：类型安全性略低，需要 type guard 保护
+- **位置**：`src/core/types.ts`
+- **建议**：当前已通过 `ForgeEventNarrow` 联合类型解决，无需进一步优化
+
+## 三、重构必要性评估
+
+### 评估结论：**建议优化，无需大规模重构**
+
+### 理由
+
+1. **架构健康度高**
+   - 分层清晰（CLI / Daemon / Web / Core）
+   - 依赖方向正确（单向依赖 core）
+   - 模块边界明确（storage / skills / claudemd）
+
+2. **已有重构基础良好**
+   - Storage 层已完成职责拆分（9 个 Operations 类）
+   - 类型系统已优化（ForgeEvent → ForgeEventNarrow）
+   - 命名规范已统一（kebab-case 文件名）
+
+3. **主要问题是测试覆盖不足**
+   - 缺少单元测试是新功能的最大风险
+   - 但不需要架构重构，只需补充测试
+
+### 如果要重构，优先级排序
+
+1. **P1：补充单元测试**（提升重构信心）
+   - 范围：core/storage, core/utils, daemon/handlers
+   - 工作量：中等（约 2-3 周）
+   - 风险：低（不改变现有代码）
+
+2. **P2：合并 Web 路由**（降低维护成本）
+   - 范围：stats + skill-stats + reports + insights → analytics
+   - 工作量：小（约 2-3 天）
+   - 风险：低（仅文件合并）
+
+3. **P3：抽取 Daemon 维护任务**（职责分离）
+   - 范围：daemon/index.ts 中的 maintenance interval
+   - 工作量：极小（约 1 天）
+   - 风险：极低（纯重构）
+
+## 四、升维优化方向（如果决定重构）
+
+### 方向 1：事件驱动架构升级
+
+**目标**：将当前同步事件处理改为异步消息队列
+
+**收益**：
+- 提升吞吐量（高并发场景）
+- 支持事件重放和恢复
+- 解耦事件生产者和消费者
+
+**代价**：
+- 引入消息队列（如 BullMQ）
+- 架构复杂度上升
+- 需要处理消息幂等性
+
+**适用场景**：单机事件量 > 10万/天
+
+### 方向 2：插件化架构
+
+**目标**：将 Skills、CLAUDE.md、Handlers 都设计为可插拔插件
+
+**收益**：
+- 用户可自定义扩展（如自定义 Handler）
+- 核心代码更稳定
+- 便于社区贡献
+
+**代价**：
+- 需要设计插件 API
+- 插件版本管理复杂
+- 文档负担增加
+
+**适用场景**：用户有自定义扩展需求
+
+### 方向 3：多租户隔离
+
+**目标**：支持多项目隔离存储和配置
+
+**收益**：
+- 支持团队协作场景
+- 数据隔离更安全
+- 可支持 SaaS 模式
+
+**代价**：
+- 数据库 schema 需要调整
+- 权限控制复杂度上升
+- 需要租户管理功能
+
+**适用场景**：企业级团队使用
+
+## 五、建议
+
+### 短期建议（1-2 个月）
+
+1. **补充单元测试**：优先为 core/storage 和 daemon/handlers 添加测试
+2. **添加存储层文档**：在 `src/core/storage/README.md` 说明架构
+3. **合并 Web 路由**：将相关路由文件合并（analytics 相关）
+
+### 中期建议（3-6 个月）
+
+1. **评估事件驱动升级**：如果事件量增长，考虑引入消息队列
+2. **插件化设计调研**：如果用户有自定义需求，启动插件 API 设计
+
+### 长期建议（6-12 个月）
+
+1. **多租户支持**：如果转向企业级产品，启动多租户架构设计
+
+## 六、总结
+
+**当前架构评级：B+（良好）**
+
+- ✅ 分层清晰，依赖方向正确
+- ✅ 已完成部分重构（Storage 层拆分）
+- ⚠️ 单元测试缺失，重构风险较高
+- ⚠️ Web 路由略碎片化
+
+**核心建议：补充测试 > 小范围优化 > 大规模重构**
+
+当前架构足够支撑业务发展，优先补充测试覆盖，无需立即进行大规模重构。

package/docs/design/fix-skills-data-and-set-leak-spec-20260516-1300.md

@@ -0,0 +1,219 @@
+# Fix Spec: Official Skills 数据分离 + UserPromptHandler Set 内存泄漏
+
+**日期**: 2026-05-16
+**状态**: Draft（待用户 review）
+
+---
+
+## 一、目标
+
+| # | 修复点 | 成功标准 |
+|---|--------|---------|
+| 1 | Official Skills 数据/代码分离 | `official-skills.ts` 不再包含任何 skill 内容字符串；新增 `.md` 文件可被 `tsc` + `npm pack` 正确带入 `dist/` |
+| 2 | UserPromptHandler 无界 Set 内存泄漏 | `resumeInjected` / `conventionInjected` Set 在 session 结束后被清理，或存在 LRU 上限，daemon 长期运行不会无限增长 |
+
+---
+
+## 二、调研结论摘要
+
+### 修复点 1 — 现状数据结构
+
+`OfficialSkill` 接口（`src/skills/official-skills.ts:6-12`）有 5 个字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | `string` | skill id，如 `official-tdd` |
+| `version` | `string` | 版本号，如 `1.2.0` |
+| `description` | `string` | 一句话描述 |
+| `keywords` | `string[]` | 关键词（部分 skill 有扩展 keywords 在 `OFFICIAL_SKILL_KEYWORDS` 里） |
+| `content` | `string` | 完整 `.md` 文本，包含 frontmatter |
+
+共 19 个 skill（OFFICIAL_SKILLS 数组） + 1 个关键词映射表 `OFFICIAL_SKILL_KEYWORDS`（19 条）。
+`content` 字段本身已是 frontmatter+body 的完整 markdown，说明 skill 文件可直接拆分为独立 `.md`。
+
+### 修复点 1 — npm 发布打包现状
+
+`package.json` 无 `files` 字段，默认发布全部未被 `.gitignore` 的文件。
+`build` 脚本（`package.json:13`）仅用 `tsc` 编译 `src/**/*.ts` 到 `dist/`，静态文件靠 `cp` 显式拷贝（`schema.sql`、`hooks/*.sh`、`launchd/*.template`）。
+**关键结论**：`.md` 数据文件不在 `tsc` 编译范围内，**需要在 build 脚本中加 `cp` 命令**，否则 `dist/` 运行时找不到文件。
+
+### 修复点 1 — registry 加载逻辑
+
+`SkillRegistry.scan()`（`src/skills/registry.ts:49-133`）分两段：
+1. 先循环 `OFFICIAL_SKILLS` 数组，直接写入 Map（无文件读取）
+2. 再扫 `~/.claude/skills/*.md`，用 `gray-matter` 解析
+
+改造后只需把第 1 段改为扫内置目录的 `.md`，解析逻辑与第 2 段完全一致。
+
+### 修复点 2 — Set 的语义
+
+两个 Set 均以 `${session_id}:${project_path}` 为 key，目的是**每个 session 只注入一次 resume/convention**。
+
+`InvocationGuard` 的参考方案（`src/skills/invocation-guard.ts`）：
+- 用 `Map<sessionId, SessionInvocations>` 存状态
+- 有 TTL（30 min）+ 5 min 定时清理
+- StopHandler 显式调用 `guard.clear(sessionId)`（`src/daemon/handlers/stop.ts:61-65`）
+
+两种修复方案对比：
+
+| | 方案 A：StopHandler 清理 | 方案 B：TTL + 定时清理 |
+|-|---|---|
+| 原理 | Stop 事件时从 Set 删除对应 key | 用 `Map<key, {timestamp}>` 替换 Set，定期扫描过期 |
+| 实现复杂度 | 低（3-5 行）| 中（需改 Set 为 Map + 定时器）|
+| 覆盖范围 | 正常关闭的 session | 还能覆盖 crash/无 Stop 事件的情况 |
+| 与现有代码一致性 | 与 InvocationGuard.clear() 模式完全一致 | 需引入新依赖模式 |
+| 内存界限保证 | 依赖 Stop 事件的完整性 | 绝对有界 |
+
+**结论**：采用 **方案 A（StopHandler 清理）为主 + 方案 B LRU 上限 1000 为兜底**，两者互补。
+
+---
+
+## 三、改动文件清单
+
+### 修复点 1
+
+| 文件路径 | 改动类型 | 改动概述 |
+|----------|----------|---------|
+| `src/skills/official/*.md` | **新建 19 个文件** | 每个 skill 对应一个 `.md`，内容为现有 `content` 字段（已含 frontmatter）；skill `name` 和 `version` 在 frontmatter 中保留 |
+| `src/skills/official-skills.ts` | **大幅削减** | 删除 `OFFICIAL_SKILLS` 数组全部 skill 字面量；保留 `OFFICIAL_SKILL_KEYWORDS` 常量和 `OfficialSkill` 接口（供类型引用）；新增导出函数 `loadOfficialSkills(builtinDir: string): OfficialSkill[]` |
+| `src/skills/registry.ts` | **修改** | `scan()` 第 1 段改为调用 `loadOfficialSkills(resolveBuiltinDir())`；新增私有方法 `resolveBuiltinDir()` 解析 `import.meta.url` 相对路径（兼容 npm 安装和开发环境）|
+| `package.json` | **修改** | `build` 脚本末尾追加 `mkdir -p dist/skills/official && cp src/skills/official/*.md dist/skills/official/` |
+| `tests/unit/skill-registry.test.ts` | **修改** | 调整 skill 数量断言（现在硬编码 `>= 16`，改为 `>= 19` 或使用动态读取数量）|
+
+### 修复点 2
+
+| 文件路径 | 改动类型 | 改动概述 |
+|----------|----------|---------|
+| `src/daemon/handlers/user-prompt.ts` | **修改** | 将两个 `Set<string>` 改为 `Map<string, number>`（值存写入时间戳）；新增 `clearSession(sessionKey: string)` 公共方法；新增静态常量 `MAX_INJECTION_KEYS = 1000` 作为 LRU 上限兜底 |
+| `src/daemon/handlers/stop.ts` | **修改** | 在 Step 4（InvocationGuard 清理）之后，增加 Step 5：调用 `userPromptHandler.clearSession(sessionKey)` |
+| `src/daemon/index.ts` 或 handler 初始化处 | **修改**（视注入方式） | 确保 `StopHandler` 持有 `UserPromptHandler` 的引用，或通过事件总线传递 |
+| `tests/unit/handlers.test.ts` | **修改** | 新增 case：同一 session 两次调用只注入一次；stop 后再次调用会重新注入 |
+
+---
+
+## 四、关键设计决策
+
+### 修复点 1
+
+**决策 1-A：每个 skill 一个 `.md` 文件，不拆 json+md**
+
+理由：`content` 字段本身已是 frontmatter+markdown 格式，直接拆分零转换成本。独立文件对 diff 友好，增删 skill 只需增删一个文件。避免引入额外的索引文件维护负担。
+
+**决策 1-B：文件放在 `src/skills/official/` 而非 `data/official-skills/`**
+
+理由：与其他 skill 相关代码同目录，减少跨目录路径解析复杂度。`tsc` 的 `rootDir` 是 `src/`，`outDir` 是 `dist/`，拷贝路径天然对应 `dist/skills/official/`，逻辑清晰。
+
+**决策 1-C：`loadOfficialSkills` 接收 `builtinDir` 参数而非硬编码 `__dirname`**
+
+理由：便于单元测试（可传入临时目录）。`registry.ts` 中统一用 `resolveBuiltinDir()` 计算路径，该函数用 `import.meta.url` 解析（ESM 环境），兼容 npm 全局安装后路径变更的场景（参考 `feedback_npm_path.md` 记录的教训）。
+
+### 修复点 2
+
+**决策 2-A：采用方案 A（Stop 清理）+ 方案 B（LRU 上限 1000）双保险**
+
+理由：方案 A 是精确清理，与 InvocationGuard 模式一致，代码可读性强；方案 B 兜底 crash/无 Stop 场景。上限 1000 entry 约占内存 < 100KB（每个 key 约 80 bytes），完全可接受。
+
+**决策 2-B：将 Set 改为 `Map<string, number>`（保存 timestamp），不引入 TTL 定时器**
+
+理由：timestamp 用于 LRU 淘汰，在 `add` 时若超过 1000 条则删最旧的一条。不需要独立定时器（依赖 Stop 清理 + 容量上限已足够），避免增加守护进程复杂度。
+
+**决策 2-C：新增 `clearSession(sessionKey)` 为 public 方法，不通过构造函数注入 StopHandler**
+
+理由：`UserPromptHandler` 不应依赖 `StopHandler`，应由 `StopHandler` 持有 `UserPromptHandler` 的引用（单向依赖）。在 daemon 初始化时将 `UserPromptHandler` 实例传入 `StopHandler` 构造函数（或 setter）。
+
+---
+
+## 五、风险点
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|---------|
+| **npm 发布后找不到 `.md` 文件** | 运行时加载 0 个 official skill，功能退化 | build 脚本加 `cp`；发布前验证 `dist/skills/official/` 目录存在（可加 `prebuild` 检查） |
+| **`import.meta.url` 路径解析在 CJS 降级时失效** | N/A（项目是纯 ESM，`"type": "module"`）| 无需处理 |
+| **`StopHandler` 持有 `UserPromptHandler` 引用导致循环依赖** | 编译报错 | 检查依赖链：`user-prompt.ts` 不 import `stop.ts`，反向持有安全 |
+| **同 `session_id` 不同 `project_path` 切换**（同一 session key 不同 project）| 理论上 session_id 全局唯一，不会出现此情况 | 无需处理 |
+| **官方 skill 版本管理** | 拆成独立文件后版本号散落各 `.md` frontmatter，不易整体更新 | 可在 `OFFICIAL_SKILL_KEYWORDS` 常量旁维护一个 `OFFICIAL_SKILL_VERSIONS` 对象供版本检查（可选，Phase 2 再做）|
+| **测试中 skill 数量硬编码** | 修复点 1 后 skill 数量变为 19，现有断言 `>= 16` 可能需要调整 | 改动时同步更新 `tests/unit/skill-registry.test.ts` 断言 |
+
+---
+
+## 六、测试策略
+
+### 修复点 1
+
+| 测试文件 | 测试内容 |
+|----------|---------|
+| `tests/unit/skill-registry.test.ts` | 修改：`skills.length >= 19`；新增：`official-tdd` 等具体 skill 可被加载；`path !== '<built-in>'`（改为真实文件路径） |
+| 新建 `tests/unit/skills/official-skills-loader.test.ts` | 验证 `loadOfficialSkills(tempDir)` 从指定目录读取所有 `.md`；验证 frontmatter 解析正确（name、version、description、keywords）；验证目录不存在时抛出有意义的错误 |
+| `tests/unit/skills/registry-multiformat.test.ts` | 现有测试保持不变（测试 gray-matter 解析逻辑，与文件位置无关）|
+
+### 修复点 2
+
+| 测试文件 | 测试内容 |
+|----------|---------|
+| `tests/unit/handlers.test.ts` | 新增：同一 session 第二次调用 `handle()` 不重复注入 resume/convention；新增：`clearSession()` 后再次调用会重新注入；新增：超过 1000 个不同 sessionKey 后不崩溃（LRU 上限生效） |
+| `tests/unit/invocation-guard.test.ts` | 参考现有结构确认模式一致性，无需改动 |
+
+---
+
+## 七、执行步骤（自底向上）
+
+```
+修复点 1：官方 Skills 数据分离
+──────────────────────────────
+Step 1  从 official-skills.ts 提取每个 skill 的 content 字段，
+        在 src/skills/official/ 下创建对应 .md 文件（19 个）
+        文件名 = skill.name + '.md'（如 official-tdd.md）
+        内容 = content 字段原文（已含 frontmatter）
+
+Step 2  在 src/skills/official-skills.ts 中：
+        - 删除 OFFICIAL_SKILLS 数组（整个 export const OFFICIAL_SKILLS）
+        - 保留 OfficialSkill interface
+        - 保留 OFFICIAL_SKILL_KEYWORDS 常量
+        - 新增 loadOfficialSkills(builtinDir: string): OfficialSkill[] 函数
+          （用 fs.readdirSync + gray-matter 解析，与 registry 现有 user skill 逻辑对齐）
+
+Step 3  修改 src/skills/registry.ts：
+        - 新增私有方法 resolveBuiltinDir(): string
+          使用 new URL('./official', import.meta.url).pathname
+        - scan() 第 1 段改为调用 loadOfficialSkills(this.resolveBuiltinDir())
+        - 其余逻辑不变
+
+Step 4  修改 package.json build 脚本：
+        末尾追加 && mkdir -p dist/skills/official && cp src/skills/official/*.md dist/skills/official/
+
+Step 5  修改 tests/unit/skill-registry.test.ts 断言数量
+
+Step 6  新建 tests/unit/skills/official-skills-loader.test.ts
+
+Step 7  运行测试验证：
+        npx vitest run tests/unit/skill-registry.test.ts --reporter=verbose
+        npx vitest run tests/unit/skills/ --reporter=verbose
+        npx tsc --noEmit
+
+修复点 2：UserPromptHandler Set 内存泄漏
+─────────────────────────────────────────
+Step 8  修改 src/daemon/handlers/user-prompt.ts：
+        - 将 resumeInjected: Set<string> 改为 Map<string, number>
+        - 将 conventionInjected: Set<string> 改为 Map<string, number>
+        - 新增常量 MAX_INJECTION_KEYS = 1000
+        - 封装私有方法 hasInjected(map, key): boolean
+        - 封装私有方法 markInjected(map, key): void
+          （在 map.size >= MAX_INJECTION_KEYS 时删除最旧的一条）
+        - 新增 public clearSession(sessionKey: string): void
+          （同时从两个 Map 删除该 key）
+
+Step 9  修改 src/daemon/handlers/stop.ts：
+        - 构造函数新增可选参数 userPromptHandler?: UserPromptHandler
+        - Step 4 的 InvocationGuard.clear() 之后，调用
+          userPromptHandler?.clearSession(`${event.session_id}:${event.project_path}`)
+
+Step 10 修改 daemon 初始化处（src/daemon/index.ts 或类似文件），
+        在构造 StopHandler 时传入 userPromptHandler 实例
+
+Step 11 修改 tests/unit/handlers.test.ts，新增 3 个 case（见测试策略）
+
+Step 12 运行测试验证：
+        npx vitest run tests/unit/handlers.test.ts --reporter=verbose
+        npx tsc --noEmit
+        npm test -- --reporter=dot
+```

package/docs/design/hook-failure-queue-spec-20260516-1530.md

@@ -0,0 +1,204 @@
+# Hook 失败缓冲队列 + Daemon 启动重放 — Spec
+
+**日期**: 2026-05-16
+**状态**: Draft（待用户 review）
+
+---
+
+## 一、目标 + 成功标准
+
+**核心目标**：实现「至少一次」事件交付，消除 daemon 重启窗口期的静默丢失。
+
+| 成功标准 | 验收方式 |
+|---|---|
+| daemon 停机 30 秒内，5 条 UserPromptSubmit 全部最终入库 | 集成测试：停 daemon → 发 5 事件 → 启动 daemon → 查 DB |
+| 队列目录不超过 500 个文件 / 7 天 | 单元测试：写 600 个文件后调 prune，剩余 ≤500 |
+| hook 总执行时间不超过 1 秒 | 脚本计时测试（`time` 命令） |
+| 重放不产生重复入库 | 集成测试：手动写重复 event_id → 验证 DB 只有一条 |
+
+**非目标**：已丢失的历史事件（本次故障之前）、跨机器同步、daemon 运行期间的网络抖动（nc 有超时保护，不属于失败场景）。
+
+---
+
+## 二、设计决策
+
+### 决策 1：队列存储格式 — per-event 独立文件
+
+**选择**：`~/.claude-forge/queue/<timestamp>-<uuid>.json` 每个事件一个文件。
+
+**理由**：
+1. 完全避免并发写冲突：5 个 hook bash 进程写不同文件名，无锁需求
+2. 原子性：`bash` 的 `echo > file` 对新建文件是原子操作（内核 create + write）
+3. 删除操作幂等：`rm -f file` 不会影响其他事件；追加模式下误删一行会破坏整个 jsonl
+
+**否决方案**：append-only jsonl —— bash 并发 `>>` 在 chunk > PIPE_BUF(512B) 时会产生交错写，且部分行损坏会影响整个文件解析。
+
+### 决策 2：队列目录位置 — `~/.claude-forge/queue/`
+
+**理由**：
+1. 与 `daemon.sock`、`data.db`、`daemon.token` 同目录，路径计算逻辑统一
+2. `expandPath` 工具已有 `~/.claude-forge/` 展开支持
+3. daemon 启动时已有 `mkdirSync` 保证父目录存在，子目录只需 `mkdir -p queue`
+
+### 决策 3：触发投递条件 — daemon 启动时一次性扫描
+
+**理由**：
+1. 失败窗口期（daemon 重启）是短暂的，启动一次扫描即可覆盖
+2. 不需要额外的 watcher 进程/定时器，降低复杂度
+3. 重放完成后队列目录为空，无持续扫描开销
+
+### 决策 4：去重策略 — `event_id` 数据库唯一索引（已存在）+ catch ignore
+
+**理由**：
+1. `events.event_id TEXT PRIMARY KEY` 已存在，无需额外工作
+2. daemon 侧只需在 `writeEvent` 的 catch 中识别 `UNIQUE constraint failed` 并静默跳过，其他错误仍 re-throw
+3. 避免内存 LRU 在 daemon 重启时丢失已处理记录的风险
+
+### 决策 5：容量保护 — 500 文件上限 + 7 天 TTL，过期写入 dead-letter
+
+- 写入前检查：队列文件数 ≥ 500，**丢弃最旧的超额文件**
+- TTL：daemon 启动重放时，跳过 > 7 天的文件，移入 `~/.claude-forge/queue/dead/`
+- dead-letter 目录不自动清理，供人工审查
+
+### 决策 6：hook 脚本写队列方式 — fork 子进程同步写
+
+**方式**：在 `nc` 失败后，用 `( ... ) &` 后台子进程写文件，主进程立即 `exit 0`。
+
+**理由**：
+1. 主进程不阻塞，子进程独立 fork 不受父退出影响
+2. bash 原生支持，比 nohup/setsid 简单
+3. 单文件写入 syscall < 5ms，子进程开销可忽略
+
+---
+
+## 三、改动文件清单
+
+| 路径 | 改动类型 | 概述 |
+|---|---|---|
+| `src/hooks/user-prompt-submit.sh` | 修改 | nc 失败后 fork 子进程写队列文件 |
+| `src/hooks/pre-tool-use.sh` | 修改 | 同上，补充 socket 存在检测 |
+| `src/hooks/post-tool-use.sh` | 修改 | 同上 |
+| `src/hooks/notification.sh` | 修改 | 同上（低优先级，可选） |
+| `src/hooks/stop.sh` | **不改** | Stop 事件无重放意义 |
+| `src/core/queue/index.ts` | 新建 | 队列读写、prune、重放逻辑 |
+| `src/daemon/index.ts` | 修改 | Step 8 之后插入 `replayQueue()` 调用 |
+| `src/core/storage/events.ts` | 修改 | `writeEvent` catch 中识别并忽略 UNIQUE 冲突 |
+| `src/tests/queue.test.ts` | 新建 | 单元测试 |
+| `tests/integration/queue-replay.integration.test.ts` | 新建 | 集成测试 |
+
+---
+
+## 四、模块设计
+
+### `src/core/queue/index.ts` 接口
+
+```
+QUEUE_DIR = ~/.claude-forge/queue/
+DEAD_DIR  = ~/.claude-forge/queue/dead/
+MAX_FILES = 500
+TTL_DAYS  = 7
+
+enqueueEvent(event: ForgeEvent): void
+  - 文件名：<iso-timestamp>-<event_id>.json
+  - 写入前 prune：目录文件数 >= MAX_FILES 删最旧
+
+replayQueue(storage: SQLiteStorage): Promise<{ replayed, skipped, dead }>
+  - 读 QUEUE_DIR 下所有 *.json
+  - TTL > 7 天 → 移入 DEAD_DIR
+  - JSON.parse → storage.writeEvent
+  - UNIQUE constraint → skipped++（去重）
+  - 成功入库 → rm 文件 → replayed++
+  - JSON 损坏 → 移入 DEAD_DIR → dead++
+
+pruneQueue(): void  // 内部使用
+```
+
+### `src/daemon/index.ts` 改动
+
+在 socket `listen` 回调内（`logger.info('Socket 服务器已监听')` 之后）追加：
+
+```
+replayQueue(storage).then(({ replayed, skipped, dead }) => {
+  logger.info(`[Queue] Replay: ${replayed} replayed, ${skipped} skipped (dup), ${dead} dead-lettered`);
+});
+```
+
+### Hook 脚本改动模式
+
+```bash
+# 当前：
+RESPONSE=$(echo "$EVENT" | nc -U -w 10 "$SOCKET_PATH" 2>/dev/null)
+
+# 新增：nc 失败或 RESPONSE 为空时 fork 写队列
+if [ -z "$RESPONSE" ]; then
+  (
+    QUEUE_DIR="$HOME/.claude-forge/queue"
+    mkdir -p "$QUEUE_DIR"
+    TS=$(date -u +"%Y%m%dT%H%M%S")
+    UUID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || echo "$$-$RANDOM")
+    echo "$EVENT" > "$QUEUE_DIR/${TS}-${UUID}.json"
+  ) &
+fi
+```
+
+注意：macOS BSD `date` 不支持 `%N` 毫秒，所以 timestamp 用秒精度 + UUID 兜底唯一性。
+
+---
+
+## 五、风险点
+
+| 风险 | 概率 | 缓解方案 |
+|---|---|---|
+| 5 hook 同时写同名文件 | 低 | 文件名含 UUID（uuidgen），冲突 < 1/10^12 |
+| JSON 文件写一半被截断 | 低 | replayQueue catch JSON.parse → dead-letter |
+| daemon 重放时 socket 刚启动又挂掉 | 极低 | 每文件独立 try/catch，单失败不中断 |
+| queue 文件含旧 `_auth` token | 必然发生 | 重放走 `storage.writeEvent`，不经 socket 认证，Zod schema strip 自动剥离 |
+| 历史已丢失数据 | 已发生 | 本次范围外；可手动从 `~/.claude/projects/*/*.jsonl` 回填 |
+
+---
+
+## 六、测试策略
+
+### 单元测试 `src/tests/queue.test.ts`
+
+| 用例 | 验证点 |
+|---|---|
+| enqueueEvent 写入 | 文件存在，内容可 JSON.parse |
+| 超过 500 文件 prune 删最旧 | 写 510 个 → 文件数 = 500 |
+| replayQueue 成功 → 文件删除 | mock writeEvent 成功 → 文件消失 |
+| UNIQUE 冲突 → 文件删 + skipped++ | mock 抛 UNIQUE → skipped=1 |
+| JSON 损坏 → 移入 dead | 非法 JSON → dead 目录有 |
+| TTL 超期 → 移入 dead | mtime 8 天前 → dead 目录有 |
+
+### 集成测试 `tests/integration/queue-replay.integration.test.ts`
+
+1. 启动 daemon → 停止 daemon
+2. `enqueueEvent` 写入 3 个 ForgeEvent
+3. 重启 daemon
+4. 查 DB：3 条事件在 events 表
+5. 验证 queue/ 为空
+6. 第二次重启验证去重（skipped=3）
+
+### E2E 验证
+
+```bash
+./scripts/dev-daemon.sh restart &
+echo '{"session_id":"test","cwd":"/tmp"}' | bash src/hooks/user-prompt-submit.sh
+sqlite3 ~/.claude-forge/data.db "SELECT count(*) FROM events WHERE session_id='test';"
+# 期望：1
+```
+
+---
+
+## 七、执行步骤（自底向上）
+
+| # | 步骤 | 文件 |
+|---|---|---|
+| 1 | 实现队列模块（enqueueEvent + replayQueue + pruneQueue） | `src/core/queue/index.ts` |
+| 2 | 单元测试 queue.test.ts 全过 | `src/tests/queue.test.ts` |
+| 3 | `events.ts writeEvent` catch UNIQUE constraint 静默忽略 | `src/core/storage/events.ts` |
+| 4 | daemon/index.ts 调用 replayQueue（socket ready 后） | `src/daemon/index.ts` |
+| 5 | 修改 3 个 hook（user-prompt-submit、pre-tool-use、post-tool-use） | `src/hooks/*.sh` |
+| 6 | 集成测试通过 | `tests/integration/queue-replay.integration.test.ts` |
+| 7 | E2E：dev-daemon.sh restart 期间发事件验证 | 手工 + changelog |
+| 8 | 部署：cp hook 到 ~/.claude-forge/hooks/ + 重启 daemon | 手工 |