vouch 贡献指南：基于显式 Vouch 信任门禁的开源协作与 Denounce 机制-育师

开源治理
CLI
认证鉴权

【免费下载链接】vouch

A community trust management system based on explicit vouches to participate.

项目地址：https://gitcode.com/gh_mirrors/vou/vouch

vouch 是一个社区信任管理系统：用户在参与项目的特定环节（例如提 PR）之前必须先被显式背书（vouched），也可以被**显式除名（denounced）**从而被彻底封禁。vouch 项目本身就是一个典型的"吃自己狗粮"案例——它的贡献流程完全由 vouch 系统强制执行。读完本篇，你将理解"vouched 才能提 PR、未 vouched 的 PR 自动关闭、denounce 可跨项目复用"这套信任门禁的完整规则、在本仓库中的真实落地方式（GitHub Actions + VOUCHED.td 信任清单），以及如何一步步获得背书、避免触发除名。

贡献门禁的基本规则

CONTRIBUTING.md 开篇就明确了本项目的贡献前提：

必须 vouched 才能开 PR：You must be **vouched** to open a pull request.未获背书的提交者开出的 PR 会被自动关闭；
Issue 不设门禁：Bug 与功能请求可以直接提 issue，不需要先获得背书；
AI 使用约束：如果你使用了 AI 辅助，除非你完全理解 AI 给出的方案，否则不要直接提交解决方案——只描述你遇到的问题，把解决工作留给维护者。

为什么要把 PR 门禁做这么严格？原文给出了动机：

这个系统存在的原因是，开源一直建立在信任之上，而 AI 让"默认信任"（trust-by-default）不再可行，因为生成"看似合理但实际质量很低"的贡献已经变得太容易了。

README.md 的 "Why?" 一节从项目设计层面进一步解释了这一背景：历史上理解代码库、实现改动、提交审查的成本足够高，天然过滤了大量低质量贡献；而 AI 工具大幅拉低了提交门槛，因此项目转向"显式信任模型"——可信的人为新人背书，被背书的人才能参与贡献。vouch 系统本身不规定具体政策，"谁可以被背书、如何被背书、背书带来什么权限"完全交给接入项目自定义，而 vouch 仓库自己选择的最严格策略就是"PR 硬门禁"。

自动关闭机制：仓库中如何 dogfood 这套系统

"未 vouched 的 PR 自动关闭"不是口头约定，而是由仓库内的工作流实现的。.github/workflows/vouch-check-pr.yml 定义了两个触发点：

on: pull_request_target: types: [opened, reopened] issue_comment: types: [created]

PR 被打开或重新打开时，执行check-pr动作并开启auto-close: true；
在 PR 的评论里输入/recheck时，会重新执行一次检查——这正是"先提 issue 获得背书、再把已打开的 PR 救回来"这一流程的关键钩子：vouched 文件更新后，贡献者无需重开 PR，只需评论/recheck触发复检。

该工作流调用 check-pr 动作，其 action.yml 暴露的核心输入包括：

输入	默认值	说明
`pr-number`	（必填）	要检查的 PR 编号
`auto-close`	`"false"`	是否自动关闭未 vouched / 被 denounced 用户的 PR
`dry-run`	`"false"`	只打印会发生什么，不实际改动
`require-vouch`	`"true"`	`false`时只封禁被 denounced 的用户
`vouched-file`	`".github/VOUCHED.td"`	信任清单文件路径
`template-file`	`""`	自定义关闭时回复贡献者的模板

动作的输出status取值为skipped（bot）、vouched、allowed或closed。从 vouch/github.nu 中gh-check-pr的实现可以看到判定顺序：

作者以[bot]结尾 →skipped，直接放行；
作者是具有 write 权限的协作者 → 视为vouched，放行；
作者在 VOUCHED 清单中 →vouched；
作者被 denounced → 发一条"作者被 vouch 清单显式封禁"的评论并关闭 PR；
其余情况（未 vouched 且require-vouch为 true）→ 渲染关闭模板、发评论、关闭 PR。

未 vouched 用户收到的是内置模板 github-pr-unvouched 渲染出的留言，其核心内容是：

Hi @{author}, thanks for your interest in contributing! This project requires that pull request authors are vouched, and you are not in the list of vouched users. This PR will be closed automatically.

注意该模板中的仓库链接指向的是项目的 CONTRIBUTING 文档——也就是说，被自动关闭的贡献者被直接引导到本篇所讲的"如何获得 vouch"流程上，形成闭环。

一个值得注意的细节：vouch 仓库只部署了check-pr检查，而没有部署 check-issue 动作。这与 CONTRIBUTING.md 中"issue 可以直接提"完全一致——门禁只作用于 PR 这一环节，问题讨论保持开放，背书流程本身也依赖"先提 issue"来完成。

如何获得 Vouched：五步流程与背后的自动化工具

CONTRIBUTING.md 给出的官方流程是：

提一个 issue，描述你想改什么、为什么改；
保持简洁；
用自己的语气写，不要让 AI 代笔；
维护者如果认可，会 approve 该 issue 并为你 vouch；
获得认可后即可提交 PR。

FAQ.md 补充了语气：获得 vouch 不应该困难，vouch 主要防止的是"低投入的 drive-by 贡献"；"像在任何正常的人类社交环境里一样做自我介绍，你就能获得 vouch"。滥用信任则会带来下一节的后果。

本仓库中 vouch 是如何被执行的

"维护者 approve 并为你 vouch"这一步由两条工作流自动完成：

.github/workflows/vouch-manage-by-issue.yml：监听issue_comment，调用 manage-by-issue 动作；
.github/workflows/vouch-manage-by-discussion.yml：监听discussion_comment，调用 manage-by-discussion 动作。

