agent-mail

Agent Mail — 可选协调适配器

Agent Mail 用于传递消息、确认信息、身份信息和临时文件预留。它不是任务跟踪器、队列、证明账本或生命周期控制器。

预留具有建议性：只有每位协作写入者都会根据同一个绝对项目路径检查预留时，才能避免冲突；如果有写入者使用不同的路径解析结果进行注册，整个账本就只是建议性的空谈。Agent Mail 不会强制未进行检查的写入者遵守预留。

命名的故障模式——将沉默视为状态：把未获回复的线程解读为“工作停滞”或“工作已完成”；没有收到邮件只能证明没有邮件送达。

反模式：出现冲突时擅自扩大或续期预留。纠正方式：如实向调用方报告冲突；是否调整范围和 TTL 由调用方决定。

边界

• 单个写入者时，跳过 Agent Mail。
• 调用方提供绝对项目路径、Agent 身份、线程 ID、参与者、路径、排他性、原因和 TTL。
• 预留用于防止协作写入者之间意外重叠。它们不会建立工作所有权，也不会影响 Plan、Candidate 或 verdict 语义。
• 邮件沉默不能证明任何工作状态。
• 消息或确认是发生过通信的证据，不是变更正确或完整的证据。该适配器无法选择 AgentOps 语义、签发有约束力的 verdict，或将工厂完成转变为交付或验证证明。
• 仅在调用方明确要求释放某个确切预留时，才释放该预留，包括任何 force_release。强制释放没有自主触发条件；应报告冲突，不得强行清除。
• Agent Mail 绝不会选择工作、改变跟踪器状态、提交代码、验证、集成、关闭、释放或交付工作。

模式和权限

存在两个互不相交的界面；不得从第一个界面进入第二个界面：

• 协调模式（默认）。 注册身份、预留或释放调用方指定的路径，以及发送、读取或确认调用方的线程。这就是全部常规用途，而且所有操作都会写入持久化的 Agent Mail 记录。
• 管理／灾难恢复模式（仅限调用方明确授权）。 安装 git pre-commit 防护、执行 doctor repair、备份／恢复，以及执行不可逆的 clear-and-reset-everything，都属于独立模式。每项操作都需要调用方针对该项操作明确授权；这些操作绝不会作为协调的副作用而执行。clear-and-reset-everything 会删除数据库和所有存储，且无法撤销——未经调用方明确授权进行破坏性重置，绝不能运行它，即使使用 --force 也不行。

操作界面

每个存储根目录只能选择一个邮箱所有者和一种访问模式。如果 HTTP/MCP 守护进程拥有该根目录，请使用其 MCP 工具；不要让直接调用的 am CLI 指向同一个数据库。只有在运行中的 Agent Mail 运行时未拥有该根目录时，才能使用 CLI 作为后备方案。如果邮箱活动锁处于忙碌状态，或读取超时达到设定上限，这属于适配器降级结果，不代表有权重启服务、修复数据库或悄悄切换根目录。

如果有 MCP 工具，请使用它们。否则使用自描述的 am CLI。明确指定目标存储根目录，并通过 am mail --help、am file_reservations --help 及相关命令组帮助信息了解当前语法；不要根据记忆中的别名推断命令。如果 macOS 上的直接读取拒绝读取诸如 /var 这样的符号链接快照目录，请对该次独立调用使用仅限调用方使用、且不含符号链接的临时目录，或报告适配器已降级；绝不要放宽路径遍历检查。

单次使用

1. 确认有多位明确协调的写入者共享此仓库。
2. 固定一个存储根目录，并选择 MCP/服务模式或直接 CLI 模式；切勿在同一个运行中的数据库上混用两种模式。
3. 使用调用方提供的身份，并针对同一个绝对项目路径进行注册。
4. 仅预留提供的路径，并设置有上限的 TTL。
5. 不等待、不缩小范围，也不更改计划，直接报告冲突。
6. 发送提供的消息一次，并记录其 ID。
7. 仅读取或确认请求的线程。
8. 在调用方推进已声明的转换之前，验证该转换中每条要求确认的消息都已收到预期收件人的确认。后续消息不代表隐式确认。
9. 仅释放调用方明确要求释放的预留。

输出

返回项目、身份、线程/消息 ID、预留 ID 和路径（及其 TTL）、冲突和时间戳。所有后续决策均由调用方负责。

终止状态必须明确报告，绝不可不作说明：

• 适配器不可用 — MCP 工具和 am CLI 均不可用：报告 Agent Mail 不可用并停止。不要改用手写协调，也不要将其视为“没有冲突”。
• 预留冲突 — 原样报告冲突的预留；不要缩小、扩大、续期或强制释放。
• 邮箱所有权冲突 — 守护进程和直接 CLI 争用同一个存储根目录：报告锁的所有者/模式并停止；不要将重启、修复或绕过锁作为协调的副作用。
• 所需确认待处理 — 报告确切的消息和预期收件人，并停止依赖此确认的转换。不要根据后续回复推断已确认，也不要在验证后补做确认。
• 超时/功能降级 — 报告操作已超时或功能降级，并说明观察到了什么、未观察到什么；超时是证据，不代表“已完成”。
• 清理 — 按 ID 列出本次会话中已释放的预留；注明仍保留（TTL 尚未到期）的预留，以便调用方查看剩余项。

参考资料

• CLI 和 MCP 界面说明
• 协调模式
• 故障排除