---
name: evo-tracker
version: "2.1.0"
category: tools
description: "当用户需要追踪项目演进时使用：记录版本变更、生成 changelog、目录快照、维护演进历史。不要用于 git commit 追踪（git 已处理）。Use when user wants to track project evolution: record version changes, generate changelog entries, snapshot directory structure, or maintain an evolution history for their requirement/code project. Do NOT use for git-level commit tracking (git already handles that)."
triggers:
  zh: ["记录变更", "版本记录", "更新日志", "changelog", "演进记录", "目录快照", "版本历史", "变更追踪", "记录一下", "存档"]
  en: ["changelog", "version history", "evolution", "snapshot", "track changes", "record version", "project diary", "milestone"]
license: MIT
compatibility: Node.js >= 14
config: 
  - config/evo-tracker.yaml
metadata: 
  author: "sunhongda@example.com"
  created: "2026-06-17"
  updated: "2026-06-19"
  status: "stable"
---

# 演进追踪 / Evo Tracker

## Changelog / 版本履历

| 日期 | 版本 | 变更摘要 |
|------|------|---------|
| 2026-06-17 | 1.0.0 | 初始版本：版本记录、变更日志生成、目录快照、演进报告 |
| 2026-06-19 | 2.0.0 | **BREAKING**: Mode 2 重构——进化记录要求变更动机/概要/影响/决策四段式，废弃 git-commit 风格 |
| 2026-06-19 | 2.1.0 | feat: Mode 5 自动触发——post-commit hook + evo-post-push.sh + pending-changes.log |

***

## Core Concept / 核心概念

### 🇨🇳
在用户的目标项目（需求工程或代码工程）中自动维护 `.evo/` 演进目录，记录每次关键变更的版本信息、变更摘要、目录结构快照，并生成结构化的演进报告。**不做** git 提交管理（git 本身已足够），只做人类可读的演进文档。

### 🇺🇸
Auto-maintains a `.evo/` evolution directory in the user's target project (requirements or code engineering), recording version info, change summaries, directory snapshots for each key change, and generating structured evolution reports. **Does NOT** manage git commits (git handles that) — only produces human-readable evolution docs.

***

## Position / 定位

```
用户的目标项目 (需求/代码工程)
        │
        ├── .evo/                    ← 演进目录 (本 skill 自动创建)
    │   ├── EVOLUTION.md         ← 演进主文档 (版本 + 变更时间线)
    │   ├── VERSION              ← 当前版本号文件
    │   ├── pending-changes.log  ← git hook 自动写入的待记录变更 (AI 检测用)
    │   ├── snapshots/           ← 目录结构快照
        │   │   ├── v1.0.0.md
        │   │   └── v1.1.0.md
        │   └── VERSION              ← 当前版本号文件
        │
        ▼
    用户触发: "记录这次变更" / "生成演进报告"
        → 本 Skill 读取项目状态 → 更新 .evo/ 目录
```

***

## Workflow / 工作流程

### Mode 1: Initialize / 初始化 (首次使用)

```
Trigger: "开始追踪这个项目的演进" / "init evolution tracking"
Action:
  1. 检测用户当前工作目录 (项目根)
  2. 创建 .evo/ 目录结构
  3. 生成初始 VERSION 文件 (如 "0.1.0") 和 EVOLUTION.md 骨架
  4. 创建初始目录快照 snapshots/v0.1.0.md
Output: .evo/ 目录创建完成，提示用户后续如何使用
```

### Mode 2: Record Significant Change / 记录重大变更

Trigger: "记录这次变更" / "记录演进" / "记录版本变更"

Action:
1. 检测 .evo/ 目录是否存在 (不存在则先初始化)
2. 读取当前 VERSION
3. 获取变更上下文（从用户的描述或当前会话的操作中）：
   a. **变更动机**（为什么做这个变更？解决了什么问题？驱动因素是什么？）
   b. **变更概要**（具体改了什么？新增/修改/删除了哪些内容？）
   c. **影响范围**（影响了哪些文件/模块/章节？是否影响下游依赖？）
   d. **关联决策**（参考了哪些会议纪要/制度文件/用户需求？）
4. 确定版本升级类型 (major/minor/patch)
5. 更新 VERSION 文件
6. 在 EVOLUTION.md 中追加一条结构化变更记录
7. [可选] 创建新的目录结构快照

Output: 更新后的 VERSION + EVOLUTION.md

### Mode 3: Generate Snapshot / 生成目录快照

```
Trigger: "生成目录快照" / "snapshot directory"
Action:
  1. 扫描项目目录树 (排除 .git, node_modules, .evo, dist, etc.)
  2. 生成 markdown 格式的 tree 视图
  3. 保存到 .evo/snapshots/v{version}.md
Output: 目录快照文件
```

