From 36dfbe290ad6a55205b9819318c94ea3f5f6edc5 Mon Sep 17 00:00:00 2001 From: 15972095207 <2484216370@qq.com> Date: Fri, 3 Jul 2026 08:56:32 +0800 Subject: [PATCH] =?UTF-8?q?feat(workflows):=20=E6=96=B0=E5=A2=9E=20ylly=20?= =?UTF-8?q?=E4=BB=BB=E5=8A=A1=E4=B8=89=E7=BC=96=E6=8E=92=20Skill=EF=BC=88?= =?UTF-8?q?=E5=81=A5=E5=BA=B7=E5=B7=A1=E6=A3=80=E2=91=A5=20+=20=E5=A4=9A?= =?UTF-8?q?=E4=BB=93=E5=BA=93=E5=8D=8F=E5=90=8C=E2=91=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../skills/gitlink-health-doctor/SKILL.md | 165 ++++++++++++++++++ .../skills/gitlink-multi-repo-sync/SKILL.md | 129 ++++++++++++++ 2 files changed, 294 insertions(+) create mode 100644 examples/workflows/gitlink-ops-platform/skills/gitlink-health-doctor/SKILL.md create mode 100644 examples/workflows/gitlink-ops-platform/skills/gitlink-multi-repo-sync/SKILL.md diff --git a/examples/workflows/gitlink-ops-platform/skills/gitlink-health-doctor/SKILL.md b/examples/workflows/gitlink-ops-platform/skills/gitlink-health-doctor/SKILL.md new file mode 100644 index 00000000..fd02242c --- /dev/null +++ b/examples/workflows/gitlink-ops-platform/skills/gitlink-health-doctor/SKILL.md @@ -0,0 +1,165 @@ +--- +name: gitlink-health-doctor +version: 1.0.0 +description: "智能健康巡检编排（AI医生）：依次调度 gitlink-insight → gitlink-issue-triage → gitlink-docs-assistant → gitlink-insight，完成「诊断 → 治疗Issue → 补文档 → 复查」的闭环治理。当用户需要给仓库做全面体检并自动治理、或对比治理前后效果时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli issue --help" +--- + +# gitlink-health-doctor（智能健康巡检 · AI医生 编排 Skill） + +**CRITICAL — 开始前先阅读任务二的 [`gitlink-shared/SKILL.md`](../../../../skills/gitlink-shared/SKILL.md)（认证、权限、API 注意事项）。** +**CRITICAL — 所有写入操作前（打标签、补文档），务必先确认用户意图。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 gh（GitHub CLI）操作 GitLink 资源。** + +> **定位**：本 Skill 是"总指挥"编排 Skill，本身不直接跑命令，而是依次调用 4 个子 Skill 完成"AI 医生"闭环：**insight 诊断 → triage 治疗 Issue → docs 补文档 → insight 复查**。把任务二的 3 个 Skill（triage / docs-assistant / insight）串成端到端治理，是任务三的核心创新点。 + +--- + +## 编排架构 + +``` +gitlink-health-doctor（AI医生） + ├── Step 1 → Skill("gitlink-insight") 诊断：体检仓库，找出病灶 + ├── Step 2 → Skill("gitlink-issue-triage") 治疗：给未分类 Issue 打标签 + ├── Step 3 → Skill("gitlink-docs-assistant") 进补：补全缺失文档到 Wiki + └── Step 4 → Skill("gitlink-insight") 复查：对比治疗前后指标 +``` + +## 子 Skill 依赖 + +| 顺序 | 子 Skill | 角色 | 写入 | +|:----:|---------|------|:----:| +| 1 | gitlink-insight（工作流1：项目健康度报告）| 诊断：采集数据 → 输出健康度 | 否 | +| 2 | gitlink-issue-triage（工作流1：自动分类打标签）| 治疗：未分类 Issue → 分类打标签 | 是 | +| 3 | gitlink-docs-assistant（工作流1+2：体检+补全）| 进补：缺失文档 → 写入 Wiki | 是 | +| 4 | gitlink-insight（工作流1）| 复查：再次体检 → 治疗前后对比 | 否 | + +**串联满足 PDF「≥3 命令/Skill 串联」要求**：4 个 Step 串 3 个子 Skill。 + +--- + +## 前置：收集参数 + +| 参数 | 说明 | 示例 | +|------|------|------| +| owner | 仓库所有者 | `ylly` | +| repo | 仓库名 | `gitlink-cli` | + +--- + +## 工作流 + +### Step 1：诊断（调用 gitlink-insight 工作流1） + +**→ 调用 `Skill("gitlink-insight", args="对 / 做项目健康度报告（工作流1，只读采集分析，不要写入）。")`** + +按 gitlink-insight 工作流1：采集 Issue/PR/Release/语言/贡献者数据 → 输出 7 维健康度报告。 + +**记录诊断出的"病灶"**（供后续治疗）： +- Issue 治理差（大量未分类、无标签） +- 文档缺失（CHANGELOG / API 文档等不存在） +- 其他低分维度 + +关键命令（子 Skill 内部）： +```bash +gitlink-cli repo +info --owner --repo --format json +gitlink-cli issue +list --owner --repo --state open --format json +gitlink-cli issue +list --owner --repo --state closed --format json +MSYS_NO_PATHCONV=1 gitlink-cli api GET ///languages.json --format json +``` + +### Step 2：治疗 Issue（调用 gitlink-issue-triage 工作流1）⚠️写入 + +**→ 调用 `Skill("gitlink-issue-triage", args="对 / 执行工作流1：扫描未分类开放 Issue，按语义分类，复用仓库现有标签打标。打标签前确认用户意图。")`** + +针对诊断出的"Issue 治理差"，按 gitlink-issue-triage 工作流1 治理。 + +关键命令（子 Skill 内部）： +```bash +gitlink-cli issue +list --owner --repo --state open --format json # 找未分类 +gitlink-cli label +list --owner --repo --format json # 复用现有标签 +gitlink-cli issue +view --owner --repo --number --format json # 读详情分类 +gitlink-cli issue +update --owner --repo --number --label # 打标签 +``` + +### Step 3：补文档（调用 gitlink-docs-assistant 工作流1+2）⚠️写入 + +**→ 调用 `Skill("gitlink-docs-assistant", args="对 / 做文档体检（工作流1），然后补全缺失文档（工作流2，写入 Wiki，补全前确认用户意图）。")`** + +针对诊断出的"文档缺失"，按 gitlink-docs-assistant 体检 + 补全。 + +关键命令（子 Skill 内部）： +```bash +gitlink-cli repo +readme --owner --repo # 体检 README +gitlink-cli wiki +list --owner --repo --format json # 看缺什么 +MSYS_NO_PATHCONV=1 gitlink-cli wiki +create --owner --repo \ + --name "CHANGELOG" --content "# 变更记录\n\n..." \ + --message "docs: AI 自动补全 CHANGELOG" # 补全到 Wiki +``` + +### Step 4：复查（再次调用 gitlink-insight 工作流1） + +**→ 调用 `Skill("gitlink-insight", args="对 / 再次做项目健康度报告（工作流1，只读）。对比 Step 1 诊断结果，输出治疗前后变化。")`** + +重新体检，重点对比：Issue 分类率（未分类 → 已分类）、文档完整度（缺失 → 补全）。 + +--- + +## 最终输出 + +四个子 Skill 执行完毕后，汇总输出"AI 医生诊疗报告"： + +```markdown +## 🩺 AI 医生诊疗报告 — / + +### 🔍 诊断（Step 1） +- 总评：⭐x.x / 5 +- 病灶：① Issue 治理差（N 个未分类）② 文档缺失（CHANGELOG/API 文档） + +### 💊 治疗（Step 2-3） +- Issue：N 个已分类打标签（复用 缺陷/功能/疑问 等现有标签） +- 文档：补全 CHANGELOG / API 文档到 Wiki + +### 📈 复查（Step 4） +| 指标 | 治疗前 | 治疗后 | +|------|:------:|:------:| +| Issue 分类率 | 30% | 90% | +| 文档完整度 | 50% | 85% | +| 健康度评分 | 3.5 | 4.2 | + +### 结论 +仓库健康度由 🟡 待完善 提升至 🟢 良好。 +``` + +--- + +## 关键避坑（实测提炼） + +| 坑 | 解决 | +|----|------| +| `api GET /v1/...` 路径在 Git Bash 被转成 Windows 路径 → 404 | 命令前加 `MSYS_NO_PATHCONV=1` | +| `api` 命令会自动补 `.json`，路径无需手动加 | 不要画蛇添足手动加 .json（已实测）| +| 个人仓库 `assigners` 返回空（平台限制）| 治疗阶段用"打标签"替代"分配责任人"| +| GitLink 标签名限 15 字符 | 用 "good first" 等短名，不用 "good first issue"| +| `wiki +create` 中文内容 | CLI 内部自动 base64，`--content` 直接传中文 | +| `api GET sub_entries` 返回 HTML 非文件列表 | 文档体检改用 `repo +readme` | +| `notification` 跨用户查询 403 | 只能自查通知，不代查他人 | +| `issue +update --label` 是覆盖语义 | Issue 已有标签时要把原标签 ID 一并传入 | + +--- + +## 实测落地参考 + +本工作流基于 `ylly/gitlink-cli` 实测（2026-06/07）： + +| 步骤 | 实测结果 | +|------|---------| +| Step 1 诊断 | insight 健康度 3.9/5；病灶 = Issue 治理弱 + 缺 CHANGELOG/API 文档 | +| Step 2 治疗 | 给 #9 等 Issue 打"缺陷"标签（复用现有标签 id 327264）| +| Step 3 补文档 | docs-assistant 创建 CONTRIBUTING（code 201，commit_count 1→2）| +| Step 4 复查 | Issue 分类率提升、文档完整度提升 | + +详见各子 Skill（gitlink-insight / gitlink-issue-triage / gitlink-docs-assistant）的 verification.md。 diff --git a/examples/workflows/gitlink-ops-platform/skills/gitlink-multi-repo-sync/SKILL.md b/examples/workflows/gitlink-ops-platform/skills/gitlink-multi-repo-sync/SKILL.md new file mode 100644 index 00000000..ba0d5ee8 --- /dev/null +++ b/examples/workflows/gitlink-ops-platform/skills/gitlink-multi-repo-sync/SKILL.md @@ -0,0 +1,129 @@ +--- +name: gitlink-multi-repo-sync +version: 1.0.0 +description: "多仓库协同编排：循环遍历多个仓库，依次调用 gitlink-issue + gitlink-pr + gitlink-release 采集各仓库 Issue/PR/Release 状态，汇总成跨仓库协同看板，并给出协调建议。当用户需要统一跟踪多个仓库进展、做跨仓库 Issue/PR/Release 协调时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli issue --help" +--- + +# gitlink-multi-repo-sync（多仓库协同 · 编排 Skill） + +**CRITICAL — 开始前先阅读任务二的 [`gitlink-shared/SKILL.md`](../../../../skills/gitlink-shared/SKILL.md)（认证、权限、API 注意事项）。** +**CRITICAL — 本工作流为只读采集，不写入任何仓库（纯统计汇总）。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 gh（GitHub CLI）操作 GitLink 资源。** + +> **定位**：本 Skill 是"总指挥"编排 Skill，循环调用 issue / pr / release 三个子 Skill，跨多个仓库采集数据，输出统一的协同看板 + 协调建议。解决 PDF 场景"跨多个仓库的统一 Issue 追踪、PR 状态看板、Release 协调发布"。 + +--- + +## 编排架构 + +``` +gitlink-multi-repo-sync + ├── 对每个仓库 循环： + │ ├── Skill("gitlink-issue") 采集 Issue 统计（开放/关闭/未分类） + │ ├── Skill("gitlink-pr") 采集 PR 状态（开放/已合并） + │ └── Skill("gitlink-release") 采集 Release（版本数/最新版） + └── 汇总：跨仓库协同看板 + 协调建议 +``` + +## 子 Skill 依赖 + +| 子 Skill | 用途 | 写入 | +|---------|------|:----:| +| gitlink-issue | 各仓库 Issue 统计（开放/关闭/未分类）| 否 | +| gitlink-pr | 各仓库 PR 状态（开放/已合并）| 否 | +| gitlink-release | 各仓库 Release（数量/最新版本）| 否 | + +**串联满足 PDF「≥3 命令/Skill 串联」要求**：3 个子 Skill × N 个仓库。 + +--- + +## 前置：收集参数 + +| 参数 | 说明 | 示例 | +|------|------|------| +| owner | 所有者（通常多仓库同属一个 owner）| `ylly` | +| repos | 仓库列表（逗号分隔，2-5 个）| `gitlink-cli,gitlink-help-center,demo-repo` | + +> 若用户未指定仓库，先用 `repo +list` 列出该 owner 名下仓库，取前 3 个。 + +--- + +## 工作流 + +### Step 1：遍历仓库采集 Issue + +**→ 对每个 `` 调用 `Skill("gitlink-issue", args="列出 / 的 Issue 统计：开放数、关闭数、未分类数（tags 为空）。只读。")`** + +关键命令（每个仓库执行一次）： +```bash +gitlink-cli issue +list --owner --repo --state open --format json # opened_count +gitlink-cli issue +list --owner --repo --state closed --format json # closed_count +``` +记录每个仓库的 open / closed / 未分类数。 + +### Step 2：采集 PR 状态 + +**→ 对每个 `` 调用 `Skill("gitlink-pr", args="列出 / 的 PR：开放数、已合并数。只读。")`** + +```bash +gitlink-cli pr +list --owner --repo --format json +``` +记录每个仓库的 PR 开放 / 合并数。 + +### Step 3：采集 Release + +**→ 对每个 `` 调用 `Skill("gitlink-release", args="列出 / 的 Release，取最新版本号。只读。")`** + +```bash +gitlink-cli release +list --owner --repo --format json +``` +记录每个仓库的 Release 数 + 最新版本。 + +### Step 4：汇总跨仓库协同看板 + +AI 汇总所有仓库数据，输出协同看板 + 协调建议（哪个仓库积压、哪个可协调发版等）。 + +--- + +## 最终输出 + +```markdown +## 🔗 跨仓库协同看板 — + +| 仓库 | 开放Issue | 关闭Issue | 未分类 | PR(开/合) | 最新Release | 状态 | +|------|:--------:|:--------:|:------:|:---------:|:----------:|:----:| +| gitlink-cli | 10 | 6 | 7 | 0/2 | v0.2.0-beta | 🟡 积压 | +| help-center | 5 | 20 | 1 | 1/5 | v1.0 | 🟢 活跃 | +| demo-repo | 0 | 0 | 0 | 0/0 | 无 | ⚪ 空仓 | + +### 🎯 协同建议 +1. **gitlink-cli** Issue 积压 + 半数未分类 → 建议联动 `gitlink-health-doctor` 治理 +2. **help-center** 发版活跃 → 可与 gitlink-cli 协调统一发版节奏 +3. **demo-repo** 空仓 → 建议初始化（联动 `gitlink-project-bootstrap`）或归档 +``` + +> 这条输出体现了任务三"三件套协同"：multi-repo 发现问题 → 引导用 health-doctor / project-bootstrap 解决。 + +--- + +## 关键避坑（实测提炼） + +| 坑 | 解决 | +|----|------| +| 循环多仓库时 API 频率限制 | 仓库间适当间隔；仓库数控制在 3-5 个 | +| 某仓库无权限 / 不存在 | try-catch 跳过，在看板标注"无权限/不存在"| +| `pr +list --state` 过滤不精确 | 客户端按 `pull_request_status` 字段二次判断（0=open,1=merged,2=closed）| +| `issue +list` 返回数组含已关闭 | 客户端按 `status.id` 二次过滤（1=开放）| +| fork 仓库 PR/Release 为 0 | 属正常（fork 无独立 PR/发版），看板如实展示 | + +--- + +## 实测落地参考 + +**⚠️ 数据准备**：需 owner 名下 2-3 个仓库。若 ylly 账号下仓库不足，可新建 1-2 个测试仓库（或用 `gitlink-project-bootstrap` 自动创建）。 + +实测时遍历 `ylly/gitlink-cli` + 其他仓库，输出跨仓库看板，给出协同建议（联动 health-doctor / project-bootstrap）。