273 lines
10 KiB
Markdown
273 lines
10 KiB
Markdown
# 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*
|