bookworm-smart-assistant/scripts/UPGRADE-ROADMAP-v4.md

549 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 测试套件
```