From 3074d8b2a6d4d9201fb3113557c8275aba95250f Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:22:13 +0000 Subject: [PATCH] docs: make Chinese README the default --- README.md | 106 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 56 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index ca498ab..4a98953 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,39 @@ + +> [!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 -> *"Cross-platform development AND near-native performance — refuse the trade-off."* +> *"跨平台开发 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)
-**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 项上线审计 —— 让应用兼得两者。
-**Install** — pick one: +**安装** —— 任选其一：
-**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:
-[Use cases](#use-cases) · [What this is](#what-this-is) · [Philosophy](#philosophy) · [Layout](#layout) · [Sources](#sources) +[使用场景](#use-cases) · [这是什么](#what-this-is) · [理念](#philosophy) · [目录结构](#layout) · [来源](#sources)
--- -## 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；哲学观点为作者综合提炼；证据取自已发布应用。