# ge

**Repository Path**: Jacean/ge

## Basic Information

- **Project Name**: ge
- **Description**: ge（gitee-cli）是一个用 Go 编写的 Gitee 命令行工具，对标 GitHub CLI (gh)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# ge · Gitee CLI

**Gitee on the command line.**

[![Go Reference](https://pkg.go.dev/badge/gitee.com/imjoey/ge/v5.svg)](https://pkg.go.dev/gitee.com/imjoey/ge/v5)
[![Go Report Card](https://goreportcard.com/badge/gitee.com/imjoey/ge/v5)](https://goreportcard.com/report/gitee.com/imjoey/ge/v5)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

</div>

`ge`（也叫 `gitee-cli`）是一个用 Go 编写的 [Gitee](https://gitee.com) 命令行工具。它将仓库、Issue、Pull Request、Release 等概念带到你的终端，让你在 `git` 旁边就能完成所有 Gitee 操作。同时为 AI Agent 提供完整的 SKILL.md，让 Agent 无需文档搜索即可直接操作 Gitee。

```bash
$ ge repo create --name my-project --private
$ ge issue create --repo my-project --title "Fix login bug"
$ ge pr list --repo my-project
$ ge release create v1.0.0 --repo my-project --title "First Release"
```

---

## 给 AI Agent：安装 ge

把以下整段原样发给你的 AI Agent（Claude Code / Codex / Hermes / OpenCode 等），它会自动完成全部安装、认证、并加载操作手册：

```
安装 ge（Gitee CLI）：

# 1. 下载并安装预编译二进制（Linux amd64；其他平台见下方文件名表）
curl -sL https://gitee.com/imjoey/ge/releases/download/v5.10.0/ge_v5.10.0_linux_amd64.tar.gz -o /tmp/ge.tgz
tar xzf /tmp/ge.tgz -C /tmp
sudo mv /tmp/ge_v5.10.0_linux_amd64/ge /usr/local/bin/ge
ge --version   # 应输出 ge version 5.10.0

# 2. 配置认证（在 https://gitee.com/profile/personal_access_tokens 生成 token）
export GITEE_TOKEN=<your-personal-access-token>

# 3. 加载操作手册（必读，覆盖全部命令、参数、Gitee 特有陷阱与端到端工作流）
#    入口：https://gitee.com/imjoey/ge/blob/main/skills/gitee-cli/SKILL.md
#    由此路由到 references/commands/*.md 与 references/workflows/*.md，按需加载
```

**其他平台**：把 URL 中的 `linux_amd64` 替换为下表对应组合，完整下载列表见 [Releases](https://gitee.com/imjoey/ge/releases)。

| OS | AMD64 | ARM64 |
|----|-------|-------|
| Linux | `linux_amd64` | `linux_arm64` |
| macOS | `darwin_amd64` | `darwin_arm64` |
| Windows | `windows_amd64` (.zip) | `windows_arm64` (.zip) |

> Token 在 [Gitee → 设置 → 私人令牌](https://gitee.com/profile/personal_access_tokens) 生成；按需勾选 scope（`issues` / `pulls` / `releases` 等）。401/403 时 `ge` 会自动诊断缺失的 scope 并打印恢复步骤。

---

## 为什么需要 ge？

GitHub 有 [`gh`](https://github.com/cli/cli)，GitLab 有 [`glab`](https://gitlab.com/gitlab-org/cli)，**Gitee 一直没有官方 CLI**。

`ge` 填补了这个空白。

- 🤖 **Agent 优先** — 内置 [SKILL.md](skills/gitee-cli/SKILL.md)，Agent 装上即用，无需翻文档猜命令
- 🌐 **完整 API v5 覆盖** — 279 个 API 方法，覆盖 Gitee API v5 全部 264 个端点（100%+），18 个资源类型
- 🚀 **开箱即用** — 一个二进制文件，零依赖，macOS / Linux / Windows 全平台
- 🔌 **非交互模式** — 所有命令支持 `--yes` / 环境变量，适合 CI/CD 和 AI Agent 调用
- 🏗️ **架构对标 gh** — Factory 模式、IOStreams、httpmock，代码质量经得起考验
- 🎨 **彩色终端输出** — 自动检测 TTY，脚本模式和交互模式都有好体验

### Agent 协同，CLI 是关键基础设施

当多个 Agent 协作开发一个项目时——一个写代码、一个管 Issue、一个做 Code Review——它们需要一个**共同的操作界面**来协调 Gitee 上的工作。CLI 就是这个界面。

```
Agent A (代码)  ──┐
                  │    ge issue create / pr create / pr merge
Agent B (Review) ──┼──▶  统一的 Gitee 操作接口
                  │    无需共享服务进程，各 Agent 独立调用
Agent C (CI/CD)  ──┘
```

- **零协调成本** — 每个 Agent 只需 `ge` 二进制 + `GITEE_TOKEN`，无需启动额外的服务进程
- **框架无关** — Claude Code、Hermes、Codex、OpenCode……任何能执行命令的 Agent 都能用
- **可组合** — 命令可以管道串联、写入脚本、嵌入 CI/CD，MCP 做不到这些
- **状态透明** — 命令的输入输出都是可读的文本，Agent 之间可以互相理解和审计

### CLI vs MCP Server

Gitee 已有官方 MCP Server（[`oschina/mcp-gitee`](https://gitee.com/oschina/mcp-gitee)），但它和 CLI 解决的是不同层面的问题。以下是对比：

| | `ge` CLI | MCP Server |
|---|---|---|
| **运行方式** | 单个二进制，即装即用 | 需要启动并维护一个服务进程 |
| **Agent 兼容性** | 任何能执行 shell 命令的 Agent | 仅支持 MCP 协议的客户端（Cursor、Claude Desktop 等） |
| **API 覆盖** | 279 个方法，264 端点全覆盖 | ~29 个工具，缺少 auth、branch protection、webhook、org、milestone、label、tag、commit 等 |
| **CI/CD** | 原生支持，环境变量认证 | 不适用，MCP 是交互式协议 |
| **脚本组合** | 可管道、可嵌入 shell 脚本 | 只能通过 MCP 协议逐个调用 |
| **多 Agent 协同** | 各 Agent 独立调用，无需共享进程 | 需要 Agent 客户端各自连接 MCP Server |
| **离线/弱网** | 命令可预编排、重试、记录 | 依赖实时协议连接 |

**两者不是替代关系，而是互补**。GitHub 同时维护 [`gh` CLI](https://github.com/cli/cli) 和 [`github-mcp-server`](https://github.com/github/github-mcp-server)——`ge` 和 Gitee MCP Server 也是同样道理。对于 Agent 自动化、CI/CD、脚本编排、多 Agent 协同等场景，CLI 是不可替代的基础设施。

## 快速开始

### 1. 认证

```bash
# 用 Token 登录（推荐）
export GITEE_TOKEN=your_personal_access_token

# 或者保存到配置文件
ge auth login --token your_personal_access_token

# 检查认证状态
ge auth status
```

> 💡 在 [Gitee → 设置 → 私人令牌](https://gitee.com/profile/personal_access_tokens) 生成 Token

### 2. 试试看

```bash
# 查看你的信息
ge user info

# 列出你的仓库
ge repo list

# 创建一个新仓库
ge repo create --name hello-world --private

# 搜索仓库
ge search repos "golang cli"
```

## 核心功能

ge 覆盖 Gitee API v5 全部 264 个端点（279 个方法），主要功能领域：

- **仓库**：`repo` — 创建、删除、fork、文件读写、协作者、部署公钥、评论、流量统计
- **Issue**：`issue` — 完整生命周期（创建/编辑/关闭/重开）+ 评论 + 标签 + 操作日志
- **Pull Request**：`pr` — 完整流程（创建/审核/测试/合并）+ diff + 评论 + 人员指派
- **分支与标签**：`branch`、`tag` — 列表、创建、保护设置
- **Release**：`release` — 创建/查看/删除 + 附件上传下载
- **用户与组织**：`user`、`org` — 个人信息、SSH key、关注、成员管理
- **通知与消息**：`notification` — 站内通知 + 私信
- **搜索**：`search` — 仓库、Issue、用户
- **企业版**：`enterprise` — 企业信息、成员、周报、Issue/PR
- **CI/CD**：`check` — Check Run 管理
- **Webhook**：`webhook` — 创建/删除/测试
- **工具**：`config`、`alias`、`completion`、`version`

每个命令都支持 `--help` 查看详细用法。

- **命令索引**：[docs/commands.md](docs/commands.md) — 所有命令组的速览
- **详细参考**：[skills/gitee-cli/references/commands/](skills/gitee-cli/references/commands/) — 每组的完整 flag 表与示例
- **任务流程**：[skills/gitee-cli/references/workflows/](skills/gitee-cli/references/workflows/) — PR 三步合并、Issue 生命周期、发版等端到端场景
- **故障排查**：[skills/gitee-cli/references/workflows/troubleshooting.md](skills/gitee-cli/references/workflows/troubleshooting.md)
- **Agent Skill 入口**：[skills/gitee-cli/SKILL.md](skills/gitee-cli/SKILL.md) — 所有 Agent 框架通用的 ge 操作指南

## 使用示例

### 仓库操作

```bash
# 列出仓库
ge repo list

# 创建仓库（非交互，适合 CI/Agent）
ge repo create --name my-project --description "My project" --private

# 删除仓库（需要确认，或用 --yes 跳过）
ge repo delete owner/my-project --yes

# Fork 仓库
ge repo fork owner/some-repo

# 管理协作者
ge repo collaborator-list --repo my-project
ge repo collaborator-add username --repo my-project --permission push
```

### Issue 工作流

```bash
# 列出 Issue
ge issue list --repo my-project
ge issue list --repo my-project --state closed

# 创建 Issue
ge issue create --repo my-project --title "Bug: crash on startup" --body "Steps to reproduce..."

# 关闭 Issue
ge issue close my-project 123
```

### Pull Request 工作流

```bash
# 列出 PR
ge pr list --repo my-project
ge pr list --repo my-project --state merged

# 创建 PR
ge pr create --repo my-project --title "feat: add login page" --source feature/login --target master

# 合并 PR
ge pr merge my-project 42
```

### Release 发布

```bash
# 创建 Release
ge release create v1.0.0 --repo my-project --title "v1.0.0 - First Release" --note "## What's New\n- Feature A\n- Bug fix B"

# 查看 Release
ge release view v1.0.0 --repo my-project

# 删除 Release
ge release delete 1 --repo my-project
```

## Agent 集成

`ge` 从第一天起就是为 Agent 设计的——不是一个二进制加上"也可以给 Agent 用"的文档，而是内置 [SKILL.md](skills/gitee-cli/SKILL.md)，Agent 读取后即可知道：
- 如何安装和认证 `ge`（见本文档顶部）
- 所有可用命令及其参数
- Gitee 与 GitHub 的差异（如三步合并流程）
- 各操作的完整示例

`skills/gitee-cli/` 是**框架中立**的标准 SKILL.md 格式（Anthropic Skills 规范，已被多家框架采纳）。Agent 只需读 `SKILL.md` 入口即可，无需关心它托管在哪种 agent 框架里。

### 多 Agent 协同实战

一个真实的多 Agent 协作场景——三个 Agent 通过 `ge` CLI 协调 Gitee 上的开发工作流：

```
┌─────────────┐    ge issue create     ┌──────────────┐
│  Hermes     │──────────────────────▶ │    Gitee     │
│  (调度)     │    ge pr review/test   │              │
│             │    ge pr merge         │  Issue #42   │
└──────┬──────┘    ge issue close      │  PR #42      │
       │                               │  Release     │
       │ 派活                          └──────▲───────┘
       ▼                                      │
┌─────────────┐    git push                  │
│ Claude Code │──────────────────────┐       │
│ (编码)      │    ge pr create      ├───────┘
└─────────────┘                      │
                                     │
┌─────────────┐    ge release create │
│  Codex      │──────────────────────┘
│  (部署)     │    ge tag create
└─────────────┘
```

```
# Hermes（调度 Agent）创建 Issue 派活
ge issue create --repo owner/ge --title "feat: add webhook support" --body "实现 webhook CRUD"

# Claude Code（编码 Agent）完成开发后创建 PR
git push origin feat/webhook
ge pr create --repo owner/ge --title "feat: add webhook support" --source feat/webhook

# Hermes 审核 PR（Gitee 三步合并）
ge pr review 42 --repo owner/ge
ge pr test 42 --repo owner/ge
ge pr merge owner/ge 42

# Codex（部署 Agent）打 Tag、发 Release
ge tag create v1.1.0 --repo owner/ge
ge release create v1.1.0 --repo owner/ge --title "Webhook Support"

# Hermes 收工
ge issue close owner/ge IJXXXX
```

**核心价值**：三个 Agent 来自不同的框架（Hermes、Claude Code、Codex），但它们都用同一个 `ge` CLI 操作 Gitee。不需要共享进程、不需要统一协议——`ge` 就是它们之间的**通用语言**。

Gitee 的 PR 合并必须走三步（review → test → merge），Agent 读取 SKILL.md 后会自动遵循这个流程，不会遗漏。

### CI/CD 场景

```bash
# 纯环境变量认证，无需配置文件
export GITEE_TOKEN=${{ secrets.GITEE_TOKEN }}

# 非交互操作
ge repo create --name auto-project --private
ge issue create --repo auto-project --title "Automated issue" --body "Created by CI"
ge pr create --repo auto-project --title "Auto PR" --source fix-branch
ge repo delete owner/auto-project --yes
```

## Shell 补全

```bash
# Bash
ge completion -s bash > /etc/bash_completion.d/ge
echo 'source /etc/bash_completion.d/ge' >> ~/.bashrc

# Zsh
ge completion -s zsh > "${fpath[1]}/_ge"

# Fish
ge completion -s fish > ~/.config/fish/completions/ge.fish
```

## 配置

### Token 优先级

`ge` 按以下顺序查找 Token：

1. `GITEE_TOKEN` 环境变量（最高优先级）
2. `GE_TOKEN` 环境变量
3. 配置文件 `~/.config/ge/config.yml` 中的 `gitee_token`
4. 遗留配置 `~/.gitee.yaml`

### 配置文件

默认位置：`~/.config/ge/config.yml`

```yaml
gitee_token: your_token        # 不推荐，优先用环境变量
owner: your_username           # 默认 owner
git_protocol: https            # https 或 ssh
editor: vim                    # 文本编辑器
```

### 环境变量

| 变量 | 说明 |
|------|------|
| `GITEE_TOKEN` | Gitee 个人访问令牌（最高优先级） |
| `GE_TOKEN` | `GITEE_TOKEN` 的别名 |
| `GE_CONFIG_PATH` | 自定义配置文件路径 |

## 项目架构

`ge` 的架构参照 GitHub CLI ([`gh`](https://github.com/cli/cli)) 的设计模式：

```
ge/
├── main.go                    # 入口
├── internal/
│   ├── cmdutil/               # Factory、错误类型、工具函数
│   ├── config/                # 配置管理（XDG 路径、Token 优先级）
│   ├── build/                 # 版本信息（ldflags + ReadBuildInfo fallback）
│   └── commands/              # 命令实现（每个功能一个目录）
│       ├── auth/              #   认证命令
│       ├── repo/              #   仓库命令
│       ├── issue/             #   Issue 命令
│       ├── pr/                #   PR 命令
│       ├── branch/            #   分支命令
│       ├── release/           #   Release 命令
│       ├── milestone/         #   里程碑命令
│       ├── label/             #   标签命令
│       ├── webhook/           #   Webhook 命令
│       ├── commit/            #   提交命令
│       ├── tag/               #   标签命令
│       ├── search/            #   搜索命令
│       ├── org/               #   组织命令
│       ├── user/              #   用户命令
│       ├── notification/      #   通知命令
│       ├── watch/             #   仓库订阅命令
│       ├── enterprise/       #   企业管理命令
│       ├── check/            #   Check Run 命令
│       ├── activity/         #   活动事件命令
│       ├── git/              #   Git 数据命令
│       ├── config/            #   配置命令
│       ├── completion/        #   Shell 补全
│       └── version/           #   版本命令
├── pkg/
│   ├── gitee/                 # Gitee API v5 客户端（Facade 层）
│   ├── giteeapi/              # go-swagger 生成的 API 客户端
│   ├── iostreams/             # I/O 流抽象（TTY 检测、颜色）
│   └── httpmock/              # HTTP Mock 测试框架
├── skills/gitee-cli/          # Agent Skill（框架中立，所有 agent 框架通用）
│   ├── SKILL.md               # Agent 入口（命令索引 + 5 条核心陷阱）
│   └── references/            # commands/ + workflows/ 详细参考
├── docs/                      # 人类向文档（commands.md / install_*.md / faq.md）
├── tests/                     # 集成测试和 E2E 测试
├── .goreleaser.yml            # 多平台发布配置
└── Makefile                   # 构建任务
```

**核心设计模式**（与 gh 一致）：

- **Factory** — `cmdutil.Factory` 注入 IOStreams、Config、HttpClient
- **Options** — 每个命令有独立的 Options 结构体
- **Test Injection** — `runF` 参数支持测试注入
- **IOStreams** — TTY 检测、颜色支持、测试模式
- **httpmock** — 可验证的 HTTP Mock，确保测试覆盖

## 测试状态

| 指标 | 值 |
|------|-----|
| 测试文件 | 247 个 |
| 测试函数 | 2,134 个 |
| 总覆盖率 | 57.6% |
| golangci-lint | 0 issues ✅ |
| API 覆盖率 | 279/264 端点 (100%+，含超额方法) |

### 各模块覆盖率

| 模块 | 覆盖率 | 模块 | 覆盖率 |
|------|--------|------|--------|
| user | 99.9% | label | 99.6% |
| tag | 99.3% | search | 98.9% |
| commit | 97.7% | notification | 92.5% |
| pr | 82.5% | issue | 76.5% |
| branch | 74.3% | repo | 65.9% |
| release | 62.8% | pkg/gitee | 40.5% |

## Gitee API 与 GitHub 的差异

`ge` 覆盖了 Gitee API v5 全部端点，但 Gitee 平台本身和 GitHub 有一些设计差异，使用时需要注意：

### PR 合并流程

Gitee 的 PR 合并是**三步审批**（review → test → merge），不是 GitHub 的一步完成。`ge pr review` 和 `ge pr test` 是两个独立的审批环节，缺一不可。详见 [SKILL.md](SKILL.md)。

### Issue 读写路径

Issue 的读操作和写操作使用不同的 URL 路径：读取走 `/repos/{owner}/{repo}/issues`，创建/更新走 `/repos/{owner}/issues`（repo 作为 body 参数）。`ge` 已统一处理，用户无需关心。

### 请求格式

Gitee Swagger 文档标注参数类型为 `formData`，但实际也接受 JSON body。`ge` 统一使用 JSON 格式。

### Issue 编号格式

Gitee 的 Issue 编号可以是字符串（如 `IJP3UP`），不全是数字。开启企业项目管理的仓库会生成字母数字混合编号。`ge issue close` 等命令同时支持数字和字符串编号。

### 平台相关行为

- 仓库设置 `has_issues: false` 时，Issue 操作会返回 400，属于正常限制
- 开启企业项目管理的仓库，部分 Issue 走企业子系统 API，可能返回 404
- `ge pr review` 偶发返回 403，是 Gitee 侧的已知行为，重试即可

> 遇到异常时，先查 [Gitee 官方 Swagger 文档](https://gitee.com/api/v5/swagger) 确认是否为平台行为。

## 开发

```bash
# 构建
make build

# 测试
make test

# 代码检查
make lint

# 多平台构建
make build-all
```

### 运行集成测试

```bash
# 单元测试（不需要 Token）
go test ./...

# 集成测试（需要真实 Gitee API）
GITEE_TOKEN=your_token GE_INTEGRATION_TEST=1 go test ./tests/...
```

---

## 贡献

欢迎贡献代码！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。

1. Fork 本仓库
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'feat: add amazing feature'`
4. 推送分支：`git push origin feature/amazing-feature`
5. 创建 Pull Request

## 许可证

[MIT License](LICENSE)

## 链接

- [Gitee API v5 文档](https://gitee.com/api/v5/swagger)
- [GitHub CLI (gh)](https://github.com/cli/cli) — 架构参考
- [问题反馈](https://gitee.com/imjoey/ge/issues)

---

<div align="center">

**如果 ge 对你有帮助，请给个 ⭐ Star 支持一下！**

</div>