FND-003：团队组织、项目治理与贡献流程

自 v0.7.0 起 · 类型：治理 · 修订版 16

权威参考 · 经团队批准 · 修订版 16 原始治理讨论：#5577 后续工作线和标签治理政策：#6808

在你们阅读此内容之前，给团队的一条提示。

软件项目失败并不是因为代码写得糟糕，而是因为编写代码的人无法协同配合。功能被重复开发，缺陷被遗漏，好的想法因为没人记录下来而烟消云散。新贡献者满怀热情前来想要帮忙，却找不到从何处入手。本 RFC 旨在搭建轻量级的框架结构，以避免这些失败——目的不在于让项目显得井井有条，而在于让团队能够更快速、更有信心、更顺畅地推进工作。本文中的每一条建议都专门针对规模较小、不断成长、由学生主导的开源团队而设计。这里没有任何内容需要项目经理、Scrum Master 或正式委员会的参与。

修订历史

目录

1. 协调问题
2. 三部分组成系统
3. GitHub 项目：工作流水线
   • 3.6 工作通道与状态所有权
4. GitHub Discussions：社区讨论与交接
   • 4.5 讨论管理与 Discord 到 GitHub 的交接
5. 团队层级与贡献权限
6. 代码所有者和分支保护
   • 6.4 架构合规性：人工审查，AI 支持
7. 问题模板
8. RFC 治理循环
9. 标签分类
10. 完成定义
11. 自动化
12. 分阶段发布

1. 协调问题

每个没有有意协调系统的项目都会发展出一个偶然的协调系统。大多数开源项目的偶然协调系统如下所示：

• 想法存在于某人的脑海中，或出现在一条会滚出屏幕的聊天消息里
• 问题在跟踪器中堆积，没有优先级、没有负责人，也没有明确的完成定义
• 贡献者提交无人请求的 PR，或主动提出帮助却得不到回应
• 团队的工作方式是被动应对：谁的声音最大谁就得到关注，哪里出了问题就修哪里，任何事情的规划都不会超过一周。
• 架构决策在 PR 评论中做出，但从未在任何地方记录。

这并非对任何人付出努力的批评，而是对默认情况下所发生现象的描述。解决方案不是增加流程，而是采用正确的流程，并根据团队的规模和成熟度在恰当的层级上加以应用。

ZeroClaw 需要以下三样东西：

1. 一个管道，用于将想法转化为已发布的代码，在每个阶段都有可见的步骤，并在每次转换时有明确的关卡。
2. 一个持续维护的讨论区，用于汇集社区的问题、想法、作品展示以及尚未进入正式流程的早期探索，既不会让这些内容流失，也不会干扰正在进行的工作
3. 治理模型，定义谁可以决定什么、架构决策如何制定以及团队如何成长

这是三个截然不同的关注点。将它们混为一谈、把所有内容都放进同一块看板，或依赖非正式的聊天来做决策，正是制造团队试图摆脱的混乱的根源。

2. 三部分系统

核心原则：**项目看板只包含团队已承诺要考虑的工作。**早期社区讨论、想法、问答和展示在该通道维护期间可以存放在 Discussions 中。已经过评估、接受并明确范围的工作则进入项目。正是这种区分让看板保持实用。

FND-003 是工作流通道和贡献管道策略的持久治理来源。RFC #6808 是面向功能的工作流通道、标签治理、问题分流和维护者路由的暂存讨论；在其策略片段被提升后，其持久规则将存放于本基础文档以及下方链接的维护者操作页面中。在策略被提升至此处之后，请勿将该 RFC 问题视为与之竞争的治理文档。

操作细节有意紧贴使用它们的工作流：

3. GitHub 项目：工作流水线

3.1 管道阶段

项目看板包含一个 状态 字段，共有七个值。每个值代表流水线中的一个阶段。这些阶段按线性顺序排列，但项目项可以回退：

💡 Idea
    ↓  Gate: Vision alignment check
📋 Backlog
    ↓  Gate: Architecture fit + acceptance criteria
🎯 Defined
    ↓  Gate: Assignee, size, risk tier confirmed
🚧 In Progress
    ↓  Gate: Tests written, CI passing
👀 In Review
    ↓  Gate: Correct reviewer tier approved, docs updated
✅ Done

加上一个可以从任何地方到达的终端状态：

🚫 Won't Do  ← explicit decision not to pursue; never silently closed

看板级别的 Won't Do 状态是一项持久性的关闭决策。当前的关闭标签拼写规则和替换流程规则记录在 维护者标签指南 和 取代指南 中。

3.2 门控问题

每个状态转换都有一个准入问题。该问题必须先回答“是“，条目才能向前推进。这就是项目看板付诸实践的方式：Vision → Architecture → Design → Implementation → Testing → Documentation 的层级结构在每个阶段都变成了一份检查清单。

为什么显式门禁对学生团队至关重要： 如果没有门禁，卡片会因为有人觉得自己完成了而移动，而不是因为“完成”有明确的定义。这是导致“已完成”工作实际上并未完成的最常见原因。门禁使定义变得可见且共享。

这些关卡问题是治理性的提示，而非需要在每个 PR 正文或问题评论中重复填写的另一份检查清单。其操作性的具体形式存在于维护者已经接触的工件中：

• 问题模板会收集首次分类所需的报告、用户价值、复现步骤、架构影响及风险提示；
• PR 模板收集范围边界、验证证据、安全/隐私影响、兼容性、回滚、标签和关联的 issue；
• 维护者 PR 工作流定义了就绪定义（Definition of Ready）、完成定义（Definition of Done）、PR 通道和合并检查；
• 标签指南定义持久化分类、过期策略标签以及清理顺序；
• 审查者操作手册定义了受理、审查深度、问题分类、自动化覆盖和队列整理。

如果发现某个旧的 FND-003 门控问题似乎缺失，请先检查这些运行位置，然后再在此处添加副本。

3.3 自定义字段

在 GitHub 项目设置中创建以下字段：

