forked from Gitlink/gitlink-cli
184 lines
8.4 KiB
Markdown
184 lines
8.4 KiB
Markdown
# GitLink CLI · 智能化能力提升
|
||
|
||
> 让 AI 智能体和开发者都能在终端高效操控 GitLink 平台，把仓库管理、Issue/PR 协作、CI/CD 变成可自动化、可复现的流程。
|
||
|
||
**第八届 CCF 开源创新大赛 · track1 GitLink-CLI 贡献赛**参赛作品。
|
||
|
||
---
|
||
|
||
## 项目简介
|
||
|
||
随着 Claude Code、Cursor 等 AI 编程智能体兴起，开发者正从"手动操作平台"转向"Agent 驱动开发"。但 GitLink 平台的能力长期锁在网页 GUI 里——AI 看不到、调不动，开发者也得在终端和浏览器间反复切换。
|
||
|
||
本项目围绕 [gitlink-cli](https://gitlink.org.cn/gitlink/gitlink-cli) 做了四件事：
|
||
|
||
1. **把平台能力命令化**——新增 19 个命令模块、110 条命令，让每类操作都能在终端一行命令完成
|
||
2. **给 AI 写使用说明书**——23 个 Skill，让 Claude Code 等智能体直接会操控 GitLink
|
||
3. **串成端到端工作流**——自研工作流引擎，一行命令把多个 Skill 串成自动化流水线
|
||
4. **延伸到科研场景**——科研项目洞悉、FAIR 合规检查、贡献者画像
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| 命令模块 | 19 个（110 条命令） |
|
||
| 批量操作 | 11 条（全部支持 `--dry-run` 预演） |
|
||
| AI Agent Skill | 23 个 |
|
||
| 预置工作流 | 5 个 |
|
||
| 单元测试 | 187 个 |
|
||
| 交叉编译平台 | 8 个（Win/Linux/macOS/FreeBSD × amd64/arm64） |
|
||
|
||
---
|
||
|
||
## 四大子赛题成果
|
||
|
||
### 子赛题一 · 增加 CLI 能力
|
||
新增 19 个 Shortcut 模块（仓库/Issue/PR/Release/CI/Webhook/标签/里程碑/Wiki/工作流…），11 条批量操作，修复跨平台兼容性（Windows/Linux/macOS/FreeBSD）。已向主仓库提交 PR。
|
||
- 代码：[`shortcuts/`](shortcuts/)、[`internal/`](internal/)、[`cmd/`](cmd/)
|
||
- 提交材料：[`提交材料/子赛题一-CLI能力/`](提交材料/子赛题一-CLI能力/)
|
||
|
||
### 子赛题二 · 编写 Skills
|
||
23 个 Skill（命令操作类 + 智能分析型），覆盖健康度报告、Release Notes 生成、Issue 智能分拣、智能代码审查、许可证合规、科研辅助等。一键 `setup-skills.sh` 装进 Claude Code 即可用 `/gitlink-xxx` 调用。
|
||
- 代码：[`skills/`](skills/)
|
||
- 演示录屏：[`提交材料/子赛题二-Skills/demos/`](提交材料/子赛题二-Skills/demos/)
|
||
|
||
### 子赛题三 · 端到端工作流
|
||
自研工作流引擎（`shortcuts/workflow/`），AI/规则双模式，5 个预置工作流（代码质量看门人/社区运营自动化/贡献者成长/多仓库协同/项目一键初始化），支持手动/轮询/定时触发，systemd 7×24 自动运行。
|
||
- 代码：[`shortcuts/workflow/`](shortcuts/workflow/)
|
||
- 提交材料：[`提交材料/子赛题三-工作流/`](提交材料/子赛题三-工作流/)
|
||
|
||
### 子赛题四 · 辅助科研
|
||
gitlink-spark（科研软件 X 光）、gitlink-research-fair（FAIR 合规检查）、gitlink-contributor-ranking（贡献者画像），面向科研项目洞悉、合规校验、协作匹配。
|
||
- 代码：[`skills/gitlink-spark`](skills/gitlink-spark)、[`skills/gitlink-research-fair`](skills/gitlink-research-fair)
|
||
- 提交材料：[`提交材料/子赛题四-科研/`](提交材料/子赛题四-科研/)
|
||
|
||
> 📁 所有变更说明、演示录屏/截图集中在 [`提交材料/`](提交材料/) 目录。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 方式一：go install（需 Go 1.26+）
|
||
go install github.com/gitlink-org/gitlink-cli@latest
|
||
|
||
# 方式二：npm
|
||
npm install -g @gitlink-ai/cli
|
||
|
||
# 方式三：下载预编译包（8 平台）
|
||
# 见 Release 页面
|
||
```
|
||
|
||
### 认证
|
||
|
||
```bash
|
||
gitlink-cli auth login # 浏览器登录，cookie 自动保存
|
||
gitlink-cli auth status # 查看登录状态
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
```bash
|
||
# 列出仓库的 Issue
|
||
gitlink-cli issue +list --owner gitlink --repo gitlink-cli
|
||
|
||
# 批量关闭（先预演）
|
||
gitlink-cli issue +batch-close --numbers 1,2,3 --dry-run
|
||
|
||
# 在 Claude Code 里一句话调用 Skill
|
||
/gitlink-triage 帮我分拣所有未分类的 Issue
|
||
```
|
||
|
||
### 一键启用 Skills（Claude Code）
|
||
|
||
```bash
|
||
bash scripts/setup-skills.sh # 把 skills/ 链接到 ~/.claude/skills/
|
||
# 之后在 Claude Code 里就能 /gitlink-xxx 调用
|
||
```
|
||
|
||
### 在线演示
|
||
|
||
Showcase Dashboard：<http://118.31.4.168:9090> —— 浏览器里点卡片就能跑命令，无需安装。
|
||
|
||
---
|
||
|
||
## 架构说明
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ 入口层 cmd/ main.go → root.go (cobra root) │
|
||
│ 4 个基础命令: auth / api / config / version │
|
||
│ 全局 flag: --owner/--repo/--format/--debug │
|
||
└───────────────┬──────────────────────────────────────────┘
|
||
│ shortcuts.RegisterAll(rootCmd)
|
||
┌───────────────▼──────────────────────────────────────────┐
|
||
│ 业务层 shortcuts/ 19 组 × 100+ 命令 + 工作流引擎 │
|
||
│ register.go 命令注册中枢 │
|
||
│ common/ RuntimeContext 业务统一上下文 │
|
||
│ workflow/ 工作流引擎（AI/规则双模式 + 5 预置流） │
|
||
└───────────────┬──────────────────────────────────────────┘
|
||
│ RuntimeContext.CallAPI / Output
|
||
┌───────────────▼──────────────────────────────────────────┐
|
||
│ 基础层 internal/ Go 内部包，不对外暴露 │
|
||
│ client/ HTTP 客户端 + .json 后缀 + 错误检测 │
|
||
│ auth/ Transport 自动注入 Cookie/access_token │
|
||
│ config/ YAML 配置 + 跨平台路径 │
|
||
│ output/ Envelope(ok/data/meta) + json/yaml/table │
|
||
└──────────────────────────────────────────────────────────┘
|
||
|
||
独立的 AI 层 skills/ 23 个 SKILL.md，面向 AI Agent 的自然语言说明书
|
||
（非编译期依赖，指导 Agent 调用编译好的二进制）
|
||
```
|
||
|
||
**核心设计**：业务命令只依赖 `RuntimeContext`，绝不直接接触 cobra/HTTP 细节——新增模块只挂一个 `shortcuts/` 子包，不动入口与基础层。这是 19 模块 100+ 命令仍保持可测试性的根本。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
gitlink-cli/
|
||
├── README.md # 本文件
|
||
├── cmd/ # 入口层（auth/api/config/version）
|
||
├── shortcuts/ # 业务层（19 命令模块 + workflow 工作流引擎）
|
||
├── internal/ # 基础层（client/auth/config/output/context/errors）
|
||
├── skills/ # 23 个 AI Agent Skill
|
||
├── showcase/ # 在线演示 Dashboard（Go 单二进制）
|
||
├── scripts/ # 脚本（setup-skills.sh 等）
|
||
├── docs/ # 设计文档、API 参考
|
||
└── 提交材料/ # ★ 比赛提交材料（变更说明 + 演示录屏/截图）
|
||
├── 子赛题一-CLI能力/
|
||
├── 子赛题二-Skills/
|
||
├── 子赛题三-工作流/
|
||
└── 子赛题四-科研/
|
||
```
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
- **语言**：Go 1.26（子赛题一）；Markdown/Shell（子赛题二三四）
|
||
- **CLI 框架**：spf13/cobra
|
||
- **密钥存储**：zalando/go-keyring（OS keychain + 文件 fallback）
|
||
- **配置**：gopkg.in/yaml.v3
|
||
- **CI/CD**：GitLink DevOps（建木引擎）自动部署 + GitHub Actions 8 平台发版
|
||
|
||
---
|
||
|
||
## 团队
|
||
|
||
| 成员 | 负责 |
|
||
|------|------|
|
||
| chroe | CLI 核心模块、Showcase、CI/CD、health/changelog/triage Skill、工作流引擎 |
|
||
| yetja | 批量操作、单元测试、license/repo/org Skill、工作流规则引擎 |
|
||
| caoweiqiong | file/member/watch/star 模块、review Skill、FreeBSD 支持 |
|
||
|
||
---
|
||
|
||
## 相关链接
|
||
|
||
- 上游仓库：<https://gitlink.org.cn/gitlink/gitlink-cli>
|
||
- 本项目（Fork）：<https://gitlink.org.cn/chroe/gitlink-cli>
|
||
- 在线 Showcase：<http://118.31.4.168:9090>
|
||
- Skills 开发指南：[`skills/README.md`](skills/README.md)
|