Zed 贡献指南：PR 规范、AI 使用政策与核心 Crate 全景图

2026-09-05 14:50:36作者：傅爽业Veleda

本文为 Zed 代码编辑器开源仓库的完整贡献指南：覆盖从贡献前置要求、受欢迎的 PR 类型、大型功能的立项流程，到 PR 合并标准、AI 辅助编码政策，以及代码库核心 crate 的架构地图。读完后你将知道哪些改动有合并机会、大型功能如何走提案流程，以及如何快速定位 Zed 源码中 gpui、editor、project 等关键 crate 的职责边界，从而高效地向项目提交高质量的变更。

贡献前置要求：行为准则与 CLA

在开始贡献之前，有两项硬性前提：

Zed 社区论坛中的所有活动都受 Zed 行为准则（Code of Conduct）约束，贡献者需遵守社区规范；
所有贡献者在贡献被合并前必须签署 Zed 的 CLA（贡献者许可协议）。

这两项是合并流程的门槛，建议在提交第一个 PR 前就完成 CLA 签署，避免 PR 提交后因法务流程被搁置。

Zed 欢迎什么样的贡献

Zed 是一个大型项目，维护团队把大部分精力放在自认为产品最需要的方向上，但也明确欢迎社区在维护者尚未想到（或没来得及做）的维度上改进产品。文档中列出了被优先欢迎的 PR 类型：

修复或完善文档；
修复 Bug；
对现有功能的小型增强，使其对更多人可用（例如适配更多平台、更多工作模式）；
小型附加功能，例如其他编辑器中常用但 Zed 尚缺的键位绑定、动作或扩展；
属于社区计划（Community Program，如官方发起的 Let's Git Together、The Guild 等活动）的任务；
维护者明确标注为开放社区贡献的功能。

文档同时给出了寻找具体切入点的官方渠道（均为仓库或官方社区内的检索入口，此处以文字描述）：文档类 issue、面向首次贡献者的 good first issue 与面向老贡献者的 good non-first issue、带有可复现步骤的已分诊 Bug、按 area:* 标签浏览特定模块的 Bug 列表，以及维护者公开征集社区参与的功能看板。

大型功能：先走 Feature Process，不要直接开 PR

如果你打算提议或实现一个较大的功能，官方建议不要从 PR 开始，而是先阅读仓库内的功能开发流程文档，理解 Zed 团队如何看待功能设计：需要给出哪些上下文、需要考虑哪些集成点、如何组织一份强提案。该流程的核心要求可以概括为四步：

为什么重要：明确功能解决什么问题，给出证据（issue 讨论、社区请求、thumbs-up 数量、同类产品的先例）；
它是什么：用几句话写出具体的功能陈述并附上背景，若无法简短描述，说明功能可能过大或过模糊；
它还影响什么：逐条过一遍集成检查清单——动作与键位是否冲突、行为是否可配置（按用户/项目/语言）、主题与语义 token、Vim 模式预期、远程开发行为、重启后的持久化、可访问性、平台差异、性能、以及与 Workspace Trust 相关的安全面；如果功能直接触碰编辑器，还要在 gutter 元素、inline 块、多光标、折叠、编辑预测、代码智能弹出、缩略图等多种组合开启的状态下测试；
落地：把以上内容作为 GitHub Discussion、issue 或 PR 描述的基底。

该文档特别强调：提案应放在 GitHub Discussions 而不是 issues 里，且若没有 staff 明确确认想要该功能，功能类 PR 的合并率非常低。

提交变更：PR 文化与合并标准

Zed 的团队文化明确偏向“能跑的代码 + 同步沟通”而非冗长的讨论串。官方建议的最佳提交方式是直接开 PR（新功能除外），并等待回复。文档中有两条非常直白的提醒：

@ 维护者或发邮件不会提高 PR 的处理优先级，只会消耗维护者的时间；
若需要更多反馈，最有效的做法是对 GitHub 评论保持快速响应，或主动约时间结对编程；如果卡在某处，尽早开一个 WIP PR，让维护者“拿着代码”和你讨论。

同时官方坦承：提交的 PR 大约只有一半会被合并。为了让 PR 有最好的合并机会，文档给出了完整清单：