关于规模估算（T 恤尺码）： 故事点需要校准和历史数据，而团队目前尚不具备这些数据。T 恤尺码直观易懂，对于当前阶段的团队来说已经足够：

XL 项在进入“进行中”状态前，几乎都应被拆解。如果无法拆解，说明设计还不够完善。

3.4 视图

在项目中创建四个命名视图：

视图 1：路线图

• 类型：路线图（时间线）
• 按里程碑分组
• 可见字段：标题、类型、大小、组件、负责人
• 用途：面向公众。“即将发布的内容及时间安排。”请在 README 中分享此链接，并与社区共享。请保持其更新。

视图 2：看板

• 类型：看板（Kanban）
• 列：状态字段值
• 仅筛选当前里程碑
• 可见字段：标题、负责人、大小、风险等级
• 目的：日常工作的可见性。每个人现在正在做什么？有哪些工作被阻塞了？

视图 3：待办事项

• 类型：表格
• 按优先级（降序），然后按大小（升序）排序
• 筛选条件：状态 = 待办 或 已定义
• 可见字段：标题、类型、优先级、大小、组件、里程碑、风险等级
• 用途：在梳理会议中使用。接下来需要处理哪些工作？哪些已经估算好并准备好被认领？

视图 4：我的工作

• 类型：板
• 筛选条件：分配人 = @me
• 用途：个人仪表板。每位贡献者只能看到自己的项目，避免无关信息干扰。

3.5 固定项

GitHub 允许每个仓库最多固定六个问题。将它们用于高信号、始终可见的沟通：

1. 当前正在讨论的活跃 RFC
2. 社区最期待的功能（最高票讨论）
3. 下一个发布里程碑跟踪问题
4. 适合新手的问题索引（一个链接到所有当前 good first issue 项目的问题）

已固定的问题是对社区的一种承诺：这些是当前最重要的事项。当优先级发生变化时，请更新它们。

3.6 工作通道与状态所有权

工作通道策略可避免看板、标签、PR 和议题在不同位置尝试回答同一个问题。

使用此拆分:

PR 通道、贡献者认领标签、过期豁免标签以及标签迁移都是稳定的治理概念，但它们的具体操作标准存放在维护者文档中。FND-003 负责划分职责：标签用于分类稳定工作，项目看板用于规划工作，原生 PR 状态负责实时审查与合并状态，issue/RFC 则用于保存决策。维护者 PR 工作流定义 PR 通道，标签指南定义具体的标签含义和清理规则，审查者操作手册说明审查者在分类和审查过程中如何应用这些信号。请将实时标签迁移视为单独的、需维护者批准的清理工作，而非普通的 PR 审查。

过期豁免属于治理例外，而非永久性的标签护盾。目标策略是：仅当泳道的运维数据源记录了该议题为何被豁免，以及哪些可见的路由证据将承载下一步决策时，status:no-stale 才有效。维护者文档定义了这些事实存放在何处，以及过期自动化或过期清理如何强制执行该规则。

4. GitHub Discussions：社区讨论与交接

4.1 维护讨论通道

将 GitHub Discussions 视为一个需要维护的社区平台。Discussions 适用于提问、想法、投票、公告、作品展示、项目或集成演示，以及那些比 Discord 更需要持久保留、但尚未纳入工作跟踪的探索性讨论。

确切的类别、类别描述和审查周期属于操作细节。它们应记录在贡献者沟通指南和维护者工作流文档中，并且可能在不修订本基础文档的情况下演进。

4.2 从讨论提升为跟踪工作

讨论不会仅仅因为存在一个话题串就变成待办工作。当讨论产生具体的、可跟踪的结果时，才将其提升为待办事项。面向贡献者的触发示例参见 Communication。

目标取决于讨论结果。已确认的缺陷和已接受的功能范围转入 issues。架构决策通过 RFC 流程处理。PR 相关的具体细节转入 PR 评论。持久性的运作规则转入维护者或贡献者文档。

在发起讨论中完成闭环。如果该分类支持答案，请在适当情况下将摘要或跟踪工作链接标记为答案。如果不支持，请添加一条最终的摘要评论，附上问题、RFC、PR 或文档链接。

4.3 不应等待投票的想法

某些条目会绕过 Discussions，直接进入受跟踪的界面：

• 安全漏洞（通过私有安全报告，绝不公开）
• 已确认的带有复现步骤的 Bug（请直接使用 Bug 报告问题模板）
• RFC 接受的基础架构项（直接从 RFC 关闭循环中生成）
• 来自项目路线图的项目（由核心团队直接放置）

4.4 架构探索

当问题面向社区且尚未准备好进行正式 RFC 时，架构探讨可以从 Discussions 开始。这降低了提出设计顾虑的门槛，不必将每个早期想法都变成需要追踪的正式决策。

当讨论线程形成具体的架构提案时，请创建 RFC issue，并将持久化的提案迁移到 RFC 中。此后，Discussion 可链接到该 RFC，不再作为唯一可信来源。

4.5 讨论管理及 Discord 到 GitHub 的交接

Discord 用于快速交流，GitHub 则是持久的记录。Discussions 是一个长期维护的 GitHub 平台，用于面向社区的交流——这类交流比 Discord 需要更高的持久性，但尚未形成可追踪的工作项。

讨论(Discussions)只有在有人负责该领域时才有效。这种责任归属可以是指定的管理员，也可以是有文档记录的审查周期。如果没有明确的责任归属，讨论(Discussions)只是一个被动的归档，而不是一条必需的接收渠道。

对于探索性、面向社区或需要广泛反馈的讨论，请使用 Discussions。当结果已经明确或具有权威性时，请使用 issue、RFC issue、PR 评论或维护者文档。面向贡献者的触发条件列表和分类示例位于 Communication。

交接无需复制整个聊天记录。只需记录结果以及足够的上下文,让其他维护者能够继续工作即可。如果某次讨论后续产生了需要跟踪的工作或长期有效的策略,请将该结果提升到负责它的相应平台中。

