Merge PR #391: feat(shortcut): 新增 notification 命令组（通知 list/read/read-all/wa

doc/changes/notification-shortcut.md

@@ -0,0 +1,17 @@
+# Notification shortcut
+
+新增 `notification` Shortcut 组，封装 GitLink 通知相关 OpenAPI：
+
+- `notification +list` — 列出通知（`--all` 含已读、`--participating` 仅参与的，支持分页）
+- `notification +read` — 标记单条通知为已读（`-i/--id`）
+- `notification +read-all` — 标记所有通知为已读
+- `notification +watch` — 关注 / 取消关注仓库通知（`-o/--owner`、`-r/--repo`，`--unwatch` 取消）
+
+实现要点：
+
+- `+list` 为 GET `/notifications`，带 `page`/`limit`/`all`/`participating` 查询参数。
+- `+read` 为 PUT `/notifications/{id}`；`+read-all` 为 PUT `/notifications`。
+- `+watch` 为 POST `/watchers/{owner}/{repo}.json`，`--unwatch` 时改用 DELETE。
+- 全部统一 `owner/repo` 自动解析与 `--format json|table|yaml` 输出。
+
+背景：通知管理此前只能在 Web 端手工进行，无法脚本化或被 Agent 调用。`notification` 组补齐命令行入口，便于 CI/Agent 做通知聚合、定期已读、仓库关注等自动化。含单元测试覆盖各命令的 HTTP 方法、路径与查询参数。

doc/commands/notification.md

@@ -0,0 +1,41 @@
+# notification — 通知管理
+
+## 概述
+
+`notification` 模块封装 GitLink 通知相关 OpenAPI：列出通知、标记已读、关注/取消关注仓库通知。
+
+## 命令列表
+
+### notification +list — 列出通知
+- **参数**：
+  - `-p, --page` 页码，默认 `1`
+  - `-l, --limit` 每页数量，默认 `20`
+- **示例**：
+  - `gitlink-cli notification +list`
+  - `gitlink-cli notification +list -l 50`
+
+### notification +read — 标记单条已读
+- **参数**：
+  - `-i, --id`（必填）通知 ID
+- **示例**：
+  - `gitlink-cli notification +read -i 12345`
+
+### notification +read-all — 全部标记已读
+- **参数**：无
+- **示例**：
+  - `gitlink-cli notification +read-all`
+
+### notification +watch — 关注/取消关注仓库通知
+- **参数**：
+  - `-o, --owner`（必填）仓库所有者
+  - `-r, --repo`（必填）仓库名称
+- **示例**：
+  - `gitlink-cli notification +watch -o Gitlink -r gitlink-cli`
+
+## 输出
+
+支持 `--format json|table|yaml`。
+
+## 备注
+
+该模块当前**尚无单元测试**（见 `开发日志.md` 待办），调用前建议用 `capability +check` 确认后端通知接口可用。

shortcuts/notification/notification.go

