命令超时与假装完成：“手脑分离”架构下的 Agent 长任务治理

在本地终端环境中，让 Agent 将长耗时命令转入后台运行并不是新问题。从 Claude Code 到各类命令行 Agent，开发者早已熟悉长命令脱离前台交互的体验：Shell 进程与 Agent 循环运行在同一台机器上，后台任务本质上是本地操作系统进程树与内存中的一个异步子进程句柄。查询状态读取本地管道，取消执行发送本地信号，其复杂度始终被封装在单机操作系统的抽象之内。

当 Agent 演进为面向企业团队的“手脑分离”架构——由受保护的控制面持有推理循环与会话状态（“脑”），由远程独立沙箱按需挂载并执行代码（“手”）——原本由同机环境兜底的单机假设全部失效。

在这一架构下，后台任务不再是一个能够随时轮询的本地 PID，而是一次跨越网络故障域的分布式状态转移。系统不仅要应对反向代理与网关的连接超时限制，还必须在网络中断、控制面 Worker 崩溃与多人并发协同中维持状态一致性；更普遍的工程失效，则是模型在脱离会话流的长任务面前，产生“命令已在后台启动”并擅自勾掉未完成待办事项的幻觉性收工。解决这一问题，需要在回合生命周期、任务清单校验、日志收集与中断控制上建立完整的状态契约。

单节点与“手脑分离”的状态与网络边界

单节点 Agent 与分布式 Agent 在长任务处理上的根本区别，不在于是否支持后台执行，而在于状态与生命周期是否需要跨越网络故障域进行多节点同步：

维度	单节点 Agent（如 Claude Code / 本地 CLI）	手脑分离架构（控制面 + 远程沙箱）
执行拓扑	脑与手同机，共享宿主 OS 内存与进程树	脑在控制面（API/Worker），手在远程独立沙箱节点
后台任务机制	本地异步子进程，依赖 OS PID 与本地文件句柄	跨节点的分布式后台任务，依赖网络状态转移与持久化元数据
连接与生命周期	本地终端交互，无中间网关超时限制	Web/IM 经由网关代理，受限于 60s~120s 读超时上限
状态持久化与恢复	依赖本地内存；CLI 退出即终止，不跨节点容灾	控制面持久化数据库与沙箱双向同步；Worker 故障可断点恢复
任务中断	直接向本地进程组发送 SIGTERM / SIGKILL	跨网络信号派发，需通过执行代际栅栏防范重试竞态
协同复杂度	单人独占终端，无需处理多方状态交织	团队多人共享会话，后台结果需处理会话锁竞争与并发排队

在“手脑分离”架构下，控制面（Web API / Agent Worker）与用户客户端（浏览器或企业 IM）通过 HTTP 或 Server-Sent Events（SSE）保持长连接。如果一条命令耗时超过 60 秒，若继续由前台同步阻塞，网关代理会因读超时主动掐断连接，导致整个执行状态悬挂。

CubePlex 设立了明确的 60 秒切分阈值：

1. 前台流式输出：命令在前 60 秒内正常将输出行流式推送到当前回复中，Agent 保持等待。
2. 跨节点状态转移与后台降级：若命令在 60 秒后仍在运行，CubePlex 将其注册为持久化的会话后台任务（Background Task），向 Agent 返回对应的 Task ID 与 Command ID。
3. 当前回复收敛：Agent 结束当前回合的回复，释放 HTTP 连接并完成检查点存储；远程沙箱内的实际进程不受影响，继续独立运行，默认享有最长 1 小时的执行期限。

在这个切分机制下，系统还必须杜绝两类常见的工程反模式：

• 禁止 Shell 逃逸符号（&、nohup、disown）：部分开发者和模型习惯在耗时命令后追加 &（例如 npm run build &）。在远程沙箱内，这会导致 Shell 进程瞬间以退出码 0 返回，命令脱离受管生命周期成为孤儿进程。它既没有持久化的 Task ID，无法捕获标准输出和异常退出码，也永远无法在结束时触发事件唤醒。CubePlex 的沙箱执行层与 Prompt 严格禁止模型使用后台符号，所有命令必须在前台启动，统一由控制面在达到 60 秒阈值时安全剥离（Detach）为受管后台任务。
• 规避模型的“忙等轮询强迫症”：当任务转入后台后，大语言模型天生倾向于在后续回合中频繁调用 sleep 5、ps aux 或 pgrep 来探测进程。这种忙等轮询会急速消耗上下文窗口与 Token 配额，并阻塞正常的交互回合。CubeLoop 明确约束模型在获知任务进入后台后，必须显式声明等待并结束当前回复，将唤醒时机完全交由底座的事件机制驱动。

