vercel-labs--zero-native/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/vercel-labs/zero-native) · [上游 README](https://github.com/vercel-labs/zero-native/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Native SDK

**Native SDK 是构建原生桌面应用的完整工具包。**

Native SDK 的诞生，是因为富有表现力的 UI 与原生性能本不应互相掣肘。开发者常常选择基于 Web 的运行时，因为它们在产品体验上提供了自由、速度与掌控力。但这种自由往往伴随着沉重的运行时负担。Native SDK 保留了富有表现力的创作模型，并以原生渲染取代运行时。

视图是 `.native` 文件中的声明式标记，逻辑是普通的 TypeScript，在构建时编译为原生代码——或可选地一等支持 Zig——而 Native SDK 自有引擎将每一个像素绘制到真实的操作系统窗口中。二进制中无浏览器、无 WebView、无 JS 运行时：Zig 驱动一切运转，TypeScript 与 Native 标记则是应用的创作方式。

<picture>
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/soundboard-dark.webp">
  <img src=".github/assets/soundboard-light.webp" alt="由 Native SDK 引擎渲染的 Soundboard 示例应用：音乐库，含专辑封面、搜索与播放栏" width="100%">
</picture>

<table>
  <tr>
    <td width="70%">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset=".github/assets/notes-dark.webp">
        <img src=".github/assets/notes-light.webp" alt="由 Native SDK 引擎渲染的 Notes 示例应用：三栏笔记管理器，含文件夹、笔记列表与打开的笔记" width="640">
      </picture>
    </td>
    <td width="30%">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset=".github/assets/calculator-dark.webp">
        <img src=".github/assets/calculator-light.webp" alt="由 Native SDK 引擎渲染的 Calculator 示例应用：完整键盘上方显示已完成的计算结果" width="270">
      </picture>
    </td>
  </tr>
</table>

<sub>上图 Soundboard、Notes 与 Calculator 来自 <a href="./examples">examples/</a> —— 每一像素均由 Native SDK 引擎绘制，通过其确定性参考渲染器捕获。图片会随你的配色方案切换。</sub>

## 快速入门

安装 CLI：

```bash
npm install -g @native-sdk/cli
```

创建并运行应用：

```bash
native init my_app
cd my_app
native dev
```

会打开一个原生窗口，内含可用的计数器。整个应用只有三个真相文件——视图、逻辑、清单——且无需构建配置。视图是 `src/app.native`，一个绑定值并分发消息（核心是计数器行）的标记文件：

```html
<row gap="8" main="center" cross="center" grow="1">
  <button variant="secondary" on-press="decrement">-</button>
  <text>{count}</text>
  <button variant="primary" on-press="increment">+</button>
</row>
```

所有逻辑位于 `src/core.ts`：一个 `Model` 接口、一个 `Msg` 联合类型，以及一个纯 `update` 函数——唯一改变状态之处，普通 TypeScript 在构建时编译为原生代码：

```ts
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` 搭建同款应用——相同循环、相同运行时，可选的一等支持。

在 `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` 是同一款音乐播放器，仅通过令牌与 chrome 处理区分。

**从一开始就原生** — 每个界面均无需浏览器或 WebView 即可渲染。引擎绘制到真实操作系统窗口，滚动物理、菜单、对话框、托盘与文本输入均交由操作系统处理，标记在构建时编译进可执行文件，因此发布构建不携带解析器或解释器——脚手架计数器应用可构建为仅几 MB 的单一二进制。

**可预测的状态** — 状态变更应显式、可检查且易于推理。事件产生消息，消息更新状态，状态渲染界面；标记可绑定与分发但绝不直接变更。循环如此确定，`native automate record` 可记录会话，`replay` 可无头复现，并逐帧对照状态指纹校验。

**简洁的创作** — 界面应易于阅读、编写与生成。视图由元素、flex 布局、`{bindings}` 以及类似 `selected="{f == filter}"` 的表达式构成，`native check` 在毫秒内根据应用实际的 `Model` 与 `Msg`——绑定、可迭代对象、消息标签——校验每个视图，并以 `file:line:column` 错误提供可学习的反馈。

**AI 是工作流的一部分** — Native SDK 面向人类与 AI 智能体共同构建软件的世界而设计。每个应用内嵌自动化服务器，任意智能体均可读取无障碍快照、驱动控件、断言实时状态，并对运行中的窗口进行确定性截图；无障碍检查结果在 `native check` 中由机器校验；CLI 还提供传授这一切的智能体技能（`native skills list`）。

## 示例

上文所示应用位于 [examples/](./examples)，多数为零配置项目——`app.zon` 加 `src/`，无构建文件——使用 `native dev` 可直接在其目录运行。

| 示例 | 展示内容 |
| --- | --- |
| [`calculator`](./examples/calculator) | 完整的小型应用：标记键盘、键盘输入、chrome 快捷键、主题。 |
| [`notes`](./examples/notes) | 通过 effects 通道实现持久化：防抖写入、启动时恢复、对话框、搜索。 |
| [`soundboard`](./examples/soundboard) | 含解码封面图的专辑网格、上下文菜单、计时器与自定义主题。 |
| [`deck`](./examples/deck) | 将 soundboard 播放器重构为紧凑的硬件机箱：双窗口、相同控件、不同令牌。 |
| [`feed`](./examples/feed) | 10 万行列表，由运行时拥有的滚动实现虚拟化。 |

[examples/README.md](./examples/README.md) 中的完整目录还涵盖受保护的 OS 能力、GPU 表面、WebView 合成、Web 前端壳，以及 iOS/Android 嵌入宿主。

## 平台

macOS 是主要开发平台，支持最为深入：Metal 呈现、系统滚动物理、原生上下文菜单、应用菜单、托盘与对话框。Linux 通过确定性软件渲染器在真实窗口中运行完整展示，支持指针、键盘、滚动、IME 输入法合成与 HiDPI；Windows 运行于 Win32 宿主，支持 IME 输入法合成，并在 CI 中受测，包括真实输入注入。移动端支持尚属实验性：iOS 已通过嵌入库在模拟器验证，Android 可交叉编译并具备完整嵌入 ABI，但两端的 API 与工具仍在演进——桌面是成熟平台。WebView 表面在所有桌面平台上共存。[platform support matrix](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) — app-core 子集、effects、subscriptions 与 Node 开发循环
- [原生 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) — 快照、控件驱动、录制/回放、截图
- [系统能力](https://native-sdk.dev/capabilities) — 受保护的 OS 服务：通知、剪贴板、对话框、凭据
- [打包分发](https://native-sdk.dev/packaging) — 从二进制到可分发应用
- [平台支持](https://native-sdk.dev/platform-support) — 各宿主平台当前支持情况

## 贡献

Native SDK 目前为 pre-1.0 版本：API 仍在调整，工具包也在快速迭代。欢迎提交 bug 报告和针对性 pull request；若改动较大，请先开 issue 以便讨论设计方案。开发环境与本地检查见 [CONTRIBUTING.md](./CONTRIBUTING.md)。

## 许可证

[Apache-2.0](./LICENSE)