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

Harness 管控與已驗證評估

狀態：現行

範圍：現行狀態

上次審閱：2026-09-14

負責人：ax-code 執行環境

模型專用的 effort、思考開關與推理重播，請見目前模型的推理控制。

選擇性的上下文與工具控制

在你的 AX Code 設定中，分別啟用每一項實驗：

{
  "experimental": {
    "context_recovery": true,
    "mcp_tool_discovery": true,
    "tail_reminders": true,
    "read_only_recipes": true
  }
}

四個選項預設都是關閉。一起採用之前，請先用你的模型測量工作成功率與經過時間。它們會保留既有的工具權限與隔離設定。請見效能診斷。

context_recovery 會公開 context_recover，並在成功的壓縮摘要加上原始碼指標。這個工具接受關鍵字、訊息 ID、選擇性的部分 ID，以及結果上限。它只讀取目前工作階段，包含壓縮前的歷史，並排除已還原的材料、隱藏的推理，以及被忽略或合成的文字。它傳回原始的訊息與部分 ID，以及有上限的摘錄。搜尋每一頁最多掃描 100 個部分，以及每個部分的前 16,000 個字元；before 會繼續往較舊的部分。找不到相符，並不能證明整段歷史都沒有那段文字。分支使用複製過來的歷史與新的 ID。摘錄裡的憑證指派會被遮罩。

mcp_tool_discovery 讓內建工具保持可用，並為已連線的 MCP 工具引入 tool_search。一次搜尋最多傳回五個相符的結構描述，並讓那些工具在下一次模型請求可用。它不會執行它們。選取範圍限於該工作階段、上限 32 個工具，而且每次請求都會與目前的准入取交集。大型結構描述可能從搜尋結果省略，改在下一次請求載入。若 tool_search 被拒絕，一般已准入的 MCP 目錄仍然可用。既有工具若名為 tool_search，會產生錯誤。

tail_reminders 只把 AX Code 產生的動態回合提醒移到供應商請求的結尾。已儲存的使用者訊息、助理推理、工具歷史與靜態指示都保持不變。這可能改變模型行為與快取的使用方式；它本身不能建立速度提升。

read_only_recipes 會公開 read_recipe。它透過一般的工具分派器，最多執行八個相依的 read、glob 或 grep 呼叫。每個子項有自己的權限檢查、鉤子、取消與工作階段證據。配方不能評估程式碼、執行殼層指令、寫入檔案、呼叫 MCP 工具，或再嵌套另一個配方。

{
  "steps": [
    { "id": "files", "tool": "glob", "parameters": { "pattern": "src/**/*.ts" } },
    {
      "id": "source",
      "tool": "read",
      "parameters": { "filePath": { "$ref": { "step": "files", "path": ["paths", 0] } } }
    }
  ],
  "select": [{ "step": "source", "path": ["text"] }]
}

標準的 glob 結果包含 paths 與 truncated；grep 結果包含 matches，其中有 path、line、text；read 結果包含 kind、呈現後的 text，以及 truncated。請依步驟與自身屬性路徑選取先前的結果。陣列選取支援字面的 contains 篩選與 limit。請檢查傳回的狀態與截斷情形。配方有 60 秒的取消期限、32KB 的引數預算、192KB 的中間結果預算，以及有上限的最終輸出。取消會等待所擁有的工具結束。新的儲存庫指示或媒體會暫停執行，並保留正常的子項輸出，讓模型在繼續之前看得到。成功的選取只在模型請求中取代中間輸出；原始的子項紀錄仍留在歷史裡。被中斷的父項會保留子項輸出。

更正進行中的生成

GET /session/{sessionID}/steering 傳回作用中的生成 UUID 與最近的回執。透過 HTTP 伺服器選擇專案時，請帶上既有的 directory 查詢參數。

送出 POST /session/{sessionID}/steering，內容如下：

{
  "expectedGeneration": "00000000-0000-4000-8000-000000000001",
  "clientID": "correction_1",
  "text": "Preserve the existing public function signature."
}

請使用 GET 得到的 UUID，不要用範例 UUID。accepted 表示更正尚待處理。applied 表示它已在迴圈邊界寫成使用者訊息，並包含其訊息 ID；這不保證供應商會完成。rejected 表示沒有套用。生命週期鉤子可以否決准入。已接受的更正會把即將完成的生成再延長一次迭代，因此在終點送出的更正會被套用，而不是被拒絕；取消與錯誤仍會拒絕待處理的更正，而且舊的生成不能把文字准入給它的下一次生成。相同內容的重試會傳回同一份保留的回執；在既有用戶端 ID 之下放入不同內容，會傳回 HTTP 409。TUI 的 ctrl+s 立即送出手勢使用這個端點。

