@winspan/claude-forge 8.51.1 → 8.54.3

package/CLAUDE.md.backup

@@ -1,488 +0,0 @@
-<!-- forge:claudemd-auto -->
-# claude-forge 工作区规范
-
-## Behavioral Rules (Always Enforced)
-
-- Do what has been asked; nothing more, nothing less
-- NEVER create files unless they're absolutely necessary for achieving your goal
-- ALWAYS prefer editing an existing file to creating a new one
-- NEVER proactively create documentation files (*.md) or README files unless explicitly requested
-- ALWAYS read a file before editing it
-- Never continuously check status after spawning a swarm — wait for results
-
-### Two-Phase Workflow (Design-First for Non-Trivial Tasks)
-
-**适用范围**：≥3 文件改动 / 新功能 / 重构 / 架构调整
-
-#### Phase 1: Generate Spec (Mandatory)
-
-1. **Spawn planner/researcher agent** with `run_in_background: true`
-2. **Agent 任务**：
-   - 调研现有代码和架构
-   - 设计实现方案
-   - 将方案写入 `docs/design/[task]-spec-YYYYMMDD-HHMM.md`
-   - 包含：目标、改动文件清单、关键设计决策、风险点、测试策略
-   - **禁止写任何代码，只输出设计文档**
-3. **主线程行为**：
-   - 告诉用户"已 spawn planner，等待 spec 生成"
-   - **然后结束响应，不做任何其他操作**
-   - 等待 agent 完成通知
-
-#### Phase 1.5: User Review (Critical Gate)
-
-Agent 完成后，**主线程必须停止并等待用户确认**：
-
-```
-设计方案已生成：docs/design/xxx-spec.md
-
-请 review 后回复：
-- "批准" / "approve" / "开始实现" → 我会 spawn coder 实现
-- "修改 [具体意见]" → 我会让 planner 调整 spec
-- "取消" / "cancel" → 停止任务
-```
-
-**绝对禁止**：
-- ❌ 主线程自行判断 spec 质量并进入 Phase 2
-- ❌ 主线程说"spec 看起来不错，我开始实现"
-- ❌ 主线程直接 spawn coder 而不等用户确认
-
-**只有收到用户明确的批准指令，才能进入 Phase 2。**
-
-#### Phase 2: Implement per Spec
-
-收到用户"批准"后：
-
-1. Spawn coder agent with `run_in_background: true`
-2. **Agent 任务**：
-   - 严格按 `docs/design/xxx-spec.md` 执行
-   - 不偏离 spec（如需调整，先更新 spec 并再次请求批准）
-   - 完成后写 `docs/implementation/[task]-changelog-YYYYMMDD-HHMM.md` 记录实际改动
-3. **主线程行为**：
-   - 告诉用户"已 spawn coder，按 spec 实现"
-   - 等待 agent 完成通知
-   - 汇总结果
-
-#### 例外：简单任务可跳过
-
-以下情况可以跳过两阶段，直接实现：
-- 单文件 1-2 行修改（typo 级别）
-- 用户明确说"不需要 spec，直接做"
-- 纯查询/调研任务（不涉及代码改动）
-
-**其他所有情况必须走两阶段流程。**
-
-### MANDATORY Agent Delegation Rule (NEVER SKIP)
-
-#### 默认行为：spawn Agent，不是自己做
-
-接到任务时，**第一反应是 spawn Agent**。"我自己做" 是需要主动决策并解释的例外，不是默认。
-
-#### 激进策略：最大化 Agent 使用（提高效率）
-
-**几乎所有任务都 spawn Agent**，包括查询、调研、代码阅读。主线程只做极简协调。
-
-#### 不 spawn 的例外清单（仅这 4 条）
-
-只有以下情况允许主线程直接处理：
-
-1. **单行 typo**：1 个文件，1 行，纯拼写错误（如 `fucntion` → `function`）
-2. **协调与汇总**：把多个 Agent 的结果整合给用户，或等待 Agent 完成通知
-3. **元任务（meta-task）**：修改本规则文件本身、git commit/push、配置 daemon 等"工具的工具"操作
-4. **即时问答**：用户问"现在几点"、"你是谁"、"帮助命令是什么"等不涉及代码/文件的纯对话
-
-**以下情况必须 spawn Agent（不再是例外）**：
-- ❌ ~~"查看文件内容"~~ → ✅ spawn Explore agent 并行搜索
-- ❌ ~~"这个函数做什么"~~ → ✅ spawn doc-reviewer 深度分析
-- ❌ ~~"找出 X 在哪"~~ → ✅ spawn Explore agent 定位
-- ❌ ~~"单文件 3 行修改"~~ → ✅ spawn coder（除非是 1 行 typo）
-- ❌ ~~"读取了解上下文"~~ → ✅ spawn researcher 系统化调研
-
-#### 强制理由声明
-
-**每次决定不 spawn 时，必须在响应开头用一句话说明理由**，格式：
-
-> 不 spawn 理由：例外 #N [具体原因]
-
-如果一句话写不出像样的理由 → 说明应该 spawn，立刻改正。
-
-写理由的目的不是仪式感，而是**让"自己做"成为可见的决策**。决策可见，才能被纠正。
-
-#### 触发关键词（强制 spawn）
-
-只要用户的 prompt 出现以下**任意一个**词或类似意图，**直接 spawn**，不要犹豫：
-
-**实现类**：
-- 实现 / implement / 开发 / develop / 创建 / create / 添加 / add / 构建 / build
-
-**修改类**：
-- 修复 / fix / 调试 / debug / 改 / change / 更新 / update / 升级 / upgrade
-
-**优化类**：
-- 重构 / refactor / 优化 / optimize / 性能 / performance / 清理 / cleanup
-
-**调研类**（新增，不再是例外）：
-- 调研 / research / 分析 / analyze / 查 / find / 找 / search / 看 / read / 列出 / list / 梳理 / review
-
-**测试类**：
-- 测试 / test / 验证 / verify / 检查 / check / 审查 / audit
-
-#### 最小 Agent 模式
-
-不需要每次都开完整 pipeline。简单任务用单个 Agent 就行：
-
-```javascript
-// 单个 Agent 即可
-Agent({
-  description: "修复 X bug",
-  subagent_type: "coder",
-  prompt: "具体任务描述，包含文件路径和修改要求..."
-})
-```
-
-复杂任务才 spawn 多个 Agent 或 pipeline（参考下方 Pipeline Templates）。
-
-#### 自检流程（接到任务后必走）
-
-1. 这是不是 5 条例外里的？→ 是 → 直接做（写出理由）
-2. 不是 → spawn Agent。多文件改动 → 多个 Agent；调研 → researcher；测试 → tester；最不济单个 coder
-
-**违规判定**：一次响应里执行了 Edit/Write 修改 ≥ 2 个文件 + 没写"不 spawn 理由"=违规。
-
-## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS
-
-- All operations MUST be concurrent/parallel in a single message
-- Use Claude Code's Task tool for spawning agents, not just MCP
-
-**Mandatory patterns:**
-- ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
-- ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
-- ALWAYS batch ALL file reads/writes/edits in ONE message
-- ALWAYS batch ALL terminal operations in ONE Bash message
-
----
-
-## Swarm Orchestration (AGGRESSIVE PARALLELISM)
-
-**核心原则：成本不是考量因素，响应速度和覆盖面是唯一目标。**
-
-- **默认开多个 Agent，不要节约** — 只要任务不是"单行修改/问候语"，一律 spawn swarm
-- **宁滥勿缺** — 拿不准就开 pipeline；多开一个 reviewer/tester 的边际成本 << 漏掉问题的代价
-- **永远并行，不要串行** — 所有能并行的 Agent 在 ONE message 里同时 spawn
-- **不要自己直接做复杂任务** — 主线程只负责协调，实现/调研/测试/审查全部委托
-
-### Auto-Start Swarm Protocol
-
-#### 不确定是否需要 Pipeline？调用 pipeline_suggest
-
-如果你不确定当前任务是否需要启动 swarm pipeline，可以调用 MCP 工具 `pipeline_suggest` 获取建议：
-
-```typescript
-// 通过 MCP 调用（如果可用）
-pipeline_suggest({
-  task_description: "修复用户登录时的 session 过期问题",
-  file_count: 5,
-  is_bug_fix: true
-})
-
-// 返回
-{
-  should_invoke: true,
-  pipeline_type: "bug_fix",
-  pipeline_code: "Task({ subagent_type: 'researcher', name: 'investigator', ... })\n...",
-  reason: "Bug 修复任务建议使用 Pipeline（调查 → 修复 → 验证）"
-}
-```
-
-**决策逻辑**：
-- `file_count >= 3` OR `is_new_feature` OR `is_refactor` OR `is_bug_fix` OR `is_performance` → 建议使用 Pipeline
-- 返回可直接复制的 Task 调用代码
-
-**10 种内置模板**：
-- Bug Fix：investigator → fixer → verifier（3 agents）
-- Feature：analyst → designer → developer → tester → reviewer（5 agents）
-- Refactor：safety-net → planner → refactorer → verifier（4 agents）
-- Investigation：reproducer → analyst（2 agents）
-- Performance：benchmarker → analyst → optimizer → verifier（4 agents）
-- BMAD Feature：product-analyst → architect → developer → qa → reviewer（5 agents，完整产品开发）
-- Harness Safe Refactor：safety-net → analyzer → planner → executor → validator（5 agents，先织安全网再动代码）
-- Harness Debug：reproducer → tracer → root-cause → fixer → verifier（5 agents，系统化排查）
-- Migration：impact-analyst + safety-net → planner → migrator → verifier（5 agents，技术迁移）
-- Security Audit：threat-modeler → code-auditor → fixer → verifier（4 agents，安全审计）
-
----
-
-When the user requests a complex task (multi-file changes, feature implementation, refactoring), **immediately execute this pattern in a SINGLE message:**
-
-```javascript
-// STEP 1: Spawn NAMED agents concurrently — all in ONE message
-// Each agent knows WHO to message next in the pipeline
-Task({
-  prompt: "Research requirements and codebase. SendMessage findings to 'architect' when done.",
-  subagent_type: "researcher", name: "researcher", run_in_background: true
-})
-Task({
-  prompt: "Wait for research from 'researcher'. Design implementation. SendMessage design to 'coder'.",
-  subagent_type: "planner", name: "architect", run_in_background: true
-})
-Task({
-  prompt: "Wait for design from 'architect'. Implement the solution. SendMessage code paths to 'tester'.",
-  subagent_type: "coder", name: "coder", run_in_background: true
-})
-Task({
-  prompt: "Wait for implementation from 'coder'. Write tests. SendMessage results to 'reviewer'.",
-  subagent_type: "tester", name: "tester", run_in_background: true
-})
-Task({
-  prompt: "Wait for test results from 'tester'. Review code quality and security. Report findings.",
-  subagent_type: "reviewer", name: "reviewer", run_in_background: true
-})
-
-// STEP 2: Kick off the pipeline
-SendMessage({ to: "researcher", summary: "Start research", message: "[task description and context]" })
-
-// Pipeline flow via SendMessage:
-// researcher ──→ architect ──→ coder ──→ tester ──→ reviewer
-```
-
-### Agent Routing (Anti-Drift)
-
-| Code | Task | Agents |
-|------|------|--------|
-| 1 | Bug Fix | researcher, coder, tester, reviewer |
-| 3 | Feature | researcher, architect, coder, tester, reviewer |
-| 5 | Refactor | researcher, architect, refactor-specialist, tester, reviewer |
-| 7 | Performance | researcher, coder, tester, reviewer |
-| 9 | Investigation | tester, researcher |
-
-**All codes: hierarchical/specialized (anti-drift)**
-
-### Task Complexity Detection
-
-**ALWAYS INVOKE SWARM**（默认行为，不要犹豫）：
-- 任何涉及代码变更的任务
-- 任何需要理解现有代码的任务
-- 新功能实现（无论大小）
-- Bug 修复（除 1-2 行 typo）
-- 重构、性能优化、架构调整
-- 调研、技术选型、方案对比
-- 测试编写、代码审查
-- 数据库变更、安全相关改动
-
-**SKIP SWARM 仅限**：
-- 单行 typo / 格式修正
-- 纯粹的问答（"这个函数做什么？"）
-- 查看文件内容（Read 即可）
-
-当用户说"调研 X"、"实现 Y"、"修复 Z"时，**不要问"要不要用 swarm"，直接开**。
-
-### Parallel Research Pattern
-
-调研类任务：**同时 spawn 多个 researcher 并行搜索不同方面**，而不是让一个 researcher 串行查。
-
-```javascript
-// 例：调研一个新框架
-Task({ subagent_type: "researcher", name: "docs-reader", prompt: "Read official docs, report API surface", run_in_background: true })
-Task({ subagent_type: "researcher", name: "code-explorer", prompt: "Find existing uses in codebase", run_in_background: true })
-Task({ subagent_type: "researcher", name: "comparator", prompt: "Compare with alternatives", run_in_background: true })
-```
-
-### Phase 文档产出（强制）
-
-每个 pipeline 阶段的 Agent 都 **MUST** 在项目 `docs/` 下生成对应阶段文档，作为可追溯的执行产物。
-
-**目录约定（自动创建，不存在则 mkdir -p）**：
-
-```
-docs/
-├── requirements/   # 需求阶段：需求分析、问题发现、范围定义、复现报告
-├── design/         # 设计阶段：架构设计、详细设计、ADR
-├── implementation/ # 编码阶段：改造点分析、详细执行计划、变更日志
-├── testing/        # 测试阶段：测试报告、回归记录、性能基线
-├── review/         # 审查阶段：代码审查、安全审计、根因分析
-└── operations/     # 运维阶段：迁移手册、回滚预案
-```
-
-**命名规范**：`<phase-prefix>-<topic>-<yyyymmdd-hhmm>.md`，例如：
-- `docs/requirements/feature-requirements-20260514-1430.md`
-- `docs/design/feature-architecture-20260514-1500.md`
-- `docs/implementation/feature-plan-20260514-1530.md`
-- `docs/testing/feature-test-report-20260514-1700.md`
-- `docs/review/feature-review-20260514-1730.md`
-
-**强制规则**：
-- Pipeline 中**每个 Agent 必须先写文档再做后续操作**（设计师先写架构再交给开发，开发先写计划再写代码）
-- SendMessage 给下游时**必须包含文档路径**，下游 Agent 必须先 Read 该文档
-- 文档要可独立阅读：包含上下文、决策、依据、产出，不依赖会话历史
-- 每个 pipeline 模板（pipeline_suggest 工具返回的 Task 调用）已经内置了文档输出指令，**不要省略**
-
-### Skill 方法论调用
-
-当任务涉及特定领域时，**主动调用 MCP 工具 `skill_invoke` 获取方法论指导**：
-
-```javascript
-// 重构任务 → 获取 Harness 安全重构方法论
-skill_invoke({ skill_id: "official-harness-legacy", reason: "需要安全重构指导" })
-
-// 调试任务 → 获取系统化调试方法论
-skill_invoke({ skill_id: "official-debug-methodology", reason: "需要调试方法论" })
-
-// 性能优化 → 获取性能优化方法论
-skill_invoke({ skill_id: "official-performance-optimization", reason: "需要性能优化指导" })
-
-// 安全审计 → 获取安全加固方法论
-skill_invoke({ skill_id: "official-security-hardening", reason: "需要安全审计指导" })
-
-// 代码审查 → 获取审查方法论
-skill_invoke({ skill_id: "official-code-review", reason: "需要代码审查指导" })
-
-// 不确定用哪个 → 先列出所有可用 skill
-skill_list({ keywords: ["debug"] })
-```
-
-**触发时机**：在 spawn swarm 之前或同时调用，将方法论内容传给对应的 Agent 作为指导。
-
-## Swarm Configuration & Anti-Drift
-
-### Anti-Drift Coding Swarm (PREFERRED DEFAULT)
-
-- ALWAYS use hierarchical topology for coding swarms
-- 不要为了"省 token"合并步骤 — 每个 Agent 都有独立的 context window，拆开更准确
-- Use specialized strategy for clear role boundaries
-- Keep task cycles short with verification gates
-- Each agent MUST end with SendMessage to the next agent in the chain
-- Do NOT implement code directly when a swarm is active — delegate to the coder step
-- Do NOT collapse a multi-step swarm into a single Task call
-
-## 项目概述
-
-本仓库是 Claude Code 工程化工具集的研发工作区。源码分布在 `src/` 下的以下模块：
-
-- `src/core/` — 核心基础设施：`types.ts`（`ForgeEvent`、`HookResult` 等跨层契约）、`config.ts`、`constants.ts`、`storage/`（SQLite + `schema.sql`）、`ai/`（ClaudeProvider）、`utils/`（logger / lru-cache / token-tracker / path 等）
-- `src/engine/` — 规则与治理引擎：`dsl/`（types / parser / compiler / runtime）、`rule-engine.ts`、`context-builder.ts`、`evidence-store.ts`、`agent-router.ts`、`experiment-router.ts`、`recommender.ts`、`conventions/*.yaml`
-- `src/capability/` — 方法论执行核心：`methodology-registry.ts`、`methodology-planner.ts`、`execution-manager.ts`、`executor/`（foreground / background / orchestrator / stream-parser / worker-auth-probe）、`methodologies/*.yaml`
-- `src/daemon/` — 守护进程：`server.ts`、`router.ts`、`lifecycle.ts`、`event-parser.ts`、`idle-detector.ts`、`idle-trigger.ts`、`auto-disable-scheduler.ts`、`methodology-pending-queue.ts`、`routing-observer.ts`、`routing-state.ts`、`handlers/`（pre-tool-use / post-tool-use / user-prompt / stop / history-exporter / methodology-formatter）、`services/`（task-segmenter）
-- `src/cli/` — CLI 入口与子命令：`init/` + `commands/`（claudemd / config / daemon / init / logs / menu / rules / skills / stats / status / template）
-- `src/skills/` — Skill 注册与匹配（registry / matcher / semantic-matcher / official-skills）
-- `src/claudemd/` — CLAUDE.md 生成与维护（tech-detector / claudemd-generator / convention-extractor / persona-manager / resume-manager）
-- `src/templates/` — 项目模板（`*.yaml` + `template-manager.ts`）
-- `src/hooks/` — Claude Code Hook shell 脚本（构建时复制到 `dist/hooks/`）
-- `src/web/` — 嵌入式 Web 服务器（Express + 静态资源 + auth/ssrf 中间件）
-- `web/` — Web 前端（React + TanStack Query + Vite）
-
-## 技术栈
-
-- 运行时：Node.js
-- 语言：TypeScript（`strict: true`）
-- 测试：Vitest
-- 构建：`tsc`（后端）+ Vite（前端）
-- 存储：SQLite（`better-sqlite3`）
-- Web：Express（后端）+ React + TanStack Query（前端）
-
-## 架构要点
-
-- 架构以声明式治理为核心：Convention YAML + DSL 表达式驱动规则引擎，而非命令式编排
-- `src/core/types.ts` 承载 `ForgeEvent`、`HookResult` 等跨层类型契约；`src/core/storage/sqlite.ts` 直接封装 SQL（文件头注释明确写了 `No repository pattern, no base class — just direct SQL in one file`），不要误以为存在 Repository 层
-- `src/engine/dsl/` 由 types / parser / compiler / runtime 四件组成；规则模型、事件模型、DSL 类型的变更属于高影响改动，**类型契约先行**收敛后再动实现
-- **决策分级：`block` / `confirm` / `warn` / `allow` 四档**（见 `src/engine/rule-engine.ts` 的 level 优先级定义）。`block` 级在 `pre-tool-use.ts` 中会硬阻断工具执行，不是"仅告知"。实际行为以 `rule-engine.ts` 为准
-- `src/capability/` 是方法论执行核心：planner 负责编排 phase，executor 分前台/后台两条路径，orchestrator 负责推进。daemon **无法主动推送消息**，前台方法论的兜底路径是 Stop → pending 队列 → 下一次 UserPromptSubmit 消费
-
-### 目录依赖约束
-
-- `core` 不反向依赖业务层
-- `engine` 可依赖 `core`
-- `capability` 可依赖 `core`、`engine`
-- `skills` / `templates` / `claudemd` 可依赖 `core`（必要时依赖 `engine`）
-- `daemon` 可依赖 `core`、`engine`、`capability`、`skills`
-- `cli` 是装配层：组合上述模块，不把规则/执行核心逻辑塞回命令实现
-- `web` 作为服务壳：HTTP 路由只做参数收敛与响应序列化，不在路由里写业务逻辑
-
-### 存储
-
-- 单一运行时数据库：`~/.claude-forge/data.db`（由 `FORGE_PATHS.database()` 统一返回），存放 events / sessions / routing_events / methodology_executions / phase_executions / tasks / injections / decisions / token_usage 等
-- Schema 通过 `src/core/storage/schema.sql` 初始化；增量迁移走 `runMigrations()`，使用幂等 `ALTER TABLE` + `PRAGMA table_info` 检测
-- 索引见 `src/core/storage/performance-indexes.sql`
-
-## 开发规范
-
-### 构建与测试
-
-```bash
-# 类型检查
-npx tsc --noEmit
-
-# 后端构建
-npx tsc
-
-# 前端构建
-cd web && npm run build
-
-# 测试
-npm run test
-
-# 完整构建（含 hook 脚本拷贝）
-npm run build
-```
-
-### Convention YAML 规范
-
-- Convention 配置统一使用 YAML（见 `src/engine/conventions/*.yaml`）
-- 每个 Convention 文件通常包含 `forbidden`（禁止规则）与 `escalation`（升级策略）段落
-- 规则的 `when` 条件使用 DSL 表达式，由 `src/engine/dsl/parser.ts` + `compiler.ts` 处理
-- 变更后需运行项目测试或对应 demo 脚本验证加载与解析
-
-### 边界层类型收敛
-
-- `src/daemon/handlers/`、`src/web/` 路由、`src/hooks/` 监听器禁止未经收敛直接访问深层字段
-- 处理动态数据时优先使用显式类型守卫、局部变量收窄或小范围断言
-- 不得把 `any` 或未收窄的 `unknown` 扩散到 `engine`、`core` 等核心层
-
-### 守护进程事件推送
-
-- SSE 推送按需触发，不要在高频事件上无条件推送完整快照
-- 会话结束、进程启动、异常恢复路径都要检查过期任务与残留索引
-- daemon 不能主动向 Claude 主会话推送消息；跨轮传递必须走 pending 队列 + 下一次 Hook 事件消费
-
-### 注意
-
-- 用户的全局 `~/.claude/CLAUDE.md` 里有一段 "Pipeline 模块架构约定（claude-forge）"，列出 `src/pipeline/` 下六个文件（`completion-gate.ts`、`completion-detector.ts`、`artifact-validator.ts`、`dynamic-node-executor.ts`、`dynamic-pipeline-repository.ts`、`pipeline/index.ts`）。**这些文件在当前代码库中不存在**，属于未落地规划。请忽略该段约束，以本项目 CLAUDE.md 为准。
-<!-- forge:end-claudemd-auto -->
-
-<!-- forge:convention-start:custom-claude-forge -->
-## 项目规范约束：claude-forge 综合规范 (v1.2.0)
-
-### 来自 Harness Engineering 安全重构规范
-
-**核心理念：先织安全网，再动代码**
-
-**TypeScript 专项原则**
-
-- 严格启用 `strict: true`，禁止 `any`
-- 模块边界用 `interface`，内部用 `type`
-- 统一 `async/await`，禁止混用 Promise 链
-- 错误处理必须显式，不得静默吞异常
-- 禁止硬编码敏感信息
-
-## 架构决策记录
-
-_架构决策将在此记录_
-
-<!-- forge:convention-end:custom-claude-forge -->
-
-<!-- forge:resume-begin:99112f2d-5b13-46f9-b39c-44429ea99302 -->
-```forge-resume-body
-## 上次工作续接
-
-⚠️ **IMPORTANT: 在开始新任务前，请先检查以下上下文**
-
-**上次在做**:
-- 当前的claude.md看起来很长，这个会不会导致理解或者指令偏差呢？
-
-**上次活跃**: 刚刚
-
-**会话行为**: 工具调用 5194 次 | Agent 委托 108 次 (Explore, coder, feature-developer) | Skill 调用 11 次
-
-_生成时间: 2026-05-15T07:10:05.173Z_
-```
-
-_生成时间: 2026-05-15T07:10:05.203Z_
-<!-- forge:resume-end:99112f2d-5b13-46f9-b39c-44429ea99302 -->

package/docs/concurrent-agents.md

@@ -1,129 +0,0 @@
-# 并发 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` — 路由遵守度监控