> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 运行并配置外壳

启动 Tauri 开发外壳，并让它连接到你的 Web 应用。

## 初学者演练

先决条件：阅读下面的两个初学者指南并完成桌面本地设置，包括 Rust 和操作系统先决条件。该代码块启动了 web 应用程序和 monorepo 中的 Tauri；在仅限桌面的结账中，仅在单独启动可访问的 Web 后端后才使用其过滤命令。 Tauri 加载该后端。

简而言之：工作区是一个团队的单独用户、数据和设置。服务器是可信后端；让提供商密钥远离浏览器和电话代码。迁移是创建或更新表的版本化数据库更改。人工智能模型是回答的引擎；型号目录是服务器上可用型号 ID 和价格的列表。提供商是一种外部服务，例如人工智能、电子邮件或计费服务。权利是允许工作区使用某项功能的授权。 Webhook 是一个服务发送到另一个服务的 URL 的消息。

1、打开`apps/desktop/src-tauri/src/lib.rs`；要求您的代理仅更改指定的窗口/托盘/热键行为，并将产品 UI 保留在 Web 应用程序中。

2、运行shell并测试close-to-tray、Quit、`CmdOrCtrl+Shift+Space`；测试`supastack:///settings/appearance?preview=1#main`。

3. 它应该聚焦现有窗口并保留路径/查询/片段。如果打开错误的页面，请比较配置的起点和确切的路线。

对于自定义代码，请从提供的 `prompts/README.md` 开始，然后复制最接近的提示：对于应用程序屏幕为 `prompts/new-app-screen.md`，对于公共页面为 `prompts/new-landing-page.md`。对于服务器、数据库或提供商工作，请为您的编码代理提供本指南的任务，并要求其读取 `AGENTS.md`、`.ai/PROJECT_CONTEXT.md` 和匹配的 `.ai/` 镜像；检查此处指定的确切源文件；列出文件并在编辑前进行检查；保留工作区所有权和仅限服务器的机密；并向您展示差异。告诉它您想要的行为、输入和输出字段、允许的角色、预期的成功和错误以及测试帐户、提供程序或设备。使用样本值；永远不要粘贴真正的秘密。

[开始之前](https://supastack.dev/zh/docs/web/before-you-start.md)

[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)

[桌面本地设置](https://supastack.dev/zh/docs/desktop/ship-in-5-minutes.md)

[座席提示和项目内存](https://supastack.dev/zh/docs/web/agents.md)

```
# Monorepo: start the web app and desktop shell together
corepack pnpm dev:desktop

# Desktop-only checkout: start Tauri after a web backend is already reachable
corepack pnpm --filter @supastack/desktop dev
```


## 在 Rust 中保持 shell 行为

`src-tauri/src/lib.rs` 创建主 1200×800 webview 窗口。关闭时将其隐藏到托盘中；退出退出。本机菜单提供主页/后退/前进/重新加载、缩放/全屏和窗口操作。窗口状态恢复保留大小/位置。


## 处理链接和召唤

shell 接受 `supastack://` 路由并根据确切配置的 HTTP(S) 应用程序源解析它们。例如，`supastack:///settings/appearance?preview=1#main` 变为 `/workspace/settings?tab=billing#plans`； `supastack:///auth/callback?code=...` 映射到 `/auth/callback?code=...`。查询字符串和片段被保留。

在显示第一个窗口之前应用启动链接。 macOS 运行时链接使用 Tauri 的 `on_open_url`； Windows 和 Linux 第二实例参数使用启用了 `deep-link` 功能的单实例回调。有效的链接聚焦并导航现有窗口。

只有具有确切配置的方案、主机和有效端口的无凭据 HTTP(S) 链接才会保留在 shell 中。无凭据的 HTTP(S)、`mailto:` 和 `tel:` 链接可以从外部打开；格式错误的链接、凭据、不受支持的方案、自定义链接上的端口以及遍历尝试都会被拒绝。配置的后端 URL 也会拒绝凭据并回退到下一个有效/默认来源。

```
SUPASTACK_APP_URL=https://your-app.example
SUPASTACK_DESKTOP_HOTKEY=CmdOrCtrl+Shift+Space

supastack:///settings/appearance?preview=1#main
# Opens https://your-app.example/workspace/settings?tab=billing#plans
```


## 验证特定于平台的行为

注入的离线覆盖提供重试、在线隐藏和重新加载 Web 应用程序。在每个目标操作系统上测试焦点、快捷键、菜单缩放、托盘和深层链接调用；单元 URL 检查本身并不能证明这些本机交互。

[桌面验收](https://supastack.dev/zh/docs/desktop/release.md)


## 安装与配置

安装工作区依赖项和 Rust 工具链以及 Tauri 的每个操作系统先决条件（WebView2 随 Windows 一起提供；macOS 和 Linux 需要其记录的软件包）。 corepack pnpm --filter @supastack/desktop dev 运行 tauri dev：它构建 Rust 核心，显示占位符 UI，并加载已解析的应用程序 URL。

运行时 SUPASTACK_APP_URL 优先，其次采用构建时写入的值。仅接受不带凭据的 HTTP(S) 地址；无效时继续尝试下一候选值。SUPASTACK_DESKTOP_HOTKEY 覆盖默认 CmdOrCtrl+Shift+Space；无效值会回退到默认快捷键，不会阻止启动。

```
corepack pnpm --filter @supastack/desktop dev
corepack pnpm --filter @supastack/desktop typecheck

SUPASTACK_APP_URL=https://app.example.com \
SUPASTACK_DESKTOP_HOTKEY=CmdOrCtrl+Shift+Space \
corepack pnpm --filter @supastack/desktop dev
```


## 实现流程

主窗口只在配置的精确来源中导航，包括协议和端口。无凭据的 HTTP(S)、mailto 和 tel 链接可以交给系统浏览器打开；其他协议会被取消。

已注册的 supastack:// 链接会将路径、查询参数和片段映射到配置的应用来源。启动时、平台打开 URL 事件和第二实例回调都使用同一套验证，深链接不能把外壳重定向到其他主机。

托盘图标和全局快捷键会显示并聚焦唯一主窗口。快捷键无响应时，通常是另一个应用占用了组合键；请改用其他 SUPASTACK_DESKTOP_HOTKEY。


## 验证与排障

修改 src-tauri 后，通过包脚本运行 cargo check 和 cargo test。然后端到端验证精确来源导航、允许的外部 URL 打开、supastack:// 路由留在配置来源、托盘和快捷键，以及重启后登录状态是否保留。


如果你想继续完成设置，可以阅读《[创建桌面端发布账户](https://supastack.dev/zh/docs/desktop/external-accounts.md)》。


## 下一篇

[创建桌面端发布账户](https://supastack.dev/zh/docs/desktop/external-accounts.md)