两者都配置了concurrency: { group: vouch-manage, cancel-in-progress: false }，用于串行化对 VOUCHED 文件的并发写入，避免两个人同时被 vouch 时互相覆盖。

manage-by-issue 动作的 action.yml 定义了一组可配置的输入，关键的有：

vouch-keyword/denounce-keyword/unvouch-keyword：触发关键词，逗号分隔，默认分别为vouch、denounce、unvouch；
roles：允许执行管理操作的 GitHub 角色，默认admin,maintain,write,triage；
allow-vouch/allow-denounce/allow-unvouch：分别开关三种操作，默认都开启；
pull-request/merge-immediately：把对 VOUCHED 文件的改动以 PR 形式提交而非直接推送（需要pull-requests: write权限）；
vouched-managers-repo/vouched-managers-file/vouched-managers-ref：支持从另一个仓库的 VOUCHED 文件读取"谁有管理权"，实现跨仓库信任管理。

当符合角色的协作者在 issue 下评论时，动作按以下语法匹配（见 manage-by-issue/README.md）：

vouch— 为 issue 作者背书
vouch @user— 为指定用户背书
vouch <reason>/vouch @user <reason>— 带理由背书
denounce、denounce @user、denounce <reason>、denounce @user <reason>— 除名
unvouch、unvouch @user— 从清单中移除

匹配成功后，动作把用户名写入仓库的 VOUCHED 清单、提交并推送，输出status为vouched、denounced、unvouched或unchanged。提交信息会自动带上触发评论的链接，便于审计"谁在哪个评论里给了背书"。

信任清单：VOUCHED.td 文件

vouch 的背书名单是一个扁平的.td（Trustdown）文件，默认查找路径为VOUCHED.td或.github/VOUCHED.td，可用标准 POSIX 工具直接解析。本仓库实际使用的 .github/VOUCHED.td 是一个纯用户名列表（按字母序），而 VOUCHED.example.td 展示了完整语法：

# 每行一个 handle（不带 @），按字母序排列 username platform:username # 可选平台前缀，如 github:mitchellh -platform:denounced-user # 减号前缀表示除名 -platform:denounced-user 除名理由

add-user、check-user、denounce-user、remove-user等核心逻辑在 vouch/lib.nu 中实现，vouch/file.nu 提供from td/to td编解码（open/save对.td文件透明工作，且保留注释与空行）。手动管理时也可以直接用 CLI：

# 查看用户状态：退出码 0 = vouched，1 = denounced，2 = unknown vouch check <username> # 预览（默认）或就地写入清单 vouch add someuser --write vouch denounce badactor --reason "Submitted AI slop" --write

实现见 vouch/cli.nu 中的add、check、denounce命令。

对 AI 辅助贡献的约束

CONTRIBUTING.md 专门用一段话约束了 AI 的使用方式：

如果你使用 AI，除非你理解这些方案，否则不要提交解决方案。否则，只提交你遇到的问题，让维护者来处理。

结合第 1 步"issue 必须用自己的语气写、不要让 AI 代笔"，可以归纳出本仓库对贡献者输入质量的完整要求：问题描述必须来自真实使用者的一手观察，且背书申请必须体现真实的人。这不是技术限制，而是信任模型的准入条件——整个系统存在的理由（README "Why?" 一节）就是 AI 让"可信度无法从提交行为本身推断"。

Denouncement：除名与可跨项目复用的封禁名单

CONTRIBUTING.md 的最后一节定义了除名（denouncement）规则：

如果你反复表现出糟糕的行为（不读说明、无礼或煽动性等），你会被denounced。这会将你加入一个封禁名单，封禁你与本项目的交互，以及任何镜像了本项目封禁名单的其他项目。

这个"镜像"能力是 vouch 设计的一个特色。VOUCHED.example.td 的头部注释解释了为什么项目自己维护一份除名清单、而不是（或除了）使用平台的 block 功能：

我们选择维护一份除名清单（而非或补充于平台自带的 block 功能），这样其他信任我们的项目可以直接"吸入"（slurp in）我们的除名名单，复用我们对不良行为者的既有判断。

文件层面，除名就是清单里的一行减号条目，例如示例中的：

-github:badguy -github:slopmaster3000 Submitted endless amounts of AI slop

check-pr/check-issue等动作对 denounced 用户是无条件封禁的（无论require-vouch是否开启），并会用固定文案关闭其 issue/PR；而 manage-by-issue 动作支持通过denounce关键词直接执行除名，配合vouched-managers-*输入还可以引用其他仓库的清单来决定"谁有权除名"。

FAQ.md 还澄清了两个常见质疑：被 vouched 的用户只是获得"与项目交互的资格"，并不获得合并 PR、推代码或发版的权限（这些仍由现有审查与系统控制把关）；默认只有 admin 和具有 write 权限的协作者能 vouch/denounce，普通被背书用户不能为他人背书。

小结：给贡献者的行动清单

只想要 vouch ？提一个简短的、自己语气写的 issue，说明想改什么、为什么，等待维护者 approve 与 vouch；
已有 PR 被自动关闭？在获得背书后，到该 PR 下评论/recheck触发复检（见 vouch-check-pr.yml）；
只想反馈 Bug？直接提 issue 即可，无需任何前置资格；
使用 AI 时，只报告问题、不提交未经验证的解决方案；
守住底线：反复的违规行为会触发 denounce，并进入可能被其他项目复用的封禁名单；
若要在其他仓库接入同样机制，可参考 README.md 的动作清单与 COOKBOOK.md 中的真实场景指南（如配合 branch protection 使用 GitHub App 令牌）。