这种机制保证了网络长连接不会被拖垮，但立刻引出了下一个更棘手的核心矛盾：脑与手脱钩后，模型如何正确感知任务依然在进行，而不是擅自宣告胜利。

防范假装完成：Todo 清单与宿主校验契约

在长任务异步化的过程中，模型最常见的失效模式是“幻觉性收工”。由于系统允许当前回复先行结束，模型在输出诸如“我已经在后台启动了数据导入脚本”之后，往往会自作主张地调用任务工具，将对应的 Checklist 项目标记为已完成，甚至向用户汇报流程已全部结束。

实际上，后台命令才刚刚启动，真正的业务产物尚未生成，脚本甚至可能在第 3 分钟因内存溢出而崩溃退出。

CubeLoop 在底座层面通过 TodoListMiddleware 与宿主校验回调，强制约束了未完成步骤的真实状态：

# CubeLoop TodoListMiddleware 中的等待声明逻辑
write_todos(
    todos=[
        {"content": "拉取基础代码", "status": "completed"},
        {"content": "执行全量测试套件", "status": "in_progress"},
        {"content": "构建生产镜像", "status": "pending"},
    ],
    wait_for_tasks=["task-deploy-build-892"],  # 显式声明正在等待的后台任务
)

该机制在运行时建立了三道防线：

1. 未完成状态强锁：只要后台任务尚未产出最终结果，对应的待办事项必须保持 in_progress 或 pending，禁止被模型单方面置为 completed。
2. 宿主双向校验：模型提交包含 wait_for_tasks 的清单时，CubeLoop 会触发 validate_task_wait 钩子向宿主（CubePlex 控制面）发起核实。只有宿主明确证实该任务 ID 真实存在且仍在健康运行时，等待声明才被接受并持久化入检查点。缺乏宿主校验或任务已非法的声明会被直接拒绝。
3. 无缝阻断提前收工：在当前回复结束前，未完成待办事项的守卫逻辑会检查是否存在有效等待。若存在有效后台任务，Agent 被允许正常挂起并结束当前回复；若不存在有效任务，守卫逻辑会强行迫使模型继续执行，避免其凭空挂起。

更重要的是等待状态的主动失效机制与并发工具调用的一致性：

• 精细划分的主动失效边界：当 Agent 挂起在 wait_for_tasks 时，系统的内部自动化策略放行（如预设的只读权限放行）或定时心跳检查不会破坏等待状态，Agent 保持静默；但只要发生任何人类意图介入——用户追加了新的插话、提交了 Human-in-the-Loop（HITL）问答答案，或人工介入批准/拒绝了一项工具调用——CubeLoop 会立即强制使等待声明失效，拉起新的模型回合优先响应人类诉求。
• 并发 Tool Call 下的状态快照幂等性：现代模型常在单回合内并行发起多个 Tool Call（例如一边发起长耗时命令，一边更新待办清单或读取代码）。若控制面在工具生命周期回调（如 after_tool_call）中采用了破坏性读取（如 pop 待办快照），批次中第一个工具返回后状态就被消费，导致同一批次中后续工具回调丢失上下文。CubeLoop 严格保证了状态快照在并发批次中的只读与幂等访问（使用 get 而非 pop），确保整批并发工具调用都能共享一致的上下文视图。

网络边界下的日志游标与崩溃恢复

在单机环境下，命令进程退出后可以直接从 stdout 读取全部输出并得到 exit code。但在远程沙箱中，进程退出与控制面成功获取完整日志是两个完全独立的网络阶段。

常见故障模式包括：命令执行完毕，容器内的 Agent 守护程序向控制面发送了通知，但在传输最后一块日志时网络中断；或者控制面的 Worker 节点在写入数据库前意外重启。如果简单地根据“退出码为 0”判定任务完成，就会出现界面上显示命令成功、右侧详情面板却丢失最后关键日志的“半残状态”。

CubePlex 0.9.0 引入了权威状态机与日志游标推进机制：

[ 沙箱 Provider 进程 ]
       │  (1) 产生输出块
       ▼
[ 流式接收缓冲区 ]
       │  (2) 写入 Command Log 成功后，才推进 Provider 日志游标
       ▼
[ 持久化数据库 (Command Log) ]
       │  (3) 校验输出完整性
       ▼
[ 结果状态机: result_pending ──> readable ──> delivered ]

