Skip to content

[feat] assistant: accept a follow-up message while a turn is still running / 运行中插入补充消息 #379

Open

Description

@wtz2333

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 queued state, 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 queued marker, 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 cancelled state 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 the queued/cancelled message states; replace the single-turn active entry with a chain entry that owns RunEvents; add POST /assistant/messages (submit-or-queue), DELETE for a queued message, a chain-scoped event stream with a replay cursor, and explicit stop scope.
  • Events: add seq per chain, message events for queue changes, and nextTurnId on end so a client knows the stream continues instead of treating end as final. Keep the existing end shape 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.ts and src/i18n/messages/en-US/assistant.ts (bilingual, delivered together).
  • Runtime layer: add a declared capability to RuntimeSpec in packages/core/src/opendirector/agent/runtime.py (e.g. supportsSteering: bool = False) and surface it through runtime_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

  1. Default queue semantics when a turn ends: auto-continue (proposed) versus a visible "continue" prompt.
  2. Multiple queued messages: one turn per message (proposed) versus coalescing consecutive submissions into the next turn.
  3. Stop scope: chain-wide with cancelled queue entries (proposed) versus turn-only where the queue continues.
  4. 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

  1. wtz2333 commented on Nov 17, 2026

    @wtz2333
    Author

    方案(待确认)

    完整方案按仓库提案格式写在 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 的交互是可以中途插话的,所以这个差距是明显的体验落差,不是偏好问题。

    本文回答三件事:

    1. 现在为什么插不进去——是少了一个按钮,还是协议层就没有位置;
    2. 如果要补,语义应该是什么(排队续跑 / 同轮注入 / 打断重开,三者代价不同);
    3. 具体怎么改,哪些必须先实测再承诺。

    2. 现状检查

    复现方式:用现有的 disconnect_turn 把一轮回复保持在运行状态(SSE 断开后 run 继续跑),运行期间再提交一次。基线 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 -> []
    

    读法:第二次提交被拒;草稿能存(正文没丢);对话消息数没变(补充内容没有进入对话);消息状态只有 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:

    if (!loaded || switching.current || submitting.current || uploading.current || !canSend || !current.current.draft.trim()) return;

    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:

    async with admission.setdefault(project_id, asyncio.Lock()):
        if project_id in active:
            raise ProjectError('当前工程已有回复正在执行。', 409)
        ...
        task = asyncio.create_task(produce())
        active[project_id] = (value.id, task, events)

    运行中的 active[project_id] 是 $(turnId, task, RunEvents)$。同一状态下 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/ 下所有适配器都是一次性启动:

    Runtime 启动方式 运行中能再送话吗
    Default / OpenCode opencode run --dir … --pure --format json --agent opendirector 不能,run 是单次任务
    Codex codex exec --json --skip-git-repo-check … --sandbox workspace-write 不能,exec 是单次任务
    Claude Code claude -p … --output-format stream-json …(native.py:120-135) 当前不能:没有 --input-format stream-json,stdin 不是消息通道
    JiuwenSwarm 自定义 JSONL 进程,stdin/stdout 待实测:stdin 常开,但协议是否接受运行中的追加帧未知
    DeepSeek Harness ACP JSON-RPC,session/prompt 一次,取消用 session/cancel 不能,ACP 这一版没有 steer 方法

    结论:任何「真·同轮注入」都要落到具体 harness 的原生能力上,逐个实测,不能靠应用层「重发一遍」假装做到了。这决定了方案必须分层。

    3. 三种可选语义

    语义 用户看到什么 代价 能覆盖的 runtime
    A. 排队续跑 消息立刻出现在对话里,标「本轮结束后执行」,当前轮结束后自动接着跑 应用层就能做;补充内容不进入正在跑的上下文,用户要知道「这句下一轮才生效」 全部
    B. 同轮注入(steering) 补充内容进入正在跑的循环,当前回复后半段就体现出来 需要各 harness 原生输入通道 + 输入合并语义;失败面大 逐个实测
    C. 打断重开 取消当前轮,把「原消息+补充」合成一条新的从头跑 已产出的内容和工作作废,最贵 全部,但不建议

    建议: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」升级为「一条链」:

    @dataclass
    class Chain:
        id: UUID                  # 首轮 turn id
        conversation_id: UUID
        events: RunEvents         # 整条链共用,事件带 seq
        turn: UUID | None         # 当前在跑的 turn
        task: asyncio.Task | None
        seq: int = 0

    chains: dict[UUID, Chain] 取代 active: dict[UUID, tuple[...]],release 从「任务结束就 pop」改为「链结束才 pop」。这一步是必需的:现在任务一结束就 active.pop,如果自动续跑放在 finally 里,中间会有一个窗口让新的 POST /turns 插进来,变成并发两轮。

    4.2 接口

    新增一个入口,语义是「发一条消息,能跑就跑,跑不了就排」:

    POST /api/creation/projects/{project_id}/assistant/messages
    body: 与 /turns 相同(Turn),另加 deliver?: 'auto' | 'queue' | 'steer',默认 auto
    
    无运行轮 → 200 text/event-stream(与 /turns 完全一致,客户端可用同一套处理)
    有运行轮 → 202 {"queued": {"id", "text", "queueSeq", "position"}, "chainId": "...", "turnId": "..."}
            (deliver=steer 且该 runtime 不支持 → 202 回退为排队,并带 "steered": false 与原因)
    

    配套:

    DELETE /assistant/messages/{message_id}      # 仅 queued 可撤回,已开始执行返回 409
    POST   /assistant/queue/dispatch             # 失败/重启后由用户显式继续队列
    POST   /assistant/turns/{turn_id}/stop?scope=chain|turn   # 默认 chain
    GET    /assistant/chains/{chain_id}/events?after=<seq>    # 断线重连,从游标续读
    

    POST /turns 保留原样(运行中仍 409),老客户端行为不变;新客户端走 /messages。等 P0 稳定后再讨论是否让 /turns 内部转调。

    事件流加两个字段,并允许一轮结束后接着下一轮:

    {"type":"start","seq":1,"turnId":"A","conversation":{...}}
    {"type":"delta","seq":2,"text":"..."}
    {"type":"queued","seq":9,"message":{...},"position":1}      # 新增:排队变化(加入/撤回)
    {"type":"end","seq":20,"turnId":"A","nextTurnId":"B","conversation":{...},"error":null}
    {"type":"start","seq":21,"turnId":"B","conversation":{...}}  # 同一 HTTP 流继续
    

    规则很简单:end 带 nextTurnId 表示链未结束,客户端不要关流;没有 nextTurnId 才是终点。seq 让重连可幂等去重(老客户端忽略未知字段,end 仍是终止信号,不会被误导)。

    4.3 服务端改造骨架

    把现在的 produce() 从「一轮」改成「一条链里的若干轮」,每轮只负责产出正文与收尾:

    async def produce_one(chain, message) -> tuple[str, dict | None]:
        """跑一轮:begin → stream → finish。返回 (status, error)。"""
        saved = await asyncio.to_thread(conversations.update, project_id, session,
                                       begin={**message, 'status': 'complete'},
                                       conversation_id=chain.conversation_id)
        chain.events.put({'type': 'start', 'turnId': str(message['id']), 'conversation': saved})
        ...  # 与现有 produce() 的上下文构造、runtimes.stream、finish 落盘一致
        return status, error
    
    async def run_chain(chain):
        while True:
            message = await asyncio.to_thread(take_next_queued, project_id, chain.conversation_id)
            if message is None:
                chain.events.put({'type': 'end', 'nextTurnId': None, 'conversation': last, 'error': last_error})
                return
            status, error = await produce_one(chain, message)
            nxt = await asyncio.to_thread(peek_next_queued, project_id, chain.conversation_id)
            if status == 'complete' and nxt is not None:
                chain.events.put({'type': 'end', 'turnId': ..., 'nextTurnId': str(nxt['id']), 'conversation': ..., 'error': None})
                continue                      # 同一条流继续,不释放 chain
            if status != 'complete' and nxt is not None:
                # 出错不自动续跑:留队,等用户点「继续」
                chain.events.put({'type': 'end', 'nextTurnId': None, 'conversation': ..., 'error': error})
                return
            chain.events.put({'type': 'end', 'nextTurnId': None, 'conversation': ..., 'error': error})
            return

    要点:

    • 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。
    • 排队消息在对话中渲染为带「等待执行 · 第 N 位」标记的用户气泡,右侧给「撤回」;cancelled 渲染为带「已取消」标记并提供「重新发送」。
    • 输入框下方一行状态提示(运行中才出现):当前回复仍在执行,这条消息会在结束后自动发送。
    • 选择器保持运行中禁用(P0 不改),排队消息的 runtime/模型在排入时快照。

    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 的处理一致,不做自动重放。
    • 撤回 vs 已执行:一旦 take_next_queued 取走并 begin,撤回返回 409(这条消息已开始执行,不能撤回。),避免「界面显示已撤回、实际已经跑了」。

    4.6 与 #375(停止后编辑重发)的关系

    #375 处理的是「停下之后改那条消息再发」;本方案处理「不停下也能补一句」。两者共用同一份消息状态与队列骨架:#375 可以把被停止的消息复位成可编辑,本方案把排队消息做成可撤回/可重发。实现顺序建议本方案先行,因为队列是 #375「重发」的落点。

    5. P1:同轮注入(按 runtime 能力开放)

    P1 不改变 P0 的排队语义,只是在能力允许时提供「并入本轮」。是否显示由 runtime 声明决定,不由前端猜。

    Runtime 候选通道 现状判断 必须先证明的事
    Claude Code -p 增加 --input-format stream-json,保持 stdin 打开,按 JSONL 写入 {"type":"user","message":{...}} 最有可能,改动局限在 native.py 的命令构造与 stdin 写入 当前 claude 版本在该模式下仍是多轮输入;--plugin-dir、--allowedTools、--permission-mode dontAsk 与该模式不冲突;追加消息不会打断正在进行的工具调用
    JiuwenSwarm 已有的 JSONL stdin 常开 取决于它的进程协议是否接受运行中的用户帧 读协议或实测;不接受就保持排队
    Codex codex exec 单次;codex app-server 的 JSON-RPC 有 thread/turn 概念 需要换执行方式,风险高 app-server 是否有「运行中追加」的公开方法;换启动方式对现有权限沙箱与事件映射的影响
    Default / OpenCode opencode run 单次;opencode serve 有 HTTP 会话接口 需要换执行方式,且 bundled 版本被固定 该版本是否有「运行中投递」接口;升级 bundled OpenCode 的成本
    DeepSeek Harness ACP session/prompt 单次 当前无 steer 方法 是否可经 ACP 扩展或上游支持;在此之前明确标为仅排队

    落地方式: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. 需要拍板的清单

    下面每项都给了建议,改起来影响面不同,请逐条确认或改判。

    1. 默认行为:本轮结束后自动开始排队消息(建议)还是留一个「继续」按钮由用户点?
      自动更符合「插入」的直觉;显式更可控,尤其在长任务上。
    2. 多条排队:一条消息一轮(建议,回复与消息一一对应)还是连续多条合并成一轮(更省 token,但回复归属变模糊)?
    3. 停止范围:默认整条链停、排队消息标为已取消(建议)还是默认只停当前轮、队列继续?
    4. 是否允许运行中改 runtime/模型:P0 保持禁用(建议)还是允许排队消息另选模型?
      允许会带来「后半段用另一个模型」的混淆,收益不明显。
    5. 失败后:保留队列等用户点继续(建议)还是自动重试一次?
    6. P1 范围:先只做 Claude Code 一条通道验证可行性(建议),通过后再评估 Codex/OpenCode 是否值得换执行方式。
    7. 文档落点:本文留在 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/nextTurnId
    packages/core/src/opendirector/agent/runtime.py RuntimeSpec.supportsSteering,进入 runtime_catalog()
    packages/core/src/opendirector/agent/native.py P1:Claude 的 --input-format stream-json 与 stdin 写入;其余 runtime 的注入入口
    packages/core/src/opendirector/agent/context.py P1:RunContext 的追加输入队列
    src/canvas/useAssistantChat.ts 运行中提交、排队状态、链内续读、撤回/继续
    src/canvas/AssistantPanel.tsx 运行中保留发送、排队气泡、状态提示
    src/backend/chat.ts 新事件与状态、四个请求封装
    src/i18n/messages/{zh-CN,en-US}/assistant.ts 新增 7 个键,中英同交付
    docs/README.md 登记本文(若保留在 docs/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/ 目录数三者一致)。
    • 同一 message id 重复提交只产生一条排队记录与一轮执行。
    • 撤回在 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 的要求给出实际截图或录屏证据(运行中排队、结束后自动续跑、撤回、停止)。

    命令示例:

    .venv/bin/python -m pytest tests/test_assistant_queue.py tests/test_assistant_conversations.py -q
    pnpm test && pnpm check:i18n && pnpm build

    9. 风险与不做的事

    • 长任务上排队会积压:一轮可能跑很久,排队消息等的时间比用户预期长。缓解:气泡上显示当前轮仍在执行、允许随时撤回;不承诺「马上生效」。
    • 自动续跑放大错误:如果上一轮已经跑偏,下一轮会带着跑偏的结果继续。缓解:失败不自动续跑;运行中提示明确「下一轮才生效」,用户可在结束时撤回。
    • 事件契约变化:end 不再是绝对终点。用 nextTurnId 表达,老客户端忽略该字段即退化为原有行为;seq 同样是增量字段。
    • 不做的事:不并发跑两轮;不做多项目并行;不改写 harness 为双工协议;不支持编辑正在执行的 prompt;不在 P0 阶段自动重放重启前的队列。

    10. 实施顺序(确认后)

    1. 后端链与队列(Chain、/messages、/queue/dispatch、事件 seq/nextTurnId)+ 测试,先不接前端。
    2. 前端运行中提交与排队气泡、自动续读、撤回;补齐双语。
    3. 停止/失败/重启三种异常的端到端验证与证据。
    4. (P1)Claude Code 单通道注入实测,写实施记录;按结论决定是否继续其他 runtime。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:agentAgent runtime, assistant chat and tools

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions