文档：接单化落地收尾，ADR 转已接受并同步下游口径
docs/adr/【ADR】DirectProject命令接单化-2026-09-23.md：状态改成已接受并指向实施计划；"落地时要同步的文档与注释"改成已同步清单。 docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md：顶部取代注扩到"事件不带回合身份"与"宿主侧 Drop 守卫兜底"两条决策形状，影响一节的两条已知边界逐条写明新口径。 docs/technical/【实施计划】DirectProject命令接单化-2026-09-23.md：四步标记落地并补每步落地结果、验收证据（rust agent:: 949 / 前端 4473）与已知坑。 docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md：正常回合改成接单后先落盘再注入；异常回合收尾写明唯一终态出口是占用对象。 docs/project-memory/shared-memory/decision-log.md：host-dropped 两条口径加取代注（含 kind 追加 environment-not-ready），并追加 2026-09-23 接单化决策一条。 docs/README.md：索引行去掉"未实施"，改成四步均已落地。
This commit is contained in:
@@ -1,9 +1,7 @@
|
||||
# 【ADR】DirectProject命令接单化
|
||||
|
||||
状态：提议（草案，设计已定稿、未实施）
|
||||
|
||||
> 本文与 `docs/README.md` 里对应的一行索引先随文档提交进仓库；状态保持「提议（草案，未实施）」，
|
||||
> 实施提交落地后改为「已接受」。
|
||||
状态：已接受（2026-09-23 落地，实施顺序与验收见
|
||||
[`【实施计划】DirectProject命令接单化-2026-09-23`](../technical/【实施计划】DirectProject命令接单化-2026-09-23.md)）
|
||||
|
||||
## 背景
|
||||
|
||||
@@ -124,13 +122,16 @@
|
||||
- 不恢复 invoke 拒绝通道，也不为"接单后的前置失败"新增事件类型——它们走同一对逻辑回合事件。
|
||||
- 本轮不做"失败条目进历史但不喂模型"（TODO），不做 Rust 端发送队列（TODO）。
|
||||
|
||||
## 落地时要同步的文档与注释
|
||||
## 落地时要同步的文档与注释（已同步 2026-09-23）
|
||||
|
||||
- `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md`：事件带 `userItemId` 的事实、
|
||||
失败原因的通道、"`turn.started` 之前的早退不产生终态事件"（作废）、失败说明是否落历史。
|
||||
- `docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md`：影响里的两条已知边界被本 ADR 取代。
|
||||
- `docs/project-memory/shared-memory/decision-log.md`：`host-dropped` 的两条口径。
|
||||
- `docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md`：影响里的两条已知边界与"事件不带回合身份"
|
||||
"宿主侧 Drop 守卫兜底"两条决策形状被本 ADR 取代。
|
||||
- `docs/technical/【实施计划】DirectProject命令接单化-2026-09-23.md`：四步标记落地，补验收证据与已知坑。
|
||||
- `docs/project-memory/shared-memory/decision-log.md`：`host-dropped` 的两条口径加取代注，并追加一条
|
||||
2026-09-23 的接单化决策。
|
||||
- `docs/README.md`：索引行去掉"未实施"。
|
||||
- 代码注释：`direct_runtime/user_input.rs` 的 `TODO(Direct 命令接单化)`、
|
||||
`chat/controller/useDirectProjectChatController.ts` 的 catch TODO、
|
||||
- 代码注释：`direct_runtime/user_input.rs` 的 `TODO`（分工改成 CLI 保持 await）、
|
||||
`chat/controller/useDirectProjectChatController.ts` 的 catch TODO（队列挪 Rust）、
|
||||
`direct_thread_wire.rs` 里 `userItemId`"由原生从已落盘条目上读取"的说明。
|
||||
|
||||
@@ -2,9 +2,11 @@
|
||||
|
||||
状态：已接受
|
||||
|
||||
> 注：本文件「影响」一节里的两条已知边界（① `kill -9` 后前端停在运行态；② `turn.started` 之前的早退
|
||||
> 不产生终态事件）已由 [`【ADR】DirectProject命令接单化-2026-09-23`](./【ADR】DirectProject命令接单化-2026-09-23.md)
|
||||
> 重新决策（草案，未实施）；实施后这两条按新 ADR 收口，本文件不再作为它们的依据。
|
||||
> 注：本文件下列口径已被 [`【ADR】DirectProject命令接单化-2026-09-23`](./【ADR】DirectProject命令接单化-2026-09-23.md)
|
||||
> 重新决策并已落地，本文件不再作为它们的依据：「影响」一节里的两条已知边界（① `kill -9` 后前端停在运行态
|
||||
> ——队列随进程消失，订阅 bootstrap 不会留下"有开始没结束"；② `turn.started` 之前的早退不产生终态事件
|
||||
> ——"早退"被拆成接单前的拒单，接单后由占用对象统一收口），以及「决策」里"事件不带回合身份"与
|
||||
> "宿主侧 Drop 守卫兜底"两条的实现形状（见下）。
|
||||
|
||||
## 背景
|
||||
|
||||
@@ -24,12 +26,12 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
|
||||
- 两侧的过滤口径必须完全一致，包含「哪些条目根本不是本项目的聊天条目」：Codex app-server 回显的用户消息（`userMessage` / 非 AGC 的 `role=user`）在落盘侧被过滤，在运行态事件侧也必须被过滤（`direct_thread_visible_item`）。少一侧就会出现「实时比历史多出两条同文本用户条目、各自开出一个耗时 0 秒的假回合，重进页面又正常」这类只有其中一侧的事实源缺陷。
|
||||
- 搬运层不生成展示形状：Thread Manager 只下发脱敏原始条目（`itemType` 原样透传），工具卡片的 `kind`、标题、折叠摘要都由前端生成。
|
||||
- 条目身份只有一套：进队列前归一成一个 `itemId`。工具条目在 `project.jsonl` 里带两个 id（调用 id 与 response item id，调用与输出共用前者），归一只在 Rust 边界做一次，Thread Manager 与前端都不暴露第二个 id 概念。
|
||||
- 事件不带回合身份：DirectProject 同一时刻只有一个回合在跑，`turn.started` 无载荷、`turn.completed` 只带 `status`；前端 state 里只有一个 `turnRunning` 布尔，没有 `turnId`。`subscribe` 返回的条目、增量、请求与队列锚点都不带 turn id。
|
||||
- 事件不带回合身份：DirectProject 同一时刻只有一个回合在跑，`turn.started` 无载荷、`turn.completed` 只带 `status`；前端 state 里只有一个 `turnRunning` 布尔，没有 `turnId`。`subscribe` 返回的条目、增量、请求与队列锚点都不带 turn id。（**按 2026-09-23 ADR §5 补充**：`turn.started` / `turn.completed` 现在带 `userItemId`，由 `clientTurnId` 推导、不读盘回填；事件仍不带 turn id，判据仍是"只有一对逻辑回合事件"。）
|
||||
- 合并只在前端，规则只保留「先到定形、后到补空白」：第一次见到的快照决定卡片形状，后续快照只补输出与状态，不做逐字段优先级表。只有"后到信息一定更全"时才例外：正文取更长的一份、工具状态允许从 `running` 升级到终态、`updatedAt` 取较新的时间。
|
||||
- 前端不保留增量缓冲：`item.delta` 直接追加到运行态条目的正文（正文只增不减）。`turn.completed` 把当前回合的运行态条目并入历史再清空，条目既不消失也不重复。
|
||||
- 活动回合的唯一判据是「出现过 `turn.started` 且未出现 `turn.completed`」；进程重启后队列消失，历史里的半截回合一律按已结束渲染。
|
||||
- 终态事件只有 `turn.completed` 一种，它同时承载三种语义：`status !== "failed"` 是正常结束 / 中断 / 终止，`status === "failed"` 是**失败**，且必须再带 `failure { kind, message }`（`message` 已脱敏截断）。失败原因只走这一条通道：前端不再从命令返回或另一条 IPC 里另造失败文案，聊天里那条失败说明仍落在同一个展示位上（本轮最后一条助手气泡、只在运行期显示），只是数据来源换成事件载荷；命令返回只用于运行错误横幅与诊断留痕。
|
||||
- 宿主侧兜底：`turn.started` 发出之后才武装 Drop 守卫，正常写完终态即解除；panic、future 被丢弃、终态之前的早退由守卫补一条 `status="failed"` + `failure.kind="host-dropped"` 的终态，避免前端永远停在"还在跑"。已知边界见「影响」一节。
|
||||
- 宿主侧兜底：`turn.started` 发出之后才武装 Drop 守卫，正常写完终态即解除；panic、future 被丢弃、终态之前的早退由守卫补一条 `status="failed"` + `failure.kind="host-dropped"` 的终态，避免前端永远停在"还在跑"。已知边界见「影响」一节。（**按 2026-09-23 ADR §2 改写**：守卫换成"接单即登记"的占用对象，终态写出后占用才释放。）
|
||||
- 执行通道断开同样是失败终态，也必须带 `failure`：连接级故障（app-server 进程退出 / stdout 流断 / JSON 行越界）与回合事件通道关闭都算，`kind="transport-failed"`、`message` 用宿主当场写下的那份诊断（含 `exitStatus` 与 stderr 摘要，已脱敏截断）。宿主在检测到连接终止的第一时间把这条事实记到本回合的执行适配器上，终态判定再从适配器读：执行适配器的看门狗盯着同一个 `closed` 标志，用调用点局部变量会输给这场调度竞争，失败原因就只剩日志、界面只会看到"本轮已结束"。判据是"适配器是否已由宿主主动关闭"——宿主自己收束（正常终态 / 用户主动停止 / 预算与交付收尾）走的是同一个 `TransportClosed` 事件，但这些不算失败。
|
||||
- 终态由**事实**判定，不由收尾阶段反推：判定按优先级取「宿主当场记下的失败（通道断开 / 等待超时 / app-server 单方面中断）→ 本回合的错误结果是 Err → 只有收尾阶段的账本读不出来时才用交付报告」，**有载荷一定写 `status="failed"`**，没载荷才用收尾阶段推出来的 `status`。收尾会把 ledger 阶段推成 `Interrupted`，让阶段决定终态就会把已经失败的一轮讲成"已结束"。模型自报失败（原生 `turn/completed.status="failed"` 的 `error`，带 `codexErrorInfo` 分类）不为载荷新增输入字段：宿主把原生 `error` 的 `codexErrorInfo` 解析成 typed 分类后当作本回合的错误结果，走同一条通道进载荷；交付报告只说明"收束到哪一步"，不得顶掉原因。
|
||||
- 回合失败在宿主内部是 **typed** 的：`agent/direct_turn_error.rs` 的 `DirectTurnError` 每个变体自带字段（并发拒绝带两个 invocation id、模型失败带分类、超时带撞的是哪条上限、通道断开带宿主诊断），**调用级拒绝**（这一轮没有开始）与**回合级失败**（这一轮已开始并被判失败）不共用判据，分流只认 `is_turn_failure()`。判据不再对原因文本做子串匹配，`LlmError` 只在平台层入口出现一次（`DirectTurnError::from_model_call`）。线上载荷 `{kind, message}`、命令边界字符串与 CLI 返回值都由这一个出口投影出来，Rust 侧任何地方都不再解析它们。
|
||||
@@ -60,7 +62,7 @@ AGC 项目开发聊天框当前同时从三处取数据：Direct 回合事件（
|
||||
- 旧项目磁盘上遗留的 `turn-stream.jsonl` / `tool-calls.jsonl` 保留不动，不迁移、不清理、不再由 DirectProject 聊天框读取。
|
||||
- 工具卡片的脱敏与截断必须在读取期执行一次，不能因为"原始条目已在磁盘"就把未脱敏内容直接渲染到界面。
|
||||
- 回合结束语义务必由 `turn.completed` 判定（失败时同一事件带 `failure` 载荷，不新增事件类型）；缺少该事件的残留回合不得被渲染成运行中。
|
||||
- 两条已知边界，都**不**在本次补路径：① 宿主进程被强杀（`kill -9`）时没有任何 `Drop` 会执行，前端仍会停在运行态，那要靠前端自己的"命令已返回却没有任何终态事件"判据；② `turn.started` 之前的早退（`turn/start` 请求失败、响应缺 `turn.id`、历史注入参数构建失败等）不产生回合、也不补终态事件——它们不会留下永远开着的回合，出问题时只有运行错误横幅解释。
|
||||
- 两条已知边界，都**不**在本次补路径，且已被 [`【ADR】DirectProject命令接单化-2026-09-23`](./【ADR】DirectProject命令接单化-2026-09-23.md) 取代（§3、§2）：① 宿主进程被强杀（`kill -9`）时没有任何 `Drop` 会执行，但队列随进程消失，新进程的订阅 bootstrap 因此不会看到"有开始没结束"，界面不会卡在忙碌态；② `turn.started` 之前的失败按发生位置分流——接单**之前**的是拒单，根本不产生回合（不写用户条目、不写失败诊断），接单**之后**的由这一轮的占用对象统一收口成 `turn.completed`，不存在"有回合却没有事件解释"的路径。
|
||||
- 失败原因里的 `message` 是宿主侧脱敏 + 截断后的可展示文本，前端仍按既有口径做一次可见文案映射（`projectRuntimeVisibleError`），映射规则不因这次改动改变。
|
||||
- 执行通道断开时用户看到的仍是既有映射结果（诊断命中不了专门规则，落到通用兜底），真实诊断在事件载荷、宿主交付报告与运行日志里；把"连接断开"改成专门文案属于映射规则变更，不在本 ADR 范围内。
|
||||
- 模型自报失败时用户看到的也仍是既有映射结果（`codex-app-server-error:<kind>` 那张中文表），区别只是原因现在从事件载荷来、同时命令返回带出运行错误横幅——这就是"事件出聊天文案、命令返回出横幅"的既有分工；前端可见文案的映射规则不因这次改动改变。
|
||||
|
||||
Reference in New Issue
Block a user