疑難排解

請先查看錯誤 code。 LangDriftError.issues 包含驗證失敗的 JSON Pointer 路徑。 SetupError.files 和 .fields 則指出設定衝突與缺少的輸入。

載入專案

PROJECT_NOT_FOUND

向上搜尋時未找到 .git 根目錄，或缺少 .drifts/project.json。 請明確指定預期的既有根目錄，或在該處執行本機設定。

PROJECT_INVALID

專案檔案是格式錯誤的 JSON，或不符合專案結構定義。 請手動檢視。設定會保留有衝突的內容，不會取代它。

SCHEMA_UNSUPPORTED

事件、產出物、專案或推理封套宣告了 1 以外的結構定義版本。 此候選版本沒有遷移途徑。 請勿在未依第 1 版結構定義檢視資料前，直接更改版本號碼。

產出物與參照

ARTIFACT_INVALID

目前的原因包括：

• 格式錯誤的 JSON，或缺少／無效的 langdrift 前置資料
• 不支援的 .md / .json 用法，或類型與目錄不符
• 未知欄位或其他結構定義不符
• 檔案或本文超過 1 MiB
• 探索上限無效，或超過檔案／目錄上限
• 重複的本機 (type, id) 身分
• 不一致的 Drift 影響值，或缺少 Evidence 來源資訊
• 無效的 GitHub 已合併提取要求測試資料

請閱讀 issues 中的欄位路徑。 剖析器不會從標題或檔名推斷缺少的身分。

PATH_OUTSIDE_ROOT

路徑為絕對路徑、向上穿越、包含禁止的區段或字元，或到達符號連結。 請使用專案 .drifts 目錄樹下的一般相對路徑。 探索絕不會跟隨符號連結。

參照問題

REFERENCE_NOT_FOUND 和 REFERENCE_CYCLE 會在 resolveReferences(...).issues 中傳回，而非拋出。 傳輸前，請登錄明確已知的外部身分、修正精確的類型／ID／路徑，或移除本機循環。

憑證與傳輸

CREDENTIAL_MISSING

參照不是 env:NAME 格式，或環境值不存在、包含換行或空位元組。 請只傳遞參照，並將實際值提供給執行環境。

REMOTE_UNAUTHORIZED

注入的傳輸機制回報 401 或 403。 路由用的 account_id 和 project_id 不會授予權限；請檢視執行時憑證與目的端政策。

REMOTE_REJECTED

注入的傳輸機制回報其他 4xx 狀態。 請檢視已驗證的封套與目的端契約。

MCP_UNAVAILABLE

傳輸失敗，且沒有可分類的 4xx 回應。 本機不會排入任何資料。 請先檢查呼叫端提供的介接器，再重試。

設定

• ROOT_INVALID — --root 無法解析為既有目錄。
• SETUP_ARGUMENT_MISSING — 非互動式執行須提供專案 ID、帳號 ID 和名稱。
• SETUP_ARGUMENT_INVALID — 請檢視支援的旗標、衝突的布林旗標，以及成對的數字型 GitHub 安裝 ID 和 owner/repository。
• SETUP_CONFLICT — 請檢查每個檔案的狀態與原因。預先檢查未寫入任何內容。
• SETUP_PATH_CONFLICT — 受管理路徑是符號連結，或其上層不是目錄。
• SETUP_CONCURRENT_CHANGE — 目的位置在預先檢查後變更，且已保留。
• SETUP_WRITE_FAILED — I/O 失敗中斷建立程序。先前建立的檔案可能保留；請檢查後重新執行。

此版本使用 Loop，且不執行舊版遷移，因此 .drifts/execution 會刻意被視為衝突。

為提供安全的應用程式診斷，reportError(error, logger) 會輸出代碼、通用訊息及驗證問題。 它會省略未知例外的本文與堆疊。