Claude Code｜任務通知與事件紀錄：有用而不洗版

通知最有用的時刻是工作完成、失敗或需要處理，而不是每個工具動作都提醒一次。本篇把事件紀錄與結果通知分開，使用本機假接收器驗證去重、失敗與重送，並確認通知只保存必要欄位，不把私人內容塞進日誌。

先讀Hooks 實用案例及事件實驗。下載第 77 篇材料，在 starter 操作。需要 Node.js 22 以上；本課通知測試不使用外部帳號。閱讀約 20 分鐘，實作約 45 分鐘。

先決定哪些資訊值得記錄

閱讀完整文字說明

任務通知與事件紀錄：有用而不洗版，以流程和文件圖形呈現教學重點。

事件紀錄回答「什麼時候、哪個工具發生了動作」，工作結果回答「驗收是否完成」，通知結果回答「接收端是否收到」。三者不能混成一個 success 欄位。發送成功不代表測試通過，工具完成也不代表整個需求已交付。

本課 audit.mjs 保存事件名稱、工具、工作階段識別及時間，寫入 run-data/events.jsonl。JSONL 是每一行一個 JSON 物件，適合逐筆追加。notification 則使用另一個資料夾，只接受 id 與 completed、failed 兩種狀態。兩份資料分開查看，更容易追查通知重送沒有改變工作結果。

工作階段識別也可能屬於不適合公開的操作資訊，保留在本機即可。分享截圖或範例時改用課程假 id；不要把整段 prompt、檔案內容、權杖或錯誤堆疊中的私人資料原封不動送到外部頻道。

先重播事件紀錄

使用 fixtures/post-edit.json 執行 audit 重播，再開啟 run-data/events.jsonl 查看最後一行。重播器補入目前 cwd，腳本將日誌寫到本次練習專案。重播兩次會有兩筆事件，這是原始事件紀錄，不需要假裝只有一次工具動作。

node hooks/replay.mjs audit fixtures/post-edit.json
node hooks/replay.mjs audit fixtures/post-edit.json

去重應用在你定義的通知事件，而不是把所有相同工具名稱的紀錄刪掉。兩次 Edit 可能處理不同檔案或來自不同任務，只因 tool_name 一樣就合併，會失去追查資訊。先決定事件識別方式，再說明哪些資料應保留。

材料的測試會在 tool_input 放一段合成敏感文字，確認它沒有出現在 audit 日誌。這能驗證目前白名單欄位的實作，但不能證明所有未來新增欄位都安全。調整日誌格式時，將這類反例一併保留在測試中。

使用本機假接收器測試通知

本篇接收器是一個寫入本機檔案的函式，不是 Slack、Email 或作業系統通知。它讓你不需要外部服務就能測試事件契約與去重。實際串接外部服務時，還要另外處理認證、網路錯誤、速率限制與收件目的地。

{
  "id": "lab-77-completed",
  "status": "completed",
  "privateNote": "合成敏感欄位，不應寫入通知"
}

node automation/send-notice.mjs fixtures/notice.json
node automation/send-notice.mjs fixtures/notice.json

第一次預期 delivered=true；第二次相同 id 與狀態預期 duplicate=true，且不重寫通知內容。開啟 run-data/notifications/lab-77-completed.json，應只有 id、status，沒有 privateNote。程式使用只在檔案不存在時建立的方式，讓同一個事件不被重複建立。

這個去重策略適用本機練習，不能直接保證跨多台機器或任意網路服務只送一次。外部服務的成功回覆遺失時，你可能不知道它是否收到；需要接收端支援冪等鍵或另外對帳。本篇先把可控範圍說清楚，之後再接可靠排程。

設計事件 id 與狀態轉換

同一任務可能先失敗、修復後成功，這是兩個值得區分的結果事件。不要把同一 id 的狀態改掉再重送，期待舊紀錄自動變成新結果。材料遇到相同 id、不同狀態會明確報錯，提醒你重新定義事件識別。

可以使用任務編號、執行編號與結果類型組合，例如 todo-104-run-2-completed。它應穩定代表一次具體事件，不含私人標題或任意長文字。重試同一次發送保留相同 id，新的工作結果則使用新的 id，這樣去重才不會吃掉真正的新通知。

{"id":"lab-77-run-2-failed","status":"failed"}

輸入格式不合法時應停止。例如含 ../ 的 id 不應被當成路徑，未知狀態不應直接寫進系統。通知函式限制 id 的字元及長度，再只複製允許欄位。這是程式驗證，不靠提示模型「請小心處理」來實現。

故障練習：接收器無法寫入

用編輯器在練習目錄建立 blocked-receiver.txt，再把它當成接收目錄傳入下方命令。因為該位置是檔案，無法建立通知資料夾，預期非零退出碼。這個故障不需要更改整個作業系統權限，也不會影響真正的收件服務。

node automation/send-notice.mjs fixtures/notice-failed.json blocked-receiver.txt

保留工作結果，將通知狀態記為發送失敗；不要把工作重新改成 failed，只因提醒沒送到。恢復正確接收目錄後，用相同事件 id 重送，預期成功；再重送一次，預期去重。這三個結果能驗證恢復流程，而不是只測正常情況。

若接入外部通知，重試應有限次、有間隔，而且保留最後錯誤。不要用失敗後立刻無限重送，否則可能把一次工作錯誤變成大量通知。對需要人處理的長期失敗，保存待送事件並明確回報，比持續佔用工作階段更容易維護。

將通知接在已驗證的結果之後

Hook 的 Stop 事件本身不表示任務成功。要發完成通知，應先有可靠的工作結果，例如固定測試通過、成果檔驗證成功，或你的應用已寫入 completed 狀態。可以由工作流程在結果確認後呼叫 send-notice，再把兩個結果分開保存。

先完成指定練習並保存實際測試結果。
只有验收通過才把本次工作標為 completed。
通知是另一個步驟；失敗時保留工作結果及待送事件。
本課只使用本機接收器，不寄信、不呼叫外部 webhook。

若需要即時知道權限提示或其他事件，可以另外選擇相應 Hook，但每類通知都要定義用途。不要把每次 PostToolUse 都當成需要提醒讀者的事件。原始日誌可以完整一些，對人的通知則集中在需要行動的變化。

讓通知能回到對應的工作結果

通知只傳達某個工作狀態發生變化，真正的成果與錯誤應在本機紀錄中可查。為通知保留工作識別碼和狀態，讀者才能把它對回同一次執行。若缺少工作識別碼，多個同時進行的任務會產生難以辨認的訊息。

遇到通知寫入失敗，保存原任務結果並另記通知失敗，不把已完成的計算當成沒有執行。這個分離讓重送通知不必重新做整個任務，也更容易判斷哪些結果已被使用者查看。

檢查日誌與完成判準

完成應有首次送達、重複事件、接收器失敗、恢復重送四種紀錄，且通知檔沒有多餘的敏感欄位。清理時先保存要交付的證據，只處理自己的 run-data；若想重新做去重實驗，使用新事件 id 或新的空練習目錄，不需刪掉全部歷史。

小練習是新增 cancelled 狀態，先決定它是否值得通知，再一起更新契約、驗證與測試。不要只讓程式接受更多字串，卻沒有說明讀者收到後應做什麼。下一篇會把這些腳本放到中文路徑及不同換行環境，測試可攜性與恢復。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code