DeepSeek Harness 聊天流中的 max-tokens 截断提示turn-max-tokens 会话节点的设计与实现【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本文基于仓库内 Agent Note 文档 2026-08-12-max-tokens-turn-end-notice.zh.md 展开。该文档记录了一次已落地implemented的 Web 聊天流缺陷修复当模型因单次请求输出 token 上限max-tokens被提供方截断时聊天界面此前没有任何可见迹象——被截断的回答看起来和正常完成一模一样。本次修复新增了一个独立的turn-max-tokens会话节点在被截断轮次的位置生成一条持久、本地化、可随历史回放重建的提示行。读完本文你将理解该问题的完整来龙去脉、节点在conversation.chat.node槽位下的实现细节、备选方案的取舍逻辑以及仓库如何用 fixture 与 golden snapshot 钉死这一行为。问题背景max-tokens结束原因存在却没有任何用户表面消费它在 DeepSeek Harness 的 agent loop 中一轮turn的结束早已被建模为带原因的turn/end事件其中就包含max-tokens这一独立结束原因。从源码看agent.ts 把StepEndReason直接收窄为completed | max-tokens两种type StepEndReason ExtractTurnEndReason, { kind: completed | max-tokens }并且在轮次推进中max-tokens具有“粘性sticky”一旦某个 step 命中输出上限后续正常完成的 step 也不能把轮次结果降级回completed见 agent.ts 的注释 max-tokens is sticky。step 层面对 finish reason 的判定则非常直接agent.tsif (finish.kind max-tokens) return { kind: max-tokens }在持久化一侧coordinator.ts 对turn/end的 reason 做了严格的结构校验completed、blocked、max-tokens、interrupted四种原因只允许携带kind一个键不允许附带错误负载只有aborted才允许额外携带reason字段。这印证了文档中的关键论断——max-tokens事件本身不携带任何 token 数量信息因此后续 UI 提示也不得编造提供方未报告的预算数据。然而问题在于agent loop 记录了原因UI 却没人消费它。Web 聊天流中只有reason.kind error的turn/end会生成会话节点即turn-error节点而unknown-surface兜底只接管 append-surface 事件。于是被提供方在输出上限处截断的轮次没有任何可见迹象截断的回答与正常完成的回答在界面上无法区分用户无从得知运行为何停止——这正是 issue #1522 报告的验收场景。方案决策新增独立的turn-max-tokens会话节点面对上述缺口修复方案是在会话节点Conversation Node体系中新增一个独立的turn-max-tokensDefinition匹配条件event.type turn/end event.data.reason.kind max-tokens呈现方式在该轮位置生成一条持久聊天行——warning 状态的 StateDot、本地化标题以及说明“已截断的输出会保留发送‘继续’可在新一轮接着输出”的指引推导原则节点只从持久会话事件推导因此刷新、恢复和历史回放会重建出完全一致的结果数据边界提示不显示任何 token 数字——事件不携带数量提示也不得伪造提供方未报告的预算数据。节点实现逐段剖析核心实现位于 turn-max-tokens.ts整个文件不到 90 行结构非常清晰。状态定义与事件匹配TurnMaxTokensState只保留三个稳定字段——turn轮次号、seq该turn/end事件的序列号、time事件时间。匹配逻辑通过match回调实现match: (event) { if (event.type turn/end event.data.reason.kind max-tokens) { return { id: String(event.data.turn), role: start } } return null },stateFrom做了同样的守卫非turn/end或 reason 不是max-tokens一律返回undefined。start阶段在状态缺失时直接抛错turn-max-tokens start requires a max-tokens turn/end杜绝非法构造update阶段保持状态不变——因为该节点只关心一个终态事件。视图节点构建buildViewNode组装TurnMaxTokensNodekind、seq、time、turn、step其中step由lastStep计算——取当前轮 location 中最后一个 step 的编号用于把提示行锚定到截断发生的那一步附近。锚点算法noticeAnchor这是实现里最讲究的细节。注释明确说明提示行必须插在 closing Assistant收尾助手消息与 turn-tail轮次收尾之间这样 turn-tail 仍是该轮最后一个 Chat 节点从而保住 turn-tail 上的 branch action分支操作不被破坏。算法取 turn-tail 数据中的closing.finalNode.seq再加上合成偏移量CHAT_SYNTHETIC_SEQ_OFFSETS.maxTokensNotice若没有收尾 Assistant则退回到turn/end自身的 seq提示行仍然停留在截断点。合成序列偏移量表定义在 common.tsexport const CHAT_SYNTHETIC_SEQ_OFFSETS { interruptedAssistant: -0.9, interruptedFollowup: -0.8, processControl: -0.1, maxTokensNotice: 0.05, finalizedFollowup: 0.1, } as const最终视图节点通过chatNode()工厂构建获得引擎持有的稳定 keycontext.key保证同一轮的重建结果可稳定对齐。渲染与本地化与错误行严格区分渲染端在 MessageItem.tsx 中实现TurnMaxTokensItemfunction TurnMaxTokensItem({ t }: { t: ChatViewSlotProps[t] }) { return ( div className{css.turnErrorRow} rolestatus StateDot statewarning className{css.turnErrorDot} / div className{css.turnErrorCopy} span className{css.maxTokensTitle}{t(message.maxTokens)}/span span className{css.turnErrorMessage}{t(message.maxTokens.hint)}/span /div /div ) }注意rolestatus语义与StateDot statewarningwarning 圆点正是把该提示与turn-error错误行区分开的关键视觉信号后者呈现为错误样式。文案在 locale.ts 中成对维护中文已达到输出 token 上限/回答被截断已有输出保留在对话中。发送“继续”可让模型接着输出。英文Output token limit reached/The reply was cut off; earlier output is preserved in the conversation. Send continue to let the model resume.渲染器通过TurnMaxTokensNodeViewmemo 化注册到按 kind 分发的conversation.chat.node槽位见 register-node-renderers.tsctx.slots.inject(conversation.chat.node, () ctx.slots.register( { name: conversation.chat.node, key: turn-max-tokens, locale: NS }, TurnMaxTokensNodeView))而节点本身则通过registerTurnMaxTokensConversationNode(ctx)注册进ctx.uiConversation.eventsDefinition 的target: chat声明了它唯一的视图目标。这样的双注册模式与turn-error、turn-tail等既有节点完全一致对照 turn-error.ts 与 turn-tail.ts。历史兼容投影legacy chat-snapshot 也包含该节点为了不让旧式快照投影legacy chat-snapshot遗漏新节点chat-snapshot-builder.ts 的legacyContribution把turn-max-tokens与turn-error、unknown等一起归类为“完整贡献”{ anchorSeq, nodes: [node.data], partial: null, running: null }而turn-tail这类纯收尾行则被显式标记为不贡献旧时间线。这意味着基于旧投影的 StatsLine 等消费方也能看到这条提示节点而不是被静默丢弃。备选方案与取舍文档记录了三个被否决或暂缓的替代方案各有清晰的工程理由值得作为决策上下文保留在turn-error上加一个 max-tokens 分支——否决。issue #1522 的验收要求明确max-tokens不得呈现为普通 provider error。共用一个节点会把两种呈现耦合在一起且两种原因携带的数据不同——error 原因带错误负载reason.error而 max-tokens 原因只有kind没有负载。强行合并会迫使 UI 在“有错误信息”与“无任何信息”之间做条件渲染破坏两类节点的数据契约。从 turn-error.ts 的failureFrom可以看到错误行需要从reason.error提取 message 与 code这与 max-tokens 节点的数据形状天然不兼容。用 turn-tail 标记代替独立聊天行——否决。turn-tail 渲染的是完成轮次的收尾信息其上的操作会在后续轮次折叠而截断提示必须停留在被截断的那一轮并且在历史中无需交互即可看到。把两者混在一起会让“截断提示”随轮次推进而消失恰恰违背了提示的持久性要求。在提示上放“继续”或“重试”按钮——暂缓。恢复输出的语义尚未确定是新开一轮还是同轮续写旧输出如何保留issue #1522 明确把它排除在范围外。指引文字已经给出安全的下一步动作发送“继续”不必先固定一个操作契约待语义确定后再补按钮不迟。测试与 golden把行为钉死修复的可验证性由两处关键测试资产保证组装式 E2E 测试max-tokens-notice.expected.e2e.ts 通过真实的构建产物packages/client/*/lib/client.jsbundles走 AppWebEntry 的 ModuleLoader 路径启动打开 keyless fixture 会话定位到 max-tokens 轮次fixture 中编号为 72图片轮和 todo 轮顺移为 73、74断言截断的回答本身仍保留在对话流中测试先findByText(/条目 3这一条写到一半被/)注释明确“the notice supplements the partial output, it never replaces it”出现带maxTokensTitle的[rolestatus]行该行的“圆点状态 标题 指引文案”三要素与 golden 完全一致。测试特意把dotwarning与文案一起钉住注释说明若将来发生“把 max-tokens 路由回错误样式”的回归即使文案仍能渲染golden 也会因圆点状态变化而失败。golden 文件位于 history-turn.expected.txt内容为dotwarning titleOutput token limit reached hintThe reply was cut off; earlier output is preserved in the conversation. Send continue to let the model resume.快照体系侧仓库的 session 快照目录下还存在snapshots/sdk/max-tokens-continue/含 session.jsonl以及 session-stats 投影测试 中直接构造turn/endreason: { kind: max-tokens }的用例说明该原因在会话统计投影中同样被作为合法终态处理。影响与边界本次改动落地后max-tokens结束在实时流、刷新和历史回放中都可见、已本地化并与错误和正常完成明确区分。伴随的 fixture 重编号需要更新两处依赖 snapshot 的注释此后任何钉 fixture 轮次号的改动都需按新布局72/73/74计数。值得注意的是边界范围Web 聊天流之外的表面ACP 与 SDK 消费方仍按各自的呈现映射处理该原因本次保持不变——这体现了 DeepSeek Harness 分层呈现presentation mapping的设计同一事件原因在不同消费面可以有各自的呈现策略修复只针对 Web 聊天流这一个表面不越界改动其他协议面。小结turn-max-tokens节点是一次教科书式的“事件原因 → UI 消费”补齐agent loop 早已如实记录max-tokens结束原因并保证其粘性持久化层也严格校验其无负载结构缺的只是 Web 聊天流里一个按 kind 分发、从持久事件推导、可随历史回放重建的呈现节点。它没有借用turn-error的样式避免误导为 provider 错误没有塞进 turn-tail避免随轮次折叠也没有越权承诺“继续/重试”的操作契约——只提供一条 warning 状态的持久提示和一句安全指引把边界与未来演进空间都留给了后续迭代。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考