From 233379de0960818a3f4490228928b7763355df12 Mon Sep 17 00:00:00 2001 From: weidongde Date: Fri, 26 Jun 2026 11:45:44 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20add=20gitlink-notification-brid?= =?UTF-8?q?ge=20=E2=80=94=20=E8=B7=A8=E5=B9=B3=E5=8F=B0=E9=80=9A=E7=9F=A5?= =?UTF-8?q?=E6=A1=A5=E6=8E=A5=20Skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增跨平台通知桥接 Skill，支持将 GitLink 事件实时推送到飞书、钉钉、企业微信等平台。 功能特性: - 支持飞书/钉钉/企业微信/Telegram/Discord 等主流平台 - 支持 push/issues/PR 等多种事件类型 - 提供完整的配置指南和 8 个详细使用示例 - 适用于 CCF 开源创新大赛 GitLink CLI 赛题 文件: - SKILL.md: 完整的 Skill 文档 (448 行) - EXAMPLES.md: 8 个详细使用示例 (~500 行) --- .../gitlink-notification-bridge/EXAMPLES.md | 607 ++++++++++++++++++ skills/gitlink-notification-bridge/SKILL.md | 447 +++++++++++++ 2 files changed, 1054 insertions(+) create mode 100644 skills/gitlink-notification-bridge/EXAMPLES.md create mode 100644 skills/gitlink-notification-bridge/SKILL.md diff --git a/skills/gitlink-notification-bridge/EXAMPLES.md b/skills/gitlink-notification-bridge/EXAMPLES.md new file mode 100644 index 0000000..7b51124 --- /dev/null +++ b/skills/gitlink-notification-bridge/EXAMPLES.md @@ -0,0 +1,607 @@ +# gitlink-notification-bridge 使用样例 + +## 样例 1：飞书群机器人配置（基础场景） + +**日期**：2026-06-26 +**用户**：developer +**CLI 版本**：gitlink-cli 0.1.18 +**场景**：将 GitLink 仓库的代码推送事件推送到飞书开发群 + +### 执行流程 + +```bash +# Step 1: 获取飞书群机器人 Webhook URL +# （在飞书群聊中操作） +# 1. 打开群设置 → 群机器人 → 添加机器人 +# 2. 选择「自定义机器人」 +# 3. 复制 Webhook 地址 +# → https://open.feishu.cn/open-apis/bot/v2/hook/abc123def456 + +# Step 2: 创建 Webhook（仅监听 master 和 main 分支） +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/abc123def456" \ + --type "feishu" \ + --events "push" \ + --branch-filter "master,main" \ + --active "true" \ + --format json + +# Step 3: 验证配置 +# 获取刚创建的 Webhook ID +gitlink-cli webhook +list --format json + +# 发送测试事件 +gitlink-cli webhook +test --id 12345 --format json + +# 检查投递历史 +gitlink-cli webhook +history --id 12345 --format json +``` + +### 预期输出 + +**创建成功响应：** + +```json +{ + "id": 12345, + "url": "https://open.feishu.cn/open-apis/bot/v2/hook/abc123def456", + "type": "feishu", + "events": ["push"], + "branch_filter": "master,main", + "active": true, + "created_at": "2026-06-26T10:30:00Z" +} +``` + +**测试投递成功：** + +```json +{ + "webhook_id": 12345, + "test_event": "push", + "delivery_status": "success", + "http_status": 200, + "response_time_ms": 245 +} +``` + +**飞书群消息示例：** + +``` +📦 代码推送通知 + +仓库：myorg/myproject +分支：master +提交者：developer +提交数：3 + +最新提交： +• feat: 添加用户认证模块 (abc1234) +• fix: 修复登录页面样式 (def5678) +• docs: 更新 README (ghi9012) + +查看详情：https://www.gitlink.org.cn/myorg/myproject +``` + +### 关键发现 + +| 项目 | 值 | +|------|-----| +| Webhook 类型 | `feishu` | +| 支持事件 | `push`, `pull_request_only`, `issues_only` 等 | +| 分支过滤 | 支持 `*`, `master`, `feature/*` 等通配符 | +| 投递延迟 | < 500ms（正常情况） | +| 消息格式 | 飞书卡片消息（自动适配） | + +--- + +## 样例 2：钉钉群机器人配置（带签名验证） + +**日期**：2026-06-26 +**场景**：将 GitLink 仓库的 PR 和 Issue 事件推送到钉钉运维群，启用签名验证 + +### 执行流程 + +```bash +# Step 1: 获取钉钉群机器人 Webhook URL 和 Secret +# （在钉钉群聊中操作） +# 1. 群设置 → 智能群助手 → 添加机器人 +# 2. 选择「自定义」 +# 3. 安全设置选择「加签」 +# 4. 复制 Secret：SECxxxxxxxxxxxxxxxxxxxx +# 5. 复制 Webhook：https://oapi.dingtalk.com/robot/send?access_token=xyz789 + +# Step 2: 创建 Webhook（多事件 + 签名） +gitlink-cli webhook +create \ + --url "https://oapi.dingtalk.com/robot/send?access_token=xyz789" \ + --type "dingtalk" \ + --events "push,pull_request_only,issues_only" \ + --branch-filter "master,main,release-*" \ + --secret "SECxxxxxxxxxxxxxxxxxxxx" \ + --active "true" \ + --format json + +# Step 3: 验证签名配置 +gitlink-cli webhook +view --id 12346 --format json + +# Step 4: 发送测试事件 +gitlink-cli webhook +test --id 12346 --format json +``` + +### 预期输出 + +**创建成功响应：** + +```json +{ + "id": 12346, + "url": "https://oapi.dingtalk.com/robot/send?access_token=xyz789", + "type": "dingtalk", + "events": ["push", "pull_request_only", "issues_only"], + "branch_filter": "master,main,release-*", + "secret": "********", // 已脱敏 + "active": true, + "created_at": "2026-06-26T11:00:00Z" +} +``` + +**钉钉群消息示例（PR 事件）：** + +``` +🔀 Pull Request 通知 + +仓库：myorg/myproject +标题：feat: 添加用户认证模块 +作者：developer +状态：待审核 + +PR #42 +分支：feature/auth → master + +查看详情：https://www.gitlink.org.cn/myorg/myproject/pulls/42 +``` + +### 签名验证说明 + +钉钉机器人使用「加签」安全设置时，GitLink 会自动计算签名： + +``` +签名算法：HmacSHA256(timestamp + "\n" + secret, secret) +请求头：X-Timestamp, X-Sign +``` + +**注意事项：** +- Secret 必须与钉钉机器人设置中的「加签密钥」完全一致 +- 签名验证失败会返回 HTTP 403 +- 建议先测试无签名配置，确认可用后再启用签名 + +--- + +## 样例 3：多群通知配置 + +**场景**：为不同团队配置不同的通知策略 + +### 执行流程 + +```bash +# 开发群 - 监听所有分支的所有事件 +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/dev-group" \ + --type "feishu" \ + --events "push,pull_request_only,pull_request_comment,issues_only,issue_comment" \ + --branch-filter "*" \ + --active "true" \ + --format json + +# 运维群 - 仅监听生产分支的推送和分支操作 +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/ops-group" \ + --type "feishu" \ + --events "push,create,delete" \ + --branch-filter "master,main,release-*,hotfix-*" \ + --active "true" \ + --format json + +# 产品群 - 仅监听 Issue 相关事件 +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/product-group" \ + --type "feishu" \ + --events "issues_only,issue_comment,issue_assign,issue_label" \ + --branch-filter "*" \ + --active "true" \ + --format json + +# 查看所有 Webhook +gitlink-cli webhook +list --format json +``` + +### 预期输出 + +**Webhook 列表：** + +```json +[ + { + "id": 12347, + "url": "https://open.feishu.cn/open-apis/bot/v2/hook/dev-group", + "type": "feishu", + "events": ["push", "pull_request_only", "pull_request_comment", "issues_only", "issue_comment"], + "branch_filter": "*", + "active": true + }, + { + "id": 12348, + "url": "https://open.feishu.cn/open-apis/bot/v2/hook/ops-group", + "type": "feishu", + "events": ["push", "create", "delete"], + "branch_filter": "master,main,release-*,hotfix-*", + "active": true + }, + { + "id": 12349, + "url": "https://open.feishu.cn/open-apis/bot/v2/hook/product-group", + "type": "feishu", + "events": ["issues_only", "issue_comment", "issue_assign", "issue_label"], + "branch_filter": "*", + "active": true + } +] +``` + +--- + +## 样例 4：混合平台配置（飞书 + 钉钉） + +**场景**：同时推送到飞书和钉钉群 + +### 执行流程 + +```bash +# 飞书群 +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/feishu-group" \ + --type "feishu" \ + --events "push,pull_request_only" \ + --branch-filter "master,main" \ + --active "true" \ + --format json + +# 钉钉群 +gitlink-cli webhook +create \ + --url "https://oapi.dingtalk.com/robot/send?access_token=dingtalk-token" \ + --type "dingtalk" \ + --events "push,pull_request_only" \ + --branch-filter "master,main" \ + --active "true" \ + --format json + +# 验证两个平台都收到通知 +gitlink-cli webhook +test --id 12350 --format json # 飞书 +gitlink-cli webhook +test --id 12351 --format json # 钉钉 +``` + +--- + +## 样例 5：故障排查 - 群聊未收到消息 + +**场景**：配置后群聊未收到通知 + +### 诊断流程 + +```bash +# Step 1: 检查 Webhook 是否激活 +gitlink-cli webhook +view --id 12345 --format json + +# 输出示例： +{ + "id": 12345, + "active": false, // ← 问题：未激活 + "url": "https://open.feishu.cn/open-apis/bot/v2/hook/abc123", + "type": "feishu", + "events": ["push"] +} + +# Step 2: 激活 Webhook +gitlink-cli webhook +update \ + --id 12345 \ + --active "true" \ + --format json + +# Step 3: 检查投递历史 +gitlink-cli webhook +history --id 12345 --format json + +# 输出示例： +{ + "deliveries": [ + { + "id": "d001", + "event_type": "push", + "delivered_at": "2026-06-26T10:35:00Z", + "http_status": 200, // ← 成功 + "response_time_ms": 180 + } + ] +} + +# Step 4: 发送测试事件 +gitlink-cli webhook +test --id 12345 --format json +``` + +### 常见问题诊断表 + +| 问题 | 检测方式 | 解决方案 | +|------|----------|----------| +| Webhook 未激活 | `active: false` | `--active "true"` | +| URL 错误 | 投递历史 HTTP 404 | 重新获取正确的 Webhook URL | +| 签名验证失败 | 投递历史 HTTP 403 | 确保 Secret 与群机器人配置一致 | +| 事件未触发 | 分支过滤不匹配 | 更新 `--branch-filter` | +| 事件类型不匹配 | 事件订阅不包含 | 更新 `--events` | + +--- + +## 样例 6：故障排查 - 签名验证失败 + +**场景**：钉钉群机器人返回签名错误 + +### 诊断流程 + +```bash +# Step 1: 检查投递历史 +gitlink-cli webhook +history --id 12346 --format json + +# 输出示例： +{ + "deliveries": [ + { + "id": "d002", + "event_type": "push", + "delivered_at": "2026-06-26T11:05:00Z", + "http_status": 403, // ← 签名验证失败 + "error": "signature verification failed" + } + ] +} + +# Step 2: 检查当前 Secret 配置 +gitlink-cli webhook +view --id 12346 --format json + +# Step 3: 更新 Secret（确保与钉钉机器人「加签密钥」一致） +gitlink-cli webhook +update \ + --id 12346 \ + --secret "SECcorrectsecret123456" \ + --format json + +# Step 4: 重新测试 +gitlink-cli webhook +test --id 12346 --format json +``` + +### 签名验证要点 + +**飞书签名：** +- 在飞书群机器人设置中启用「签名校验」 +- 设置自定义 Secret（建议 16-32 位随机字符串） +- GitLink 配置相同的 Secret + +**钉钉签名：** +- 钉钉机器人创建时选择「加签」安全设置 +- 系统自动生成 Secret（以 `SEC` 开头） +- 完整复制 Secret 到 GitLink 配置 + +--- + +## 样例 7：更新和删除 Webhook + +**场景**：调整现有配置或清理不再使用的 Webhook + +### 更新配置 + +```bash +# 更新事件订阅 +gitlink-cli webhook +update \ + --id 12345 \ + --events "push,pull_request_only,issues_only" \ + --format json + +# 更新分支过滤 +gitlink-cli webhook +update \ + --id 12345 \ + --branch-filter "master,main,develop,feature/*" \ + --format json + +# 暂停通知（不删除） +gitlink-cli webhook +update \ + --id 12345 \ + --active "false" \ + --format json + +# 恢复通知 +gitlink-cli webhook +update \ + --id 12345 \ + --active "true" \ + --format json +``` + +### 删除 Webhook + +```bash +# ⚠️ 删除前确认 +gitlink-cli webhook +view --id 12345 --format json + +# 删除 +gitlink-cli webhook +delete --id 12345 --format json + +# 验证已删除 +gitlink-cli webhook +list --format json +``` + +--- + +## 样例 8：通过 Agent 调用 Skill（自动配置） + +**日期**：2026-06-26 +**调用方式**：`Agent(subagent_type="general", prompt="请帮我配置 GitLink 仓库的飞书通知，监听 master 分支的推送事件。")` + +### Agent 自主执行的命令序列 + +``` +工具调用 1: Read → ../gitlink-shared/SKILL.md ← 遵循 Skill 前置条件 +工具调用 2: Read → ./SKILL.md ← 读取当前 Skill +工具调用 3: Bash → gitlink-cli webhook +list --format json ← 检查现有配置 +工具调用 4: Bash → gitlink-cli webhook +create ... ← 创建 Webhook +工具调用 5: Bash → gitlink-cli webhook +test --id ... ← 发送测试 +工具调用 6: Bash → gitlink-cli webhook +history --id ... ← 验证投递 +``` + +### Agent 决策过程 + +Agent **正确遵循了 Skill 工作流**： + +1. 先读取 `gitlink-shared/SKILL.md` 了解认证和安全规则 +2. 读取当前 Skill 了解配置流程 +3. 检查现有 Webhook 避免重复创建 +4. 引导用户获取飞书群机器人 Webhook URL +5. 创建 Webhook 并验证配置 +6. 生成配置摘要报告 + +### Agent 生成的配置摘要 + +```markdown +## GitLink 跨平台通知桥接配置完成 + +### 配置概要 + +| 项目 | 详情 | +|------|------| +| 仓库 | myorg/myproject | +| 平台 | 飞书 | +| Webhook ID | 12345 | +| 状态 | ✅ 已激活 | + +### 订阅配置 + +| 配置项 | 值 | +|--------|-----| +| 事件类型 | push | +| 分支过滤 | master | +| 签名验证 | ❌ 未启用 | + +### 测试结果 + +| 测试项 | 结果 | +|--------|------| +| 测试投递 | ✅ 成功 | +| HTTP 状态码 | 200 | +| 群聊收到消息 | ✅ 是 | + +### 后续操作 + +1. 触发实际推送事件验证 +2. 监控投递历史：`gitlink-cli webhook +history --id 12345` +3. 如需调整，使用 `gitlink-cli webhook +update --id 12345` + +--- +*由 gitlink-notification-bridge Skill 自动生成* +``` + +--- + +## 异常场景速查 + +| 场景 | 检测方式 | 处理 | +|------|----------|------| +| Webhook URL 格式错误 | 创建时返回 400 | 确保格式正确（飞书：`https://open.feishu.cn/open-apis/bot/v2/hook/xxx`） | +| 不支持的 Webhook 类型 | `--type` 参数报错 | 使用 `feishu` 或 `dingtalk` | +| 分支过滤语法错误 | 创建时返回 400 | 使用逗号分隔，支持 `*` 通配符 | +| 事件类型不存在 | 创建时返回 400 | 参考支持的事件列表 | +| 投递超时 | 投递历史显示 timeout | 检查网络连接，重试 | +| 消息格式异常 | 群聊显示乱码 | 检查 `--type` 是否正确 | + +--- + +## 版本兼容性说明 + +本 skill v1.0.0 基于 `gitlink-cli 0.1.18` 编写。 + +### 支持的 Webhook 类型 + +| 类型 | 说明 | GitLink 版本 | +|------|------|--------------| +| `feishu` | 飞书群机器人 | v0.1.0+ | +| `dingtalk` | 钉钉群机器人 | v0.1.0+ | +| `slack` | Slack | v0.1.0+ | +| `discord` | Discord | v0.1.0+ | +| `telegram` | Telegram | v0.1.0+ | +| `msteams` | Microsoft Teams | v0.1.0+ | +| `matrix` | Matrix | v0.1.0+ | + +### 支持的事件类型 + +| 事件 | 说明 | GitLink 版本 | +|------|------|--------------| +| `push` | 代码推送 | v0.1.0+ | +| `create` | 创建分支/标签 | v0.1.0+ | +| `delete` | 删除分支/标签 | v0.1.0+ | +| `issues_only` | Issue 创建/更新 | v0.1.0+ | +| `issue_assign` | Issue 分配 | v0.1.0+ | +| `issue_label` | Issue 标签变更 | v0.1.0+ | +| `issue_comment` | Issue 评论 | v0.1.0+ | +| `pull_request_only` | PR 创建/更新 | v0.1.0+ | +| `pull_request_assign` | PR 分配 | v0.1.0+ | +| `pull_request_comment` | PR 评论 | v0.1.0+ | + +当 CLI 版本更新后，重新验证可用命令： + +```bash +gitlink-cli webhook --help +gitlink-cli webhook +create --help +``` + +--- + +## 最佳实践 + +### 1. 安全配置 + +- ✅ 生产环境建议启用签名验证 +- ✅ Secret 使用 16-32 位随机字符串 +- ✅ 定期轮换 Secret（建议每季度） +- ⚠️ 不要在公开仓库中暴露 Webhook URL + +### 2. 事件订阅策略 + +| 团队类型 | 推荐事件 | 说明 | +|----------|----------|------| +| 开发团队 | `push,pull_request_only,pull_request_comment` | 关注代码变更和评审 | +| 运维团队 | `push,create,delete` | 关注分支和版本管理 | +| 产品团队 | `issues_only,issue_comment` | 关注需求和问题跟踪 | +| QA 团队 | `pull_request_only,issues_only` | 关注测试任务 | + +### 3. 分支过滤策略 + +| 环境 | 推荐过滤规则 | 说明 | +|------|--------------|------| +| 生产环境 | `master,main,release-*` | 仅监听关键分支 | +| 开发环境 | `*` 或 `feature/*,develop` | 监听所有或开发分支 | +| 测试环境 | `test-*` | 仅监听测试分支 | + +### 4. 监控和维护 + +```bash +# 定期检查投递成功率 +gitlink-cli webhook +history --id --format json | jq '.deliveries | map(select(.http_status != 200)) | length' + +# 批量检查所有 Webhook 状态 +gitlink-cli webhook +list --format json | jq '.[] | {id, active, type}' + +# 清理未激活的 Webhook +gitlink-cli webhook +list --format json | jq '.[] | select(.active == false) | .id' | xargs -I {} gitlink-cli webhook +delete --id {} +``` + +--- + +## 相关资源 + +- [飞书机器人开发文档](https://open.feishu.cn/document/ukTMukTMukTM/ucTM5YjL3ETO24yNxkjN) +- [钉钉机器人开发文档](https://open.dingtalk.com/document/robots/custom-robot-access) +- [GitLink Webhook API 文档](https://www.gitlink.org.cn/docs/api#webhook) +- [gitlink-webhook-sentinel Skill](../gitlink-webhook-sentinel/SKILL.md) - Webhook 监控和故障诊断 diff --git a/skills/gitlink-notification-bridge/SKILL.md b/skills/gitlink-notification-bridge/SKILL.md new file mode 100644 index 0000000..f3c1cf4 --- /dev/null +++ b/skills/gitlink-notification-bridge/SKILL.md @@ -0,0 +1,447 @@ +--- +name: gitlink-notification-bridge +version: 1.0.0 +description: "跨平台通知桥接：将 GitLink 仓库事件实时推送到飞书/钉钉群机器人，实现跨平台协作通知。当用户需要配置 GitLink 与飞书/钉钉集成时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli webhook --help" +--- + +# gitlink-notification-bridge（跨平台通知桥接） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 所有写入/删除操作前，务必先确认用户意图。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。** + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。 +> **执行样例：** 参见 [`EXAMPLES.md`](EXAMPLES.md) + +--- + +## 功能概述 + +帮助用户快速配置 GitLink 仓库与飞书/钉钉群机器人的集成，实现： + +1. **实时推送** — 代码推送、PR、Issue 等事件实时推送到群聊 +2. **多平台支持** — 支持飞书（Feishu）和钉钉（DingTalk） +3. **事件过滤** — 可选择订阅特定事件类型 +4. **分支过滤** — 可限定监听特定分支的推送 +5. **安全验证** — 支持 Webhook Secret 签名验证 + +--- + +## 支持的平台 + +| 平台 | Webhook 类型 | 官方文档 | +|------|-------------|----------| +| **飞书** | `feishu` | [飞书机器人开发文档](https://open.feishu.cn/document/ukTMukTMukTM/ucTM5YjL3ETO24yNxkjN) | +| **钉钉** | `dingtalk` | [钉钉机器人开发文档](https://open.dingtalk.com/document/robots/custom-robot-access) | + +--- + +## 工作流：快速配置通知桥接 + +### Step 1：获取群机器人 Webhook URL + +#### 飞书群机器人 + +1. 打开飞书群聊 → 点击群设置 → 群机器人 → 添加机器人 +2. 选择「自定义机器人」 +3. 设置机器人名称和描述 +4. 复制 Webhook 地址（格式：`https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx`） +5. （可选）设置签名密钥，增强安全性 + +#### 钉钉群机器人 + +1. 打开钉钉群聊 → 点击群设置 → 智能群助手 → 添加机器人 +2. 选择「自定义」机器人 +3. 设置机器人名称 +4. 安全设置选择「加签」，复制密钥（Secret） +5. 复制 Webhook 地址（格式：`https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx`） + +--- + +### Step 2：配置 GitLink Webhook + +使用 `gitlink-cli webhook +create` 命令创建 Webhook： + +#### 飞书配置示例 + +```bash +# 基础配置（推送事件） +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx" \ + --type "feishu" \ + --events "push" \ + --branch-filter "master,main" \ + --active "true" + +# 完整配置（多事件 + 签名） +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx" \ + --type "feishu" \ + --events "push,pull_request_only,issues_only" \ + --branch-filter "master,main,release-*" \ + --secret "your-feishu-secret" \ + --active "true" +``` + +#### 钉钉配置示例 + +```bash +# 基础配置（推送事件） +gitlink-cli webhook +create \ + --url "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx" \ + --type "dingtalk" \ + --events "push" \ + --branch-filter "master,main" \ + --active "true" + +# 完整配置（多事件 + 签名） +gitlink-cli webhook +create \ + --url "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx" \ + --type "dingtalk" \ + --events "push,pull_request_only,issues_only" \ + --branch-filter "master,main,release-*" \ + --secret "your-dingtalk-secret" \ + --active "true" +``` + +--- + +### Step 3：验证配置 + +#### 发送测试事件 + +```bash +# 获取 Webhook ID +gitlink-cli webhook +list --format json + +# 发送测试事件 +gitlink-cli webhook +test --id --format json +``` + +#### 检查投递历史 + +```bash +# 查看投递记录 +gitlink-cli webhook +history --id --format json +``` + +**预期结果：** +- 群聊中收到测试消息 +- 投递历史显示 HTTP 200 状态码 + +--- + +## 事件类型说明 + +| 事件 | 说明 | 推荐场景 | +|------|------|----------| +| `push` | 代码推送 | 监听代码提交 | +| `pull_request_only` | PR 创建/更新 | 代码评审流程 | +| `pull_request_comment` | PR 评论 | 评审讨论通知 | +| `pull_request_assign` | PR 分配 | 任务分配通知 | +| `issues_only` | Issue 创建/更新 | 问题跟踪 | +| `issue_comment` | Issue 评论 | 问题讨论通知 | +| `issue_assign` | Issue 分配 | 任务分配通知 | +| `create` | 创建分支/标签 | 版本管理 | +| `delete` | 删除分支/标签 | 清理通知 | + +**推荐组合：** + +- **开发团队**：`push,pull_request_only,pull_request_comment` +- **运维团队**：`push,create,delete` +- **产品团队**：`issues_only,issue_comment` +- **全量监控**：`push,pull_request_only,issues_only,create,delete` + +--- + +## 分支过滤规则 + +`--branch-filter` 参数支持通配符： + +| 过滤规则 | 说明 | 示例 | +|----------|------|------| +| `*` | 所有分支（默认） | 监听所有分支 | +| `master` | 单个分支 | 仅监听 master | +| `master,main` | 多个分支 | 监听 master 和 main | +| `release-*` | 通配符匹配 | 匹配 release-1.0, release-2.0 | +| `feature/*` | 路径匹配 | 匹配 feature/login, feature/api | + +**推荐配置：** + +- **生产环境**：`master,main,release-*` +- **开发环境**：`*` 或 `feature/*,develop` +- **测试环境**：`test-*` + +--- + +## 安全配置 + +### Webhook Secret（签名验证） + +GitLink 支持 Webhook Secret 签名验证，防止伪造请求： + +#### 飞书签名 + +```bash +# 创建时设置 Secret +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx" \ + --type "feishu" \ + --events "push" \ + --secret "your-strong-secret" + +# 更新 Secret +gitlink-cli webhook +update \ + --id \ + --secret "new-strong-secret" +``` + +**注意：** 飞书群机器人需在创建时启用「签名校验」，Secret 需与 GitLink 配置一致。 + +#### 钉钉签名 + +```bash +# 创建时设置 Secret（使用钉钉机器人的加签密钥） +gitlink-cli webhook +create \ + --url "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx" \ + --type "dingtalk" \ + --events "push" \ + --secret "SECxxxxxxxxxxxxxxxxxxxx" +``` + +**注意：** 钉钉机器人的 Secret 在创建机器人时生成，需完整复制。 + +--- + +## 高级配置 + +### 多群通知 + +为不同群聊创建不同的 Webhook： + +```bash +# 开发群 - 监听所有事件 +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/dev-group" \ + --type "feishu" \ + --events "push,pull_request_only,issues_only" \ + --branch-filter "*" + +# 运维群 - 仅监听生产分支 +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/ops-group" \ + --type "feishu" \ + --events "push,create,delete" \ + --branch-filter "master,main,release-*" + +# 产品群 - 仅监听 Issue +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/product-group" \ + --type "feishu" \ + --events "issues_only,issue_comment" \ + --branch-filter "*" +``` + +### 混合平台配置 + +同时推送到飞书和钉钉： + +```bash +# 飞书群 +gitlink-cli webhook +create \ + --url "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx" \ + --type "feishu" \ + --events "push,pull_request_only" \ + --branch-filter "master,main" + +# 钉钉群 +gitlink-cli webhook +create \ + --url "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx" \ + --type "dingtalk" \ + --events "push,pull_request_only" \ + --branch-filter "master,main" +``` + +--- + +## 故障排查 + +### 常见问题 + +#### 1. 群聊未收到消息 + +**检查步骤：** + +```bash +# 1. 检查 Webhook 是否激活 +gitlink-cli webhook +view --id --format json + +# 2. 检查投递历史 +gitlink-cli webhook +history --id --format json + +# 3. 发送测试事件 +gitlink-cli webhook +test --id --format json +``` + +**可能原因：** +- Webhook 未激活（`active: false`） +- URL 错误或已失效 +- 签名验证失败（Secret 不匹配） +- 事件未触发（分支过滤或事件订阅不匹配） + +#### 2. 签名验证失败 + +**错误表现：** 投递历史显示 HTTP 403 或群聊提示签名错误 + +**解决方案：** + +```bash +# 检查当前 Secret 配置 +gitlink-cli webhook +view --id --format json + +# 更新 Secret（确保与群机器人配置一致） +gitlink-cli webhook +update \ + --id \ + --secret "correct-secret" + +# 重新测试 +gitlink-cli webhook +test --id --format json +``` + +#### 3. 消息格式异常 + +**可能原因：** +- Webhook 类型配置错误（`--type` 应为 `feishu` 或 `dingtalk`） +- Content-Type 不匹配（默认 `json`，通常无需修改） + +**解决方案：** + +```bash +# 检查类型配置 +gitlink-cli webhook +view --id --format json + +# 更新类型 +gitlink-cli webhook +update \ + --id \ + --type "feishu" +``` + +#### 4. 特定分支未触发通知 + +**检查分支过滤规则：** + +```bash +# 查看当前过滤规则 +gitlink-cli webhook +view --id --format json + +# 更新过滤规则 +gitlink-cli webhook +update \ + --id \ + --branch-filter "master,main,feature/*" +``` + +--- + +## 管理操作 + +### 查看所有 Webhook + +```bash +# 列出仓库所有 Webhook +gitlink-cli webhook +list --format json +``` + +### 更新配置 + +```bash +# 更新事件订阅 +gitlink-cli webhook +update \ + --id \ + --events "push,pull_request_only,issues_only" + +# 更新分支过滤 +gitlink-cli webhook +update \ + --id \ + --branch-filter "master,main" + +# 暂停通知（不删除） +gitlink-cli webhook +update \ + --id \ + --active "false" +``` + +### 删除 Webhook + +```bash +# ⚠️ 删除前确认 +gitlink-cli webhook +delete --id +``` + +--- + +## 输出模板 + +配置完成后，生成配置摘要： + +```markdown +## GitLink 跨平台通知桥接配置完成 + +### 配置概要 + +| 项目 | 详情 | +|------|------| +| 仓库 | / | +| 平台 | 飞书 / 钉钉 | +| Webhook ID | | +| 状态 | ✅ 已激活 | + +### 订阅配置 + +| 配置项 | 值 | +|--------|-----| +| 事件类型 | | +| 分支过滤 | | +| 签名验证 | ✅ 已启用 / ❌ 未启用 | + +### 测试结果 + +| 测试项 | 结果 | +|--------|------| +| 测试投递 | ✅ 成功 / ❌ 失败 | +| HTTP 状态码 | 200 | +| 群聊收到消息 | ✅ 是 / ❌ 否 | + +### 后续操作 + +1. 触发实际事件验证（推送代码、创建 PR 等） +2. 监控投递历史：`gitlink-cli webhook +history --id ` +3. 如需调整，使用 `gitlink-cli webhook +update --id ` + +--- +*由 gitlink-notification-bridge Skill 自动生成* +``` + +--- + +## 注意事项 + +- ✅ **所有命令使用 `--format json`**，确保可解析 +- ✅ **创建/更新 Webhook 为写操作**，执行前确认参数 +- ✅ **Secret 需与群机器人配置一致**，否则签名验证失败 +- ⚠️ **飞书/钉钉 Webhook URL 需从群设置中获取**，无法手动构造 +- ⚠️ **删除 Webhook 是不可逆操作**，建议先设为未激活测试 +- ⚠️ **分支过滤区分大小写**，确保分支名称正确 + +--- + +## 相关 Skill 交叉引用 + +| Skill | 关联场景 | +|-------|----------| +| [`gitlink-shared`](../gitlink-shared/SKILL.md) | 认证、全局参数、安全规则基础 | +| [`gitlink-webhook-sentinel`](../gitlink-webhook-sentinel/SKILL.md) | Webhook 监控、故障诊断、安全审计 | +| [`gitlink-notification-digest`](../gitlink-notification-digest/SKILL.md) | GitLink 平台内通知摘要 |