@winspan/claude-forge 8.41.0 → 8.51.0

package/dist/web/static/assets/task-title-BhOcemuR.js

@@ -0,0 +1,2 @@
+function e(n,t){if(!(n!=null&&n.trim()))return"(无标题)";const m=n.trim();if(m.startsWith("<task-notification>")){const s=m.match(/<summary>([\s\S]*?)<\/summary>/);if(s&&s[1].trim()){const r=s[1].trim();return r.length>80?r.slice(0,80)+"…":r}if(t){const r=t.match(/<summary>([\s\S]*?)<\/summary>/);if(r&&r[1].trim()){const a=r[1].trim();return a.length>80?a.slice(0,80)+"…":a}return`(子任务回调) — ${t.trim().slice(0,60).replace(/\s+/g," ")}${t.trim().length>60?"…":""}`}return"(子任务回调)"}return m.length>80?m.slice(0,80)+"…":m}export{e as n};
+//# sourceMappingURL=task-title-BhOcemuR.js.map

package/dist/web/static/assets/task-title-BhOcemuR.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-title-BhOcemuR.js","sources":["../../src/utils/task-title.ts"],"sourcesContent":["/**\n * normalizeTaskTitle — pure helper for rendering task titles.\n *\n * Some tasks are stored with their title set to the raw <task-notification>\n * XML blob (sub-agent completion callbacks). When the blob is truncated to\n * 19 characters (just the opening tag), the title is unreadable.\n *\n * This function detects that case and falls back to `firstPrompt` — the first\n * UserPromptSubmit user_prompt for the task, supplied from the backend via the\n * `first_prompt` field in /api/tasks responses.\n *\n * No React dependency. Safe to import in unit tests.\n */\n\nconst MAX_LEN = 80\n\nexport function normalizeTaskTitle(\n  title: string | null | undefined,\n  firstPrompt?: string | null,\n): string {\n  if (!title?.trim()) return '(无标题)'\n  const trimmed = title.trim()\n\n  // Detect <task-notification> XML callback blobs (including bare 19-char token)\n  if (trimmed.startsWith('<task-notification>')) {\n    // First, try to extract <summary> from the title itself (full XML blob)\n    const matchInTitle = trimmed.match(/<summary>([\\s\\S]*?)<\\/summary>/)\n    if (matchInTitle && matchInTitle[1].trim()) {\n      const summary = matchInTitle[1].trim()\n      return summary.length > MAX_LEN ? summary.slice(0, MAX_LEN) + '…' : summary\n    }\n\n    // Title has no summary (e.g. bare 19-char token) — try firstPrompt\n    if (firstPrompt) {\n      const matchInPrompt = firstPrompt.match(/<summary>([\\s\\S]*?)<\\/summary>/)\n      if (matchInPrompt && matchInPrompt[1].trim()) {\n        const summary = matchInPrompt[1].trim()\n        return summary.length > MAX_LEN ? summary.slice(0, MAX_LEN) + '…' : summary\n      }\n      // Has firstPrompt but no <summary> tag — show head of prompt\n      const head = firstPrompt.trim().slice(0, 60).replace(/\\s+/g, ' ')\n      return `(子任务回调) — ${head}${firstPrompt.trim().length > 60 ? '…' : ''}`\n    }\n\n    return '(子任务回调)'\n  }\n\n  return trimmed.length > MAX_LEN ? trimmed.slice(0, MAX_LEN) + '…' : trimmed\n}\n"],"names":["normalizeTaskTitle","title","firstPrompt","trimmed","matchInTitle","summary","matchInPrompt"],"mappings":"AAgBO,SAASA,EACdC,EACAC,EACQ,CACR,GAAI,EAACD,GAAA,MAAAA,EAAO,QAAQ,MAAO,QAC3B,MAAME,EAAUF,EAAM,KAAA,EAGtB,GAAIE,EAAQ,WAAW,qBAAqB,EAAG,CAE7C,MAAMC,EAAeD,EAAQ,MAAM,gCAAgC,EACnE,GAAIC,GAAgBA,EAAa,CAAC,EAAE,OAAQ,CAC1C,MAAMC,EAAUD,EAAa,CAAC,EAAE,KAAA,EAChC,OAAOC,EAAQ,OAAS,GAAUA,EAAQ,MAAM,EAAG,EAAO,EAAI,IAAMA,CACtE,CAGA,GAAIH,EAAa,CACf,MAAMI,EAAgBJ,EAAY,MAAM,gCAAgC,EACxE,GAAII,GAAiBA,EAAc,CAAC,EAAE,OAAQ,CAC5C,MAAMD,EAAUC,EAAc,CAAC,EAAE,KAAA,EACjC,OAAOD,EAAQ,OAAS,GAAUA,EAAQ,MAAM,EAAG,EAAO,EAAI,IAAMA,CACtE,CAGA,MAAO,aADMH,EAAY,KAAA,EAAO,MAAM,EAAG,EAAE,EAAE,QAAQ,OAAQ,GAAG,CACxC,GAAGA,EAAY,OAAO,OAAS,GAAK,IAAM,EAAE,EACtE,CAEA,MAAO,SACT,CAEA,OAAOC,EAAQ,OAAS,GAAUA,EAAQ,MAAM,EAAG,EAAO,EAAI,IAAMA,CACtE"}

package/dist/web/static/assets/time-Bxuk0M-C.js

@@ -0,0 +1,2 @@
+function n(t){if(!t)return new Date(0);const e=t.trim();return e.endsWith("Z")||/[+-]\d{2}:\d{2}$/.test(e)?new Date(e):new Date(e+"Z")}export{n as p};
+//# sourceMappingURL=time-Bxuk0M-C.js.map

package/dist/web/static/assets/time-Bxuk0M-C.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-Bxuk0M-C.js","sources":["../../src/utils/time.ts"],"sourcesContent":["/**\n * SQLite stores ISO timestamps without 'Z' suffix.\n * JS `new Date()` treats such strings as local time, causing an offset.\n * This helper ensures the timestamp is always parsed as UTC.\n */\nexport function parseUTC(timestamp: string | null | undefined): Date {\n  if (!timestamp) return new Date(0);\n  const s = timestamp.trim();\n  if (s.endsWith('Z') || /[+-]\\d{2}:\\d{2}$/.test(s)) {\n    return new Date(s);\n  }\n  return new Date(s + 'Z');\n}\n"],"names":["parseUTC","timestamp","s"],"mappings":"AAKO,SAASA,EAASC,EAA4C,CACnE,GAAI,CAACA,EAAW,OAAO,IAAI,KAAK,CAAC,EACjC,MAAMC,EAAID,EAAU,KAAA,EACpB,OAAIC,EAAE,SAAS,GAAG,GAAK,mBAAmB,KAAKA,CAAC,EACvC,IAAI,KAAKA,CAAC,EAEZ,IAAI,KAAKA,EAAI,GAAG,CACzB"}

package/dist/web/static/index.html

@@ -5,14 +5,14 @@
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Claude Forge 管理后台</title>
-    <script type="module" crossorigin src="/assets/index-Cgr9qMtq.js"></script>
+    <script type="module" crossorigin src="/assets/index-CBX47X8l.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/react-vendor-CSp-GLFF.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-CMMjVdZs.js">
-    <link rel="modulepreload" crossorigin href="/assets/react-router-I-HqunH7.js">
+    <link rel="modulepreload" crossorigin href="/assets/react-router-r79dBVy4.js">
     <link rel="modulepreload" crossorigin href="/assets/query-C99w429o.js">
     <link rel="modulepreload" crossorigin href="/assets/syntax-highlighter-44FakypI.js">
-    <link rel="modulepreload" crossorigin href="/assets/lucide-53bR2rki.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-CngWb5gC.css">
+    <link rel="modulepreload" crossorigin href="/assets/lucide-Bs_edTLa.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-DjIoMdoR.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/concurrent-agents.md

@@ -0,0 +1,129 @@
+# 并发 Agent 功能
+
+## 概述
+
+支持一次路由到多个 agent 并发执行，提升吞吐 3-5x。适用于多个独立任务可以并行处理的场景。
+
+## 配置示例
+
+在 `src/engine/conventions/routing.yaml` 或用户覆盖文件 `~/.claude-forge/routing.yaml` 中添加规则：
+
+```yaml
+schemaVersion: "1.0"
+rules:
+  - when:
+      taskType: multi_domain
+      complexity: [moderate, complex]
+    action:
+      type: route_to_agent_group
+      agents:
+        - name: coder
+          focus: "前端 UI 实现"
+        - name: tester
+          focus: "单元测试编写"
+        - name: doc-reviewer
+          focus: "文档审校"
+    rationale: "三个任务独立，可并发执行"
+
+  - when:
+      default: true
+    action:
+      type: route_to_skill
+      strategy: best_match
+```
+
+## 使用方式
+
+### 用户输入
+
+```
+开启多个 Agent 进行后续任务
+```
+
+### 系统响应
+
+```
+根据路由决策，请并发启动以下 agent：
+
+1. **coder** — 前端 UI 实现
+2. **tester** — 单元测试编写
+3. **doc-reviewer** — 文档审校
+
+在同一个回答里发起所有 Task 调用。
+```
+
+### 实际执行
+
+系统会在同一个响应中并发调用多个 Agent 工具：
+
+```typescript
+// 伪代码示例
+Agent({ subagent_type: "coder", prompt: "实现前端 UI", run_in_background: true });
+Agent({ subagent_type: "tester", prompt: "编写单元测试", run_in_background: true });
+Agent({ subagent_type: "doc-reviewer", prompt: "审校文档", run_in_background: true });
+```
+
+## 限制
+
+- **最多并发 5 个 agent**：避免资源争抢和上下文混乱
+- **任务必须独立**：agent 之间不能有依赖关系（如 A 的输出是 B 的输入）
+- **每个 agent 必须设置 `run_in_background=true`**：确保并发执行而非串行等待
+
+## 监控
+
+RoutingObserver 会检查：
+
+- 是否调用了推荐的 agent
+- 是否设置了 `run_in_background=true`
+- 部分遵守（推荐 3 个调用 2 个）不算 refusal
+
+## 适用场景
+
+✅ **适合并发**：
+- 前端 + 后端 + 测试独立开发
+- 多个模块的文档审校
+- 不同子系统的性能优化
+
+❌ **不适合并发**：
+- 需要先设计架构再实现代码（有依赖）
+- 需要先修复 bug 再编写测试（有顺序）
+- 需要先重构再优化性能（有前置条件）
+
+## 配置验证
+
+验证规则是否正确加载：
+
+```bash
+# 查看当前加载的路由规则
+npx tsx scripts/demo-routing.ts
+
+# 或通过 Web UI 查看
+# 访问 http://localhost:3000/routing
+```
+
+## 故障排查
+
+### 问题：agent 没有并发执行
+
+**原因**：可能是 `run_in_background` 未设置或路由决策未生效。
+
+**解决**：
+1. 检查 `routing.yaml` 中的 `when` 条件是否匹配
+2. 确认 RoutingObserver 日志中是否有 "route_to_agent_group" 决策
+3. 验证 Agent 调用时是否传递了 `run_in_background: true`
+
+### 问题：部分 agent 被跳过
+
+**原因**：可能是某些 agent 被自动禁用（auto-disable）。
+
+**解决**：
+1. 检查 `~/.claude-forge/auto-disable.json` 中的禁用记录
+2. 通过 Web UI 手动启用被禁用的 agent
+3. 调整 auto-disable 阈值（默认连续 3 次拒绝后禁用）
+
+## 相关文件
+
+- `src/engine/agent-router.ts` — 路由决策核心逻辑
+- `src/engine/conventions/routing.yaml` — 默认路由规则
+- `tests/unit/agent-router-concurrent.test.ts` — 并发路由单元测试
+- `src/daemon/handlers/routing-observer.ts` — 路由遵守度监控

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
+```