桌面端与 Web 端 QA

有些改动只有实际体验过才能判断效果：例如配置流程、控制面板，以及任何需要确认“在真实窗口中用起来是否自然”的场景。本文档介绍了调出这一界面的具体操作方法。

快速开始（Web QA 栈）

1. 创建全新栈：
   • hstack stack new codex-bootstrap-qa-⟦K1⟧ --repo=<repoPath> --port=<uniquePort>
2. 构建并激活运行时：
   • hstack stack build codex-bootstrap-qa-⟦K2⟧ --activate-runtime
3. 优先使用运行时快照：
   • hstack stack env codex-bootstrap-qa-⟦K3⟧ set KAIWU_STACK_RUNTIME_MODE=prefer
4. 启动栈（运行时）：
   • hstack stack start codex-bootstrap-qa-⟦K4⟧ --runtime
5. 身份验证：
   • hstack stack auth codex-bootstrap-qa-⟦K5⟧ login --force

快速开始（通过 Tauri 进行原生桌面端 QA）

推荐方式（栈管理的开发环境 + TUI）：

• yarn tui:with-tauri

说明：

• 栈启动器会将桌面端应用指向现有的 Expo 开发服务器。
• 启动器使用 apps/ui/src-tauri 内的 --config 文件，并配合 -c 配置覆盖项（避免栈目录的相对路径问题）。
• 如需查看解析后的启动方案（devUrl/配置路径/标识符）：node ./apps/stack/scripts/tauri_dev.mjs --json。
• yarn ui:tauri 与 yarn --cwd apps/ui tauri:qa 不会启动 Expo；请先在另一个终端运行 yarn ui（或 yarn --cwd apps/ui start），或直接使用 yarn tui:with-tauri。

使用 @hypothesi/tauri-mcp-server 进行原生手动 QA

我们使用 @hypothesi/tauri-mcp-server 来驱动真实的原生 Tauri 窗口（支持截图、点击、键入输入、获取 DOM 快照以及查看日志）。

前置条件

• 应用必须通过 tauri dev 运行（带调试断言）；MCP 桥接插件已在 apps/ui/src-tauri/src/lib.rs 中注册。
• 公共开发配置中需启用 MCP 功能：
  • apps/ui/src-tauri/tauri.publicdev.conf.json 包含 app.security.capabilities = ["default","mcp-dev"]。
  • apps/ui/src-tauri/capabilities/mcp-dev.json 授予 mcp-bridge:default。

将 MCP 服务器安装到 Codex

在仓库根目录下运行：

• npx -y install-mcp @hypothesi/tauri-mcp-server --client codex --yes --oauth no

安装完成后重启 Codex（客户端配置在启动时加载）。

启动原生应用

可选方式：

• yarn ui:tauri（独立运行；要求 Expo 开发服务器已在运行）
• yarn tui:with-tauri（推荐方式；与栈及 TUI 保持统一）
• yarn --cwd apps/ui tauri:qa（同时启动 Tauri 应用和 MCP 服务器用于 QA；要求 Expo 开发服务器已在运行）

可选的启动方案预览：

• yarn --cwd apps/ui tauri:qa --json

原始 MCP CLI 辅助命令：

• yarn --cwd apps/ui tauri:mcp:cli --help
• yarn --cwd apps/ui tauri:mcp:session:start

说明：

• 默认情况下，yarn ui:tauri / yarn --cwd apps/ui tauri:qa 会在启动 Tauri 前等待 Metro 报告 packager-status:running；可使用 KAIWU_STACK_TAURI_WAIT_FOR_EXPO=0 禁用该等待机制。

启动驱动会话

在 MCP 客户端（Codex）中，使用 driver_session 工具启动会话：

• driver_session → { "action": "start" }

CLI 备用方案（脱离 MCP 客户端单独运行命令）：

• yarn --cwd apps/ui tauri:mcp:session:start

实现细节（用于排查连接问题）：

• MCP 桥接插件在 9223 端口（或 9223–9322 中下一个可用端口）运行 WebSocket 服务器，默认绑定 0.0.0.0。
• 如有需要，可显式指定目标主机：
  • driver_session → { "action": "start", "host": "127.0.0.1" }

QA 实用工具

• webview_screenshot（在 issue 中附带验证凭据）
• webview_dom_snapshot（确认实际渲染的内容）
• webview_find_element + webview_interact（点击按钮 / 切换开关）
• webview_keyboard（向输入框键入内容）
• read_logs（webview 与系统日志）
• ipc_monitor + ipc_get_captured（确认 invoke(...) 调用及有效载荷）