---
title: "AI 开发 Skill — zenit Zig UI 文档"
description: "一份给 Claude Code 等 AI Agent 的开发说明书。装上之后，Agent 写 zenit 界面时会先选现成组件、用 token 和样式配方、按 zenit 的…"
url: https://zenit.z.express/zh/docs/guide/ai-skill
language: zh-CN
alternate_en: https://zenit.z.express/docs/guide/ai-skill.md
alternate_es: https://zenit.z.express/es/docs/guide/ai-skill.md
alternate_ja: https://zenit.z.express/ja/docs/guide/ai-skill.md
alternate_ko: https://zenit.z.express/ko/docs/guide/ai-skill.md
alternate_fr: https://zenit.z.express/fr/docs/guide/ai-skill.md
alternate_de: https://zenit.z.express/de/docs/guide/ai-skill.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# zenit UI dev Skill

一份给 Claude Code 等 AI Agent 的开发说明书。装上之后，Agent 写 zenit 界面时会先选现成组件、用 token 和样式配方、按 zenit 的生命周期管理状态，并在交付前构建、截图自验。

## 下载

压缩包内是一个标准的 Agent Skill 目录：入口 `SKILL.md` 很短，只放规则和决策表；细节拆在 `references/` 里，Agent 按需读取，不占上下文。

