注释：记录 Direct 命令接单化的 TODO 与实现要点

- `direct_runtime/user_input.rs` 命令入口加 TODO：目标形状（接单 + spawn、`turn.started` 与终态守卫下沉、接单后早退必须补终态、环境类失败升为回合级、宿主侧承担留痕与上报）与两条已决策的作废项 - `useDirectProjectChatController.ts` 的 catch 加同一份 TODO，说明它现在兼职"接单被拒"与"回合失败"、将来只剩前者 - 两处都指向草案 `docs/adr/【ADR】DirectProject命令接单化-2026-09-23.md`，本次不实施、不提交该草案
2026-09-23 15:36:03 +08:00
parent 34b95b5826
commit 46b86527f9
2 changed files with 18 additions and 0 deletions
@@ -32,6 +32,20 @@ pub(crate) fn normalize_direct_client_turn_id(
 ///
 /// 字符串只在这里、由 [`DirectTurnError`] 的 `Display` 生成一次；前端拿到的仍是"一句给用户看的话"，
 /// 而 Rust 侧从命令入口到宿主出口全程只传 typed 错误。
+///
+// TODO(Direct 命令接单化，未实施)：现在这个命令 await 整轮，于是"命令边界"承担了不属于它的角色——
+// 回合失败的文案要靠这条 Err 回到界面，认证失败重试也只能挂在它上面。目标形状（草案见
+// `docs/adr/【ADR】DirectProject命令接单化-2026-09-23.md`，落地前不要照抄这里的一半）：
+//   1. 命令只负责**接单**：校验 + 权限门 + 用户条目落盘 + 占用调用身份，然后 spawn 整轮任务并立刻
+//      返回；"这一轮跑成什么"只由订阅事件回答。
+//   2. `turn.started` 与终态兜底守卫的所有权下沉到接单任务：接单之后**任何**早退（连不上
+//      app-server、配置 / 凭据未就绪、历史注入构建失败、`turn/start` 被拒）都必须有终态事件收口，
+//      否则前端的乐观气泡会永远停在"宿主还没确认"。
+//   3. 于是连接 / 环境类失败要从调用级升成回合级：`EnvironmentNotReady` 只留"接单前就能判定"的
+//      语义（目录 / 权限 / 输入 / 并发）。
+//   4. 诊断留痕与错误上报必须在宿主侧完成：接单之后命令不再返回 Err，前端 catch 看不到这些失败。
+//   5. 顺带作废两条现役行为（已决策）：删掉由 invoke 拒绝驱动的认证重试；失败横幅改由 reducer
+//      供数据；"接单被拒"的文案不再占用状态行，改成这条消息下面的本地助手气泡。
 #[tauri::command]
 pub(crate) async fn chat_with_game_creator_direct_codex(
    project_path: String,
@@ -582,6 +582,10 @@ export function useDirectProjectChatController({
        runAnalytics.settle();
      }
      // 清单刷新统一交给 startTurn 的 finally：成功与报错路径都覆盖，且只读一次。
+      // TODO(Direct 命令接单化，未实施)：下面这个 catch 现在兼职"接单被拒"与"回合失败"两种回执。
+      // 计划（`docs/adr/【ADR】DirectProject命令接单化-2026-09-23.md`，草案）是让命令只负责接单、
+      // 整轮结果只由订阅事件的载荷回答：届时这里只剩接单被拒，文案改成这条消息下面的本地助手
+      // 气泡，状态行改由 reducer 供数据，而 invoke 拒绝驱动的认证重试作废。
    } catch (error) {
      if (
        isDirectCodexTurnAlreadyRunningError(error) ||