Claude Code 系统提醒解析:Attached Machine「回复未收到」的故障状态提示词设计

原创2026-10-08 17:27:441,730 阅读
文章标签:人工智能提示工程代码智能体文档

Claude Code 系统提醒解析:Attached Machine「回复未收到」的故障状态提示词设计

本文基于 Claude Code 提示词开源镜像仓库中的 系统提醒原文,逐段解析这条在云会话连接用户本机(attached machine)场景下注入的故障处理提示词:它报告了哪种故障状态、由哪些模板变量驱动、如何约束 Agent 在「命令结果未知」时的行为,以及它与同族其他 attached machine 提醒在故障谱系中的分工。读完本文,你可以完整读懂该提示词每个变量的取值来源与每条行为指令的设计意图,并将其作为设计「命令失联」类 Agent 故障恢复提示词的直接参考。

一、这条系统提醒的定位

Claude Code 并不是只有一个固定的 system prompt,而是由 500+ 条按环境条件动态拼接的提示词片段组成(见 README 的说明)。其中 system-reminder-* 系列是运行时注入的「系统提醒」文本,用于在特定事件发生时向模型通报状态并给出行动约束。

System Reminder: Attached machine reply not received(276 tokens,提取自 Claude Code v2.1.287,见文件头部 front matter 的 ccVersion 字段)专门处理这样一类故障:机器仍然连接、且能响应存活探测,但某条已发命令的回复始终没有送达,因此该命令的结果处于未知状态。README 对该条目的索引描述是:

Reports that a still-connected attached machine's reply to a command never arrived despite liveness checks, so the outcome is unknown, forbids re-running non-idempotent commands just to see output, and suggests narrower commands for large output.

完整的原始模板如下(保留 原文 逐字内容):

${REMOTE_MACHINE_NAME} is still connected, but its reply to this command was not
received (${UNANSWERED_CHECK_COUNT} checks about ${MATH_OBJECT.round(CHECK_INTERVAL_MS/1000)} s
apart got no answer, though ${REMOTE_MACHINE_NAME} answered a liveness check). Its state is
unknown — it may have completed, failed, or still be running; the reply may have been too
large to deliver. Do not re-run non-idempotent commands on ${REMOTE_MACHINE_NAME} just to see
the output. If the output may be large, try a narrower command (part of a file, a filter, or a
smaller image); otherwise do the rest of the task without ${REMOTE_MACHINE_NAME}, and tell the
user what you could not verify.

渲染成对话后,模型看到的就是一段「状态通报 + 行动指令」,没有多余寒暄。这个紧凑结构本身就是设计要点:故障恢复类提醒必须同时说清三件事——发生了什么、为什么不能简单重试、现在应该做什么。

二、模板变量与插值语法拆解

front matter 声明了 4 个插值变量,逐个说明其语义:

变量 类型 语义
REMOTE_MACHINE_NAME 字符串 用户本机的展示名。模板中出现 3 次(开头、存活检查从句、两条指令中),始终指代同一台机器,避免模型在多台机器场景下张冠李戴
UNANSWERED_CHECK_COUNT 数字 连续未应答的探测次数,是「失联程度」的量化证据
MATH_OBJECT JS 对象 提供 round() 等数学方法。模板内直接写 ${MATH_OBJECT.round(CHECK_INTERVAL_MS/1000)},把毫秒间隔取整成秒数后再渲染
CHECK_INTERVAL_MS 数字 两次存活检查之间的间隔(毫秒),经上面的取整运算后以「about N s apart」的形式呈现

