ci(pr-agent): publish native code reviews (#6110)

docs/pr-agent.md

@@ -1,86 +1,50 @@
 # PR-Agent 使用说明
 
-本仓库通过 GitHub Actions 运行开源 PR-Agent，用于自动维护 PR 摘要、发布行内代码审查建议，并在每轮审查后发布一条简短的 Code Review 总结评论。
+本仓库通过 GitHub Actions 运行 PR-Agent，帮助贡献者维护 PR 摘要、获取代码审查结果和提出 PR 相关问题。
 
-## 触发方式
+## 自动执行
 
-`.github/workflows/pr-agent.yml` 监听：
+同仓分支和来自 fork 的 PR 都会自动执行 PR-Agent。
 
-- `pull_request_target`：PR 打开、重新打开、标记 ready、请求 review、推送新 commit 时自动运行。
-- `issue_comment`：允许身份在 PR 评论里写允许的命令时手动运行。
+PR 在以下场景会自动处理：
 
-PR 事件会自动执行受控审查，包含同仓 PR 和 fork PR。允许身份也可以在 PR 评论中使用允许的命令触发受控审查。
-允许身份包括 `OWNER`、`MEMBER`、`COLLABORATOR`、`CONTRIBUTOR` 和 `FIRST_TIME_CONTRIBUTOR`。
+- 打开或重新打开 PR。
+- 将草稿 PR 标记为可审查。
+- 请求审查。
+- 每次推送新的 commit。
 
-## Workflow 权限
+PR 带有 `skip pr-agent` 标签，或标题以 `[Auto]`、`Auto` 开头时，自动和手工路径都会跳过。
 
-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 的用户。
+在 PR 的普通讨论评论中使用以下命令：
 
 ```text
 /describe
-/improve
+/review
 /ask 这次改动有没有遗漏权限校验？
 ```
 
-评论触发依赖 `issue_comment` 事件。普通 issue 评论、Bot 评论、非允许身份评论、以及不以允许命令开头的评论都会跳过。
+- `/describe`：更新 PR Body 内按语言显示的 `PR-Agent 摘要` 或 `PR-Agent Summary`，并保留贡献者原有的 PR 描述。
+- `/review`：发起一次代码审查。
+- `/ask ...`：就当前 PR 提问，回复会发布在普通 PR 评论中。
 
-## 输出约定
+手工命令仅允许以下 GitHub 身份关联的用户使用：`OWNER`、`MEMBER`、`COLLABORATOR`、`CONTRIBUTOR`、`FIRST_TIME_CONTRIBUTOR`。
 
-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 总结评论。
+## 审查结果
 
-行内建议可使用风险前缀：
+`/describe` 的结果位于 PR Body 中按语言显示的 `PR-Agent 摘要` 或 `PR-Agent Summary` 区域，用于概览本次变更。
 
-- `🔴 **High Risk**:`：高风险问题。
-- `🟡 **Medium Risk**:`：中风险问题。
-- `🔵 **Low Risk**:`：低风险问题。
+`/review` 和自动审查会通过原生 GitHub Review 发布，结果位于 Review 页签，标题固定为 `PR-Agent Code Review`。审查摘要包含可点击的 `文件:行号` 链接；可定位到本次变更的具体问题会在对应代码行以行内评论呈现，无法行内定位的问题仍通过摘要中的链接呈现。
 
-可按需再启用的工具配置：
+审查不会额外创建专用的摘要评论。未发现需要处理的问题时，Review 会显示：
 
-- `[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。
+workflow 使用固定 digest 的 PR-Agent 容器镜像，不使用浮动标签。自动审查通过 `pull_request_target` 在目标仓库上下文中读取 PR 信息，但不会 checkout 或执行 PR 分支代码。
 
-当前使用 `pull_request_target` 支持 PR 自动审查，但 workflow 不 checkout 或执行 PR 分支代码，只运行固定 digest 的 PR-Agent 容器并通过 GitHub API 读取 PR diff。`issue_comment` 属于 base repo 事件，因此评论命令只允许指定身份触发。
+权限保持最小化：只授予读取仓库内容所需的 `contents: read`，以及更新 PR Body、发布 Review 和回复 PR 评论所需的写权限；不会向仓库推送代码或创建提交。