From 94d51157895515f4727af6f16552fa0900e6c99a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9E=97=E8=BF=AA=E6=96=87?= <3117675914@qq.com> Date: Wed, 3 Jun 2026 10:31:42 +0800 Subject: [PATCH] =?UTF-8?q?fix(notification-digest):=20v2.0.0=20=E2=80=94?= =?UTF-8?q?=20=E4=BF=AE=E6=AD=A3=E8=99=9A=E6=9E=84=E7=9A=84=20notification?= =?UTF-8?q?=20=E5=91=BD=E4=BB=A4=E4=B8=BA=E5=AE=9E=E9=99=85=20messages=20A?= =?UTF-8?q?PI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - notification +list/+read/+read-all 均不存在，替换为 gitlink-cli api 调用 - API 端点: GET /api/users/{owner}/messages.json - 标记已读: POST /api/users/{owner}/messages/{id}/read - 添加 CLI 路径 Bug 说明（前导 / 导致解析错误） - 补充完整 source 枚举值表（30+ 个枚举） - 新增 EXAMPLES.md（手动执行 + Agent 测试两个样例） - gitlink-shared/api-reference.md 补充消息 API 章节 Co-Authored-By: Claude Opus 4.8 --- .../gitlink-notification-digest/EXAMPLES.md | 306 ++++++++++++++++++ skills/gitlink-notification-digest/SKILL.md | 214 +++++++++--- .../references/api-reference.md | 97 ++++++ 3 files changed, 572 insertions(+), 45 deletions(-) create mode 100644 skills/gitlink-notification-digest/EXAMPLES.md diff --git a/skills/gitlink-notification-digest/EXAMPLES.md b/skills/gitlink-notification-digest/EXAMPLES.md new file mode 100644 index 0000000..7c52285 --- /dev/null +++ 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在 jiangtx/gitlink-cli 提交了一个合并请求：label 模块新建", + "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在 jiangtx/gitlink-cli 提交了一个合并请求：pr 域补全", + "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在 jiangtx/gitlink-cli 提交了一个合并请求：repo 域补全", + "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在 jiangtx/gitlink-cli 提交了一个合并请求：基础设施修复", + "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": "CWQ 点赞了你管理的仓库 CWQ/Aether_Lens_System-v0.0.1", + "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": "Somebird 已加入项目 CWQ/Aether_Lens_System-v0.0.1", + "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": "Somebird 点赞了你管理的仓库 CWQ/Aether_Lens_System-v0.0.1", + "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 | 响应以 `` 开头 | 去掉路径前导 `/` 重试 | +| 未读通知 > 返回条数 | `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 +``` diff --git a/skills/gitlink-notification-digest/SKILL.md b/skills/gitlink-notification-digest/SKILL.md index e0f9fa8..72cf9df 100644 --- 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在 jiangtx/gitlink-cli 提交了一个合并请求：label 模块新建", + "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` 枚举参考：** + +
+展开查看全部 source 枚举值 + +| 枚举值 | 含义 | +|--------|------| +| `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 已合并 | + +
#### 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 --format json +gitlink-cli api POST "users/{owner}/messages/{id}/read" --format json + +# 批量标记已读 — 逐条调用，GitLink 暂无批量已读 API +for id in ; 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 --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 --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"` diff --git a/skills/gitlink-shared/references/api-reference.md b/skills/gitlink-shared/references/api-reference.md index 13c6d84..3c258b7 100644 --- 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 + +# ⚠️ 路径不要以 / 开头，否则会被解析为本地文件路径 +```