> ## 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

# 构建你的第一个功能

从一处原生外壳改动到一个已验证窗口的端到端演练。

## 初学者演练

先决条件：阅读下面两篇入门指南，完成 Desktop 本地安装，并在编辑器中以根目录打开此存储库。外壳在启动时把 SUPASTACK_APP_URL 作为终端设置读取——而不是从已保存的 .env 文件中读取。

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

1. 打开 `.agents/skills/add-a-desktop-capability/SKILL.md`——或让您的编码代理照它执行——并做一处小的原生改动，例如新增一个 View 菜单项或换一个召唤快捷键。

2. 运行 `cargo check`，启动外壳，并在打开的窗口中实际验证该改动。

3. 在您计划发布的每个操作系统上重复验证——托盘、快捷键和菜单行为因平台而异。

对自定义代码，写明行为名称、它影响的菜单或快捷键，以及在每个操作系统上应发生的效果。把任务交给您的编码代理，并要求它先读 `AGENTS.md`、`.ai/PROJECT_CONTEXT.md` 以及将触碰文件的 `.ai/` 镜像文档；在编辑前列出文件和检查项；并向您展示 diff。使用示例值；切勿粘贴真实密钥。

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

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

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

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


## 先决定原生还是产品

用户视为产品界面的一切——界面、数据、设置——属于 web 应用，会自动出现在窗口中。只有操作系统层面的行为属于 Rust：窗口、托盘、菜单、全局快捷键、开机自启和更新检查。

```
apps/desktop/src-tauri/src/lib.rs
apps/desktop/src-tauri/tauri.conf.json
apps/desktop/src-tauri/capabilities/default.json
```


## 保持 webview 沙箱最小化

Webview 只能调用 `capabilities/default.json` 列出的内容。需要新插件的改动要在 `Cargo.toml` 中添加 crate、在 `lib.rs` 中注册，并在 capabilities 中授予最小权限——绝不使用通配符。

持久化的外壳状态——窗口位置、缩放、更新通道、窗口偏好——通过附带的 sidecar 存放在应用数据目录中，而不是由您手工管理的文件。


## 在每个目标操作系统上验证

运行 cargo test，然后在 Windows、macOS 和 Linux 上打开真实窗口：窗口状态恢复、关闭到托盘、单实例聚焦，以及在您的改动生效时的召唤快捷键。一个操作系统通过并不能证明另外两个也没问题。

[原生菜单和窗口偏好](https://supastack.dev/zh/docs/desktop/menus.md)

[Desktop 测试清单](https://supastack.dev/zh/docs/desktop/testing.md)


## 下一篇

[用编码代理构建](https://supastack.dev/zh/docs/desktop/agents.md)