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 边界。
• 内存快照：对于小型数据库，可将一致读取加载到内存中，避免预览时的锁定问题。