几个值得注意的实现细节:

  • 插值即模板引擎调用。与兄弟文件(如 stopped answering 提醒 中的 ${IS_WHILE_COMMAND_RUNNING?"...":"..."} 三元分支)一样,这些 ${...} 表达式在 Claude Code 渲染阶段求值,模型看到的是纯文本。MATH_OBJECT.round(CHECK_INTERVAL_MS/1000) 这种「模板内直接调方法」的写法说明渲染器允许注入任意可调用对象,而不是单纯的变量替换。
  • 证据先于结论。模板没有直接说「机器出问题了」,而是先给数据:N 次检查、约每 X 秒一次、均无应答——同时紧跟反证「though it answered a liveness check」。这组对照精确刻画了故障边界:链路是通的(存活检查有应答),但业务回复丢了。
  • token 开销被显式管理。README 标注该条为 276 tokens,且注明含插值的条目实际开销会有 ±20 tokens 浮动。对每次故障事件才注入一次、但可能反复注入的提醒文本,控制篇幅是明确的工程取舍。

三、「结果未知」状态的四条行为指令

模板后半段是针对未知状态的恢复策略,四条指令各有针对的典型错误:

  1. 禁止重跑非幂等命令。原文:Do not re-run non-idempotent commands on ${REMOTE_MACHINE_NAME} just to see the output. 这是最危险的一类误判:命令可能已经执行成功,仅为「看一眼输出」而重跑,会把一次部署变成两次、一笔支付变成两笔。模板把幂等性作为重跑的唯一准入门槛——只读、可安全重复的命令允许,非幂等的一律禁止。
  2. 大输出场景改用收窄命令。the reply may have been too large to deliver 指出了失联的一个可能根因是回包过大而非机器故障,因此给出的解法是 try a narrower command (part of a file, a filter, or a smaller image)——读文件的一部分、加过滤条件、或换更小的图片。注意原文特意举了「smaller image」,说明 attached machine 场景确实包含截屏/图片这类大二进制回包。
  3. 无法收窄时绕开该机器继续任务。otherwise do the rest of task without ${REMOTE_MACHINE_NAME}——Agent 不应在原地等待或空转,而要把不依赖该机器的部分先做完。
  4. 如实报告无法验证的部分。tell the user what you could not verify——这与仓库中多条「truthful reporting」基调的提示词(如 Reporting outcomes 要求区分观察到的结果与意图、不得夸大未完成的工作)一脉相承:未知就是未知,不能把「没收到回复」粉饰成「应该成功了」。

四、在 attached machine 故障提醒家族中的位置

这条提醒不是孤立存在的。从同一批文件看,Claude Code 为「本机失联」构建了分层的故障谱系,每条提醒对应一个可区分的状态:

故障状态 判定特征 核心指令 文件
回复未收到(本文主角) 机器仍连接、应答存活检查,但命令回包 N 次探测未达 禁重跑非幂等;大输出改用收窄命令;绕开该机器继续;报告未验证项 system-reminder-attached-machine-reply-not-received.md
停止应答 健康检查本身无人应答(命令运行中或发出后) 重连前禁重试非幂等命令,且本回合内不得再调用该机器 system-reminder-attached-machine-stopped-answering.md
不可达(离线) 机器列表标记为不可达(睡眠/离线/对端未运行) 禁止调用;禁止 sleep/轮询等待;仅当用户要求时单次重试 system-reminder-unreachable-attached-machines.md
停止提供工具 对端 Claude 应用关闭/断连/云会话工具开关被关,调用被拒且「Nothing was sent」 请用户检查对端应用;若是借文件夹接入的会话,之后需重新申请该文件夹 system-reminder-attached-device-stopped-offering-tools.md
信任拒绝 会话携带未标记信任的仓库/文件,调用被拒 重试无效;调用一次文件夹列表工具,把信任问题转述给人 system-reminder-attached-machine-untrusted-attachments-refusal.md

对比前两条可以更清楚地看到主角提醒的边界:stopped answering 是连存活检查都没人应答(链路层面失联),指令严厉到「本回合内不要再碰」;而 reply not received 是链路活着但业务回包丢了,所以还保留了一条「改用更窄命令重取输出」的抢救路径——毕竟机器是活的,只可能是回包太大或投递失败。两条提醒共享同一套变量(REMOTE_MACHINE_NAME、UNANSWERED_CHECK_COUNT、CHECK_INTERVAL_MS、MATH_OBJECT),可以推断它们在同一个探测/等待循环中被触发,只是按「存活检查是否仍被应答」分流到不同文案。

