CLI 与夹具退役：DirectProject 只剩入队一个命令入口

- cli.rs 删 CliCommand::DirectCodexChat 变体、project_path_mut 分支、--direct-codex-chat 解析与派发 - direct_runtime/mod.rs 删 run_direct_game_creator_turn_at 与 run_direct_game_creator_turn_at_with_creation_type - 删 scripts/direct-execution-production-fixture.mjs（CLI 唯一消费者） - user_input.rs 模块注释改成"唯一的命令入口"，不再承诺 CLI 分工 - 顺带删掉只剩测试在用的 direct_turn_error_boundary_text，判据只剩 direct_turn_enqueue_failure 一处 - 三条命令边界测试改打 direct_turn_enqueue_failure(...).message，覆盖不变 - 文档：09-22 里程碑把 --direct-codex-chat 从"范围外（保留）"改成退役项，两份 Direct 技术方案的 CLI 承诺删掉， 09-23 ADR 的"CLI 保持 await"标为口径反转，decision-log 追加口径修正，实施计划标注第 4 步落地
2026-09-30 10:25:38 +08:00
parent 0534e9c678
commit 25f3e41623
10 changed files with 33 additions and 1097 deletions
@@ -2148,24 +2148,10 @@ pub(crate) fn record_direct_codex_failure(
    public_text
 }

-/// 命令边界的错误文本：可留痕的调用级入队失败在这里补一份运行错误诊断（文案里不带诊断引用），
-/// 其余只输出 [`DirectTurnError`] 的 `Display`。
-///
-/// 分层改成 typed 之前，这几条"宿主 / 环境事实"是在回合失败通道里被写进诊断的；分层之后它们不再
-/// 进那条通道，留痕在这里补回来。GUI 命令与 CLI 边界共用这一份，禁止在各自边界再写一套判据；
-/// 回合级失败已在上游写过诊断，这里直接放行。
-pub(crate) fn direct_turn_error_boundary_text(
-    root: &Path,
-    client_turn_id: Option<&str>,
-    failure: DirectTurnError,
-) -> String {
-    direct_turn_enqueue_failure(root, client_turn_id, failure).message
-}
-
 /// 入队失败边界：可留痕的调用级失败（宿主 / 环境事实）在这里补一份运行错误诊断，然后连同**结构化
 /// 变体**一起交给前端；其余只输出 [`DirectTurnError`] 的 `Display`。
 ///
