# 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 工具函数
- 所有脚本语法校验
