# Bookworm v6.0 战略演进设计文档

> 基于 v5.8 全维度审计 + 计算机哲学评审，设计三个核心演进方向

**创建日期**: 2026-03-04
**状态**: 设计稿 (待实施)
**影响范围**: 路由引擎 / 技能组织 / 质量闭环 / 视觉测试 / LLM 网关

---

## S1: 概率性路由引擎

### 问题陈述

当前 38 条消歧规则是**手工编码的信道编码**，维护成本随技能数 O(N²) 增长。
当技能数 >100 时，消歧规则将成为维护瓶颈 (需 ~80+ 条)。

### 设计方案: 三阶段渐进演化

#### 阶段 1: 强化隐式反馈闭环 (v5.9)

**现有基础**:
- `implicit-feedback.js` 已实现 5 分钟窗口内的路由确认/纠正推断
- `route-ab-test.js` 已实现 Thompson Sampling + 收敛检测
- `route-weights.json` 已支持权重增量 [-0.5, +0.5]

**增强点**:
```
1. 在 route-auditor.js (Stop hook) 中自动触发 implicit-feedback
   当前: 手动运行 / 无集成
   增强: 每次会话结束自动推断本次所有路由的正确性

2. 将 implicit-feedback 结果自动回流到 route-weights.json
   当前: 只写 route-feedback.jsonl，未回流
   增强: 添加 applyImplicitWeights() 函数
     confirmed → weight += 0.05 (限幅)
     corrected → weight -= 0.1, 正确技能 += 0.1

3. 扩展 A/B 实验的触发范围
   当前: 仅 top-2 差距 < 15% 时触发
   增强: 加入消歧规则命中时的强制实验
     当消歧规则覆盖 BM25 结果时 → 50% 概率保留 BM25 原选择
     收集对比数据 → 验证消歧规则是否真的优于 BM25
```

**实现路径**:
```javascript
// route-auditor.js 增强 (Stop hook)
const implicit = require('../scripts/implicit-feedback.js');
const feedback = implicit.inferFeedback({ maxDays: 1 });
implicit.applyToWeights(feedback); // 新增函数
```

**预期效果**: 消歧规则中 ~30% 可通过数据验证其必要性，不必要的规则可退役。

#### 阶段 2: 学习型消歧 (v6.0)

**核心设计**: 将硬编码规则转化为可学习的软规则

```
消歧规则现状:
  { "pattern": "React+Bug", "action": "debugger" }  // 硬编码

学习型消歧:
  {
    "pattern": "React+Bug",
    "baseAction": "debugger",
    "learnedWeight": 0.85,    // 从反馈数据学习
    "alternatives": {
      "frontend-expert": 0.10,
      "reviewer-expert": 0.05
    },
    "confidence": 0.92,       // 基于样本量
    "sampleCount": 47
  }
```

**实现**: 新增 `scripts/adaptive-disambiguator.js`

```javascript
// 核心算法: Bayesian Rule Learning
class AdaptiveDisambiguator {
  constructor(rules, feedbackHistory) {
    this.rules = rules;
    this.priors = this.initPriors(rules);
  }

  // 每条规则维护一个 Dirichlet 分布
  // α_i = 先验 + 命中后成功次数
  initPriors(rules) {
    return rules.map(r => ({
      pattern: r.pattern,
      // 先验: 硬编码 action 获得 α=10 的强先验
      alphas: { [r.action]: 10, _other: 1 },
      totalSamples: 0,
    }));
  }

  // 根据后验分布选择 action
  selectAction(matchedRuleIdx, candidates) {
    const prior = this.priors[matchedRuleIdx];

    // 样本充足 (>30) 且收敛 → 确定性选择
    if (prior.totalSamples > 30) {
      const maxAlpha = Math.max(...Object.values(prior.alphas));
      const winner = Object.keys(prior.alphas)
        .find(k => prior.alphas[k] === maxAlpha);
      if (maxAlpha / prior.totalSamples > 0.8) return winner;
    }

    // 样本不足或未收敛 → Thompson Sampling
    return this.thompsonSample(prior.alphas, candidates);
  }

  // 记录反馈
  recordFeedback(ruleIdx, selectedSkill, wasCorrect) {
    const prior = this.priors[ruleIdx];
    if (wasCorrect) {
      prior.alphas[selectedSkill] = (prior.alphas[selectedSkill] || 0) + 1;
    } else {
      prior.alphas[selectedSkill] = Math.max(0, (prior.alphas[selectedSkill] || 1) - 0.5);
    }
    prior.totalSamples++;
  }
}
```

**安全机制**:
- 硬编码规则作为强先验 (α=10)，需要大量反面证据才能推翻
- 前 30 个样本内不改变行为，仅收集数据
- 任何规则的学习权重偏离先验 >50% 时，写入 evolution-log 并标记审查

