native-feel.skill

"跨平台开发 AND 近乎原生性能 — 拒绝二选一。"

一个用于设计具有原生体验感的跨平台桌面应用的 Agent Skill — 提炼自 Raycast 2.0 技术深度解析，并基于对已发布的 Raycast Beta.app 二进制文件的逆向工程构建。

两个通常相互矛盾的目标：便捷的跨平台开发，和近乎原生的性能。本 Skill 捕获了那些让应用同时拥有两者的结构性选择 — 八项架构原则、四层架构、一份 WebKit/WebView2 生存指南、一份 75 项发布检查清单。

<br>

安装 — 选择一种方式：

A. 使用 skills（任何兼容的 Agent）：

npx skills add yetone/native-feel-skill -g

-g 标志表示全局安装（用户级别），这样每个项目都可以使用。

B. 或将此提示粘贴给你的 AI Agent：

为我安装 native-feel skill：

1. 将 https://github.com/yetone/native-feel-skill 克隆到你的
   用户级 skills 目录，命名为 `native-feel-cross-platform-desktop/`
   （使用你的 Agent 在本机读取 skills 的路径 — 例如
   Claude Code 的 `~/.claude/skills/`）。
2. 验证 SKILL.md 以及 references/ 和 checklists/ 子目录是否存在。
3. 完成后确认安装路径。

使用场景 · 这是什么 · 设计理念 · 目录结构 · 参考来源

</div>

使用场景

安装完成后，每当对话涉及跨平台桌面架构、WebView 疑难问题、或让 UI 具备原生体验感时，Skill 会自动激活。两种常见的使用方式：

场景 1 — 重构现有应用以提升原生体验感

你有一个 Electron / Tauri / Web 封装的应用，设计师（或你自己的眼睛）告诉你它看起来还是很"网页化"。你想知道从哪里开始，以及在不进行完全重写的情况下能走多远。

你    ❯ 我的 Electron 应用在 macOS 上感觉很网页化 — 设计师说它
         不像一个真正的 Mac 应用。我应该从哪里开始？

Agent ❯ 最快的路径是使用 75 项原生体验检查清单
         (checklists/ship-readiness.md)。大多数 Electron 应用
         都会在相同的 6-8 项上失败：
           - 列表项上的 cursor:pointer（第 21 项）
           - 网页风格的模态遮罩，而非原生 sheet（第 19 项）
           - 硬编码的品牌强调色，而非系统强调色（第 33 项）
           - 页面淡入过渡效果（第 40 项）
           - 不透明窗口背景，而非平台材质（第 31 项）
           - WebKit 右键菜单仍然触发（第 23 项）
         每项修复需要 5-30 分钟；加在一起就能让你在很大程度上
         "通过 30 秒挑剔用户测试"。

         首先有个更大的问题：你需要走多远？如果"够用"意味着
         通过那 30 秒测试，Electron + 这份检查清单可以让你
         不用重写就完成 80%。如果你想要"和 Mac 应用无法区分"
         — Liquid Glass 材质、原生弹窗、200ms 内启动 — 
         Electron 有一个你会碰到的天花板。要我先运行决策树吗？

场景 2 — 从零开始构建跨平台原生体验应用

全新项目，必须在 macOS + Windows 上运行，原生体验感是核心卖点 — 一个启动器、一个效率工具、一个用户全天使用的 AI 工作空间。

你    ❯ 开始一个新的桌面应用 — macOS + Windows，原生体验感
         是整个产品的核心。我应该使用什么架构？

Agent ❯ 在讨论架构之前，决策树
         (checklists/decision-tree.md) 会针对几种常见情况
         排除此技术栈 — 先快速检查一下：
           - 冷启动预算？    (<100ms → 改为构建原生应用)
           - 内存下限？      (<150MB → 改为构建原生应用)
           - 扩展生态系统？  (是 → 需要 Node 层)
           - 开发周期？      (<3个月 → 从 Electron 开始)

         如果通过检查，四层架构是：

           ┌──────────────────────────────────────────────────┐
           │ 原生外壳       Swift/AppKit  +  C#/WPF        │
           │       ↕   一套 IPC 模式，为所有端生成代码        │
           │ 系统 WebView    WKWebView    +  WebView2       │
           │   运行 React + TypeScript，1:1 共享             │
           │       ↕                                          │
           │ Node 后端       单个长生命周期进程              │
           │       ↕                                          │
           │ Rust 核心       UniFFI 桥接，可共享              │
           │                   给 iOS 和服务器                │
           └──────────────────────────────────────────────────┘

         那些出错成本高昂的决策，按顺序排列：
           1. IPC 契约（一套模式，代码生成）。这步错了，你
              以后就得在压力下重建。
           2. WebView 生存标志（occlusion off, alpha-prewarm,
              _doAfterNextPresentationUpdate, font prewarming）。
           3. 内存卫生（延迟加载扩展，积极销毁次要窗口）。

         想要从边界开始 — 在哪里划定跨平台分界线 — 还是
         从 IPC 契约开始？因为那套模式错了意味着以后要
         重建每一个桥接层。

该 Skill 适用于的其他问题

