ContribOS 是一个开源贡献伴侣工具，同时提供指南和 MCP 服务器。它的定位是帮助新开源贡献者在 AI 时代获得信任并成功合并 PR。进入 2026 年，写代码已不是贡献的难点：AI 让 PR 变得廉价，维护者因此设置 PR 上限、担保名单和 AI 政策，新人的合并率随之下降。ContribOS 的目标是让你的 PR 值得维护者花时间处理。它不会替你开 PR、发评论或认领 issue，也不会代写说明，只负责指路，由你自行决定。
主要能力：
- 政策雷达（policy.py）：从贡献文档、AI 政策、模板、担保名单、CI 配置和历史中构建仓库政策视图。每条结论都指向具体文件与行号（或 git 历史），可自行核对。
- 基于证据的简报（brief.py）：按代码中的罕见词匹配、路径匹配、以及相似历史 PR 触及的文件对文件排序，并通过共同变更历史找出相关测试。
- 提交前检查（check.py）：包含提交前检查、理解度验证和 PR 草稿。
- 环境诊断（setup_doctor.py）：根据 CI 和文档生成安装步骤，并诊断失败原因。
- 可参与性检查（find.py）：评估 issue 可认领性、仓库欢迎程度与响应速度。
- 提案草拟（claim.py）：起草提案与担保介绍。
- 理解证明（proof.py）：在有你的改动和无你的改动两种情况下运行测试（文件在 finally 中恢复）。
- 语气检查（tone.py）：检查你即将发布的文本。
- 本地 agent 规则（agent_rules.py）：生成本地 agent 技能与钩子。
- 审查辅导（review.py）：对审查评论分类、起草回复并跟踪后续落实。
- 贡献记录（record.py）：生成 markdown 和自包含 HTML 页面的贡献记录。
使用方式：多数可离线运行的功能只需 git，包括 policy、brief --title、claim --title、setup、check、bench 和 review --data。使用 --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 读取任意修订，无需 checkout。precedent.py 构建主分支变更（squash and merge PR）、其触及文件和所修复 issue 的 SQLite 索引。github.py 是可选的 API 客户端，所有调用方都处理其缺失情况。mcp_server.py 是零依赖的 MCP stdio 服务器。
适用场景：适合希望在维护者设置 AI 政策、PR 上限和担保名单的仓库中提高合并率的新贡献者；也适合想了解某仓库接受改动的具体方式、在提交前自检理解程度、并积累可验证贡献记录的人。项目欢迎贡献，包括 Hacktoberfest；建议先从标注 good first issue 的 issue 入手，评论认领后阅读 CONTRIBUTING.md，其中涵盖认领 issue、披露 AI 使用和运行测试的规则。
验证与限制：已在真实仓库（Flask、pytest、Ghostty）上测试 policy、brief、claim --title、setup、check、bench、mcp；2026-10-01 针对线上 GitHub API 测试了 find、claim <url> 和 record；并在临时 git 仓库中测试 agent-rules、check --verify-test、tone、policy radar v2。测试通过 python -m unittest discover -s tests 运行，共 59 个测试，CI 覆盖 Linux、macOS 和 Windows。基准测试（2026-09-28，离线，以 PR 标题代指 issue）显示，与历史 PR 匹配对文件定位帮助不大，印证了“找文件是通用能力”的判断；下一步基准需要真实 issue 文本和审查评论，这需要 GITHUB_TOKEN。发布流程为：更新 pyproject.toml、contribos/init.py 和 server.json 中两处版本号，运行测试后提交推送，再打标签并发布。