Zed 扩展发布与维护 FAQ：审核周期、PR 规则与失联接管政策全解读

Zed 扩展发布生态有一套围绕 zed-industries/extensions 扩展仓库运转的治理规则：从提交 PR 前的前置检查、审核周期与 PR 存活规则，到扩展发布后的维护义务、Bug 上报路径与“所有者失联”时的接管机制，本文结合 发布 FAQ 原文 及 Zed 仓库内的相关文档与源码，系统梳理这些规则“是什么、为什么、踩坑了怎么办”，帮助你作为扩展作者或维护者顺利走完发布、更新与长期维护的全流程。

关联文档与扩展发布流程全景

FAQ 并非孤立的问答清单，它隶属于 Zed 文档中 “Extensions → Publishing” 一节，与下面几份文档共同构成完整的发布流程：

• 发布概览：三步走入口——检查前置要求、补许可协议、按发布指南提交；
• 发布前置要求：通用、语言、语言服务器、调试器、主题、图标主题、代码片段、MCP 服务器等各类扩展各自必须满足的门槛；
• 许可协议要求：可接受的许可证白名单与放置位置；
• 发布指南：以 PR 提交扩展的具体操作步骤与 PR 规则；
• 更新扩展：发布后如何发新版本；
• 发布 FAQ：本文主体，回答围绕发布与维护的高频问题。

FAQ 全文覆盖了三个阶段的问题：发布中（审核多久、PR 为何被关）、发布后维护（是否有维护义务、Bug 去哪报、如何退场）、极端情况治理（所有者失联怎么办、为何不能复用别人的 grammar）。下面按这三个阶段展开。

投稿审核时长：需要等多久，为什么慢

对应原文档条目：How long will the review of my submission take?

Zed 团队坦诚地说明：目前无法对审核时长做任何承诺。经验数据是：

• 大多数提交在数周内能收到第一轮反馈；
• 部分扩展可能需要更久，最长可达一到两个月；
• 个别情况下甚至更长，最主要的原因是评审队列存在大量积压（backlog）。

FAQ 特别指出，这份文档本身也是他们改善贡献者体验的努力之一——即通过公开这些“幕后规则”让作者对流程更有预期。对开发者而言的实践含义是：提交后不要因短期无回复而反复催促或重复提交；如果想加速流程，应当把精力放在提交质量上，确保一次通过评审（见下面前置要求相关条目）。

PR 关闭规则：三类触发条件与“3 周无响应”红线

对应原文档条目：Why was my PR closed?

扩展发布以 PR 形式提交到扩展仓库，并受 发布指南 中“pull request rules”约束。综合两份文档，PR 被关闭主要分两种情况：

1. 严重违反前置要求而被直接关闭。 前置要求即 发布前置要求 中的清单。FAQ 明确：由于提交量很大，对于这类 PR 不会提供额外解释，作者需要自行对照前置要求复查。

2. 因“失活”（stale）被关闭。 发布指南 规定，任何针对扩展仓库的 PR 必须遵守：

• 每个 PR 只允许新增或更新一个扩展；
• 同一时刻最多只能有三个处于打开状态的 PR；
• 对维护者反馈的响应窗口为 3 周，超过 3 周无响应即视为失活并被关闭。

无论新提交还是更新提交都适用同一套规则。被关闭的原因若是对维护者反馈超过 3 周未回应，作者随时可以重新开一个全新 PR，评审团队会再次处理——失活关闭并非“终审判决”。

在 Zed 仓库中，扩展提交后由服务端构建、打包并发布到扩展注册表，其构建逻辑可以在 crates/extension/src/extension_builder.rs 等处看到端倪（该文件即负责将扩展清单编译为可分发的二进制）。提交内容的规范性直接决定 CI 与人工评审能否快速通过。

为什么关闭后要求“开新 PR”而不是继续旧的

对应原文档条目：Why was I asked to open a new PR instead of continuing my closed one?

这是不少作者困惑的点。FAQ 给出的原因很实际：

• 积压巨大，全新 PR 能让队列保持更短、更可控；
• 经验表明，全新 PR 通常处于更易于评审的状态；
• 相比之下，在旧 PR 上“声称已修改”的更新往往实际上处于损坏、无法合并的状态，反而浪费评审者与贡献者双方的时间。

