From a2e95c1d1d7610cce0c2be1974477073994cfbee Mon Sep 17 00:00:00 2001 From: wtz2333 Date: Tue, 17 Nov 2026 19:50:42 +0800 Subject: [PATCH] [docs] record the mid-turn message design MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A supplementary message cannot be sent while a reply runs: the composer swaps send for stop, Enter is a silent no-op, and the API refuses a second turn with 409. Nothing in the chain is missing a button — there is no place for a second message at all. This page records the check that established that (with the probe output), the three delivery semantics weighed (queue and continue, steer inside the turn, interrupt and restart), and the queue design: a message is stored at once with `queued`, runs as its own turn after the active one, and the stream stays open across turns through `nextTurnId` so a viewer keeps receiving without reconnecting. It also says which trade-offs were taken and which are still open, including what P1 would need from each runtime. Behaviour semantics live in the agent runtime page; this is the record of the reasoning behind them. --- docs/README.md | 1 + docs/development/midturn-message.md | 323 ++++++++++++++++++++++++++++ 2 files changed, 324 insertions(+) create mode 100644 docs/development/midturn-message.md diff --git a/docs/README.md b/docs/README.md index cc14c4725..bd592d7d6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,7 @@ This directory is the entry point for the repository's shared documentation. The | [CI layer assessment](development/ci-layer-assessment.md) | Timing evidence, critical PR representatives and staged Python classification | Measured evidence or classification decisions change | | [Issue #87 Windows handoff](development/issue-87-windows-handoff.md) ([中文](development/issue-87-windows-handoff.zh-CN.md)) | Native ACL repair and final text acceptance | The shared checkpoint or native validation scope changes | | [Development lessons](development/lessons.md) | Risks identified from recent fixes | New evidence emerges or a lesson no longer applies | +| [Mid-turn messages](development/midturn-message.md) | Design record: why a supplementary message was refused during a turn, the alternatives weighed, and the queued-delivery rules now in place | A design trade-off changes; behaviour semantics live in the agent runtime page | | [CI failure patterns](development/ci-failures.md) | Known timing-sensitive CI failures and how to tell flakes from regressions | A pattern is fixed, newly observed, or the watchlist changes | | [Release tags and daily cuts](development/release.md) | Public SemVer tags and the daily patch cut | The tag scheme, daily cut gate, or version-field set changes | | [UI performance design](development/ui-performance.md) | Interaction design principles, latency budgets, and measurement | A UI performance principle, target, or measurement method changes | diff --git a/docs/development/midturn-message.md b/docs/development/midturn-message.md new file mode 100644 index 000000000..a513d129d --- /dev/null +++ b/docs/development/midturn-message.md @@ -0,0 +1,323 @@ +# 运行中插入补充消息:设计记录 + +状态:设计记录。P0 已按本文落地,排队、撤回、手动继续的行为见第 6.1 节;进度与待办以 issue #379 为准,P1 仍待实测(第 5 节) +记录时间:2026-11-17(实现前检查用当时的工作分支 `fix/agent-wait-progress-131` @ `9d08bf5a`,实现基于 `origin/main` @ `729b49bc`) +范围:`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. 实现前的现状检查 + +下面这一段是动手之前的事实,保留下来是因为它解释了为什么会这样设计;当前的接口语义见 [agent runtime](../architecture/agent-runtime.md) 的「运行生命周期」一节。 + +复现方式:用当时的 `disconnect_turn` 把一轮回复保持在运行状态(SSE 断开后 run 继续跑),运行期间再提交一次。基线 `9d08bf5a`,实测输出: + +```text +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`: + +```ts +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`: + +```python +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」升级为「一条链」: + +```python +@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 接口 + +新增一个入口,语义是「发一条消息,能跑就跑,跑不了就排」: + +```text +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 与原因) +``` + +配套: + +```text +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= # 断线重连,从游标续读 +``` + +`POST /turns` 保留原样(运行中仍 409),老客户端行为不变;新客户端走 `/messages`。等 P0 稳定后再讨论是否让 `/turns` 内部转调。 + +事件流加两个字段,并允许一轮结束后接着下一轮: + +```text +{"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()` 从「一轮」改成「一条链里的若干轮」,每轮只负责产出正文与收尾: + +```python +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. 取舍清单 + +下面每项都给了建议。6.1 记录已按建议值落地的部分;其余项仍需要确认后再改。 + +### 6.1 已按建议默认值实现的部分 + +第 1、2、3、5 项在实现里用了建议值,改判时需要一起改后端: + +- 第 1 项:本轮结束后自动开始下一条排队消息,不额外点按钮;只有队列「停着」(重启、上一轮失败)时才出现「继续执行」提示。 +- 第 2 项:一条消息一轮,回复与消息一一对应,链上每轮一个 `end` 帧。 +- 第 3 项:停止默认停整条链,排队消息标为 `cancelled` 并保留可读。 +- 第 5 项:失败不自动重试,队列保留在 `queued`,由用户点「继续执行」开始。 + +第 4 项(运行中改模型)与第 6 项(P1 范围)仍按建议值保持未做:运行中 runtime/模型选择器依旧禁用,P1 需要先在有 CLI 的机器上实测。 + +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_retract.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` 的要求给出实际截图或录屏证据(运行中排队、结束后自动续跑、撤回、停止)。 + +命令示例: + +```bash +.venv/bin/python -m pytest tests/test_assistant_queue.py tests/test_assistant_retract.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。