feat(pr): add review shortcuts

2026-05-21 17:20:15 +08:00 · 2026-05-21 17:20:15 +08:00 · fbea42ecce
parent fde322669a
commit fbea42ecce
8 changed files with 361 additions and 4 deletions
--- a/README.md
+++ b/README.md
@ -188,6 +188,13 @@ gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42

 # View changed files
 gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
+
+# List PR reviews
+gitlink-cli pr +reviews --owner Gitlink --repo forgeplus -i 42
+
+# Approve a PR after previewing the request
+gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM" --dry-run
+gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM"
 ```

 ### Branch Management
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@ -200,6 +200,13 @@ gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42

 # 查看 PR 变更文件
 gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
+
+# 查看 PR 审查记录
+gitlink-cli pr +reviews --owner Gitlink --repo forgeplus -i 42
+
+# 预览并通过 PR
+gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM" --dry-run
+gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM"
 ```

 ### 发布管理
--- a/shortcuts/pr/pr.go
+++ b/shortcuts/pr/pr.go
@ -167,6 +167,87 @@ func Shortcuts() []*common.Shortcut {
 				return ctx.Output(env)
 			},
 		},
+		{
+			Name:        "reviews",
+			Description: "List pull request reviews",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+				{Name: "status", Short: "s", Usage: "Filter review status: common, approved, rejected"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id")
+				if err != nil {
+					return err
+				}
+				q := url.Values{}
+				if status := ctx.Arg("status"); status != "" {
+					if err := validatePRReviewStatus(status); err != nil {
+						return err
+					}
+					q.Set("status", status)
+				}
+				env, err := ctx.CallAPIWithQuery("GET", prReviewsPath(ctx, id), q)
+				if err != nil {
+					return err
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "review",
+			Description: "Create a pull request review",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "PR number", Required: true},
+				{Name: "status", Short: "s", Usage: "Review status: common, approved, rejected", Default: "common"},
+				{Name: "content", Short: "c", Usage: "Review content", Required: true},
+				{Name: "commit", Short: "m", Usage: "Commit SHA to attach the review to"},
+				{Name: "dry-run", Usage: "Preview the review request without creating it", Bool: true, Default: "false"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				if err := ctx.ResolveOwnerRepo(); err != nil {
+					return err
+				}
+				id, err := ctx.RequireArg("id")
+				if err != nil {
+					return err
+				}
+				content, err := ctx.RequireArg("content")
+				if err != nil {
+					return err
+				}
+				status := ctx.Arg("status")
+				if status == "" {
+					status = "common"
+				}
+				if err := validatePRReviewStatus(status); err != nil {
+					return err
+				}
+				payload := map[string]interface{}{
+					"content": content,
+					"status":  status,
+				}
+				if commit := ctx.Arg("commit"); commit != "" {
+					payload["commit_id"] = commit
+				}
+				if ctx.Arg("dry-run") == "true" {
+					return ctx.OutputData(map[string]interface{}{
+						"repository":   fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
+						"pull_request": id,
+						"dry_run":      true,
+						"action":       "create_review",
+						"payload":      payload,
+					})
+				}
+				env, err := ctx.CallAPI("POST", prReviewsPath(ctx, id), payload)
+				if err != nil {
+					return err
+				}
+				return ctx.Output(env)
+			},
+		},
 		{
 			Name:        "comment",
 			Description: "Add a comment to a pull request",
@ -203,6 +284,19 @@ func Shortcuts() []*common.Shortcut {
 	}
 }

+func prReviewsPath(ctx *common.RuntimeContext, id string) string {
+	return fmt.Sprintf("/v1/%s/%s/pulls/%s/reviews", ctx.Owner, ctx.Repo, id)
+}
+
+func validatePRReviewStatus(status string) error {
+	switch status {
+	case "common", "approved", "rejected":
+		return nil
+	default:
+		return fmt.Errorf("invalid --status value %q: use common, approved, or rejected", status)
+	}
+}
+
 func extractIssueID(env *output.Envelope) (int64, error) {
 	data, ok := env.Data.(map[string]interface{})
 	if !ok {
--- a/shortcuts/pr/pr_test.go
+++ b/shortcuts/pr/pr_test.go
@ -91,6 +91,105 @@ func TestPRCommentFailsWhenIssueFieldMissing(t *testing.T) {
 	}
 }

+func TestPRReviewsUsesV1EndpointWithStatusFilter(t *testing.T) {
+	var calledPath string
+	var status string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "GET" || r.URL.Path != "/v1/owner/repo/pulls/13/reviews.json" {
+			t.Fatalf("unexpected request: %s %s?%s", r.Method, r.URL.Path, r.URL.RawQuery)
+		}
+		calledPath = r.URL.Path
+		status = r.URL.Query().Get("status")
+		writeJSON(t, w, map[string]interface{}{
+			"total_count": float64(1),
+			"reviews": []map[string]interface{}{
+				{
+					"id":      float64(100),
+					"content": "LGTM",
+					"status":  "approved",
+				},
+			},
+		})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "reviews", map[string]string{
+		"id":     "13",
+		"status": "approved",
+	})
+	if err != nil {
+		t.Fatalf("reviews shortcut failed: %v", err)
+	}
+	assertEqual(t, calledPath, "/v1/owner/repo/pulls/13/reviews.json")
+	assertEqual(t, status, "approved")
+}
+
+func TestPRReviewPostsReviewPayload(t *testing.T) {
+	var reviewPayload map[string]interface{}
+	var reviewPath string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "POST" || r.URL.Path != "/v1/owner/repo/pulls/13/reviews.json" {
+			t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
+		}
+		reviewPath = r.URL.Path
+		reviewPayload = decodeJSON(t, r)
+		writeJSON(t, w, map[string]interface{}{
+			"id":        float64(101),
+			"content":   "Looks good",
+			"status":    "approved",
+			"commit_id": "abc123",
+		})
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "review", map[string]string{
+		"id":      "13",
+		"status":  "approved",
+		"content": "Looks good",
+		"commit":  "abc123",
+	})
+	if err != nil {
+		t.Fatalf("review shortcut failed: %v", err)
+	}
+	assertEqual(t, reviewPath, "/v1/owner/repo/pulls/13/reviews.json")
+	assertEqual(t, reviewPayload["content"], "Looks good")
+	assertEqual(t, reviewPayload["status"], "approved")
+	assertEqual(t, reviewPayload["commit_id"], "abc123")
+}
+
+func TestPRReviewDryRunDoesNotCallAPI(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("server should not be called during dry-run: %s %s", r.Method, r.URL.Path)
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "review", map[string]string{
+		"id":      "13",
+		"status":  "rejected",
+		"content": "Please fix the failing tests",
+		"dry-run": "true",
+	})
+	if err != nil {
+		t.Fatalf("review dry-run failed: %v", err)
+	}
+}
+
+func TestPRReviewRejectsInvalidStatus(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Fatalf("server should not be called for invalid status: %s %s", r.Method, r.URL.Path)
+	}))
+	defer server.Close()
+
+	err := runPRShortcut(t, server, "review", map[string]string{
+		"id":      "13",
+		"status":  "approve",
+		"content": "LGTM",
+	})
+	if err == nil {
+		t.Fatal("expected error for invalid review status, got nil")
+	}
+}
+
 func runPRShortcut(t *testing.T, server *httptest.Server, name string, args map[string]string) error {
 	t.Helper()
 	shortcut := findPRShortcut(t, name)
--- a/skills/README.md
+++ b/skills/README.md
@ -123,7 +123,7 @@ skills/
 | **gitlink-shared** | 认证、全局参数、API 参考、安全规则、分支约定 | `auth login`, `auth status` |
 | **gitlink-repo** | 仓库管理 | `repo +list`, `repo +create`, `repo +info`, `repo +fork` |
 | **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +view`, `issue +close`, `issue +batch-close` |
-| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +review` |
+| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +reviews`, `pr +review` |
 | **gitlink-branch** | 分支管理 | `branch +list`, `branch +create`, `branch +delete`, `branch +protect` |
 | **gitlink-release** | 版本发布 | `release +list`, `release +create`, `release +view` |

--- a/skills/gitlink-pr/SKILL.md
+++ b/skills/gitlink-pr/SKILL.md
@ -1,7 +1,7 @@
 ---
 name: gitlink-pr
 version: 1.0.0
-description: "Pull Request 管理：创建、查看、合并、关闭 PR，查看变更文件和 Diff。当用户需要操作 GitLink PR 时触发。"
+description: "Pull Request 管理：创建、查看、合并、关闭 PR，查看变更文件、Diff 和审查记录。当用户需要操作 GitLink PR 时触发。"
 metadata:
  requires:
    bins: ["gitlink-cli"]
@ -25,7 +25,9 @@ metadata:
 | `pr +merge` | 合并 PR | 是 |
 | `pr +close` | 关闭 PR | 是 |
 | `pr +files` | 变更文件列表 | 否 |
-| `pr +diff` | 查看提交列表 | 否 |
+| `pr +diff` | 查看变更文件和 diff 内容 | 否 |
+| `pr +reviews` | 查看 PR 审查记录 | 否（公开项目） |
+| `pr +review` | 创建 PR 审查（comment/approve/reject） | 是 |
 | `pr +comment` | 给 PR 添加评论 | 是 |

 ## 使用示例
@ -50,6 +52,15 @@ gitlink-cli pr +close --id 3
 # 查看变更文件（含 diff 内容）
 gitlink-cli pr +files --id 3

+# 查看 PR 审查记录
+gitlink-cli pr +reviews --id 3
+gitlink-cli pr +reviews --id 3 --status approved
+
+# 创建 PR 审查（先 dry-run，再真实提交）
+gitlink-cli pr +review --id 3 --status approved --content "LGTM" --dry-run
+gitlink-cli pr +review --id 3 --status approved --content "LGTM"
+gitlink-cli pr +review --id 3 --status rejected --content "测试未通过，请修复后再合并"
+
 # 给 PR 添加评论
 gitlink-cli pr +comment --id 3 --body "LGTM, ready to merge"
 ```
@ -115,8 +126,11 @@ gitlink-cli api PUT /:owner/:repo/update_file --body '{"filepath":"file.md","con
 # 检查是否可合并
 gitlink-cli api POST /:owner/:repo/pulls/check_can_merge --body '{"head":"dev","base":"main"}'

+# 查看 Review 列表
+gitlink-cli api GET /v1/:owner/:repo/pulls/:id/reviews
+
 # 创建 Review
-gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{"body":"LGTM","event":"APPROVE"}'
+gitlink-cli api POST /v1/:owner/:repo/pulls/:id/reviews --body '{"content":"LGTM","status":"approved"}'

 # 获取可用分支
 gitlink-cli api GET /:owner/:repo/pulls/get_branches
@ -131,6 +145,8 @@ gitlink-cli api GET /:owner/:repo/pulls/get_branches
 - PR 查看/合并/关闭需要使用 `pull_request_number`（即网页 URL `/pulls/N` 中的序号，从 `pr +list` 返回）
 - `pr +merge` 默认使用 merge 方式，可通过 `--method` 指定 rebase 或 squash
 - `pr +diff` 实际调用 `/pulls/:id/files` 端点，返回变更文件列表和 diff 内容
+- `pr +reviews` / `pr +review` 使用 v1 API，`--id` 为网页 URL `/pulls/N` 中的 PR 序号
+- `pr +review --status` 支持 `common`、`approved`、`rejected`；写入前建议先使用 `--dry-run` 预览
 - `pr +list` 的 `--state` 参数（open/merged/closed）仅影响统计计数，API 返回的列表可能包含所有状态的 PR
 - PR 状态值：`pull_request_status` 0=open, 1=merged, 2=closed
 - 关联已有 Issue 时，把 Issue 编号或 URL 写入 PR `--body`，或使用 `issue +comment` 留痕；不要用 Raw API 对 Issue 做不完整更新，否则可能清空 Issue 描述
--- a/skills/gitlink-pr/references/gitlink-pr-review.md
+++ b/skills/gitlink-pr/references/gitlink-pr-review.md
@ -0,0 +1,73 @@
+# pr +review
+
+> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+创建 Pull Request 审查，可提交普通审查意见、通过（approve）或拒绝/请求修改（reject）。写入前建议先使用 `--dry-run` 预览请求内容。
+
+## 命令
+
+```bash
+# 预览普通审查评论
+gitlink-cli pr +review --id 3 --status common --content "整体看起来可以" --dry-run
+
+# 提交普通审查评论
+gitlink-cli pr +review --id 3 --status common --content "整体看起来可以"
+
+# 通过 PR
+gitlink-cli pr +review --id 3 --status approved --content "LGTM"
+
+# 请求修改 / 拒绝通过
+gitlink-cli pr +review --id 3 --status rejected --content "测试未通过，请修复后再合并"
+
+# 绑定到指定 commit
+gitlink-cli pr +review --id 3 --status approved --content "LGTM" --commit <commit_sha>
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--id` / `-i` | 是 | PR 序号（网页 URL `/pulls/N` 中的 `N`，即 `pull_request_number`） |
+| `--status` / `-s` | 否 | 审查状态：`common`、`approved`、`rejected`，默认 `common` |
+| `--content` / `-c` | 是 | 审查内容 |
+| `--commit` / `-m` | 否 | 绑定审查的 commit SHA，对应 API 字段 `commit_id` |
+| `--dry-run` | 否 | 只预览请求，不创建审查 |
+
+## API
+
+```
+POST /v1/{owner}/{repo}/pulls/{number}/reviews
+```
+
+请求体：
+
+```json
+{
+  "content": "LGTM",
+  "status": "approved",
+  "commit_id": "<commit_sha>"
+}
+```
+
+其中 `commit_id` 仅在传入 `--commit` 时发送。
+
+## 安全流程
+
+对写操作建议遵循：
+
+1. 先用 `pr +view` / `pr +files` / `pr +reviews` 获取上下文。
+2. 准备审查内容和状态。
+3. 执行 `pr +review --dry-run` 预览。
+4. 用户确认后去掉 `--dry-run` 执行真实写入。
+
+## 注意事项
+
+- `--status approved` 表示通过 PR；`--status rejected` 表示拒绝/请求修改；`--status common` 表示普通审查意见。
+- `--content` 必填，避免产生没有上下文的 approve/reject。
+- `--dry-run` 不会请求 GitLink API，适合 Agent 在执行写操作前展示计划。
+
+## References
+
+- [gitlink-shared SKILL.md](../../gitlink-shared/SKILL.md) -- 认证与全局参数
+- [gitlink-pr SKILL.md](../SKILL.md) -- PR 操作总览
+- [pr +reviews](gitlink-pr-reviews.md) -- 查看 PR 审查记录
--- a/skills/gitlink-pr/references/gitlink-pr-reviews.md
+++ b/skills/gitlink-pr/references/gitlink-pr-reviews.md
@ -0,0 +1,61 @@
+# pr +reviews
+
+> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查看 Pull Request 的审查记录，可按审查状态过滤。适合在合并前检查是否已有 approve、reject 或普通审查意见。
+
+## 命令
+
+```bash
+# 查看 PR 审查记录
+gitlink-cli pr +reviews --id 3
+
+# 简写
+gitlink-cli pr +reviews -i 3
+
+# 按状态筛选
+gitlink-cli pr +reviews -i 3 --status approved
+gitlink-cli pr +reviews -i 3 --status rejected
+gitlink-cli pr +reviews -i 3 --status common
+
+# 指定仓库并输出 JSON
+gitlink-cli pr +reviews --owner Gitlink --repo forgeplus -i 3 --format json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--id` / `-i` | 是 | PR 序号（网页 URL `/pulls/N` 中的 `N`，即 `pull_request_number`） |
+| `--status` / `-s` | 否 | 审查状态：`common`、`approved`、`rejected` |
+
+## API
+
+```
+GET /v1/{owner}/{repo}/pulls/{number}/reviews
+```
+
+当传入 `--status` 时，会附加查询参数：
+
+```
+status=<common|approved|rejected>
+```
+
+## 典型流程
+
+1. `pr +view --id <number>` 确认 PR 状态。
+2. `pr +files --id <number>` 查看变更文件。
+3. `pr +reviews --id <number>` 查看现有审查记录。
+4. 根据审查结果决定是否使用 `pr +review` 添加普通评论、approve 或 reject。
+
+## 注意事项
+
+- `--id` 不是数据库 ID，而是网页 URL `/pulls/N` 中的 PR 序号。
+- 这是只读查询命令，不会修改 PR。
+- `approved` 表示通过，`rejected` 表示拒绝/请求修改，`common` 表示普通审查评论。
+
+## References
+
+- [gitlink-shared SKILL.md](../../gitlink-shared/SKILL.md) -- 认证与全局参数
+- [gitlink-pr SKILL.md](../SKILL.md) -- PR 操作总览
+- [pr +review](gitlink-pr-review.md) -- 创建 PR 审查