diff --git a/skills/gitlink-community-ops/EXAMPLES.md b/skills/gitlink-community-ops/EXAMPLES.md new file mode 100644 index 0000000..9413aed --- /dev/null +++ b/skills/gitlink-community-ops/EXAMPLES.md @@ -0,0 +1,187 @@ +# gitlink-community-ops · EXAMPLES(执行流程演示) + +> 本文档记录 AI Agent(Claude Code)如何针对真实仓库 **jiangtx/gitlink-cli** 执行 `gitlink-community-ops` Skill,完成「新 Issue 自动分类 → 分配责任人 → 定期生成社区周报 → 自动发布 Release Notes」的社区运营端到端自动化。 + +--- + +## 1. 仓库背景 + +- **jiangtx/gitlink-cli** 是 `gitlink-cli` 的 fork 仓库,托管于 GitLink 平台。 +- 仓库包含完整的社区协作要素:Issue(缺陷/需求/咨询)、Pull Request、贡献者、Release、里程碑。 +- 主要贡献者:**wyxfzgg**(上游主导)、**jiangtx**(fork 维护者)、**林迪文** 等。 +- 典型协作节奏:上游提 PR 合并 → fork 跟随同步;社区用户通过 Issue 反馈安装/编码/认证问题。 +- 调用约束:owner = `jiangtx`、repo = `gitlink-cli`;所有操作只能用 `gitlink-cli`,禁止用 `gh`。 + +--- + +## 2. 触发示例 + +**用户自然语言请求**: + +> "帮我把 jiangtx/gitlink-cli 这周的社区运营跑一遍:把最近攒着的新 Issue 分分类、指派给对应的人,顺手出一份本周社区周报,顺便看看最近合并的 PR 够不够发个小版本。" + +**Agent 意图判定**:命中 `gitlink-community-ops` 的「全流程触发模式」,覆盖 SKILL.md 的 Step1 → Step5(数据采集 → Issue 分诊 → 社区动态汇总 → 周报撰写 → Release 发布)。 + +--- + +## 3. Agent 执行流程(分步) + +> 下面每步均遵循 SKILL.md:标注「动作说明 → 调用的 gitlink-cli 命令 → 作用 → 预期输出」。只读步骤直接执行;写入步骤(⚠️)在执行前回显方案给用户确认。 + +### Step 0:意图确认与参数锁定(编排前置) + +- **动作说明**:Agent 解析用户请求,确认走「全流程模式」,锁定 `owner=jiangtx`、`repo=gitlink-cli`;询问版本号意向(暂不强制)。 +- **调用**:无命令,纯对话确认。 +- **作用**:避免多余写入;符合 SKILL.md「Agent 第一步先与用户确认走哪种模式」。 +- **预期输出**:Agent 回复确认参数与模式,例如: + > "确认参数:owner=jiangtx / repo=gitlink-cli,模式=全流程(分诊 + 周报 + Release 候选)。只读采集会直接做,写入(批量改 Issue、发布 Release)前会先给你过目。是否继续?" + +--- + +### Step 1:数据采集(纯命令,只读) + +- **动作说明**:拉取开放 Issue 与贡献者列表,识别「无标签 / 无 assignee / 长期未更新」三类待处理 Issue,作为 Step2 的分诊输入。 +- **调用的命令与作用**: + + | 命令 | 作用 | + |---|---| + | `gitlink-cli issue +list --owner jiangtx --repo gitlink-cli --state open --limit 50 --format json` | 拉取开放 Issue,解析待处理集合 | + | `gitlink-cli export +contributors --owner jiangtx --repo gitlink-cli --format json --output contributors.json` | 导出贡献者(用于 Step2 派单与 Step3 人物榜) | + | `gitlink-cli export +issues --owner jiangtx --repo gitlink-cli --state all --format json --output issues.json` | 导出全部 Issue 供分析趋势 | + +- **预期输出(示例,非真实数值)**: + - `issue +list` 返回 JSON 数组,每条含 `id / number / title / labels / assignees / updated_at`。 + - Agent 解析后给出结构化小结(示例): + > "当前开放 Issue 共 N 条;其中无标签 X 条、无责任人 Y 条、超过 14 天未更新 Z 条,将进入 Step2 分诊。" + - `contributors.json`、`issues.json` 落地到工作目录(目录需预建,见 gitlink-cli tooling 备注)。 + +--- + +### Step 2:Issue 自动分类与分配(🤖AI 判断点 + ⚠️写入命令) + +- **动作说明**:调用子 Skill **`gitlink-issue-triage`**;先拉取仓库可用元数据(标签/优先级/可分配人员),由 AI 结合 Issue 标题与正文给出分类与责任人方案;回显给用户确认后,批量更新落地。 +- **调用的命令与作用**: + + | 命令 | 作用 | + |---|---| + | `gitlink-cli workflow +triage --owner jiangtx --repo gitlink-cli --state open --limit 50 --lang zh-CN --format json` | 内置分诊规则给出初步分类(bug/feature/优先级) | + | `gitlink-cli issue +priorities --owner jiangtx --repo gitlink-cli` | 仓库可用优先级枚举 | + | `gitlink-cli issue +tags --owner jiangtx --repo gitlink-cli` | 仓库可用标签枚举 | + | `gitlink-cli issue +assigners --owner jiangtx --repo gitlink-cli` | 可分配人员(注意:返回空 ≠ 不能指派,可结合 `member +list` 取 user-id) | + | ⚠️ `gitlink-cli issue +series-update --owner jiangtx --repo gitlink-cli --ids --status open` | 批量更新状态/字段(确认后执行) | + +- **🤖AI 判断点**:对每个待处理 Issue,结合 title/body 与贡献者擅长领域(如认证/编码类问题派 wyxfzgg,fork 维护与文档派 jiangtx,UI/文案相关派 林迪文),决定 优先级 + 标签 + 责任人,组装批量参数。 +- **预期输出(示例)**: + - 分诊方案表(示例片段): + + | Issue# | 标题(示例主题) | 建议标签 | 优先级 | 责任人 | + |---|---|---|---|---| + | #12 | 中文用户名路径乱码 | bug · encoding | high | wyxfzgg | + | #15 | exe 不在 PATH | bug · install | medium | jiangtx | + | #18 | +assigners 返回空 | bug · issue | medium | 林迪文 | + + - ⚠️确认话术(SKILL.md 规定): + > "共 N 条 Issue,预计修改状态/标签/责任人,是否执行 `issue +series-update`?" + - 用户确认后执行,返回更新条数与成功/失败计数。 + +--- + +### Step 3:社区动态汇总(🤖AI 判断点,调用两个子 Skill) + +- **动作说明**:调用子 Skill **`gitlink-notification-digest`**(通知聚合)与 **`gitlink-contributor-insight`**(贡献者活跃度),为周报产出结构化中间结果。 +- **调用的命令与作用**: + + | 命令 | 作用 | + |---|---| + | `gitlink-cli notification +list --limit 50 --format json` | 拉取通知(默认未读),去重归类为 PR/Issue/Release/CI | + | `gitlink-cli repo +activity --owner jiangtx --repo gitlink-cli` | 仓库活跃曲线,量化本周热度 | + | `gitlink-cli user +heatmap --login jiangtx` | 贡献热力图(可选其他贡献者) | + | `gitlink-cli user +stats --login jiangtx` | 个人统计数据 | + +- **🤖AI 判断点**: + - 通知去重归类,提炼本周待办(如「待 review 的 PR」「待回复的 Issue」)。 + - 识别「本周新晋贡献者 / Top 活跃 / 需感谢的人」,输出结构化中间结果供 Step4 引用。 +- **预期输出(示例)**: + > "本周通知归类:PR 相关 N 条、Issue M 条、CI K 条;待办 Top3:①review PR#xx ②回复 Issue#12 ③跟进 CI 失败。贡献者洞察:新晋 1 位、Top 活跃 wyxfzgg / jiangtx、建议致谢:林迪文。" + +--- + +### Step 4:撰写社区周报(🤖AI 判断点) + +- **动作说明**:汇总 Step1–3 结构化结果,按固定五板块撰写 `WEEKLY-REPORT.md`;落盘前向用户展示大纲。 +- **调用**:以 AI 撰写为主;可选 `gitlink-cli pm +weekly --project ` 补充官方周报数据(需项目 ID,此处 fork 仓库通常无项目 ID,可跳过)。 +- **周报板块(SKILL.md 规定)**: + 1. 本周数据概览(新增 Issue N / 合并 PR M / 新贡献者 K) + 2. 重点 Issue 进展 + 3. 贡献者榜单 + 4. 待跟进事项 + 5. 下周计划 +- **预期输出(示例大纲)**: + > 大纲:①数据概览(开放 Issue ↓X、合并 PR +M、新贡献者 1)②重点进展(编码乱码修复、assigner 指派异常排查)③贡献者榜(wyxfzgg / jiangtx / 林迪文)④待跟进(3 条 review、1 次 CI 报红)⑤下周(发版候选、补全文档)。确认后即落盘 `WEEKLY-REPORT.md`。 + +--- + +### Step 5:Release 候选与发布(🤖AI 判断点 + ⚠️写入命令) + +- **动作说明**:调用子 Skill **`gitlink-release-auto`** 与 **`gitlink-release-notes`**;采集自上 tag 以来的合并 PR 与提交,判定是否值得发版,按 conventional commits 分组生成 Release Notes;确认版本号后发布。 +- **调用的命令与作用**: + + | 命令 | 作用 | + |---|---| + | `gitlink-cli repo +tags --owner jiangtx --repo gitlink-cli` | 最近 tag,确定发版起点 | + | `gitlink-cli repo +commits --owner jiangtx --repo gitlink-cli` | 自上 tag 以来提交 | + | `gitlink-cli pr +list --owner jiangtx --repo gitlink-cli --state closed --limit 50` | 近期 PR(筛选已合并) | + | `gitlink-cli repo +compare --owner jiangtx --repo gitlink-cli --base --head master` | 完整 diff 摘要 | + | `gitlink-cli release +list --owner jiangtx --repo gitlink-cli` | 确认目标 tag 未被占用 | + | ⚠️ `gitlink-cli release +create --owner jiangtx --repo gitlink-cli --tag --name "" --body "" --target master` | 发布 Release(确认后执行) | + +- **🤖AI 判断点**: + - 判断变更是否值得发版(仅文档微调则建议跳过)。 + - 按 feat/fix/perf/docs 分组,识别 BREAKING CHANGE。 + - 生成 Release Notes 正文,让用户确认版本号(major/minor/patch)。 +- **预期输出(示例)**: + > "自上个 tag 以来共合并 N 个 PR,含 1 个 feat、2 个 fix,无 BREAKING CHANGE → 建议发 patch 版本。Release Notes 草稿(Features / Bug Fixes / Docs)已生成。确认版本号后执行 `release +create`。" + - 发布成功返回 Release 标题与访问入口(URL 形式)。 + +--- + +## 4. 最终产物 + +一次完整执行的交付物清单: + +| 产物 | 形态 | 说明 | +|---|---|---| +| `contributors.json` / `issues.json` | 数据文件 | Step1 采集的结构化原始数据 | +| **分诊执行结果** | 操作回执 | Step2 批量更新条数、责任人分配结果 | +| **周报中间结果** | 结构化文本 | Step3 通知归类 + 贡献者洞察 | +| **`WEEKLY-REPORT.md`** | 社区周报 | Step4 五板块周报,落盘到工作目录 | +| **Release Notes + 新版本 Release** | 发版产物 | Step5 发布的 tag 与 Release 页面 | + +**执行清单(Agent 末尾自报)示例**: +> "本次社区运营完成:分诊 Issue N 条(指派 wyxfzgg / jiangtx / 林迪文);周报已生成于 `<工作目录>/WEEKLY-REPORT.md`;判定可发版,已发布 Release ``。" + +--- + +## 5. ✅ 验证检查清单 + +- [ ] owner=jiangtx / repo=gitlink-cli 参数正确,未误用 `gh`。 +- [ ] 已先阅读 `gitlink-shared/SKILL.md` 的认证/权限/API 注意事项。 +- [ ] Step1 只读采集未产生任何写入。 +- [ ] Step2 的 `issue +series-update` 执行前已回显分诊方案并获用户确认。 +- [ ] Step3 通知/贡献者数据已去重、归类,无重复计数。 +- [ ] Step4 周报包含五板块齐全,落盘前展示过大纲。 +- [ ] Step5 发版前已用 `release +list` 确认 tag 未被占用。 +- [ ] `release +create` 的 tag / name / body 已回显预览并确认版本号。 +- [ ] 导出文件目录已预建(避免 export 写盘失败)。 +- [ ] 中文路径/编码问题已规避(ASCII 工作目录 + UTF-8)。 +- [ ] 末尾输出完整执行清单(分诊条数 / 周报路径 / Release 入口)。 + +--- + +## 6. 备注 + +- 本文档为 **「执行流程演示」**,基于 `gitlink-community-ops/SKILL.md` 的 Agent 执行设计编写,展示触发条件、编排步骤、调用的 `gitlink-cli` 命令与预期产物。 +- 文中所有「预期输出 / 示例」均为说明性占位,**非真实线上 API 数值**,不冒充实跑结果;实际条数、ID、URL 以在已登录的 Claude Code 中真实执行 `gitlink-cli` 的返回为准。 +- 支持裁剪触发:仅 Issue 分类(Step1→2)、仅周报(Step1→3→4)、仅 Release(Step5);Agent 第一步先与用户确认模式。 +- 已知注意点(来自记忆):预编译 exe 不在 PATH 须全路径调用;`issue +assigners` 返回空 ≠ 不能指派,可用 `member +list` 取 user-id 后通过 `--assigner-ids` 指派;中文用户名路径易致 CLI 乱码,统一用 ASCII 工作目录。 +- **完整线上验证需在已登录(GitLink 令牌有效)的 Claude Code 中执行本流程。** diff --git a/skills/gitlink-contributor-growth/EXAMPLES.md b/skills/gitlink-contributor-growth/EXAMPLES.md new file mode 100644 index 0000000..2377440 --- /dev/null +++ b/skills/gitlink-contributor-growth/EXAMPLES.md @@ -0,0 +1,277 @@ +# gitlink-contributor-growth · EXAMPLES(执行流程演示) + +> 本文档演示 Claude Code(AI Agent)如何针对真实仓库 **jiangtx/gitlink-cli** 执行「贡献者成长体系」Skill:追踪 PR/Issue 活动 → 生成贡献排行 → 自动颁发徽章 → 产出成长报告。 + +一句话概述:面向 fork 仓库做月度贡献回顾,用 gitlink-cli 串联 contributor-insight / user / commit-quality / release-auto / issue 多个子能力,把活跃贡献者排成榜并公开授予徽章。 + +--- + +## 仓库背景 + +- `jiangtx/gitlink-cli` 是上游 `gitlink-cli` 的 fork。 +- 已知活跃贡献者:`wyxfzgg`、`jiangtx`、`林迪文`、`whzy`、`wangyue789`、`Mengz` 等。 +- 本例时间窗:**2026 年 6 月**(月度回顾)。 +- 计量口径:fork 场景按 **PR 维度**(非 commits)更贴合贡献实际。 + +--- + +## 触发示例 + +> **用户**:"做一次 jiangtx/gitlink-cli 的月度贡献回顾,生成贡献排行榜并给 Top 贡献者颁发徽章。" + +--- + +## Agent 执行流程 + +> 严格对应 `SKILL.md` 的 Step 0 ~ Step 6。每步标注:动作说明 / 调用命令 / 作用 / 预期输出。 + +### Step 0 · 🤖AI 澄清采集范围(AI 判断点) + +**动作**:Agent 向用户确认四要素,信息齐全则跳过。 + +**判定结果**: +- 目标仓库:`owner=jiangtx`、`repo=gitlink-cli` +- 时间窗:`2026-06-01 ~ 2026-06-30` +- 榜单维度:综合榜 + 四枚徽章(🏆月度之星 / 🔧修复达人 / 📖文档能手 / 🌱新人突破) +- 公开颁榜:是(Step4 在 Issue 评论颁奖) + +> 该步骤无 CLI 调用。 + +--- + +### Step 1 · 采集贡献数据(纯命令) + +**动作**:优先用 `export` 模块批量导出结构化数据,按 login 聚合,取 Top 候选。 + +**调用的命令**: +```bash +gitlink-cli export +contributors --owner jiangtx --repo gitlink-cli --format json --output contributors.json +gitlink-cli export +prs --owner jiangtx --repo gitlink-cli --format json --output prs.json +gitlink-cli export +issues --owner jiangtx --repo gitlink-cli --format json --output issues.json +``` +**作用**:稳定批量导出贡献者、PR、Issue 的 JSON,供聚合分析;字段不全时再补 `repo +contributors / +activity`。 + +**补充核验命令(按需)**: +```bash +gitlink-cli repo +contributors --owner jiangtx --repo gitlink-cli +gitlink-cli repo +activity --owner jiangtx --repo gitlink-cli +``` + +**预期输出(示例,非真实 API 数值)**: +```json +// contributors.json(节选) +[ + { "login": "wyxfzgg", "contributions": 34 }, + { "login": "jiangtx", "contributions": 28 }, + { "login": "林迪文", "contributions": 19 }, + { "login": "whzy", "contributions": 12 }, + { "login": "wangyue789", "contributions": 9 }, + { "login": "Mengz", "contributions": 6 } +] +``` + +**🤖AI 判断点**:读取三份 JSON,按 login 聚合 PR/Issue/评论/合并数;识别新人(首次贡献落在 6 月内);取 Top N(默认 15)候选。 + +--- + +### Step 2 · 🤖AI 深度分析(子 Skill 编排) + +**动作**:对 Top 候选调子 Skill 画像与打分。 + +**2.1 编排 `gitlink-contributor-insight`** —— 逐人活跃度、贡献类型(feature/bugfix/docs/refactor)、影响力。 + +**2.2 编排 `gitlink-commit-quality`** —— 代表性 PR 质量评估,给 0-100 质量分(规范、测试、聚焦度),避免只看数量。 + +**2.3 调 `gitlink-user` 核验 Top 5**: +```bash +gitlink-cli user +info --login wyxfzgg +gitlink-cli user +heatmap --login wyxfzgg +gitlink-cli user +stats --login wyxfzgg +# 对 jiangtx / 林迪文 / whzy / wangyue789 同样执行三条命令 +``` +**作用**:核验候选人资料、活跃热力、累计统计,为颁奖词引用真实数据。 + +**预期输出(示例)**: +``` +# user +info --login wyxfzgg +login: wyxfzgg +name: 王亿鑫 +followers: 42 +created_at: 2024-03-11 + +# user +heatmap --login wyxfzgg +2026-06-01: 5 2026-06-02: 3 ... 2026-06-30: 4 (连续活跃) + +# user +stats --login wyxfzgg +prs: 47 issues: 23 reviews: 88 +``` + +**🤖AI 综合打分(透明可解释)**: +``` +综合分 = 0.4*活跃度 + 0.3*质量分 + 0.2*影响力 + 0.1*趋势 +``` + +**示例打分(写入本地草稿 `scoring.md`,不提交)**: + +| rank | login | 活跃度 | 质量分 | 影响力 | 趋势 | 综合分 | 新人? | +|---|---|---|---|---|---|---|---| +| 1 | wyxfzgg | 92 | 88 | 85 | 90 | **89.9** | 否 | +| 2 | jiangtx | 86 | 84 | 90 | 82 | **85.6** | 否 | +| 3 | 林迪文 | 78 | 90 | 76 | 88 | **81.6** | 否 | +| 4 | whzy | 70 | 82 | 68 | 80 | **74.8** | 否 | +| 5 | wangyue789 | 66 | 78 | 60 | 92 | **70.6** | 是 | +| 6 | Mengz | 58 | 75 | 55 | 85 | **65.6** | 是 | + +--- + +### Step 3 · 🤖AI 生成排行榜 + 设计徽章(须用户确认) + +**动作**:根据综合分与贡献类型落定四枚徽章归属,并撰写颁奖词草稿(客观陈述、正向、≤120 字、引用真实数据)。 + +**徽章归属(草稿)**: + +| 徽章 | 获奖者 | 依据 | +|---|---|---| +| 🏆 月度之星 | wyxfzgg | 综合分第一 | +| 🔧 修复达人 | jiangtx | bugfix 类 PR 合并最多且质量分达标 | +| 📖 文档能手 | 林迪文 | docs 类贡献最多 | +| 🌱 新人突破奖 | wangyue789 | 时间窗内首次贡献即进 Top N | + +**颁奖词草稿(示例)**: +- 🏆 **@wyxfzgg**:本月提交 34 次贡献、合并 PR 12 个、参与 review 88 次,活跃与质量双高,是团队当之无愧的月度之星。 +- 🔧 **@jiangtx**:主导 7 个 bugfix PR 合并,质量分 84,修复了流水线与 issue 指派两类顽疾,稳如磐石。 +- 📖 **@林迪文**:贡献 6 篇文档 PR,质量分 90,把 Skill 编排与 API 认证讲得最清楚。 +- 🌱 **@wangyue789**:首次贡献即提交 9 次有效贡献、综合分 70.6,进步曲线最陡峭。 + +**⚠️强制确认**:Agent 把"榜单 + 徽章归属 + 颁奖词全文"复述给用户,确认或调整后才进入 Step4。 + +--- + +### Step 4 · 颁发徽章(纯命令,须先经 Step3 确认) + +**动作**:在仓库"贡献者公告 Issue"下逐条评论颁奖;若无则先建。 + +**4.1 查找公告 Issue**: +```bash +gitlink-cli issue +list --owner jiangtx --repo gitlink-cli --state open --limit 50 +``` +**作用**:定位已有贡献者公告 Issue;无则进入 4.2 创建。 + +**4.2 创建公告 Issue(若无)**: +```bash +gitlink-cli issue +create --owner jiangtx --repo gitlink-cli \ + --title "贡献者成长榜 · 2026-06" \ + --body "本月贡献回顾:覆盖 6 人,合并 PR X 个。榜单与徽章见下方评论。" +``` +**预期输出(示例)**:`Created issue #142` + +**4.3 颁发(每位获奖者一条 comment,每条发出前再次复述确认)**: +```bash +gitlink-cli issue +comment --owner jiangtx --repo gitlink-cli --number 142 \ + --body "🆔 @wyxfzgg | 🏅 🏆月度之星 | 📝 本月提交 34 次贡献、合并 PR 12 个、参与 review 88 次,活跃与质量双高,是团队当之无愧的月度之星。" + +gitlink-cli issue +comment --owner jiangtx --repo gitlink-cli --number 142 \ + --body "🆔 @jiangtx | 🏅 🔧修复达人 | 📝 主导 7 个 bugfix PR 合并,质量分 84,修复了流水线与 issue 指派两类顽疾,稳如磐石。" + +gitlink-cli issue +comment --owner jiangtx --repo gitlink-cli --number 142 \ + --body "🆔 @林迪文 | 🏅 📖文档能手 | 📝 贡献 6 篇文档 PR,质量分 90,把 Skill 编排与 API 认证讲得最清楚。" + +gitlink-cli issue +comment --owner jiangtx --repo gitlink-cli --number 142 \ + --body "🆔 @wangyue789 | 🏅 🌱新人突破奖 | 📝 首次贡献即提交 9 次有效贡献、综合分 70.6,进步曲线最陡峭。" +``` +**预期输出(示例)**:`Commented on issue #142`(×4) + +> 🤖AI 判断点:用户若要"静默颁奖"则跳过本步,仅在 Step5 报告列出。 + +--- + +### Step 5 · 🤖AI 生成成长报告(AI 判断点 + 写入命令) + +**动作**:撰写 `CONTRIBUTION-LEADERBOARD.md`,并调 `gitlink-release-auto` 提炼"本期亮点"。 + +**5.1 编排 `gitlink-release-auto` 提炼亮点**(输出 3-5 条结构化高光时刻,示例): +- 流水线健康度从 78% 提升至 96% +- issue 指派链路修复,`member +list` 可直接拿 user-id 指派 +- Skill 体系新增 contributor-growth 编排 +- commit-quality 质量分接入贡献排行 + +**5.2 写入仓库**(确认目标分支与路径后): +```bash +gitlink-cli repo +update-file --owner jiangtx --repo gitlink-cli \ + --filepath CONTRIBUTION-LEADERBOARD.md \ + --content "<报告全文>" \ + --message "docs: 更新贡献者成长榜 2026-06" +``` +(首次创建则用 `repo +create-file`,同参数。) + +> 🤖AI 判断点:用户若要本地落盘不入库,则写本地文件,跳过 CLI 写入。 + +--- + +### Step 6 · 🤖AI 总结输出(AI 判断点) + +**动作**:Agent 汇报执行结果。 + +**示例汇报**: +- 采集覆盖:6 人、PR X 个、Issue Y 个 +- 榜单:Top 3 = `wyxfzgg` / `jiangtx` / `林迪文` +- 颁奖:在 Issue #142 发出 4 条评论 +- 报告:`CONTRIBUTION-LEADERBOARD.md` 位于仓库根 +- 后续建议:是否周期执行(如每月 1 号自动跑);是否补 `release +create` 发版公告 + +--- + +## 最终产物 + +### 产物 1 · 贡献排行榜 + +合并 Step 2 打分表与 Step 3 徽章归属表,即完整排行榜(rank / login / 综合分 / 分项 / 徽章 / 新人标记)。 + +### 产物 2 · 徽章评论(Issue #142) + +见 Step 4.3 四条 comment 全文(🆔 @login | 🏅 徽章 | 📝 颁奖词)。 + +### 产物 3 · 成长报告 CONTRIBUTION-LEADERBOARD.md(结构) + +```markdown +# 贡献者成长榜 · jiangtx/gitlink-cli · 2026-06 + +## 头部 +- 时间窗:2026-06-01 ~ 2026-06-30 +- 仓库:jiangtx/gitlink-cli +- 覆盖人数:6 / 总 PR:X / 总 Issue:Y + +## 本期亮点 +(release-auto 提炼的 3-5 条高光时刻) + +## 完整排行榜 +| rank | login | 综合分 | 活跃度 | 质量分 | 影响力 | 趋势 | 徽章 | 新人? | + +## 徽章授予记录 +(颁奖词全文 ×4) + +## 致谢与展望 +``` + +--- + +## ✅ 验证检查清单 + +- [ ] Step0 四要素已与用户确认(owner/repo、时间窗、维度、是否公开) +- [ ] Step1 三份 export JSON 成功落盘,按 login 聚合无遗漏贡献者 +- [ ] Step2 综合分公式透明,`scoring.md` 草稿含分项与新人标记 +- [ ] Step3 榜单 + 4 枚徽章归属 + 颁奖词全文已复述并获用户确认 +- [ ] Step4 每条 comment 发出前再次复述;颁奖词客观、正向、无贬损 +- [ ] Step5 报告含 5 个段落(头部/亮点/排行/徽章/致谢),写入分支与路径已确认 +- [ ] Step6 汇报覆盖人数、Top3、颁奖 Issue 号、报告位置、后续建议齐全 +- [ ] 全程未使用 `gh` 操作 GitLink;所有写入操作均经用户确认 + +--- + +## 备注 + +- 本记录为「执行流程演示」,描述 Claude Code 执行 `gitlink-contributor-growth` Skill 的标准路径与命令串联方式,**非某次实跑日志**。 +- 文中"预期输出 / 示例"里的打分、贡献数、Issue 号、文件路径等均为**示意值**,用于说明命令串联与产物结构,不代表真实 API 返回;真实数值以命令实跑为准。 +- **可复现性边界**:Step0–2(分析)为**只读**,可安全重复执行;Step4 `issue +comment`、Step5 `repo +create-file` / `+update-file` 为**写操作**,执行前须由用户逐条确认。 +- **徽章红线**:徽章是对真实用户的公开评价,颁奖词须客观、正向、避免贬损,颁布前向用户复述最终文案。 +- **仓库背景**:`jiangtx/gitlink-cli` 为上游 `gitlink-cli` 的 fork,贡献维度按 **PR 维度**(非 commits)计量更贴合 fork 场景。 diff --git a/skills/gitlink-multi-repo-ops/EXAMPLES.md b/skills/gitlink-multi-repo-ops/EXAMPLES.md new file mode 100644 index 0000000..ff311ee --- /dev/null +++ b/skills/gitlink-multi-repo-ops/EXAMPLES.md @@ -0,0 +1,318 @@ +# gitlink-multi-repo-ops 示例集(EXAMPLES) + +> 记录 AI Agent(Claude Code)如何基于 [`SKILL.md`](./SKILL.md) 工作流,针对 **jiangtx/gitlink-cli(fork)** 与 **Gitlink/gitlink-cli(上游)** 两个真实仓库执行多仓库协同编排:跨仓 Issue 统一追踪、PR 状态看板、Release 协调发布。 + +--- + +## 1. 一句话概述 + +当用户需要"同时管理 / 对比 / 协调多个 GitLink 仓库"时,Agent 扮演"导演",循环调用 `issue / pr / release / insight / workflow` 等子 Skill 的 gitlink-cli 只读命令完成聚合分析,生成跨仓看板,并在用户显式确认后按拓扑顺序协调发布 Release。 + +--- + +## 2. 触发示例(用户自然语言请求) + +> **用户**:"帮我对齐一下 fork(`jiangtx/gitlink-cli`)和上游(`Gitlink/gitlink-cli`)的进度——两边各有多少未处理 Issue 和未合并 PR,fork 落后上游多少个 Release,能不能把这个月的改动协调发一个版本?先给我看统一看板,发布前等我确认。" + +这条请求同时包含: +- 跨仓统一看板(Issue + PR + Release 落差) +- Release 协调发布(且明确要求"发布前等我确认" → 触发 Step5 强制确认门禁) + +--- + +## 3. Agent 执行流程(分步) + +> 仓库清单:`repo_list = ["jiangtx/gitlink-cli", "Gitlink/gitlink-cli"]` +> 约定:以下"预期输出 / 示例"均为**示意结构**,非真实 API 数值,不代表实跑结果。 + +### Step 1:🤖 AI 解析仓库清单(AI 判断点) + +- **动作说明**:从自然语言中抽取规范化的 `owner/repo`,去重、补全大小写。本例两个仓库名都明确给出,无需枚举候选。 +- **调用命令**:本步为 AI 解析,无强制命令。仅当仓库名不明确时才枚举: + - `gitlink-cli repo +list --owner Gitlink --limit 50` + - **作用**:当用户只给组织名时拉取候选仓库,请用户圈定。 +- **🤖 AI 判断点**:清单为空或歧义时**必须暂停确认**,不得擅自推断。 +- **产出**:内部 `repo_list`,供后续循环。 +- **预期示例**: + ```text + repo_list: + - jiangtx/gitlink-cli # fork + - Gitlink/gitlink-cli # upstream + ``` + +--- + +### Step 2:跨仓库数据采集(纯命令,循环执行,全只读) + +对 `repo_list` 每个 repo 串行执行只读命令,结果按仓库归档到 `data/`。 + +#### Step 2.1 — 逐仓 Issue 采集 + +- **命令(每仓一次)**: + ```bash + gitlink-cli issue +list --owner jiangtx --repo gitlink-cli --state open --limit 50 + gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --limit 50 + ``` +- **作用**:拉取两仓全部开放 Issue,作为统一看板的 Issue 数据源。 +- **预期示例(示意结构)**: + ```json + [ + { "number": 87, "title": "导出 CSV 在 Windows 中文路径乱码", "labels": ["bug","P1"], "assignee": "..." }, + { "number": 91, "title": "release +create 对 fork 仓库 tag 冲突", "labels": ["bug","P0"], "assignee": null } + ] + ``` + +#### Step 2.2 — 逐仓 PR 采集 + +- **命令(每仓一次)**: + ```bash + gitlink-cli pr +list --owner jiangtx --repo gitlink-cli --state open --limit 50 + gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --limit 50 + ``` +- **作用**:拉取两仓开放 PR,识别"fork → 上游"回流 PR 与上游待合并 PR。 +- **预期示例(示意结构)**: + ```json + [ + { "number": 142, "title": "fix: 中文路径乱码(回流上游)", "head": "jiangtx:fix/encoding", "base": "main", "mergeable": "unknown" }, + { "number": 150, "title": "feat: release 协调拓扑排序", "head": "feature/release-coord", "base": "main", "mergeable": "true" } + ] + ``` + +#### Step 2.3 — 逐仓 Release 采集 + +- **命令(每仓一次)**: + ```bash + gitlink-cli release +list --owner jiangtx --repo gitlink-cli --limit 10 + gitlink-cli release +list --owner Gitlink --repo gitlink-cli --limit 10 + ``` +- **作用**:对比两仓最新 Release,计算 fork 落后上游的版本落差(协调发布的依据)。 +- **预期示例(示意结构)**: + ```json + [ + { "id": 100231, "tag_name": "v1.2.0", "name": "GitLink CLI v1.2.0", "created_at": "2026-05-10" } + ] + ``` + +#### Step 2.4 / 2.5 — 里程碑与仓库信息 + +- **命令(每仓一次)**: + ```bash + gitlink-cli milestone +list --owner jiangtx --repo gitlink-cli + gitlink-cli milestone +list --owner Gitlink --repo gitlink-cli + gitlink-cli repo +info --owner jiangtx --repo gitlink-cli + gitlink-cli repo +info --owner Gitlink --repo gitlink-cli + ``` +- **作用**:判断两仓是否共享同一里程碑(决定能否捆绑在同一发布批次);取默认分支、是否 fork 等元数据。 +- **🤖 AI 判断点(容错)**:某仓库采集失败(404 / 无权限)记入 `errors[]`,**不中断流程**,看板标注"采集失败"。 +- 全部 GET,安全无需确认。 + +--- + +### Step 3:🤖 AI 跨仓统一分析(AI 判断点) + +#### Step 3.1 — 逐仓仓库报告与健康度 + +- **命令(逐仓)**: + ```bash + gitlink-cli workflow +repo-report --repository jiangtx/gitlink-cli + gitlink-cli workflow +repo-report --repository Gitlink/gitlink-cli + gitlink-cli workflow +health --repository jiangtx/gitlink-cli + gitlink-cli workflow +health --repository Gitlink/gitlink-cli + ``` +- **作用**:取得每仓"未关闭 Issue / 未合并 PR / 距上次 Release 时长 / 健康分",供跨仓横向对比。 +- **预期示例(示意结构)**: + ```text + jiangtx/gitlink-cli | open_issues=12 | open_prs=5 | last_release=v1.1.3 (46天前) | health=B + Gitlink/gitlink-cli | open_issues=27 | open_prs=8 | last_release=v1.2.0 (61天前) | health=A- + ``` + +#### Step 3.2 — Issue 堆积时分类(可选) + +- **命令**: + ```bash + gitlink-cli workflow +triage --owner Gitlink --repo gitlink-cli --state open + ``` +- **作用**:上游 Issue 较多时做分诊,区分 bug / feature / 重复,便于看板按优先级归并。 + +#### Step 3.3 — 跨仓活跃度与贡献者对比(insight) + +- **命令(逐仓,Step4 前置采集)**: + ```bash + gitlink-cli repo +activity --owner jiangtx --repo gitlink-cli + gitlink-cli repo +activity --owner Gitlink --repo gitlink-cli + gitlink-cli repo +contributors --owner jiangtx --repo gitlink-cli --limit 10 + gitlink-cli repo +contributors --owner Gitlink --repo gitlink-cli --limit 10 + ``` +- **作用**:识别共享贡献者(回流 PR 作者)、判断两仓活跃节奏是否同步。 +- **🤖 AI 判断点**: + - 对比得出瓶颈仓库与风险仓库; + - 识别跨仓关联 Issue(如 fork 的 #87 与上游 #120 标题/标签相似 → 标注"已回流"); + - 汇总每仓 P0/P1 issue 与阻塞 PR,形成优先级矩阵。 + +--- + +### Step 4:🤖 AI 生成协同看板(AI 判断点,产物) + +- **动作说明**:综合 Step2/3 数据,撰写 `MULTI-REPO-DASHBOARD.md`(结构见下方第 4 节)。 +- **可选导出命令(用户提及"导出"时)**: + ```bash + gitlink-cli export +issues --owner jiangtx --repo gitlink-cli --output data/jiangtx_issues.csv + gitlink-cli export +prs --owner Gitlink --repo gitlink-cli --output data/gitlink_prs.csv + ``` +- **作用**:将看板原始数据落盘 CSV,便于离线分析或备份。 +- 全只读,无需确认。 + +--- + +### Step 5:🤖 AI Release 依赖判断(AI 判断点,关键决策) + +#### Step 5.1 — 发布分支冲突预检 + +- **命令(对发布相关 PR)**: + ```bash + gitlink-cli pr +check-merge --owner Gitlink --repo gitlink-cli --number 150 + gitlink-cli pr +check-merge --owner jiangtx --repo gitlink-cli --number 142 + ``` +- **作用**:确认回流 / 发布分支 PR 是否可干净合并,作为发布门禁。 +- **预期示例(示意)**:`{"number":150,"mergeable":true,"conflicts":[]}` 或 `{"number":142,"mergeable":false,"conflicts":["src/release.go"]}`。 + +#### Step 5.2 — 核对现有 Release + +- **命令**: + ```bash + gitlink-cli release +view --owner Gitlink --repo gitlink-cli --id 100231 + gitlink-cli release +view --owner jiangtx --repo gitlink-cli --id 100198 + ``` +- **作用**:确认版本号不冲突、确认 fork 当前基线版本。 +- **🤖 AI 判断点(依赖拓扑排序)**:fork 依赖上游 → 发布顺序为 **上游先、fork 后**(fork rebase / 合并上游后再打 tag)。 + ```text + 建议发布顺序: + 1. Gitlink/gitlink-cli → v1.3.0 (上游先行,含 PR #150) + 2. jiangtx/gitlink-cli → v1.3.0-fork.1 (fork 同步上游 v1.3.0 后再发) + ``` +- **🤖 AI 判断点(发布门禁)**:任一仓库存在阻断级未合并 PR 或 P0 issue,先警告,不得自动跳过。 +- **⚠️ 强制确认**:暂停,向用户确认发布计划与顺序;未确认**严禁**进入 Step6。 + +--- + +### Step 6:Release 协调发布(纯命令,需用户确认,串行) + +> 仅当用户在 Step5 明确批准后执行。按拓扑顺序逐仓串行,前一个失败则停止,避免半发布。 + +#### Step 6.1 — 上游先行发布 + +- **命令**: + ```bash + gitlink-cli release +create --owner Gitlink --repo gitlink-cli \ + --tag v1.3.0 --name "GitLink CLI v1.3.0" \ + --body "feat: release 协调拓扑排序;fix: 中文路径乱码" --target main + ``` +- **作用**:在上游创建 v1.3.0 Release。 +- **发布后核对**: + ```bash + gitlink-cli release +view --owner Gitlink --repo gitlink-cli --id + ``` + +#### Step 6.2 — fork 同步后再发布 + +- **前置**:fork 已 rebase / 合并上游 v1.3.0(由用户侧 Git 操作完成)。 +- **命令**: + ```bash + gitlink-cli release +create --owner jiangtx --repo gitlink-cli \ + --tag v1.3.0-fork.1 --name "GitLink CLI v1.3.0-fork.1 (jiangtx)" \ + --body "sync upstream v1.3.0" --target main + ``` +- **作用**:在 fork 创建对齐版本。 +- **发布后核对**: + ```bash + gitlink-cli release +view --owner jiangtx --repo gitlink-cli --id + ``` + +- **🤖 AI 判断点(失败处理)**:中间某仓失败,记录已成功与失败仓,回滚交由用户(**不擅自 `release +delete`**)。 +- **可选(用户明确要求清理"已发布修复"的 issue,再次确认后)**: + ```bash + gitlink-cli issue +batch-close --owner Gitlink --repo gitlink-cli --numbers 120,124 + ``` + +--- + +## 4. 最终产物 + +### 4.1 跨仓 Issue / PR 状态看板(`MULTI-REPO-DASHBOARD.md` 节选) + +#### ① 仓库总览表 + +| 仓库 | 类型 | 开放 Issue | 开放 PR | 最新 Release | 距今 | 健康分 | +|---|---|---|---|---|---|---| +| Gitlink/gitlink-cli | 上游 | 27 | 8 | v1.2.0 | ~61 天 | A- | +| jiangtx/gitlink-cli | fork | 12 | 5 | v1.1.3 | ~46 天 | B | + +#### ② 跨仓 Issue 看板(按优先级归并) + +| 优先级 | 上游 Issue | fork Issue | 关联 / 处置 | +|---|---|---|---| +| P0 | — | #91 release tag 冲突 | 阻断 fork 发布,先修 | +| P1 | #120 中文路径乱码 | #87(同源) | 已由 PR #142 回流上游 | +| P2 | #124, #130 … | — | 排期处理 | + +#### ③ 跨仓 PR 看板(可合并 / 阻塞 / 冲突) + +| PR | 所属仓库 | 方向 | 状态 | 备注 | +|---|---|---|---|---| +| #150 | Gitlink/gitlink-cli | feature→main | ✅ 可合并 | v1.3.0 纳入 | +| #142 | jiangtx/gitlink-cli | fork→上游回流 | ⚠️ 冲突 | 需 rebase 上游 | + +#### ④ Release 协调时间线 + +```text +D0 上游 Gitlink/gitlink-cli 发布 v1.3.0(含 PR #150) +D+1 fork rebase 上游 v1.3.0,解决 PR #142 冲突 +D+2 fork jiangtx/gitlink-cli 发布 v1.3.0-fork.1 +``` + +#### ⑤ 风险提示 + +- fork PR #142 与上游存在冲突,是本次协调发布的**关键路径**。 +- 上游已有 61 天未发版,Issue 堆积 27 个,建议本次 v1.3.0 后启动 triage。 +- fork 落后上游一个版本(v1.1.3 vs v1.2.0),存在漂移风险。 + +### 4.2 Release 协调方案(草案 → 用户确认 → 执行) + +```text +发布批次(单批次,拓扑序): + 1) Gitlink/gitlink-cli v1.3.0 tag=v1.3.0 target=main + 2) jiangtx/gitlink-cli v1.3.0-fork.1 tag=v1.3.0-fork.1 target=main + +门禁检查: + - [×] 上游 PR #150 check-merge = true + - [!] fork PR #142 check-merge = false → 需 rebase 后重检 + - [×] 无 P0 issue 残留于发布分支(#91 已修复) + +发布后核对:每仓 release +view 确认 tag/body 落库。 +``` + +--- + +## 5. ✅ 验证检查清单 + +- [ ] `repo_list` 已去重、大小写规范,含 fork 与上游两个仓库。 +- [ ] Step2 每仓都跑过 `issue +list`、`pr +list`、`release +list`、`milestone +list`、`repo +info`。 +- [ ] 采集失败的仓库在看板标注"采集失败",未中断整体流程。 +- [ ] Step3 已对两仓执行 `workflow +repo-report` 与 `workflow +health`,得到横向对比。 +- [ ] `MULTI-REPO-DASHBOARD.md` 含 5 个必备区块(总览表 / Issue 看板 / PR 看板 / Release 时间线 / 风险)。 +- [ ] Step5 已对发布相关 PR 执行 `pr +check-merge`,并完成依赖拓扑排序(上游→fork)。 +- [ ] 任一阻断级 PR / P0 issue 都已告警,未自动跳过。 +- [ ] **Step6 写操作已获用户显式确认**,且按拓扑顺序串行执行。 +- [ ] 每仓发布后执行 `release +view` 核对 tag 与 notes。 +- [ ] 发布失败时未擅自 `release +delete`,已交接用户决策。 + +--- + +## 6. 备注 + +- 本文档为 **「执行流程演示」**,严格基于 [`SKILL.md`](./SKILL.md) 的工作流(Step1→Step6)编写;文中"预期输出 / 示例"为**示意结构**,用于说明命令产出形态,**不代表真实 API 数值、非实跑截图**。 +- **可复现性边界**: + - **只读聚合**(Step1–Step4 的 `list / info / report / health / activity / contributors / export`)为实跑可复现部分,可在真实 GitLink 仓库上安全直接执行。 + - **写操作**(Step5 的决策、Step6 的 `release +create` / `issue +batch-close`)必须经**用户显式确认**后方可执行;失败回滚由用户决定,Agent 不擅自删除。 +- 仓库背景说明:`jiangtx/gitlink-cli` 为个人 fork,`Gitlink/gitlink-cli` 为上游主仓;二者通过回流 PR、版本同步形成多仓库协同关系,是本 Skill 的典型场景。 +- 本编排型 Skill 只做"导演",单仓深度操作细节(issue / pr / release / insight / workflow 各自的参数与边界)以对应子 Skill 的 SKILL.md 为准。 diff --git a/skills/gitlink-pr-gate/EXAMPLES.md b/skills/gitlink-pr-gate/EXAMPLES.md new file mode 100644 index 0000000..d27a4d1 --- /dev/null +++ b/skills/gitlink-pr-gate/EXAMPLES.md @@ -0,0 +1,325 @@ +# gitlink-pr-gate 示例集(EXAMPLES) + +> 本文演示 AI Agent(Claude Code)如何针对真实仓库 **jiangtx/gitlink-cli** 执行「代码质量看门人」Skill:PR 提交后自动 Review → 跑/核对 CI → 汇总结构化评论 → 质量达标自动合并。 + +--- + +## 一、仓库背景 + +- **目标仓库**:`jiangtx/gitlink-cli`,是上游 `gitlink-cli` 的 fork,仓库内既有同步类 PR,也有 feature/fix 类原创 PR。 +- **运行约定**(来自全局记忆):预编译的 `gitlink-cli` 可执行文件不在 PATH 中,须用**全路径**调用;中文用户名路径会让原生 CLI 输出乱码,因此工作目录统一用 ASCII 路径 + UTF-8。 +- **认证**:所有命令通过环境变量或配置文件读取 GitLink Token(详见 `../gitlink-shared/SKILL.md`)。 +- **本演示场景**:一位贡献者提交了 PR #25「feat: 新增 issue 批量指派命令」,作为代码质量看门人,Agent 需要对该 PR 做全流程把关。 + +--- + +## 二、触发示例 + +> **用户**:"帮我审查 `jiangtx/gitlink-cli` 的 PR #25,跑一下 CI,没问题就评论并合并。" + +这是一条典型的自然语言请求,命中 `gitlink-pr-gate` 的触发条件——"审查 PR + 把关合并质量"。Agent 解析出: + +- **owner**:`jiangtx` +- **repo**:`gitlink-cli` +- **PR 编号**:`25` +- **隐含意图**:审查 → CI 核对 → 评论 → 合并(全流程编排) + +--- + +## 三、Agent 执行流程 + +下面按 SKILL.md 的工作流分步执行。每步标注:动作类型(🤖AI 判断点 / 纯命令)、调用的 gitlink-cli 命令、作用、预期输出(示例,非真实 API 数值)。写操作(Step4 comment、Step5 merge)均标注 **[需确认]**。 + +--- + +### Step 0: 🤖AI 解析审查目标(AI 判断点) + +**动作说明**:用户已明确给出 PR #25,无需候选搜索。Agent 先确认 PR 存在并拿到基本信息(标题、源分支、作者、改动统计),为后续审查建立上下文。 + +**调用命令**: + +```bash +gitlink-cli pr +view --owner jiangtx --repo gitlink-cli --number 25 +``` + +**作用**:确认 PR 存在、获取元信息。 + +**预期输出(示例)**: + +``` +PR #25 feat: 新增 issue 批量指派命令 +状态: open +作者: contributor-a +源分支: feat/issue-bulk-assign → 目标分支: main +改动: 5 files changed, +120 / -30 +创建于: 2026-07-09 +``` + +> 🤖AI 判断:PR 存在且为 open、feature 类、源/目标分支清晰,进入 Step1 采集变更。 + +--- + +### Step 1: 采集 PR 变更(纯命令,只读) + +**动作说明**:拉取审查所需的全部素材——完整 diff、变更文件清单、提交历史。本步全部只读,无需用户确认。 + +**调用命令(三条并列只读命令)**: + +```bash +gitlink-cli pr +diff --owner jiangtx --repo gitlink-cli --number 25 +gitlink-cli pr +files --owner jiangtx --repo gitlink-cli --number 25 +gitlink-cli pr +commits --owner jiangtx --repo gitlink-cli --number 25 +``` + +**作用**: +- `+diff`:拿到逐行变更,作为 Step2 语义审查的输入。 +- `+files`:拿到变更文件清单,快速定位审查范围。 +- `+commits`:拿到提交历史,作为 Step2 提交规范检查的输入。 + +**预期输出(示例)**: + +``` +# pr +files +cmd/issue_bulk.go (新增) +85 +cmd/issue_bulk_test.go (新增) +20 +internal/assigner/bulk.go (新增) +15 +README.md (修改) +5 / -3 +docs/issue-bulk.md (修改) -27(旧文档清理) + +# pr +commits +8a3f1c2 feat: 新增 issue 批量指派命令 +2b9e0d1 docs: 更新批量指派说明 +``` + +> 🤖AI 判断:5 个文件、+120/-30、2 个提交,范围可控,适合全量语义审查。 + +--- + +### Step 2: 🤖AI 代码审查(AI 判断点 + 子 Skill) + +**动作说明**:本步是编排核心,Agent 调用两个子 Skill 做语义审查与规范检查,并做可合并性预检。 + +#### 2.1 调用子 Skill:`gitlink-code-review` + +**动作说明**:对 Step1 的 diff 做语义分析,覆盖逻辑错误、边界条件、空指针、资源泄漏、安全隐患(注入/鉴权/敏感信息)、性能与可读性。 + +**调用命令(子 Skill 内部)**: + +```bash +# 子 Skill gitlink-code-review 的语义审查入口(示意,实际由子 Skill 封装) +gitlink-cli pr +diff --owner jiangtx --repo gitlink-cli --number 25 +``` + +**作用**:拉取 diff 后交由 AI 做语义级问题挖掘。 + +**预期输出(示例)**: + +``` +审查发现: +- internal/assigner/bulk.go:18 未校验 user-id 为空 → 空指派风险(建议) +- cmd/issue_bulk.go:42 单函数 60 行,建议拆分(可读性,建议) +- 未发现注入/鉴权类安全问题 +- 资源管理:HTTP client 正常关闭,无泄漏 +``` + +#### 2.2 调用子 Skill:`gitlink-commit-quality` + +**动作说明**:检查提交规范——Conventional Commits(feat/fix/docs/...)、PR 描述完整性、分支命名。 + +**调用命令(子 Skill 内部)**: + +```bash +gitlink-cli pr +commits --owner jiangtx --repo gitlink-cli --number 25 +``` + +**预期输出(示例)**: + +``` +提交规范: + ✅ 8a3f1c2 feat: ... 符合 Conventional Commits + ✅ 2b9e0d1 docs: ... 符合 Conventional Commits + ✅ 分支名 feat/issue-bulk-assign 符合规范 + ⚠️ PR 描述缺少「测试方式」一节 +``` + +#### 2.3 可合并性预检(纯命令,辅助) + +**调用命令**: + +```bash +gitlink-cli pr +check-merge --owner jiangtx --repo gitlink-cli --number 25 +``` + +**作用**:检查与目标分支是否有冲突。 + +**预期输出(示例)**: + +``` +可合并: ✅ 无冲突 +``` + +> 🤖AI 判断(分级): +> - 🔴 阻断问题:**无** +> - 🟡 建议改进:①`bulk.go:18` 校验空 user-id;②`issue_bulk.go:42` 拆分长函数;③PR 描述补充「测试方式」 +> - 🟢 亮点:提交信息规范、含单元测试、文档同步更新 + +--- + +### Step 3: CI 检查(纯命令 + 子 Skill) + +**动作说明**:调子 Skill `gitlink-ci-health` 核对该 PR 相关构建状态,必要时查失败日志。 + +#### 3.1 调用子 Skill:`gitlink-ci-health` + +**调用命令**: + +```bash +gitlink-cli ci +builds --owner jiangtx --repo gitlink-cli --limit 10 +``` + +**作用**:拉取最近构建列表,定位该 PR 触发的流水线。 + +**预期输出(示例)**: + +``` +build #1120 PR #25 push success 2026-07-10 10:21 +build #1119 PR #25 push success 2026-07-10 09:58 +build #1118 main push success 2026-07-09 22:10 +``` + +#### 3.2(失败时才查日志) + +**调用命令**: + +```bash +gitlink-cli ci +logs --owner jiangtx --repo gitlink-cli --number 1120 +``` + +**作用**:仅在 CI 失败时排查根因。本例 CI 全绿,**跳过**。 + +> 🤖AI 判断: +> - CI 全绿(build #1120、#1119 均 success)→ 客观质量达标 +> - 无 CI 失败、无未跑记录 + +--- + +### Step 4: 🤖AI 汇总评审 → 发布评论(AI 判断点 + 写命令) **[需确认]** + +**动作说明**:综合 Step2 审查 + Step3 CI,生成结构化 Review 评论,**先把评论全文复述给用户确认**,确认后再用 `pr +comment` 发布。 + +**生成评论全文(示例)**: + +```markdown +## 🤖 自动审查结论 +**CI 状态**: ✅ 全绿(build #1120 / #1119) +**可合并**: 是(无 🔴 阻断问题、CI 全绿、无冲突) + +🔴 阻断问题: 无 + +🟡 建议改进: +- internal/assigner/bulk.go:18 — 建议校验 user-id 为空,避免空指派 +- cmd/issue_bulk.go:42 — 单函数较长(约 60 行),建议拆分 +- PR 描述建议补充「测试方式」一节 + +🟢 亮点: +- 提交信息符合 Conventional Commits(feat / docs) +- 已包含单元测试(issue_bulk_test.go) +- 文档与代码同步更新 +``` + +**调用命令(写入操作)** **[需确认]**: + +```bash +gitlink-cli pr +comment --owner jiangtx --repo gitlink-cli --number 25 --body "<上述评审全文>" +``` + +**作用**:将结构化 Review 评论发布到 PR #25。 + +**预期输出(示例)**: + +``` +评论已发布到 PR #25(comment id: 8877) +``` + +> ⚠️ 写操作:发布前已向用户复述全文并获得确认。 + +--- + +### Step 5: 🤖AI 质量达标判断 → 合并(AI 判断点 + 写命令) **[需确认]** + +**动作说明**:综合判断是否达标。 + +**达标条件核验**: +| 条件 | 结果 | +|---|---| +| 无 🔴 阻断问题 | ✅ | +| CI 全绿 | ✅ | +| 无合并冲突(`pr +check-merge`) | ✅ | + +**调用命令(写入操作)** **[需确认]**: + +```bash +gitlink-cli pr +merge --owner jiangtx --repo gitlink-cli --number 25 +``` + +**作用**:合并 PR #25 到 main。 + +**预期输出(示例)**: + +``` +PR #25 已合并到 main(merge commit: 9c4d2aa) +``` + +> ⚠️ 写操作:合并为高风险写操作,已把审查结论完整复述给用户,**用户明确确认后**才合并。 +> +> 🤖AI 判断(合并后可选,均需二次确认):若 PR 关联了 Issue(如 `fix #20`),可关闭相关 Issue;若关联里程碑,可更新里程碑进度——这些后续动作同样需要用户确认,本演示不再展开。 + +--- + +## 四、最终产物 + +### 4.1 已发布的结构化 Review 评论 + +即 Step4 的评论全文(见上),已作为 comment id 8877 发布到 PR #25。 + +### 4.2 合并决策记录 + +``` +仓库: jiangtx/gitlink-cli +PR: #25 feat: 新增 issue 批量指派命令 +作者: contributor-a +决策: ✅ 合并(达标) +合并提交: 9c4d2aa +依据: + - 代码审查: 无 🔴 阻断,3 项 🟡 建议(非阻断,已记录供后续迭代) + - 提交规范: 符合 Conventional Commits + - CI: 全绿(build #1120 / #1119) + - 冲突预检: 无冲突 + - 用户确认: 已对评论与合并分别确认 +``` + +--- + +## 五、✅ 验证检查清单 + +执行完该 Skill 后,逐项核对: + +- [ ] Step0:`pr +view` 返回的 PR 编号、状态(open)、分支与用户指定一致。 +- [ ] Step1:`pr +diff` / `+files` / `+commits` 三者均成功返回,diff 行数与 `pr +view` 的改动统计吻合。 +- [ ] Step2:`code-review` 已覆盖逻辑/安全/性能/可读性;`commit-quality` 已检查 Conventional Commits 与分支命名;`pr +check-merge` 已返回无冲突(或有冲突已被记录)。 +- [ ] Step3:`ci +builds` 能定位到该 PR 的构建记录;状态判定正确(全绿 / 失败 / 未跑三选一)。 +- [ ] Step4:结构化评论包含 CI 状态、可合并结论、🔴/🟡/🟢 三级清单;**评论发布前已复述全文给用户确认**。 +- [ ] Step5:达标条件三项(无阻断 + CI 全绿 + 无冲突)逐一核验;**合并命令仅在用户明确确认后执行**。 +- [ ] 写操作清单:`pr +comment`、`pr +merge` 两步均带 `[需确认]` 标注,无未经确认的写入。 +- [ ] 全程未使用 `gh`(GitHub CLI)操作 GitLink 资源——只用 `gitlink-cli`。 +- [ ] 输出路径与工作目录均为 ASCII,无中文用户名路径乱码。 + +--- + +## 六、备注 + +- **性质说明**:本文件为「**执行流程演示**」,基于 `SKILL.md` 的工作流设计而成。文中所有「预期输出」均为**示例**,用于说明命令的输出形态与 Agent 判断逻辑,**并非真实 API 返回数值的冒充实跑**。真实执行时,输出数值(comment id、build id、merge commit hash 等)以 GitLink 实际返回为准。 +- **写操作需确认**:Step4 的 `pr +comment`、Step5 的 `pr +merge` 均为写入操作。按 SKILL.md 的 CRITICAL 约定,**评论全文必须先复述给用户确认**,**自动合并必须把审查结论完整复述并经用户明确同意**。本演示中对应步骤均以 **[需确认]** 标注。 +- **AI 审查 ≠ 替代人工**:本 Skill 的 AI 代码审查是辅助判断,最终合并决策由用户拍板。若 Step2 发现 🔴 阻断问题或 Step3 CI 失败,则进入"不合并、列出需修改项"分支(对应 SKILL.md 工作流的 S8 分支),等待作者修复后重审。 +- **子 Skill 职责边界**:代码审查的深度仍由 `gitlink-code-review` / `gitlink-commit-quality` / `gitlink-ci-health` 各自负责,本 Skill 只编排调用顺序并做汇总判断,不替代任一子 Skill 的内部规则。 +- **命令串联规模**:本演示串联了 `pr +view`、`pr +diff`、`pr +files`、`pr +commits`、`pr +check-merge`、`ci +builds`、(可选 `ci +logs`)、`pr +comment`、`pr +merge` 共 8+ 个命令与 3 个子 Skill,满足 SKILL.md"≥3 个命令串联"的要求。 diff --git a/skills/gitlink-project-bootstrap/EXAMPLES.md b/skills/gitlink-project-bootstrap/EXAMPLES.md new file mode 100644 index 0000000..aefce52 --- /dev/null +++ b/skills/gitlink-project-bootstrap/EXAMPLES.md @@ -0,0 +1,291 @@ +# EXAMPLES — gitlink-project-bootstrap(项目一键初始化演示) + +> 记录 AI Agent(Claude Code)如何调用 `gitlink-project-bootstrap` Skill,从一句话需求出发,为 `jiangtx` 组织下的示例仓库 `demo-repo` 完成端到端初始化。 + +--- + +## 一句话概述 + +输入「项目描述」→ Agent 解析需求并确认 → 创建仓库骨架(README/LICENSE/CI)→ 初始化协作体系(label/milestone/member)→ 创建首批 Issue 与里程碑 → 配置 webhook → 输出初始化报告,实现一键拉起一个可协作的新项目。 + +--- + +## 触发示例(用户自然语言请求) + +> **用户**:「帮我在 jiangtx 组织下初始化一个叫 `demo-repo` 的 Go 项目,成员有小王和小李,先做成私有仓库。」 + +Agent 据此进入 `gitlink-project-bootstrap` 的 6 步工作流。 + +--- + +## Agent 执行流程 + +> 下方所有命令、参数严格遵循 [`SKILL.md`](./SKILL.md) 工作流与 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 的统一 Envelope 输出格式(`{ok, data, meta}`)。 +> 所有「预期输出」均为**格式示例**,其中的 ID、编号、时间戳等数值为**示意值**,不代表真实 API 回包。 + +### Step 1 · 🤖 AI 需求解析(含命令核验 + 强制确认) + +**动作说明**:Agent 从用户一句话中提取项目名、语言、描述、可见性、成员,对缺失字段标注「(推断)」并出示「初始化清单」等待确认;同时用只读命令核验操作者身份、反查成员用户 ID。 + +| # | 命令 | 作用 | +|---|------|------| +| 1 | `gitlink-cli user +me` | 核验当前登录的操作者身份(确认有 jiangtx 的写权限) | +| 2 | `gitlink-cli search +users -k 小王` | 反查「小王」的用户 ID,供 Step3 加成员使用 | +| 3 | `gitlink-cli search +users -k 小李` | 反查「小李」的用户 ID | + +**预期输出(示例,数值为示意)**: + +```jsonc +// user +me +{ + "ok": true, + "data": { "login": "jiangtx", "user_id": 10086, "name": "蒋同学" } +} + +// search +users -k 小王 +{ + "ok": true, + "data": [ { "id": 20001, "login": "xiaowang", "name": "小王" } ], + "meta": { "total_count": 1 } +} +``` + +**🤖 AI 产出「初始化清单」并等待确认(需确认 ❗)**: + +``` +- 项目名 : demo-repo +- 描述 : 示例 Go 项目——演示 gitlink-cli 一键初始化 +- 语言/技术栈 : Go(决定 README/CI 模板,将采用 go build / go test 模板) +- 可见性 : private(私有) +- owner : jiangtx +- 成员 : 小王(id=20001)、小李(id=20002) +- 缺省推断 : 里程碑名 "MVP"(推断)、License MIT(推断) +``` + +> ⚠️ 用户确认或修改清单后,才进入 Step2。**未确认不执行任何写入命令。** + +--- + +### Step 2 · 创建仓库骨架(写入,每个命令均需确认 ❗) + +**动作说明**:先用 `repo +create` 建空仓库;再由 Agent 按语言生成 README.md / LICENSE / CI 配置内容,逐个 `repo +create-file` 写入。 + +| # | 命令 | 作用 | +|---|------|------| +| 1 | `gitlink-cli repo +create --name demo-repo --description "示例 Go 项目——演示 gitlink-cli 一键初始化" --private true` | 在 jiangtx 下创建私有空仓库(需确认 ❗) | +| 2 | `gitlink-cli repo +create-file --owner jiangtx --repo demo-repo --filepath README.md --content "" --message "docs: add README"` | 写入 README(需确认 ❗) | +| 3 | `gitlink-cli repo +create-file --owner jiangtx --repo demo-repo --filepath LICENSE --content "" --message "docs: add LICENSE"` | 写入 MIT LICENSE(需确认 ❗) | +| 4 | `gitlink-cli repo +create-file --owner jiangtx --repo demo-repo --filepath .gitlink-ci.yml --content "" --message "ci: add pipeline config"` | 写入 CI 流水线配置(需确认 ❗) | + +**Agent 按 Go 栈生成的内容要点(示例,非真实回包)**: + +- `README.md`:项目标题、简介、`go build`/`go run`/`go test` 用法、目录约定。 +- `LICENSE`:标准 MIT 文本,` jiangtx`。 +- `.gitlink-ci.yml`:`stages: [build, test]`,`go build ./...` 与 `go test ./...`。 + +**预期输出(示例)**: + +```jsonc +// repo +create +{ + "ok": true, + "data": { + "identifier": "jiangtx/demo-repo", + "name": "demo-repo", + "private": true, + "web_url": "https://www.gitlink.org.cn/jiangtx/demo-repo" + } +} + +// repo +create-file(README) +{ + "ok": true, + "data": { "filepath": "README.md", "branch": "master", "commit": { "sha": "<示例 sha>", "message": "docs: add README" } } +} +``` + +> 💡 GitLink 默认主分支为 `master`(非 `main`),由 CLI 自动处理映射。 + +--- + +### Step 3 · 初始化协作体系(写入,加成员需确认 ❗) + +**动作说明**:建立标准标签体系(Agent 推荐配色)、创建首个里程碑、批量添加成员(先 `--dry-run` 预览,确认后正式添加)。 + +**3.1 标签体系(Agent 推荐配色)** + +```bash +gitlink-cli label +create --owner jiangtx --repo demo-repo --name bug --color "#d73a4a" +gitlink-cli label +create --owner jiangtx --repo demo-repo --name feature --color "#a2eeef" +gitlink-cli label +create --owner jiangtx --repo demo-repo --name documentation --color "#0075ca" +``` + +作用:建立 bug / feature / documentation 三类标准标签,供后续 Issue 分类。预期输出(示例): + +```jsonc +{ "ok": true, "data": { "id": 9001, "name": "bug", "color": "#d73a4a" } } +``` + +**3.2 里程碑** + +```bash +gitlink-cli milestone +create --owner jiangtx --repo demo-repo --name "MVP" +``` + +作用:创建首个里程碑 `MVP`(对应 API 字段 `fixed_version_id`),后续 Issue 可挂载其下。预期输出(示例): + +```jsonc +{ "ok": true, "data": { "id": 5001, "name": "MVP" } } +``` + +**3.3 批量加成员(先预览 → 确认 → 正式添加)** + +```bash +# Step A:预览(dry-run,不写入) +gitlink-cli member +batch-add --owner jiangtx --repo demo-repo --user-ids 20001,20002 --dry-run + +# Step B:用户确认后,去掉 --dry-run 正式添加(需确认 ❗) +gitlink-cli member +batch-add --owner jiangtx --repo demo-repo --user-ids 20001,20002 +``` + +作用:把小王、小李加入 demo-repo。预期输出(示例): + +```jsonc +// --dry-run 预览 +{ "ok": true, "data": { "dry_run": true, "to_add": [ {"user_id":20001,"login":"xiaowang"}, {"user_id":20002,"login":"xiaoli"} ] } } + +// 正式添加(默认角色 Developer) +{ "ok": true, "data": { "added": [ {"user_id":20001,"role":"Developer"}, {"user_id":20002,"role":"Developer"} ] } } +``` + +> 💡 角色可选 Manager / Developer / Reporter,默认 Developer;如需变更用 `member +role --user-id --role Developer`。 + +--- + +### Step 4 · 🤖 AI 推荐首批 Issue(写入,逐条需确认 ❗) + +**动作说明**:Agent 按 Go 项目类型推荐首批 Issue,与用户确认后逐条创建。CLI 创建 Issue 时会自动设置 `status_id=1`(新增)与 `priority_id=2`(正常)。 + +**Agent 推荐清单(示例)**: + +``` +1. 搭建项目结构(cmd/ internal/ go.mod) +2. 配置 CI 流水线联调(验证 .gitlink-ci.yml) +3. 编写使用文档与示例 +4. 搭建本地开发环境脚本 +5. 冒烟测试用例骨架 +``` + +```bash +gitlink-cli issue +create --owner jiangtx --repo demo-repo \ + --title "搭建项目结构" \ + --body "初始化 cmd/ internal/ go.mod 等标准目录结构" \ + --label bug \ + --milestone MVP +``` + +作用:创建首批 Issue,并打上标签、挂到 MVP 里程碑下。预期输出(示例): + +```jsonc +{ + "ok": true, + "data": { + "project_issues_index": 1, + "subject": "搭建项目结构", + "status_id": 1, + "priority_id": 2 + } +} +``` + +> 💡 `project_issues_index` 即网页 URL 中可见的 Issue 编号(如 `issues/1`),后续 `issue +view --number 1`、`issue +close --number 1` 均用此编号。 + +--- + +### Step 5 · 配置自动化(写入,需确认 ❗) + +**动作说明**:向用户询问 Webhook 回调 URL 后创建 webhook,并触发一次测试投递验证连通性。 + +```bash +# 1) 创建 webhook(需确认 ❗) +gitlink-cli webhook +create --owner jiangtx --repo demo-repo \ + --url https://ci.example.com/hook/demo-repo --events push,merge_request + +# 2) 用上一步返回的 webhook id 触发测试 +gitlink-cli webhook +test --owner jiangtx --repo demo-repo --id 68 +``` + +作用:`webhook +create` 注册推送/合并请求事件回调;`webhook +test` 触发一次 ping 投递以验证目标可达。预期输出(示例): + +```jsonc +// webhook +create +{ "ok": true, "data": { "id": 68, "url": "https://ci.example.com/hook/demo-repo", "events": ["push","merge_request"] } } + +// webhook +test +{ "ok": true, "data": { "id": 68, "test_event": "push", "status": "delivered" } } +``` + +> 💡 若测试投递失败(如目标不可达),不阻塞流程,统一在 Step6 报告中列出。 + +--- + +### Step 6 · 🤖 AI 输出初始化报告(调 onboarding) + +**动作说明**:调用子 Skill `gitlink-onboarding` 生成新人上手文档段落,并汇总整轮初始化结果;可选 `repo +info` 复核仓库状态。 + +```bash +# 可选:复核仓库状态 +gitlink-cli repo +info --owner jiangtx --repo demo-repo +``` + +**🤖 Agent 汇总的初始化报告(示例文案,数值为示意)**: + +``` +✅ 项目初始化完成 — jiangtx/demo-repo +- 仓库地址 : https://www.gitlink.org.cn/jiangtx/demo-repo (私有) +- 初始文件 : README.md / LICENSE(MIT) / .gitlink-ci.yml(Go) +- 标签 : bug / feature / documentation(共 3 个) +- 里程碑 : MVP +- 成员 : jiangtx(owner)、小王(Developer)、小李(Developer) +- 首批 Issue: #1 搭建项目结构 / #2 配置 CI 联调 / #3 编写文档 / #4 本地环境脚本 / #5 冒烟测试骨架 +- Webhook : id=68,events=push,merge_request,测试投递 delivered +- 新人上手 : (gitlink-onboarding 生成的引导段落) +``` + +--- + +## 最终产物 + +一次成功的初始化将在 GitLink 上产出: + +1. **新仓库** `jiangtx/demo-repo`(私有),地址 `https://www.gitlink.org.cn/jiangtx/demo-repo`。 +2. **初始配置文件**:`README.md`、`LICENSE`(MIT)、`.gitlink-ci.yml`(Go 构建/测试流水线)。 +3. **协作体系**:3 个标准标签、1 个里程碑 `MVP`、2 名 Developer 成员。 +4. **首批 Issue**:5 条挂载在 MVP 下的初始化任务。 +5. **自动化**:1 个 push/merge_request webhook(测试通过)。 +6. **新人引导**:由 `gitlink-onboarding` 生成的上手文档段落 + 初始化报告。 + +--- + +## ✅ 验证检查清单 + +- [ ] `gitlink-cli auth status` 已登录,且操作者对 `jiangtx` 有写权限。 +- [ ] Step1 出示的「初始化清单」已获用户确认(含推断字段)。 +- [ ] `jiangtx/demo-repo` 可访问且可见性为 private。 +- [ ] `README.md` / `LICENSE` / `.gitlink-ci.yml` 三文件均存在于默认分支 `master`。 +- [ ] 标签 bug / feature / documentation 颜色正确、数量 = 3。 +- [ ] 里程碑 `MVP` 存在;首批 Issue 均已挂载、编号连续。 +- [ ] 成员小王、小李角色正确(Developer)。 +- [ ] webhook id 已创建且 `webhook +test` 投递状态为 delivered。 +- [ ] 关键命令(repo +create / create-file / milestone +create)未报错(逐步熔断未触发)。 +- [ ] 初始化报告已生成,部分失败项(如有)已逐条列出。 + +--- + +## 备注 + +- **本文件为「执行流程演示」**:上述命令串联与「预期输出」用于说明 Agent 如何按 `SKILL.md` 的 6 步工作流编排,**不是真实 API 回包**;其中的 ID、编号、SHA、时间戳等均为**示意值**,实际以平台真实回包为准。 +- **所有写操作均需用户确认**:`repo +create` / `repo +create-file` / `label +create` / `milestone +create` / `member +batch-add`(正式)/ `issue +create` / `webhook +create` 在演示中均标注「需确认 ❗」,Agent 必须出示意图、获用户授权后才执行,避免在真实组织下误建资源。 +- **失败不自动回滚**:依据 `SKILL.md` 反模式约定,本 Skill **不**自动 `repo +delete`;如初始化中途失败,是否回滚由用户决定并授权。 +- **工具边界**:GitLink 资源一律用 `gitlink-cli`,禁止用 `gh` / `curl` 绕过;主分支默认 `master`,由 CLI 自动与本地 `main` 双向映射。 +- **成员/指派注意**:演示中成员 ID 由 `search +users` 反查;若后续 Issue 需指派,使用 `issue +create --assigner-ids `(成员能加入 ≠ 默认指派成功,需以 `--assigner-ids` 显式传值)。