#### 阶段 3: 向量嵌入补充 (v6.x)

**方案**: 用 MCP 调用嵌入模型，为每次查询生成向量，与预计算的技能向量做余弦相似度

```
用户输入 "优化首屏加载速度"
  ↓
BM25 路由: frontend-expert (0.72), performance-expert (0.68)
  ↓ (差距 < 15%, 触发向量补充)
Embedding: text-embedding-3-small
  query_vec = embed("优化首屏加载速度")
  skill_vecs = precomputed  (每个技能 description 的 embedding)
  cos_sim: performance-expert (0.89), frontend-expert (0.76)
  ↓
融合: BM25(0.5) + Embedding(0.3) + Context(0.2)
  performance-expert: 0.5*0.68 + 0.3*0.89 + 0.2*ctx = 0.607 + ctx
  frontend-expert:    0.5*0.72 + 0.3*0.76 + 0.2*ctx = 0.588 + ctx
```

**前置条件**:
- 集成 LiteLLM/OpenRouter MCP 或 本地 ollama embedding
- 预计算 68 个技能向量 → `skills-embeddings.json`
- 仅在 BM25 top-2 差距 < 15% 时触发 (节省 API 调用)

**延迟预算**: +200-500ms (仅低置信度查询触发)

---

## S2: 层级化技能组织

### 问题陈述

68 技能平铺在同一层级，BM25 评分 O(N*K*T) 随 N 线性增长。
消歧冲突以 O(N²) 增长。当前 61 个关键词冲突已经很高。

### 设计方案: 两级路由

```
Layer 1: 域路由 (Domain Router)
  ├── dev          (22 技能: frontend, backend, mobile, ...)
  ├── architecture (11 技能: architect, database, cloud-native, ...)
  ├── devops       (6 技能: devops, devsecops, git, sre, ...)
  ├── quality      (3 技能: tester, reviewer, project-audit)
  ├── product      (4 技能: product-manager, designer, ux, coordinator)
  ├── business     (9 技能: business-plan, finance, sales, ...)
  ├── content      (5 技能: tech-writer, copywriter, email, ...)
  ├── ai-data      (3 技能: ai-ml, data-analyst, data-engineer)
  ├── security     (1 技能: security-expert)
  └── meta         (4 技能: genesis-engine, prompt-optimizer, ...)

Layer 2: 技能路由 (Skill Router)
  在选定域内做精确 BM25 匹配
```

### 数据结构

在 `skills-index.json` 中新增 `domain` 字段:

```json
{
  "domains": {
    "dev": {
      "keywords": ["代码", "开发", "实现", "写", "组件", "API", "接口", ...],
      "skills": ["frontend-expert", "backend-builder", "mobile-expert", ...]
    },
    "architecture": {
      "keywords": ["架构", "设计", "选型", "DDD", "微服务", ...],
      "skills": ["architect-expert", "database-tuning-expert", ...]
    }
  }
}
```

### 路由流程

```
用户输入 "React 组件性能优化"
  ↓
Layer 1: 域分类器
  dev: 0.7 (React, 组件)
  architecture: 0.3 (性能, 优化)
  → 选择 dev (top-1)，保留 architecture 作为辅助域

Layer 2: 域内 BM25 (仅 22 技能)
  frontend-expert: 0.85
  performance-expert: 0.72  (跨域辅助)
  → 最终: frontend-expert

消歧规则: 仅需覆盖**域内冲突** (22 技能间 vs 68 技能间)
  域内冲突数: ~15 条 (vs 全局 38 条)
```

### 复杂度分析

| 指标 | 当前 (平铺) | 层级化 | 改善 |
|------|-----------|--------|------|
| BM25 评分次数 | 68 | ~10 (域) + ~22 (域内) = 32 | -53% |
| 消歧规则维护 | O(N²) ≈ 38 | O(K) + O((N/K)²) ≈ 15 | -60% |
| N=100 时规则数 | ~80 | ~25 | -69% |
| N=200 时规则数 | ~160 | ~45 | -72% |

### 兼容性设计

- 层级化路由与现有平铺路由**并行运行** (A/B 测试)
- route-ab-test 框架可直接复用
- 域分类器复用现有 BM25 引擎，仅更换索引维度
- 消歧规则按域分组，无需全局重写

### 实现路径

```
v5.9: 在 skills-index.json 中为每个技能添加 domain 字段 (手工标注)
v6.0: 实现 domain-router.js (Layer 1 路由器)
v6.1: 在 route-interceptor 中 A/B 测试 flat vs hierarchical
v6.2: 收敛后切换默认路由策略
```

---

## P3-13: 视觉回归测试