因此对维护者而言，全新 PR 处理起来更快，也更容易顺利合并。建议实践：被要求开新 PR 时，务必在本地完整自测后再提交，避免“看似改了、实则跑不起来”。

前置要求为何如此严格

对应原文档条目：Why do you enforce so many strict prerequisites?

FAQ 用两点解释严格前置要求的初衷：

1. 保障基础质量：目标是平衡“开放的扩展生态”与“一定的标准和质量”。用户在 Zed 中安装扩展时，应当能放心其基本可用，而无需自己先审计一遍。即便前置要求无法拦截所有问题，它们也提供了人人都能依赖的基线。
2. 聚合重复劳动：如果多个维护者各自维护“功能几乎相同”的扩展，用户被分散在多个扩展之间，会给所有人带来大量变更成本（churn）。把同类努力引导到一处，对所有者、贡献者、用户三方都有利——每个用例只有一个扩展时，用户也无需猜测该装哪一个。

若扩展最终仍然不可用或无人维护，则交由本文后面“失联接管”的策略处理。

前置要求同样约束已发布扩展

对应原文档条目：Do the prerequisites also apply to already published extensions?

是的。 已发布的扩展并不豁免，其更新提交与新提交遵守同一标准。

唯一的例外是 ID 限制：扩展 ID 一旦发布便不可更改（注册表按 ID 追踪扩展），因此已存在的 ID 保持原样，只约束新扩展。结合 发布前置要求 看，ID 的约束包括：唯一、kebab-case 命名、不得包含 zed 或 extension 字样、能准确反映扩展用途；不同类型的扩展还被要求通过后缀或前缀体现类型，例如语言服务器用 -language-server/-lsp、调试器用 -debugger、主题用 -theme、图标主题用 -icon-theme/-icons、代码片段用 -snippets、MCP 服务器用 mcp-server-/-mcp-server 等。

发布后的维护义务：没有强制，但建议响应

对应原文档条目：Do I have to maintain my extension?

FAQ 给出一个让作者安心的明确答复：发布之后，Zed 团队不会对你的扩展提出任何后续的强制要求，是否持续维护完全自愿。

当然，FAQ 也诚恳地补充：没有扩展在第一天就是完美的——Bug 会暴露、改进请求会到来。虽然维护永不强制，但若能在合理时间窗口内回应用户报告，对所有人都有帮助。

发现他人扩展有 Bug 或想改进：先回上游

对应原文档条目：I found a bug in an extension or want to improve it. What should I do?

当你在使用某个扩展时发现问题，或希望改进它时：

1. 首选：在原始扩展仓库中上报或提出改进建议，而不是另起炉灶发布一个功能重叠的新扩展。
2. 理由与前文一致：多数所有者欢迎报告与贡献；把努力留在单一处，既避免用户在“几乎相同的扩展”之间做选择，也避免维护者重复评审。

这也正是 发布前置要求 中“不得发布注册表中已有功能”这一条的政策基础——遇到既有扩展的问题，先尝试向既有扩展做贡献（详见 FAQ 对应小节 的指引）。

如果所有者长期不回应，才轮到下一节的“失联接管”机制。

放弃维护：转让所有权或申请移除

对应原文档条目：I no longer want to maintain my extension. What now?

想退出时不必有心理负担，FAQ 明确“优先级会变，从扩展抽身不是什么坏事”。作为现任所有者，你有三种选择：

• 转让仓库所有权给新的维护者；
• 在扩展仓库（zed-industries/extensions）上开 issue 或 PR，申请移除你的扩展；
• 只是放着不管也完全可以——FAQ 特别指出，许多扩展虽然几乎没更新过，依然拥有大量满意用户。

所有者失联：社区 fork 与 Zed 官方接管的双轨机制

对应原文档条目：What happens when an extension owner stops responding to reported issues?

Zed 不希望已发布扩展因失联而“腐烂”，从而让用户得到糟糕体验。因此当扩展所有者无法被联系上时，存在两条替代路径：

• 社区 fork：贡献者可以 fork 该扩展，并提议把 fork 作为现有扩展的替代品；
• 官方托管：Zed 团队成员可以把扩展 fork 进 zed-extensions 组织，在那里由“社区 + Zed 团队”联合继续维护。

