wehub-resource-sync
214 lines
11 KiB
Markdown
214 lines
11 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!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 文件为准。
|
||
|
||
<div align="center">
|
||
|
||
# native-feel.skill
|
||
|
||
> *"跨平台开发 AND 接近原生的性能 —— 拒绝二选一。"*
|
||
|
||
[](LICENSE)
|
||
[](https://github.com/yetone/native-feel-skill)
|
||
|
||
<br>
|
||
|
||
**用于设计具有原生体验的跨平台桌面应用的 Agent Skill** —— 提炼自 Raycast 2.0 技术深度解析，并以对已发布 `Raycast Beta.app` 二进制的逆向工程为基础。
|
||
|
||
两个目标往往会相互拉扯：便捷的跨平台开发，以及接近原生的性能。本 skill 收录了那些结构性选择 —— 八项架构原则、四层架构、WebKit/WebView2 生存指南、75 项上线审计 —— 让应用兼得两者。
|
||
|
||
<br>
|
||
|
||
**安装** —— 任选其一：
|
||
|
||
</div>
|
||
|
||
**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.
|
||
```
|
||
|
||
<div align="center">
|
||
|
||
[使用场景](#use-cases) · [这是什么](#what-this-is) · [理念](#philosophy) · [目录结构](#layout) · [来源](#sources)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
安装后，只要对话涉及跨平台桌面架构、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；哲学观点为作者综合提炼；证据取自已发布应用。
|