PR Genius 是一个基于真实仓库案例研究的拉取请求（Pull Request）贡献顾问，定位为面向专业开源贡献者和 AI 智能体的「外部 PR CRM」——即管理你提交到其他仓库的 PR，而不是一个 PR 仪表盘。它的核心主张是：不替你写 PR，而是知道哪些 PR 会被关闭，从而帮助避免被拒绝。
【用途与定位】 项目用于在提交 PR 之前评估其被合并的概率与潜在风险，并在提交之后跟踪状态：包括是否该修复 CI、是否该变基（rebase）、是否该继续等待、是否该催促（ping）维护者，或者是否该放弃。仓库中加载了来自 67 个仓库、共 943 条模式。仓库说明明确指出，触发覆盖率（规则在真实 PR 上触发的频率）由 scripts/measure_pattern_coverage.py 单独衡量（见 issue #66），并且不宣称存在「质量通过率」指标，因为当前集合不可测量，故不作断言。
【主要能力】
- 合并概率分析与模式匹配：基于真实案例库给出分析，帮助判断 PR 的走向。
- 状态心跳：通过 cron 每日运行，自动检测状态，如 NEEDS_REBASE / CI_FAILING（需立即修复）、STALE_REVIEW（超过阈值后催促）、STALE_NO_REVIEW（考虑放弃）、CLEAN / WAITING（继续等待）。
- contributor_view（贡献者视图）：回答「我现在该不该提交这个 PR，阻塞点是什么」，是预提交门禁，可在开 PR 前运行，修改后再次运行。
- maintainer_view（维护者视图）：回答「维护者应该如何处理这个 PR」，采用 5 种动作决策：READY_FOR_REVIEW、WAIT_FOR_AUTHOR、CLOSE_DUPLICATE、CLOSE_STALE_OR_RISKY、HOLD_MAINTAINER_DECISION。
- 知识库与仓库画像：可按仓库获取 profile（python3 -m prgenius profile get owner/name），规则因项目而异。
【使用方式】 命令行：安装后控制台脚本为 prgenius-core，python3 -m prgenius 等价。每个命令都接受全局参数 --repo-root 指向知识库检出目录。首次运行 doctor 很重要，它会告知知识库包是否被找到、缺失哪些可选部分；裸 pip install 后显示 overall: NOT OK 属预期，因为该 wheel 只包含代码，并非安装损坏，警告会指明该做什么。issue 和 issue-batch 为 v1.6.3 新增。 MCP 配置：支持 Docker 方式构建 stdio MCP 服务器（docker build -t pr-genius . && docker run --rm -i pr-genius），该镜像为 stdio 服务器而非 HTTP 服务；ghcr.io/zsxh1990/pr-genius 镜像由 Dockerfile.github_action 构建，用于 GitHub Action，不用于 MCP stdio。MCP 工具参数中 title 为 analyze_pr、coach_pr、triage_pr 必填；repo 为多数工具必填，格式 owner/name；pr_description 可选；query 为 search_patterns 必填；diff_stat 可选，为 git diff --stat 输出，是 PR 体积的权威信号，缺少时 impact / review 字段为 null。star_count ≥ 0、repo_merge_rate 在 [0.0, 1.0]、author_association 取值 NONE/CONTRIBUTOR/COLLABORATOR/MEMBER/OWNER、mergeable 取值 MERGEABLE/CONFLICTING/UNKNOWN，非法值会被拒绝而非静默产出无意义结果。 GitHub Action：可在任意仓库使用。comment_mode 控制是否把完整分析作为可见 PR 评论发布（类似 pr-agent 的 /review）：never（默认）、high_risk（仅高风险时发布）、always（每次运行都发布，已有评论原地更新，不会刷屏）。旧版 comment_on_high_risk: true 仍受支持，行为等同 comment_mode: high_risk。标签建议使用 @v2.1.4 固定发布标签以保证可复现；@main 为最新开发版，不建议生产使用。没有跟踪 2.x 的浮动主版本标签，唯一的浮动主版本标签 v1 冻结在 v1.8.0，不存在 v2 标签，应固定完整的 vX.Y.Z 标签。Docker 镜像标签由 publish-ghcr.yml 从每个 vX.Y.Z git 标签生成 {version} / {major}.{minor} / {major}，例如 latest、2.1.4、2.1、2。可用 Dependabot 自动更新。 DSH（Cordis）插件：v2.0.0+ 提供，可嵌入 DeepSeek Harness 的聊天侧栏、顾问面板、会话标签、偏好设置区以及 /prgenius 斜杠命令。TypeScript 层只是薄壳，分析委托给现有 Python MCP 引擎；插件在其上增加五个 UI 表面。维护者模式是同样的五个表面在不同投影下运行。所有可调项经 Schemastery 校验，可在 cordis.yml 设置而无需改代码，非法值在加载时失败并指明字段；完整 schema 见 src/config.ts（14 个叶子字段，涵盖 kbRoot、MCP 传输/命令/参数/URL/超时/协议版本、侧栏默认视图、维护者开关/动作/置信下限/停滞天数、语言、风险过滤）。插件与 v1.x 关系：封装同一个 Python 分析引擎（prgenius/src/prgenius/mcp.py），v1.x CLI 与 MCP 服务器继续工作不变，插件只增加 UI 与配置管理，不派生分析逻辑。 【贡献者要点】 从 FIX_BEFORE_SUBMIT 到 READY_TO_SUBMIT 的实践要点：关联 issue（正文写 Fixes #N / Closes #N，这是首个 PR 被打回最常见原因）；保持小体积（体积来自 --diff-stat，不传则 impact/review 为 null，应传）；测试要在没有你的改动时失败（两边都通过的测试只是装饰）；匹配目标仓库自身的约定而非全局约定，先读该仓库 profile，规则因项目而异，这正是知识库的意义。仓库数字可在当前提交下通过 python3 -c "from prgenius.parser import iter_profiles, iter_case_studies; from prgenius.evaluator import load_anti_patterns, load_success_patterns; print(len(list(iter_profiles('.'))), len(list(iter_case_studies('.'))), len(load_anti_patterns('.')), len(load_success_patterns('.')))" 验证。 【适用场景与限制】 适用于专业开源贡献者、AI 智能体，以及需要以维护者视角审阅 PR 的场景；可集成到 CI（GitHub Action）、容器化部署（GHCR Docker 镜像）或聊天环境（DSH 插件）。 限制与诚实说明：仓库明确表示 DSH 插件已通过 TypeScript 编译、单元测试和静态契约一致性验证（scripts/check_dsh_plugin_contract.py，27/27 检查），并在真实 DSH 运行时运行过（issue #100、#101、#103 由此发现）；但当前代码仍未验证——2.1.5 及之后发布的修复尚未在宿主环境中重新验证，本版本的渲染与运行时行为需要该复检。版本矩阵见 docs/compatibility.md（每个单元格均标记为未运行），完整性记分卡见 docs/maturity-self-assessment.md。相关文档还包括 docs/index.md（文件地图）、AGENT_GUIDELINES_SCHEMA.md、ROUNDS_SCHEMA.md、BLACKLIST.md（不跟踪的仓库）、CONTRIBUTING.md（欢迎 AI 辅助 PR）、行为准则与安全策略，并提供中文版 README（README.zh-CN.md）。 【暂未提供】 仓库资料未提供具体的收费方式、价格、各平台支持细节或效果量化数据。
