# atomgit-cli

**Repository Path**: openkylin/atomgit-cli

## Basic Information

- **Project Name**: atomgit-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: packaging/openkylin/nile
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AtomGit CLI (ag)

AtomGit 命令行工具，参考 GitHub CLI (gh) 开发。

## 安装

### npm

需要 Node.js 18 或更高版本：

```bash
npm install --global @hust-open-atom-club/atomgit-cli
ag version
```

npm 会通过当前操作系统和 CPU 对应的可选依赖安装预编译二进制，不需要运行 `postinstall` 脚本。

### Nix / NixOS

AtomGit CLI 已进入 `nixos-unstable`，包名为 `atomgit-cli`，安装后提供 `ag` 命令。

如果你的 Nix registry 或 flake input 已指向 `nixos-unstable`：

```bash
nix profile install nixpkgs#atomgit-cli
ag version
```

如果你使用的是稳定版 nixpkgs，可以显式从 `nixos-unstable` 安装：

```bash
nix profile install github:NixOS/nixpkgs/nixos-unstable#atomgit-cli
```

临时运行：

```bash
nix run github:NixOS/nixpkgs/nixos-unstable#atomgit-cli -- version
```

其他安装方式请参阅[完整安装指南](https://atomgit.com/hust-open-atom-club/atomgit-cli/blob/main/docs/installation.md)。

### 从源码构建

```bash
# 构建到 bin/ag（Windows 为 bin/ag.exe）
make build

# 安装到 $GOPATH/bin
make install
```

## 配置

首次使用本工具前，需要选择以下任一方式配置访问令牌：

- 使用 OAuth 登录（推荐）：运行 `ag auth login`，在浏览器中完成 AtomGit 授权。登录成功后，`ag` 会自动将认证信息写入令牌文件。

- 手动创建访问令牌：参考 [AtomGit 访问令牌（PAT）文档](https://docs.gitcode.com/docs/help/home/user_center/security_management/user_pat/)，依次进入「个人设置」->「访问令牌」->「新建访问令牌」，按需设置权限范围和到期时间，再将生成的 PAT 写入令牌文件。PAT 创建后只显示一次，请立即妥善保存，不要将其提交到代码仓库或分享给他人。

令牌文件的默认路径因操作系统而异：

- Linux：`/home/<用户名>/.config/ag-cli/token.json`
- macOS：`/Users/<用户名>/.config/ag-cli/token.json`
- Windows：`C:\Users\<用户名>\.config\ag-cli\token.json`

手动配置 PAT 时，文件内容至少包括：

```json
{
  "access_token": "your-personal-access-token",
  "user": "your-atomgit-login",
  "token_type": "Bearer"
}
```

配置文件字段说明：

| 字段 | 是否必填 | 说明 |
| --- | --- | --- |
| `access_token` | 是 | 用于调用 AtomGit API 的访问令牌。手动配置时填写刚创建的 PAT；请勿泄露或提交到版本控制。 |
| `user` | 是 | AtomGit 登录用户名（账号标识），不是昵称或邮箱。 |
| `refresh_token` | 否 | OAuth 刷新令牌，仅由 `ag auth login` 获取，并供 `ag auth refresh` 换取新的访问令牌。PAT 没有该字段。 |
| `expires_in` | 否 | OAuth 访问令牌从签发时刻起的有效秒数，由服务端返回。PAT 的有效期在创建 PAT 时设置，手动配置可省略。 |
| `created_at` | 否 | CLI 保存或刷新 OAuth 凭据时记录的 Unix 时间戳（秒），用于表示签发/保存时间。手动配置 PAT 时可省略。 |
| `token_type` | 是 | 令牌认证类型。当前 PAT 和 OAuth 访问令牌均使用 `Bearer`。 |

`ag auth login` 会自动写入上述 OAuth 字段；手动使用 PAT 时不要自行编造 `refresh_token`、`expires_in` 或 `created_at`。请确保配置文件仅允许当前用户读取和写入令牌文件。

### 输出安全

`ag` 默认会将终端控制字符转换为可见转义文本，包括输出经管道转发时，以防止仓库、Issue、PR 或 Git 服务端返回的内容注入终端控制序列。确实需要为机器处理保留原始字节时，可显式使用全局参数 `--raw-output`，例如 `ag --raw-output pr diff owner/repo 123`；请勿将未经检查的原始输出直接转发到终端。

## 命令

### 认证

```bash
# 浏览器 OAuth 登录并写入令牌文件
ag auth login
# 已登录时会提示无需重复登录；若要重新走浏览器：ag auth login --force

# 用 refresh_token 刷新 access_token（需之前登录响应里包含 refresh_token）
ag auth refresh

# 查看认证状态
ag auth status

# 显示当前 token
ag auth token

# 删除本地令牌文件
ag auth logout
```

可选环境变量（覆盖默认 OAuth 应用）：`AG_OAUTH_CLIENT_ID`、`AG_OAUTH_CLIENT_SECRET`；若本机 **8765** 端口被占用，可设置 **`AG_OAUTH_REDIRECT_PORT`**（需与 AtomGit 应用配置的回调地址一致）。

### 仓库 (repo)

```bash
# 列出仓库（默认显示 30 条）
ag repo list

# 指定最多列出100条仓库
ag repo list --limit 100

# 查看仓库详情
ag repo view owner/repo

# 创建仓库
# 在当前用户账号下创建
ag repo create my-project --public

# 在指定个人或组织账号下创建
ag repo create owner/my-project --public --description "My project"

# 克隆仓库
ag repo clone owner/repo
ag repo clone owner/repo --branch dev

# Fork 仓库
ag repo fork owner/repo
ag repo fork owner/repo --name my-fork --public

# 删除仓库
ag repo delete owner/repo --yes
```

### Pull Request (pr)

```bash
# 列出 PR
ag pr list owner/repo
ag pr list owner/repo --state closed

# 查看 PR
ag pr view owner/repo 123

# 查看 PR diff
ag pr diff owner/repo 123

# 创建 PR
ag pr create owner/repo --title "Fix bug" --body "Description" --base main --head feature-branch

# 关闭 PR
ag pr close owner/repo 123
```

#### PR 评论

```bash
# 创建评论
ag pr comment create owner/repo 123 --body "LGTM!"
ag pr comment create owner/repo 123 --body-file review.md

# 查看所有评论（树形结构显示）
ag pr comment view owner/repo 123

# 编辑评论（交互式编辑）
ag pr comment edit owner/repo 123 456
ag pr comment edit owner/repo 123 456 --body "Updated comment"

# 删除评论
ag pr comment delete owner/repo 123 456
ag pr comment delete owner/repo 123 456 --yes

# 回复评论（PR 特有）
ag pr comment reply owner/repo 123 456 --body "Thanks for the feedback!"
```

### Issue

```bash
# 列出 Issue
ag issue list owner/repo
ag issue list owner/repo --state all

# 查看 Issue
ag issue view owner/repo 42

# 添加 Issue 标签（使用逗号分隔多个标签）
ag issue label owner/repo 42 "bug, help wanted,priority/high"

# 修改 Issue 标题或正文
ag issue edit owner/repo 42 --title "Updated title"
ag issue edit owner/repo 42 --body "Updated description"
ag issue edit owner/repo 42 --body-file details.md

# 创建 Issue
ag issue create owner/repo --title "Bug report" --body "Description"
```

#### Issue 评论

```bash
# 创建评论
ag issue comment create owner/repo 42 --body "I can reproduce this issue"
ag issue comment create owner/repo 42 --body-file details.md

# 查看所有评论
ag issue comment view owner/repo 42

# 编辑评论（交互式编辑）
ag issue comment edit owner/repo 42 789
ag issue comment edit owner/repo 42 789 --body "Updated information"

# 删除评论
ag issue comment delete owner/repo 42 789
ag issue comment delete owner/repo 42 789 --yes
```

### Label

```bash
# 列出仓库标签（默认显示 30 条）
ag label list owner/repo
ag label list owner/repo --limit 50
```

### License

```bash
# 检查 license 合规性
ag license check MIT
ag license check Apache-2.0
ag license check GPL-3.0
```

### SSH Key

```bash
# 添加 SSH key
ag ssh-key add ~/.ssh/id_rsa.pub --title "My Laptop"
cat ~/.ssh/id_rsa.pub | ag ssh-key add --title "My Laptop"
```

### 版本

```bash
# 查看版本信息
ag version

# 等价的根级参数
ag --version

# 机器可读的 JSON 输出
ag version --json
```

通过 `make build` 或 `make install` 从源码构建且未注入发布元数据时，版本默认值为 `dev`。如果 Go 构建信息包含模块版本、源码提交或提交时间，`ag version` 会使用这些信息替代或补充默认值；工作区存在未提交改动时，版本还会带有 dirty 标记。

## 发布打包

发布版使用 [GoReleaser](https://goreleaser.com/install/) 打包，tag 统一使用 `vX.Y.Z` 三段式 SemVer。正式发布前应先提交所有改动，并在当前 HEAD 创建版本 tag：

```bash
npm run version:npm -- 0.6.0
git tag v0.6.0
make release VERSION=v0.6.0
```

`make release` 会检查工作区干净、tag 存在且指向当前 HEAD，然后在 `dist/v0.6.0/` 生成以下文件：

- Linux 和 macOS 的 amd64/arm64 `.tar.gz` 归档。
- Windows 的 amd64/arm64 `.zip` 归档。
- 已绑定当前 tag 的 `install.sh` 和 `install.ps1`。
- `npm/` 下的六个平台二进制包、一个主启动包和独立的 `npm/checksums.txt`。
- 仅覆盖 AtomGit Release 附件（六个归档和两个安装脚本）的根 `checksums.txt`。

发布 npm 制品时，先发布 `npm/` 下六个名称带平台和架构的包；确认它们可用后，再发布 `atomgit-cli` 主包。主包和平台包必须使用相同版本。

上传 Release 附件前可校验所有制品：

```bash
# Linux
(cd dist/v0.6.0 && sha256sum -c checksums.txt)

# macOS
(cd dist/v0.6.0 && shasum -a 256 -c checksums.txt)
```

npm tarball 不作为 AtomGit Release 附件上传，可在发布到 npm registry 前单独校验：

```bash
(cd dist/v0.6.0/npm && shasum -a 256 -c checksums.txt)
```

未创建 tag 时，可使用 `make release-snapshot VERSION=v0.6.0` 进行本地试打包。Snapshot 允许脏工作区，其制品仅用于验证，不应上传到正式 Release。

底层 `scripts/build-release.sh` 也接受 `TAG`、`AG_RELEASE_SNAPSHOT=1` 和 `SOURCE_DATE_EPOCH` 环境变量。`SOURCE_DATE_EPOCH` 会同时固定二进制中的构建日期以及归档内文件的时间戳，用于生成可复现的发布制品；历史两段式 tag 仅保留给 snapshot 兼容。

### 维护 Nix package

更新 Nix package 的版本和 `vendorHash` 时，推荐先进入 flake 提供的开发环境，以使用项目声明的工具版本：

```bash
nix develop
./scripts/update-nix-package.sh v0.6.0
```

也可以直接运行更新脚本：

```bash
./scripts/update-nix-package.sh v0.6.0
```

直接运行需要预先安装 Nix 和 Git，并要求 `tar` 支持以 NUL 分隔的文件列表；Linux 上的 GNU tar 和 macOS 默认的 bsdtar 均受支持。脚本会更新 `flake.nix` 中的版本和 `vendorHash`，随后执行 `nix build .#ag` 和 `ag version --json` 验证。验证失败时会自动恢复原始 `flake.nix`，且脚本不会提交、打标签或推送。

## 项目结构

```
atomgit-cli/
├── .goreleaser.yaml            # GoReleaser 跨平台打包配置
├── Makefile                    # 构建、测试、安装和发布入口
├── install.sh                  # Linux/macOS 安装脚本
├── install.ps1                 # Windows 安装脚本
├── bin/ag.js                   # npm 主包的平台二进制启动器
├── scripts/build-npm-packages.js # 从 Release 归档生成七个 npm 包
├── cmd/ag/main.go              # 入口
├── internal/
│   ├── agcmd/cmd.go            # 核心命令处理
│   ├── config/config.go        # 配置管理
│   ├── version/version.go      # 版本元数据
│   └── api/
│       ├── client.go           # API 客户端
│       └── types.go            # 数据类型
├── pkg/
│   ├── cmdutil/factory.go      # 命令工厂
│   └── cmd/
│       ├── root/root.go        # 根命令
│       ├── auth/auth.go        # 认证命令
│       ├── repo/               # 仓库命令
│       │   ├── repo.go
│       │   ├── create.go
│       │   ├── clone.go
│       │   ├── delete.go
│       │   └── fork.go
│       ├── pr/                 # PR 命令
│       │   ├── pr.go
│       │   └── comment/        # PR 评论命令
│       ├── issue/              # Issue 命令
│       │   ├── issue.go
│       │   └── comment/        # Issue 评论命令
│       ├── label/              # 标签命令
│       │   └── label.go
│       ├── license/            # License 命令
│       │   ├── license.go
│       │   └── check.go
│       ├── ssh-key/ssh_key.go  # SSH key 命令
│       └── version/version.go  # 版本命令
├── scripts/build-release.sh    # GoReleaser 打包包装脚本
└── go.mod
```

## API

使用 AtomGit API v5: `https://api.atomgit.com/api/v5`

## 参考

- [AtomGit API 文档](https://docs.atomgit.com/docs/apis/)
- [GitHub CLI](https://cli.github.com/)

## License

[木兰宽松许可证第2版](LICENSE) (Mulan Permissive Software License, Version 2)

Copyright (c) 2026 AtomGit CLI Contributors