# gitlink-cli

[![GitLink](https://img.shields.io/badge/GitLink-Gitlink%2Fgitlink--cli-green)](https://www.gitlink.org.cn/Gitlink/gitlink-cli)
[![License](https://img.shields.io/badge/License-MulanPSL--2.0-blue.svg)](https://license.coscl.org.cn/MulanPSL2)
[![Go Version](https://img.shields.io/badge/Go-1.26%2B-blue.svg)](https://golang.org)
[![npm version](https://img.shields.io/npm/v/@gitlink-ai/cli.svg)](https://www.npmjs.com/package/@gitlink-ai/cli)

GitLink 官方命令行工具，面向开发者与 AI Agent 设计。支持 **macOS、Linux、Windows**，覆盖仓库管理、Issue 追踪、Pull Request、CI/CD 与 AI 自动化工作流，提供 **40+ 命令**与 **20+ AI Agent Skills**。

**[English](./README.md)**

---

## 项目概述

本项目围绕 GitLink 开源协作平台的自动化能力建设，涵盖三个子任务方向。

### 子任务一：增加和完善 GitLink-CLI 能力（50%）

> 定位：扩展 CLI 功能 | 难度：中高 | 技术栈：Go

构建健壮、跨平台、AI 友好的命令行工具，覆盖 GitLink 平台全功能。

**核心架构 — 三层设计：**

```
Shortcuts（40+ 命令）
  → 面向人类和 AI Agent 的简洁命令
  → issue +create, pr +list, wiki +create ...
      ↓
Raw API（全接口覆盖）
  → 直接调用 GitLink OpenAPI
  → api GET /users/me, api POST /.../issues ...
      ↓
Config & Auth（配置管理层）
  → 认证、上下文解析、输出格式
  → auth login, config init, --format json
```

**CLI 能力一览：**

| 类别 | 能力 |
|------|------|
| 📦 仓库 | 列表、创建、Fork、删除、查看详情 |
| 🐛 Issue | 创建、更新、关闭、评论，6 种批量操作（关闭/状态/优先级/指派人/标签/创建） |
| 📖 Wiki | 查看、创建、更新、删除 Wiki 页面 |
| 🔀 PR | 创建、合并、Review、查看变更文件 |
| 🌿 分支 | 创建、删除、列表、保护、解除保护 |
| 🏷️ Release | 创建、查看、删除版本发布 |
| 🔗 Webhook | 创建、查看、更新、删除、测试 Webhook |
| 🏢 组织 | 管理组织、成员、团队 |
| 🔧 CI | 查看构建、日志、CI/CD 操作 |
| 🔍 搜索 | 搜索仓库、用户 |
| 👤 用户 | 查看用户资料 |
| 📋 项目管理 | Sprint 管理、看板、周报 |
| 🔌 Raw API | 直接调用任意 GitLink OpenAPI 端点 |

**技术亮点：**

- **Agent-Native 设计** — 每个命令经过真实 Agent 测试，参数精简、默认值智能、输出结构化
- **跨平台** — macOS / Linux / Windows (x64/arm64)，一键安装
- **安全可控** — OS 原生密钥链存储、`GITLINK_TOKEN` 环境变量支持 CI/CD
- **智能上下文解析** — 自动从 `git remote origin` 解析 owner/repo，减少参数输入
- **开箱即用** — MulanPSL-2.0 开源，`npm install -g @gitlink-ai/cli` 一条命令

### 子任务二：编写和丰富 GitLink Skills（20%）

> 定位：开发 Agent Skill | 难度：中 | 无需 Go，Markdown + CLI 调用即可

Skills 是为 Claude Code 及其他 AI Agent 设计的结构化知识库。每个 Skill 包含 `SKILL.md`（命令参考）、`REFERENCE.md`（API 参考）、`TROUBLESHOOTING.md`（故障排查）和 `examples/`（完整工作流示例）。AI Agent 通过读取 Skills 即可自动操作 GitLink 平台，无需手动查阅文档。

**Skills 目录结构：**

```
skills/
├── gitlink-shared/           # 认证、全局参数、安全规则、分支约定
├── gitlink-repo/             # 仓库管理
├── gitlink-issue/            # Issue 管理
├── gitlink-pr/               # Pull Request
├── gitlink-branch/           # 分支管理
├── gitlink-release/          # 版本发布
├── gitlink-wiki/             # Wiki 管理
├── gitlink-webhook/          # Webhook 管理
├── gitlink-org/              # 组织管理
├── gitlink-user/             # 用户管理
├── gitlink-ci/               # CI/CD
├── gitlink-search/           # 搜索功能
├── gitlink-pm/               # 项目管理（Sprint / 看板 / 周报）
├── gitlink-team/             # 团队管理
├── gitlink-changelog/        # Release Notes / Changelog 生成
├── gitlink-health/           # 项目健康度报告（Issue 响应时间、PR 合并效率、贡献者活跃度）
├── gitlink-contrib/          # 贡献报告（统计与排名）
├── gitlink-compliance/       # 安全与合规（许可证扫描、敏感信息检测、PII 扫描）
├── gitlink-issue-triage/     # Issue 自动分类（tracker/priority/labels 判定）
├── gitlink-onboard/          # 新人引导（Good First Issue 识别与欢迎评论）
├── gitlink-workflow/         # AI 工作流编排（Issue 分类、PR Review、Release Notes）
├── gitlink-code-review/      # 智能代码审查（四维度评分、结构化 Review 意见）
├── gitlink-research/         # 科研辅助（项目洞察、热点追踪、合规复现、协作匹配、论文引用）
└── gitlink-code-insight/     # 功能全景索引（全部 Shortcuts 分类展示）
```

**所有 Skills 概览：**

| Skill | 说明 | 典型命令 |
|-------|------|----------|
| **gitlink-shared** | 认证、全局参数、API 参考、安全规则 | `auth login`, `auth status` |
| **gitlink-repo** | 仓库管理 | `repo +list`, `repo +create`, `repo +info`, `repo +fork` |
| **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +view`, `issue +close`, `issue +batch-close` |
| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +review` |
| **gitlink-branch** | 分支管理 | `branch +list`, `branch +create`, `branch +delete`, `branch +protect` |
| **gitlink-release** | 版本发布 | `release +list`, `release +create`, `release +view` |
| **gitlink-wiki** | Wiki 管理 | `wiki +list`, `wiki +view`, `wiki +create`, `wiki +update`, `wiki +delete` |
| **gitlink-webhook** | Webhook 管理 | `webhook +list`, `webhook +create`, `webhook +test` |
| **gitlink-org** | 组织管理 | `org +list`, `org +info`, `org +members` |
| **gitlink-user** | 用户管理 | `user +me`, `user +info` |
| **gitlink-ci** | CI/CD | `ci +builds`, `ci +logs` |
| **gitlink-search** | 搜索功能 | `search +repos`, `search +users` |
| **gitlink-pm** | 项目管理 | Sprint 管理、看板、周报（通过 Raw API） |
| **gitlink-team** | 团队管理 | `team +list`, `team +create`, `team +add-member` |
| **gitlink-changelog** | Release Notes 生成 | 自动收集 commits/PR/Issue，生成结构化版本说明 |
| **gitlink-health** | 项目健康度报告 | Issue 响应时间、PR 合并效率、贡献者活跃度统计 |
| **gitlink-contrib** | 贡献报告 | `contrib +report` |
| **gitlink-compliance** | 安全与合规 | `compliance +scan`, `compliance +secrets`, `compliance +license` |
| **gitlink-issue-triage** | Issue 自动分类 | 自动判定 tracker/priority/labels，生成审计报告 |
| **gitlink-onboard** | 新人引导 | `onboard +welcome` |
| **gitlink-workflow** | AI 工作流编排 | Issue 分类、PR Review、仓库初始化、Sprint 报告 |
| **gitlink-code-review** | 智能代码审查 | 四维度评分（代码质量/安全性/性能/可维护性）、自动发布 Review 评论 |
| **gitlink-research** | 科研辅助 | 项目洞察、热点追踪、合规复现、协作匹配、进度预警、论文引用 |
| **gitlink-code-insight** | 功能全景索引 | 全部 Shortcuts 分类索引，含说明和示例 |

**AI Agent 如何使用 Skills：**

```
用户: "帮我在 GitLink 上创建一个 Issue"
    ↓
AI Agent 读取 gitlink-issue/SKILL.md
    ↓
AI Agent 执行: gitlink-cli issue +create -t "..." -b "..."
    ↓
完成！
```

AI Agent 可以自动完成：创建/管理 Issue、创建/合并 PR、发布 Release、管理 Wiki、分类 Issue、生成 Release Notes、执行代码审查等。

### 子任务三：构建端到端自动化工作流（20%）

> 定位：组合现有能力解决实际问题 | 难度：低-中 | 无需写底层代码

组合 gitlink-cli 命令与 Skills，串联多个步骤形成完整的可复现自动化场景。工作流通过 Shell/PowerShell 脚本编排，支持 AI Agent 驱动执行。

---

**五大自动化工作流总览：**

| # | 场景 | 脚本 | 串联命令数 | 解决什么问题 |
|---|------|------|-----------|-------------|
| 1 | 社区运营自动化 | `01-community-ops.sh` | 7 | Issue 积压无人处理、周报手写、Release Notes 手动整理 |
| 2 | 代码质量看门人 | `02-code-quality-gatekeeper.sh` | 7 | PR 审查效率低、质量标准不统一、AI 代码审查 |
| 3 | 项目一键初始化 | `03-project-init.sh` | 8 | 新建项目重复劳动多、README/License/CI/Issue/里程碑手动配 |
| 4 | 多仓库协同 | `04-multi-repo-collab.sh` | 7 | 跨仓库状态分散、缺乏统一视图 |
| 5 | 贡献者成长体系 | `05-contributor-growth.sh` | 6 | 贡献者活跃度难追踪、缺乏激励机制 |

---

### 场景一：社区运营自动化

**脚本**：`workflows/01-community-ops.sh`

**工作流程**：

```
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
```

---

### 场景二：代码质量看门人

**脚本**：`workflows/02-code-quality-gatekeeper.sh`

**工作流程**：

```
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 审查示例输出**：

```
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
```

---

### 场景三：项目一键初始化

**脚本**：`workflows/03-project-init.sh` / `03-project-init.ps1`

**工作流程**：

```
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
```

---

### 场景四：多仓库协同

**脚本**：`workflows/04-multi-repo-collab.sh` / `04-multi-repo-collab.ps1`

**工作流程**：

```
repo +list → 列出组织下所有仓库
    ↓
对每个仓库：
  issue +list → 获取 open/closed Issue
  pr +list → 获取 open/merged PR
  release +list → 获取最新 Release
    ↓
计算健康度评分（对齐 gitlink-health Skill · 100 分扣分制）：
  核心指标（75 分）：Issue 解决率 < 50% 扣 25、PR 合并率 < 50% 扣 25、近期无活动扣 25
  辅助指标（25 分）：Open Issue > 20 扣 10、Open PR > 10 扣 10、超 30 天无 Release 扣 5
  五级评定：优秀（≥90）→ 良好（≥70）→ 一般（≥50）→ 需关注（≥30）→ 严重（<30）
    ↓
生成 HTML 仪表盘：
  - 总览卡片：仓库数、Open Issue 数、Open PR 数、总活动量
  - 详情表格：每个仓库的 Issue/PR/Release 状态 + 折叠明细
  - 健康度色带：绿色优秀 / 蓝色良好 / 黄色一般 / 橙色需关注 / 红色严重
    ↓
（可选）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 --detail-limit 10

# 预览模式
bash workflows/04-multi-repo-collab.sh --org 你的组织 --dry-run

# 示例
bash workflows/04-multi-repo-collab.sh --org zzx-coder
```

运行后在当前目录生成 `dashboard.html`，浏览器打开即可查看。

---

### 场景五：贡献者成长体系

**脚本**：`workflows/05-contributor-growth.sh`

**工作流程**：

```
contrib +report → 生成带 ECharts 饼图的 HTML 贡献报告
    ↓
issue +list → 统计 Issue 活动
pr +list → 统计 PR 活动
api GET /contributors → 获取提交数等 API 统计
    ↓
计算贡献分数（AHP 权重模型）：
  - 代码变更量：30%（归一化处理）
  - PR 被合并：25%（归一化处理）
  - 创建/解决 Issue：15%（归一化处理）
  - Issue 评论：15%（归一化处理）
  - 团队成员：15%（是/否 二分）
  → 加权求和得 0-100 综合分
    ↓
评定等级：
  Champion（冠军）          >= 80 分
  Core Contributor（核心）   >= 60 分
  Active Contributor（活跃） >= 40 分
  Contributor（贡献者）      >= 20 分
  Newcomer（新人）           < 20 分
    ↓
（可选）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
```

---

### 环境准备

**1. 安装 gitlink-cli**

```bash
gitlink-cli version
# 未安装则从项目根目录构建
cd 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="你的私人令牌"                  # 或环境变量
gitlink-cli auth status                              # 验证：应显示 ✓ Logged in
```

**4. 验证环境**

```bash
gitlink-cli issue +list --owner zzx-coder --repo gitlink-cli --state open --limit 3 --format json | jq '.ok'
# 应输出：true
```

---

### 共享库 `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` | 彩色日志输出 |

---

### 工作流通用参数

| 参数 | 说明 |
|------|------|
| `--owner` | 仓库所有者（自动从 git remote 解析） |
| `--repo` | 仓库名称（自动从 git remote 解析） |
| `--org` | 组织名称（多仓库协同时需要） |
| `--dry-run` | 预览模式，不实际执行写操作 |
| `--help` | 显示帮助信息 |

---

### 涉及的 Skill

| Skill | 被使用的场景 | 作用 |
|-------|-------------|------|
| `gitlink-code-review` | 场景 2 | 审查维度、检查项、评分标准 |
| `gitlink-issue-triage` | 场景 1 | Issue 分类规则（关键词匹配、优先级判定） |
| `gitlink-changelog` | 场景 1 | Release Notes 生成模板 |
| `gitlink-health` | 场景 4 | 项目健康度评分体系（100 分扣分制） |
| `gitlink-onboard` | 场景 5 | 新人引导和 Issue 推荐规则 |
| `gitlink-workflow` | 全部 | 基础工作流编排 |

---

### 测试

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

---

### 项目结构（workflows/）

```
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                      # 工作流详细文档
```

---

## 安装与快速开始

### 环境要求

- 支持平台：macOS、Linux、Windows (x64/arm64)
- Go 1.26+（仅从源码构建时需要）

### 快速开始（面向用户）

**一键安装（推荐）：**

```bash
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash
```

**从 npm 安装：**

```bash
npm install -g @gitlink-ai/cli
```

二进制文件在 `postinstall` 阶段自动下载，无需额外操作。

**从源码构建：**

```bash
git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
cd gitlink-cli
make install
```

> Windows 用户在 PowerShell 或 CMD 中运行 `npm install -g @gitlink-ai/cli`。从源码构建使用 `go install .` 代替 `make install`。

**配置与使用：**

```bash
# 1. 配置（一次性）
gitlink-cli config init

# 2. 登录（任选一种）
gitlink-cli auth login            # 用户名/密码（推荐）
gitlink-cli auth login --token    # 或粘贴私人令牌
export GITLINK_TOKEN="your-token" # 或环境变量（CI/CD 环境）

# 3. 开始使用
gitlink-cli repo +list
```

### 快速开始（AI Agent）

> 以下步骤供 AI Agent 使用。部分步骤需用户在浏览器中完成。

```bash
# Step 1 — 安装（一条命令完成 CLI + 全部 Skills）
npm install -g @gitlink-ai/cli

# Step 2 — 配置
gitlink-cli config init

# Step 3 — 登录
gitlink-cli auth login                              # 交互式环境
export GITLINK_TOKEN="your-private-token"           # 非交互式环境（CI/CD、MCP 等）

# Step 4 — 验证
gitlink-cli user +me
```

### 卸载

**Linux/macOS**：`bash uninstall.sh`
**Windows PowerShell**：`.\uninstall.ps1`
**npm**：`npm uninstall -g @gitlink-ai/cli`

---

## 使用示例

### 仓库操作

```bash
gitlink-cli repo +list
gitlink-cli repo +info --owner Gitlink --repo forgeplus
gitlink-cli repo +create -n my-project -d "项目描述"
gitlink-cli repo +fork --owner Gitlink --repo forgeplus
```

### Issue 管理

```bash
gitlink-cli issue +list --owner Gitlink --repo forgeplus
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: 登录失败" -b "复现步骤..."
gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123
gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 123,124 --dry-run
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.csv
gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "已修复"
```

### Pull Request

```bash
gitlink-cli pr +list --owner Gitlink --repo forgeplus
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: 搜索功能" --head feature/search --base master
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: 新功能" --head your_username/forgeplus:feature/my-feature --base master
gitlink-cli pr +view --owner Gitlink --repo forgeplus -i 42
gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42
gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
```

### 分支管理

```bash
gitlink-cli branch +list --owner Gitlink --repo forgeplus
gitlink-cli branch +create --name feature/new-feature
gitlink-cli branch +delete --name feature/old-feature
gitlink-cli branch +protect --name main
gitlink-cli branch +unprotect --name main
```

### Webhook 管理

```bash
gitlink-cli webhook +list --owner Gitlink --repo forgeplus
gitlink-cli webhook +create --owner Gitlink --repo forgeplus --url https://ci.example.com/webhook --events push,pull_request
gitlink-cli webhook +create --url https://jenkins.example.com/webhook --secret my-secret-key --events push --description "CI/CD 触发器"
gitlink-cli webhook +info --id 456
gitlink-cli webhook +update --id 456 --url https://new-url.example.com/webhook --events push,pull_request,issue
gitlink-cli webhook +test --id 456
gitlink-cli webhook +delete --id 456
gitlink-cli webhook +events
```

### Release 管理

```bash
gitlink-cli release +list --owner Gitlink --repo forgeplus
gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..."
gitlink-cli release +view --owner Gitlink --repo forgeplus -i <version_id>
```

### Wiki 管理

```bash
gitlink-cli wiki +list --owner Gitlink --repo forgeplus
gitlink-cli wiki +view --owner Gitlink --repo forgeplus --title "快速入门"
gitlink-cli wiki +create --title "新页面" --content "页面内容"
gitlink-cli wiki +update --title "新页面" --cover "更新内容" --owner Gitlink --repo forgeplus
gitlink-cli wiki +update --title "新页面" --add "追加内容" --owner Gitlink --repo forgeplus
gitlink-cli wiki +delete --title "新页面" --owner Gitlink --repo forgeplus
```

### 搜索

```bash
gitlink-cli search +repos -k "machine learning"
gitlink-cli search +users -k "zhangsan"
```

### CI/CD

```bash
gitlink-cli ci +list --owner Gitlink --repo forgeplus
gitlink-cli ci +log --owner Gitlink --repo forgeplus -i <build_id>
gitlink-cli ci +restart --owner Gitlink --repo forgeplus -i <build_id>
```

### Raw API

Shortcuts 未覆盖的端点可直接调用 Raw API：

```bash
gitlink-cli api GET /users/me
gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}'
gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5'
```

---

## 全局参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--owner` | 仓库所有者 | `--owner Gitlink` |
| `--repo` | 仓库名称 | `--repo forgeplus` |
| `--format` | 输出格式（json/table/yaml） | `--format json` |
| `--debug` | 启用调试输出 | `--debug` |

**自动上下文解析：** 在 git 仓库内运行命令时，`--owner` 和 `--repo` 自动从 `git remote origin` 解析。

---

## 分支约定

| 平台 | 默认分支 |
|------|----------|
| GitHub | `main` |
| GitLink | `master` |

推送到 GitLink：

```bash
git push gitlink main:master
# 或配置 git remote
git config remote.gitlink.push refs/heads/main:refs/heads/master
git push gitlink
```

---

## 项目目录结构

```
gitlink-cli/
├── cmd/                      # Cobra 命令定义
│   ├── root.go               # Root 命令 + 全局 flag
│   ├── auth/                 # 认证命令
│   ├── api/                  # Raw API 命令
│   ├── config/               # 配置命令
│   └── cmdutil/              # 全局工具
├── internal/                 # 内部包
│   ├── auth/                 # 登录、Token 存储、Transport
│   ├── client/               # HTTP 客户端 + 分页
│   ├── config/               # 配置文件管理
│   ├── context/              # Git remote 解析
│   └── output/               # 输出 envelope + formatter
├── shortcuts/                # Shortcut 实现
│   ├── common/               # 框架（types, runner）
│   ├── repo/ issue/ pr/ branch/ release/ org/ ci/ search/ user/ wiki/
│   └── register.go           # 注册入口
├── skills/                   # AI Agent Skills
│   ├── README.md             # Skills 详细指南
│   ├── gitlink-shared/       # 共享规则
│   ├── gitlink-repo/ issue/ pr/ branch/ release/ ...
│   ├── gitlink-health/       # 项目健康度
│   ├── gitlink-changelog/    # Release Notes
│   ├── gitlink-code-review/  # AI 代码审查
│   ├── gitlink-research/     # 科研辅助
│   └── ...
├── workflows/                # 端到端自动化工作流
│   ├── README.md             # 工作流说明
│   ├── lib/common.sh         # 共享工具库
│   ├── 01-community-ops.sh   # 社区运营自动化
│   ├── 02-code-quality-gatekeeper.sh  # 代码质量看门人
│   ├── 03-project-init.sh    # 项目一键初始化
│   ├── 04-multi-repo-collab.sh  # 多仓库协同
│   ├── 05-contributor-growth.sh  # 贡献者成长体系
│   └── test.sh               # 测试套件
├── doc/                      # 设计文档
│   ├── design.md
│   ├── CODE_SYNC_STRATEGY_FINAL.md
│   └── ...
├── main.go
├── Makefile
├── go.mod
├── README.md
└── README.zh-CN.md
```

---

## 文档索引

- [Skills 指南](skills/README.md) — AI Agent Skills 详细文档
- [工作流说明](workflows/README.md) — 五大自动化工作流详情
- [设计文档](doc/design.md) — 架构设计和开发计划
- [安装指南](doc/INSTALL.md) — 详细安装步骤
- [卸载指南](doc/UNINSTALL.md) — 详细卸载步骤
- [API 参考](skills/gitlink-shared/REFERENCE.md) — 完整 API 参考
- [故障排查](skills/gitlink-shared/TROUBLESHOOTING.md) — 常见问题排查

---

## 常见问题

### Q: 如何在脚本中使用 gitlink-cli？

使用 `GITLINK_TOKEN` 环境变量 + `--format json`：

```bash
export GITLINK_TOKEN="your-private-token"
gitlink-cli repo +list --format json | jq '.data.projects[] | .name'
```

### Q: 如何自动解析 owner/repo？

在 git 仓库目录下运行命令，CLI 自动从 `git remote origin` 解析：

```bash
cd ~/my-gitlink-project
gitlink-cli issue +list  # 自动使用当前仓库
```

### Q: Token 过期了怎么办？

```bash
gitlink-cli auth login            # 用户名/密码登录
gitlink-cli auth login --token    # 或使用私人令牌
```

### Q: 如何在 CI/CD 或非交互式环境（如 Trae sandbox）中使用？

设置 `GITLINK_TOKEN` 环境变量，无需 `auth login`：

```bash
export GITLINK_TOKEN="your-private-token"
gitlink-cli repo +list   # 立即可用
```

优先级：`GITLINK_TOKEN` 环境变量 > 密钥链/文件存储 Token。

### Q: npm 安装成功但 `gitlink-cli` 报告缺少二进制文件？

先尝试重新安装 `npm install -g @gitlink-ai/cli`。如仍报错，检查 release 页面是否包含对应平台的资源文件，或手动下载二进制 / 从源码 `go install .` 构建。

### Q: Windows 上凭证存储在哪里？

gitlink-cli 使用 Windows Credential Manager 安全存储 Token。如果 Credential Manager 不可用，自动回退到文件存储（`~/.config/gitlink-cli/credentials`）。

---

## 相关资源

- [gitlink-bisync](https://www.gitlink.org.cn/wbtiger/gitlink-bisync) — 代码双向同步系统
- [测试报告](doc/SKILLS_TEST_REPORT_2026-04-02.md) — Skills 功能测试报告
- [代码同步方案](doc/CODE_SYNC_STRATEGY_FINAL.md) — GitHub ↔ GitLink 同步设计

---

## 许可证

[MulanPSL-2.0](https://license.coscl.org.cn/MulanPSL2)