### Mode 5: Auto-Trigger via Git Hooks / 通过 Git Hooks 自动触发

```
Trigger: git commit → post-commit hook → writes pending-changes.log
         git push   → evo-post-push.sh   → detects pending changes → prompts user

Mechanism:
  1. post-commit hook (installed by skills/scripts/setup-hooks.sh):
     - After every commit, appends commit info to each .evo/pending-changes.log:
       [abc123] 2026-06-18T14:30:00+08:00 | feat(evo): 初始化演进追踪
         Files: prd/.evo/VERSION skills/.evo/VERSION ...
     - Also triggers skill validation + doc refresh when SKILL.md files change

  2. evo-post-push.sh (push wrapper):
     - Usage: bash skills/scripts/evo-post-push.sh [git-push-args]
     - Or set git alias: git config alias.pevo '!bash skills/scripts/evo-post-push.sh'
     - After successful push, scans all .evo/pending-changes.log files
     - Displays pending changes and prompts user to run evo-tracker

  3. Sisyphus Integration:
     - When Sisyphus handles git push (via git-workflow), it checks pending-changes.log
     - Automatically prompts: "检测到 N 个待记录的演进变更，是否现在记录？"
     - On user confirmation, proceeds with Mode 2 (record significant change)

Setup:
  bash skills/scripts/setup-hooks.sh          # Install post-commit hook
  git config alias.pevo '!bash skills/scripts/evo-post-push.sh'  # Optional: push alias

Clear pending logs after recording:
  bash skills/scripts/evo-post-push.sh --clear
```

### Mode 4: Generate Report / 生成演进报告

```
Trigger: "生成演进报告" / "evolution report"
Action:
  1. 读取 .evo/EVOLUTION.md 中所有变更记录
  2. 读取 .evo/snapshots/ 中的关键快照
  3. 聚合为结构化报告:
     - 项目总览 (名称、当前版本、总变更次数)
     - 版本时间线 (每个版本的变更摘要)
     - 目录结构演变 (从快照中对比)
      - 变更分类统计 (major/minor/patch 数量)
Output: 演进报告 (输出到屏幕或文件)
```

***

## .evo/ Directory Spec / .evo/ 目录结构规范

```
{用户项目根}/
└── .evo/
    ├── VERSION              # 纯文本: "1.0.0"
    ├── EVOLUTION.md         # 演进主文档
    │   # 格式 (每版本一条记录):
    │   #
    │   # ## [1.0.0] - 2026-06-18
    │   #
    │   # ### 变更动机 (Why)
    │   # 基于 2026-06-18 会议纪要的 5 项关键决策，需全面重构驾驶舱文档以对齐设计方向。
    │   # 核心驱动力：权限模型变更（实例→模板）、组件指标绑定简化（1:1）、文档可读性提升。
    │   #
    │   # ### 变更概要 (What)
    │   # - **新增**：§〇 核心概念关系图（三层设计时模型：指标→组件→模版）
    │   # - **重构**：27 条指标由紧凑表格改为逐项详述，新增 availableDimensions/apiInterface 字段
    │   # - **重构**：22 个组件由表格改为逐项详述，新增 interactionType/outputParams 字段，拆分多指标组件
    │   # - **删除**：§5.3 实例权限规则，权限字段 scopeRule/targetRoles 从实例元数据移除
    │   # - **迁移**：权限定义上移至模版层，§5.3 可见性矩阵迁移至 §六
    │   # - **清理**：删除 stakeholders/drillFields/aggGranularity/indicatorCategory 残留字段
    │   #
    │   # ### 影响范围 (Impact)
    │   # - 文件：prd/驾驶舱-完备需求分析-终版-V5.md (599→1085 行)
    │   # - 章节：§〇(重写)/§三(重构)/§四(重构)/§五(删除)/§六(精简)
    │   # - 跨引用：全部 §六/§七/§八/§九 引用重新编号为 §五~§八
    │   #
    │   # ### 关联决策 (Decisions)
    │   # - 会议纪要：meeting/20260618会议纪要.md (5 项关键决策)
    │   # - 默认应用：组件 interactionType 联动语义（可点击联动/被联动刷新/无交互）
    │   # - 默认应用：指标 outputParams 过滤参数类型化
    │   # - 延迟项：字段血缘暂不纳入（待林姐 Excel 就绪）
    │   #
    │   # ## [0.2.0] - 2026-06-15
    │   # ...
    │
    └── snapshots/           # 目录结构快照
        ├── v1.0.0.md        # 1.0.0 版本时的目录树
        └── v1.1.0.md
```

***

## Iron Law / 核心铁律

