# PR-Agent 使用说明

本仓库通过 GitHub Actions 运行开源 PR-Agent，用于自动维护 PR 摘要、发布行内代码审查建议，并在每轮审查后发布一条简短的 Code Review 总结评论。

## 触发方式

`.github/workflows/pr-agent.yml` 监听：

- `pull_request_target`：PR 打开、重新打开、标记 ready、请求 review、推送新 commit 时自动运行。
- `issue_comment`：允许身份在 PR 评论里写允许的命令时手动运行。

PR 事件会自动执行受控审查，包含同仓 PR 和 fork PR。允许身份也可以在 PR 评论中使用允许的命令触发受控审查。
允许身份包括 `OWNER`、`MEMBER`、`COLLABORATOR`、`CONTRIBUTOR` 和 `FIRST_TIME_CONTRIBUTOR`。

## Workflow 权限

workflow 设置了最小可用权限：

- `contents: read`：读取仓库内容和 PR diff。
- `pull-requests: write`：更新 PR 描述、发布 PR Review 或修改 PR 相关元数据。
- `issues: write`：PR 评论在 GitHub API 中属于 issue comments，手动命令和总结评论需要该权限。

没有开启 `contents: write`。当前配置不让 PR-Agent 往仓库推代码或提交 changelog，因此不需要内容写权限。

## 自动行为

PR 事件默认自动执行：

- `/describe`：更新 PR Body 中的 `PR-Agent 摘要` / `PR-Agent Summary` 标记区域，保留用户原始描述。
- `/improve`：发布 GitHub 行内代码审查建议，不发布 PR-Agent 建议表格。

workflow 会在 `/improve` 后发布一条普通 PR 评论：

- 评论标题为 `## Code Review`。
- 如果本轮有新增行内建议，会基于这些建议生成自然语言总结。
- 如果本轮没有新增行内建议，直接发布无更多反馈的简短总结。
- 下一次运行前会删除上一条 PR-Agent Code Review 总结评论，避免评论堆叠，同时保留新的通知事件。

## 常用评论命令

以下身份可在 PR 评论中使用：

- `OWNER`：仓库所有者。
- `MEMBER`：组织仓库中的组织成员。
- `COLLABORATOR`：仓库协作者。
- `CONTRIBUTOR`：曾经向仓库提交并合入过代码的贡献者。
- `FIRST_TIME_CONTRIBUTOR`：首次向仓库贡献 PR 的用户。

```text
/describe
/improve
/ask 这次改动有没有遗漏权限校验？
```

评论触发依赖 `issue_comment` 事件。普通 issue 评论、Bot 评论、非允许身份评论、以及不以允许命令开头的评论都会跳过。

## 输出约定

PR-Agent 配置集中在 `.github/workflows/pr-agent.yml` 中维护。公开说明只描述用户可见行为：

- 根据 PR 标题和用户原始描述自动选择中文或英文；无法识别时默认中文。
- 保留用户原始 PR 描述，只更新 PR Body 中的 PR-Agent 标记区域。
- 不使用 PR-Agent 的 Reviewer Guide 输出。
- 不输出 PR Type、额外标签、图表或 describe 评论。
- 只发布值得维护者处理的问题型行内建议。
- 行内建议可使用 GitHub suggestion 形式，便于直接采纳。
- 没有建议时不发布 PR-Agent 建议表格，只保留简短的 Code Review 总结评论。

行内建议可使用风险前缀：

- `🔴 **High Risk**:`：高风险问题。
- `🟡 **Medium Risk**:`：中风险问题。
- `🔵 **Low Risk**:`：低风险问题。

可按需再启用的工具配置：

- `[pr_update_changelog]`：配合 `/update_changelog` 生成 changelog 建议。
- `[pr_add_docs]`：配合 `/add_docs` 生成文档建议。
- `[pr_test]`：配合 `/test` 生成测试建议；它不会替代仓库自己的测试命令。
- `[pr_questions]`：配合 `/ask ...` 回答 PR 相关问题。

## 安全边界

PR-Agent 依赖的 Docker 镜像在 workflow 中固定版本号和 digest，不使用浮动的 `latest` 或仅依赖可变 tag。

当前使用 `pull_request_target` 支持 PR 自动审查，但 workflow 不 checkout 或执行 PR 分支代码，只运行固定 digest 的 PR-Agent 容器并通过 GitHub API 读取 PR diff。`issue_comment` 属于 base repo 事件，因此评论命令只允许指定身份触发。