SourceTrace 原始軌跡是做什麼的？

SourceTrace 會將 AI 生成的知識樹與其來源圖像進行比對，並針對每個問題提供可追溯的證據說明。使用者無需憑空相信任何發現：每個發現都會說明為什麼它是個問題、來源材料在哪裡（頁碼與引文），以及依據什麼（證據 ID）。

一般的模型通常能找出錯誤。SourceTrace 的附加價值在於結果是可查證的：每個節點與邊都有判定，每個判定都引用證據，類別與風險等級固定，且每次輸出的格式一致。

輸入

來源圖像： PNG/JPG 格式，每頁一張（例如匯出為圖像的投影片）。它們是唯一的真相來源。如果使用者有 PPT 或 PDF，請要求他們先匯出為圖像。
知識樹： 符合 schemas/knowledge-tree.schema.json 的 JSON（節點包含 id、label、definition、kind；邊包含 id、source、target、relation）。如果知識樹使用其他格式或其他關係名稱，請先進行轉換，並告知使用者你所做的映射。

以下路徑如 scripts/…、schemas/… 和 references/… 均相對於此技能所在資料夾。

輸出

將所有檔案寫入同一個輸出資料夾，預設為知識樹旁邊的 sourcetrace-output/：

檔案	階段	內容
`evidence-index.json`	2	從圖像中提取的每一項證據（由你撰寫）
`audit.json`	4–6	每個節點與邊的判定，以及遺漏項目（你撰寫判斷；腳本將其補全）
`report.md`	6	人類可讀的報告（由 `scripts/build_report.py` 產生；請勿自行撰寫）

切勿修改使用者的知識樹。SourceTrace 僅負責報告與建議；由使用者決定最終取捨。

工作流程

依序執行六個階段。在證據索引建立之前，請勿跳過到判斷知識樹的步驟：針對索引進行審計（而非僅憑你對投影片的印象）才能使發現具有可追溯性。

1. 來源攝取

python scripts/validate_input.py --tree <knowledge-tree.json> --images <image folder or files> --json

錯誤（"valid": false）：停止，以白話方式向使用者說明錯誤，並請他們修正輸入。請勿對無效的知識樹進行審計。
警告（例如 DISCONNECTED_TREE、ISOLATED_NODE、DUPLICATE_EDGE）：繼續執行。build_report.py 會將它們放入報告的「結構」章節。
summary.images 為每個圖像指定其 source_id 與 page。在第 2 階段中，請準確使用這些識別碼。

然後檢視每個圖像，記下其標題、文字、表格與圖表。

2. 證據提取

按照 references/evidence-extraction.md 建立 evidence-index.json。在提取之前請先閱讀該檔案；簡而言之：

每個投影片標題、項目符號、表格列與圖表關係各為一個項目。
以原文逐字引用文字。細微的措辭變更正是審計必須捕捉的目標。
提取所有內容，包括作業或閱讀筆記。
誠實設定 certainty；low 可信度的證據本身無法駁斥知識樹中的項目。

然後驗證其內容，並在繼續之前修正所有錯誤：

python scripts/validate_evidence.py --index <output>/evidence-index.json

3. 知識映射

將知識樹視為一系列待檢驗的主張，而非事實。將其拆分為：

節點： 標籤與定義是否正確？
邊：兩個節點之間的關係是否正確？將邊解讀為 來源關係目標。

分別對它們進行審計。節點可能正確，但使用該節點的邊卻不正確（反之亦然）；每個節點與邊都將獲得各自獨立的判定。

針對每個節點與邊，列出與其相關的證據項目。搜尋整個索引，而不僅僅是你預期的頁面：有些主張只有在結合兩頁內容時才能被確認或駁斥。

4. 雙向審計

樹 → 來源： 對於每個節點與邊，判斷證據是否支持它。每個節點與邊都必須獲得判定，包含正確的部分；確認正確的內容也是結果的一部分。
來源 → 樹： 遍歷證據索引，找出未被任何節點或邊涵蓋的重要內容。

請遵循 references/audit-rules.md 中關於判定方式、何謂重要內容以及邊界情況的說明。

5. 衝突檢測

將每個問題分類到恰好一個類別，並賦予風險等級。使用 references/audit-rules.md 中的決策順序：依序回答其問題，在遇到第一個「是」時停止。請勿憑感覺選擇類別；這個順序是保持兩次執行一致性的關鍵。

類別	說明
`conceptual-error`	節點的定義與來源衝突。
`incorrect-relationship`	邊的關係與來源衝突，即使兩個節點都正確。
`unsupported-expansion`	內容未在來源中找到，即使一般來說是正確的。
`overgeneralization`	受支持的內容被延伸至超出來源所述範圍。
`ambiguous`	過於模糊或不確定，無法確認或駁斥。
`omission`	重要的來源內容在知識樹中遺漏。

6. 審計報告

將你的判斷寫入 audit.json，然後讓腳本檢查並產生報告。你負責決策；腳本負責計數、編號、排序與格式化。這種分工方式能讓兩次執行產生相同的報告。

你寫入的 audit.json（v0.1，schema 為 schemas/audit.schema.json）：

{
  "schema_version": "0.1",
  "items": [
    { "target": "N001", "verdict": "supported", "evidence": ["EV-002"] },
    { "target": "N002", "verdict": "finding", "evidence": ["EV-008"],
      "category": "conceptual-error", "risk": "high",
      "reason": "...", "recommendation": "..." }
  ],
  "omissions": [
    { "category": "omission", "tier": "core", "risk": "medium", "evidence": ["EV-016"],
      "reason": "...", "recommendation": "..." },
    { "category": "omission", "tier": "core", "risk": "high", "risk_reason": "central concept of the lecture",
      "evidence": ["EV-003"], "reason": "...", "recommendation": "..." }
  ]
}

items： 知識樹中每個節點與邊各有一個對應項目。
reason： 說明為什麼這是個問題，用一兩句話描述，並引用確切不同的文字。
recommendation： 具體的修訂建議，且須符合知識樹 schema（僅允許使用 kind 與 relation 的合法值）。
tier（僅限 omission）：core 或 supporting，定義見 references/audit-rules.md。
risk_reason： 僅在風險等級與預設值不同時使用。
請勿包含 summary、structure_warnings 與 finding_id；腳本會自動計算。

然後執行：

python scripts/build_report.py --tree <knowledge-tree.json> --index <output>/evidence-index.json --audit <output>/audit.json

錯誤： 不會寫入任何檔案。請修正 audit.json 並重新執行，直到成功為止。請勿繞過檢查機制。
成功： 腳本會使用 summary、structure_warnings 和 finding_id（F-001、F-002，依報告順序排列）改寫 audit.json，並在旁邊寫入 report.md。報告語言會與投影片語言一致；如果使用者要求其他語言，可傳入 --lang zh 或 --lang en。

最後，告知使用者報告的位置、摘要中的計數，以及最重要的幾個問題（以幾行說明即可）。請勿貼上整份報告。

處理特殊輸入

無法讀取的圖像： 以 low 可信度提取你能辨識的內容，在受影響的發現之 reason 中提及該頁面，並告知使用者；請勿憑空捏造內容。
知識樹涵蓋了圖像中沒有的素材（例如僅提供了部分投影片）：將這些項目標記為 unsupported-expansion，並告知使用者可能是缺少頁面所導致。
非常大的投影片組或知識樹： 在第 2 階段逐頁處理，在第 4 階段逐節點處理，並將結果邊做邊寫入檔案，而非全部記在腦中。

SourceTrace 原始軌跡