本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文

目標保證

狀態：現行 範圍：目標接受檢查與來源新鮮度 上次審閱：2026-09-14 負責人：AX Code runtime 維護者

目標規劃器產生的程式碼變更計畫會宣告可執行的接受檢查。每項檢查指名它所涵蓋的結果、精確指令、目的，以及預定環境。agent 執行 verify_project 並帶上該檢查的 goalCheck id 時，AX Code 會記錄執行證據。

{ "goalCheck": "invoice-parity" }

指令來自已凍結的目標計畫。agent 不能透過這次呼叫把它換成不同指令。既有的 bash 權限仍然適用。完成目標要求每項已宣告檢查的最新嘗試都通過，且目標、工作階段、工作區、契約與來源內容相符。接受說明解釋結果；它不能取代已執行的檢查。一般 shell 執行，以及被完全略過的檢查，不能提供這項證據。

沒有保證的舊目標計畫保留較早的完成規則。需要新契約時，請清除並重建舊目標；就地編輯其凍結需求會造成契約不符。分叉會保留契約，但需要在新工作階段中重新執行檢查。

準備遷移專案

提供帶有修訂識別碼的權威舊版來源或匯出、有界限的涵蓋清單，以及在斷言無法驗證時會失敗的檢查指令稿。把註解與較早的遷移實作當作待調查的線索。已核准的行為變更要與舊版對等需求分開記錄。

為請求的變更實際影響的層級選擇檢查：

指令稿必須在執行檢查前先斷言目標身分。憑證要放在專案既有的憑證機制中，絕不要放進計畫文字、指令或目標描述。檢查應對失敗的斷言、缺少的環境，或略過的必要斷言回傳非零結束代碼。避免會掩蓋失敗的包裝程式。AX Code 無法從成功的行程結束推斷斷言。

大型遷移請把工作組織成有界限的業務流程批次，並維護一份清單，連結表單、相依性、舊版參照與接受檢查。同時回報已接受的批次與剩餘涵蓋範圍。通過一個批次並不表示完成整次遷移。

計畫記錄的內容

規劃器提供 assurance 物件。這個說明用片段假設專案具有所參照的來源匯出與檢查指令稿：

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

所有接受 id 都必須被涵蓋。指令從工作區根目錄執行。保證物件與接受契約一起凍結。agent 在持續的目標上下文中收到已驗證的範圍、來源參照、檢查 id 與已宣告的目標。缺少或遭改動的契約會產生還原通知。產生的對話摘要仍然可能出錯；已宣告的參照與目標標籤是需求，不是獨立觀察到的事實。

用來衡量此目標改變了什麼的 Git 範圍，必須以 {BASELINE} 作為之前狀態。規劃器會把該佔位符改寫成提交計畫時擷取的 HEAD SHA，因此位於 origin/main 之前、已經存在的提交，或髒的工作樹，不能使目標無法完成。遠端追蹤參照（origin/main、@{u}、refs/remotes/…）會被拒絕作為該之前狀態，除非目標目的指名該遠端。已分歧或髒的路徑請記在風險之下；不要凍結一項已經失敗的閘門檢查，除非目的就是修正該失敗。

新鮮度與限制

Git 來源指紋包含已宣告 sourcePaths 內、受追蹤以及未被忽略之未追蹤檔案的實際位元組。明確的檔案路徑也包含被忽略的設定檔；目錄路徑保留 Git 忽略規則。可變的目標計畫檢查清單被排除；其凍結需求透過契約摘要檢查。非 Git 專案會遞迴為已宣告的 sourcePaths 製作指紋，包括缺少的路徑。該範圍要包含每個相關來源、設定檔與檢查指令稿。

指紋製作限制為 20,000 個項目與 128 MiB 的檔案內容。連結的來源、巢狀 Git 儲存庫、特殊檔案、逸出路徑、變更中的檔案，以及無法讀取的內容，都不能產生新鮮證據。這類失敗會阻擋有保證的完成。檢查輸出成品應放到被忽略的位置，以免產生報告時改變正在驗證的來源。

