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

# native-feel.skill > *"跨平台开发 AND 接近原生的性能 —— 拒绝二选一。"* [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Agent Skill](https://img.shields.io/badge/Agent-Skill-7c3aed)](https://github.com/yetone/native-feel-skill)
**用于设计具有原生体验的跨平台桌面应用的 Agent Skill** —— 提炼自 Raycast 2.0 技术深度解析，并以对已发布 `Raycast Beta.app` 二进制的逆向工程为基础。两个目标往往会相互拉扯：便捷的跨平台开发，以及接近原生的性能。本 skill 收录了那些结构性选择 —— 八项架构原则、四层架构、WebKit/WebView2 生存指南、75 项上线审计 —— 让应用兼得两者。
**安装** —— 任选其一：

**A. 使用 [`skills`](https://github.com/vercel-labs/skills)（任意兼容 agent）：** ```bash 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. ```

[使用场景](#use-cases) · [这是什么](#what-this-is) · [理念](#philosophy) · [目录结构](#layout) · [来源](#sources)

--- ## 使用场景安装后，只要对话涉及跨平台桌面架构、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`](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`](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](https://www.raycast.com/blog/a-technical-deep-dive-into-the-new-raycast) - 对 `Raycast Beta.app` v0.60.0 的逆向工程（macOS 26+ 构建，Xcode 17，arm64）——发现内容与方法见 [`references/07-evidence-raycast.md`](references/07-evidence-raycast.md)。 ## License MIT —— 详见 [`LICENSE`](LICENSE)。 ## Credits 以 Agent Skill 形式撰写。本 skill 描述的架构来自 Raycast；哲学观点为作者综合提炼；证据取自已发布应用。