衝突檢測器
一個自包含的技能，用於尋找一組文件中的矛盾。每份文件都會被載入 (路徑 / 內嵌文字 / 內嵌 JSON)，提取其中的事實，然後一個跨文件規則引擎會根據規範金鑰配對主張並標記不匹配的部分。
強制工作流程
相依性引導 (首次使用時執行)
在首次執行前，探查此技能的執行期相依性：
- 核心：純標準函式庫 — 無需安裝。
- 可選：
PyYAML(僅當配置/輸入是.yaml檔案時需要；JSON 輸入可僅使用標準函式庫處理)。
如果缺少 PyYAML 且輸入是 YAML，請告知使用者並詢問是否要 pip install pyyaml；僅在使用者確認後才安裝。未經明確同意，切勿安裝到全域環境中。
- 載入 YAML 配置 (參考
config/examples/two_docs.yaml)。 - 確認每個
documents[].value/documents[].path都可訪問。 - 執行
python -m src.cli run --config <path> [--format json,csv,md]。 - 報告每個層級的衝突數量，並指導使用者前往
./conflicts/conflicts_<run_id>.*。
使用時機
- 必須檢查兩個或更多文件、資料集或提取的事實表之間是否存在矛盾。
- 使用者要求「檢測衝突」、「找出矛盾」、「交叉比對主張」或詢問「這些文件是否一致」。
- 一個主張 (數字、狀態、命名事實) 出現在多個來源中，必須跨來源進行比較。
- 從文件中提取的事實表必須在依賴其結果前，審計其內部一致性。
使用範例
# 在執行前驗證配置 (快速，不寫入報告)。
python -m src.cli validate --config config/examples/two_docs.yaml
# 列出配置解析後的文件來源。
python -m src.cli list-docs --config config/examples/two_docs.yaml
# 執行檢測；選擇輸出格式 (預設：json)。
python -m src.cli run --config config/examples/two_docs.yaml --format json,csv,md
報告會寫入到 ./conflicts/conflicts_<run_id>.{json,csv,md}；JSON 是機器可讀的合約。
錯誤處理
- 配置無效 (
validate以非零狀態碼退出) — 修正報告中提到的欄位並重新驗證；不要手動繞過綱要違規。 - 文件來源無法訪問 — 執行中止並指出有問題的
documents[]條目；請驗證路徑或內嵌值，然後重試。 - 未發現衝突 — 這是一個有效且可報告的結果 (空報告)，不是錯誤；請明確說明，不要重新執行。
- 意外的退出碼 — 逐字報告錯誤訊息；不要退而求其次地手動比較文件。
檢測層級
| 層級 | 種類 | 嚴重性 | 範例 |
|---|---|---|---|
entity | numeric_mismatch, boolean | 高 | speed = 10 與 speed = 20 |
clause | categorical | 中 | status = "active" 與 status = "archived" |
argument | categorical (文字) | 低 | 不一致的自由文字行 |
限制
- 提取是以鍵值為導向；自由文字段落僅在
argument層級參與 (基於行的比較)。 - 單位正規化是透過表格驅動 (
unit_map)；自訂單位規則必須透過配置提供。