coding agent tool design feedback error code

實作

讓工具回饋說清楚：哪裡失敗、接著能做什麼

把雜訊很多的指令與不透明瀏覽器失敗改成窄工具，回傳穩定代號、有限證據與一個安全修復方向。

難度
中階
預估時間
120 分鐘
更新日期
2026-10-02
文案複核
speak-human-tw
兩輪
本課內容
  1. 01先把定義說清楚
  2. 02現場情境
  3. 03實作範例
  4. 04照著做，每一步都有檢查點
  5. 05實務脈絡
  6. 06動手實作
  7. 07故障診間
  8. 08正式上線前的邊界
  9. 09資料來源與主張限制

這一課會完成什麼

  • 依任務設計工具輸入，避免提供可執行任意 Shell 指令的繞過入口
  • 回傳精簡有型別的觀察紀錄，保留證據但不塞爆脈絡
  • 分開模型需要的修復提示，以及只供授權操作人員讀取的詳細診斷
  • 測成功、輸入格式錯誤、權限拒絕、逾時、超出大小限制與寫入結果未知

開始前先準備

  • • 模組 01 到 04 的契約、地圖、初始化程序與功能台帳
  • • 可重播指令、API、資料庫與瀏覽器結果的本機模擬轉接層

先把定義說清楚

可判讀的工具回饋

供 Agent 使用的工具要有明確邊界：輸入經 schema 驗證，權限由執行環境提供，結果以封閉聯集型別表示，並指出失敗在哪一層、允許的下一步是什麼。模型不必從數千行終端輸出猜測狀態，也不能自行填入權限。脈絡只接收簡短觀察與證據識別碼，完整的遮蔽紀錄、執行軌跡和截圖留在受保護的儲存區，需要時再透過明確介面讀取。

程式撰寫 agent 依靠環境回饋決定下一步。指令只回退出 1、瀏覽器執行器把 skipped 當成功，或 API 輔助函式無法區分 denied、逾時與 partial 操作效果，下一步便只能猜。模型多想幾輪，也無法還原工具丟掉的證據。

通用 shell 適合探索，重複工作則值得做受限範圍。具名檢查可以驗正確路由、限制輸出、遮蔽測試資料 token、保存截圖，並回穩定修復代號。規則與證據由應用程式程式碼控制，agent 則拿到足以行動的觀察紀錄。

現場情境

綠色命令掩蓋壞掉的使用者路徑

工具輸出、重試、截圖與應用程式狀態都是合成測試資料。

負責人
你是平台工程師，要將範圍過大的 Shell 指令改成任務專用、結果明確的工具。
要做的決策
哪些工具邊界與結果碼能指出真正失敗層，並讓 agent 選安全下一步？
目前狀態
Agent 每次修改都跑整套測試，輸出超過可用脈絡。指令退出碼為 0，但瀏覽器檢查因缺執行檔而被略過；Agent 仍把請求變更功能標成 verified。
預期成果
有型別的結果分開回報單元測試、契約、持久化與瀏覽器檢查，拒絕未授權的修復方式，所有結論都附證據。

限制條件

  • • 工具只能作用於當前環境 ID 與程式庫允許清單
  • • 模型看到的結果不得出現機密、Cookie、原始測試資料文字或呼叫堆疊
  • • 寫入完成狀態未知未核對實際結果前不得重試

實作範例

CHECK_SKIPPED 擋下一次假完成

證據類型: 具名模擬情境

舊驗證程序在未安裝瀏覽器時回 0，最後一行寫 42 項檢查通過，前面才提到瀏覽器檢查遭略過。Agent 只引用最後一行，將台帳改成 verified。

新版 verify_feature 逐層回傳明確狀態。瀏覽器層回 CHECK_SKIPPED、BROWSER_MISSING、retryable: false，nextAction 指向初始化。必要檢查未 PASS，狀態控制器便拒絕轉成 verified。

初始化固定版本的瀏覽器後，同一工具發現確認結果在重新整理後消失。Agent 修好持久化，重跑失敗案例，再跑完整流程。驗收憑證附四層結果、提交版本、環境與截圖雜湊。

主張限制

穩定程式碼能改善控制，不能保證檢查本身代表正確產品行為。任務契約、測試資料、權限與發布後果仍由人負責。

做法

照著做，每一步都有檢查點

程式撰寫 agent 呼叫有上限的Release Desk 工具，收到精簡程式碼與證據 ID；完整遮蔽敏感資訊的軌跡留在受保護儲存區。

現場情境

哪些工具邊界與結果碼能指出真正失敗層，並讓 agent 選安全下一步？

  1. 01盤點決策與危險捷徑
  2. 02定義 schema 與結果聯集型別
  3. 03重播不利的結果

驗收條件

Agent 能從精簡觀察紀錄分清設定、規則、暫時性、產品與操作結果未知；審查者仍可開證據重現結論。

這張圖要幫你看懂什麼觀察紀錄與受保護的證據分流圖能說清哪些內容進脈絡，以及授權在哪裡執行。
  1. 01

    盤點決策與危險捷徑

    沿基準版本列每個指令、使用者、權限來源、必要證據、輸出量與下一步。標出通用 shell、原始紀錄、廣泛路徑、隱藏 skip 與可能重複效果的寫入重試。

    檢查點 · 每個重複呼叫都對到有上限的決策，危險捷徑有外部控制或移除理由。

  2. 02

    定義 schema 與結果聯集型別

    定義封閉參數、長度及路徑限制。結果分成功、輸入格式錯誤、權限拒絕、可重試、結果未知與失敗。精簡觀察和受保護的完整證據分開保存，並指定哪個系統元件提供環境身分及授權。

    檢查點 · Unknown 欄位、絕對路徑、任意指令、超出大小限制的輸入與模型自行提供的環境身分都在執行前被拒。

  3. 03

    重播不利的結果

    模擬轉接層依序回瀏覽器缺漏、資料遷移不合法、證據 denied、暫時性讀取逾時、unknown 寫入與超出大小限制的紀錄，驗程式碼、重試、證據、敏感資訊遮蔽與操作。

    檢查點 · 各案例不用讀完整終端輸出也能選下一步；機密不進模型輸入，寫入結果未知時只允許核對。

  4. 04

    跑 fresh-agent 選擇

    給新工作階段三個失敗與工具清單，記已選定的工具、參數、呼叫、位元組、修復與最終證據，使用相同契約比較 broad-shell 基準版本。

    檢查點 · 全新工作階段選對工具、維持呼叫上限、修到失敗層，也不能靠 skipped 檢查建 verified。

實務脈絡

展示版之後

G1

從下一個決策倒推結果

先列工具呼叫後允許的下一步：繼續、修正輸入、初始化、核對結果、請求授權或停止。資料庫檢查須分清 schema 缺漏、初始資料缺漏、存取被拒、服務無法連線及正常狀態；一個布林值不足以指示怎麼處理。

回傳狀態、錯誤代號、摘要、能否重試、證據 ID 與下一步。完整紀錄、查詢計畫、軌跡和截圖存於受保護的外部儲存區。需要深入診斷時，透過 read_evidence 取得已核准的資料部分，避免把整份終端輸出重新送入模型。

G2

工具說明也是可測介面

工具名稱和 schema 要交代用途、限制及欄位來源。使用封閉列舉值、長度限制、相對於程式庫的路徑，以及由伺服器提供的環境 ID。不要用可任意加欄位的參數袋，讓呼叫者把指令、憑證或目的地藏進輔助函式。

用保留任務集合測工具選擇，記錯工具、缺參數、虛構欄位、重複呼叫與復原。只有執行軌跡顯示固定誤解才調整名稱或說明；工具清單變更也要跑回歸測試。

G3

交付補強

工具的 nextAction 列出政策允許的下一步。RETRYABLE 同時回 retryAfter、最大及已用次數，並保留相同冪等邊界；DENIED 指向 request_authority 或停止，不能要求改規則繞過；UNKNOWN 指向核對結果，不叫人重送。把每條路徑寫進控制器測試，確認執行器不會把所有非零結果都交給通用重試。