同一步驟裡的平行工具呼叫

模型在一則助理訊息裡送出數個工具呼叫時，執行環境會透過工作階段範圍的讀寫閘門並行執行它們。唯讀工具共用通道並且重疊執行；檔案編輯、bash、bash_input、筆記本編輯、ops_apply、MCP 工具，以及任何包含非並行安全子項的 batch，會取得獨占通道，並依到達順序單獨執行。在等待時被中止的呼叫絕不會執行。批次對自己分派的呼叫保有排序屏障，子工作階段也有自己的閘門。

回執只存在於處理程序內，每個工作階段最多 256 筆，待處理請求最多 32 筆。已結束的回執與不活躍的工作階段項目可以被清出。重新啟動之後，請取得新的生成，並核對已儲存的訊息；這個 API 不保證重新啟動之後還能持久查詢回執。產生的 SDK 公開 session.steering 與 session.steer。

把已儲存的後續訊息導進進行中的回合

POST /task-queue/{taskID}/steer 會在工作階段進行中之生成的下一個步驟邊界，把佇列裡後續訊息的文字准入進去。送達點與 POST /session/{sessionID}/steering 相同，並在同一請求中取消該佇列列，同時在列的承載上記錄 steeredInto（生成 UUID）與 steeredAt，供稽核使用。只有文字、最多 16,000 個字元的後續訊息可以導向；被導向的文字沿用進行中回合的代理程式、模型與工具。附件、不是後續訊息的種類、已經結束的列，以及過大的文字，會以 HTTP 400 拒絕。請求進行中若該列先變成另一種狀態，則傳回 HTTP 409。

回應帶有最新的佇列項目，以及可為空的回執。沒有作用中的生成時，該列保持不變，回應會回報 generation_not_active，回執為空；呼叫者接著可以改用 POST /task-queue/{taskID}/send-now。它只把該列移到佇列最前面，仍然要等回合結束。被導向的列不能復原，但它會以 cancelled 留在 /queue 歷史中，並帶有稽核欄位，仍然看得到。

在 TUI 裡，input_submit_steer 按鍵綁定（預設 ctrl+s）會在已有打好的草稿時導向該草稿；忙碌工作階段上的編輯區是空的時，它改以 FIFO 順序提升已儲存佇列裡可導向的前綴，並停在第一個不可導向的列，因此後面的後續訊息絕不會插到它前面。側邊欄的後續訊息區段與 /queue 對話框提供相同的逐列立即導向動作，已排入佇列的後續訊息附近會提示目前綁定的按鍵。產生的 SDK 公開 taskQueue.steer。

從已驗證的工作提出技能

技能候選是 AX Code 既有本機儲存體中的明確紀錄。在你提升它們之前，它們不會進入技能探索，也絕不會觸發自動的模型呼叫或指示改寫。

以 name、description、applicability、procedure 與 evidence 建立提案 JSON 檔；後者內含 sessionID、messageID 與 partID。證據必須指出一份原始且成功的 verify_project 結果，其中包含針對目前乾淨 Git 修訂執行過的測試或型別檢查封套。只寫一句成功，或任意的殼層結束代碼，並不足夠。驗證必須引用另一個工作階段在同一修訂上的成功驗證。

ax-code skill candidate propose --proposal proposal.json
ax-code skill candidate show verified-procedure
ax-code skill candidate validate verified-procedure --proposal independent-evidence.json
ax-code skill candidate promote verified-procedure
ax-code skill candidate retire verified-procedure

請把輸入 JSON 放在工作樹之外，或放在被忽略的本機目錄，乾淨修訂檢查才有意義。提升會建立 .ax-code/skill/{name}/SKILL.md，而不覆寫既有技能。來源證據會在提升之前再檢查一次。符號連結的目錄會被拒絕。停用只移除該候選自己、且未被改過的檔案；手動編輯會造成衝突。請重新啟動既有的執行環境執行個體，以重新整理它快取的技能探索。通過檢查只為那些檢查建立證據；提升之前請審閱該程序是否適用。

擷取配對實驗

從原始碼工作複本使用：

