ProofPR

AI 写 PR 很快，人审 PR 很贵。

ProofPR 是给开源维护者和团队 reviewer 使用的 AI PR 初审门禁。

它不是个人开发者的 git 工作树工具，也不是 AI code reviewer。它只在人工审查开始前回答一个问题：

这个 PR 现在值不值得维护者投入时间 review？

ProofPR 会读取 PR diff、PR 描述和仓库配置，判断贡献者是否补齐了测试、复现、截图、变更说明、权限理由，以及这次改动是否碰到依赖、workflow、secret、MCP 或其他高风险区域。输出结果只服务 reviewer 的第一轮判断：

结论：可以 review、先补证据，还是高风险先别合并。
缺口：测试、复现、截图、变更说明、权限理由。
重点：供应链、Workflow 权限、密钥、MCP、敏感路径和改动范围。

适合谁

你是谁	是否适合
开源维护者，需要处理陌生贡献者或 AI 生成 PR	适合
团队 reviewer，希望 PR 先补齐验证证据再进入 review	适合
安全/平台团队，关注依赖、workflow、secret、发布链路变更	适合
个人开发者，自己写、自己测、自己合并	通常不需要
想找一个 AI 自动判断代码对错的 reviewer	不适合

现在能用吗

GitHub Release：v1.0.0
npm：proof-pr@1.0.0
GitHub Action：linsk27/proof-pr@v1.0.0
当前源码 benchmark：22/22 passed
默认接入：npx proof-pr@latest init
接入体检：npx proof-pr@latest doctor
本地模拟初审：npx proof-pr@latest check
生成补证请求：npx proof-pr@latest request
可视化报告：init 生成的 workflow 会自动上传 proofpr-report.html artifact

1.0 状态：

功能收口：不继续扩成大而全的开发者工具，只保留 PR 初审、补证、供应链/Workflow 风险提醒。
边界明确：不判断代码业务逻辑对错，不替代人工 review，不承诺发现所有漏洞。
发布链路已验证：npm Trusted Publishing 已绑定 linsk27/proof-pr + release.yml，v0.1.21 到 v1.0.0 已通过 GitHub OIDC 自动发布到 npm。
维护策略：1.0 后优先修 bug、修文档、补真实案例；不再继续堆复杂命令。

验证你拿到的是最新版本：

npm view proof-pr version
npx proof-pr@latest --version

这两个命令当前都应输出 1.0.0。

不知道怎么开始时，直接运行中文向导：

npx proof-pr@latest
# 或
npx proof-pr@latest guide

如果你习惯先看帮助，npx proof-pr@latest --help 会显示中文命令说明，并在底部给出常用复制命令。子命令帮助页默认只展示常用参数，高级参数仍可使用；普通接入不需要先理解完整参数表。

正式使用只需要两步：

目标	命令
接入 GitHub PR 自动检查	`npx proof-pr@latest init`
体检接入是否正确	`npx proof-pr@latest doctor`

本地命令是辅助项：

目标	命令
发 PR 前模拟初审	`npx proof-pr@latest check`
生成贡献者补证请求	`npx proof-pr@latest request`

其他能力是辅助项，不是理解 ProofPR 的入口：

场景	命令
自动修复常见接入问题	`npx proof-pr@latest doctor --fix`
不接入仓库，先体验报告	`npx proof-pr@latest demo workflow --locale zh-CN`
把补证请求写入文件	`npx proof-pr@latest request --output proofpr-request.md`
输出完整补证模板	`npx proof-pr@latest request --full`
生成 HTML 可视化报告	`npx proof-pr@latest check --format html --output proofpr-report.html`
生成 SARIF	`npx proof-pr@latest check --format sarif --output proofpr.sarif`
查看内置案例	`npx proof-pr@latest demo --list`

本地 check 通常没有 PR 标题和描述上下文，报告会明确提示这一点；打开 PR 后，ProofPR 会结合 PR 标题和描述重新评估证据。需要本地模拟 PR 描述时，把描述写入 pr.md，再运行 npx proof-pr@latest check --pr-body-file pr.md。这个命令也会出现在 check --help 的常用复制里。

它解决什么问题

