contribos

ContribOS

赢得信任，合并 PR，再次参与。 ContribOS 帮助开源项目的新贡献者赢得信任。它会帮你找到欢迎你参与的项目，说明这个仓库希望如何完成更改，检查你是否真正理解自己的更改，在评审过程中指导你，并将已合并的 PR 转化为一份记录，供下一位维护者核实。

到了 2026 年，编写代码已不再是参与贡献的难点。AI 让提交 PR 的成本大幅降低，维护者则以 PR 数量上限、背书名单和 AI 政策作为回应，新手 PR 的合并率随之下降。ContribOS 让你的 PR 值得维护者花时间评审。

ContribOS 绝不会替你创建 PR、发表评论或认领议题，也绝不会替你撰写说明。它只指引方向，由你来决定。

如果 ContribOS 帮你避免了一次被拒的 PR，在这个仓库点个 ⭐，让更多贡献者发现它。

看看它如何运作

创建 PR 之前，先询问仓库对贡献的要求。以下是运行 contribos policy pallets/flask 的真实输出，内容经过精简（快照日期为 2026 年 10 月 6 日；运行命令可查看最新结果）：

# Contribution policy: pallets/flask

## AI policy
No written AI policy found. Disclosing AI use is still the courteous default.

## Tests
Changes are expected to come with tests.
- `.github/pull_request_template.md:20`: - Add tests that demonstrate the correct behavior of the change. Tests

## Changelog
Changes usually need a changelog or news entry.
- `.github/pull_request_template.md:23`: - Add an entry in CHANGES.rst summarizing the change and linking to the issue.

## Tests in practice
50% of recent code PRs also changed tests.
- `git history`: 19 of 38 recent code-changing PRs

## Outside PRs
2 of the last 49 closed PRs from non-members landed.

每项说明都指向一个文件和行号（或 Git 历史记录），因此你可以自行核实。ContribOS 只指引方向，由你来决定。

pip install contribos
contribos policy pallets/flask

使用历程

步骤	命令	你会获得什么
查找	contribos find --lang python --topic web	按「值得一试 / 可能合适 / 跳过」分类的开放问题，并附上依据：是否有人认领？是否有开放 PR？维护者是否活跃？问题是否清晰？此外还会提供仓库欢迎情况：是否已归档、背书名单、AI 政策、外部 PR 合并率、外部 PR 等待首次人工回复的时长、搁置数量、过时机器人，以及你在该仓库的开放 PR
规则	contribos policy owner/repo	仓库的 AI 政策、披露格式（Assisted-by: 等尾注）、背书门槛、「优先新手问题不得使用 AI」规定、先提问题和先认领的惯例、测试、变更日志、DCO/CLA、风格工具和活动情况，每项均附有 file:line 引文。--json 会以 Agent 可读取的形式提供相同规则
提议	contribos claim <issue-url>	编码前发布的简短提议：可能涉及的文件、规模相近的历史 PR、测试应该放在哪里，以及一个切实的问题。会提醒你注意已被认领的问题、尚无维护者的问题、优先新手问题的 AI 规则和先提问题的规则。如果仓库有背书名单，会先起草自我介绍
语气	contribos tone comment.md --kind comment	标记机器撰写的迹象（delve、流行术语、助手式开场白、填充内容）、长度问题、缺少的问题，以及你即将发布的内容中残留的占位符
Agent 规则	contribos agent-rules . --ai "Claude Code"	将此仓库的规则告知你的编码 Agent：为 Claude Code、Codex、Copilot 和 Cursor 生成一个 SKILL.md、一个阻止 Agent 创建 PR 或发布评论的钩子，以及一个用于签署确认和 AI 披露尾注的 commit-msg 钩子。所有内容仅保存在本地，不纳入 git
设置	contribos setup owner/repo	根据仓库的 CI 和贡献指南整理出的具体步骤：运行时版本、安装、服务、环境变量、测试和 lint 命令
诊断	contribos setup --diagnose output.txt	解释失败原因：缺少依赖、版本错误、服务未运行、环境变量问题、本机编译工具、易波动的测试，或真实的测试失败（以及如何确认问题不是由你造成的）
了解	contribos brief <issue-url>	要阅读的文件及选择每个文件的原因、相似的历史 PR 及评审者的意见、相关测试、应避免触碰的相似文件、项目惯例和可能的评审问题。添加 --llm 可获得以证据为依据的通俗摘要
验证	contribos check --explain explain.md --verify-test "pytest tests/test_x.py" --issue 123 --ai "Claude Code: drafted the test" --pr-draft pr.md	提交前检查：变更范围与相似历史变更的对比、测试、变更日志、签署确认、遗留调试内容、AI 政策和披露尾注，以及同一问题的竞争 PR。--verify-test 会先使用修复运行测试，再将源文件还原为基准版本后再次运行，让你证明没有你的更改时测试会失败。它会检查你的说明是否涵盖每个变更文件，并说明你不确定的内容，然后起草 PR：改了什么及原因、如何验证、有哪些不确定之处、相关历史变更、AI 协助情况
回复	contribos review <pr-url> --path .	对每条评审意见进行分类（阻塞、需要修改、问题、小问题……），指出其对应代码、呼应的项目惯例、回复草稿、尚未回复的内容及已等待的时长，以及失败的 CI
成长	contribos record <github-user> --html me.html	可公开访问并分享链接的记录：已合并的 PR、修改请求、是否回复了每条评审意见、是否解释了你的更改并披露 AI 使用情况
Agent	contribos mcp	为 Claude Code、Cursor、Codex 等提供 9 个 MCP 工具（policy、brief、setup、diagnose、check、review、find、claim、tone）；当 Agent 有文本输入时可接收文本：claude mcp add contribos -- python -m contribos mcp

