vercel-labs/native

# Native SDK **Native SDK 是一套用于构建原生桌面应用的完整工具包。** Native SDK 之所以存在，是因为富有表现力的 UI 和原生性能不应成为相互竞争的目标。开发者通常会选择基于 Web 的 runtime，因为它们为产品体验提供了自由、速度和控制力。但这种自由往往伴随着庞大的 runtime。Native SDK 保留了富有表现力的编写模型，并用原生渲染取代了 runtime。 视图是 `.native` 文件中的声明式标记，逻辑是在构建时编译为原生代码的纯 TypeScript —— 或者是首要支持的 Zig —— 而 Native SDK 自身的引擎会将每个像素绘制到真实的操作系统窗口中。二进制文件中没有浏览器，没有 WebView，也没有 JS runtime：Zig 负责底层一切的运转，而 TypeScript 和 Native 标记则用于编写应用。 _{Soundboard、Notes 和 Calculator 均来自 examples/ —— 每一个像素都由 Native SDK 引擎绘制，并通过其确定性参考渲染器捕获。这些图像会跟随您的配色方案。} ## 快速开始 安装 CLI： ``` npm install -g @native-sdk/cli ``` 创建并运行应用： ``` native init my_app cd my_app native dev ``` 一个带有可用计数器的原生窗口将会打开。整个应用只有三个核心文件 —— 视图、逻辑和 manifest —— 并且没有构建配置。视图是 `src/app.native`，一个绑定值并分发消息的标记文件（其核心是计数器行）： ``` - {count} + ``` 所有逻辑都位于 `src/core.ts` 中：一个 `Model` 接口、一个 `Msg` 联合类型，以及一个纯 `update` 函数 —— 这是唯一改变状态的地方，即在构建时编译为原生代码的纯 TypeScript： ``` export function update(model: Model, msg: Msg): Model { switch (msg.kind) { case "increment": return { ...model, count: model.count + 1 }; case "decrement": return { ...model, count: model.count - 1 }; case "reset": return { ...model, count: 0 }; } } ``` 更倾向于用 Zig 编写核心逻辑？`native init my_app --template zig-core` 会使用 `src/main.zig` 搭建相同的应用 —— 相同的循环、相同的 runtime，首要支持供您选择。 在 `native dev` 运行期间编辑 `src/app.native`，窗口会原地更新，同时保留您的状态。`native dev --core` 会在 node 下运行 TypeScript 核心以进行即时逻辑检查，`native check` 可以在几毫秒内验证核心和所有视图而无需构建，而 `native build` 会生成优化后的发布二进制文件。 在 [native-sdk.dev/quick-start](https://native-sdk.dev/quick-start) 阅读完整指南。 ## 您将获得什么 **默认即美观** — 优秀的软件不应从一张白纸开始。内置的组件目录 —— 按钮、选项卡、文本框、对话框、图表、虚拟列表等 —— 都附带了经过深思熟虑的排版、间距和颜色，因此 `native init` 搭建的应用在第一次打开窗口时就已经看起来像是经过精心设计的。 **设计上可定制** — 您的应用应该有自己的标识，而不是我们的。样式端到端均由 design tokens 控制：颜色、圆角和排版通过名称进行解析，在主题更改时会实时重新解析，并且可以被整体替换 —— `examples/soundboard` 和 `examples/deck` 是同一个音乐播放器，仅通过 tokens 和一次外观修饰将它们区分开来。 **从一开始就是原生的** — 每个界面都不通过浏览器或 WebView 进行渲染。引擎直接绘制到真实的操作系统窗口中，同时滚动物理效果、菜单、对话框、系统托盘和文本输入交由操作系统处理，并且标记会在构建时编译进可执行文件中，因此发布版本不包含任何解析器或解释器 —— 搭建的计数器应用最终构建出的单个二进制文件仅有几兆字节大小。 **可预测的状态** — 状态变化应该是显式的、可检查的且易于推理的。事件产生消息，消息更新状态，状态渲染界面；标记可以绑定和分发，但绝不会发生突变。这个循环是如此具有确定性，以至于 `native automate record` 可以记录一次会话日志，而 `replay` 可以在无头模式下重现它，并通过状态指纹逐帧进行验证。 **编写简单** — 界面应该易于阅读、易于编写且易于生成。视图由元素、flex 布局、`{bindings}` 以及像 `selected="{f == filter}"` 这样的表达式组成，并且 `native check` 会在几毫秒内根据应用实际的 `Model` 和 `Msg` 验证每个视图 —— 包括绑定、可迭代对象、消息标签 —— 并提供具有指导意义的 `file:line:column` 格式错误提示。 **AI 是工作流的一部分** — Native SDK 是为人类和 AI agent 共同构建软件的世界而设计的。每个应用都嵌入了一个自动化服务器，因此任何 agent 都可以读取无障碍快照、驱动 widget、对实时状态进行断言，并对运行中的窗口截取确定性的屏幕截图；无障碍检查结果在 `native check` 中由机器进行验证；并且 CLI 附带了教授所有这些知识的 agent 技能（`native skills list`）。 ## 示例 上图中展示的应用位于 [examples/](./examples) 中，大多数都是零配置项目 —— `app.zon` 加上 `src/`，无需构建文件 —— 直接在它们的目录中通过 `native dev` 运行。 | 示例 | 展示内容 | | --- | --- | | [`calculator`](./examples/calculator) | 一个完整的小型应用：标记键盘、键盘输入、快捷键、主题设置。 | | [`notes`](./examples/notes) | 通过 effects channel 实现持久化：防抖写入、启动时恢复、对话框、搜索。 | | [`soundboard`](./examples/soundboard) | 带有解码封面图、上下文菜单、定时器和自定义主题的专辑网格。 | | [`deck`](./examples/deck) | 将 soundboard 播放器重构为密集的硬件底盘：两个窗口，相同的 widget，不同的 tokens。 | | [`feed`](./examples/feed) | 一个拥有 10 万行的列表，通过 runtime 拥有的滚动实现虚拟化。 | [examples/README.md](./examples/README.md) 中的完整目录还涵盖了受保护的 OS capabilities、GPU surfaces、WebView 合成、Web 前端 shell 以及 iOS/Android 嵌入宿主。 ## 平台 macOS 是主要的开发平台，拥有最深度的支持：Metal 呈现、OS 滚动物理效果、原生上下文菜单、应用菜单、托盘和对话框。Linux 通过真实窗口中的确定性软件渲染器运行完整的展示，支持指针、键盘、滚动、IME composition 和 HiDPI；Windows 在带有 IME composition 的 Win32 宿主上运行，并在 CI 中进行了实际测试，包括真实的输入注入。移动端支持处于实验阶段：iOS 通过嵌入库在模拟器中得到了验证，Android 则通过完整的嵌入 ABI 进行交叉编译，但两者的 API 和工具仍在不断发展中 —— 桌面端是成熟的平台。WebView surfaces 在所有桌面平台上共存。[平台支持矩阵](https://native-sdk.dev/platform-support) 准确记录了每个宿主目前支持的功能。 ## 文档 完整文档位于 [native-sdk.dev](https://native-sdk.dev)。 - [快速开始](https://native-sdk.dev/quick-start) — 安装并运行一个经过测试的应用 - [设计理念](https://native-sdk.dev/philosophy) — 该工具包背后的六项原则 - [应用模型](https://native-sdk.dev/app-model) — model/message/update 循环、连线与热重载 - [TypeScript 核心](https://native-sdk.dev/typescript) — 应用核心子集、effects、subscriptions 以及 node 开发循环 - [Native UI](https://native-sdk.dev/native-ui) — 标记中的每一个元素、属性和模式 - [组件](https://native-sdk.dev/components) — 组件目录 - [状态与数据流](https://native-sdk.dev/state) — 派生而非存储（derive-don't-store）、绑定和文本编辑 - [测试](https://native-sdk.dev/testing) — 完整的 UI 测试循环，可在任何机器上无头运行 - [自动化](https://native-sdk.dev/automation) — 快照、widget 驱动、记录/重放、屏幕截图 - [能力](https://native-sdk.dev/capabilities) — 受保护的 OS 服务：通知、剪贴板、对话框、凭证 - [打包](https://native-sdk.dev/packaging) — 从二进制文件到可分发应用 - [平台支持](https://native-sdk.dev/platform-support) — 各个宿主目前支持的功能 ## 贡献 Native SDK 处于 1.0 版本之前的阶段：API 仍在变动，工具包正在快速发展。欢迎提交 Bug 报告和有针对性的 pull request —— 对于较大的更改，请先开启一个 issue，以便讨论设计。有关开发设置和本地检查，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 许可证 [Apache-2.0](./LICENSE)

标签：TypeScript, UI框架, Zig, 原生SDK, 安全插件, 文档结构分析, 暗色界面, 桌面应用开发