pnpm --dir packages/ax-code exec tsx script/harness-eval.ts run /path/to/manifest.json > /path/to/runs.ndjson
pnpm --dir packages/ax-code exec tsx script/harness-eval.ts compare /path/to/runs.ndjson baseline candidate

受信任的操作者資訊清單包含明確的 provider/model、runtimeRevision、選擇性的 CLI command argv、repetitions、timeoutMs、恰好兩個具名的 arms，以及 tasks。每個實驗臂有選擇性的 features（即上方那些實驗旗標）與 toolProfile。每項工作提供 id、prompt、內嵌的 files（path 與 content），以及 oracle。判定程式是受信任的 JavaScript，由 Node 在程式開發處理程序結束之後執行；process.argv[1] 用來識別暫存測試夾具。它的程式碼留在代理程式工作區之外，而且絕不會來自模型的回應。

每次嘗試都會拿到全新的 Git 測試夾具。判定程式必須在初始測試夾具上以結束代碼 1 失敗。執行器使用固定的無介面 CLI 叫用，在各次重複之間交替實驗臂的順序，套用逾時，並在完成的嘗試之後再跑一次判定程式。elapsedMs 包含程式開發處理程序與執行後驗證；verificationMs 會另外標出後者。測試夾具的設定，以及最初那次失敗檢查，都不算在內。串流會在每次嘗試完成、失敗、逾時或取消的當下記錄它。評估紀錄不會送出原始提示、子處理程序輸出與憑證。被中斷的批次仍然不完整，不能產生配對比較。

比較會拒絕重複項目，以及缺少或不符的工作、模型、批次與重複次數配對。失敗與未驗證的嘗試仍留在成功率的分母裡。延遲中位數與成對比率，明確以已驗證的成功為條件。P95 需要在同一個工作、模型、批次與實驗臂的儲存格內有 20 次成功觀察；混合儲存格的彙總會省略它。批次會對資訊清單取雜湊，但執行環境修訂，以及外部的供應商、設定與快取條件，仍需要操作者自行控制。小型冒煙測試不能證明一般情況下速度較優，也不能作為改變預設的理由。

能力選擇與復原診斷

當模型至少有 64,000 token 的上下文、支援推理，並且支援工具時，自主請求可以包含長代理程式上下文套件。沒有登錄項目的模型，這三項都必須在解析後的模型中繼資料裡宣告。補充套件的字元估計上限是 2,048 token；它不是對話視窗。明確的否定宣告與已登錄的限制會阻止准入。這項提示文字的最佳化，不能證明與快取或保留思考相容，也不會改變自動的 Super-Long 期限與步調。那些仍沿用既有的資格條件與覆寫規則。

最新一則使用者訊息之後，若連續兩次結構化工具失敗（在合成的尾端提醒之前計數），而且存在可用的 effort 變體，下一次模型呼叫會要求更深的推理。成功的工具結果會把計數歸零。使用者明確指定的 effort，以及已設定的推理選項，仍然優先。這改變的是 effort 的選擇，不是重試上限或工具權限。

本機的 llm.request 重播事件包含 capabilityResolution：協定、上下文視窗、是否選了上下文套件或 Super-Long 模式、連續的工具失敗次數，以及推理選擇或未套用的原因。boundary: "policy-selection" 描述的是 AX Code 的決定；外掛與供應商 SDK 仍可能改動最終請求。明確的 GPT-6 effort 值會被保留；API 要求 low 或更高，而不是 none 或 minimal。事件保留的是請求雜湊，不是提示或憑證本文。沒有 effort 變體，並不表示供應商預設的思考已經停用。

配對的 harness 擷取會讀取 CLI 的 JSON step_finish 與 tool_use 事件，取得輸入、輸出、推理與快取讀取的 token、已完成的工具呼叫，以及工具錯誤。重複的部分 ID 只計一次。metricsStatus 是 observed、partial 或 unavailable。被截斷或格式錯誤的串流，以及被中斷的嘗試，不會給出總計。比較會報告每個指標已觀察到與缺失的執行次數，以及中位數，包含有觀察值的失敗嘗試。缺失的值仍然算缺失。這些計數描述的是送出的執行環境事件，不是供應商計費、子工作階段用量，或原生 CLI 內部工具。完整觀察到、但沒有終端工具事件的串流，會回報零次工具呼叫。工作是否成功仍以判定程式的驗證為準；只有用量不能證明復原成功，也不能證明品質較好。