@winspan/claude-forge 8.51.1 → 8.54.3

package/ARCHITECTURE_ISSUES.md

@@ -1,249 +0,0 @@
-# 架构问题诊断报告
-
-## 问题汇总
-
-### 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

@@ -1,265 +0,0 @@
-<!-- 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)
-- **前端**: React 18 + Vite + Tailwind + react-router-dom + react-query + Recharts（`web/` 目录，build 后被 cp 到 dist/web/static/）
-- **测试**: 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:c726870f-5a76-4899-aaf8-bfe21e4ab45d -->
-```forge-resume-body
-## 上次工作续接
-
-⚠️ **IMPORTANT: 在开始新任务前，请先检查以下上下文**
-
-**上次在做**:
-- <task-notification>
-
-**上次活跃**: 刚刚
-
-**会话行为**: 工具调用 2480 次 | Agent 委托 70 次 (Explore, coder, planner) | Skill 调用 31 次
-
-_生成时间: 2026-05-18T09:01:35.482Z_
-```
-
-_生成时间: 2026-05-18T09:01:35.484Z_
-<!-- forge:resume-end:c726870f-5a76-4899-aaf8-bfe21e4ab45d -->