确认变更是被需要的：Bug 修复随时欢迎，但功能类改动应先与团队确认。如果没有已获 staff 确认的 GitHub issue 支撑，先开 GitHub Discussion 而不是 PR——这条对提议修改 Zed 扩展 API（Extension API）的改动尤其适用；
清晰描述你在解决什么问题，以及为什么它重要；
包含测试。对 UI 改动，考虑更新视觉回归测试（见下文 macOS 视觉回归测试一节）；
若改动在 UI 上可见，附上截图或屏幕录像；
PR 只围绕一件事：如果是 Bug 修复，不要顺带加两个功能加一次重构；
AI 辅助要保持在你的判断和责任范围内：作者自己都不理解的“vibe-coded”PR 很难被合并。

每个作者最多 3 个开放 PR

文档明确说明：当前对每位作者的开放 PR 数量上限为 3 个。理由有三：

经验规律是第一个 PR 落地后，后续 PR 的合并概率会显著提升；
同时挂着一堆 PR 容易在移动的 main 分支上“烂尾”；
当贡献速度超过 review 能力（包括偶尔出现的自动化提交洪峰）时，限流能保持评审秩序。

官方建议的路径是：先开一个，把它走完，再开下一个。

通常不会被合并的改动

虽然维护者强调“没有硬性规则”，但文档列出了典型的拒收清单：

任何可以用扩展提供的内容，例如新语言支持或新主题——应通过扩展机制（Zed 扩展开发文档）完成，而不是改主仓库；
没有事先与 Zed staff 讨论就提交的扩展 API 改动；
新文件图标：Zed 默认图标主题是由设计团队手工设计、保证视觉整体性的，不接受“现成 SVG”式提交；
维护者主观判断“复杂度收益比不成立”的功能；
巨型重构；
无测试的非平凡改动；
不改变应用逻辑的纯风格改动：减少分配、去掉 .unwrap()、修错字都是好改动，但把代码改得“更易读”这种纯主观调整可能不被接受；
任何看起来是AI 生成且作者不理解其输出的内容。

AI 政策要点

Zed 欢迎使用 LLM 辅助编码，但标准很高，核心立场是必须有一个真正理解 LLM 产出的人类在回路中。具体规则：

不接受来自自主 agent 的贡献，违反此条的 PR 可能被直接关闭（有时不通知）；
与维护者的沟通（评论回复、PR 描述等）不要完全交给 LLM 代写——“读者是人，我们想听你说话，而不是模型说话”；非英语母语者若用 LLM 精修或翻译消息，建议把机器翻译放在引用块中，并在其后附上母语原文；
若认为有必要分享与 LLM 对话的上下文，只放相关部分到引用块（>）中，明确标注其为 AI 生成，并附上你自己的评注说明它为何相关、你从中得出了什么。

该政策改编自 ripgrep 项目的 AI policy。

评审者内部判断准则

文档还罕见地公开了内部评审的三档决策逻辑，可作为提交前自查的参照：

功能/修复显然优秀，且代码优秀 → 直接合并；
功能/修复显然优秀，代码接近优秀 → 发 PR 评论，或邀结对打磨到位；
功能/修复不显然优秀，或代码需要推倒重写 → 附带感谢和说明后关闭 PR。

UI/UX 自查清单

如果你的改动影响 UI，文档要求对照以下完整清单自查：

可访问性 / 人体工学

所有键盘快捷键是否按预期工作？
快捷键是否可被发现（tooltip、菜单、文档）？
是否可以完全不用鼠标（纯键盘导航）使用？
所有鼠标操作是否都正常（拖拽、右键菜单、调整大小、滚动）？
功能在浅色和深色主题下是否都美观？
hover 状态与焦点指示是否清晰一致？

响应式布局

UI 能否在以下环境优雅伸缩：窄面板（并排分屏）、短面板（13 英寸笔记本）、高 DPI / Retina 屏；
调整面板或窗口大小时 UI 是否依然可用且美观；
对话框和模态是否保持居中且不出视口边界。

平台一致性

功能在 Windows、Linux、macOS 上是否都完整可用；
是否尊重系统级设置（字体、缩放、输入法）。

性能

所有用户交互必须即时反馈；若用户请求了慢操作（如 LLM 生成），必须有工作进展的指示；
处理大文件、大项目或重负载时不能退化；
帧耗时不得超过 8ms（对应 120fps）。

一致性

是否符合 Zed 设计语言（间距、排版、图标）——图标需参照 crates/icons 的图标设计指南（16x16 视图框、1.2px 描边、内部 12x12 包围盒、filled/outlined 命名约定等）；
术语、标签与语气是否与 Zed 其余部分一致；
交互模式是否一致（标签如何关闭、模态如何退出、错误如何展示）。

国际化与文案

字符串是否简洁、清晰、无歧义；
是否避免了只有内部人员才懂的 Zed 黑话。

