document-evolution-tracker
一個自包含的技能，用於追蹤文件在不同版本間的演變。給定一個版本家族（例如包含 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）。