依下一步決策選回傳欄位。若只需知道遷移缺漏、schema 版本與修復指令，就不回完整資料庫 URL、資料表或堆疊。操作人員仍可經授權查已遮蔽敏感資訊的階段紀錄、查詢代號和環境版本；存取本身也記入稽核。保留診斷能力，同時控制模型脈絡和資料暴露。

Read_evidence 本身也要有窄範圍。參數使用證據 ID、已核准的分組型別與位元組上限，不接受任意路徑或全文查詢。執行環境驗呼叫端、任務、環境、保存期限與資料類別，回傳內容仍視為不受信任觀察紀錄，不能提升成程式庫指令。測試資料應包含一段看似要求關閉防護規則的被污染的紀錄，證明它只停留在資料通道。

工具改版時比較能力、schema、輸出上限、重試語意及授權來源的差異。發布憑證附新舊 schema 雜湊、受影響的保留案例、選擇正確率、回傳大小的極端值，以及權限拒絕行為。即使只改名稱，也檢查舊工作階段和產生的指引有無過期參考，避免持續呼叫不存在的工具。

每個錯誤碼要有穩定語意與責任歸屬。輸入不合法由呼叫者修正；環境未就緒回初始化程序；權限不足交給授權負責人；暫時性讀取失敗才允許有限重試；寫入結果不明交給操作效果結果核對；產品驗收失敗指向相關測試與檔案範圍。若所有錯誤都回同一段『請稍後再試』，agent 會把架構、權限與資料問題全部當網路波動，造成重複呼叫與錯誤修復。

工具測試應從執行器外側注入惡意與異常輸入。包含跳脫相對路徑、超長字串、未知欄位、偽造環境識別、相似工具名稱、被污染的錯誤訊息、截斷輸出與取消訊號。確認驗證失敗發生在任何檔案、網路或資料操作之前，並且紀錄中不會把被拒內容原樣寫出。這些案例通過只證明目前契約能擋已知手法，工具範圍改變時仍要重新做威脅檢視。

用全新工作階段評估實際決策：工具和參數是否正確、是否重複讀相同證據、拒絕後是否嘗試越權、寫入結果未知時是否先核對，以及完成宣告是否附完整檢查。受限工具可能略增呼叫次數；若能減少假完成和危險重試，仍有價值。報告同時列成本與控制結果。

工具維護要指定負責人與相容政策。當執行器改版，舊 schema 的呼叫是明確拒絕、短期轉接或雙版本支援，要在發佈前決定，不能把解析失敗交給 agent 猜。轉接層只處理形狀差異，不可悄悄放寬權限、補入缺少參數或改變重試語意。每次版本切換保留舊版失敗測試資料，確認過期工作階段收到可理解的升級訊息，也不會因備援路徑取得更多能力。操作人員儀表板需顯示各版本呼叫量、錯誤碼與淘汰期限，等消費端清零後才移除舊介面。

動手實作

將Release Desk 檢查包成有型別的回饋工具

建立 inspect_health、verify_feature、read_evidence 與 reconcile_effect，重播六種結果，確認有上限的觀察紀錄與允許下一個操作。

準備項目

  • • 保存 noisy 基準版本輸出，記錄位元組與缺少的決策欄位
  • • 宣告環境 ID、路徑允許清單、敏感資訊遮蔽與模型傳送資料上限

本課產出

四個有輸入輸出上限的工具契約、用於保留案例的模擬轉接層、敏感資訊遮蔽規則、回傳大小報告、決策表，以及模型和操作人員各自看到的證據樣本。

起始模板: Tool observation contract

TypeScript
type ToolObservation = {
  status: "PASS" | "FAIL" | "DENIED" | "RETRYABLE" | "UNKNOWN";
  code: string;
  summary: string;
  retryable: boolean;
  evidenceIds: string[];
  nextAction: "continue" | "repair" | "initialize" | "reconcile" | "request_authority" | "stop";
};

可下載的實作檔

Tool observation contract

tool-observation.ts · TypeScript

An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.

Run receipt template

he-05-receipt.json · JSON

A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.

驗收指令

npm run harness:tools -- --fixtures fixtures/tool-outcomes.jsonl --max-output 4096

預期 receipt

