工作階段交接技巧 是做什麼的?
目的
大型上下文視窗會隨著 token 數量累積,導致指令遵循度、推理精確度與工具準確度下降。長時間的工作階段充滿了已被取代的計畫、中斷的草稿以及重複的錯誤追蹤。重置為全新的工作階段可以恢復效能,但盲目地丟棄上下文會導致狀態遺失、產生幻覺的進度以及重複的錯誤。
session-handoff 技巧標準化了代理如何快照當前狀態。它將短期的運作記憶轉換為一份可行、可驗證的橋接文件,供下一個工作階段使用。
工作流程:結束工作階段(6 個步驟)
當代理工作階段達到操作極限或暫停工作時,請執行以下步驟:
-
審查 Git 與工作區狀態 執行
git status -s和git diff --stat以建立基於現實的依據。切勿依賴聊天記錄來判斷哪些檔案被修改過。識別已修改、未追蹤以及已暫存的檔案。 -
捕捉目標狀態與實際實作狀態 用一句話定義原始目標。精確記錄哪些內容已驗證為可運作(附上通過的測試指令或執行時期檢查),哪些仍為部分完成或未經驗證。
-
記錄已做出的決策與放棄的路徑 列出在工作階段中確定的架構與設計選擇,並附上具體的理由。明確記錄負面決策(嘗試過但放棄的方法),以防止下一個代理重新嘗試失敗的解決方案。
-
整理受影響的檔案與相關符號 列出被修改或參照的關鍵檔案路徑、函式、類別與 schema 定義。必要時包含行號參考。
-
標記未解決的問題及其擁有者與驗證方式 列出所有未解決的邊界情況、失敗的測試、延遲的任務以及環境限制。每個未解決的問題必須指定由誰解決(人類或代理)以及如何驗證完成。
-
指定立即的下一步行動 草擬一個單一、原子、明確的指令,供下一個代理在第一次互動時執行。不要提供廣泛的列表;請指定要運行的確切指令或要編輯的第一個檔案。
操作規則
- 區分事實與推測:通過的測試是事實;假設程式碼能編譯就代表能運作是推測。將未經驗證的假設明確標示為
[UNVERIFIED]。 - 強制要求未解決問題的擁有者與驗證方式:每個未解決的問題必須指定擁有者(
Human或Agent)以及確定性的驗證標準(例如pytest tests/auth/test_token.py:test_refresh_rotation passes)。 - 禁止模糊的延續指示:切勿撰寫「繼續處理驗證功能」或「完成前端元件」。請指出確切的符號、檔案以及失敗模式。
- 參考真實工作區識別碼:所有對程式碼的參考必須使用確切的檔案路徑與符號名稱。請勿使用通用化的虛擬碼描述。
範例:工作階段交接備忘錄
# 工作階段交接:JWT 輪換實作
### 目標與當前狀態
- **目標**:在 FastAPI 驗證服務中實作 refresh token 輪換與撤銷。
- **當前狀態**:Refresh token 資料庫遷移已完成,輪換端點已建立。Token 產生與資料庫持久化功能正常運作。撤銷黑名單快取尚未接入依賴驗證器。
- **驗證**:`pytest tests/test_auth_tokens.py` 通過(4/4 測試)。
### 已做出的決策(附理由)
- **使用 Redis 存放 Token 撤銷清單**:選擇 Redis 而非 Postgres 查詢來處理已撤銷的 JTI token,目的是將受保護路由的延遲保持在 5ms 以下。
- **拒絕無狀態 Refresh Token**:我們最初評估了在 JWT 聲明中使用滑動有效期而不持久化的方案,但由於被盜用的 token 在自然到期前無法被撤銷而放棄。
- **Token 格式**:選擇 UUIDv4 作為 `jti` 聲明,以維持與現有 session 儲存 schema 的相容性。
### 已變更的檔案
- `src/services/auth.py`:新增 `rotate_refresh_token(old_token: str)` 函式與 Redis 無效化呼叫。
- `src/models/tokens.py`:新增 `RefreshTokenRecord` SQLModel 表格,用於追蹤 token 家族。
- `alembic/versions/20261005_add_token_families.py`:用於建立 `token_records` 表格的遷移腳本。
- `tests/test_auth_tokens.py`:新增 token 家族產生與輪換的單元測試。
### 未解決的問題
- [Agent] 將 `verify_token_not_revoked` 接入 `src/api/deps.py` -> 驗證方式:檢查 `tests/test_auth_deps.py` 在 token 被列入黑名單時會失敗。
- [Agent] 處理輪換時 Redis 無法連接的資料庫回滾情況 -> 驗證方式:在單元測試中模擬 Redis 連線失敗。
- [Human] 在 `.env.test` 中為 CI 執行設定 `REDIS_AUTH_URL` 密鑰。
### 下一步行動
開啟 `src/api/deps.py`,從 `src.services.auth` 匯入 `is_token_blacklisted`。在 `get_current_user` 中,於 JWT 解碼驗證後立即插入該檢查。
### 注意事項
- 請勿修改 `src/core/config.py` 中現有的 `access_token` 到期時間(目前為 15 分鐘)。
- 在本地啟動 API 伺服器之前,必須先執行 Alembic 遷移腳本 `20261005_add_token_families.py`(`alembic upgrade head`)。
反模式
- 聊天記錄傾印:將原始對話記錄直接貼進交接備忘錄。你會立刻用本來想要逃脫的對話雜訊污染下一個工作階段的上下文視窗。
- 虛假完成:將某個模組標記為「已完成」,但實際上它僅被撰寫,並未執行或測試過。
- 遺漏的絕路:省略那些失敗的方案。下一個代理會讀取程式碼庫,看到同樣明顯的路徑,然後重新實作那個已失敗的方法。
- 抽象的下一個步驟:以「下一步:實作剩餘測試」結尾。新的代理會浪費 3-5 次不必要的互動來發現需要測試什麼。
限制
- 此技巧僅能產生書面交接文件;無法保留即時狀態,例如正在執行的程序、未提交的終端機輸出或記憶體中的除錯上下文——請在備忘錄中明確記錄任何重要的項目。
- 交接品質受限於結束工作階段所記錄的內容:未被寫下的決策、死路或檔案變更,無法被下一個工作階段還原。
- 它不能取代版本控制或問題追蹤系統;請先提交工作成果,並在備忘錄中參考提交記錄或票證,而非重複記載。