Zed 功能开发流程：从需求论证到发布提案的完整工程指南

本文基于 Zed 仓库中的 功能开发流程文档，系统讲解 Zed 团队对“中大型功能”（新 UI、行为变更、跨模块改动）所要求的设计与论证流程：如何为功能立项收集证据、如何撰写一份具体的功能陈述、如何走查十项影响面清单（快捷键、设置、主题、Vim 模式、远程开发、持久化、无障碍、平台差异、性能、安全），并最终以 GitHub Discussion/Issue/PR 的形式落地。读完后，你可以按同一套模板为自己的 Zed 功能提案组织材料，并在仓库中找到每个检查项对应的源码位置作为佐证。

适用对象：哪些改动必须走完整流程

文档开篇即划定了适用边界：本流程面向中大型功能——新增 UI、行为变更、或横跨 Zed 多个部分的工作。而小型改动，例如新增一个快捷键（keybinding）或调整某项设置，不需要完整执行这套流程。

这个边界在 CONTRIBUTING.md 中得到呼应：贡献指南明确列出了团队偏爱的 PR 类型，其中就包括“为现有功能做小型增强”和“小型附加功能，比如其他编辑器里缺失的快捷键或动作”。换句话说：

• 小改动 → 直接提 PR，附测试与截图即可；
• 中大型功能 → 先读流程文档，用 Discussion 立项，再进入编码。

前置要求：动手前先确认团队是否想要这个功能

文档中有一段针对外部贡献者的加粗提醒，核心信息有三点：

1. 投入大量精力之前，先确认这是团队想要的功能；
2. 先阅读 贡献指南 与官方的功能请求（Feature Request）规范——如果已经存在一个带有工作人员明确确认的 GitHub issue，可以直接推进；否则应当从 GitHub Discussion 开始，而不是直接提 PR；
3. 跳过这一流程的功能请求 PR，合并率极低（文档原文用了 "very low merge rate"）。

CONTRIBUTING.md 从维护者视角给出了同样的警告：团队大致只合并提交的 PR 的一半，且“如果你希望 PR 有最好的合并几率，首先要确保这个变更是被想要的——功能应当先与我们确认”；对于任何提议修改 Zed 扩展 API 的变更，这一要求尤其严格。它还给出了一条明确的操作指引：

打算提议或构建一个较大的功能？不要从 PR 开始，先阅读功能流程文档，了解如何提供上下文、考虑哪些集成点、以及如何组织一份有力的提案。提案的正确位置是 GitHub Discussions（而非 GitHub issues）。

第 1 步：Why does this matter —— 为功能立项找证据

文档强调“每个功能都始于一个想法”，但在写任何代码之前，必须先把想法“钉死”（ground it）。需要回答三个问题：

• 它解决什么问题？
• 证据是什么？ 例如 GitHub issues、Discord 里的用户请求、点赞（thumbs-up）数量、相关博客文章等；
• 有没有先例（prior art）？ 如果 VS Code、JetBrains、Neovim 或某个极受欢迎的插件里已经有类似功能，这就是一个强信号。如果你的想法更新颖，就应该说清楚它“基于什么”——文档给出的对比示例很直白：“这是 X 功能，针对 Zed 的多缓冲区（multi-buffers）做了适配”，远比“我觉得这个会很酷”有用得多。

这一步的价值在于把“我觉得不错”转化为可被团队评估的证据链：问题定义 + 需求热度 + 行业参照。

第 2 步：What is it —— 写一份具体、短小的功能陈述

文档要求：用几句话写出功能陈述（feature statement），并用第 1 步收集到的上下文支撑它。如果无法用几句话描述这个功能，说明它可能太大或太模糊。

文档给出了一个可以直接套用的格式模板，以 “Inline Git Blame” 为例：

Feature（功能）： Inline Git Blame

Purpose（目的）： 在编辑器文本的每一行之后直接显示该行最后一次提交的作者和提交信息，让开发者无需打开 git blame 就能理解代码历史。

Background（背景）： 这是所有主流代码编辑器的标配功能：