"为什么我的 WKWebView 在隐藏和重新显示时会闪烁？" → 带你通读 references/03-webview-survival.md（最可能是 A.1 节流或 A.2 启动闪烁）。
"类型化 IPC 应该如何跨 Rust、Swift 和 TypeScript 工作？" → references/04-ipc-contract.md 中的基于 UniFFI 的模式，包含 Raycast Beta 实际使用的 Coordinator/EventHandler 结构。
"我的应用常驻内存 450 MB，这很糟糕吗？" → references/05-memory-truths.md 中的六个常见活动监视器误解以及实际应该测量什么。
"我设计师的设计稿‘足够原生’吗？" → references/06-native-conventions.md 中的 70+ 项惯例检查清单。

"我们不是一个在上面撒了一些原生钩子的 Web 应用。我们是一个使用 Web 做 UI 的原生应用。" — Raycast

这是什么

这是一份面向架构师、技术负责人和工程师的参考资料，他们需要构建满足以下条件的桌面应用：

从单一 UI 代码库在 macOS + Windows（可选 Linux）上运行，
在 500 ms 内启动并保持常驻内存低于 500 MB，
对用户来说 与原生应用无法区分（没有 cursor: pointer 这类破绽、启动没有白屏闪烁、没有 WebKit 右键菜单、没有 JS 平滑滚动），
支持 TypeScript 插件/扩展生态系统，
可以将性能关键代码共享给 iOS 和服务器后端。

这就是四层架构：原生外壳 → 系统 WebView (WKWebView/WebView2) → Node 后端 → Rust 核心，通过单一类型化 IPC 模式连接，该模式为每个运行时生成客户端。

这不是什么

不适用于单一操作系统的应用（直接构建原生应用即可）。
不适用于 Electron 风格的"够用就行"应用（这里的打磨预算要高出 5-10 倍）。
不适用于有严格 <150 MB 或 <100 ms 冷启动预算的应用（这个下限是真实存在的）。
不适用于游戏、文档编辑器或媒体播放器。

运行 checklists/decision-tree.md 来判断这个架构是否适合你的项目。它会针对几种常见情况主动排除自己 — 直接说明不合适比强行给出适配的建议更有用。

目录结构

native-feel-skill/
├── SKILL.md                                # Agent 入口点
├── references/
│   ├── 01-philosophy.md                    # 驱动所有决策的 8 项原则
│   ├── 02-architecture.md                  # 四层架构
│   ├── 03-webview-survival.md              # WebKit/WebView2 疑难问题 + 修复方案（宝藏内容）
│   ├── 04-ipc-contract.md                  # 跨 Rust/Swift/C#/TS 的类型化 IPC
│   ├── 05-memory-truths.md                 # 为什么活动监视器在说谎
│   ├── 06-native-conventions.md            # 原生体验审计检查的 70+ 项内容
│   └── 07-evidence-raycast.md              # 对 Raycast Beta 逆向工程的发现
└── checklists/
    ├── decision-tree.md                    # 你应该使用这个架构吗？
    └── ship-readiness.md                   # 75 项发布前审计清单

设计理念

这个架构解决的核心矛盾是：当跨平台开发便捷性和近乎原生性能这两个目标通常相互矛盾时，一个桌面应用如何同时实现它们？ 八项原则指出了结构性的解决方案：

在渲染层面划定边界 — WebView 以上共享，WebView 以下分化；这是唯一能同时保留开发体验和原生体验感的层次。
一套模式，多种语言 — 在声明时一次性支付多语言成本，永远不要在调用站点支付。
接纳平台，而不是与平台竞争 — 操作系统在绘制模糊、滚动、材质和深色模式方面比你做得更好。
性能是一种感知属性 — 用户感受到的是什么，而不是活动监视器报告的是什么。
短迭代循环就是产品本身 — 200 ms 热重载 vs 30 秒原生重新构建是 150 倍的复利优势。
有意识地跨越边界 — IPC 有成本；将每一次跨边界设计为异步、批量、模式化类型。
身份感是肌肉记忆 — 热键、排列顺序、动作动词就是应用本身；其他一切都是实现细节。
区分基线与边际 — WebView+Node 的底层是租来的；只有你的脏页面是你可以优化的。

先阅读 references/01-philosophy.md。其他一切都是其结果。

关于 Agent Skills

Agent Skills 是正在兴起的领域知识打包标准，任何兼容的 Agent（Claude Code、Claude Agent SDK 或其他支持 Agent Skill 的运行时）都可以发现并加载。通过本 README 顶部的提示安装后，当 Agent 的对话涉及跨平台桌面架构、WebView 疑难问题或 Raycast 风格应用时，Skill 会自动激活 — 触发条件声明在 SKILL.md 的 frontmatter 中。

参考来源

Raycast 官方技术文章：A Technical Deep Dive into the New Raycast
对 Raycast Beta.app v0.60.0（macOS 26+ 构建，Xcode 17，arm64）的逆向工程 — 参见 references/07-evidence-raycast.md 了解发现了什么以及如何发现。

许可证

MIT — 参见 LICENSE。

致谢

作为一个 Agent Skill 创作。本 Skill 描述的架构属于 Raycast；设计理念是作者的综合提炼；实证证据来自已发布的应用。

本内容由 Coze AI 生成，请遵循相关法律法规及《人工智能生成合成内容标识办法》使用与传播。