常见 PR 问题	ProofPR 给维护者什么
PR 描述很薄，只写了 fixed bug。	判断描述质量，要求补充动机、复现、验证和影响。
改了代码但没有测试，也没有手动验证说明。	输出 `needs-evidence`，让维护者先要证据再深度审查。
改了 `.github/workflows/**`、依赖、`.env`、MCP 配置。	把敏感文件列出来，给出重点审查清单。
新增依赖、大版本升级、非注册表来源、未固定版本、`postinstall` 脚本。	提醒核查供应链来源、变更说明、迁移说明、解析覆盖和 lockfile 是否同步。
使用 `pull_request_target` 并 checkout PR head。	标记为高风险组合，避免高权限上下文运行不可信 PR 代码。
团队想要求 UI 改动必须有截图。	用 Evidence Contract 声明路径级证据要求。
想把扫描结果做成可分享页面。	输出可搜索、可筛选、可复制补证清单的独立 HTML 风险面板。

最快开始

0. 先体验，不改仓库

npx proof-pr@latest demo workflow --locale zh-CN

想看所有内置案例：

npx proof-pr@latest demo --list

1. 生成配置和 workflow

npx proof-pr@latest init

这个命令会一次生成三份接入文件：

.proofpr.yml
.github/workflows/proofpr.yml
.github/pull_request_template.md

默认配置已经适合开源仓库试用；PR 模板会引导贡献者补充验证、复现、截图、变更说明和权限理由。生成的 workflow 还会默认保存 proofpr-report.html artifact，维护者可以在 Actions 页面直接下载可视化报告。如果仓库里已经有这些文件，init 默认会保留不覆盖，并告诉你哪些文件已存在；需要刷新到当前模板时再加 --force。

2. 体检接入状态

npx proof-pr@latest doctor

doctor 会检查 .proofpr.yml、.github/workflows/proofpr.yml、PR 模板、Action 版本、PR 事件、评论权限和本地 diff 是否可读。它会像 check 一样自动识别常见主分支，并在报告顶部给出一句话建议，目标是告诉新用户“装好了吗，下一步做什么”。

3. 提交并打开 PR

git add .proofpr.yml .github/workflows/proofpr.yml .github/pull_request_template.md
git commit -m "chore: add ProofPR"

ProofPR 会在这些时机运行：

PR opened：第一次打开 PR。
PR synchronize：PR 分支继续 push。
PR reopened：重新打开 PR。

4. 看报告或生成补证请求

报告主要出现在 PR 评论区、GitHub Actions summary、workflow annotations 和 proofpr-report artifact。想先本地试跑，也可以直接执行：

npx proof-pr@latest check

如果当前分支没有可扫描 diff，check 会输出短提示并告诉你下一步运行 doctor、demo，或提交改动后再检查。

如果你只想得到一段可以直接发给贡献者的补证说明：

npx proof-pr@latest request

如果当前分支没有可扫描 diff，request 也会输出短提示，不会生成误导性的补证评论。

真实 PR 评论截图来自 demo PR #1：

本地 CLI 扫描真实项目 AI-Vue3-python-flask-Blog 的输出：

新增的 workflow 供应链风险案例输出：

独立 HTML 可视化报告：

Benchmark 输出，证明规则样本仍按预期命中：

说明：上面的 PR 评论和 CLI 图片来自真实运行；终端风格图片由当前仓库命令输出渲染生成，不是手写 mock。下面的 SVG 是帮助理解流程的示意图。

报告怎么看

报告优先看四个结论：

输出	含义
`Risk` / `风险等级`	`low`、`medium`、`high`，表示整体审查风险。
`Evidence score` / `证据评分`	0-100 分，越高代表 PR 证据越充分。
`审查门禁`	建议常规审查、重点审查、先补证据，或风险处理前不要合并。
`Risk Radar` / `风险雷达`	把 rule id 归并成证据完整性、供应链、Workflow 权限、密钥泄露和审查范围，先告诉维护者该从哪里看。
`审查行动清单`	可直接执行的维护者 checklist 和重点文件。
`一键补证建议`	可复制给贡献者的 PR 描述补充模板，减少来回追问。

报告会出现在：

PR Conversation 评论区。
GitHub Actions job summary。
Workflow annotations / PR 文件视图。
GitHub Actions artifact：默认的 proofpr-report.html 可视化报告。
可选 GitHub Code Scanning，见 SARIF 文档。
本地 HTML 可视化报告；报告里可以按严重程度筛选、搜索文件/规则，并复制补证清单。

它会检查什么

