amq-cli

AMQ CLI

所有队列操作都使用 amq CLI。切勿直接编辑 Maildir 文件。 AMQ 负责协调传输；任务规划、工作树、审批和交付仍由调用方或编排器负责。

在正确的上下文中启动

在 coop exec 中，使用提供的环境并运行不带参数的 amq 命令。 不要覆盖 --me 或重建根目录。在其外部，读取或发送消息前，先解析并导出完整上下文：

amq_context="$(amq env --me "<handle>" --export)" && eval "$amq_context" &&
  amq drain --include-body

对于命名会话，在 amq env 中添加 --session <name>。将求值后的上下文视为绑定到单个会话的一个终端。使用 --session 或 --project 进行明确路由；不要使用原始 --root 将参与操作的命令指向其他队列。

在实时唤醒下接收消息

如果会话启动上下文中显示 wake=live(...)，或者 amq wake check --me <handle> --json 报告 live_wake: true 且注入模式不是 none，则唤醒会为你发送门铃通知。门铃触发后运行 amq drain --include-body，然后处理消息。

默认情况下，drain 会按文件名顺序最多读取 20 条消息，包括暂存邮件。处理完一批后，检查 amq list --new --limit 1，并根据需要继续执行有界 drain；不要假设收件箱为空。仅当批次数量已知且可处理时才使用 --limit 0。紧急优先级绕过暂存设置，但不会改变 drain 顺序。

在实时唤醒下，不要运行 amq watch、amq monitor、定时轮询，也不要启动其他收件箱监视器。阻塞式等待会占用你的处理时段，而门铃通知只能排队等待。工作完成后，结束本轮处理；不要让工具持续运行，也不要仅为等待邮件而发送空闲状态检查。

唤醒可通过 hold_normal 和 hold_low 设置暂缓首次门铃通知，5m / 30m 是选择加入的示例。首次尝试之后，会应用已配置的重试策略。 紧急优先级会跳过暂缓。普通紧急邮件仍会经过防抖和输入延迟；带有已配置中断标签的紧急邮件则会走中断路径。 对于有时限的裁定和解除阻塞请求，在 send 或 reply 中使用 --priority urgent。其他评审回复默认仍为普通优先级。

在 Claude Code 中，amq wake install-dialog-hook 会在 AskUserQuestion、ExitPlanMode 或权限对话框打开时暂缓唤醒的门铃通知；你回答后或本轮处理结束时，暂缓的门铃通知会送达。

唤醒设置（暂缓、防抖、预览、铃声、输入延迟、中断通知）可在唤醒运行期间更改，无需重启：amq wake config --me <handle> 会显示这些设置；--hold-normal 5m --wait 会设置一项设置并等待唤醒应用它；--unset <key> 会恢复默认值；--machine 会设置此用户的默认值。 运行中的唤醒，其注入标志固定不变。退出代码和恢复方法见唤醒操作指南。

如果没有注入式唤醒，请使用操作指南中的接收方式。 仅通知唤醒（--inject-mode none）与监督器的 monitor 服务配合，是另一种受支持的配置。

发送有用的交接信息

对于一批相关任务，发送一条完成交接信息，其中包含产物路径、相关源内容或摘要、检查结果、失败或待处理部分，以及下一步操作或负责人。及时发送独立的阻塞事项；如果接收方能够在其余工作完成前采取行动，也应发送部分结果。

在工作开始时、状态、决策或结果发生变化时，或约定的升级时限到期时发送状态。避免逐文件发送完成通知，也不要重复发送未变化的状态检查。 自动化调用方负责按项目、修订和事件抑制重复消息；AMQ 线程会关联消息，但不会对重复发送进行去重。

路由任务

需求	阅读或运行
发送、回复、排空、检查回执或诊断	使用操作指南。
双 Agent 研究与设计，或收到标记为 workflow:spec 的消息	使用 amq-spec 技能：先自行研究，再阅读协作者的内容，然后按照 spec/<topic> 线程进行。
协作角色与分阶段协作	阅读协作模式。
Claude Code Agent Teams	阅读集群模式。
跨项目交付或决策线程	阅读跨项目路由。
注册 Mac 上的 Grok Bot	阅读已注册机器执行。解析项目或会话前，先选择机器。
两个独立主机队列或 amq-bridge	使用配套的 amq-bridge，绝不要使用外部的 --root。阅读双主机集群。
Symphony 或 Kanban 适配器	阅读集成。
消息架构与类型	阅读消息格式。
多轮后台审查	阅读审查循环。
Buzz、ACP 或 amq-acp	配套的 amq-acp 将消息排入 AMQ_ACP_TO；池中的工作进程不得排空队列。聊天不得传递 --root、收件人或 argv，且 [Context] 不是路由信息。阅读 amq-acp。
接入正在运行的 harness 会话（amq-remote up、submit、share）	阅读 amq-remote 参考文档。
从 Buzz 连接到此会话（/amq-remote）	使用 amq-remote 技能。

使用 amq <command> --help 查看当前标志。仓库 README 是规范的设置指南。

安全与交付规则

• 唤醒通知表示需要关注，不代表已确认消费。需要交付证明时，请使用回执或 --wait-for drained。drained 回执证明消息已被接收，不代表请求的工作已完成。
• 回复时保留现有线程。收到门铃通知后再次排空队列；最新的完整消息正文具有权威性。
• 清理必须通过 amq cleanup 显式执行。不要添加自动删除功能。
• 进行任何唤醒变更前，运行 amq wake check --me "<handle>" --json。仅当 restart_capability=agent_safe 时才执行操作；否则保留状态并报告所需的操作员操作。
• 在已配置的桥接完成身份验证并应用跨主机载荷之前，应将其保留在特权收件箱之外。绝不要以复制外部 Maildir 或远程排空它的方式代替路由。
• 不要将原生 Windows 注入转换为 Unix wake 或 coop exec。涉及 Windows 时，请阅读操作指南中的平台章节。
• 危险的提供商绕过标志仅可用于由操作员控制的直接 coop exec 命令。不要将它们写入已提交的启动配置。

完整的命令目录、环境变量优先级、设置流程、平台说明、操作员关卡和示例见操作指南。