yetone--native-feel-skill/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

native-feel.skill

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

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

两个目标往往会相互拉扯：便捷的跨平台开发，以及接近原生的性能。本 skill 收录了那些结构性选择 —— 八项架构原则、四层架构、WebKit/WebView2 生存指南、75 项上线审计 —— 让应用兼得两者。

安装 —— 任选其一：

A. 使用 skills（任意兼容 agent）：

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

-g 标志会全局（用户级）安装，因此每个项目都会自动加载。

B. 或将以下提示词粘贴给你的 AI agent：

Install the native-feel skill for me:

1. Clone https://github.com/yetone/native-feel-skill into your
   user-level skills directory as `native-feel-cross-platform-desktop/`
   (whatever path your agent reads skills from on this machine — e.g.
   `~/.claude/skills/` for Claude Code).
2. Verify that SKILL.md plus the references/ and checklists/ subdirs
   are present.
3. Confirm the install path when done.

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

---

使用场景

安装后，只要对话涉及跨平台桌面架构、WebView 怪癖，或让 UI 具备原生感，该 skill 就会自动激活。两种常见用法：

场景 1 — 重构现有应用，使其更具原生感

你有一个 Electron / Tauri / 网页封装应用，设计师（或你自己的眼光）告诉你它感觉很「网页味」。你想知道从哪里入手，以及在不彻底重写的情况下能推进到什么程度。

You    ❯ My Electron app feels web-y on macOS — the designer says it
         doesn't pass for a real Mac app. Where do I start?

Agent  ❯ Quickest path is the 75-item native-feel audit
         (checklists/ship-readiness.md). Most Electron apps fail
         the same 6–8 items:
           - cursor:pointer on rows (item 21)
           - web-style modal overlays instead of native sheets (19)
           - hardcoded brand accent instead of system accent (33)
           - page fade-transitions (40)
           - opaque window background instead of platform material (31)
           - WebKit context menu still firing (23)
         Each is a 5-to-30-minute fix; together they move you most
         of the way to "passes the 30-second skeptical user test."

         Bigger question first: how far do you need to go? If "good
         enough" means passing that 30-second test, Electron + this
         audit gets you 80% there without rewriting. If you want
         "indistinguishable from a Mac app" — Liquid Glass materials,
         native popovers, sub-200ms launch — Electron has a ceiling
         you'll hit. Want me to run the decision tree first?

场景 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?

该 skill 还擅长处理的其他事项

• "为什么我在隐藏再显示 WKWebView 时会闪烁？" → 带你排查 references/03-webview-survival.md（最可能是 A.1 节流或 A.2 启动闪烁）。
• "跨 Rust、Swift 和 TypeScript 的类型化 IPC 应如何设计？" → references/04-ipc-contract.md 中基于 UniFFI 的模式，以及 Raycast Beta 实际采用的 Coordinator/EventHandler 结构。
• "我的应用常驻内存 450 MB，这算糟吗？" → references/05-memory-truths.md 中的六项常见 Activity Monitor 误读，以及真正该测量的指标。
• "我设计师的规格够『原生』吗？" → references/06-native-conventions.md 中 70+ 项惯例审计。

---

"我们不是在上面撒了点原生钩子的网页应用。我们是使用 Web 作为 UI 的原生应用。" — Raycast

这是什么

面向架构师、技术负责人和工程师的参考，用于构建满足以下要求的桌面应用：

• 从单一 UI 代码库运行于 macOS + Windows（可选 Linux），
• 启动时间低于 500 ms，常驻内存低于 500 MB，
• 对用户而言与原生应用难以区分（无 cursor: pointer 穿帮细节、启动无白屏、无 WebKit 上下文菜单、无 smooth-scroll JS），
• 支持 TypeScript 插件/扩展生态，
• 可与 iOS 及服务端后端共享性能关键代码。

这是四层架构：native shell → system WebView (WKWebView/WebView2) → Node backend → Rust core，通过单一类型化 IPC schema 串联，并为每个运行时生成客户端。

这不是什么

• 不适用于单操作系统应用（直接做原生即可）。
• 不适用于 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

Philosophy

这一架构要解决的核心张力：桌面应用如何在兼顾便捷跨平台开发与接近原生性能的同时，化解二者通常相互掣肘的矛盾？ 以下八项原则概括了相应的结构性取舍：

1. 把接缝放在渲染层 —— 在 WebView 之上共享，在其之下分化；这是唯一能让开发体验（DX）与原生质感同时成立的层级。
2. 一套 schema，多种语言 —— 多语言代价只在声明处支付一次，绝不在调用点重复。
3. 拥抱平台，而非与之竞争 —— 模糊、滚动、材质与深色模式，操作系统画得比你好。
4. 性能是感知属性 —— 取决于用户的感受，而非 Activity Monitor 的报告。
5. 短迭代循环即产品 —— 200 ms 热重载对比 30 s 原生重编译，带来 150× 的复利优势。
6. 有意跨越边界 —— IPC 有成本；将每一次跨界设计为异步、批量化、schema 类型化。
7. 身份即肌肉记忆 —— 快捷键、排序、动词就是应用本身；其余皆为实现细节。
8. 区分基线与边际 —— WebView+Node 底层是租来的；只有你那些“脏页”才真正归你优化。

请先阅读 references/01-philosophy.md。其余内容皆由此推导而出。

About Agent Skills

Agent Skills 是用于封装领域知识的新兴标准，任何兼容的智能体（Claude Code、Claude Agent SDK 或其他支持 Agent Skill 的运行时）均可发现并加载。通过本 README 顶部的提示安装后，当对话涉及跨平台桌面架构、WebView 特性或 Raycast 风格应用时，该 skill 会自动激活——触发条件声明于 SKILL.md 的 frontmatter 中。

Sources

• 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。

License

MIT —— 详见 LICENSE。

Credits

以 Agent Skill 形式撰写。本 skill 描述的架构来自 Raycast；哲学观点为作者综合提炼；证据取自已发布应用。