bookworm-smart-assistant/docs/project-introduction.md

# Bookworm Smart Assistant v5.6 — 项目介绍

---

## 一句话定位

**基于 Claude Code 的自进化智能路由系统，将单一 AI 助手扩展为 50 专家技能 + 10 智能体的协作网络，实现"说人话，干专家活"。**

---

## 1. 项目背景与痛点

### 痛点

| 问题 | 表现 |
|------|------|
| AI 助手是"万金油" | 什么都能答，但什么都不够专业 |
| 上下文容易丢失 | 长对话中忘记之前的决策和约定 |
| 无法自我改进 | 同样的错误反复出现，没有学习能力 |
| 质量不可控 | 没有门控机制，低质量输出直达用户 |
| 基建维护靠人工 | 配置漂移、版本不一致需要人工排查 |

### 机会

Claude Code 提供了 Hooks、MCP、Agent、Skill 四大扩展机制，但缺少一个**将它们有机编排、持续进化**的系统层。Bookworm 填补了这个空白。

---

## 2. 解决方案

### 核心架构：7 层流水线

```
用户输入
  ↓
L1 路由层 ─── Neural Gateway: BM25 + TF-IDF + 上下文融合 → [BWR] 指令
  ↓
L2 门控层 ─── 5 个 PreToolUse 钩子: 文件保护 / 危险拦截 / 合规校验
  ↓
L3 执行层 ─── 50 专家技能 + 10 智能体 + 6 MCP 服务
  ↓
L4 后处理层 ─ 变更感知 / 构建追踪 / 活动日志
  ↓
L5 会话结束 ─ 合规审计 + 磁盘清理
  ↓
L6 学习闭环 ─ 显式纠正 + 隐式反馈 → 权重回注 L1
  ↓
L7 自进化 ── 感知 → 审计 → 修复 → 记录 (无人值守)
```

### 核心能力

**能力一：语义路由引擎**

用户只需用自然语言描述需求，系统自动匹配最合适的专家技能：

```
"React 页面加载慢"  → performance-expert (非 frontend)
"API 安全漏洞"      → security-expert (非 backend)
"帮我写个 PRD"      → product-manager-expert
"从零搭建电商后台"  → orchestrator (多技能编排)
```

- 27 条消歧规则处理模糊边界（如"测试"一词在不同上下文路由到 5 个不同技能）
- 19 组同义词展开覆盖中英文混合输入
- 会话滑动窗口保持上下文连贯性

**能力二：多层安全门控**

```
L2 门控三道防线:
├─ block-sensitive-files  → 保护 hooks/*.js 不被意外修改
├─ block-dangerous-commands → 拦截 rm -rf / DROP TABLE 等危险操作
└─ route-compliance-gate  → 确保 Skill 调用匹配路由指令
```

**能力三：自进化闭环**

```
文件修改 → drift-detector 感知
       → self-auditor 8 维审计
       → self-healer 自动修复元数据
       → evolution-log 记录进化轨迹

路由反馈 → 显式纠正 + 隐式信号
       → 权重学习 (5 天半衰期指数衰减)
       → 限幅 [-0.5, +0.5] 安全约束
       → 回注路由引擎
```

---

## 3. 系统规模

| 维度 | 数量 | 说明 |
|------|------|------|
| 专家技能 | **50** | 覆盖前端/后端/架构/安全/DevOps/AI/产品/商业等 20+ 领域 |
| 智能体 | **10** | 2 Opus (编排+审查) + 8 Sonnet (审计/修复/测试/构建等) |
| 钩子 | **17** | 13 已注册 + 4 备用 (按需激活，减少默认延迟) |
| MCP 服务 | **6** | 深度研究 / 实时文档 / 结构化推理 / 浏览器自动化 |
| 消歧规则 | **27** | 外部化 JSON，可热更新 |
| 同义词组 | **19** | 中英文双语覆盖 |
| 加权关键词 | **2,393** | 三层权重 (core/strong/extended) + TF-IDF 区分度 |
| 编译规则 | **92** | 合规门控 pattern |
| 完整性校验 | **24 文件** | SHA256 + HMAC 机器绑定签名 |
| 测试用例 | **1,371** | 46 个测试文件，全绿 |
| 脚本模块 | **45** | 路由/学习/健康/报告/清理等 |

---

## 4. 健康度量体系

### 10 维健康评分引擎

```
┌──────────────────────────────────────────────────────┐
│  H1  配置一致性  13%  ████████████████████  100      │
│  H2  行为基线    13%  ████████████████████  100      │
│  H3  磁盘健康    10%  ████████████████████  100      │
│  H4  钩子完整性  13%  ████████████████████  100      │
│  H5  技能索引     9%  ████████████████████  100      │
│  H6  规则缓存     9%  ████████████████████  100      │
│  H7  路由准确率  13%  ████████████████████  100      │
│  H8  学习收敛    10%  ██████████████████░░   90      │
│  H9  路由合规    10%  ████████████████████  100      │
│  H10 Hook有效性   9%  ████████████████████  100      │
├──────────────────────────────────────────────────────┤
│                              总分:  99 / 100         │
└──────────────────────────────────────────────────────┘
```