[下载 Skill.zip · 54 KB](https://zenit.z.express/downloads/zenit-ui-dev.zip)[在线查看 SKILL.md](https://zenit.z.express/downloads/zenit-ui-dev.SKILL.md)

zenit-ui-dev/

SKILL.md9.6 KB

references/

app-architecture.md7.2 KB

components.md8.3 KB

macos-native.md8.2 KB

pencil-design.md7.9 KB

performance.md4.1 KB

pitfalls.md8.5 KB

project-setup.md8.1 KB

state-reactivity.md7.8 KB

styling.md5.8 KB

ui-tree-layout.md6.1 KB

verification.md5.7 KB

tools/

design\_diff.ts20.6 KB

png.ts3.6 KB

shot.ts3.7 KB

## 安装

1.  **放进 Skill 目录**
    
    个人使用放 `~/.claude/skills/`，对所有项目生效；团队共享放仓库里的 `.claude/skills/` 并提交，克隆仓库的人自动获得。
    
2.  **重启 Agent 会话**
    
    Claude Code 在会话开始时扫描 Skill。新开会话后，输入 `/skills` 能看到 `zenit-ui-dev` 即安装成功。
    
3.  **像平时一样提需求**
    
    涉及 zenit 界面的任务会自动加载它，也可以显式说「用 zenit-ui-dev skill」。
    

下载后解压到个人目录（所有项目生效）：

解压到

```zig
~/.claude/skills/
└── zenit-ui-dev/
    ├── SKILL.md
    ├── references/
    └── tools/
```

或解压到项目目录并提交（团队共享）：

解压到

```zig
.claude/skills/
└── zenit-ui-dev/
    ├── SKILL.md
    ├── references/
    └── tools/
```

```sh
# Codex and other agents that read AGENTS.md: unpack into the repo and reference it
unzip -oq zenit-ui-dev.zip -d .agents/skills
echo '- zenit UI: read .agents/skills/zenit-ui-dev/SKILL.md before writing UI code' >> AGENTS.md
```

> NOTE
> 
> **跟随 zenit 版本更新。** zenit 在 1.0 之前允许破坏性变更。升级 zenit 后重新下载本 Skill 覆盖旧目录；Skill 里写明了它对应的 zenit 版本，Agent 发现与项目中的 API 不一致时会以源码为准。

## 里面有什么

| 文件 | 内容 |
| --- | --- |
| `SKILL.md` | 入口：触发条件、工作流、硬规则、决策表，以及何时读哪份 reference |
| `references/app-architecture.md` | 以一个生产级编辑器为例的大型应用分层：状态、视图、命令、服务 |
| `references/components.md` | ui.widgets 目录、两种 mount 形态、「设计元素 → 组件」选型表 |
| `references/macos-native.md` | 菜单、快捷键、文件对话框、剪贴板、拖拽、多窗口、IME |
| `references/pencil-design.md` | Pencil（pen.dev）设计稿还原：MCP 读数值、字段映射、截图数值比对 |
| `references/performance.md` | 虚拟列表、脏标记、大文本、后台线程与主线程通信 |
| `references/pitfalls.md` | 从 zenit 与生产项目修复记录整理的「现象 → 原因 → 正确做法」 |
| `references/project-setup.md` | 新建项目、build.zig / build.zig.zon、打包 .app、构建选项转发 |
| `references/state-reactivity.md` | bindState / cx.on、Signal / Memo / Effect、Scope 生命周期与清理 |
| `references/styling.md` | Token → styles.zig → recipe 三层、主题、ui.arb 逃生舱 |
| `references/ui-tree-layout.md` | 节点、Flex 布局、尺寸、更新节点、显隐、坐标 |
| `references/verification.md` | Agent 自验闭环：构建、截图、E2E harness、DevTools、日志 |
| `tools/design_diff.ts` | 设计稿 PNG 与应用截图的数值比对，输出可执行的修改提示 |
| `tools/png.ts` | design\_diff 使用的零依赖 PNG 解码器 |
| `tools/shot.ts` | 通过文件 RPC 给任意 zenit 应用截图（Retina） |

**先选组件，再手搓**

把设计稿里的每个元素映射到 ui.widgets 里的现成组件，避免 Agent 用 box 重新拼一个 Button。

**生命周期写对**

bindState、pub deinit、Scope 清理与页面切换的规则，直接对应最常见的泄漏、重复释放和悬垂指针。

**交付前自己看一眼**

要求 Agent 构建、运行、截图并对照需求检查，而不是只看编译通过。

**真实项目的坑**

从真实生产项目的修复记录里整理出的问题清单，每条都有原因和正确做法。

## 推荐：搭配 Pencil 设计

[Pencilpen.dev](https://www.pen.dev/)

推荐工作流 · PENCIL + SKILL

推荐搭配 Pencil，设计 + AI 一起开发

我们推荐用 [Pencil](https://www.pen.dev/) 画界面，再让 Agent 结合本 Skill 实现。.pen 的 Flex 布局、间距、圆角、字号和 lucide 图标与 zenit 的模型很接近；Skill 里附了字段映射表和 design\_diff 比对工具，方便 Agent 按数值而不是凭感觉还原。

[了解 Pencil](https://www.pen.dev/)

1.  01.penPencil 设计稿
2.  02MCPAgent 读取精确数值
3.  03zig组件 + token 写出 zenit 代码
4.  04diff截图与设计稿数值比对

1.  **连接 Pencil MCP**
    
    在 Agent 里启用 Pencil 的 MCP server 并打开 .pen 文件。Skill 规定 .pen 只能通过 MCP 读取：MCP 会展开设计变量、给出解析后的真实尺寸，这两样是还原最需要的。
    
2.  **读数值，不看图**
    
    Agent 先用 `Get(nodeId, { resolveVariables: true })` 拿到 gap、padding、圆角、字号和颜色，再按映射表写成 zenit：`fill_container → .fill()`，`chevron-down → ui.icons.chevron_down`。
    
3.  **数值比对到对齐**
    
    导出设计稿（scale 2），用 `tools/shot.ts` 截取真实窗口，`tools/design_diff.ts` 给出位移、尺寸差、热力图与配色偏差，Agent 按提示修改；每轮约 5 秒。
    

```sh
SKILL=~/.claude/skills/zenit-ui-dev
bun $SKILL/tools/design_diff.ts --self-test
ZENIT_E2E_FILE_RPC_DIR=$RPCDIR bun $SKILL/tools/shot.ts /tmp/actual.png
bun $SKILL/tools/design_diff.ts /tmp/design/<nodeId>.png /tmp/actual.png
```

## 怎么用

不需要特殊语法。描述你要的界面或问题即可，下面是几个效果较好的提法：

```
用 Pencil MCP 读取当前 .pen 里的「Settings」画板，用 zenit 还原成设置窗口，design_diff 分数到 90 以上再交给我。
用 zenit 给这个 app 加一个设置窗口：左侧分类列表，右侧表单，改动实时生效。
把 src/views/sidebar.zig 里手写的样式迁移到 styles.zig + recipe。
文件树 5 万个节点时滚动卡顿，帮我查原因并修掉，修完截图给我看。
```

> TIP
> 
> **给出验收方式。** 在需求里写上「修完截图给我看」或「用 E2E 验证」，Agent 会按 Skill 里的自验流程执行，你拿到的是看过效果的结果。

## 内容来源

Skill 的规则来自两个项目：zenit 框架本身（公开 API、示例、组件目录、测试工具），以及一个基于 zenit 开发的生产级 macOS 编辑器（大型应用的分层方式、原生集成和修复记录）。示例代码尽量取自这两个仓库中可编译的代码，并与本手册保持一致。

源文件在官网仓库的 `skill/zenit-ui-dev/`，构建时由 `scripts/pack-skill.mjs` 打包。也可以直接[阅读 SKILL.md](https://zenit.z.express/downloads/zenit-ui-dev.SKILL.md)。