-/// GUI 命令与 CLI 边界共用这一份判据（CLI 只要文本，走上面的 `..._text`），禁止在各自边界再写一套。
+/// 命令边界只有这一份判据，禁止在各处再写一套。
 pub(crate) fn direct_turn_enqueue_failure(
    root: &Path,
    client_turn_id: Option<&str>,
@@ -4432,39 +4418,6 @@ pub(crate) fn check_direct_turn_preconditions(
        .map_err(|detail| DirectTurnError::InputRejected { detail })?;
    Ok(())
 }
-pub(crate) async fn run_direct_game_creator_turn_at(
-    root: &Path,
-    prompt: &str,
-) -> Result<String, DirectTurnError> {
-    // The CLI entry point does not receive the GUI's clientTurnId.  Still arm
-    // one invocation identity so an otherwise optional AGC generation tool
-    // cannot fail merely because the request came through the CLI.  This is
-    // local execution identity only; it does not create a Runtime task or DAG.
-    let invocation_id = format!("direct-cli-{}", unix_millis());
-    let _invocation = DirectTaonierActiveInvocationGuard::enter(root, &invocation_id)?;
-    run_direct_game_creator_turn_at_with_creation_type(root, prompt, None).await
-}
-
-pub(crate) async fn run_direct_game_creator_turn_at_with_creation_type(
-    root: &Path,
-    prompt: &str,
-    creation_type: Option<&str>,
-) -> Result<String, DirectTurnError> {
-    // CLI 入口没有"入队 / 放行"这两步（它 await 整轮，要那段回复文本），前置条件在这里自己过一遍；
-    // GUI 命令在入队半里过同一份判据。
-    check_direct_turn_preconditions(root, prompt, creation_type)?;
-    run_direct_game_creator_turn_at_with_creation_type_and_emitter(
-        root,
-        prompt,
-        creation_type,
-        None,
-        None,
-        None,
-        None,
-    )
-    .await
-}
-
 pub(crate) async fn run_direct_game_creator_turn_at_with_creation_type_and_emitter(
    root: &Path,
    prompt: &str,
@@ -7739,13 +7692,14 @@ mod tests {
        let root = parent.path().join("project");
        init_local_game_project_at(&root, "direct-diagnostic", "直连诊断").expect("init project");

-        let text = direct_turn_error_boundary_text(
+        let text = direct_turn_enqueue_failure(
            &root,
            Some("direct-codex:turn-1:user"),
            DirectTurnError::EnvironmentNotReady {
                detail: "Codex app-server 启动失败：找不到可执行文件".into(),
            },
-        );
+        )
+        .message;

        assert!(text.contains("direct-codex-failure:v2"), "{text}");
        assert!(!text.contains("详情："), "{text}");
@@ -7765,7 +7719,7 @@ mod tests {
        let root = parent.path().join("project");
        init_local_game_project_at(&root, "direct-diagnostic", "直连诊断").expect("init project");

-        let text = direct_turn_error_boundary_text(&root, None, DirectTurnError::ContentEmpty);
+        let text = direct_turn_enqueue_failure(&root, None, DirectTurnError::ContentEmpty).message;

        assert_eq!(text, "聊天内容不能为空");
        assert!(!root.join(".agent/runtime/errors").exists());
@@ -7782,11 +7736,12 @@ mod tests {
            DirectTurnError::turn_failed(DirectCodexFailureStage::CodeGeneration, "模型失败");
        let recorded = record_direct_codex_failure(&root, &failure, None);
        // 上游把返回串挂进 `TurnFailed.detail`，边界再见到它时只做 `Display`，不再写诊断。
-        let text = direct_turn_error_boundary_text(
+        let text = direct_turn_enqueue_failure(
            &root,
            None,
            DirectTurnError::turn_failed(DirectCodexFailureStage::CodeGeneration, recorded.clone()),
-        );
+        )
+        .message;

        assert_eq!(text, recorded);
        let entries = std::fs::read_dir(root.join(".agent/runtime/errors"))
@@ -39,9 +39,8 @@ pub(crate) fn normalize_direct_client_turn_id(
 /// 入队失败不写用户条目、不产生任何事件。可留痕的调用级失败（宿主 / 环境事实）仍在边界补一份运行
 /// 错误诊断，返回串不带诊断引用。
 ///
-/// 与 CLI 的分工：CLI 入口（`cli.rs` 的 `direct-codex.chat`）**保持 await**——它要把那段回复文本
-/// 打到终端上，没有事件订阅可用；两个入口共用 [`direct_turn_error_boundary_text`] /
-/// [`direct_turn_enqueue_failure`]，不要再各写一套判据。
+/// 它是 DirectProject 唯一的命令入口：终端入口 `--direct-codex-chat`（它要保持 await 才能把回复打到
+/// 终端上）已经退役，不要再为"手工跑一轮"新增第二条直接起回合的路径。
 ///
 /// 设计见 `docs/adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md`。
 #[tauri::command]
@@ -14,10 +14,6 @@ pub(crate) enum CliCommand {
        agent_id: String,
        prompt: String,
    },
-    DirectCodexChat {
-        project_path: PathBuf,
-        prompt: String,
-    },
    AgentTask {
        project_path: PathBuf,
        agent_id: String,
@@ -178,7 +174,6 @@ impl CliCommand {
                ..
            } => Some((project_path, *initialize)),
            Self::AgentChat { project_path, .. }
-            | Self::DirectCodexChat { project_path, .. }
            | Self::AgentRuntimeStatus { project_path, .. }
            | Self::AgentContextCompact { project_path, .. }
            | Self::AgentGoalStatus { project_path, .. }
@@ -699,19 +694,6 @@ pub(crate) fn parse_cli_command(args: &[String]) -> Result<Option<CliCommand>, S
            prompt: prompt.to_string(),
        }));
    }
-    if args.first().map(String::as_str) == Some("--direct-codex-chat") {
-        if args.len() < 3 {
-            return Err("用法：--direct-codex-chat <本地项目绝对路径> <聊天内容>".to_string());
-        }
-        let prompt = args[2..].join(" ");
-        if prompt.trim().is_empty() {
-            return Err("聊天内容不能为空".to_string());
-        }
-        return Ok(Some(CliCommand::DirectCodexChat {
-            project_path: PathBuf::from(&args[1]),
-            prompt: prompt.trim().to_string(),
-        }));
-    }
    if args.first().map(String::as_str) == Some("--agent-task") {
        let mut rest = args[1..].to_vec();
        let initialize = if let Some(index) = rest.iter().position(|arg| arg == "--init") {
@@ -896,44 +878,6 @@ pub(crate) fn run_cli_command(command: CliCommand) -> Result<(), String> {
            println!("replyText={}", reply.reply_text);
            Ok(())
        }
-        CliCommand::DirectCodexChat {
-            project_path,
-            prompt,
-        } => {
-            let project_path = canonicalize_cli_path(&project_path, "本地项目路径", true)?;
-            if !project_path.join(".agent/manifest.json").is_file() {
-                let project_name = project_path
-                    .file_name()
-                    .and_then(|value| value.to_str())
-                    .unwrap_or("Codex 直连项目");
-                init_local_game_project_at(
-                    &project_path,
-                    &format!("direct-codex-{}", unix_millis()),
-                    project_name,
-                )?;
-            }
-            let runtime = tokio::runtime::Builder::new_multi_thread()
-                .enable_all()
-                .build()
-                .map_err(|error| format!("创建 CLI runtime 失败：{error}"))?;
-            let reply_result = runtime.block_on(async {
-                run_direct_game_creator_turn_at(&project_path, &prompt)
-                    .await
-                    // CLI 也是命令边界：typed 错误在这里序列化成一行给终端看的文本；可留痕的
-                    // 调用级拒绝（宿主 / 环境事实）与 GUI 走同一份投影（同一份 `Display` 文案，
-                    // 不另加 `详情：` 引用），差别只在 CLI 自己 await 整轮、拿到回复文本。
-                    .map_err(|failure| {
-                        direct_turn_error_boundary_text(&project_path, None, failure)
-                    })
-            });
-            let shutdown_result = shutdown_game_creator_codex_app_servers();
-            let reply = reply_result?;
-            shutdown_result?;
-            println!("direct-codex.chat.completed");
-            println!("projectPath={}", project_path.display());
-            println!("replyText={reply}");
-            Ok(())
-        }
        CliCommand::AgentTask {
            project_path,
            agent_id,
@@ -110,7 +110,9 @@
  界面不会卡在忙碌态。
 - 必须同步的注释：`chat/controller/useDirectProjectChatController.ts`（catch 的职责）、
  `chat/conversation/directTurnPresentation.ts`（"`invoke` 直到整轮结束才返回"这句会变成错的）。
- CLI 保持 await（它要那段回复文本），两个入口的分工在命令模块里写清楚。
+- ~~CLI 保持 await（它要那段回复文本），两个入口的分工在命令模块里写清楚。~~ **口径反转**：`--direct-codex-chat`
+  整个退役（见 [`【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24`](./【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)），
+  DirectProject 只剩「入队」一个命令入口。

 ## 备选方案与取舍

@@ -36,7 +36,12 @@
 - 命令 id 注册表 `GAME_CREATION_APP_COMMANDS` 与 `GameCreationAppPermission`（项目权限策略词汇表；App 前端只用 `GameCreationAppCommandDescriptor` 类型表达权限判定与审计粒度，数组本体由 Rust 策略路径消费）。
 - `needsInitializedChatProject` 与项目权限策略链路。
 - Rust 侧路径/路由的 `/` 前缀校验。
- `--agent-run`、`--agent-enqueue`、`--agent-task`、`--agent-steer`、`--agent-retry`、`--agent-cancel`、`--agent-confirm`、`--agent-resume`、`--agent-runtime-status`、`--agent-goal-*`、`--agent-context-compact`、`--runner-status`、`--runner-shutdown-if-idle`、`--llm-status`、`--preview-serve`、`--environment-check`、`--direct-codex-chat` 等运维与开发 CLI 控制命令。
+- `--agent-run`、`--agent-enqueue`、`--agent-task`、`--agent-steer`、`--agent-retry`、`--agent-cancel`、`--agent-confirm`、`--agent-resume`、`--agent-runtime-status`、`--agent-goal-*`、`--agent-context-compact`、`--runner-status`、`--runner-shutdown-if-idle`、`--llm-status`、`--preview-serve`、`--environment-check` 等运维与开发 CLI 控制命令。
+
+已退役（口径变更，见 [`【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24`](../../adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)）：
+- `--direct-codex-chat`（本文件此前列为「范围外（保留）」）：DirectProject 命令入队化之后不再保留第二条直接起回合的入口，
+  它唯一的实际消费者是手工夹具 `scripts/direct-execution-production-fixture.mjs`，两者一起退役；同批删掉只服务它的
+  `run_direct_game_creator_turn_at` / `run_direct_game_creator_turn_at_with_creation_type`。
 - 保留的真实 E2E 套件：`supervisor-swarm`、`supervisor-swarm-transient-retry`、`supervisor-swarm-final-reply-transient-retry`、`supervisor-swarm-tool-plan-handoff-runner-kill`、`goal-runtime`、`response-stream`、`web-search`、`context-compaction`、`scoped-agents`、`project-skill`、`parallel-read`、`steer-runner-kill`、`process-session`。

 ## 检查点
@@ -9491,7 +9491,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（队列与埋点听回合终态，不听命令返回）：前端发送队列的放行改由"回合完成（终态事件）或接单被拒"驱动，reducer 新增 `completedTurnCount` 作为唯一判据——不能用 `turnRunning` 的下降沿，一轮可能同批开始 + 结束。埋点结算同样挂到回合终态：不能在接单返回时结算，成绩是回合末才入 `pending_runs`，提前结算会变成空操作；`runTurn` 返回"是否接单"，接单失败的路径只清句柄、不结算。**加 TODO：这条队列以后挪到 Rust 端，落点就是 Thread Manager 的接单动作。** 首页"运行中的项目"快照改由 TM 的逻辑回合导出，任务侧不再单独维护一张表。
 - 决策（认证失败不再重跑整轮）：删掉 `withDirectCodexSessionRefresh` 的"刷新 + 重跑整轮"（重跑会重复落盘用户消息），登录态失效按普通回合失败呈现；用同一个包装的 `cancel_direct_codex_turn` 一并去掉。
 - 决策（失败原因本轮不落历史）：失败原因只走事件载荷与宿主诊断（`.agent/runtime/errors` + 应用日志 + 错误上报池由宿主投影写出，进池责任从前端 catch 移到宿主），不写进 `project.jsonl`——重进项目只会看到那条没有回复的用户消息。**加 TODO（暂定做法见 ADR 备选方案第 3 条 (b)）：以后要做"进历史但不喂模型"的失败条目，本轮明确不持久化。**
- 决策（CLI 保持 await）：CLI 入口（`cli.rs` 的 `direct-codex.chat`）继续 await 整轮，因为它要把回复文本打到终端、没有事件订阅可用；两个入口共用同一份接单前检查、同一个命令主体和同一份 `Display` 文案，不各写一套判据。
+- 决策（CLI 保持 await）：CLI 入口（`cli.rs` 的 `direct-codex.chat`）继续 await 整轮，因为它要把回复文本打到终端、没有事件订阅可用；两个入口共用同一份接单前检查、同一个命令主体和同一份 `Display` 文案，不各写一套判据。**（口径修正：本条已作废——2026-09-24 的 `--direct-codex-chat` 退役把 CLI 入口整个删掉，DirectProject 只剩「入队」一个命令入口；见本文件同日「命令入队化」那条与 `【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24`。）**
 - 明确不做：不给失败载荷加字段（不加 `detailRef`）；不恢复 invoke 拒绝通道，也不为"接单后的前置失败"新增事件类型；本轮不做"失败条目进历史但不喂模型"（TODO）、不做 Rust 端发送队列（TODO）。
 - 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/{direct_turn_accept.rs,direct_thread_manager.rs,direct_thread_wire.rs,direct_turn_error.rs,direct_turn_failure.rs,direct_project_context.rs,direct_runtime/{mod.rs,user_input.rs},codex_app_server/mod.rs,runtime_driver/entrypoints.rs,cli.rs}`、前端 `chat/{controller/useDirectProjectChatController.ts,controller/useDirectProjectTurnStatus.ts,controller/useDirectThreadChatSubscription.ts,conversation/directCodexConversation.ts,conversation/directThreadChat.ts,conversation/directTurnPresentation.ts}`、`chat/generated/{DirectTurnError,DirectTurnRejection,DirectThreadEvent,...}.ts` 与 `tests/{directThreadChat.test.ts,appSurface/*.suite.ts}`；文档 `docs/adr/【ADR】DirectProject命令接单化-2026-09-23.md`、`docs/technical/【实施计划】DirectProject命令接单化-2026-09-23.md`、`docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md` 与 `docs/adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md`。
 - 已知坑：`cargo test export_bindings` 会重写全部 `chat/generated/`（引号风格漂移），跑完要 `git checkout --` 掉不是本次新增的文件；本机 rust 全量 `--bins` 测试会挂在 mock server 的 `inet_csk_accept` 上，用 `--bins "agent::"` 之类过滤跑。
@@ -9598,11 +9598,14 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
  再落盘用户条目、下发用户条目、起整轮。**放行不重跑检查、不存在放行失败**，放行之后的一切失败都是回合失败，
  走既有 `turn.completed.failure`，不新增通道。kick 点 = 回合任务收尾（含 drop 守卫盖 panic）+ 中止路径 + 入队之后，
  幂等且在临界区里认领队首；入队不取 `DirectTaonierActiveInvocationGuard`（它必须整轮持有，是这一轮的调用身份）。
- 决策（前端）：不再持有队列副本，chip 只由事件投影，入队失败只由命令返回值给反馈（保留提示文案与"不丢草稿"）；
-  埋点句柄改由宿主在放行时开。
+- 决策（前端）：不再持有队列副本，chip 只由事件投影，入队失败只由命令返回值给反馈（保留提示文案与"不丢草稿"）。
+  **（落地修正，2026-09-24）**：埋点句柄仍由前端在入队那一刻生成并随命令交给宿主（放行不重算，与其它入队检查产物一起
+  存进队列条目），前端把句柄按 `clientTurnId` 存成一张表、回合终态按本轮开口条目的 canonical 身份认领结算；
+  "不丢草稿"由「提交等命令的入队结果、只有用户自己能改的入队失败才返回 false」实现（不再是"宿主在放行时开句柄"）。
 - 决策（顺带退役）：`--direct-codex-chat` 整个退役——它唯一的实际消费者是手工夹具
  `scripts/direct-execution-production-fixture.mjs`（PR #439 引入、不在 CI、无 npm/harness 注册、无测试钉它），
-  夹具一并退役；`TurnAlreadyRunning` 与前端"同一轮消息仍在处理中"分支随之删除。
+  夹具一并退役。**（落地修正，2026-09-24）**：`TurnAlreadyRunning` 的最后一个生产点在调用身份守卫里
+  （占用登记那条早已随入队化消失），所以它连同前端"同一轮消息仍在处理中"分支一起放到**守卫清理那一步**再删。
  `DirectTaonierActiveInvocationGuard` 的身份与 Thread Manager 的 `active_turn.turn_id` 是同一件事的两份记录，
  CLI 退役后让那五个读者改读 Thread Manager，再在第二步删掉守卫与它的 60 秒卡死兜底
  （删前必须保住"回合卡死可被取消解开"这条由 `d833ca9d3` 事故换来的保证）。
@@ -15,7 +15,7 @@
 | 第 1 步 命令 = 入队 | 已落地 | `enqueue_direct_codex_turn`（`+_typed`）；队列条目落在 `agent/direct_thread_queue.rs`，带上入队时产出的 `prompt` / `creation_type` / `analytics_attempt_id` |
 | 第 2 步 队列归 Thread Manager | 已落地 | `StoredEvent.pending` 产物字段 + `enqueue_pending_turn` / `remove_pending_turn` / `claim_pending_turn`；放行在 `agent/direct_turn_dispatch.rs`（`kick_direct_queue_dispatch` + `DirectTurnReservation`） |
 | 第 3 步 前端收口 | 已落地 | 见下面「第 3 步的落地细则」 |
-| 第 4 步 CLI 与夹具退役 | 待做 | |
+| 第 4 步 CLI 与夹具退役 | 已落地 | 删 `CliCommand::DirectCodexChat`（变体 / `project_path_mut` / 解析 / 派发）、`run_direct_game_creator_turn_at` 一对包装函数与夹具脚本；顺带删掉只剩测试在用的 `direct_turn_error_boundary_text`（判据只剩 `direct_turn_enqueue_failure` 一处），三条边界测试改打 `direct_turn_enqueue_failure(...).message`。**`TurnAlreadyRunning` 挪到第 5 步**（它最后一个生产点在调用身份守卫里） |
 | 第 5 步 守卫清理 | 待做 | |

 ## 第 0 步：词表切换（与代码同批，不单独提交）
@@ -165,7 +165,8 @@ Supervisor / 做方案首轮忽略 `attachments`，行为不变。
 - `chat_with_game_creator_direct_codex` 增加 `attachments: Option<Vec<DirectCodexTurnAttachment>>`，先渲染再调用现有 `run_direct_game_creator_turn_at_with_creation_type_and_emitter`
 - 把现有 Home 渲染测试迁到新文件；本文件不再保留一份平行实现

-不要把 attachments 顺着 inner turn / emitter / CLI 往下传。CLI `run_direct_game_creator_turn_at` 不变。
+不要把 attachments 顺着 inner turn / emitter 往下传。（CLI 入口 `run_direct_game_creator_turn_at` 已随命令入队化退役，见
+[`【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24`](../adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)。）

 ### 5.2 前端

@@ -38,7 +38,7 @@ Direct GUI 回合已经能看见 Codex `item/completed`，但只收成 UI 活动
 - 不拷隔离 `CODEX_HOME`、不落 `auth.json`、不落 `aggregated_output` / MCP `result` / patch `diff` / `FunctionCallOutput` 正文。
 - 不把原始 item JSON 送进 Tauri 前端事件（现有 `DirectCodexTurnObservation` 仍只允许安全活动词和流式正文）。
 - 不扫 `kind=uploaded` 历史附件；只记本轮 sidecar 提供的集合。
- DirectHome、ToolHost、CLI `--direct-codex-chat`（无 `clientTurnId`）本期不写这份账本。
+- DirectHome、ToolHost 本期不写这份账本。（`--direct-codex-chat` 已随命令入队化退役，不再是入口。）
 - 本期不改 UI，不在聊天面板展示审计。
 - 不把 issue #212 标成已修复；sidecar 与本账本是两段工作。

@@ -292,7 +292,9 @@ chat_with_game_creator_direct_codex
      → 写 turn_end + agent.db 摘要
 ```

- CLI `run_direct_game_creator_turn_at` **不** 接 audit（无 `clientTurnId`）。
+- CLI 入口已退役：`run_direct_game_creator_turn_at` 与 `--direct-codex-chat` 一起删除（见
+  [`【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24`](../adr/【ADR】DirectProject命令入队化与待发消息队列归宿主-2026-09-24.md)），
+  所以「无 `clientTurnId` 的 Direct 回合」这条路径不存在了。
 - Home command 不接 audit。
 - 不要把 attachments / audit 顺着 CLI inner、pool、ToolHost 往下传。
 - `DirectCodexTurnObservation` **不** 增加原始 `params`。审计走独立 `DirectCodexTurnAudit`，避免 stdout 正文进入 Tauri 事件。