• （VS Code 的截图）
• （IntelliJ 的截图）
• （Neovim 的截图）
• 并且对应的 GitHub issue 有 146 个点赞。

Decisions（决策）： 需要决定使用 git CLI 还是 git 库。Zed 使用的是 git 库，但它的 blame 实现对代码编辑器来说太慢，因此应当使用 CLI 的 porcelain 接口。

注意这个模板的四个字段各有分工：Purpose 定义用户价值，Background 提供先例与需求证据，Decisions 提前暴露关键技术取舍——在提案阶段就点明“库 API 太慢、改用 CLI porcelain 接口”，能显著减少后续评审中的来回。文档同时说明这只是示例格式，你可以按自己功能的特点裁剪，但“短小、具体、有依据”的原则不变。

第 3 步：What else does this affect —— 十项影响面清单

这是整个流程中最实操的部分。文档要求在动手构建前逐项走查下面这张清单（并非每一项都会用到）：

检查项	需要回答的问题
动作与快捷键（Actions & keybindings）	功能定义了哪些动作？默认快捷键是否与现有绑定冲突？
设置（Settings）	行为是否可配置？按用户、按项目还是按语言区分？别忘了把新设置加进 Settings UI
主题与样式（Themes & styling）	是否需要新的语义化 token（semantic token）？亮色和暗色模式下看起来是否都正确？
Vim 模式（Vim mode）	Vim 用户对该功能可能有不同的预期
远程开发（Remote development）	功能在远程项目下是否可用？文件路径、shell 命令、环境变量都可能表现不同
重启后持久化（Persistence across restarts）	功能状态是否应当跨重启保留？
无障碍（Accessibility）	是否支持键盘导航？焦点状态是否清晰？
平台差异（Platform differences）	macOS、Linux、Windows 上行为是否有差异？
性能（Performance）	面对大文件或大型项目时表现如何？交互是否即时？
安全（Security）	功能与 Workspace Trust 如何交互？是否给 Zed 打开新的攻击面？

下面结合仓库源码，说明几个检查项在 Zed 中的具体落点，方便你把“清单”落到“代码”：

设置：新设置必须注册进 Settings 结构并同步到 Settings UI

文档特别提醒“别忘了把新设置加到 Settings UI”。在仓库中，设置的声明与解析集中在 settings crate——各功能通过 impl Settings for XxxSettings 声明可配置字段，由 settings_store.rs 负责加载与监听变更；而图形化的设置面板由 settings_ui 实现，按 pages 目录 组织各设置页面。从源码结构看，一个新设置如果只在 settings.rs 中声明而不出现在 Settings UI 中，用户就无法在界面里发现和修改它——这正是文档这条提醒对应的工程事实。所有内置设置项的完整清单可参考 全量设置文档。

主题与样式：新增语义 token 需要理解 Zed 的 token 体系

清单中“是否需要新的语义 token”对应仓库中的两套机制：一方面，语义化 token 文档 描述了编辑器内容着色如何映射到主题；另一方面，仓库自带默认规则文件 default_semantic_token_rules.json。从源码结构看，如果你的功能引入了新的元素类型（如新的行内注释样式），就需要确认它在现有 token 集合中有归属，或按该文档的说明新增 token 并验证亮/暗两套主题下的表现。

快捷键：先核对默认键位映射，避免冲突

“默认快捷键是否与现有绑定冲突”这一项，可以直接对照仓库中的默认键位映射来检查，例如 default-linux.json、default-macos.json、default-windows.json 以及 initial.json，各平台差异可进一步查看 keymaps 目录。Zed 中功能的“动作（action）”定义与键位解耦（动作定义在代码中，键位在 keymap 中绑定），所以提案阶段就应明确：这个功能声明了哪些 action、打算绑定到哪些键、与哪些现有键位可能冲突。

安全：Workspace Trust 是功能提案的必答题

