Skip to content

Commit 44c19bf

Browse files
committed
[docs] make the mid-turn page a design record instead of a status page
The page was written before the work started, so its background and current state read in the present tense and its status line listed the pull requests that carry the change. Both go stale the moment the change lands, and the enduring behaviour already lives in the agent runtime page. It now says when it was recorded and which revision the check ran against, keeps its findings in the past tense, and leaves progress to issue #379. The index row says what to update it for: a trade-off, not a semantic change.
1 parent f2a5ef8 commit 44c19bf

2 files changed

Lines changed: 16 additions & 13 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ This directory is the entry point for the repository's shared documentation. The
1616
| [CI layer assessment](development/ci-layer-assessment.md) | Timing evidence, critical PR representatives and staged Python classification | Measured evidence or classification decisions change |
1717
| [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 |
1818
| [Development lessons](development/lessons.md) | Risks identified from recent fixes | New evidence emerges or a lesson no longer applies |
19-
| [Mid-turn messages](development/midturn-message.md) | Why a supplementary message cannot be sent while a turn runs, and the design for queued delivery | Queue, steering or stop semantics change |
19+
| [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 |
2020
| [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 |
2121
| [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 |
2222
| [UI performance design](development/ui-performance.md) | Interaction design principles, latency budgets, and measurement | A UI performance principle, target, or measurement method changes |

‎docs/development/midturn-message.md‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
1-
# 运行中插入补充消息:现状检查与方案
1+
# 运行中插入补充消息:设计记录
22

3-
状态:P0 已按本文实现(后端 #381、撤回与手动继续 #384、前端 #383、#385);第 6 节里已按建议默认值落地的项见 6.1,P1 仍待实测(第 5 节)
3+
状态:设计记录。P0 已按本文落地,排队、撤回、手动继续的行为见第 6.1 节;进度与待办以 issue #379 为准,P1 仍待实测(第 5 节)
4+
记录时间:2026-11-17(实现前检查用当时的工作分支 `fix/agent-wait-progress-131` @ `9d08bf5a`,实现基于 `origin/main` @ `729b49bc`)
45
范围:`src/canvas/`、`src/backend/chat.ts`、`src/i18n/messages/*/assistant.ts`、`apps/api/src/opendirector_api/agent.py`、`packages/core/src/opendirector/agent/`
56
关联:issue #379;路线图 #261;停止后编辑重发 #375;会话管理 #247
67

78
## 1. 背景
89

9-
现在的对话是一问一答:发送之后,输入框的发送按钮被换成停止按钮,必须等这一轮回完才能再说话。用户真正的需要是「做这件事的时候,再补一句」——想起漏掉的约束、追加一个素材、纠正方向。等 3 分钟再说,产出的东西已经错了;点停止再说,这一轮的工作全丢。
10+
实现之前,对话是一问一答:发送之后,输入框的发送按钮被换成停止按钮,必须等这一轮回完才能再说话。用户真正的需要是「做这件事的时候,再补一句」——想起漏掉的约束、追加一个素材、纠正方向。等 3 分钟再说,产出的东西已经错了;点停止再说,这一轮的工作全丢。
1011

1112
Codex、DSH 这类 harness 的交互是可以中途插话的,所以这个差距是明显的体验落差,不是偏好问题。
1213

@@ -16,9 +17,11 @@ Codex、DSH 这类 harness 的交互是可以中途插话的,所以这个差
1617
2. 如果要补,语义应该是什么(排队续跑 / 同轮注入 / 打断重开,三者代价不同);
1718
3. 具体怎么改,哪些必须先实测再承诺。
1819

19-
## 2. 现状检查
20+
## 2. 实现前的现状检查
2021

21-
复现方式:用现有的 `disconnect_turn` 把一轮回复保持在运行状态(SSE 断开后 run 继续跑),运行期间再提交一次。基线 `9d08bf5a`,实测输出:
22+
下面这一段是动手之前的事实,保留下来是因为它解释了为什么会这样设计;当前的接口语义见 [agent runtime](../architecture/agent-runtime.md) 的「运行生命周期」一节。
23+
24+
复现方式:用当时的 `disconnect_turn` 把一轮回复保持在运行状态(SSE 断开后 run 继续跑),运行期间再提交一次。基线 `9d08bf5a`,实测输出:
2225

2326
```text
2427
PROBE second turn -> 409 {'detail': '当前工程已有回复正在执行。', 'code': 'operation_rejected'}
@@ -242,18 +245,18 @@ P1 不改变 P0 的排队语义,只是在能力允许时提供「并入本轮
242245

243246
注入的实现位置固定在 `native.py`/`deepseek.py` 的进程会话层:`RunContext` 增加一个可选输入队列,适配器在 `stream()` 里并发读取它并写入 harness 的 stdin/HTTP 会话;成功注入时向事件流补一条 `{"type":"steered","text":...}`,失败则回退为排队并把原因写进 `end.error`。这样上层(API/前端)不需要知道 harness 差异。
244247

245-
## 6. 需要拍板的清单
248+
## 6. 取舍清单
246249

247-
下面每项都给了建议,改起来影响面不同,请逐条确认或改判。
250+
下面每项都给了建议。6.1 记录已按建议值落地的部分;其余项仍需要确认后再改。
248251

249252
### 6.1 已按建议默认值实现的部分
250253

251254
第 1、2、3、5 项在实现里用了建议值,改判时需要一起改后端:
252255

253-
- 第 1 项:本轮结束后自动开始下一条排队消息,不额外点按钮;只有队列「停着」(重启、上一轮失败)时才出现「继续执行」提示(#381、#385)。
254-
- 第 2 项:一条消息一轮,回复与消息一一对应,链上每轮一个 `end` 帧(#381)。
255-
- 第 3 项:停止默认停整条链,排队消息标为 `cancelled` 并保留可读(#381)。
256-
- 第 5 项:失败不自动重试,队列保留在 `queued`,由用户点「继续执行」开始(#384、#385)。
256+
- 第 1 项:本轮结束后自动开始下一条排队消息,不额外点按钮;只有队列「停着」(重启、上一轮失败)时才出现「继续执行」提示。
257+
- 第 2 项:一条消息一轮,回复与消息一一对应,链上每轮一个 `end` 帧。
258+
- 第 3 项:停止默认停整条链,排队消息标为 `cancelled` 并保留可读。
259+
- 第 5 项:失败不自动重试,队列保留在 `queued`,由用户点「继续执行」开始。
257260

258261
第 4 项(运行中改模型)与第 6 项(P1 范围)仍按建议值保持未做:运行中 runtime/模型选择器依旧禁用,P1 需要先在有 CLI 的机器上实测。
259262

@@ -312,7 +315,7 @@ pnpm test && pnpm check:i18n && pnpm build
312315
- **事件契约变化**:`end` 不再是绝对终点。用 `nextTurnId` 表达,老客户端忽略该字段即退化为原有行为;`seq` 同样是增量字段。
313316
- **不做的事**:不并发跑两轮;不做多项目并行;不改写 harness 为双工协议;不支持编辑正在执行的 prompt;不在 P0 阶段自动重放重启前的队列。
314317

315-
## 10. 实施顺序(确认后)
318+
## 10. 实施顺序
316319

317320
1. 后端链与队列(`Chain`、`/messages`、`/queue/dispatch`、事件 `seq`/`nextTurnId`)+ 测试,先不接前端。
318321
2. 前端运行中提交与排队气泡、自动续读、撤回;补齐双语。

0 commit comments

Comments
 (0)