五、背景:attached machine 的调用路由机制

理解这条提醒,需要知道命令是怎么发出去、又是怎么丢的。根据 Bash 工具描述中的 Machines 小节:

  • 当会话列出了 attached machine(用户自己的电脑),Bash 工具会在两个环境二选一执行:每次调用时把 _host 字段(REMOTE_MACHINE_FIELD_NAME 变量,实际字段名即 _host)设为机器名,命令就路由到该机器;省略该字段则在本会话自己的环境(云端容器)中执行。
  • 按「命令关心哪台机器」逐次选择路由;用户文件、应用、磁盘、进程只在其本机上存在。
  • 机器会上下线:列表中标为不可达的机器不要调用,且严禁 sleep、轮询或安排等待;把这里能做的先做完,等用户说回来了再查一次。

也就是说,「回复未收到」发生在一个已经选定了 _host 的调用之后:命令已经送达(否则会走到 stopped answering / unreachable 分支),存活探测也还在通过,但结果回包在多次探测窗口内没有回来。Remote machine-only resources routing 提醒 则界定了哪些任务「必须」走这台机器(平台工具如 Xcode、Docker 守护进程、集群/云登录、USB 设备、/Users/… 类路径、项目外大数据、内网地址),以及哪些任务不该绕道本机(项目自身代码的构建失败要修代码;本环境屏蔽的公共站点要直说被屏蔽)——这些判断直接影响「绕开该机器继续任务」时,剩余工作是否真的能在容器里完成。

六、版本沿革

该提醒的演进在 CHANGELOG 中有明确记录,两条值得注意:

  • v2.1.284 新增:CHANGELOG 记载其初版语义与现在一致——「连接中的机器回包从未到达,结果未知;禁止为看输出而重跑非幂等命令;建议收窄命令」。
  • v2.1.287 措辞修订:与 stopped answering 一起,fallback 句从「做 this container 能做的事」改为「在不用该命名远程机器的前提下继续任务」(continue the task without the named remote machine instead of doing what "this container can do")。这一改动的实际效果是:不再暗示「容器能兜底」,而是把「哪部分工作被这台机器卡住、哪部分可以继续」的决策权交还给模型按任务判断,避免模型误以为容器内一定可替代执行。

当前仓库快照对应的整体版本为 v2.1.292(见 README 顶部说明),而该文件 front matter 标注的 ccVersion 为 2.1.287,表示 2.1.287 之后的版本中这条模板文本未再发生变化。

七、小结:一个可复用的「命令失联」提示词模式

把这条 276 token 的模板抽象出来,它给出的「结果未知」处理范式包含五个要素,可直接迁移到其他 Agent 系统中:

  1. 量化证据:未应答次数 + 检查间隔(N checks about X s apart),而非模糊的「超时了」;
  2. 反证并列:同时陈述「但存活检查有应答」,帮模型缩小故障面(投递失败 vs 机器宕机);
  3. 状态三值化:明确「可能已完成、可能失败、可能仍在运行」,不诱导模型猜结论;
  4. 幂等门控:以命令是否幂等作为能否重跑的唯一判据,大输出场景给收窄命令的替代路径;
  5. 诚实上报:强制向用户说明「哪些未能验证」,而不是默认成功或默认失败。

结合 unreachable 提醒 中「单次调用最多 10 秒失败、是确认机器回来的唯一途径,因此只在用户要求时重试」以及全局「禁止 sleep/轮询/定时等待」的约束,可以看出 Claude Code 对 attached machine 故障的整体设计取向:用确定性的探测信号 + 明确的禁止清单替代模型的自主等待,把「什么时候再试」的决策权收回给用户,把「失联期间做什么」的决策权交给任务本身。

登录后查看全文
claude-code-system-prompts