docs: make Chinese README the default
This commit is contained in:
wehub-resource-sync
@@ -1,33 +1,39 @@
|
||||
<!-- 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
|
||||
|
||||
> *"Cross-platform development AND near-native performance — refuse the trade-off."*
|
||||
> *"跨平台开发 AND 接近原生的性能 —— 拒绝二选一。"*
|
||||
|
||||
[](LICENSE)
|
||||
[](https://github.com/yetone/native-feel-skill)
|
||||
|
||||
<br>
|
||||
|
||||
**An Agent Skill for designing cross-platform desktop apps that feel native** — distilled from Raycast's 2.0 technical deep-dive and grounded in reverse-engineering of the shipping `Raycast Beta.app` binary.
|
||||
**用于设计具有原生体验的跨平台桌面应用的 Agent Skill** —— 提炼自 Raycast 2.0 技术深度解析，并以对已发布 `Raycast Beta.app` 二进制的逆向工程为基础。
|
||||
|
||||
Two goals usually pull against each other: convenient cross-platform development, and near-native performance. This skill captures the structural choices — eight architectural tenets, a four-layer architecture, a WebKit/WebView2 survival guide, a 75-item ship audit — that let an app have both.
|
||||
两个目标往往会相互拉扯：便捷的跨平台开发，以及接近原生的性能。本 skill 收录了那些结构性选择 —— 八项架构原则、四层架构、WebKit/WebView2 生存指南、75 项上线审计 —— 让应用兼得两者。
|
||||
|
||||
<br>
|
||||
|
||||
**Install** — pick one:
|
||||
**安装** —— 任选其一：
|
||||
|
||||
</div>
|
||||
|
||||
**A. With [`skills`](https://github.com/vercel-labs/skills) (any compatible agent):**
|
||||
**A. 使用 [`skills`](https://github.com/vercel-labs/skills)（任意兼容 agent）：**
|
||||
|
||||
```bash
|
||||
npx skills add yetone/native-feel-skill -g
|
||||
```
|
||||
|
||||
The `-g` flag installs globally (user-level) so every project picks it up.
|
||||
`-g` 标志会全局（用户级）安装，因此每个项目都会自动加载。
|
||||
|
||||
**B. Or paste this prompt to your AI agent:**
|
||||
**B. 或将以下提示词粘贴给你的 AI agent：**
|
||||
|
||||
```
|
||||
Install the native-feel skill for me:
|
||||
@@ -43,19 +49,19 @@ Install the native-feel skill for me:
|
||||
|
||||
<div align="center">
|
||||
|
||||
[Use cases](#use-cases) · [What this is](#what-this-is) · [Philosophy](#philosophy) · [Layout](#layout) · [Sources](#sources)
|
||||
[使用场景](#use-cases) · [这是什么](#what-this-is) · [理念](#philosophy) · [目录结构](#layout) · [来源](#sources)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Use cases
|
||||
## 使用场景
|
||||
|
||||
Once installed, the skill activates automatically whenever the conversation touches cross-platform desktop architecture, WebView quirks, or making a UI feel native. Two common ways to use it:
|
||||
安装后，只要对话涉及跨平台桌面架构、WebView 怪癖，或让 UI 具备原生感，该 skill 就会自动激活。两种常见用法：
|
||||
|
||||
### Case 1 — Refactor an existing app to feel more native
|
||||
### 场景 1 — 重构现有应用，使其更具原生感
|
||||
|
||||
You have an Electron / Tauri / web-wrapped app, and a designer (or your own eye) tells you it feels web-y. You want to know where to start and how far you can take it without a full rewrite.
|
||||
你有一个 Electron / Tauri / 网页封装应用，设计师（或你自己的眼光）告诉你它感觉很「网页味」。你想知道从哪里入手，以及在不彻底重写的情况下能推进到什么程度。
|
||||
|
||||
```
|
||||
You ❯ My Electron app feels web-y on macOS — the designer says it
|
||||
@@ -81,9 +87,9 @@ Agent ❯ Quickest path is the 75-item native-feel audit
|
||||
you'll hit. Want me to run the decision tree first?
|
||||
```
|
||||
|
||||
### Case 2 — Build a cross-platform native-feel app from scratch
|
||||
### 场景 2 — 从零构建具有原生体验的跨平台应用
|
||||
|
||||
Greenfield project, must run on macOS + Windows, and the native feel is the *point* — a launcher, a productivity tool, an AI workspace your users live in all day.
|
||||
绿地项目，必须运行于 macOS + Windows，而原生感正是**核心卖点** —— 启动器、效率工具、用户整天沉浸其中的 AI 工作区。
|
||||
|
||||
```
|
||||
You ❯ Starting a new desktop app — macOS + Windows, native feel
|
||||
@@ -124,39 +130,39 @@ Agent ❯ Before architecture, the decision tree
|
||||
that schema wrong means rebuilding every bridge later?
|
||||
```
|
||||
|
||||
### Other things the skill is good for
|
||||
### 该 skill 还擅长处理的其他事项
|
||||
|
||||
- **"Why is my WKWebView flickering when I hide and re-show it?"** → walks you through `references/03-webview-survival.md` (most likely A.1 throttling or A.2 startup flicker).
|
||||
- **"How should typed IPC work across Rust, Swift, and TypeScript?"** → the UniFFI-based pattern in `references/04-ipc-contract.md`, with the exact `Coordinator`/`EventHandler` shape Raycast Beta ships.
|
||||
- **"My app is at 450 MB resident, is that bad?"** → the six common Activity-Monitor mistakes and what to actually measure, in `references/05-memory-truths.md`.
|
||||
- **"Is my designer's spec ‘native enough’?"** → the 70+ item conventions audit in `references/06-native-conventions.md`.
|
||||
- **"为什么我在隐藏再显示 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+ 项惯例审计。
|
||||
|
||||
---
|
||||
|
||||
> *"We're not a web app with some native hooks sprinkled on top. We're a native app that uses web for its UI."* — Raycast
|
||||
> *"我们不是在上面撒了点原生钩子的网页应用。我们是使用 Web 作为 UI 的原生应用。"* — Raycast
|
||||
|
||||
## What this is
|
||||
## 这是什么
|
||||
|
||||
A reference for architects, tech leads, and engineers who must build a desktop app that:
|
||||
面向架构师、技术负责人和工程师的参考，用于构建满足以下要求的桌面应用：
|
||||
|
||||
- runs on **macOS + Windows** (optionally Linux) from a single UI codebase,
|
||||
- launches in under 500 ms and stays under 500 MB resident,
|
||||
- is **indistinguishable from a native app** to its users (no `cursor: pointer` tell-tales, no white-flash on launch, no WebKit context menu, no smooth-scroll JS),
|
||||
- supports a **plugin/extension ecosystem** in TypeScript,
|
||||
- can share performance-critical code with iOS and a server backend.
|
||||
- 从单一 UI 代码库运行于 **macOS + Windows**（可选 Linux），
|
||||
- 启动时间低于 500 ms，常驻内存低于 500 MB，
|
||||
- 对用户而言**与原生应用难以区分**（无 `cursor: pointer` 穿帮细节、启动无白屏、无 WebKit 上下文菜单、无 smooth-scroll JS），
|
||||
- 支持 TypeScript **插件/扩展生态**，
|
||||
- 可与 iOS 及服务端后端共享性能关键代码。
|
||||
|
||||
This is the four-layer architecture: **native shell → system WebView (WKWebView/WebView2) → Node backend → Rust core**, wired together with a single typed IPC schema that generates clients for every runtime.
|
||||
这是四层架构：**native shell → system WebView (WKWebView/WebView2) → Node backend → Rust core**，通过单一类型化 IPC schema 串联，并为每个运行时生成客户端。
|
||||
|
||||
## What this is not
|
||||
## 这不是什么
|
||||
|
||||
- Not for single-OS apps (just build native).
|
||||
- Not for Electron-style "good enough" apps (the polish budget here is 5–10× higher).
|
||||
- Not for apps with strict <150 MB or <100 ms cold-start budgets (the floor is real).
|
||||
- Not for games, document editors, or media players.
|
||||
- 不适用于单操作系统应用（直接做原生即可）。
|
||||
- 不适用于 Electron 式「够用就行」的应用（此处的打磨预算要高 5–10 倍）。
|
||||
- 不适用于要求严格 <150 MB 或 <100 ms 冷启动预算的应用（底线是实实在在的）。
|
||||
- 不适用于游戏、文档编辑器或媒体播放器。
|
||||
|
||||
Run [`checklists/decision-tree.md`](checklists/decision-tree.md) to find out if this architecture is even right for your project. It rules itself out for several common cases — saying so directly is more useful than over-fitting advice.
|
||||
运行 [`checklists/decision-tree.md`](checklists/decision-tree.md)，判断该架构是否适合你的项目。它会对多种常见场景直接排除自身 —— 坦率说明比过度拟合建议更有用。
|
||||
|
||||
## Layout
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
native-feel-skill/
|
||||
@@ -176,32 +182,32 @@ native-feel-skill/
|
||||
|
||||
## Philosophy
|
||||
|
||||
The central tension this architecture resolves: **how can a desktop app deliver convenient cross-platform development AND near-native performance, when those goals usually pull against each other?** Eight tenets name the structural moves:
|
||||
这一架构要解决的核心张力：**桌面应用如何在兼顾便捷跨平台开发与接近原生性能的同时，化解二者通常相互掣肘的矛盾？** 以下八项原则概括了相应的结构性取舍：
|
||||
|
||||
1. **Place the seam at the rendering surface** — share above the WebView, diverge below it; this is the only altitude where both DX and native feel survive.
|
||||
2. **One schema, many languages** — pay the polyglot tax once at the declaration, never at the call site.
|
||||
3. **Adopt the platform; don't compete with it** — the OS draws blur, scrolling, materials, and dark mode better than you can.
|
||||
4. **Performance is a property of perception** — what the user feels, not what Activity Monitor reports.
|
||||
5. **The short iteration loop is the product** — 200 ms hot reload vs 30 s native rebuild is a 150× compounding advantage.
|
||||
6. **Cross boundaries intentionally** — IPC has a cost; design every crossing as async, batched, schema-typed.
|
||||
7. **Identity is muscle memory** — the hotkey, the rank order, the verbs are the app; everything else is implementation.
|
||||
8. **Separate baseline from margin** — the WebView+Node floor is rented; only your dirty pages are yours to optimize.
|
||||
1. **把接缝放在渲染层** —— 在 WebView 之上共享，在其之下分化；这是唯一能让开发体验（DX）与原生质感同时成立的层级。
|
||||
2. **一套 schema，多种语言** —— 多语言代价只在声明处支付一次，绝不在调用点重复。
|
||||
3. **拥抱平台，而非与之竞争** —— 模糊、滚动、材质与深色模式，操作系统画得比你好。
|
||||
4. **性能是感知属性** —— 取决于用户的感受，而非 Activity Monitor 的报告。
|
||||
5. **短迭代循环即产品** —— 200 ms 热重载对比 30 s 原生重编译，带来 150× 的复利优势。
|
||||
6. **有意跨越边界** —— IPC 有成本；将每一次跨界设计为异步、批量化、schema 类型化。
|
||||
7. **身份即肌肉记忆** —— 快捷键、排序、动词就是应用本身；其余皆为实现细节。
|
||||
8. **区分基线与边际** —— WebView+Node 底层是租来的；只有你那些“脏页”才真正归你优化。
|
||||
|
||||
Read [`references/01-philosophy.md`](references/01-philosophy.md) first. Everything else is consequence.
|
||||
请先阅读 [`references/01-philosophy.md`](references/01-philosophy.md)。其余内容皆由此推导而出。
|
||||
|
||||
## About Agent Skills
|
||||
|
||||
Agent Skills are the emerging standard for packaging domain knowledge that any compatible agent (Claude Code, the Claude Agent SDK, or other Agent-Skill-aware runtimes) can discover and load. Once installed via the prompt at the top of this README, the skill activates automatically when the agent's conversation touches cross-platform desktop architecture, WebView quirks, or Raycast-style apps — the trigger conditions are declared in `SKILL.md`'s frontmatter.
|
||||
Agent Skills 是用于封装领域知识的新兴标准，任何兼容的智能体（Claude Code、Claude Agent SDK 或其他支持 Agent Skill 的运行时）均可发现并加载。通过本 README 顶部的提示安装后，当对话涉及跨平台桌面架构、WebView 特性或 Raycast 风格应用时，该 skill 会自动激活——触发条件声明于 `SKILL.md` 的 frontmatter 中。
|
||||
|
||||
## Sources
|
||||
|
||||
- Raycast's public technical post: [A Technical Deep Dive into the New Raycast](https://www.raycast.com/blog/a-technical-deep-dive-into-the-new-raycast)
|
||||
- Reverse engineering of `Raycast Beta.app` v0.60.0 (macOS 26+ build, Xcode 17, arm64) — see [`references/07-evidence-raycast.md`](references/07-evidence-raycast.md) for what was found and how.
|
||||
- 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 — see [`LICENSE`](LICENSE).
|
||||
MIT —— 详见 [`LICENSE`](LICENSE)。
|
||||
|
||||
## Credits
|
||||
|
||||
Authored as an Agent Skill. The architecture this skill describes is Raycast's; the philosophy is the author's synthesis; the evidence is from the shipping app.
|
||||
以 Agent Skill 形式撰写。本 skill 描述的架构来自 Raycast；哲学观点为作者综合提炼；证据取自已发布应用。
|
||||
|
||||
Reference in New Issue
Block a user