### 关键运营指标

| 指标 | 当前值 | 说明 |
|------|--------|------|
| 路由准确率 | **100%** | 455 条反馈，0 误路由 |
| 权重收敛状态 | **零漂移** | 学习系统已完全收敛 |
| 测试通过率 | **100%** | 1371/1371 |
| 完整性校验 | **24/24 PASS** | SHA256 + HMAC 全部通过 |

---

## 5. 技术亮点

### 5.1 BM25 + 上下文融合评分

```
综合得分 = BM25基础分(0.6) + 会话上下文(0.2) + 项目类型(0.1) + 工作流模式(0.1)
```

不是简单的关键词匹配，而是结合当前对话历史、项目类型、操作序列的多维评分。

### 5.2 管道检测 (v5.6 新增)

```bash
# 传统方式: exitCode 被 tail 覆盖，误判为成功
vitest run | tail -5    # exitCode = 0 (tail 的退出码)

# Bookworm: 解析输出内容，识别 12 种测试框架的汇总行
# "3 failed" → failure    "0 failed, 12 passed" → success
```

### 5.3 自愈安全约束

self-healer 只修改**元数据层** (版本号、计数、注册表条目、索引)，绝不修改技能逻辑、智能体行为、钩子业务代码。

### 5.4 学习安全基座

- 技能名白名单校验 — 防止学习虚构技能
- 权重限幅 [-0.5, +0.5] — 防止单一反馈暴走
- 5 天半衰期衰减 — 旧反馈自然退出
- Holdout 验证集 — 评估学习效果

---

## 6. 版本演进

```
v4.8  关键词共现匹配, 6 维健康检查
  ↓
v4.9  BM25 评分, TF-IDF 加权, 三层关键词, 隐式反馈
  ↓
v5.0  会话追踪, 项目检测, 工作流模式, 路由融合
  ↓
v5.1  IQR+Z-score 异常检测, EWMA 动态阈值, 技能链推荐
  ↓
v5.2  Neural Gateway 强制路由, 意图分类, 合规门控
  ↓
v5.3  会话路由记忆, A/B 实验框架, Hook 并行派遣
  ↓
v5.4  消歧规则引擎 (18规则), 学习安全基座, 关键词缺口检测
  ↓
v5.5  架构评审修复, dispatcher 委托模式, 消歧外部化 (22规则)
  ↓
v5.6  闭环校验: actualSkill 合规闭环, 管道检测, 0-failed 修复
       消歧 27 规则, 同义词 19 组, 1371 tests 全绿 ← 当前版本
```

---

## 7. 项目结构

```
.claude/
├── CLAUDE.md                    # 系统主配置 (路由规则/偏好/架构声明)
├── settings.json                # Hook 注册 + MCP 配置
├── skills-index.json            # 50×2393 编译索引
├── stats-compiled.json          # 实时统计快照
├── checksums.json + .sig        # 24 文件完整性签名
│
├── skills/                      # 50 个专家技能
│   ├── frontend-expert/SKILL.md
│   ├── backend-builder/SKILL.md
│   └── ...
│
├── agents/                      # 10 个智能体
│   ├── orchestrator.md          # Opus - 多技能编排
│   ├── self-auditor.md          # Sonnet - 8 维审计
│   └── ...
│
├── hooks/                       # 17 个钩子
│   ├── route-interceptor.js     # 路由入口 (UserPromptSubmit)
│   ├── route-compliance-gate.js # 合规校验 (PreToolUse)
│   ├── build-outcome-tracker.js # 构建追踪 (PostToolUse)
│   ├── route-auditor.js         # 合规审计 (Stop)
│   └── ...
│
├── scripts/                     # 45 个脚本模块
│   ├── route-analyzer.js        # BM25 评分引擎
│   ├── health-check.js          # 10 维健康评分
│   ├── generate-stats.js        # 统计生成器
│   └── ...
│
└── debug/                       # 运行时数据
    ├── route-weights.json       # 学习权重
    ├── route-feedback.jsonl     # 路由反馈日志
    └── evolution-log.jsonl      # 进化轨迹
```

---

## 8. 适用场景

| 场景 | 说明 |
|------|------|
| 全栈独立开发者 | 一个人 = 50 个专家，覆盖开发全生命周期 |
| 技术团队 Leader | 架构评审、代码审查、技术选型的 AI 副驾驶 |
| 创业者 | 从 BP 撰写到产品开发到部署上线，端到端支持 |
| Claude Code 深度用户 | 将原生能力扩展 10 倍，且持续自我进化 |

---

## 9. 核心价值

```
┌────────────────────────────────────────────────────┐
│                                                    │
│   普通 AI 助手:  用户适应 AI                        │
│                                                    │
│   Bookworm:     AI 适应用户                        │
│                                                    │
│   - 自动识别意图，路由到最合适的专家                  │
│   - 从每次交互中学习，持续提升准确率                  │
│   - 多层门控确保输出质量                             │
│   - 无人值守自愈，配置永不漂移                       │
│                                                    │
└────────────────────────────────────────────────────┘
```

---

*Bookworm Smart Assistant v5.6 | 2026-03-01 | 健康评分 99/100*