native-feel-skill

跨平台桌面应用设计指南：让 AI 生成的应用"假装原生"

一个真实的产品困境

2025年，Raycast 团队决定将这款 macOS 上口碑极佳的效率启动器，扩展到 Windows 平台。他们的工程团队面临一个所有跨平台开发者都熟悉的经典困境：用 Electron？性能差、内存大、交互"网页味"太重。用纯原生？两个平台各写一遍，维护成本翻倍。

最终 Raycast 选择了第三条路——四层混合架构：Swift 原生外壳 + WKWebView 渲染界面 + Node 后端 + Rust 核心。这套架构让 Windows 版 Raycast 在正式发布时，已经拥有接近原生 macOS 版本的体验。

问题在于：这套方法论从未被系统性地整理过。每家公司都在自己摸索，踩过的坑、下过的功夫，没有积累成可复用的知识。native-feel-skill 正是为了填补这个空白而诞生的。

核心问题：为什么跨平台和原生体验是一对矛盾？

传统的跨平台方案都有取舍：

• 纯原生（Swift/C#）：性能完美、体验原生，但 macOS + Windows = 两套代码库，每个功能都要写两遍，迭代成本极高。
• Electron：一份代码跑全平台，但内存占用大（Chromium 基础开销 ~150MB），动画卡顿、窗口闪烁、上下文菜单风格不对，处处透着"网页应用"的气息。
• Tauri：比 Electron 轻量，但 Rust 前端生态远不如 Electron 成熟，企业级应用案例少。

Raycast 的解法核心在于：把跨平台边界精确地画在 WebView 表面，而不是 App 边界或业务逻辑边界。这样，既能共享 UI 代码和业务逻辑，又能让系统级交互（窗口管理、快捷键、系统托盘、无障碍）保持原生实现。

八大架构原则：拒绝"要么性能、要么跨平台"

该 skill 提炼出八个架构原则，每条都针对一对具体的矛盾：

#	原则	核心含义
T1	在渲染层画跨平台边界	共享 UI 代码，但窗口/快捷键/文件对话框必须原生
T2	一个 Schema，多种语言	所有 IPC 通信用统一的 schema 定义，codegen 生成各语言客户端，避免类型漂移
T3	拥抱平台，不要竞争	用系统原生的窗口材质、滚动条、手势，而非自己实现一套
T4	性能是可感知的属性	冷启动 <600ms、热启动 <200ms、无白屏白闪——这些用户立刻能感知
T5	让 Rust 连接一切	核心逻辑用 Rust，通过 UniFFI 桥接到 Swift/Node，性能最优
T6	有意穿越边界	每个进程间通信都有明确目的，避免过度耦合
T7	不要自己发明平台约定	遵循 macOS HIG / Windows UX 规范，不画蛇添足
T8	区分基准和边际	理解每种架构的内存基准线（macOS ~90MB、Windows ~130MB），不要有不切实际的优化目标

四层架构详解：每层为什么存在

这是 skill 最核心的交付物。四层各司其职，缺一不可：

第一层：原生宿主外壳（Native Host Shell）

• macOS 用 Swift + AppKit，Windows 用 C# + WPF/WinUI 3
• 负责：窗口生命周期、NSWindow/Win32 HWND、全局快捷键、菜单栏/系统托盘、Dock/任务栏存在感、文件关联、无障碍集成、WebView 实例化与生命周期管理
• 体积：磁盘约 5–15MB，内存约 30–40MB

第二层：WebView 渲染层

• macOS 用 WKWebView，Windows 用 WebView2
• 运行 React + TypeScript 界面，UI 代码全平台共享
• 这是跨平台的核心收益层——一份 React 代码，两端渲染

第三层：Node.js 后端

• 单一常驻进程，捆绑 Node 运行时
• 负责：SQLite 数据库、扩展运行时、网络 I/O、业务逻辑

第四层：Rust 核心

• 通过 UniFFI 桥接到 Swift 和 Node
• 可与 iOS App 和服务端共享核心代码
• 负责：高性能计算、AI 推理加速、文件索引等计算密集任务

IPC 架构（最易出错的地方）： 六条通信边（Native ↔ Rust、Node ↔ React、Rust ↔ Node 等），必须用统一的 schema（Protobuf 或 TypeScript 类型）定义，通过 codegen 生成各语言客户端。一旦手写序列化，类型漂移导致运行时错误是迟早的事。

