# Bookworm Smart Assistant — 前瞻性升级路线图

> 基于 v3.7 全流程测试 (2026-02-20, 217/217 PASS) 的架构分析
> 分析模型: Claude Opus 4.6

---

## 〇、当前系统画像

```
v3.7 架构现状:
  50 Skills (静态 SKILL.md, 关键词路由)
  10 Agents (固定模板: Feature/Bugfix/Optimization/Greenfield)
   8 Hooks  (正则匹配, 串行管道 stdin→stdout)
   7 MCPs   (全局常驻, npx 按需拉取)
  日志: JSONL 追加, 无索引
  自进化: drift-detector → self-auditor → self-healer (线性闭环)
  安全: 正则 pattern matching, 4 层防护
  测试: 128 单元 + 67 集成, 纯功能验证
```

**核心优势**: 闭环完整、fail-closed 安全哲学、元数据/业务逻辑隔离
**关键瓶颈**: 规则硬编码、无学习能力、线性审计、单节点日志

---

## 一、钩子系统升级 (Hooks v2)

### 1.1 现状痛点

| 问题 | 影响 |
|------|------|
| 正则 pattern matching 天花板 | 新型攻击 (混淆/编码绕过) 无法覆盖 |
| 每个钩子独立进程 `execSync` | 8 钩子串行 = 累计延迟 ~40ms/次 |
| 无状态执行 (每次冷启动) | 无法基于历史行为做风险评估 |
| 硬编码模式列表 | 新增规则必须改代码 + 重启 |

### 1.2 升级方向

**A. 规则外部化 — 优先级: HIGH / 难度: LOW**

```
hooks/
├── rules/
│   ├── deny-patterns.json      # DENY 规则 (热加载)
│   ├── ask-patterns.json       # ASK 规则
│   ├── sensitive-paths.json    # 敏感路径
│   └── sensitive-content.json  # 敏感内容
├── block-dangerous-commands.js # 引擎 (不变)
└── block-sensitive-files.js    # 引擎 (不变)
```

- 规则与引擎分离, 非开发者也可维护
- 支持 `rules/*.local.json` 项目级覆盖
- 钩子启动时热加载, 无需修改 .js 代码

**B. 长驻进程 + IPC — 优先级: MEDIUM / 难度: MEDIUM**

当前每次工具调用 spawn 8 个 Node 进程 → 改为单个常驻进程:

```
┌──────────────────────────────┐
│  hook-daemon (长驻进程)        │
│  ├── 监听 Unix Socket/Named Pipe │
│  ├── 内存中缓存所有规则          │
│  ├── 维护会话级上下文            │
│  └── 批量处理 Pre/Post 事件      │
└──────────────────────────────┘
```

- 启动成本从 ~5ms/钩子 降到 <1ms (IPC 通信)
- 可维护会话级状态 (如: 同一文件 10 分钟内修改 5 次 → 触发告警)

**C. AST 级命令分析 — 优先级: HIGH / 难度: HIGH**

正则无法准确解析复合命令 (引号嵌套、变量展开、heredoc)。引入轻量 shell parser:

```javascript
// 当前: 正则拆分, 引号内分号会误判
const parts = cmd.split(/\s*(?:&&|\|\||;)\s*/);

// 升级: 用 shell-quote 或 bash-parser 做 AST 分析
const ast = parseShellCommand(cmd);
for (const node of ast.commands) {
  if (node.type === 'Command' && isDangerous(node)) { ... }
}
```

推荐库: `shell-quote` (轻量) 或 `bash-parser` (完整 AST)

---

## 二、智能路由升级 (Router v2)

### 2.1 现状痛点

| 问题 | 影响 |
|------|------|
| 6 级优先级硬编码在 CLAUDE.md | 消歧规则越加越多, 维护困难 |
| 关键词匹配无法理解语义 | "这个组件性能不行" 是 performance 还是 frontend? |
| 无路由反馈学习 | 误路由后无法自动纠偏 |

### 2.2 升级方向

**A. Embedding 语义路由 — 优先级: HIGH / 难度: MEDIUM**

为每个 SKILL.md 的 description 生成 embedding, 用户输入也生成 embedding, 余弦相似度排序:

```
用户输入: "React 组件在低端 Android 上渲染卡顿"
                    ↓ embedding
  ┌─ performance-expert  0.89  ← 最佳匹配
  ├─ mobile-expert       0.85
  ├─ frontend-expert     0.82
  └─ debugger-expert     0.71

→ 主路由: performance-expert
→ 候选: mobile-expert (交叉领域时可联合调用)
```

实现方式:
- 预计算: 50 个技能的 embedding 缓存为 `skills-embeddings.json`
- 运行时: 用户输入 → 本地 embedding → top-K 相似度匹配
- 模型: 用 Claude 自身的 tool_use 做 re-ranking, 或本地 ONNX 小模型

**B. 路由置信度 + 多技能协作 — 优先级: MEDIUM / 难度: LOW**

当前是单一路由 (1 个输入 → 1 个技能)。升级为置信度评分:

```
高置信度 (>0.85): 直接路由
中置信度 (0.6-0.85): 路由到主技能, system prompt 中注入辅助技能的关键指引
低置信度 (<0.6): 询问用户确认, 或 fallback developer-expert
```

**C. 路由审计日志 + 学习反馈 — 优先级: MEDIUM / 难度: LOW**

```jsonl
{"ts":"...","input":"React 卡顿","routed":"performance-expert","confidence":0.89,"user_override":null}
{"ts":"...","input":"支付页面布局","routed":"designer-expert","confidence":0.72,"user_override":"frontend-expert"}
```

- 记录每次路由决策和用户纠正
- 定期分析: 哪些技能容易被误路由 → 优化 description 或消歧规则
- 为 embedding 路由提供 fine-tuning 信号

---

## 三、自进化系统升级 (Evolution v2)

### 3.1 现状痛点

| 问题 | 影响 |
|------|------|
| 线性闭环 (detect → audit → heal) | 无法并行审计, 无预测能力 |
| self-healer 只修复元数据 | 业务逻辑退化无法自愈 |
| evolution-log 仅追加文本 | 无法做趋势分析和模式识别 |
| drift-detector 只检测 .claude/ 变更 | 项目代码的质量退化不感知 |

### 3.2 升级方向

**A. 结构化进化日志 — 优先级: HIGH / 难度: LOW**

```
evolution-log.md (当前文本)
       ↓ 升级为
evolution-log.jsonl (结构化)

每条记录:
{
  "ts": "2026-02-20T17:30:00Z",
  "trigger": "drift-detector",     // 触发源
  "dimension": "D2",               // 审计维度
  "finding": "技能数 49 vs 声明 50", // 问题
  "action": "M2:计数修正",          // 修复模式
  "before": "50",                   // 修复前
  "after": "49",                    // 修复后
  "files": ["CLAUDE.md:228"]       // 涉及文件
}
```

好处: 可查询、可聚合、可做趋势图

**B. 预测性审计 — 优先级: MEDIUM / 难度: MEDIUM**

从被动检测升级为主动预测:

```
进化日志模式分析:
  "过去 30 天, D1 (配置一致性) 触发了 12 次修复"
  "每次新增技能后, D2 必定触发"
  "版本号漂移平均 2.3 天出现一次"
      ↓
预测: 下次新增技能时, 自动预生成 SKILL-REGISTRY 条目
      版本号变更时, 自动同步所有引用点
```

**C. 三级自愈体系 — 优先级: HIGH / 难度: MEDIUM**

```
Level 0: 元数据自愈 (当前能力)
  → 版本号/计数/注册表 自动修复

Level 1: 配置自愈 (新增)
  → settings.json 钩子注册缺失时自动补全
  → MCP 配置与实际不匹配时修正
  → tsconfig/eslint 配置漂移检测与修复

Level 2: 质量自愈 (新增)
  → 检测到测试覆盖率下降时, 触发 test-writer 补充测试
  → 检测到新增代码无类型注解时, 提醒 + 自动补全
  → 检测到重复代码 (clone detection) 时, 建议抽取
```

Level 2 的安全边界: 不自动修改, 只生成建议 + PR diff 预览, 等待用户确认。

---

## 四、可观测性升级 (Observability v2)

### 4.1 现状痛点

| 问题 | 影响 |
|------|------|
| JSONL 纯追加, 无索引 | 查询历史事件需要全文扫描 |
| 无指标聚合 | 不知道哪个技能用得最多、哪个最慢 |
| 无告警机制 | 异常模式 (如同一钩子连续拦截) 无法主动通知 |
| watch-activity 仅实时流 | 无历史回放和时间范围查询 |

### 4.2 升级方向

**A. 指标仪表盘 — 优先级: HIGH / 难度: LOW**

新增 `scripts/dashboard.js`:

```
┌─────────────────────────────────────────────┐
│  Bookworm Dashboard — 2026-02-20            │
├─────────────────────────────────────────────┤
│  今日事件: 280  │  Skills: 187  Agents: 43  │
│  MCP: 21        │  Bash: 18     Write: 11   │
├─────────────────────────────────────────────┤
│  TOP 5 Skills:                               │
│    1. frontend-expert    ████████████  34     │
│    2. backend-builder    █████████    28      │
│    3. debugger-expert    ███████      22      │
│    4. architect-expert   █████        16      │
│    5. tester-expert      ████         13      │
├─────────────────────────────────────────────┤
│  钩子拦截率:                                  │
│    block-dangerous:  3 deny / 5 ask / 142 pass│
│    block-sensitive:  1 deny / 2 ask / 98 pass │
├─────────────────────────────────────────────┤
│  磁盘: 1806 MB (GOOD)  │  健康: 80/100       │
└─────────────────────────────────────────────┘
```

数据源: 解析 `debug/activity-*.jsonl`, 纯 Node.js 无依赖

**B. 钩子拦截日志 — 优先级: HIGH / 难度: LOW**

当前 activity-logger 只记录 PostToolUse。拦截事件 (PreToolUse exit 2) 无日志。

新增: `hooks/security-logger.js` (PreToolUse 出口记录)

```jsonl
{"ts":"...","event":"deny","hook":"block-dangerous-commands","reason":"递归删除","command":"rm -rf /"}
{"ts":"...","event":"ask","hook":"block-sensitive-files","reason":"AWS Key","file":"config.js"}
```

输出: `debug/security-YYYY-MM-DD.jsonl`

**C. 周报自动生成 — 优先级: LOW / 难度: LOW**

```
每周日 self-auditor 自动生成:
  - 本周技能使用分布 (哪些没用过 → 考虑是否退役)
  - 钩子拦截趋势 (安全事件是否增多)
  - 磁盘增长曲线 (预测何时触发 WARNING)
  - 路由误触发统计 (如有路由日志)
```

---

## 五、安全体系升级 (Security v2)

### 5.1 现状痛点

| 问题 | 影响 |
|------|------|
| 正则无法处理编码绕过 | `echo cm0gLXJmIC8= \| base64 -d \| sh` 需专门规则 |
| 无运行时沙箱 | 钩子放行后命令无限制执行 |
| 凭证检测仅 pattern matching | 自定义格式密钥无法识别 |
| 无行为基线 | 无法区分正常 rm 和异常 rm |

### 5.2 升级方向

**A. 多层编码解码器 — 优先级: HIGH / 难度: LOW**

在正则匹配前, 增加预处理管道:

```javascript
function preprocess(cmd) {
  let decoded = cmd;
  // 1. Base64 解码 (检测 base64 -d 管道)
  decoded = tryDecodeBase64Pipes(decoded);
  // 2. URL 解码
  decoded = tryDecodeURL(decoded);
  // 3. Hex 解码 (\x72\x6d → rm)
  decoded = tryDecodeHex(decoded);
  // 4. Unicode 解码
  decoded = tryDecodeUnicode(decoded);
  return [cmd, decoded]; // 原始 + 解码后都做检测
}
```

**B. 行为基线与异常检测 — 优先级: MEDIUM / 难度: HIGH**

```
正常行为基线 (从历史 activity-*.jsonl 学习):
  - 用户平均每天 write 23 个文件
  - bash 命令平均长度 45 字符
  - 从未在 /etc/ 下写过文件

异常信号:
  - 突然 write 200 个文件 → 可能是误操作或恶意脚本
  - bash 命令长度 > 500 → 可能是注入攻击
  - 首次写入 /etc/passwd → 高危告警
```

实现: 在 hook-daemon 中维护滑动窗口统计, 超出 3σ 触发 ask。

**C. 钩子完整性自保护 — 优先级: HIGH / 难度: LOW**

防止钩子自身被篡改:

```javascript
// 在 activity-logger.js 启动时校验所有钩子文件的 SHA256
const HOOK_CHECKSUMS = {
  'block-sensitive-files.js': 'sha256:a1b2c3...',
  'block-dangerous-commands.js': 'sha256:d4e5f6...',
  // ...
};

// 不匹配时拒绝启动, 写入安全日志
```

---

## 六、MCP 生态升级 (MCP v2)

### 6.1 升级方向

**A. MCP 健康监测 — 优先级: HIGH / 难度: LOW**

```javascript
// self-auditor D5 增强: 不仅检查配置, 还 ping 可达性
for (const [name, config] of Object.entries(mcpServers)) {
  const healthy = await pingMcpServer(name, config);
  // 记录: 启动耗时、是否可连接、版本号
}
```

**B. MCP 自动发现与推荐 — 优先级: MEDIUM / 难度: MEDIUM**

基于项目 package.json / requirements.txt 自动推荐:

```
检测到 prisma 依赖 → 推荐 @prisma/mcp-server
检测到 supabase 依赖 → 推荐 @supabase/mcp-server
检测到 .github/workflows → 推荐 github-actions-mcp
```

**C. MCP 按需生命周期 — 优先级: LOW / 难度: MEDIUM**

当前全局 MCP 全部常驻。改为按需启动 + 空闲超时回收:

```
mcp-lifecycle:
  cold → 用户触发相关 intent → warm (启动进程)
  warm → 5 分钟无调用 → cold (回收进程)
  好处: 减少内存占用, 7 个 npx 进程 → 按需 1-2 个
```

---

## 七、技能系统升级 (Skills v2)

### 7.1 升级方向

**A. 技能组合 (Skill Composition) — 优先级: HIGH / 难度: MEDIUM**

当前: 1 个输入 → 1 个技能。升级为可组合:

```yaml
# SKILL.md 新增字段
composable:
  requires: [architect-expert]     # 前置依赖
  enhances: [backend-builder]      # 可增强
  conflicts: [frontend-expert]     # 互斥

# 路由引擎: 当匹配到 database-tuning-expert
#   且上下文含 "架构" → 自动注入 architect-expert 的关键指引
```

**B. 技能版本与 A/B 测试 — 优先级: MEDIUM / 难度: LOW**

```
skills/
├── frontend-expert/
│   ├── SKILL.md          # v2 (stable, 当前版本)
│   └── SKILL.v3-beta.md  # v3 (beta, A/B 测试中)
```

路由时按比例分流: 90% 走 v2, 10% 走 v3-beta。记录两者的用户满意度。

**C. 技能退役机制 — 优先级: LOW / 难度: LOW**

基于 activity-logger 数据自动识别:

```
过去 90 天从未被调用的技能 → 标记为 dormant
连续 180 天 dormant → 建议归档
用户确认 → 移到 skills/_archived/
```

---

## 八、测试体系升级 (Testing v2)

### 8.1 现状痛点

| 问题 | 影响 |
|------|------|
| 128 单元测试覆盖功能路径 | 缺少边界值/模糊测试 |
| 无性能基准 | 钩子延迟退化无法发现 |
| production-sim 是黑盒 | 只验证"有日志", 不验证"日志正确" |

### 8.2 升级方向

**A. 性能基准测试 — 优先级: HIGH / 难度: LOW**

```javascript
// hooks/__tests__/benchmark.test.js
describe('性能基准', () => {
  it('block-dangerous-commands 应在 10ms 内完成', async () => {
    const start = performance.now();
    await runHook('block-dangerous-commands', safePayload);
    expect(performance.now() - start).toBeLessThan(10);
  });

  it('8 钩子串行总延迟应在 50ms 内', async () => {
    // 模拟一次完整的工具调用通过所有钩子
  });
});
```

**B. Fuzzing 测试 — 优先级: MEDIUM / 难度: MEDIUM**

```javascript
// 用随机生成的命令字符串测试 block-dangerous-commands
// 确保不会 crash, 且 fail-closed 生效
describe('Fuzzing', () => {
  for (let i = 0; i < 1000; i++) {
    const fuzz = generateRandomShellCommand();
    it(`不应 crash: ${fuzz.slice(0,40)}...`, async () => {
      const result = await runHook('block-dangerous-commands', { command: fuzz });
      expect(result.exitCode).toBeOneOf([0, 2]); // 只允许放行或拦截, 不允许崩溃
    });
  }
});
```

**C. 合约测试 (Contract Testing) — 优先级: MEDIUM / 难度: LOW**

```javascript
// 验证 self-auditor 的输出能被 self-healer 正确消费
describe('auditor → healer 合约', () => {
  it('审计 JSON 应包含 findings 数组', () => { ... });
  it('每个 finding 应有 id/severity/dimension/fix_hint', () => { ... });
  it('healer 应能解析所有 severity 值', () => { ... });
});
```

---

## 九、升级优先级矩阵

按 **价值/成本比** 排序:

| 优先级 | 升级项 | 价值 | 成本 | 建议版本 |
|--------|--------|------|------|---------|
| P0 | 规则外部化 (hooks/rules/*.json) | 高 | 低 | v3.8 |
| P0 | 钩子拦截日志 (security-logger) | 高 | 低 | v3.8 |
| P0 | 结构化进化日志 (JSONL) | 高 | 低 | v3.8 |
| P0 | 性能基准测试 | 高 | 低 | v3.8 |
| P1 | 指标仪表盘 (dashboard.js) | 高 | 低 | v3.9 |
| P1 | 钩子完整性自保护 (SHA256) | 高 | 低 | v3.9 |
| P1 | 多层编码解码器 | 高 | 低 | v3.9 |
| P1 | 技能退役机制 | 中 | 低 | v3.9 |
| P2 | Embedding 语义路由 | 高 | 中 | v4.0 |
| P2 | 技能组合 (Composition) | 高 | 中 | v4.0 |
| P2 | 三级自愈体系 | 高 | 中 | v4.0 |
| P2 | AST 级命令分析 | 高 | 高 | v4.0 |
| P3 | 长驻进程 Hook Daemon | 中 | 中 | v4.1 |
| P3 | MCP 按需生命周期 | 低 | 中 | v4.1 |
| P3 | 行为基线异常检测 | 中 | 高 | v4.1 |
| P3 | Fuzzing 测试 | 中 | 中 | v4.1 |
| P3 | 预测性审计 | 中 | 中 | v4.1 |

---

## 十、版本规划

### v3.8 — 可观测性补全 (预计 1-2 天)
```
新增: hooks/rules/*.json 规则外部化
新增: hooks/security-logger.js 拦截事件日志
升级: evolution-log.md → evolution-log.jsonl
新增: hooks/__tests__/benchmark.test.js
```

### v3.9 — 安全加固 (预计 2-3 天)
```
新增: scripts/dashboard.js 指标仪表盘
新增: hooks/integrity-check.js 钩子文件 SHA256 校验
升级: block-dangerous-commands.js 多层编码解码
新增: 技能退役机制 (基于 activity 日志)
新增: hooks/__tests__/contract.test.js 合约测试
```

### v4.0 — 智能路由 (预计 1 周)
```
新增: skills-embeddings.json 语义向量缓存
升级: CLAUDE.md 路由引擎 → embedding + re-ranking
新增: SKILL.md composable 字段 + 技能组合
升级: self-healer Level 1 (配置自愈)
升级: block-dangerous-commands.js AST 解析
```

### v4.1 — 自主智能 (预计 2 周)
```
升级: hooks → hook-daemon 长驻进程架构
新增: 行为基线 + 异常检测引擎
新增: 预测性审计 (进化日志模式挖掘)
升级: MCP 按需启停生命周期
新增: Fuzzing 测试套件
```