清单把“该功能与 Workspace Trust 如何交互”单列出来，因为 Zed 对不受信任的项目会进入受限模式。这一机制的实现在 security_modal.rs：当用户打开未受信任的项目时，安全弹窗会提示“Untrusted projects are opened in Restricted Mode to protect your system”，用户选择信任后，信任状态写入 trusted_worktrees 模块并影响工作区的可用能力。因此，任何会执行命令、访问文件、解析外部数据的新功能，在提案里都必须说明：它在 Restricted Mode 下如何降级？是否引入新的注入面？

持久化与远程开发：分别对应 workspace 序列化与 remote 三件套

• 持久化：工作区状态的序列化逻辑位于 persistence.rs。如果功能持有跨会话状态（例如某个面板的展开状态、任务运行状态），提案中应明确哪些状态要持久化、以什么格式存储。
• 远程开发：Zed 的远程能力分布在 remote、remote_connection、remote_server 等 crate。文档提醒“文件路径、shell 命令、环境变量都可能表现不同”，含义是：在本地绝对路径、本地 shell 环境里成立的假设，在远程项目里可能不成立——比如读取本地配置文件的逻辑在远程端要改读远程机器上的文件。

Vim 模式与编辑器专项检查

Vim 支持是一个独立层，实现在 vim crate。文档把 Vim 单独列出，是因为 Vim 用户对“光标移动、模式切换、动作语义”的默认预期与普通模式不同，同一个功能在两种工作流下的行为契约可能完全不同。

此外，文档对触碰 editor 的功能加了一段专项提示：编辑器内部有大量并存的功能——gutter 元素、inline blocks、多光标、代码折叠、edit prediction（编辑预测）、代码智能 popover、minimap——测试时必须让这些功能的不同组合同时处于激活状态。并且“在普通 buffer 中可用的功能，在 multi-buffer 中可能需要禁用”。这些交互对象都集中在 editor crate 中，例如 edit prediction 相关逻辑在 editor.rs 中就有多处集成点；这也解释了为什么 Zed 要求 UI 变更考虑视觉回归测试（CONTRIBUTING.md 在“发送变更”一节中建议为 UI 变更更新 visual regression tests）。

第 4 步：Ship it —— 把研究结论变成 Discussion / Issue / PR 描述

文档的最后一步只有一句话，但点明了整个流程的产出物：把前三步的成果（为什么做、是什么、影响什么）作为 GitHub Discussion、issue 或 PR 描述的底稿。好的产品研究能让所有人对齐三件事——目标、行业现状（state of the art）、可能需要考虑的取舍（tradeoffs）。

落地时可以按这份隐含的“提案骨架”组织文字：

1. Purpose / Background（来自第 1、2 步：问题、证据、先例、功能陈述）；
2. Decisions（关键技术路线与已识别的取舍，如 git CLI vs 库）；
3. Impact checklist（第 3 步十项清单中实际命中的条目，逐条给出你的结论：影响什么、计划怎么做、或明确不受影响）；
4. 后续计划（先做 Discussion 还是先提 early PR 对齐方向——CONTRIBUTING.md 建议“尽早开 PR，以便带着代码讨论”）。

延伸阅读：与仓库内其他规范文档的关系

这套功能流程不是孤立存在的，与仓库内两份文档构成“立项—实现—验收”的链条：

• 功能开发流程（本文主体）：立项论证与影响面分析；
• CONTRIBUTING.md：PR 提交规范、合并偏好、AI 使用政策，以及一份详细的 UI/UX checklist（可访问性、响应式、平台一致性、性能——包括“所有交互必须即时反馈”“帧时间不得超过 8ms 以维持 120fps”等硬性标准，恰好是流程文档中“性能”检查项的量化版本）、以及 Zed 各核心 crate 的鸟瞰图（gpui、editor、project、workspace、vim、lsp 等），可作为影响面分析时定位代码的地图；
• 术语表：CONTRIBUTING 建议初贡献者常备在侧，覆盖代码库中反复出现的结构名词。

一句话总结：Zed 的功能流程本质上是一份“提案前自检单”——用三问完成立项（为什么、是什么、影响什么），用十项清单完成影响面走查（每项都有明确的仓库代码落点可查），最后把研究结论固化为 Discussion/PR 描述。对贡献者而言，走这套流程本身就是合并率最高的路径。