用户路径与边界情况

快乐路径是什么样？不快乐路径（错误、拒绝、非法状态）呢？
离线与在线状态下的表现；未认证与已认证状态下的表现；
数据缺失、损坏或延迟时如何表现；
错误信息是否可操作、且符合 Zed 的表达风格。

可发现性与学习曲线

首次用户无需文档能否上手；
是否存在直觉化的撤销/重做；
高级功能是否可发现但不打扰；
是否有从新手到专家的路径（渐进式披露）。

代码库全景：核心 Crate 一览

官方建议贡献者常备 Zed 术语表在手——它解释了贯穿整个代码库的结构和术语，例如 GPUI 中的 App、Entity、Context、Task 等状态管理概念，以及 Window、Pane、Dock、Project、Worktree、Multibuffer 等 UI 结构概念。

Zed 由若干较小的 Rust crate 组成，文档列出了贡献者最可能打交道的核心 crate：

Crate	职责
gpui	GPU 加速的 UI 框架，提供 Zed 的全部 UI 构建块；官方建议先熟悉其根级文档
editor	核心 `Editor` 类型，驱动代码编辑器和 Zed 内各种输入框；同时处理 Inlay Hints、代码补全等 LSP 功能的展示层
project	管理文件树中的文件与导航，也是 Zed 侧与 LSP 通信的一方
workspace	处理本地状态序列化，并把多个项目分组到窗口中
vim	在 `editor` 之上的 Vim 工作流薄实现
lsp	与外部 LSP 服务器通信
language	驱动 `editor` 对语言的理解——从符号列表到语法映射
collab	协作服务器本体，驱动项目共享等协作功能
rpc	定义与协作服务器之间交换的消息
theme	定义主题系统并提供默认主题
ui	贯穿 Zed 的 UI 组件与通用模式集合
cli	调用 Zed 二进制的 CLI crate
zed	所有东西汇聚之处，Zed 的 `main` 入口点

结合源码验证的架构细节

工具链：仓库根目录的 rust-toolchain.toml 锁定了 Rust 工具链为 1.97.1（minimal profile，含 rustfmt、clippy、rust-analyzer、rust-src 组件），并声明了三个额外编译目标：wasm32-wasip2（扩展）、wasm32-unknown-unknown（Web 版 gpui）、x86_64-unknown-linux-musl（远程服务器）。这也解释了上表中扩展 API 与远程开发在架构中的位置。

gpui 的三层 API：从 crates/gpui/README.md 可以看到，GPUI 被描述为“混合即时与保留模式、GPU 加速的 Rust UI 框架”，并提供三种使用层次：基于 Entity 的状态管理与通信、通过实现 Render trait 的 View 进行声明式 UI、以及用于精细控制的底层 Element 命令式 API；独立应用以 gpui_platform::application() 创建 Application 并通过 App::open_window() 开窗口。理解这一层是读懂 Zed 全部 UI 代码的前提。

入口点：crates/zed/src/main.rs 即上表所述的全局 main 入口，所有 crate 最终在此装配；同目录下的 crates/zed/src/visual_test_runner.rs 则实现了下文提到的视觉回归测试运行器。

macOS 视觉回归测试（PR 要求的一部分）

由于“包含测试”是 PR 合并标准之一，而 UI 改动的测试手段是视觉回归测试，这里补充其完整操作（见 docs/src/development/macos.md）：

该测试会捕获真实 Zed 窗口截图并与基线图片对比，仅在 macOS 上可用，且终端需要获得屏幕录制权限（首次运行会自动弹窗，或手动在“系统设置 > 隐私与安全性 > 屏幕录制”中授权并重启终端）。

运行命令：

cargo run -p zed --bin zed_visual_test_runner --features visual-tests

基线图片存储在 crates/zed/test_fixtures/visual_tests/ 目录，但被 gitignore 以避免仓库膨胀，因此需要先在已知良好状态下本地生成基线：

git checkout origin/main
UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests
git checkout -

之后再切回自己的分支运行同一命令，即可比对 UI 变更是否引入了视觉回归。

打包 Zed 的说明

对于打包相关的工作，CONTRIBUTING.md 将读者指向 Zed 官方文档中的 “Notes for packaging Zed” 一节（位于官方开发文档的 Linux 页面）。仓库中同样存在对应的构建脚本可供参考，例如 script/bundle-linux、script/bundle-mac、script/bundle-windows.ps1 与 script/bundle-freebsd，它们分别对应各平台的产物打包流程；Dockerfile-distros 则用于多发行版打包的容器环境。