agentdb-state-manager

AgentDB 狀態管理器是一項進階工具技能，旨在自動化軟體開發環境中填補簡單檔案追蹤與大規模資料庫管理之間的落差。透過將 DuckDB 作為嵌入式分析引擎，它能將分散的 TODO_*.md 原始檔案轉換為結構化、可查詢的資料庫。這使 AI 代理能夠執行複雜的操作，例如關鍵路徑分析、瓶頸識別以及專案狀態轉換的縱向追蹤，而無需重複解析檔案，從而減少效能開銷與 Token 消耗。此工具專為在 Claude Code 環境中使用，且需要對多階段工作流程進行高度可視化管理技術團隊而設計。

• 提供唯讀分析快取，支援透過 SQL 查詢任務依賴關係、階段時程與專案進度。

• 自動化上下文檢查點管理，能在特定 Token 閾值捕捉系統狀態，確保複雜推理任務的快速恢復與銜接。

• 採用不可變的「唯追加」記錄方式，確保狀態變更的稽核軌跡，並為專案健康報告提供歷史指標。

• 具備模式驅動的組織架構，可與既有的規劃與執行結構無縫整合，並使用標準化的 JSON 工作流程狀態定義。

• 提供高效能的跨階段查詢能力，相較於手動解析檔案，能顯著降低延遲與 Token 使用成本。

• 主要輸入為代表當前專案狀態的標準 TODO_*.md 檔案，透過內建的同步工具將資料寫入 DuckDB 實例。

• 輸出提供關於專案瓶頸、任務阻塞依賴關係以及實作階段演變的詳細洞察。

• 運作於跨階段模型（Utilities），意即適用於規劃、實作、品質保證、整合與發布流程。

• 使用基於時間戳記的會話 ID，確保在 24 小時運作視窗內的多次代理調用之間具有可重現性與一致性。

• 使用限制包括需要進行初始 Schema 設定，並且必須將 TODO_*.md 維持為真理來源（Source of Truth），AgentDB 僅作為分析導向的鏡像儲存。