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 仅作为分析导向的镜像存储。