5. 团队层级与贡献权限

5.1 三个层级

开源项目奉行精英主义：影响力和话语权来自实际贡献，而非资历、头衔或人脉。这正是开源软件区别于商业软件的特质之一，值得明确传授。

这三个层级反映了逐步增强的对项目承诺：

第 1 级：社区

任何人。无需审批。

他们能做什么：

• 使用问题模板打开问题
• 在任何问题或拉取请求中发表评论
• 参与讨论并对想法进行投票
• 提交拉取请求（将在合并前进行审核）
• 编辑 GitHub Wiki

他们无法做到：

• 被分配问题（可以请求被分配）
• 批准 PR
• 合并 PR
• 对具有约束力的 RFC 进行投票

层级 2：贡献者

已在 master 分支中合并至少两个 PR 的社区成员。

如何成为其中一员： 有两个 PR 被合并，并获得核心团队成员认可。第 2 层目前没有持久的成员资格记录；请参见 §5.3。

他们在社区之外获得的收益：

• 可以分配问题
• 可以作为 PR 的审查者（非必需的审查）
• 在讨论中对想法投票计入晋升阈值
• 可以请求 RFC 讨论，而无需先通过讨论

他们仍然无法做到的是：

• 批准高风险路径的 PR
• 合并 PR
• 投 RFC 投票

为什么需要这个层级： 它为新手贡献者设立了一个可见且可实现的初步里程碑。“如何更深入地参与？”有了明确的答案：合并两个 PR。这有助于激励早期的优质贡献，并为团队提供了一种公开认可贡献者的方式。

第三级：核心团队

在过去一段时间内展现出持续且高质量贡献，并已被现有核心团队成员邀请的贡献者。

如何成为核心团队成员： 由现有核心团队成员发出邀请，并在 Discussions 中公开宣布。没有正式的门槛；这是基于以往贡献的质量、一致性和契合度所做出的判断。

他们作为贡献者之外获得的权益：

• 对仓库的写入访问
• 可以合并已满足审查要求的 PR
• 可以批准高风险路径的 PR（需符合 CODEOWNERS 要求）
• 在 RFC 上投出绑定投票
• 可以通过项目管道移动项目
• 可以发布版本
• 参与治理决策（核心团队讨论）

职责：

• 在3个工作日内处理新提交的问题
• 在5个工作日内审查其专业领域的PR
• 参与 RFC 投票
• 遵守项目的行为准则

5.2 懒共识规则

对于常规决策——比如添加标签、关闭过期 issue、更新文档——核心团队成员遵循 lazy consensus（默认同意） 原则：如果你在相关 issue 中宣布了自己的意图，且 48 小时内没有任何核心团队成员提出反对，你即可继续推进。这样既避免了凡事都要明确批准所导致的停滞，又保持了透明度。

“惰性共识”不适用于：

• RFC 接受或拒绝
• 发布
• 对 CODEOWNERS 或分支保护规则的更改
• 对本治理文档的更改
• 核心团队新增成员

这些始终需要核心团队的明确投票。

5.3 记录团队成员

成员资格本身由决策确立，而非任何文件或 GitHub 设置。根据第 5.1 条，某人成为 Core Team 成员须经现有 Core Team 成员邀请，并在 Discussions 中公开宣布。该决策及其公开宣布才是可信来源。以下所有内容均是其下游记录，均不构成成员名册：

core-contributors GitHub 团队和仓库协作者列表，位于组织设置中：属于访问控制，而非成员记录。它们反映的是谁可以写入仓库，这是成员身份的结果，而非其定义。预期它们与成员列表在两个方向上均存在差异。其中包含非真实人员的自动化账户，且访问权限可能是直接授予的、在成员资格决定之前已持有的，或仍在等待接受邀请。当您需要了解谁可以推送时，请查阅这些内容。当您需要了解谁是核心团队成员时，请查阅准许其加入的公告。

仓库根目录下的 .github/CODEOWNERS：用于评审路由，而非成员资格。它记录了在哪些路径上需要请求谁进行评审。被列入其中并不代表拥有成员资格，成为成员也不意味着会被列入其中。根据 §5.2，对其进行更改需要经过 Core Team 的明确投票。

Communication 中的维护者表格：当前成员及其负责工作的人类可读摘要。它是最接近已发布名单的内容，由人工维护，因此应将其视为准入决策的摘要，而非权威依据。对于关注领域，它是 CODEOWNERS 的便捷视图，两者存在分歧时，以 CODEOWNERS 为准。

移除的处理方式与接纳相同：它们都是决策，并记录在作出决策的地方。撤销访问权限或将某人从 CODEOWNERS 中移除，是落实离开的操作；但其本身并不构成离开。

本文档第 1 至第 7 版在仓库根目录指定了一个 CONTRIBUTORS.md 文件作为按层级组织的成员记录，并命名了 zeroclaw-core 和 zeroclaw-contributors 两个 GitHub 团队。三者均从未创建；该组织实际使用单一的 core-contributors 团队。RFC #6808 独立得出了相同结论，记录了 FND-003 团队层级结构并非当前可见的路由模型，且新的通道规则不应基于该结构构建。这些引用在此予以撤销，而非继续作为不存在的机制的描述保留。

第 2 级目前没有持久的成员资格记录。是建立这样的记录，还是取消该级别，是团队尚待解决的问题。

6. CODEOWNERS 和分支保护

6.1 CODEOWNERS

CODEOWNERS 文件使治理自动化。它定义了哪些路径在 PR 合并前需要哪个团队的审查。GitHub 将其作为必需审查来强制执行：在满足该要求之前，PR 无法合并。

下面的区块是原始的示例性提案，保留它是因为其中展示了有关受保护审查路由的思路。它不是当前文件，不应复制。.github/CODEOWNERS 已经存在并在持续维护；它将路由指向个人句柄，而不是团队句柄，其路径遵循 #6537 确立的微内核改造后的 crate 布局。此处使用的 @zeroclaw-labs/zeroclaw-core 和 @zeroclaw-labs/zeroclaw-contributors 句柄从未创建；请参阅 §5.3。其宽泛的路由路径不是当前的 risk:high 分类器；请阅读现行文件和维护者标签指南，了解当前的路由和风险语义。

