目录
1. 项目概述
2、软件总体设计
2.1 软件体系结构设计
2.2 用户界面设计
2.3 数据库设计
2.4 系统度量
3、系统静态模型
3.1 命令框架层设计
3.2 快捷命令层设计
3.3 核心库层设计
4、系统动态模型
4.1 用例一：用户认证与仓库操作
4.2 用例二：Issue 批量管理
4.3 用例三：AI 自动化工作流
5、系统部署模型


1. 项目概述

gitlink-cli 是 GitLink（确实开源）平台的命令行工具。GitLink 是 CCF 官方开源协作平台，后端提供 490+ API 端点，但此前缺少官方 CLI 工具。本项目填补了这个空白。

应用背景：
开发者在日常工作中需要频繁操作仓库、Issue、PR、分支等资源。浏览器操作效率低，无法批量处理，也不能与 CI/CD 流水线集成。gitlink-cli 让开发者在终端中完成所有平台操作，并通过 AI Agent Skill 支持 Claude Code 自动化执行复杂工作流。

功能描述：
- 仓库管理：创建、列表、详情、Fork、删除、设置、批量操作
- Issue 管理：列表、创建、查看、更新、关闭、评论、标签、6 种批量命令
- PR 管理：列表、创建、查看、合并、关闭、代码审查、变更文件查看
- 分支管理：列表、创建、删除、保护
- 发布管理：列表、创建、查看、删除
- Wiki 管理：列表、创建、查看、更新、删除
- Webhook 管理：列表、创建、更新、删除、测试
- CI/CD 管理：构建列表、日志、重启、停止
- 组织与团队管理：组织列表、详情、成员、团队 CRUD
- 合规检查：许可证扫描、敏感信息检测、依赖审计
- 搜索：仓库搜索、用户搜索
- AI 工作流：社区运营、代码审查、项目初始化、多仓库协同、贡献者成长

性能要求：
- 单次 API 调用响应时间 < 2 秒
- 批量操作支持并发执行，错误不中断
- 分页自动遍历，支持大数据量场景
- 跨平台支持：Windows、macOS、Linux


2、软件总体设计

2.1 软件体系结构设计

本项目采用分层架构，从上到共分为五层：

（1）入口层：main.go 和 cmd/root.go，基于 Cobra 框架构建命令树。
（2）命令层：cmd/ 目录，包含 auth、api、config、compliance 四个顶级命令。
（3）快捷命令层：shortcuts/ 目录，16 个资源组，每组通过 +动词 子命令暴露操作。
（4）核心库层：internal/ 目录，包含 HTTP 客户端、认证、配置、输出格式化、错误处理。
（5）AI 扩展层：skills/ 目录（24 个 SKILL.md）和 workflows/ 目录（bash/PowerShell 脚本）。

各层的职责划分：

[入口层] main.go → cmd.Execute() → Cobra root 命令
    ↓
[命令层] auth / api / config / compliance
    ↓
[快捷命令层] shortcuts/ → repo/issue/pr/wiki/... → common.Shortcut 声明式定义
    ↓
[核心库层] internal/client → HTTP 请求 → internal/auth → Token 注入
           internal/output → 格式化输出（JSON/Table/YAML）
           internal/config → 配置文件读写
           internal/context → git remote 解析 owner/repo
    ↓
[AI 扩展层] skills/ → SKILL.md 定义（供 Claude Code 调用）
            workflows/ → 可执行脚本（bash/PowerShell）

核心设计模式是声明式 Shortcut 框架。每个快捷命令通过 common.Shortcut 结构体定义 Name、Flags、Run 函数，由 runner.go 统一挂载到 Cobra 命令树。开发者新增命令只需实现 Run 函数，不需要关心命令注册和参数解析的细节。

三层命令体系：
- Layer 1 Shortcuts：语义化封装，覆盖 16 个领域共 80+ 命令（如 issue +create）
- Layer 2 API Commands：原始 HTTP 调用（api GET/POST/PUT/DELETE）
- Layer 3 Raw API：覆盖全部 490+ 端点，自动注入认证 Header


2.2 用户界面设计

本项目是 CLI 工具，用户界面是终端命令行。界面设计遵循以下原则：

（1）命令格式统一：gitlink-cli <资源> +<动作> [flags]
   例如：gitlink-cli issue +create --title "Bug" --body "描述"