### 🇨🇳
1. **只追踪人类可读的演进，不管 git**: Evo-tracker 生成的是供人阅读的版本文档和 changelog，不是 git 的替代品。违规：❌ 尝试用 evo-tracker 替代 `git commit`。合规：✅ 在 git commit 之外，额外生成人类友好的演进文档。
2. **初始化前必须确认项目根**: 不在非项目目录创建 .evo/。违规：❌ 在 /tmp 创建 .evo/。合规：✅ 先确认当前目录是项目根（含 .git、package.json 或需求文档）。
3. **不覆盖已有记录**: 追加模式，永不删除或覆盖已有变更条目。违规：❌ 直接改写 EVOLUTION.md 的历史记录。合规：✅ 始终在头部追加新记录。
4. **最小侵入**: .evo/ 目录只有一个目的——追踪演进。不在其中放配置、脚本或其他东西。违规：❌ 在 .evo/ 放 CI 配置。合规：✅ .evo/ 只含 VERSION, EVOLUTION.md, snapshots/。

### 🇺🇸
1. **Track human-readable evolution, not git**: Produces readable version docs, not git replacement.
2. **Confirm project root before init**: Never create .evo/ outside a real project.
3. **Never overwrite existing records**: Always append, never mutate history.
4. **Minimal intrusion**: .evo/ serves one purpose — evolution tracking. No configs or scripts.

***

## Red Flags / 三层防御

### Layer 1: Input / 输入
- **INPUT-01**: 用户不在项目目录中 → 🟡 WARN → 提示用户先 cd 到项目根
- **INPUT-02**: 用户提供的版本号不符合 semver → 🟡 WARN → 自动修正或提示用户确认
- **INPUT-03**: 检测不到 .evo/ 目录且用户消息不是"初始化" → 🔵 INFO → 询问是否初始化

### Layer 2: Execution / 执行
- **EXEC-01**: VERSION 文件格式损坏 → 🔴 CRITICAL → 中止，提示手动检查
- **EXEC-02**: 目录快照生成失败 (权限问题) → 🟡 WARN → 跳过快照，继续记录变更

### Layer 3: Output / 输出
- **OUTPUT-01**: EVOLUTION.md 写入失败 → 🔴 CRITICAL → 报告错误，保留旧文件

***

## Output / 输出规范

### 🇨🇳
每次操作后输出简要摘要：
- **初始化**: "✅ 已在 {项目根} 创建 .evo/ 演进目录，当前版本 0.1.0"
- **记录变更**: "✅ 已记录重大变更: [v6.0.0] → .evo/EVOLUTION.md"
- **快照**: "✅ 已保存目录快照: .evo/snapshots/v1.0.0.md (包含 {N} 个文件)"
- **报告**: 输出到终端或写入 .evo/REPORT-{date}.md

### 🇺🇸
Brief summary after each operation.

***

## Auto-Review / 自检清单

| # | 检查项 |
|---|--------|
| 1 | .evo/ 目录是否存在且结构正确 |
| 2 | VERSION 中的版本号是否符合 semver |
| 3 | EVOLUTION.md 中的记录是否按时间倒序 |
| 4 | 是否只在用户明确请求时才操作 (不是每次对话都记录) |
| 5 | 新记录是否追加而非覆盖 |

***

## Examples / 示例

### 场景1: 首次使用，初始化演进追踪
```
用户: "帮我初始化这个项目的演进追踪"
Evo-tracker:
  1. 检测到 /Users/me/my-project 含 .git 目录
  2. ✅ 创建 .evo/VERSION (0.1.0)
  3. ✅ 创建 .evo/EVOLUTION.md
  4. ✅ 创建初始快照 .evo/snapshots/v0.1.0.md
```

### 场景2: 完成一个重大变更后记录
```
用户: "记录演进，这次基于会议纪要重构了V5文档"
Evo-tracker:
  1. 读取当前版本: 5.1.0
  2. 分析上下文（从会话中提取变更动机/概要/影响/决策）
  3. 更新 VERSION: 6.0.0 (major — 架构级变更)
  4. 追加到 EVOLUTION.md:
     ## [6.0.0] - 2026-06-19
     ### 变更动机
     基于 2026-06-18 会议纪要...
     ### 变更概要
     - 重构：27条指标逐项详述...
     ### 影响范围
     ...
     ### 关联决策
     ...
  5. ✅ 已记录演进: v6.0.0
```

### 场景3: 查看演进报告
```
用户: "生成演进报告"
Evo-tracker:
  1. 读取 .evo/EVOLUTION.md
   2. 聚合: 总版本 3 个, major 2 次, minor 1 次, patch 1 次
  3. 输出:
     # 项目演进报告
     当前版本: 1.0.0 | 总变更: 8 次 | 活跃天数: 12
     ...
```