官方教學中文版SDK 與自定義 Agent
SDK Hooks
說明 Copilot SDK hooks 如何控制工具執行、修改結果、注入上下文、處理錯誤和審計互動。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| SDK hooks | 鉤子 | 在 agent 生命週期介入的回撥。 |
| 介入時機 | timing | 執行前 / 後 / 出錯時觸發。 |
| 用途 | use | 校驗 / 記錄 / 攔截。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用 SDK hooks 在合適時機介入 agent 行為（校驗 / 攔截 / 記錄）。
你是 Copilot SDK hooks 顧問。
【角色】
Copilot SDK hooks 顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 我想在什麼時機介入：___
- 介入要做什麼（校驗 / 攔截 / 記錄）：___
- 要攔截的高危操作：___
- 記錄需求：___
- 經驗水平：___
【工作流程】
1. 梳理可用的 hook 時機
2. 把我的需求對映到 hook
3. 給校驗 / 攔截 / 記錄寫法
4. 說明順序和副作用
5. 給驗證
【輸出規範】
▌一、hook 時機
▌二、需求對映
▌三、校驗 / 攔截 / 記錄
▌四、順序副作用 + 驗證
【硬約束】
- hook 邏輯簡單可測
- 攔截高危操作而非事後補救
- 記錄不記敏感資訊
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或許可權一律以官方文件為準，禁止照搬過時寫法SDK Hooks（鉤子）是讓 agent 進入工程治理的關鍵點。沒有 hooks，你只能事後看結果；有 hooks，你可以在工具呼叫前攔截、在呼叫後記錄、在會話開始時注入上下文、在出錯時統一處理——這是把 demo 升到生產 agent 必經的一道關。
Hook 不是安全銀彈：底層許可權收緊（API token / 網路 / 檔案許可權）才是第一道防線，hook 是第二道控制和審計。兩條防線缺一道都會留漏洞。
1. 官方 hooks 清單
GitHub 官方 quickstart 列出這些 hooks：
onPreToolUse：工具執行前，用於許可權控制和引數校驗。onPostToolUse：工具執行後，用於結果轉換和記錄記錄。onUserPromptSubmitted：使用者傳送訊息時，用於 prompt 修改和過濾。onSessionStart：會話開始，用於追加上下文和設定 session。onSessionEnd：會話結束，用於清理和分析。onErrorOccurred：發生錯誤時，用於自定義錯誤處理。
flowchart TD
Start["onSessionStart"] --> Prompt["onUserPromptSubmitted"]
Prompt --> Pre["onPreToolUse"]
Pre --> Decision{"allow / deny / modify?"}
Decision --> Tool["Tool executes"]
Tool --> Post["onPostToolUse"]
Post --> Response["Assistant response"]
Response --> End["onSessionEnd"]
Tool --> Error["onErrorOccurred"]
style Pre fill:#fef3c7,stroke:#d97706,stroke-width:2px
style Error fill:#fee2e2,stroke:#dc2626,stroke-width:2px2. 最小攔截示例
onPreToolUse 可以返回 permissionDecision：
const blockedTools = ["shell", "bash", "exec"];
const session = await client.createSession({
hooks: {
onPreToolUse: async (input) => {
if (blockedTools.includes(input.toolName)) {
return {
permissionDecision: "deny",
permissionDecisionReason: "Shell access is not permitted",
};
}
return { permissionDecision: "allow" };
},
},
});這類 hook 適合做：
- 工具 allowlist / denylist。
- 引數校驗。
- 路徑邊界檢查。
- 高風險操作審批。
- 敏感 prompt 過濾。
3. Hook 的正確職責
適合放進 hook：
- 記錄 tool name、tool args、tool result 摘要。
- 阻止危險工具。
- 注入使用者偏好和目前組織上下文。
- 統一錯誤處理。
- 新增 trace correlation id。
不適合放進 hook：
- 大段業務邏輯。
- 長時間阻塞任務。
- 靠字串猜測所有安全風險。
- 把金鑰打進記錄。
- 悄悄改寫使用者意圖。
4. 商業級 hook 策略
上線前至少做 4 類 hook：
- Pre-tool guard：阻止危險工具、危險路徑、危險引數。
- Post-tool audit：記錄成功和失敗結果，但脫敏。
- Session context：注入 tenant、role、policy version。
- Error handling：把錯誤分成可重試、需人工、應停止。
Hook 輸出會進入 agent 工作流，必須控制噪聲。過多記錄或過長上下文會反過來汙染模型判斷。
深讀：hook 不是安全銀彈
Hook 可以攔截 SDK session 內的行為，但不能替代底層許可權。真正不能訪問的系統，API token、網路、檔案許可權都應該先收緊。
最穩的安全模型是：底層許可權最小化，hook 做二次控制和審計。
本章自檢
- 是否有
onPreToolUse阻止危險工具？ - 是否有
onPostToolUse記錄工具呼叫結果？ - 是否避免把敏感資料寫入記錄或上下文？
- 是否有
onErrorOccurred的分級處理？ - 是否能把 hook 事件關聯到 session 和使用者？
透過標準：工具呼叫前能控，呼叫後能查，失敗時能解釋。
官方來源
- Quickstart for hooks —— GitHub 官方 hooks 清單和示例。
- Pre-tool use hook —— GitHub 官方工具執行前 hook。
- Post-tool use hook —— GitHub 官方工具執行後 hook。
- Error handling hook —— GitHub 官方錯誤處理 hook。