MaxHu-xuan/task-state-guard

解決的問題

TaskStateGuard 提供了一種在服務重啟後重新協調「卡住」任務狀態的方法。在 AI 代理執行環境或背景工作進程中，當系統當機或重啟時，任務常仍標記為 running 或 pending，導致操作員無法確定工作是否實際完成，或結果是否已交付給使用者。此工具根據明確的截止時間與寬限期，將過期狀態收斂至終端狀態（如 timed_out），而無需猜測工作是否成功。

工作原理

它使用嵌入式 SQLite 資料庫來維護任務與交付狀態的帳本。採用兩個獨立的狀態機：

• 任務狀態：追蹤工作是否為 queued、running、succeeded、failed、timed_out 或 cancelled。
• 交付狀態：追蹤結果是否為 pending、delivered、failed 或 not_applicable（用於內部任務）。

透過分離這兩個狀態，系統可區分已完成但結果尚未交付的任務。reconcile 命令會識別超出寬限期的任務，並更新為終端狀態，而 doctor 命令則對資料庫模式與事件鏈進行健康檢查，以確保帳本的可信度。

適用對象

• 需要在重啟後恢復狀態的 AI 代理與背景工作進程服務開發者。
• 需要工作流程可觀察性，且無需將敏感提示或任務內容儲存在診斷帳本中即可審計任務結果的運維人員。
• 在 Linux、macOS 或 Windows 上執行本地工作流程，需要一致狀態合約與本地檔案保護的使用者。

特色亮點

• 狀態機分離：明確區分工作完成與結果交付。
• 預演模式（Dry-run）：允許使用者在套用協調前查看變更的總計數。
• 隱私導向：不儲存提示、訊息或任務內容，僅儲存元資料與可選指紋。
• 跨平台支援：支援類 Unix 系統的 POSIX 檔案權限，並在 Windows 上識別 DACL 边界。
• 記憶體快照：對於小型資料庫，可將一致讀取載入記憶體，避免預覽時的鎖定問題。