diff --git a/skills/gitlink-maintainer-radar/SKILL.md b/skills/gitlink-maintainer-radar/SKILL.md new file mode 100644 index 0000000..7f34682 --- /dev/null +++ b/skills/gitlink-maintainer-radar/SKILL.md @@ -0,0 +1,223 @@ +--- +name: gitlink-maintainer-radar +description: "维护者雷达:面向 GitLink 仓库维护者,联合扫描 open Pull Request、open Issue、消息提醒、review 分配和等待时长,识别响应超时、review 负载失衡、负责人长期停滞等协作瓶颈,生成按优先级排序的处置清单、催办建议和责任调整建议。用于用户需要值班巡检待办、判断哪些事项被晾着了、找出 reviewer 瓶颈、发现有负责人但无进展的条目,或生成维护者今日工作面板时。" +--- + +# gitlink-maintainer-radar + +**CRITICAL - 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md),按其中的认证、全局参数和安全规则执行。** +**CRITICAL - 所有 GitLink 操作只使用 `gitlink-cli`,不要改用 `gh`、`glab` 或网页猜测数据。** +**CRITICAL - 默认只读分析。只有在用户明确要求时才回写评论、标签或成员分配。** + +这个 skill 不再做“把通知列表抄一遍”的弱摘要,而是把三类真正影响维护者效率的治理信号合在一起: + +1. **响应时效雷达**:找出超出响应 SLA 的 Issue 和 PR。 +2. **Review 负载雷达**:判断 reviewer 是否失衡,以及哪些 PR 因分配不均而卡住。 +3. **责任停滞雷达**:识别已经有 assignee / reviewer,但长期没有推进动作的条目。 + +把它当作“维护者值班面板”来用,而不是通知中心。 + +## 核心能力 + +### 1. 响应时效雷达 + +优先识别这些最有用的 SLA 违约场景: + +- 超过 24 小时无人首次响应的 Issue +- 超过 3 天无人 review 的 PR +- 已经 `approve` 但 2 天内没有推进合并或进一步处理的 PR +- `requested changes` 之后作者长期未更新的 PR +- 作者已经更新、但维护者超过 48 小时未复看的 PR + +这些信号最适合直接形成“今天先处理什么”的清单。 + +### 2. Review 负载雷达 + +从多人协作角度,重点看: + +- 哪些 reviewer 手上挂了太多待处理 PR +- 哪些 reviewer 长期没有被分配,存在空闲容量 +- 哪些 PR 因 reviewer 单点瓶颈停滞 +- 哪些 PR 一直在同一个 reviewer 身上来回等待 +- 哪些高优先级 PR 值得建议重新分配 reviewer + +这个模块的目标不是简单统计数量,而是指出“哪里需要重新分配”。 + +### 3. 责任停滞雷达 + +重点识别这些“看起来有人负责,实际上没人推进”的场景: + +- 有 assignee 的 Issue 长期无新评论、无状态更新 +- 有 reviewer / assignee 的 PR 长期无 review、无结论、无合并动作 +- 同一个责任人名下积压了过多停滞事项 +- 条目虽然被分配,但最近一次动作仍然停留在发起人一侧 +- 责任关系已经失效,应该提醒、转派或收口 + +这个模块比单纯的 stale 检查更实用,因为它关心的是“责任失效”。 + +### 4. 统一处置建议 + +把前面三类信号收敛成维护者真正能执行的动作: + +- 先回复哪些条目,快速消除首响超时 +- 哪些 PR 需要重新分配 reviewer +- 哪些 assignee / reviewer 需要提醒 +- 哪些长期停滞条目应该收口、降级或重新明确责任人 +- 哪些条目虽然 noisy,但本轮值班可以忽略 + +## 判断规则 + +### HOT + +- 超过 SLA 且当前明显在等维护者动作 +- 已 `approve` 但无人推进合并,且影响版本节奏 +- 高优先级 PR 因 reviewer 负载失衡卡住 +- 有负责人但超过阈值完全无动作 +- 首次贡献者的高质量提交长期无人回应 + +### WATCH + +- 尚未超 SLA,但已经接近阈值 +- 责任人存在,但推进节奏明显偏慢 +- reviewer 负载有失衡趋势,但还未造成明确阻塞 +- 讨论在继续,但一直没有收敛到下一步动作 + +### BACKGROUND + +- 普通消息提醒和不会改变维护节奏的系统通知 +- 已明确有人处理且最近有进展的条目 +- 短期不影响主线和协作节奏的低优先级事项 + +详细矩阵和建议阈值见 [`references/triage-matrix.md`](references/triage-matrix.md)。 + +## 工作流 + +### Step 1:确认仓库与维护者视角 + +先确认当前登录用户和仓库范围: + +```bash +gitlink-cli auth status +gitlink-cli repo +info --owner --repo --format json +``` + +如果用户没有显式提供仓库,且当前目录就是目标仓库,可以使用自动解析。 + +### Step 2:抓取基础队列数据 + +至少获取这几组数据: + +```bash +# 未读消息,用于捕捉 @ 提醒和人工催办信号 +gitlink-cli api GET "users//messages.json" --query "status=1&limit=40" --format json + +# open PR +gitlink-cli pr +list --owner --repo --state open --format json + +# open Issue +gitlink-cli issue +list --owner --repo --state open --format json +``` + +如果队列很大,先拉最近 40 条,再聚焦高风险对象。 + +### Step 3:为高风险 PR 补拉 review 与等待链路 + +对命中 SLA、负载失衡或停滞信号的 PR,继续获取: + +```bash +gitlink-cli pr +view --owner --repo -i --format json +gitlink-cli pr +reviews --owner --repo -i --format json +gitlink-cli pr +version-diff --owner --repo -i --format json +``` + +要明确判断: + +- 当前在等作者、等 reviewer,还是等 maintainer 决策 +- 最近一次有效推进动作是谁完成的 +- review 结论是否已经形成,但没有后续动作 +- 是否存在 reviewer 过载导致的人工瓶颈 + +如果用户需要深入判断代码可行性,切换到 `gitlink-pr-assessor`。如果用户要判断是否适合集成主线,切换到 `gitlink-pr-integrator`。 + +### Step 4:为停滞 Issue 建立责任视图 + +对 Issue 至少判断: + +- 是否已有 assignee +- 最近一次评论或状态更新距离现在多久 +- 当前是在等提问方补信息,还是在等维护者接手 +- 是否值得补标签、转派或收口 + +### Step 5:构建统一处置面板 + +输出不止要说明“发生了什么”,还要告诉维护者下一步怎么做: + +- 哪些条目要先回复,修复 SLA 超时 +- 哪些 PR 应该重新分配 reviewer +- 哪些条目需要提醒当前责任人 +- 哪些条目应该转派、收口或延后 +- 如果用户要求,生成适合直接发布的中文提醒评论草稿 + +评论草稿模板见 [`references/comment-templates.md`](references/comment-templates.md)。 + +### Step 6:输出维护者报告 + +报告应至少包含: + +1. SLA 超时条目 +2. reviewer 负载失衡情况 +3. 有负责人但停滞的条目 +4. 今天建议先做的动作 +5. 可延后的背景项 + +推荐输出模板: + +```markdown +# 维护者雷达报告 + +## SLA 超时 +- Issue #87:超过 24 小时无人首次响应,当前仍无明确责任人。 +- PR #123:作者 2 天前已按 review 修改,当前等待维护者复看。 + +## Review 负载 +- reviewer A 当前挂着 5 个待 review PR,是主要瓶颈。 +- reviewer B 最近没有分配到待处理条目,存在可释放容量。 + +## 责任停滞 +- Issue #91 已分配给 maintainer C,但 6 天没有新动作。 +- PR #118 有 reviewer,但上一轮意见后一直无人推进结论。 + +## 今日建议动作 +- 先回复 Issue #87,避免继续首响超时。 +- 把 PR #126 从 reviewer A 转给 reviewer B。 +- 对 PR #118 发送一次责任确认提醒。 + +## 可延后 +- 项目关注、点赞、普通系统通知可忽略。 +``` + +## 评论与写操作规则 + +只有用户明确要求时,才执行这些动作: + +- 给 PR / Issue 发表评论 +- 调整标签 +- 变更成员或分配关系 +- 标记消息已读 + +在回写之前,先把拟执行动作和目标对象列清楚,再执行。 + +## 处理边界 + +- 这个 skill 的重点是“维护治理与协作分流”,不是完整代码审查。 +- 它比 `gitlink-issue-triage` 更偏责任推进,而不是 Issue 语义分类。 +- 它比 `gitlink-health`、`gitlink-insight` 更偏当下值班,而不是全局健康分析。 +- 如果仓库没有启用 GitLink 平台 CI,不影响这个 skill 的核心价值。 + +## 典型触发语句 + +- “帮我看下这个仓库哪些 Issue 和 PR 被晾着了。” +- “扫描一下 open PR 和 open Issue,给我一个维护者值班清单。” +- “哪些 PR 因 reviewer 负载不均卡住了?” +- “找出有负责人但没进展的条目。” +- “把今天必须回复、必须转派、必须催办的事项挑出来。” diff --git a/skills/gitlink-maintainer-radar/agents/openai.yaml b/skills/gitlink-maintainer-radar/agents/openai.yaml new file mode 100644 index 0000000..a68ddc2 --- /dev/null +++ b/skills/gitlink-maintainer-radar/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "维护者雷达" + short_description: "识别响应超时、review 失衡和责任停滞,生成维护者处置面板。" + default_prompt: "Use $gitlink-maintainer-radar 扫描这个 GitLink 仓库当前的响应 SLA、review 负载和责任停滞情况,输出按优先级排序的处置清单和建议动作。" diff --git a/skills/gitlink-maintainer-radar/assets/codex-skill-directory.png b/skills/gitlink-maintainer-radar/assets/codex-skill-directory.png new file mode 100644 index 0000000..17f97e0 Binary files /dev/null and b/skills/gitlink-maintainer-radar/assets/codex-skill-directory.png differ diff --git a/skills/gitlink-maintainer-radar/assets/codex-validation-output-1.png b/skills/gitlink-maintainer-radar/assets/codex-validation-output-1.png new file mode 100644 index 0000000..d9c2309 Binary files /dev/null and b/skills/gitlink-maintainer-radar/assets/codex-validation-output-1.png differ diff --git a/skills/gitlink-maintainer-radar/assets/codex-validation-output-2.png b/skills/gitlink-maintainer-radar/assets/codex-validation-output-2.png new file mode 100644 index 0000000..97266d1 Binary files /dev/null and b/skills/gitlink-maintainer-radar/assets/codex-validation-output-2.png differ diff --git a/skills/gitlink-maintainer-radar/examples/codex-validation-2026-06-26.md b/skills/gitlink-maintainer-radar/examples/codex-validation-2026-06-26.md new file mode 100644 index 0000000..ca5b17e --- /dev/null +++ b/skills/gitlink-maintainer-radar/examples/codex-validation-2026-06-26.md @@ -0,0 +1,91 @@ +# Codex 验证记录(2026-06-26) + +Agent 平台:Codex + +验证目标:确认 `gitlink-maintainer-radar` 能针对 GitLink 仓库的 open PR 与 open Issue 队列输出维护者可直接执行的值班报告,识别响应超时、review 分配缺失、责任停滞和今日优先动作。 + +验证结果如下: + +# GitLink/gitlink-cli 维护者雷达报告 + +扫描时间:2026-06-26 11:46 +08:00 + +open PR:156 条 + +open Issue:按客户端过滤 `status_name != 关闭` 后为 9 条 + +数据说明:GitLink 的 `--state open` 返回中混入了关闭 Issue,已按状态二次过滤。 + +### 今日最优先处理 + +1. **PR #225 `feat(repo): add scaffold creation options`** + - 状态:已 `approved`,但 open 已约 10.2 天,review 后仍未推进。 + - 建议:今天优先做合并前确认或说明阻塞原因。这是最短动作、收益最高的一项。 + +2. **Issue #17 `API是否支持自动读取仓库内文件(README等)?`** + - 状态:创建约 36.1 天,0 评论,无负责人。 + - 建议:补首响,判断是 API 能力咨询、文档补充,还是转为需求。 + +3. **Issue #18 `giklink-cli issue +update后issue状态框变红色`** + - 状态:创建约 35.0 天,0 评论,无负责人。 + - 建议:补首响并要求复现步骤;这是明确 bug 信号。 + +4. **Issue #20 `bug: api 命令单次调用不替换 :owner/:repo 占位符(0.2.0)`** + - 状态:约 13.6 天无新动作,无负责人。 + - 建议:关联/核对 PR #281,若 #281 覆盖该问题,优先推进 #281 并在 Issue 中同步状态。 + +5. **PR #281 `fix(api): 补齐单次请求模板变量与请求头支持`** + - 状态:新近 PR,但对应已有长期 Issue #20。 + - 建议:作为“解堵型 PR”优先 review,减少 Issue 队列停滞。 + +### SLA 超时 + +**PR 侧:** + +- 156 条 open PR 中,139 条超过 3 天没有 review 记录。 +- 其中 53 条几乎没有有效讨论,`journals_count <= 1`,属于首响/初审明显不足。 +- 只有 4 条 open PR 有 review 记录,review 覆盖率非常低。 + +高优先级超时 PR: + +- #225:已 approved 但未推进。 +- #228-#232:Ct201314 提交的一组 skill PR,约 13.8 天无 review、无讨论。 +- #254/#258:luwanzhou 的 API/output 修复类 PR,约 11 天无 review,且属于基础能力修复。 +- #139/#242:wiki 相关 PR,约 11.5 天无 review,功能重叠,建议一起处理。 + +**Issue 侧:** + +- #17、#18:0 评论,超过 24 小时首响 SLA 很久。 +- #5、#14、#15、#20、#21:均无负责人且长期无新进展。 +- #2:状态未知,约 68.8 天未更新,建议收口或重新定性。 + +### Review 负载失衡 + +没有发现“某个 reviewer 明确挂载过多 PR”的证据,因为当前 PR 列表里的 `reviewers` 基本为空,review API 也只有 4 条记录。 + +真正的问题是:**review 分配缺失,而不是某个人过载。** + +建议今天做一次分配重整: + +- 给基础修复类 PR 指定 reviewer:#281、#254、#258。 +- 给命令族 PR 按模块分配:PR 列表组 #283/#284/#285,branch 组 #282/#268,template 组 #274/#263/#72。 +- 对超大 PR #276/#259 不直接分配普通 review,先要求拆分。 + +### 有负责人但长期无进展 + +未在当前 open PR / open Issue 的结构化字段中发现明确 assignee 或 reviewer 负责人挂载后长期停滞的 open 条目。 + +但存在“责任缺失型停滞”: + +- PR:大量条目无 reviewer。 +- Issue:9 条 open-ish Issue 均无明确负责人。 +- 维护建议:先补负责人,再谈 SLA;否则队列会继续堆积。 + +### 今日行动清单 + +1. 推进 #225:合并前确认或说明不合并原因。 +2. 回复 Issue #17/#18:补首响并要求必要上下文。 +3. 把 #20 与 #281 绑定处理:先 review #281。 +4. 建立 reviewer 分配批次:基础修复、PR 命令、branch、template、repo、user/account 分组处理。 +5. 对 #276/#259 发出拆分要求,避免它们继续阻塞大量小 PR。 +6. 对 #228-#232 这组 skill PR 给一次批量初审或收口说明。 diff --git a/skills/gitlink-maintainer-radar/examples/daily-maintainer-scan.md b/skills/gitlink-maintainer-radar/examples/daily-maintainer-scan.md new file mode 100644 index 0000000..91e17cf --- /dev/null +++ b/skills/gitlink-maintainer-radar/examples/daily-maintainer-scan.md @@ -0,0 +1,21 @@ +# 示例:日常值班扫描 + +用户请求: + +```text +Use $gitlink-maintainer-radar 扫描 Gitlink/gitlink-cli 当前 open PR 和 open Issue,告诉我今天维护者先处理什么。 +``` + +期望动作: + +1. 读取 `../gitlink-shared/SKILL.md`。 +2. 获取当前登录用户、仓库信息、未读消息、open PR、open Issue。 +3. 对命中的高风险 PR 补拉详情和 review。 +4. 输出一份中文报告,至少包含“SLA 超时”“Review 负载”“责任停滞”“今日建议动作”。 + +输出要点: + +- 不要把所有通知原样抄出来。 +- 优先指出卡在维护者侧的条目。 +- 优先发现超时未响应、review 失衡和责任失效。 +- 给出 3 到 5 条能直接执行的建议。 diff --git a/skills/gitlink-maintainer-radar/examples/release-window-scan.md b/skills/gitlink-maintainer-radar/examples/release-window-scan.md new file mode 100644 index 0000000..0423131 --- /dev/null +++ b/skills/gitlink-maintainer-radar/examples/release-window-scan.md @@ -0,0 +1,19 @@ +# 示例:版本窗口前的维护者巡检 + +用户请求: + +```text +Use $gitlink-maintainer-radar 看一下这个仓库在发版前有哪些 open PR / Issue 需要维护者优先清理,并帮我起草两条提醒评论。 +``` + +期望动作: + +1. 先做常规队列扫描。 +2. 特别关注会影响发布节奏、分支稳定性、review 负载和责任停滞的条目。 +3. 从 `references/comment-templates.md` 取合适模版,结合上下文改写两条中文评论草稿。 + +输出要点: + +- 明确区分“今天必须处理”和“可以发版后再看”。 +- 如果没有足够证据,不要武断下结论。 +- 默认给评论草稿,不要直接回写远端。 diff --git a/skills/gitlink-maintainer-radar/examples/reviewer-balance-scan.md b/skills/gitlink-maintainer-radar/examples/reviewer-balance-scan.md new file mode 100644 index 0000000..7b87ea1 --- /dev/null +++ b/skills/gitlink-maintainer-radar/examples/reviewer-balance-scan.md @@ -0,0 +1,20 @@ +# 示例:review 负载与责任停滞巡检 + +用户请求: + +```text +Use $gitlink-maintainer-radar 看一下这个仓库最近哪些 PR 因 reviewer 负载失衡或责任人停滞而卡住,给我一个转派和提醒建议清单。 +``` + +期望动作: + +1. 读取 `../gitlink-shared/SKILL.md`。 +2. 获取 open PR、相关 review 和未读提醒。 +3. 识别 reviewer 高负载、低负载和停滞责任条目。 +4. 输出按优先级排序的“转派建议”“提醒建议”“可继续观察”三部分结果。 + +输出要点: + +- 不只统计 reviewer 数量,要指出具体的阻塞链路。 +- 如果没有明确 reviewer 字段,也要基于 review 历史和等待关系做近似判断。 +- 默认给建议,不直接修改分配关系。 diff --git a/skills/gitlink-maintainer-radar/references/comment-templates.md b/skills/gitlink-maintainer-radar/references/comment-templates.md new file mode 100644 index 0000000..ad510e0 --- /dev/null +++ b/skills/gitlink-maintainer-radar/references/comment-templates.md @@ -0,0 +1,52 @@ +# 维护者常用评论模板 + +根据实际语境改写,不要机械复制。 + +## 首响超时回复 + +```text +感谢反馈,这条事项已经进入维护者待处理队列。我先补一个响应,接下来会按优先级继续跟进;如果你这边还有复现信息、影响范围或预期行为,也可以继续补充,这会帮助更快推进。 +``` + +## 请求作者补充上下文 + +```text +感谢提交。当前描述还不足以支持快速决策,请补充一下: +1. 这个改动具体要解决什么问题; +2. 你是如何验证结果的; +3. 是否影响现有命令输出、兼容性或默认行为。 +补齐后我们继续跟进。 +``` + +## 提醒维护者侧待复看 + +```text +这条 PR 作者已经根据前一轮意见更新,当前主要等待维护者复看。建议优先确认: +1. 阻塞问题是否已经解决; +2. 是否还需要补测试或补文档; +3. 是否适合进入下一步合并评估。 +``` + +## 建议重新分配 reviewer + +```text +这条 PR 当前已经等待了一段时间。考虑到现有 reviewer 队列负载较高,建议补充或调整 reviewer,避免继续在同一环节排队。 +``` + +## 责任停滞提醒 + +```text +这条事项已经分配责任人,但最近一段时间没有新的推进动作。请当前责任人确认一下后续计划;如果短期内无法继续推进,建议明确是否需要转派、补充上下文或先收口。 +``` + +## 提醒作者缩小改动范围 + +```text +这个提交想解决的问题有价值,但当前改动面偏大,已经同时触及多个主题。建议先收敛成一个更小、边界更清晰的版本,这样更容易评审和合并。 +``` + +## 长期无响应条目收口 + +```text +这条讨论已经停留一段时间。为了避免队列持续堆积,请作者确认是否还会继续推进;如果短期内没有计划,我们会先按当前状态收口,后续需要时可以再重新开启。 +``` diff --git a/skills/gitlink-maintainer-radar/references/triage-matrix.md b/skills/gitlink-maintainer-radar/references/triage-matrix.md new file mode 100644 index 0000000..1ee0a5b --- /dev/null +++ b/skills/gitlink-maintainer-radar/references/triage-matrix.md @@ -0,0 +1,54 @@ +# 维护者雷达优先级矩阵 + +这个矩阵同时覆盖三类判断: + +1. 响应是否超出 SLA +2. reviewer 负载是否失衡 +3. 责任关系是否失效或停滞 + +按下面的规则把条目分到 `HOT`、`WATCH`、`BACKGROUND`。多个信号同时命中时,取更高优先级。 + +## HOT + +- Issue 超过 24 小时无人首次响应,且当前明显需要维护者接手。 +- PR 超过 3 天无人 review,或作者更新后超过 48 小时无人复看。 +- PR 已 `approve` 超过 2 天仍无人推进合并或后续处理。 +- 同一 reviewer 挂着多个高优先级 PR,已经形成明显瓶颈。 +- 条目已有 assignee / reviewer,但在阈值内完全无新动作。 +- 新贡献者提交或高影响条目因无人响应而持续停滞。 + +## WATCH + +- 条目还未超 SLA,但已经接近阈值。 +- reviewer 分配不均已经出现趋势,但还没形成硬阻塞。 +- Issue 有责任人,但更新频率明显偏低。 +- PR 讨论在继续,但没有明确下一步负责人。 +- requested changes 后长时间无更新,需要维护者决定提醒还是收口。 + +## BACKGROUND + +- 普通系统消息、点赞、关注、加入退出项目。 +- 已经明确归属、暂时不需要维护者处理的条目。 +- 与当前值班轮次无关的历史性提醒。 + +## 额外判断维度 + +在同优先级内,再按这些维度排序: + +1. 是否在等待维护者,而不是等待作者。 +2. 是否影响新贡献者体验或版本节奏。 +3. 是否能通过一次短动作明显降低队列风险。 +4. 是否会牵连多个 PR、Issue 或模块。 +5. 是否存在明显的 reviewer 负载再平衡空间。 +6. 是否属于“已分配但无人推进”的责任失效。 + +## 建议阈值 + +如果仓库没有自定义规则,默认使用下面的启发式阈值: + +- Issue 首响超时:24 小时 +- PR 首次 review 超时:72 小时 +- `approve` 后无人推进:48 小时 +- 作者按 review 更新后无人复看:48 小时 +- assignee / reviewer 名下条目长期停滞:5 到 7 天 +- reviewer 高负载预警:同一时间挂 4 个以上待处理 PR diff --git a/skills/gitlink-notification-digest/EXAMPLES.md b/skills/gitlink-notification-digest/EXAMPLES.md deleted file mode 100644 index 7c52285..0000000 --- a/skills/gitlink-notification-digest/EXAMPLES.md +++ /dev/null @@ -1,306 +0,0 @@ -# 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 deleted file mode 100644 index 72cf9df..0000000 --- a/skills/gitlink-notification-digest/SKILL.md +++ /dev/null @@ -1,311 +0,0 @@ ---- -name: gitlink-notification-digest -version: 2.0.0 -description: "通知摘要:汇总 GitLink 通知并按类型分类,生成通知摘要报告,支持批量标记已读。当用户需要查看通知摘要、整理通知、清理未读通知时触发。" -metadata: - requires: - bins: ["gitlink-cli"] ---- - -# gitlink-notification-digest(通知摘要) - -**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md),其中包含认证、权限处理和 API 注意事项。** -**CRITICAL — 标记已读为写操作,执行前需确认用户意图。** -**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`(GitHub CLI)操作 GitLink 资源。** - -> **前置条件:** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。 -> **执行样例:** 参见 [`EXAMPLES.md`](EXAMPLES.md) - ---- - -## 功能概述 - -帮助用户高效管理 GitLink 通知(GitLink 平台称为「消息」): - -1. **通知列表** — 获取所有未读通知 -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 -# 获取未读通知(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 -``` - -**参数说明:** - -| 参数 | 位置 | 说明 | -|------|------|------| -| `{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` 字段分类 - -| 类型 | `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` 枚举参考:** - -
-展开查看全部 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 - 立即** | 含 `Atme` 的消息(IssueAtme, PullReuqestAtme) | -| **P1 - 今天** | 自己管理的仓库有 PR 合并/关闭,或被分配的 Issue/PR 有更新 | -| **P2 - 本周** | 关注的仓库有新 PR、新 Issue | -| **P3 - 可忽略** | 点赞(ProjectPraised)、成员加入/离开、Fork 等系统通知 | - -### Step 3:生成通知摘要 - -按下方输出模板生成报告。 - -### Step 4:标记已读(可选,需确认) - -```bash -# 标记单条已读 -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 -``` - -> ⚠️ **执行前必须确认用户意图** — 标记已读为写操作。 -> ⚠️ **GitLink 没有批量已读 API**,需要逐条标记。 - ---- - -## 输出模板 - -```markdown -# 🔔 通知摘要 - -> 生成时间:{{当前时间}} -> 未读通知:{{unread_count}} 条 / 总计:{{total_count}} 条 - ---- - -## 一、概要 - -| 类型 | 未读 | 总计 | -|------|------|------| -| @提及 | {{mention_unread}} | {{mention_total}} | -| Issue 更新 | {{issue_unread}} | {{issue_total}} | -| PR 更新 | {{pr_unread}} | {{pr_total}} | -| 系统通知 | {{system_unread}} | {{system_total}} | -| 其他 | {{other_unread}} | {{other_total}} | - ---- - -## 二、需要立即处理(P0) - -> 如无,输出:*🎉 无紧急通知。* - -| # | 类型 | 仓库 | 内容摘要 | 时间 | -|---|------|------|----------|------| -| 1 | 🔴@提及 | {{repo}} | {{summary}} | {{time}} | - ---- - -## 三、今天处理(P1) - -> 如无,输出:*无待处理通知。* - -| # | 类型 | 仓库 | 内容摘要 | 时间 | -|---|------|------|----------|------| - ---- - -## 四、本周关注(P2) - -> 如无,输出:*无需要本周关注的通知。* - ---- - -## 五、可忽略(P3) - -> 如本段被折叠,输出:*{{p3_count}} 条低优先级通知,已折叠。* - ---- - -## 六、通知趋势 - -| 时间段 | 通知数 | -|--------|--------| -| 今日 | {{today_count}} | -| 昨日 | {{yesterday_count}} | -| 本周 | {{week_count}} | -| 上周 | {{last_week_count}} | - ---- - -## 七、近期已读回顾 - -> 列出最近 3-5 条已读但值得回顾的通知(如角色变更、PR 合并等)。 - ---- - -## 操作建议 - -- 建议标记已读:{{suggest_read_count}} 条 P3 通知 -- 需要回复/处理:{{need_action_count}} 条 P0/P1 通知 - -如需标记 P3 通知为已读,我可以逐条执行: -`gitlink-cli api POST "users/{owner}/messages/{id}/read"` -``` - ---- - -## 异常场景处理 - -| 场景 | 处理方式 | -|------|----------| -| 无未读通知 | 输出"🎉 所有通知已处理完毕" | -| 通知数量 > 50 | 分页获取(page 1/2/3),优先分析最近 50 条 | -| API 返回 HTML 而非 JSON | 路径可能以 `/` 开头导致解析错误,去掉前导 `/` 重试 | -| `unread_notification` > messages 数组长度 | 存在多页数据,追加 `--query "page=2"` 获取 | -| 用户名不确定 | 先执行 `gitlink-cli auth status` 获取当前登录用户 | - ---- - -## 注意事项 - -- ✅ **所有命令使用 `--format json`**,确保可解析 -- ✅ **标记已读为写操作**,执行前必须确认用户意图 -- ✅ **本 Skill 默认只读分析**,仅在用户明确要求时标记已读 -- ⚠️ **`gitlink-cli api` 路径不要以 `/` 开头**(CLI Bug) -- ⚠️ **GitLink 用「消息(messages)」而非「通知(notifications)」** -- ⚠️ **`source` 字段 `PullReuqestAtme` 是官方拼写错误**,实际使用注意匹配 -- ⚠️ **通知可能分页**,数量 >20 时需追加 `--query "page=2"`