convez.ai
AgenteDevOps & InfraestruturaIntermediário
yanqr213

Agent PR Brief

yanqr213/agent-pr-brief

Gera PR briefs completos com risco, testes e evidências para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Gerador offline de resumos de PR para entregas de agentes IA com listas de risco, evidência de testes, matrizes por arquivo e suporte a Markdown/JSON/SARIF. Automatiza a criação de PR descriptions de alta qualidade a partir de diffs, logs de commit, outputs de testes e notas do agente, facilitando a revisão com checklist, CI gates e múltiplos formatos de saída.

Instalação

$npx convez-ai yanqr213/agent-pr-brief

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar documentação de PRs gerados por agentes de código (Codex, Claude Code)
  • Gerar matrizes de evidência de testes por arquivo modificado
  • Criar CI gates que bloqueiam PRs sem evidência suficiente
  • Produzir relatórios SARIF para Code Scanning com achados mapeados

Veredito

Ferramenta especializada e bem-arquitetada para democratizar qualidade em PRs gerados por IA. Cobre um nicho real (agentes IA + CI/CD) com múltiplos formatos e CI gates robustos. Recomendado para times com fluxos intensivos de agentes de código.

README

A tradução para o português deste README ainda está na fila.

agent-pr-brief

agent-pr-brief 是一个离线 Python CLI,用来把 AI coding agent 的交付证据整理成 PR 描述和 reviewer briefing。它读取 git diff、commit log、测试输出、agent notes 和风险配置,生成中英可读的 PR 摘要、风险清单、逐文件证据矩阵、测试证据表、review checklist、follow-up items,并支持 Markdown、JSON、GitHub PR 正文、GitHub 评论、可勾选清单、SARIF 输出与 CI gate。

适合 Codex、Claude Code 或其他 AI 编程代理在完成任务后自动产出高质量 PR 文案,让 reviewer 更快看到“改了什么、风险在哪里、证据是否足够”。

安装

本地开发安装:

python -m pip install -e .

运行 CLI:

agent-pr-brief --help

Python 版本要求:3.9+。运行时优先使用标准库,无强制第三方依赖。

快速使用

初始化配置:

agent-pr-brief init-config --output .agent-pr-brief.json

从当前 git 工作区生成 Markdown PR brief:

agent-pr-brief draft --config .agent-pr-brief.json --tests examples/pytest-output.txt --output build/pr-brief.md

直接从示例 diff、测试输出和 agent notes 生成可审阅简报:

agent-pr-brief draft \
  --config examples/sample-config.json \
  --diff-file examples/sample.diff \
  --tests examples/pytest-output.txt \
  --notes examples/agent-notes.md \
  --output build/pr-brief.md

生成 JSON:

agent-pr-brief draft --format json --tests examples/junit.xml --output build/pr-brief.json

生成可直接粘贴到 GitHub PR description 的精简正文:

agent-pr-brief draft \
  --config examples/sample-config.json \
  --diff-file examples/sample.diff \
  --tests examples/pytest-output.txt \
  --notes examples/agent-notes.md \
  --format pr-body \
  --output build/pr-body.md

生成适合自动发布到 GitHub PR conversation 或写入 Actions step summary 的紧凑评论:

agent-pr-brief draft \
  --config examples/sample-config.json \
  --diff-file examples/sample.diff \
  --tests examples/pytest-output.txt \
  --notes examples/agent-notes.md \
  --format gh-comment \
  --output build/gh-comment.md

gh pr comment 123 --body-file build/gh-comment.md
cat build/gh-comment.md >> "$GITHUB_STEP_SUMMARY"

生成 reviewer 可勾选的 PR 准备度清单:

agent-pr-brief draft \
  --config examples/sample-config.json \
  --diff-file examples/sample.diff \
  --tests examples/pytest-output.txt \
  --notes examples/agent-notes.md \
  --format checklist \
  --output build/pr-readiness.md

生成 GitHub Code Scanning 可上传的 SARIF gate 报告:

agent-pr-brief draft \
  --config examples/sample-config.json \
  --diff-file examples/sample.diff \
  --tests examples/pytest-output.txt \
  --format sarif \
  --output build/pr-brief.sarif

