文档演化追踪器 是做什么的？
一个独立的技能，用于追踪文档在不同版本之间的演化。
给定一个版本家族（例如包含 v1.md, v2.md, ... 或时间戳文件的目录），
它会计算连续版本之间的段落级差异，并追踪概念谱系（引入、保留、修改、
丢弃）。
强制流程
依赖引导（首次运行时）
在首次运行前，探测该技能的运行时依赖：
- 核心：纯标准库 —— 无需安装。
- 可选：
PyYAML（仅当配置文件为.yaml时；JSON 配置 仅使用标准库即可工作）。
如果缺少 PyYAML 且配置文件为 YAML 格式，则告知用户并询问
是否要 pip install pyyaml；仅在用户确认后才安装。切勿
在未经明确同意的情况下安装到全局环境中。
-
加载一个配置（参考
config/examples/family.json；当 PyYAML 已安装时 也支持 YAML 配置）。 -
确认
versions_dir至少包含两个版本文件。 -
python -m src.cli run --config <路径> [--concepts "A,B"]。 -
报告过渡次数并引导用户查看
./evolution/evolution_<跟踪ID>.{md,json}。
适用场景
- 有一系列文档版本（按时间戳或顺序命名）需要 随时间进行比较。
- 用户提出“追踪文档变更”、“版本历史”、“ 草稿间变化”或“概念谱系”。
- 需要跨草稿追踪一个命名概念（术语、标题、 定义）的引入、修改或丢弃时间。
- 需要以时间线而非单一端到端差异的形式 报告草稿的演化。
使用示例
# 验证配置并查看发现的版本文件。
python -m src.cli validate --config config/examples/family.json
python -m src.cli versions --config config/examples/family.json
# 运行追踪器；可选指定要追踪的概念。
python -m src.cli run --config config/examples/family.json --concepts "entropy,partition function"
报告写入 ./evolution/evolution_<跟踪ID>.{md,json}；
Markdown 时间线供读者阅读，JSON 供程序化使用。
故障处理
- 配置无效（
validate退出码非零）——修复报告指出的字段 并重新验证；命名方案和versions_dir通常是 问题所在。 - 发现少于两个版本——运行中止；检查
version_naming规则与实际文件名是否匹配，然后重试。 - 某个概念从未出现——它会被报告为在所有版本中 缺失，这是有效结果，而非错误。
- 意外退出码——逐字报告错误信息；不要回退 到手动比较文件。
差异粒度
| 粒度 | 分割规则 |
|---|---|
line | 非空行 |
paragraph（默认） | 空行分隔的块 |
sentence | 标点分隔的句子 |
限制
- 差异对比是结构性的（通过
difflib进行块对齐），而非语义性的。 一个概念仅在版本的文本中出现其精确短语（不区分大小写）时才 “存在”。 - 不支持
sequential/timestamp之外的自定义命名方案。