@winspan/claude-forge 8.53.2 → 8.54.4

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

@@ -1,232 +0,0 @@
-# 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

@@ -1,219 +0,0 @@
-# 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
-```