@winspan/claude-forge 8.39.0 → 8.50.6

package/.claude/CLAUDE.md

@@ -0,0 +1,17 @@
+
+<!-- forge:claudemd-prompt -->
+## 项目 CLAUDE.md 初始化
+
+当前项目尚未配置 CLAUDE.md 指令文件。请在会话开始时主动询问用户：
+
+> 检测到当前项目还没有 CLAUDE.md，要不要我根据项目技术栈自动生成一个？
+> 这可以帮助 Claude Code 更好地理解项目规范。
+
+如果用户同意，请执行以下步骤：
+1. 在项目根目录运行 `claude-forge claudemd detect` 查看检测到的技术栈
+2. 运行 `claude-forge claudemd init` 自动生成根目录的 CLAUDE.md
+3. 生成后阅读 CLAUDE.md 内容，确认合理性
+4. 告知用户可以手动编辑补充自定义规则
+
+如果用户拒绝，请删除本提示块。
+<!-- forge:end-claudemd-prompt -->

package/.eslintrc.js

@@ -0,0 +1,23 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier'
+  ],
+  plugins: ['@typescript-eslint'],
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+    project: './tsconfig.json'
+  },
+  env: {
+    node: true,
+    es2022: true
+  },
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    'no-console': 'off'
+  }
+};

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}

package/ARCHITECTURE_ISSUES.md

@@ -0,0 +1,249 @@
+# 架构问题诊断报告
+
+## 问题汇总
+
+### 1. Agent 详情弹窗空白 ❌
+
+**现象**：Web UI 点击 `bmad-spec-only` 等 methodology agents 时，右侧弹窗显示 "Agent not found"。
+
+**根因**：
+- `GET /api/agents/:name` 端点只读取 `~/.claude/agents/*.md` 文件
+- Methodology agents（`bmad-*`、`harness-*`）是 **builtin agents**，存在于 `AgentRegistry` 内存中，但没有写到磁盘
+- 前端调用 `/api/agents/bmad-spec-only` 返回 404
+
+**影响**：用户无法查看 methodology agents 的详细内容（prompt、tools、skills 等）。
+
+**修复方案**：
+```typescript
+// src/web/routes/agents.ts:49
+app.get('/api/agents/:name', (req, res) => {
+  const { name } = req.params;
+  
+  // 1. 先从 AgentRegistry 查找（支持 builtin agents）
+  const agent = ctx.agents?.get(name);
+  if (agent) {
+    res.json({
+      name: agent.name,
+      description: agent.description,
+      version: agent.version,
+      tools: agent.tools,
+      skills: agent.skills,
+      content: agent.content,
+      source: agent.source,  // 'builtin' | 'user' | 'project'
+    });
+    return;
+  }
+  
+  // 2. Fallback：读取磁盘文件（兼容旧逻辑）
+  const agentsDir = path.join(homedir(), '.claude', 'agents');
+  const filePath = path.join(agentsDir, `${name}.md`);
+  if (!fs.existsSync(filePath)) {
+    res.status(404).json({ error: 'Agent not found' });
+    return;
+  }
+  // ... 原有文件读取逻辑
+});
+```
+
+---
+
+### 2. Agent 不调用 ⚠️
+
+**现象**：用户反馈 "Agent 不调用"。
+
+**实际情况**：
+- 路由统计显示 **8 次 agent 路由**（最近 24 小时）
+- 路由到了 `bmad-spec-only`、`harness-investigate`、`researcher` 等
+- **Agent 路由正常工作**
+
+**可能误解**：
+1. 用户期望看到 "Agent 被调用" 的明确提示，但 UI 没有显示
+2. 用户期望 Agent 自动执行某些操作，但实际上 Agent 只是改变了 Claude 的行为模式（通过 system message 注入）
+
+**验证**：
+```sql
+SELECT session_id, routed_to_type, routed_to_name, created_at 
+FROM routing_events 
+ORDER BY created_at DESC LIMIT 5;
+
+-- 结果：
+-- f76bc6b1-...|agent|bmad-spec-only|2026-05-12 02:48:02
+-- f76bc6b1-...|agent|harness-investigate|2026-05-12 02:52:27
+```
+
+**改进方案**：
+1. **Web UI 增强**：在 Dashboard 显示 "当前 session 已路由到 X agent"
+2. **日志可见性**：在 Claude Code 对话中显示路由决策（可选，通过 `additionalContext` 注入）
+
+---
+
+### 3. Skill 不调用 ❌
+
+**现象**：没有任何 skill 调用记录。
+
+**根因**：
+- `routing_events` 表中 `routed_to_type='skill'` 的记录为 **0**
+- `skill_invocations` 表为空（没有任何 `skill_invoke` 工具调用）
+
+**原因分析**：
+
+#### 3.1 Skill 路由从未触发
+```typescript
+// src/daemon/handlers/user-prompt.ts:97-100
+if (this.router && !analysis.isMetaPrompt) {
+  decision = this.router.decide(...);
+  
+  if (decision.action.type === 'route_to_skill') {
+    // ← 这个分支从未执行过
+  }
+}
+```
+
+**可能原因**：
+- `ExperimentRouter.decide()` 从未返回 `route_to_skill` 决策
+- Skill 路由规则配置不完整或条件过严
+
+#### 3.2 Skill 只能手动触发
+根据代码注释：
+```typescript
+// src/daemon/handlers/user-prompt.ts:9-10
+// Skill 仅通过 slash command /<skill-name> 手动触发
+```
+
+这意味着 **Skill 不会自动路由**，必须用户显式输入 `/skill-name` 才能触发。
+
+**验证方案**：
+1. 检查 `ExperimentRouter` 的 skill 路由规则
+2. 测试手动触发：在 Claude Code 中输入 `/official-code-review` 等
+
+---
+
+### 4. 工作流触发条件不明 ❓
+
+**现象**：用户不清楚什么时候触发 workflow（BMAD / Harness）。
+
+**触发机制**：
+
+#### 4.1 Workflow 通过 `skill_invoke` 触发
+```typescript
+// src/skills/tools/skill-invoke.ts:63
+const workflowMeta = parseWorkflowMeta(reason);
+// 解析 "bmad/implement:user-auth" → { workflow: 'bmad', phase: 'implement', slug: 'user-auth' }
+
+// 如果 reason 符合格式，则记录到 skill_invocations 表
+if (workflowMeta) {
+  await storage.recordSkillInvocation({
+    workflow: workflowMeta.workflow,
+    phase: workflowMeta.phase,
+    feature_slug: workflowMeta.slug,
+    // ...
+  });
+}
+```
+
+#### 4.2 当前状态
+```sql
+SELECT COUNT(*) FROM skill_invocations;
+-- 结果：0（没有任何 workflow 记录）
+```
+
+**原因**：
+1. **Agent 从未调用 `skill_invoke` 工具**
+2. Methodology agents（`bmad-*`、`harness-*`）的 prompt 中虽然提到了 `skill_invoke`，但 Agent 实际执行时没有调用
+
+**触发条件**：
+1. 用户提问被路由到 methodology agent（如 `bmad-spec-only`）
+2. Agent 理解任务后，调用 `skill_invoke` 工具
+3. `reason` 参数格式为 `<workflow>/<phase>[:<slug>]`（如 `bmad/analyze:user-auth`）
+4. 系统自动记录到 `skill_invocations` 表，Web UI 显示 workflow 进度
+
+**为什么没有触发**：
+- Methodology agents 的 prompt 可能没有明确指示 "必须调用 skill_invoke"
+- Agent 可能直接回答问题，而不是调用工具
+- MCP server 的 `skill_invoke` 工具可能没有正确注册
+
+---
+
+## 架构设计问题
+
+### 1. Agent 详情端点设计不一致
+
+**问题**：
+- `GET /api/agents` 返回 `official` 数组（包含 builtin agents）
+- `GET /api/agents/:name` 只读取磁盘文件（不包含 builtin agents）
+
+**影响**：前端列表显示 19 个 agents，但点击 builtin agents 时返回 404。
+
+**建议**：统一从 `AgentRegistry` 读取，磁盘文件作为 fallback。
+
+---
+
+### 2. Skill 路由机制不清晰
+
+**问题**：
+- 代码注释说 "Skill 仅通过 slash command 手动触发"
+- 但 `ExperimentRouter` 有 `route_to_skill` 决策类型
+- 两者矛盾
+
+**建议**：
+1. 如果 Skill 只支持手动触发，删除 `route_to_skill` 路由逻辑
+2. 如果 Skill 支持自动路由，补充路由规则并更新文档
+
+---
+
+### 3. Workflow 触发依赖隐式行为
+
+**问题**：
+- Workflow 触发依赖 Agent 主动调用 `skill_invoke` 工具
+- 但 Agent 的 prompt 中没有强制要求调用
+- 导致 workflow 从未被触发
+
+**建议**：
+1. 在 methodology agents 的 prompt 中明确指示：
+   ```markdown
+   ## 执行流程
+   
+   1. 理解任务后，**必须**调用 `skill_invoke` 工具
+   2. `reason` 参数格式：`bmad/<phase>:<feature-slug>`
+   3. 例如：`skill_invoke(skill_id="official-code-review", reason="bmad/analyze:user-auth")`
+   ```
+
+2. 或者改为 **自动记录 workflow**：
+   - 当 Agent 被路由时，自动创建 workflow 记录
+   - 不依赖 Agent 调用 `skill_invoke`
+
+---
+
+## 优先级修复建议
+
+### P0（立即修复）
+1. **修复 Agent 详情 404** — 让 `/api/agents/:name` 支持 builtin agents
+2. **验证 MCP `skill_invoke` 工具** — 确认工具已正确注册
+
+### P1（短期优化）
+1. **增强 Web UI** — 显示当前 session 的路由状态
+2. **补充 Skill 路由规则** — 或明确文档说明 "仅手动触发"
+
+### P2（长期改进）
+1. **简化 Workflow 触发** — 不依赖 Agent 主动调用工具
+2. **统一 Agent 存储** — builtin / user / project 统一接口
+
+---
+
+## 测试验证清单
+
+- [ ] `curl http://127.0.0.1:3721/api/agents/bmad-spec-only` 返回完整内容（不是 404）
+- [ ] Web UI 点击 `bmad-spec-only` 显示详情弹窗
+- [ ] 在 Claude Code 中输入 `/official-code-review` 触发 skill
+- [ ] `sqlite3 ~/.claude-forge/data.db "SELECT * FROM skill_invocations LIMIT 1;"` 有记录
+- [ ] Web UI Workflows 页面显示进度条
+
+---
+
+## 相关文件
+
+- `src/web/routes/agents.ts:49` — Agent 详情端点
+- `src/daemon/handlers/user-prompt.ts:97-140` — Agent/Skill 路由逻辑
+- `src/skills/tools/skill-invoke.ts:63` — Workflow 解析
+- `src/agents/methodologies/agent-builder.ts` — Methodology agent prompt 生成
+- `web/src/components/AgentCard.tsx` — 前端 Agent 卡片组件

package/CLAUDE.md

@@ -0,0 +1,265 @@
+<!-- forge:claudemd-auto -->
+# claude-forge 工作区规范
+
+## 自检（每次响应前必读）
+
+**在开始任何操作前，先问自己**：
+
+1. 我是否要修改 ≥2 个文件？
+2. 我是否要修改 ≥10 行代码？
+3. 这是否是新功能/重构/Bug 修复？
+4. 我修改的代码所在模块**测试覆盖率 < 50%** 吗？
+
+**如果 1-3 任一答案是"是"，且我没有 spawn Agent**：
+- ❌ 停下来 → 重新评估例外 → 否则立即 spawn Agent
+
+**如果 4 答案是"是"**（改老代码 + 测试薄弱）：
+- ❌ 不要 spawn 普通 `coder` / `planner`
+- ✅ 必须走 **Harness 或 Hybrid 工作流**（详见下方「工作流升级判定」）
+
+**违规示例**：
+- "修复 daemon handler bug（改老代码 + 0 测试）" → 应走 `harness-hotfix`，不是 `coder`
+- "重构 738 行字面量为 .md 文件" → 应走 `refactor-safe`，不是 `coder`
+- "新功能加在 hook 脚本" → 应走 `hybrid-feature-with-safety`，不是 `planner+coder`
+
+---
+
+## 核心行为规则
+
+- Do what has been asked; nothing more, nothing less
+- NEVER create files unless absolutely necessary
+- ALWAYS prefer editing existing files to creating new ones
+- ALWAYS read a file before editing it
+- Never continuously check status after spawning agents — wait for results
+
+---
+
+## Two-Phase Workflow (BMAD 默认路径)
+
+**适用范围**：≥3 文件改动 / 新功能 / 重构 / 架构调整
+**前提**：通过「工作流升级判定」确认为 BMAD 路径（测试覆盖充分 / 全新模块）
+**如果改老代码 + 测试薄弱** → 改走 Harness/Hybrid 三阶段（见下方）
+
+### Phase 1: Generate Spec
+
+1. Spawn planner/researcher agent with `run_in_background: true`
+2. Agent 输出 `docs/design/[task]-spec-YYYYMMDD-HHMM.md`，包含：
+   - 目标、改动文件清单、关键设计决策、风险点、测试策略
+   - **禁止写任何代码**
+3. 主线程告诉用户"已 spawn planner，等待 spec 生成"，**然后结束响应**
+
+### Phase 1.5: User Review (Critical Gate)
+
+Agent 完成后，**主线程必须停止并等待用户确认**：
+
+```
+设计方案已生成：docs/design/xxx-spec.md
+
+请 review 后回复：
+- "批准" / "approve" → 我会 spawn coder 实现
+- "修改 [意见]" → 我会调整 spec
+- "取消" → 停止任务
+```
+
+**绝对禁止**：
+- ❌ 主线程自行判断 spec 质量并进入 Phase 2
+- ❌ 主线程直接 spawn coder 而不等用户确认
+
+### Phase 2: Implement per Spec
+
+收到用户"批准"后：
+1. Spawn coder agent with `run_in_background: true`
+2. 严格按 spec 执行，完成后写 `docs/implementation/[task]-changelog-YYYYMMDD-HHMM.md`
+
+### 例外
+
+可跳过两阶段：
+- 单文件 1-2 行修改
+- 用户明确说"不需要 spec"
+- 纯查询/调研任务
+
+---
+
+## Agent 委托规则
+
+### 默认行为：spawn Agent
+
+接到任务时，**第一反应是 spawn Agent**。主线程只做协调。
+
+### 不 spawn 的例外（仅 4 条）
+
+1. **单行 typo**：1 文件 1 行拼写错误
+2. **协调与汇总**：整合 Agent 结果
+3. **元任务（极小改动）**：git commit/push、daemon 启停、单行规则调整
+4. **即时问答**：不涉及代码/文件的纯对话
+
+**注意**：
+- 例外 #3 不包括"重构 CLAUDE.md"、"修改多个配置文件"等大改动
+- 如果改动 ≥2 文件或 ≥10 行，必须 spawn Agent
+
+### 强制 spawn 的场景
+
+以下必须 spawn Agent：
+- 查/找/看/列出 → Explore agent
+- 函数分析/代码阅读 → doc-reviewer
+- 单文件 2+ 行修改 → coder
+- 实现/修复/重构/优化 → 对应 agent
+
+### 强制理由声明
+
+每次不 spawn 时，必须在响应开头说明：
+
+> 不 spawn 理由：例外 #N [具体原因]
+
+---
+
+## 工作流升级判定（spawn agent 前必查）
+
+**默认是 BMAD（planner+coder）**，但满足下表条件**必须升级到 Harness/Hybrid**。
+
+### 判定表
+
+| 任务特征 | 推荐 agent | 工作流序列 |
+|---------|-----------|----------|
+| **改老代码 + 模块测试覆盖 < 50%** | `refactor-safe` | safety-net → design → implement → test → review |
+| **已知原因的 Bug 修复**（紧急/明确）| `harness-hotfix` | safety-net → fix → verify |
+| **未知/偶发 Bug**（需先定位）| `harness-debug-full` | reproduce → safety-net → root-cause → fix → verify |
+| **新功能改老代码 + 测试薄弱** | `hybrid-feature-with-safety` | safety-net → analyze → design → implement → test → review |
+| **先修 bug 再加功能** | `hybrid-fix-then-feature` | reproduce → fix → verify → design → implement → review |
+| **全新模块 / 测试充分**（覆盖 ≥50%）| `planner` + `coder` | BMAD analyze → design → implement |
+| **纯调研 / 单行 typo / 元任务** | 不 spawn 或 `Explore` | — |
+
+### 测试覆盖快速判定
+
+修改 `src/<module>/` 前必查：
+
+```bash
+SRC=$(find src/<module> -name "*.ts" -not -name "*.test.ts" 2>/dev/null | wc -l)
+TST=$(find tests/unit/<module> src/tests -name "*.test.ts" 2>/dev/null | wc -l)
+echo "ratio: $TST / $SRC"
+```
+
+`TST/SRC < 50%` → **触发 Harness safety-net 阶段**（不要直接改代码）
+
+### 项目模块覆盖现状（提醒）
+
+| 模块 | 覆盖判定 | 默认走 |
+|------|---------|--------|
+| `src/daemon/handlers/` | 部分（≥50%）| BMAD，但 hotfix 类 bug 走 `harness-hotfix` |
+| `src/daemon/services/` | **零测试** | **Harness/Hybrid 强制** |
+| `src/core/storage/` | 高（≥80%）| BMAD |
+| `src/core/queue/` | 高（新写时已加）| BMAD |
+| `src/skills/` | 中（~40%）| 大改走 `refactor-safe` |
+| `src/web/routes/` | 中 | BMAD |
+| `src/hooks/*.sh` | 0（无 sh 测试）| 改 hook 必走 Hybrid |
+| `src/claudemd/` | 低 | `refactor-safe` |
+
+### 违规自查
+
+过去 5 次任务全踩坑，请引以为戒：
+
+- ❌ "修复 daemon schema 收紧拒收 bug"（改 events.ts + 5 个 hook）→ 走了 `coder`，应走 `harness-hotfix`
+- ❌ "Official Skills 数据分离"（重构 738 行老代码）→ 走了 `planner+coder`，应走 `refactor-safe`
+- ❌ "Hook 失败缓冲队列"（新功能 + 改 4 个老 hook）→ 走了 `planner+coder`，应走 `hybrid-feature-with-safety`
+
+**判定时机**：在「自检」之后、「Two-Phase Workflow」之前。判定结果若是 Harness/Hybrid，跳过 Two-Phase，直接 spawn 对应 agent。
+
+---
+
+## 并发规则
+
+- All operations MUST be concurrent/parallel in ONE message
+- ALWAYS batch ALL agents in ONE message with `run_in_background: true`
+- ALWAYS batch ALL file reads/writes/edits in ONE message
+- ALWAYS batch ALL terminal operations in ONE Bash message
+
+---
+
+## 项目特定信息
+
+### 技术栈
+
+- **语言**: TypeScript (Node.js 24+)
+- **数据库**: SQLite (better-sqlite3)
+- **前端**: 原生 HTML + Vanilla JS（单文件 SPA），无打包
+- **测试**: Vitest
+
+### 架构要点
+
+**分层**：
+- `src/cli/` — CLI 命令
+- `src/daemon/` — 后台守护进程（事件处理）
+- `src/web/` — Web 仪表盘
+- `src/core/` — 共享核心（storage/config/types）
+- `src/claudemd/` — CLAUDE.md 生成器
+- `src/skills/` — Skill 匹配与注入
+
+**存储**：
+- 主库：`~/.claude-forge/data.db`
+- 表：sessions, events, tasks, routing_events, skill_invocations, token_usage
+
+### 开发规范
+
+**构建与测试**：
+```bash
+npm run build        # 构建前后端
+npm test             # 运行测试
+./scripts/dev-daemon.sh restart  # 重启 daemon
+```
+
+**守护进程事件推送**：
+- PreToolUse / PostToolUse / UserPromptSubmit / Stop / Notification
+- 通过 Unix socket 推送到 daemon
+
+**注意**：
+- daemon 和 CLI 都用系统 node（v26）
+- better-sqlite3 12.10.0 支持 v26
+- 修改 schema 需要手动迁移（无自动 migration）
+
+### 命名规范
+
+**文件命名**：
+- 统一使用 kebab-case：`task-segmenter.ts`、`user-prompt.ts`
+- 禁止混用 camelCase：~~`taskSegmenter.ts`~~
+- 测试文件：`*.test.ts`（单元测试）、`*.integration.test.ts`（集成测试）
+
+**函数命名**：
+- 查询操作统一用 `query` 前缀：`queryEvents()`、`queryTasks()`
+- 写入操作统一用 `write` 前缀：`writeEvent()`、`writeTask()`
+- 列表操作统一用 `list` 前缀：`listSessions()`、`listSkills()`
+- 获取单个资源用 `get` 前缀：`getSession()`、`getTask()`
+- 禁止混用：~~`fetchEvents()`~~、~~`findTasks()`~~、~~`retrieveSessions()`~~
+
+**变量命名**：
+- 布尔值用 `is`/`has`/`should` 前缀：`isValid`、`hasError`、`shouldRetry`
+- 时间戳统一用 `timestamp` 或 `ts`：`event.timestamp`、`routing.ts`
+- Session ID 统一用 `session_id`（数据库）或 `sessionId`（代码）
+
+**常量命名**：
+- 全大写 + 下划线：`MAX_BUFFER_SIZE`、`TASK_SWITCH_MINUTES`
+- 配置常量放在文件顶部或 `src/core/constants.ts`
+
+---
+
+## 上次工作续接
+
+（由 daemon 自动更新，记录最近任务上下文）
+
+<!-- forge:resume-begin:3db22ee6-9c91-4b8f-a164-cb0b086497e5 -->
+```forge-resume-body
+## 上次工作续接
+
+⚠️ **IMPORTANT: 在开始新任务前，请先检查以下上下文**
+
+**上次在做**:
+- commit + bump 8.50.6 + push
+
+**上次活跃**: 刚刚
+
+**会话行为**: 工具调用 1003 次 | Agent 委托 18 次 (Explore, coder, harness-hotfix) | Skill 调用 8 次
+
+_生成时间: 2026-05-18T01:42:42.936Z_
+```
+
+_生成时间: 2026-05-18T01:42:42.937Z_
+<!-- forge:resume-end:3db22ee6-9c91-4b8f-a164-cb0b086497e5 -->