From 1e7ea51368f15ab421988efa64f841734308b2d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Thu, 24 Sep 2026 20:46:53 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9ADirectProject=20?= =?UTF-8?q?=E5=91=BD=E4=BB=A4=E5=85=A5=E9=98=9F=E5=8C=96=E4=B8=8E=E5=BE=85?= =?UTF-8?q?=E5=8F=91=E6=B6=88=E6=81=AF=E9=98=9F=E5=88=97=E5=BD=92=E5=AE=BF?= =?UTF-8?q?=E4=B8=BB=E8=AE=BE=E8=AE=A1=E5=AE=9A=E7=A8=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 ADR：命令=入队、放行归 Thread Manager、待发消息队列作为运行态事件归宿主 - 新增实施计划：五步落地顺序、标识符映射表、每步不变式与验收证据 - CONTEXT.md：接单/拒单词条替换为入队/入队失败/放行，新增待发消息队列与待发消息词条 - docs/README.md 补两条索引；decision-log.md 追加同日决策记录 --- CONTEXT.md | 30 ++-- docs/README.md | 2 + ...命令入队化与待发消息队列归宿主-2026-09-24.md | 139 +++++++++++++++++ .../shared-memory/decision-log.md | 33 ++++ ...ject命令入队化与待发消息队列归宿主-2026-09-24.md | 144 ++++++++++++++++++ 5 files changed, 339 insertions(+), 9 deletions(-) create mode 100644 docs/adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md create mode 100644 docs/technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md diff --git a/CONTEXT.md b/CONTEXT.md index c22344ea0..00f7c178e 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -192,7 +192,7 @@ _Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI ## 项目开发对话（DirectProject） **DirectProject 专属聊天模块**: -AGC 普通项目聊天的独立容器，拥有 DirectProject 的聊天状态、运行态订阅、历史读取、发送队列、附件和中止交互，并把聊天投影交给专属表现层渲染；它不承接 Supervisor、Design Agent 或 Planning V2 的运行态。 +AGC 普通项目聊天的独立容器，拥有 DirectProject 的聊天状态、运行态订阅、历史读取、待发消息队列的投影、附件和中止交互，并把聊天投影交给专属表现层渲染；它不承接 Supervisor、Design Agent 或 Planning V2 的运行态。 _Avoid_: 把 DirectProject 作为项目总控聊天的一个布尔分支、把四种 Agent 会话抽象成同一事实源 **项目工作台布局**: @@ -208,20 +208,32 @@ Thread Manager 向订阅者推送的当前回合原始事件流，只服务运 _Avoid_: 进度通知、快照轮询、第二套历史 **逻辑回合**: -Thread Manager 拥有的一对回合边界（开始与结束），由接单动作开启、由这一轮的占用对象写出，不镜像 Codex 原生回合；界面忙碌态与回合结果只认它。 +Thread Manager 拥有的一对回合边界（开始与结束），由放行动作开启、由这一轮的占用对象写出，不镜像 Codex 原生回合；界面忙碌态与回合结果只认它。 _Avoid_: Codex 原生回合、原生日志、进程生命周期 -**接单**: -把一条用户消息交给宿主开始执行的动作，成立即表示这一轮已经存在；此后结果只由运行态事件回答。 -_Avoid_: 发送成功、命令调用、接口返回 +**待发消息队列**: +Thread Manager 按项目持有的待发用户消息序列，只支持按入队顺序追加与按身份移除，状态由运行态事件派生，不落盘、不构成第二份事实源。 +_Avoid_: 前端本地队列、队列副本、待发消息的持久化记录 -**拒单**: -接单成立之前拒绝这次请求（并发、权限、目录、参数、工程准备未就绪），只回一条可展示原因，不产生回合事件，也不写用户条目。 +**待发消息**: +已经通过入队检查、等待被放行的用户消息；它在放行之前不是回合，不写用户条目、不产生回合事件。 +_Avoid_: 回合、在途回合、草稿 + +**入队**: +把一条用户消息交给宿主的动作：宿主跑完入队检查后把它放进待发消息队列；入队成立只表示这条消息会按顺序被放行。 +_Avoid_: 发送成功、已经开跑、回合成立 + +**入队失败**: +入队检查未通过（身份、形状、容量、权限、目录、参数、工程准备未就绪）时拒绝这次请求，只回一条可展示原因，不入队、不产生回合事件，也不写用户条目。 _Avoid_: 回合失败、执行失败、失败事件 +**放行**: +Thread Manager 在一个回合收口之后把队首的待发消息送进回合：同一临界区里登记占用、落盘用户条目、发出逻辑回合开始事件并起整轮；放行之后的结果只由运行态事件回答。 +_Avoid_: 前端放行、定时轮询、放行失败 + **在途回合**: -界面本地已经把这条用户消息发出去、宿主还没有对应回合开始事件的那一小段状态。 -_Avoid_: 运行中回合、乐观锁、发送队列 +界面本地已经入队、宿主还没有对应回合开始事件的那一小段状态。 +_Avoid_: 运行中回合、乐观锁、前端发送队列 **聊天投影**: 把项目对话历史条目与运行态事件转换成消息气泡和工具卡片的读取期转换；不持久化，也不构成事实源。 diff --git a/docs/README.md b/docs/README.md index 20a519f46..e183cb872 100644 --- a/docs/README.md +++ b/docs/README.md @@ -48,6 +48,8 @@ - [引用候选由宿主注入](./adr/【ADR】引用候选由宿主注入-2026-09-22.md)：引用输入区只接受宿主注入的引用 provider，素材选择面板独立成组件，附件芯片成为本轮附件唯一事实源。 - [DirectProject 命令接单化](./adr/【ADR】DirectProject命令接单化-2026-09-23.md)：命令只负责接单、事件流回答整轮结果；拒单前置、失败后置。 - [DirectProject 命令接单化实施计划](./technical/【实施计划】DirectProject命令接单化-2026-09-23.md)：四步落地顺序、每步不变式与验收；四步均已落地。 +- [DirectProject 命令入队化与待发消息队列归宿主](./adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)：命令只负责入队，放行归 Thread Manager；待发消息队列作为运行态事件归宿主、前端只投影；CLI 直连入口与调用身份守卫一并退役。 +- [DirectProject 命令入队化与待发消息队列归宿主实施计划](./technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)：五步落地顺序、每步不变式与验收；待实施。 - [GameAgent 对话工具调用卡片](./technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md)：把右侧对话里的执行命令 / 写文件投影成 Codex 风格可折叠卡片，含采集、独立历史文件、事件字段与回读契约。 - [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。 - [AGC 通用插件宿主与编辑器适配](./technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md)：通用插件宿主、SDK、权限审计、UI 挂载和 Cocos 编辑器适配边界。 diff --git a/docs/adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md b/docs/adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md new file mode 100644 index 000000000..d4e741723 --- /dev/null +++ b/docs/adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md @@ -0,0 +1,139 @@ +# 【ADR】DirectProject命令入队化与待发消息队列归宿主 + +状态：已接受（2026-09-24 设计定稿；**尚未落地**，实施顺序与验收见 +[`【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24`](../technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)） + +## 背景 + +待发消息队列今天是纯前端状态：回合运行中用户再发送就进本地 FIFO +（`chat/components/DirectProjectComposer/chatComposerQueue.ts`），回合终态事件到达后由**恰好开着的那个窗口**放行队首 +（`useDirectProjectChatController.ts` 的完成计数 effect 与 `startTurn` 的 `finally`）。三个问题： + +1. 队列是这条对话里唯一没有宿主持有者的事实：另一个窗口、另一个订阅者，或只是离开工作台再回来，都看不到已经排了什么队。 +2. 放行落在"哪个窗口恰好开着"上。队列一旦共享（本 ADR 要做的），两个窗口都会去放行队首，必然双发。 +3. 命令边界今天写的是"接单"：校验通过就登记占用、落盘用户条目、起整轮。但用户按下发送时想要的是"这条消息会被依次处理"—— + 命令的成功含义与用户意图之间隔着一次长度未定义的等待。 + +前置口径：`【ADR】DirectProject命令接单化-2026-09-23` 已把逻辑回合收归 Thread Manager，并在 §8 留了 TODO +「以后这条队列挪到 Rust 端，落点就是 Thread Manager 的接单动作」，同时把 Rust 端发送队列列进"明确不做"。 +本 ADR 就是那条 TODO 的收口，并顺带收掉两处已经没有现役价值的实现。 + +## 决策 + +### 1. 词表：入队 / 入队失败 / 放行 + +- 命令边界的成功与失败改叫 **入队 / 入队失败**；「接单」「拒单」两个词退役，不再出现在文档、注释、标识符与测试名里。 +- 旧「接单」在语义上的角色（这一轮真正成立的那一刻）改叫 **放行**。 +- 因此旧句「接单成立 ⇔ 事件流里有开始有结束」要改写成「**放行成立** ⇔ 事件流里有开始有结束」。这不是换词而是角色搬家： + 逐处改写时按角色判，不做字面替换（命令边界→入队/入队失败；回合成立→放行；检查归属→入队时的检查）。 + +### 2. 命令 = 入队 + +`chat_with_game_creator_direct_codex` 改义改名（建议 `enqueue_direct_codex_turn`），主体是今天"接单前"那条链**原样**跑完： +`clientTurnId` 校验 → 工作流恢复 → 用户条目校验 → prompt 投影 → 前置条件 → 工程准备；通过后**只入队**—— +追加 `queue.enqueued`，不登记占用、不落盘用户条目、不发回合事件、不起 codex。 +任何一步失败就是**入队失败**，走命令返回的 typed 载荷（`DirectTurnRejection` → `DirectTurnEnqueueFailure`），用户就在现场。 + +入队按 `clientTurnId` 幂等，判重范围是"在队 ∪ 正在跑的那一轮"；重复入队返回同一次成功，不再是并发拒单。 + +### 3. 队列归 Thread Manager + +- 每个 thread（线程身份就是项目规范路径）一条 FIFO；本期只支持**按顺序追加**与**按身份移除**，不做重排、优先级、编辑。 +- 队列状态**就是事件列表本身**：`queue.enqueued` 在条目仍在队期间不可回收，离开队列（取消或放行）时转为可回收并被既有规则回收。 + 不新增第二张队列表；`subscribe` 的 live-set bootstrap 因此天然把当前队列交给新订阅者——这就是"加入者看到的那几条"。 +- 上限 5 只数**在队条目**（不数正在跑的那一轮），由 Rust 持有；满队时入队失败并给出既有提示文案。 + +### 4. 线上形状 + +- `queue.enqueued { clientTurnId, userItem, creationType?, at }`：`userItem` 是 canonical 用户条目，前端据此派生 chip 文案， + Rust 不渲染、不裁成展示形状。事件**不带** prompt——prompt 是入队检查的产物，只留在宿主的队列条目里。 +- `queue.removed { clientTurnId, reason }`：`reason` 是 ts-rs 导出的 **typed 枚举**（`cancelled | dispatched`），永不用字符串， + 形状与 `turn.completed{status, failure?}` 同构。 +- 两条事件与其它运行态事件同一条流、同一个 reducer。 + +### 5. 放行 = 旧「接单」的语义角色 + +Thread Manager 在一个回合收口**之后**原子地做：取队首 → 登记占用 → 发 `turn.started` → 落盘用户条目 → 下发用户条目 → 起整轮， +并在同一临界区写 `queue.removed{ dispatched }`（chip 消失与气泡出现在同一批 consume 里，中间没有空窗）。 + +**放行不重跑任何检查，也不存在"放行失败"这种状态**：放行之后的一切失败都是**回合失败**，走既有 `turn.completed.failure` 通道； +不新增任何失败通道，也不为放行补拒单出口。 + +### 6. 放行的触发与监护顺序 + +- 唯一放行点：回合任务收尾之后的 `kick`（正常 / 失败 / 中止三条路径共用，外加一个 drop 守卫盖 panic），幂等，并且在临界区里原子认领队首。 +- 入队时也踢一脚：「队列非空 + 线程空闲」是合法状态，对应今天的"直接发送"。 +- 入队**不取** `DirectTaonierActiveInvocationGuard`：它必须整轮持有（它是这一轮的调用身份，付费美术、执行会话、MCP、校验、 + 上下文预取都靠它把工作归属到自己那一轮），入队若取它等于"回合运行中不能入队"。入队路径的并发由工程准备自身的项目写锁与队列兜。 + +### 7. 渲染侧 + +前端不再持有队列副本：chip 只由事件投影（入队被拒时只由命令返回值给反馈，保留既有提示文案与"不丢草稿"行为）； +忙态只由事件投影加「队列非空」指示。排队消息在放行前**不写** `project.jsonl`，用户气泡仍然只来自宿主条目（"落盘即放行"不变）。 + +### 8. 作用域与寿命 + +每项目一条、全进程共享：A 窗口排队 B 窗口可见可取消；切项目、离开工作台、关窗口都不影响队列继续放行；进程结束队列消失。 +**不做跨进程持久化**。 + +### 9. 顺带退役 + +- `--direct-codex-chat` 整个退役（解析、派发，以及只服务它的 `run_direct_game_creator_turn_at` 一对函数）。 + 它的历史用途只有一个：手工生产验证夹具 `scripts/direct-execution-production-fixture.mjs`（PR #439 引入，不在 CI、 + 没有 npm 脚本或 harness 注册、没有任何测试钉它，唯一硬依赖是进程退出码）。没有产品入口价值，也不该在入队化之后 + 成为第二条直接起回合的路径；夹具脚本一并退役。 +- CLI 一退，`DirectTurnError::TurnAlreadyRunning` 的两个生产点（调用身份守卫、占用登记）都没有调用方， + 它连同前端"同一轮消息仍在处理中"文案、专属分支与测试一起删。 +- `DirectTaonierActiveInvocationGuard` 的**身份**与 Thread Manager 的 `active_turn.turn_id` 是同一件事的两份记录 + （GUI 路径下同源字符串），而 09-23 ADR 立的是"同一件事只许有一处真相"。CLI 退役后它的硬阻塞消失：第二步让那五个读者 + 改读 Thread Manager 的活动回合身份，守卫连同它的测试与 60 秒卡死兜底一起删。删之前必须确认取消路径的无条件终态 + 仍然解得开"回合卡死"（那次兜底来自真实事故 `d833ca9d3`）。 + +## 备选方案与取舍 + +1. **状态归宿主、放行留前端**（再用一条 `claim` 命令做 CAS 认领）：前端机器原样保留，但队列的继续推进依赖至少一个窗口活着， + 且"谁去认领"要靠竞态解决——正是要消掉的东西。作废。 +2. **入队只做形状校验、把前置检查留到放行**：会造出"放行期拒单"——一个没有调用方在等的失败，得为它发明新通道； + 而且"首个回合还在建工程、第二条已经排队"这类合法流程会被入队误拒。作废（检查跟着入队走）。 +3. **一条 `queue.changed{items:[…]}` 快照事件**代替两条细粒度事件：reducer 更傻，但每次变更搬全量、与既有细粒度事件风格不一致。不选。 +4. **`reason` 用字符串**：前端只能猜、无法穷举、无法在类型层穷尽分支。不选，用 typed 枚举。 +5. **保留 CLI**：省掉夹具改写，但等于为手工验证工具长期保留第二条直接起回合的路径，与"命令只有入队一个入口"冲突。不选。 + +## 影响与代价 + +- **入队即写盘**：引用 UI 设计文档的条目在 prompt 投影时会生成 `ui/generated-.js`（`ui_editor/persistence.rs`）； + 从队列里取消不撤该文件。 +- **检查是时间点事实**：放行不重跑，按入队那一刻的结论放行；manifest、权限、目录在入队之后变化也照旧放行，偏差落到回合失败。 +- **队列随进程消失**：待发消息只在内存与事件流里，`kill -9` / 退出后重进看不到（与 09-16 ADR 的 `kill -9` 口径一致）。 +- **退役面**：前端 `completionPendingRef`、`handledCompletedTurnCountRef`、`busyBaselineTurnCountRef`、`dispatchNextQueuedTurn`、 + `turnBusyRef`/`beginTurnBusy`/`endTurnBusy`、`queueSequenceRef`、`queuedTurns*`、排队条目那部分 `pendingRunAnalyticsRef` + 与 `chatComposerQueue.ts` 的队列逻辑整体退役；`directProjectTurnStatus` 的"命令在飞"分支收成 IPC 在飞； + 埋点句柄改由宿主在放行时开。 +- **词表切换是一次性跨文档动作**：仓库里「接单/拒单」共 384 处，并非全属同一个域 + （`features/agent-runtime` 的"拒单文案"属另一个域，改成"请求被拒"；`单测` 这类是假阳性）。 + 两份已接受的 ADR 保留正文与文件名，顶部加词表注记。 +- **失去手工验证手段**：CLI 退役同时带走"真实二进制驱动执行层生产验证"这条手工路径（夹具脚本一并退役）。 + 它不在 CI，损失的是排障时的一次性手段，不是门禁。 +- **埋点**：attempt id 只用于宿主内存里的候选配对与前端结算（同 `session_id` 的 `Settle` 才提交）， + 前端不再需要为排队条目提前持有它；平台会话代际翻转的 `discard` 判定仍是渲染侧职责，落地时逐条核对。 + +## 明确不做 + +- 不做跨进程持久化（不在入队时写 `project.jsonl`：那会在历史里留下一条永远不会跑的假消息，破坏"用户气泡只来自宿主条目"）。 +- 不做重排、优先级、编辑待发条目；也不做"队列挂起 / 继续"状态——入队化之后队列里不存在会被拒的条目。 +- 不给放行新增失败通道，不为"放行不重跑检查"补兜底。 +- 不保留 CLI，也不为夹具保留别名或兼容入口。 + +## 落地时要同步的文档与注释 + +- `CONTEXT.md`：词条（待发消息队列 / 待发消息 / 入队 / 入队失败 / 放行 / 逻辑回合 / 在途回合）。 +- `docs/adr/【ADR】DirectProject命令接单化-2026-09-23.md`：§8 的 TODO 与"明确不做：Rust 端发送队列"、§7 的"命令在飞"措辞、 + CLI 保持 await 的分工，全部改为入队化口径（正文保留，顶部加词表注记）。 +- `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md`：事件协议一节补两个队列事件与放行时序。 +- `docs/technical/【实施计划】DirectProject命令接单化-2026-09-23.md`：第 4 步的队列 TODO 指向本 ADR。 +- `docs/technical/【技术方案】Direct回合行为审计账本-2026-08-31.md`、`【技术方案】DirectProject本轮附件路径映射-2026-08-31.md`、 + `docs/project-memory/plans/【里程碑】退役AGC项目对话斜杠命令与终端swarm chat入口-2026-09-22.md`：删掉对 CLI 入口的承诺 + （最后那处现在写在"范围外（保留）"里，口径反转）。 +- `docs/project-memory/shared-memory/decision-log.md`：追加本决定，并修正"CLI 保持 await"那条。 +- 代码注释：`agent/direct_runtime/user_input.rs` 模块注释里的 CLI 分工一段删掉；`direct_turn_accept.rs`、 + `direct_thread_manager.rs`、`useDirectProjectChatController.ts` 的旧措辞与 TODO 一并改。 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 53b75ec40..f8304d518 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -9578,3 +9578,36 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 验证：`cargo test -p module-runtime --lib agc_models::`（4 passed）、`cargo test -p api-server --bin api-server agc` 与 `llm::`、AGC 客户端 `configuration::`、admin-web 页面定向 Vitest 与 typecheck、两套 workspace 的 `cargo fmt -- --check`、`check:encoding`/`check:doc-index`/`check:spacetime-schema`/`git diff --check`。 - 验证（真实上游 smoke，本地 dev DB）：清空 `agc_model_catalog` 后启动 api-server → 日志 `已按上游模型列表初始化 AGC 模型目录 revision=1 model_count=6`；登录后 `GET /api/llm/models` 返回同一批模型、`displayName` 即上游原名、默认项为排序后第一项；上游不可达/非 2xx 时启动只记录 error、AGC 接口 `503` 且目录保持未初始化；目录已存在时重启不重写。 - 边界（未验证/残留）：上游在售模型超过 32 条时同步会失败（目录项上限未改）；`qwen-image-3.0` 这类图像模型会一起进入目录，是否对 AGC 隐藏由 owner 在后台停用；混合版本期间未升级的 api-server 会把自己的 AGC 接口打到 `503`，module 与 api-server 必须同批发布/回滚。 + +## 2026-09-24 命令入队化与待发消息队列归宿主：放行归 Thread Manager，CLI 直连入口退役 + +- 决策（词表）：「接单 / 拒单」退役，命令边界的成功与失败改叫「入队 / 入队失败」；旧「接单」的语义角色 + （这一轮真正成立的那一刻）改叫「放行」。所以旧句"接单成立 ⇔ 事件流里有开始有结束"改成"放行成立 ⇔ …"， + 逐处按角色改、不做字面替换；`features/agent-runtime` 的"拒单文案"属另一个域，改"请求被拒"。 +- 决策（命令 = 入队）：`chat_with_game_creator_direct_codex` 改义改名（暂定 `enqueue_direct_codex_turn`）， + 把今天"接单前"那条检查链原样跑完（身份 → 工作流恢复 → 用户条目校验 → prompt 投影 → 前置条件 → 工程准备）， + 通过后只入队：不登记占用、不落盘用户条目、不发回合事件、不起 codex；失败走命令返回的 typed 载荷 + （`DirectTurnRejection` → `DirectTurnEnqueueFailure`）。入队按 `clientTurnId` 幂等（判重范围 = 在队 ∪ 在跑）。 +- 决策（队列归 Thread Manager）：每项目一条 FIFO，只支持按顺序追加与按身份移除；队列的成员与顺序就是事件列表本身 + （`queue.enqueued` 在队期间不可回收、离开队列后可回收），`subscribe` 的 live-set bootstrap 因此天然把当前队列 + 交给中途加入的订阅者；上限 5 只数在队条目，由 Rust 持有。 +- 决策（线上形状）：`queue.enqueued{clientTurnId,userItem,creationType?,at}` + `queue.removed{clientTurnId,reason}`， + `reason` 是 ts-rs 导出的 typed 枚举（`cancelled|dispatched`），不用字符串；事件不带 prompt—— + prompt 是入队检查的产物，只留在宿主的队列条目里。 +- 决策（放行）：Thread Manager 在回合收口之后原子地「取队首 → 登记占用 → `turn.started` + `queue.removed{dispatched}`」， + 再落盘用户条目、下发用户条目、起整轮。**放行不重跑检查、不存在放行失败**，放行之后的一切失败都是回合失败， + 走既有 `turn.completed.failure`，不新增通道。kick 点 = 回合任务收尾（含 drop 守卫盖 panic）+ 中止路径 + 入队之后， + 幂等且在临界区里认领队首；入队不取 `DirectTaonierActiveInvocationGuard`（它必须整轮持有，是这一轮的调用身份）。 +- 决策（前端）：不再持有队列副本，chip 只由事件投影，入队失败只由命令返回值给反馈（保留提示文案与"不丢草稿"）； + 埋点句柄改由宿主在放行时开。 +- 决策（顺带退役）：`--direct-codex-chat` 整个退役——它唯一的实际消费者是手工夹具 + `scripts/direct-execution-production-fixture.mjs`（PR #439 引入、不在 CI、无 npm/harness 注册、无测试钉它）， + 夹具一并退役；`TurnAlreadyRunning` 与前端"同一轮消息仍在处理中"分支随之删除。 + `DirectTaonierActiveInvocationGuard` 的身份与 Thread Manager 的 `active_turn.turn_id` 是同一件事的两份记录， + CLI 退役后让那五个读者改读 Thread Manager，再在第二步删掉守卫与它的 60 秒卡死兜底 + （删前必须保住"回合卡死可被取消解开"这条由 `d833ca9d3` 事故换来的保证）。 +- 代价：入队即写盘（引用 UI 设计文档的条目会生成 `ui/generated-.js`，取消不撤）；检查是时间点事实、 + 放行不重跑（manifest / 权限 / 目录变化后照旧放行，偏差落到回合失败）；队列随进程消失，不做跨进程持久化； + 失去"真实二进制驱动执行层生产验证"这条手工路径。 +- 验证方式（设计稿，尚未实施）：`docs/adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md`、 + `docs/technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md`。 diff --git a/docs/technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md b/docs/technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md new file mode 100644 index 000000000..150ef125a --- /dev/null +++ b/docs/technical/【实施计划】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md @@ -0,0 +1,144 @@ +# DirectProject 命令入队化与待发消息队列归宿主实施计划 + +更新时间：`2026-09-24` + +状态：**待实施**（设计已定稿，尚未开工） + +设计口径见 [`【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24`](../adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)。 +本文件只排实施顺序、不变式与验收，不重复设计理由。 + +## 第 0 步：词表切换（与代码同批，不单独提交） + +「接单 / 拒单」退役，改成「入队 / 入队失败 / 放行」。逐处按角色改，**不做字面替换**： + +| 旧写法 | 新写法 | +| --- | --- | +| 命令的成功 / 失败（接单 / 拒单） | 入队 / 入队失败 | +| 这一轮真正成立的那一刻（接单） | 放行 | +| 接单前的检查 | 入队时的检查 | +| 接单成立 ⇔ 事件流里有开始有结束 | **放行成立** ⇔ 事件流里有开始有结束 | +| 接单后的失败都是回合失败 | **放行后**的失败都是回合失败 | + +三类出现点必须分开处理（全仓 384 处）： + +1. DirectProject 域（文档、注释、标识符、测试名）：按上表改。主要落点 `docs/adr/【ADR】DirectProject命令接单化-2026-09-23.md`、 + `docs/technical/【实施计划】DirectProject命令接单化-2026-09-23.md`、 + `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md`、`CONTEXT.md`、 + `agent/direct_runtime/user_input.rs`、`agent/direct_turn_accept.rs`、`agent/direct_turn_error.rs`、`agent/direct_thread_manager.rs`、 + `chat/controller/useDirectProjectChatController.ts`、`chat/conversation/directTurnPresentation.ts`、`tests/appSurface/chat-composer.suite.ts`。 +2. `features/agent-runtime` 域的「拒单文案」（`model.ts`、`tests/agentRuntimeModel.test.ts`）：那里没有队列， + 改成「请求被拒 / 拒绝」，不要写成「入队失败」。 +3. 假阳性：`单测` 这类词不动（如 `server-rs/crates/api-server/src/editor_project.rs`）。 + +标识符同批改（映射表）： + +| 旧 | 新 | +| --- | --- | +| `chat_with_game_creator_direct_codex` | `enqueue_direct_codex_turn` | +| `DirectTurnRejection`（ts-rs 导出） | `DirectTurnEnqueueFailure` | +| 前端 `readDirectTurnRejection` / `directTurnRejectionNotice*` | `readDirectTurnEnqueueFailure` / `directTurnEnqueueFailureNotice*` | +| Rust `direct_turn_rejection` | `direct_turn_enqueue_failure` | +| `DirectTurnReservation::accept` | `DirectTurnReservation::start` | +| `accept_direct_thread_turn` / `DirectThreadManager::accept_turn` | `start_direct_thread_turn` / `start_turn` | +| `agent/direct_turn_accept.rs` | `agent/direct_turn_dispatch.rs` | +| `DirectTurnError::TurnAlreadyRunning` | 删除（第 4 步判据确认零调用方后） | + +两份已接受的 ADR 保留正文与文件名，只在顶部加一行词表注记，避免正文里的旧词变成假命题。 + +验收：`rg -n "接单|拒单"` 在 DirectProject 域与 `agent-runtime` 域均为 0；生成绑定重跑（`cargo test export_bindings`）后 +`git diff` 只剩映射表内的改动。 + +## 第 1 步：命令 = 入队（Rust） + +改动点： + +- `agent/direct_runtime/user_input.rs`：把命令主体拆成两半。 + **入队半**：`clientTurnId` 校验 → 工作流恢复 → 用户条目校验 → prompt 投影 → 前置条件 → 工程准备 → 入队； + 任何一步失败返回 typed 入队失败。**放行半**（第 2 步）从占用登记起。 +- 队列条目（宿主侧产物，只在内存）：`PendingDirectTurn { client_turn_id, user_item: Value, prompt: String, creation_type: Option, at: u64 }`。 + `prompt` 与 `creation_type` 是入队检查的产物，放行不再重算；事件里**不带** `prompt`。 +- `agent/direct_thread_manager.rs`： + - `MAX_PENDING_DIRECT_TURNS = 5` 落在 Rust，只数在队条目；满队 → typed 入队失败。 + - 队列的成员与顺序**就是事件列表本身**：宿主侧产物挂在对应的 `queue.enqueued` 事件上（`StoredEvent` 增加一个非序列化的 + 可选产物字段），不另建队列表。 + - `observe_event`：`queue.enqueued` 在队期间**不可回收**；`queue.removed` 可回收，并把同 `clientTurnId` 的 enqueued 标记为可回收。 + `is_bootstrap_event` 不改——live-set bootstrap 因此自动把当前队列交给新订阅者。 + - 入队幂等：判重范围「在队 ∪ 正在跑的那一轮」，重复入队返回同一次成功。 + - `remove_direct_project_pending_turn(project_path, client_turn_id)`：typed 结果枚举 `Removed | AlreadyDispatched | NotFound`， + 在临界区里判「是否仍未被认领」。 +- 线上形状：`DirectThreadEvent::QueueEnqueued { client_turn_id, user_item, creation_type?, at }`（`queue.enqueued`）、 + `QueueRemoved { client_turn_id, reason: DirectQueueRemovalReason }`（`queue.removed`）， + `DirectQueueRemovalReason` 是 ts-rs 导出的 typed 枚举 `cancelled | dispatched`。 + +不变式：入队不登记占用、不落盘、不发回合事件、不起 codex；入队失败不写用户条目、不产生事件。 + +## 第 2 步：放行与 kick + +- `start_direct_thread_turn`：同一个临界区里「取队首 → 占用登记 → `turn.started` + `queue.removed{dispatched}`」； + 之后落盘用户条目 → 下发用户条目 → spawn 整轮（顺序与今天的接单后半段一致，`accept` 必须早于落盘与 `turn/start`）。 +- `kick_direct_queue_dispatch(thread_id)`：幂等；在临界区里判「无占用 + 队首存在 + 未被认领」，认领后 spawn 放行任务。 + 调用点三个：回合任务收尾（正常 / 失败共用）、中止路径、入队之后。 +- panic 兜底：回合任务里的一个 drop 守卫负责踢一脚，保证任务 panic 或 future 被丢弃时队列不会永久停住。 +- 入队不取 `DirectTaonierActiveInvocationGuard`；该守卫继续由整轮持有。 +- 不变式：放行不重跑检查、没有放行失败；放行之后的一切失败都走 `turn.completed.failure`。 + +验收（Rust 单测）：放行原子性（`queue.removed{dispatched}` 与 `turn.started` 同批、无中间窗口）； +kick 幂等（并发两次只认领一次）；队首在放行后被移除、remove 对已放行条目返回 `AlreadyDispatched`； +回合失败 / 中止后队列继续放行下一条；任务 panic 后队列仍能继续；多订阅者游标各自独立时 bootstrap 仍重建完整队列。 + +## 第 3 步：前端收口 + +退役： + +- `chatComposerQueue.ts` 的 `enqueueChatTurn` / `dequeueChatTurn` / `removeQueuedChatTurn` / `isChatTurnQueueFull` / + `MAX_QUEUED_CHAT_TURNS`（提示文案 `chatQueueFullNotice` 保留，改由 Rust 的 typed 入队失败驱动）。 +- controller 的 `queuedTurns` / `queuedTurnsRef` / `queueSequenceRef` / `completionPendingRef` / `handledCompletedTurnCountRef` / + `busyBaselineTurnCountRef` / `dispatchNextQueuedTurn` / `beginTurnBusy` / `endTurnBusy` / `turnBusyRef` 与排序用的计数 effect。 +- 排队条目那部分 `pendingRunAnalyticsRef` 与 `beginDirectRunAnalytics` 的调用时序（埋点句柄改由宿主在放行时开）。 + +保留与改写： + +- chip 由运行态事件的投影驱动（新增 pending 列表投影与两条队列事件的 reducer 分支）； + chip 文案仍用现成的派生（`directCodexContentToPromptText` + `resourceLabelResolver`），只是输入换成事件里的 `userItem`。 +- 取消 chip 改调 `remove_direct_project_pending_turn`；入队失败只由命令返回值驱动提示（保留"不丢草稿"行为）。 +- 忙态 = 事件投影 + 「队列非空」指示；`directProjectTurnStatus` 的"命令在飞"分支收成 IPC 在飞。 +- 写权限门 `ensureConversationWriteAllowed` 留在入队之前（确认框必须在用户在场时弹）。 + +验收：`tests/directThreadChat.test.ts` 补队列事件投影用例；`tests/appSurface/chat-composer.suite.ts` 的排队 / 取消 / 满队 / +放行三组用例改成新语义；`npm --workspace apps/ai-game-creator-shell run typecheck` 通过。 + +## 第 4 步：CLI 与夹具退役 + +- `cli.rs`：删 `CliCommand::DirectCodexChat` 变体、`project_path_mut` 分支（`cli.rs:181`）与派发分支（`cli.rs:899-935`）。 +- `agent/direct_runtime/mod.rs`：删 `run_direct_game_creator_turn_at` 与 `run_direct_game_creator_turn_at_with_creation_type` + （各自只有彼此与 CLI 一个调用方）。 +- 删 `apps/ai-game-creator-shell/scripts/direct-execution-production-fixture.mjs`（CLI 的唯一消费者）。 +- 删 `DirectTurnError::TurnAlreadyRunning`（两个生产点都没了）与前端"同一轮消息仍在处理中"文案、专属分支、 + `tests/appSurface/project-conversation.suite.ts` 的对应断言。 +- 文档同步：09-22 里程碑把 `--direct-codex-chat` 从"范围外（保留）"改成退役项；两份 Direct 技术方案的 CLI 承诺删掉； + 09-23 ADR 与 `decision-log.md` 里"CLI 保持 await"的口径改掉。 + +验收：`rg -n -- "--direct-codex-chat"` 与 `rg -n "run_direct_game_creator_turn_at"` 零命中； +`cargo check --tests` 无新增 `dead_code` 告警；`check-config.mjs` 与 `.gitea/workflows/project-ci.yml` 不受影响（已核实无引用）。 + +## 第 5 步：守卫清理（CLI 退役之后） + +- 五个身份读者（`agent/direct_execution.rs`、`agent/direct_tool_bridge.rs`、`agent/direct_runtime/mod.rs` 的付费美术重生成、 + `agent/direct_validation.rs`、`agent/direct_project_context.rs`）改读 Thread Manager 的活动回合身份 + （新增一个按项目路径取 `active_turn.turn_id` 的只读入口）。 +- 删 `DirectTaonierActiveInvocationGuard` 与 `release_stale_direct_taonier_active_invocation` 及其测试 + （`direct_runtime/mod.rs` 的守卫用例、`direct_project_context.rs`、`direct_tool_bridge.rs`、`direct_tools_mcp.rs`、 + `user_input.rs`、`codex_app_server/mod.rs` 的集成用例），取消路径改为直接走无条件的 `complete_direct_thread_turn("aborted")`。 +- 前置判据：补一条测试证明"回合任务被 park / 泄漏时，取消仍能清空占用并让队列继续放行"——那次 60 秒兜底来自真实事故 + （`d833ca9d3`），删它必须有等价保证。 + +## 验收与证据 + +- Rust：第 1、2、5 步各自的单测；`cargo test` 定向 + `cargo check --tests` 无新增告警。 +- Node：`npx vitest run tests/appSurface.test.ts`、`npm --workspace apps/ai-game-creator-shell run typecheck`。 +- 端到端（`chat-composer.suite.ts`）：回合运行中入队两条 → 取消一条 → 终态后只放行剩下那条； + 入队只发生一次 IPC、没有第二次发送命令；满队提示；入队失败时草稿不丢。 +- 手工：两个窗口看同一项目（A 排队 B 可见可取消）；离开工作台再回来队列仍在并继续放行； + `kill -9` 后重进队列消失（与 ADR 的已知边界一致）。 +- 全仓：`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。 +- 不涉及 SpacetimeDB schema，不需要 `npm run check:spacetime-schema`。