SARIF 会把 no-tests、missing-required-tests、risk_missing_evidence、test-failures 等交付证据问题映射成 Code Scanning result;能定位到文件的 finding 会指向对应变更路径。

只解析 diff:

agent-pr-brief from-diff examples/sample.diff --format markdown

只解析测试输出:

agent-pr-brief from-tests examples/pytest-output.txt --test-parser pytest --format json

CI gate:

agent-pr-brief check --config .agent-pr-brief.json --tests examples/pytest-output.txt --check warning

--check error 只在错误级别 gate 失败时返回非零;--check warning 会在 warning 或 error 时返回非零;--check off 永不因 gate 返回非零。

子命令

  • draft:读取 diff、测试证据、agent notes、commit log,生成完整 PR brief。
  • check:执行缺失证据、失败测试、风险路径无测试等 gate。
  • from-diff:解析 git diff、numstat 或 name-status 输入,输出分类后的文件清单。
  • from-tests:解析 pytest/plain/JUnit 测试输出。
  • init-config:生成 JSON 风险配置模板。

所有写文件命令都支持 --output,并会自动创建父目录。

配置

配置文件是 JSON,字段如下:

{
  "risk_paths": {
    "agent_pr_brief/**": "CLI/reporting logic changed; verify generated Markdown and JSON."
  },
  "required_tests_by_path": {
    "agent_pr_brief/**": ["unit", "cli-smoke"]
  },
  "labels": {
    "tests": ["tests/**"],
    "ci": [".github/workflows/**"]
  },
  "review_checklist_items": [
    "Does the summary match the actual diff?"
  ],
  "template_language": "bilingual"
}

说明:

  • risk_paths:路径 glob 到风险提示的映射。
  • required_tests_by_path:路径 glob 到所需证据名称的映射。
  • labels:输出摘要中用于聚类的标签。
  • review_checklist_items:固定 review 检查项。
  • template_language:zh、en 或 bilingual。

输出结构

JSON 输出包含:

  • metadata:生成时间、工具名、模板语言。
  • change_summary:文件数、增删行、分类、标签、逐文件信息。
  • commits:可选 commit log。
  • agent_notes:可选 agent 备注。
  • risk_list:命中的风险路径。
  • evidence_matrix:逐文件证据矩阵,包含 path、category、risk、required/covered/missing evidence 和 status。
  • test_evidence:解析后的测试证据。
  • review_checklist:review checklist。
  • follow_up_items:缺失证据或失败测试引出的后续事项。
  • checks:CI gate 结果。
  • readiness:仅完整 draft JSON 输出中包含,给出 READY/REVIEW/BLOCK 决策、0-100 分数、证据清单和 agent handoff prompt。
  • template_snippets:中英模板片段。

Markdown 输出使用同一结构,面向 PR 描述和 reviewer briefing。

--format pr-body 输出更短,更适合直接作为 GitHub PR 正文,包含 Summary、Validation、Risk Notes、Reviewer Checklist、Follow-ups、Gate 和可选 Agent Notes。

--format gh-comment 输出更紧凑,适合 gh pr comment --body-file 或 $GITHUB_STEP_SUMMARY:顶部展示 READY/REVIEW/BLOCK、范围、验证和 gate findings,证据矩阵与 reviewer checklist 放进可展开的 <details> 中。

--format checklist 输出更偏执行:包含 READY/REVIEW/BLOCK 决策、准备度分数、reviewer 必查项、证据清单、风险文件、follow-up 和可直接交给下一个 agent 的 handoff prompt。

--format sarif 输出 SARIF 2.1.0,适合上传 GitHub Code Scanning,把缺测试、风险路径缺验证、失败测试等 agent 交付证据问题显示为可审计 alert。

证据矩阵示例:

| File | Category | Risk | Required Evidence | Covered Evidence | Missing Evidence | Status |
| --- | --- | --- | --- | --- | --- | --- |
| `agent_pr_brief/brief.py` | python | yes | unit, cli-smoke | unit, cli-smoke | - | covered |

CI 示例

项目自带 GitHub Actions workflow,会运行测试和 CLI 烟测。你也可以在自己的 CI 中加入:

python -m pip install -e .
python -m unittest discover -s tests
agent-pr-brief check --config .agent-pr-brief.json --tests test-output.txt --check warning --output build/check.json --format json
agent-pr-brief draft --config .agent-pr-brief.json --tests test-output.txt --format pr-body --output build/pr-body.md
agent-pr-brief draft --config .agent-pr-brief.json --tests test-output.txt --format gh-comment --output build/gh-comment.md
agent-pr-brief draft --config .agent-pr-brief.json --tests test-output.txt --format checklist --output build/pr-readiness.md
agent-pr-brief draft --config .agent-pr-brief.json --tests test-output.txt --format sarif --output build/pr-brief.sarif

上传 SARIF 到 GitHub Code Scanning:

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: "3.12"
  - run: python -m pip install agent-pr-brief
  - run: |
      agent-pr-brief draft \
        --config .agent-pr-brief.json \
        --tests test-output.txt \
        --format sarif \
        --output build/pr-brief.sarif \
        --check off
  - uses: github/codeql-action/upload-sarif@v3
    if: always()
    with:
      sarif_file: build/pr-brief.sarif

示例

examples/ 目录包含:

  • sample.diff:可直接用于 from-diff。
  • pytest-output.txt:pytest 输出示例。
  • junit.xml:JUnit XML 示例。
  • agent-notes.md:agent notes 示例。
  • sample-config.json:可运行配置示例。

示例中如需域名,只使用 .test 域。

适用场景

  • AI agent 完成任务后自动生成 PR 描述。
  • AI agent 在 CI 里自动把交付证据发布成 PR 评论或 Actions summary。
  • reviewer 想快速看到风险路径和测试证据。
  • reviewer 想拿到可勾选的 PR 准备度清单,而不是只读长报告。
  • 团队希望用 CI gate 防止缺失测试证据的 agent 交付进入 review。
  • 需要 JSON 输出接入内部自动化、机器人或审计流水线。

限制

  • 工具只基于本地输入做离线启发式分析,不理解业务真实语义。
  • diff 分类和风险提示依赖配置与路径规则,不能替代人工 review。
  • 测试解析覆盖 pytest/plain/JUnit 常见输出,复杂自定义 runner 建议先转换成 JUnit 或 plain 摘要。
  • gate 表示证据完整性和显式失败信号,不代表代码一定正确。

English

agent-pr-brief is an offline Python CLI that turns AI coding agent delivery evidence into pull request descriptions and reviewer briefings. It reads git diff, commit log, test output, agent notes, and a JSON risk configuration, then emits Markdown, JSON, concise pr-body Markdown, compact gh-comment Markdown for GitHub PR conversations or Actions summaries, executable checklist Markdown, or SARIF for GitHub Code Scanning with a change summary, risk list, per-file evidence matrix, test evidence table, review checklist, follow-up items, bilingual snippets, and CI-friendly checks.

Install locally with python -m pip install -e ., initialize config with agent-pr-brief init-config, generate a brief with agent-pr-brief draft, and enforce gates with agent-pr-brief check --check warning.

The tool is designed for local automation after agents such as Codex or Claude Code finish a coding task. It does not publish anything remotely and does not require network access at runtime.

The evidence matrix is the main reviewer shortcut: every changed file gets a row showing configured risk, required evidence, covered evidence, missing evidence, and status. This makes it easy to spot agent deliveries that changed risky files without enough test proof.

Use --format pr-body when you want a shorter GitHub-ready PR description instead of the full reviewer briefing. Use --format gh-comment when CI or an agent should post a compact PR comment with validation and gate findings up front plus an expandable evidence matrix. Use --format checklist when the reviewer or the next agent needs a READY/REVIEW/BLOCK decision, a readiness score, unchecked evidence items, risk files, and a handoff prompt.

Use --format sarif when you want missing tests, missing required evidence, risk paths without validation, and failed test evidence to appear in GitHub Code Scanning.

Ver o original no GitHub

Bom para

Relacionados