0.6.0 • Published 2d agoCLI

@hust-open-atom-club/atomgit-cli

Licence

MulanPSL-2.0

Version

0.6.0

Deps

Size

22 kB

Vulns

Weekly

Summary Dependency Versions

AtomGit CLI (ag)

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

安装

npm

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

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

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

从源码构建

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

# 安装到 $GOPATH/bin
make install

配置

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

使用 OAuth 登录（推荐）：运行 ag auth login，在浏览器中完成 AtomGit 授权。登录成功后，ag 会自动将认证信息写入令牌文件。
手动创建访问令牌：参考 AtomGit 访问令牌（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 时，文件内容至少包括：

{
  "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；请勿将未经检查的原始输出直接转发到终端。

命令

认证

# 浏览器 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)

# 列出仓库（默认显示 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)

# 列出 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 评论

# 创建评论
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

# 列出 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 评论

# 创建评论
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

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

License

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

SSH Key

# 添加 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"

版本

# 查看版本信息
ag version

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

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

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

发布打包

发布版使用 GoReleaser 打包，tag 统一使用 vX.Y.Z 三段式 SemVer。正式发布前应先提交所有改动，并在当前 HEAD 创建版本 tag：

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 附件前可校验所有制品：

# 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 前单独校验：

(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 提供的开发环境，以使用项目声明的工具版本：

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

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

./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