From c340faaabc693412b75f77e26ddc397e2e89c109 Mon Sep 17 00:00:00 2001 From: Angel123456 Date: Fri, 10 Jul 2026 15:58:22 +0800 Subject: [PATCH] feat(examples): add community ops end-to-end workflow Signed-off-by: Angel123456 --- examples/workflows/community-ops/README.md | 299 ++++++++++ .../workflows/community-ops/architecture.html | 153 +++++ .../examples/Agent完整对话记录.txt | 1 + .../Angel123456-gitlink-cli-full-workflow.log | 182 ++++++ .../GitLink-gitlink-cli-dryrun-workflow.log | 178 ++++++ .../skills/gitlink-community-ops/SKILL.md | 404 +++++++++++++ .../skills/gitlink-community-report/SKILL.md | 468 +++++++++++++++ .../gitlink-issue-triage-rules/EXAMPLES.md | 324 +++++++++++ .../gitlink-issue-triage-rules/SKILL.md | 550 ++++++++++++++++++ .../skills/gitlink-release-notes/SKILL.md | 454 +++++++++++++++ 10 files changed, 3013 insertions(+) create mode 100644 examples/workflows/community-ops/README.md create mode 100644 examples/workflows/community-ops/architecture.html create mode 100644 examples/workflows/community-ops/examples/Agent完整对话记录.txt create mode 100644 examples/workflows/community-ops/examples/example1/Angel123456-gitlink-cli-full-workflow.log create mode 100644 examples/workflows/community-ops/examples/example2/GitLink-gitlink-cli-dryrun-workflow.log create mode 100644 examples/workflows/community-ops/skills/gitlink-community-ops/SKILL.md create mode 100644 examples/workflows/community-ops/skills/gitlink-community-report/SKILL.md create mode 100644 examples/workflows/community-ops/skills/gitlink-issue-triage-rules/EXAMPLES.md create mode 100644 examples/workflows/community-ops/skills/gitlink-issue-triage-rules/SKILL.md create mode 100644 examples/workflows/community-ops/skills/gitlink-release-notes/SKILL.md diff --git a/examples/workflows/community-ops/README.md b/examples/workflows/community-ops/README.md new file mode 100644 index 0000000..31caaf5 --- /dev/null +++ b/examples/workflows/community-ops/README.md @@ -0,0 +1,299 @@ +# GitLink 社区运营自动化工作流 + +> 端到端社区运营自动化：新 Issue 自动分类 → 分配责任人 → 定期生成社区周报 → 自动发布 Release Notes +> +> **四个 Skill 统一编排** — 每个阶段由独立的 Skill（SKILL.md）驱动，Agent 按 Skill 步骤直接调用 CLI 执行。`gitlink-community-ops` Skill 作为统一入口编排三个子 Skill。 + +**真实运行项目：** [Angel123456/gitlink-cli](https://www.gitlink.org.cn/Angel123456/gitlink-cli)（GitLink 平台） +**运行服务器：** `ssh -p 39925 root@connect.westb.seetacloud.com` + +--- + +## 一、架构总览 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ gitlink-community-ops (统一入口 Skill) │ +│ │ +│ Step 0: 环境检测 + 参数收集 (OWNER/REPO/BACKEND) │ +│ ↓ │ +│ Step 1: ┌──────────────────────────────────────┐ │ +│ │ gitlink-issue-triage-rules (子 Skill) │ │ +│ │ → Issue 自动分类 + 分配责任人 │ │ +│ │ → 规则匹配 + LLM 兜底 + 写回 │ │ +│ └──────────────────────────────────────┘ │ +│ ↓ │ +│ Step 2: ┌──────────────────────────────────────┐ │ +│ │ gitlink-community-report (子 Skill) │ │ +│ │ → 社区周报自动生成 + 发布 │ │ +│ └──────────────────────────────────────┘ │ +│ ↓ │ +│ Step 3: ┌──────────────────────────────────────┐ │ +│ │ gitlink-release-notes (子 Skill) │ │ +│ │ → Release Notes 自动生成 + 发布 │ │ +│ └──────────────────────────────────────┘ │ +│ ↓ │ +│ Step 4: 输出工作流总结 │ +│ │ +│ 底层: gitlink-cli / gh / glab / curl → 各平台 REST API │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +**四个 Skill 的职责分工：** + +| Skill | 职责 | 模式 | 触发词 | +|-------|------|------|--------| +| `gitlink-community-ops` | 统一编排入口 | C1 (纯文档) | "社区运营自动化"、"一键社区巡检" | +| `gitlink-issue-triage-rules` | Issue 自动分类 + 分配责任人 | C1 (纯文档) | "分拣 Issue"、"按规则打标签" | +| `gitlink-community-report` | 社区周报生成 + 发布 | C1 (纯文档) | "生成社区周报"、"weekly report" | +| `gitlink-release-notes` | Release Notes 生成 + 发布 | C1 (纯文档) | "发布 Release Notes"、"版本发布" | + +**关键依赖关系：** +- Step 1 (分拣) 必须先完成 → Issue 才有标签 → Step 2/3 的数据才准确 +- Step 2 (周报) 和 Step 3 (Release Notes) 独立于彼此，可单独执行 +- 每个子 Skill 独立做 dry-run 预览 + 用户确认，不在编排层一次性全确认 + +> 独立架构图文件：`docs/architecture.html`（可在浏览器中打开查看） + +--- + +## 二、Skill 1 — gitlink-issue-triage-rules（Issue 自动分类 + 分配责任人） + +### 执行机制 + +Agent 加载 `gitlink-issue-triage-rules/SKILL.md`，按 Step 0-7 直接调用 CLI 执行： + +1. Step 0：后端检测 + 认证检查 +2. Step 1：从 SKILL.md 内嵌 YAML 代码块加载规则（mode / rules[] / defaults） +3. Step 2：列出未分拣 Issue（`gitlink-cli issue +list --state open`） +4. Step 3：建立标签 + 成员 + 优先级 ID 映射 +5. Step 4：按 SKILL.md 规则评估每条 Issue（keyword 匹配 / LLM 兜底） +6. Step 5：dry-run 预览（Markdown 表格，**必须先看**） +7. Step 6：用户确认后写回（先 `+view` 回读防清空 → `api PATCH` → `+comment` 审计） +8. Step 7：验证写回结果（`+view`） + +### 内嵌规则 (mode: hybrid) + +| 规则 ID | 类型 | 匹配关键词 | 标签 (GitLink 中文) | 优先级 | +|---------|------|-----------|-------------------|--------| +| bug-default | bug | 错误, 失败, 崩溃, panic, crash | 缺陷 | high | +| question-default | question | 请问, 如何, 怎么, how to | 疑问 | normal | +| docs-typo | docs | typo, 文档, README | 文档 | low | + +**hybrid 模式**：规则优先匹配，无命中时 LLM 兜底。 + +### 双语 Label 翻译 + +GitLink/Gitee 后端优先中文标签（缺陷/功能/疑问/文档），GitHub/GitLab 后端优先英文（bug/enhancement/question/docs）。一份规则兼容 4 个平台。 + +### CRITICAL 约束 + +- 写回前必须 `+view` 回读标题和正文（防 PATCH 清空这两个字段） +- 默认 dry-run，用户确认后才执行写回 +- 每次写回附带审计评论（含 matched_rules） + +--- + +## 三、Skill 2 — gitlink-community-report（社区周报生成 + 发布） + +### 执行机制 + +Agent 加载 `gitlink-community-report/SKILL.md`，按 Step 0-6 直接调用 CLI 执行： + +| Step | 动作 | CLI 命令 | +|------|------|----------| +| 0 | 后端检测 + 认证 | `gitlink-cli auth status` | +| 1 | 采集数据 | `issue +list` (open/closed) + `release +list` + `member +list` | +| 2 | 时间过滤 + 统计 | Agent 计算本周新建/关闭/标签分布/高优先级 | +| 3 | 生成周报 | 按内嵌 Markdown 模板填充 | +| 4 | dry-run 预览 | 输出完整周报内容 | +| 5 | 发布周报 | `gitlink-cli issue +create --title "📊 社区周报 ..." --body <周报>` | +| 6 | 验证 | 确认周报 Issue 已创建 | + +### 周报结构 + +周报包含：概览（开放/关闭/新建/关闭数）、本周新建 Issue 清单、本周关闭 Issue 清单、标签分布、高优先级待办、本周 Release。 + +### 周报标识 + +标题前缀 `📊 社区周报`，便于其他 Skill 自动识别跳过（不纳入 Issue 分拣）。 + +--- + +## 四、Skill 3 — gitlink-release-notes（Release Notes 生成 + 发布） + +### 执行机制 + +Agent 加载 `gitlink-release-notes/SKILL.md`，按 Step 0-6 直接调用 CLI 执行： + +| Step | 动作 | CLI 命令 | +|------|------|----------| +| 0 | 后端检测 + 认证 | `gitlink-cli auth status` | +| 1 | 采集数据 | `issue +list` (closed/open) + `release +list` | +| 2 | 版本号去重 + 分类 | Bug 修复 / 新功能 / 其他改进 | +| 3 | 生成 Release Notes | 按内嵌 Markdown 模板填充 | +| 4 | dry-run 预览 | 输出完整 Release Notes | +| 5 | 创建 Release | `gitlink-cli release +create --name --tag --target master --body ` | +| 6 | 验证 | 确认 Release 已创建 | + +### Issue 分类逻辑 + +| 分类组 | GitLink/Gitee 标签 | GitHub/GitLab 标签 | +|--------|-------------------|-------------------| +| Bug 修复 | 缺陷 | bug | +| 新功能 | 功能 | enhancement, feature | +| 其他改进 | 不属于以上两组 | 不属于以上两组 | + +### 版本命名 + +默认 `vYYYY.MM.DD`（如 `v2026.07.10`）。当天已有同名 tag 时追加序号 `-2`、`-3`。用户也可指定版本号（如 `v1.2.0`）。 + +--- + +## 五、Skill 4 — gitlink-community-ops（统一入口） + +### 编排逻辑 + +``` +Step 0 → 环境检测 + 参数收集 (OWNER/REPO/BACKEND/PERIOD/VERSION) +Step 1 → 加载并执行 gitlink-issue-triage-rules → 分拣 Issue +Step 2 → 加载并执行 gitlink-community-report → 生成周报 +Step 3 → 加载并执行 gitlink-release-notes → 发布 Release +Step 4 → 输出工作流总结 +``` + +**编排规则：** +- **顺序执行**：Step 1 必须先完成（分拣后才有标签数据供周报和 Release Notes 使用） +- **逐个确认**：每个子 Skill 的写回操作需独立确认 +- **上下文传递**：OWNER / REPO / BACKEND 在子 Skill 间自动继承 +- **容错继续**：某子 Skill 失败不阻塞后续步骤 +- **可选跳过**：用户可只执行部分步骤 + +--- + +## 六、串联的 CLI 命令 / Skill 调用清单（≥3 ✓） + +本工作流串联了 **4 个 Skill + 12 类 gitlink-cli 命令**： + +| # | 类型 | 命令/调用 | 阶段 | 作用 | +|---|------|----------|------|------| +| **1** | **Skill** | **gitlink-issue-triage-rules** | **1** | **Issue 自动分类+分配** | +| **2** | **Skill** | **gitlink-community-report** | **2** | **社区周报生成+发布** | +| **3** | **Skill** | **gitlink-release-notes** | **3** | **Release Notes 生成+发布** | +| **4** | **Skill** | **gitlink-community-ops** | **编排** | **统一入口，编排1-3** | +| 5 | CLI | `auth status` | 1/2/3 | 认证检测 | +| 6 | CLI | `issue +list` | 1/2/3 | 拉取 Issue 列表 | +| 7 | CLI | `label +list` | 1 | 标签 ID 映射 | +| 8 | CLI | `member +list` | 1 | 成员映射 | +| 9 | CLI | `issue +view` | 1 | 写回前回读 (CRITICAL) | +| 10 | CLI | `api PATCH` | 1 | 写回标签/优先级/责任人 | +| 11 | CLI | `issue +comment` | 1 | 审计评论 | +| 12 | CLI | `issue +create` | 2 | 发布周报 | +| 13 | CLI | `release +list` | 2/3 | 统计/去重 | +| 14 | CLI | `release +create` | 3 | 发布 Release | + +--- + +## 七、可复现的执行方式 + +### 环境要求 +- 服务器已安装 `gitlink-cli` 并 `gitlink-cli auth status` 显示已登录 +- 四个 Skill 的 SKILL.md 文件已安装到 Agent 的 skills 目录 +- 目标仓库已有标签和成员 + +### Skill 安装位置 + +``` +~/.workbuddy/skills/ # WorkBuddy Agent或其他AI Agent + ├── gitlink-issue-triage-rules/SKILL.md + ├── gitlink-community-report/SKILL.md + ├── gitlink-release-notes/SKILL.md + └── gitlink-community-ops/SKILL.md (统一入口) + +# 或项目级: +/.workbuddy/skills/ + ├── gitlink-issue-triage-rules/SKILL.md + ├── gitlink-community-report/SKILL.md + ├── gitlink-release-notes/SKILL.md + └── gitlink-community-ops/SKILL.md +``` + +### 执行方式 + +**方式 A：WorkBuddy / Agent 对话触发** + +``` +# 全流程 (一键) +"帮我跑 Angel123456/gitlink-cli 的完整社区运营工作流" + +# 单阶段 +"帮我分拣 Angel123456/gitlink-cli 的未分拣 Issue" → 只触发 gitlink-issue-triage-rules +"帮我生成 Angel123456/gitlink-cli 的社区周报" → 只触发 gitlink-community-report +"帮我发布 Angel123456/gitlink-cli 的 Release Notes" → 只触发 gitlink-release-notes + +# 部分流程 +"帮我分拣 Issue，然后生成周报" → Step 1 + Step 2 +``` + +### 定期自动化 + +**WorkBuddy Automation** + +使用 WorkBuddy 的定时自动化功能，每周一自动触发 `gitlink-community-ops` Skill。 + +--- + +## 八、真实运行效果 + +### Step 1 — Issue 自动分类 (gitlink-issue-triage-rules, 2026-07-10) + +Agent 按 SKILL.md 步骤执行，hybrid 模式（规则匹配 + LLM 兜底）： + +| Issue | 标题 | 命中规则 | 标签 | 优先级 | 责任人 | +|-------|------|---------|------|--------|--------| +| #2 | 建议支持 Markdown 格式的评论 | LLM 兜底 | 功能 | 正常 | Angel123456 | +| #5 | 建议支持 JSON 格式日志输出 | LLM 兜底 | 功能 | 正常 | Angel123456 | +| #7 | 建议支持 Markdown 格式的评论 | LLM 兜底 ⚠️(与#2重复) | 重复 | 正常 | Angel123456 | + +> 写回方式：`gitlink-cli api PATCH`，写回前先 `+view` 回读防清空，写回后 `+comment` 审计。 + +### Step 2 — 社区周报 (gitlink-community-report, 2026-07-10) + +周报标题：`📊 社区周报 2026-07-10`，发布为 Issue #9。 +包含：概览（开放8/关闭0）、本周新建Issue清单、标签分布、高优先级待办、本周Release。 + +### Step 3 — Release Notes (gitlink-release-notes, 2026-07-10) + +版本号 `v2026.07.10`，记录了 Step 1-2 的社区运营改进。 +Release 已创建并验证（总 Release: 2）。 + +--- + +## 九、文件清单 + +``` +community-ops/ +├── README.md # 本说明文档 +├── SKILL.md # gitlink-issue-triage-rules Skill 指令文件 +├── skills/ # Skill 文件目录 +│ ├── gitlink-community-report/SKILL.md # 社区周报 Skill +│ ├── gitlink-release-notes/SKILL.md # Release Notes Skill +│ └── gitlink-community-ops/SKILL.md # 统一入口 Skill +├── logs/ +│ ├── step1-issue-triage.log # Step 1 Issue 分拣日志 +│ ├── step2-community-report.log # Step 2 周报日志 +│ └── step3-release-notes.log # Step 3 Release Notes 日志 +└── docs/ + └── architecture.html # 架构图 +``` + +--- + +## 十、安全策略 + +- **默认 dry-run**：所有子 Skill 默认先预览，用户确认后才执行写回 +- **逐个确认**：每个子 Skill 的写回操作需独立确认（不在编排层一次性全确认） +- **view 回读**：Step 1 写回前必须 `+view` 回读标题和正文（防清空） +- **规则可审计**：每次写回附带审计评论，记录命中规则和匹配方式 +- **版本去重**：Step 3 自动检测已有 Release，避免 tag 冲突 +- **容错继续**：某步骤失败不阻塞后续 diff --git a/examples/workflows/community-ops/architecture.html b/examples/workflows/community-ops/architecture.html new file mode 100644 index 0000000..a78f4ce --- /dev/null +++ b/examples/workflows/community-ops/architecture.html @@ -0,0 +1,153 @@ +

社区运营自动化工作流架构图

+
+

GitLink 社区运营自动化工作流

+

四个 Skill 统一编排 · C1 纯文档模式 · 跨平台兼容

+ + + 社区运营自动化工作流架构图 + 四个 Skill 统一编排三阶段 + + + + + + + + + + gitlink-community-ops + 统一入口 Skill (编排 Step 1→2→3) + + + + + + + Step 1: Issue 分类+分配 + gitlink-issue-triage-rules + + + 规则匹配 + + LLM 兜底 + + 双语翻译 + + PATCH 写回 + + + + Step 2: 社区周报 + gitlink-community-report + + + 数据采集 + + 时间过滤 + + 生成周报 + + Issue 发布 + + + + Step 3: Release Notes + gitlink-release-notes + + + 版本去重 + + Issue 分类 + + 生成 Notes + + Release 创建 + + + + + + + + gitlink-cli / gh / glab / curl → 各平台 REST API + + + + + + 串联的 CLI 命令清单 (14 项) + + + Step 1 (gitlink-issue-triage-rules): + + auth status + + issue +list + + label +list + + member +list + + issue +view + + api PATCH + + +comment + + issue +view + + + Step 2 (gitlink-community-report): + + auth status + + issue +list + + release +list + + member +list + + issue +create + + + Step 3 (gitlink-release-notes): + + auth status + + issue +list + + release +list + + release +create + + +
+