WebKit/WebView2 生存指南：25+ 真实 Bug 的精确修复方案

这是 skill 中技术密度最高的文件。每个 Bug 都有：症状、原因、精确修复代码。

举几个典型例子：

macOS WKWebView 隐藏窗口节流（最多见）：用热键打开启动器时，第一个动画卡顿，计时器冻结，requestAnimationFrame 以 1Hz 运行而非 60Hz——这是因为 WebKit 的隐藏窗口检测把窗口当成"不可见"大幅节流了。修复方法：在 Swift 侧关闭 WebKit 的遮挡检测（webView._unfreezeWebView()），同时在 JS 侧监听 visibilitychange 事件重置。

Windows WebView2 背景色闪屏：冷启动时先出现白色或黑色背景再显示内容，需要在 WebView2 初始化时设置 DefaultBackgroundColor 并等待 NavigationCompleted 信号再显示窗口。

macOS 原生右键菜单被 WebKit 拦截：WKWebView 默认的上下文菜单会泄露 Web 风格，需要 override willOpenMenu 方法替换为原生 NSMenu。

上船审查清单：75 项"假装原生"的逐项检查

ship-readiness.md 包含 75 项可量化检查，分为六大类：冷启动（10项）、窗口管理（15项）、输入与光标（15项）、动画与过渡（10项）、无障碍（12项）、扩展性与更新（13项）。每项用 ✓/✗/N/A 标记。

典型失败项（许多 Electron 应用都会命中）：

• 第 21 项：可点击行使用了 cursor: pointer——原生列表行不变光标
• 第 19 项：用了网页风格的 modal 遮罩而非原生 sheet
• 第 33 项：硬编码的品牌色而非系统强调色
• 第 40 项：页面淡入淡出过渡（Web 风格）而非原生视图切换
• 第 31 项：窗口背景不透明而非平台材质

决策树：用 5 个问题快速判断你是否需要这个架构

skill 内置了决策树，5 个问题快速判断是否适用：

1. 目标平台数：仅 macOS 或仅 Windows → 不需要，用纯原生
2. 冷启动预算：要求 <100ms → 不适合，构建原生
3. 内存下限：要求 <150MB → 不适合
4. 扩展生态：需要插件系统 → 需要 Node 层
5. 研发周期：<3个月 → 从 Electron 开始

如果你的项目通过了决策树，这个 skill 提供了从架构设计到具体实现的完整知识支撑。

争议与局限：这套方案不适合什么场景

明确不适合的场景：

• 单平台应用：只做 macOS 或只做 Windows，直接用原生开发
• 内存敏感型工具：监控软件、后台 Daemon，90MB 基准线无法接受
• 超快速交付：研发周期 <3 个月，Electron 更快上手
• Linux 优先：skill 的证据基础是 macOS + Windows，Linux WebKitGTK 有额外坑未覆盖
• 游戏或 3D 应用：WebView 不是这类场景的正确选择

内存真相：即使是 Raycast 这种优化到极致的产品，四层架构的内存基准也在 350–450MB（窗口隐藏、空闲）到 500–700MB（搜索活跃），高峰期可达 800MB–1.2GB。相比 Raycast v1 纯 AppKit 的 200–300MB，跨平台税约 150MB。这是必须提前告知团队的硬成本。

行业意义：AI 编程时代的"工程设计手册"

随着 Claude Code、GitHub Copilot 等 AI 编程工具成熟，AI 生成代码的能力越来越强。但 AI 生成一个体验优秀的跨平台桌面应用是个完全不同的挑战——这需要精确的架构决策知识，而不是通用的代码补全。

native-feel-skill 的意义在于：将 Raycast 团队数年摸索出的工程决策，封装成 AI Agent 可以调用的结构化知识。任何 AI Agent 在面对"帮用户设计一个跨平台桌面应用"的请求时，装载这个 skill 后能给出一致、准确、经过验证的架构建议，而不是泛泛而谈。

这代表了 AI 编程工具发展的一个重要方向：从"生成代码"到"生成正确决策"。

---

项目链接：yetone/native-feel-skill | MIT License | 1777 Stars