但只有满足以下条件之一，才会执行上述动作：

1. 现任所有者给出了书面许可；或
2. 存在书面的联系尝试证明，且所有者对这些尝试至少 6 周无响应。

两者都不满足时，扩展维持现状、仍归现任所有者。

FAQ 还补充了两条细则：

• 这种切换不必是永久性的：若原所有者重新变得可联系，扩展可以再切回原始仓库；
• 触发条件用“书面证明”而非口头主张，是为了在缺乏官方仲裁机制的公开生态中留痕可查。

为何语言扩展不能复用内置 grammar 或其他扩展的 grammar

对应原文档条目：Why can't my language reuse builtin grammars or a grammar from another extension?

这是技术上最关键的一条 FAQ，原因是上游变更的“静默破坏”风险：

如果某个语言依赖一份并不归它所有的 grammar，那么当该 grammar（例如内置在 Zed 或另一扩展中）更新时，Tree-sitter 解析产生的节点结构可能随之改变，进而无声地破坏依赖它的语言（语法高亮、缩进、大纲、代码注入等基于语法树的功能都会受影响）。为了避免这种脆弱的隐式耦合，规则要求：

每种语言必须使用自己扩展的 extension.toml 中声明的 grammar。

也就是说，grammar 的所有权必须与使用它的语言同属一个扩展。这一要求在 语言扩展文档 中亦有对应说明：grammar 在扩展的 extension.toml 中通过 repository（grammar 仓库地址）与 rev（Git 修订号，如 commit SHA）字段单独注册。Zed 仓库自带扩展即是这一形态的实例，例如 测试扩展的 extension.toml 中声明了 [grammars.gleam] 及其来源仓库与固定提交；glsl 扩展、html 扩展、proto 扩展 也遵循同样的清单结构。在 Zed 主仓库中，语言支持整体也是围绕“自有的 Tree-sitter grammar + queries”构建的，例如 内置语言定义、各语言的 config.toml 与其 .scm 查询文件。因此扩展作者若想支持某种语言，正确姿势是：在扩展自己的 extension.toml 里引入该语言的 grammar，并为它编写全套查询文件。

对政策有疑问或不认同：去哪里讨论

对应原文档条目：I have questions about these policies or disagree with them. Where can I raise that?

FAQ 的作者们先道了谢，然后强调：这些政策都是在充分理由下加入的，但并非全部一成不变，Zed 珍视围绕它们的开放讨论。如果你觉得某条政策不合理或有问题：

• 在 zed-industries/zed 仓库中开一个 discussion；
• 在其中 @ 提及 @MrSubidubi（Zed 扩展治理相关的维护者）。

比起让你带着挫败感离开，Zed 更愿意把政策逐条讨论清楚——这是 FAQ 原文的态度，也是把维护者“后台考量”公开化的体现。

实践要点速查

把 FAQ 全篇浓缩为可直接照做的清单：

场景	正确做法
提交审核	做好前置要求与许可，接受“数周起步、无承诺”的周期
避免 PR 被关	每 PR 只动 1 个扩展、最多 3 个并发 PR、3 周内响应反馈
PR 被关	按 发布前置要求 复查；失活关闭可随时开新 PR 重来
已发布扩展	更新同样受前置要求约束；唯一例外是 ID（不可变更）
发现他人扩展的 Bug	先在原扩展仓库上报/提改进，不另起竞争扩展
不想维护了	转让仓库、申请移除，或直接搁置均可
所有者失联	需书面许可，或“书面联系证明 + ≥6 周无响应”，才能社区 fork 或官方接管
语言扩展 grammar	必须在自己的 extension.toml 声明，禁止复用他处 grammar
政策讨论	在 zed 仓库开 discussion 并 @ 维护者

FAQ 全文的锚点式组织结构保留了极强的可检索性——每一条都以一个独立锚点问题开头（如 #pr-closed、#unresponsive-owner、#grammar-reuse），这意味着无论是人工查阅还是被 LLM/Agent 引用，都可以精确到单个政策条目。建议扩展作者把 FAQ 原文 与 发布指南、前置要求、许可要求、更新文档 四份文档放在一起通读一遍，再进入提交流程——它们共同定义了 Zed 扩展生态中“从投稿到长期维护”的完整行为准则。