forked from Gitlink/gitlink-cli
528 lines
17 KiB
Markdown
528 lines
17 KiB
Markdown
# GitLink CLI 工作流自动化
|
||
|
||
5 个端到端自动化场景，将 gitlink-cli 的 shortcut 命令串联成完整工作流，解决实际项目管理痛点。
|
||
|
||
---
|
||
|
||
## 环境准备
|
||
|
||
### 1. 安装 gitlink-cli
|
||
|
||
```bash
|
||
# 确认已安装
|
||
gitlink-cli version
|
||
|
||
# 未安装则从项目根目录构建
|
||
cd /home/kevin/gitlink-cli
|
||
make build
|
||
```
|
||
|
||
### 2. 安装 jq
|
||
|
||
脚本用 `jq` 解析 CLI 返回的 JSON。
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt-get install -y jq
|
||
|
||
# macOS
|
||
brew install jq
|
||
```
|
||
|
||
### 3. 登录认证
|
||
|
||
```bash
|
||
# 方式一：交互式登录（推荐）
|
||
gitlink-cli auth login
|
||
|
||
# 方式二：环境变量
|
||
export GITLINK_TOKEN="你的私人令牌"
|
||
# 令牌获取：https://gitlink.org.cn → 个人设置 → 私人令牌
|
||
|
||
# 验证
|
||
gitlink-cli auth status
|
||
# 应显示：✓ Logged in as 用户名
|
||
```
|
||
|
||
### 4. 验证环境
|
||
|
||
```bash
|
||
# 测试 JSON 输出是否正常
|
||
gitlink-cli issue +list --owner zzx-coder --repo gitlink-cli --state open --limit 3 --format json | jq '.ok'
|
||
# 应输出：true
|
||
```
|
||
|
||
---
|
||
|
||
## 五个场景
|
||
|
||
| # | 场景 | 脚本 | 串联命令 | 解决什么问题 |
|
||
|---|------|------|---------|-------------|
|
||
| 1 | 社区运营自动化 | `01-community-ops.sh` | 7 个 | Issue 积压无人处理、周报手写、Release Notes 手动整理 |
|
||
| 2 | 代码质量看门人 | `02-code-quality-gatekeeper.sh` | 7 个 | PR 审查效率低、质量标准不统一、AI 代码审查（基于 gitlink-code-review skill） |
|
||
| 3 | 项目一键初始化 | `03-project-init.sh` | 8 个 | 新建项目重复劳动多、README/许可证/CI/Issue/里程碑手动配 |
|
||
| 4 | 多仓库协同 | `04-multi-repo-collab.sh` | 7 个 | 跨仓库状态分散、缺乏统一视图 |
|
||
| 5 | 贡献者成长体系 | `05-contributor-growth.sh` | 6 个 | 贡献者活跃度难追踪、缺乏激励机制 |
|
||
|
||
---
|
||
|
||
## 场景一：社区运营自动化
|
||
|
||
**脚本**: `01-community-ops.sh`
|
||
|
||
### 解决什么问题
|
||
|
||
新 Issue 没人分类、不知道谁该负责、社区周报手写、发版时才手忙脚乱写 Release Notes。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
issue +list → 读取所有 open Issue
|
||
↓
|
||
按关键词分类: Bug / Feature / Question / Docs
|
||
↓
|
||
issue +label-add → 自动打标签
|
||
↓
|
||
repo +members → 获取仓库成员列表
|
||
issue +update → 轮询分配负责人
|
||
↓
|
||
pr +list → 统计本周合并的 PR
|
||
issue +list → 统计本周关闭的 Issue
|
||
↓
|
||
wiki +create → 发布社区周报到 Wiki
|
||
↓
|
||
release +create → 自动生成 Release Notes
|
||
```
|
||
|
||
### 串联的命令
|
||
|
||
| 步骤 | 命令 | 作用 |
|
||
|------|------|------|
|
||
| 1 | `issue +list` | 获取所有 open Issue |
|
||
| 2 | `issue +label-add` | 按分类打标签 (bug/feature/question/documentation) |
|
||
| 3 | `repo +members` | 获取仓库成员列表 |
|
||
| 4 | `issue +update` | 给 Bug/Feature Issue 分配负责人 |
|
||
| 5 | `pr +list` | 统计本周合并的 PR |
|
||
| 6 | `wiki +create` | 发布社区周报 |
|
||
| 7 | `release +create` | 自动生成 Release Notes |
|
||
|
||
### 输出有什么用
|
||
|
||
- **标签分类**: 仓库 Issue 页面可按标签筛选，一目了然
|
||
- **负责人分配**: 每个 Issue 有明确负责人，避免互相推诿
|
||
- **Wiki 周报**: 团队和社区用户可在 Wiki 查看每周进展
|
||
- **Release Notes**: 发版时无需手动整理变更
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
bash workflows/01-community-ops.sh --owner 你的组织 --repo 你的仓库
|
||
|
||
# 示例
|
||
bash workflows/01-community-ops.sh --owner zzx-coder --repo gitlink-cli
|
||
```
|
||
|
||
---
|
||
|
||
## 场景二：代码质量看门人
|
||
|
||
**脚本**: `02-code-quality-gatekeeper.sh`
|
||
|
||
### 解决什么问题
|
||
|
||
PR 审查是代码质量的核心环节，但人工审查耗时且标准不统一。这个工作流加载 **gitlink-code-review skill** 的审查方法论，用 AI (Claude) 对 PR 进行四维度代码审查，自动打分评级，达标后自动合并。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
pr +list → 获取所有 open PR
|
||
↓
|
||
pr +view → 读取 PR 详情
|
||
pr +files → 获取变更文件列表
|
||
pr +diff → 获取代码差异
|
||
↓
|
||
加载 gitlink-code-review skill:
|
||
- 审查维度与检查项
|
||
- 评分标准 (90-100 优秀, 75-89 良好, ...)
|
||
- 问题严重级别 (CRITICAL/HIGH/MEDIUM/LOW)
|
||
↓
|
||
┌─────────────────────────────────────┐
|
||
│ AI 代码审查 (Claude + Skill) │
|
||
│ 四维度评分 (各 0-25，总分 100): │
|
||
│ - 代码质量: 复杂度、命名、注释 │
|
||
│ - 安全性: SQL注入、XSS、敏感信息 │
|
||
│ - 性能: 循环效率、资源泄漏、N+1 │
|
||
│ - 可维护性: 重复、职责单一、耦合 │
|
||
│ │
|
||
│ 输出: │
|
||
│ - 结构化问题清单 (severity+file+ │
|
||
│ rule+description+suggestion) │
|
||
│ - 优秀实践 (positive_notes) │
|
||
│ - 改进建议 (recommendations) │
|
||
│ - 总分 + PASS/FAIL │
|
||
└─────────────────────────────────────┘
|
||
↓
|
||
api POST /reviews → 发布审查评论到 PR
|
||
↓
|
||
ci +builds → 检查 CI 构建状态
|
||
↓
|
||
pr +merge → 分数 >= 阈值 且 CI 通过 → 自动合并
|
||
```
|
||
|
||
### AI 审查示例输出（基于 gitlink-code-review skill）
|
||
|
||
```
|
||
Overall Score: 88 / 100
|
||
Code Quality: 23 / 25
|
||
Security: 25 / 25
|
||
Performance: 20 / 25
|
||
Maintainability: 20 / 25
|
||
|
||
Issues Found:
|
||
- [LOW] quality: 条目格式说明中 PR 条目用 (@作者) 带括号，commit 条目用 (作者名) 不带 @ 前缀
|
||
→ 统一格式规范，建议 commit 条目也使用 (@作者) 格式
|
||
- [LOW] maintainability: 示例中贡献者列表变更但完整变更日志链接仍指向旧仓库
|
||
→ 将变更日志链接中的 OWNER 也更新为与示例贡献者一致
|
||
|
||
Positive Notes:
|
||
+ 变更目的清晰，所有文件的修改一致地贯彻了需求，无遗漏
|
||
+ 变更范围合理，仅修改文档和示例，不涉及代码逻辑变更，风险极低
|
||
|
||
Recommendations:
|
||
> 统一 PR 条目和 commit 条目的作者标注格式
|
||
> 在 collect-data.md 中补充 author 字段为空时的降级处理说明
|
||
```
|
||
|
||
### 串联的命令
|
||
|
||
| 步骤 | 命令 | 作用 |
|
||
|------|------|------|
|
||
| 1 | `pr +list` | 获取 open PR 列表 |
|
||
| 2 | `pr +view` | 读取 PR 详情（标题、作者、状态） |
|
||
| 3 | `pr +files` | 获取变更文件列表 |
|
||
| 4 | `pr +diff` | 获取代码差异内容 |
|
||
| 5 | `gitlink-code-review` | 加载 skill 的审查维度、检查项、评分标准 |
|
||
| 6 | `claude -p` | AI 按 skill 方法论进行四维度代码审查 |
|
||
| 7 | `api POST .../reviews` | 将审查评论发布到 PR |
|
||
| 8 | `pr +merge` | 质量分 >= 阈值且 CI 通过时自动合并 |
|
||
|
||
### 输出有什么用
|
||
|
||
- **结构化评分**: 每个 PR 有 0-100 的质量评分，团队可设定统一合并门槛
|
||
- **AI 问题清单**: 自动列出安全隐患、性能问题、代码质量问题，人工审查时重点关注
|
||
- **PR 评论**: 审查结果直接评论在 PR 上，作者和审查者都能看到
|
||
- **自动合并**: 高质量 PR 无需人工点击
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
# 审查所有 open PR
|
||
bash workflows/02-code-quality-gatekeeper.sh --owner 你的组织 --repo 你的仓库
|
||
|
||
# 审查指定 PR
|
||
bash workflows/02-code-quality-gatekeeper.sh --owner 你的组织 --repo 你的仓库 --pr-id 42
|
||
|
||
# 自定义质量阈值（默认 80）
|
||
bash workflows/02-code-quality-gatekeeper.sh --owner 你的组织 --repo 你的仓库 --threshold 70
|
||
|
||
# 预览模式（不实际合并）
|
||
bash workflows/02-code-quality-gatekeeper.sh --owner 你的组织 --repo 你的仓库 --dry-run
|
||
|
||
# 示例
|
||
bash workflows/02-code-quality-gatekeeper.sh --owner zzx-coder --repo gitlink-cli --pr-id 20
|
||
```
|
||
|
||
---
|
||
|
||
## 场景三：项目一键初始化
|
||
|
||
**脚本**: `03-project-init.sh` / `03-project-init.ps1`
|
||
|
||
### 解决什么问题
|
||
|
||
新建项目仓库后，还要手动创建 README、写 LICENSE、配置 CI/CD、创建 Issue 和里程碑、设置分支保护、打初始 Release。一条命令搞定全部。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
repo +create → 创建仓库
|
||
↓
|
||
git clone → 克隆空仓库到本地
|
||
↓
|
||
生成文件 → README.md (语言模板) + LICENSE (MIT) + CONTRIBUTING.md + .gitlink-ci.yml
|
||
↓
|
||
git add/commit/push → 将脚手架文件推送到仓库
|
||
↓
|
||
milestone +create × 3 → 创建项目里程碑:
|
||
- v0.1.0 - MVP
|
||
- v0.2.0 - Feature Complete
|
||
- v1.0.0 - Production Ready
|
||
↓
|
||
issue +create × 5 → 创建初始待办 Issue (打标签):
|
||
- 搭建 CI/CD 流水线
|
||
- 编写项目文档
|
||
- 建立代码审查流程
|
||
- 添加单元测试
|
||
- 配置依赖管理
|
||
↓
|
||
branch +protect → 保护 master 分支
|
||
↓
|
||
release +create → 创建 v0.1.0 初始版本
|
||
```
|
||
|
||
### 串联的命令
|
||
|
||
| 步骤 | 命令 | 作用 |
|
||
|------|------|------|
|
||
| 1 | `repo +create` | 创建新仓库 |
|
||
| 2 | `git clone` | 克隆空仓库到本地临时目录 |
|
||
| 3 | 文件生成 | 生成 README.md / LICENSE / CONTRIBUTING.md / .gitlink-ci.yml |
|
||
| 4 | `git add/commit/push` | 推送脚手架文件到 master 分支 |
|
||
| 5 | `milestone +create` | 创建 3 个项目里程碑 (MVP → Production) |
|
||
| 6 | `issue +create` | 创建 5 个初始 Issue 并打标签 |
|
||
| 7 | `branch +protect` | 设置 master 分支保护规则 |
|
||
| 8 | `release +create` | 创建 v0.1.0 初始版本 |
|
||
|
||
### 输出有什么用
|
||
|
||
- **开箱即用**: 克隆后仓库已有 README、LICENSE、CI 配置，可直接开始开发
|
||
- **仓库内文件**: README/LICENSE/CONTRIBUTING/CI 是仓库里的真实文件，不是 Wiki 页面
|
||
- **里程碑规划**: 从 MVP 到正式版的路线图已建立
|
||
- **标准化 Issue**: 关键待办已创建好，团队可直接认领
|
||
- **分支保护**: 防止直接 push 到 master，强制走 PR 流程
|
||
- **首个 Release**: 项目从创建之初就有版本管理
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
# Go 项目
|
||
bash workflows/03-project-init.sh --owner 你的组织 --name my-go-app --description "我的Go应用" --lang go
|
||
|
||
# Python 项目（私有）
|
||
bash workflows/03-project-init.sh --owner 你的组织 --name my-api --description "REST API服务" --lang python --private
|
||
|
||
# Node.js 项目
|
||
bash workflows/03-project-init.sh --owner 你的组织 --name my-web --description "Web前端" --lang node
|
||
|
||
# Java 项目
|
||
bash workflows/03-project-init.sh --owner 你的组织 --name my-service --description "微服务" --lang java
|
||
```
|
||
|
||
---
|
||
|
||
## 场景四：多仓库协同
|
||
|
||
**脚本**: `04-multi-repo-collab.sh`
|
||
|
||
### 解决什么问题
|
||
|
||
当一个组织有多个仓库时，管理者需要逐个查看每个仓库的 Issue、PR、Release 状态。这个工作流汇总所有仓库数据，生成一个 HTML 仪表盘，并支持一键协调发版。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
repo +list → 列出组织下所有仓库
|
||
↓
|
||
对每个仓库:
|
||
issue +list → 获取 open/closed Issue
|
||
pr +list → 获取 open/merged PR
|
||
release +list → 获取最新 Release
|
||
↓
|
||
生成 HTML 仪表盘:
|
||
- 总览卡片: 仓库数、Open Issue、Open PR、总活动量
|
||
- 详情表格: 每个仓库的 Issue/PR/Release 状态
|
||
- 健康度: Healthy / Moderate / Needs Attention
|
||
↓
|
||
（可选）release +create → 一键为所有仓库创建同一版本号的 Release
|
||
```
|
||
|
||
### 串联的命令
|
||
|
||
| 步骤 | 命令 | 作用 |
|
||
|------|------|------|
|
||
| 1 | `repo +list` | 列出组织下所有仓库 |
|
||
| 2 | `issue +list` | 获取每个仓库的 Issue 数据 |
|
||
| 3 | `pr +list` | 获取每个仓库的 PR 数据 |
|
||
| 4 | `release +list` | 获取每个仓库的最新 Release |
|
||
| 5 | 生成 HTML | 输出可视化仪表盘 |
|
||
| 6 | `release +create` | （可选）协调发版 |
|
||
|
||
### 输出有什么用
|
||
|
||
- **统一视图**: 一个 HTML 页面看到组织所有仓库的健康状态
|
||
- **健康度预警**: Open Issue 超 10 个标橙色，超 20 个标红色
|
||
- **协调发版**: 多个关联仓库需要同步发版时，一条命令搞定
|
||
- **可分享**: HTML 文件可直接发给团队或部署到内部网站
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
# 扫描组织下所有仓库
|
||
bash workflows/04-multi-repo-collab.sh --org 你的组织
|
||
|
||
# 只看指定仓库
|
||
bash workflows/04-multi-repo-collab.sh --org 你的组织 --repos "repo-a,repo-b,repo-c"
|
||
|
||
# 生成仪表盘 + 协调发版
|
||
bash workflows/04-multi-repo-collab.sh --org 你的组织 --release v2.0.0
|
||
|
||
# 自定义输出文件
|
||
bash workflows/04-multi-repo-collab.sh --org 你的组织 --output my-dashboard.html
|
||
|
||
# 示例
|
||
bash workflows/04-multi-repo-collab.sh --org zzx-coder
|
||
```
|
||
|
||
运行后在当前目录生成 `dashboard.html`，浏览器打开即可查看。
|
||
|
||
---
|
||
|
||
## 场景五：贡献者成长体系
|
||
|
||
**脚本**: `05-contributor-growth.sh`
|
||
|
||
### 解决什么问题
|
||
|
||
开源项目需要激励贡献者持续参与，但很难量化每个人的贡献。这个工作流自动追踪贡献者活动，计算贡献分数，生成排行榜，并可选自动颁发成就徽章。
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
contrib +report → 生成带 ECharts 饼图的 HTML 贡献报告
|
||
↓
|
||
issue +list → 统计 Issue 活动
|
||
pr +list → 统计 PR 活动
|
||
api GET /contributors → 获取提交数等 API 统计
|
||
↓
|
||
计算贡献分数 (AHP 权重模型):
|
||
- PR 被合并: 10 分
|
||
- 提交 PR: 5 分
|
||
- 创建/解决 Issue: 3 分
|
||
- 代码提交: 2 分
|
||
↓
|
||
评定等级:
|
||
Champion (冠军) >= 50 分
|
||
Core Contributor >= 30 分
|
||
Active Contributor >= 15 分
|
||
Contributor >= 5 分
|
||
Newcomer (新人) < 5 分
|
||
↓
|
||
（可选）issue +create → 自动创建徽章颁发 Issue
|
||
↓
|
||
wiki +create → 发布排行榜到 Wiki
|
||
```
|
||
|
||
### 串联的命令
|
||
|
||
| 步骤 | 命令 | 作用 |
|
||
|------|------|------|
|
||
| 1 | `contrib +report` | 生成 HTML 贡献报告（带 ECharts 图表） |
|
||
| 2 | `issue +list` | 统计 open/closed Issue 活动 |
|
||
| 3 | `pr +list` | 统计 open/merged PR 活动 |
|
||
| 4 | `api GET /contributors` | 获取 API 级别的贡献者统计 |
|
||
| 5 | `issue +create` | （可选）自动颁发成就徽章 |
|
||
| 6 | `wiki +create` | 发布排行榜到 Wiki |
|
||
|
||
### 输出有什么用
|
||
|
||
- **HTML 贡献报告**: 可视化展示贡献分布，适合团队会议演示
|
||
- **贡献排行榜**: 量化每个人的贡献，公开透明
|
||
- **Wiki 排行榜**: 永久保存，贡献者可随时查看排名
|
||
- **徽章激励**: 通过 Issue 颁发徽章，增强成就感和归属感
|
||
|
||
### 运行
|
||
|
||
```bash
|
||
# 基本运行
|
||
bash workflows/05-contributor-growth.sh --owner 你的组织 --repo 你的仓库
|
||
|
||
# 自定义统计周期（默认 30 天）
|
||
bash workflows/05-contributor-growth.sh --owner 你的组织 --repo 你的仓库 --period 90
|
||
|
||
# 启用自动颁发徽章
|
||
bash workflows/05-contributor-growth.sh --owner 你的组织 --repo 你的仓库 --award
|
||
|
||
# 示例
|
||
bash workflows/05-contributor-growth.sh --owner zzx-coder --repo gitlink-cli --award
|
||
```
|
||
|
||
---
|
||
|
||
## 通用参数
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `--owner OWNER` | 仓库所属组织或用户（在 git 仓库内可自动检测） |
|
||
| `--repo REPO` | 仓库名称（在 git 仓库内可自动检测） |
|
||
| `--dry-run` | 预览模式，不实际执行写操作 |
|
||
| `--help` | 显示帮助信息 |
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
workflows/
|
||
├── lib/
|
||
│ └── common.sh # 共享工具库（认证、JSON解析、CLI封装、日志）
|
||
├── 01-community-ops.sh # 场景一：社区运营自动化
|
||
├── 02-code-quality-gatekeeper.sh # 场景二：代码质量看门人（AI审查）
|
||
├── 03-project-init.sh # 场景三：项目一键初始化
|
||
├── 04-multi-repo-collab.sh # 场景四：多仓库协同
|
||
├── 05-contributor-growth.sh # 场景五：贡献者成长体系
|
||
├── test.sh # 测试套件
|
||
└── README.md # 本文档
|
||
```
|
||
|
||
### 共享库 `lib/common.sh`
|
||
|
||
所有脚本共享的基础设施：
|
||
|
||
| 函数 | 作用 |
|
||
|------|------|
|
||
| `check_auth` | 检查认证状态（环境变量 或 CLI 登录） |
|
||
| `gl_run` | CLI 封装，自动追加 `--format json` |
|
||
| `gl_check` | CLI 封装 + JSON 格式校验 + ok 字段检查 |
|
||
| `json_ok` / `json_get` / `json_error` | JSON 解析工具 |
|
||
| `detect_owner_repo` | 从 git remote 自动检测 owner/repo |
|
||
| `log_step` / `log_ok` / `log_warn` / `log_err` | 彩色日志输出 |
|
||
|
||
---
|
||
|
||
## 涉及的 Skill
|
||
|
||
工作流通过加载 Skill 的审查方法论、分类规则和模板来指导 AI 分析：
|
||
|
||
| Skill | 被哪个场景使用 | 作用 |
|
||
|-------|-------------|------|
|
||
| `gitlink-code-review` | 场景 2 | **已集成** — 加载审查维度、检查项、评分标准，指导 AI 代码审查 |
|
||
| `gitlink-issue-triage` | 场景 1 | Issue 分类规则（关键词匹配、优先级判定） |
|
||
| `gitlink-changelog` | 场景 1 | Release Notes 生成模板（按类型分组、贡献者列表） |
|
||
| `gitlink-health` | 场景 4 | 项目健康度评分体系（100 分制） |
|
||
| `gitlink-onboard` | 场景 5 | 新人引导和 Issue 推荐规则 |
|
||
| `gitlink-workflow` | 全部 | 基础工作流编排（Issue 分类、PR 审查、发版、Sprint 报告） |
|
||
|
||
> 场景 2 的 `gitlink-code-review` skill 已完整集成：脚本运行时自动从 `skills/gitlink-code-review/SKILL.md` 加载审查维度和检查项，传给 AI 作为审查方法论。其他场景使用关键词匹配等规则引擎。
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行测试套件（使用真实 GitLink 仓库验证）
|
||
bash workflows/test.sh
|
||
|
||
# 指定仓库
|
||
bash workflows/test.sh zzx-coder gitlink-cli
|
||
```
|
||
|
||
测试覆盖：
|
||
- 认证状态检查
|
||
- CLI JSON 输出格式验证
|
||
- 数据字段提取（issue/PR/repo/release/member/contributor）
|
||
- PR 文件和 Diff 内容解析
|
||
- Issue/PR View 接口
|
||
- Wiki / Label 列表接口
|
||
- common.sh 工具函数
|
||
- 所有脚本语法校验
|