Repository navigation
Description
Parent roadmap: #261. Related work: edit and resend after stopping #375, conversation management #247, turn/tool/job/receipt correlation #372.
Summary / 摘要
While a reply is streaming, the assistant cannot accept a supplementary instruction. The composer replaces Send with Stop, Enter is silently dropped, and the API answers any second submission for the same project with 409 当前工程已有回复正在执行。. The draft survives, but it cannot be delivered until the turn ends. A user who remembers a missing constraint while the Agent is working must either interrupt the turn (discarding work) or wait and hope the result is not already wrong.
本 issue 描述一个已复现的能力缺口,并提出分层方案:运行中提交的补充消息进入投递队列,当前轮结束后在同一对话里自动续跑(P0,对所有 runtime 生效);在此基础上,对具备原生输入通道的 harness 提供同轮插入(P1,逐个 runtime 实测后再开放)。
Current behavior (verified)
Reproduction: pytest + TestClient, one turn held open through the existing disconnect_turn helper (the run keeps going after the SSE connection closes), then a second submission while active[project_id] is populated. Observed on 9d08bf5a:
PROBE second turn -> 409 {'detail': '当前工程已有回复正在执行。', 'code': 'operation_rejected'}
PROBE draft save -> 200
PROBE messages before/after -> 2 2
PROBE queued markers -> ['complete', 'streaming']
PROBE follow-up routes -> []
| Layer | Location | Behavior |
|---|---|---|
| Submit guard | apps/api/src/opendirector_api/agent.py:291-297 |
POST /turns takes a per-project admission lock, sees project_id in active, raises ProjectError('当前工程已有回复正在执行。', 409) |
| Composer | src/canvas/AssistantPanel.tsx:729-746 |
chat.sending replaces the submit button with the stop button; there is no queued/insert affordance |
| Keyboard | src/canvas/useAssistantChat.ts:436 |
send() returns early while submitting.current is set, so Enter during a turn is a silent no-op |
| Picker state | src/canvas/AssistantPanel.tsx:703,712,719 |
agent, skill and model pickers are disabled while chat.sending |
| Stream shape | src/backend/chat.ts:72-79 |
ChatEvent ends at end; status has complete/streaming/stopped/interrupted, no queued |
| Route surface | apps/api/src/opendirector_api/agent.py |
no queue, retract or follow-up endpoint exists; conversation switching is also refused while running |
| Design statement | docs/architecture/agent-runtime.md |
"同一工程同时只接受一个回复运行" — the single-run guarantee is intentional, not a bug |
The single-run guarantee is worth keeping: it is what keeps runtime sessions, active, the conversation file and the tool ledger consistent. What is missing is a place for input that arrives during a run.
Goal and scope
Let a user submit a supplementary message at any time, and deliver it without losing it, without breaking the single-run guarantee, and with an explicit, inspectable result.
- P0 — queued follow-up, universal. A submission during a run is persisted immediately as a user message in
queuedstate, shown in the conversation, and dispatched as the next turn in the same conversation once the current turn reaches a terminal state. Works for every runtime, including those whose process takes exactly one prompt. - P1 — same-turn steering, per runtime. Where the harness exposes an input channel while it runs (streaming stdin, session server, ACP extension), deliver the text into the running turn and mark it as applied to that turn. Gated on measured capability, not on documentation.
- Out of scope: multi-project parallelism, multi-Agent, reordering or editing the running prompt, and rewriting the runtimes into a duplex protocol.
User flow and rules
- While a turn runs, the composer stays writable and Enter submits. The send action becomes "queue for the next turn" (P0) or offers "insert into this turn" when the runtime declares steering support (P1).
- A queued message appears immediately in the transcript, above the streaming reply's continuation, with a
queuedmarker, its position, and a retract action. Queueing is a commit: the text leaves the draft, and the draft content is preserved in the message. - The running turn keeps its original prompt. A queued message is context for the next turn only, and the next turn sees the finished reply of the previous one. The UI states this, so a user does not believe the current answer already reflects the addition.
- When a turn ends and the queue is non-empty, the next turn starts automatically on the same stream, so the transcript never shows a stopped chain between two turns.
- Multiple queued messages are delivered in submission order, one turn each, unless the user merges them explicitly.
- Stop acts on a chain, not a single turn: stopping cancels the running turn and leaves queued messages in
cancelledstate with a Resend action. Interrupting must never silently consume a supplement. A per-turn continue action is offered separately. - A failed turn stops the chain and keeps the queue intact for an explicit retry. Automatic continuation after an error is not allowed.
- After a process restart, queued messages survive and are offered for continuation instead of being replayed automatically.
- Idempotency: resubmitting the same message id while queued returns the existing queue entry rather than a duplicate or a conflict; the conflict response remains for a message id that is already part of a turn.
- Every state (queued, dispatched, applied to a running turn, cancelled, failed) is visible in the conversation after a reload and through the Agent/CLI entry points.
Implementation impact
Reuse conversation persistence, turn submission, RunEvents replay and the stop path; add the minimum queue record and stream continuation.
- Backend: extend
Conversations(apps/api/src/opendirector_api/agent.py:61) with a per-conversation queue and thequeued/cancelledmessage states; replace the single-turnactiveentry with a chain entry that ownsRunEvents; addPOST /assistant/messages(submit-or-queue),DELETEfor a queued message, a chain-scoped event stream with a replay cursor, and explicit stop scope. - Events: add
seqper chain,messageevents for queue changes, andnextTurnIdonendso a client knows the stream continues instead of treatingendas final. Keep the existingendshape valid for clients that ignore the new fields. - Frontend:
src/canvas/useAssistantChat.ts(submit while running, continue the follower across turns, queue state and retract),src/canvas/AssistantPanel.tsx(composer stays enabled, queued marker and retract, stop semantics),src/backend/chat.ts(event and status types),src/i18n/messages/zh-CN/assistant.tsandsrc/i18n/messages/en-US/assistant.ts(bilingual, delivered together). - Runtime layer: add a declared capability to
RuntimeSpecinpackages/core/src/opendirector/agent/runtime.py(e.g.supportsSteering: bool = False) and surface it throughruntime_catalog()/GET /assistant/runtimes, so the UI never offers an insert the harness cannot honor. No runtime switches to steering without a measured probe.
Acceptance criteria
- Submit during a streaming turn; the text is persisted immediately, visible as
queued, and executed as the next turn after the current one ends, without a second client action. - The running turn receives exactly its original prompt; the next turn receives the queue in order with the previous reply in context.
- Queue two or three messages during one turn; all are delivered exactly once, in order, with no duplicate turn and no lost message.
- Retract a queued message before dispatch; it never reaches a runtime and the transcript shows it as withdrawn.
- Stop during a turn with a queued message; the turn stops, the queued message becomes
cancelled, is not auto-run, and can be resent. - A turn that fails leaves the queue intact for an explicit retry; no automatic continuation.
- Reload, disconnect and process restart preserve queue state and never replay a delivered message.
- Duplicate submission of the same message id produces one queue entry and one turn.
- Steering, where enabled for a runtime, delivers the supplement into the running turn and the reply reflects it; when it is not supported the UI offers queueing instead of failing late.
- Both locales cover every new string, and the UI states whether the supplement applies to this turn or the next.
Decisions to confirm
- Default queue semantics when a turn ends: auto-continue (proposed) versus a visible "continue" prompt.
- Multiple queued messages: one turn per message (proposed) versus coalescing consecutive submissions into the next turn.
- Stop scope: chain-wide with
cancelledqueue entries (proposed) versus turn-only where the queue continues. - Whether a queued message should also be included in a P1 steering-capable turn automatically, or only when the user picks "insert into this turn".
Activity
wtz2333 commentedon Nov 17, 2026
方案(待确认)
完整方案按仓库提案格式写在
docs/development/midturn-message.md(提交52889d26,分支docs/midturn-message)。当前账号对ThinkFlowLab/OpenDirector没有写权限(git push返回 403),所以先以评论形式贴在这里;拿到写权限或改走 fork 后再提交 PR。以下为正文,第 6 节是需要拍板的清单。
运行中插入补充消息:现状检查与方案
状态:方案待确认(第 6 节是需要拍板的清单)
范围:
src/canvas/、src/backend/chat.ts、src/i18n/messages/*/assistant.ts、apps/api/src/opendirector_api/agent.py、packages/core/src/opendirector/agent/关联:issue #379;路线图 #261;停止后编辑重发 #375;会话管理 #247
1. 背景
现在的对话是一问一答:发送之后,输入框的发送按钮被换成停止按钮,必须等这一轮回完才能再说话。用户真正的需要是「做这件事的时候,再补一句」——想起漏掉的约束、追加一个素材、纠正方向。等 3 分钟再说,产出的东西已经错了;点停止再说,这一轮的工作全丢。
Codex、DSH 这类 harness 的交互是可以中途插话的,所以这个差距是明显的体验落差,不是偏好问题。
本文回答三件事:
2. 现状检查
复现方式:用现有的
disconnect_turn把一轮回复保持在运行状态(SSE 断开后 run 继续跑),运行期间再提交一次。基线9d08bf5a,实测输出:读法:第二次提交被拒;草稿能存(正文没丢);对话消息数没变(补充内容没有进入对话);消息状态只有
complete/streaming(没有「待执行」);路由表里没有任何承接入口。四条合起来说明:补充内容既没有落地位置,也没有排队位置,只是留在草稿里。2.1 前端:运行中把「发送」换成了「停止」
src/canvas/AssistantPanel.tsx:729-746:chat.sending为真时,提交按钮整体替换成停止按钮;否则才是type="submit"、disabled={!chat.canSend || locked || !value.draft.trim()}的发送按钮。也就是说运行中根本没有提交入口,不是提交后失败。同一状态下
AgentPicker(:703)、SkillPicker(:712)、ModelPicker(:719)都被chat.sending禁用,避免运行中改配置。2.2 按 Enter 为什么没反应
src/canvas/useAssistantChat.ts:436:submitting.current在follow()开始时置真,直到这一轮end才在finally里复位。所以运行中按 Enter 是一条静默return:文字留在草稿里,没有任何提示,用户会以为键盘坏了。这是比「按钮变灰」更糟的一种状态——按钮至少是可见的。值得注意的是输入框本身是可写的:
ChatReferenceEditor.tsx:801的contentEditable={!disabled && !busy},而AssistantPanel.tsx:593只传了disabled={locked},busy是组件内部用于引用解析的useState。所以能打字、不能发,落差全落在提交这一步。2.3 服务端:单轮互斥是设计,不是疏漏
apps/api/src/opendirector_api/agent.py:291-297:运行中的$(turnId, task, RunEvents)$ 。同一状态下
active[project_id]是POST /conversations也拒绝(请先停止或等待当前回复结束,再切换对话。),GET /turns/{turn_id}/events只对当前运行轮有效,其余 404。docs/architecture/agent-runtime.md明写「同一工程同时只接受一个回复运行」。这条约束值得保留:它让 runtime 会话、active、conversation.json和工具账本之间只有一个写者,一旦放开并发,重连、停止、落盘的语义都要重做。所以缺的不是一个判断,而是**「运行期间来的输入放在哪里」这个位置**。
2.4 Runtime:每轮只有一个 prompt 入口
packages/core/src/opendirector/agent/下所有适配器都是一次性启动:opencode run --dir … --pure --format json --agent opendirectorrun是单次任务codex exec --json --skip-git-repo-check … --sandbox workspace-writeexec是单次任务claude -p … --output-format stream-json …(native.py:120-135)--input-format stream-json,stdin 不是消息通道session/prompt一次,取消用session/cancel结论:任何「真·同轮注入」都要落到具体 harness 的原生能力上,逐个实测,不能靠应用层「重发一遍」假装做到了。这决定了方案必须分层。
3. 三种可选语义
建议:A 作为通用底线(P0),先让「插不进去」这个硬伤消失;B 作为按 runtime 开放的能力(P1),没有实测就不显示;C 不做,避免让用户为一句补充付掉整轮成本。
A 的语义要诚实地告诉用户:这条补充不改变正在生成的这一轮,它会在这一轮结束后立刻以同一对话继续执行,并且能看到上一轮的产出。这样用户的预期和实际行为一致,不会误以为当前回复已经听取了补充。
4. P0:排队 + 自动续跑
4.1 数据
消息状态在现有
complete | streaming | stopped | interrupted之外增加两个:queued:已接受、未执行。带queueSeq(会话内单调递增)与提交时的runtime/model快照。cancelled:排队后被撤回或被停止取消,保留正文以便用户重发。队列本身不另建文件:直接复用
conversation.json的messages,status == 'queued'且queueSeq递增即队列。好处是刷新、重连、重开工程天然一致;坏处是每次取队首要做一次读改写,但这本来就在Conversations.update的事务里。「链」是运行时概念,链 id 取首轮 turn id;
active从「一个 turn」升级为「一条链」:chains: dict[UUID, Chain]取代active: dict[UUID, tuple[...]],release从「任务结束就 pop」改为「链结束才 pop」。这一步是必需的:现在任务一结束就active.pop,如果自动续跑放在finally里,中间会有一个窗口让新的POST /turns插进来,变成并发两轮。4.2 接口
新增一个入口,语义是「发一条消息,能跑就跑,跑不了就排」:
配套:
POST /turns保留原样(运行中仍 409),老客户端行为不变;新客户端走/messages。等 P0 稳定后再讨论是否让/turns内部转调。事件流加两个字段,并允许一轮结束后接着下一轮:
规则很简单:
end带nextTurnId表示链未结束,客户端不要关流;没有nextTurnId才是终点。seq让重连可幂等去重(老客户端忽略未知字段,end仍是终止信号,不会被误导)。4.3 服务端改造骨架
把现在的
produce()从「一轮」改成「一条链里的若干轮」,每轮只负责产出正文与收尾:要点:
take_next_queued与begin在同一把admission锁内完成,避免「取到队首但另一个请求也取到」。begin时状态从queued改为complete(表示已执行),助手占位仍按现有逻辑插入;如果客户端在这中间撤回,take_next_queued要先校验status == 'queued'。nextTurnId必须在end之前确定(peek_next_queued),否则客户端会先关流再重连,出现可见的断档。finally才chains.pop(project_id),并释放admission。4.4 前端改造
src/canvas/useAssistantChat.ts:send()拆成两条路径:空闲 → 现有follow();sending为真 →POST /messages拿 202,把返回的排队消息与queueSeq落进messages,清空草稿与素材/技能选择(与正常发送一致),并显示一条「已排队」的轻提示。同一个submitting.current仍用于防连击,但不再因为「正在运行」而整段 return。follow()的循环在end处判断:nextTurnId存在则更新turnId.current继续读同一流(不清sending、不重读对话),否则按现在的方式收尾。retractQueued(id)调DELETE;continueQueue()调queue/dispatch。GET /chains/{chainId}/events?after=<最后 seq>;resume()保留现有「读对话 + 附加运行轮」的兜底。src/canvas/AssistantPanel.tsx:title说明「本轮结束后自动发送」;草稿非空即可点,不再依赖canSend。cancelled渲染为带「已取消」标记并提供「重新发送」。当前回复仍在执行,这条消息会在结束后自动发送。src/backend/chat.ts:ChatMessage.status增加queued/cancelled,ChatEvent增加queued类型与seq、nextTurnId、turnId字段;新增queueMessage/retractQueued/dispatchQueue/attachChain四个薄封装。i18n 新增键(中英同时交付,
pnpm check:i18n校验):assistant.panel.queue、assistant.panel.queueHint、assistant.message.queued、assistant.message.cancelled、assistant.queue.retract、assistant.queue.resend、assistant.queue.continue。4.5 停止、失败、重启
queued改为cancelled,end不带nextTurnId。理由:点停止时的心理预期是「都停下」,悄悄继续跑下一轮会让用户失去控制感。需要只停当前轮的人可以用scope=turn,此时链在停止落盘后继续。end收尾、界面给「继续执行排队消息」。自动重试会把一次配置错误放大成三连失败。chains是进程内状态,重启即消失;queued消息留在conversation.json里,GET ''时随对话返回,界面给「继续执行」。这与现在streaming占位被标成interrupted的处理一致,不做自动重放。take_next_queued取走并begin,撤回返回 409(这条消息已开始执行,不能撤回。),避免「界面显示已撤回、实际已经跑了」。4.6 与 #375(停止后编辑重发)的关系
#375 处理的是「停下之后改那条消息再发」;本方案处理「不停下也能补一句」。两者共用同一份消息状态与队列骨架:#375 可以把被停止的消息复位成可编辑,本方案把排队消息做成可撤回/可重发。实现顺序建议本方案先行,因为队列是 #375「重发」的落点。
5. P1:同轮注入(按 runtime 能力开放)
P1 不改变 P0 的排队语义,只是在能力允许时提供「并入本轮」。是否显示由 runtime 声明决定,不由前端猜。
-p增加--input-format stream-json,保持 stdin 打开,按 JSONL 写入{"type":"user","message":{...}}native.py的命令构造与 stdin 写入--plugin-dir、--allowedTools、--permission-mode dontAsk与该模式不冲突;追加消息不会打断正在进行的工具调用codex exec单次;codex app-server的 JSON-RPC 有 thread/turn 概念opencode run单次;opencode serve有 HTTP 会话接口session/prompt单次落地方式:
RuntimeSpec增加supportsSteering: bool = False(packages/core/src/opendirector/agent/runtime.py:18-31),经runtime_catalog()出现在GET /assistant/runtimes;前端据此决定是否显示「并入本轮」。默认全为false,每开一个都要附一份实测记录(命令、版本、会话 id、追加前后的输出片段),记录落在本文「实施记录」或对应 PR 描述里,不写「文档说支持」。注入的实现位置固定在
native.py/deepseek.py的进程会话层:RunContext增加一个可选输入队列,适配器在stream()里并发读取它并写入 harness 的 stdin/HTTP 会话;成功注入时向事件流补一条{"type":"steered","text":...},失败则回退为排队并把原因写进end.error。这样上层(API/前端)不需要知道 harness 差异。6. 需要拍板的清单
下面每项都给了建议,改起来影响面不同,请逐条确认或改判。
自动更符合「插入」的直觉;显式更可控,尤其在长任务上。
允许会带来「后半段用另一个模型」的混淆,收益不明显。
docs/development/(建议,与reference-catalog-preload.md同级)还是合并进docs/architecture/agent-runtime.md的「运行生命周期」一节?建议先独立成文,稳定后把语义结论回填到架构文档。
7. 影响文件
apps/api/src/opendirector_api/agent.py/messages、/queue/dispatch、/chains/{id}/events、stop 的scope;Chain取代active;Conversations增加排队读写与queued/cancelled状态;事件加seq/nextTurnIdpackages/core/src/opendirector/agent/runtime.pyRuntimeSpec.supportsSteering,进入runtime_catalog()packages/core/src/opendirector/agent/native.py--input-format stream-json与 stdin 写入;其余 runtime 的注入入口packages/core/src/opendirector/agent/context.pyRunContext的追加输入队列src/canvas/useAssistantChat.tssrc/canvas/AssistantPanel.tsxsrc/backend/chat.tssrc/i18n/messages/{zh-CN,en-US}/assistant.tsdocs/README.mddocs/development/)tests/test_assistant_queue.py(新增)、tests/test_assistant_conversations.py(扩展)8. 验收与验证
后端(沿用
tests/test_assistant_conversations.py的 fixture 与disconnect_turn手法,把「一轮不结束」变成稳定前提):POST /messages返回 202,对话里出现queued消息,消息数 +1,GET /turns/{当前}仍可续读。start下一轮,end.nextTurnId指向它,队列消息恰好执行一次(消息数、turn 数、agent-runs/目录数三者一致)。queued阶段成功,在已执行阶段 409;撤回后不会再有该轮的运行时调用。scope=chain停止:当前轮stopped,剩余消息cancelled,不再自动起轮;scope=turn:队列继续。queue/dispatch能接着跑。GET /chains/{id}/events?after=N只补发 N 之后的事件,客户端不重复渲染。queued消息仍在,且不会被自动执行。前端:
pnpm test(node --test,覆盖 reducer 的排队/撤回/续读)、pnpm check:i18n、pnpm build(tsc --noEmit);交互按docs/development/validation.md的要求给出实际截图或录屏证据(运行中排队、结束后自动续跑、撤回、停止)。命令示例:
9. 风险与不做的事
end不再是绝对终点。用nextTurnId表达,老客户端忽略该字段即退化为原有行为;seq同样是增量字段。10. 实施顺序(确认后)
Chain、/messages、/queue/dispatch、事件seq/nextTurnId)+ 测试,先不接前端。[feat] agent: take back a queued message and continue a stalled queue
[docs] make the mid-turn page a design record instead of a status page