### 设计方案

在 `zero-defect-guardian` 技能中集成 Playwright 截图对比:

```
修改前截图 → 修改代码 → 修改后截图 → 像素对比 → 差异报告
```

**实现**:
```javascript
// scripts/visual-regression.js
const { chromium } = require('playwright');

async function captureBaseline(url, selector, outputPath) {
  const browser = await chromium.launch();
  const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
  await page.goto(url);
  const element = selector ? await page.$(selector) : page;
  await element.screenshot({ path: outputPath });
  await browser.close();
}

async function compareSnapshots(baselinePath, currentPath, diffPath) {
  // pixelmatch 库 (npm i pixelmatch pngjs)
  const pixelmatch = require('pixelmatch');
  const { PNG } = require('pngjs');
  // ... 像素对比逻辑
  return { mismatchPercentage, diffPixels };
}
```

**集成点**:
- `zero-defect-guardian` SKILL.md 增加 visual regression 章节
- tester-expert 的 E2E 测试模板增加截图对比步骤
- quality-gate D4 性能维度增加视觉回归检查

---

## P3-14: LLM Gateway MCP

### 设计方案

创建统一 LLM 调用网关:

```json
// mcp-templates.md 新增
"llm-gateway": {
  "args": ["/c", "npx", "-y", "mcp-server-litellm", "--config", "./litellm.yaml"],
  "command": "cmd", "type": "stdio"
}
```

**litellm.yaml 模板**:
```yaml
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: ${OPENAI_API_KEY}
  - model_name: qwen-plus
    litellm_params:
      model: dashscope/qwen-plus
      api_key: ${DASHSCOPE_API_KEY}
  - model_name: embedding
    litellm_params:
      model: openai/text-embedding-3-small
      api_key: ${OPENAI_API_KEY}
```

**用途**: ai-ml-expert 中的 RAG/Agent 开发可通过 MCP 直接调用多模型。

---

## P3-15: 多模态闭环

### 设计方案

```
Figma 设计稿 → get_design_context (Figma MCP)
  ↓
AI 生成代码 → frontend-expert / canvas-ui-designer
  ↓
启动本地 dev server → Bash: npm run dev
  ↓
Playwright 截图 → mcp__playwright__browser_take_screenshot
  ↓
与 Figma 原稿对比 → visual-regression.js
  ↓
差异 > 5% → 自动修复循环 (最多 3 轮)
差异 ≤ 5% → PASS
```

**关键约束**: 需要 Figma MCP + Playwright MCP 同时可用。

---

## P3-16: Skill 热加载

### 设计方案

当前添加新技能需要:
1. 创建 `skills/new-skill/SKILL.md`
2. 运行 `node scripts/generate-skill-index.js` 重建索引
3. 重启 Claude Code 会话

**热加载方案**:
- 在 `post-edit-dispatcher.js` 检测 `skills/*/SKILL.md` 的写入
- 自动触发 `generate-skill-index.js` 重建索引
- 路由引擎在下次调用时自动加载新索引 (已有的 loadIndex() 每次读文件)

```javascript
// post-edit-dispatcher.js 增强
function checkSkillHotReload(filePath) {
  if (/skills\/[^/]+\/SKILL\.md$/.test(filePath)) {
    // 异步重建索引 (不阻塞当前 hook)
    const { execFile } = require('child_process');
    execFile(process.execPath,
      [path.join(ROOT, 'scripts/generate-skill-index.js')],
      { timeout: 10000 },
      () => {} // 静默完成
    );
    return '[skill-hot-reload] 检测到技能文件变更，索引已自动重建';
  }
  return null;
}
```

**无需重启会话**: 因为 `loadIndex()` 每次路由都从磁盘读取 skills-index.json。

---

## 实施路线图

```
v5.9 (2周内):
  ├── S1-Phase1: implicit-feedback 自动化 + 消歧规则 A/B 验证
  ├── S2-Step1: skills-index.json 添加 domain 字段
  └── P3-16: Skill 热加载 (dispatcher 增强)

v6.0 (1月内):
  ├── S1-Phase2: Bayesian 学习型消歧器
  ├── S2-Step2: domain-router.js 实现
  ├── P3-13: visual-regression.js 实现
  └── P3-14: LLM Gateway MCP 模板

v6.1 (2月内):
  ├── S2-Step3: flat vs hierarchical A/B 测试
  ├── P3-15: 多模态闭环 (Figma→Code→Screenshot→Diff)
  └── S1-Phase3: 向量嵌入补充 (依赖 LLM Gateway)

v6.2 (季度):
  └── 收敛与清理: 退役无效消歧规则, 切换默认路由策略
```

---

*设计完成: 2026-03-04 | 审阅状态: 待 self-auditor 验证*