diff --git a/examples/workflows/zhangqing-task3/01-community-ops-automation.md b/examples/workflows/zhangqing-task3/01-community-ops-automation.md index 0996344..25e6a63 100644 --- a/examples/workflows/zhangqing-task3/01-community-ops-automation.md +++ b/examples/workflows/zhangqing-task3/01-community-ops-automation.md @@ -57,15 +57,46 @@ - URL: https://gitlink.org.cn/ylly/gitlink-cli/releases - name: `v0.2.0 Beta 1 — 任务三阶段版（预发布）` -## 任务二 Skill 串联关系 +## 任务二 Skill 蓝图对照（按 SKILL.md 行号） -| 步骤 | 使用的 Skill | 角色 | -|------|-------------|------| -| 1 | gitlink-issue-triage | Issue 分类 | -| 3 | gitlink-insight | 周报洞察 | -| 4 | gitlink-release-auto | 自动发版 | +本工作流每一步都严格按任务二 Skill 蓝图执行，Skill 是**设计蓝图**，本报告是蓝图的**落地执行**。 -3 个 Skill 串联，满足 PDF「≥3 命令/Skill 串联」要求。 +### 步骤 1 ← `gitlink-issue-triage/SKILL.md` 工作流 1（自动分类打标签） + +| 执行动作 | SKILL.md 蓝图位置 | 蓝图要求 | 实际执行 | +|---------|------------------|---------|---------| +| 拉开放 Issue | 第 58-62 行 Step 1 | `issue +list --state open` | ✅ 拉到 16 个 | +| 筛未分类 | 第 64-68 行 Step 2 | 过滤 `tags=[]` | ✅ 11 个未分类 | +| 读详情分类 | 第 70-78 行 Step 3-4 | 标题+描述语义分类 | ✅ 按中文标签语义归类 | +| 复用现有标签 | 第 80-91 行 Step 5 | **优先复用仓库已有中文标签** | ✅ 直接复用「测试/缺陷/功能/性能/疑问」未新建 | +| 打标签 | 第 93-99 行 Step 6 | `issue +update --label`（覆盖语义） | ✅ 11 个全部分类完成 | +| 输出报告 | 第 101-117 行 Step 7 | 表格汇总 | ✅ 见本报告步骤 1 表格 | + +**关键决策对照**：SKILL.md 第 91 行明确说"优先复用现有标签（含中文同义词），先匹配再考虑新建英文标签"。本仓库已有「缺陷/功能/文档」等中文标签，**未新建任何英文标签**，完全符合蓝图。 + +### 步骤 2 ← `gitlink-issue-triage/SKILL.md` 工作流 2（自动分配 + 通知） + +SKILL.md 第 125-146 行 Step 1-2 已**预判**此场景：个人仓库 `assigners` 返回空数组（第 133 行红框警告），按第 146 行"列表为空则跳过分配并在报告中标注"处理。✅ 实际执行与蓝图预判一致，跳过并在报告标注。 + +### 步骤 3 ← `gitlink-insight/SKILL.md` 工作流 2（Sprint 周报） + +| 执行动作 | SKILL.md 蓝图位置 | 蓝图要求 | 实际执行 | +|---------|------------------|---------|---------| +| 采集 Issue 数据 | 第 120-122 行 | closed + open issue | ✅ 16 open / 6 closed | +| 采集 PR 数据 | 第 123-125 行 | merged PR | ✅ 2 merged | +| 采集 Release | 第 126-128 行 | `release +list` | ✅ Release=0（发版前） | +| 风险标注 | 第 164-165 行 | 列风险与阻塞 | ✅ 标注"未发布 Release""测试类 Issue 可清理" | + +### 步骤 4 ← `gitlink-release-auto/SKILL.md` + +| 执行动作 | SKILL.md 蓝图位置 | 蓝图要求 | 实际执行 | +|---------|------------------|---------|---------| +| 版本号推荐 | 第 32-90 行 一、版本号推荐 | 按 Conventional Commits 分类推 Semver | ✅ feat 26/fix 17 → MINOR 升 → v0.2.0 | +| Release Notes 生成 | 第 94-145 行 二、自动生成 | 按类型分组 + 贡献者去重 | ✅ 按 Conventional Commits 分组，贡献者去重 | +| 预发布版本 | 第 179-189 行 三、预发布版本 | `--prerelease true` | ✅ 选 beta.1 预发布（等整合者发正式 v0.2.0） | +| 贡献者去重 | 第 145 行红框警告 | **必须去重** | ✅ 跨提交去重为 14 人 | + +**3 个 Skill 串联，满足 PDF「≥3 命令/Skill 串联」要求。** ## 关键避坑（本工作流踩到的） diff --git a/examples/workflows/zhangqing-task3/05-contributor-growth.md b/examples/workflows/zhangqing-task3/05-contributor-growth.md index f3a8166..35b9d78 100644 --- a/examples/workflows/zhangqing-task3/05-contributor-growth.md +++ b/examples/workflows/zhangqing-task3/05-contributor-growth.md @@ -44,4 +44,34 @@ （GitLink 无"用户主页评论"能力，改在 Issue 评论或新建颁奖 Issue 演示） **Step 3: 可选 — 新建颁奖 Issue** -创建一个 Issue「🏆 v0.2.0-beta.1 贡献者排行榜公布」，body 含本排行榜，用 @mention 提及 Top 贡献者，并打上「星级贡献者」label。 \ No newline at end of file +创建一个 Issue「🏆 v0.2.0-beta.1 贡献者排行榜公布」，body 含本排行榜，用 @mention 提及 Top 贡献者，并打上「星级贡献者」label。 + +--- + +## Skill 蓝图对照（按 SKILL.md 行号） + +### 取数阶段 ← `gitlink-insight/SKILL.md` 工作流 3（贡献者洞察） + +| 执行动作 | SKILL.md 蓝图位置 | 蓝图要求 | 实际执行 | +|---------|------------------|---------|---------| +| 贡献者列表 | 第 173-183 行 采集数据 | `contributors` + merged PR + user info | ✅ commits 走 `git log`（contributors API 返回 HTML，降级方案）+ merged PR + Issue 作者聚合 | +| 角色与活跃度 | 第 185-203 行 输出格式 | 排行 + 活跃度分布 | ✅ 综合积分公式 commits×1+PR×5+Issue×2，按贡献分层 | +| 三层分布 | 第 194-197 行 | 核心/活跃/新增 | ✅ 对应「星级/活跃/贡献者」三级徽章 | + +### 发奖阶段 ← `gitlink-issue-triage/SKILL.md` 工作流 1 + 通用 label 操作 + +| 执行动作 | SKILL.md 蓝图位置 | 蓝图要求 | 实际执行 | +|---------|------------------|---------|---------| +| 查现有标签 | 第 80-84 行 Step 5 | `label +list` 命中则复用 | ✅ 仓库原无徽章 label，3 个均新建 | +| 创建徽章 | 第 86-89 行 | `label +create --name --color` | ✅ 星级 394180 / 活跃 394181 / 贡献者 394182 | +| 颁奖 Issue | 第 101-117 行报告格式 | 表格 + @mention | ✅ Issue #17 已建并打「星级贡献者」label | + +### Skill 串联数 + +| 步骤 | 使用的 Skill/命令 | 角色 | +|------|------------------|------| +| 1 | git log + issue +list + pr +list（insight 工作流 3 数据源） | 取数 | +| 2 | label +create（issue-triage 工作流 1 Step 5） | 建徽章 | +| 3 | issue +create + issue +update --label（issue-triage 工作流 1 Step 6） | 颁奖 | + +**3 步串联，满足 PDF「≥3 命令/Skill 串联」要求。** \ No newline at end of file diff --git a/examples/workflows/zhangqing-task3/07-onboarding-nanny.md b/examples/workflows/zhangqing-task3/07-onboarding-nanny.md index 0753836..f6fa06a 100644 --- a/examples/workflows/zhangqing-task3/07-onboarding-nanny.md +++ b/examples/workflows/zhangqing-task3/07-onboarding-nanny.md @@ -71,3 +71,49 @@ MSYS_NO_PATHCONV=1 ./gitlink-cli.exe api POST /v1/ylly/gitlink-cli/issues//jo 2. **issue +list 与 issue +view 的 tag 字段不一致**：list 用 `issue_tags` 且可能不返回，view 用 `tags` 字段才完整 3. **创建 issue 必须传 `done_ratio: 0`**，否则 MySQL 报 `Column 'done_ratio' cannot be null` 4. **issue create 时 issue_tag_ids 字段不生效**（GitLink bug），需创建后用 `issue +update --label ` 补打 + +--- + +## Skill 蓝图对照（按 SKILL.md 行号） + +本工作流 5 个 Step 严格按 `gitlink-onboarding/SKILL.md` 蓝图执行。 + +### Step 2 ← `gitlink-onboarding/SKILL.md` 工作流 1（good-first-issue 自动标记） + +| 执行动作 | SKILL.md 蓝图位置 | 蓝图要求 | 实际执行 | +|---------|------------------|---------|---------| +| 取开放 Issue | 第 54-58 行 Step 1 | `issue +list` | ✅ 17 个开放 Issue | +| 按识别标准评估 | 第 31-46 行 + 第 60-62 行 Step 2 | 5 条友好信号 + 3 条排除标准 | ✅ 3 个 docs 类入选，14 个按排除标准剔除 | +| 复用现有标签 | 第 64-74 行 Step 3 | 优先复用，无则建 | ✅ 仓库已有 good first label（id 382660），未新建 | +| 输出标记报告 | 第 84-95 行 Step 5 | 表格汇总 | ✅ `onboarding_identify_report.md` | + +**关键对照**：SKILL.md 第 44-46 行排除标准（性能优化/描述模糊/CI 部署）逐条复审 14 个未入选 Issue，全部命中排除理由（测试数据 / 模糊描述 / 性能 / 新功能开发）。 + +### Step 3 ← `gitlink-onboarding/SKILL.md` 工作流 2（引导评论生成） + +| 执行动作 | SKILL.md 蓝图位置 | 蓝图要求 | 实际执行 | +|---------|------------------|---------|---------| +| 读 Issue 详情 | 第 103-107 行 Step 1 | `issue +view` | ✅ #8/#13/#14 各取详情 | +| 生成个性化评论 | 第 109-117 行 Step 2 | **禁止固定模板**，4 要素（任务/文件/本地准备/PR 规范） | ✅ 3 条**完全不同**的评论，每条指向具体文件 | +| 发布评论 | 第 118-123 行 Step 3 | `issue +comment` | ✅ journals 478829/478830/478831（绕中文编码走 Raw API） | +| 个性化要求 | 第 205 行注意事项 | "避免对所有 Issue 用同一句" | ✅ #8 指 `wiki.go` / #13 指 `Makefile` / #13 指 `wiki +list --format json` | + +### Step 4 ← 通用通知能力 + +`notification +list` 自查询（受限）。`gitlink-shared/SKILL.md` 平台限制：只能查自己的通知。✅ 用 `--owner zhangqing23` 自查 13 条通知。 + +### Step 5 ← `gitlink-insight/SKILL.md` 工作流 3（贡献者洞察）交叉验证 + +通知 `[ProjectMemberJoined]` + `[ProjectPullRequest]` + `pr +list --state merged` 三源交叉 → 完整还原 ZxR123-Z 从入会到首次贡献全过程。该方法论对应 insight SKILL.md 第 173-203 行"贡献者列表 + PR 数据 + 用户信息"多源聚合。 + +### Skill 串联数 + +| 步骤 | 使用的 Skill/命令 | 角色 | +|------|------------------|------| +| 1 | member +invite-link | 邀请能力演示 | +| 2 | onboarding 工作流 1（识别） | good-first 识别 | +| 3 | onboarding 工作流 2（引导评论） | 个性化引导 | +| 4 | notification +list | 通知系统查看 | +| 5 | insight 工作流 3（交叉验证） | 首次贡献追踪 | + +**5 步串联，满足 PDF「≥3 命令/Skill 串联」要求。** diff --git a/examples/workflows/zhangqing-task3/README.md b/examples/workflows/zhangqing-task3/README.md index c7212de..921d9e6 100644 --- a/examples/workflows/zhangqing-task3/README.md +++ b/examples/workflows/zhangqing-task3/README.md @@ -30,6 +30,7 @@ | `05-contributor-growth.md` | ⑤ 贡献者排行榜 + 徽章授予方案 | | `07-onboarding-nanny.md` | ⑦ 新人保姆 5 步执行报告 | | `release-notes-v0.2.0-beta.1.md` | ① 发布的 Release Notes 全文 | +| `agent-dialogue-triggers.md` | **Agent 对话触发语**（PDF 首要产物：演示 Skill 驱动 Agent） | | `reproduce.sh` | **可复现脚本**（评委照着跑） | --- @@ -56,6 +57,26 @@ bash examples/workflows/zhangqing-task3/reproduce.sh --- +## 任务二 Skill 作为设计蓝图（PDF 核心：Skill = 设计蓝图） + +本目录的 3 份执行报告都新增了「Skill 蓝图对照」段，**逐动作引用 SKILL.md 行号**，证明每步执行都严格按蓝图落地： + +| 工作流 | 蓝图 SKILL.md 行号定位 | +|--------|----------------------| +| ① 步骤 1 分类 | `gitlink-issue-triage/SKILL.md` 工作流 1（第 54-117 行），含分类规则表第 35-50 行 | +| ① 步骤 2 分配（跳过）| `gitlink-issue-triage/SKILL.md` 第 125-146 行（蓝图预判个人仓库 assigners 为空）| +| ① 步骤 3 周报 | `gitlink-insight/SKILL.md` 工作流 2（第 116-166 行）| +| ① 步骤 4 发版 | `gitlink-release-auto/SKILL.md` 一/二/三（第 32-189 行），含预发布第 179-189 行 | +| ⑤ 取数 | `gitlink-insight/SKILL.md` 工作流 3（第 169-203 行）| +| ⑤ 发奖 | `gitlink-issue-triage/SKILL.md` 工作流 1 Step 5-6（第 80-117 行）| +| ⑦ Step 2 识别 | `gitlink-onboarding/SKILL.md` 工作流 1（第 50-95 行）+ 识别标准第 31-46 行 | +| ⑦ Step 3 引导 | `gitlink-onboarding/SKILL.md` 工作流 2（第 99-145 行）+ 个性化要求第 205 行 | +| ⑦ Step 5 追踪 | `gitlink-insight/SKILL.md` 工作流 3（第 169-203 行）多源聚合 | + +**意义**：评委打开任一报告的「Skill 蓝图对照」段，可拿着 SKILL.md 行号对照检查，验证"Skill 不是摆设，是真正驱动 Agent 执行的设计蓝图"。 + +--- + ## 关键技术发现（避坑） ### 1. GitLink API 路径双轨制 ⚠ diff --git a/examples/workflows/zhangqing-task3/agent-dialogue-triggers.md b/examples/workflows/zhangqing-task3/agent-dialogue-triggers.md new file mode 100644 index 0000000..53118f8 --- /dev/null +++ b/examples/workflows/zhangqing-task3/agent-dialogue-triggers.md @@ -0,0 +1,129 @@ +# Agent 对话触发语（PDF 核心：Agent 对话是首要产物） + +> 用途：评委/复现者在 Claude Code 里**逐字粘贴**下面任一条触发语，即可观察到 +> AI Agent 自动加载对应 Skill（按 SKILL.md 蓝图）→ 调 gitlink-cli 命令 → 串联多步 → 落地写入。 +> 把这个对话过程截图/录屏，就是 PDF 要求的「Agent 对话记录」产物。 + +--- + +## 为什么需要触发语 + +PDF「正确做法」明确： + +- **Agent 对话记录是首要产物**，脚本是辅助 +- **Skill 是设计蓝图**，不是配置文件 +- 必须能演示"Skill 真的被加载、真的驱动 Agent 执行" + +触发语的设计原则：**用自然语言匹配 SKILL.md 第 4 行 `description` 字段的触发语义**，让 Agent 自动识别并调用 Skill 工具。 + +--- + +## 前置准备（所有触发语共用） + +在 Claude Code 里先说一句建立上下文： + +``` +我在做 GitLink 端到端自动化任务三。目标仓库是 ylly/gitlink-cli， +我的登录账号是 zhangqing23（已是该仓库 Manager）。 +gitlink-cli.exe 在 C:/Users/Lenovo/Desktop/gitlink-cli/ 目录下，已 auth login。 +下面我会给你具体的自动化需求，请用任务二设计好的 Skill 来做。 +``` + +--- + +## 工作流 ① 触发语（社区运营自动化） + +**单条完整触发语**（推荐用于演示，一句话串起分类→周报→发版）： + +``` +请帮我对 ylly/gitlink-cli 做一次社区运营收尾： +1. 自动分拣所有未分类的开放 Issue（用 gitlink-issue-triage 工作流1）； +2. 生成一份项目周报（用 gitlink-insight 工作流2）； +3. 根据自上次发版以来的提交历史，推荐版本号并生成 Release Notes， + 先给我预览，确认后再发布（用 gitlink-release-auto）。 +每一步执行前告诉我你正在加载哪个 Skill、对应 SKILL.md 的哪一段。 +``` + +**分步触发语**（如果只想演示单步）： + +| Step | 触发语（直接粘贴） | 对应 Skill 蓝图 | +|:----:|-------------------|----------------| +| 1 | "帮我把 ylly/gitlink-cli 所有没标签的开放 Issue 自动分类打标签" | issue-triage 工作流 1 | +| 2 | "给我一份 ylly/gitlink-cli 本周的项目周报" | insight 工作流 2 | +| 3 | "根据 ylly/gitlink-cli 自上次发版以来的提交，推荐下一个版本号并生成 Release Notes" | release-auto 一、二 | + +**预期 Agent 行为**（截图要点）： +- Agent 会先说"使用 gitlink-issue-triage Skill" +- 调用 `issue +list --state open` → 筛未分类 → `issue +view` 读详情 → 按分类规则表归类 → `issue +update --label` +- 每步都会展示它对应 SKILL.md 的哪一段（这是"Skill 作为设计蓝图"的可视证据） + +--- + +## 工作流 ⑤ 触发语（贡献者成长体系） + +**单条完整触发语**： + +``` +请帮我对 ylly/gitlink-cli 建立贡献者成长体系： +1. 取仓库全历史的 commits（git log）+ merged PR（pr +list --state merged） + + Issue 作者（issue +list），生成一份综合积分排行榜（公式 commits×1 + PR×5 + Issue×2）， + 过滤掉测试号 15972095207 / 2403_89190320 / fsafasff； +2. 按三层标准授予徽章（星级/活跃/贡献者），先创建对应 label（颜色 #FFD700/#FF6B35/#87C95F）； +3. 建一个颁奖 Issue 公布排行榜并 @mention Top 贡献者。 +执行前先给我清单确认。 +``` + +**预期 Agent 行为**： +- Agent 调用 insight 工作流 3 的数据采集方法（第 173-183 行） +- 调用 issue-triage 工作流 1 Step 5 的 label 创建（第 86-89 行） +- 输出排行榜表格 + 颁奖动作清单等用户确认 + +--- + +## 工作流 ⑦ 触发语（新人全流程保姆） + +**单条完整触发语**： + +``` +请帮我对 ylly/gitlink-cli 做新人引导全流程： +1. 用 member +invite-link 演示邀请能力（仓库无真实新人账号，仅演示）； +2. 扫描开放 Issue，按新人友好识别标准找出适合新人的 Issue（onboarding 工作流1）； +3. 对找出的 good first Issue 写**完全个性化**的引导评论（onboarding 工作流2）， + 每条评论要定位到具体文件、给本地准备命令、写 PR 提交规范——禁止用同一模板； +4. 用 notification +list --owner zhangqing23 看通知动态； +5. 交叉验证通知 + Issue + PR 数据，还原一位新人从加入到首次贡献的全过程。 +写入操作前给我预览。 +``` + +**分步触发语**： + +| Step | 触发语 | 对应 Skill 蓝图 | +|:----:|-------|----------------| +| 2 | "帮我找出 ylly/gitlink-cli 适合新人的 Issue 并打 good first 标签" | onboarding 工作流 1 | +| 3 | "帮我给 ylly/gitlink-cli 适合新人的 Issue 写个性化引导评论" | onboarding 工作流 2 | + +**预期 Agent 行为**： +- 识别阶段会引用 onboarding SKILL.md 第 31-46 行的 5 条友好信号 + 3 条排除标准 +- 引导评论阶段会引用第 205 行"禁止对所有 Issue 用同一句"，每条评论定位不同文件 + +--- + +## 对话产物采集建议 + +录 Agent 对话时重点截这几段（对应 PDF 评分点）： + +1. **Skill 加载声明**：Agent 说"我将使用 gitlink-xxx Skill"的那一句 +2. **蓝图引用**：Agent 提到"按 SKILL.md 第 X-Y 行"的段落 +3. **命令调用**：Agent 调 gitlink-cli 的命令行（带参数） +4. **真实写入回执**：服务器返回的 `ok:true` / `id` / `version_id` 等 +5. **网页验证**：复制返回的 URL 到浏览器打开看到真实效果 + +--- + +## 与 reproduce.sh 的关系 + +| 产物 | 角色 | 适合谁看 | +|------|------|---------| +| **Agent 对话记录**（本文档触发的） | 首要产物，演示"Skill 驱动 Agent" | 评委看过程 | +| `reproduce.sh` | 辅助产物，纯命令复现 | 评委验结果 | +| 3 份执行报告 | 落地证据，含 Skill 蓝图对照 | 评委查细节 |