From fbd30d7c6658deba671825dd906664c4f6aa1af1 Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Fri, 2 Oct 2026 11:17:28 +0800
Subject: [PATCH 1/9] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20UI=20=E7=BC=96?=
 =?UTF-8?q?=E8=BE=91=E5=99=A8=E5=BE=AA=E7=8E=AF=E6=B8=B8=E6=A0=87=E4=B8=8E?=
 =?UTF-8?q?=E5=A4=8D=E5=88=B6=E6=80=81=E8=A2=AB=E5=BB=B6=E8=BF=9F=20effect?=
 =?UTF-8?q?=20=E8=A6=86=E7=9B=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

界面树循环游标改为渲染期换算有效游标，不再用被动 effect 事后重置
复制路径按钮把复制态绑定到具体路径，去掉延迟重置的 effect
复制态断言改为等待异步落盘，避免同步断言抢跑
新增 useUiTreeNodeCycle 循环顺序与界面树替换重置用例
---
 .../components/UiEditorCopyPathButton.tsx     | 27 +++---
 .../src/view/ui-editor/useUiTreeNodeCycle.ts  | 24 ++++-
 .../tests/uiEditorPage.test.ts                |  3 +-
 .../tests/uiTreeNodeCycle.test.ts             | 96 +++++++++++++++++++
 4 files changed, 133 insertions(+), 17 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/tests/uiTreeNodeCycle.test.ts

diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorCopyPathButton.tsx b/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorCopyPathButton.tsx
index ea19e48bf..b33d9e62a 100644
--- a/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorCopyPathButton.tsx
+++ b/apps/ai-game-creator-shell/src/view/ui-editor/components/UiEditorCopyPathButton.tsx
@@ -1,31 +1,36 @@
 import { writeText } from '@tauri-apps/plugin-clipboard-manager';
 import { Copy } from 'lucide-react';
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
+
+type CopyState = 'idle' | 'copied' | 'failed';
 
 export function UiEditorCopyPathButton({
   relativePath,
 }: {
   relativePath: string;
 }) {
-  const [copyState, setCopyState] = useState<'idle' | 'copied' | 'failed'>(
-    'idle',
-  );
-
-  useEffect(() => setCopyState('idle'), [relativePath]);
+  // 复制态跟着具体路径走：路径变了就等于回到未复制。这里不用 effect 事后重置，
+  // 因为延迟执行的 effect 会晚于复制结果落盘，把「已复制」覆盖回未复制。
+  const [copyState, setCopyState] = useState<{
+    relativePath: string;
+    value: CopyState;
+  }>({ relativePath, value: 'idle' });
+  const value =
+    copyState.relativePath === relativePath ? copyState.value : 'idle';
 
   async function copyPath() {
-    setCopyState('idle');
+    setCopyState({ relativePath, value: 'idle' });
     try {
       await writeText(relativePath);
-      setCopyState('copied');
+      setCopyState({ relativePath, value: 'copied' });
     } catch {
-      setCopyState('failed');
+      setCopyState({ relativePath, value: 'failed' });
     }
   }
 
   return (
     <>
-      {copyState === 'failed' ? (
+      {value === 'failed' ? (
         <p className="mt-2 text-xs text-red-600" role="alert">
           复制失败，请手动复制路径。
         </p>
@@ -36,7 +41,7 @@ export function UiEditorCopyPathButton({
         onClick={() => void copyPath()}
       >
         <Copy size={14} aria-hidden="true" />
-        {copyState === 'copied' ? '已复制' : '复制路径'}
+        {value === 'copied' ? '已复制' : '复制路径'}
       </button>
     </>
   );
diff --git a/apps/ai-game-creator-shell/src/view/ui-editor/useUiTreeNodeCycle.ts b/apps/ai-game-creator-shell/src/view/ui-editor/useUiTreeNodeCycle.ts
index cb0053562..6d8c9bfb8 100644
--- a/apps/ai-game-creator-shell/src/view/ui-editor/useUiTreeNodeCycle.ts
+++ b/apps/ai-game-creator-shell/src/view/ui-editor/useUiTreeNodeCycle.ts
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useState } from 'react';
 
 import {
   getNextMatchingUiTreeNodeTarget,
@@ -9,6 +9,11 @@ import type { NodeId } from '../../features/ui-editor/types/NodeId';
 import type { UIDesignImageId } from '../../features/ui-editor/types/UIDesignImageId';
 import type { UITree } from '../../features/ui-editor/types/UITree';
 
+type UiTreeNodeCycleState = {
+  trees: UITree[];
+  cursor: UiTreeNodeCursor | null;
+};
+
 export function useUiTreeNodeCycle({
   uiTrees,
   matches,
@@ -18,9 +23,15 @@ export function useUiTreeNodeCycle({
   matches: (target: UiTreeNodeTarget) => boolean;
   onFocusNode: (treeId: UIDesignImageId, nodeId: NodeId) => void;
 }) {
-  const [lastCursor, setLastCursor] = useState<UiTreeNodeCursor | null>(null);
-
-  useEffect(() => setLastCursor(null), [uiTrees]);
+  // 界面树整体被替换时，新一轮循环要从第一项重新开始。这里把「游标属于哪一版
+  // 界面树」一起记下来，在渲染期直接换算成有效游标，而不是放进 useEffect：
+  // 被动 effect 的 flush 可能晚于紧随其后的点击，会把刚落盘的游标覆盖回 null，
+  // 让「定位下一项」反复停在第一项。
+  const [cycle, setCycle] = useState<UiTreeNodeCycleState>({
+    trees: uiTrees,
+    cursor: null,
+  });
+  const lastCursor = cycle.trees === uiTrees ? cycle.cursor : null;
 
   const focusNext = useCallback(() => {
     const target = getNextMatchingUiTreeNodeTarget(
@@ -29,7 +40,10 @@ export function useUiTreeNodeCycle({
       matches,
     );
     if (!target) return;
-    setLastCursor({ treeId: target.treeId, nodeId: target.node.id });
+    setCycle({
+      trees: uiTrees,
+      cursor: { treeId: target.treeId, nodeId: target.node.id },
+    });
     onFocusNode(target.treeId, target.node.id);
   }, [lastCursor, matches, onFocusNode, uiTrees]);
 
diff --git a/apps/ai-game-creator-shell/tests/uiEditorPage.test.ts b/apps/ai-game-creator-shell/tests/uiEditorPage.test.ts
index 0bea3af72..6575d7c54 100644
--- a/apps/ai-game-creator-shell/tests/uiEditorPage.test.ts
+++ b/apps/ai-game-creator-shell/tests/uiEditorPage.test.ts
@@ -916,7 +916,8 @@ describe('UiEditorPage', () => {
     await waitFor(() =>
       expect(writeText).toHaveBeenCalledWith('ui/generated-example.js'),
     );
-    expect(screen.getByRole('button', { name: '已复制' })).toBeTruthy();
+    // 复制态在剪贴板写入 resolve 之后才提交，必须等它落盘再断言。
+    expect(await screen.findByRole('button', { name: '已复制' })).toBeTruthy();
   });
 
   it('shows a save-success modal without a generated path', async () => {
diff --git a/apps/ai-game-creator-shell/tests/uiTreeNodeCycle.test.ts b/apps/ai-game-creator-shell/tests/uiTreeNodeCycle.test.ts
new file mode 100644
index 000000000..fe73af837
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/uiTreeNodeCycle.test.ts
@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  isNeedReview,
+  type UiTreeNodeTarget,
+} from '../src/features/ui-editor/stageStatusOverview';
+import type { Node as UiNode } from '../src/features/ui-editor/types/Node';
+import type { UITree } from '../src/features/ui-editor/types/UITree';
+import { useUiTreeNodeCycle } from '../src/view/ui-editor/useUiTreeNodeCycle';
+
+function node(
+  id: string,
+  layoutStatus: UiNode['metadata']['layout_status'],
+): UiNode {
+  return {
+    id,
+    layout: {
+      transform: {
+        anchor_min: [0, 0],
+        anchor_max: [1, 1],
+        offset_min: [0, 0],
+        offset_max: [0, 0],
+      },
+      custom_minimum_size: [0, 0],
+      size_flags_horizontal: 1,
+      size_flags_vertical: 1,
+      size_flags_stretch_ratio: 1,
+      container: 'None',
+    },
+    metadata: {
+      name: id,
+      description: '',
+      layout_status: layoutStatus,
+      component_status: 'NoProblem',
+      allow_llm_edit_layout: true,
+      allow_llm_edit_component: true,
+      source: 'System',
+    },
+    component: null,
+    children_display_mode: undefined,
+    offset: { min: [0, 0], max: [0, 0] },
+    children: [],
+  };
+}
+
+function reviewTree(): UITree {
+  return {
+    src_ui_design: 'page',
+    root: {
+      ...node('page-root', 'NoProblem'),
+      children: [
+        node('review-a', { NeedReview: '请检查 0' }),
+        node('review-b', { NeedReview: '请检查 1' }),
+        node('review-c', { NeedReview: '请检查 2' }),
+      ],
+    },
+  };
+}
+
+const matchesReviewNode = ({ node }: UiTreeNodeTarget) =>
+  isNeedReview(node.metadata.layout_status);
+
+describe('useUiTreeNodeCycle', () => {
+  it('按顺序循环待检查节点，并在界面树整体替换后重新从第一项开始', () => {
+    const uiTrees = [reviewTree()];
+    const onFocusNode = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ trees }: { trees: UITree[] }) =>
+        useUiTreeNodeCycle({
+          uiTrees: trees,
+          matches: matchesReviewNode,
+          onFocusNode,
+        }),
+      { initialProps: { trees: uiTrees } },
+    );
+
+    act(() => result.current.focusNext());
+    expect(onFocusNode).toHaveBeenLastCalledWith('page', 'review-a');
+
+    act(() => result.current.focusNext());
+    expect(onFocusNode).toHaveBeenLastCalledWith('page', 'review-b');
+
+    // 同一版界面树上的无关渲染不得重置循环游标。
+    rerender({ trees: uiTrees });
+    act(() => result.current.focusNext());
+    expect(onFocusNode).toHaveBeenLastCalledWith('page', 'review-c');
+
+    // 界面树被整体替换时，下一项回到第一项。
+    rerender({ trees: [...uiTrees] });
+    act(() => result.current.focusNext());
+    expect(onFocusNode).toHaveBeenLastCalledWith('page', 'review-a');
+  });
+});

From 6bf57c1e51e1e017aef5e474eebd8867e76b5415 Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Fri, 2 Oct 2026 11:43:17 +0800
Subject: [PATCH 2/9] =?UTF-8?q?AGC=20=E6=8A=8A=E6=89=A7=E8=A1=8C=E5=99=A8?=
 =?UTF-8?q?=E4=B8=8E=E7=BA=BF=E5=8D=8F=E8=AE=AE=E6=8B=86=E6=88=90=E6=AD=A3?=
 =?UTF-8?q?=E4=BA=A4=E7=BB=B4=E5=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AgcAgentMode 回退为仅 codex/cc，只表示执行器；新增 AgcModelProtocol 表示线协议
协议取值 openai_responses/openai_chat/anthropic，与执行器组合封闭并在校验时失败关闭
存量目录缺 protocol 时按执行器推导；历史误写的 agentMode=anthropic 读取时归一为 cc
后台 AGC 模型页拆成 Agent 模式与协议两列，新增协议下拉与对应测试
公开目录 /api/llm/models 与后台 DTO 同时下发解析后的 protocol
客户端持久化 selectedModelProtocol，选模型时按执行器推导兜底协议并校验组合
Codex wire_api 按协议在 responses/chat 间切换，不再硬编码 responses
同步 appSurface 与模型选择测试断言，补 protocol 字段
同步模型别名文档与后端架构文档的正交维度说明
---
 apps/admin-web/src/api/adminApiTypes.ts       |   8 +-
 .../src/pages/AdminAgcModelsPage.test.tsx     |  46 ++++++
 .../src/pages/AdminAgcModelsPage.tsx          |  19 ++-
 .../src/agent/codex_app_server/mod.rs         |  27 +++-
 .../src-tauri/src/commands.rs                 |  29 +++-
 .../src-tauri/src/config.rs                   |   3 +
 .../src-tauri/src/llm_catalog.rs              |   8 +
 .../src-tauri/src/main.rs                     |   7 +
 .../ConversationModelSelect.tsx               |  23 +++
 .../src/services/clientApi.ts                 |   5 +-
 .../tests/appSurface/design-agent.suite.ts    |   1 +
 .../tests/appSurface/home.suite.ts            |   1 +
 .../tests/conversationModelSelect.test.tsx    |   5 +
 ...方案】AGC后台模型别名与对话选择-2026-09-05.md |   6 +-
 ...�】server-rs与SpacetimeDB数据契约-2026-05-15.md |   2 +-
 server-rs/crates/api-server/src/agc_models.rs |  27 +++-
 server-rs/crates/api-server/src/llm/mod.rs    |  14 +-
 .../crates/module-runtime/src/agc_models.rs   | 143 ++++++++++++++++--
 .../crates/shared-contracts/src/admin.rs      |   4 +
 server-rs/crates/shared-contracts/src/llm.rs  |   3 +
 20 files changed, 346 insertions(+), 35 deletions(-)

diff --git a/apps/admin-web/src/api/adminApiTypes.ts b/apps/admin-web/src/api/adminApiTypes.ts
index c3a9e7256..1f7ffeec2 100644
--- a/apps/admin-web/src/api/adminApiTypes.ts
+++ b/apps/admin-web/src/api/adminApiTypes.ts
@@ -1075,7 +1075,11 @@ export interface AdminRechargeRefundActionResponse {
 export interface AdminWalletRestrictionResponse {
   wallet: AdminProfileWalletPayload;
 }
-export type AdminAgcAgentMode = 'codex' | 'cc' | 'anthropic';
+export type AdminAgcAgentMode = 'codex' | 'cc';
+export type AdminAgcModelProtocol =
+  | 'openai_responses'
+  | 'openai_chat'
+  | 'anthropic';
 
 export interface AdminAgcModel {
   id: string;
@@ -1083,6 +1087,8 @@ export interface AdminAgcModel {
   modelId: string;
   enabled: boolean;
   agentMode: AdminAgcAgentMode;
+  /** 上游线协议，与执行器正交。 */
+  protocol?: AdminAgcModelProtocol;
 }
 
 export interface AdminAgcModelCatalog {
diff --git a/apps/admin-web/src/pages/AdminAgcModelsPage.test.tsx b/apps/admin-web/src/pages/AdminAgcModelsPage.test.tsx
index 77b9262bb..612d21826 100644
--- a/apps/admin-web/src/pages/AdminAgcModelsPage.test.tsx
+++ b/apps/admin-web/src/pages/AdminAgcModelsPage.test.tsx
@@ -104,3 +104,49 @@ test('new models default to Codex and save the selected Agent mode', async () =>
     });
   });
 });
+
+test('协议与 Agent 模式是独立字段，可按模型单独选择', async () => {
+  const catalog = {
+    revision: 3,
+    defaultModelId: 'quality',
+    models: [
+      {
+        id: 'quality',
+        alias: '高质量',
+        modelId: 'claude-opus-5-5',
+        enabled: true,
+        agentMode: 'cc' as const,
+        protocol: 'anthropic' as const,
+      },
+    ],
+  };
+  vi.mocked(getAgcModelCatalog).mockResolvedValue(catalog);
+  vi.mocked(saveAgcModelCatalog).mockImplementation(async (_, input) => ({
+    ...input,
+    revision: 4,
+  }));
+  render(<AdminAgcModelsPage token="test" onUnauthorized={vi.fn()} />);
+  await screen.findByDisplayValue('claude-opus-5-5');
+
+  const agentMode = screen.getByLabelText('模型 1 Agent 模式') as HTMLSelectElement;
+  const protocol = screen.getByLabelText('模型 1 协议') as HTMLSelectElement;
+  expect(agentMode.value).toBe('cc');
+  expect(protocol.value).toBe('anthropic');
+  // 执行器下拉里不再混入协议取值。
+  expect(
+    Array.from(agentMode.options).map((option) => option.value),
+  ).toEqual(['codex', 'cc']);
+
+  fireEvent.change(agentMode, { target: { value: 'codex' } });
+  fireEvent.change(protocol, { target: { value: 'openai_chat' } });
+  fireEvent.click(screen.getByRole('button', { name: '保存' }));
+
+  await waitFor(() => {
+    const calls = vi.mocked(saveAgcModelCatalog).mock.calls;
+    const payload = calls[calls.length - 1]?.[1];
+    expect(payload?.models[0]).toMatchObject({
+      agentMode: 'codex',
+      protocol: 'openai_chat',
+    });
+  });
+});
diff --git a/apps/admin-web/src/pages/AdminAgcModelsPage.tsx b/apps/admin-web/src/pages/AdminAgcModelsPage.tsx
index cab805cf7..b009aa222 100644
--- a/apps/admin-web/src/pages/AdminAgcModelsPage.tsx
+++ b/apps/admin-web/src/pages/AdminAgcModelsPage.tsx
@@ -117,6 +117,7 @@ export function AdminAgcModelsPage({
           { key: 'alias', label: '别名' },
           { key: 'modelId', label: '实际模型名' },
           { key: 'agentMode', label: 'Agent 模式' },
+          { key: 'protocol', label: '协议' },
           { key: 'enabled', label: '启用' },
           { key: 'default', label: '默认' },
           { key: 'actions', label: '操作' },
@@ -157,6 +158,7 @@ export function AdminAgcModelsPage({
                             modelId: '',
                             enabled: true,
                             agentMode: 'codex',
+                            protocol: 'openai_responses',
                           },
                         ],
                       },
@@ -226,7 +228,22 @@ export function AdminAgcModelsPage({
                 >
                   <option value="codex">Codex</option>
                   <option value="cc">Claude Code</option>
-                  <option value="anthropic">Anthropic 协议</option>
+                </select>
+              </td>
+              <td>
+                <select
+                  aria-label={`模型 ${index + 1} 协议`}
+                  value={model.protocol ?? 'openai_responses'}
+                  disabled={busy}
+                  onChange={(e) =>
+                    update(model.id, {
+                      protocol: e.target.value as AdminAgcModel['protocol'],
+                    })
+                  }
+                >
+                  <option value="openai_responses">OpenAI Responses</option>
+                  <option value="openai_chat">OpenAI Chat Completions</option>
+                  <option value="anthropic">Anthropic Messages</option>
                 </select>
               </td>
               <td>
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs
index d81e102aa..3abf9ef84 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs
@@ -1971,6 +1971,28 @@ fn configure_game_creator_codex_app_server_command(
     )
 }
 
+/// Codex 的 `wire_api` 取自所选模型的线协议。
+///
+/// 单测不读全局配置：用例里没有真实的模型选择，读它会引入环境依赖，所以测试态固定
+/// `responses`，真实构建按 `selected_model_protocol` 在 `responses` / `chat` 间切换。
+fn game_creator_codex_provider_wire_api() -> &'static str {
+    #[cfg(test)]
+    {
+        "responses"
+    }
+    #[cfg(not(test))]
+    {
+        match crate::config::load_game_creator_app_config()
+            .ok()
+            .and_then(|config| config.selected_model_protocol)
+            .as_deref()
+        {
+            Some("openai_chat") => "chat",
+            _ => "responses",
+        }
+    }
+}
+
 fn configure_game_creator_codex_app_server_command_for_mode(
     command: &mut tokio::process::Command,
     llm: &GameCreatorLlmConfig,
@@ -2127,6 +2149,9 @@ fn configure_game_creator_codex_app_server_command_for_mode(
         let provider_token = provider_proxy
             .map(CodexProviderProxy::downstream_bearer_token)
             .unwrap_or(legacy_api_key);
+        // 线协议由所选模型的 `protocol` 决定：openai_chat 走 /chat/completions，
+        // 其余走 /responses。测试里不读全局配置，避免用例依赖运行环境。
+        let wire_api = game_creator_codex_provider_wire_api();
         command
             .arg("-c")
             .arg(format!(
@@ -2151,7 +2176,7 @@ fn configure_game_creator_codex_app_server_command_for_mode(
             .arg("-c")
             .arg(format!(
                 "model_providers.{GAME_CREATOR_CODEX_APP_SERVER_PROVIDER_ID}.wire_api={}",
-                quoted_toml_string("responses")?
+                quoted_toml_string(wire_api)?
             ))
             .env(GAME_CREATOR_CODEX_APP_SERVER_API_KEY_ENV, provider_token);
     }
diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
index 9be6df9bb..565de0461 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
@@ -1078,6 +1078,7 @@ fn select_game_creator_model_inner(
     model_id: String,
     is_default: bool,
     catalog_agent_mode: Option<String>,
+    catalog_protocol: Option<String>,
 ) -> Result<GameCreatorAppConfigView, String> {
     let _guard = GAME_CREATOR_CONFIG_WRITE_LOCK
         .lock()
@@ -1098,13 +1099,34 @@ fn select_game_creator_model_inner(
     if let Some(agent_mode) = catalog_agent_mode {
         config.agent_mode = match agent_mode.trim() {
             "codex" => GAME_CREATOR_AGENT_MODE_CODEX_APP_SERVER.to_string(),
-            // `cc` 是 Claude 执行器的历史别名，`anthropic` 是同一执行器的显式协议值。
-            "cc" | "anthropic" => GAME_CREATOR_AGENT_MODE_CLAUDE_CODE_CLI.to_string(),
+            "cc" => GAME_CREATOR_AGENT_MODE_CLAUDE_CODE_CLI.to_string(),
             value => return Err(format!("模型 Agent 模式无效：{value}")),
         };
     }
+    // 协议与执行器正交，但合法组合是封闭的；缺省按执行器推导。
+    let protocol = match catalog_protocol.as_deref().map(str::trim) {
+        Some("openai_responses") => "openai_responses",
+        Some("openai_chat") => "openai_chat",
+        Some("anthropic") => "anthropic",
+        Some("") | None => {
+            if config.agent_mode == GAME_CREATOR_AGENT_MODE_CLAUDE_CODE_CLI {
+                "anthropic"
+            } else {
+                "openai_responses"
+            }
+        }
+        Some(value) => return Err(format!("模型协议无效：{value}")),
+    };
+    let claude = config.agent_mode == GAME_CREATOR_AGENT_MODE_CLAUDE_CODE_CLI;
+    if claude != (protocol == "anthropic") {
+        return Err(format!(
+            "执行器与协议组合无效：{} 不支持 {protocol}",
+            config.agent_mode
+        ));
+    }
     config.selected_model_id = model_id;
     config.selected_model_is_default = is_default;
+    config.selected_model_protocol = Some(protocol.to_string());
     persist_game_creator_app_config(config, overlays, true)
 }
 
@@ -1113,8 +1135,9 @@ pub(crate) fn select_game_creator_model(
     model_id: String,
     is_default: bool,
     agent_mode: Option<String>,
+    protocol: Option<String>,
 ) -> Result<GameCreatorAppConfigView, String> {
-    select_game_creator_model_inner(model_id, is_default, agent_mode)
+    select_game_creator_model_inner(model_id, is_default, agent_mode, protocol)
 }
 
 fn persist_game_creator_app_config(
diff --git a/apps/ai-game-creator-shell/src-tauri/src/config.rs b/apps/ai-game-creator-shell/src-tauri/src/config.rs
index 6eb153861..2eaf16112 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/config.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/config.rs
@@ -4037,6 +4037,9 @@ fn merge_game_creator_config_content(
     if let Some(selected_model_is_default) = file_config.selected_model_is_default {
         config.selected_model_is_default = selected_model_is_default;
     }
+    if let Some(selected_model_protocol) = file_config.selected_model_protocol {
+        config.selected_model_protocol = Some(selected_model_protocol);
+    }
     Ok(())
 }
 
diff --git a/apps/ai-game-creator-shell/src-tauri/src/llm_catalog.rs b/apps/ai-game-creator-shell/src-tauri/src/llm_catalog.rs
index 0944e4f9f..7e89cb64f 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/llm_catalog.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/llm_catalog.rs
@@ -16,6 +16,10 @@ fn default_codex_agent_mode() -> String {
     "codex".to_string()
 }
 
+fn default_model_protocol() -> String {
+    "openai_responses".to_string()
+}
+
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
 struct WireModelSummary {
@@ -23,6 +27,9 @@ struct WireModelSummary {
     display_name: String,
     #[serde(default = "default_codex_agent_mode")]
     agent_mode: String,
+    /// 线协议与执行器正交；旧服务端不下发时按 OpenAI Responses 兼容。
+    #[serde(default = "default_model_protocol")]
+    protocol: String,
 }
 
 #[derive(Debug, Deserialize)]
@@ -56,6 +63,7 @@ fn map_catalog(catalog: WireModelCatalog) -> LlmModelsResponse {
                 id: model.id,
                 display_name: model.display_name,
                 agent_mode: model.agent_mode,
+                protocol: model.protocol,
             })
             .collect(),
         revision: catalog.revision,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index ea1b8dc56..befa993db 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -812,6 +812,9 @@ struct GameCreatorAppConfigFile {
     selected_model_id: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     selected_model_is_default: Option<bool>,
+    /// 所选模型的上游线协议，与 `agent_mode`（执行器）正交。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    selected_model_protocol: Option<String>,
 }
 
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
@@ -873,6 +876,9 @@ struct GameCreatorAppConfig {
     selected_model_id: String,
     #[serde(default)]
     selected_model_is_default: bool,
+    /// 所选模型的上游线协议；缺省按执行器推导。
+    #[serde(default)]
+    selected_model_protocol: Option<String>,
 }
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
@@ -1384,6 +1390,7 @@ impl Default for GameCreatorAppConfig {
             editor_api: GameCreatorEditorApiConfig::default(),
             selected_model_id: String::new(),
             selected_model_is_default: false,
+            selected_model_protocol: None,
         }
     }
 }
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/ConversationModelSelect.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/ConversationModelSelect.tsx
index b7b44234b..2bc9df75c 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/ConversationModelSelect.tsx
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/ConversationModelSelect.tsx
@@ -19,6 +19,22 @@ import {
   refreshLlmModelCatalog,
 } from '../../services/llmModelCatalog';
 
+/**
+ * 线协议与执行器正交；目录没下发时按执行器推导默认协议，保证发往后端的组合始终合法。
+ */
+function resolveModelProtocol(
+  model: { agentMode?: 'codex' | 'cc'; protocol?: string } | undefined,
+): 'openai_responses' | 'openai_chat' | 'anthropic' {
+  if (
+    model?.protocol === 'openai_responses' ||
+    model?.protocol === 'openai_chat' ||
+    model?.protocol === 'anthropic'
+  ) {
+    return model.protocol;
+  }
+  return model?.agentMode === 'cc' ? 'anthropic' : 'openai_responses';
+}
+
 export type ConversationModelSelectHandle = {
   /** 发送前校验：刷新目录，并在所选模型已停用/删除时回退默认模型。 */
   ensureUsable: () => Promise<boolean>;
@@ -174,6 +190,9 @@ export function ConversationModelSelect({
               agentMode:
                 catalog.models.find((model) => model.id === next)?.agentMode ??
                 'codex',
+              protocol: resolveModelProtocol(
+                catalog.models.find((model) => model.id === next),
+              ),
             }),
           );
         } catch {
@@ -341,11 +360,15 @@ export function ConversationModelSelect({
       if (!invoke) throw new Error('Native host unavailable');
       const agentMode =
         models.find((model) => model.id === id)?.agentMode ?? 'codex';
+      const protocol = resolveModelProtocol(
+        models.find((model) => model.id === id),
+      );
       const result = await queueConfigWrite(() =>
         invoke<GameCreatorAppConfigView>('select_game_creator_model', {
           modelId: id,
           isDefault: false,
           agentMode,
+          protocol,
         }),
       );
       if (result.config.selectedModelId !== id)
diff --git a/apps/ai-game-creator-shell/src/services/clientApi.ts b/apps/ai-game-creator-shell/src/services/clientApi.ts
index 2221e5cfd..5c1bff3cc 100644
--- a/apps/ai-game-creator-shell/src/services/clientApi.ts
+++ b/apps/ai-game-creator-shell/src/services/clientApi.ts
@@ -3,7 +3,10 @@ import { resolveTauriInvoke } from '../app/tauri';
 export type ClientLlmModel = {
   displayName: string;
   id: string;
-  agentMode: 'codex' | 'cc' | 'anthropic';
+  /** 执行器：codex 或 cc。线协议是与之正交的独立维度。 */
+  agentMode: 'codex' | 'cc';
+  /** 上游线协议；服务端未下发时按执行器的默认协议解释。 */
+  protocol?: 'openai_responses' | 'openai_chat' | 'anthropic';
 };
 
 export type ClientLlmModelCatalog = {
diff --git a/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
index 15ec5f80d..d96c09714 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
@@ -282,6 +282,7 @@ export function registerDesignAgentSurfaceTests() {
         modelId: 'fast',
         isDefault: false,
         agentMode: 'codex',
+        protocol: 'openai_responses',
       });
       expect(
         screen.getByRole('button', { name: '对话模型' }).textContent,
diff --git a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
index 912be89a7..c0c9a5327 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
@@ -149,6 +149,7 @@ export function registerClientHomeTests() {
         modelId: 'fast',
         isDefault: false,
         agentMode: 'codex',
+        protocol: 'openai_responses',
       }),
     );
     expect(modelTrigger.textContent).toContain('快速');
diff --git a/apps/ai-game-creator-shell/tests/conversationModelSelect.test.tsx b/apps/ai-game-creator-shell/tests/conversationModelSelect.test.tsx
index 9208b832b..c2a5c252f 100644
--- a/apps/ai-game-creator-shell/tests/conversationModelSelect.test.tsx
+++ b/apps/ai-game-creator-shell/tests/conversationModelSelect.test.tsx
@@ -130,6 +130,7 @@ test('custom mode only shows checked endpoint model IDs and never requests the p
     modelId: 'vendor/fast:latest',
     isDefault: false,
     agentMode: 'codex',
+    protocol: 'openai_responses',
   });
 });
 
@@ -290,6 +291,7 @@ test('only displays aliases and persists selection through the native command',
       modelId: 'fast',
       isDefault: false,
       agentMode: 'cc',
+      protocol: 'anthropic',
     }),
   );
   await waitFor(() => expect(onReady).toHaveBeenLastCalledWith(true));
@@ -320,6 +322,7 @@ test('falls back to the default model when the saved selection was removed', asy
     modelId: 'quality',
     isDefault: true,
     agentMode: 'codex',
+    protocol: 'openai_responses',
   });
   expect(
     screen.getByRole('button', { name: '对话模型' }).textContent,
@@ -529,6 +532,7 @@ test('pre-send validation falls back when the selected model is disabled', async
     modelId: 'quality',
     isDefault: true,
     agentMode: 'codex',
+    protocol: 'openai_responses',
   });
 });
 
@@ -554,6 +558,7 @@ test('follows the new server default when the saved selection was the default',
     modelId: 'fast',
     isDefault: true,
     agentMode: 'cc',
+    protocol: 'anthropic',
   });
   expect(
     screen.getByRole('button', { name: '对话模型' }).textContent,
diff --git a/docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md b/docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md
index 347575fbf..d14ae6087 100644
--- a/docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md
+++ b/docs/technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md
@@ -55,8 +55,10 @@
 
 ## 模型绑定 Agent 执行模式
 
-- 后台 AGC 模型目录每项新增 `agentMode`，接受 `codex`、`cc` 与 `anthropic`；缺少该字段的历史目录按 `codex` 解释，后台新增模型默认 `codex`。`anthropic` 是 2026-10-01 新增的显式 Anthropic Messages 协议值，`cc` 保留为同一 Claude 执行器的历史别名（两者都映射到 `claude_code_cli`），新目录项应直接写 `anthropic`。
-- 2026-10-01 补充：`cc`/`anthropic` 一律经平台 LLM 网关的独立 Anthropic 路由 `POST /api/llm/anthropic/{*path}`，客户端 `ANTHROPIC_BASE_URL` 为 `{apiBaseUrl}/api/llm/anthropic`，不得再用配置里的 `llm.baseUrl`（那是 Router 地址，平台不会把账号 Router key 下发给客户端）。Claude Agent SDK 自己拼 `{base}/v1/messages` 并带 `authorization: bearer` 与 `anthropic-version`，网关据此转发上游 `{routerBase}/v1/messages`。
+- 后台 AGC 模型目录每项新增 `agentMode`，只接受 `codex` 与 `cc`；缺少该字段的历史目录按 `codex` 解释，后台新增模型默认 `codex`。
+- 2026-10-01 修正（原先误把协议塞进 `agentMode`）：**执行器与线协议是两个正交维度**。目录新增独立字段 `protocol`，取值 `openai_responses` / `openai_chat` / `anthropic`；`agentMode` 只表示客户端启动哪个执行器。合法组合是封闭的——`codex` 只能用 `openai_responses` 或 `openai_chat`，`cc` 只能用 `anthropic`，其余组合在后台保存与目录加载时都失败关闭。存量目录缺少 `protocol` 时按执行器推导（codex → `openai_responses`，cc → `anthropic`）；历史误写的 `agentMode: "anthropic"` 读取时归一到 `cc`。
+- 选路由协议决定：`openai_responses` → `/api/llm/v1/responses`，`openai_chat` → `/api/llm/v1/chat/completions`，`anthropic` → 独立路由 `/api/llm/anthropic/{*path}`。客户端把所选模型的协议与执行器一起持久化（`agentMode` + `selectedModelProtocol`），Codex 的 `wire_api` 按协议在 `responses` / `chat` 间切换。
+- 2026-10-01 补充：`cc` 一律经平台 LLM 网关的独立 Anthropic 路由，客户端 `ANTHROPIC_BASE_URL` 为 `{apiBaseUrl}/api/llm/anthropic`，不得再用配置里的 `llm.baseUrl`（那是 Router 地址，平台不会把账号 Router key 下发给客户端）。Claude Agent SDK 自己拼 `{base}/v1/messages` 并带 `authorization: bearer` 与 `anthropic-version`，网关据此转发上游 `{routerBase}/v1/messages`。
 - `codex` 仍表示现有 AGC Codex app-server 执行链路；`cc` 表示 AGC 客户端启动随包的 Claude Agent SDK sidecar，模型的 `modelId` 原样作为 Claude Agent SDK 的模型标识，不把 Claude 协议伪装成 OpenAI Responses。sidecar 随 AGC 安装包携带 SDK 及匹配平台的 Claude Code runtime，用户不需要预先安装 `claude` 命令。
 - `/api/llm/models` 的启用模型摘要返回 `agentMode`，后台完整目录、管理 DTO 和客户端目录保持同一绑定快照。客户端在选择模型时同时持久化模型 ID 与执行模式；默认模型变化、模型被停用或目录刷新回退时一并更新执行模式。
 - 客户端设置保存不得把后台模型绑定覆盖回 Codex。旧客户端配置缺少执行模式时继续按 Codex 运行；旧后台响应缺少 `agentMode` 时客户端按 Codex 兼容。
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index fb31bb682..94f2a7a51 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -536,7 +536,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - 私有单例表，主键 `id=0`，保存 `catalog_json`、`revision`、`updated_at`；不存凭据。
 - `read_agc_model_catalog` / `save_agc_model_catalog` 只接受已登记的 runtime service identity，保存使用 revision 乐观锁；缺行时读取返回 `AGC_MODEL_CATALOG_NOT_INITIALIZED`，不返回任何内置目录。
 - 目录初始值来自上游同步：api-server（API/All 角色）启动时若目录缺失、结构与当前定义不符或校验不通过，就用分组定价列表 `GET {Router 控制面}/api/pricing?group=taonier`（公开只读、不带凭据）的 `data[].model_name` 生成目录（`id` 为模型名 slug，`alias`/`modelId` 为上游原名），失败只记录 error、不写替代目录，由下一次启动重试；未初始化期间 AGC 目录与对话接口、后台目录接口都失败关闭（`503`）。
-- 后台 owner 通过 `GET/PUT /admin/api/agc-models` 管理稳定标识、必填别名、实际模型名、启用状态和默认项；客户端 `GET /api/llm/models` 仅返回启用项的稳定标识、别名和目录 `revision`（供条件刷新，不暴露实际模型名）。
+- 后台 owner 通过 `GET/PUT /admin/api/agc-models` 管理稳定标识、必填别名、实际模型名、启用状态、默认项，以及**执行器 `agentMode` 与线协议 `protocol` 两个正交维度**：`agentMode` 只取 `codex` / `cc`，`protocol` 只取 `openai_responses` / `openai_chat` / `anthropic`，合法组合封闭（codex ⇒ responses/chat，cc ⇒ anthropic），非法组合在保存与加载两侧都失败关闭；存量目录缺 `protocol` 时按执行器推导。客户端 `GET /api/llm/models` 返回启用项的稳定标识、别名、`agentMode`、解析后的 `protocol` 和目录 `revision`（供条件刷新，不暴露实际模型名）。
 - Responses / Chat 请求按目录解析模型；未知或停用项拒绝。AGC 的 `platform-default` 请求标识使用目录默认项。详细契约见 `technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md`。
 
 ### `error_report`
diff --git a/server-rs/crates/api-server/src/agc_models.rs b/server-rs/crates/api-server/src/agc_models.rs
index 391e32f5f..4875fec63 100644
--- a/server-rs/crates/api-server/src/agc_models.rs
+++ b/server-rs/crates/api-server/src/agc_models.rs
@@ -9,6 +9,7 @@ use axum::{
 };
 use module_runtime::{
     AGC_MODEL_CATALOG_CONFLICT, AGC_MODEL_CATALOG_NOT_INITIALIZED, AgcAgentMode, AgcModelCatalog,
+    AgcModelProtocol,
 };
 use shared_contracts::admin::{AdminAgcModel, AdminAgcModelCatalog};
 use spacetime_client::SpacetimeClientError;
@@ -235,12 +236,21 @@ pub async fn admin_save_agc_models(
             let agent_mode = AgcAgentMode::parse(&m.agent_mode).map_err(|message| {
                 AppError::from_status(StatusCode::BAD_REQUEST).with_message(message)
             })?;
+            let protocol = m
+                .protocol
+                .as_deref()
+                .map(AgcModelProtocol::parse)
+                .transpose()
+                .map_err(|message| {
+                    AppError::from_status(StatusCode::BAD_REQUEST).with_message(message)
+                })?;
             Ok(module_runtime::AgcModel {
                 id: m.id,
                 alias: m.alias,
                 model_id: m.model_id,
                 enabled: m.enabled,
                 agent_mode,
+                protocol,
             })
         })
         .collect::<Result<Vec<_>, AppError>>()?;
@@ -277,12 +287,17 @@ fn catalog_dto(catalog: AgcModelCatalog) -> AdminAgcModelCatalog {
         models: catalog
             .models
             .into_iter()
-            .map(|m| AdminAgcModel {
-                id: m.id,
-                alias: m.alias,
-                model_id: m.model_id,
-                enabled: m.enabled,
-                agent_mode: m.agent_mode.as_str().to_string(),
+            .map(|m| {
+                // 回读给出解析后的具体协议，后台不会看到空值。
+                let protocol = m.resolved_protocol().as_str().to_string();
+                AdminAgcModel {
+                    id: m.id,
+                    alias: m.alias,
+                    model_id: m.model_id,
+                    enabled: m.enabled,
+                    agent_mode: m.agent_mode.as_str().to_string(),
+                    protocol: Some(protocol),
+                }
             })
             .collect(),
     }
diff --git a/server-rs/crates/api-server/src/llm/mod.rs b/server-rs/crates/api-server/src/llm/mod.rs
index 3ff4dc75c..b97a8da5d 100644
--- a/server-rs/crates/api-server/src/llm/mod.rs
+++ b/server-rs/crates/api-server/src/llm/mod.rs
@@ -198,11 +198,15 @@ fn public_model_catalog(catalog: module_runtime::AgcModelCatalog) -> LlmModelsRe
             .models
             .into_iter()
             .filter(|model| model.enabled)
-            .map(|model| LlmModelSummary {
-                id: model.id,
-                // 初始目录里别名就是上游原始模型名（不再填“高质量/快速”这类人工别名）。
-                display_name: model.alias,
-                agent_mode: model.agent_mode.as_str().to_string(),
+            .map(|model| {
+                let protocol = model.resolved_protocol().as_str().to_string();
+                LlmModelSummary {
+                    id: model.id,
+                    // 初始目录里别名就是上游原始模型名（不再填“高质量/快速”这类人工别名）。
+                    display_name: model.alias,
+                    agent_mode: model.agent_mode.as_str().to_string(),
+                    protocol,
+                }
             })
             .collect(),
         revision: catalog.revision,
diff --git a/server-rs/crates/module-runtime/src/agc_models.rs b/server-rs/crates/module-runtime/src/agc_models.rs
index e4ff1c5fb..a6d406afc 100644
--- a/server-rs/crates/module-runtime/src/agc_models.rs
+++ b/server-rs/crates/module-runtime/src/agc_models.rs
@@ -16,10 +16,10 @@ pub const AGC_MODEL_CATALOG_MAX_MODELS: usize = 32;
 #[serde(rename_all = "lowercase")]
 pub enum AgcAgentMode {
     Codex,
+    /// `anthropic` 是早期把协议混进执行器时写下的历史取值，读取时归一到 `cc`；
+    /// 协议本身由 `AgcModel.protocol` 表达。
+    #[serde(alias = "anthropic")]
     Cc,
-    /// 显式 Anthropic Messages 协议。`cc` 是同一执行器的历史别名，
-    /// 新目录项应直接写 `anthropic`。
-    Anthropic,
 }
 
 impl Default for AgcAgentMode {
@@ -33,7 +33,6 @@ impl AgcAgentMode {
         match self {
             Self::Codex => "codex",
             Self::Cc => "cc",
-            Self::Anthropic => "anthropic",
         }
     }
 
@@ -41,8 +40,68 @@ impl AgcAgentMode {
         match value {
             "codex" => Ok(Self::Codex),
             "cc" => Ok(Self::Cc),
+            _ => Err("Agent 模式只允许 codex 或 cc".into()),
+        }
+    }
+
+    /// 该执行器允许的线协议。协议与执行器是正交维度，但合法组合是封闭的：
+    /// Codex 只能走 OpenAI Responses / Chat Completions，Claude Code 只能走
+    /// Anthropic Messages。
+    pub const fn supports(self, protocol: AgcModelProtocol) -> bool {
+        match self {
+            Self::Codex => matches!(
+                protocol,
+                AgcModelProtocol::OpenAiResponses | AgcModelProtocol::OpenAiChat
+            ),
+            Self::Cc => matches!(protocol, AgcModelProtocol::Anthropic),
+        }
+    }
+
+    /// 存量目录缺少协议字段时按执行器的默认线协议解释。
+    pub const fn default_protocol(self) -> AgcModelProtocol {
+        match self {
+            Self::Codex => AgcModelProtocol::OpenAiResponses,
+            Self::Cc => AgcModelProtocol::Anthropic,
+        }
+    }
+}
+
+/// 上游线协议，与执行器正交。
+///
+/// `openai_responses` / `openai_chat` 走 `/api/llm/v1/responses` 与
+/// `/api/llm/v1/chat/completions`；`anthropic` 走独立的
+/// `/api/llm/anthropic/{*path}`。
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AgcModelProtocol {
+    #[serde(rename = "openai_responses")]
+    OpenAiResponses,
+    #[serde(rename = "openai_chat")]
+    OpenAiChat,
+    #[serde(rename = "anthropic")]
+    Anthropic,
+}
+
+impl Default for AgcModelProtocol {
+    fn default() -> Self {
+        Self::OpenAiResponses
+    }
+}
+
+impl AgcModelProtocol {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::OpenAiResponses => "openai_responses",
+            Self::OpenAiChat => "openai_chat",
+            Self::Anthropic => "anthropic",
+        }
+    }
+
+    pub fn parse(value: &str) -> Result<Self, String> {
+        match value {
+            "openai_responses" => Ok(Self::OpenAiResponses),
+            "openai_chat" => Ok(Self::OpenAiChat),
             "anthropic" => Ok(Self::Anthropic),
-            _ => Err("Agent 模式只允许 codex、cc 或 anthropic".into()),
+            _ => Err("协议只允许 openai_responses、openai_chat 或 anthropic".into()),
         }
     }
 }
@@ -57,6 +116,18 @@ pub struct AgcModel {
     /// 绑定 AGC 客户端实际启动的 Agent，存量目录缺失时兼容为 Codex。
     #[serde(default)]
     pub agent_mode: AgcAgentMode,
+    /// 上游线协议。存量目录缺失时按 `agent_mode` 的默认协议解释；
+    /// 保存时必须与 `agent_mode` 组成合法组合。
+    #[serde(default)]
+    pub protocol: Option<AgcModelProtocol>,
+}
+
+impl AgcModel {
+    /// 显式协议优先，缺失时回退到执行器的默认协议。
+    pub fn resolved_protocol(&self) -> AgcModelProtocol {
+        self.protocol
+            .unwrap_or_else(|| self.agent_mode.default_protocol())
+    }
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
@@ -97,6 +168,7 @@ impl AgcModelCatalog {
                 model_id,
                 enabled: true,
                 agent_mode: AgcAgentMode::default(),
+                protocol: None,
             });
         }
         let default_model_id = entries
@@ -147,6 +219,14 @@ impl AgcModelCatalog {
             {
                 return Err("实际模型名不能为空，长度不能超过 200 字节".into());
             }
+            let protocol = model.resolved_protocol();
+            if !model.agent_mode.supports(protocol) {
+                return Err(format!(
+                    "Agent 模式 {} 不支持协议 {}：Codex 只能用 openai_responses / openai_chat，Claude Code 只能用 anthropic",
+                    model.agent_mode.as_str(),
+                    protocol.as_str()
+                ));
+            }
         }
         self.resolve(&self.default_model_id).map(|_| ())
     }
@@ -235,6 +315,7 @@ mod tests {
             model_id: model_id.into(),
             enabled: true,
             agent_mode: AgcAgentMode::default(),
+            protocol: None,
         }
     }
 
@@ -345,20 +426,13 @@ mod tests {
     }
 
     #[test]
-    fn catalog_agent_mode_accepts_codex_cc_and_anthropic_only() {
+    fn catalog_agent_mode_rejects_values_outside_codex_and_cc() {
         let mut catalog =
             AgcModelCatalog::from_upstream_models(upstream(&["model-a", "model-b"]), 0).unwrap();
         catalog.models[0].agent_mode = AgcAgentMode::Cc;
         assert!(catalog.validate().is_ok());
         assert_eq!(catalog.models[0].agent_mode.as_str(), "cc");
-
-        catalog.models[0].agent_mode = AgcAgentMode::Anthropic;
-        assert!(catalog.validate().is_ok());
-        assert_eq!(catalog.models[0].agent_mode.as_str(), "anthropic");
-        assert_eq!(
-            AgcAgentMode::parse("anthropic").unwrap(),
-            AgcAgentMode::Anthropic
-        );
+        assert!(AgcAgentMode::parse("anthropic").is_err());
 
         let invalid: Result<AgcModelCatalog, _> = serde_json::from_str(
             r#"{"revision":0,"defaultModelId":"model-a","models":[{"id":"model-a","alias":"model-a","modelId":"model-a","enabled":true,"agentMode":"provider"}]}"#,
@@ -366,6 +440,47 @@ mod tests {
         assert!(invalid.is_err());
     }
 
+    #[test]
+    fn protocol_is_orthogonal_to_agent_mode_and_pairs_are_closed() {
+        // 协议缺省按执行器推导：codex -> openai_responses，cc -> anthropic。
+        let mut catalog =
+            AgcModelCatalog::from_upstream_models(upstream(&["model-a", "model-b"]), 0).unwrap();
+        assert_eq!(
+            catalog.models[0].resolved_protocol(),
+            AgcModelProtocol::OpenAiResponses
+        );
+        catalog.models[0].agent_mode = AgcAgentMode::Cc;
+        assert_eq!(
+            catalog.models[0].resolved_protocol(),
+            AgcModelProtocol::Anthropic
+        );
+        assert_eq!(
+            AgcModelProtocol::parse("anthropic").unwrap().as_str(),
+            "anthropic"
+        );
+
+        // codex 支持两种 OpenAI 线协议。
+        catalog.models[0].agent_mode = AgcAgentMode::Codex;
+        catalog.models[0].protocol = Some(AgcModelProtocol::OpenAiChat);
+        assert!(catalog.validate().is_ok());
+        catalog.models[0].protocol = Some(AgcModelProtocol::OpenAiResponses);
+        assert!(catalog.validate().is_ok());
+
+        // 非法组合必须失败关闭：codex + anthropic。
+        catalog.models[0].protocol = Some(AgcModelProtocol::Anthropic);
+        let error = catalog
+            .validate()
+            .expect_err("codex must reject the anthropic protocol");
+        assert!(error.contains("不支持协议"), "{error}");
+
+        // cc 只支持 anthropic。
+        catalog.models[0].agent_mode = AgcAgentMode::Cc;
+        catalog.models[0].protocol = Some(AgcModelProtocol::OpenAiChat);
+        assert!(catalog.validate().is_err());
+        catalog.models[0].protocol = Some(AgcModelProtocol::Anthropic);
+        assert!(catalog.validate().is_ok());
+    }
+
     #[test]
     fn catalog_rejects_duplicate_aliases_and_ids() {
         let mut catalog =
diff --git a/server-rs/crates/shared-contracts/src/admin.rs b/server-rs/crates/shared-contracts/src/admin.rs
index 0309a831d..ad9d7af64 100644
--- a/server-rs/crates/shared-contracts/src/admin.rs
+++ b/server-rs/crates/shared-contracts/src/admin.rs
@@ -1663,6 +1663,10 @@ pub struct AdminAgcModel {
     /// 旧后台请求缺失时按 Codex 兼容。
     #[serde(default = "default_codex_agent_mode")]
     pub agent_mode: String,
+    /// 上游线协议，与 `agent_mode` 正交。缺省时按 `agent_mode` 的默认协议解释，
+    /// 服务端回读时始终给出解析后的具体值。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub protocol: Option<String>,
 }
 
 #[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
diff --git a/server-rs/crates/shared-contracts/src/llm.rs b/server-rs/crates/shared-contracts/src/llm.rs
index 0b958f23f..a02708cf7 100644
--- a/server-rs/crates/shared-contracts/src/llm.rs
+++ b/server-rs/crates/shared-contracts/src/llm.rs
@@ -65,7 +65,10 @@ mod tests {
 pub struct LlmModelSummary {
     pub display_name: String,
     pub id: String,
+    /// 执行器：`codex` 或 `cc`。
     pub agent_mode: String,
+    /// 上游线协议，与执行器正交：`openai_responses` / `openai_chat` / `anthropic`。
+    pub protocol: String,
 }
 
 #[derive(Debug, serde::Serialize)]

From 98cb0d237e95be27266b3437e5c51784f9c326f5 Mon Sep 17 00:00:00 2001
From: Linghong <ink29535@proton.me>
Date: Fri, 2 Oct 2026 12:56:55 +0800
Subject: [PATCH 3/9] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=9B=BA=E5=AE=9A?=
 =?UTF-8?q?=E8=AF=95=E7=8E=A9=E8=AF=AF=E5=88=A4=E7=A5=96=E5=85=88=E6=8C=87?=
 =?UTF-8?q?=E9=92=88=E7=A9=BF=E9=80=8F=E6=A0=B7=E5=BC=8F=EF=BC=88#547?=
 =?UTF-8?q?=EF=BC=89=20(#583)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

关联 #547。

固定试玩将任意祖先的 `pointer-events:none` 累计为按钮禁用，导致覆盖层穿透、按钮恢复 `auto` 的合法布局在实际点击前被拒绝。现在只检查目标控件自身的计算样式；未覆盖的继承 `none` 仍拒绝，原有命中、可见性、disabled、aria-disabled、inert 和真实输入校验保持有效。

复用现有浏览器夹具，补充双视口穿透布局回归及九种不可用控件拒绝场景，并同步场景指纹快照、技术方案和共享排障记录。

验证：
- 修复前真实 Chrome 在 desktop/mobile 均复现 start 被误判 disabled；修复后合法布局完整通过开始、主要操作和重开，sequence 从 0 到 3、最终 phase 为 ready。
- 浏览器模块单元测试：27 passed；14 个真实浏览器测试默认 ignored，其中本次显式执行并通过 4 个相关用例（新增 2 个，已有 2 个）。新增拒绝用例在双视口覆盖继承 none、目标 none、目标 none/子元素 auto、disabled、禁用 fieldset、aria-disabled、inert、隐藏和遮挡。
- rustfmt、编码检查、文档索引检查、git diff --check 通过；完成独立代码审查。

验证边界：未运行全量测试；当前工作区未找到现场游戏导出，尚未复核该游戏开始流程。generic 的 mobile 结果为移动视口下的真实鼠标输入，未进行真实触摸验收。

Reviewed-on: https://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/583
Co-authored-by: Linghong <ink29535@proton.me>
Co-committed-by: Linghong <ink29535@proton.me>
---
 .../src-tauri/src/browser/playtest/mod.rs     |   4 +-
 .../src-tauri/src/browser/tests.rs            | 134 ++++++++++++++++--
 docs/project-memory/shared-memory/pitfalls.md |   5 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   6 +
 4 files changed, 135 insertions(+), 14 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/browser/playtest/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/browser/playtest/mod.rs
index df4619c02..1df7ccf9a 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/browser/playtest/mod.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/browser/playtest/mod.rs
@@ -422,7 +422,8 @@ pub(super) const PROBE_PLAYTEST_CONTROL_SCRIPT: &str = r#"function() {
   }
 
   let stylesVisible = true;
-  let pointerBlocked = false;
+  // 后代可用 auto 覆盖祖先的 none；未覆盖时计算样式仍会继承 none。
+  const pointerBlocked = getComputedStyle(this).pointerEvents === 'none';
   for (let current = this; current instanceof HTMLElement; current = current.parentElement) {
     const style = getComputedStyle(current);
     const opacity = Number.parseFloat(style.opacity);
@@ -431,7 +432,6 @@ pub(super) const PROBE_PLAYTEST_CONTROL_SCRIPT: &str = r#"function() {
       && style.visibility !== 'hidden'
       && style.visibility !== 'collapse'
       && (Number.isNaN(opacity) || opacity > 0);
-    pointerBlocked ||= style.pointerEvents === 'none';
   }
 
   const rect = this.getBoundingClientRect();
diff --git a/apps/ai-game-creator-shell/src-tauri/src/browser/tests.rs b/apps/ai-game-creator-shell/src-tauri/src/browser/tests.rs
index 0d98e7c97..9d8733862 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/browser/tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/browser/tests.rs
@@ -270,16 +270,12 @@ fn playtest_scenario_fingerprints_are_fixed_lowercase_sha256_values() {
     let tetris = browser_playtest_scenario_fingerprint(BrowserPlaytestScenario::TetrisV1);
     let lane = browser_playtest_scenario_fingerprint(BrowserPlaytestScenario::LaneDefenseV1);
     assert_eq!(
-        generic,
-        "e5e1b4d01e39cb7b0dd2fd5a56982c3ddf825a926738d99152875ee1ff412a8d"
-    );
-    assert_eq!(
-        tetris,
-        "b3c49f43f70291ea5c9431a21bb751fead2e244c8e97fecec20ee3e38215a59c"
-    );
-    assert_eq!(
-        lane,
-        "6a24072ce7a570dd29edac0ca3fa905546140e44ca4ab6412d8fc7fe1239aa5a"
+        [generic.as_str(), tetris.as_str(), lane.as_str()],
+        [
+            "85e7ec677411745ad3a7385db67a2c89441cb2ccc12a7a1853bb87ba74f15e0d",
+            "60c202a9fe6313dd414365db52df8b5b63110971f89708ac1563d531f510f4ff",
+            "a3120c8cf585f2e06091229c3b7c3a5bd8aa08821704064edc611297ee54f466",
+        ]
     );
     assert!(generic.bytes().all(|byte| byte.is_ascii_hexdigit()));
     assert!(tetris.bytes().all(|byte| byte.is_ascii_hexdigit()));
@@ -1354,7 +1350,7 @@ async fn real_chrome_generic_playtest_rejects_one_frame_playing_state() {
 #[tokio::test]
 #[ignore = "requires an installed Chrome/Chromium/Edge and explicit local browser execution"]
 async fn real_chrome_generic_playtest_accepts_earlier_window_capture_stop_immediate_flow() {
-    let result = run_stable_generic_viewport_fixture(false).await;
+    let result = run_stable_generic_viewport_fixture(false, None).await;
     assert!(
         result.passed,
         "diagnostics={:#?}\nviewports={:#?}",
@@ -1388,7 +1384,7 @@ async fn real_chrome_generic_playtest_accepts_earlier_window_capture_stop_immedi
 #[tokio::test]
 #[ignore = "requires an installed Chrome/Chromium/Edge and explicit local browser execution"]
 async fn real_chrome_generic_playtest_rejects_mobile_only_unwired_control() {
-    let result = run_stable_generic_viewport_fixture(true).await;
+    let result = run_stable_generic_viewport_fixture(true, None).await;
     assert!(
         !result.passed,
         "a successful desktop cannot hide mobile gameplay failure"
@@ -1410,8 +1406,117 @@ async fn real_chrome_generic_playtest_rejects_mobile_only_unwired_control() {
         .any(|message| message.starts_with("playtest mobile:")));
 }
 
+#[tokio::test]
+#[ignore = "requires an installed Chrome/Chromium/Edge and explicit local browser execution"]
+async fn real_chrome_generic_playtest_pointer_events_allows_auto_under_none() {
+    let result = run_stable_generic_viewport_fixture(
+        false,
+        Some(
+            r#"<div style="pointer-events:none;padding:20px">
+          <button type="button" data-playtest-id="start" style="pointer-events:auto;padding:0">
+            <span style="display:block;padding:20px">Start</span>
+          </button>
+        </div>"#,
+        ),
+    )
+    .await;
+    assert!(result.passed, "{:?}", result.diagnostics);
+    for viewport in REQUIRED_VIEWPORTS {
+        let playtest = &result
+            .viewport_playtests
+            .iter()
+            .find(|entry| entry.viewport == viewport)
+            .expect("each viewport must have gameplay evidence")
+            .result;
+        assert!(playtest.passed, "{viewport:?}: {:?}", playtest.diagnostics);
+        assert_eq!(playtest.initial_sequence, Some(0));
+        assert_eq!(playtest.final_sequence, Some(3));
+        assert_eq!(playtest.final_phase, Some(BrowserPlaytestPhase::Ready));
+        assert!(playtest.assertions.iter().all(|assertion| assertion.passed));
+    }
+}
+
+#[tokio::test]
+#[ignore = "requires an installed Chrome/Chromium/Edge and explicit local browser execution"]
+async fn real_chrome_generic_playtest_pointer_events_keeps_unavailable_controls_blocked() {
+    for (case, markup) in [
+        (
+            "inherited-none",
+            r#"<div style="pointer-events:none"><button data-playtest-id="start">Start</button></div>"#,
+        ),
+        (
+            "own-none",
+            r#"<button data-playtest-id="start" style="pointer-events:none">Start</button>"#,
+        ),
+        (
+            "own-none-child-auto",
+            r#"<button data-playtest-id="start" style="pointer-events:none;padding:0"><span style="pointer-events:auto;display:block;padding:20px">Start</span></button>"#,
+        ),
+        (
+            "disabled",
+            r#"<button data-playtest-id="start" disabled>Start</button>"#,
+        ),
+        (
+            "disabled-fieldset",
+            r#"<fieldset disabled><button data-playtest-id="start">Start</button></fieldset>"#,
+        ),
+        (
+            "aria-disabled",
+            r#"<button data-playtest-id="start" aria-disabled="true">Start</button>"#,
+        ),
+        (
+            "inert",
+            r#"<div inert><button data-playtest-id="start" style="pointer-events:auto">Start</button></div>"#,
+        ),
+        (
+            "hidden",
+            r#"<div style="display:none"><button data-playtest-id="start">Start</button></div>"#,
+        ),
+        (
+            "covered",
+            r#"<div style="position:relative;width:max-content"><button data-playtest-id="start">Start</button><div style="position:absolute;inset:0;background:black"></div></div>"#,
+        ),
+    ] {
+        let result = run_stable_generic_viewport_fixture(false, Some(markup)).await;
+        assert!(!result.passed, "{case} must fail");
+        for viewport in REQUIRED_VIEWPORTS {
+            let playtest = &result
+                .viewport_playtests
+                .iter()
+                .find(|entry| entry.viewport == viewport)
+                .expect("each viewport must have gameplay evidence")
+                .result;
+            assert!(!playtest.passed, "{case} / {viewport:?} must fail");
+            assert!(
+                playtest
+                    .diagnostics
+                    .iter()
+                    .any(|message| message.contains("固定试玩控件 start")),
+                "{case} / {viewport:?}: {:?}",
+                playtest.diagnostics
+            );
+            assert!(
+                playtest.assertions.iter().any(|assertion| {
+                    assertion.name == "start-control-clicked" && !assertion.passed
+                }),
+                "{case} / {viewport:?} must be rejected before input"
+            );
+            if case == "own-none-child-auto" {
+                assert!(
+                    playtest.diagnostics.iter().any(|message| {
+                        message == "固定试玩控件 start 处于 disabled 状态"
+                    }),
+                    "{viewport:?}: child hit must not enable the pointer-blocked target: {:?}",
+                    playtest.diagnostics
+                );
+            }
+        }
+    }
+}
+
 async fn run_stable_generic_viewport_fixture(
     mobile_action_broken: bool,
+    start_markup: Option<&str>,
 ) -> BrowserValidationResult {
     use std::io::{Read, Write};
     use std::net::TcpListener;
@@ -1482,6 +1587,11 @@ async fn run_stable_generic_viewport_fixture(
 </body>
 </html>"#;
     let html = String::from_utf8_lossy(html)
+        .replace(
+            r#"<button type="button" data-playtest-id="start">Start</button>"#,
+            start_markup
+                .unwrap_or(r#"<button type="button" data-playtest-id="start">Start</button>"#),
+        )
         .replace(
             "const mobileActionBroken = false;",
             if mobile_action_broken {
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index ef8834e21..bd5b91ae2 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -2,6 +2,11 @@
 
 这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。
 
+## 2026-10-02 固定试玩误判祖先的指针穿透样式
+
+- `pointer-events:none` 不会强制禁用整棵子树；后代显式 `auto` 可以恢复命中。控件探针只检查目标的计算样式，继承未覆盖的 `none` 仍拒绝；可见性、遮挡、disabled 与 inert 保留各自检查。
+- 修复和回归必须经过生产输入入口及可信事件驱动的状态变化，不能用程序化点击证明真实可玩。双视口 generic 回归与真实触摸验收需要区分，详见 AGC 实施计划“固定试玩控件的指针命中边界”。
+
 ## 2026-10-01 Rust 分片编译失败只剩汇总错误
 
 - **原因**：`--message-format=json` 把编译诊断写到 stdout；只读取 `compiler-artifact` 的运行器会丢弃 `compiler-message`，CI 只能看到「due to 1 previous error」。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 02d6de4ba..b06f3589a 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -1,5 +1,11 @@
 # AI 游戏创作智能体 App 实施计划
 
+## 2026-10-02 固定试玩控件的指针命中边界
+
+固定试玩只按目标控件自身的计算样式判断 `pointer-events:none`，不累计祖先的 `none`。覆盖层为 `none`、按钮显式恢复 `auto` 是合法布局；按钮未覆盖时仍会继承 `none` 并被拒绝。保留祖先可见性、中心点 `elementFromPoint` 命中、原生 disabled、aria-disabled 和 inert 检查；目标自身为 `none` 时，即使内部子元素恢复 `auto`，也不放行目标控件。
+
+继续使用现有真实鼠标／触摸输入及游戏状态变化验收，不以 JS 强制点击或改写游戏样式绕过宿主检查。公共探针源码已进入场景指纹，修改后旧指纹证据按现行 stale 规则处理。定向回归入口为 `real_chrome_generic_playtest_pointer_events_`：在 desktop/mobile 两个视口验证祖先穿透、子元素命中和开始／主要操作／重开状态推进，并验证继承禁用、目标禁用、原生禁用、aria-disabled、inert、隐藏及遮挡仍拒绝。generic 的移动视口沿用鼠标输入，不将其表述为真实触摸验收；现场游戏开始流程需另行复核。
+
 ## 2026-10-01 项目文件列举的范围与并发边界
 
 `agc_list_project_files` 的项目内 `path` 在遍历时限制到目标文件、目标目录及其必要祖先；不递归无关子树，也不读取无关条目的元数据。Agent 的控制面、敏感文件和快照排除规则在读取条目元数据之前生效；通用 UI 文件树保持原有可见范围。引擎生成目录仍按项目根身份排除，不能因定向列举改变判定基准。

From 563f6a8e04c410e61488a73ef66cb1f7a4ebaa51 Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Fri, 2 Oct 2026 12:56:59 +0800
Subject: [PATCH 4/9] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20AGC=20Rust=20=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95=E5=A4=B9=E5=85=B7=E6=9C=AA=E8=B7=9F=E9=9A=8F=E6=89=A7?=
 =?UTF-8?q?=E8=A1=8C=E5=99=A8=E4=B8=8E=E5=8D=8F=E8=AE=AE=E6=AD=A3=E4=BA=A4?=
 =?UTF-8?q?=E6=8B=86=E5=88=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

补 select_game_creator_model 第 4 个协议参数（传 None，按执行器推导协议）
补四处 GameCreatorAppConfig 字面量的 selected_model_protocol: None
目的：HEAD 上测试模块编译失败（9 个错误），挡住预检与运行时分类的定向验证
验证：cargo test --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute --bin genarrative-ai-game-creator-shell tests::configuration:: 45 passed
---
 .../src-tauri/src/tests/configuration.rs       | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/configuration.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/configuration.rs
index 56d9b20f3..a90ab61fe 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/configuration.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/configuration.rs
@@ -38,9 +38,9 @@ fn custom_llm_config_save_reload_and_selection_preserve_overlay_and_credentials(
     write_game_creator_config_atomically(&overlay, r#"{"llm":{"customEnabled":true,"apiKey":"fixture-key","baseUrl":"https://custom.example/v1","visibleModels":["a/v1","b:v2"]},"selectedModelId":"a/v1","selectedModelIsDefault":true}"#).unwrap();
     let mut config = read_game_creator_app_config().unwrap().config;
     assert_eq!(config.llm.model, "a/v1");
-    let selected = select_game_creator_model("b:v2".into(), false, None).unwrap();
+    let selected = select_game_creator_model("b:v2".into(), false, None, None).unwrap();
     assert_eq!(selected.config.llm.model, "b:v2");
-    assert!(select_game_creator_model("not-listed".into(), false, None).is_err());
+    assert!(select_game_creator_model("not-listed".into(), false, None, None).is_err());
     config.llm.visible_models = vec!["b:v2".into()];
     config.llm.api_key = "changed-fixture-key".into();
     write_game_creator_app_config(config).unwrap();
@@ -817,6 +817,7 @@ fn app_config_commands_write_runtime_config_file() {
         agent_llm,
         selected_model_id: "default".to_string(),
         selected_model_is_default: false,
+        selected_model_protocol: None,
     })
     .expect("write runtime config");
 
@@ -964,7 +965,7 @@ fn app_config_model_selection_only_updates_model_overlay() {
     )
     .expect("write overlay");
     let saved =
-        select_game_creator_model("new-model".to_string(), true, None).expect("select model");
+        select_game_creator_model("new-model".to_string(), true, None, None).expect("select model");
     let effective = load_game_creator_app_config().expect("effective config");
     assert_eq!(saved.config.selected_model_id, "new-model");
     assert_eq!(effective.selected_model_id, "new-model");
@@ -986,13 +987,13 @@ fn model_selection_default_flag_round_trips() {
     fs::create_dir_all(&root).expect("runtime config dir");
     let _guard = use_test_runtime_config_dir(root.clone());
 
-    let saved =
-        select_game_creator_model("quality".to_string(), true, None).expect("select default model");
+    let saved = select_game_creator_model("quality".to_string(), true, None, None)
+        .expect("select default model");
     assert_eq!(saved.config.selected_model_id, "quality");
     assert!(saved.config.selected_model_is_default);
 
-    let saved =
-        select_game_creator_model("fast".to_string(), false, None).expect("select explicit model");
+    let saved = select_game_creator_model("fast".to_string(), false, None, None)
+        .expect("select explicit model");
     assert_eq!(saved.config.selected_model_id, "fast");
     assert!(!saved.config.selected_model_is_default);
 
@@ -1021,6 +1022,7 @@ fn app_config_write_rejects_invalid_api_kind() {
         agent_llm: BTreeMap::new(),
         selected_model_id: "default".to_string(),
         selected_model_is_default: false,
+        selected_model_protocol: None,
     });
 
     assert!(result
@@ -1048,6 +1050,7 @@ fn app_config_write_rejects_invalid_reasoning_effort() {
         agent_llm: BTreeMap::new(),
         selected_model_id: "default".to_string(),
         selected_model_is_default: false,
+        selected_model_protocol: None,
     });
 
     assert!(result
@@ -1075,6 +1078,7 @@ fn app_config_write_rejects_too_small_request_timeout() {
         agent_llm: BTreeMap::new(),
         selected_model_id: "default".to_string(),
         selected_model_is_default: false,
+        selected_model_protocol: None,
     });
 
     assert!(result

From e3b412744018588eb4894c215f195ea2469a473c Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Fri, 2 Oct 2026 12:59:04 +0800
Subject: [PATCH 5/9] =?UTF-8?q?=E7=BB=9F=E4=B8=80=20AGC=20=E5=A4=B1?=
 =?UTF-8?q?=E8=B4=A5=E5=85=9C=E5=BA=95=E5=8F=A3=E5=BE=84=EF=BC=9A=E5=85=9C?=
 =?UTF-8?q?=E5=BA=95=E5=8F=AA=E7=94=A8=E4=B8=93=E7=94=A8=E9=94=99=E8=AF=AF?=
 =?UTF-8?q?=E7=A0=81=E4=B8=8E=E4=B8=93=E7=94=A8=E6=96=87=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 homeCreationFailure 统一创建失败出口：宿主机器码 / IPC 失联 / 专用未分类兜底三种文案，宿主原始文本改为 appendWebviewLog 落 application.log 而不上屏
首页创建失败不再无条件覆盖成「创建未完成，请重试」，也不再写死「首条需求投递失败」指认某一步；工作区已建好时保留该事实并提供「已创建的工作区」恢复说法
宿主预检按真实原因分流浏览器验证错误码（browser-missing / launch-timeout / launch-failed / cancelled / browser-cleanup-failed / browser-environment-failed / evidence-failed / input-invalid / page-check-failed），未识别落回专用 web-preflight-unclassified
依赖准备收据保留宿主返回的真实失败码，不再一律写成 web-scaffold-preparation-failed
直连回合失败分类器 else 改为专用 runtime-unclassified，并补 sidecar-turn-timeout / sidecar-launch-failed / app-server-launch-failed / claude-code-failed 四个有证据的具体码
Codex CLI 与 Claude sidecar 的进程启动失败保留真实 OS 错误，不再报成「不支持 app-server 子命令」或「Node runtime 不可用」
更新检查新增结果型入口 checkForAppUpdateResult，「关于」页检查失败显示真实原因而不是「当前已是最新版本」
首页无码预检兜底文案不再写「请检查 Node/npm 或浏览器」这类未证实的候选原因
同步 pitfalls 六条与团队约定：兜底码/兜底文案规则、五项修复的现象根因处理验证、测试夹具编译修复记录
验证：vitest homeCreationFailure/homeWebPreflight/appUpdate/appSurface 共 215 passed；cargo test environment_check:: 19 passed、agent::runtime_error:: 5 passed、direct_failure_diagnostic 4 passed、tests::configuration:: 45 passed；cargo fmt --check、tsc --noEmit、npm run typecheck、check:encoding、git diff --check 通过
---
 .../src-tauri/src/agent/claude_code_cli.rs    |   6 +-
 .../src-tauri/src/agent/direct_runtime/mod.rs |   6 +-
 .../src-tauri/src/agent/runtime_error.rs      |  51 ++++++-
 .../src-tauri/src/config.rs                   |   7 +-
 .../src/environment_check/web_creation.rs     | 134 +++++++++++++++++-
 .../features/app-shell/homeCreationFailure.ts | 116 +++++++++++++++
 .../features/app-shell/homeWebPreflight.ts    |   8 +-
 .../app-shell/useHomeProjectCreation.ts       |  70 +++++----
 .../runtime-config/RuntimeConfigDialog.tsx    |  31 ++--
 .../src/services/appUpdate.ts                 |  61 ++++++--
 .../src/view/home/index.tsx                   |   9 +-
 .../tests/appSurface/home.suite.ts            |  10 +-
 .../tests/appUpdate.test.ts                   |  67 +++++++--
 .../tests/homeCreationFailure.test.ts         |  82 +++++++++++
 .../tests/homeWebPreflight.test.tsx           |   4 +-
 docs/project-memory/shared-memory/pitfalls.md |  48 +++++++
 .../shared-memory/team-conventions.md         |   2 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   2 +-
 18 files changed, 627 insertions(+), 87 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src/features/app-shell/homeCreationFailure.ts
 create mode 100644 apps/ai-game-creator-shell/tests/homeCreationFailure.test.ts

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs
index 263b314da..827b06682 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs
@@ -313,7 +313,11 @@ pub(crate) fn game_creator_claude_code_cli_version_identity() -> Result<String,
         .stdin(Stdio::null())
         .stderr(Stdio::null())
         .output()
-        .map_err(|_| "Claude Agent SDK sidecar 的 Node runtime 不可用".to_string())?;
+        .map_err(|error| {
+            // `output()` 失败只说明进程没能启动（可执行文件缺失、权限不足或被拦截），
+            // 不能笼统说成「Node runtime 不可用」并丢掉 OS 错误。
+            format!("Claude Agent SDK sidecar 的 Node runtime 启动失败：{error}")
+        })?;
     if !output.status.success() {
         return Err("Claude Agent SDK sidecar 的 Node runtime 版本检查失败".to_string());
     }
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs
index 06b012c94..f5059ed82 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs
@@ -7338,7 +7338,7 @@ mod tests {
         );
 
         assert!(error
-            .starts_with("direct-codex-failure:v2 stage=art-preparation code=runtime-failure retryable=true summary="));
+            .starts_with("direct-codex-failure:v2 stage=art-preparation code=runtime-unclassified retryable=true summary="));
         assert!(error.contains("<redacted-url>"), "{error}");
         assert!(error.contains("<absolute-path>"), "{error}");
         assert!(!error.contains("authorization=Bearer secret"), "{error}");
@@ -7382,7 +7382,7 @@ mod tests {
 
         assert!(
             error.starts_with(
-                "direct-codex-failure:v2 stage=code-generation code=runtime-failure retryable=false summary="
+                "direct-codex-failure:v2 stage=code-generation code=runtime-unclassified retryable=false summary="
             ),
             "{error}"
         );
@@ -7421,7 +7421,7 @@ mod tests {
         );
 
         assert!(
-            error.contains("stage=art-preparation code=runtime-failure retryable=false"),
+            error.contains("stage=art-preparation code=runtime-unclassified retryable=false"),
             "{error}"
         );
         assert!(error.contains("历史画布资源不满足安全恢复条件"), "{error}");
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs
index 8f83bfc4d..8f1896f59 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs
@@ -204,6 +204,12 @@ fn single_line_log_field(value: &str) -> String {
     value.replace(['\r', '\n'], " ")
 }
 
+/// 直连回合失败的持久化标签。
+///
+/// 这里是**唯一**的失败分类出口，标签会被写进 `.agent/runtime/errors/*.json` 与
+/// `direct-codex-failure:v2` 文案。未识别的原因必须落回专门的 `runtime-unclassified`：
+/// 以前这里借用具体的 `runtime-failure` 兜底，任何新失败形态都会被读成「运行时失败」，
+/// 真正的失败原因反而被盖掉，也无法从标签看出分类覆盖率。
 pub(crate) fn classify_direct_codex_error(error: &str) -> &'static str {
     let normalized = error.to_ascii_lowercase();
     if normalized.contains("等待 turn/completed 超时") {
@@ -224,8 +230,16 @@ pub(crate) fn classify_direct_codex_error(error: &str) -> &'static str {
         "tool-invalid-arguments"
     } else if normalized.contains("codex app-server-error:other") {
         "app-server-other"
+    } else if normalized.contains("sidecar") && normalized.contains("超时") {
+        "sidecar-turn-timeout"
+    } else if normalized.contains("sidecar") && normalized.contains("启动失败") {
+        "sidecar-launch-failed"
+    } else if normalized.contains("codex app-server 启动失败") {
+        "app-server-launch-failed"
+    } else if normalized.contains("claude code 返回失败终态") {
+        "claude-code-failed"
     } else {
-        "runtime-failure"
+        "runtime-unclassified"
     }
 }
 
@@ -361,4 +375,39 @@ mod tests {
             "tool-invalid-arguments"
         );
     }
+
+    #[test]
+    fn known_sidecar_and_app_server_failures_keep_their_own_codes() {
+        assert_eq!(
+            classify_direct_codex_error("Claude Agent SDK sidecar 回合超时"),
+            "sidecar-turn-timeout"
+        );
+        assert_eq!(
+            classify_direct_codex_error(
+                "Claude Agent SDK sidecar 的 Node runtime 启动失败：拒绝访问"
+            ),
+            "sidecar-launch-failed"
+        );
+        assert_eq!(
+            classify_direct_codex_error("Codex app-server 启动失败：找不到可执行文件"),
+            "app-server-launch-failed"
+        );
+        assert_eq!(
+            classify_direct_codex_error("Claude Code 返回失败终态"),
+            "claude-code-failed"
+        );
+    }
+
+    #[test]
+    fn unclassified_failures_get_a_dedicated_code() {
+        // 任何一个未识别原因都不能被读成某个具体故障：只允许专用兜底码。
+        assert_eq!(
+            classify_direct_codex_error("某种尚未识别的新失败"),
+            "runtime-unclassified"
+        );
+        assert_eq!(
+            classify_direct_codex_error("读取陶泥儿画布资源失败：<redacted-url>"),
+            "runtime-unclassified"
+        );
+    }
 }
diff --git a/apps/ai-game-creator-shell/src-tauri/src/config.rs b/apps/ai-game-creator-shell/src-tauri/src/config.rs
index 2eaf16112..294a3b49d 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/config.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/config.rs
@@ -583,7 +583,12 @@ fn check_game_creator_codex_app_server_available() -> Result<(), String> {
         .stdin(std::process::Stdio::null())
         .stderr(std::process::Stdio::null())
         .output()
-        .map_err(|_| "Codex CLI 不支持 app-server 子命令".to_string())?;
+        .map_err(|error| {
+            // 进程起不来（可执行文件缺失、路径错误、权限不足或被安全软件拦截）与
+            // 「不支持 app-server 子命令」是两码事：报成后者会让用户去升级 CLI，
+            // 升级完仍是同一个错。这里保留真实 OS 错误。
+            format!("Codex CLI 启动失败：{error}")
+        })?;
     if !output.status.success()
         || !String::from_utf8_lossy(&output.stdout).contains("codex app-server")
     {
diff --git a/apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs b/apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs
index 4378f32d7..8fa08dcd6 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs
@@ -302,6 +302,46 @@ async fn host_npm(
         .map_err(str::to_string)
 }
 
+/// 浏览器验证失败的宿主错误码。
+///
+/// 验证层会为不同原因返回不同文本：没有可用浏览器、启动失败或启动超时、宿主取消、
+/// 浏览器收束未确认、证据写入失败、输入或页面校验失败。把它们统一压成「浏览器有问题」，
+/// 用户和值班人员都会朝浏览器方向排查却查不到原因，所以这里按真实原因分流；
+/// 未识别的原因落回专用兜底码 `web-preflight-unclassified`，不再借用某个具体子系统。
+fn browser_validation_failure_code(error: &str) -> &'static str {
+    if error.contains("未发现可用的") {
+        "web-preflight-browser-missing"
+    } else if error.contains("启动浏览器超时") {
+        "web-preflight-browser-launch-timeout"
+    } else if error.contains("启动浏览器失败") {
+        "web-preflight-browser-launch-failed"
+    } else if error.contains("宿主已停止本轮浏览器验证") {
+        "web-preflight-cancelled"
+    } else if error.contains("browser-cleanup")
+        || error.contains("browser-tree-reap")
+        || error.contains("browser-version-invalid")
+    {
+        "web-preflight-browser-cleanup-failed"
+    } else if error.contains("浏览器临时") || error.contains("浏览器配置") {
+        "web-preflight-browser-environment-failed"
+    } else if error.contains("evidenceRoot")
+        || error.contains("证据")
+        || error.contains("浏览器验证报告")
+        || error.contains("浏览器验证截图")
+    {
+        "web-preflight-evidence-failed"
+    } else if error.contains("预览 URL")
+        || error.contains("viewports")
+        || error.contains("settleMs")
+    {
+        "web-preflight-input-invalid"
+    } else if error.contains("页面导航失败") || error.contains("截图不是有效 PNG") {
+        "web-preflight-page-check-failed"
+    } else {
+        "web-preflight-unclassified"
+    }
+}
+
 pub(crate) async fn host_web_creation_preflight() -> Value {
     let started = Instant::now();
     // 预检前顺手清扫陈旧的无头浏览器，避免残留进程放大本轮超时。
@@ -322,7 +362,7 @@ pub(crate) async fn host_web_creation_preflight() -> Value {
         let validation = crate::browser::validate_local_preview_in_browser(BrowserValidationInput {
             url: preview.url, viewports: vec![BrowserValidationViewport::Desktop, BrowserValidationViewport::Mobile], expected_text: vec![], settle_ms: 100, fail_on_console_error: true, playtest_scenario: None, evidence_root: root.join("evidence"),
         }).await;
-        let result = validation.map_err(|_| "web-preflight-browser-failed")?;
+        let result = validation.map_err(|error| browser_validation_failure_code(&error).to_string())?;
         if !result.passed || result.viewport_results.len() != 2 { return Err("web-preflight-page-check-failed".into()); }
         let mut pngs = Vec::new();
         for viewport in result.viewport_results {
@@ -382,6 +422,24 @@ fn claim_preparation(root: &Path) -> Result<Option<(ScaffoldReceipt, Preparation
     Ok(Some((receipt, claim)))
 }
 
+/// 依赖准备收据里的失败码。
+///
+/// 收据只存机器码，但也不能把任何失败都写成同一个通用码——那等于把这条诊断线索作废。
+/// 这里从宿主错误里取出真正的码（`Web 新项目依赖准备失败：web-build-timeout；…` 取
+/// `web-build-timeout`，裸码原样保留），只有确实拿不到码时才落回专用兜底。
+fn scaffold_failure_code(error: &str) -> String {
+    let candidate = error
+        .split(|ch: char| !(ch.is_ascii_lowercase() || ch.is_ascii_digit() || ch == '-'))
+        .find(|token| {
+            token.len() >= 4
+                && token.chars().any(|ch| ch.is_ascii_lowercase())
+                && token.chars().any(|ch| ch == '-')
+        });
+    candidate
+        .unwrap_or("web-scaffold-preparation-failed")
+        .to_string()
+}
+
 pub(crate) async fn prepare_new_web_project_at(
     root: &Path,
     creation_type: Option<&str>,
@@ -457,7 +515,7 @@ pub(crate) async fn prepare_new_web_project_at(
     receipt.last_failure_code = result
         .as_ref()
         .err()
-        .map(|_| "web-scaffold-preparation-failed".into());
+        .map(|error| scaffold_failure_code(error));
     if result.is_ok() {
         let entry = fs::read(ordinary_path(root, "game/dist/index.html")?)
             .map_err(|_| "web-scaffold-dist-missing")?;
@@ -474,6 +532,78 @@ pub(crate) async fn prepare_new_web_project_at(
 mod tests {
     use super::*;
 
+    #[test]
+    fn browser_validation_failures_keep_their_own_reason_codes() {
+        assert_eq!(
+            browser_validation_failure_code(
+                "未发现可用的 Google Chrome、Chromium 或 Microsoft Edge"
+            ),
+            "web-preflight-browser-missing"
+        );
+        assert_eq!(
+            browser_validation_failure_code("启动浏览器超时"),
+            "web-preflight-browser-launch-timeout"
+        );
+        assert_eq!(
+            browser_validation_failure_code("启动浏览器失败：2"),
+            "web-preflight-browser-launch-failed"
+        );
+        assert_eq!(
+            browser_validation_failure_code("宿主已停止本轮浏览器验证"),
+            "web-preflight-cancelled"
+        );
+        assert_eq!(
+            browser_validation_failure_code(
+                "browser-cleanup-unconfirmed: 浏览器收束后无法证明退出，请核对本轮验证进程"
+            ),
+            "web-preflight-browser-cleanup-failed"
+        );
+        assert_eq!(
+            browser_validation_failure_code("创建浏览器临时目录失败：拒绝访问"),
+            "web-preflight-browser-environment-failed"
+        );
+        assert_eq!(
+            browser_validation_failure_code("evidenceRoot 必须是真实目录且不能是符号链接"),
+            "web-preflight-evidence-failed"
+        );
+        assert_eq!(
+            browser_validation_failure_code("只允许带显式端口的 http://127.0.0.1 预览 URL"),
+            "web-preflight-input-invalid"
+        );
+        assert_eq!(
+            browser_validation_failure_code("desktop 页面导航失败：timeout"),
+            "web-preflight-page-check-failed"
+        );
+        // 未识别的原因必须落回专用兜底码，不能借上面任何一个具体子系统码。
+        assert_eq!(
+            browser_validation_failure_code("某种尚未识别的新失败"),
+            "web-preflight-unclassified"
+        );
+    }
+
+    #[test]
+    fn scaffold_receipt_keeps_the_real_failure_code() {
+        assert_eq!(
+            scaffold_failure_code("web-build-timeout"),
+            "web-build-timeout"
+        );
+        assert_eq!(
+            scaffold_failure_code("Web 新项目依赖准备失败：web-build-command-failed；尚未启动生成"),
+            "web-build-command-failed"
+        );
+        assert_eq!(
+            scaffold_failure_code(
+                "Web 游戏环境预检未通过：web-preflight-browser-missing；尚未启动生成"
+            ),
+            "web-preflight-browser-missing"
+        );
+        // 拿不到机器码时才使用专用兜底。
+        assert_eq!(
+            scaffold_failure_code("没有机器码的中文说明"),
+            "web-scaffold-preparation-failed"
+        );
+    }
+
     #[test]
     fn only_new_unmodified_scaffolds_receive_a_preparation_receipt() {
         let root = tempfile::tempdir().unwrap();
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/homeCreationFailure.ts b/apps/ai-game-creator-shell/src/features/app-shell/homeCreationFailure.ts
new file mode 100644
index 000000000..2ac9e3fbe
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/app-shell/homeCreationFailure.ts
@@ -0,0 +1,116 @@
+/**
+ * 首页自动创建失败的用户可见文案与证据出口。
+ *
+ * 两条硬约束：
+ *
+ * 1. 首页状态区只显示**本模块算出来的**文案。宿主返回的原始文本（Provider 英文、IPC 报错、
+ *    测试夹具字符串）一律不上屏，只作为证据写进 `application.log`；原来的写法把整段底层文本
+ *    透传上屏，或者反过来把它覆盖成通用文案，两种都不对。
+ * 2. 兜底必须是专门的兜底文案，不能借用某个具体原因冒充（把 IPC 断连说成「环境预检未通过」、
+ *    把已经建好的工作区说成「创建未完成」都属此类）。宿主给了机器码就显示机器码，给不出就
+ *    落回本模块的专用兜底，并按「工作区是否已经建好」分成两条，避免用户重做一遍。
+ */
+
+/** 未分类失败的专用兜底文案。 */
+export const HOME_CREATION_UNCLASSIFIED_FAILURE = '创建未完成，请重试';
+
+export const HOME_CREATION_AFTER_PROJECT_FAILURE =
+  '工作区已创建，但未能进入项目开发；请从「已创建的工作区」打开后重试。';
+
+export const HOME_CREATION_IPC_FAILURE =
+  '与客户端本体的连接中断，创建未完成；请重启客户端后重试。';
+
+export const HOME_CREATION_AFTER_PROJECT_IPC_FAILURE =
+  '工作区已创建；与客户端本体的连接中断，未能进入项目开发；请重启客户端后从「已创建的工作区」打开。';
+
+/** WebView / Tauri 调用通道自身失联时的固定形状。 */
+const HOME_CREATION_TRANSPORT_PATTERNS = [
+  'failed to fetch',
+  'ipc custom protocol failed',
+  'window.__tauri__',
+] as const;
+
+/** 宿主错误里的机器码（`project-revision-conflict`、`web-build-timeout` 这类连字符标识）。 */
+const HOME_CREATION_HOST_CODE = /[a-z][a-z0-9]*(?:-[a-z0-9]+)+/;
+
+/**
+ * 已经整理好用户文案的创建失败。
+ *
+ * `diagnostic` 保留宿主原始文本，只用于日志与诊断；因为它可能包含 Provider、路径或凭据文本，
+ * 不允许直接进入首页状态区。
+ */
+export class HomeCreationFailure extends Error {
+  readonly userMessage: string;
+  readonly diagnostic: string;
+
+  constructor(userMessage: string, diagnostic: string) {
+    super(userMessage);
+    this.name = 'HomeCreationFailure';
+    this.userMessage = userMessage;
+    this.diagnostic = diagnostic;
+  }
+}
+
+export function homeCreationDiagnosticText(error: unknown): string {
+  if (error instanceof Error) return error.message.trim();
+  if (typeof error === 'string') return error.trim();
+  return '';
+}
+
+function isHomeCreationTransportText(text: string): boolean {
+  const normalized = text.toLowerCase();
+  return HOME_CREATION_TRANSPORT_PATTERNS.some((pattern) =>
+    normalized.includes(pattern),
+  );
+}
+
+/**
+ * 由宿主错误算出用户可见文案。
+ *
+ * `projectCreated` 必须由调用方按自己掌握的事实传入：工作区已经建好时，文案要保留这个事实
+ * 并指向「已创建的工作区」恢复入口。
+ */
+export function homeCreationFailureMessage(
+  error: unknown,
+  options: { projectCreated?: boolean } = {},
+): string {
+  const projectCreated = options.projectCreated === true;
+  const text = homeCreationDiagnosticText(error);
+  if (isHomeCreationTransportText(text)) {
+    return projectCreated
+      ? HOME_CREATION_AFTER_PROJECT_IPC_FAILURE
+      : HOME_CREATION_IPC_FAILURE;
+  }
+  const code = HOME_CREATION_HOST_CODE.exec(text)?.[0];
+  if (code) {
+    return projectCreated
+      ? `工作区已创建；未能进入项目开发（${code}）；请从「已创建的工作区」打开后重试。`
+      : `创建未完成（${code}）；请重试。`;
+  }
+  return projectCreated
+    ? HOME_CREATION_AFTER_PROJECT_FAILURE
+    : HOME_CREATION_UNCLASSIFIED_FAILURE;
+}
+
+/** 包装成带证据的创建失败；控制器负责把 `diagnostic` 写进日志后再抛出。 */
+export function createHomeCreationFailure(
+  error: unknown,
+  options: { projectCreated?: boolean } = {},
+): HomeCreationFailure {
+  return new HomeCreationFailure(
+    homeCreationFailureMessage(error, options),
+    homeCreationDiagnosticText(error),
+  );
+}
+
+/**
+ * 首页出口：只认控制器包装过的文案。
+ *
+ * 走到这里却不是 `HomeCreationFailure`，说明失败发生在控制器之外，只能落回专用兜底——
+ * 绝不把未知文本原样渲染到状态区。
+ */
+export function resolveHomeCreationFailureMessage(error: unknown): string {
+  return error instanceof HomeCreationFailure
+    ? error.userMessage
+    : HOME_CREATION_UNCLASSIFIED_FAILURE;
+}
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts b/apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts
index 674160eb8..976be5cbd 100644
--- a/apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts
+++ b/apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts
@@ -1,8 +1,14 @@
 import type { ProjectStartMode, TauriInvoke } from '../../app/types';
 import type { HomeCreationType } from '../../view/home/useHomeDraftStore';
 
+/**
+ * 宿主返回 blocked 但没有携带原因码时的专用兜底文案。
+ *
+ * 不能像旧文案那样写「请检查 Node/npm 或浏览器」：那是三个未被证实的候选原因，
+ * 用户照它排查会白费力气，而真正的宿主原因码在上面的分支里已经会原样显示。
+ */
 export const HOME_WEB_PREFLIGHT_FAILURE =
-  'Web 游戏环境预检未通过，请检查 Node/npm 或浏览器后重试；尚未开始生成。';
+  'Web 游戏环境预检未通过，宿主没有返回具体原因码；尚未开始生成。';
 
 export const HOME_WEB_PREFLIGHT_IPC_FAILURE =
   'Web 游戏环境预检调用失败，客户端连接异常；请重启客户端后重试，尚未开始生成。';
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts b/apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts
index bd065b4fa..33c5f5a7c 100644
--- a/apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts
+++ b/apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts
@@ -36,6 +36,7 @@ import {
   createClientOperation,
   transitionClientOperation,
 } from '../../services/clientOperation';
+import { appendWebviewLog } from '../../services/errorReporting';
 import type {
   HomeAttachmentDraft,
   HomeCreationType,
@@ -55,6 +56,10 @@ import {
 } from '../project-summary/projectSummary';
 import { importDesignFiles } from '../project-workspace/importDesignFiles';
 import { clearAclElevationDenials } from './aclElevation';
+import {
+  createHomeCreationFailure,
+  type HomeCreationFailure,
+} from './homeCreationFailure';
 import {
   ensureHomeWebCreationEnvironment,
   homeWebPreflightErrorMessage,
@@ -416,6 +421,24 @@ export function useHomeProjectCreation({
     resetLauncherHomeDraft();
   }
 
+  /**
+   * 创建失败的统一收口。
+   *
+   * 用户可见文案由 `createHomeCreationFailure` 按真实原因算出（宿主机器码 / 调用通道失联 /
+   * 专用未分类兜底），宿主原始文本只写进 `application.log` 作为证据，不渲染到首页状态区。
+   */
+  function failHomeCreation(
+    error: unknown,
+    projectCreated: boolean,
+  ): HomeCreationFailure {
+    const failure = createHomeCreationFailure(error, { projectCreated });
+    if (failure.diagnostic) {
+      appendWebviewLog('error', [`[home-creation] ${failure.diagnostic}`]);
+    }
+    setStatus(failure.userMessage);
+    return failure;
+  }
+
   async function createHomeProjectFromDirectory(
     nextProjectPath: string,
     creationType: HomeCreationType,
@@ -439,6 +462,8 @@ export function useHomeProjectCreation({
         ? beginProjectOpenAnalytics(invoke, 'create')
         : analytics;
     setStatus('正在创建项目');
+    // 兜底文案必须区分「还没建」和「建好了但没进去」：只有 init 成功后才置位。
+    let createdProjectPath: string | null = null;
     try {
       if (!skipNonEmptyCheck) {
         const nonEmpty = await invoke<boolean>(
@@ -471,29 +496,23 @@ export function useHomeProjectCreation({
           name: projectNameFromPath(trimmedProjectPath),
         },
       );
-      try {
-        await enterCreatedHomeProject(
-          invoke,
-          result,
-          creationType,
-          prompt,
-          attachments,
-          startMode,
-          analytics,
-        );
-        setStatus('已创建项目，正在开始智能创作');
-      } catch (error) {
-        throw new Error(
-          `项目已创建；首条需求投递失败：${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-      }
+      createdProjectPath = result.projectPath;
+      // 这里失败时项目目录已经建好：文案由外层按「已建好」分类，不拼底层文本，
+      // 也不指认具体是哪一步失败（运行时切换、附件导入、进入工作台都可能抛）。
+      await enterCreatedHomeProject(
+        invoke,
+        result,
+        creationType,
+        prompt,
+        attachments,
+        startMode,
+        analytics,
+      );
+      setStatus('已创建项目，正在开始智能创作');
       return '已创建项目并进入项目开发';
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      setStatus(message);
-      throw error;
+      // 目录已经建好时保留「已创建」这一事实，避免用户重做一遍。
+      throw failHomeCreation(error, createdProjectPath !== null);
     }
   }
 
@@ -955,17 +974,14 @@ export function useHomeProjectCreation({
           return '已创建工作区并进入项目开发';
         } catch (error) {
           // 项目目录已经建好了：把它登记进最近项目，用户可以直接打开，不必重新建一遍。
+          // 文案交给外层统一按「已建好」分类，这里不拼底层文本。
           rememberRecentWorkspace(result.projectPath);
           setHomeCreationOperation(
             transitionClientOperation(operation, 'retryable-failure', {
               scope: { projectPath: result.projectPath },
             }),
           );
-          const message = `工作区已创建；首条需求投递失败：${
-            error instanceof Error ? error.message : String(error)
-          }`;
-          setStatus(message);
-          throw new Error(message);
+          throw error;
         }
       } catch (error) {
         setHomeCreationOperation(
@@ -978,7 +994,7 @@ export function useHomeProjectCreation({
         if (createdProjectPath) {
           rememberRecentWorkspace(createdProjectPath);
         }
-        throw error;
+        throw failHomeCreation(error, Boolean(createdProjectPath));
       } finally {
         if (watchdogId !== undefined) {
           window.clearTimeout(watchdogId);
diff --git a/apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx b/apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx
index 1b4a52659..0d62ed6dc 100644
--- a/apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx
+++ b/apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx
@@ -36,7 +36,7 @@ import {
   type GameCreatorLlmReasoningEffort,
   gameCreatorLlmReasoningEfforts,
 } from '../../app/types';
-import { checkForAppUpdate } from '../../services/appUpdate';
+import { checkForAppUpdateResult } from '../../services/appUpdate';
 import { notifyLlmConfigChanged } from '../../services/llmModelCatalog';
 import {
   AGC_PLUGIN_STATE_CHANGED_EVENT,
@@ -84,12 +84,7 @@ const defaultRuntimeConfigDraft: GameCreatorAppConfig = {
 };
 
 type RuntimeSettingsSection =
-  | 'general'
-  | 'workspace'
-  | 'agents'
-  | 'extensions'
-  | 'advanced'
-  | 'about';
+  'general' | 'workspace' | 'agents' | 'extensions' | 'advanced' | 'about';
 
 type RuntimeConfigToast = {
   tone: 'success' | 'error';
@@ -724,13 +719,21 @@ export function RuntimeConfigDialog({
     setAppUpdateChecking(true);
     setAppUpdateStatus('正在检查更新…');
     try {
-      const update = await checkForAppUpdate({ force: true });
-      setAppUpdateStatus(
-        update
-          ? `发现新版本 v${update.version}，可在更新弹窗中下载`
-          : '当前已是最新版本',
-      );
-    } catch {
+      const result = await checkForAppUpdateResult({ force: true });
+      if (result.status === 'available') {
+        setAppUpdateStatus(
+          `发现新版本 v${result.update.version}，可在更新弹窗中下载`,
+        );
+      } else if (result.status === 'current') {
+        setAppUpdateStatus('当前已是最新版本');
+      } else if (result.status === 'failed') {
+        // 检查失败必须如实说明，不能显示成「当前已是最新版本」。
+        setAppUpdateStatus(`检查更新失败：${result.message}`);
+      } else {
+        setAppUpdateStatus('当前渠道未启用更新检查');
+      }
+    } catch (error) {
+      // 结果型入口已经收口了检查失败；这里只兜住调用方自身的意外抛错。
       setAppUpdateStatus('检查更新失败，请稍后重试');
     } finally {
       setAppUpdateChecking(false);
diff --git a/apps/ai-game-creator-shell/src/services/appUpdate.ts b/apps/ai-game-creator-shell/src/services/appUpdate.ts
index 188909bc8..12e82a9ec 100644
--- a/apps/ai-game-creator-shell/src/services/appUpdate.ts
+++ b/apps/ai-game-creator-shell/src/services/appUpdate.ts
@@ -19,8 +19,17 @@ export type AppUpdateProgress = {
   totalBytes?: number;
 };
 
+/**
+ * 更新检查结果。必须能区分「有更新 / 已是最新 / 检查失败」，失败不得冒充「已是最新」。
+ */
+export type AppUpdateCheckResult =
+  | { status: 'available'; update: AppUpdateInfo }
+  | { status: 'current' }
+  | { status: 'failed'; message: string }
+  | { status: 'disabled' };
+
 let pendingUpdate: Update | null = null;
-let updateCheckPromise: Promise<AppUpdateInfo | null> | null = null;
+let updateCheckResultPromise: Promise<AppUpdateCheckResult> | null = null;
 const updateListeners = new Set<(update: AppUpdateInfo | null) => void>();
 
 function toAppUpdateInfo(update: Update): AppUpdateInfo {
@@ -31,29 +40,53 @@ function toAppUpdateInfo(update: Update): AppUpdateInfo {
   };
 }
 
-async function runAppUpdateCheck(): Promise<AppUpdateInfo | null> {
+function appUpdateFailureMessage(error: unknown): string {
+  const text =
+    error instanceof Error ? error.message.trim() : String(error ?? '').trim();
+  return text || '更新服务未返回原因';
+}
+
+async function runAppUpdateCheck(): Promise<AppUpdateCheckResult> {
   try {
     const update = await check();
     pendingUpdate = update;
     const info = update ? toAppUpdateInfo(update) : null;
     updateListeners.forEach((listener) => listener(info));
-    return info;
-  } catch {
-    // 清单 404、渠道缺少当前平台条目、网络或签名错误都按“无更新”收口，不阻塞启动。
+    return info ? { status: 'available', update: info } : { status: 'current' };
+  } catch (error) {
+    // 启动期仍然不阻塞（调用方是后台提示，不是用户操作），但这次检查必须记为失败：
+    // 清单 404、渠道缺少当前平台条目、网络或签名错误都不能再冒充「已是最新」。
     pendingUpdate = null;
-    return null;
+    return { status: 'failed', message: appUpdateFailureMessage(error) };
   }
 }
 
-/** 同一客户端生命周期内只请求一次清单；`force` 供「关于」页手动检查使用。 */
-export function checkForAppUpdate(
+/**
+ * 同一客户端生命周期内只请求一次清单；`force` 供「关于」页手动检查使用。
+ *
+ * 手动检查必须用这个结果型入口：旧入口把失败也返回 null，界面就会显示「当前已是最新版本」。
+ */
+export async function checkForAppUpdateResult(
+  options: { force?: boolean } = {},
+): Promise<AppUpdateCheckResult> {
+  // 开发态（`agc` 启动）默认关闭更新检查：不请求清单，也不显示更新入口。
+  if (!appUpdateCheckEnabled) return { status: 'disabled' };
+  if (options.force) updateCheckResultPromise = null;
+  updateCheckResultPromise ??= runAppUpdateCheck();
+  return updateCheckResultPromise;
+}
+
+/**
+ * 只关心「有没有更新」的投影，供启动期更新提示使用。
+ *
+ * 失败在这里仍然是 null（不阻塞启动）。**不要**再用这个 null 去显示「已是最新」——
+ * 那需要 `checkForAppUpdateResult()`。
+ */
+export async function checkForAppUpdate(
   options: { force?: boolean } = {},
 ): Promise<AppUpdateInfo | null> {
-  // 开发态（`agc` 启动）默认关闭更新检查：不请求清单，也不显示更新入口。
-  if (!appUpdateCheckEnabled) return Promise.resolve(null);
-  if (options.force) updateCheckPromise = null;
-  updateCheckPromise ??= runAppUpdateCheck();
-  return updateCheckPromise;
+  const result = await checkForAppUpdateResult(options);
+  return result.status === 'available' ? result.update : null;
 }
 
 export function subscribeToAppUpdate(
@@ -103,5 +136,5 @@ function restartAppAfterUpdate() {
 
 export function resetAppUpdateCheckForTests() {
   pendingUpdate = null;
-  updateCheckPromise = null;
+  updateCheckResultPromise = null;
 }
diff --git a/apps/ai-game-creator-shell/src/view/home/index.tsx b/apps/ai-game-creator-shell/src/view/home/index.tsx
index 3d605d066..79fbbc52a 100644
--- a/apps/ai-game-creator-shell/src/view/home/index.tsx
+++ b/apps/ai-game-creator-shell/src/view/home/index.tsx
@@ -13,6 +13,7 @@ import { useRef, useState } from 'react';
 
 import BRAND_ICON from '../../../../../packages/shared/src/icons/taonier-product-ip.png';
 import type { ProjectStartMode } from '../../app/types';
+import { resolveHomeCreationFailureMessage } from '../../features/app-shell/homeCreationFailure';
 import { ConversationModelSelect } from '../../features/project-workspace/ConversationModelSelect';
 import type { GameTemplateEntry } from '../../features/template-library/templateLibraryModel';
 import RichInputArea, { UploadButton } from './components/RichInputArea';
@@ -192,10 +193,10 @@ export default function HomeView({
           startMode,
         ),
       );
-    } catch {
-      // 详细错误已由工作区创建控制器记录；首页只显示稳定的用户可执行提示，
-      // 避免把底层 Provider/IPC 文本直接渲染到首页状态区。
-      onStatusChange('创建未完成，请重试');
+    } catch (error) {
+      // 控制器已经给出用户可见文案（宿主机器码、IPC 提示或专用兜底）；首页只透传它，
+      // 既不覆盖成通用文案，也不把宿主原始文本渲染到状态区。
+      onStatusChange(resolveHomeCreationFailureMessage(error));
     } finally {
       homeCreationBusyRef.current = false;
       setHomeCreationBusy(false);
diff --git a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
index c0c9a5327..3bdc76a74 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
@@ -1,3 +1,4 @@
+import { HOME_CREATION_AFTER_PROJECT_FAILURE } from '../../src/features/app-shell/homeCreationFailure';
 import type { ProjectChatComponentProps } from '../../src/features/app-shell/model';
 import { WorkspaceLauncherShell } from '../../src/features/app-shell/WorkspaceLauncher';
 import {
@@ -1856,8 +1857,7 @@ export function registerHomeProjectCreationTests() {
       '卡住的自动建项',
     );
     let resolveAutomaticProject:
-      | ((result: Record<string, unknown>) => void)
-      | null = null;
+      ((result: Record<string, unknown>) => void) | null = null;
     const invoke = vi.fn(async (command: string) => {
       if (command === 'preflight_web_game_creation') return { status: 'ready' };
       if (command === 'create_automatic_local_game_project') {
@@ -1977,7 +1977,11 @@ export function registerHomeProjectCreationTests() {
     });
     fireEvent.keyDown(promptInput, { key: 'Enter', code: 'Enter' });
 
-    expect(await screen.findByText('创建未完成，请重试')).not.toBeNull();
+    // 工作区已经建好，就必须如实说「已创建」，不能覆盖成「创建未完成」；宿主原始文本
+    // （这里是夹具里的英文原因）不上屏，只作为证据写进 application.log。
+    expect(
+      await screen.findByText(HOME_CREATION_AFTER_PROJECT_FAILURE),
+    ).not.toBeNull();
     expect(screen.getByText(`已创建的工作区：${projectPath}`)).not.toBeNull();
     await waitFor(() => {
       expect(invoke).toHaveBeenCalledWith('inspect_local_project_directory', {
diff --git a/apps/ai-game-creator-shell/tests/appUpdate.test.ts b/apps/ai-game-creator-shell/tests/appUpdate.test.ts
index f17c8406c..40a46bd59 100644
--- a/apps/ai-game-creator-shell/tests/appUpdate.test.ts
+++ b/apps/ai-game-creator-shell/tests/appUpdate.test.ts
@@ -43,9 +43,8 @@ describe('AGC 客户端更新', () => {
   it('开发态开关关闭时不请求清单', async () => {
     vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '0');
     vi.resetModules();
-    const { checkForAppUpdate, resetAppUpdateCheckForTests } = await import(
-      '../src/services/appUpdate'
-    );
+    const { checkForAppUpdate, resetAppUpdateCheckForTests } =
+      await import('../src/services/appUpdate');
 
     await expect(checkForAppUpdate()).resolves.toBeNull();
     expect(checkMock).not.toHaveBeenCalled();
@@ -56,9 +55,8 @@ describe('AGC 客户端更新', () => {
     vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
     vi.resetModules();
     checkMock.mockResolvedValue(fakeUpdate() as never);
-    const { checkForAppUpdate, resetAppUpdateCheckForTests } = await import(
-      '../src/services/appUpdate'
-    );
+    const { checkForAppUpdate, resetAppUpdateCheckForTests } =
+      await import('../src/services/appUpdate');
 
     await expect(checkForAppUpdate()).resolves.toEqual({
       version: '99.0.0',
@@ -70,15 +68,59 @@ describe('AGC 客户端更新', () => {
     resetAppUpdateCheckForTests();
   });
 
-  it('清单缺失或网络失败时静默按无更新收口', async () => {
+  it('清单缺失或网络失败时启动期静默，但结果型入口如实报失败', async () => {
     vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
     vi.resetModules();
     checkMock.mockRejectedValue(new Error('updater: manifest 404'));
-    const { checkForAppUpdate, resetAppUpdateCheckForTests } = await import(
-      '../src/services/appUpdate'
-    );
+    const {
+      checkForAppUpdate,
+      checkForAppUpdateResult,
+      resetAppUpdateCheckForTests,
+    } = await import('../src/services/appUpdate');
 
+    // 启动期提示用旧投影：失败仍然静默，不阻塞启动、不弹更新。
     await expect(checkForAppUpdate()).resolves.toBeNull();
+    // 手动检查必须拿到失败原因，不能显示成「当前已是最新版本」。
+    await expect(checkForAppUpdateResult({ force: true })).resolves.toEqual({
+      status: 'failed',
+      message: 'updater: manifest 404',
+    });
+    resetAppUpdateCheckForTests();
+  });
+
+  it('结果型入口区分「有更新」与「已是最新」', async () => {
+    vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
+    vi.resetModules();
+    checkMock.mockResolvedValueOnce(null as never);
+    const { checkForAppUpdateResult, resetAppUpdateCheckForTests } =
+      await import('../src/services/appUpdate');
+
+    await expect(checkForAppUpdateResult()).resolves.toEqual({
+      status: 'current',
+    });
+
+    checkMock.mockResolvedValueOnce(fakeUpdate() as never);
+    await expect(checkForAppUpdateResult({ force: true })).resolves.toEqual({
+      status: 'available',
+      update: {
+        version: '99.0.0',
+        currentVersion: '0.1.47',
+        releaseNotes: '修复与改进',
+      },
+    });
+    resetAppUpdateCheckForTests();
+  });
+
+  it('开关关闭时结果型入口报 disabled，不冒充已是最新', async () => {
+    vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '0');
+    vi.resetModules();
+    const { checkForAppUpdateResult, resetAppUpdateCheckForTests } =
+      await import('../src/services/appUpdate');
+
+    await expect(checkForAppUpdateResult()).resolves.toEqual({
+      status: 'disabled',
+    });
+    expect(checkMock).not.toHaveBeenCalled();
     resetAppUpdateCheckForTests();
   });
 
@@ -110,9 +152,8 @@ describe('AGC 客户端更新', () => {
   it('没有待安装更新时安装请求失败关闭', async () => {
     vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
     vi.resetModules();
-    const { installAppUpdate, resetAppUpdateCheckForTests } = await import(
-      '../src/services/appUpdate'
-    );
+    const { installAppUpdate, resetAppUpdateCheckForTests } =
+      await import('../src/services/appUpdate');
 
     await expect(installAppUpdate()).rejects.toThrow('没有可安装的更新');
     resetAppUpdateCheckForTests();
diff --git a/apps/ai-game-creator-shell/tests/homeCreationFailure.test.ts b/apps/ai-game-creator-shell/tests/homeCreationFailure.test.ts
new file mode 100644
index 000000000..11c1db813
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/homeCreationFailure.test.ts
@@ -0,0 +1,82 @@
+import { expect, it } from 'vitest';
+
+import {
+  createHomeCreationFailure,
+  HOME_CREATION_AFTER_PROJECT_FAILURE,
+  HOME_CREATION_AFTER_PROJECT_IPC_FAILURE,
+  HOME_CREATION_IPC_FAILURE,
+  HOME_CREATION_UNCLASSIFIED_FAILURE,
+  HomeCreationFailure,
+  homeCreationFailureMessage,
+  resolveHomeCreationFailureMessage,
+} from '../src/features/app-shell/homeCreationFailure';
+
+it('宿主机器码原样显示，不落回通用文案', () => {
+  expect(
+    homeCreationFailureMessage(
+      new Error('项目已被其它操作改动：project-revision-conflict'),
+    ),
+  ).toBe('创建未完成（project-revision-conflict）；请重试。');
+  expect(
+    homeCreationFailureMessage(new Error('web-build-timeout'), {
+      projectCreated: true,
+    }),
+  ).toBe(
+    '工作区已创建；未能进入项目开发（web-build-timeout）；请从「已创建的工作区」打开后重试。',
+  );
+});
+
+it('调用通道失联使用专用 IPC 文案，不冒充业务原因', () => {
+  expect(homeCreationFailureMessage(new Error('Failed to fetch'))).toBe(
+    HOME_CREATION_IPC_FAILURE,
+  );
+  expect(
+    homeCreationFailureMessage(
+      new Error(
+        'IPC custom protocol failed, Tauri will now use the postMessage interface instead TypeError: Failed to fetch',
+      ),
+      { projectCreated: true },
+    ),
+  ).toBe(HOME_CREATION_AFTER_PROJECT_IPC_FAILURE);
+});
+
+it('拿不到任何机器码时使用专用兜底，并按是否已建好工作区分文案', () => {
+  expect(homeCreationFailureMessage(new Error('自动创建测试结束'))).toBe(
+    HOME_CREATION_UNCLASSIFIED_FAILURE,
+  );
+  expect(homeCreationFailureMessage(undefined)).toBe(
+    HOME_CREATION_UNCLASSIFIED_FAILURE,
+  );
+  expect(
+    homeCreationFailureMessage(new Error('design runtime unavailable'), {
+      projectCreated: true,
+    }),
+  ).toBe(HOME_CREATION_AFTER_PROJECT_FAILURE);
+});
+
+it('宿主原始文本只进诊断，不进用户文案', () => {
+  const failure = createHomeCreationFailure(
+    new Error('Provider 返回 500：https://provider.example/private'),
+    { projectCreated: false },
+  );
+  expect(failure).toBeInstanceOf(HomeCreationFailure);
+  expect(failure.userMessage).toBe(HOME_CREATION_UNCLASSIFIED_FAILURE);
+  expect(failure.diagnostic).toBe(
+    'Provider 返回 500：https://provider.example/private',
+  );
+});
+
+it('首页出口只认控制器包装过的文案，未知值落回专用兜底', () => {
+  const failure = createHomeCreationFailure(
+    new Error('project-revision-conflict'),
+  );
+  expect(resolveHomeCreationFailureMessage(failure)).toBe(
+    '创建未完成（project-revision-conflict）；请重试。',
+  );
+  expect(resolveHomeCreationFailureMessage(new Error('自动创建测试结束'))).toBe(
+    HOME_CREATION_UNCLASSIFIED_FAILURE,
+  );
+  expect(resolveHomeCreationFailureMessage(undefined)).toBe(
+    HOME_CREATION_UNCLASSIFIED_FAILURE,
+  );
+});
diff --git a/apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx b/apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx
index e24a39d30..34cea47b3 100644
--- a/apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx
+++ b/apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx
@@ -73,7 +73,7 @@ it('awaits the real home preflight before naming or creating a game', async () =
 it('blocks naming, creation, and first generation with the host error code', async () => {
   const { result, calls } = mount(async () => {
     throw new Error(
-      'Web 游戏环境预检未通过：web-preflight-browser-failed；尚未启动生成',
+      'Web 游戏环境预检未通过：web-preflight-browser-missing；尚未启动生成',
     );
   });
   let status = '';
@@ -84,7 +84,7 @@ it('blocks naming, creation, and first generation with the host error code', asy
     );
   });
   expect(status).toBe(
-    'Web 游戏环境预检未通过（web-preflight-browser-failed）；尚未开始生成。',
+    'Web 游戏环境预检未通过（web-preflight-browser-missing）；尚未开始生成。',
   );
   expect(calls).toEqual(['preflight_web_game_creation']);
   expect(result.current.currentProjectContext).toBeNull();
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index bd5b91ae2..833613fbe 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -6253,3 +6253,51 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/` 
 - **处理**：保留预检失败关闭语义，但提取 Rust 返回的安全错误码；对无错误码的 Tauri 调用故障显示独立 IPC 提示，并仅对这类瞬态调用失败重试一次。首页调用方必须透传该安全提示，不能重新覆盖为通用文案。
 - **验证**：`apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx` 覆盖 ready、具体宿主错误码、IPC 失败、无错误码 blocked 和 planning 绕过；同一 Windows 安装包 CLI 实测 Node `v22.22.2`、npm `10.9.7`、Edge desktop/mobile PNG 均通过。
 - **关联**：`apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx`、`apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs`。
+
+## 2026-10-02 AGC 首页把创建失败覆盖成通用文案，「项目已建好」被说成「创建未完成」
+
+- **现象**：首页自动创建在项目目录已经建好之后失败（策划运行时切换、附件导入、进入工作台抛错）时，浮层显示「创建未完成，请重试」，而同一页面同时列着「已创建的工作区：…」；用户会以为没建成功，再建一遍。
+- **根因**：`useHomeProjectCreation.ts` 把底层文本拼进「工作区已创建；未能进入项目开发：<原因>」再抛出，`src/view/home/index.tsx` 的 `catch` 又无条件覆盖成写死的通用文案。注释声称“详细错误已由工作区创建控制器记录”，实际只有一次 `setStatus`，紧接着就被覆盖，没有任何落盘；同一处的包装文案还写死成「首条需求投递失败」，把运行时切换、附件导入等失败都指认成“投递”这一步。
+- **处理**：新增 `homeCreationFailure.ts` 作为唯一出口：由宿主机器码（`project-revision-conflict` / `web-build-timeout` 这类连字符标识）、Tauri/WebView 传输形状（`Failed to fetch`、IPC 自定义协议失败）与专用兜底共同决定用户文案，并按“工作区是否已建好”分成两条；宿主原始文本不再上屏，改为 `appendWebviewLog` 写进 `application.log` 作为证据（脱敏沿用 `normalizeDiagnosticText`）。控制器抛出 `HomeCreationFailure`（带 `userMessage` 与 `diagnostic`），首页只透传它的 `userMessage`，对未知值一律落回专用兜底；包装文案改为中性的「未能进入项目开发」，不再指认某一步。
+- **验证**：`apps/ai-game-creator-shell/tests/homeCreationFailure.test.ts` 5 条覆盖机器码、传输故障、无码兜底、原始文本只进诊断、首页出口；`npx vitest run tests/appSurface.test.ts tests/homeCreationFailure.test.ts tests/homeWebPreflight.test.tsx tests/appUpdate.test.ts` 215 passed / 9 skipped；`npx tsc --noEmit -p tsconfig.json` 与 `npm run typecheck` 通过。
+- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/homeCreationFailure.ts`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/src/view/home/index.tsx`、`apps/ai-game-creator-shell/tests/homeCreationFailure.test.ts`、`apps/ai-game-creator-shell/tests/appSurface/home.suite.ts`。
+
+## 2026-10-02 AGC 宿主预检把浏览器验证的多种原因压成一个 browser-failed
+
+- **现象**：预检失败一律提示浏览器相关问题，但同一安装包 `--environment-check` 可能返回 `status=ready`；宿主侧真实原因可能是证据目录不可写、报告写盘失败、宿主取消或浏览器收束未确认。
+- **根因**：`environment_check/web_creation.rs` 把 `validate_local_preview_in_browser` 的所有 `Err` 统一映射成 `web-preflight-browser-failed`（验证层实际会返回“未发现可用浏览器”“启动浏览器超时”“启动浏览器失败：<OS 码>”“宿主已停止本轮浏览器验证”“browser-cleanup-unconfirmed”“evidenceRoot …”“页面导航失败”等）。同一文件的依赖准备收据又把任何失败都写成 `web-scaffold-preparation-failed`，而宿主返回的真实机器码就在手上，等于把唯一的诊断线索作废。
+- **处理**：按真实原因分流成 `web-preflight-browser-missing` / `-launch-timeout` / `-launch-failed` / `web-preflight-cancelled` / `-browser-cleanup-failed` / `-browser-environment-failed` / `-evidence-failed` / `-input-invalid` / `-page-check-failed`，未识别原因落回专用兜底 `web-preflight-unclassified`；收据改为保留宿主返回的真实机器码，只有确实拿不到码时才用专用兜底；首页无码兜底文案不再写「请检查 Node/npm 或浏览器」这种未证实的候选原因。
+- **验证**：`cargo test --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute --bin genarrative-ai-game-creator-shell environment_check::` 19 passed（含 `browser_validation_failures_keep_their_own_reason_codes`、`scaffold_receipt_keeps_the_real_failure_code`）。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs`、`apps/ai-game-creator-shell/src-tauri/src/browser/process.rs`、`apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts`。
+
+## 2026-10-02 AGC 直连回合失败分类器拿具体码当兜底
+
+- **现象**：同一条 `code=runtime-failure` 同时承载「Claude Code 返回失败终态」与「Claude Agent SDK sidecar 回合超时」两种完全不同的原因；任何新失败形态都会静默并入该桶，从标签上看不出分类覆盖率。
+- **根因**：`agent/runtime_error.rs` 的 `classify_direct_codex_error` 用具体码 `runtime-failure` 做 `else` 兜底，并且整条分类依赖中文子串嗅探，未识别原因既没有专用兜底槽，也不进入统计口径。
+- **处理**：`else` 改为专用兜底码 `runtime-unclassified`；把已有真实证据的原因提升为具体码 `sidecar-turn-timeout` / `sidecar-launch-failed` / `app-server-launch-failed` / `claude-code-failed`。前端 `direct-codex-failure:v1|v2` 解析本就接受任意 `[a-z0-9-]+`，不需要兼容层。
+- **验证**：`cargo test … agent::runtime_error::` 5 passed（含新增的 `known_sidecar_and_app_server_failures_keep_their_own_codes`、`unclassified_failures_get_a_dedicated_code`）；`cargo test … direct_failure_diagnostic` 4 passed（断言已改为按实际原因分类）。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs`、`apps/ai-game-creator-shell/src/features/agent-runtime/model.ts`。
+
+## 2026-10-02 AGC 子进程启动失败被报成「不支持子命令」/「Node runtime 不可用」
+
+- **现象**：Codex CLI 可执行文件缺失、路径错误、权限不足或被安全软件拦截时，用户被提示「当前 Codex CLI 不支持 app-server 子命令，请升级 Codex CLI」，升级后仍是同一个错；Claude sidecar 的 Node 进程完全起不来时被笼统说成「Node runtime 不可用」，且丢掉 OS 错误码。
+- **根因**：`config.rs::check_game_creator_codex_app_server_available` 与 `agent/claude_code_cli.rs::game_creator_claude_code_cli_version_identity` 都把 `Command::output()` 的 `map_err(|_| …)` 归因到“子命令不支持”或“运行时不可用”。`output()` 失败只可能是 spawn/exec 失败，与“不支持子命令”是两码事。
+- **处理**：两处改为保留真实 OS 错误的「启动失败」文案；`output()` 成功但输出不符时仍保留原来的“不支持 app-server 子命令，请升级”判据，失败关闭语义不变。
+- **验证**：`cargo test … tests::configuration::` 45 passed（覆盖 LLM 配置状态链路）；同一 `--bin` 编译通过。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/config.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs`。
+
+## 2026-10-02 AGC 更新检查失败被显示成「当前已是最新版本」
+
+- **现象**：「关于」页手动检查更新，在清单 404、渠道缺少当前平台条目、网络失败或签名校验失败时仍显示「当前已是最新版本」。
+- **根因**：`services/appUpdate.ts` 把更新插件的所有异常统一 `return null`（按“无更新”收口），而这个 `null` 同时表示“没有更新”和“检查失败”；`RuntimeConfigDialog` 里对应的 `catch` 分支因此永远不可达，失败被兜成成功。
+- **处理**：新增结果型入口 `checkForAppUpdateResult()`（`available` / `current` / `failed` / `disabled`），失败保留插件返回的原始原因；`checkForAppUpdate()` 退化为启动期投影（失败仍静默、不阻塞启动、不动更新提示）；「关于」页按结果分别显示，失败显示具体原因，渠道未启用不再冒充“已是最新”。
+- **验证**：`apps/ai-game-creator-shell/tests/appUpdate.test.ts` 9 passed（新增失败/已是最新/有更新/未启用四组用例，并保留启动期静默断言）；`npx tsc --noEmit` 通过。
+- **关联**：`apps/ai-game-creator-shell/src/services/appUpdate.ts`、`apps/ai-game-creator-shell/src/features/runtime-config/RuntimeConfigDialog.tsx`、`apps/ai-game-creator-shell/tests/appUpdate.test.ts`。
+
+## 2026-10-02 AGC 测试夹具未跟随“执行器与协议正交”拆分，HEAD 上 Rust 测试无法编译
+
+- **现象**：`cargo test --bin genarrative-ai-game-creator-shell` 在 HEAD 上直接编译失败，9 个错误全部集中在 `src/tests/configuration.rs`：`select_game_creator_model` 少了第 4 个协议参数、`GameCreatorAppConfig` 少了 `selected_model_protocol` 字段。
+- **根因**：`6bf57c1e5` 把执行器与线协议拆成正交维度时只更新了生产代码，测试夹具没有同步，于是所有 Rust 定向验证（包括随包预检与运行时分类）都被挡住。
+- **处理**：夹具补 `None` 协议参数与 `selected_model_protocol: None`，不改任何断言口径。
+- **验证**：`cargo test --features=… --bin … tests::configuration::` 45 passed。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/tests/configuration.rs`、`apps/ai-game-creator-shell/src-tauri/src/commands.rs`、`apps/ai-game-creator-shell/src-tauri/src/main.rs`。
diff --git a/docs/project-memory/shared-memory/team-conventions.md b/docs/project-memory/shared-memory/team-conventions.md
index 3e9341b5c..8fb88c73c 100644
--- a/docs/project-memory/shared-memory/team-conventions.md
+++ b/docs/project-memory/shared-memory/team-conventions.md
@@ -18,6 +18,8 @@
 
 - DirectProject 工具可并行调度，依赖由调用方等待，同资源事务与付费动作幂等不能放松。Web 创作先用客户端环境预检，分层验证共用持久的 `validation.maxRuns`，不改写 Provider 的 `llm.maxRetries`；成功证据按输入指纹复用，达标后交付。完整回合条目统一保存在 `project.jsonl`；旧平行审计和附属请求分段计时已退出生产入口，不能因残留实现或测试而恢复旧契约。界面生命周期耗时与独立模型使用记录继续有效，未知边界不补零。详见 AGC 主专题的“Direct 历史、审计与耗时的现行边界”。
 
+- 用户可见失败必须与真实原因对齐：兜底只允许使用**专门的兜底码/兜底文案**（`*-unclassified` / `*-unknown` / `Other` / IPC 与未分类专用提示），任何一层都不得借用某个具体子系统的错误去兜住无关原因（把 Tauri IPC 断连说成「环境预检未通过」、把进程启动失败说成「不支持 app-server 子命令」、把更新检查失败说成「已是最新」都属此类）。下层已经算好的**用户文案**（宿主错误码、控制器整理过的提示）只能透传，不得被上层覆盖成通用文案；宿主原始文本（Provider 文本、IPC 报错、完整路径）不直接上屏，只作为证据写进 `application.log`、运行时错误事件或 analytics。分类器的 `else` 必须是专用未分类码，不能用已有具体码兼任。详见 pitfalls 的 2026-10-02 批次条目。
+
 - DirectProject 源码修改走 `agc_apply_patch`、进度走 `agc_update_plan`：SDK 原生的 `apply_patch` / `update_plan` 注册会被按回合移除（全局串行单例），不要恢复它们或用伪造工具注解换取并发。补丁只在当前项目内、受当前回合 Write 许可和受控进程约束，失败可能已部分写入，未知结果不自动重放；计划完成不构成验收证据。
 
 - 捆绑 Codex 版本只在 `build_support/codex_bundle.rs` 固定一次，不要在测试或脚本里另写字面量；升级 SDK 后必须重跑模型目录真实用例、宿主补丁往返、并发夹具与发行载荷 smoke。原生命令工具名随 SDK 版本变化（0.155 起为 `exec_command` / `write_stdin`），脚本与夹具应按真实目录取用，不要按旧名字硬编码。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index b06f3589a..0d7440178 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -184,7 +184,7 @@ UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_sema
 ### 环境与工作流
 
 - 客户端交付配套 Node/npm；发布包从本机已安装且与目标平台/架构一致的工具链制作受校验资源，保留许可并校验内容摘要。安装态不依赖系统 PATH 的 Node；开发态可使用已验证的宿主运行时。不得从项目或相对 PATH 加载伪造运行时。随包运行时是**单架构**官方发行版，因此 macOS 当前只构建 `aarch64-apple-darwin` 单架构包；要出 universal 必须先让 staging 支持按架构各带一份同版本运行时，在此之前 universal 目标失败关闭，不得只带宿主架构那一份糊过去。
-- 新建 Web 游戏在生图和大量实现前执行客户端环境预检，检查 Node/npm 的实际版本、浏览器启动和 CDP 可用性。报告只包含安全状态、版本、耗时和错误码。缺失或异常必须尽早返回阻塞，不能指示模型改宿主环境、全盘搜索或自行下载一套运行时。编辑器工程不强制 Web 工具链。
+- 新建 Web 游戏在生图和大量实现前执行客户端环境预检，检查 Node/npm 的实际版本、浏览器启动和 CDP 可用性。报告只包含安全状态、版本、耗时和错误码；错误码必须按真实原因分流，浏览器验证只允许在确有证据时使用 `web-preflight-browser-missing` / `-launch-timeout` / `-launch-failed` / `-browser-cleanup-failed`，取消、证据写入、输入与页面校验各有独立码，未识别原因落回专用 `web-preflight-unclassified`，不得用一个具体子系统码兜底。缺失或异常必须尽早返回阻塞，不能指示模型改宿主环境、全盘搜索或自行下载一套运行时。编辑器工程不强制 Web 工具链。
 - 预检不安装依赖、不修改项目 revision、不请求平台生成；构建仍执行项目自己的 npm 脚本。Codex 隔离 HOME 与平台凭据边界保持不变，客户端把已验证的运行时加入执行 PATH，不能把宿主凭据目录交给模型。
 - 第一轮先明确本次必需玩法、素材和验收项。同批独立读取尽量合并，必需图片一次规划；已有且可用的资产复用。已有目标全部通过后给出交付结果，非阻塞的新点子列为后续工作，不在收尾时主动开启新的生产链。
 

From aad5a0bcefa187b6b54bce01deeb399cd86fb4c9 Mon Sep 17 00:00:00 2001
From: Linghong <ink29535@proton.me>
Date: Fri, 2 Oct 2026 13:29:08 +0800
Subject: [PATCH 6/9] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=85=AC=E5=BC=80?=
 =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E7=9B=AE=E5=BD=95=E6=B5=8B=E8=AF=95=E9=81=97?=
 =?UTF-8?q?=E6=BC=8F=E5=8D=8F=E8=AE=AE=E5=AD=97=E6=AE=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

补齐公开模型目录完整 JSON 断言中的 protocol 字段。
同步后端契约文档中的回归验证说明。
验证模型目录定向测试、编码检查、文档索引和 Rust 格式检查通过。
---
 docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md | 1 +
 server-rs/crates/api-server/src/llm/mod.rs                    | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index 94f2a7a51..766820acc 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -537,6 +537,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - `read_agc_model_catalog` / `save_agc_model_catalog` 只接受已登记的 runtime service identity，保存使用 revision 乐观锁；缺行时读取返回 `AGC_MODEL_CATALOG_NOT_INITIALIZED`，不返回任何内置目录。
 - 目录初始值来自上游同步：api-server（API/All 角色）启动时若目录缺失、结构与当前定义不符或校验不通过，就用分组定价列表 `GET {Router 控制面}/api/pricing?group=taonier`（公开只读、不带凭据）的 `data[].model_name` 生成目录（`id` 为模型名 slug，`alias`/`modelId` 为上游原名），失败只记录 error、不写替代目录，由下一次启动重试；未初始化期间 AGC 目录与对话接口、后台目录接口都失败关闭（`503`）。
 - 后台 owner 通过 `GET/PUT /admin/api/agc-models` 管理稳定标识、必填别名、实际模型名、启用状态、默认项，以及**执行器 `agentMode` 与线协议 `protocol` 两个正交维度**：`agentMode` 只取 `codex` / `cc`，`protocol` 只取 `openai_responses` / `openai_chat` / `anthropic`，合法组合封闭（codex ⇒ responses/chat，cc ⇒ anthropic），非法组合在保存与加载两侧都失败关闭；存量目录缺 `protocol` 时按执行器推导。客户端 `GET /api/llm/models` 返回启用项的稳定标识、别名、`agentMode`、解析后的 `protocol` 和目录 `revision`（供条件刷新，不暴露实际模型名）。
+- 公开目录回归测试 `llm::model_catalog_tests::public_catalog_exposes_stable_id_and_upstream_alias` 对完整模型 JSON 做相等断言，包含默认 Codex 模型的 `protocol: "openai_responses"`；调整返回字段时同步更新该断言，并保留禁用项过滤和内部字段不下发的验证。
 - Responses / Chat 请求按目录解析模型；未知或停用项拒绝。AGC 的 `platform-default` 请求标识使用目录默认项。详细契约见 `technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md`。
 
 ### `error_report`
diff --git a/server-rs/crates/api-server/src/llm/mod.rs b/server-rs/crates/api-server/src/llm/mod.rs
index b97a8da5d..e43cf2e8f 100644
--- a/server-rs/crates/api-server/src/llm/mod.rs
+++ b/server-rs/crates/api-server/src/llm/mod.rs
@@ -48,7 +48,7 @@ mod model_catalog_tests {
         // 客户端拿到稳定标识 + 别名（别名就是上游原始模型名），实际模型名不下发。
         assert_eq!(
             payload["models"],
-            json!([{"id": "gpt-5-6-sol", "displayName": "gpt-5.6-sol", "agentMode": "codex"}])
+            json!([{"id": "gpt-5-6-sol", "displayName": "gpt-5.6-sol", "agentMode": "codex", "protocol": "openai_responses"}])
         );
         assert_eq!(payload["defaultModelId"], "gpt-5-6-sol");
         assert_eq!(payload["revision"], json!(7));

From a59d068c1d641c95ab5bc3f11bbea0f9c092acf1 Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Fri, 2 Oct 2026 13:47:36 +0800
Subject: [PATCH 7/9] =?UTF-8?q?=E7=BB=99=20Direct=20=E5=9B=9E=E5=90=88?=
 =?UTF-8?q?=E7=9A=84=E9=9D=99=E9=BB=98=E6=97=A9=E9=80=80=E8=A1=A5=E4=B8=8A?=
 =?UTF-8?q?=E8=AF=8A=E6=96=AD=E7=95=99=E7=97=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TurnReservation 兜底收口时写应用日志，并用 thread::panicking 区分 panic 与 future 被丢弃/取消
新增 Direct 回合 panic hook：task-local 携带回合身份，panic 时记录位置与负载
两处均 cfg(not(test))，不污染用例与本机 AppData
---
 .../src/agent/thread_manager/dispatch.rs      | 75 ++++++++++++++++++-
 1 file changed, 72 insertions(+), 3 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
index 5eabb23b6..4bfcadd2e 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
@@ -84,13 +84,80 @@ impl Drop for TurnReservation {
     fn drop(&mut self) {
         // 兜底：任务 panic、future 被丢弃、或今后在终态之前新增的 `?` 早退。
         // 这类失败说不出原因，只给分类；能说清原因的错误必须由调用方在更早的地方显式收口。
-        let _ = self.finish_if_unfinished(DirectTurnTerminal::host_dropped());
+        let finalized_by_guard = self.finish_if_unfinished(DirectTurnTerminal::host_dropped());
+        // 兜底一旦真的收口，就说明这一轮**从未写下终态**：深层既没成功也没失败地退出了。
+        // 这条必须留应用日志，否则离线只剩一个 `phase=working` 的账本，无从判断是哪一层
+        // 提前退出（真实案例：2026-10-02 连续两轮只留下 working 账本，errors/ 与
+        // application.log 全空）。测试态不写，避免用例污染本机 AppData。
+        #[cfg(not(test))]
+        if finalized_by_guard {
+            let _ = crate::append_application_log(
+                "error".to_string(),
+                "direct-turn".to_string(),
+                format!(
+                    "agent.direct_turn.host_dropped threadId={} turnToken={} userItemId={} panicking={}",
+                    self.thread_id,
+                    self.token,
+                    self.user_item_id.as_deref().unwrap_or("-"),
+                    // true = 这一轮是被 panic 带走的；false = future 被丢弃或取消。
+                    std::thread::panicking()
+                ),
+            );
+        }
         // 占用的释放就是"这个项目腾出了跑回合的位置"：踢一脚，队里排着的消息不必等下一次用户动作。
         // panic 也走这里，所以队列不会因为一个任务炸掉而永久停住。
         kick_queue_dispatch(Path::new(&self.thread_id));
     }
 }
 
+// 运行段经 task-local 携带回合身份，panic hook 据此把 panic 位置与负载写进应用日志。
+// task-local 而非 thread-local：多线程 runtime 下 future 会跨 worker 迁移。
+tokio::task_local! {
+    static DIRECT_TURN_PANIC_CONTEXT: Option<(String, String)>;
+}
+
+/// 兜底诊断：Direct 回合任务 panic 时，把位置与负载写进应用日志。
+///
+/// 没有它时，panic 只会让 `TurnReservation::drop` 把回合收成 `HostDropped`——那是"说不出原因"
+/// 的分类，离线只留一个 `phase=working` 的账本，`.agent/runtime/errors/` 与 `application.log`
+/// 全空，无法判断是哪一层退出的（真实案例：2026-10-02 连续两轮如此）。
+fn ensure_direct_turn_panic_hook() {
+    static ONCE: std::sync::Once = std::sync::Once::new();
+    ONCE.call_once(|| {
+        let previous = std::panic::take_hook();
+        std::panic::set_hook(Box::new(move |info| {
+            if let Ok(Some((thread_id, token))) = DIRECT_TURN_PANIC_CONTEXT.try_with(Clone::clone) {
+                let location = info
+                    .location()
+                    .map(|location| {
+                        format!(
+                            "{}:{}:{}",
+                            location.file(),
+                            location.line(),
+                            location.column()
+                        )
+                    })
+                    .unwrap_or_else(|| "未知位置".to_string());
+                #[cfg(not(test))]
+                let _ = crate::append_application_log(
+                    "error".to_string(),
+                    "direct-turn".to_string(),
+                    format!(
+                        "agent.direct_turn.panic threadId={} turnToken={} location={} payload={}",
+                        thread_id,
+                        token,
+                        location,
+                        info.payload_as_str().unwrap_or("未知 panic 负载")
+                    ),
+                );
+                #[cfg(test)]
+                let _ = (thread_id, token, location);
+            }
+            previous(info);
+        }));
+    });
+}
+
 /// 踢一脚：让队首那条待发消息有机会变成一轮真的回合。
 ///
 /// 幂等，三个调用点：**入队之后**（队列空且没有回合在跑时，放行就是这一脚，不必再等一个调度周期）、
@@ -109,10 +176,12 @@ pub(crate) fn kick_queue_dispatch(root: &Path) {
         crate::platform_session::current_platform_session_write_state().identity_generation;
     let reservation = TurnReservation::resume(&thread_id, &dispatched);
     let root = root.to_path_buf();
-    tauri::async_runtime::spawn(async move {
+    ensure_direct_turn_panic_hook();
+    let panic_context = Some((thread_id.clone(), dispatched.token.clone()));
+    tauri::async_runtime::spawn(DIRECT_TURN_PANIC_CONTEXT.scope(panic_context, async move {
         run_dispatched_direct_turn(root, dispatched, reservation, release_identity_generation)
             .await;
-    });
+    }));
 }
 
 /// 放行之后这一段：取这一轮的调用身份 → 落盘用户条目 → 下发 → 跑整轮。

From a6428228d1a13c8cdf1b98d43eef718340445f15 Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Fri, 2 Oct 2026 13:51:52 +0800
Subject: [PATCH 8/9] =?UTF-8?q?Direct=20=E5=9B=9E=E5=90=88=20panic=20?=
 =?UTF-8?q?=E8=BD=AC=E6=88=90=E5=8F=AF=E8=AF=8A=E6=96=AD=E7=9A=84=E5=88=86?=
 =?UTF-8?q?=E7=B1=BB=E5=A4=B1=E8=B4=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

dispatch 层用 AssertUnwindSafe/catch_unwind 接住回合体 panic，不再落到 HostDropped 兜底
panic 负载转成直接可读文本并写进脱敏诊断与应用日志，终态改为分类失败
补齐 futures::FutureExt 导入
---
 .../src/agent/thread_manager/dispatch.rs      | 60 +++++++++++++++----
 1 file changed, 48 insertions(+), 12 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
index 4bfcadd2e..9e8a43357 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
@@ -13,13 +13,16 @@
 
 use std::path::{Path, PathBuf};
 
+use futures::FutureExt;
+
 #[cfg(test)]
 use crate::agent::PendingTurn;
 use crate::agent::{
     append_direct_project_user_message_at, claim_pending_turn, complete_turn_if_reserved,
-    direct_codex_user_item_to_prompt, direct_now_ms, redact_agent_runtime_error,
-    run_direct_game_creator_turn_at_with_creation_type_and_emitter, thread_id_for_project,
-    DirectGameCreatorTurnUpdateEmitter, DirectTurnError, DirectTurnTerminal, DispatchedTurn,
+    direct_codex_user_item_to_prompt, direct_now_ms, record_direct_codex_failure,
+    redact_agent_runtime_error, run_direct_game_creator_turn_at_with_creation_type_and_emitter,
+    thread_id_for_project, DirectCodexFailureStage, DirectGameCreatorTurnUpdateEmitter,
+    DirectTurnError, DirectTurnTerminal, DispatchedTurn,
 };
 
 /// 一次放行的占用。持有它就代表这一轮还没收口。
@@ -184,6 +187,17 @@ pub(crate) fn kick_queue_dispatch(root: &Path) {
     }));
 }
 
+/// 把 panic 负载转成可读文本：`panic!("…")` 的负载是 `&str`，`panic!("{x}")` 是 `String`。
+fn direct_turn_panic_detail(payload: &(dyn std::any::Any + Send)) -> String {
+    if let Some(text) = payload.downcast_ref::<&str>() {
+        (*text).to_string()
+    } else if let Some(text) = payload.downcast_ref::<String>() {
+        text.clone()
+    } else {
+        "未知 panic 负载".to_string()
+    }
+}
+
 /// 放行之后这一段：取这一轮的调用身份 → 落盘用户条目 → 下发 → 跑整轮。
 ///
 /// 这一段的每个失败都是**回合失败**：占用与开始事件已经写好，只走占用对象的终态出口，不再回到任何
@@ -218,16 +232,38 @@ async fn run_dispatched_direct_turn(
     crate::agent::codex_app_server::emit_direct_thread_user_item(&root, &canonical_user_item);
     let capture = crate::analytics::gui::capture_writer_context();
     let emitter = DirectGameCreatorTurnUpdateEmitter::new(&root, turn_id);
-    let outcome = run_direct_game_creator_turn_at_with_creation_type_and_emitter(
-        &root,
-        &prompt,
-        dispatched.pending.creation_type.as_deref(),
-        Some(&emitter),
-        Some(canonical_user_item.clone()),
-        capture,
-        release_identity_generation,
+    // 回合体 panic 不能落到 `TurnReservation` 的 Drop 兜底：那会把这一轮收成"说不出原因"的
+    // `HostDropped`，症状正是用户看到的「本轮执行已中断，请重试」，而项目侧诊断与应用日志
+    // **一行都不会有**（真实案例：2026-10-02 连续两轮）。这里把 panic 转成分类失败，
+    // 走与正常失败同一条收口：先写脱敏诊断，再写终态。
+    let outcome = match std::panic::AssertUnwindSafe(
+        run_direct_game_creator_turn_at_with_creation_type_and_emitter(
+            &root,
+            &prompt,
+            dispatched.pending.creation_type.as_deref(),
+            Some(&emitter),
+            Some(canonical_user_item.clone()),
+            capture,
+            release_identity_generation,
+        ),
     )
-    .await;
+    .catch_unwind()
+    .await
+    {
+        Ok(result) => result,
+        Err(payload) => {
+            let failure = DirectTurnError::turn_failed(
+                DirectCodexFailureStage::CodeGeneration,
+                format!(
+                    "DirectProject 宿主任务 panic：{}",
+                    direct_turn_panic_detail(payload.as_ref())
+                ),
+            );
+            let stage = failure.turn_failure_stage();
+            let detail = record_direct_codex_failure(&root, &failure, Some(turn_id.as_str()));
+            Err(DirectTurnError::TurnFailed { stage, detail })
+        }
+    };
     match outcome {
         Ok(_) => {
             // 深层的终态出口已经在 `run_turn` 里写出 `turn.completed`；这里只补最后一条回合更新。

From b8a659c12f4f67b7c1e04583028d014d144a228d Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Fri, 2 Oct 2026 13:54:50 +0800
Subject: [PATCH 9/9] =?UTF-8?q?Direct=20=E5=9B=9E=E5=90=88=E5=85=9C?=
 =?UTF-8?q?=E5=BA=95=E6=94=B6=E5=8F=A3=E5=90=8C=E6=97=B6=E5=86=99=E9=A1=B9?=
 =?UTF-8?q?=E7=9B=AE=E4=BE=A7=E8=84=B1=E6=95=8F=E8=AF=8A=E6=96=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TurnReservation 兜底收口时除应用日志外，再写一份 .agent/runtime/errors 脱敏诊断
诊断正文带 threadId 与 turnToken，便于与账本、运行日志对账
---
 .../src-tauri/src/agent/thread_manager/dispatch.rs     | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
index 9e8a43357..be5bc35cb 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs
@@ -94,6 +94,16 @@ impl Drop for TurnReservation {
         // application.log 全空）。测试态不写，避免用例污染本机 AppData。
         #[cfg(not(test))]
         if finalized_by_guard {
+            // 项目侧也留一份脱敏诊断：用户在项目目录里就能看到这一轮的收场，
+            // 不必只依赖 AppData 的应用日志。
+            let failure = DirectTurnError::TurnFailed {
+                stage: DirectCodexFailureStage::CodeGeneration,
+                detail: format!(
+                    "DirectProject 宿主任务提前结束（panic、future 被丢弃或被取消），本轮未写下终态；threadId={} turnToken={}",
+                    self.thread_id, self.token
+                ),
+            };
+            let _ = record_direct_codex_failure(Path::new(&self.thread_id), &failure, None);
             let _ = crate::append_application_log(
                 "error".to_string(),
                 "direct-turn".to_string(),