# CODEOWNERS — Automatic review routing by protected surface
# See the maintainer label guide for risk definitions.
# See the governance foundation doc and RFC issue template for team tier definitions.

# ── Protected review routing: Core Team review ──────────────────────────────

src/security/**                 @zeroclaw-labs/zeroclaw-core
src/gateway/**                  @zeroclaw-labs/zeroclaw-core
src/runtime/**                  @zeroclaw-labs/zeroclaw-core
src/tools/shell.rs              @zeroclaw-labs/zeroclaw-core
src/tools/file_write.rs         @zeroclaw-labs/zeroclaw-core
src/tools/security_ops.rs       @zeroclaw-labs/zeroclaw-core

# ── Governance and configuration: requires Core Team approval ───────────────

.github/**                      @zeroclaw-labs/zeroclaw-core
CODEOWNERS                      @zeroclaw-labs/zeroclaw-core
Cargo.toml                      @zeroclaw-labs/zeroclaw-core
deny.toml                       @zeroclaw-labs/zeroclaw-core

# ── Architecture documents: requires Core Team review ───────────────────────

docs/book/src/foundations/**    @zeroclaw-labs/zeroclaw-core
docs/book/src/architecture/decisions/**  @zeroclaw-labs/zeroclaw-core
AGENTS.md                       @zeroclaw-labs/zeroclaw-core

# ── Default: any Contributor or Core Team member can review ─────────────────

*                               @zeroclaw-labs/zeroclaw-contributors

当特定的核心团队成员对组件负责时，请在团队句柄旁添加他们各自的句柄。在 CODEOWNERS 中，越具体的规则优先级越高：更具体的路径规则会覆盖更通用的规则。

6.2 分支保护规则

为 master 分支配置以下分支保护规则：

为什么管理员不能绕过： 小型团队项目中最常见的错误之一，就是把分支保护视为“给别人用的“。一旦管理员可以绕过，他们就会在时间压力下、紧急情况中、抱着“就这一次“的心态去绕过。久而久之，这便成了常态。规则只有对所有人都适用，才有意义。如果真的遇到紧急情况，正确的应对方式是更快地走完流程，而不是跳过它。

GitHub 原生的批准数量是按受保护分支或规则集目标配置的，而不是根据 PR 标签有条件地配置。除非单独批准的技术强制执行设计具备用于 Core Team 批准的机器可读授权，否则维护者必须通过文档化的合并检查清单执行 risk:high OR domain:security 要求，并保留可审计的审查记录。risk:manual 仅冻结未来的自动风险替换；不能降低此要求。

6.3 必需的签核状态

在合并任何 PR 之前必须通过的 CI 检查：

build (stable)          ← cargo build --release
test                    ← cargo test
fmt                     ← cargo fmt --all -- --check
clippy                  ← cargo clippy --all-targets -- -D warnings

随着工作区按照架构 RFC 拆分为多个 crate，请为每个 crate 添加相应的检查。对 crates/zeroclaw-api 的更改应独立运行该 crate 的测试套件。

6.4 架构合规性：人工审查，AI 支持

本节之所以存在，是因为这个问题终将被提出（实际上已经出现过了），它理应有一个清晰、有据可查的答案，而不是在每个 PR 上反复争论。

问题： 我们是否应该添加一个自动化门禁，用于检查 PR 是否符合 RFC 中定义的架构和设计模式？

答案： 不是。理解其中的原因非常重要。

存在两种根本不同的质量保障方式，它们需要不同的机制。

第一种是_结构合规性_：这段代码是否违反了机械规则？zeroclaw-kernel 是否导入了 TelegramChannel？依赖图的边是否指向了错误的方向？是否存在 clippy 警告？这些都是二元问题。代码要么违反了规则，要么没有。编译器、cargo deny 和 cargo clippy --workspace 已经强制执行这些规则。不需要人类参与，也不需要 AI 介入。机器是权威的、快速的，并且对于事实性违规绝不会出错。

第二种是 架构意图：这个决策是否应该放在这里？这个抽象是否处在正确的层次？这个权衡是否与愿景一致？这种耦合在第 3 阶段会不会带来痛苦？这个 PR 是否会造成在当前 diff 中看不出来的维护负担？这些问题需要判断力、上下文，以及对架构 为何 存在的理解，而不仅仅是了解规则是什么。没有任何自动化工具能够可靠地回答这些问题，因为答案取决于不在 diff 中的信息：路线图、团队当前的优先事项、贡献者的意图，以及该决策的长期成本。

自动化架构判断的失败模式都很糟糕。

一个对细微架构违规视而不见的门禁会制造虚假的信心。开发者看到 ✅，便以为自己的决策得到了验证。最具破坏性的架构漂移——那种需要数年才能理清的——在结构上看起来是正确的。它能编译通过。它能通过 lint 检查。依赖图也没有问题。问题在于，它违背了设计的本意，而这种违背只会在后期才显现出来，那时撤销它的代价已经非常高昂。

一个因工具误读上下文而标记了有效架构决策的关卡，会教导开发者完全忽略该关卡。一旦团队学会了点击跳过嘈杂的自动化检查，该检查在实际操作中便形同虚设，尽管它在 CI 中仍在运行。项目为此浪费了 CI 分钟数，却产生了负价值。

CODEOWNERS 是架构合规的关卡，审查者是工具。

§6.1 中的 CODEOWNERS 配置已将 crate 边界、trait 定义、依赖关系图、src/security/ 和 .github/ 等受保护的审查范围路由给 Core Team 审查者。这种路由与 risk:* 分类是相互独立的。Core Team 审查者以 RFC 为参考框架，负责进行架构合规检查。他们带来了任何自动化都无法复制的上下文判断。

这就是 RFC、AGENTS.md 文件以及文档规范存在的原因：不是为了供机器解析并生成评分，而是为了让人类审查者有一个一致且文档化的框架来应用。RFC 回答了“为什么存在这种架构”，而审查者则回答“这个 PR 是服务于还是削弱了这种架构”。

AI 应融入开发流程，而非合并门禁。

AI 工具，比如 Claude、Copilot、Cursor，以及未来出现的任何工具，在用对地方时对架构工作确实很有帮助。而对的地方是_在开发过程中_，而不是_在合并关卡处_。

在开发过程中，配备 RFC 和 crate 的 AGENTS.md 的 AI 助手可以帮助贡献者在编写代码之前理解新的功能属于哪个 crate，在代码结构仍在塑造时标记潜在的依赖倒置问题，解释设计模式存在的原因，并建议新的抽象是否处于正确的层级。这是增量的，它使贡献者更加有能力。

在代码审查过程中，AI 助手可以帮助人类审查者起草结构化的反馈，将变更与 RFC（请求评论）进行交叉引用，并识别 RFC 中与当前 PR（拉取请求）相关的讨论问题。这一过程也是增量的。审查者提供判断力，而 AI 提供速度和记忆能力。

AI 无法取代的是判断力。“AI 帮我评估这个 PR“和“AI 自动为这个 PR 把关“是性质完全不同的两件事，而只有前者适用于架构决策。一旦项目把架构合规性交由某个自动化关卡来把关（无论它多么精密），架构就会开始以无人察觉的方式逐渐偏移，等到发现时为时已晚。

实际策略，直白地说：

• 结构合规性（导入方向、依赖图、代码检查、格式化）由 CI 强制执行。这是不可协商的，并且已自动化。
• 架构意图合规性通过 CODEOWNERS 路由至核心团队审查员来强制执行。这是不可协商的，并且需要人工处理。
• AI 工具在开发阶段为贡献者提供支持，并在代码审查阶段为审查者提供支持。它们不会仅凭自身权限来阻止合并操作。
• 如果团队希望在未来评估 AI 辅助审查工具，该评估需先通过 RFC 流程。未经文档化的决策，不得将其添加到 .github/workflows/ 中。

此政策并非对人工智能或自动化的限制，而是认识到不同的问题需要不同的工具，在合适的地方使用合适的工具正是架构 RFC 对代码库所提出的要求。

7. 问题模板

Issue 模板将传入的报告引导至正确的处理流程，然后再由人工处理。编写良好的模板可以自动收集分类所需的信息。如果缺少或忽略模板，则会导致需要三次评论交互才能理解的问题。

运维真实信息源为 .github/ISSUE_TEMPLATE/。请勿在此重复完整的模板 YAML。当模板措辞发生变更时，请更新 issue 表单本身，并将本节内容保持在持久意图层面。

当前进料通道:

安全漏洞不提供公开的问题模板。config.yml 链接到私密安全策略、Discord、GitHub Discussions、贡献指南、RFC 流程以及维护者 PR 工作流，以便贡献者在创建受跟踪的问题之前选择合适的渠道。

Issue 模板用于收集证据，但其本身并不决定最终标签。维护者在检查正文、讨论和关联工作后，仍会应用需要人工判断的标签，例如 status:accepted、status:no-stale、help wanted 和 good first issue。特别是，status:no-stale 不应通过模板自动应用。在添加或保留 stale 保护之前，tracker、RFC 或长期存续的已接受 issue 必须同时记录 stale 豁免原因以及可见的下一步决策或复审面。

8. RFC 治理循环

RFC 流程在文档 RFC 和架构 RFC 中确立。本节定义了闭环：RFC 如何从提案推进到决策再到执行。

何时需要 RFC。 RFC 会在实施之前记录持久的项目级决策。提案至少满足以下一项时，需要提交 RFC：

• 新的安全层，或对项目安全模型的重大变更；
• 治理、贡献流程或项目权限变更；
• 跨领域架构重构，改变既有边界之间的所有权或契约；或
• 一个新的子系统，或另一个项目级能力边界。

不要仅仅因为工作包含普通功能新增、模式或数据迁移、配置字段或默认值变更，或范围明确的实现重构，就要求编写 RFC。这些工作通过 issue 和 PR 进行。只有当它们的实质性影响同时满足上述某项触发条件时，才需要 RFC。

触发条件取决于对项目的实质性影响，而不是议题标题、作者、是否由 AI 辅助产生，或仅仅存在迁移、功能或默认值更改。安全漏洞应通过私下报告，绝不发布公开 RFC。

维护者可以在已提交的 RFC 不符合触发条件时，将其重新标记或关闭为普通 issue、功能请求或实现后续事项。处理结果说明相关工作是否仍然有效，以及后续在哪一处继续进行。这是对工作进行分流，并非就实质内容予以拒绝。

8.1 RFC 的完整生命周期

讨论期间作者进行的一般修订和澄清不会重新计时。实质性改变拟议决策的修订会建立一个新的稳定快照，公开标识该快照后，适用的最短讨论期将重新开始。

1. AUTHOR opens an RFC issue using the RFC issue template,
   naming the trigger the proposal crosses
           |
2. DISCUSSION PERIOD, against a visible proposal
     minimum 48 hours for an ordinary RFC
     minimum 72 hours when the exceptional unanimous path is requested
   Anyone can comment. Core Team members engage substantively.
           |
3. VOTE OPENS once the period has elapsed and the proposal is stable.
   The vote-opening comment records:
     - the immutable proposal snapshot (artifact, commit, or issue-body digest)
     - the assigned active electorate, and inactive Core notified for re-entry
     - the threshold, and why it applies
     - that quorum requires two explicit ballots
     - the exact UTC deadline, 72 hours after opening
           |
4. CORE TEAM BALLOTS, one of:
     APPROVE  accept the snapshot as written
     REVISE   request changes, withhold approval, do not veto
     REJECT   blocking objection, with a specific reason
   A member's latest ballot before the deadline supersedes their earlier one.
           |
5. OUTCOME, applied in this precedence order:
     a. Fewer than two explicit ballots        -> DEFERRED
     b. Quorum met and any final ballot REJECT -> REJECTED
     c. Quorum met, no REJECT, two-thirds
        approving explicitly or by silence     -> ACCEPTED
     d. Otherwise                              -> RETURNED TO DISCUSSION

已接受的 RFC 带有 status:accepted，结案记录会处理每一项 REVISE 关注点，而不是将其丢弃。被拒绝的 RFC 会在记录阻塞性反对意见并附上相关 issue 链接后关闭，以便在底层问题仍然存在时继续跟踪；拒绝结束的是当前提案，不一定是该问题本身。延期提案会保持开放，并记录再次投票的条件；未作更改的延期提案可以直接进入新的 72 小时投票，无需重复讨论。

使用当前的 type:rfc 和 status:accepted 标签。不存在并行的 rfc:* 状态标签系列。

Rev. 15 适用于批准后开启的 RFC 投票。它不会自动使此前已接受的 RFC 失效；历史流程的审计和修正工作仍单独跟踪。

投票只有在最终活跃选民中的每位成员都已明确批准，且没有任何其他情况下不活跃的 Core 贡献者要求完整投票期限时，才能提前结束。结束记录必须说明其为何在截止期限之前结束。特殊的一致通过投票只有在每位指定投票者都明确批准后才能提前结束。

8.2 投票阈值

最终活跃选民总数的三分之二是默认阈值，向上取整为整数选民数。最终活跃选民总数等于投票开始时分配的选民总数，加上在同一投票中投票的其他当前 Core Team 成员。

• 法定人数要求至少两名现任 Core 贡献者投出明确选票。沉默永远不计入法定人数。
• 达到法定人数后，最终活跃选民的沉默仅对普通投票计作 APPROVE。
• REVISE 计为不批准，不会否决。
• REJECT 会在达到法定人数后否决接受。

例如，当最终活跃选民中有四名成员时，一名明确投出 APPROVE、一名明确投出 REVISE，以及两名保持沉默的成员会产生四票中的三票赞成，达到阈值。

一致同意仅适用于因成本或不可逆性而使超多数批准不足以作出决定的情况，例如许可证或法律所有权变更。开启投票时必须说明为何适用一致同意。一致同意投票要求每位被分配且符合资格的 Core 贡献者明确给出 APPROVE；沉默不能构成一致同意。

**活跃选民。**活跃的 Core 贡献者是当前的 Core Team 成员，并且在前 30 天内于正式开启的 RFC 投票中投出了明确的 APPROVE、REVISE 或 REJECT 选票，且未公开表示退出或记录为在投票期间无法参与。当前不活跃的 Core 成员会收到通知，并可通过参与投票加入该投票的最终选民名单；此举也会使其在之后的投票中重新激活。

每次投票都会分别确定法定人数和分母。投票开启时会检查活跃度；之后在另一场并行投票中的活动不会改变已开启投票的选民范围。

8.2a 核心会议决策与 GitHub 桥接

GitHub 是提案文本、讨论、投票开启、选票、截止日期和结果的唯一权威来源。Discord 可以发布 RFC 公告或进行讨论，但不会确立治理状态。

项目已批准的内部决策记录中记载的核心贡献者会议决定，可指导维护者立即采取行动，并可取代先前的内部指示。任何更改项目公开状态的此类行动，都必须在受影响的 issue、PR、跟踪器或 RFC 上留下 GitHub 桥接记录。桥接记录需注明会议日期或决策记录，概述所采用的决定，说明已采取的公开行动，并说明这是一次性例外还是长期有效的规则变更。

会议决定不会默默重写本文档、贡献者文档、标签、issue 模板或 RFC 结果。只有在相关 GitHub 和文档界面中有所体现时，持久性的治理变更才会成为政策。对于特殊的一致通过决定，内部会议记录不能替代所需的 GitHub 明确批准，除非该记录记录了批准成员，并且公开 issue 记录了这一依据。

8.3 持久的后续行动与 ADR 的关联

对于新接受的 RFC，在实现开始之前，必须能从 RFC issue 中看到最终形态和持久的后续跟进。仅仅接受本身并不能完成治理交接。对于在实现之后审计的已接受 RFC，追溯性地记录处置结果，而不重新打开已完成的工作。

每条处置记录都会标识权威的最终形态、所选处置方式及其理由、持久性制品或交付跟踪项，以及在仍需后续跟进时的负责人或下一步行动。

使用四种处理方式之一：

• ADR: 当决策对未来架构构成实质性约束时为必需。判断指标包括：出人意料的系统边界、不明显的权衡，或会实质性限制未来架构备选方案的选择。
• 常设文档更新： 当持久性成果是操作文档、参考文档、工作流文档、安全文档或用户契约，而非新的架构决策时，需执行此操作。
• 实施或跟踪跟进： 当现有 ADR、FND 或常设文档已载有该决策且交付工作尚未完成时需要执行。请链接交付跟踪器及其下一步行动。
• 无需单独工件： 当已识别的现有 FND、ADR、常设文档、已完成的实现或取代性决策已保存相应结果，且无需额外的交付跟踪时，允许不创建单独工件。问题中必须记录该理由并链接到持久化载体。

RFC 是讨论和接受的载体。ADR 是重大架构决策的永久记录，而不是每个已接受 RFC 的强制摘要。当已接受的决策达到上述架构阈值时，常设文档和实现跟踪器不能取代 ADR。

8.4 基础 RFCs

早期提案文档后来已被表示为 RFC issues 和 foundation documents:

9. 标签分类

标签是 issue 和 PR 上的元数据层。一套一致、设计良好的标签系统能够实现筛选、报告和自动化。而不一致的标签系统（常见情况是由创建 issue 的人随意添加标签）则会产生干扰。

使用命名空间标签系统。每个标签都有一个前缀，用于标识其类别：

type: 这是哪种类型的工作？

priority: 这有多紧急？

size: 这个工作项有多大？

component: 系统的哪个部分？

组件:内核 · 组件:网关 · 组件:通道 · 组件:工具 · 组件:内存 · 组件:安全 · 组件:硬件 · 组件:文档 · 组件:基础设施

使用 #f1f5f9（浅灰色）作为所有组件标签的颜色，以便在视觉上与其他类别区分开来。

risk: 风险等级是什么？（与 AGENTS.md 保持一致）

status： 此处处于流程中的哪个阶段？

此表记录了治理意图和历史分类结构。如需了解当前实际生效的标签语义和自动化行为，请参考维护者标签指南作为操作依据；维护者文档包含了来自 #6808 的后续标签策略修正。

当前社区认领标签是无前缀的 good first issue 和 help wanted；上方的 status:* 认领条目属于历史分类法。当前运营风险标签还区分问题风险（根据报告预估的修复影响范围）与 PR 风险（实际待审查的 diff）。有关当前策略，请参阅维护者标签指南。

终态关闭标签属于运营策略，并非本基础文档中历史 status:* 分类体系的一部分。当前的解决标签请参阅维护者标签指南，替换流程规则请参阅取代指南。

rfc: RFC 专属状态

在第 15 版中弃用，且从未作为活动标签创建。RFC 状态使用活动的 type:rfc 和 status:accepted 标签；请参见 §8.1。

10. 完成定义

“完成”有其特定含义。如果你不加以定义，每个人都会有不同的理解，而分歧会在最糟糕的时刻浮现：在评审时、在发布时，或在用户提交缺陷报告之后。

当满足以下条件时，一项任务即被视为已完成：

对于代码更改

• 该 PR 已经过所需审查者层级（根据 CODEOWNERS 和风险等级）的审查和批准。
• 所有 CI 检查均通过：cargo fmt、cargo clippy、cargo test
• 针对新增或更改的行为编写了测试（至少包含单元测试；面向用户的特性需包含集成测试）
• PR 之前通过的测试覆盖率没有丢失
• PR 描述说明 改动内容 及 改动原因（不能只写“修复 bug”：是什么 bug、问题出在哪里、做了哪些改动）
• 如果更改影响了面向用户的行为，则相关参考文档将在同一 PR 中更新。
• 如果变更较大，请在正确的里程碑部分添加 CHANGELOG.md 条目
• 如果该变更需要 ADR：则 ADR 应在实现 PR 之前或与其同时编写、链接并合并。

用于文档变更

• 存在且有效的 YAML frontmatter
• 所有内部链接均正确解析
• 如果文档描述的是当前行为，则其准确性基于当前的 master 分支。
• 如果文档是 ADR，它遵循 Nygard 格式，并包含一个 status 字段。

用于发布

• 里程碑中的所有项目都处于“完成”状态，或者已明确移至下一个里程碑，并附有解释原因的注释。
• 该版本的 CHANGELOG.md 条目已完成
• 此里程碑中的每个已接受 RFC 都已记录长期有效的处置结论；所需的 ADR 和常设文档更新已合并，剩余的交付跟踪项已链接
• 该版本已在至少一个平台上进行了测试（至少包括 Linux x86_64）。
• 发布标签遵循语义化版本控制

“完成定义”规则

在软件团队中，存在一种“已完成”但并非“完全完成”的工作概念。“已完成”仅表示代码已编写完毕，而“完全完成”则意味着代码已经过测试、文档化、审查、合并并正式发布。上述的“完成定义”描述的就是“完全完成”的状态。只有满足完整定义的工作，才能被称为“已完成”。

11. 自动化

GitHub Projects v2 与 GitHub Actions 结合使用，能够实现显著的自动化，从而减少手动协调的工作量。以下是按价值与工作量比排序的实施建议。

11.1 项目板自动化（内置，无需操作）

在项目的内置自动化设置中配置这些内容：

11.2 GitHub Actions 工作流

根据变更文件自动添加标签：

活动路径标注器会根据已更改的文件为 PR 应用范围标签。风险和大小标签目前由维护者手动应用；维护者标签指南是标签名称、自动化状态和风险语义的实时来源。

自动请求 CODEOWNERS 评审（内置于 CODEOWNERS：无需 Action）：

当文件存在且分支保护要求启用时，GitHub 会自动强制执行 CODEOWNERS。无需采取任何操作。

过期 issue 管理（维护者运行）：

存储库中当前未配置 GitHub Actions stale 工作流。维护者通过运行 stale 扫描来防止不活跃的 issue 积压，同时为受影响的社区保留明确的响应窗口。issue stale 策略 是有关时间节点、qualifying 活动、排除条件和重新参与的唯一操作依据；issue 分类协议仅承载执行机制。

PR 大小标记（未来/可选）：

如果后续添加 size 自动化，应遵循维护者标签指南中的实时名称（size:XS 到 size:XL），并在推送更新时重新计算，这样标签就能描述正在审查的差异。在此之前，size 标签由维护者手动添加。

合并 PR 时的里程碑检查 (.github/workflows/milestone-check.yml)：

如果合并 PR 时未关联已分配里程碑的 issue，则发出警告（而非阻止）。这是一种温和的提醒，而非强制限制：目的是避免工作未被跟踪到某个发布版本就开展。

11.3 哪些内容暂不要自动化

• 自动发布草稿： GitHub 的 release-drafter 很有用，但会增加配置开销。在团队建立了稳定的发布节奏后再添加它。
• 自动依赖更新（Dependabot PR）： 启用 Dependabot 安全更新（免费、低噪音），但在团队实现 CI 稳定性之前，暂缓自动版本升级。在 CI 基础尚未稳固时，升级版本会产生大量噪音。
• Sprint 规划自动化： 不要自动化 Sprint 规划。它需要关于容量、优先级和团队背景的人类判断，在当前团队规模下，没有任何自动化可以替代这种判断。

12. 分阶段发布

治理和工具必须逐步引入。一次性引入所有内容会在团队理解每个部分的存在意义之前产生开销。

第 1 阶段 · 本周：“基础”

最小可行的治理设置。让团队立即协调起来。

• 创建包含状态、类型、优先级和里程碑字段的 GitHub 项目
• 创建四个项目视图（路线图、看板、待办事项、我的工作）
• 在贡献者沟通文档和维护者工作流文档中，启用 GitHub Discussions 并维护其分类说明
• 为现有提案（第 8.4 节）创建三个 RFC 问题
• 添加第 7 节中列出的 issue 模板
• 创建 CODEOWNERS 文件（第 6.1 节）
• 在 master 分支上启用分支保护规则（第 6.2 节）
• 将剩余的标签分类体系（第 9 节）添加到仓库中
• 固定这三个 RFC 问题和下一个发布里程碑问题

成功信号： 新问题会自动出现在项目中。团队清楚在哪里查找活跃工作，以及在哪里发布想法。

阶段 2 · v0.7.0 里程碑：“The Pipeline”

建立完整的工作流程，并根据已批准的 RFC 填充待办事项列表。

• 向项目添加“大小”、“风险等级”和“组件”字段
• 将微内核架构 RFC 中的交付物填充到待办事项列表中
• 将文档标准 RFC 中的交付物填充到待办事项列表中。
• 对现有的三项提案进行首次正式 RFC 投票
• 完成所选的基础 ADR 集（根据 docs RFC，范围为 ADR-001 至 ADR-007）
• 实现按路径自动标记的 Actions 工作流
• 实现过期的问题管理流程
• 创建核心团队 GitHub 团队，以单个 core-contributors 团队的形式发布，而非最初计划的两个团队。原本与之并列的 CONTRIBUTORS.md 名册项已废弃；详见 §5.3。

成功信号： 团队每天都在使用看板。项目在各个阶段中推进，并可见地执行关卡检查。微内核架构的 RFC 已记录了投票结果。

第三阶段 · v0.8.0 里程碑：“发展社区”

随着插件系统逐渐可用，外部贡献者将陆续加入。贡献基础设施必须准备就绪。

• 实现 PR 大小标签工作流
• 为插件 SDK 工作创建第一批 good first issue 条目（至少 5 个）
• 将 Good First Issue Index 添加为置顶 issue，并附上当前适合新手的 issue 链接
• 建立想法推广阈值，并将第一个讨论想法推广为问题
• 记录核心团队扩充流程：邀请新核心团队成员的标准

成功信号： 至少有一名外部贡献者（不在当前团队中）通过一个 good first issue 提交了 PR。Discussions Ideas 分类有活跃的社区参与。

阶段 4 · v1.0.0：“可持续治理”

到 v1.0.0 时，治理模型应当能够自我维持：团队无需为此费心，它应当自然而然地运转。

• 根据实际效果，审查并更新治理文档
• 确定发布周期（发布的频率以及由谁负责发布）
• 发布插件注册表治理文档（根据架构 RFC）
• 如果仅基于里程碑的规划感觉过于松散，可以考虑引入时间盒周期（如两周或四周）。
• 记录核心团队成员退出或变为不活跃状态的过程

成功信号： 过去六个月的开发历史显示，团队持续使用该流水线。问题在 3 天内被分类处理，PR 在 5 天内完成审查，每次合并都会更新 CHANGELOG。

附录 A：术语表

Backlog 整理：一项定期的团队活动（通常每周或每两周进行一次），团队在此过程中审查 backlog、重新调整事项优先级、关闭陈旧的事项，并确保排在前面的事项处于“已定义“状态且可供着手处理。

分支保护：一项 GitHub 功能，可阻止直接推送到受保护的分支，并在合并前强制执行各项要求（代码评审、CI 检查）。

CODEOWNERS：一个 GitHub 文件，当 PR 中修改了某些人或团队所拥有的文件时，会自动向其请求审查。

完成的定义：一份共享的检查清单，明确规定了某个工作项的“完成“究竟意味着什么。如果没有共享的定义，“完成“对每个人来说都意味着不同的东西。

默认通过（Lazy consensus）：一种决策方式，即提议的操作在规定时间内无人反对即可继续执行。这减少了对常规决策要求显式批准所带来的开销。

精英治理：一种治理模式，其中权威和影响力是通过实际贡献赢得的，而非通过资历或头衔。在开源项目中是标准做法。

里程碑：GitHub 的一项功能，用于按发布目标对议题和 PR 进行分组。里程碑代表软件的一个版本。

T 恤尺码法：一种使用抽象尺寸（XS、S、M、L、XL）而非数字故事点的估算技术。无需历史校准数据即可轻松使用，适合处于早期阶段的团队。

问题分类：审查新问题的过程，用于确认问题是否有效、分配标签和优先级、将其关联到里程碑，并确定其应纳入待办事项列表还是应予关闭。

附录 B：延伸阅读

• GitHub Projects 文档：GitHub Projects v2 功能的完整参考。
• GitHub Discussions 文档：GitHub Discussions 的设置指南和治理选项。
• CODEOWNERS 语法参考：CODEOWNERS 文件的完整语法。
• 《Producing Open Source Software》：Karl Fogel 著：关于运营开源项目的权威著作。可在 producingoss.com 免费在线阅读。其中关于治理、贡献者管理和沟通的章节可直接应用。
• 《开源治理模型简介》：Apache Software Foundation 的治理文档是一个很好的范例，展示了成熟的开源项目如何将权威与决策制度化：https://www.apache.org/foundation/governance/
• Vale 散文检查工具：Vale：在文档 RFC 中被引用；与 good first issue 文档改进工作流程集成。

本提案是在 ZeroClaw v0.6.8 及之前两份架构与文档 RFC 的背景下制定的。这里提出的治理模型有意保持轻量，以适应处于社区成长早期阶段、由学生主导的项目。它的设计具备可扩展性：随着团队的成长逐步增加流程，而非一次性全部引入。

最好的治理模型是团队真正会遵循的最简单模型。从这里开始，根据你所学到的进行调整。