未被明確指名的忽略檔、來源範圍外的相依性、資料庫與部署，需要在專案指令中有斷言。回執記錄的是執行當下的觀察；它不證明外部狀態之後沒有改變。變更設定、資料庫或部署後，請重新執行受影響的檢查。AX Code 不會自動發現所有舊版行為，也不會認證遷移對等。

規劃何時執行

兩個介面的規劃都是選擇加入。/goal <objective> 與 create_goal 若沒有 assure，會立即開始目標：它沒有凍結的接受條件，完成與否由工作中的計畫（待辦事項）加上最後一次變更後通過的驗證來判斷。/goal --assure <objective> 與 create_goal 若帶有 assure: true，會先執行計畫撰寫器，這才使下方已執行檢查的回執成為完成需求。

沒有契約的目標會在顯示處說明（/goal view、目標對話框、控制訊息），因此你不必推斷其完成閘門。被取代的目標若有有效契約，/goal replace 會保留保證。

規劃上下文與模型選擇

目標規劃透過 /goal 與 create_goal 工具繼承所選的工作階段模型。相容的呼叫端變體會被保留。唯讀撰寫器收到近期的原始使用者需求與附件參照，紀錄預算為 16 KiB。過大的紀錄會停止納入較舊紀錄並附通知，因此較舊的需求不能悄悄取代被省略的修正；內嵌媒體內容不會被當成已檢查的證據。若需求只存在於媒體中，請提供可檢查的來源檔。

進度與阻礙

get_goal 包含目前檢查狀態（通過、失敗、過時、執行中或缺少）與近期工具證據 ID。完成閘門仍要求目前成功的回執。受阻的更新需要阻礙種類、原因、所需的外部變更、原始證據 ID，以及確認沒有剩餘的獨立工作。阻礙原因是由可檢查紀錄支持的模型宣告，不是對外部服務仍然不可用的認證。

重複產生、且沒有新的成功工具證據的已完成回合，會收到復原指引，然後暫停目標並揭露未完成的工作。新的研究結果可以計入而不必編輯來源；重寫待辦與重複的相同結果則不算。這是有界的啟發式，不是語意進度的證明。/goal resume 會開始另一次嘗試。為較早目標產生的工具呼叫不能終止其替代品。工具建立的目標，要在模型於下一步收到建立結果之後，才能用於狀態更新。

修訂既有計畫

使用 /goal revise <correction> 明確修訂作用中、已暫停或受阻的凍結目標。已完成的工作與用盡的預算需要新目標。先前的計畫與摘要保持完整。修訂後的計畫取得新的身分，以及一筆本機準備好的修訂紀錄，連結兩份摘要與該修正。目前的目標身分決定實際安裝了哪個候選；失敗的並行候選可能留在磁碟上供檢查。舊回執留在歷史中，不能滿足新修訂。token 預算與已累計用量會結轉；修訂不會給予新的花費預算。

修訂會取消目前的執行，並在準備新計畫時暫停目標。若規劃失敗，先前的契約仍可恢復；先前受阻的目標會保持該狀態。規劃期間的使用者暫停或取消會阻止啟用。並行的取代會阻止候選接管。模型工具不能悄悄修訂凍結需求。請檢閱產生的計畫與其接受條件；單靠可執行指令並不能確立其斷言涵蓋了修正後的請求。

檢閱結果與之後的來源變更

非空白的檢閱記錄並不表示檢閱成功。對於必要的外部檢閱者，請使用專案擁有的檢查，驗證實際結束代碼、終端完成、來源或 diff 身分，以及最終發現或明確的無發現裁決。僅有警告的記錄、部分推理與逾時都必須失敗。失敗的嘗試請分開保留以供診斷。

新的程式碼變更提交會拒絕被辨識出的簡單檔案存在檢查與檢視檢查。這是狹窄的入場防護，不是對任意 shell 指令的語意證明。既有凍結契約保留其結構描述與摘要；檢查點會在較舊檢查有此弱點時警告。

