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

全新项目，必须在 macOS + Windows 上运行，原生体验是关键——比如启动器、生产力工具、用户整天使用的 AI 工作空间。

You    ❯ Starting a new desktop app — macOS + Windows, native feel
         is the whole pitch. What architecture should I use?

Agent  ❯ Before architecture, the decision tree
         (checklists/decision-tree.md) rules this stack out for
         several common shapes — quick check first:
           - Cold-start budget?  (<100ms → build native instead)
           - Memory floor?       (<150MB → build native instead)
           - Extension ecosystem? (yes → need the Node layer)
           - Runway?             (<3mo → start on Electron)

         If you pass, the four-layer architecture is:

           ┌──────────────────────────────────────────────────┐
           │ Native shell      Swift/AppKit  +  C#/WPF        │
           │       ↕   one IPC schema, codegen for all sides  │
           │ System WebView    WKWebView    +  WebView2       │
           │   running React + TypeScript, shared 1:1         │
           │       ↕                                          │
           │ Node backend      single long-lived process      │
           │       ↕                                          │
           │ Rust core         UniFFI-bridged, sharable       │
           │                   with iOS and server            │
           └──────────────────────────────────────────────────┘

         The expensive-to-get-wrong decisions, in order:
           1. The IPC contract (one schema, codegen). Get this wrong
              and you rebuild it later under duress.
           2. WebView survival flags (occlusion off, alpha-prewarm,
              _doAfterNextPresentationUpdate, font prewarming).
           3. Memory hygiene (lazy-load extensions, tear down
              secondary windows aggressively).

         Want to start with the seam — where to draw the cross-
         platform line — or with the IPC contract, since getting
         that schema wrong means rebuilding every bridge later?

该技能还擅长其他方面

• "为什么我的 WKWebView 在隐藏并重新显示时会闪烁？" → 引导你查看 references/03-webview-survival.md（很可能是 A.1 节流或 A.2 启动闪烁）。
• "类型化 IPC 应如何在 Rust、Swift 和 TypeScript 之间工作？" → 基于 UniFFI 的模式，见 references/04-ipc-contract.md，以及 Raycast Beta 发布的精确 Coordinator/EventHandler 形态。
• "我的应用常驻内存 450 MB，这算糟糕吗？" → 活动监视器的六个常见误区以及实际应测量什么，见 references/05-memory-truths.md。
• "我的设计师的规格说明是否'足够原生'？" → 70 多项约定审计，见 references/06-native-conventions.md。

"我们不是带有一些原生钩子的网页应用。我们是使用网页作为 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                                # entry point for the agent
├── references/
│   ├── 01-philosophy.md                    # 8 tenets that drive every decision
│   ├── 02-architecture.md                  # the four-layer architecture
│   ├── 03-webview-survival.md              # WebKit/WebView2 quirks + fixes (the goldmine)
│   ├── 04-ipc-contract.md                  # typed IPC across Rust/Swift/C#/TS
│   ├── 05-memory-truths.md                 # why Activity Monitor lies
│   ├── 06-native-conventions.md            # 70+ items the native-feel audit checks
│   └── 07-evidence-raycast.md              # what a reverse-eng. of Raycast Beta shows
└── checklists/
    ├── decision-tree.md                    # should you use this architecture?
    └── ship-readiness.md                   # 75-item launch audit

理念

此架构解决的核心矛盾：当便捷的跨平台开发与接近原生的性能通常相互拉扯时，桌面应用如何两者兼得？ 八大原则指明了结构性举措：

1. 将接缝置于渲染表面 —— 在 WebView 之上共享，在其之下分化；这是唯一能让开发体验和原生体验同时存活的层级。
2. 一个模式，多种语言 —— 多语言成本只在声明时支付一次，绝不在调用点支付。
3. 顺应平台，而非与之竞争 —— 操作系统绘制的模糊、滚动、材质和深色模式比你做得更好。
4. 性能是感知的属性 —— 用户感受到的，而非活动监视器报告的。
5. 短迭代循环即产品 —— 200 ms 热重载对比 30 s 原生重建是 150 倍的复利优势。
6. 有意跨越边界 —— IPC 有成本；将每次跨越设计为异步、批量、模式类型化。
7. 身份是肌肉记忆 —— 快捷键、排序、动词就是应用本身；其余都是实现细节。
8. 区分基线余量与边际 —— WebView+Node 的地板是租来的；只有你的脏页面才值得优化。

先读 references/01-philosophy.md。其余皆是推论。

关于 Agent Skills

Agent Skills 是封装领域知识的新兴标准，任何兼容的 agent（Claude Code、Claude Agent SDK 或其他支持 Agent-Skill 的运行时）都能发现并加载。通过本 README 顶部的提示词安装后，当 agent 的对话涉及跨平台桌面架构、WebView 怪癖或 Raycast 风格应用时，该技能会自动激活——触发条件在 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 编写。本技能描述的架构属于 Raycast；理念是作者的综述；证据来自已发布的应用。