kitorz/token-step-tracker

Token 警示（不適用於處女座）

在不中斷任務、不聲稱計費精確度的前提下，追蹤約略的 Token 使用量。

開始追蹤

1. 將任務分解為有意義的、基於成果的步驟。如果已有現有計畫，則保留它。
2. 陳述一次：Token 數字為估計值，且排除隱藏的系統、推理及平台開銷。
3. 從使用者的請求中讀取一個正整數的警示間隔，例如 5000（對應 "alert every 5000 tokens"）。當使用者請求警示但未指定間隔時，使用 10000。主動陳述一次使用的間隔。
4. 將下一個警示門檻設為一個間隔，並在每次警示後按間隔推進。
5. 不要僅為了改善估計而進行額外的工具呼叫、重新讀取檔案，或產生額外的內容。

報告每個完成的步驟

在報告步驟的有用結果後，附加這個緊湊的檢查點：

Token 檢查點 · 步驟 {n}: {name}
此步驟：≈{low}–{high} Token | 累積：≈{low}–{high}
主要驅動因素：{最大的可觀察來源}
下次節省：{一項可行的建議，或 "No worthwhile change—keep the current approach."}

僅在步驟產生意義結果時才計數。不要為狀態訊息、批准、等待或瑣碎的內部動作建立檢查點。

顯示門檻警示

在每個檢查點之後，將累積範圍的中點與下一個警示門檻進行比較。當中點達到或超過門檻時，附加：

> :red_circle: TOKEN 警示 | **{threshold} 估計 Token 已使用**

使用紅色圓圈加上粗體數字作為可攜式降級方案。如果主機支援安全的內聯 HTML 顏色，則將值渲染為 <span style="color:#d00"><strong>{threshold}</strong></span>；絕對不要發出原始終端機轉義碼。純技能無法建立作業系統通知或保證文字顏色，因此將其稱為警示，而非系統彈出視窗。

如果一個步驟跨越了多個門檻，則為跨越的最高門檻發出一個警示，並將下一個門檻推進到超過累積中點。絕不重複已發出的警示。

一致地估計

根據步驟期間處理或產生的可觀察內容進行估計：

• 英文散文：大約每 4 個字元 1 個 Token。
• 中文散文：大約每 1.5–2 個字元 1 個 Token。
• 程式碼與結構化資料：大約每 3 個字元 1 個 Token。
• 包含相關的提示文字、新讀取的工具輸出、產生的內容，以及該步驟明顯重複使用的上下文。
• 避免在同一個步驟內重複計算同一件產物。
• 使用至少 ±25% 寬的範圍；當上下文重複使用不明確時，則放寬範圍。
• 將邊界四捨五入為合理的數值。偏好使用 ≈800–1,200，而非 ≈917–1,143。
• 將步驟範圍相加，以維持累積範圍。

絕不推斷隱藏的推理 Token、平台指令、快取行為、計費或貨幣成本。如果執行環境明確提供了使用量，則將其單獨報告為精確的執行時使用量，而不是將其混入估計中。

推薦節省方法

每個檢查點最多給出一項建議。針對最大的可觀察可避免成本：

• 大檔案讀取：先搜尋，然後僅讀取匹配的部分。
• 重複的讀取或搜尋：重複使用已取得的結果。
• 廣泛的工具輸出：縮小路徑、欄位、日期範圍或結果數量。
• 過大的上下文：在繼續之前，總結穩定的發現。
• 過長的產生輸出：在不需要細節時，請求或產生更緊湊的格式。
• 重複失敗：檢查錯誤並在重試前改變方法。
• 過多的範例：除非需要比較，否則保留一個代表性範例。

不要為了減少 Token 而建議跳過驗證、安全檢查、必要的證據或使用者要求的細節。如果不存在有意義的節省空間，則直接說明，而不是編造建議。

結束追蹤

在任務的最終結果後，包含一個簡短的總結：

Token 估計總結
步驟數：{count} | 總計：≈{low}–{high} Token
最大步驟：{step name}（≈{low}–{high}）
警示間隔：{interval} Token | 已觸發警示：{count}
下次執行的最佳節省：{單一最大影響建議}
準確度：僅估計；排除隱藏的系統、推理、快取及平台開銷。

保持檢查點和總結為使用者實際任務的次要部分。