PASS he-05 agent-readable-tools
fixtures=6 stableCodes=6 secretHits=0
unknownWriteRetries=0 verifiedFromSkipped=false

預期結果

Agent 能從精簡觀察紀錄分清設定、規則、暫時性、產品與操作結果未知；審查者仍可開證據重現結論。

留給下一課

後續由程式強制執行的規則、評測、復原與總整專案執行軌跡都使用這套結果資料包，不允許用無限制的備援指令繞過。

驗收條件

  1. 01參數驗證拒絕任意指令、目的地、絕對路徑、unknown 與超出大小限制的值
  2. 02六類案例各回穩定代號、能否重試、證據 ID 與唯一允許的下一步
  3. 03送入模型的資料低於位元組上限，不含預埋的洩漏偵測字串或原始工作階段資料
  4. 04任何必要檢查 skipped、缺漏、denied、unknown 或失敗的都不能 verified

常見故障

故障診間

F1Agent 仍一直選通用 shell，而不是任務專用的檢查。
先檢查
比較工具清單說明、參數 friction、證據、選擇執行軌跡與備援權限。
可能原因
窄工具沒說清決策涵蓋程度，或無限制的 shell 比它容易。
修復方式
補齊結果欄位與說明，對該任務類型移除或 policy-gate 繞過。
下次怎麼避免
工具名稱、schema、說明或權限變更就跑選擇測試資料。
F2逾時後請求變更被送出兩次。
先檢查
追冪等鍵、派送執行驗收憑證、操作台帳、狀態、重試旗標與結果核對。
可能原因
工具把寫入結果未知，誤當成可以直接重試的傳輸失敗。
修復方式
停止重試，查正式可信的操作效果，再從 reconciled 結果恢復。
下次怎麼避免
完成狀態未知有獨立程式碼，寫入前後程序崩潰都要測。
F3精簡回饋無法診斷新失敗。
先檢查
打開證據 ID，確認關聯、階段、版本與安全診斷分組是否保存。
可能原因
Trim 直接刪除證據，沒有分離觀察紀錄與診斷儲存位置。
修復方式
外部保留完整已遮蔽敏感資訊的證據，增加限定範圍的讀取路徑。
下次怎麼避免
同時驗脈絡預算與操作人員重建。

展示版之後

正式上線前的邊界

  1. 01工具用途、限制、參數 schema、授權來源與終止結果版本化
  2. 02環境、根目錄、範圍與憑證由可信的執行環境提供
  3. 03模型觀察紀錄有型別的、有上限的、已遮蔽敏感資訊的、actionable 並連受保護的證據
  4. 04台帳分清拒絕、可重試、結果未知、失敗、略過與通過
  5. 05寫入使用冪等性與結果核對，unknown 後不直接重試
  6. 06工具清單、schema、轉接層或規則改版時，重跑保留的工具選擇與惡意輸入案例

證據類型

資料來源與主張限制

資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。

  1. [1]
    打造有效的 agent

    Anthropic · 官方文件 · 2026-08-26

    採用能通過需求的最簡架構 · workflow 模式 · 環境回饋 · 停止條件
  2. [2]知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
  3. [3]
    Harness Engineering Guide

    Nexu · 公開案例 · 2026-08-26

    執行環境邊界 · 工具系統 · sandbox · 復原模式
  4. [4]
    Learn Harness Engineering

    Walking Labs · 公開案例 · 2026-08-26

    專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
  5. [5]
    長時間應用程式開發的 harness 設計

    Anthropic · 已發表研究 · 2026-08-26

    planner、generator、evaluator · 可測合約 · 簡化 harness · 成本取捨

延伸的 Tenten 資源

Field guide

Tool use and function calling

Design typed application tools, validation, authorization, result projection, and audit events.

查看資源Field guide

MCP and external systems

Extend tool boundaries across approved hosts, identities, discovery, and removal.

查看資源

當本機 harness 要接進真實程式庫

帶著驗收憑證、失敗案例，以及那條還拿不準的控制邊界來。

在團隊拉長 agent 自治時間前，Tenten 可以一起檢查程式庫可讀性、權限、評測器涵蓋、worktree 隔離、復原與上線證據。

預約成果檢視查看 FDE 交付方法