（2）输出格式三选一：通过 --format 参数选择 json、table、yaml，默认 table。
   table 格式使用 tabwriter 对齐，支持 ANSI 颜色高亮表头。
   json 格式使用统一的 Envelope 结构：{ok, data, error, meta}。

（3）全局参数：--owner、--repo（自动从 git remote 解析）、--format、--debug、--no-truncate、--columns、--no-color。

（4）Shell 补全：支持 bash、zsh、fish、powershell 四种 shell 的自动补全。

（5）帮助系统：每个命令支持 --help，显示用法、参数说明和示例。

用户操作流程：
用户打开终端 → 输入 gitlink-cli auth login 登录 → 使用具体命令操作资源
→ 输出结果以 table/json/yaml 格式显示 → 可通过管道传递给其他工具


2.3 数据库设计

本项目不使用传统数据库。数据存储分为两部分：

（1）配置文件存储：
路径：~/.config/gitlink-cli/config.yaml
内容：base_url（API 地址）、default_format（输出格式）、editor、pager
格式：YAML

（2）凭证存储：
使用 go-keyring 库，调用操作系统原生密钥管理：
- macOS：Keychain
- Linux：Secret Service（GNOME Keyring / KDE Wallet）
- Windows：Credential Manager
Fallback：~/.config/gitlink-cli/credentials（文件权限 0600）

存储的数据结构：
Token（字符串）→ 关联 gitlink.org.cn 的 Bearer Token
Config（YAML）→ base_url、default_format、editor、pager 等配置项

本项目不需要关系型数据库，所有数据来自 GitLink 平台 API 的实时查询。


2.4 系统度量

（1）代码规模：
- Go 源文件：60 个
- Go 代码总行数：14,932 行
- 测试文件：12 个，共 4,279 行
- 测试覆盖率：测试代码占总代码的 22.3%

（2）按模块统计：

模块               文件数   代码行数
main（入口）        1       13
cmd（命令层）       5       379
internal（核心库）  13      2,242
shortcuts（快捷层） 41      12,398
合计                60      14,932

（3）功能规模：
- Shortcut 命令组：16 个
- Shortcut 命令总数：80+
- AI Skill 定义：24 个 SKILL.md
- 自动化工作流脚本：15+ 个（bash/PowerShell）
- 支持的 Shell 补全：4 种（bash/zsh/fish/powershell）

（4）依赖规模：
- 直接依赖：4 个（cobra、go-keyring、golang.org/x/term、yaml.v3）
- 编译产物大小：约 11.9 MB（单二进制文件）


3、系统静态模型

3.1 命令框架层设计

命令框架层由 cmd/ 包和 shortcuts/common/ 包组成，定义了整个 CLI 的骨架。

核心类结构：

（1）cobra.Command（来自 spf13/cobra 库）
- 每个命令对应一个 cobra.Command 实例
- rootCmd 是根命令，所有子命令通过 AddCommand 挂载
- root.go 定义全局 PersistentFlags（--owner、--repo、--format 等）

（2）common.Shortcut 结构体：
type Shortcut struct {
    Name        string
    Description string
    Long        string
    Example     string
    Flags       []Flag
    DryRun      bool
    DryRunHint  func(ctx *RuntimeContext) (string, error)
    Validate    func(args map[string]string) error
    Run         func(ctx *RuntimeContext) error
}

（3）common.Flag 结构体：
type Flag struct {
    Name     string
    Short    string
    Usage    string
    Required bool
    Default  string
    Bool     bool
    Choices  []string
    Validate func(value string) error
}

（4）common.RuntimeContext 结构体：
type RuntimeContext struct {
    Client            *client.Client
    Owner             string
    Repo              string
    Format            string
    CommandName       string
    Args              map[string]string
    GatewayBaseURL    string
    GatewayHTTPClient *http.Client
    NoTruncate        bool
    Columns           string
    NoColor           bool
}

RuntimeContext 提供以下核心方法：
- ResolveOwnerRepo()：从 git remote 或 flags 解析 owner/repo
- CallAPI(method, path, body)：发起 HTTP 请求
- PaginateAll(path, params)：自动遍历分页
- Output(env)：格式化输出
- OutputData(data)：封装为成功 Envelope 并输出

（5）register.go 的注册机制：
RegisterAll(root) 遍历 16 个命令组，每组创建 cobra.Command 并调用 MountShortcuts 挂载子命令。MountShortcuts 遍历 Shortcut 切片，为每个 Shortcut 创建对应的 cobra.Command，绑定 flags 和 RunE 函数。


3.2 快捷命令层设计

快捷命令层位于 shortcuts/ 目录，包含 16 个命令组。每个组是一个独立的 Go 包，通过 Shortcuts() 函数返回 []*common.Shortcut 切片。

命令组列表：
- board：看板操作（view/columns/issues/move/assign/stats）— 832 行
- branch：分支操作（list/create/delete/protect）— 157 行
- ci：CI/CD 操作（builds/logs/restart/stop）— 117 行
- file：文件操作（ls/read/create/update/delete/commits/diff）— 886 行
- issue：Issue 操作（14 个命令，含 6 种批量操作）— 3,058 行
- milestone：里程碑操作（list/create/view/update/delete/status）— 525 行
- org：组织操作（list/info/members/create/update）— 476 行
- pr：PR 操作（list/create/view/merge/close/review/files/diff）— 973 行
- release：发布操作（list/create/view/delete）— 179 行
- repo：仓库操作（含 batch-create/batch-update/batch-delete/batch-member）— 1,781 行
- search：搜索操作（repos/users）— 88 行
- team：团队操作（list/create/delete/members）— 192 行
- user：用户操作（me/info）— 41 行
- webhook：Webhook 操作（list/create/view/update/delete/test/events）— 649 行
- wiki：Wiki 操作（list/create/view/update/delete/lint/fix/sync）— 1,612 行

最大的两个模块是 issue（3,058 行）和 wiki（1,612 行）。issue 模块包含批量操作功能，wiki 模块处理双域名架构和 base64 编解码。

批量操作设计模式（以 issue 为例）：
- BatchResult：单条操作结果（number/action/status/error）
- BatchSummary：汇总信息（total/succeeded/failed/results）
- 输入灵活：--numbers（内联）和 --from（CSV 文件）可同时使用
- dry-run 统一：所有批量命令支持 --dry-run 预览
- 错误不中断：单条失败不影响后续处理


3.3 核心库层设计

核心库层位于 internal/ 目录，包含 7 个子包：

（1）internal/auth — 认证模块（3 个文件，272 行）
- login.go：登录流程（用户名密码或 Token 粘贴）
- token_store.go：Token 存储（go-keyring 跨平台支持）
- transport.go：HTTP Transport，自动在请求 Header 中注入 Bearer Token

（2）internal/client — HTTP 客户端（2 个文件，319 行）
- client.go：封装 Get/Post/Put/Delete 方法，自动追加 .json 后缀，双重错误检查（HTTP 状态码 + JSON body 中的 status 字段）
- pagination.go：分页迭代器，自动遍历 Kaminari 风格分页

（3）internal/compliance — 合规检查（4 个文件，685 行）
- cmd.go：compliance 子命令定义
- scanner.go：扫描器实现
- license.go：许可证检测
- rules.go：合规规则定义

（4）internal/config — 配置管理（1 个文件，125 行）
- config.go：读写 ~/.config/gitlink-cli/config.yaml

（5）internal/context — 上下文解析（1 个文件，91 行）
- repo.go：从 git remote 的 origin URL 自动解析 owner 和 repo

（6）internal/errors — 错误处理（1 个文件，150 行）
- errors.go：统一错误类型 CLIError，包含 Kind（错误分类）、Message、Suggestion、Command 字段
- 错误分类：KindAuth、KindInput、KindForbidden、KindNotFound、KindServer、KindUnknown

（7）internal/output — 输出格式化（3 个文件，425 行）
- envelope.go：定义 Envelope 结构体 {OK, Data, Error, Meta}
- formatter.go：三种输出格式（JSON/YAML/Table），table 使用 tabwriter 对齐，支持 ANSI 颜色、列过滤、值截断控制


4、系统动态模型

4.1 用例一：用户认证与仓库操作

用例描述：用户首次使用 gitlink-cli，完成登录并查看仓库信息。

参与者：开发者（终端用户）

前置条件：已安装 gitlink-cli，网络可访问 gitlink.org.cn

主要流程：

（1）用户执行 gitlink-cli auth login
（2）系统提示输入用户名和密码
（3）系统调用 POST /api/accounts/login 获取 Token
（4）Token 存入 OS Keychain
（5）用户进入 git 仓库目录，执行 gitlink-cli repo +info
（6）系统从 .git/config 解析 remote origin URL，提取 owner/repo
（7）系统调用 GET /api/{owner}/{repo}/detail.json
（8）系统以 table 格式输出仓库信息

异常流程：
- Token 过期（7 天有效期）：系统返回 401 错误，提示运行 gitlink-cli auth login 重新登录
- 非 git 目录：系统提示使用 --owner 和 --repo 参数显式指定

API 调用序列：
POST /api/accounts/login → {token: "..."}
GET /api/{owner}/{repo}/detail.json → {name, description, default_branch, ...}


4.2 用例二：Issue 批量管理

用例描述：项目维护者批量关闭过期 Issue 并批量创建新 Issue。

参与者：项目维护者

前置条件：已登录，有仓库写权限

主要流程：

（1）用户执行 gitlink-cli issue +batch-close --numbers 101,102,103,104 --dry-run
（2）系统预览：显示 4 个 Issue 将被关闭，不实际执行
（3）用户确认后去掉 --dry-run，重新执行
（4）系统逐个调用 PUT /api/{owner}/{repo}/issues/{number}，设置 state 为 closed
（5）系统输出 BatchSummary：total=4, succeeded=4, failed=0

（6）用户准备 CSV 文件 issues.csv：
title,body,priority,label
"登录页面样式异常","点击按钮后样式错乱","high","缺陷"
"新增数据导出功能","支持 CSV 和 JSON 格式导出","normal","功能"

（7）用户执行 gitlink-cli issue +batch-create --from issues.csv --template bug
（8）系统逐个调用 POST /api/{owner}/{repo}/issues 创建 Issue
（9）系统输出 BatchSummary：total=2, succeeded=2, failed=0

异常流程：
- 单条操作失败：记录错误，继续处理后续条目，最终 exit code = 1
- API 字段静默失败：GitLink 对不认识的字段返回 200 而非报错，需通过浏览器 DevTools 确认字段名


4.3 用例三：AI 自动化工作流

用例描述：使用 Claude Code 和 gitlink-cli Skill 自动完成社区运营任务。

参与者：社区运营者（通过 Claude Code 交互）

前置条件：Claude Code 已安装，gitlink-cli 已登录

主要流程：

（1）用户在 Claude Code 中说"帮我跑社区运营工作流"
（2）Claude Code 触发 gitlink-workflows skill，显示功能菜单
（3）用户选择"社区运营自动化"
（4）Claude Code 调用 gitlink-cli issue +list --state open --format json
（5）Claude Code 分析 Issue 列表，按类型分类（bug/feature/question）
（6）Claude Code 调用 gitlink-cli issue +label-add 添加分类标签
（7）Claude Code 调用 gitlink-cli pr +list 获取近期 PR
（8）Claude Code 生成周报摘要，包含 Issue 统计、PR 合并情况、贡献者活跃度

Skill 调用链：
gitlink-shared（认证检查）→ gitlink-issue（Issue 操作）→ gitlink-pr（PR 操作）→ gitlink-workflow（工作流编排）


5、系统部署模型

本项目采用单二进制分发模式，部署简单。

（1）构建环境：
- Go 1.26.1+
- Makefile 管理构建流程
- 构建命令：make build（通过 -ldflags 注入版本号）

（2）分发方式：
- 直接下载：从 GitHub Releases 下载预编译二进制
- npm 安装：npm install -g gitlink-cli
- 源码编译：go install github.com/gitlink-org/gitlink-cli@latest
- 安装脚本：install.sh（Linux/macOS）、install.ps1（Windows）

（3）目标平台：
- Windows（amd64）
- macOS（amd64、arm64）
- Linux（amd64、arm64）

（4）依赖服务：
- GitLink API：https://www.gitlink.org.cn/api（主站 API）
- GitLink Gateway：https://gateway.gitlink.org.cn/api（Wiki API 专用）
- OS Keychain：系统密钥管理服务（存储 Token）

（5）CI/CD 集成：
- GitHub Actions：.github/workflows/release.yml 自动构建和发布
- GitLink DevOps：.devops/gitlink-cli-autodeploy.yml 平台自动部署

（6）部署架构：

用户终端
    ↓
gitlink-cli（本地二进制）
    ↓ HTTP/HTTPS
GitLink API Server（gitlink.org.cn）
    ↓
GitLink Gateway（gateway.gitlink.org.cn，Wiki 专用）

gitlink-cli 是纯客户端工具，不运行后台服务。所有数据存储在用户本地（配置文件 + OS Keychain），业务数据完全来自 GitLink 平台 API 的实时查询。