安装

pip install contribos     # Python 3.10+, git. Zero external dependencies.
export GITHUB_TOKEN=...   # needed for find, claim/brief from an issue URL, review, record
`policy` also runs without a token, but it skips pull-request signals and says so at the top of its output.

所有可离线运行的功能都支持离线运行：policy、brief --title、claim --title、setup、check、bench 和 review --data 仅需 git。添加 --offline 可跳过 API，添加 --update 可获取新的提交。克隆和索引缓存在 ~/.cache/contribos（CONTRIBOS_CACHE）中。

可选的 AI 摘要：设置 CONTRIBOS_LLM=anthropic（并提供 ANTHROPIC_API_KEY）或 CONTRIBOS_LLM=openai（并提供 OPENAI_API_KEY），还可选设置 CONTRIBOS_MODEL。模型只会解释 ContribOS 已收集的证据。任何引用证据之外文件的句子都会被丢弃。

工作原理

• repo.py 处理缓存的克隆。它通过 git show 和 git grep 读取任意修订，因此无需检出。
• precedent.py 构建主线变更（压缩合并和合并 PR）的 SQLite 索引，记录这些变更涉及的文件以及修复的问题。
• policy.py 是政策雷达，根据贡献文档、AI 政策、模板、担保名单、CI 配置和历史记录构建。
• brief.py 根据代码中的罕见词匹配、路径匹配以及类似过往 PR 涉及的文件为文件排序。它还会通过共同变更历史查找相关测试。
• check.py 用于提交前检查、理解验证以及 PR 草稿生成。
• setup_doctor.py 根据 CI 和文档生成设置步骤，并诊断故障。
• find.py 检查问题是否适合认领、仓库是否欢迎贡献者以及响应速度。
• claim.py 起草提案和担保引荐。
• proof.py 在有无你的变更时分别运行测试（并在 finally 中还原文件）。
• tone.py 检查你即将发布的文本。
• agent_rules.py 编写本地 Agent 技能和钩子。
• review.py 对审查评论进行分类、起草回复并跟踪后续处理。
• record.py 构建贡献记录（Markdown 以及独立的 HTML 页面）。
• llm.py 是可选的提供方层（Anthropic 或 OpenAI），支持引用溯源。
• mcp_server.py 是无需依赖的 MCP stdio 服务。
• github.py 是可选的 API 客户端。所有调用方都能处理其缺失的情况。
• bench.py 运行历史基准测试。

基准测试（2026-09-28，离线，以 PR 标题代替问题描述）

仓库	Brief hit@5	仅 Grep hit@5
pallets/flask（30 个 PR）	0.77	0.73
pytest-dev/pytest（30 个 PR）	0.87	0.87

与过往 PR 匹配只能略微提升文件查找效果，这印证了计划中的判断：查找文件已是通用能力。真正的价值在于了解过往 PR 如何解决问题，以及审查者提出了什么要求。下一轮基准测试需要真实的问题文本和审查评论，这需要 GITHUB_TOKEN。

贡献

欢迎贡献，包括参与 Hacktoberfest。请从标记为 good first issue 的问题开始，在其中一条评论认领该问题，并先阅读 CONTRIBUTING.md。其中介绍了如何认领问题、披露 AI 使用情况以及运行测试。若要查看 ContribOS 读取这些规则的方式：

contribos policy adityatiwari101104/contribos

状态

• 已在真实仓库（Flask、pytest、Ghostty）中测试：policy、brief、claim --title、setup、check、bench、mcp。
• 已于 2026-10-01 针对 GitHub 实时 API 测试：find（在 maximilianfeix/proxy-scraper 和 brekkylab/backlot 上评估问题是否适合认领，并计算维护者响应时间中位数）、claim <url>（利用过往相似 PR 和目标文件起草编码前提案）以及 record（验证 @adityatiwari101104 的公开已合并 PR 作品集）。
• 已在临时 git 仓库中测试：agent-rules（git 状态保持干净、保护机制会阻止 gh pr create、commit-msg 钩子会强制要求 sign-off 和 trailer）、check --verify-test、tone、政策雷达 v2。
• 测试：python -m unittest discover -s tests（59 个测试，CI 矩阵覆盖 Linux、macOS 和 Windows）。

发布

1. 在 pyproject.toml、contribos/__init__.py 和 server.json 中的两个位置更新版本号。
2. 运行 python -m unittest discover -s tests，然后提交并推送。
3. 创建标签并发布：

git tag v<version>
git push origin v<version>
python -m build
twine upload dist/*
mcp-publisher login github
mcp-publisher publish