agent-coherence

AI 智能体正越来越多地用于读取、处理并写回共享状态——包括项目文件、记忆存储、配置项和知识库。当多个智能体跨会话或并发执行此类操作时，会出现一种静默失败模式：某个智能体在 T 时刻读取状态、完成工作后，在 T+N 时刻写回——却不知道在此期间另一个智能体或会话已经修改了该状态。其结果是静默的更新丢失：后一次写入会覆盖前一次，既无报错，也无警告，更没有任何异常提示。

agent-coherence 是一个数据平面协调层，用于消除此类故障。它追踪读取的代际信息，并强制执行新鲜度保证：在任何智能体提交对共享状态的写入之前，系统会校验该智能体读取的内容是否仍然是最新的。如果自智能体上次读取后状态已发生变化，写入将被拒绝，智能体必须重新获取——重新读取最新状态后才能继续。这既避免了跨顺序会话的过期覆盖（时间一致性），也避免了同一主机上并发运行中的过期覆盖（通过比较并交换实现的乐观并发控制）。

该方案以开源 Python 库的形式交付，配备可插拔的适配器模型、一个用于在项目规则文件上强制执行一致性的官方 Claude Code 插件，以及一个面向工具原生智能体集成的 MCP 服务器接口。其目标用户是构建生产级 AI 智能体工作流的开发团队，在这些场景中，共享状态的正确性具有业务关键性。