bookworm-smart-assistant/skills/evolution-tracker/SKILL.md

---
name: evolution-tracker
version: 1.0.0
description: |
  系统进化追踪器。可视化 Bookworm 系统的进化时间线，分析版本历史、
  变更趋势、触发器分布和修复统计。基于 evolution-log.jsonl 数据。
  触发词: "进化追踪", "evolution", "系统历史", "变更时间线", "版本历史",
  "进化日志", "evolution tracker", "系统进化"。
  支持子命令: timeline, stats, version [ver], search [keyword], health-trend。
maturity: stable
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
---

# /evolution-tracker — 系统进化追踪器

分析 `evolution-log.jsonl` 生成系统进化可视化报告。

## 数据源

```
主数据: ~/.claude/evolution-log.jsonl
辅助:   ~/.claude/stats-compiled.json (当前快照)
辅助:   ~/.claude/debug/health-snapshots/ (历史健康评分)
```

**JSONL 字段**:
| 字段 | 必需 | 说明 |
|------|------|------|
| `seq` | ✅ | 自增序号 |
| `ts` | ✅ | ISO 日期 (YYYY-MM-DD) |
| `version` | ✅ | 系统版本 (vX.Y) |
| `trigger` | ✅ | 触发源 (self-healer/version-bump/auto-cleanup/human/...) |
| `summary` | ✅ | 变更摘要 |
| `scope` | - | 变更范围 (major-upgrade/auto-cleanup/...) |
| `fix_count` | - | 修复文件数 |
| `fix_note` | - | 修复详情 |
| `tags` | - | 分类标签数组 |

## 子命令

根据用户输入匹配子命令。无参数时默认执行 `timeline`。

---

### timeline (默认) — 进化时间线

读取全部 JSONL 记录，按日期分组，生成 ASCII 时间线：

```bash
LOG="$HOME/.claude/evolution-log.jsonl"
TOTAL=$(wc -l < "$LOG" | tr -d ' ')
echo "共 $TOTAL 条进化记录"
```

**输出格式**:

```markdown
## 系统进化时间线

共 N 条记录 | 时间跨度: YYYY-MM-DD → YYYY-MM-DD | 版本: vX.Y → vX.Y

### vX.Y (YYYY-MM-DD — YYYY-MM-DD)
│
├─ MM-DD  [trigger] summary (tags)
├─ MM-DD  [trigger] summary (tags)
│
### vX.Y-1 (...)
│
├─ ...
```

规则:
- 按版本分组，版本内按日期倒序
- summary 超 80 字截断加 `...`
- 每个版本组统计: N 条记录, M 次修复, K 个文件
- major-upgrade scope 用 `★` 标记

---

### stats — 统计分析

生成多维度统计报告:

```bash
LOG="$HOME/.claude/evolution-log.jsonl"
node -e "
const fs = require('fs');
const lines = fs.readFileSync('$LOG','utf8').trim().split('\n').map(l => JSON.parse(l));

// 1. 版本分布
const versions = {};
lines.forEach(l => { versions[l.version] = (versions[l.version]||0) + 1; });

// 2. 触发源分布
const triggers = {};
lines.forEach(l => { triggers[l.trigger] = (triggers[l.trigger]||0) + 1; });

// 3. 标签热力图
const tags = {};
lines.forEach(l => (l.tags||[]).forEach(t => { tags[t] = (tags[t]||0) + 1; }));

// 4. 修复统计
const fixes = lines.filter(l => l.fix_count > 0);
const totalFixes = fixes.reduce((s,l) => s + l.fix_count, 0);

// 5. 活跃度 (按周)
const weeks = {};
lines.forEach(l => {
  const d = new Date(l.ts);
  const w = l.ts.slice(0,7) + '-W' + Math.ceil(d.getDate()/7);
  weeks[w] = (weeks[w]||0) + 1;
});

console.log(JSON.stringify({
  total: lines.length,
  dateRange: [lines[0].ts, lines[lines.length-1].ts],
  versions, triggers, tags,
  fixSessions: fixes.length,
  totalFilesFixed: totalFixes,
  weeklyActivity: weeks
}, null, 2));
"
```

**输出格式**:

```markdown
## 进化统计报告

### 概览
| 指标 | 值 |
|------|-----|
| 总记录数 | N |
| 时间跨度 | X 天 |
| 版本数 | N |
| 修复会话 | N 次 |
| 修复文件总数 | N 个 |

### 版本分布
| 版本 | 记录数 | 占比 |
|------|--------|------|
| vX.Y | N | XX% |

### 触发源排名
| 触发源 | 次数 | 占比 | 柱状图 |
|--------|------|------|--------|
| self-healer | N | XX% | ████████ |
| version-bump | N | XX% | ████ |

### 标签热力图
| 标签 | 出现次数 |
|------|---------|
| security | N |
| metadata-sync | N |

### 周活跃度
(ASCII 柱状图，每周一列)
```

---

### version [ver] — 版本详情

显示指定版本的所有变更记录:

```bash
LOG="$HOME/.claude/evolution-log.jsonl"
node -e "
const fs = require('fs');
const ver = '$1' || 'latest';
const lines = fs.readFileSync('$LOG','utf8').trim().split('\n').map(l => JSON.parse(l));
const target = ver === 'latest' ? lines[lines.length-1].version : ver;
const filtered = lines.filter(l => l.version === target);
console.log(JSON.stringify(filtered, null, 2));
"
```

其中 `$1` 替换为用户指定的版本号。无参数时显示最新版本。

**输出**: 该版本所有记录的详细列表 + 汇总统计。

---

### search [keyword] — 关键词搜索

在 summary、tags、fix_note 中搜索关键词:

```bash
LOG="$HOME/.claude/evolution-log.jsonl"
grep -i "$1" "$LOG" | head -20
```

**输出**: 匹配的记录列表，高亮关键词，按日期倒序。

---

### health-trend — 健康趋势

关联 `debug/health-snapshots/` 中的历史快照数据:

```bash
SNAPSHOTS="$HOME/.claude/debug/health-snapshots"
ls -t "$SNAPSHOTS"/*.json 2>/dev/null | head -10
```

读取最近 N 个快照，提取 overall 评分，与 evolution-log 事件关联:

```markdown
## 健康趋势

日期       评分   事件
2026-03-29  92   ← 中期路线图执行完成
2026-03-28  85   ← v6.4 升级
2026-03-25  92   ← 全面修复 (14 项 HIGH+MEDIUM)
...

趋势: [ASCII 折线图]
```

---

## 输出约定

- 所有输出使用 markdown 格式
- 数字右对齐，百分比保留整数
- ASCII 图表使用全角块字符 (█▓▒░)
- 超过 20 条记录的列表显示 Top 20 + "... 还有 N 条"
- 日期格式统一 YYYY-MM-DD

## 注意事项

- evolution-log.jsonl 是 append-only 日志，不修改现有记录
- 本 Skill 为只读，不写入任何文件
- JSONL 解析容错: 跳过格式错误的行并报告