Merge PR #210: feat(skills): 新增维护者交接与分支治理 Skills
# Conflicts: # skills/README.md
This commit is contained in:
commit
bb5a3f404d
|
|
@ -0,0 +1,43 @@
|
|||
# 维护者工作流 Skills
|
||||
|
||||
本次补充了两条面向仓库维护者的新 Skill,重点解决“交接信息散落”和“旧分支不敢清理”这两类高频但容易被忽略的问题。
|
||||
|
||||
## 新增内容
|
||||
|
||||
### 1. `gitlink-maintainer-handoff`
|
||||
|
||||
- 汇总站内消息、仓库健康度、开放 PR、开放 Issue 和最近发布
|
||||
- 输出可直接交给下一位维护者的 Markdown 交接摘要
|
||||
- 默认只读,适合值班交接、周报、比赛期间的维护汇总
|
||||
|
||||
### 2. `gitlink-branch-hygiene`
|
||||
|
||||
- 面向分支治理场景,识别默认分支、主分支别名、保护分支、无 PR 分支和可删除候选
|
||||
- 把 compare 的零差异返回 `[-2] 分支内容相同,无需创建合并请求` 解释为正常治理信号,而不是失败
|
||||
- 先输出计划,再要求用户确认删除,避免误删分支
|
||||
|
||||
## 文档与示例
|
||||
|
||||
- 新增 `skills/gitlink-maintainer-handoff/SKILL.md`
|
||||
- 新增 `skills/gitlink-maintainer-handoff/examples/gitlink-cli-maintainer-handoff.md`
|
||||
- 新增 `skills/gitlink-branch-hygiene/SKILL.md`
|
||||
- 新增 `skills/gitlink-branch-hygiene/examples/gitlink-cli-branch-hygiene.md`
|
||||
- 更新 `skills/README.md`
|
||||
|
||||
## 平台验证
|
||||
|
||||
本次示例在 Codex 中完成验证,触发方式为自然语言请求 + `gitlink-cli` 实际命令执行。Skill 本身仅依赖 Markdown 规则和标准 CLI 调用,也兼容 Claude Code、Cursor 等可读取 `SKILL.md` 的主流 Agent 平台。
|
||||
|
||||
## 本地验证命令
|
||||
|
||||
```bash
|
||||
go run . user +me --format json
|
||||
go run . api GET "users/Mengz/messages.json" --query "status=1&limit=20" --format json
|
||||
go run . workflow +repo-report --owner Gitlink --repo gitlink-cli --lang zh-CN --format markdown
|
||||
go run . workflow +pr-summary --owner Gitlink --repo gitlink-cli --number 209 --lang zh-CN --format markdown
|
||||
go run . issue +list --owner Gitlink --repo gitlink-cli --state open --limit 10 --format json
|
||||
go run . release +list --owner Gitlink --repo gitlink-cli --limit 3 --format json
|
||||
go run . branch +list --owner Gitlink --repo gitlink-cli --format json
|
||||
go run . compare +view --owner Gitlink --repo gitlink-cli --head fix/pr-review-journal-sync --base master --format json
|
||||
go run . compare +view --owner Gitlink --repo gitlink-cli --head main --base master --format json
|
||||
```
|
||||
|
|
@ -153,7 +153,8 @@ skills/
|
|||
| **gitlink-pm** | 项目管理 | 通过 Raw API 访问 |
|
||||
| **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes |
|
||||
| **gitlink-health** | 开源项目健康度 | 详情见SKILL.md |
|
||||
| **gitlink-research-profile** | 科研主体画像(人/团队) | `profile +ability`, `profile +major`, `profile +role` |
|
||||
| **gitlink-maintainer-handoff** | 维护者交接摘要 | `workflow +repo-report`, `pr +list`, `issue +list`, `release +list` |
|
||||
| **gitlink-branch-hygiene** | 分支治理与清理建议 | `branch +list`, `compare +view`, `pr +list`, `branch +delete` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -259,6 +260,10 @@ gitlink-cli org +info -i Gitlink
|
|||
- [gitlink-org/SKILL.md](gitlink-org/SKILL.md) - 组织命令
|
||||
- [gitlink-user/SKILL.md](gitlink-user/SKILL.md) - 用户命令
|
||||
|
||||
**维护者治理**:
|
||||
- [gitlink-maintainer-handoff/SKILL.md](gitlink-maintainer-handoff/SKILL.md) - 维护者交接摘要
|
||||
- [gitlink-branch-hygiene/SKILL.md](gitlink-branch-hygiene/SKILL.md) - 分支治理与清理建议
|
||||
|
||||
---
|
||||
|
||||
## ❓ 常见问题
|
||||
|
|
|
|||
|
|
@ -0,0 +1,188 @@
|
|||
---
|
||||
name: gitlink-branch-hygiene
|
||||
version: 1.0.0
|
||||
description: "分支治理与清理建议:识别默认分支、保护分支、无差异旧分支、无 PR 分支和潜在可删除分支,生成安全的分支治理计划。当用户需要整理仓库分支、降低分支噪音、准备清理旧分支时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli branch --help"
|
||||
---
|
||||
|
||||
# gitlink-branch-hygiene(分支治理与清理建议)
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md),其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — `branch +delete` 是破坏性操作,必须先输出清理计划,再在用户明确确认后逐条删除。**
|
||||
**CRITICAL — `compare +view` / `compare +files` 返回 `[-2] 分支内容相同,无需创建合并请求` 时,应将其解释为“分支与基线无差异”,而不是分析失败。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。**
|
||||
|
||||
> **前置条件:** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。
|
||||
> **执行样例:** 参见 [`examples/gitlink-cli-branch-hygiene.md`](examples/gitlink-cli-branch-hygiene.md)
|
||||
|
||||
---
|
||||
|
||||
## 功能概述
|
||||
|
||||
本 Skill 解决维护者日常很常见、但很容易因为怕误删而长期拖着不做的事情:分支治理。
|
||||
|
||||
它的目标不是“看到旧分支就删”,而是先把分支分成三类:
|
||||
|
||||
1. **保留**:默认分支、主分支别名、受保护分支、有开放 PR 的分支
|
||||
2. **人工确认**:无 PR 但可能还有内容差异、名称特殊、仍有保留价值的分支
|
||||
3. **可删除候选**:无 PR、无保护、与默认分支无差异、明显完成历史使命的分支
|
||||
|
||||
---
|
||||
|
||||
## 工作流:生成分支治理计划
|
||||
|
||||
### Step 1:获取全部分支
|
||||
|
||||
```bash
|
||||
gitlink-cli branch +list --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
重点字段:
|
||||
|
||||
- `name`
|
||||
- `default_branch`
|
||||
- `protected`
|
||||
- `has_pull_request`
|
||||
- `commit_time`
|
||||
- `commit_time_from_now`
|
||||
|
||||
### Step 2:获取开放 PR,建立“正在协作中的分支”集合
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --limit 50 --format json
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
- PR 列表可能混入非 open 状态,必要时按返回字段再次过滤
|
||||
- 只要某个分支仍被开放 PR 使用,就不能直接列入删除候选
|
||||
|
||||
### Step 3:对可疑分支做差异检查
|
||||
|
||||
对满足以下条件的分支,进一步执行 compare:
|
||||
|
||||
- 不是默认分支
|
||||
- 不是 `main` / `master` 主分支别名
|
||||
- 没有关联开放 PR
|
||||
- 当前未受保护
|
||||
|
||||
```bash
|
||||
gitlink-cli compare +view --owner <owner> --repo <repo> --head <branch> --base <default-branch> --format json
|
||||
```
|
||||
|
||||
必要时补充文件级差异:
|
||||
|
||||
```bash
|
||||
gitlink-cli compare +files --owner <owner> --repo <repo> --head <branch> --base <default-branch> --format json
|
||||
```
|
||||
|
||||
判断规则:
|
||||
|
||||
- 返回 `[-2] 分支内容相同,无需创建合并请求`:记为“零差异”
|
||||
- 返回正常 compare 数据:说明分支仍有内容差异,放入“人工确认”
|
||||
|
||||
### Step 4:分类输出
|
||||
|
||||
#### 一定保留
|
||||
|
||||
- 默认分支
|
||||
- `main` / `master` 主分支别名
|
||||
- `protected=true`
|
||||
- `has_pull_request=true` 或仍被开放 PR 引用
|
||||
- `release/`、`hotfix/`、`support/` 等维护分支
|
||||
|
||||
#### 人工确认
|
||||
|
||||
- 无 PR 但仍有内容差异
|
||||
- 名称带业务语义且最近仍有提交
|
||||
- 用户明确说明要保留的实验分支
|
||||
|
||||
#### 可删除候选
|
||||
|
||||
- 非默认分支
|
||||
- 非 `main` / `master`
|
||||
- 无开放 PR
|
||||
- 未受保护
|
||||
- 与默认分支零差异
|
||||
- 最近提交时间已明显落后,且名称不属于长期维护约定
|
||||
|
||||
### Step 5:用户确认后再执行删除
|
||||
|
||||
```bash
|
||||
gitlink-cli branch +delete --owner <owner> --repo <repo> --name <branch>
|
||||
```
|
||||
|
||||
执行策略:
|
||||
|
||||
- 一次删除一条,不要批量盲删
|
||||
- 每删除一条都重新确认剩余候选集合
|
||||
- 删除后重新跑 `branch +list`,确认结果已生效
|
||||
|
||||
---
|
||||
|
||||
## 输出模板
|
||||
|
||||
```markdown
|
||||
# 分支治理计划
|
||||
|
||||
> 仓库:{{owner}}/{{repo}}
|
||||
> 默认分支:{{default_branch}}
|
||||
> 生成时间:{{now}}
|
||||
|
||||
## 一、分支概览
|
||||
|
||||
- 总分支数:{{total}}
|
||||
- 受保护分支:{{protected_count}}
|
||||
- 开放 PR 使用中的分支:{{active_pr_count}}
|
||||
- 可删除候选:{{delete_candidate_count}}
|
||||
|
||||
## 二、保留分支
|
||||
|
||||
| 分支 | 原因 |
|
||||
|------|------|
|
||||
| {{branch}} | {{reason}} |
|
||||
|
||||
## 三、人工确认
|
||||
|
||||
| 分支 | 原因 | 下一步 |
|
||||
|------|------|--------|
|
||||
| {{branch}} | {{reason}} | {{next_action}} |
|
||||
|
||||
## 四、可删除候选
|
||||
|
||||
| 分支 | 原因 | 删除前最后确认 |
|
||||
|------|------|----------------|
|
||||
| {{branch}} | {{reason}} | {{check}} |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键注意事项
|
||||
|
||||
### 1. `main` 不等于“可删的非默认分支”
|
||||
|
||||
很多仓库虽然默认分支是 `master`,但仍会保留 `main` 作为兼容分支或迁移别名。遇到这种情况,应默认保留,除非维护者明确要求清理。
|
||||
|
||||
### 2. 保护分支优先于差异判断
|
||||
|
||||
即使 compare 显示和默认分支零差异,只要分支受保护,也应先归入“保留”或“人工确认”。
|
||||
|
||||
### 3. compare 的 `[-2]` 不是错误
|
||||
|
||||
GitLink compare 在零差异场景会返回错误码 `-2`,语义其实是“无差异”。Skill 必须把这个结果转成正常判断,避免误报。
|
||||
|
||||
### 4. 删除动作必须逐条确认
|
||||
|
||||
分支治理的价值来自“减少噪音”,不是“激进清空”。凡是有疑问的分支,都先留在“人工确认”而不是强删。
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- 先做只读报告,再做删除
|
||||
- 对每个候选分支写出“为什么删”和“删前还要看什么”
|
||||
- 对有 PR 但长期未推进的分支,优先建议“催进度 / 关闭 PR”,不是直接删分支
|
||||
- 报告建议用 Markdown 输出,便于直接贴到团队群或维护者交接文档中
|
||||
|
|
@ -0,0 +1,118 @@
|
|||
# gitlink-branch-hygiene 使用示例
|
||||
|
||||
> 触发方式:自然语言自动匹配
|
||||
> 日期:2026-06-11
|
||||
> Agent 平台:Codex
|
||||
> 验证状态:✅ 通过(命令全部真实执行,完成了分支分类和可删除候选识别)
|
||||
|
||||
---
|
||||
|
||||
## 用户输入
|
||||
|
||||
```text
|
||||
帮我看看 Gitlink/gitlink-cli 现在有哪些分支可以安全清理,先不要真的删除,给我一个治理计划。
|
||||
```
|
||||
|
||||
## Skill 触发
|
||||
|
||||
Agent 根据“分支”“清理”“治理计划”“先不要真的删除”等关键词,自动匹配 `gitlink-branch-hygiene`,并按只读优先策略执行。
|
||||
|
||||
---
|
||||
|
||||
## 执行过程摘要
|
||||
|
||||
### Step 1:读取分支列表
|
||||
|
||||
```bash
|
||||
gitlink-cli branch +list --owner Gitlink --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
得到 6 条分支:
|
||||
|
||||
| 分支 | 是否保护 | 是否有关联 PR | 最近提交 |
|
||||
|------|----------|---------------|----------|
|
||||
| master | 否 | 是 | 2天前 |
|
||||
| fix/pr-review-journal-sync | 否 | 否 | 9天前 |
|
||||
| test/slash-1778992192 | 是 | 否 | 25天前 |
|
||||
| main | 否 | 否 | 25天前 |
|
||||
| test/branch-skill-1778991125 | 是 | 否 | 25天前 |
|
||||
| test/unprotect-1778991372 | 是 | 否 | 25天前 |
|
||||
|
||||
### Step 2:读取开放 PR,避免误删协作分支
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --limit 50 --format json
|
||||
```
|
||||
|
||||
结果:当前仓库存在开放 PR,默认分支 `master` 仍在被协作流程使用,不能纳入删除候选。
|
||||
|
||||
### Step 3:检查无 PR 分支与默认分支的差异
|
||||
|
||||
先检查 `fix/pr-review-journal-sync`:
|
||||
|
||||
```bash
|
||||
gitlink-cli compare +view --owner Gitlink --repo gitlink-cli --head fix/pr-review-journal-sync --base master --format json
|
||||
```
|
||||
|
||||
返回:
|
||||
|
||||
```text
|
||||
[-2] 分支内容相同,无需创建合并请求
|
||||
```
|
||||
|
||||
结论:该分支与 `master` 已无内容差异,可视为零差异分支。
|
||||
|
||||
再检查 `main`:
|
||||
|
||||
```bash
|
||||
gitlink-cli compare +view --owner Gitlink --repo gitlink-cli --head main --base master --format json
|
||||
```
|
||||
|
||||
同样返回零差异,但由于 `main` 属于主分支别名,不直接列入删除候选。
|
||||
|
||||
---
|
||||
|
||||
## 生成的治理计划
|
||||
|
||||
```markdown
|
||||
# Gitlink/gitlink-cli 分支治理计划
|
||||
|
||||
> 生成时间:2026-06-11
|
||||
> 默认分支:master
|
||||
|
||||
## 一、分支概览
|
||||
|
||||
- 总分支数:6
|
||||
- 受保护分支:3
|
||||
- 可直接保留:5
|
||||
- 可删除候选:1
|
||||
|
||||
## 二、保留分支
|
||||
|
||||
| 分支 | 原因 |
|
||||
|------|------|
|
||||
| master | 默认分支,持续承载协作流程 |
|
||||
| main | 与 master 零差异,但属于主分支别名,默认保留 |
|
||||
| test/slash-1778992192 | 受保护分支,不做自动清理 |
|
||||
| test/branch-skill-1778991125 | 受保护分支,不做自动清理 |
|
||||
| test/unprotect-1778991372 | 受保护分支,不做自动清理 |
|
||||
|
||||
## 三、可删除候选
|
||||
|
||||
| 分支 | 原因 | 删除前最后确认 |
|
||||
|------|------|----------------|
|
||||
| fix/pr-review-journal-sync | 无开放 PR、未受保护、距今 9 天、与 master 零差异 | 确认没有外部流程仍引用该分支后,可执行 `branch +delete` |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 验证结论
|
||||
|
||||
| 检查项 | 结果 |
|
||||
|--------|------|
|
||||
| Skill 自动触发 | ✅ |
|
||||
| 能识别默认分支和保护分支 | ✅ |
|
||||
| 能把 `main` 识别为主分支别名而非误删对象 | ✅ |
|
||||
| 能识别无 PR 分支 | ✅ |
|
||||
| 能正确把 compare 的 `-2` 解释为“零差异” | ✅ |
|
||||
| 能输出只读的治理计划而不直接执行删除 | ✅ |
|
||||
|
|
@ -0,0 +1,200 @@
|
|||
---
|
||||
name: gitlink-maintainer-handoff
|
||||
version: 1.0.0
|
||||
description: "维护者交接摘要:汇总站内消息、开放 Issue/PR、最近发布和仓库风险,生成下一位维护者可直接接手的交接清单。当用户需要值班交接、日报/周报、维护汇总时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli workflow --help"
|
||||
---
|
||||
|
||||
# gitlink-maintainer-handoff(维护者交接摘要)
|
||||
|
||||
**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/gitlink-cli-maintainer-handoff.md`](examples/gitlink-cli-maintainer-handoff.md)
|
||||
|
||||
---
|
||||
|
||||
## 功能概述
|
||||
|
||||
本 Skill 面向项目维护者、值班同学和接手协作者,目标是在一次读取中回答四个问题:
|
||||
|
||||
1. 现在有没有需要立刻处理的站内消息或仓库风险
|
||||
2. 当前开放的 PR 和 Issue 哪些最值得优先跟进
|
||||
3. 最近一次发布之后,仓库当前处在什么状态
|
||||
4. 下一位维护者接手时,最先该做什么
|
||||
|
||||
适用场景:
|
||||
|
||||
- 日交接 / 周交接
|
||||
- 比赛或答辩期间的维护汇总
|
||||
- 仓库管理员换班
|
||||
- 长假前的维护状态封板
|
||||
|
||||
---
|
||||
|
||||
## 工作流:生成维护者交接摘要
|
||||
|
||||
### Step 1:确认当前账号和交接范围
|
||||
|
||||
```bash
|
||||
# 确认当前登录账号
|
||||
gitlink-cli user +me --format json
|
||||
|
||||
# 建议显式指定目标仓库,避免当前目录 remote 干扰
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
如果用户没有指定仓库,先确认当前目录的 `origin` 指向,再决定是否继续。
|
||||
|
||||
### Step 2:读取站内消息积压
|
||||
|
||||
```bash
|
||||
# 当前用户的未读站内消息
|
||||
gitlink-cli api GET "users/{login}/messages.json" --query "status=1&limit=20" --format json
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
- `unread_notification` 和 `unread_atme` 都要纳入摘要
|
||||
- 即使结果为 0,也要在报告里明确写出“当前无站内消息积压”
|
||||
- 消息读取属于只读;只有“标记已读”才算写操作
|
||||
|
||||
### Step 3:读取仓库治理总览
|
||||
|
||||
```bash
|
||||
# 一次性获取健康度、Issue 摘要和 PR 摘要
|
||||
gitlink-cli workflow +repo-report --owner <owner> --repo <repo> --lang zh-CN --format json
|
||||
```
|
||||
|
||||
重点提取:
|
||||
|
||||
- `health.health_score`
|
||||
- `risk_level`
|
||||
- `recommendations`
|
||||
- `issue_summary`
|
||||
- `pr_summary`
|
||||
|
||||
规则:
|
||||
|
||||
- 如果 `risk_level=high`,摘要顶部必须给出风险提示
|
||||
- `workflow +repo-report` 是交接总览,不足以替代单条 PR/Issue 跟进
|
||||
|
||||
### Step 4:拉取开放 PR 列表并识别交接重点
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --limit 20 --format json
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
- GitLink 的 PR 列表接口在部分场景下会返回额外状态,必要时按返回字段做客户端过滤
|
||||
- 优先保留最近创建、最近更新、标题明确、影响面较大的 PR
|
||||
- 对 1 到 3 个重点 PR,可继续补充 `workflow +pr-summary`
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +pr-summary --owner <owner> --repo <repo> --number <pr-number> --lang zh-CN --format markdown
|
||||
```
|
||||
|
||||
### Step 5:拉取开放 Issue 列表并识别阻塞项
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state open --limit 20 --format json
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
- `status_id=0` 视为“状态异常但仍需人工确认”的开放 Issue,不要直接忽略
|
||||
- 优先关注最近更新时间新、描述明确、影响 CLI 可用性的缺陷
|
||||
- 如果仓库没有标签体系,允许用标题关键词和更新时间代替标签判断优先级
|
||||
|
||||
### Step 6:查看最近发布状态
|
||||
|
||||
```bash
|
||||
gitlink-cli release +list --owner <owner> --repo <repo> --limit 3 --format json
|
||||
```
|
||||
|
||||
重点提取:
|
||||
|
||||
- 最近 release 的 `tag_name`
|
||||
- `published_at`
|
||||
- `target_commitish`
|
||||
- 附件数量(用于判断资产是否完整)
|
||||
|
||||
### Step 7:生成可直接交接的 Markdown 摘要
|
||||
|
||||
输出时建议固定为以下结构:
|
||||
|
||||
```markdown
|
||||
# 维护者交接摘要
|
||||
|
||||
> 仓库:{{owner}}/{{repo}}
|
||||
> 生成时间:{{now}}
|
||||
> 接手账号:{{login}}
|
||||
|
||||
## 一、当前状态
|
||||
|
||||
- 站内消息:{{message_summary}}
|
||||
- 仓库风险:{{risk_level}}(健康分 {{health_score}})
|
||||
- 最近发布:{{latest_release}}
|
||||
|
||||
## 二、优先跟进的 PR
|
||||
|
||||
| PR | 标题 | 建议动作 |
|
||||
|----|------|----------|
|
||||
| #{{number}} | {{title}} | {{next_action}} |
|
||||
|
||||
## 三、优先跟进的 Issue
|
||||
|
||||
| Issue | 标题 | 风险提示 | 建议动作 |
|
||||
|-------|------|----------|----------|
|
||||
| #{{number}} | {{title}} | {{risk_note}} | {{next_action}} |
|
||||
|
||||
## 四、下一位维护者第一小时建议
|
||||
|
||||
1. {{first_action}}
|
||||
2. {{second_action}}
|
||||
3. {{third_action}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 输出规则
|
||||
|
||||
- 先写结论,再写证据,不要把原始 JSON 直接堆给用户
|
||||
- 没有数据时输出“无积压 / 无紧急项”,不要留空章节
|
||||
- 交接建议必须是动作导向句子,例如“先看 PR #209 的分页逻辑验证结果”
|
||||
- 如果仓库风险高,但站内消息为空,要明确说明“风险来自仓库治理数据而非消息积压”
|
||||
|
||||
---
|
||||
|
||||
## 异常场景处理
|
||||
|
||||
### 1. 消息列表为空
|
||||
|
||||
这不是失败,直接写明当前没有未读消息即可。
|
||||
|
||||
### 2. PR/Issue 列表返回数量异常
|
||||
|
||||
优先相信结构化返回字段,并在报告里标注“已按客户端规则过滤”。
|
||||
|
||||
### 3. `workflow +repo-report` 无法获取部分指标
|
||||
|
||||
保留已有结果,并在结论中注明“部分指标按保守策略评分”。
|
||||
|
||||
### 4. 用户希望顺手处理 PR / Issue
|
||||
|
||||
先完成交接摘要,再单独征求确认,避免把只读交接和写操作混在一起。
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- 交接报告优先使用 `--lang zh-CN`
|
||||
- 需要给下一位维护者看的内容,优先用 Markdown 输出
|
||||
- 需要给另一个 Agent 继续处理的内容,优先保留 JSON 结构化数据
|
||||
- 如果只打算看单个 PR,不要用 handoff 技能替代 `gitlink-code-review`
|
||||
|
|
@ -0,0 +1,153 @@
|
|||
# gitlink-maintainer-handoff 使用示例
|
||||
|
||||
> 触发方式:自然语言自动匹配
|
||||
> 日期:2026-06-11
|
||||
> Agent 平台:Codex
|
||||
> 验证状态:✅ 通过(命令全部真实执行,生成了可复用交接摘要)
|
||||
|
||||
---
|
||||
|
||||
## 用户输入
|
||||
|
||||
```text
|
||||
帮我给 Gitlink/gitlink-cli 生成一份今天的维护者交接摘要,我晚点要把仓库交给别人继续跟。
|
||||
```
|
||||
|
||||
## Skill 触发
|
||||
|
||||
Agent 识别到关键词“维护者”“交接摘要”“继续跟进”,自动匹配 `gitlink-maintainer-handoff`,并先读取 `gitlink-shared` 的认证和只读规则。
|
||||
|
||||
---
|
||||
|
||||
## 执行过程摘要
|
||||
|
||||
### Step 1:确认当前账号
|
||||
|
||||
```bash
|
||||
gitlink-cli user +me --format json
|
||||
```
|
||||
|
||||
结果:当前账号为 `Mengz`。
|
||||
|
||||
### Step 2:检查站内消息积压
|
||||
|
||||
```bash
|
||||
gitlink-cli api GET "users/Mengz/messages.json" --query "status=1&limit=20" --format json
|
||||
```
|
||||
|
||||
结果:未读消息为 `0`,说明当前没有站内消息积压。
|
||||
|
||||
### Step 3:获取仓库治理总览
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +repo-report --owner Gitlink --repo gitlink-cli --lang zh-CN --format markdown
|
||||
```
|
||||
|
||||
关键结果:
|
||||
|
||||
- 仓库综合分 `49`
|
||||
- 健康分 `58`
|
||||
- 风险等级 `high`
|
||||
- 建议优先审查长期未处理 PR,并补齐 README / CONTRIBUTING / LICENSE 相关治理项
|
||||
|
||||
### Step 4:提取开放 PR 焦点
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --limit 10 --format json
|
||||
```
|
||||
|
||||
抽取出的近期 PR 样本:
|
||||
|
||||
| PR | 标题 | 创建时间 |
|
||||
|----|------|----------|
|
||||
| #209 | feat(milestone): 增加里程碑进度分析快捷命令 | 2026-06-11 02:00 |
|
||||
| #208 | feat(user): add pinned project shortcuts | 2026-06-10 13:06 |
|
||||
| #207 | feat(user): add statistics shortcuts | 2026-06-10 13:06 |
|
||||
| #206 | feat(commit): add commit inspection shortcuts | 2026-06-10 13:05 |
|
||||
| #205 | fix(issue): 修复详情缺失并保护更新元数据 | 2026-06-10 11:32 |
|
||||
|
||||
对最新的 PR 再补充一份审阅摘要:
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +pr-summary --owner Gitlink --repo gitlink-cli --number 209 --lang zh-CN --format markdown
|
||||
```
|
||||
|
||||
结果:规则引擎将 `#209` 标为高风险关注项,建议重点复查命令兼容性、文档一致性和测试覆盖。
|
||||
|
||||
### Step 5:提取开放 Issue 焦点
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --limit 10 --format json
|
||||
```
|
||||
|
||||
关键结果:
|
||||
|
||||
- 当前开放 Issue 共 `8` 条
|
||||
- 最近更新的条目包括 `#6`、`#19`
|
||||
- `#15` 和 `#2` 的 `status_id=0`,属于需要人工确认的异常状态 Issue
|
||||
|
||||
### Step 6:查看最近发布
|
||||
|
||||
```bash
|
||||
gitlink-cli release +list --owner Gitlink --repo gitlink-cli --limit 3 --format json
|
||||
```
|
||||
|
||||
关键结果:
|
||||
|
||||
- 最近一次发布为 `v0.2.0`
|
||||
- 发布时间 `2026-06-09 01:23`
|
||||
- 目标分支 `master`
|
||||
- 发布资产数量 `6`
|
||||
|
||||
---
|
||||
|
||||
## 生成的交接摘要
|
||||
|
||||
```markdown
|
||||
# Gitlink/gitlink-cli 维护者交接摘要
|
||||
|
||||
> 生成时间:2026-06-11
|
||||
> 接手账号:Mengz
|
||||
|
||||
## 一、当前状态
|
||||
|
||||
- 站内消息:当前无未读消息积压,可以直接从仓库治理数据开始接手
|
||||
- 仓库风险:high,健康分 58,综合分 49
|
||||
- 最近发布:v0.2.0 已于 2026-06-09 发布到 master,附件 6 个,发布资产完整
|
||||
|
||||
## 二、优先跟进的 PR
|
||||
|
||||
| PR | 标题 | 建议动作 |
|
||||
|----|------|----------|
|
||||
| #209 | feat(milestone): 增加里程碑进度分析快捷命令 | 先复查分页边界和 README 示例是否一致 |
|
||||
| #208 | feat(user): add pinned project shortcuts | 确认批量更新和排序的 dry-run 语义 |
|
||||
| #205 | fix(issue): 修复详情缺失并保护更新元数据 | 重点看 edit 元数据保护逻辑是否覆盖失败路径 |
|
||||
|
||||
## 三、优先跟进的 Issue
|
||||
|
||||
| Issue | 标题 | 风险提示 | 建议动作 |
|
||||
|-------|------|----------|----------|
|
||||
| #19 | windows环境下部分Agent执行gitlink-cli命令失败 | 新近提交,可能影响 Agent 赛道可用性 | 尽快复现并确认影响范围 |
|
||||
| #18 | giklink-cli issue +update后issue状态框变红色 | 影响 Issue 更新可靠性 | 核对修复分支和回归测试 |
|
||||
| #15 | issue +view 返回的数据与网页显示不一致 | status_id=0,状态异常 | 人工确认服务端状态,再决定是否继续跟进 |
|
||||
|
||||
## 四、下一位维护者第一小时建议
|
||||
|
||||
1. 先看 `workflow +repo-report` 里提到的高风险项,把长期未处理 PR 列出跟进顺序。
|
||||
2. 然后处理 `#19` 和 `#18` 这类直接影响 CLI 使用体验的问题。
|
||||
3. 最后回看最近发布后的资产和文档项,确认后续 PR 是否补齐治理缺口。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 验证结论
|
||||
|
||||
| 检查项 | 结果 |
|
||||
|--------|------|
|
||||
| Skill 自动触发 | ✅ |
|
||||
| 能读取当前登录账号 | ✅ |
|
||||
| 能处理“无未读消息”场景 | ✅ |
|
||||
| 能汇总仓库健康度和风险等级 | ✅ |
|
||||
| 能提取近期 PR / Issue 焦点 | ✅ |
|
||||
| 能补充最近发布状态 | ✅ |
|
||||
| 交接摘要可直接交给下一位维护者使用 | ✅ |
|
||||
Loading…
Reference in New Issue