feat(skills): 新增 3 个 Agent Skill — wiki-builder, pipeline-guardian, webhook-sentinel
新增 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 <noreply@anthropic.com>
This commit is contained in:
whale
parent
7947d4dfd6
commit
f1dd01bebc
|
|
@ -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 <owner_id> --page 1 --limit 20 --format json
|
||||
```
|
||||
|
||||
记录所有流水线的 `id`、`name`、`status`。
|
||||
|
||||
### Step 2：获取近期运行记录
|
||||
|
||||
对每个流水线获取运行历史：
|
||||
|
||||
```bash
|
||||
gitlink-cli pipeline +runs --owner <owner> --repo <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 <owner> --repo <repo> --run-id <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 <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
### Step 2：获取运行结果
|
||||
|
||||
```bash
|
||||
gitlink-cli pipeline +results --owner <owner> --repo <repo> --run-id <failed_run_id> --format json
|
||||
```
|
||||
|
||||
确定失败的阶段（stage）和步骤（step）。
|
||||
|
||||
### Step 3：获取失败日志
|
||||
|
||||
```bash
|
||||
gitlink-cli pipeline +logs --owner <owner> --repo <repo> --run-id <failed_run_id> --id <pipeline_id> --index <job_index> --format json
|
||||
```
|
||||
|
||||
> **注意**：`pipeline +logs` 需要提供 `--run-id`、`--id`（流水线 ID）和 `--index`（作业索引）。先通过 `pipeline +results` 获取这些参数。
|
||||
|
||||
### Step 4：补充 CI 日志（如需要）
|
||||
|
||||
```bash
|
||||
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli ci +log --build <build_id> --format json
|
||||
```
|
||||
|
||||
### Step 5：分析错误模式
|
||||
|
||||
将日志中的错误信息与**常见失败模式目录**（见文末）匹配，定位根因。
|
||||
|
||||
### Step 6：输出分析报告
|
||||
|
||||
包含：
|
||||
- 失败构建基本信息（ID、分支、时间）
|
||||
- 错误日志关键片段
|
||||
- 匹配的失败模式
|
||||
- 根因分析结论
|
||||
- 修复建议（具体的代码或配置修改方案）
|
||||
|
||||
---
|
||||
|
||||
## 工作流 3：性能优化分析
|
||||
|
||||
**触发场景**：用户说"构建太慢了""优化一下流水线""构建耗时分析"。
|
||||
|
||||
### Step 1：收集运行耗时数据
|
||||
|
||||
```bash
|
||||
gitlink-cli pipeline +runs --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
提取每次运行的 `duration`，计算：
|
||||
- 平均耗时
|
||||
- 中位数耗时
|
||||
- 最大 / 最小耗时
|
||||
- P90 / P95 耗时
|
||||
|
||||
### Step 2：获取各阶段结果
|
||||
|
||||
对多次运行获取结果，对比各阶段耗时：
|
||||
|
||||
```bash
|
||||
gitlink-cli pipeline +results --owner <owner> --repo <repo> --run-id <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 <owner_id> --format json
|
||||
```
|
||||
|
||||
对每个流水线：
|
||||
|
||||
```bash
|
||||
gitlink-cli pipeline +view --owner <owner> --repo <repo> --id <pipeline_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 调用频率，避免请求过快
|
||||
- 日志分析时仅提取关键错误行，避免处理过多数据
|
||||
- 将巡检报告保存为文件以便后续对比和追踪趋势
|
||||
|
|
@ -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 生成*
|
||||
|
|
@ -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 <id>` | 查看单个 Webhook 详情 |
|
||||
| `gitlink-cli webhook +create` | 创建 Webhook |
|
||||
| `gitlink-cli webhook +update --id <id>` | 更新 Webhook |
|
||||
| `gitlink-cli webhook +delete --id <id>` | 删除 Webhook |
|
||||
| `gitlink-cli webhook +history --id <id>` | 查看 Webhook 投递历史（任务列表） |
|
||||
| `gitlink-cli webhook +test --id <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 <webhook_id> --format json
|
||||
```
|
||||
|
||||
对每个 Webhook，统计：
|
||||
- 总投递次数
|
||||
- 成功次数（HTTP 2xx 响应）
|
||||
- 失败次数（HTTP 4xx/5xx 响应或超时）
|
||||
- 投递成功率
|
||||
|
||||
### Step 3：发送测试事件验证活跃端点
|
||||
|
||||
```bash
|
||||
# 对可疑或长时间无投递记录的 Webhook 发送测试
|
||||
gitlink-cli webhook +test --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
### Step 4：生成健康报告
|
||||
|
||||
按以下模板输出巡检报告：
|
||||
|
||||
```markdown
|
||||
## Webhook 健康巡检报告 — <owner>/<repo>
|
||||
|
||||
### 总览
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| Webhook 总数 | <total> |
|
||||
| 活跃 Webhook | <active_count> |
|
||||
| 未激活 Webhook | <inactive_count> |
|
||||
| 健康端点 | <healthy_count> |
|
||||
| 异常端点 | <unhealthy_count> |
|
||||
| 整体成功率 | <success_rate>% |
|
||||
|
||||
### 端点健康状态
|
||||
|
||||
| ID | URL | 类型 | 状态 | 成功率 | 最近失败原因 |
|
||||
|----|-----|------|:----:|:------:|-------------|
|
||||
| <id> | <url> | <type> | Healthy/Warning/Critical | xx% | <reason> |
|
||||
|
||||
### 异常端点详情
|
||||
|
||||
#### Webhook #<id> — <url>
|
||||
- **类型**：<type>
|
||||
- **事件订阅**：<events>
|
||||
- **分支过滤**：<branch_filter>
|
||||
- **最近投递状态**：<last_delivery_status>
|
||||
- **连续失败次数**：<consecutive_failures>
|
||||
- **建议操作**：<recommendation>
|
||||
|
||||
---
|
||||
*由 gitlink-webhook-sentinel Skill 自动生成*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流 2：故障诊断
|
||||
|
||||
**场景**：当某个 Webhook 投递失败时，深入分析失败原因。
|
||||
|
||||
### Step 1：获取 Webhook 详情
|
||||
|
||||
```bash
|
||||
# 查看目标 Webhook 完整配置
|
||||
gitlink-cli webhook +view --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
重点检查：
|
||||
- `url`：端点地址是否正确、是否可达
|
||||
- `content_type`：与目标系统期望的格式是否一致
|
||||
- `http_method`：是否与端点期望的方法一致
|
||||
- `active`：是否处于激活状态
|
||||
- `secret`：是否已配置签名密钥
|
||||
|
||||
### Step 2：获取投递历史
|
||||
|
||||
```bash
|
||||
# 获取投递任务列表（包含每次投递的详细信息）
|
||||
gitlink-cli webhook +history --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
分析每次投递记录：
|
||||
- 响应状态码（`response_status_code`）
|
||||
- 响应内容（如有）
|
||||
- 投递时间
|
||||
- 是否成功
|
||||
|
||||
### Step 3：根据状态码定位问题
|
||||
|
||||
参考「常见失败响应码参考表」进行匹配分析，确定根因类别。
|
||||
|
||||
### Step 4：发送测试验证
|
||||
|
||||
```bash
|
||||
# 发送测试事件以复现/验证问题
|
||||
gitlink-cli webhook +test --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
### Step 5：输出诊断报告
|
||||
|
||||
```markdown
|
||||
## Webhook 故障诊断报告 — #<id> <url>
|
||||
|
||||
### 诊断摘要
|
||||
|
||||
| 项目 | 详情 |
|
||||
|------|------|
|
||||
| Webhook ID | <id> |
|
||||
| 端点 URL | <url> |
|
||||
| 类型 | <type> |
|
||||
| 问题类别 | <category> |
|
||||
| 严重程度 | Critical/Warning/Info |
|
||||
|
||||
### 根因分析
|
||||
|
||||
**主要原因**：<primary_cause>
|
||||
|
||||
**证据**：
|
||||
- <evidence_1>
|
||||
- <evidence_2>
|
||||
|
||||
### 修复建议
|
||||
|
||||
1. **立即操作**：<immediate_fix>
|
||||
2. **后续验证**：<verification_step>
|
||||
3. **长期优化**：<long_term_improvement>
|
||||
|
||||
### 相关投递记录
|
||||
|
||||
| 时间 | 状态码 | 结果 |
|
||||
|------|--------|------|
|
||||
| <time> | <code> | Success/Failed |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流 3：安全审计
|
||||
|
||||
**场景**：审查 Webhook 配置的安全性，检查 Secret 配置、Content-Type 和端点安全性。
|
||||
|
||||
### Step 1：获取所有 Webhook 配置
|
||||
|
||||
```bash
|
||||
# 列出所有 Webhook
|
||||
gitlink-cli webhook +list --format json
|
||||
|
||||
# 逐个查看详细配置
|
||||
gitlink-cli webhook +view --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
### Step 2：安全检查清单
|
||||
|
||||
逐项审查以下安全指标：
|
||||
|
||||
| 检查项 | 安全标准 | 风险等级 |
|
||||
|--------|----------|:--------:|
|
||||
| Secret 配置 | 所有生产 Webhook 必须配置签名密钥 | Critical |
|
||||
| URL 协议 | 必须使用 HTTPS，禁止 HTTP | Critical |
|
||||
| Content-Type | 推荐 `json`，避免 `form`（结构化更强） | Warning |
|
||||
| URL 暴露信息 | URL 中不应包含 Token、密钥等敏感信息 | Critical |
|
||||
| 事件范围 | 仅订阅必要事件，避免过度订阅 | Warning |
|
||||
| 分支过滤 | 生产环境应设置分支过滤，不建议 `*` | Info |
|
||||
| 激活状态 | 已废弃的 Webhook 应设为未激活或删除 | Info |
|
||||
|
||||
### Step 3：输出安全审计报告
|
||||
|
||||
```markdown
|
||||
## Webhook 安全审计报告 — <owner>/<repo>
|
||||
|
||||
### 审计概要
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 审计 Webhook 数 | <total> |
|
||||
| 通过检查 | <passed> |
|
||||
| 存在风险 | <at_risk> |
|
||||
| Critical 风险 | <critical_count> |
|
||||
| Warning 风险 | <warning_count> |
|
||||
|
||||
### 检查结果
|
||||
|
||||
| ID | URL | Secret | HTTPS | Content-Type | 事件范围 | 风险等级 |
|
||||
|----|-----|:------:|:-----:|:------------:|----------|:--------:|
|
||||
| <id> | <url> | Yes/No | Yes/No | json/form | <events> | Healthy/At Risk |
|
||||
|
||||
### Critical 问题
|
||||
|
||||
#### Webhook #<id> — 未配置 Secret
|
||||
- **影响**：任何人都可以伪造 Webhook Payload，存在安全风险
|
||||
- **修复**：
|
||||
```bash
|
||||
gitlink-cli webhook +update --id <id> --secret "<strong_secret>"
|
||||
```
|
||||
- **注意**：更新 Secret 后需同步更新接收端的验签逻辑
|
||||
|
||||
#### Webhook #<id> — 使用 HTTP 端点
|
||||
- **影响**：Payload 以明文传输，可被中间人截获
|
||||
- **修复**：将 URL 更改为 HTTPS 端点
|
||||
```bash
|
||||
gitlink-cli webhook +update --id <id> --url "https://..."
|
||||
```
|
||||
|
||||
### Warning 问题
|
||||
|
||||
<按严重程度列出所有 Warning 级别问题>
|
||||
|
||||
### 改进建议
|
||||
|
||||
1. <suggestion_1>
|
||||
2. <suggestion_2>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流 4：Webhook 配置优化
|
||||
|
||||
**场景**：审查现有 Webhook 的配置合理性，优化事件订阅和分支过滤规则。
|
||||
|
||||
### Step 1：获取当前配置
|
||||
|
||||
```bash
|
||||
# 获取所有 Webhook 列表
|
||||
gitlink-cli webhook +list --format json
|
||||
|
||||
# 查看每个 Webhook 的详细配置
|
||||
gitlink-cli webhook +view --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
### Step 2：配置审查
|
||||
|
||||
对每个 Webhook 逐项审查：
|
||||
|
||||
**事件订阅优化**：
|
||||
- 是否订阅了从未触发过的事件？建议移除
|
||||
- 是否遗漏了必要的事件？建议补充
|
||||
- 同一端点是否存在多个 Webhook 重复订阅？建议合并
|
||||
|
||||
**分支过滤优化**：
|
||||
- `branch_filter` 为 `*` 时：确认是否确实需要监听所有分支
|
||||
- 生产环境建议限定为 `master,main,release-*` 等模式
|
||||
- 开发环境可放宽为 `*` 或 `feature/*`
|
||||
|
||||
**类型与格式优化**：
|
||||
- 目标系统类型是否正确（`gitea` / `slack` / `dingtalk` 等）
|
||||
- `content_type` 是否与目标系统匹配（推荐 `json`）
|
||||
- `http_method` 是否正确
|
||||
|
||||
**冗余清理**：
|
||||
- 是否有指向已下线服务的 Webhook？应删除
|
||||
- 是否有长期未激活的 Webhook？确认是否仍需要
|
||||
|
||||
### Step 3：生成优化建议
|
||||
|
||||
```markdown
|
||||
## Webhook 配置优化报告 — <owner>/<repo>
|
||||
|
||||
### 优化概要
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 审查 Webhook 数 | <total> |
|
||||
| 需要优化 | <needs_optimization> |
|
||||
| 配置合理 | <well_configured> |
|
||||
| 建议删除 | <recommend_deletion> |
|
||||
|
||||
### 优化建议明细
|
||||
|
||||
#### Webhook #<id> — <url>
|
||||
|
||||
**当前配置**：
|
||||
- 事件：<current_events>
|
||||
- 分支过滤：<current_branch_filter>
|
||||
- 类型：<current_type>
|
||||
- Content-Type：<current_content_type>
|
||||
|
||||
**优化建议**：
|
||||
| 项目 | 当前值 | 建议值 | 原因 |
|
||||
|------|--------|--------|------|
|
||||
| events | <current> | <suggested> | <reason> |
|
||||
| branch-filter | <current> | <suggested> | <reason> |
|
||||
|
||||
**执行命令**：
|
||||
```bash
|
||||
gitlink-cli webhook +update --id <id> --events "push,pull_request_only" --branch-filter "master,main"
|
||||
```
|
||||
|
||||
### 冗余 Webhook 清理
|
||||
|
||||
| ID | URL | 原因 | 操作 |
|
||||
|----|-----|------|------|
|
||||
| <id> | <url> | <reason> | 删除/禁用 |
|
||||
```
|
||||
|
||||
### Step 4：执行优化（需用户确认）
|
||||
|
||||
**CRITICAL — 所有修改操作前务必确认用户意图。**
|
||||
|
||||
```bash
|
||||
# 更新 Webhook 配置
|
||||
gitlink-cli webhook +update --id <id> --events "<optimized_events>" --branch-filter "<filter>"
|
||||
|
||||
# 删除确认废弃的 Webhook（需用户明确同意）
|
||||
gitlink-cli webhook +delete --id <id>
|
||||
|
||||
# 更新后发送测试验证
|
||||
gitlink-cli webhook +test --id <id> --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见失败响应码参考表
|
||||
|
||||
| HTTP 状态码 | 含义 | 可能原因 | 排查方向 |
|
||||
|:-----------:|------|----------|----------|
|
||||
| `200` | 成功 | 正常投递 | 无需处理 |
|
||||
| `301/302` | 重定向 | 端点 URL 已变更 | 更新为最终目标 URL |
|
||||
| `400` | 请求无效 | Payload 格式错误、Content-Type 不匹配 | 检查 `content_type` 配置，验证 Payload 结构 |
|
||||
| `401` | 未认证 | 目标端点要求认证但未提供 | 检查 URL 是否需要 Basic Auth，或在 URL 中嵌入认证参数 |
|
||||
| `403` | 禁止访问 | 签名验证失败、IP 白名单未通过 | 检查 Secret 配置是否与接收端一致 |
|
||||
| `404` | 未找到 | 端点 URL 错误或已下线 | 确认 URL 是否正确，服务是否在运行 |
|
||||
| `408` | 请求超时 | 接收端处理过慢 | 优化接收端逻辑，或联系服务方 |
|
||||
| `422` | 无法处理 | Payload 结构不符合目标系统预期 | 检查 `type` 配置是否匹配目标系统 |
|
||||
| `429` | 请求过多 | 触发目标系统限流 | 降低事件触发频率或联系服务方提高限额 |
|
||||
| `500` | 服务器内部错误 | 接收端服务异常 | 联系目标系统维护方 |
|
||||
| `502` | 网关错误 | 目标服务器上游故障 | 检查目标服务是否正常，稍后重试 |
|
||||
| `503` | 服务不可用 | 目标服务维护或过载 | 等待恢复后重试 |
|
||||
| `504` | 网关超时 | 接收端响应时间过长 | 优化接收端处理逻辑，或设置异步处理 |
|
||||
| Timeout | 连接超时 | 网络不通、DNS 解析失败、防火墙阻断 | 检查网络连通性、DNS 配置、防火墙规则 |
|
||||
|
||||
---
|
||||
|
||||
## Raw API 参考
|
||||
|
||||
Webhook 相关的 GitLink API 端点：
|
||||
|
||||
```bash
|
||||
# 列出所有 Webhook
|
||||
gitlink-cli api GET /v1/:owner/:repo/webhooks --format json
|
||||
|
||||
# 查看 Webhook 详情
|
||||
gitlink-cli api GET /v1/:owner/:repo/webhooks/:id --format json
|
||||
|
||||
# 创建 Webhook
|
||||
gitlink-cli api POST /v1/:owner/:repo/webhooks --body '{
|
||||
"type": "gitea",
|
||||
"active": true,
|
||||
"content_type": "json",
|
||||
"http_method": "POST",
|
||||
"url": "https://example.com/webhook",
|
||||
"secret": "your-secret",
|
||||
"branch_filter": "master",
|
||||
"events": ["push", "pull_request_only"]
|
||||
}'
|
||||
|
||||
# 更新 Webhook
|
||||
gitlink-cli api PUT /v1/:owner/:repo/webhooks/:id --body '{...}'
|
||||
|
||||
# 删除 Webhook
|
||||
gitlink-cli api DELETE /v1/:owner/:repo/webhooks/:id
|
||||
|
||||
# 获取投递任务历史
|
||||
gitlink-cli api GET /v1/:owner/:repo/webhooks/:id/hooktasks --format json
|
||||
|
||||
# 发送测试事件
|
||||
gitlink-cli api POST /v1/:owner/:repo/webhooks/:id/tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `webhook +history` 返回的是该 Webhook 的投递任务列表（hooktasks），包含每次投递的状态和响应信息
|
||||
- `webhook +test` 会向目标端点发送一个测试 Payload，请确保目标服务能处理测试事件
|
||||
- 更新 Webhook 的 Secret 时，接收端的验签逻辑需同步更新
|
||||
- 删除 Webhook 是不可逆操作，执行前务必确认
|
||||
- 对于使用 `--format json` 的命令，建议配合 `jq` 工具进行数据过滤和统计
|
||||
|
||||
---
|
||||
|
||||
## 相关 Skill 交叉引用
|
||||
|
||||
| Skill | 关联场景 |
|
||||
|-------|----------|
|
||||
| [`gitlink-shared`](../gitlink-shared/SKILL.md) | 认证、全局参数、安全规则基础 |
|
||||
| [`gitlink-workflow`](../gitlink-workflow/SKILL.md) | AI 自动化工作流 |
|
||||
| [`gitlink-health`](../gitlink-health/SKILL.md) | 项目整体健康度分析（Webhook 可作为子维度） |
|
||||
|
|
@ -0,0 +1,226 @@
|
|||
# Webhook 健康巡检工作流示例
|
||||
|
||||
本文档展示一个完整的 Webhook 健康巡检工作流，涵盖列出 Webhook、检查投递历史、识别问题端点、安全审计和配置优化的全过程。
|
||||
|
||||
> **前置条件**：已完成 `gitlink-cli auth login` 认证。所有命令使用 `gitlink-cli`，不使用 `gh`。
|
||||
|
||||
---
|
||||
|
||||
## 场景描述
|
||||
|
||||
仓库 `whale_hihihi/test` 配置了多个 Webhook，需要：
|
||||
1. 巡检所有 Webhook 的健康状态
|
||||
2. 诊断投递失败的端点
|
||||
3. 审计安全配置
|
||||
4. 优化 Webhook 配置
|
||||
|
||||
---
|
||||
|
||||
## Step 1：列出所有 Webhook
|
||||
|
||||
```bash
|
||||
# 获取仓库所有 Webhook
|
||||
gitlink-cli webhook +list --owner whale_hihihi --repo test --format json
|
||||
```
|
||||
|
||||
**示例输出分析**：
|
||||
|
||||
假设仓库有 3 个 Webhook：
|
||||
- `#10` — `https://ci.example.com/webhook` (Gitea, active)
|
||||
- `#11` — `https://hooks.slack.com/services/T00/B00/xxx` (Slack, active)
|
||||
- `#12` — `http://dev.local:3000/hook` (Gitea, active)
|
||||
|
||||
**初步发现**：
|
||||
- Webhook #12 使用 HTTP 而非 HTTPS（安全风险）
|
||||
- 共 3 个 Webhook，全部处于激活状态
|
||||
|
||||
---
|
||||
|
||||
## Step 2：逐个检查投递历史
|
||||
|
||||
```bash
|
||||
# 检查 Webhook #10 的投递历史
|
||||
gitlink-cli webhook +history --id 10 --format json
|
||||
|
||||
# 检查 Webhook #11 的投递历史
|
||||
gitlink-cli webhook +history --id 11 --format json
|
||||
|
||||
# 检查 Webhook #12 的投递历史
|
||||
gitlink-cli webhook +history --id 12 --format json
|
||||
```
|
||||
|
||||
**示例分析**：
|
||||
|
||||
| Webhook | 总投递 | 成功 | 失败 | 成功率 | 状态 |
|
||||
|---------|--------|------|------|--------|------|
|
||||
| #10 CI | 50 | 48 | 2 | 96% | Healthy |
|
||||
| #11 Slack | 30 | 25 | 5 | 83% | Warning |
|
||||
| #12 Dev | 10 | 3 | 7 | 30% | Critical |
|
||||
|
||||
---
|
||||
|
||||
## Step 3：深入诊断异常端点
|
||||
|
||||
### 诊断 Webhook #11（Slack）
|
||||
|
||||
```bash
|
||||
# 查看详细配置
|
||||
gitlink-cli webhook +view --id 11 --format json
|
||||
```
|
||||
|
||||
分析投递失败记录，发现响应码为 `403`。参考失败码表：
|
||||
- `403` = 签名验证失败或 IP 白名单未通过
|
||||
|
||||
**结论**：Slack Webhook Secret 可能配置不正确。
|
||||
|
||||
### 诊断 Webhook #12（Dev Local）
|
||||
|
||||
```bash
|
||||
# 查看详细配置
|
||||
gitlink-cli webhook +view --id 12 --format json
|
||||
```
|
||||
|
||||
分析投递失败记录，发现响应码为 `504`（网关超时）和 `Timeout`（连接超时）。
|
||||
|
||||
**结论**：本地开发服务器响应过慢或网络不通。
|
||||
|
||||
### 发送测试验证
|
||||
|
||||
```bash
|
||||
# 对 Webhook #11 发送测试
|
||||
gitlink-cli webhook +test --id 11 --format json
|
||||
|
||||
# 对 Webhook #12 发送测试
|
||||
gitlink-cli webhook +test --id 12 --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4：安全审计
|
||||
|
||||
对每个 Webhook 逐项检查：
|
||||
|
||||
| 检查项 | #10 CI | #11 Slack | #12 Dev |
|
||||
|--------|--------|-----------|---------|
|
||||
| Secret 配置 | Yes | No | Yes |
|
||||
| HTTPS | Yes | Yes | No |
|
||||
| Content-Type | json | json | json |
|
||||
| 事件范围 | push | push,issues_only,pull_request_only | push,create,delete |
|
||||
| 分支过滤 | master | * | * |
|
||||
|
||||
**审计发现**：
|
||||
- **Critical**：#11 未配置 Secret（可被伪造）
|
||||
- **Critical**：#12 使用 HTTP（明文传输）
|
||||
- **Warning**：#11 和 #12 的 `branch_filter` 为 `*`（监听所有分支）
|
||||
|
||||
---
|
||||
|
||||
## Step 5：配置优化建议
|
||||
|
||||
### Webhook #10（CI）— 配置合理
|
||||
- 事件订阅和分支过滤合理，无需调整
|
||||
|
||||
### Webhook #11（Slack）— 需要修复
|
||||
- 添加 Secret
|
||||
- 收窄分支过滤
|
||||
|
||||
```bash
|
||||
# 修复：添加 Secret 并限制分支过滤
|
||||
gitlink-cli webhook +update --id 11 --secret "xJk9$mK2pL5qR8vW" --branch-filter "master,main"
|
||||
```
|
||||
|
||||
### Webhook #12（Dev Local）— 建议禁用或删除
|
||||
- 开发环境 Webhook，使用 HTTP 且不稳定
|
||||
- 建议禁用或删除
|
||||
|
||||
```bash
|
||||
# 选项 A：禁用
|
||||
gitlink-cli webhook +update --id 12 --active false
|
||||
|
||||
# 选项 B：删除（需用户确认）
|
||||
gitlink-cli webhook +delete --id 12
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6：生成完整报告
|
||||
|
||||
巡检完成后，输出以下报告：
|
||||
|
||||
```markdown
|
||||
## Webhook 健康巡检报告 — whale_hihihi/test
|
||||
|
||||
### 总览
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| Webhook 总数 | 3 |
|
||||
| 活跃 Webhook | 3 |
|
||||
| 健康端点 | 1 |
|
||||
| Warning 端点 | 1 |
|
||||
| Critical 端点 | 1 |
|
||||
| 整体成功率 | 76/90 (84.4%) |
|
||||
|
||||
### 端点健康状态
|
||||
|
||||
| ID | URL | 类型 | 状态 | 成功率 | 最近失败原因 |
|
||||
|----|-----|------|:----:|:------:|-------------|
|
||||
| 10 | https://ci.example.com/webhook | gitea | Healthy | 96% | — |
|
||||
| 11 | https://hooks.slack.com/... | slack | Warning | 83% | 403 Forbidden |
|
||||
| 12 | http://dev.local:3000/hook | gitea | Critical | 30% | 504 Gateway Timeout |
|
||||
|
||||
### 安全审计
|
||||
|
||||
| ID | Secret | HTTPS | 分支过滤 | 风险等级 |
|
||||
|----|:------:|:-----:|----------|:--------:|
|
||||
| 10 | Yes | Yes | master | Healthy |
|
||||
| 11 | No | Yes | * | At Risk |
|
||||
| 12 | Yes | No | * | At Risk |
|
||||
|
||||
### 异常端点详情
|
||||
|
||||
#### Webhook #11 — Slack 通知
|
||||
- **问题**：Secret 未配置 + 分支过滤过宽
|
||||
- **连续失败**：最近 5 次投递中 5 次返回 403
|
||||
- **修复命令**：
|
||||
```bash
|
||||
gitlink-cli webhook +update --id 11 --secret "<secret>" --branch-filter "master,main"
|
||||
```
|
||||
|
||||
#### Webhook #12 — Dev Local
|
||||
- **问题**：HTTP 明文传输 + 目标服务不稳定
|
||||
- **连续失败**：最近 7 次投递中 7 次超时
|
||||
- **修复建议**：确认服务是否仍在使用，若已废弃建议删除
|
||||
```bash
|
||||
gitlink-cli webhook +delete --id 12
|
||||
```
|
||||
|
||||
### 优化操作汇总
|
||||
|
||||
| 优先级 | 操作 | 命令 |
|
||||
|--------|------|------|
|
||||
| P0 | 为 Slack Webhook 添加 Secret | `gitlink-cli webhook +update --id 11 --secret "..."` |
|
||||
| P1 | 禁用/删除 Dev Local Webhook | `gitlink-cli webhook +delete --id 12` |
|
||||
| P2 | Slack Webhook 收窄分支过滤 | `gitlink-cli webhook +update --id 11 --branch-filter "master,main"` |
|
||||
|
||||
---
|
||||
*由 gitlink-webhook-sentinel Skill 自动生成*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 后续验证
|
||||
|
||||
修复操作完成后，再次执行测试验证：
|
||||
|
||||
```bash
|
||||
# 验证修复后的 Webhook #11
|
||||
gitlink-cli webhook +test --id 11 --format json
|
||||
|
||||
# 确认 Webhook #12 已删除
|
||||
gitlink-cli webhook +list --format json
|
||||
```
|
||||
|
||||
预期结果：
|
||||
- Webhook #11 测试投递返回 200
|
||||
- Webhook 列表中不再包含 #12
|
||||
|
|
@ -0,0 +1,341 @@
|
|||
---
|
||||
name: gitlink-wiki-builder
|
||||
version: 1.0.0
|
||||
description: "Wiki 文档自动化：自动组织文档结构、生成侧边栏导航、创建文档模板、同步代码变更到 Wiki。当用户需要批量管理 Wiki 页面、生成项目文档或维护 Wiki 结构时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli wiki --help"
|
||||
---
|
||||
|
||||
# gitlink-wiki-builder（Wiki 文档自动化）
|
||||
|
||||
**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) 了解认证和全局参数。
|
||||
|
||||
## 命令参考
|
||||
|
||||
GitLink Wiki 支持 9 个 CLI 命令：
|
||||
|
||||
| 命令 | 功能 | 关键 Flags |
|
||||
|------|------|-----------|
|
||||
| `wiki +list` | 列出所有 Wiki 页面 | `--format json` |
|
||||
| `wiki +view` | 查看单个页面内容 | `--name (-n)` |
|
||||
| `wiki +create` | 创建新页面 | `--name (-n)`, `--content (-c)`, `--message (-m)`, `--dir (-d)` |
|
||||
| `wiki +update` | 更新页面内容 | `--name (-n)`, `--content (-c)`, `--message (-m)` |
|
||||
| `wiki +delete` | 删除页面（自动清理侧边栏） | `--name (-n)` |
|
||||
| `wiki +mkdir` | 创建侧边栏目录 | `--name (-n)`, `--parent (-p)` |
|
||||
| `wiki +rmdir` | 删除侧边栏目录及子项 | `--name (-n)` |
|
||||
| `wiki +rename` | 重命名页面（迁移内容 + 更新侧边栏） | `--name (-n)`, `--new-name (-N)` |
|
||||
| `wiki +renamedir` | 重命名侧边栏目录 | `--name (-n)`, `--new-name (-N)` |
|
||||
|
||||
### 侧边栏结构模板
|
||||
|
||||
GitLink Wiki 使用 `_Sidebar` 特殊页面管理导航。侧边栏结构采用缩进层级：
|
||||
|
||||
```
|
||||
- 开发指南
|
||||
[[开发环境搭建]]
|
||||
[[代码规范]]
|
||||
[[提交规范]]
|
||||
- API参考
|
||||
[[REST API 概览]]
|
||||
[[认证与授权]]
|
||||
[[错误码说明]]
|
||||
- 架构设计
|
||||
[[系统架构总览]]
|
||||
[[数据库设计]]
|
||||
[[模块依赖关系]]
|
||||
- 常见问题
|
||||
[[安装问题排查]]
|
||||
[[配置说明]]
|
||||
[[FAQ]]
|
||||
```
|
||||
|
||||
- 顶层目录以 `- 目录名` 表示
|
||||
- 子页面以 Tab 缩进 + `[[页面名]]` 链接表示
|
||||
- `wiki +create --dir <目录名>` 自动在对应目录下插入页面链接
|
||||
- `wiki +mkdir` 创建新目录，`wiki +rmdir` 删除目录及其子项
|
||||
|
||||
---
|
||||
|
||||
## 工作流概览
|
||||
|
||||
| 阶段 | 工作流 | 说明 |
|
||||
|------|--------|------|
|
||||
| 1 | 文档结构初始化 | 创建完整的 Wiki 目录结构和索引页面 |
|
||||
| 2 | 侧边栏导航维护 | 自动生成和更新侧边栏导航 |
|
||||
| 3 | 文档模板生成 | 创建标准文档模板（贡献指南、开发环境等） |
|
||||
| 4 | 批量页面更新 | 批量更新 Wiki 页面内容 |
|
||||
|
||||
---
|
||||
|
||||
## 详细工作流
|
||||
|
||||
### 工作流 1：文档结构初始化
|
||||
|
||||
**场景**：项目新建或重构时，一键创建标准化的 Wiki 文档结构。
|
||||
|
||||
#### Step 1：创建侧边栏顶级目录
|
||||
|
||||
```bash
|
||||
# 创建四大核心目录
|
||||
gitlink-cli wiki +mkdir --name "开发指南"
|
||||
gitlink-cli wiki +mkdir --name "API参考"
|
||||
gitlink-cli wiki +mkdir --name "架构设计"
|
||||
gitlink-cli wiki +mkdir --name "常见问题"
|
||||
```
|
||||
|
||||
> 目录创建后会在 `_Sidebar` 页面自动添加对应的顶级条目。
|
||||
|
||||
#### Step 2：在各目录下创建索引页面
|
||||
|
||||
```bash
|
||||
# 开发指南目录
|
||||
gitlink-cli wiki +create \
|
||||
--name "开发环境搭建" \
|
||||
--content "# 开发环境搭建\n\n## 前置要求\n\n...\n\n## 安装步骤\n\n...\n\n## 常用命令\n\n..." \
|
||||
--message "初始化：创建开发环境搭建文档" \
|
||||
--dir "开发指南"
|
||||
|
||||
gitlink-cli wiki +create \
|
||||
--name "代码规范" \
|
||||
--content "# 代码规范\n\n## 命名约定\n\n...\n\n## 格式化\n\n..." \
|
||||
--message "初始化：创建代码规范文档" \
|
||||
--dir "开发指南"
|
||||
|
||||
gitlink-cli wiki +create \
|
||||
--name "提交规范" \
|
||||
--content "# 提交规范\n\n## Commit Message 格式\n\n...\n\n## 分支策略\n\n..." \
|
||||
--message "初始化：创建提交规范文档" \
|
||||
--dir "开发指南"
|
||||
|
||||
# API参考目录
|
||||
gitlink-cli wiki +create \
|
||||
--name "REST API 概览" \
|
||||
--content "# REST API 概览\n\n## 基础 URL\n\n...\n\n## 认证方式\n\n...\n\n## 通用响应格式\n\n..." \
|
||||
--message "初始化：创建 API 概览文档" \
|
||||
--dir "API参考"
|
||||
|
||||
gitlink-cli wiki +create \
|
||||
--name "认证与授权" \
|
||||
--content "# 认证与授权\n\n## OAuth2 流程\n\n...\n\n## Token 管理\n\n..." \
|
||||
--message "初始化：创建认证文档" \
|
||||
--dir "API参考"
|
||||
|
||||
gitlink-cli wiki +create \
|
||||
--name "错误码说明" \
|
||||
--content "# 错误码说明\n\n## HTTP 状态码\n\n...\n\n## 业务错误码\n\n..." \
|
||||
--message "初始化：创建错误码文档" \
|
||||
--dir "API参考"
|
||||
|
||||
# 架构设计目录
|
||||
gitlink-cli wiki +create \
|
||||
--name "系统架构总览" \
|
||||
--content "# 系统架构总览\n\n## 整体架构\n\n...\n\n## 核心模块\n\n..." \
|
||||
--message "初始化：创建架构总览文档" \
|
||||
--dir "架构设计"
|
||||
|
||||
# 常见问题目录
|
||||
gitlink-cli wiki +create \
|
||||
--name "FAQ" \
|
||||
--content "# 常见问题\n\n## 安装相关\n\n### Q: 安装失败怎么办？\n\n...\n\n## 使用相关\n\n..." \
|
||||
--message "初始化：创建 FAQ 文档" \
|
||||
--dir "常见问题"
|
||||
```
|
||||
|
||||
> `--dir` 参数会在侧边栏对应目录下自动添加 `[[页面名]]` 链接。
|
||||
|
||||
#### Step 3：验证结构
|
||||
|
||||
```bash
|
||||
# 列出所有 Wiki 页面，确认创建结果
|
||||
gitlink-cli wiki +list --format json
|
||||
|
||||
# 查看侧边栏，确认导航结构正确
|
||||
gitlink-cli wiki +view --name "_Sidebar"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 工作流 2：侧边栏导航维护
|
||||
|
||||
**场景**：项目文档结构变更时，自动维护侧边栏导航的一致性。
|
||||
|
||||
#### 场景 A：添加新页面到已有目录
|
||||
|
||||
```bash
|
||||
# 创建页面并直接关联到目录
|
||||
gitlink-cli wiki +create \
|
||||
--name "部署指南" \
|
||||
--content "# 部署指南\n\n## Docker 部署\n\n...\n\n## 手动部署\n\n..." \
|
||||
--message "添加部署指南" \
|
||||
--dir "开发指南"
|
||||
```
|
||||
|
||||
> `--dir` 自动将 `[[部署指南]]` 插入到侧边栏 "开发指南" 目录下。
|
||||
|
||||
#### 场景 B：添加新的子目录
|
||||
|
||||
```bash
|
||||
# 在已有目录下创建子目录
|
||||
gitlink-cli wiki +mkdir --name "数据库" --parent "架构设计"
|
||||
|
||||
# 在子目录下创建页面
|
||||
gitlink-cli wiki +create \
|
||||
--name "数据库设计" \
|
||||
--content "# 数据库设计\n\n## ER 图\n\n...\n\n## 表结构说明\n\n..." \
|
||||
--message "添加数据库设计文档" \
|
||||
--dir "数据库"
|
||||
```
|
||||
|
||||
> `--parent` 在指定目录下创建缩进的子目录。
|
||||
|
||||
#### 场景 C：删除页面和目录
|
||||
|
||||
```bash
|
||||
# 删除页面（自动从侧边栏移除链接）
|
||||
gitlink-cli wiki +delete --name "旧文档"
|
||||
|
||||
# 删除目录（自动移除目录及所有子项）
|
||||
gitlink-cli wiki +rmdir --name "废弃目录"
|
||||
```
|
||||
|
||||
> `+delete` 会自动清理侧边栏中对应的 `[[页面名]]` 链接。`+rmdir` 会移除目录行及所有子行。
|
||||
|
||||
#### 场景 D：重命名页面和目录
|
||||
|
||||
```bash
|
||||
# 重命名页面（自动迁移内容 + 更新侧边栏链接）
|
||||
gitlink-cli wiki +rename --name "旧名称" --new-name "新名称"
|
||||
|
||||
# 重命名目录（更新侧边栏中的目录标题）
|
||||
gitlink-cli wiki +renamedir --name "旧目录名" --new-name "新目录名"
|
||||
```
|
||||
|
||||
> `+rename` 执行"获取旧页面内容 → 创建新页面 → 删除旧页面 → 更新侧边栏"的完整流程。
|
||||
|
||||
---
|
||||
|
||||
### 工作流 3：文档模板生成
|
||||
|
||||
**场景**：为新项目或标准化流程批量创建文档模板页面。
|
||||
|
||||
#### Step 1：生成贡献指南
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +create \
|
||||
--name "CONTRIBUTING" \
|
||||
--content "# 贡献指南\n\n感谢你对本项目的关注！以下是参与贡献的流程。\n\n## 如何贡献\n\n### 报告 Bug\n\n1. 搜索已有 Issue，确认没有被报告过\n2. 创建新 Issue，包含：复现步骤、预期行为、实际行为、环境信息\n\n### 提交代码\n\n1. Fork 本仓库\n2. 创建功能分支：\n\n\`\`\`bash\ngit checkout -b feature/my-feature\n\`\`\`\n\n3. 提交更改，遵循 [提交规范](/提交规范)\n4. 发起 Pull Request\n\n### 代码审查\n\n所有 PR 需要至少一位维护者 Review 通过后方可合并。\n\n## 行为准则\n\n请尊重所有贡献者，保持友善和建设性的交流。\n" \
|
||||
--message "创建贡献指南模板" \
|
||||
--dir "开发指南"
|
||||
```
|
||||
|
||||
#### Step 2：生成开发环境搭建文档
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +create \
|
||||
--name "开发环境搭建" \
|
||||
--content "# 开发环境搭建\n\n## 系统要求\n\n| 工具 | 最低版本 |\n|------|----------|\n| Go | 1.21+ |\n| Git | 2.30+ |\n\n## 快速开始\n\n\`\`\`bash\n# 克隆仓库\ngit clone <repo-url>\ncd <repo-name>\n\n# 安装依赖\ngo mod download\n\n# 构建\ngo build -o gitlink-cli .\n\n# 运行测试\ngo test ./...\n\`\`\`\n\n## IDE 推荐\n\n- VS Code + Go 扩展\n- GoLand\n\n## 常见问题\n\n参见 [[FAQ]]\n" \
|
||||
--message "创建开发环境搭建模板" \
|
||||
--dir "开发指南"
|
||||
```
|
||||
|
||||
#### Step 3：生成 API 文档模板
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +create \
|
||||
--name "API 文档模板" \
|
||||
--content "# API 文档模板\n\n## 接口名称\n\n简要描述接口用途。\n\n### 请求\n\n\`\`\`\nMETHOD /api/v1/endpoint\n\`\`\`\n\n**请求参数：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|:----:|------|\n| | | | |\n\n### 响应\n\n**成功响应（200）：**\n\n\`\`\`json\n{\n \"status\": 0,\n \"message\": \"success\",\n \"data\": {}\n}\n\`\`\`\n\n**错误响应：**\n\n| 状态码 | 说明 |\n|--------|------|\n| 400 | 参数错误 |\n| 401 | 未认证 |\n| 403 | 无权限 |\n| 404 | 资源不存在 |\n" \
|
||||
--message "创建 API 文档模板" \
|
||||
--dir "API参考"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 工作流 4：批量页面更新
|
||||
|
||||
**场景**：版本升级、全局术语变更或批量内容修正时，一次性更新多个 Wiki 页面。
|
||||
|
||||
#### Step 1：获取当前所有页面列表
|
||||
|
||||
```bash
|
||||
# 列出所有页面，确定需要更新的范围
|
||||
gitlink-cli wiki +list --format json
|
||||
```
|
||||
|
||||
#### Step 2：逐个读取并分析页面内容
|
||||
|
||||
```bash
|
||||
# 查看需要更新的页面
|
||||
gitlink-cli wiki +view --name "开发环境搭建"
|
||||
gitlink-cli wiki +view --name "部署指南"
|
||||
gitlink-cli wiki +view --name "REST API 概览"
|
||||
```
|
||||
|
||||
> Agent 应解析 `wiki +view` 的输出，提取 `content_base64` 字段，解码后分析需要修改的部分。
|
||||
|
||||
#### Step 3：批量更新页面
|
||||
|
||||
```bash
|
||||
# 更新版本号（示例：全局升级 v1.0 → v2.0）
|
||||
gitlink-cli wiki +update \
|
||||
--name "开发环境搭建" \
|
||||
--content "# 开发环境搭建\n\n## 系统要求\n\n| 工具 | 最低版本 |\n|------|----------|\n| Go | 1.22+ |\n| Git | 2.40+ |\n\n..." \
|
||||
--message "更新：升级系统要求版本"
|
||||
|
||||
gitlink-cli wiki +update \
|
||||
--name "部署指南" \
|
||||
--content "# 部署指南（v2.0）\n\n## 变更说明\n\nv2.0 新增以下部署要求：\n\n..." \
|
||||
--message "更新：同步 v2.0 部署变更"
|
||||
|
||||
gitlink-cli wiki +update \
|
||||
--name "REST API 概览" \
|
||||
--content "# REST API 概览\n\n## 基础 URL\n\n`https://api.example.com/v2`\n\n..." \
|
||||
--message "更新：API 基础 URL 升级至 v2"
|
||||
```
|
||||
|
||||
#### 批量更新注意事项
|
||||
|
||||
- 所有写入操作前**必须确认用户意图**，特别是涉及多个页面的批量更新
|
||||
- 建议先在单个页面上验证更新效果，确认无误后再批量执行
|
||||
- 每次更新提供清晰的 `--message`，便于后续追溯变更历史
|
||||
- 如果更新过程中某个页面失败，记录失败的页面名称和错误信息，继续处理剩余页面
|
||||
|
||||
---
|
||||
|
||||
## 侧边栏操作速查
|
||||
|
||||
| 操作 | 命令 | 侧边栏效果 |
|
||||
|------|------|-----------|
|
||||
| 创建顶级目录 | `wiki +mkdir --name "目录名"` | 添加 `- 目录名` |
|
||||
| 创建子目录 | `wiki +mkdir --name "子目录" --parent "父目录"` | 在父目录下缩进添加 `- 子目录` |
|
||||
| 删除目录 | `wiki +rmdir --name "目录名"` | 移除目录及所有子行 |
|
||||
| 重命名目录 | `wiki +renamedir --name "旧名" --new-name "新名"` | 替换目录标题 |
|
||||
| 创建页面到目录 | `wiki +create --name "页面" --content "..." --dir "目录"` | 在目录下添加 `[[页面]]` |
|
||||
| 删除页面 | `wiki +delete --name "页面"` | 自动移除 `[[页面]]` 链接 |
|
||||
| 重命名页面 | `wiki +rename --name "旧名" --new-name "新名"` | 自动替换 `[[旧名]]` 为 `[[新名]]` |
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- Wiki 操作通过独立的网关 API（`gateway.gitlink.org.cn/api`）执行，与仓库 API 不同
|
||||
- `wiki +create --dir` 要求目录已存在于侧边栏中，否则会报错；应先 `wiki +mkdir` 再 `wiki +create --dir`
|
||||
- `wiki +rename` 执行"获取内容 → 创建新页面 → 删除旧页面 → 更新侧边栏"的完整流程，操作不可逆
|
||||
- `wiki +rmdir` 会删除目录及该目录下所有子项（页面链接和子目录），操作不可逆
|
||||
- 侧边栏使用 Tab 缩进表示层级，手动编辑 `_Sidebar` 页面时请保持缩进一致
|
||||
- 建议在执行批量操作前先用 `wiki +list` 和 `wiki +view --name "_Sidebar"` 确认当前状态
|
||||
|
||||
---
|
||||
|
||||
## 相关 Skill 交叉引用
|
||||
|
||||
| Skill | 关联场景 |
|
||||
|-------|----------|
|
||||
| [`gitlink-shared`](../gitlink-shared/SKILL.md) | 认证、全局参数、安全规则基础 |
|
||||
| [`gitlink-code-review`](../gitlink-code-review/SKILL.md) | 审查 PR 时同步更新 Wiki 文档 |
|
||||
| [`gitlink-workflow`](../gitlink-workflow/SKILL.md) | 自动化工作流，可结合 Wiki 更新 |
|
||||
|
|
@ -0,0 +1,356 @@
|
|||
# Wiki 从零初始化工作流示例
|
||||
|
||||
本文档展示如何使用 `gitlink-wiki-builder` Skill 为新仓库 `whale_hihihi/test` 从零搭建完整的 Wiki 文档结构。
|
||||
|
||||
> **前置条件**：已完成 `gitlink-cli auth login` 认证。详见 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。
|
||||
|
||||
---
|
||||
|
||||
## Step 1：确认当前 Wiki 状态
|
||||
|
||||
初始化前先查看当前 Wiki 页面列表，确认是否为空或存在已有内容。
|
||||
|
||||
```bash
|
||||
# 列出所有 Wiki 页面
|
||||
gitlink-cli wiki +list --owner whale_hihihi --repo test --format json
|
||||
```
|
||||
|
||||
预期输出（空 Wiki）：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2：创建顶级目录结构
|
||||
|
||||
为项目创建四个核心文档分类目录。
|
||||
|
||||
```bash
|
||||
# 创建顶级目录
|
||||
gitlink-cli wiki +mkdir --name "开发指南" --owner whale_hihihi --repo test
|
||||
gitlink-cli wiki +mkdir --name "API参考" --owner whale_hihihi --repo test
|
||||
gitlink-cli wiki +mkdir --name "架构设计" --owner whale_hihihi --repo test
|
||||
gitlink-cli wiki +mkdir --name "常见问题" --owner whale_hihihi --repo test
|
||||
```
|
||||
|
||||
预期输出：
|
||||
|
||||
```
|
||||
Directory "开发指南" created.
|
||||
Directory "API参考" created.
|
||||
Directory "架构设计" created.
|
||||
Directory "常见问题" created.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3：在"开发指南"目录下创建页面
|
||||
|
||||
```bash
|
||||
# 创建开发环境搭建文档
|
||||
gitlink-cli wiki +create \
|
||||
--name "开发环境搭建" \
|
||||
--content "# 开发环境搭建
|
||||
|
||||
## 系统要求
|
||||
|
||||
| 工具 | 最低版本 |
|
||||
|------|----------|
|
||||
| Go | 1.21+ |
|
||||
| Git | 2.30+ |
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 克隆仓库：\`git clone https://gitlink.org.cn/whale_hihihi/test.git\`
|
||||
2. 安装依赖：\`go mod download\`
|
||||
3. 构建：\`go build -o test .\`
|
||||
4. 运行测试：\`go test ./...\`
|
||||
|
||||
## IDE 配置
|
||||
|
||||
推荐使用 VS Code + Go 扩展，安装后可获得代码补全、跳转定义和调试支持。" \
|
||||
--message "初始化：创建开发环境搭建文档" \
|
||||
--dir "开发指南" \
|
||||
--owner whale_hihihi --repo test
|
||||
|
||||
# 创建代码规范文档
|
||||
gitlink-cli wiki +create \
|
||||
--name "代码规范" \
|
||||
--content "# 代码规范
|
||||
|
||||
## 命名约定
|
||||
|
||||
- 包名：小写单词，不使用下划线（如 \`shortcuts\`）
|
||||
- 导出函数：大驼峰（如 \`CreateWiki\`）
|
||||
- 内部函数：小驼峰（如 \`fetchProjectID\`）
|
||||
- 常量：大写 + 下划线（如 \`MAX_RETRIES\`）
|
||||
|
||||
## 格式化
|
||||
|
||||
使用 \`gofmt\` 或 \`goimports\` 格式化代码，提交前确保通过 \`golangci-lint run\`。
|
||||
|
||||
## 注释规范
|
||||
|
||||
- 导出标识符必须有文档注释
|
||||
- 注释以标识符名称开头：\`// Shortcuts returns wiki management shortcuts.\`" \
|
||||
--message "初始化：创建代码规范文档" \
|
||||
--dir "开发指南" \
|
||||
--owner whale_hihihi --repo test
|
||||
|
||||
# 创建贡献指南
|
||||
gitlink-cli wiki +create \
|
||||
--name "CONTRIBUTING" \
|
||||
--content "# 贡献指南
|
||||
|
||||
感谢你对本项目的关注！
|
||||
|
||||
## 报告 Bug
|
||||
|
||||
1. 搜索已有 Issue，确认未被报告
|
||||
2. 创建新 Issue，包含：复现步骤、预期行为、实际行为、环境信息
|
||||
|
||||
## 提交代码
|
||||
|
||||
1. Fork 仓库
|
||||
2. 创建功能分支：\`git checkout -b feature/my-feature\`
|
||||
3. 提交更改，遵循 Commit Message 规范
|
||||
4. 发起 Pull Request
|
||||
|
||||
## 代码审查
|
||||
|
||||
所有 PR 需要至少一位维护者 Review 通过后方可合并。" \
|
||||
--message "初始化：创建贡献指南" \
|
||||
--dir "开发指南" \
|
||||
--owner whale_hihihi --repo test
|
||||
```
|
||||
|
||||
预期输出（每个页面）：
|
||||
|
||||
```
|
||||
Page "开发环境搭建" added to directory "开发指南" in sidebar.
|
||||
Page "代码规范" added to directory "开发指南" in sidebar.
|
||||
Page "CONTRIBUTING" added to directory "开发指南" in sidebar.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4：在"API参考"目录下创建页面
|
||||
|
||||
```bash
|
||||
# 创建 API 概览
|
||||
gitlink-cli wiki +create \
|
||||
--name "REST API 概览" \
|
||||
--content "# REST API 概览
|
||||
|
||||
## 基础 URL
|
||||
|
||||
\`https://api.example.com/v1\`
|
||||
|
||||
## 认证方式
|
||||
|
||||
所有 API 请求需在 Header 中携带 Token：
|
||||
|
||||
\`\`\`
|
||||
Authorization: Bearer <token>
|
||||
\`\`\`
|
||||
|
||||
## 通用响应格式
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
\"status\": 0,
|
||||
\"message\": \"success\",
|
||||
\"data\": {}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
## 速率限制
|
||||
|
||||
每个 Token 每分钟最多 60 次请求。" \
|
||||
--message "初始化：创建 API 概览文档" \
|
||||
--dir "API参考" \
|
||||
--owner whale_hihihi --repo test
|
||||
|
||||
# 创建错误码文档
|
||||
gitlink-cli wiki +create \
|
||||
--name "错误码说明" \
|
||||
--content "# 错误码说明
|
||||
|
||||
## HTTP 状态码
|
||||
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 成功 |
|
||||
| 400 | 参数错误 |
|
||||
| 401 | 未认证 |
|
||||
| 403 | 无权限 |
|
||||
| 404 | 资源不存在 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 业务错误码
|
||||
|
||||
| 错误码 | 说明 | 处理建议 |
|
||||
|--------|------|----------|
|
||||
| 10001 | Token 过期 | 重新获取 Token |
|
||||
| 10002 | 权限不足 | 联系管理员 |
|
||||
| 20001 | 资源已存在 | 检查是否重复创建 |" \
|
||||
--message "初始化：创建错误码文档" \
|
||||
--dir "API参考" \
|
||||
--owner whale_hihihi --repo test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5：在"架构设计"目录下创建页面和子目录
|
||||
|
||||
```bash
|
||||
# 创建架构总览
|
||||
gitlink-cli wiki +create \
|
||||
--name "系统架构总览" \
|
||||
--content "# 系统架构总览
|
||||
|
||||
## 整体架构
|
||||
|
||||
项目采用分层架构：
|
||||
|
||||
- **CLI 层**：命令行解析和用户交互（Cobra 框架）
|
||||
- **Shortcut 层**：高级命令封装（Issue、PR、Wiki 等）
|
||||
- **API 层**：GitLink REST API 客户端
|
||||
- **工具层**：输出格式化、国际化、配置管理
|
||||
|
||||
## 核心模块
|
||||
|
||||
| 模块 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| shortcuts | ./shortcuts/ | 高级命令封装 |
|
||||
| internal | ./internal/ | 内部工具库 |
|
||||
| cmd | ./cmd/ | CLI 入口 |" \
|
||||
--message "初始化：创建架构总览文档" \
|
||||
--dir "架构设计" \
|
||||
--owner whale_hihihi --repo test
|
||||
|
||||
# 创建子目录"数据库"并在其中创建页面
|
||||
gitlink-cli wiki +mkdir --name "数据库" --parent "架构设计" \
|
||||
--owner whale_hihihi --repo test
|
||||
|
||||
gitlink-cli wiki +create \
|
||||
--name "数据库设计" \
|
||||
--content "# 数据库设计
|
||||
|
||||
## 设计原则
|
||||
|
||||
- 所有表使用自增 ID 作为主键
|
||||
- 时间字段统一使用 \`datetime\` 类型
|
||||
- 软删除使用 \`is_deleted\` 标记
|
||||
|
||||
## 核心表
|
||||
|
||||
### users 表
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | int | 主键 |
|
||||
| user_name | varchar(50) | 用户名 |
|
||||
| email | varchar(100) | 邮箱 |
|
||||
| created_at | datetime | 创建时间 |" \
|
||||
--message "初始化：创建数据库设计文档" \
|
||||
--dir "数据库" \
|
||||
--owner whale_hihihi --repo test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6：在"常见问题"目录下创建页面
|
||||
|
||||
```bash
|
||||
gitlink-cli wiki +create \
|
||||
--name "FAQ" \
|
||||
--content "# 常见问题
|
||||
|
||||
## 安装相关
|
||||
|
||||
### Q: go build 失败怎么办？
|
||||
|
||||
确认 Go 版本 >= 1.21，然后执行：
|
||||
|
||||
\`\`\`bash
|
||||
go clean -cache
|
||||
go mod tidy
|
||||
go build -o test .
|
||||
\`\`\`
|
||||
|
||||
### Q: 认证失败怎么办？
|
||||
|
||||
1. 确认已执行 \`gitlink-cli auth login\`
|
||||
2. 检查 Token 是否过期
|
||||
3. 重新登录：\`gitlink-cli auth login --force\`
|
||||
|
||||
## 使用相关
|
||||
|
||||
### Q: Wiki 命令返回 404？
|
||||
|
||||
Wiki 功能需要在 GitLink 项目中先启用 Wiki 模块。在项目设置中开启后重试。
|
||||
|
||||
### Q: 如何查看 API 请求的详细信息？
|
||||
|
||||
使用 \`--verbose\` 参数查看请求和响应的详细信息：
|
||||
|
||||
\`\`\`bash
|
||||
gitlink-cli wiki +list --verbose
|
||||
\`\`\`" \
|
||||
--message "初始化：创建 FAQ 文档" \
|
||||
--dir "常见问题" \
|
||||
--owner whale_hihihi --repo test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7：验证最终结构
|
||||
|
||||
```bash
|
||||
# 查看侧边栏，确认目录和页面结构正确
|
||||
gitlink-cli wiki +view --name "_Sidebar" --owner whale_hihihi --repo test
|
||||
|
||||
# 列出所有页面
|
||||
gitlink-cli wiki +list --owner whale_hihihi --repo test --format json
|
||||
```
|
||||
|
||||
预期侧边栏结构：
|
||||
|
||||
```
|
||||
- 开发指南
|
||||
[[开发环境搭建]]
|
||||
[[代码规范]]
|
||||
[[CONTRIBUTING]]
|
||||
- API参考
|
||||
[[REST API 概览]]
|
||||
[[错误码说明]]
|
||||
- 架构设计
|
||||
[[系统架构总览]]
|
||||
- 数据库
|
||||
[[数据库设计]]
|
||||
- 常见问题
|
||||
[[FAQ]]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 执行汇总
|
||||
|
||||
| 操作 | 数量 | 命令 |
|
||||
|------|:----:|------|
|
||||
| 创建顶级目录 | 4 | `wiki +mkdir` |
|
||||
| 创建子目录 | 1 | `wiki +mkdir --parent` |
|
||||
| 创建 Wiki 页面 | 9 | `wiki +create --dir` |
|
||||
|
||||
总计执行 14 条 `gitlink-cli` 命令，完成从零到完整 Wiki 文档结构的搭建。
|
||||
|
||||
---
|
||||
|
||||
*由 gitlink-wiki-builder Skill 示例工作流生成*
|
||||
Loading…
Reference in New Issue