目標檢查的新鮮度也會為目前目標期間、成功的檔案編輯工具所回報的已解析檔案路徑製作指紋，包括每個 multiedit 結果，以及原始來源清單省略的路徑。之後對那些檔案的編輯會使較早的回執失效。凍結契約與摘要不變。此追蹤使用檔案工具結果的中繼資料；它不會推斷任意 shell 副作用或測試涵蓋。既有的檔案系統侷限、連結、大小與檔案數限制仍然適用。

檢查輸出與目標檢查點會揭露額外路徑。若凍結的測試指令省略了必要的回歸，請請求 /goal revise <correction> 並執行修訂後的檢查。把檔案納入指紋只證明新鮮度，不證明測試行使了該檔案。規劃開放式錯誤掃瞄時，偏好有界的來源目錄，以及包含新回歸的測試指令。

工作區別名會針對觀察到的檔案路徑正規化。外部暫存檔不會變成工作區來源輸入；檢查點會揭露外部內容未被製作指紋。必要的外部狀態仍需要專案擁有的驗證。

提交範圍證據

非空白的 git log <baseline>..HEAD -- <paths> 只證明某次提交符合篩選。它不排除該提交中的無關檔案，或其他提交。新的程式碼變更計畫會拒絕被辨識出的、獨立且非空白的路徑篩選 Git 記錄斷言；較舊的凍結檢查會收到修訂指引，而不改變其摘要或讀取時驗證。

請使用專案擁有的驗證器，檢查基準祖先、要求非空白範圍，並在不使用路徑篩選的情況下檢查每次提交中的每個變更路徑。包含已刪除的檔案與重新命名的兩側，明確處理合併提交，並分開驗證任何必要的分支或訊息屬性。使用 /goal revise 強化既有契約；不要編輯凍結需求。

計畫大小與完整重新提交

呈現的計畫，包括 Markdown 與保證 JSON，必須放進 8,192 個 UTF-8 位元組內。目標是低於 7,168 位元組。若提交超過上限，請縮短重複的說明並重新提交完整物件，包括 kind 與所有必要欄位。保留接受 id 與檢查；執行環境不會截斷需求，也不會提高讀取器上限來接受過大的計畫。

本機 CLI 動畫檢閱回執

儲存庫擁有的 packages/ax-code/script/verify-cli-review-receipts.ts 會檢查 round-* 成品，位置在以 --root 選定的回執根目錄下。每一輪需要 revision.txt，而且 grok、claude 與 codex 各自需要 exit.txt，其中含 0，以及 stdout.jsonl（Grok 文字事件）或 stdout.txt（Claude／Codex）中的一項最終裁決。失敗的嘗試要保存在已完成輪次目錄之外；不要把失敗變成結束代碼為零的回執。

dispositions.json 包含 findings 陣列。每個項目指名 round、cli、id、status（fixed 或 rejected），以及非空白的 evidence。已修正的項目另外需要 regression 物件，其中含字面儲存庫路徑 file（位於 packages/ax-code/test/cli/tui/ 之下）以及精確的 Vitest fullName。重複的處置或含糊的多重裁決會失敗。

驗證器使用已安裝的 Vitest 執行那些檔案，並把全域重試預設設為零（個別測試選項可以覆寫該預設），然後檢查每個被參照的斷言恰好通過一次。缺少、略過、失敗或含糊的斷言會使驗證失敗。這證明那些被參照的測試通過了，而不是它們的斷言在語意上涵蓋該發現。被拒絕的處置仍是已記錄的判斷。最終一輪必須符合目前的 HEAD；標成已修正的發現需要較新的修訂與檢閱輪次。未提交的核心套件來源、測試或設定變更會阻止驗證。不要把無關的本機 ax-code.json 設定放進提交。

對此儲存庫，vitest run --dir test/cli/tui 會在掃描 TUI 目錄時保留一般通道的排除。群組執行器仍可用 AX_TEST_FILES 選擇精確檔案；目錄選擇不會停用排除。