@@ -0,0 +1,97 @@
+package notification
+
+import (
+	"fmt"
+	"net/url"
+
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+func Shortcuts() []*common.Shortcut {
+	return []*common.Shortcut{
+		{
+			Name:        "list",
+			Description: "列出通知",
+			Flags: []common.Flag{
+				{Name: "all", Usage: "显示所有通知（含已读）", Bool: true, Default: "false"},
+				{Name: "participating", Usage: "仅显示参与的通知", Bool: true, Default: "false"},
+				{Name: "page", Short: "p", Usage: "页码", Default: "1"},
+				{Name: "limit", Short: "l", Usage: "每页数量", Default: "20"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				q := url.Values{}
+				q.Set("page", ctx.Arg("page"))
+				q.Set("limit", ctx.Arg("limit"))
+				if ctx.Arg("all") == "true" {
+					q.Set("all", "true")
+				}
+				if ctx.Arg("participating") == "true" {
+					q.Set("participating", "true")
+				}
+				env, err := ctx.CallAPIWithQuery("GET", "/notifications", q)
+				if err != nil {
+					return err
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "read",
+			Description: "标记单条通知为已读",
+			Flags: []common.Flag{
+				{Name: "id", Short: "i", Usage: "通知 ID", Required: true},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				id, err := ctx.RequireArg("id")
+				if err != nil {
+					return err
+				}
+				env, err := ctx.CallAPI("PUT", fmt.Sprintf("/notifications/%s", id), nil)
+				if err != nil {
+					return err
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "read-all",
+			Description: "标记所有通知为已读",
+			Run: func(ctx *common.RuntimeContext) error {
+				env, err := ctx.CallAPI("PUT", "/notifications", nil)
+				if err != nil {
+					return err
+				}
+				return ctx.Output(env)
+			},
+		},
+		{
+			Name:        "watch",
+			Description: "关注或取消关注仓库的通知",
+			Flags: []common.Flag{
+				{Name: "owner", Short: "o", Usage: "仓库所有者", Required: true},
+				{Name: "repo", Short: "r", Usage: "仓库名称", Required: true},
+				{Name: "unwatch", Usage: "取消关注（默认为关注）", Bool: true, Default: "false"},
+			},
+			Run: func(ctx *common.RuntimeContext) error {
+				owner, err := ctx.RequireArg("owner")
+				if err != nil {
+					return err
+				}
+				repo, err := ctx.RequireArg("repo")
+				if err != nil {
+					return err
+				}
+				path := fmt.Sprintf("/watchers/%s/%s.json", owner, repo)
+				method := "POST"
+				if ctx.Arg("unwatch") == "true" {
+					method = "DELETE"
+				}
+				env, err := ctx.CallAPI(method, path, nil)
+				if err != nil {
+					return err
+				}
+				return ctx.Output(env)
+			},
+		},
+	}
+}

shortcuts/notification/notification_test.go

@@ -0,0 +1,189 @@
+package notification
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gitlink-org/gitlink-cli/internal/client"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/common"
+)
+
+func runNotifShortcut(t *testing.T, server *httptest.Server, name string, args map[string]string) error {
+	t.Helper()
+	s := findNotifShortcut(t, name)
+	ctx := &common.RuntimeContext{
+		Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL},
+		Owner:  "owner",
+		Repo:   "repo",
+		Format: "json",
+		Args:   args,
+	}
+	return s.Run(ctx)
+}
+
+func findNotifShortcut(t *testing.T, name string) *common.Shortcut {
+	t.Helper()
+	for _, s := range Shortcuts() {
+		if s.Name == name {
+			return s
+		}
+	}
+	t.Fatalf("shortcut %q not found", name)
+	return nil
+}
+
+func writeNotifJSON(w http.ResponseWriter, v interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(v)
+}
+
+// --- list ---
+
+func TestNotifListBasic(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "GET" {
+			t.Fatalf("expected GET, got %s", r.Method)
+		}
+		if r.URL.Path != "/notifications.json" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		if got := r.URL.Query().Get("page"); got != "1" {
+			t.Fatalf("got page %q, want %q", got, "1")
+		}
+		if got := r.URL.Query().Get("limit"); got != "20" {
+			t.Fatalf("got limit %q, want %q", got, "20")
+		}
+		writeNotifJSON(w, map[string]interface{}{
+			"total_count": float64(1),
+			"notifications": []interface{}{
+				map[string]interface{}{"id": float64(1), "unread": true},
+			},
+		})
+	}))
+	defer server.Close()
+
+	err := runNotifShortcut(t, server, "list", map[string]string{
+		"page": "1", "limit": "20", "all": "false", "participating": "false",
+	})
+	if err != nil {
+		t.Fatalf("list failed: %v", err)
+	}
+}
+
+func TestNotifListWithAll(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.URL.Query().Get("all"); got != "true" {
+			t.Fatalf("expected all=true, got %q", got)
+		}
+		writeNotifJSON(w, map[string]interface{}{"total_count": float64(0), "notifications": []interface{}{}})
+	}))
+	defer server.Close()
+
+	err := runNotifShortcut(t, server, "list", map[string]string{
+		"page": "1", "limit": "20", "all": "true", "participating": "false",
+	})
+	if err != nil {
+		t.Fatalf("list with all failed: %v", err)
+	}
+}
+
+func TestNotifListWithParticipating(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.URL.Query().Get("participating"); got != "true" {
+			t.Fatalf("expected participating=true, got %q", got)
+		}
+		writeNotifJSON(w, map[string]interface{}{"total_count": float64(0), "notifications": []interface{}{}})
+	}))
+	defer server.Close()
+
+	err := runNotifShortcut(t, server, "list", map[string]string{
+		"page": "1", "limit": "20", "all": "false", "participating": "true",
+	})
+	if err != nil {
+		t.Fatalf("list with participating failed: %v", err)
+	}
+}
+
+// --- read ---
+
+func TestNotifRead(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "PUT" {
+			t.Fatalf("expected PUT, got %s", r.Method)
+		}
+		if r.URL.Path != "/notifications/42.json" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		writeNotifJSON(w, map[string]interface{}{"status": 0, "message": "success"})
+	}))
+	defer server.Close()
+
+	err := runNotifShortcut(t, server, "read", map[string]string{"id": "42"})
+	if err != nil {
+		t.Fatalf("read failed: %v", err)
+	}
+}
+
+// --- read-all ---
+
+func TestNotifReadAll(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "PUT" {
+			t.Fatalf("expected PUT, got %s", r.Method)
+		}
+		if r.URL.Path != "/notifications.json" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		writeNotifJSON(w, map[string]interface{}{"status": 0, "message": "success"})
+	}))
+	defer server.Close()
+
+	err := runNotifShortcut(t, server, "read-all", map[string]string{})
+	if err != nil {
+		t.Fatalf("read-all failed: %v", err)
+	}
+}
+
+// --- watch ---
+
+func TestNotifWatch(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "POST" {
+			t.Fatalf("expected POST, got %s", r.Method)
+		}
+		if r.URL.Path != "/watchers/alice/repo.json" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		writeNotifJSON(w, map[string]interface{}{"status": 0, "message": "success"})
+	}))
+	defer server.Close()
+
+	err := runNotifShortcut(t, server, "watch", map[string]string{
+		"owner": "alice", "repo": "repo", "unwatch": "false",
+	})
+	if err != nil {
+		t.Fatalf("watch failed: %v", err)
+	}
+}
+
+func TestNotifUnwatch(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "DELETE" {
+			t.Fatalf("expected DELETE, got %s", r.Method)
+		}
+		if r.URL.Path != "/watchers/bob/project.json" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		writeNotifJSON(w, map[string]interface{}{"status": 0, "message": "success"})
+	}))
+	defer server.Close()
+
+	err := runNotifShortcut(t, server, "watch", map[string]string{
+		"owner": "bob", "repo": "project", "unwatch": "true",
+	})
+	if err != nil {
+		t.Fatalf("unwatch failed: %v", err)
+	}
+}

shortcuts/register.go

@@ -17,6 +17,7 @@ import (
 	"github.com/gitlink-org/gitlink-cli/shortcuts/license"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/member"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/milestone"
+	"github.com/gitlink-org/gitlink-cli/shortcuts/notification"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/org"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/pipeline"
 	"github.com/gitlink-org/gitlink-cli/shortcuts/pr"
@@ -43,6 +44,7 @@ func RegisterAll(root *cobra.Command, translators ...*i18n.Translator) {
 		"license":   license.Shortcuts(),
 		"member":    member.Shortcuts(),
 		"milestone": milestone.Shortcuts(),
+		"notification": notification.Shortcuts(),
 		"pipeline":  pipeline.Shortcuts(),
 		"pr":        pr.Shortcuts(tr),
 		"profile":   profile.Shortcuts(tr),
@@ -69,6 +71,7 @@ func RegisterAll(root *cobra.Command, translators ...*i18n.Translator) {
 		"license":   "License operations",
 		"member":    "Repository member operations",
 		"milestone": "Milestone operations",
+		"notification": "Notification operations",
 		"pipeline":  "Pipeline operations",
 		"pr":        tr.T("cmd.pr.short"),
 		"profile":   tr.T("cmd.profile.short"),