From f1dd01bebc8126073c622e613b6949c245e166b2 Mon Sep 17 00:00:00 2001 From: whale Date: Mon, 8 Jun 2026 12:01:48 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E6=96=B0=E5=A2=9E=203=20?= =?UTF-8?q?=E4=B8=AA=20Agent=20Skill=20=E2=80=94=20wiki-builder,=20pipelin?= =?UTF-8?q?e-guardian,=20webhook-sentinel?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 Skill： - gitlink-wiki-builder: Wiki 文档自动化，填补 9 个 wiki CLI 命令的 Skill 空白 - gitlink-pipeline-guardian: 流水线健康监控、故障分析和性能优化 - gitlink-webhook-sentinel: Webhook 投递监控、故障诊断和安全审计 每个 Skill 包含 SKILL.md + examples/，已在 Claude Code 中验证通过。 Co-Authored-By: Claude Opus 4.8 --- skills/gitlink-pipeline-guardian/SKILL.md | 373 +++++++++++++ .../examples/pipeline-guardian-workflow.md | 300 +++++++++++ skills/gitlink-webhook-sentinel/SKILL.md | 497 ++++++++++++++++++ .../examples/webhook-sentinel-workflow.md | 226 ++++++++ skills/gitlink-wiki-builder/SKILL.md | 341 ++++++++++++ .../examples/wiki-builder-workflow.md | 356 +++++++++++++ 6 files changed, 2093 insertions(+) create mode 100644 skills/gitlink-pipeline-guardian/SKILL.md create mode 100644 skills/gitlink-pipeline-guardian/examples/pipeline-guardian-workflow.md create mode 100644 skills/gitlink-webhook-sentinel/SKILL.md create mode 100644 skills/gitlink-webhook-sentinel/examples/webhook-sentinel-workflow.md create mode 100644 skills/gitlink-wiki-builder/SKILL.md create mode 100644 skills/gitlink-wiki-builder/examples/wiki-builder-workflow.md diff --git a/skills/gitlink-pipeline-guardian/SKILL.md b/skills/gitlink-pipeline-guardian/SKILL.md new file mode 100644 index 0000000..c34a48d --- /dev/null +++ b/skills/gitlink-pipeline-guardian/SKILL.md @@ -0,0 +1,373 @@ +--- +name: gitlink-pipeline-guardian +version: 1.0.0 +description: "流水线健康守护：监控 CI/CD 流水线状态、分析失败模式、识别慢速构建、生成健康度评分报告。当用户需要排查流水线故障或优化构建效率时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli pipeline --help" +--- + +# gitlink-pipeline-guardian（流水线健康守护） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 本 Skill 为只读巡检与分析工具。涉及 pipeline 的启用/禁用/删除/运行操作，需经用户确认后方可执行。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。** + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。 + +--- + +## 定位与产物 + +面向项目维护者的流水线健康守护工具，核心能力： + +1. **流水线健康巡检** — 全面扫描流水线运行状态，生成 0-100 健康度评分报告 +2. **故障根因分析** — 针对失败构建深入分析日志，定位错误模式并给出修复建议 +3. **性能优化分析** — 分析构建耗时分布，识别瓶颈阶段并提出优化方案 +4. **流水线配置审计** — 审计流水线配置规范性，推荐最佳实践 + +与 `gitlink-ci-health`（关注 CI/CD 基础设施层，使用 `ci +builds`）不同，本 Skill 关注的是**流水线工作流层面**（Pipeline），使用 `pipeline +runs`、`pipeline +logs`、`pipeline +results` 等命令，覆盖从构建编排到执行结果的完整链路。 + +### 命令矩阵 + +| 命令 | 用途 | 涉及工作流 | +|------|------|-----------| +| `pipeline +list` | 列出平台流水线 | 巡检、配置审计 | +| `pipeline +runs` | 列出流水线运行记录 | 巡检、故障分析、性能分析 | +| `pipeline +view` | 查看流水线详情 | 巡检、配置审计 | +| `pipeline +logs` | 查询流水线运行日志 | 故障分析 | +| `pipeline +results` | 查看流水线运行结果 | 巡检、故障分析、性能分析 | +| `ci +builds` | 查看 CI 构建列表 | 巡检（补充） | +| `ci +log` | 查看 CI 构建日志 | 故障分析（补充） | +| `ci +restart` | 重启 CI 构建 | 故障修复（需确认） | + +--- + +## 工作流 1：流水线健康巡检 + +**触发场景**：用户说"流水线怎么样""Pipeline 健康度""流水线报告""构建状态一览"。 + +### Step 1：获取流水线列表 + +```bash +gitlink-cli pipeline +list --owner-id --page 1 --limit 20 --format json +``` + +记录所有流水线的 `id`、`name`、`status`。 + +### Step 2：获取近期运行记录 + +对每个流水线获取运行历史： + +```bash +gitlink-cli pipeline +runs --owner --repo --ref master --format json +``` + +提取每次运行的： +- `status` — 运行状态（success / failure / running / pending / cancelled） +- `started_at` / `finished_at` — 时间信息 +- `duration` — 耗时 +- `workflow` — 触发的工作流文件 +- `branch` / `ref` — 触发分支 + +### Step 3：获取运行结果详情 + +对最近的关键运行获取结果： + +```bash +gitlink-cli pipeline +results --owner --repo --run-id --format json +``` + +### Step 4：计算健康度评分 + +按以下评分模板计算总分（满分 100）。 + +#### 健康度评分模板 + +| 维度 | 权重 | 满分 | 评分标准 | +|------|------|------|----------| +| **可用性** | — | 20 | 流水线全部可用=20，部分禁用按比例扣分，全部不可用=0 | +| **成功率** | — | 25 | ≥95%=25，≥90%=22，≥80%=18，≥70%=12，≥60%=8，<60%=4，无数据=0 | +| **稳定性** | — | 20 | 近10次全部成功=20，8-9次=16，6-7次=12，4-5次=8，<4次=4 | +| **性能** | — | 15 | 平均耗时 ≤2min=15，≤5min=12，≤10min=9，≤20min=6，>20min=3 | +| **频率** | — | 10 | 每天有构建=10，2-3天=8，每周=5，更少=2，无运行=0 | +| **规范性** | — | 10 | 有命名规范=3，有失败通知=3，有缓存策略=2，有并行配置=2，无=0 | + +**总评分级**： + +| 分数范围 | 等级 | 状态 | +|----------|------|------| +| 90-100 | A | 健康 | +| 75-89 | B | 良好 | +| 60-74 | C | 需关注 | +| 40-59 | D | 需改进 | +| 0-39 | F | 严重 | + +### Step 5：生成健康巡检报告 + +按输出模板（见文末）生成报告。 + +--- + +## 工作流 2：故障根因分析 + +**触发场景**：用户说"这个构建为什么失败""流水线报错了""帮我排查一下 pipeline 失败"。 + +### Step 1：定位失败运行 + +```bash +# 获取近期运行，找到状态为 failure 的记录 +gitlink-cli pipeline +runs --owner --repo --format json +``` + +### Step 2：获取运行结果 + +```bash +gitlink-cli pipeline +results --owner --repo --run-id --format json +``` + +确定失败的阶段（stage）和步骤（step）。 + +### Step 3：获取失败日志 + +```bash +gitlink-cli pipeline +logs --owner --repo --run-id --id --index --format json +``` + +> **注意**：`pipeline +logs` 需要提供 `--run-id`、`--id`（流水线 ID）和 `--index`（作业索引）。先通过 `pipeline +results` 获取这些参数。 + +### Step 4：补充 CI 日志（如需要） + +```bash +gitlink-cli ci +builds --owner --repo --format json +gitlink-cli ci +log --build --format json +``` + +### Step 5：分析错误模式 + +将日志中的错误信息与**常见失败模式目录**（见文末）匹配，定位根因。 + +### Step 6：输出分析报告 + +包含： +- 失败构建基本信息（ID、分支、时间） +- 错误日志关键片段 +- 匹配的失败模式 +- 根因分析结论 +- 修复建议（具体的代码或配置修改方案） + +--- + +## 工作流 3：性能优化分析 + +**触发场景**：用户说"构建太慢了""优化一下流水线""构建耗时分析"。 + +### Step 1：收集运行耗时数据 + +```bash +gitlink-cli pipeline +runs --owner --repo --format json +``` + +提取每次运行的 `duration`，计算： +- 平均耗时 +- 中位数耗时 +- 最大 / 最小耗时 +- P90 / P95 耗时 + +### Step 2：获取各阶段结果 + +对多次运行获取结果，对比各阶段耗时： + +```bash +gitlink-cli pipeline +results --owner --repo --run-id --format json +``` + +### Step 3：识别瓶颈阶段 + +按阶段统计平均耗时，找出耗时最长的 TOP 3 阶段。 + +### Step 4：慢速构建分析 + +识别超过平均耗时 1.5 倍的构建，分析可能的慢速原因： +- 依赖安装阶段过长 → 未使用缓存 +- 测试阶段过长 → 未并行执行 +- 构建阶段过长 → 未增量构建 +- 部署阶段过长 → 资源不足 + +### Step 5：输出优化建议 + +包含： +- 当前耗时统计（表格） +- 瓶颈阶段排名 +- 慢速构建列表及原因 +- 具体优化建议（带预期收益估算） + +--- + +## 工作流 4：流水线配置审计 + +**触发场景**：用户说"流水线配置合不合理""审计一下 pipeline""流水线最佳实践检查"。 + +### Step 1：获取流水线详情 + +```bash +gitlink-cli pipeline +list --owner-id --format json +``` + +对每个流水线： + +```bash +gitlink-cli pipeline +view --owner --repo --id --format json +``` + +### Step 2：审计检查清单 + +逐项检查以下配置规范： + +| 检查项 | 审计标准 | 状态 | +|--------|----------|------| +| **命名规范** | 流水线名称清晰、有业务含义 | 通过/不通过 | +| **触发条件** | 配置了合理的触发分支和事件 | 通过/不通过 | +| **超时设置** | 各阶段设置了合理的超时时间 | 通过/不通过 | +| **重试策略** | 关键阶段配置了重试 | 通过/不通过 | +| **缓存配置** | 依赖安装阶段使用了缓存 | 通过/不通过 | +| **并行执行** | 无依赖的阶段配置了并行 | 通过/不通过 | +| **通知配置** | 配置了失败通知机制 | 通过/不通过 | +| **环境变量** | 敏感信息通过 Secret 管理 | 通过/不通过 | +| **版本锁定** | 依赖版本已锁定（非 latest） | 通过/不通过 | +| **清理策略** | 配置了构建产物清理 | 通过/不通过 | + +### Step 3：生成审计报告 + +按检查清单生成报告，标注通过率和不通过项的改进建议。 + +--- + +## 常见失败模式目录 + +以下为流水线构建中的常见失败模式，用于故障根因分析时的模式匹配。 + +### 编译/构建错误 + +| 模式 ID | 模式名称 | 关键特征 | 常见原因 | +|---------|----------|----------|----------| +| F-COMP-001 | 依赖下载失败 | `npm ERR!`、`Could not resolve`、`download failed` | 网络问题、私有源不可达、版本不存在 | +| F-COMP-002 | 编译语法错误 | `SyntaxError`、`compilation error`、`parse error` | 代码语法问题、语言版本不兼容 | +| F-COMP-003 | 内存不足 | `OOM`、`out of memory`、`heap`、`137 exit code` | 构建资源不足、内存泄漏 | +| F-COMP-004 | 磁盘空间不足 | `No space left`、`ENOSPC`、`disk full` | 构建缓存堆积、产物过大 | +| F-COMP-005 | 版本不兼容 | `version mismatch`、`incompatible`、`unsupported version` | 运行时版本与代码不匹配 | + +### 测试错误 + +| 模式 ID | 模式名称 | 关键特征 | 常见原因 | +|---------|----------|----------|----------| +| F-TEST-001 | 单元测试失败 | `FAIL`、`AssertionError`、`expected but got` | 代码逻辑错误、测试用例过时 | +| F-TEST-002 | 集成测试失败 | `connection refused`、`timeout`、`ECONNREFUSED` | 服务依赖不可用、环境配置错误 | +| F-TEST-003 | 测试超时 | `timeout`、`exceeded`、`Deadline exceeded` | 测试死锁、外部依赖响应慢 | +| F-TEST-004 | 测试覆盖率不达标 | `coverage`、`threshold`、`below` | 代码缺少测试覆盖 | + +### 环境/配置错误 + +| 模式 ID | 模式名称 | 关键特征 | 常见原因 | +|---------|----------|----------|----------| +| F-ENV-001 | 环境变量缺失 | `undefined`、`not set`、`missing env` | Secret 未配置、变量名拼写错误 | +| F-ENV-002 | 权限不足 | `permission denied`、`403`、`unauthorized` | 凭证过期、角色权限不足 | +| F-ENV-003 | Docker 构建失败 | `Dockerfile`、`image not found`、`build failed` | 基础镜像不存在、Dockerfile 语法错误 | +| F-ENV-004 | 资源限制 | `rate limit`、`too many requests`、`429` | API 调用频率超限 | + +### 部署错误 + +| 模式 ID | 模式名称 | 关键特征 | 常见原因 | +|---------|----------|----------|----------| +| F-DEPLOY-001 | 部署超时 | `deployment timeout`、`rollout stuck` | 镜像拉取慢、资源不足 | +| F-DEPLOY-002 | 部署验证失败 | `health check failed`、`unhealthy` | 应用启动失败、配置错误 | +| F-DEPLOY-003 | 回滚触发 | `rollback`、`reverted` | 部署后检测到故障自动回滚 | + +--- + +## 输出模板：流水线健康巡检报告 + +```markdown +# 流水线健康巡检报告：{{仓库名}} + +> 巡检时间：{{当前时间}} +> 仓库：{{full_name}} +> 流水线数量：{{pipeline_count}} + +--- + +## 一、健康度总览 + +| 指标 | 数值 | 评分 | +|------|------|------| +| 可用性 | {{可用流水线}}/{{总数}} | {{availability_score}}/20 | +| 成功率 | {{success_rate}}%（{{success_count}}/{{total_count}}） | {{success_score}}/25 | +| 稳定性 | 近 10 次 {{recent_success}} 次成功 | {{stability_score}}/20 | +| 性能 | 平均耗时 {{avg_duration}} | {{performance_score}}/15 | +| 频率 | {{frequency_desc}} | {{frequency_score}}/10 | +| 规范性 | 通过 {{passed_checks}}/{{total_checks}} 项 | {{compliance_score}}/10 | +| **总分** | | **{{total_score}}/100（等级 {{grade}}）** | + +## 二、运行趋势 + +最近 20 次运行状态： +{{status_bar}} +（S=成功 F=失败 R=运行中 -=待执行 C=已取消） + +| 时间段 | 总运行 | 成功 | 失败 | 成功率 | +|--------|--------|------|------|--------| +| 最近 7 天 | {{w1_total}} | {{w1_success}} | {{w1_fail}} | {{w1_rate}}% | +| 7-14 天 | {{w2_total}} | {{w2_success}} | {{w2_fail}} | {{w2_rate}}% | +| 14-30 天 | {{w3_total}} | {{w3_success}} | {{w3_fail}} | {{w3_rate}}% | + +## 三、性能概览 + +| 指标 | 数值 | +|------|------| +| 平均耗时 | {{avg_duration}} | +| 中位数耗时 | {{median_duration}} | +| P90 耗时 | {{p90_duration}} | +| 最快构建 | {{min_duration}}（#{{min_run_id}}） | +| 最慢构建 | {{max_duration}}（#{{max_run_id}}） | + +## 四、故障摘要 + +> 如无失败运行，输出：**分析期内无失败运行，流水线运行健康。** + +| 运行 ID | 工作流 | 分支 | 状态 | 耗时 | 错误模式 | +|---------|--------|------|------|------|----------| +| {{run_id}} | {{workflow}} | {{branch}} | {{status}} | {{duration}} | {{error_pattern}} | + +## 五、改进建议 + +{{improvement_suggestions}} + +--- +*报告由 gitlink-pipeline-guardian 生成* +``` + +--- + +## 异常场景处理 + +| 场景 | 处理方式 | +|------|----------| +| 无流水线 | 报告"仓库尚未配置流水线"，建议创建 `.gitea/workflows` 或通过 Web 界面创建 | +| 流水线全部禁用 | 标注"所有流水线已禁用"，可用性评分为 0 | +| 运行记录为空 | 标注"流水线无运行记录"，跳过成功率和性能评分 | +| `pipeline +logs` 返回空 | 标注"日志不可用"，基于 `pipeline +results` 进行有限分析 | +| 构建记录 < 5 次 | 标注"样本量不足，统计不具代表性" | +| 流水线数量 > 10 | 仅分析最近活跃的 10 条流水线 | + +--- + +## 最佳实践 + +- 所有命令使用 `--format json`，确保输出可解析 +- Owner/repo 优先从 `git remote` 自动解析 +- 巡检类操作为只读，不会修改任何流水线配置 +- 涉及启用/禁用/删除/运行操作需经用户确认后执行 +- 批量获取运行记录时控制 API 调用频率，避免请求过快 +- 日志分析时仅提取关键错误行，避免处理过多数据 +- 将巡检报告保存为文件以便后续对比和追踪趋势 diff --git a/skills/gitlink-pipeline-guardian/examples/pipeline-guardian-workflow.md b/skills/gitlink-pipeline-guardian/examples/pipeline-guardian-workflow.md new file mode 100644 index 0000000..847cfd5 --- /dev/null +++ b/skills/gitlink-pipeline-guardian/examples/pipeline-guardian-workflow.md @@ -0,0 +1,300 @@ +# 流水线健康巡检工作流示例 + +本文档展示如何使用 `gitlink-pipeline-guardian` Skill 对仓库 `whale_hihihi/gitlink-cli` 执行完整的流水线健康巡检，生成健康度评分报告。 + +> **前置条件**：已完成 `gitlink-cli auth login` 认证。详见 [`../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。 + +--- + +## Step 1：获取流水线列表 + +查看仓库下所有流水线的基本信息。 + +```bash +gitlink-cli pipeline +list --owner-id 123 --page 1 --limit 20 --format json +``` + +预期输出： + +```json +{ + "pipelines": [ + {"id": 7, "name": "CI Build", "status": "active"}, + {"id": 8, "name": "Deploy Staging", "status": "active"}, + {"id": 9, "name": "Deploy Production", "status": "disabled"}, + {"id": 10, "name": "Nightly Tests", "status": "active"} + ] +} +``` + +记录：共 4 条流水线，3 条可用，1 条已禁用（Deploy Production）。 + +--- + +## Step 2：获取近期运行记录 + +获取仓库的流水线运行历史。 + +```bash +gitlink-cli pipeline +runs --owner whale_hihihi --repo gitlink-cli --ref master --format json +``` + +预期输出： + +```json +{ + "runs": [ + {"id": 101, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "success", "duration": 185, "started_at": "2026-06-08T09:00:00Z"}, + {"id": 100, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "success", "duration": 192, "started_at": "2026-06-08T06:00:00Z"}, + {"id": 99, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "failure", "duration": 67, "started_at": "2026-06-07T18:00:00Z"}, + {"id": 98, "pipeline_id": 8, "workflow": "deploy-staging.yml", "ref": "master", "status": "success", "duration": 340, "started_at": "2026-06-07T15:00:00Z"}, + {"id": 97, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "success", "duration": 178, "started_at": "2026-06-07T12:00:00Z"}, + {"id": 96, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "success", "duration": 201, "started_at": "2026-06-07T09:00:00Z"}, + {"id": 95, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "failure", "duration": 45, "started_at": "2026-06-06T18:00:00Z"}, + {"id": 94, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "success", "duration": 188, "started_at": "2026-06-06T12:00:00Z"}, + {"id": 93, "pipeline_id": 8, "workflow": "deploy-staging.yml", "ref": "master", "status": "success", "duration": 355, "started_at": "2026-06-06T10:00:00Z"}, + {"id": 92, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "success", "duration": 195, "started_at": "2026-06-06T06:00:00Z"}, + {"id": 91, "pipeline_id": 10, "workflow": "nightly.yml", "ref": "master", "status": "success", "duration": 620, "started_at": "2026-06-05T02:00:00Z"}, + {"id": 90, "pipeline_id": 7, "workflow": "ci.yml", "ref": "master", "status": "success", "duration": 180, "started_at": "2026-06-05T09:00:00Z"} + ] +} +``` + +统计摘要： +- 总运行：12 次 +- 成功：10 次 +- 失败：2 次 +- 成功率：83.3% + +--- + +## Step 3：获取失败运行的结果详情 + +对失败的 run 99 和 run 95 获取结果。 + +```bash +gitlink-cli pipeline +results --owner whale_hihihi --repo gitlink-cli --run-id 99 --format json +``` + +预期输出： + +```json +{ + "run_id": 99, + "status": "failure", + "jobs": [ + {"index": 0, "name": "lint", "status": "success", "duration": 15}, + {"index": 1, "name": "test", "status": "failure", "duration": 52}, + {"index": 2, "name": "build", "status": "skipped", "duration": 0} + ] +} +``` + +确定失败阶段：`test`（index=1）。 + +--- + +## Step 4：获取失败日志 + +获取 run 99 的 test 阶段日志。 + +```bash +gitlink-cli pipeline +logs --owner whale_hihihi --repo gitlink-cli --run-id 99 --id 7 --index 1 --format json +``` + +预期输出： + +```json +{ + "logs": "--- Running test suite...\n=== FAIL: TestAuthLogin (0.32s)\n auth_test.go:45: expected status 200, got 500\n auth_test.go:46: server returned internal error\n=== FAIL: TestAPICall (0.18s)\n api_test.go:112: connection refused to localhost:8080\nFAIL\nexit code 1" +``` + +错误模式匹配： +- `connection refused` → **F-TEST-002**（集成测试失败） +- `expected status 200, got 500` → **F-TEST-001**（单元测试断言失败） + +--- + +## Step 5：查看流水线详情（配置审计） + +查看各流水线的配置情况。 + +```bash +gitlink-cli pipeline +view --owner whale_hihihi --repo gitlink-cli --id 7 --format json +``` + +预期输出： + +```json +{ + "id": 7, + "name": "CI Build", + "description": "Main CI pipeline for build, test and lint", + "workflows": ["ci.yml"], + "triggers": ["push", "pull_request"], + "status": "active" +} +``` + +--- + +## Step 6：补充 CI 构建数据 + +```bash +gitlink-cli ci +builds --owner whale_hihihi --repo gitlink-cli --format json +``` + +预期输出： + +```json +{ + "builds": [ + {"id": 201, "status": "success", "branch": "master", "created_at": "2026-06-08T09:01:00Z"}, + {"id": 200, "status": "success", "branch": "master", "created_at": "2026-06-08T06:01:00Z"}, + {"id": 199, "status": "failed", "branch": "master", "created_at": "2026-06-07T18:01:00Z"} + ] +} +``` + +CI 数据与 Pipeline 数据交叉验证一致。 + +--- + +## Step 7：计算健康度评分 + +### 评分计算过程 + +**可用性（满分 20）**： +- 3 条可用 / 4 条总数 = 75% +- 得分：15/20 + +**成功率（满分 25）**： +- 10 成功 / 12 总运行 = 83.3% +- 区间 ≥80% → 得分：18/25 + +**稳定性（满分 20）**： +- 近 10 次：8 次成功 +- 区间 8-9 次 → 得分：16/20 + +**性能（满分 15）**： +- CI 构建平均耗时：(185+192+67+178+201+45+188+195+180)/9 ≈ 159 秒 ≈ 2.7 分钟 +- 区间 ≤5min → 得分：12/15 + +**频率（满分 10）**： +- 最近 7 天有 10 次运行，每天均有构建 +- 得分：10/10 + +**规范性（满分 10）**： +- 有命名规范（CI Build / Deploy Staging / Nightly Tests）：3 分 +- 失败通知：未知（保守记 0 分） +- 缓存策略：未知（保守记 0 分） +- 并行配置：未知（保守记 0 分） +- 得分：3/10 + +### 汇总 + +| 维度 | 得分 | 满分 | +|------|------|------| +| 可用性 | 15 | 20 | +| 成功率 | 18 | 25 | +| 稳定性 | 16 | 20 | +| 性能 | 12 | 15 | +| 频率 | 10 | 10 | +| 规范性 | 3 | 10 | +| **总分** | **74** | **100** | + +**等级：C（需关注）** + +--- + +## 完整报告 + +以下是生成的完整巡检报告。 + +--- + +# 流水线健康巡检报告：whale_hihihi/gitlink-cli + +> 巡检时间：2026-06-08 10:30:00 +> 仓库：whale_hihihi/gitlink-cli +> 流水线数量：4（3 可用 / 1 禁用） + +--- + +## 一、健康度总览 + +| 指标 | 数值 | 评分 | +|------|------|------| +| 可用性 | 3/4 条流水线可用 | 15/20 | +| 成功率 | 83.3%（10/12） | 18/25 | +| 稳定性 | 近 10 次 8 次成功 | 16/20 | +| 性能 | 平均耗时 2.7 分钟 | 12/15 | +| 频率 | 每天有构建 | 10/10 | +| 规范性 | 通过 1/4 项 | 3/10 | +| **总分** | | **74/100（等级 C — 需关注）** | + +## 二、运行趋势 + +最近 20 次运行状态： +``` +S S F S S S F S S S S S +``` +（S=成功 F=失败 R=运行中 -=待执行 C=已取消） + +| 时间段 | 总运行 | 成功 | 失败 | 成功率 | +|--------|--------|------|------|--------| +| 最近 7 天 | 10 | 8 | 2 | 80% | +| 7-14 天 | 2 | 2 | 0 | 100% | + +## 三、性能概览 + +| 指标 | 数值 | +|------|------| +| 平均耗时 | 2 分 39 秒 | +| 中位数耗时 | 3 分 5 秒 | +| P90 耗时 | 5 分 40 秒 | +| 最快构建 | 45 秒（#95 — 失败，提前终止） | +| 最慢构建 | 10 分 20 秒（#91 — Nightly Tests） | + +### 按流水线分组 + +| 流水线 | 运行次数 | 平均耗时 | 成功率 | +|--------|----------|----------|--------| +| CI Build (#7) | 9 | 3 分 5 秒 | 77.8% | +| Deploy Staging (#8) | 2 | 5 分 48 秒 | 100% | +| Nightly Tests (#10) | 1 | 10 分 20 秒 | 100% | + +## 四、故障摘要 + +| 运行 ID | 工作流 | 分支 | 状态 | 耗时 | 错误模式 | +|---------|--------|------|------|------|----------| +| #99 | ci.yml | master | failure | 1 分 7 秒 | F-TEST-001 单元测试断言失败，F-TEST-002 集成测试连接拒绝 | +| #95 | ci.yml | master | failure | 45 秒 | F-TEST-002 集成测试连接拒绝（未获取详细日志） | + +### 根因分析 + +两次失败均发生在 `test` 阶段，共同特征为 `connection refused to localhost:8080`，表明测试依赖的本地服务在构建环境中未正确启动。这是**集成测试环境配置问题**（F-TEST-002），而非代码逻辑错误。 + +## 五、改进建议 + +### 高优先级 + +1. **修复集成测试环境**：两次失败均为测试服务连接失败。建议在 CI 工作流中添加服务启动步骤，确保 localhost:8080 在测试运行前可用。可使用 `docker-compose` 或内联脚本启动依赖服务。 + +2. **启用 Deploy Production 流水线**：当前 Deploy Production（#9）处于禁用状态。如已不再需要，建议删除以减少管理负担；如仍需要，建议评估后重新启用。 + +### 中优先级 + +3. **配置失败通知**：当前未检测到失败通知机制。建议配置 Webhook 或邮件通知，确保构建失败时维护者能及时响应。 + +4. **添加缓存策略**：CI 构建平均 3 分钟，其中依赖安装可能占比较高。建议启用依赖缓存（如 Go module cache、npm cache）以缩短构建时间。 + +### 低优先级 + +5. **并行化测试阶段**：Nightly Tests 耗时超过 10 分钟，可考虑将测试拆分为多个并行任务以缩短总耗时。 + +6. **启用 Deploy Production 后配置审批门禁**：确保生产部署需人工确认，避免自动部署引入风险。 + +--- + +*报告由 gitlink-pipeline-guardian 生成* diff --git a/skills/gitlink-webhook-sentinel/SKILL.md b/skills/gitlink-webhook-sentinel/SKILL.md new file mode 100644 index 0000000..a4a73cf --- /dev/null +++ b/skills/gitlink-webhook-sentinel/SKILL.md @@ -0,0 +1,497 @@ +--- +name: gitlink-webhook-sentinel +version: 1.0.0 +description: "Webhook 监控哨兵：监控 Webhook 投递成功率、检测端点问题、验证安全配置、分析失败原因。当用户需要排查 Webhook 集成问题或监控 Webhook 健康状态时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli webhook --help" +--- + +# gitlink-webhook-sentinel（Webhook 监控哨兵） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 所有写入/删除操作前，务必先确认用户意图。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。** + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。 + +## 工作流概览 + +本 Skill 提供一套完整的 Webhook 监控与诊断工作流，覆盖从健康巡检到故障排查、安全审计和配置优化的全过程。 + +| 阶段 | 操作 | AI Agent 角色 | +|------|------|--------------| +| 1 健康巡检 | 列出所有 Webhook，检查投递历史，识别失败端点 | 采集数据并生成健康报告 | +| 2 故障诊断 | 深入分析失败投递记录，检查响应码和 Payload | 定位根因并给出修复建议 | +| 3 安全审计 | 验证 Webhook Secret、Content-Type 配置、端点安全性 | 检出安全隐患并生成审计报告 | +| 4 配置优化 | 审查事件订阅、分支过滤器、配置合理性 | 提出优化建议并协助调整 | + +--- + +## 命令参考 + +| 命令 | 说明 | +|------|------| +| `gitlink-cli webhook +list` | 列出仓库所有 Webhook | +| `gitlink-cli webhook +view --id ` | 查看单个 Webhook 详情 | +| `gitlink-cli webhook +create` | 创建 Webhook | +| `gitlink-cli webhook +update --id ` | 更新 Webhook | +| `gitlink-cli webhook +delete --id ` | 删除 Webhook | +| `gitlink-cli webhook +history --id ` | 查看 Webhook 投递历史（任务列表） | +| `gitlink-cli webhook +test --id ` | 发送测试事件到 Webhook 端点 | + +### 支持的 Webhook 类型 + +| 类型 | 说明 | +|------|------| +| `gitea` | Gitea 原生格式（默认） | +| `slack` | Slack 通知 | +| `discord` | Discord 通知 | +| `dingtalk` | 钉钉机器人 | +| `telegram` | Telegram Bot | +| `msteams` | Microsoft Teams | +| `feishu` | 飞书机器人 | +| `matrix` | Matrix 协议 | +| `jianmu` | 建木 CI | +| `softbot` | SoftBot | + +### 支持的事件类型 + +| 事件 | 说明 | +|------|------| +| `push` | 推送代码 | +| `create` | 创建分支/标签 | +| `delete` | 删除分支/标签 | +| `issues_only` | Issue 创建/更新 | +| `issue_assign` | Issue 分配 | +| `issue_label` | Issue 标签变更 | +| `issue_comment` | Issue 评论 | +| `pull_request_only` | PR 创建/更新 | +| `pull_request_assign` | PR 分配 | +| `pull_request_comment` | PR 评论 | + +### create/update 参数 + +| 参数 | 短选项 | 说明 | 默认值 | +|------|--------|------|--------| +| `--url` | `-u` | Webhook 端点 URL | （必填） | +| `--events` | `-e` | 逗号分隔的事件列表 | （必填） | +| `--type` | `-t` | Webhook 类型 | `gitea` | +| `--content-type` | | 内容格式：`json` 或 `form` | `json` | +| `--http-method` | | HTTP 方法：`GET` 或 `POST` | `POST` | +| `--secret` | `-s` | Webhook 签名密钥 | | +| `--branch-filter` | | 分支过滤通配符 | `*` | +| `--active` | | 是否激活：`true` 或 `false` | `true` | + +--- + +## 工作流 1：Webhook 健康巡检 + +**场景**：定期巡检仓库所有 Webhook 的运行状态，识别投递失败的端点。 + +### Step 1：获取所有 Webhook 列表 + +```bash +# 列出仓库所有 Webhook +gitlink-cli webhook +list --format json +``` + +分析返回数据，关注以下字段： +- `id`：Webhook ID +- `url`：端点地址 +- `active`：是否激活 +- `type`：Webhook 类型 +- `events`：订阅的事件列表 +- `branch_filter`：分支过滤规则 + +### Step 2：逐个检查投递历史 + +```bash +# 查看每个 Webhook 的投递任务记录 +gitlink-cli webhook +history --id --format json +``` + +对每个 Webhook，统计： +- 总投递次数 +- 成功次数（HTTP 2xx 响应） +- 失败次数（HTTP 4xx/5xx 响应或超时） +- 投递成功率 + +### Step 3：发送测试事件验证活跃端点 + +```bash +# 对可疑或长时间无投递记录的 Webhook 发送测试 +gitlink-cli webhook +test --id --format json +``` + +### Step 4：生成健康报告 + +按以下模板输出巡检报告： + +```markdown +## Webhook 健康巡检报告 — / + +### 总览 + +| 指标 | 数值 | +|------|------| +| Webhook 总数 | | +| 活跃 Webhook | | +| 未激活 Webhook | | +| 健康端点 | | +| 异常端点 | | +| 整体成功率 | % | + +### 端点健康状态 + +| ID | URL | 类型 | 状态 | 成功率 | 最近失败原因 | +|----|-----|------|:----:|:------:|-------------| +| | | | Healthy/Warning/Critical | xx% | | + +### 异常端点详情 + +#### Webhook # — +- **类型**： +- **事件订阅**： +- **分支过滤**： +- **最近投递状态**： +- **连续失败次数**： +- **建议操作**： + +--- +*由 gitlink-webhook-sentinel Skill 自动生成* +``` + +--- + +## 工作流 2：故障诊断 + +**场景**：当某个 Webhook 投递失败时，深入分析失败原因。 + +### Step 1：获取 Webhook 详情 + +```bash +# 查看目标 Webhook 完整配置 +gitlink-cli webhook +view --id --format json +``` + +重点检查： +- `url`：端点地址是否正确、是否可达 +- `content_type`：与目标系统期望的格式是否一致 +- `http_method`：是否与端点期望的方法一致 +- `active`：是否处于激活状态 +- `secret`：是否已配置签名密钥 + +### Step 2：获取投递历史 + +```bash +# 获取投递任务列表（包含每次投递的详细信息） +gitlink-cli webhook +history --id --format json +``` + +分析每次投递记录： +- 响应状态码（`response_status_code`） +- 响应内容（如有） +- 投递时间 +- 是否成功 + +### Step 3：根据状态码定位问题 + +参考「常见失败响应码参考表」进行匹配分析，确定根因类别。 + +### Step 4：发送测试验证 + +```bash +# 发送测试事件以复现/验证问题 +gitlink-cli webhook +test --id --format json +``` + +### Step 5：输出诊断报告 + +```markdown +## Webhook 故障诊断报告 — # + +### 诊断摘要 + +| 项目 | 详情 | +|------|------| +| Webhook ID | | +| 端点 URL | | +| 类型 | | +| 问题类别 | | +| 严重程度 | Critical/Warning/Info | + +### 根因分析 + +**主要原因**： + +**证据**： +- +- + +### 修复建议 + +1. **立即操作**： +2. **后续验证**： +3. **长期优化**： + +### 相关投递记录 + +| 时间 | 状态码 | 结果 | +|------|--------|------| +|