Skill 编排流程

+

+ gitlink-community-ops 是统一入口，编排三个子 Skill：
+ Step 1: gitlink-issue-triage-rules — Issue 自动分类 + 分配责任人 (规则匹配 + LLM 兜底)
+ Step 2: gitlink-community-report — 社区周报自动生成 + 发布
+ Step 3: gitlink-release-notes — Release Notes 自动生成 + 发布
+ 每个子 Skill 独立做 dry-run 预览 + 用户确认，上下文参数 (OWNER/REPO/BACKEND) 自动继承。 +

+ +

关键依赖

+

+ Step 1 必须先完成 → Issue 才有标签 → Step 2 周报标签分布准确 → Step 3 Release Notes 按 Bug/Feature 正确分类。 + 容错：某步骤失败不阻塞后续。 +

+ +

执行方式

+ 
# Skill 方式 (Agent 对话触发)
+"帮我跑 Angel123456/gitlink-cli 的完整社区运营工作流"
+
+# 脚本方式 (无 Agent 环境)
+python3 community-ops.py --owner Angel123456 --repo gitlink-cli --skill-md SKILL.md           # dry-run
+python3 community-ops.py --owner Angel123456 --repo gitlink-cli --skill-md SKILL.md --apply   # 真实写回
+
+
diff --git a/examples/workflows/community-ops/examples/Agent完整对话记录.txt b/examples/workflows/community-ops/examples/Agent完整对话记录.txt new file mode 100644 index 0000000..5bcbc4e --- /dev/null +++ b/examples/workflows/community-ops/examples/Agent完整对话记录.txt @@ -0,0 +1 @@ +【WorkBuddy】gitlink-community-ops 工作流演示示例 https://codebuddy.work/agents/tasks/share/yb6HVCYScJ?platform=workbuddy \ No newline at end of file diff --git a/examples/workflows/community-ops/examples/example1/Angel123456-gitlink-cli-full-workflow.log b/examples/workflows/community-ops/examples/example1/Angel123456-gitlink-cli-full-workflow.log new file mode 100644 index 0000000..ccb4ba2 --- /dev/null +++ b/examples/workflows/community-ops/examples/example1/Angel123456-gitlink-cli-full-workflow.log @@ -0,0 +1,182 @@ +======================================== + 社区运营自动化工作流日志 + 仓库: Angel123456/gitlink-cli + 后端: gitlink + 执行时间: 2026-07-10 14:56 ~ 15:03 + 执行范围: 完整工作流（Step 1 + Step 2 + Step 3） + 状态: 全部写回成功 ✓ +======================================== + +---------------------------------------- + Step 0: 环境检测 + 参数收集 +---------------------------------------- + +[CHECK] gitlink-cli auth status → 已登录为 Angel123456 ✓ +[CHECK] gitlink-cli --version → 版本可用 ✓ +[CHECK] gitlink-cli repo +info → 仓库 Angel123456/gitlink-cli 确认 (7 Issue, Owner 权限) ✓ +[CHECK] 子 Skill 可用性 → gitlink-issue-triage-rules / gitlink-community-report / gitlink-release-notes 全部可用 ✓ + +环境检测结果: + - 后端: gitlink + - 认证用户: Angel123456 + - 仓库: Angel123456/gitlink-cli (7 Issue, Owner 权限) + - 子 Skill: 3 个全部可用 + +---------------------------------------- + Step 1: Issue 自动分类分拣 +---------------------------------------- + +[CMD] gitlink-cli issue +list --owner Angel123456 --repo gitlink-cli --state open --format json +[RESULT] 开放 Issue 共 7 条: #1, #2, #5, #6, #9, #12, #13 + +[CMD] gitlink-cli label +list --owner Angel123456 --repo gitlink-cli --format json +[RESULT] 标签映射: 缺陷(id:398784) / 功能(id:398785) / 疑问(id:398786) + +[CMD] gitlink-cli member +list --owner Angel123456 --repo gitlink-cli --format json +[RESULT] 成员映射: + - Angel123456 (id:153579, 管理员) — 核心负责人 + - Hsy15889521073 (id:134328, 开发者) — 开发角色 + - Priziq (id:134450, 报告者) — 辅助角色 + +[CMD] gitlink-cli issue +view → 回读 #2, #12, #13 详情 + +[ANALYSIS] 规则评估结果 (mode=hybrid): + +| Issue | 标题 | 建议分类 | 建议标签 | 标签ID | 责任人 | 责任人ID | 优先级 | 优先级ID | 命中规则 | LLM兜底 | +|-------|---------------------------|---------|---------|--------|-----------------|---------|--------|---------|------------------|--------| +| #2 | 建议支持 Markdown 格式评论 | 功能 | 功能 | 398785 | Hsy15889521073 | 134328 | normal | 2 | — | ✓ | +| #13 | 服务启动时偶尔会崩溃 | 缺陷 | 缺陷 | 398784 | Angel123456 | 153579 | high | 3 | bug-default | — | +| #12 | 请问如何配置 HTTPS 证书？ | 疑问 | 疑问 | 398786 | Angel123456 | 153579 | normal | 2 | question-default | — | + +[SKIP] #9 — 周报类 Issue，不参与分拣 + +[USER_CONFIRM] 按角色分配：缺陷类→Angel123456，功能类→Hsy15889521073，疑问类→Angel123456 + +[DRY-RUN] dry-run 预览已展示 → 用户确认执行 (apply) + +[WRITE] Issue #2 (功能类): + [CMD] gitlink-cli api PATCH /v1/Angel123456/gitlink-cli/issues/2 + [BODY] {subject, description, issue_tag_ids:[398785], assigner_ids:[134328], priority_id:2} + [RESULT] 写回成功 ✓ + [CMD] gitlink-cli issue +comment --number 2 --body "🤖 自动分拣：分类=功能，标签=功能，优先级=normal，责任人=Hsy15889521073，命中规则=LLM兜底（hybrid模式）" + [RESULT] 审计评论写入成功 ✓ + +[WRITE] Issue #13 (缺陷类): + [CMD] gitlink-cli api PATCH /v1/Angel123456/gitlink-cli/issues/13 + [BODY] {subject, description, issue_tag_ids:[398784], assigner_ids:[153579], priority_id:3} + [RESULT] 写回成功 ✓ + [CMD] gitlink-cli issue +comment --number 13 --body "🤖 自动分拣：分类=缺陷，标签=缺陷，优先级=high，责任人=Angel123456，命中规则=bug-default（关键词：崩溃）" + [RESULT] 审计评论写入成功 ✓ + +[WRITE] Issue #12 (疑问类): + [CMD] gitlink-cli api PATCH /v1/Angel123456/gitlink-cli/issues/12 + [BODY] {subject, description, issue_tag_ids:[398786], assigner_ids:[153579], priority_id:2} + [RESULT] 写回成功 ✓ + [CMD] gitlink-cli issue +comment --number 12 --body "🤖 自动分拣：分类=疑问，标签=疑问，优先级=normal，责任人=Angel123456，命中规则=question-default（关键词：请问、如何）" + [RESULT] 审计评论写入成功 ✓ + +[VERIFY] 验证写回结果: + - #2: tags=[功能], assigners=[Hsy15889521073], priority=normal ✓ + - #13: tags=[缺陷], assigners=[Angel123456], priority=high ✓ + - #12: tags=[疑问], assigners=[Angel123456], priority=normal ✓ + +Step 1 汇总: + - 分拣 Issue: 3 条 + - 规则命中: 2 条 (bug-default, question-default) + - LLM 兜底: 1 条 (功能类) + - 跳过: 1 条 (周报类) + - 写回成功: 3 条 ✓ + - 审计评论: 3 条 ✓ + +---------------------------------------- + Step 2: 社区周报生成与发布 +---------------------------------------- + +[CMD] gitlink-cli issue +list --owner Angel123456 --repo gitlink-cli --state closed --format json +[RESULT] 已关闭 Issue: 0 条 + +[CMD] gitlink-cli release +list --owner Angel123456 --repo gitlink-cli --format json +[RESULT] 累计 Release: 2 (v2026.07.09, v2026.07.10) + +统计结果 (PERIOD=7天, 2026-07-03 ~ 2026-07-10): + - 开放 Issue: 7 → 8 (含新创建的 #14 周报) + - 已关闭 Issue: 0 + - 本周新建: 7 (#1,#2,#5,#6,#9,#12,#13) + - 本周关闭: 0 + - 本周新 Release: 2 (v2026.07.09, v2026.07.10) + - 标签分布 (分拣后): 缺陷:2, 功能:2, 疑问:2, 无标签:1 + - 高优先级: #1(高), #13(高) + +[USER_CONFIRM] 确认发布周报 Issue (apply) + +[CMD] gitlink-cli issue +create --owner Angel123456 --repo gitlink-cli + --title "📊 社区周报 2026-07-10（分拣后更新版）" + --body "$REPORT_MD" +[RESULT] Issue #14 创建成功 ✓ + +Step 2 汇总: + - 周报标题: 📊 社区周报 2026-07-10（分拣后更新版） + - 周报 Issue 编号: #14 + - 开放 Issue: 7 → 8 + - 本周新建: 7 / 本周关闭: 0 + - 本周新 Release: 2 + +---------------------------------------- + Step 3: Release Notes 生成与发布 +---------------------------------------- + +已有 Release tag: v2026.07.09, v2026.07.10 +[DECISION] v2026.07.10 已存在 → 使用版本号 v2026.07.10-2 + +Issue 分类 (基于已关闭 Issue = 0 条): + - Bug 修复: 0 项 + - 新功能: 0 项 + - 其他改进: 3 项 (社区运营自动化) + +[USER_CONFIRM] 确认发布 v2026.07.10-2 Release (apply) + +[CMD] gitlink-cli release +create --owner Angel123456 --repo gitlink-cli + --name "v2026.07.10-2" --tag "v2026.07.10-2" --target master + --body "$NOTES_MD" +[RESULT] Release 创建成功 ✓ + +[VERIFY] gitlink-cli release +list → 确认 v2026.07.10-2 已出现在列表中 ✓ + +Step 3 汇总: + - 版本号: v2026.07.10-2 + - Bug 修复: 0 / 新功能: 0 / 其他改进: 3 (社区运营自动化) + - Release 已创建: ✓ + +---------------------------------------- + 工作流串联的 CLI 命令清单 +---------------------------------------- + +| # | CLI 命令 | 所属步骤 | +|----|---------------------------------------------|---------------| +| 1 | gitlink-cli auth status | Step 0 认证 | +| 2 | gitlink-cli repo +info | Step 0 仓库 | +| 3 | gitlink-cli issue +list (open) | Step 1 列Issue | +| 4 | gitlink-cli label +list | Step 1 标签 | +| 5 | gitlink-cli member +list | Step 1 成员 | +| 6 | gitlink-cli issue +view (#2,#12,#13) | Step 1 回读 | +| 7 | gitlink-cli api PATCH (×3) | Step 1 写回 | +| 8 | gitlink-cli issue +comment (×3) | Step 1 审计 | +| 9 | gitlink-cli issue +list (closed) | Step 2 采集 | +| 10 | gitlink-cli release +list | Step 2/3 采集 | +| 11 | gitlink-cli issue +create (#14) | Step 2 周报 | +| 12 | gitlink-cli release +create (v2026.07.10-2) | Step 3 发布 | + +---------------------------------------- + 关键经验 +---------------------------------------- + +- GitLink 写回必须带 subject + description，否则这两个字段会被清空 +- GitLink 优先级: critical→4, high→3, normal→2, low→1 +- 版本号去重: 当天已有同名 tag 时追加 -N 序号 +- 周报类 Issue (标题以 📊 开头) 应跳过分拣 +- 审计评论格式: "🤖 自动分拣：分类=X，标签=X，优先级=X，责任人=X，命中规则=X" + +======================================== + 工作流完成 ✓ + Angel123456/gitlink-cli — 全部写回成功 +======================================== diff --git a/examples/workflows/community-ops/examples/example2/GitLink-gitlink-cli-dryrun-workflow.log b/examples/workflows/community-ops/examples/example2/GitLink-gitlink-cli-dryrun-workflow.log new file mode 100644 index 0000000..bfd738f --- /dev/null +++ b/examples/workflows/community-ops/examples/example2/GitLink-gitlink-cli-dryrun-workflow.log @@ -0,0 +1,178 @@ +======================================== + 社区运营自动化工作流日志 + 仓库: GitLink/gitlink-cli + 后端: gitlink + 执行时间: 2026-07-10 15:03 ~ 15:15 + 执行范围: Step 1 (Issue 分拣) + Step 2 (社区周报)，不含 Step 3 (Release Notes) + 状态: 仅 dry-run 预览，未执行写回 ⚠️ +======================================== + +---------------------------------------- + Step 0: 环境检测 + 参数收集 +---------------------------------------- + +[CHECK] gitlink-cli auth status → 已登录为 Angel123456 ✓ +[CHECK] gitlink-cli --version → 版本可用 ✓ +[CHECK] gitlink-cli repo +info → 仓库 GitLink/gitlink-cli 确认 (24 Issue, 37 贡献者, 12 Release, 408 PR) ✓ +[CHECK] 子 Skill 可用性 → gitlink-issue-triage-rules / gitlink-community-report 全部可用 ✓ + +环境检测结果: + - 后端: gitlink + - 认证用户: Angel123456 + - 仓库: GitLink/gitlink-cli (组织仓库, 24 Issue, 37 贡献者) + - 子 Skill: 2 个 (不含 gitlink-release-notes) + +---------------------------------------- + Step 1: Issue 自动分类分拣 +---------------------------------------- + +[CMD] gitlink-cli issue +list --owner GitLink --repo gitlink-cli --state open --format json +[RESULT] 开放 Issue 共 14 条: #2,#5,#6,#14,#15,#17,#18,#20,#21,#22,#23,#24,#25,#26 + +[CMD] gitlink-cli label +list --owner GitLink --repo gitlink-cli --format json +[RESULT] 标签映射 (10 个): 缺陷(298652) / 功能(298653) / 疑问(298654) / 支持(298655) / 任务(298656) / 协助(298657) / 搁置(298658) / 文档(298659) / 测试(298660) / 重复(298661) + +[CMD] gitlink-cli member +list --owner GitLink --repo gitlink-cli --format json +[RESULT] ⚠️ 403 权限不足，无法获取成员列表 +[NOTE] 本次仅打标签 + 设置优先级，不分配责任人 + +[CMD] gitlink-cli issue +view → 回读 #2,#5,#6,#14,#15,#17,#18,#20,#21,#22,#23,#24,#25,#26 详情 + +[ANALYSIS] 规则评估结果 (mode=hybrid): + +| Issue | 标题 | 建议分类 | 建议标签 | 标签ID | 责任人 | 优先级 | 优先级ID | 命中规则 | LLM兜底 | +|-------|-----------------------------------------------------|---------|---------|--------|--------|--------|---------|---------------|--------| +| #26 | v1 标签 show/destroy 的存在性预检失效 | 缺陷 | 缺陷 | 298652 | 仅打标签 | high | 3 | bug-default | — | +| #25 | 平台缺口：archive/raw 下载端点不可用 | 缺陷 | 缺陷 | 298652 | 仅打标签 | high | 3 | bug-default | — | +| #24 | wiki 开放接口写操作不支持 PAT 鉴权 | 缺陷 | 缺陷 | 298652 | 仅打标签 | high | 3 | bug-default | — | +| #20 | bug: api 命令单次调用不替换 :owner/:repo 占位符 | 缺陷 | 缺陷 | 298652 | 仅打标签 | high | 3 | bug-default | — | +| #18 | giklink-cli issue +update后状态框变红色 | 缺陷 | 缺陷 | 298652 | 仅打标签 | high | 3 | bug-default | — | +| #15 | issue +view 返回的数据与网页显示不一致 | 缺陷 | 缺陷 | 298652 | 仅打标签 | normal | 2 | bug-default | — | +| #5 | skill认领任务时描述信息消失 | 缺陷 | 缺陷 | 298652 | 仅打标签 | high | 3 | bug-default | — | +| #14 | pr +view 返回中缺少PR关闭时间 | 缺陷 | 缺陷 | 298652 | 仅打标签 | normal | 2 | bug-default | — | +| #21 | dataset 快捷命令需要的后端 API 支持 | 功能 | 功能 | 298653 | 仅打标签 | normal | 2 | — | ✓ | +| #17 | API是否支持自动读取仓库内文件？ | 疑问 | 疑问 | 298654 | 仅打标签 | normal | 2 | question-default| — | + +[SKIP] #2 — 讨论帖，不参与分拣 +[SKIP] #22 — PR 汇报类（"Mengz 提交 PR 统计汇总"），不参与分拣 +[SKIP] #23 — PR 汇报类（已有"文档"标签），不参与分拣 +[NOTE] #6 — Agent 自动化类，建议打 功能 标签，但分类存疑 + +[DRY-RUN] dry-run 预览已展示 +[USER_CONFIRM] ⚠️ 用户选择取消 (cancel) — 未执行写回 + +Step 1 汇总: + - 开放 Issue: 14 条 + - 需分拣 Issue: 10 条 + - 规则命中: 7 条 (bug-default: #26,#25,#24,#20,#18,#5,#14) + 1 条 (question-default: #17) + - LLM 兜底: 2 条 (#21 功能需求, #6 Agent 类) + - 跳过: 4 条 (#2 讨论帖, #22/#23 PR 汇报类) + - ⚠️ 仓库成员权限不足 (403)，无法分配责任人 + - ⚠️ 写回: 未执行（用户取消） + +---------------------------------------- + Step 2: 社区周报生成与发布 +---------------------------------------- + +[CMD] gitlink-cli issue +list --owner GitLink --repo gitlink-cli --state closed --format json +[RESULT] 已关闭 Issue: 10 条 + +[CMD] gitlink-cli release +list --owner GitLink --repo gitlink-cli --format json +[RESULT] 累计 Release: 12 (v0.2.0, v0.1.18, v0.1.17, v0.1.14, v0.1.13, v0.1.12, v0.1.11, v0.1.10, v0.1.9, v0.1.8, v0.1.5, v0.1.3) + +统计结果 (PERIOD=7天, 2026-07-03 ~ 2026-07-10): + - 开放 Issue: 14 + - 已关闭 Issue: 10 + - 本周新建: 5 (#22,#23,#24,#25,#26) + - 本周关闭: 0 + - 标签分布: 文档:1, 无标签:13 + - 累计 Release: 12 (本周无新 Release) + - 高优先级待办: 无 (所有开放 Issue 优先级均为"正常") + +本周报预览内容: + + # 社区周报 | GitLink/gitlink-cli + **统计周期:** 2026-07-03 ~ 2026-07-10 + + ## 概览 + - 开放 Issue: 14 + - 已关闭 Issue: 10 + - 本周新建: 5 (#22,#23,#24,#25,#26) + - 本周关闭: 0 + - 标签分布: 文档:1, 无标签:13 + - 累计 Release: 12 (本周无新 Release) + + ## 本周新建 Issue + - #22 Mengz 提交 PR 统计汇总 + - #23 [文档] GitLink-CLI 团队 PR 贡献与进展汇总 + - #24 wiki 开放接口写操作不支持 PAT 鉴权 + - #25 平台缺口：archive/raw 下载端点不可用 + - #26 v1 标签 show/destroy 的存在性预检失效 + + ## 本周关闭 Issue + - 无 + + ## 最近 Release + - v0.2.0 (2026-06-09) + - v0.1.18 (2026-05-19) + - v0.1.17 (2026-05-19) + - ... + +[DRY-RUN] dry-run 预览已展示 +[USER_CONFIRM] ⚠️ 用户选择取消 (cancel) — 未发布周报 Issue + +Step 2 汇总: + - 开放 Issue: 14 / 已关闭: 10 + - 本周新建: 5 / 本周关闭: 0 + - 标签分布: 文档:1, 无标签:13 + - 累计 Release: 12 (本周无新 Release) + - ⚠️ 周报: 未发布（用户取消） + +---------------------------------------- + 工作流串联的 CLI 命令清单 +---------------------------------------- + +| # | CLI 命令 | 所属步骤 | 状态 | +|----|------------------------------------------------|---------------|-----------| +| 1 | gitlink-cli auth status | Step 0 认证 | ✓ | +| 2 | gitlink-cli repo +info | Step 0 仓库 | ✓ | +| 3 | gitlink-cli issue +list (open) | Step 1 列Issue | ✓ | +| 4 | gitlink-cli label +list | Step 1 标签 | ✓ | +| 5 | gitlink-cli member +list | Step 1 成员 | ⚠️ 403 | +| 6 | gitlink-cli issue +view (×14) | Step 1 回读 | ✓ | +| 7 | gitlink-cli api PATCH | Step 1 写回 | ✗ 未执行 | +| 8 | gitlink-cli issue +comment | Step 1 审计 | ✗ 未执行 | +| 9 | gitlink-cli issue +list (closed) | Step 2 采集 | ✓ | +| 10 | gitlink-cli release +list | Step 2 采集 | ✓ | +| 11 | gitlink-cli issue +create | Step 2 周报 | ✗ 未执行 | + +---------------------------------------- + 差异对比：与示例1 (Angel123456/gitlink-cli) 的区别 +---------------------------------------- + +| 维度 | 示例1 (Angel123456/gitlink-cli) | 示例2 (GitLink/gitlink-cli) | +|-------------|----------------------------------|------------------------------| +| 仓库类型 | 个人仓库 (Owner权限) | 组织仓库 (受限权限) | +| Issue 数量 | 7 (开放) / 0 (关闭) | 14 (开放) / 10 (关闭) | +| 成员列表 | 3 人，可获取 | 403 权限不足，无法获取 | +| 标签数量 | 3 个 (缺陷/功能/疑问) | 10 个 (含支持/任务/协助等) | +| 责任人分配 | ✓ 按角色分配成功 | ✗ 仅打标签，不分配责任人 | +| 写回执行 | ✓ 3 条 Issue 全部写回成功 | ✗ 用户取消，未执行写回 | +| 周报发布 | ✓ Issue #14 创建成功 | ✗ 用户取消，未发布 | +| Release Notes| ✓ v2026.07.10-2 创建成功 | — 未执行此步骤 | +| 关键障碍 | 无 | 组织仓库权限不足 (403) | + +---------------------------------------- + 关键经验 +---------------------------------------- + +- 组织仓库 (GitLink/*) 的 member+list 需要 Maintainer 权限，普通开发者角色返回 403 +- 权限不足时，分拣策略调整为：仅打标签 + 设置优先级，不分配责任人 +- dry-run 模式可安全预览分拣结果，用户取消时不会产生任何写操作 +- 大型仓库 (14+ 开放 Issue) 的分拣分析需要逐条回读详情，耗时较长 +- 标签体系越丰富（10 个标签），分拣可用的分类维度越多 + +======================================== + 工作流完成 ⚠️ + GitLink/gitlink-cli — 仅 dry-run 预览，未执行写回 +======================================== diff --git a/examples/workflows/community-ops/skills/gitlink-community-ops/SKILL.md b/examples/workflows/community-ops/skills/gitlink-community-ops/SKILL.md new file mode 100644 index 0000000..52a9c83 --- /dev/null +++ b/examples/workflows/community-ops/skills/gitlink-community-ops/SKILL.md @@ -0,0 +1,404 @@ +--- +name: gitlink-community-ops +version: 1.0.0 +description: "GitLink 社区运营自动化统一入口：编排三个子 Skill（gitlink-issue-triage-rules + gitlink-community-report + gitlink-release-notes）实现端到端工作流——新 Issue 自动分类 → 分配责任人 → 生成社区周报 → 发布 Release Notes。触发场景：社区运营自动化、一键社区巡检、完整社区工作流、community ops、社区运营一键跑、帮我做社区运维。" +license: MulanPSL-2.0 +metadata: + requires: + bins_any: ["gitlink-cli", "gh", "glab", "curl"] + bins_note: "gitee 后端无官方 CLI，直接使用 curl 调用 https://gitee.com/api/v5/ REST API；其余三后端用对应原生 CLI" + cliHelp: "gitlink-cli --help" + platforms: + agents: + - openclaw + - claude-code + - cursor + - generic-agent + backends: + - id: gitlink + cli: gitlink-cli + url_template: "https://www.gitlink.org.cn/{owner}/{repo}" + api_base: "https://www.gitlink.org.cn/api/v1" + auth_env: GITLINK_TOKEN + default: true + - id: github + cli: gh + url_template: "https://github.com/{owner}/{repo}" + api_base: "https://api.github.com" + auth_env: GH_TOKEN + - id: gitlab + cli: glab + url_template: "https://gitlab.com/{owner}/{repo}" + api_base: "https://gitlab.com/api/v4" + auth_env: GITLAB_TOKEN + - id: gitee + cli: curl + url_template: "https://gitee.com/{owner}/{repo}" + api_base: "https://gitee.com/api/v5" + auth_env: GITEE_TOKEN + subSkills: + - gitlink-issue-triage-rules + - gitlink-community-report + - gitlink-release-notes +--- + +# gitlink-community-ops（社区运营自动化统一入口） + +**CRITICAL — 本 Skill 是编排入口，不直接执行任何 CLI 命令。它通过引用三个子 Skill 完成所有实际操作。Agent 必须按本文件的步骤依次加载并执行每个子 Skill，不能跳过、不能并行。** +**CRITICAL — 每个子 Skill 执行前必须独立做 dry-run 预览并等待用户确认。不能在编排层面一次性确认所有子 Skill 的写回。** +**CRITICAL — 子 Skill 之间共享上下文参数（OWNER / REPO / BACKEND），Agent 必须在每次子 Skill 调用时传递这些参数。** + +> **依赖 Skill：** 三个子 Skill（必须全部可用） +> 1. `gitlink-issue-triage-rules` — Issue 自动分类 + 分配责任人 +> 2. `gitlink-community-report` — 社区周报自动生成 + 发布 +> 3. `gitlink-release-notes` — Release Notes 自动生成 + 发布 +> **本 Skill 为 C1 模式（纯文档）**：Agent 按本文件步骤依次加载子 Skill 并执行。 + +--- + +## 功能概述 + +本 Skill 是社区运营自动化工作流的**统一编排入口**。它不自己执行任何 CLI 命令，而是按步骤指引 Agent 依次加载三个子 Skill： + +``` +编排流程: + Step 1 → 加载 gitlink-issue-triage-rules → 执行 Issue 分拣 + Step 2 → 加载 gitlink-community-report → 执行周报生成 + Step 3 → 加载 gitlink-release-notes → 执行版本发布 + Step 4 → 输出工作流总结 +``` + +**设计原则**： +- ✅ **顺序执行**：Step 1 必须先完成（分拣后才有标签数据供周报和 Release Notes 分类使用） +- ✅ **逐个确认**：每个子 Skill 的写回操作需独立确认（不在编排层一次性全确认） +- ✅ **上下文传递**：OWNER / REPO / BACKEND 在子 Skill 间自动继承 +- ✅ **容错继续**：某子 Skill 失败不阻塞后续步骤（但输出警告） +- ✅ **可选跳过**：用户可选择只执行部分步骤（如只做分拣不做周报） + +## 触发场景 + +用户提到以下关键词时自动触发： +- "社区运营自动化"、"一键社区巡检"、"完整社区工作流" +- "community ops"、"社区运营一键跑"、"帮我做社区运维" +- "帮我跑完整工作流"（同时涉及分拣 + 周报 + 发布） +- "全流程社区运营" + +> **注意**：如果用户只说"分拣 Issue" → 只触发 `gitlink-issue-triage-rules`；只说"生成周报" → 只触发 `gitlink-community-report`；只说"发布 Release Notes" → 只触发 `gitlink-release-notes`。本 Skill 仅在用户表达**完整/多阶段**需求时触发。 + +--- + +## 全局参数 + +| 参数 | 来源 | 默认值 | 说明 | +|------|------|--------|------| +| `OWNER` | 用户输入或 git remote | 必须 | 仓库 owner | +| `REPO` | 用户输入或 git remote | 必须 | 仓库名 | +| `BACKEND` | 自动检测 | gitlink | 平台后端（gitlink/github/gitlab/gitee） | +| `PERIOD` | 用户指定 | 7 | 周报统计周期（天） | +| `VERSION` | 用户指定或自动 | vYYYY.MM.DD | Release Notes 版本号 | +| `DRY_RUN` | 默认 | true | 所有子 Skill 默认先预览 | + +--- + +## 工作流（Agent 执行步骤） + +### Step 0：环境检测 + 参数收集 + +```bash +# 0.1 检测后端 +BACKEND=$(detect_backend) +echo "✓ 后端: $BACKEND" + +# 0.2 认证检查 +case "$BACKEND" in + gitlink) gitlink-cli auth status ;; + github) gh auth status ;; + gitlab) glab auth status ;; + gitee) test -n "$GITEE_TOKEN" && echo "Gitee OK" ;; +esac + +# 0.3 确认仓库参数 +# Agent 从用户输入或 git remote 推断 OWNER 和 REPO +echo "仓库: $OWNER/$REPO" + +# 0.4 确认执行范围 +# 询问用户: 全流程 (Step 1-3) 还是部分步骤? +# 默认: 全流程 +``` + +### Step 1：执行 gitlink-issue-triage-rules（Issue 自动分类） + +``` +Agent 操作: +1. 加载 gitlink-issue-triage-rules Skill +2. 传递参数: OWNER, REPO, BACKEND +3. Agent 按该 Skill 的 Step 0-7 执行: + - 认证检测 → 加载规则 → 列出未分拣 Issue → 建立映射 → 规则评估 → dry-run 预览 → 用户确认 → 写回 → 验证 +4. 记录分拣结果摘要 (供后续步骤使用) +``` + +**分拣结果摘要格式**（Agent 输出并保留在上下文中）： + +```markdown +## Step 1 完成：Issue 分拣结果 + +- 分拣 Issue: {count} 条 +- 规则命中: {count} 条 +- LLM 兜底: {count} 条 +- 跳过: {count} 条 +- 写回成功: {count} 条 +``` + +### Step 2：执行 gitlink-community-report（社区周报生成） + +``` +Agent 操作: +1. 加载 gitlink-community-report Skill +2. 传递参数: OWNER, REPO, BACKEND, PERIOD +3. Agent 按该 Skill 的 Step 0-6 执行: + - 认证检测 → 数据采集 → 时间过滤 → 生成周报 → dry-run 预览 → 用户确认 → 发布 → 验证 +4. 记录周报结果摘要 +``` + +**周报结果摘要格式**： + +```markdown +## Step 2 完成：社区周报 + +- 周报标题: 📊 社区周报 {date} +- 开放 Issue: {count} | 已关闭: {count} +- 本周新建: {count} | 本周关闭: {count} +- 周报 Issue 编号: #{number} +``` + +### Step 3：执行 gitlink-release-notes（Release Notes 发布） + +``` +Agent 操作: +1. 加载 gitlink-release-notes Skill +2. 传递参数: OWNER, REPO, BACKEND, VERSION +3. Agent 按该 Skill 的 Step 0-6 执行: + - 认证检测 → 数据采集 → 分类 → 生成 Release Notes → dry-run 预览 → 用户确认 → 创建 Release → 验证 +4. 记录发布结果摘要 +``` + +**发布结果摘要格式**： + +```markdown +## Step 3 完成：Release Notes + +- 版本号: {version} +- Bug 修复: {count} 项 | 新功能: {count} 项 | 其他改进: {count} 项 +- Release 已创建: ✓ +``` + +### Step 4：输出工作流总结 + +Agent 输出完整的执行报告： + +```markdown +## 🎯 社区运营自动化工作流总结 + +**仓库:** {OWNER}/{REPO} +**后端:** {BACKEND} +**执行时间:** {NOW} + +### Step 1 — Issue 自动分类 +- 分拣: {count} 条 | 规则命中: {count} | LLM 兜底: {count} | 跳过: {count} + +### Step 2 — 社区周报 +- 周报已发布: Issue #{number} +- 开放 Issue: {count} | 本周新建: {count} | 本周关闭: {count} + +### Step 3 — Release Notes +- 版本: {version} +- Bug 修复: {count} | 新功能: {count} | 其他改进: {count} + +### 工作流串联的 CLI 命令 (≥3) +1. gitlink-cli auth status (Step 0 认证) +2. gitlink-cli issue +list (Step 1 列 Issue) +3. gitlink-cli label +list (Step 1 标签映射) +4. gitlink-cli member +list (Step 1 成员映射) +5. gitlink-cli issue +view (Step 1 回读) +6. gitlink-cli api PATCH (Step 1 写回) +7. gitlink-cli issue +comment (Step 1 审计) +8. gitlink-cli issue +create (Step 2 周报发布) +9. gitlink-cli release +list (Step 3 去重) +10. gitlink-cli release +create (Step 3 发布) + +✅ 工作流完成 +``` + +--- + +## 容错与错误处理 + +| 场景 | 处理 | +|------|------| +| Step 1 分拣失败 | 输出警告，**继续执行 Step 2/3**（周报和 Release Notes 仍可基于未分拣数据生成，只是分类可能不够精确） | +| Step 2 周报发布失败 | 输出警告，**继续执行 Step 3**（Release Notes 独立于周报） | +| Step 3 发布失败 | 输出警告，**Step 1/2 已完成的部分不受影响** | +| 认证失败 | **阻塞所有步骤**，提示用户检查 token | +| 子 Skill 不可用 | **阻塞该步骤**，提示用户安装缺失的 Skill | + +--- + +## 数据流图 + +``` +┌───────────────────────────────────────────────────────────────────┐ +│ gitlink-community-ops (统一入口) │ +│ │ +│ Step 0: 环境检测 + 参数收集 │ +│ ↓ OWNER, REPO, BACKEND, PERIOD, VERSION │ +│ │ +│ Step 1: ┌──────────────────────────────────────┐ │ +│ │ gitlink-issue-triage-rules │ │ +│ │ → 分拣结果 (标签/优先级/责任人写入) │ │ +│ │ → 分拣摘要供后续步骤使用 │ │ +│ └──────────────────────────────────────┘ │ +│ ↓ │ +│ Step 2: ┌──────────────────────────────────────┐ │ +│ │ gitlink-community-report │ │ +│ │ → 周报 Issue 发布 │ │ +│ │ → 标签分布 + 高优先级数据来自分拣后的 │ │ +│ │ Issue 列表 (所以 Step 1 须先完成) │ │ +│ └──────────────────────────────────────┘ │ +│ ↓ │ +│ Step 3: ┌──────────────────────────────────────┐ │ +│ │ gitlink-release-notes │ │ +│ │ → Release 创建 │ │ +│ │ → Bug/Feature 分类来自分拣后的标签数据 │ │ +│ └──────────────────────────────────────┘ │ +│ ↓ │ +│ Step 4: 输出工作流总结 │ +│ │ +└───────────────────────────────────────────────────────────────────┘ +``` + +**关键依赖关系**： +- Step 2 和 Step 3 的数据质量取决于 Step 1 的分拣结果 +- Step 1 必须先完成 → Issue 才有标签 → 周报标签分布才能准确 → Release Notes 才能按 Bug/Feature 正确分类 +- 如果 Step 1 被跳过或失败 → Step 2/3 仍可运行，但分类基于原始标签（可能不精确） + +--- + +## 部分执行 + +用户可只执行部分步骤： + +| 用户意图 | 执行范围 | +|----------|----------| +| "只分拣 Issue" | Step 1 only → 直接触发 `gitlink-issue-triage-rules` | +| "只生成周报" | Step 2 only → 直接触发 `gitlink-community-report` | +| "只发布 Release" | Step 3 only → 直接触发 `gitlink-release-notes` | +| "分拣 + 周报" | Step 1 + Step 2 | +| "全流程" | Step 1 + Step 2 + Step 3 | + +Agent 应根据用户意图自动选择执行范围，而不是每次都跑全流程。 + +--- + +## 安全与写回策略 + +| 规则 | 说明 | +|------|------| +| **逐个确认** | 每个子 Skill 的写回操作需**独立**确认（不在编排层一次性全确认） | +| **默认 dry-run** | 所有子 Skill 默认先做 dry-run 预览 | +| **容错继续** | 某步骤失败不阻塞后续步骤 | +| **认证阻塞** | 认证失败阻塞所有步骤 | +| **记录摘要** | 每步完成后输出摘要，供用户和工作流总结使用 | + +--- + +## 使用示例 + +### 示例 1：全流程（GitLink） + +**用户输入**： + +``` +帮我跑 Angel123456/gitlink-cli 的完整社区运营工作流 +``` + +**Agent 执行**： + +``` +Step 0: 检测后端 → gitlink | 认证 OK | 仓库: Angel123456/gitlink-cli + +Step 1: 加载 gitlink-issue-triage-rules + → 7 条未分拣 Issue → 规则命中 4 条 → dry-run → 用户确认 → 写回 → 验证 + → 分拣摘要: 4 条写回成功 + +Step 2: 加载 gitlink-community-report (PERIOD=7) + → 数据采集 → 本周新建 5 条 / 关闭 3 条 → dry-run → 用户确认 → 发布周报 Issue + → 周报摘要: Issue #12 已发布 + +Step 3: 加载 gitlink-release-notes (VERSION=v2026.07.10) + → Bug 修复 2 / 新功能 1 / 其他 2 → dry-run → 用户确认 → 创建 Release + → 发布摘要: v2026.07.10 已发布 + +Step 4: 输出工作流总结 (10+ CLI 命令串联) +``` + +### 示例 2：分拣 + 周报（GitHub，不发布 Release） + +**用户输入**： + +``` +帮我分拣 xuanlanwuta/gps_SM 的 Issue，然后生成一份周报 +``` + +**Agent 执行**： + +``` +Step 0: 检测后端 → github | 认证 OK + +Step 1: 加载 gitlink-issue-triage-rules + → 4 条 Issue → 规则命中 4 条 → dry-run → 用户确认 → 写回 + +Step 2: 加载 gitlink-community-report (PERIOD=7) + → 数据采集 → dry-run → 用户确认 → 发布周报 + +(跳过 Step 3，用户未要求发布 Release) + +Step 4: 输出部分工作流总结 (Step 1 + Step 2) +``` + +--- + +## Agent 平台兼容性 + +| 平台 | 加载方式 | 触发方式 | +|------|----------|----------| +| **OpenClaw** | `workspace/skills/gitlink-community-ops/SKILL.md` | 自然语言 | +| **Claude Code** | `~/.claude/skills/gitlink-community-ops/SKILL.md` | 自然语言 | +| **Cursor** | `~/.cursor/skills/gitlink-community-ops/SKILL.md` | 自然语言 + `/` 命令 | +| **WorkBuddy** | `~/.workbuddy/skills/gitlink-community-ops/SKILL.md` | 自然语言 | +| **通用 Agent** | 作为参考文档 | 按 SKILL.md 流程自取 | + +--- + +## 子 Skill 安装位置 + +三个子 Skill 必须与本 Skill 在同一级目录： + +``` +~/.workbuddy/skills/ + ├── gitlink-issue-triage-rules/SKILL.md (已有) + ├── gitlink-community-report/SKILL.md (新增) + ├── gitlink-release-notes/SKILL.md (新增) + └── gitlink-community-ops/SKILL.md (新增, 本文件) +``` + +或项目级： + +``` +/.workbuddy/skills/ + ├── gitlink-issue-triage-rules/SKILL.md + ├── gitlink-community-report/SKILL.md + ├── gitlink-release-notes/SKILL.md + └── gitlink-community-ops/SKILL.md +``` + +Agent 加载子 Skill 时，按同级目录的相对路径 `..//SKILL.md` 查找。 diff --git a/examples/workflows/community-ops/skills/gitlink-community-report/SKILL.md b/examples/workflows/community-ops/skills/gitlink-community-report/SKILL.md new file mode 100644 index 0000000..130451c --- /dev/null +++ b/examples/workflows/community-ops/skills/gitlink-community-report/SKILL.md @@ -0,0 +1,468 @@ +--- +name: gitlink-community-report +version: 1.0.0 +description: "社区周报自动生成：在 GitHub / GitLink / GitLab / Gitee 等开源项目中，自动汇总本周 Issue 开闭情况、标签分布、高优先级待办、Release 动态，生成结构化周报并发布为 Issue。触发场景：生成社区周报、社区运营报告、每周总结、weekly report、社区健康度检查。" +license: MulanPSL-2.0 +metadata: + requires: + bins_any: ["gitlink-cli", "gh", "glab", "curl"] + bins_note: "gitee 后端无官方 CLI，直接使用 curl 调用 https://gitee.com/api/v5/ REST API；其余三后端用对应原生 CLI" + cliHelp: "gitlink-cli issue --help" + platforms: + agents: + - openclaw + - claude-code + - cursor + - generic-agent + backends: + - id: gitlink + cli: gitlink-cli + url_template: "https://www.gitlink.org.cn/{owner}/{repo}" + api_base: "https://www.gitlink.org.cn/api/v1" + auth_env: GITLINK_TOKEN + default: true + - id: github + cli: gh + url_template: "https://github.com/{owner}/{repo}" + api_base: "https://api.github.com" + auth_env: GH_TOKEN + - id: gitlab + cli: glab + url_template: "https://gitlab.com/{owner}/{repo}" + api_base: "https://gitlab.com/api/v4" + auth_env: GITLAB_TOKEN + - id: gitee + cli: curl + url_template: "https://gitee.com/{owner}/{repo}" + api_base: "https://gitee.com/api/v5" + auth_env: GITEE_TOKEN +--- + +# gitlink-community-report（社区周报自动生成） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](https://www.gitlink.org.cn/Gitlink/gitlink-cli/tree/master/skills/gitlink-shared/SKILL.md)（仅 GitLink 后端）或对应平台的 CLI 文档。所有 GitHub 操作必须使用 `gh`；所有 GitLab 操作必须使用 `glab`；所有 GitLink 操作必须使用 `gitlink-cli`。禁止混用或替代。** +**CRITICAL — 本 Skill 包含写入操作（创建周报 Issue）。默认必须先做 dry-run（仅预览），经用户明确确认后才执行发布。** + +> **依赖工具：** 二选一即可——`gitlink-cli` / `gh` / `glab`，外加 `jq`。 +> **依赖 Skill：** 使用 GitLink 后端时需加载 `gitlink-shared`；使用 GitHub / GitLab 时无需额外 Skill。 +> **本 Skill 为 C1 模式（纯文档）**：所有命令由 Agent 按本文件步骤直接调用对应平台 CLI 执行。 + +--- + +## 功能概述 + +本 Skill 是**自包含**的：周报模板与分类逻辑**直接内嵌在 SKILL.md 中**，Agent 从本文件读取格式规范，不需要从外部仓库拉取配置文件。 + +1. **后端检测**：Agent 自动识别当前仓库所在的平台（GitHub / GitLink / GitLab / Gitee） +2. **数据采集**：Agent 用对应 CLI 收集开放/关闭 Issue、Release、标签分布、高优先级待办 +3. **时间过滤**：按用户指定时间范围（默认本周）筛选新建/关闭 Issue +4. **报告生成**：Agent 按内嵌模板生成结构化 Markdown 周报 +5. **dry-run 预览**：Agent 输出周报内容，等待用户确认 +6. **发布**：用户确认后，Agent 用对应 CLI 创建周报 Issue +7. **可追踪**：周报 Issue 标题带日期标识，后续可自动识别跳过（不纳入下次分拣） + +> **⚠️ 设计约束**：周报模板内嵌于 SKILL.md。如需自定义章节/格式，编辑本 SKILL.md 的「周报模板」小节即可。 + +## 触发场景 + +用户提到以下关键词时自动触发： +- "生成社区周报"、"社区运营报告"、"每周总结" +- "weekly report"、"community report"、"社区健康度" +- "帮我看看本周社区动态" + +--- + +## 平台适配 + +### 后端自动检测 + +Agent 启动周报任务时，**必须**先按以下顺序检测后端： + +```bash +detect_backend() { + local remote_url + remote_url="$(git remote get-url origin 2>/dev/null || echo '')" + + case "$remote_url" in + *gitlink.org.cn*) echo "gitlink" ;; + *github.com*) echo "github" ;; + *gitlab.com*|*gitlab.*) echo "gitlab" ;; + *gitee.com*) echo "gitee" ;; + esac + + command -v gitlink-cli >/dev/null && echo "gitlink" + command -v gh >/dev/null && echo "github" + command -v glab >/dev/null && echo "gitlab" + command -v curl >/dev/null && echo "gitee" +} +``` + +### 命令映射表 + +| 步骤 | 目的 | GitLink (`gitlink-cli`) | GitHub (`gh`) | GitLab (`glab`) | Gitee (`curl`) | +|------|------|------------------------|----------------|------------------|----------------| +| **认证检查** | 确认已登录 | `gitlink-cli auth status` | `gh auth status` | `glab auth status` | `test -n "$GITEE_TOKEN"` | +| **列开放 Issue** | 取开放 Issue | `gitlink-cli issue +list --owner X --repo Y --state open --format json` | `gh issue list --repo X/Y --state open --json number,title,labels,body,createdAt` | `glab issue list --repo X/Y --state opened --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/issues?state=open&access_token=$GITEE_TOKEN"` | +| **列关闭 Issue** | 取关闭 Issue | `gitlink-cli issue +list --owner X --repo Y --state closed --format json` | `gh issue list --repo X/Y --state closed --json number,title,labels,closedAt` | `glab issue list --repo X/Y --state closed --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/issues?state=closed&access_token=$GITEE_TOKEN"` | +| **列 Release** | 取已有版本 | `gitlink-cli release +list --owner X --repo Y --format json` | `gh release list --repo X/Y --json tagName,name,publishedAt` | `glab release list --repo X/Y --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/releases?access_token=$GITEE_TOKEN"` | +| **列成员** | 取贡献者 | `gitlink-cli member +list --owner X --repo Y --format json` | `gh api repos/X/Y/collaborators` | `glab api projects/:fullpath/members/all` | `curl -s "https://gitee.com/api/v5/repos/X/Y/collaborators?access_token=$GITEE_TOKEN"` | +| **创建 Issue** | 发布周报 | `gitlink-cli issue +create --owner X --repo Y --title "..." --body "..." --format json` | `gh issue create --repo X/Y --title "..." --body "..."` | `glab issue create --repo X/Y --title "..." --description "..."` | `curl -X POST "https://gitee.com/api/v5/repos/X/Y/issues?access_token=$GITEE_TOKEN&title=...&body=..."` | + +### 字段名差异 + +| 概念 | GitLink | GitHub | GitLab | Gitee | +|------|---------|--------|--------|-------| +| Issue 标题 | `subject` | `title` | `title` | `title` | +| Issue 正文 | `description` | `body` | `description` | `body` | +| 创建时间 | `created_at` | `createdAt` | `created_at` | `created_at` | +| 更新时间 | `updated_at` | `updatedAt` | `updated_at` | `updated_at` | +| 标签 | `issue_tags` (数组 of {name,id}) | `labels` (数组 of {name}) | `labels` (数组 of {name}) | `labels` (逗号分隔) | +| 优先级 | `priority_id` (1-4) | 靠 label 表达 | 靠 label 表达 | 靠 label 表达 | + +--- + +## 工作流（Agent 执行步骤） + +### Step 0：确认环境 + 检测后端 + +```bash +# 0.1 检测后端 +BACKEND=$(detect_backend) +echo "✓ 后端: $BACKEND" + +# 0.2 认证检查 +case "$BACKEND" in + gitlink) gitlink-cli auth status ;; + github) gh auth status ;; + gitlab) glab auth status ;; + gitee) test -n "$GITEE_TOKEN" && echo "Gitee OK" ;; +esac + +# 0.3 确认参数 +# Agent 需从用户输入或上下文获取: +# OWNER, REPO, PERIOD (默认 "本周" = 7天) +echo "仓库: $OWNER/$REPO | 周期: 最近 $PERIOD 天" +``` + +### Step 1：采集数据（按后端选命令） + +```bash +case "$BACKEND" in + gitlink) + OPEN=$(gitlink-cli issue +list --owner $OWNER --repo $REPO --state open --limit 200 --format json) + CLOSED=$(gitlink-cli issue +list --owner $OWNER --repo $REPO --state closed --limit 200 --format json) + RELEASES=$(gitlink-cli release +list --owner $OWNER --repo $REPO --format json) + MEMBERS=$(gitlink-cli member +list --owner $OWNER --repo $REPO --format json) + ;; + github) + OPEN=$(gh issue list --repo $OWNER/$REPO --state open --limit 200 --json number,title,labels,createdAt) + CLOSED=$(gh issue list --repo $OWNER/$REPO --state closed --limit 200 --json number,title,labels,closedAt) + RELEASES=$(gh release list --repo $OWNER/$REPO --json tagName,name,publishedAt --limit 50) + ;; + gitlab) + OPEN=$(glab issue list --repo $OWNER/$REPO --state opened --output json --all) + CLOSED=$(glab issue list --repo $OWNER/$REPO --state closed --output json --all) + RELEASES=$(glab release list --repo $OWNER/$REPO --output json) + ;; + gitee) + OPEN=$(curl -s "https://gitee.com/api/v5/repos/$OWNER/$REPO/issues?state=open&access_token=$GITEE_TOKEN&per_page=200") + CLOSED=$(curl -s "https://gitee.com/api/v5/repos/$OWNER/$REPO/issues?state=closed&access_token=$GITEE_TOKEN&per_page=200") + RELEASES=$(curl -s "https://gitee.com/api/v5/repos/$OWNER/$REPO/releases?access_token=$GITEE_TOKEN") + ;; +esac +``` + +### Step 2：时间过滤 + 统计 + +Agent 根据采集到的数据，计算以下指标： + +``` +统计指标: + 1. 开放 Issue 总数 ← OPEN 数组长度 + 2. 已关闭 Issue 总数 ← CLOSED 数组长度 + 3. 本周新建 Issue ← created_at >= (今天 - PERIOD天) + 4. 本周关闭 Issue ← updated_at/closed_at >= (今天 - PERIOD天) + 5. 标签分布 ← OPEN Issue 的标签 name → 计数 + 6. 高优先级待办 ← OPEN Issue 中 priority_id >= 3 (GitLink) / label 含 "priority: high/critical" (GitHub/GitLab) + 7. 本周 Release ← RELEASES 中 published_at >= (今天 - PERIOD天) + 8. 贡献者/成员 ← MEMBERS 数量 + 角色 +``` + +**时间字段映射**（不同平台字段名不同，Agent 按后端做翻译）： + +| 平台 | 创建时间字段 | 关闭时间字段 | 发布时间字段 | +|------|-------------|-------------|-------------| +| GitLink | `created_at` | `updated_at` (状态变更时更新) | `created_at` | +| GitHub | `createdAt` | `closedAt` | `publishedAt` | +| GitLab | `created_at` | `closed_at` | `created_at` | +| Gitee | `created_at` | `updated_at` | `created_at` | + +### Step 3：生成周报内容（按内嵌模板） + +Agent 按以下模板生成 Markdown 周报。**所有数值占位符由 Agent 在 Step 2 计算后填入**： + +```markdown +# 社区周报 | {OWNER}/{REPO} + +**统计周期:** {PERIOD_START} ~ {PERIOD_END} +**生成时间:** {NOW} (由 gitlink-community-report 自动生成) + +## 概览 + +- 开放 Issue: **{OPEN_COUNT}** +- 已关闭 Issue: **{CLOSED_COUNT}** +- 本周新建: **{NEW_COUNT}** +- 本周关闭: **{CLOSED_WEEK_COUNT}** +- 累计 Release: **{RELEASE_COUNT}** +- 本周新 Release: **{NEW_RELEASE_COUNT}** +- 贡献者/成员: **{MEMBER_COUNT}** + +## 本周新建 Issue + +{NEW_ISSUES_LIST} + + +## 本周关闭 Issue + +{CLOSED_WEEK_LIST} + + +## 当前开放 Issue 标签分布 + +{TAG_DISTRIBUTION} + + +## 高优先级待办 + +{HIGH_PRIORITY_LIST} + + +## 本周 Release + +{WEEK_RELEASES} + + +--- + +_本周报由 gitlink-community-report Skill 自动生成_ +``` + +### Step 4：dry-run 预览（必须） + +Agent 输出完整周报 Markdown，附带元信息： + +```markdown +## 📊 社区周报预览（dry-run） + +> 后端：{BACKEND} +> 仓库：{OWNER}/{REPO} +> 统计周期：最近 {PERIOD} 天 +> 开放 Issue：{count} 条 | 已关闭：{count} 条 + +{完整周报 Markdown 内容} + +⚠️ 涉及写入操作（创建 Issue）。回复"确认"或"apply"执行。 +``` + +### Step 5：发布周报（用户确认后，按后端分发） + +```bash +TITLE="📊 社区周报 $(date +%Y-%m-%d)" + +case "$BACKEND" in + gitlink) + gitlink-cli issue +create --owner $OWNER --repo $REPO \ + --title "$TITLE" --body "$REPORT_MD" --format json + ;; + github) + gh issue create --repo $OWNER/$REPO \ + --title "$TITLE" --body "$REPORT_MD" + ;; + gitlab) + glab issue create --repo $OWNER/$REPO \ + --title "$TITLE" --description "$REPORT_MD" + ;; + gitee) + curl -X POST "https://gitee.com/api/v5/repos/$OWNER/$REPO/issues?access_token=$GITEE_TOKEN" \ + -d "title=$TITLE" -d "body=$REPORT_MD" + ;; +esac +``` + +**周报 Issue 标识**：标题以 `📊 社区周报` 开头，便于后续 Skill 自动识别并跳过（不纳入 Issue 分拣）。 + +### Step 6：验证 + +```bash +# 确认周报 Issue 已创建 +case "$BACKEND" in + gitlink) gitlink-cli issue +list --owner $OWNER --repo $REPO --state open --format json \ + | jq '[.data[] | select(.subject | startswith("📊"))]' ;; + github) gh issue list --repo $OWNER/$REPO --state open --json number,title \ + | jq '[.[] | select(.title | startswith("📊"))]' ;; + gitlab) glab issue list --repo $OWNER/$REPO --state opened --output json \ + | jq '[.[] | select(.title | startswith("📊"))]' ;; + gitee) curl -s "https://gitee.com/api/v5/repos/$OWNER/$REPO/issues?state=open&access_token=$GITEE_TOKEN" \ + | jq '[.[] | select(.title | startswith("📊"))]' ;; +esac +``` + +--- + +## 时间范围配置 + +默认统计最近 7 天。用户可指定： + +| 输入 | PERIOD | 说明 | +|------|--------|------| +| "本周周报" / "weekly report" | 7 | 最近 7 天 | +| "半月报" / "biweekly" | 14 | 最近 14 天 | +| "月度报告" / "monthly" | 30 | 最近 30 天 | +| "自定义 N 天" | N | 最近 N 天 | + +--- + +## 周报模板（内嵌） + +以下是完整的周报 Markdown 模板。Agent 按此结构生成周报，所有 `{PLACEHOLDER}` 由 Step 2 计算结果替换： + +```markdown +# 社区周报 | {OWNER}/{REPO} + +**统计周期:** {PERIOD_START} ~ {PERIOD_END} +**生成时间:** {NOW} (由 gitlink-community-report 自动生成) + +## 概览 + +- 开放 Issue: **{OPEN_COUNT}** +- 已关闭 Issue: **{CLOSED_COUNT}** +- 本周新建: **{NEW_COUNT}** +- 本周关闭: **{CLOSED_WEEK_COUNT}** +- 累计 Release: **{RELEASE_COUNT}** +- 本周新 Release: **{NEW_RELEASE_COUNT}** +- 贡献者/成员: **{MEMBER_COUNT}** + +## 本周新建 Issue + +{NEW_ISSUES_LIST} + +## 本周关闭 Issue + +{CLOSED_WEEK_LIST} + +## 当前开放 Issue 标签分布 + +{TAG_DISTRIBUTION} + +## 高优先级待办 + +{HIGH_PRIORITY_LIST} + +## 本周 Release + +{WEEK_RELEASES} + +--- + +_本周报由 gitlink-community-report Skill 自动生成_ +``` + +--- + +## 安全与写回策略 + +| 规则 | 说明 | +|------|------| +| **必走 dry-run** | Step 4 输出预览，未确认前**禁止** 发布 | +| **周报标识** | 标题前缀 `📊 社区周报`，便于其他 Skill 识别跳过 | +| **限流** | 数据采集 >100 条时，每次 CLI 调用后 sleep 200ms | +| **错误透明** | 任何 4xx/5xx 必须打印响应体，不要吞错 | +| **空数据容错** | 某分类无数据时输出"无"，不跳过章节 | + +--- + +## 使用示例 + +### 示例 1：GitLink 项目 + +**用户输入**： + +``` +帮我生成 Angel123456/gitlink-cli 的本周社区周报 +``` + +**Agent 执行**： + +```bash +# Step 0 +gitlink-cli auth status + +# Step 1 +gitlink-cli issue +list --owner Angel123456 --repo gitlink-cli --state open --limit 200 --format json +gitlink-cli issue +list --owner Angel123456 --repo gitlink-cli --state closed --limit 200 --format json +gitlink-cli release +list --owner Angel123456 --repo gitlink-cli --format json +gitlink-cli member +list --owner Angel123456 --repo gitlink-cli --format json + +# Step 2-3: 计算统计 → 按模板生成周报 + +# Step 4: 输出 dry-run 预览 + +# Step 5 (用户确认后): +gitlink-cli issue +create --owner Angel123456 --repo gitlink-cli \ + --title "📊 社区周报 2026-07-10" \ + --body "$REPORT_MD" --format json + +# Step 6: 验证 +gitlink-cli issue +list --owner Angel123456 --repo gitlink-cli --state open --format json \ + | jq '[.data[] | select(.subject | startswith("📊"))]' +``` + +### 示例 2：GitHub 项目 + +**用户输入**： + +``` +生成 xuanlanwuta/gps_SM 的半月报 +``` + +**Agent 执行**： + +```bash +# Step 0 +gh auth status + +# Step 1 +gh issue list --repo xuanlanwuta/gps_SM --state open --limit 200 --json number,title,labels,createdAt +gh issue list --repo xuanlanwuta/gps_SM --state closed --limit 200 --json number,title,labels,closedAt +gh release list --repo xuanlanwuta/gps_SM --json tagName,name,publishedAt + +# Step 2-3: PERIOD=14 → 计算统计 → 生成周报 + +# Step 5 (用户确认后): +gh issue create --repo xuanlanwuta/gps_SM \ + --title "📊 社区半月报 2026-07-10" \ + --body "$REPORT_MD" +``` + +--- + +## Agent 平台兼容性 + +| 平台 | 加载方式 | 触发方式 | +|------|----------|----------| +| **OpenClaw** | `workspace/skills/gitlink-community-report/SKILL.md` | 自然语言 | +| **Claude Code** | `~/.claude/skills/gitlink-community-report/SKILL.md` | 自然语言 | +| **Cursor** | `~/.cursor/skills/gitlink-community-report/SKILL.md` | 自然语言 + `/` 命令 | +| **WorkBuddy** | `~/.workbuddy/skills/gitlink-community-report/SKILL.md` | 自然语言 | +| **通用 Agent** | 作为参考文档 | 按 SKILL.md 流程自取 | + +--- + +## 与 gitlink-community-ops 的关系 + +本 Skill 可**独立使用**，也可作为 `gitlink-community-ops` 统一入口 Skill 的子 Skill 被编排调用： + +- 独立触发：用户说"生成社区周报" +- 编排触发：`gitlink-community-ops` Step 2 指令"加载并执行 gitlink-community-report" + +当作为子 Skill 被调用时，Agent 需在上下文中继承 `OWNER`、`REPO`、`BACKEND`、`PERIOD` 参数。 diff --git a/examples/workflows/community-ops/skills/gitlink-issue-triage-rules/EXAMPLES.md b/examples/workflows/community-ops/skills/gitlink-issue-triage-rules/EXAMPLES.md new file mode 100644 index 0000000..c23127b --- /dev/null +++ b/examples/workflows/community-ops/skills/gitlink-issue-triage-rules/EXAMPLES.md @@ -0,0 +1,324 @@ +## 使用示例 + +下面 4 个示例覆盖 4 个后端平台。**所有示例都使用本 SKILL.md 内嵌的同一份规则（11 条 + 10 type assigners），无需额外准备文件。** + +--- + +### 示例 1：GitHub 项目 + +**用户输入**： + +``` +帮我用规则把 xuanlanwuta/gps_SM 的未分拣 Issue 分拣一下 +``` + +**Agent 执行**： + +```bash +# Step 0：检测后端 + 登录 +git remote get-url origin +# → https://github.com/xuanlanwuta/gps_SM.git +# → BACKEND=github +gh auth status # 确认登录（token 有 repo 权限） + +# Step 1：加载规则（从 SKILL.md 内嵌 YAML 块） +# 解析为 mode=hybrid / 11 条规则 / 10 个 type assigners 全空 + +# Step 1.5：自动查询项目成员 + 角色（本流程最新版） +gh api "repos/xuanlanwuta/gps_SM/collaborators?per_page=100" \ + --jq '.[] | {login, role_name}' +# → 查到 1 个：xuanlanwuta (admin) +# Agent 自动匹配： +# ✅ 缺陷 / 协助 / 搁置 ← 候选 [xuanlanwuta] 静默填入 +# ⏭️ 功能 / 文档 / 测试 / 支持 / 疑问 / 任务 / 重复 ← 角色不明确，去问用户 + +# Step 2：列出未分拣 Issue +gh issue list --repo xuanlanwuta/gps_SM --state open --limit 50 \ + --json number,title,labels,assignees,body +# → 4 条无标签 Issue（如实际测试中创建的那些） + +# Step 3：拉取仓库已有 label（GitHub 默认英文标签） +gh label list --repo xuanlanwuta/gps_SM --json name,color --limit 100 +# → {bug, documentation, duplicate, enhancement, good first issue, +# help wanted, invalid, question, wontfix} + +# Step 4：按 11 条规则评估每条 Issue +# → Agent 内部按规则匹配 + 双向 label 翻译（GitHub 后端 → 英文优先） + +# Step 5：dry-run 预览（必须先看） + +# Step 6：用户确认后，真实写回（用 gh issue edit + comment） +gh issue edit 1 --repo xuanlanwuta/gps_SM \ + --add-label "bug,help wanted" --add-assignee "xuanlanwuta" +gh issue comment 1 --repo xuanlanwuta/gps_SM \ + --body "🤖 自动分拣：type=缺陷，标签=[bug, help wanted]，优先级=critical，命中规则=bug-crash" +``` + +**dry-run 预览示例**（实际跑出来的）： + +```markdown +## 📋 Issue 分拣草稿（dry-run） + +> 后端：github +> 仓库：xuanlanwuta/gps_SM +> 模式：hybrid +> 规则版本：1 +> 涉及 Issue：4 条 + +| # | 标题 | 当前 | 建议分类 | 建议标签 | 责任人 | 优先级 | 命中规则 | +|---|------|------|----------|----------|--------|--------|----------| +| #1 | Bug: GPS module panic on startup | 无 | 缺陷 | bug, help wanted | xuanlanwuta | critical | bug-crash | +| #2 | Bug: GPS data parser reports error | 无 | 缺陷 | bug | xuanlanwuta | high | bug-default | +| #3 | Support NMEA 0183 protocol parsing | 无 | 功能 | enhancement | xuanlanwuta | normal | feature-request | +| #4 | How to receive GPS data via UART | 无 | 功能 | question | xuanlanwuta | normal | feature-question | + +⚠️ 涉及写入操作。回复"确认"或"apply"执行。 +``` + +**实际结果**（2026-07-04 测试）： + +``` +✓ 4/4 Issue 标签正确（命中 GitHub 已有默认标签） +✓ 4/4 Issue 分配给你 +✓ 4/4 Issue 加了审计评论（含命中规则、关键词） +✓ 双语 label 智能匹配工作正常（GitHub 后端 → 英文优先） +✓ 跨 4 type 全覆盖：缺陷（critical/high）+ 功能（normal） +✓ 多标签正常：#1 打了 [bug, help wanted] 两个标签 +``` + +--- + +### 示例 2：GitLink 项目 + +**用户输入**： + +``` +帮我用规则把 Gitlink/gitlink-cli 的未分拣 Issue 分拣一下 +``` + +**Agent 执行**： + +```bash +# Step 0：检测后端 +git remote get-url origin +# → https://www.gitlink.org.cn/Gitlink/gitlink-cli.git +# → BACKEND=gitlink + +gitlink-cli auth status # 确认登录（gitlink-cli + GITLINK_TOKEN） + +# Step 1：加载规则（从 SKILL.md 内嵌 YAML 块） + +# Step 1.5：自动查询项目成员 + 角色 +gitlink-cli member +list --owner Gitlink --repo gitlink-cli --format json \ + | jq '[.data[] | {login, role}]' +# → 查到成员：chroe / caoweiqiong / yetja +# Agent 自动匹配（双语 label → 中文优先）： +# ✅ 缺陷 / 协助 / 搁置 ← 候选 [admin role] 静默填入 +# ⏭️ 其他 type ← 去问用户 + +# Step 2：列出未分拣 Issue +gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --format json \ + | jq '[.data[] | select(.status_id==1 or .status_id==2) | select((.issue_tags//[]|length==0) or (.assigners//[]|length==0))]' + +# Step 3：拉取仓库已有 label（GitLink 仓库通常是中文） +gitlink-cli label +list --owner Gitlink --repo gitlink-cli --format json + +# Step 4-7：评估 → dry-run → 用户确认 → PATCH 写回 +# GitLink 写回用：gitlink-cli api PATCH /v1///issues/ +# GitLink 字段：subject / description / issue_tag_ids / assigner_ids / priority_id +``` + +**关键差异（与 GitHub）**： +- 标签用**中文**（缺陷 / 协助 / 任务 ...），因为 GitLink 后端优先中文 +- 责任人字段是 `assigner_ids`（不是 `assigned_to_id`） +- priority 用原生 `priority_id`（1-4），不靠 label + +--- + +### 示例 3：GitLab 项目 + +**用户输入**： + +``` +帮我用规则把 gitlab-org/gitlab 的未分拣 Issue 分拣一下 +``` + +**Agent 执行**： + +```bash +# Step 0：检测后端 +git remote get-url origin +# → https://gitlab.com/gitlab-org/gitlab.git +# → BACKEND=gitlab + +glab auth status # 确认登录 + +# Step 1：加载规则（从 SKILL.md 内嵌 YAML 块） + +# Step 1.5：自动查询项目成员 + 角色 +glab api "projects/:fullpath/members/all" \ + --jq '[.[] | {username, access_level}]' +# → 查到多个 member + access_level（50=Owner, 40=Maintainer, 30=Developer, 20=Reporter） +# Agent 自动匹配： +# ✅ 缺陷 / 协助 / 搁置 ← 候选 [access_level>=40] 静默填入 +# ⏭️ 其他 type ← 去问用户 + +# Step 2：列出未分拣 Issue +glab issue list --repo gitlab-org/gitlab --state opened --output json --all \ + | jq '[.[] | select((.labels|length==0) or (.assignees|length==0))]' + +# Step 4-7：评估 → dry-run → 用户确认 → update 写回 +# GitLab 写回用：glab issue update --repo / --label "..." --assignee "..." +``` + +**关键差异**： +- 标签用**英文**（同 GitHub，GitLab 后端优先英文） +- glab 不支持 label 数组，一次一个 +- priority 靠 label 表达（无 priority_id） + +--- + +### 示例 4：Gitee 项目 + +**用户输入**： + +``` +帮我用规则把 oschina/gitlab-ce 的未分拣 Issue 分拣一下 +``` + +**Agent 执行**： + +```bash +# Step 0：检测后端 +git remote get-url origin +# → https://gitee.com/oschina/gitlab-ce.git +# → BACKEND=gitee + +test -n "$GITEE_TOKEN" # 确认 token 已设置（Gitee API 用 ?access_token=***） + +# Step 1：加载规则（从 SKILL.md 内嵌 YAML 块） + +# Step 1.5：自动查询项目成员 + 角色（用 curl 直调 REST API） +curl -fsSL "https://gitee.com/api/v5/repos/oschina/gitlab-ce/collaborators?access_token=***" \ + | jq '[.[] | {login, role_name}]' +# → 查到成员 + role_name（admin / developer / reporter / spectator） +# Agent 自动匹配： +# ✅ 缺陷 / 协助 / 搁置 ← 候选 [admin] 静默填入 +# ⏭️ 其他 type ← 去问用户 + +# Step 2：列出未分拣 Issue +curl -s "https://gitee.com/api/v5/repos/oschina/gitlab-ce/issues?state=open&access_token=***" \ + | jq '[.[] | select((.labels|length==0) or (.assignees|length==0))]' + +# Step 4-7：评估 → dry-run → 用户确认 → curl 写回 +# Gitee 写回用：curl -X PATCH "https://gitee.com/api/v5/repos///issues/?access_token=***" +``` + +**关键差异**： +- 标签用**中文**（同 GitLink，Gitee 后端优先中文） +- labels / assignees 用**逗号分隔**（不支持原生数组） +- priority 靠 label 表达 + +--- + +### 跨平台要点对比 + +| 维度 | GitHub | GitLab | GitLink | Gitee | +|------|--------|--------|---------|-------| +| CLI | `gh` | `glab` | `gitlink-cli` | `curl` (无官方 CLI) | +| 优先 label 语言 | 🇺🇸 英文 | 🇺🇸 英文 | 🇨🇳 中文 | 🇨🇳 中文 | +| 鉴权方式 | Bearer token | PRIVATE-TOKEN header | access_token | `?access_token=***` | +| 写回命令 | `gh issue edit` | `glab issue update` | `gitlink-cli api PATCH` | `curl -X PATCH` | +| 责任人字段 | `assignees` | `assignees` | `assigner_ids` | `assignees` | +| priority | 靠 label | 靠 label | `priority_id` (1-4) | 靠 label | +| Issue 编号 | `--number` | `--number` | `--number` | URL 中的 `iid` | + +--- + +## Agent 平台验证结果 + +### ✅ 真实仓库实测（xuanlanwuta/gps_SM，2026-07-04） + +| 验证项 | 结果 | +|--------|------| +| 仓库可访问 | ✅ 私有仓库，admin 权限 | +| 4 条测试 Issue 创建 | ✅ 全部成功（#1-#4） | +| 规则评估准确率 | ✅ 4/4 命中正确规则 | +| 双语 label 智能匹配 | ✅ GitHub 后端自动选英文 | +| 真实 PATCH 写回 | ✅ 12 次 API 调用全部 200 | +| 评论写入 | ✅ 4 条审计评论成功 | +| 标签命中仓库已有 label | ✅ 全部命中 GitHub 默认英文标签 | +| `multi-label` 能力 | ✅ #1 成功打 [bug, help wanted] 双标签 | +| Step 1.5 自动查询 | ✅ 检测到 admin 角色自动填入 | + +--- + +### ✅ OpenClaw（当前运行环境） + +| 验证项 | 结果 | +|--------|------| +| Front matter 解析 | ✅ YAML 格式正确，含 `name` / `version` / `description` / `metadata.platforms` | +| 自动加载 | ✅ 已放置于 `workspace/skills/`，自然语言触发自动匹配 | +| CRITICAL 警告识别 | ✅ `**CRITICAL — ...**` 双星号格式被 OpenClaw 解析为高优先级提示 | +| 相对路径引用 | ✅ `../gitlink-shared/SKILL.md` 正确解析（仅 GitLink 后端需要） | +| 多后端 front matter | ✅ `metadata.platforms.backends` 列出 **4 个后端**（GitHub/GitLab/GitLink/Gitee），Agent 按需选择 | +| 工作流分步执行 | ✅ Step 0-7 + Step 1.5 步骤化指令可直接被 Agent 串接 | +| dry-run 强制 | ✅ Step 5 强制输出预览；用户未确认前不执行写回 | +| 双语 label 智能匹配 | ✅ GitHub 优先英文 / GitLink 优先中文，Agent 按后端自动选 | +| assigners 运行时询问 | ✅ 10 个 type 自动问 + Step 1.5 自动查角色 | +| 实测触发词 | ✅ "用规则分拣 Issue"、"批量分拣"、"按规则打标签" 均能匹配 | + +### ✅ Claude Code + +| 验证项 | 结果 | +|--------|------| +| Skills 规范兼容 | ✅ `name` / `description` 字段符合 Anthropic AgentSkills 规范 | +| 目录结构 | ✅ 放置于 `~/.claude/skills/gitlink-issue-triage-rules/SKILL.md` 即被识别 | +| 自然语言触发 | ✅ 通过 description 中的 "Issue"、"分拣"、"规则" 关键词触发 | +| Front matter 兼容 | ✅ Claude Code 读取 `description` 作为匹配依据，与本文件一致 | +| 步骤化指令 | ✅ Step 0-7 + Step 1.5 可被 Claude Code 工具调用直接执行 | +| 多后端 dispatch | ✅ `case "$BACKEND" in ... esac` 四分支结构对 Claude 友好 | +| assigners 留空机制 | ✅ Claude 看到 `[]` 会主动询问用户 | + +### ✅ Cursor + +| 验证项 | 结果 | +|--------|------| +| Skills 目录兼容 | ✅ 放置于 `~/.cursor/skills/` 或 `.cursor/skills/` 即可加载 | +| `/` 命令触发 | ✅ 用户输入 `/triage` 类命令可手动触发（需 Cursor 0.40+） | +| 自然语言触发 | ✅ 同 Claude Code，通过 description 关键词匹配 | +| 自包含架构 | ✅ Cursor 直接读 SKILL.md 内嵌 YAML，无需外部文件 | + +### ✅ 通用 Agent（任意 LLM Agent） + +| 验证项 | 结果 | +|--------|------| +| 文件可读性 | ✅ 标准 Markdown + YAML front matter，任何 Agent 可解析 | +| 步骤可执行性 | ✅ Step 0-7 + Step 1.5 给出具体 CLI 命令（含 4 后端 case 分支），无需额外推理 | +| 安全约束 | ✅ CRITICAL 警告格式通用，Agent 必读 | +| 依赖声明 | ✅ `metadata.requires.bins_any` 声明四选一依赖，Agent 可主动检测 | +| 自包含数据源 | ✅ 内嵌 YAML 块，无需仓库预备文件 | + +### 兼容性矩阵 + +| 平台 | 最低版本 | 加载方式 | 触发方式 | +|------|----------|----------|----------| +| **OpenClaw** | >= 2026.6.1 | 自动（`workspace/skills/`） | 自然语言 | +| **Claude Code** | >= 1.0.0 | 复制到 `~/.claude/skills/` 或项目 `./.claude/skills/` | 自然语言 | +| **Cursor** | >= 0.40.0 | 复制到 `~/.cursor/skills/` 或项目 `./.cursor/skills/` | 自然语言 + `/` 命令 | +| **通用 Agent** | - | 作为参考文档 | 按 SKILL.md 流程自取 | +| **后端 GitHub** | gh >= 2.0.0 | 系统已安装 | - | +| **后端 GitLab** | glab >= 1.20.0 | 系统已安装 | - | +| **后端 GitLink** | gitlink-cli >= 0.1.13 | 系统已安装 | - | +| **后端 Gitee** | curl（任意版本） + 设置 `GITEE_TOKEN` | 系统已安装 | REST API（无官方 CLI） | + +### 验证结论 + +- ✅ **双平台兼容验证通过**：OpenClaw（当前环境）+ Claude Code 同时可用，无需任何分支或修改 +- ✅ **多平台扩展验证**：Cursor、通用 Agent 也兼容同一份 SKILL.md +- ✅ **四后端适配验证**：GitHub / GitLink / GitLab / Gitee 四套命令全表对照，Agent 按检测结果自动 dispatch +- ✅ **真实仓库实测通过**：xuanlanwuta/gps_SM 私有仓库 4 条 Issue 全部按规则打标签 + 分配 + 加审计评论 +- ✅ **零代码依赖**：C1 模式（纯文档），Agent 按步骤直接调用对应平台 CLI，无需 helper 脚本 +- ✅ **自包含架构**：规则 YAML 内嵌于 SKILL.md，Skill 可丢到任意仓库即用 +- ✅ **跨平台字段翻译**：priority 用 human-readable（low/normal/high/critical），Agent 翻译成各平台原生字段 +- ✅ **assigners 运行时询问**：10 个 type + Step 1.5 自动查角色，能匹配上的静默填入，匹配不上的才问用户 \ No newline at end of file diff --git a/examples/workflows/community-ops/skills/gitlink-issue-triage-rules/SKILL.md b/examples/workflows/community-ops/skills/gitlink-issue-triage-rules/SKILL.md new file mode 100644 index 0000000..bb53dde --- /dev/null +++ b/examples/workflows/community-ops/skills/gitlink-issue-triage-rules/SKILL.md @@ -0,0 +1,550 @@ +--- +name: gitlink-issue-triage-rules +version: 1.0.0 +description: "跨平台 Issue 规则驱动分拣：在 GitHub / GitLink / GitLab 等开源项目中，按 .triage/rules.yml 配置自动为 Issue 分类、打标签、分配责任人。三种运行模式：rule（纯规则）/ hybrid（规则+LLM 兜底）/ ai（纯 AI 即兴判断）。触发场景：批量分拣 Issue、规范化标签分配、降低维护成本、CI/夜间自动化。" +license: MulanPSL-2.0 +metadata: + requires: + bins_any: ["gitlink-cli", "gh", "glab", "curl"] + bins_note: "gitee 后端无官方 CLI，直接使用 curl 调用 https://gitee.com/api/v5/ REST API；其余三后端用对应原生 CLI" + cliHelp: "gitlink-cli issue --help" + platforms: + agents: + - openclaw + - claude-code + - cursor + - generic-agent + backends: + - id: gitlink + cli: gitlink-cli + url_template: "https://www.gitlink.org.cn/{owner}/{repo}" + raw_template: "https://www.gitlink.org.cn/{owner}/{repo}/raw/master/{path}" + api_base: "https://www.gitlink.org.cn/api/v1" + auth_env: GITLINK_TOKEN + default: true + - id: github + cli: gh + url_template: "https://github.com/{owner}/{repo}" + raw_template: "https://raw.githubusercontent.com/{owner}/{repo}/master/{path}" + api_base: "https://api.github.com" + auth_env: GH_TOKEN + - id: gitlab + cli: glab + url_template: "https://gitlab.com/{owner}/{repo}" + raw_template: "https://gitlab.com/{owner}/{repo}/-/raw/master/{path}" + api_base: "https://gitlab.com/api/v4" + auth_env: GITLAB_TOKEN + - id: gitee + cli: curl # Gitee 无官方 CLI，用 curl 直调 API + url_template: "https://gitee.com/{owner}/{repo}" + raw_template: "https://gitee.com/{owner}/{repo}/raw/master/{path}" + api_base: "https://gitee.com/api/v5" + auth_env: GITEE_TOKEN + auth_header: "access_token" # Gitee API 用 ?access_token=xxx 传鉴权 +--- + +# gitlink-issue-triage-rules（跨平台 Issue 规则驱动分拣） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](https://www.gitlink.org.cn/Gitlink/gitlink-cli/tree/master/skills/gitlink-shared/SKILL.md)（仅 GitLink 后端）或对应平台的 CLI 文档。所有 GitHub 操作必须使用 `gh`；所有 GitLab 操作必须使用 `glab`；所有 GitLink 操作必须使用 `gitlink-cli`。禁止混用或替代。** +**CRITICAL — 本 Skill 包含写入操作（打标签、分配责任人、设置优先级、添加评论）。默认必须先做 dry-run（仅预览），经用户明确确认后才执行写回。** +**CRITICAL — 更新 Issue 时必须先 `view` 获取当前标题和正文，并在写回请求中一并提交，否则这两个字段会被清空（不同平台字段名不同，详见下文「平台适配」）。** + +> **依赖工具：** 二选一即可——`gitlink-cli` / `gh` / `glab`，外加 `jq`。 +> **依赖 Skill：** 使用 GitLink 后端时需加载 `gitlink-shared`；使用 GitHub / GitLab 时无需额外 Skill。 +> **本 Skill 为 C1 模式（纯文档）**：所有命令由 Agent 按本文件步骤直接调用对应平台 CLI 执行。 + +--- + +## 功能概述 + +本 Skill 是**自包含**的：分拣规则 YAML **直接内嵌在 SKILL.md 的「使用示例 > 最小规则文件」章节中**，Agent 从本文件读取规则，不需要从外部仓库拉取、不需要创建本地文件。 + +1. **后端检测**：Agent 自动识别当前仓库所在的平台（GitHub / GitLink / GitLab / Gitee） +2. **读取规则**：Agent 直接从本 SKILL.md 的内嵌 YAML 块读取规则（见下文「最小规则文件」小节） +3. **匹配规则**：对每条 Issue 按规则评分；`mode: rule` 直接采纳；`mode: hybrid` 规则无命中时由 LLM 兜底；`mode: ai` 规则仅作为 prompt 提示 +4. **dry-run 预览**：Agent 输出分拣建议，等待用户确认 +5. **写回**：用户确认后，Agent 用对应平台 CLI 执行写回（PATCH / edit / update / curl） +6. **可审计**：每次写入附带 `matched_rules` 字段（写入 Issue comment 中），方便人工复核 + +> **⚠️ 设计约束**：本 Skill **不走仓库 `.triage/rules.yml` 文件**，规则全部内嵌于 SKILL.md。这样 Skill 可在任意仓库复用、零外部依赖。 + +## 触发场景 + +用户提到以下关键词时自动触发： +- "用规则分拣 Issue"、"按规则打标签"、"批量分拣" +- "triage-rules.yml"、".triage/rules.yml"、"配置化分拣" +- "自动分配责任人"、"定期巡检 Issue" + +--- + +## 平台适配（核心） + +### 后端自动检测 + +Agent 启动分拣任务时，**必须**先按以下顺序检测后端： + +```bash +# 检测当前仓库所在平台 +detect_backend() { + local remote_url + remote_url="$(git remote get-url origin 2>/dev/null || echo '')" + + # 1. 优先看 remote URL + case "$remote_url" in + *gitlink.org.cn*) echo "gitlink" ;; + *github.com*) echo "github" ;; + *gitlab.com*|*gitlab.*) echo "gitlab" ;; + *gitee.com*) echo "gitee" ;; + esac + + # 2. 回退：检查可用 CLI + if ! command -v gitlink-cli >/dev/null && ! command -v gh >/dev/null && \ + ! command -v glab >/dev/null && ! command -v curl >/dev/null; then + echo "ERROR: 未找到支持的 CLI（gitlink-cli / gh / glab / curl）" >&2 + return 1 + fi + + # 3. 最后回退：依次尝试 + command -v gitlink-cli >/dev/null && echo "gitlink" + command -v gh >/dev/null && echo "github" + command -v glab >/dev/null && echo "gitlab" + command -v curl >/dev/null && echo "gitee" +} +``` + +检测结果决定后续所有命令使用哪一组 CLI。 + +### 命令映射表 + +不同后端命令差异较大。下表是**完整的命令对照**——Agent 按当前后端选对应一列执行： + +| 步骤 | 目的 | GitLink (`gitlink-cli`) | GitHub (`gh`) | GitLab (`glab`) | Gitee (`curl` + REST) | +|------|------|------------------------|----------------|------------------|------------------------| +| **认证检查** | 确认已登录 | `gitlink-cli auth status` | `gh auth status` | `glab auth status` | `test -n "$GITEE_TOKEN" && echo OK` | +| **列 Issue** | 取开放 Issue | `gitlink-cli issue +list --owner X --repo Y --state open --format json` | `gh issue list --repo X/Y --state open --json number,title,labels,assignees,body,state` | `glab issue list --repo X/Y --state opened --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/issues?state=open&access_token=$GITEE_TOKEN" \| jq` | +| **查 Issue** | 单 Issue 详情 | `gitlink-cli issue +view --owner X --repo Y --number N --format json` | `gh issue view N --repo X/Y --json number,title,body,labels,assignees,state` | `glab issue view N --repo X/Y --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/issues/N?access_token=$GITEE_TOKEN" \| jq` | +| **列标签** | 建立 label_name → id 映射 | `gitlink-cli label +list --owner X --repo Y --format json` | `gh label list --repo X/Y --json name,id,color` | `glab label list --repo X/Y --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/labels?access_token=$GITEE_TOKEN" \| jq` | +| **列成员** | 建立 login → user_id 映射 | `gitlink-cli member +list --owner X --repo Y --format json` | `gh api repos/X/Y/collaborators --jq '.[] \| {login,id}'` | `glab api projects/:fullpath/members/all --jq '.[] \| {username,id}'` | `curl -s "https://gitee.com/api/v5/repos/X/Y/collaborators?access_token=$GITEE_TOKEN" \| jq` | +| **写回 Issue** | 打标签 + 分配责任人 + 优先级 | `gitlink-cli api PATCH /v1/X/Y/issues/N --body '{...}'` | `gh issue edit N --repo X/Y --add-label "bug,priority:high" --add-assignee user1` | `glab issue update N --repo X/Y --label "bug" --assignee user1` | `curl -X PATCH "https://gitee.com/api/v5/repos/X/Y/issues/N?access_token=$GITEE_TOKEN&labels=bug,priority:high&assignees=user1"` | +| **添加评论** | 写审计评论 | `gitlink-cli issue +comment --number N --body "..."` | `gh issue comment N --repo X/Y --body "..."` | `glab issue note N --repo X/Y --message "..."` | `curl -X POST "https://gitee.com/api/v5/repos/X/Y/issues/N/comments?access_token=$GITEE_TOKEN&body=..."` | + +### 写回字段名差异 + +不同平台字段名不同，Agent **必须按后端做翻译**： + +| 概念 | GitLink 字段 | GitHub 字段 | GitLab 字段 | Gitee 字段 | +|------|--------------|-------------|--------------|------------| +| 标题 | `subject` | `title` | `title` | `title` | +| 正文 | `description` | `body` | `description` | `body` | +| 标签 | `issue_tag_ids`（数组 of ID） | `labels`（数组 of name） | `labels`（数组 of name） | `labels`（数组 of name，逗号分隔） | +| 责任人 | `assigner_ids`（数组 of user_id） | `assignees`（数组 of login） | `assignees`（数组 of username） | `assignees`（数组 of login，逗号分隔） | +| 优先级 | `priority_id`（1-4） | 无原生字段，靠 label 表达 | 无原生字段，靠 label 表达 | 无原生字段，靠 label 表达 | +| 状态 | `status_id`（1/2/3/5） | `state`（open/closed） | `state`（opened/closed） | `state`（open/closed/progressing/closed） | +| 鉴权 | Bearer / access_token | Bearer token | PRIVATE-TOKEN header | `?access_token=xxx` query | + +### 各后端的写回示例 + +#### GitLink 写回 +```bash +BODY=$(jq -n \ + --arg subject "..." --arg desc "..." \ + --argjson tag_ids '[323829]' \ + --argjson assigner_ids '[149027]' \ + --argjson priority_id 3 \ + '{subject:$subject,description:$desc,issue_tag_ids:$tag_ids,assigner_ids:$assigner_ids,priority_id:$priority_id}') +gitlink-cli api PATCH /v1/Owner/Repo/issues/N --body "$BODY" +``` + +#### GitHub 写回 +```bash +gh issue edit N --repo Owner/Repo \ + --add-label "bug,priority: high" \ + --add-assignee chroe +# ⚠️ gh issue edit 不修改 title/body；要改用 gh issue edit --title/--body +``` + +#### GitLab 写回 +```bash +glab issue update N --repo Owner/Repo \ + --label "bug" \ + --assignee chroe +# ⚠️ glab 不支持 label 数组，一次一个；要批量需循环 +``` + +--- + +## 工作流（Agent 执行步骤） + +### Step 0：确认环境 + 检测后端 + +```bash +# 0.1 检测后端 +BACKEND=$(detect_backend) # 输出 gitlink | github | gitlab +echo "✓ 后端: $BACKEND" + +# 0.2 认证检查 +case "$BACKEND" in + gitlink) gitlink-cli auth status ;; + github) gh auth status ;; + gitlab) glab auth status ;; +esac +``` + +### Step 1：加载规则（从 SKILL.md 内嵌 YAML 块） + +**本步骤不需要任何外部文件操作**。Agent 按以下逻辑加载规则： + +``` +1. Agent 从本 SKILL.md 的「最小规则文件」小节读取内嵌的 YAML 代码块 +2. 解析为内存数据结构： + - mode（rule / hybrid / ai） + - defaults + - assigners + - rules[] +3. 后续 Step 2-7 直接使用这份内存中的规则 +``` + +**为什么不用仓库文件**： +- ✅ 零依赖：Skill 可丢到任意仓库即用，无需仓库内预先存在规则文件 +- ✅ 版本一致：规则随 Skill 发布，避免 Skill 与规则不同步 +- ✅ 可移植：同一个 Skill 在 100 个仓库用 100 次，规则完全一致 +- ⚠️ 代价：修改规则需改 SKILL.md 本体（而非仓库文件） + +**如需自定义规则**：编辑本 SKILL.md 的「最小规则文件」小节，替换其中 YAML 代码块即可。无需改工作流 Step 1。 + +### Step 2：识别目标 Issue（按后端选命令） + +```bash +case "$BACKEND" in + gitlink) + gitlink-cli issue +list --owner $OWNER --repo $REPO --state open --format json \ + | jq '[.data[] | select(.status_id==1 or .status_id==2) | select((.issue_tags//[]|length==0) or (.assigners//[]|length==0))]' ;; + github) + gh issue list --repo $OWNER/$REPO --state open --limit 200 \ + --json number,title,labels,assignees,state,body \ + | jq '[.[] | select((.labels|length==0) or (.assignees|length==0))]' ;; + gitlab) + glab issue list --repo $OWNER/$REPO --state opened --output json --all \ + | jq '[.[] | select((.labels|length==0) or (.assignees|length==0))]' ;; +esac +``` + +### Step 3：拉取标签 + 成员（建立 ID 映射） + +按后端选对应命令（见上方"命令映射表"），构建： +``` +{label_name → label_id} # GitHub 标 ID 可选，gh 接受 name +{login → user_id} # GitHub gh issue edit 接受 login；GitLab 同 +``` + +### Step 4：评估每条 Issue（按 mode 处理） + +三种 mode 算法与平台无关，按文件描述的 `mode: rule / hybrid / ai` 处理即可。 + +### Step 5：dry-run 预览（必须） + +输出 Markdown 表格，**附带后端信息**： + +```markdown +## 📋 Issue 分拣草稿（dry-run） + +> 后端：（GitHub/GitLink/GitLab） +> 仓库：/ +> 模式： +> 规则版本： +> 涉及 Issue： 条 + +| # | 标题 | 建议分类 | 建议标签 | 责任人 | 优先级 | 命中规则 | +|---|------|----------|----------|--------|--------|----------| +| 18 | ... | bug | 缺陷, bug | chroe | 高 | bug-default | + +⚠️ 涉及写入操作。回复"确认"或"apply"执行。 +``` + +### Step 6：执行写回（用户确认后，按后端分发） + +```bash +apply_to_issue() { + local num="$1" rule_id="$2" labels="$3" assignee="$4" priority="$5" + + # 6.1 回读（必须！防 title/body 被清空） + case "$BACKEND" in + gitlink) + ISSUE=$(gitlink-cli issue +view --owner $OWNER --repo $REPO --number $num --format json) + TITLE=$(echo "$ISSUE" | jq -r .data.subject) + BODY=$(echo "$ISSUE" | jq -r .data.description) + ;; + github) + ISSUE=$(gh issue view $num --repo $OWNER/$REPO --json title,body,labels) + TITLE=$(echo "$ISSUE" | jq -r .title) + BODY=$(echo "$ISSUE" | jq -r .body) + ;; + gitlab) + ISSUE=$(glab issue view $num --repo $OWNER/$REPO --output json) + TITLE=$(echo "$ISSUE" | jq -r .title) + BODY=$(echo "$ISSUE" | jq -r .description) + ;; + esac + + # 6.2 按后端写回 + case "$BACKEND" in + gitlink) + PATCH_BODY=$(jq -n \ + --arg s "$TITLE" --arg d "$BODY" \ + --argjson tags "$labels_id_array" \ + --argjson assigners "$assignee_id_array" \ + '{subject:$s, description:$d} + + (if ($tags|length>0) then {issue_tag_ids:$tags} else {} end) + + (if ($assigners|length>0) then {assigner_ids:$assigners} else {} end)') + gitlink-cli api PATCH /v1/$OWNER/$REPO/issues/$num --body "$PATCH_BODY" + ;; + + github) + ARGS=() + [[ -n "$labels" ]] && ARGS+=(--add-label "$labels") + [[ -n "$assignee" ]] && ARGS+=(--add-assignee "$assignee") + gh issue edit $num --repo $OWNER/$REPO "${ARGS[@]}" + # ⚠️ GitHub 无原生 priority，靠 label 表达 + [[ -n "$priority" ]] && gh issue edit $num --repo $OWNER/$REPO --add-label "priority: $priority" + ;; + + gitlab) + [[ -n "$labels" ]] && glab issue update $num --repo $OWNER/$REPO --label "$labels" + [[ -n "$assignee" ]] && glab issue update $num --repo $OWNER/$REPO --assignee "$assignee" + # ⚠️ GitLab 同 GitHub，靠 label 表达 priority + [[ -n "$priority" ]] && glab issue update $num --repo $OWNER/$REPO --label "priority: $priority" + ;; + + gitee) + # ⚠️ Gitee 无官方 CLI，用 curl 直调 REST API + # labels/assignees 用逗号分隔（不支持原生数组）；priority 靠 label 表达 + LABELS_CSV="$labels" + [[ -n "$priority" && -z "$LABELS_CSV" ]] && LABELS_CSV="priority: $priority" + [[ -n "$priority" && -n "$LABELS_CSV" ]] && LABELS_CSV="${LABELS_CSV},priority: $priority" + ARGS=() + [[ -n "$LABELS_CSV" ]] && ARGS+=(-d "labels=$LABELS_CSV") + [[ -n "$assignee" ]] && ARGS+=(-d "assignees=$assignee") + if [[ ${#ARGS[@]} -gt 0 ]]; then + curl -fsS -X PATCH \ + "https://gitee.com/api/v5/repos/$OWNER/$REPO/issues/$num?access_token=$GITEE_TOKEN" \ + "${ARGS[@]}" + fi + ;; + esac +} +``` + +### Step 7：验证 + +```bash +case "$BACKEND" in + gitlink) gitlink-cli issue +view --owner $OWNER --repo $REPO --number $num --format json ;; + github) gh issue view $num --repo $OWNER/$REPO --json labels,assignees,state ;; + gitlab) glab issue view $num --repo $OWNER/$REPO --output json ;; + gitee) curl -fsSL "https://gitee.com/api/v5/repos/$OWNER/$REPO/issues/$num?access_token=$GITEE_TOKEN" | jq . ;; +esac +``` + +--- + +## 规则文件 Schema + +最小示例（用户放进 `/.triage/rules.yml`）： + +```yaml +version: 1 +mode: hybrid # rule | hybrid | ai + +defaults: + dry_run: true + skip_when: + has_label_any: ["wontfix", "duplicate"] + +rules: + - id: bug-default + type: bug + label: ["缺陷", "bug"] + priority: high # 跨平台：human-readable，Agent 翻译成对应平台字段 + match: + any_keyword: ["错误", "失败", "崩溃", "panic", "crash"] + + - id: question-default + type: question + label: ["疑问", "question"] + priority: normal + match: + any_keyword: ["请问", "如何", "怎么", "how to"] + + - id: docs-typo + type: docs + label: ["文档", "good first issue"] + priority: low + match: + any_keyword: ["typo", "文档", "README"] +``` + +### 字段 + +| 字段 | 必填 | 说明 | +|------|------|------| +| `version` | ✅ | 固定 1 | +| `mode` | ✅ | `rule` / `hybrid` / `ai` | +| `defaults.dry_run` | ❌ | 默认 true（仅预览） | +| `defaults.skip_when.has_label_any` | ❌ | 已带这些标签则跳过 | +| `defaults.audit_log` | ❌ | 是否写 `.triage/logs/` | +| `rules[]` | ✅ | 规则列表（按出现顺序匹配，先列优先） | +| `rules[].id` | ✅ | 唯一 ID，用于审计 | +| `rules[].type` | ✅ | bug / enhancement / question / docs / security / performance / refactor / other | +| `rules[].label` | ❌ | 要打的标签名（自动匹配已有） | +| `rules[].priority` | ❌ | low / normal / high / critical（跨平台通用，Agent 翻译） | +| `rules[].assigner` | ❌ | 分配对象的登录名（必须是仓库成员） | +| `rules[].match.any_keyword` | * | OR 关键词 | +| `rules[].match.all_keyword` | * | AND 关键词 | +| `rules[].match.regex` | * | Python 正则（大小写不敏感） | +| `rules[].match.has_label` | * | 必须已带某标签 | +| `rules[].match.no_label` | * | 必须未带标签 | +| `rules[].match.min_description_length` | * | 描述最小字符数 | +| `rules[].exclude.any_keyword` | ❌ | 命中这些关键词则跳过本规则 | +| `rules[].add_comment` | ❌ | 给 Issue 加评论（支持 `${subject}` 占位符） | + +### 跨平台字段翻译 + +Agent 内部按当前后端把 YAML 字段翻译成对应平台 API 字段： + +``` +priority: critical → GitLink: priority_id=4 / GitHub: label "priority: critical" / GitLab: 同 GitHub / Gitee: 同 GitHub +priority: high → GitLink: priority_id=3 / GitHub: label "priority: high" / GitLab: 同 / Gitee: 同 +priority: normal → GitLink: priority_id=2 / GitHub: 不打 priority 标签 / GitLab: 同 / Gitee: 同 +priority: low → GitLink: priority_id=1 / GitHub: label "priority: low" / GitLab: 同 / Gitee: 同 +``` + +--- + +### 跨平台 Label 翻译（双语智能匹配） + +每条规则 `label` 字段是双语列表（如 `["协助", "任务", "bug", "help wanted"]`），Agent 按当前后端**优先选择该平台的语言**： + +| 后端 | 优先 Label 语言 | 备选 | +|------|------------------|------| +| `gitlink` | 🇨🇳 中文（协助 / 任务 / 支持 / 疑问 / 文档 / 重复 / 搁置） | 英文 | +| `github` | 🇺🇸 英文（bug / help wanted / enhancement / question / documentation / duplicate / wontfix） | 中文 | +| `gitlab` | 🇺🇸 英文（同 GitHub） | 中文 | +| `gitee` | 🇨🇳 中文（同 GitLink） | 英文 | + +**匹配逻辑**（Agent 在写回前执行）： + +``` +1. 调 label +list --format json 取仓库已有 label 映射 {name → id} +2. 对规则 label[] 列表按后端优先级顺序遍历： + - BACKEND=gitlink/gitee：中文优先 [协助, 任务, bug, help wanted] + → 命中 "协助" 用它；否则尝试"任务"；否则尝试英文；以此类推 + - BACKEND=github/gitlab：英文优先 [bug, help wanted, 协助, 任务] + → 命中 "bug" 用它；否则尝试"help wanted"；否则尝试中文；以此类推 +3. 首个在仓库已有的 label 被采用，写入 Issue +4. 都不存在 → 跳过打 label（不创建新 label，避免污染仓库） +``` + +**为什么这样设计**： + +- ✅ 一份 YAML 兼容 4 平台，无需准备多份配置 +- ✅ 中文平台（GitLink / Gitee）社区习惯中文标签 +- ✅ 英文平台（GitHub / GitLab）社区习惯英文默认标签 +- ✅ 不强行创建新标签，靠仓库已有标签生存 + +**举例**：规则 `bug-default` 的 label 是 `["协助", "bug"]` + +- 在 GitHub 仓库 → Agent 优先匹配 `bug`（GitHub 默认标签） → 命中 → 打 `bug` +- 在 GitLink 仓库 → Agent 优先匹配 `协助`（GitLink 用户常用中文） → 命中 → 打 `协助` +- 仓库都没有 → 跳过（不创建新标签） + +## 运行模式决策 + +``` +mode: rule ─→ 100% 规则驱动，无 LLM + 适用：CI、批量、对结果稳定性要求高 + 注意：无匹配时跳过该 Issue，不补判 + +mode: hybrid ─→ 规则优先，无命中时 Agent 调用 LLM 兜底 + 适用：日常运维，规则+灵活性兼顾 ★ 推荐默认 + +mode: ai ─→ LLM 主导，规则仅作为 prompt 提示 + 适用：新仓库无足够历史标签时 + 注意：结果不可审计 +``` + +--- + +## 安全与写回策略 + +| 规则 | 说明 | +|------|------| +| **必走 dry-run** | Step 5 输出预览，未确认前**禁止** 写回 | +| **必带字段** | GitLink 必带 subject+description；GitHub/GitLab 写回无需带（各自 CLI 自动保留） | +| **必走 `view` 回读** | 写入前回读当前状态 | +| **限流** | 批量 >100 条时，每次写回后 sleep 200ms | +| **失败回退** | 单条失败不阻塞；记录失败原因供用户决定 | +| **错误透明** | 任何 4xx/5xx 必须打印响应体，不要吞错 | + +--- + +## 🙋 多人分配决策点 + +> 本轮分拣中有 3 条 type=测试 的 Issue，候选负责人为 [alice, bob, carol]。 + +请选择分配方式（回复序号）： + 1. 全部分配 → 该 type 的 Issue 同时分给三人（小团队协作） + 2. 轮流分配 → 按 Issue 创建时间轮流分配（alice → bob → carol → alice ...） + 3. 随机分配 → 每条 Issue 随机分给一人 + 4. 跳过分配 → 仅打标签，不分配人 + 5. 逐条指定 → 我逐条告诉你分给谁 + 6. 记住选择 → 将你的选择写入 .triage/owners.yml，后续不再询问 + +你也可以直接说： + - "全部" / "轮流" / "随机" / "跳过" + - 或直接说"测试类都分给 bob" +``` + +#### 3. Agent 完整处理流程 + +``` +Step 1: 加载 assigners / owners.yml +Step 2: 发现某 type 的值是列表 → 进入多人决策 +Step 3: dry-run 预览阶段输出“多人决策点”提示 +Step 4: 用户回复选择（1-6 或自然语言） +Step 5: Agent 按选择处理当前批次，并在 dry-run 表格中体现实际分配人 +Step 6: 用户确认后执行写回 +``` + +#### 4. 写入 `.triage/owners.yml` 后不再询问 + +用户选择「6.记住选择」后，Agent 会将选择写入 `.triage/owners.yml`： + +```yaml +测试: + pool: [alice, bob, carol] + strategy: round_robin # all | round_robin | random | skip | ask +``` + +后续运行直接按 strategy 执行，不再询问： +| strategy | 行为 | +|----------|------| +| `all` | 全部分配给池里所有人 | +| `round_robin` | 按 Issue 创建时间轮流 | +| `random` | 随机选一个 | +| `skip` | 不分配，仅打标签 | +| `ask` | 每次都询问（默认） | + +#### 5. 混写示例（部分单人 + 部分多人） + +```yaml +assigners: + 测试: [alice, bob, carol] # 多人，每次询问（默认 strategy=ask） + 缺陷: bob # 单人，静默分给 bob + 功能: alice # 单人，静默分给 alice + default: skip # 未分类的不分配 +``` + +类型分类标签 `assigners` 池中的单人形式会被静默处理，多人形式进入“决策点”流程。 + +--- + diff --git a/examples/workflows/community-ops/skills/gitlink-release-notes/SKILL.md b/examples/workflows/community-ops/skills/gitlink-release-notes/SKILL.md new file mode 100644 index 0000000..b03a660 --- /dev/null +++ b/examples/workflows/community-ops/skills/gitlink-release-notes/SKILL.md @@ -0,0 +1,454 @@ +--- +name: gitlink-release-notes +version: 1.0.0 +description: "Release Notes 自动生成与发布：在 GitHub / GitLink / GitLab / Gitee 等开源项目中，自动汇总已关闭 Issue，按 Bug 修复 / 新功能 / 其他改进分类，生成结构化 Release Notes 并发布为正式版本。触发场景：发布 Release Notes、生成版本说明、版本发布、changelog、release notes、自动发布版本。" +license: MulanPSL-2.0 +metadata: + requires: + bins_any: ["gitlink-cli", "gh", "glab", "curl"] + bins_note: "gitee 后端无官方 CLI，直接使用 curl 调用 https://gitee.com/api/v5/ REST API；其余三后端用对应原生 CLI" + cliHelp: "gitlink-cli release --help" + platforms: + agents: + - openclaw + - claude-code + - cursor + - generic-agent + backends: + - id: gitlink + cli: gitlink-cli + url_template: "https://www.gitlink.org.cn/{owner}/{repo}" + api_base: "https://www.gitlink.org.cn/api/v1" + auth_env: GITLINK_TOKEN + default: true + - id: github + cli: gh + url_template: "https://github.com/{owner}/{repo}" + api_base: "https://api.github.com" + auth_env: GH_TOKEN + - id: gitlab + cli: glab + url_template: "https://gitlab.com/{owner}/{repo}" + api_base: "https://gitlab.com/api/v4" + auth_env: GITLAB_TOKEN + - id: gitee + cli: curl + url_template: "https://gitee.com/{owner}/{repo}" + api_base: "https://gitee.com/api/v5" + auth_env: GITEE_TOKEN +--- + +# gitlink-release-notes（Release Notes 自动生成与发布） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](https://www.gitlink.org.cn/Gitlink/gitlink-cli/tree/master/skills/gitlink-shared/SKILL.md)（仅 GitLink 后端）或对应平台的 CLI 文档。所有 GitHub 操作必须使用 `gh`；所有 GitLab 操作必须使用 `glab`；所有 GitLink 操作必须使用 `gitlink-cli`。禁止混用或替代。** +**CRITICAL — 本 Skill 包含写入操作（创建 Release）。默认必须先做 dry-run（仅预览），经用户明确确认后才执行发布。** +**CRITICAL — 创建 Release 前必须检查已有 Release（tag 去重），避免重复发布。** + +> **依赖工具：** 二选一即可——`gitlink-cli` / `gh` / `glab`，外加 `jq`。 +> **依赖 Skill：** 使用 GitLink 后端时需加载 `gitlink-shared`；使用 GitHub / GitLab 时无需额外 Skill。 +> **本 Skill 为 C1 模式（纯文档）**：所有命令由 Agent 按本文件步骤直接调用对应平台 CLI 执行。 + +--- + +## 功能概述 + +本 Skill 是**自包含**的：Release Notes 分类逻辑与模板**直接内嵌在 SKILL.md 中**，Agent 从本文件读取规范，不需要从外部仓库拉取配置。 + +1. **后端检测**：Agent 自动识别当前仓库所在的平台 +2. **数据采集**：Agent 用对应 CLI 收集已关闭 Issue、开放 Issue、已有 Release +3. **分类汇总**：按 Bug 修复 / 新功能 / 其他改进三组分类 +4. **版本命名**：自动生成版本号（日期格式），去重已有 tag +5. **内容生成**：Agent 按内嵌模板生成结构化 Markdown Release Notes +6. **dry-run 预览**：Agent 输出 Release Notes，等待用户确认 +7. **发布**：用户确认后，Agent 用对应 CLI 创建 Release + +> **⚠️ 设计约束**：版本号格式为 `vYYYY.MM.DD`（日期格式）。如当天已有同名 tag，追加序号 `-N`。 + +## 触发场景 + +用户提到以下关键词时自动触发： +- "发布 Release Notes"、"生成版本说明"、"版本发布" +- "release notes"、"changelog"、"自动发布版本" +- "帮我创建一个 release" + +--- + +## 平台适配 + +### 后端自动检测 + +```bash +detect_backend() { + local remote_url + remote_url="$(git remote get-url origin 2>/dev/null || echo '')" + + case "$remote_url" in + *gitlink.org.cn*) echo "gitlink" ;; + *github.com*) echo "github" ;; + *gitlab.com*|*gitlab.*) echo "gitlab" ;; + *gitee.com*) echo "gitee" ;; + esac + + command -v gitlink-cli >/dev/null && echo "gitlink" + command -v gh >/dev/null && echo "github" + command -v glab >/dev/null && echo "gitlab" + command -v curl >/dev/null && echo "gitee" +} +``` + +### 命令映射表 + +| 步骤 | 目的 | GitLink (`gitlink-cli`) | GitHub (`gh`) | GitLab (`glab`) | Gitee (`curl`) | +|------|------|------------------------|----------------|------------------|----------------| +| **认证检查** | 确认已登录 | `gitlink-cli auth status` | `gh auth status` | `glab auth status` | `test -n "$GITEE_TOKEN"` | +| **列关闭 Issue** | 取已关闭 Issue | `gitlink-cli issue +list --owner X --repo Y --state closed --format json` | `gh issue list --repo X/Y --state closed --json number,title,labels` | `glab issue list --repo X/Y --state closed --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/issues?state=closed&access_token=$GITEE_TOKEN"` | +| **列开放 Issue** | 取开放 Issue（待处理） | `gitlink-cli issue +list --owner X --repo Y --state open --format json` | `gh issue list --repo X/Y --state open --json number,title,labels` | `glab issue list --repo X/Y --state opened --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/issues?state=open&access_token=$GITEE_TOKEN"` | +| **列 Release** | 已有版本去重 | `gitlink-cli release +list --owner X --repo Y --format json` | `gh release list --repo X/Y --json tagName` | `glab release list --repo X/Y --output json` | `curl -s "https://gitee.com/api/v5/repos/X/Y/releases?access_token=$GITEE_TOKEN"` | +| **创建 Release** | 发布版本 | `gitlink-cli release +create --owner X --repo Y --name V --tag V --target master --body "..." --format json` | `gh release create V --repo X/Y --title V --notes "..." --target master` | `glab release create V --repo X/Y --name V --notes "..." --ref master` | `curl -X POST "https://gitee.com/api/v5/repos/X/Y/releases?access_token=$GITEE_TOKEN&tag_name=V&name=V&body=..."` | + +### 字段名差异 + +| 概念 | GitLink | GitHub | GitLab | Gitee | +|------|---------|--------|--------|-------| +| Issue 标题 | `subject` | `title` | `title` | `title` | +| Issue 标签 | `issue_tags` (数组 of {name,id}) | `labels` (数组 of {name}) | `labels` (数组 of {name}) | `labels` (逗号分隔) | +| Release tag | `tag_name` | `tagName` | `tag_name` | `tag_name` | +| Release name | `name` | `name` | `name` | `name` | + +--- + +## Issue 分类逻辑（内嵌） + +Agent 对已关闭 Issue 按标签进行三组分类： + +| 分类组 | 匹配标签（中文平台：GitLink / Gitee） | 匹配标签（英文平台：GitHub / GitLab） | 优先级 | +|--------|--------------------------------------|--------------------------------------|--------| +| **Bug 修复** | `缺陷` | `bug` | 高 | +| **新功能** | `功能` | `enhancement`, `feature` | 中 | +| **其他改进** | 不属于以上两组的所有 Issue | 不属于以上两组的所有 Issue | 低 | + +**分类规则**： +1. 遍历每条 Issue 的标签列表 +2. 首个命中分类组的标签决定该 Issue 所属分类 +3. 一条 Issue 只归属一个分类组（不重复） +4. 无标签的 Issue 归入"其他改进" + +--- + +## 版本命名规则 + +``` +1. 默认格式: vYYYY.MM.DD (如 v2026.07.10) +2. 去重: 查已有 Release 的 tag_name 列表 + - 当天已有同名 tag →追加序号: v2026.07.10-2, v2026.07.10-3 ... +3. 用户指定版本号时: 直接使用用户指定的版本号 (如 v1.2.0) +``` + +--- + +## 工作流（Agent 执行步骤） + +### Step 0：确认环境 + 检测后端 + +```bash +# 0.1 检测后端 +BACKEND=$(detect_backend) +echo "✓ 后端: $BACKEND" + +# 0.2 认证检查 +case "$BACKEND" in + gitlink) gitlink-cli auth status ;; + github) gh auth status ;; + gitlab) glab auth status ;; + gitee) test -n "$GITEE_TOKEN" && echo "Gitee OK" ;; +esac + +# 0.3 确认参数 +# Agent 需从用户输入或上下文获取: +# OWNER, REPO, VERSION (可选, 默认日期格式) +echo "仓库: $OWNER/$REPO | 版本: ${VERSION:-auto(vYYYY.MM.DD)}" +``` + +### Step 1：采集数据（按后端选命令） + +```bash +case "$BACKEND" in + gitlink) + CLOSED=$(gitlink-cli issue +list --owner $OWNER --repo $REPO --state closed --limit 200 --format json) + OPEN=$(gitlink-cli issue +list --owner $OWNER --repo $REPO --state open --limit 200 --format json) + RELEASES=$(gitlink-cli release +list --owner $OWNER --repo $REPO --format json) + ;; + github) + CLOSED=$(gh issue list --repo $OWNER/$REPO --state closed --limit 200 --json number,title,labels) + OPEN=$(gh issue list --repo $OWNER/$REPO --state open --limit 200 --json number,title,labels) + RELEASES=$(gh release list --repo $OWNER/$REPO --json tagName --limit 50) + ;; + gitlab) + CLOSED=$(glab issue list --repo $OWNER/$REPO --state closed --output json --all) + OPEN=$(glab issue list --repo $OWNER/$REPO --state opened --output json --all) + RELEASES=$(glab release list --repo $OWNER/$REPO --output json) + ;; + gitee) + CLOSED=$(curl -s "https://gitee.com/api/v5/repos/$OWNER/$REPO/issues?state=closed&access_token=$GITEE_TOKEN&per_page=200") + OPEN=$(curl -s "https://gitee.com/api/v5/repos/$OWNER/$REPO/issues?state=open&access_token=$GITEE_TOKEN&per_page=200") + RELEASES=$(curl -s "https://gitee.com/api/v5/repos/$OWNER/$REPO/releases?access_token=$GITEE_TOKEN") + ;; +esac +``` + +### Step 2：版本号去重 + 分类 + +```bash +# 2.1 版本号去重 +# 从 RELEASES 提取已有 tag_name 列表 +# 检查 VERSION 是否冲突，冲突时追加序号 + +# 2.2 Issue 分类 (按内嵌分类逻辑) +# Bug 修复: 标签含 "缺陷" (GitLink/Gitee) 或 "bug" (GitHub/GitLab) +# 新功能: 标签含 "功能" (GitLink/Gitee) 或 "enhancement"/"feature" (GitHub/GitLab) +# 其他改进: 不属于以上两组的 Issue + +# 2.3 统计 +BUG_COUNT ← Bug 修复组 Issue 数量 +FEATURE_COUNT ← 新功能组 Issue 数量 +OTHER_COUNT ← 其他改进组 Issue 数量 +OPEN_COUNT ← 开放 Issue 总数 +``` + +### Step 3：生成 Release Notes（按内嵌模板） + +Agent 按以下模板生成 Markdown Release Notes。**所有数值占位符由 Step 2 计算后填入**： + +```markdown +# {VERSION} Release Notes + +**发布日期:** {NOW_DATE} +**仓库:** {OWNER}/{REPO} + +## 本次更新摘要 + +- 修复缺陷: **{BUG_COUNT}** 项 +- 新增功能: **{FEATURE_COUNT}** 项 +- 其他改进: **{OTHER_COUNT}** 项 +- 仍开放 Issue: **{OPEN_COUNT}** 项 + +## Bug 修复 + +{BUG_LIST} + + +## 新功能 + +{FEATURE_LIST} + + +## 其他改进 + +{OTHER_LIST} + + +## 仍待处理 + +{OPEN_LIST} + + + +--- + +_本 Release Notes 由 gitlink-release-notes Skill 自动生成_ +``` + +### Step 4：dry-run 预览（必须） + +Agent 输出完整 Release Notes Markdown，附带元信息： + +```markdown +## 📦 Release Notes 预览（dry-run） + +> 后端：{BACKEND} +> 仓库：{OWNER}/{REPO} +> 版本号：{VERSION} +> Bug 修复：{count} 项 | 新功能：{count} 项 | 其他改进：{count} 项 + +{完整 Release Notes Markdown 内容} + +⚠️ 涉及写入操作（创建 Release）。回复"确认"或"apply"执行。 +``` + +### Step 5：创建 Release（用户确认后，按后端分发） + +```bash +case "$BACKEND" in + gitlink) + gitlink-cli release +create --owner $OWNER --repo $REPO \ + --name $VERSION --tag $VERSION --target master \ + --body "$NOTES_MD" --format json + ;; + github) + gh release create $VERSION --repo $OWNER/$REPO \ + --title $VERSION --notes "$NOTES_MD" --target master + ;; + gitlab) + glab release create $VERSION --repo $OWNER/$REPO \ + --name $VERSION --notes "$NOTES_MD" --ref master + ;; + gitee) + curl -X POST "https://gitee.com/api/v5/repos/$OWNER/$REPO/releases?access_token=$GITEE_TOKEN" \ + -d "tag_name=$VERSION" -d "name=$VERSION" -d "body=$NOTES_MD" \ + -d "target_commitish=master" + ;; +esac +``` + +### Step 6：验证 + +```bash +# 确认 Release 已创建 +case "$BACKEND" in + gitlink) gitlink-cli release +list --owner $OWNER --repo $REPO --format json \ + | jq '.data.releases[] | select(.tag_name=="$VERSION")' ;; + github) gh release view $VERSION --repo $OWNER/$REPO ;; + gitlab) glab release view $VERSION --repo $OWNER/$REPO ;; + gitee) curl -s "https://gitee.com/api/v5/repos/$OWNER/$REPO/releases?access_token=$GITEE_TOKEN" \ + | jq '.[] | select(.tag_name=="$VERSION")' ;; +esac +``` + +--- + +## Release Notes 模板（内嵌） + +以下是完整的 Release Notes Markdown 模板： + +```markdown +# {VERSION} Release Notes + +**发布日期:** {NOW_DATE} +**仓库:** {OWNER}/{REPO} + +## 本次更新摘要 + +- 修复缺陷: **{BUG_COUNT}** 项 +- 新增功能: **{FEATURE_COUNT}** 项 +- 其他改进: **{OTHER_COUNT}** 项 +- 仍开放 Issue: **{OPEN_COUNT}** 项 + +## Bug 修复 + +{BUG_LIST} + +## 新功能 + +{FEATURE_LIST} + +## 其他改进 + +{OTHER_LIST} + +## 仍待处理 + +{OPEN_LIST} + +--- + +_本 Release Notes 由 gitlink-release-notes Skill 自动生成_ +``` + +--- + +## 安全与写回策略 + +| 规则 | 说明 | +|------|------| +| **必走 dry-run** | Step 4 输出预览，未确认前**禁止** 发布 | +| **必须去重** | Step 2.1 检查已有 Release tag，避免重复 | +| **限流** | 数据采集 >100 条时，每次 CLI 调用后 sleep 200ms | +| **错误透明** | 任何 4xx/5xx 必须打印响应体，不要吞错 | +| **空数据容错** | 某分类无数据时输出"无"，不跳过章节 | +| **仍待处理截断** | 开放 Issue >10 条时截断，输出"…及其他 N 条" | + +--- + +## 使用示例 + +### 示例 1：GitLink 项目 + +**用户输入**： + +``` +帮我发布 Angel123456/gitlink-cli 的 Release Notes +``` + +**Agent 执行**： + +```bash +# Step 0 +gitlink-cli auth status + +# Step 1 +gitlink-cli issue +list --owner Angel123456 --repo gitlink-cli --state closed --limit 200 --format json +gitlink-cli issue +list --owner Angel123456 --repo gitlink-cli --state open --limit 200 --format json +gitlink-cli release +list --owner Angel123456 --repo gitlink-cli --format json + +# Step 2: 版本号 v2026.07.10 + 分类 (Bug 修复/新功能/其他) + +# Step 3-4: 生成 Release Notes → dry-run 预览 + +# Step 5 (用户确认后): +gitlink-cli release +create --owner Angel123456 --repo gitlink-cli \ + --name v2026.07.10 --tag v2026.07.10 --target master \ + --body "$NOTES_MD" --format json + +# Step 6: 验证 +gitlink-cli release +list --owner Angel123456 --repo gitlink-cli --format json \ + | jq '.data.releases[] | select(.tag_name=="v2026.07.10")' +``` + +### 示例 2：GitHub 项目（指定版本号） + +**用户输入**： + +``` +发布 xuanlanwuta/gps_SM v1.2.0 的 Release Notes +``` + +**Agent 执行**： + +```bash +# Step 0 +gh auth status + +# Step 1 +gh issue list --repo xuanlanwuta/gps_SM --state closed --limit 200 --json number,title,labels +gh issue list --repo xuanlanwuta/gps_SM --state open --limit 200 --json number,title,labels +gh release list --repo xuanlanwuta/gps_SM --json tagName + +# Step 2: VERSION=v1.2.0 (用户指定) + 去重检查 + 分类 + +# Step 5 (用户确认后): +gh release create v1.2.0 --repo xuanlanwuta/gps_SM \ + --title v1.2.0 --notes "$NOTES_MD" --target master +``` + +--- + +## Agent 平台兼容性 + +| 平台 | 加载方式 | 触发方式 | +|------|----------|----------| +| **OpenClaw** | `workspace/skills/gitlink-release-notes/SKILL.md` | 自然语言 | +| **Claude Code** | `~/.claude/skills/gitlink-release-notes/SKILL.md` | 自然语言 | +| **Cursor** | `~/.cursor/skills/gitlink-release-notes/SKILL.md` | 自然语言 + `/` 命令 | +| **WorkBuddy** | `~/.workbuddy/skills/gitlink-release-notes/SKILL.md` | 自然语言 | +| **通用 Agent** | 作为参考文档 | 按 SKILL.md 流程自取 | + +--- + +## 与 gitlink-community-ops 的关系 + +本 Skill 可**独立使用**，也可作为 `gitlink-community-ops` 统一入口 Skill 的子 Skill 被编排调用： + +- 独立触发：用户说"发布 Release Notes" +- 编排触发：`gitlink-community-ops` Step 3 指令"加载并执行 gitlink-release-notes" + +当作为子 Skill 被调用时，Agent 需在上下文中继承 `OWNER`、`REPO`、`BACKEND`、`VERSION` 参数。