• 游标与落盘严格绑定：控制面只有在输出分块被完整持久化到 Command Log 之后，才会向前推进 Provider 端的日志读取游标。任何读取或写入阶段的临时失败，都会让状态停留在 result_pending，而不是伪造一个空日志结果。
• 崩溃安全重放：若 Worker 发生重启，恢复程序会根据已确认的游标重新拉取末尾切片。为了防范数据静默丢失，系统宁可在恢复时安全重放最后一段日志，也绝不在游标未确认前推进状态。
• 区分权威缺失：如果沙箱实例因宿主机硬件故障彻底失联，系统会明确将其标记为“输出不可用（Unavailable）”，而非展示为空字符串的成功结果。
• Worker 重启与孤儿任务协调：当控制面 Worker 因发布重启、OOM 或节点漂移发生故障转移时，远端沙箱可能依然在运行长任务，但内存中的任务 Handle 和实时日志 SSE 订阅全部中断。控制面的后台任务协调器（Background Task Coordinator）在启动和定期巡检时，会主动通过数据库记录与底层沙箱 Provider 对齐真实进程状态。协调器通过带有代际栅栏保护的查询回收已完成的孤儿任务，幂等补发完成通知，既防止任务因 Worker 重启永久挂死，也避免重复投递引发模型被多次惊醒的风暴。

代际栅栏与跨网络取消信号

长耗时任务必然伴随着人工干预。当一个构建任务执行缓慢或行为偏离预期时，用户需要能够随时中断任务。

CubePlex 提供了两种维度的停止控制：

• Stop task：针对单个后台任务发起终止；
• Stop all：同时终止当前正在输出的响应，以及属于当前执行代际的所有后台任务。

在手脑分离架构下，取消操作的难点在于异步信号延迟与重试竞态。

假设用户点击了“停止任务”，取消请求由控制面写入事件队列并派发到远端沙箱。如果在信号到达前的一瞬间，该任务因超时刚好退出，且自动化策略触发了快速重试并拉起了一个新的执行进程，迟到的取消信号是否会误杀刚刚启动的新任务？

为了防止跨代误杀，系统引入了执行代际栅栏（Generation Fence）：

每一个后台任务都严格绑定其创建时的执行代际 ID（Generation ID）。当控制面下发停止指令时，携带该代际标识；沙箱端执行驱动在派发系统信号（SIGTERM，超时后升级为 SIGKILL）前，比对目标进程的代际标识。已被废弃的历史代际请求被直接丢弃，确保新发起的重试或后续步骤不会受到波及。

在状态呈现上，被接受的停止请求在沙箱 Provider 确认底层进程真正销毁前，统一展示为 Stopping 状态；只有收到可信的进程终止凭证后，才会完成资源回收。

多人协同会话中的事件唤醒与锁竞争

当沙箱内的长耗时命令在数十分钟后顺利完成，控制面必须将 Agent 重新唤醒，继续推进后续清单。

在单人单对话场景中，唤醒逻辑相对直接。但在团队 Agent 环境中（如 CubePlex Topic 或对接企业飞书、Slack 频道的多人会话），后台任务完成时往往面临复杂的会话锁竞争：

1. 身份归属绑定：后台任务最终产出的结果属于内部事件（Internal Task Event）。为了保证审计轨迹和权限一致，结果事件必须严格挂载在最初触发该命令的用户身份下，而不能以匿名的系统身份或当前正在查看界面的其他用户身份派发。
2. 避免打断活跃对话：当后台任务完成的瞬间，频道内可能正有另一位成员在向 Agent 提问，或者正悬挂着一个需要特定负责人确认的审批卡片。此时如果后台结果强制唤醒模型插入回复，会破坏正在进行的上下文。
3. 入队与空闲唤醒：内部任务事件在投递时遵循排队策略。如果当前会话正由某位成员的活跃 Run 占用，任务结果保持就绪等待，直到当前 Run 正常结束且会话恢复空闲状态，才自动拉起一轮新的执行，供 Agent 检查输出并勾选清单。

结语

单节点 Agent 依赖单机操作系统的进程控制来掩盖长任务的复杂性，但这种同构假定在面向企业团队的生产环境中无法维系。

把 Harness 提升到控制面、把执行下沉到隔离沙箱的“手脑分离”设计，是保障系统可用性、审计安全与多租户隔离的必经之路。而伴随这种架构必然出现的，就是对长耗时任务的端到端治理：从 60 秒前后台分流、Todo 宿主校验契约，到日志游标落盘、代际栅栏以及协同事件排队。只有将这些状态流转固化为确定性的系统机制，Agent 才能在真实世界的长时间任务中告别假装收工与连接超时，稳定交付可信的业务结果。