Merge pull request 'fix(notification-digest): v2.0.0 修正虚构 notification 命令' (#11) from dw into master

2026-06-03 10:32:30 +08:00 · 2026-06-03 10:32:30 +08:00 · eae0269171
parent dd82cf4d3f 94d5115789
commit eae0269171
3 changed files with 572 additions and 45 deletions
--- a/skills/gitlink-notification-digest/EXAMPLES.md
+++ b/skills/gitlink-notification-digest/EXAMPLES.md
@ -0,0 +1,306 @@
+# gitlink-notification-digest 使用样例
+
+## 样例 1：手动执行通知摘要
+
+**日期**：2026-06-03
+**用户**：lindiwen23
+**CLI 版本**：gitlink-cli 0.1.18
+
+### 执行流程
+
+```bash
+# Step 1: 获取用户名
+gitlink-cli auth status
+# → Logged in as lindiwen23
+
+# Step 2: 获取未读通知（status=1）
+gitlink-cli api GET "users/lindiwen23/messages.json" --query "status=1&limit=20" --format json
+# → 7 条未读，unread_notification=7, unread_atme=0
+
+# Step 3: 获取已读通知（用于趋势分析和回顾）
+gitlink-cli api GET "users/lindiwen23/messages.json" --query "status=2&limit=20" --format json
+# → 21 条已读
+
+# Step 4: 分类统计、生成摘要报告
+```
+
+### 关键发现
+
+| 项目 | 值 |
+|------|-----|
+| 未读通知 | 7 条 |
+| @我未读 | 0 条 |
+| 总通知 | 28 条（7 未读 + 21 已读） |
+| 不存在命令 | `gitlink-cli notification`（整个子命令不存在） |
+| 实际 API | `GET /api/users/{owner}/messages.json` |
+| CLI Bug | `api` 路径以 `/` 开头会被解析为本地文件路径 |
+
+### 原始 API 返回（未读 7 条）
+
+```json
+{
+  "total_count": 7,
+  "type": "",
+  "unread_notification": 7,
+  "unread_atme": 0,
+  "messages": [
+    {
+      "id": 740214, "status": 1,
+      "content": "jiangtx在 <b>jiangtx/gitlink-cli</b> 提交了一个合并请求：<b>label 模块新建</b>",
+      "notification_url": "https://www.gitlink.org.cn/jiangtx/gitlink-cli/pulls/15347",
+      "source": "ProjectPullRequest",
+      "created_at": "2026-06-03 00:27:37", "time_ago": "10小时前",
+      "type": "notification"
+    },
+    {
+      "id": 740213, "status": 1,
+      "content": "jiangtx在 <b>jiangtx/gitlink-cli</b> 提交了一个合并请求：<b>pr 域补全</b>",
+      "notification_url": "https://www.gitlink.org.cn/jiangtx/gitlink-cli/pulls/15346",
+      "source": "ProjectPullRequest",
+      "created_at": "2026-06-03 00:11:48", "time_ago": "10小时前",
+      "type": "notification"
+    },
+    {
+      "id": 740178, "status": 1,
+      "content": "jiangtx在 <b>jiangtx/gitlink-cli</b> 提交了一个合并请求：<b>repo 域补全</b>",
+      "notification_url": "https://www.gitlink.org.cn/jiangtx/gitlink-cli/pulls/15343",
+      "source": "ProjectPullRequest",
+      "created_at": "2026-06-02 23:29:52", "time_ago": "11小时前",
+      "type": "notification"
+    },
+    {
+      "id": 740076, "status": 1,
+      "content": "jiangtx在 <b>jiangtx/gitlink-cli</b> 提交了一个合并请求：<b>基础设施修复</b>",
+      "notification_url": "https://www.gitlink.org.cn/jiangtx/gitlink-cli/pulls/15336",
+      "source": "ProjectPullRequest",
+      "created_at": "2026-06-02 16:56:47", "time_ago": "17小时前",
+      "type": "notification"
+    },
+    {
+      "id": 740002, "status": 1,
+      "content": "<b>CWQ</b> 点赞了你管理的仓库 <b>CWQ/Aether_Lens_System-v0.0.1</b>",
+      "notification_url": "https://www.gitlink.org.cn/caoweiqiong",
+      "source": "ProjectPraised",
+      "created_at": "2026-06-02 15:12:55", "time_ago": "19小时前",
+      "type": "notification"
+    },
+    {
+      "id": 738181, "status": 1,
+      "content": "<b>Somebird</b> 已加入项目 <b>CWQ/Aether_Lens_System-v0.0.1</b>",
+      "notification_url": "https://www.gitlink.org.cn/caoweiqiong/Aether",
+      "source": "ProjectMemberJoined",
+      "created_at": "2026-06-01 22:22:07", "time_ago": "1天前",
+      "type": "notification"
+    },
+    {
+      "id": 738136, "status": 1,
+      "content": "<b>Somebird</b> 点赞了你管理的仓库 <b>CWQ/Aether_Lens_System-v0.0.1</b>",
+      "notification_url": "https://www.gitlink.org.cn/Somebird",
+      "source": "ProjectPraised",
+      "created_at": "2026-06-01 20:18:28", "time_ago": "2天前",
+      "type": "notification"
+    }
+  ]
+}
+```
+
+### 分类处理
+
+按 `source` 字段分类：
+
+| source | 含义 | 数量 | 优先级 |
+|--------|------|------|--------|
+| `ProjectPullRequest` | 项目新 PR（jiangtx/gitlink-cli） | 4 | P2 |
+| `ProjectPraised` | 项目被点赞（CWQ/Aether_Lens_System） | 2 | P3 |
+| `ProjectMemberJoined` | 新成员加入 | 1 | P3 |
+
+### 生成的报告
+
+```markdown
+# 🔔 通知摘要
+
+> 生成时间：2026-06-03 10:18
+> 未读通知：7 条 / 总计：28 条
+
+---
+
+## 一、概要
+
+| 类型 | 未读 | 总计 |
+|------|------|------|
+| 🔴 @提及 | 0 | 0 |
+| 🟡 Issue 更新 | 0 | 0 |
+| 🟢 PR 更新 | 4 | ~8 |
+| 🔵 系统通知 | 3 | ~19 |
+
+---
+
+## 二、需要立即处理（P0）
+
+🎉 无紧急通知。
+
+## 三、今天处理（P1）
+
+无待处理通知。
+
+## 四、本周关注（P2）
+
+| # | 类型 | 仓库 | 内容摘要 | 时间 |
+|---|------|------|----------|------|
+| 1 | 🟢 PR | jiangtx/gitlink-cli | label 模块新建 (#15347) | 6/3 00:27 |
+| 2 | 🟢 PR | jiangtx/gitlink-cli | pr 域补全 (#15346) | 6/3 00:11 |
+| 3 | 🟢 PR | jiangtx/gitlink-cli | repo 域补全 (#15343) | 6/2 23:29 |
+| 4 | 🟢 PR | jiangtx/gitlink-cli | 基础设施修复 (#15336) | 6/2 16:56 |
+
+## 五、可忽略（P3）
+
+| # | 类型 | 仓库 | 内容摘要 | 时间 |
+|---|------|------|----------|------|
+| 1 | 🔵 点赞 | CWQ/Aether_Lens_System-v0.0.1 | CWQ 点赞了仓库 | 6/2 15:12 |
+| 2 | 🔵 成员 | CWQ/Aether_Lens_System-v0.0.1 | Somebird 加入项目 | 6/1 22:22 |
+| 3 | 🔵 点赞 | CWQ/Aether_Lens_System-v0.0.1 | Somebird 点赞了仓库 | 6/1 20:18 |
+
+## 六、通知趋势
+
+| 时间段 | 通知数 |
+|--------|--------|
+| 今日（6/3） | 2 |
+| 昨日（6/2） | 3 |
+| 本周（6/1-6/3） | 8 |
+
+## 操作建议
+
+- 建议标记已读：3 条 P3 通知
+- 需要回复/处理：0 条 P0/P1 通知
+```
+
+### 经验总结
+
+1. **`gitlink-cli notification` 命令不存在**：GitLink CLI 没有内置 notification 子命令，所有操作需通过 `gitlink-cli api` 调用 Raw API
+2. **API 端点是 `messages` 不是 `notifications`**：GitLink 用「消息」术语
+3. **CLI 路径 Bug**：`gitlink-cli api` 的 PATH 参数以 `/` 开头会被解析为本地文件路径，必须去掉前导 `/`
+4. **响应字段 `unread_notification` 和 `unread_atme`**：顶层统计字段可直接用于分类计数，无需遍历全部消息
+5. **没有批量已读 API**：标记已读需逐条调用 `POST users/{owner}/messages/{id}/read`
+6. **`source` 字段 `PullReuqestAtme`**：官方 API 存在拼写错误（应为 PullRequestAtme），匹配时注意
+
+---
+
+## 样例 2：通过 Agent 调用 Skill（自动摘要）
+
+**日期**：2026-06-03
+**调用方式**：`Agent(subagent_type="general-purpose", prompt="请调用 gitlink-notification-digest skill，帮我整理通知。")`
+
+### Agent 自主执行的命令序列
+
+```
+工具调用 1: Read  → ../gitlink-shared/SKILL.md              ← 遵循 Skill 前置条件
+工具调用 2: Bash  → gitlink-cli auth status                  ← 获取用户名
+工具调用 3: Bash  → gitlink-cli api GET "users/lindiwen23/messages.json"
+                      --query "status=1&limit=20" --format json   ← 获取未读
+工具调用 4: Bash  → gitlink-cli api GET "users/lindiwen23/messages.json"
+                      --query "status=2&limit=20" --format json   ← 获取已读（趋势分析）
+工具调用 5: Bash  → gitlink-cli api GET "users/lindiwen23/messages.json"
+                      --query "limit=20" --format json            ← 获取全部（总计统计）
+```
+
+### Agent 决策过程
+
+Agent **正确遵循了 skill v2.0.0 的工作流**：
+
+1. 先读取 `gitlink-shared/SKILL.md` 了解认证和全局参数
+2. 用 `auth status` 获取当前用户 `lindiwen23`
+3. 使用 Raw API（路径无前导 `/`）获取未读、已读、全部三类数据
+4. 按 `source` 字段分类：`ProjectPullRequest` → P2，`ProjectPraised`/`ProjectMemberJoined` → P3
+5. 按输出模板生成结构化报告，含所有七个章节
+6. 主动询问是否需要标记 P3 通知为已读
+
+共消耗 **35,601 tokens**，**6 次工具调用**，耗时 **51.7 秒**。
+
+### Agent 生成的报告
+
+```markdown
+# 通知摘要
+
+> 生成时间：2026-06-03 10:30
+> 未读通知：7 条 / 总计：28 条（含已读 21 条）
+> @我未读：0 条
+
+## 一、概要
+
+| 类型 | 未读 | 总计 |
+|------|------|------|
+| @提及 | 0 | 0 |
+| Issue 更新 | 0 | 0 |
+| PR 更新 | 4 | 7 |
+| 系统通知 | 3 | 21 |
+
+## 二、需要立即处理（P0）
+无紧急通知。
+
+## 三、今天处理（P1）
+无待处理通知。
+
+## 四、本周关注（P2）
+4 条 jiangtx/gitlink-cli 的 PR 需关注
+
+## 五、可忽略（P3）
+3 条 CWQ/Aether_Lens_System-v0.0.1 的点赞和成员通知
+
+## 六、通知趋势
+| 时间段 | 通知数 |
+|--------|--------|
+| 今日 | 2 |
+| 昨日 | 3 |
+| 本周 | 7 |
+
+## 七、近期已读回顾
+| 类型 | 内容 | 时间 |
+|------|------|------|
+| 加入项目 | 加入 jiangtx/gitlink-cli | 06-01 |
+| 成员加入 | wyxttn 加入 yetja/灵枢 | 05-29 |
+| PR 合并 | 帮助中心 PR 已通过 | 05-13 |
+| 角色变更 | 帮助中心角色改为管理员 | 05-13 |
+
+## 操作建议
+- 建议标记已读：3 条 P3 通知
+- 需要关注：4 条 P2 通知
+```
+
+### 验证结论
+
+✅ skill v2.0.0 验证通过：
+- Agent 正确使用了 `gitlink-cli api` 而非不存在的 `gitlink-cli notification`
+- Agent 路径没有以 `/` 开头，避开了 CLI 路径解析 Bug
+- Agent 按 `source` 枚举值正确分类，识别出 `PullReuqestAtme` 拼写异常
+- Agent 正确区分了 P0/P1/P2/P3 优先级
+- Agent 使用 `unread_notification`/`unread_atme` 顶层字段快速统计
+- Agent 生成了趋势章节和已读回顾章节
+- 报告结构完整，七个章节覆盖全部模板要求
+
+---
+
+## 异常场景速查
+
+| 场景 | 检测方式 | 处理 |
+|------|----------|------|
+| `notification +list` 命令不存在 | 运行 `gitlink-cli notification` 报错 | 改用 `gitlink-cli api GET "users/{owner}/messages.json"` |
+| API 返回 HTML 而非 JSON | 响应以 `<!doctype html>` 开头 | 去掉路径前导 `/` 重试 |
+| 未读通知 > 返回条数 | `total_count` > `messages.length` | 追加 `--query "page=2"` |
+| 用户名不确定 | `auth status` 输出 | 从输出中提取 login 字段 |
+| 无未读通知 | `unread_notification == 0` | 输出 "🎉 所有通知已处理完毕" |
+
+---
+
+## 版本兼容性说明
+
+本 skill v2.0.0 基于 `gitlink-cli 0.1.18` 编写。关键变更：
+
+| 版本 | `notification` 子命令 | 实际 API | 标记已读 |
+|------|----------------------|----------|----------|
+| v1.0.0 | `notification +list`（虚构） | 不存在 | `notification +read-all`（虚构） |
+| v2.0.0 | 无此子命令 | `GET /api/users/{owner}/messages.json` | `POST /api/users/{owner}/messages/{id}/read` |
+
+当 CLI 版本更新后，重新验证可用命令：
+```bash
+gitlink-cli --help
+```
--- a/skills/gitlink-notification-digest/SKILL.md
+++ b/skills/gitlink-notification-digest/SKILL.md
@ -1,95 +1,209 @@
 ---
 name: gitlink-notification-digest
-version: 1.0.0
+version: 2.0.0
 description: "通知摘要：汇总 GitLink 通知并按类型分类，生成通知摘要报告，支持批量标记已读。当用户需要查看通知摘要、整理通知、清理未读通知时触发。"
 metadata:
  requires:
    bins: ["gitlink-cli"]
-  cliHelp: "gitlink-cli notification --help"
 ---

 # gitlink-notification-digest（通知摘要）

 **CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
-**CRITICAL — `notification +read` 和 `+read-all` 为写操作，执行前需确认用户意图。**
+**CRITICAL — 标记已读为写操作，执行前需确认用户意图。**
 **CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**

 > **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
+> **执行样例：** 参见 [`EXAMPLES.md`](EXAMPLES.md)

 ---

 ## 功能概述

-帮助用户高效管理 GitLink 通知：
+帮助用户高效管理 GitLink 通知（GitLink 平台称为「消息」）：

 1. **通知列表** — 获取所有未读通知
-2. **自动分类** — 按类型（Issue/PR/评论/系统）分组
+2. **自动分类** — 按 `source` 字段分类（Issue/PR/系统等）
 3. **优先级判断** — 识别需要立即处理的通知
 4. **批量操作** — 支持标记已读（需确认）
 5. **摘要报告** — 生成结构化通知摘要

 ---

+## ⚠️ 关键注意事项
+
+### CLI 路径处理 Bug
+
+**`gitlink-cli api` 的路径参数不要以 `/` 开头**，否则会被错误解析为本地文件路径。
+
+```bash
+# ❌ 错误 — 路径以 / 开头会被解析为 D:/Applications/Git/...
+gitlink-cli api GET /users/me
+
+# ✅ 正确 — 去掉前导 /
+gitlink-cli api GET "users/{owner}/messages.json"
+```
+
+### 术语对照
+
+GitLink 平台用「**消息**」（messages）而不是「通知」（notifications）。API 端点和字段均使用 `messages`。
+
+---
+
 ## 工作流：通知摘要

 ### Step 1：获取通知列表

+使用 Raw API 调用 `/api/users/{owner}/messages.json`：
+
 ```bash
-gitlink-cli notification +list --format json
+# 获取未读通知（status=1 表示未读，2 表示已读）
+gitlink-cli api GET "users/{owner}/messages.json" --query "status=1&limit=20" --format json
+
+# 获取全部通知（含已读）
+gitlink-cli api GET "users/{owner}/messages.json" --query "limit=20" --format json
+
+# 分页获取
+gitlink-cli api GET "users/{owner}/messages.json" --query "status=1&page=2&limit=20" --format json
+
+# 按类型过滤
+# type=notification  系统消息（仓库动态、PR、Issue 等）
+# type=atme          @我消息
+gitlink-cli api GET "users/{owner}/messages.json" --query "type=atme&status=1&limit=20" --format json
 ```

-获取参数：
- 默认获取未读通知
- 如需全部通知（含已读）：`--all`
- 如需仅参与的通知：`--participating`
- 分页：`--page 2 --limit 20`
+**参数说明：**

-提取每条通知的：
- `id` — 通知 ID（用于 `+read` 单条标记已读）
- `content` — 通知内容（HTML 格式，从中提取摘要文本）
- `source` — 通知来源类型（如 IssueAtme、PullRequestAssigned、ProjectForked 等）
- `notification_url` — 通知链接，从中解析关联仓库（提取 URL path 中的 `/owner/repo/` 段）
- `created_at` — 通知时间
- `status` — 状态（1=未读，2=已读）
+| 参数 | 位置 | 说明 |
+|------|------|------|
+| `{owner}` | Path | 当前用户名（从 `gitlink-cli auth status` 获取） |
+| `status` | Query | 1=未读，2=已读，不传=全部 |
+| `type` | Query | `notification`=系统消息，`atme`=@我消息，不传=全部 |
+| `page` | Query | 页码（默认 1） |
+| `limit` | Query | 每页条数（默认 20） |
+
+**响应结构：**
+
+```json
+{
+  "total_count": 28,
+  "type": "",
+  "unread_notification": 7,
+  "unread_atme": 0,
+  "messages": [
+    {
+      "id": 740214,
+      "status": 1,
+      "content": "jiangtx在 <b>jiangtx/gitlink-cli</b> 提交了一个合并请求：<b>label 模块新建</b>",
+      "notification_url": "https://www.gitlink.org.cn/jiangtx/gitlink-cli/pulls/15347",
+      "source": "ProjectPullRequest",
+      "created_at": "2026-06-03 00:27:37",
+      "time_ago": "10小时前",
+      "type": "notification",
+      "sender": {
+        "id": 113,
+        "type": "User",
+        "name": "jiangtx",
+        "login": "jiangtx",
+        "image_url": "..."
+      }
+    }
+  ]
+}
+```
+
+**提取字段：**
+- `id` — 消息 ID（用于标记已读）
+- `content` — HTML 格式的通知内容
+- `source` — 通知来源类型（枚举值，见下方分类表）
+- `notification_url` — 跳转链接，可从中解析仓库（提取 URL 中的 `/owner/repo/` 段）
+- `created_at` — 通知时间（格式 `YYYY-MM-DD HH:mm:ss`）
+- `status` — 1=未读，2=已读
+- `type` — `notification` 或 `atme`
+- `sender` — 发送者信息（login, name, image_url）

 ### Step 2：分类与优先级

-#### 2.1 按类型分类（优先使用 `source` 字段）
+#### 2.1 按 `source` 字段分类

-| 类型 | `source` 字段匹配 | 处理建议 |
-|------|------------------|----------|
-| 🔴 **@提及** | 含 `Atme`（如 IssueAtme, PullRequestAtme） | 立即查看回复 |
-| 🟡 **Issue 更新** | 含 `Issue`（如 IssueAssigned, IssueClosed） | 当天处理 |
-| 🟢 **PR 更新** | 含 `PullRequest`（如 PullRequestAssigned, PullRequestMerged） | 跟进代码 |
-| 🔵 **系统通知** | 含 `Project`/`Organization`（如 ProjectForked, ProjectJoined） | 知悉即可 |
-| ⚪ **其他** | 不匹配以上 | 按需查看 |
+| 类型 | `source` 枚举值 | 处理建议 |
+|------|-----------------|----------|
+| 🔴 **@提及** | `IssueAtme`, `PullReuqestAtme`（注意官方 API 拼写如此） | 立即查看回复 |
+| 🟡 **Issue 更新** | `IssueAssigned`, `IssueExpire`, `IssueChanged`, `IssueDeleted`, `IssueJournal`, `ProjectIssue` | 当天处理 |
+| 🟢 **PR 更新** | `PullRequestAssigned`, `PullRequestChanged`, `PullRequestClosed`, `PullRequestJournal`, `PullRequestMerged`, `ProjectPullRequest` | 跟进代码 |
+| 🔵 **系统通知** | `ProjectJoined`, `ProjectLeft`, `ProjectMemberJoined`, `ProjectMemberLeft`, `ProjectForked`, `ProjectPraised`, `ProjectRole`, `ProjectFollowed`, `ProjectDeleted`, `ProjectTransfer`, `ProjectSettingChanged`, `ProjectMilestone`, `ProjectMilestoneCompleted`, `ProjectVersion`, `OrganizationJoined`, `OrganizationLeft`, `OrganizationRole`, `ProjectOpenDevOps` | 知悉即可 |
+| ⚪ **其他** | `LoginIpTip` 及未列出的值 | 按需查看 |

-> `source` 字段返回的是结构化枚举值（如 `IssueAtme`），优先以此分类。`content` 字段为 HTML 文本，仅作补充参考。
+**完整 `source` 枚举参考：**
+
+<details>
+<summary>展开查看全部 source 枚举值</summary>
+
+| 枚举值 | 含义 |
+|--------|------|
+| `IssueAssigned` | 有新指派给我的疑修 |
+| `IssueExpire` | 我创建或负责的疑修截止日期到达最后一天 |
+| `IssueAtme` | 在疑修中@我 |
+| `IssueChanged` | 我创建或负责的疑修状态变更 |
+| `IssueDeleted` | 我创建或负责的疑修删除 |
+| `IssueJournal` | 我创建或负责的疑修有新的评论 |
+| `LoginIpTip` | 登录 IP 提示 |
+| `OrganizationJoined` | 加入组织 |
+| `OrganizationLeft` | 离开组织 |
+| `OrganizationRole` | 组织角色变更 |
+| `ProjectDeleted` | 项目被删除 |
+| `ProjectFollowed` | 有人关注了项目 |
+| `ProjectForked` | 项目被 Fork |
+| `ProjectIssue` | 项目新 Issue |
+| `ProjectJoined` | 加入项目 |
+| `ProjectLeft` | 离开项目 |
+| `ProjectMemberJoined` | 新成员加入项目 |
+| `ProjectMemberLeft` | 成员离开项目 |
+| `ProjectMilestoneCompleted` | 里程碑完成 |
+| `ProjectMilestone` | 新里程碑 |
+| `ProjectOpenDevOps` | DevOps 引擎开通 |
+| `ProjectPraised` | 项目被点赞 |
+| `ProjectPullRequest` | 项目新 PR |
+| `ProjectRole` | 项目角色变更 |
+| `ProjectSettingChanged` | 项目设置变更 |
+| `ProjectTransfer` | 项目转让 |
+| `ProjectVersion` | 新版本发布 |
+| `PullRequestAssigned` | 有指派给我的 PR |
+| `PullReuqestAtme` | 在 PR 中@我（**官方拼写如此**） |
+| `PullRequestChanged` | PR 状态变更 |
+| `PullRequestClosed` | PR 被关闭 |
+| `PullRequestJournal` | PR 有新评论 |
+| `PullRequestMerged` | PR 已合并 |
+
+</details>

 #### 2.2 优先级排序

 | 优先级 | 判定 |
 |--------|------|
-| **P0 - 立即** | @提及 + 来自自己参与的 Issue/PR |
-| **P1 - 今天** | 自己创建的 Issue/PR 有新回复，或分配的 Issue 有更新 |
-| **P2 - 本周** | 关注的仓库有新动态 |
-| **P3 - 可忽略** | 系统通知、已解决的 Issue |
+| **P0 - 立即** | 含 `Atme` 的消息（IssueAtme, PullReuqestAtme） |
+| **P1 - 今天** | 自己管理的仓库有 PR 合并/关闭，或被分配的 Issue/PR 有更新 |
+| **P2 - 本周** | 关注的仓库有新 PR、新 Issue |
+| **P3 - 可忽略** | 点赞（ProjectPraised）、成员加入/离开、Fork 等系统通知 |

 ### Step 3：生成通知摘要

-按模板输出。
+按下方输出模板生成报告。

-### Step 4：批量标记已读（可选，需确认）
+### Step 4：标记已读（可选，需确认）

 ```bash
-# 标记全部已读
-gitlink-cli notification +read-all --format json
-
 # 标记单条已读
-gitlink-cli notification +read --id <notification_id> --format json
+gitlink-cli api POST "users/{owner}/messages/{id}/read" --format json
+
+# 批量标记已读 — 逐条调用，GitLink 暂无批量已读 API
+for id in <id1> <id2> <id3>; do
+  gitlink-cli api POST "users/{owner}/messages/$id/read" --format json
+done
 ```

-> ⚠️ **执行前必须确认用户意图** — `+read` 和 `+read-all` 为写操作。
+> ⚠️ **执行前必须确认用户意图** — 标记已读为写操作。
+> ⚠️ **GitLink 没有批量已读 API**，需要逐条标记。

 ---

@ -157,13 +271,19 @@ gitlink-cli notification +read --id <notification_id> --format json

 ---

+## 七、近期已读回顾
+
+> 列出最近 3-5 条已读但值得回顾的通知（如角色变更、PR 合并等）。
+
+---
+
 ## 操作建议

 - 建议标记已读：{{suggest_read_count}} 条 P3 通知
 - 需要回复/处理：{{need_action_count}} 条 P0/P1 通知

-如需标记全部已读，我可以执行：
-`gitlink-cli notification +read-all`
+如需标记 P3 通知为已读，我可以逐条执行：
+`gitlink-cli api POST "users/{owner}/messages/{id}/read"`
 ```

 ---
@ -173,15 +293,19 @@ gitlink-cli notification +read --id <notification_id> --format json
 | 场景 | 处理方式 |
 |------|----------|
 | 无未读通知 | 输出"🎉 所有通知已处理完毕" |
-| 通知数量 > 50 | 分批获取（page 1/2/3），优先分析最近 50 条 |
-| `notification +list` 返回空 | 检查认证状态（参考 gitlink-shared） |
+| 通知数量 > 50 | 分页获取（page 1/2/3），优先分析最近 50 条 |
+| API 返回 HTML 而非 JSON | 路径可能以 `/` 开头导致解析错误，去掉前导 `/` 重试 |
+| `unread_notification` > messages 数组长度 | 存在多页数据，追加 `--query "page=2"` 获取 |
+| 用户名不确定 | 先执行 `gitlink-cli auth status` 获取当前登录用户 |

 ---

 ## 注意事项

 - ✅ **所有命令使用 `--format json`**，确保可解析
- ✅ **`+read` 和 `+read-all` 为写操作**，执行前必须确认用户意图
+- ✅ **标记已读为写操作**，执行前必须确认用户意图
 - ✅ **本 Skill 默认只读分析**，仅在用户明确要求时标记已读
- ⚠️ **通知类型依赖标题关键词推断**，实际类型可能有偏差
- ⚠️ **通知可能分页**，数量 >20 时需追加 `--page 2` 等
+- ⚠️ **`gitlink-cli api` 路径不要以 `/` 开头**（CLI Bug）
+- ⚠️ **GitLink 用「消息（messages）」而非「通知（notifications）」**
+- ⚠️ **`source` 字段 `PullReuqestAtme` 是官方拼写错误**，实际使用注意匹配
+- ⚠️ **通知可能分页**，数量 >20 时需追加 `--query "page=2"`
--- a/skills/gitlink-shared/references/api-reference.md
+++ b/skills/gitlink-shared/references/api-reference.md
@ -73,3 +73,100 @@
 | Branch 删除返回"不存在" | 无法删除分支 | 待 GitLink 修复 |
 | Release 删除返回"不存在" | 无法删除发布 | 待 GitLink 修复 |
 | Create File 返回"已存在" | 无法通过 API 创建文件 | 待 GitLink 修复 |
+| `api` 命令路径以 `/` 开头会被解析为本地路径 | 返回 HTML 而非 JSON | 去掉路径前导 `/` 即可 |
+
+---
+
+## 消息（通知）API
+
+GitLink 的通知功能通过「消息」API 实现。
+
+### 端点
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/users/{owner}/messages.json` | GET | 获取用户消息列表 |
+| `/users/{owner}/messages/{id}/read` | POST | 标记单条消息已读 |
+| `/users/{owner}/messages/{id}` | DELETE | 删除消息 |
+| `/users/{owner}/messages/settings` | GET | 平台消息设置 |
+| `/users/{owner}/messages/settings/list` | GET | 用户消息设置列表 |
+| `/users/{owner}/messages/settings/update` | POST | 更新用户消息设置 |
+
+### 查询参数（GET messages.json）
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `status` | integer | 1=未读，2=已读，不传=全部 |
+| `type` | string | `notification`=系统消息，`atme`=@我消息，不传=全部 |
+| `page` | integer | 页码（默认 1） |
+| `limit` | integer | 每页条数（默认 20） |
+
+### 响应字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total_count` | integer | 总消息数 |
+| `unread_notification` | integer | 未读系统消息数 |
+| `unread_atme` | integer | 未读@我消息数 |
+| `messages[].id` | integer | 消息唯一 ID |
+| `messages[].status` | integer | 1=未读，2=已读 |
+| `messages[].content` | string | HTML 格式的消息内容 |
+| `messages[].source` | enum | 消息来源类型（见下方枚举表） |
+| `messages[].notification_url` | string | 消息跳转链接 |
+| `messages[].created_at` | string | 创建时间（YYYY-MM-DD HH:mm:ss） |
+| `messages[].time_ago` | string | 相对时间描述 |
+| `messages[].type` | string | `notification` 或 `atme` |
+| `messages[].sender` | object | 发送者信息（id, name, login, image_url） |
+
+### source 枚举值
+
+| 枚举值 | 含义 | 分类 |
+|--------|------|------|
+| `IssueAssigned` | 有新指派给我的疑修 | Issue |
+| `IssueExpire` | 疑修截止日期到达最后一天 | Issue |
+| `IssueAtme` | 在疑修中@我 | @提及 |
+| `IssueChanged` | 疑修状态变更 | Issue |
+| `IssueDeleted` | 疑修被删除 | Issue |
+| `IssueJournal` | 疑修有新评论 | Issue |
+| `ProjectIssue` | 项目新 Issue | Issue |
+| `PullRequestAssigned` | 有新指派给我的 PR | PR |
+| `PullReuqestAtme` | 在 PR 中@我（**官方 API 拼写如此**） | @提及 |
+| `PullRequestChanged` | PR 状态变更 | PR |
+| `PullRequestClosed` | PR 被关闭 | PR |
+| `PullRequestJournal` | PR 有新评论 | PR |
+| `PullRequestMerged` | PR 已合并 | PR |
+| `ProjectPullRequest` | 项目有新 PR | PR |
+| `ProjectJoined` | 加入项目 | 系统 |
+| `ProjectLeft` | 离开项目 | 系统 |
+| `ProjectMemberJoined` | 新成员加入项目 | 系统 |
+| `ProjectMemberLeft` | 成员离开项目 | 系统 |
+| `ProjectForked` | 项目被 Fork | 系统 |
+| `ProjectPraised` | 项目被点赞 | 系统 |
+| `ProjectRole` | 项目角色变更 | 系统 |
+| `ProjectFollowed` | 项目被关注 | 系统 |
+| `ProjectDeleted` | 项目被删除 | 系统 |
+| `ProjectTransfer` | 项目转让 | 系统 |
+| `ProjectSettingChanged` | 项目设置变更 | 系统 |
+| `ProjectMilestone` | 新里程碑 | 系统 |
+| `ProjectMilestoneCompleted` | 里程碑完成 | 系统 |
+| `ProjectVersion` | 新版本发布 | 系统 |
+| `ProjectOpenDevOps` | DevOps 引擎开通 | 系统 |
+| `OrganizationJoined` | 加入组织 | 系统 |
+| `OrganizationLeft` | 离开组织 | 系统 |
+| `OrganizationRole` | 组织角色变更 | 系统 |
+| `LoginIpTip` | 登录 IP 提示 | 其他 |
+
+### 调用示例
+
+```bash
+# 获取未读通知
+gitlink-cli api GET "users/lindiwen23/messages.json" --query "status=1&limit=20" --format json
+
+# 获取 @我 的通知
+gitlink-cli api GET "users/lindiwen23/messages.json" --query "type=atme&status=1" --format json
+
+# 标记单条已读
+gitlink-cli api POST "users/lindiwen23/messages/740214/read" --format json
+
+# ⚠️ 路径不要以 / 开头，否则会被解析为本地文件路径
+```