检查项	触发信号
改动规模	文件数、增删行数过大。
PR 描述质量	body 缺失或过薄。
测试和验证证据	代码改动没有测试文件，也没有验证说明。
复现上下文	缺少复现步骤、before/after、预期/实际结果。
Evidence Contract	命中仓库自定义路径，但缺少要求的截图、验证、变更说明或权限理由。
敏感路径	`.github/workflows/*`、`.env`、依赖文件、Dockerfile、MCP 配置等。
secrets	常见 API key、token、数据库连接串。
依赖变化	新增依赖、大版本升级、非注册表来源、未固定版本、manifest/lockfile 不一致、lockfile-only 变更、解析覆盖。
包生命周期脚本	`preinstall`、`install`、`postinstall`、`prepare` 等。
GitHub Actions 风险	写权限、OIDC、`pull_request_target`、PR head checkout 高风险组合。
MCP 风险	`command`、`args`、`env`、token、secret、password 等配置。

本地 CLI

先看中文向导：

npx proof-pr@latest guide

体检仓库是否接入正确：

npx proof-pr@latest doctor

扫描当前分支 diff：

npx proof-pr@latest check

check 会自动选择 origin/main、origin/master、main 或 master 作为对比基准，并扫描当前工作区相对 base 的最终状态：已提交分支 diff、staged、unstaged 和未跟踪新文件都会纳入。主分支不是这些名字时再显式指定：

npx proof-pr@latest check --base origin/dev

扫描内置案例：

npx proof-pr@latest demo workflow --locale zh-CN
npx proof-pr@latest demo secret --locale zh-CN
npx proof-pr@latest demo ui-evidence --locale zh-CN

生成独立 HTML 可视化报告：

npx proof-pr@latest check --format html --output proofpr-report.html

HTML 报告不是静态截图：它可以按高/中/低风险筛选、搜索规则或文件，并把“需要贡献者补什么”一键复制到 PR 描述或评论里。

维护规则或发版前再运行 benchmark：

npx proof-pr@latest benchmark --cases benchmarks/cases

配置示例

开源仓库推荐先用：

locale: zh-CN
preset: open-source-maintainer

comment:
  enabled: true

如果 UI 改动必须有截图和验证说明，可以加 Evidence Contract：

evidence:
  contracts:
    - id: ui-screenshot
      paths:
        - "src/components/**"
        - "app/**"
      requires:
        - screenshot
        - verification
      severity: medium

init 默认已经会在 GitHub Action 里保存 HTML 面板，对应 workflow 片段如下：

- uses: linsk27/proof-pr@v1.0.0
  with:
    html-output: proofpr-report.html
- uses: actions/upload-artifact@v4
  with:
    name: proofpr-report
    path: proofpr-report.html

内置预设：

预设	适合场景
`balanced`	低噪音试用。
`open-source-maintainer`	开源仓库推荐。
`security-strict`	安全敏感项目。
`ai-generated-pr`	AI 生成 PR 较多的仓库。
`mcp-security`	关注 MCP、Cursor、VS Code、本地 agent 配置。
`dependency-careful`	关注依赖清单、锁文件、多语言包管理配置和供应链风险。

准确性边界

ProofPR 的准确性不是“能不能发现所有代码 bug”。它做的是 确定性 PR triage：

不调用大模型，不上传代码。
不判断作者是不是用了 AI。
不替代人工代码审查。
只基于 diff、PR 描述和配置里的规则做可复现判断。
用 benchmark case 验证规则命中、风险等级和审查门禁是否符合预期。

这让它适合作为开源仓库的第一道门：先过滤“证据不足、风险边界不清”的 PR，让维护者把时间花在真正值得审查的改动上。

文档

下一步

上架 GitHub Marketplace。
增加 Issue 质量检查模式。
做规则插件系统，让团队可以写自己的规则。
可选集成 OpenSSF Scorecard、gitleaks、GitHub dependency-review。
可选 AI summary，但核心评分继续保持确定性、可复现、不上传代码。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm benchmark
pnpm build
pnpm release:check

重新生成 README 截图：

pnpm docs:screenshots

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 82 Commits
.github		.github
benchmarks		benchmarks
docs		docs
examples		examples
packages		packages
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
.proofpr.yml		.proofpr.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
action.yml		action.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ProofPR

适合谁

现在能用吗

它解决什么问题

最快开始

0. 先体验，不改仓库

1. 生成配置和 workflow

2. 体检接入状态

3. 提交并打开 PR

4. 看报告或生成补证请求

报告怎么看

它会检查什么

本地 CLI

配置示例

准确性边界

文档

下一步

开发

License

About

Uh oh!

Releases 51

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

ProofPR

适合谁

现在能用吗

它解决什么问题

最快开始

0. 先体验，不改仓库

1. 生成配置和 workflow

2. 体检接入状态

3. 提交并打开 PR

4. 看报告或生成补证请求

报告怎么看

它会检查什么

本地 CLI

配置示例

准确性边界

文档

下一步

开发

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 51

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages