dcode 执行 /offload 时返回 409 怎么排查？

dcode 执行 /offload 时返回 409 怎么排查？

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

在 dcode（deepagents-code）的 TUI 会话里执行/offload（别名/compact，用于"Summarize and offload older messages to free context"，见 COMMANDS.md）时，请求可能被服务器以 HTTP 409 Conflict 拒绝。dcode 的 TUI 和 headless 模式都是本地临时 LangGraph 服务器的客户端，/offload是服务器端操作而不是客户端文件系统动作，409 正是这条服务器路由定义的线程冲突信号。这篇文章基于仓库中 offload 路由的源码注释和 openwiki 文档，说明 409 的准确含义、每种冲突类型对应的判断依据，以及把线程恢复到可完成 offload 状态的操作方式。

先确认 409 的含义：什么都没提交，可以安全重试

/offload路由的状态码语义在路由实现的文档字符串中有明确定义（offload_api.py）：

• 200— 操作完成，或返回一个可续答的 hook 请求；后一种情况同样不写状态；
• 422— 请求体格式错误，按字段名指出，什么都没执行；
• 409— 线程冲突：active、interrupted、持有 pending graph work、未注册、没有可 offload 的 checkpoint，或 checkpoint 已越过读取时的版本。Nothing committed（没有任何状态被提交）；
• 503— 服务器运行时无法构建，什么都没执行；
• 500— 无法确定的写入（压缩已发生但提交无法确认，detail 会说明）或服务器内部错误。

也就是说，409 是"线程当前不满足执行条件"，不是数据损坏。路由在提交之前拒绝冲突，且 offload 允许写入的通道白名单只有_summarization_event、_summarization_session_id和_session_cost_usd，绝不包含messages（见 context-management）。409 之后 checkpoint 消息原样未动，等线程恢复空闲后重新执行即可。

409 响应体是{"detail": ...}，detail文本指出具体是哪一类冲突，这是排查的入口。

对照 detail 判断冲突类型

路由文档字符串列出的 409 冲突类型与对应情形如下：

另外两条同样返回 409 的边界（见 run-dcode-session）：

1. 并发/重复尝试被注册表拒绝。服务器按线程加锁串行化 offload 操作，(thread_id, operation_id)注册表会拒绝重复的 active 或 terminal 尝试。同一线程上并发触发两次 offload，或重复提交同一个 operation id 的旧尝试，会得到 409。对 TUI 用户来说就是不要在一次 offload 尚未结束时再次触发。

2. workspace 绑定阶段的 409（offload_api.py）。这发生在会话启动绑定工作区时，不是 offload 压缩冲突，文档给出的 detail 有两种：

   • clients cannot claim project workspace policy— 客户端在请求中声明了项目级 workspace 策略字段，而策略以服务器为准，客户端只能声明会话级策略；
   • workspace configuration does not match server policy— 客户端携带的配置指纹与服务器解析出的策略不一致（配置漂移）。服务器在每次执行时重新解析 workspace 策略，宁可拒绝也不在变更后的信任或配置下静默运行。

被中断的运行留下的 busy 线程

409 中较常见的一类来源是：客户端取消了 SSE 流，但服务器端的 run 尚未结束。仓库中 remote_client.py 的aupdate_state文档说明了这一模式——服务器仍认为线程 busy 时，恢复路径会取消 pending/running 的 run（带超时上限、并发执行）并清理 checkpoint 中的 pending work；aabandon_pending_work的注释也明确"409 恰好发生在 run 从客户端侧被取消的线程上"。该行为由集成测试 test_pending_work_recovery.py 覆盖：测试构造一个在工具节点前暂停的图，通过客户端放弃它，并验证被取消的工具从未执行、错误ToolMessage记录了取消。

对应到你的操作：如果 409 出现在你中断了某次运行之后，等客户端恢复流程把 pending work 清理干净（线程不再 busy）再重试 offload。注意文档同时说明：error 状态的线程是有资格的——只要失败的轮次没有留下 pending 节点，仍然可以执行 offload 恢复，不需要因为上一轮报错就放弃。

如果 offload 正在进行中

hook 机制会让 offload 走多轮：如果PreCompact/PreToolUsehook 需要答复，路由返回的是200加可续答的 interrupt，客户端用同一个 operation id 携带累积的 hook 答复重发，服务器从头重放已回答的调用。所以"卡住等待答复"表现为 200 interrupt 而不是 409，不要把它误判为冲突。

如果确认需要终止一个已注册的 offload 操作，服务器提供了取消端点POST /dcode/threads/{thread_id}/offload/{operation_id}/cancel（offload_api.py）：它取消注册的操作并等待其进入终态，返回cancelled（取消成功）或finished（操作已经完成）。

验证 offload 已成功

• 重试后的成功响应是200，状态为 complete。此时只有白名单通道（摘要事件、摘要 session id、会话成本）被写入，消息身份保持不变。
• 在 TUI 中用/context查看当前 context window 占用（见 COMMANDS.md），与 offload 前对比，确认上下文已释放。
• 本地模式下，会话压缩归档存放在DEEPAGENTS_HOME（默认~/.deepagents）的conversation_history目录下，每个会话一个 markdown 归档{session_id}.md；每次压缩追加一个带时间戳的## Summarized at段落而不是覆盖旧内容，所以可以在文件里核对本次压缩是否产生了新段落（见 context-management）。
• 仓库的集成测试 test_compact_resume.py 展示了官方验证形态：对生产形态服务器执行/offload，校验 checkpoint 消息身份不变、cutoff 前进，并归档后可通过 agent 自己的read_file工具读回。

边界与常见误判

• 409 与 500 不要混淆。500 且 detail 说明"压缩已发生但提交无法确认"时，是 indeterminate write——压缩工作可能已经发生、成本可能已经产生，这与 409 的"什么都没提交"性质不同，按 detail 的指引处理而不是简单重试。
• 503 是运行时构建失败，与线程状态无关；文档给出的处理是查看服务器启动日志（detail 文案为 "The server could not build its agent runtime ... Check the server log for the startup failure."）。
• workspace 绑定 409 与 offload 409 是不同阶段的问题。前者出现在会话绑定工作区时，指向客户端声明与服务器策略不一致；它不是"等线程空闲"能解决的，需要核对客户端与服务器两侧的配置来源是否一致（服务器始终是唯一权威）。
• offload 允许重试的前提来自文档明确的拒绝条件：路由只接受空闲、已注册、无 pending graph work的线程，且在规划后再次校验空闲性和 checkpoint 一致性。因此"线程空闲后重试"是文档支撑的操作路径，而不是经验推断。

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents