@hust-open-atom-club/atomgit-cli 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +77 -53
  2. package/README.md +35 -319
  3. package/bin/ag.js +1 -0
  4. package/package.json +8 -7
package/LICENSE CHANGED
@@ -1,105 +1,129 @@
1
- 木兰宽松许可证第2版
1
+ 木兰宽松许可证， 第2版
2
+ 2020年1月 http://license.coscl.org.cn/MulanPSL2
2
3
 
3
- 您对软件的使用、复制、分发和修改受木兰宽松许可证第2版（以下简称"本许可证"）约束。如果您接受本许可证的条款和条件，则您被授予本许可证中规定的权利。
4
4
 
5
- 1. 定义
5
+ 您对“软件”的复制、使用、修改及分发受木兰宽松许可证，第2版（“本许可证”）的如下条款的约束：
6
6
 
7
- "软件"是指由贡献者提供的、随本许可证分发的软件及相关文档。
7
+ 0. 定义
8
8
 
9
- "贡献者"是指对软件作出修改或贡献的个人或实体。
9
+ “软件”是指由“贡献”构成的许可在“本许可证”下的程序和相关文档的集合。
10
10
 
11
- "贡献"是指贡献者对软件作出的任何修改或添加。
11
+ “贡献”是指由任一“贡献者”许可在“本许可证”下的受版权法保护的作品。
12
12
 
13
- "您"（或"您的"）是指行使本许可证授予的权利的个人或实体。
13
+ “贡献者”是指将受版权法保护的作品许可在“本许可证”下的自然人或“法人实体”。
14
14
 
15
- 2. 授权
15
+ “法人实体”是指提交贡献的机构及其“关联实体”。
16
16
 
17
- 在遵守本许可证条款和条件的前提下，每位贡献者特此授予您永久的、全球性的、非独占的、免费的、免版税的、不可撤销的版权许可，允许您以源代码或二进制形式使用、复制、修改、分发软件，无论是否修改。
17
+ “关联实体”是指，对“本许可证”下的行为方而言，控制、受控制或与其共同受控制的机构，此处的控制是指有受控方或共同受控方至少50%直接或间接的投票权、资金或其他有价证券。
18
18
 
19
- 3. 条件
19
+ 1. 授予版权许可
20
20
 
21
- 您在分发软件时必须满足以下条件：
21
+ 每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的版权许可，您可以复制、使用、修改、分发其“贡献”，不论修改与否。
22
22
 
23
- (a) 您必须在软件的每个副本或实质性部分中包含本许可证的副本。
23
+ 2. 授予专利许可
24
24
 
25
- (b) 如果您修改软件，您必须在修改的文件中显著地声明您已更改文件。
25
+ 每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的（根据本条规定撤销除外）专利许可，供您制造、委托制造、使用、许诺销售、销售、进口其“贡献”或以其他方式转移其“贡献”。前述专利许可仅限于“贡献者”现在或将来拥有或控制的其“贡献”本身或其“贡献”与许可“贡献”时的“软件”结合而将必然会侵犯的专利权利要求，不包括对“贡献”的修改或包含“贡献”的其他结合。如果您或您的“关联实体”直接或间接地，就“软件”或其中的“贡献”对任何人发起专利侵权诉讼（包括反诉或交叉诉讼）或其他专利维权行动，指控其侵犯专利权，则“本许可证”授予您对“软件”的专利许可自您提起诉讼或发起维权行动之日终止。
26
26
 
27
- (c) 如果您以二进制形式分发软件，您必须在分发的文档或材料中包含本许可证的副本。
27
+ 3. 无商标许可
28
28
 
29
- 4. 专利授权
29
+ “本许可证”不提供对“贡献者”的商品名称、商标、服务标志或产品名称的商标许可，但您为满足第4条规定的声明义务而必须使用除外。
30
30
 
31
- 每位贡献者特此授予您永久的、全球性的、非独占的、免费的、免版税的、不可撤销的（本节所述除外）专利许可，允许您制造、委托制造、使用、许诺销售、销售、进口和以其他方式转让软件。
31
+ 4. 分发限制
32
32
 
33
- 5. 免责声明
33
+ 您可以在任何媒介中将“软件”以源程序形式或可执行形式重新分发，不论修改与否，但您必须向接收者提供“本许可证”的副本，并保留“软件”中的版权、商标、专利及免责声明。
34
34
 
35
- 软件按"原样"提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同、侵权或其他方面，由软件或软件的使用或其他交易引起或与之相关。
35
+ 5. 免责声明与责任限制
36
36
 
37
- 6. 责任限制
37
+ “软件”及其中的“贡献”在提供时不带任何明示或默示的担保。在任何情况下，“贡献者”或版权所有者不对任何人因使用“软件”或其中的“贡献”而引发的任何直接或间接损失承担责任，不论因何种原因导致或者基于何种法律理论，即使其曾被建议有此种损失的可能性。
38
38
 
39
- 在任何情况下，任何贡献者均不对您因使用软件而产生的任何直接、间接、附带、特殊、惩罚性或后果性损害（包括但不限于采购替代商品或服务；使用、数据或利润损失；或业务中断）负责，无论责任理论如何，无论是合同、严格责任还是侵权（包括疏忽或其他），即使已被告知此类损害的可能性。
39
+ 6. 语言
40
+ “本许可证”以中英文双语表述，中英文版本具有同等法律效力。如果中英文版本存在任何冲突不一致，以中文版为准。
40
41
 
41
- 7. 终止
42
+ 条款结束
42
43
 
43
- 如果您违反本许可证的任何条款，本许可证授予您的权利将自动终止。但是，如果您纠正违规行为，则从纠正之日起，您的权利将恢复。
44
+ 如何将木兰宽松许可证，第2版，应用到您的软件
44
45
 
45
- 8. 其他
46
+ 如果您希望将木兰宽松许可证，第2版，应用到您的新软件，为了方便接收者查阅，建议您完成如下三步：
46
47
 
47
- 本许可证受中华人民共和国法律管辖并按其解释。
48
+ 1， 请您补充如下声明中的空白，包括软件名、软件的首次发表年份以及您作为版权人的名字；
48
49
 
49
- 如果本许可证的任何条款被认定为不可执行，该条款应仅在使其可执行的必要范围内进行修改，其余条款仍具有完全效力。
50
+ 2， 请您在软件包的一级目录下创建以“LICENSE”为名的文件，将整个许可证文本放入该文件中；
50
51
 
51
- 这是本许可证的全部协议，取代您与贡献者之间关于软件的任何先前或同时的口头或书面通信、建议和陈述。
52
+ 3， 请将如下声明文本放入每个源文件的头部注释中。
52
53
 
53
- ---
54
+ Copyright (c) 2026 HUST OpenAtom Club
55
+ Copyright (c) 2026 AtomGit
56
+ Copyright (c) 2026 The AtomGit CLI Contributors
57
+ AtomGit CLI is licensed under Mulan PSL v2.
58
+ You can use this software according to the terms and conditions of the Mulan PSL v2.
59
+ You may obtain a copy of Mulan PSL v2 at:
60
+ http://license.coscl.org.cn/MulanPSL2
61
+ THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
62
+ See the Mulan PSL v2 for more details.
54
63
 
55
- Mulan Permissive Software License, Version 2 (Mulan PSL v2)
56
64
 
57
- Your use, reproduction, distribution and modification of the Software are governed by this Mulan Permissive Software License, Version 2 (the "License").
65
+ Mulan Permissive Software License，Version 2
58
66
 
59
- 1. Definitions
67
+ Mulan Permissive Software License，Version 2 (Mulan PSL v2)
68
+ January 2020 http://license.coscl.org.cn/MulanPSL2
60
69
 
61
- "Software" means the software and related documentation distributed with this License.
70
+ Your reproduction, use, modification and distribution of the Software shall be subject to Mulan PSL v2 (this License) with the following terms and conditions:
62
71
 
63
- "Contributor" means the individual or entity that makes modifications to or contributes to the Software.
72
+ 0. Definition
64
73
 
65
- "Contribution" means any modification or addition to the Software made by a Contributor.
74
+ Software means the program and related documents which are licensed under this License and comprise all Contribution(s).
66
75
 
67
- "You" (or "Your") means an individual or entity exercising rights under this License.
76
+ Contribution means the copyrightable work licensed by a particular Contributor under this License.
68
77
 
69
- 2. Grant of Rights
78
+ Contributor means the Individual or Legal Entity who licenses its copyrightable work under this License.
70
79
 
71
- Subject to the terms and conditions of this License, each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to use, reproduce, modify, distribute the Software in source or binary form, with or without modification.
80
+ Legal Entity means the entity making a Contribution and all its Affiliates.
72
81
 
73
- 3. Conditions
82
+ Affiliates means entities that control, are controlled by, or are under common control with the acting entity under this License, ‘control’ means direct or indirect ownership of at least fifty percent (50%) of the voting power, capital or other securities of controlled or commonly controlled entity.
74
83
 
75
- You must satisfy the following conditions when You distribute the Software:
84
+ 1. Grant of Copyright License
76
85
 
77
- (a) You must include a copy of this License in every copy or substantial portion of the Software.
86
+ Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable copyright license to reproduce, use, modify, or distribute its Contribution, with modification or not.
78
87
 
79
- (b) If You modify the Software, You must cause the modified files to carry prominent notices stating that You have changed the files.
88
+ 2. Grant of Patent License
80
89
 
81
- (c) If You distribute the Software in binary form, You must include a copy of this License in the documentation or other materials provided with the distribution.
90
+ Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable (except for revocation under this Section) patent license to make, have made, use, offer for sale, sell, import or otherwise transfer its Contribution, where such patent license is only limited to the patent claims owned or controlled by such Contributor now or in future which will be necessarily infringed by its Contribution alone, or by combination of the Contribution with the Software to which the Contribution was contributed. The patent license shall not apply to any modification of the Contribution, and any other combination which includes the Contribution. If you or your Affiliates directly or indirectly institute patent litigation (including a cross claim or counterclaim in a litigation) or other patent enforcement activities against any individual or entity by alleging that the Software or any Contribution in it infringes patents, then any patent license granted to you under this License for the Software shall terminate as of the date such litigation or activity is filed or taken.
82
91
 
83
- 4. Patent License
92
+ 3. No Trademark License
84
93
 
85
- Each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Software.
94
+ No trademark license is granted to use the trade names, trademarks, service marks, or product names of Contributor, except as required to fulfill notice requirements in Section 4.
86
95
 
87
- 5. Disclaimer of Warranty
96
+ 4. Distribution Restriction
88
97
 
89
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
98
+ You may distribute the Software in any medium with or without modification, whether in source or executable forms, provided that you provide recipients with a copy of this License and retain copyright, patent, trademark and disclaimer statements in the Software.
90
99
 
91
- 6. Limitation of Liability
100
+ 5. Disclaimer of Warranty and Limitation of Liability
92
101
 
93
- IN NO EVENT SHALL ANY CONTRIBUTOR BE LIABLE TO YOU FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
102
+ THE SOFTWARE AND CONTRIBUTION IN IT ARE PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE OR THE CONTRIBUTION IN IT, NO MATTER HOW IT’S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
94
103
 
95
- 7. Termination
104
+ 6. Language
96
105
 
97
- This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. However, if You cure such breach, Your rights under this License shall be reinstated from the date of such cure.
106
+ THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION SHALL PREVAIL.
98
107
 
99
- 8. Miscellaneous
108
+ END OF THE TERMS AND CONDITIONS
100
109
 
101
- This License shall be governed by and construed in accordance with the laws of the People's Republic of China.
110
+ How to Apply the Mulan Permissive Software License，Version 2 (Mulan PSL v2) to Your Software
102
111
 
103
- If any provision of this License is held to be unenforceable, such provision shall be modified only to the extent necessary to make it enforceable, and the remaining provisions shall remain in full force and effect.
112
+ To apply the Mulan PSL v2 to your work, for easy identification by recipients, you are suggested to complete following three steps:
104
113
 
105
- This License constitutes the entire agreement between You and the Contributors with respect to the Software and supersedes all prior or contemporaneous oral or written communications, proposals and representations with respect to the Software.
114
+ i Fill in the blanks in following statement, including insert your software name, the year of the first publication of your software, and your name identified as the copyright owner;
115
+
116
+ ii Create a file named “LICENSE” which contains the whole context of this License in the first directory of your software package;
117
+
118
+ iii Attach the statement to the appropriate annotated syntax at the beginning of each source file.
119
+
120
+
121
+ Copyright (c) 2026 HUST OpenAtom Club
122
+ Copyright (c) 2026 AtomGit
123
+ Copyright (c) 2026 The AtomGit CLI Contributors
124
+ AtomGit CLI is licensed under Mulan PSL v2.
125
+ You can use this software according to the terms and conditions of the Mulan PSL v2.
126
+ You may obtain a copy of Mulan PSL v2 at:
127
+ http://license.coscl.org.cn/MulanPSL2
128
+ THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
129
+ See the Mulan PSL v2 for more details.
package/README.md CHANGED
@@ -10,371 +10,87 @@ AtomGit 命令行工具，参考 GitHub CLI (gh) 开发。
10
10
 
11
11
  ```bash
12
12
  npm install --global @hust-open-atom-club/atomgit-cli
13
- ag version
14
13
  ```
15
14
 
16
15
  npm 会通过当前操作系统和 CPU 对应的可选依赖安装预编译二进制，不需要运行 `postinstall` 脚本。
17
16
 
18
- ### Nix / NixOS
19
-
20
- AtomGit CLI 已进入 `nixos-unstable`，包名为 `atomgit-cli`，安装后提供 `ag` 命令。
21
-
22
- 如果你的 Nix registry 或 flake input 已指向 `nixos-unstable`：
23
-
24
- ```bash
25
- nix profile install nixpkgs#atomgit-cli
26
- ag version
27
- ```
28
-
29
- 如果你使用的是稳定版 nixpkgs，可以显式从 `nixos-unstable` 安装：
30
-
31
- ```bash
32
- nix profile install github:NixOS/nixpkgs/nixos-unstable#atomgit-cli
33
- ```
17
+ ### Homebrew
34
18
 
35
- 临时运行：
19
+ macOS 或 Linux 用户可以通过项目维护的 Homebrew tap 安装：
36
20
 
37
21
  ```bash
38
- nix run github:NixOS/nixpkgs/nixos-unstable#atomgit-cli -- version
22
+ brew install hust-open-atom-club/tap/atomgit-cli
39
23
  ```
40
24
 
41
- 其他安装方式请参阅[完整安装指南](https://atomgit.com/hust-open-atom-club/atomgit-cli/blob/main/docs/installation.md)。
25
+ ### Scoop
42
26
 
43
- ### 从源码构建
27
+ Windows 用户可以通过组织维护的 scoop bucket 安装：
44
28
 
45
- ```bash
46
- # 构建到 bin/ag（Windows 为 bin/ag.exe）
47
- make build
48
-
49
- # 安装到 $GOPATH/bin
50
- make install
29
+ ```powershell
30
+ scoop install https://raw.githubusercontent.com/hust-open-atom-club/ScoopBucket/main/bucket/atomgit-cli.json
51
31
  ```
52
32
 
53
- ## 配置
54
-
55
- 首次使用本工具前，需要选择以下任一方式配置访问令牌：
56
-
57
- - 使用 OAuth 登录（推荐）：运行 `ag auth login`，在浏览器中完成 AtomGit 授权。登录成功后，`ag` 会自动将认证信息写入令牌文件。
58
-
59
- - 手动创建访问令牌：参考 [AtomGit 访问令牌（PAT）文档](https://docs.gitcode.com/docs/help/home/user_center/security_management/user_pat/)，依次进入「个人设置」->「访问令牌」->「新建访问令牌」，按需设置权限范围和到期时间，再将生成的 PAT 写入令牌文件。PAT 创建后只显示一次，请立即妥善保存，不要将其提交到代码仓库或分享给他人。
60
-
61
- 令牌文件的默认路径因操作系统而异：
62
-
63
- - Linux：`/home/<用户名>/.config/ag-cli/token.json`
64
- - macOS：`/Users/<用户名>/.config/ag-cli/token.json`
65
- - Windows：`C:\Users\<用户名>\.config\ag-cli\token.json`
66
-
67
- 手动配置 PAT 时，文件内容至少包括：
68
-
69
- ```json
70
- {
71
- "access_token": "your-personal-access-token",
72
- "user": "your-atomgit-login",
73
- "token_type": "Bearer"
74
- }
75
- ```
76
-
77
- 配置文件字段说明：
78
-
79
- | 字段 | 是否必填 | 说明 |
80
- | --- | --- | --- |
81
- | `access_token` | 是 | 用于调用 AtomGit API 的访问令牌。手动配置时填写刚创建的 PAT；请勿泄露或提交到版本控制。 |
82
- | `user` | 是 | AtomGit 登录用户名（账号标识），不是昵称或邮箱。 |
83
- | `refresh_token` | 否 | OAuth 刷新令牌，仅由 `ag auth login` 获取，并供 `ag auth refresh` 换取新的访问令牌。PAT 没有该字段。 |
84
- | `expires_in` | 否 | OAuth 访问令牌从签发时刻起的有效秒数，由服务端返回。PAT 的有效期在创建 PAT 时设置，手动配置可省略。 |
85
- | `created_at` | 否 | CLI 保存或刷新 OAuth 凭据时记录的 Unix 时间戳（秒），用于表示签发/保存时间。手动配置 PAT 时可省略。 |
86
- | `token_type` | 是 | 令牌认证类型。当前 PAT 和 OAuth 访问令牌均使用 `Bearer`。 |
87
-
88
- `ag auth login` 会自动写入上述 OAuth 字段；手动使用 PAT 时不要自行编造 `refresh_token`、`expires_in` 或 `created_at`。请确保配置文件仅允许当前用户读取和写入令牌文件。
89
-
90
- ### 输出安全
33
+ Scoop 安装的二进制由 Scoop 管理升级，并报告 `selfUpdate=false, source=scoop`。
91
34
 
92
- `ag` 默认会将终端控制字符转换为可见转义文本，包括输出经管道转发时，以防止仓库、Issue、PR 或 Git 服务端返回的内容注入终端控制序列。确实需要为机器处理保留原始字节时，可显式使用全局参数 `--raw-output`，例如 `ag --raw-output pr diff owner/repo 123`；请勿将未经检查的原始输出直接转发到终端。
93
-
94
- ## 命令
95
-
96
- ### 认证
97
-
98
- ```bash
99
- # 浏览器 OAuth 登录并写入令牌文件
100
- ag auth login
101
- # 已登录时会提示无需重复登录；若要重新走浏览器：ag auth login --force
102
-
103
- # 用 refresh_token 刷新 access_token（需之前登录响应里包含 refresh_token）
104
- ag auth refresh
105
-
106
- # 查看认证状态
107
- ag auth status
108
-
109
- # 显示当前 token
110
- ag auth token
111
-
112
- # 删除本地令牌文件
113
- ag auth logout
114
- ```
115
-
116
- 可选环境变量（覆盖默认 OAuth 应用）：`AG_OAUTH_CLIENT_ID`、`AG_OAUTH_CLIENT_SECRET`；若本机 **8765** 端口被占用，可设置 **`AG_OAUTH_REDIRECT_PORT`**（需与 AtomGit 应用配置的回调地址一致）。
117
-
118
- ### 仓库 (repo)
119
-
120
- ```bash
121
- # 列出仓库（默认显示 30 条）
122
- ag repo list
123
-
124
- # 指定最多列出100条仓库
125
- ag repo list --limit 100
126
-
127
- # 查看仓库详情
128
- ag repo view owner/repo
129
-
130
- # 创建仓库
131
- # 在当前用户账号下创建
132
- ag repo create my-project --public
133
-
134
- # 在指定个人或组织账号下创建
135
- ag repo create owner/my-project --public --description "My project"
136
-
137
- # 克隆仓库
138
- ag repo clone owner/repo
139
- ag repo clone owner/repo --branch dev
140
-
141
- # Fork 仓库
142
- ag repo fork owner/repo
143
- ag repo fork owner/repo --name my-fork --public
35
+ ### Nix / NixOS
144
36
 
145
- # 删除仓库
146
- ag repo delete owner/repo --yes
147
- ```
37
+ AtomGit CLI 已进入 `nixos-unstable`，包名为 `atomgit-cli`，安装后提供 `ag` 命令。
148
38
 
149
- ### Pull Request (pr)
39
+ 如果你的 Nix registry 或 flake input 已指向 `nixos-unstable`：
150
40
 
151
41
  ```bash
152
- # 列出 PR
153
- ag pr list owner/repo
154
- ag pr list owner/repo --state closed
155
-
156
- # 查看 PR
157
- ag pr view owner/repo 123
158
-
159
- # 查看 PR diff
160
- ag pr diff owner/repo 123
161
-
162
- # 创建 PR
163
- ag pr create owner/repo --title "Fix bug" --body "Description" --base main --head feature-branch
164
-
165
- # 关闭 PR
166
- ag pr close owner/repo 123
42
+ nix profile install nixpkgs#atomgit-cli
167
43
  ```
168
44
 
169
- #### PR 评论
45
+ 如果你使用的是稳定版 nixpkgs，可以显式从 `nixos-unstable` 安装：
170
46
 
171
47
  ```bash
172
- # 创建评论
173
- ag pr comment create owner/repo 123 --body "LGTM!"
174
- ag pr comment create owner/repo 123 --body-file review.md
175
-
176
- # 查看所有评论（树形结构显示）
177
- ag pr comment view owner/repo 123
178
-
179
- # 编辑评论（交互式编辑）
180
- ag pr comment edit owner/repo 123 456
181
- ag pr comment edit owner/repo 123 456 --body "Updated comment"
182
-
183
- # 删除评论
184
- ag pr comment delete owner/repo 123 456
185
- ag pr comment delete owner/repo 123 456 --yes
186
-
187
- # 回复评论（PR 特有）
188
- ag pr comment reply owner/repo 123 456 --body "Thanks for the feedback!"
48
+ nix profile install github:NixOS/nixpkgs/nixos-unstable#atomgit-cli
189
49
  ```
190
50
 
191
- ### Issue
51
+ ### Go
192
52
 
193
- ```bash
194
- # 列出 Issue
195
- ag issue list owner/repo
196
- ag issue list owner/repo --state all
197
-
198
- # 查看 Issue
199
- ag issue view owner/repo 42
200
-
201
- # 添加 Issue 标签（使用逗号分隔多个标签）
202
- ag issue label owner/repo 42 "bug, help wanted,priority/high"
203
-
204
- # 修改 Issue 标题或正文
205
- ag issue edit owner/repo 42 --title "Updated title"
206
- ag issue edit owner/repo 42 --body "Updated description"
207
- ag issue edit owner/repo 42 --body-file details.md
208
-
209
- # 创建 Issue
210
- ag issue create owner/repo --title "Bug report" --body "Description"
211
- ```
212
-
213
- #### Issue 评论
53
+ 需要 Go 1.24.2 或更高版本。项目正式支持 macOS、Linux 和 Windows；其他 Go 目标平台的兼容性不作保证：
214
54
 
215
55
  ```bash
216
- # 创建评论
217
- ag issue comment create owner/repo 42 --body "I can reproduce this issue"
218
- ag issue comment create owner/repo 42 --body-file details.md
219
-
220
- # 查看所有评论
221
- ag issue comment view owner/repo 42
222
-
223
- # 编辑评论（交互式编辑）
224
- ag issue comment edit owner/repo 42 789
225
- ag issue comment edit owner/repo 42 789 --body "Updated information"
226
-
227
- # 删除评论
228
- ag issue comment delete owner/repo 42 789
229
- ag issue comment delete owner/repo 42 789 --yes
56
+ go install atomgit.com/hust-open-atom-club/atomgit-cli/cmd/ag@latest
230
57
  ```
231
58
 
232
- ### Label
233
-
234
- ```bash
235
- # 列出仓库标签（默认显示 30 条）
236
- ag label list owner/repo
237
- ag label list owner/repo --limit 50
238
- ```
59
+ **注意：** 通过 Go 模块代理安装时，`ag version` 能显示模块版本，但由于模块代理提供的源码包不包含 Git 历史，文本输出会省略无法获得的 commit 和构建时间；`ag version --json` 中对应字段为 `unknown`。这不影响 CLI 功能；如需完整的版本元数据，请使用 npm、Homebrew 或 Release 页面提供的预编译版本。
239
60
 
240
- ### License
61
+ 其他安装方式请参阅[完整安装指南](docs/installation.md)。
241
62
 
242
- ```bash
243
- # 检查 license 合规性
244
- ag license check MIT
245
- ag license check Apache-2.0
246
- ag license check GPL-3.0
247
- ```
63
+ ## 配置
248
64
 
249
- ### SSH Key
65
+ 首次使用时运行 `ag auth login` 完成 OAuth 登录。访问令牌、手动配置、输出安全和仓库推断规则请参阅[配置指南](docs/configuration.md)。
250
66
 
251
- ```bash
252
- # 添加 SSH key
253
- ag ssh-key add ~/.ssh/id_rsa.pub --title "My Laptop"
254
- cat ~/.ssh/id_rsa.pub | ag ssh-key add --title "My Laptop"
255
- ```
67
+ ## 命令
256
68
 
257
- ### 版本
69
+ 完成认证后，可以通过 `ag` 管理 AtomGit 仓库、Issue、Pull Request、Release 和其他资源：
258
70
 
259
71
  ```bash
260
- # 查看版本信息
261
- ag version
262
-
263
- # 等价的根级参数
264
- ag --version
265
-
266
- # 机器可读的 JSON 输出
267
- ag version --json
72
+ ag auth status
73
+ ag repo view
74
+ ag issue list
75
+ ag pr list
76
+ ag --help
268
77
  ```
269
78
 
270
- 通过 `make build` 或 `make install` 从源码构建且未注入发布元数据时，版本默认值为 `dev`。如果 Go 构建信息包含模块版本、源码提交或提交时间，`ag version` 会使用这些信息替代或补充默认值；工作区存在未提交改动时，版本还会带有 dirty 标记。
79
+ 各命令的参数、行为说明和完整示例请参阅[命令使用指南](docs/usage.md)。
271
80
 
272
81
  ## 发布打包
273
82
 
274
- 发布版使用 [GoReleaser](https://goreleaser.com/install/) 打包，tag 统一使用 `vX.Y.Z` 三段式 SemVer。正式发布前应先提交所有改动，并在当前 HEAD 创建版本 tag：
275
-
276
- ```bash
277
- npm run version:npm -- 0.6.0
278
- git tag v0.6.0
279
- make release VERSION=v0.6.0
280
- ```
281
-
282
- `make release` 会检查工作区干净、tag 存在且指向当前 HEAD，然后在 `dist/v0.6.0/` 生成以下文件：
283
-
284
- - Linux 和 macOS 的 amd64/arm64 `.tar.gz` 归档。
285
- - Windows 的 amd64/arm64 `.zip` 归档。
286
- - 已绑定当前 tag 的 `install.sh` 和 `install.ps1`。
287
- - `npm/` 下的六个平台二进制包、一个主启动包和独立的 `npm/checksums.txt`。
288
- - 仅覆盖 AtomGit Release 附件（六个归档和两个安装脚本）的根 `checksums.txt`。
289
-
290
- 发布 npm 制品时，先发布 `npm/` 下六个名称带平台和架构的包；确认它们可用后，再发布 `atomgit-cli` 主包。主包和平台包必须使用相同版本。
291
-
292
- 上传 Release 附件前可校验所有制品：
293
-
294
- ```bash
295
- # Linux
296
- (cd dist/v0.6.0 && sha256sum -c checksums.txt)
297
-
298
- # macOS
299
- (cd dist/v0.6.0 && shasum -a 256 -c checksums.txt)
300
- ```
301
-
302
- npm tarball 不作为 AtomGit Release 附件上传，可在发布到 npm registry 前单独校验：
303
-
304
- ```bash
305
- (cd dist/v0.6.0/npm && shasum -a 256 -c checksums.txt)
306
- ```
307
-
308
- 未创建 tag 时，可使用 `make release-snapshot VERSION=v0.6.0` 进行本地试打包。Snapshot 允许脏工作区，其制品仅用于验证，不应上传到正式 Release。
309
-
310
- 底层 `scripts/build-release.sh` 也接受 `TAG`、`AG_RELEASE_SNAPSHOT=1` 和 `SOURCE_DATE_EPOCH` 环境变量。`SOURCE_DATE_EPOCH` 会同时固定二进制中的构建日期以及归档内文件的时间戳，用于生成可复现的发布制品；历史两段式 tag 仅保留给 snapshot 兼容。
311
-
312
- ### 维护 Nix package
313
-
314
- 更新 Nix package 的版本和 `vendorHash` 时，推荐先进入 flake 提供的开发环境，以使用项目声明的工具版本：
315
-
316
- ```bash
317
- nix develop
318
- ./scripts/update-nix-package.sh v0.6.0
319
- ```
320
-
321
- 也可以直接运行更新脚本：
322
-
323
- ```bash
324
- ./scripts/update-nix-package.sh v0.6.0
325
- ```
326
-
327
- 直接运行需要预先安装 Nix 和 Git，并要求 `tar` 支持以 NUL 分隔的文件列表；Linux 上的 GNU tar 和 macOS 默认的 bsdtar 均受支持。脚本会更新 `flake.nix` 中的版本和 `vendorHash`，随后执行 `nix build .#ag` 和 `ag version --json` 验证。验证失败时会自动恢复原始 `flake.nix`，且脚本不会提交、打标签或推送。
83
+ GoReleaser、npm 制品和 Nix package 的发布与维护流程请参阅[发布指南](docs/releasing.md)。
328
84
 
329
85
  ## 项目结构
330
86
 
331
- ```
332
- atomgit-cli/
333
- ├── .goreleaser.yaml # GoReleaser 跨平台打包配置
334
- ├── Makefile # 构建、测试、安装和发布入口
335
- ├── install.sh # Linux/macOS 安装脚本
336
- ├── install.ps1 # Windows 安装脚本
337
- ├── bin/ag.js # npm 主包的平台二进制启动器
338
- ├── scripts/build-npm-packages.js # 从 Release 归档生成七个 npm 包
339
- ├── cmd/ag/main.go # 入口
340
- ├── internal/
341
- │ ├── agcmd/cmd.go # 核心命令处理
342
- │ ├── config/config.go # 配置管理
343
- │ ├── version/version.go # 版本元数据
344
- │ └── api/
345
- │ ├── client.go # API 客户端
346
- │ └── types.go # 数据类型
347
- ├── pkg/
348
- │ ├── cmdutil/factory.go # 命令工厂
349
- │ └── cmd/
350
- │ ├── root/root.go # 根命令
351
- │ ├── auth/auth.go # 认证命令
352
- │ ├── repo/ # 仓库命令
353
- │ │ ├── repo.go
354
- │ │ ├── create.go
355
- │ │ ├── clone.go
356
- │ │ ├── delete.go
357
- │ │ └── fork.go
358
- │ ├── pr/ # PR 命令
359
- │ │ ├── pr.go
360
- │ │ └── comment/ # PR 评论命令
361
- │ ├── issue/ # Issue 命令
362
- │ │ ├── issue.go
363
- │ │ └── comment/ # Issue 评论命令
364
- │ ├── label/ # 标签命令
365
- │ │ └── label.go
366
- │ ├── license/ # License 命令
367
- │ │ ├── license.go
368
- │ │ └── check.go
369
- │ ├── ssh-key/ssh_key.go # SSH key 命令
370
- │ └── version/version.go # 版本命令
371
- ├── scripts/build-release.sh # GoReleaser 打包包装脚本
372
- └── go.mod
373
- ```
87
+ CLI 的主要执行流程为 `cmd/ag` → `internal/agcmd` → `pkg/cmd/root` → 各命令包。目录职责、命令包列表和扩展方式请参阅[项目结构说明](docs/project-structure.md)。
374
88
 
375
89
  ## API
376
90
 
377
- 使用 AtomGit API v5: `https://api.atomgit.com/api/v5`
91
+ 常规仓库功能使用 AtomGit API v5：`https://api.atomgit.com/api/v5`。
92
+
93
+ Actions 运行检查使用独立的 AtomGit API v8：`https://api.atomgit.com/api/v8`。
378
94
 
379
95
  ## 参考
380
96
 
@@ -385,4 +101,4 @@ atomgit-cli/
385
101
 
386
102
  [木兰宽松许可证第2版](LICENSE) (Mulan Permissive Software License, Version 2)
387
103
 
388
- Copyright (c) 2026 AtomGit CLI Contributors
104
+ Copyright (c) 2026 HUST OpenAtom Club, AtomGit, and the AtomGit CLI contributors
package/bin/ag.js CHANGED
@@ -6,6 +6,7 @@ const PLATFORM_PACKAGES = {
6
6
  "darwin-arm64": "@hust-open-atom-club/atomgit-cli-darwin-arm64",
7
7
  "darwin-x64": "@hust-open-atom-club/atomgit-cli-darwin-x64",
8
8
  "linux-arm64": "@hust-open-atom-club/atomgit-cli-linux-arm64",
9
+ "linux-loong64": "@hust-open-atom-club/atomgit-cli-linux-loong64",
9
10
  "linux-x64": "@hust-open-atom-club/atomgit-cli-linux-x64",
10
11
  "win32-arm64": "@hust-open-atom-club/atomgit-cli-win32-arm64",
11
12
  "win32-x64": "@hust-open-atom-club/atomgit-cli-win32-x64",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hust-open-atom-club/atomgit-cli",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "AtomGit command-line interface",
5
5
  "license": "MulanPSL-2.0",
6
6
  "repository": {
@@ -28,12 +28,13 @@
28
28
  "version:npm": "node scripts/set-npm-version.js"
29
29
  },
30
30
  "optionalDependencies": {
31
- "@hust-open-atom-club/atomgit-cli-darwin-arm64": "0.6.0",
32
- "@hust-open-atom-club/atomgit-cli-darwin-x64": "0.6.0",
33
- "@hust-open-atom-club/atomgit-cli-linux-arm64": "0.6.0",
34
- "@hust-open-atom-club/atomgit-cli-linux-x64": "0.6.0",
35
- "@hust-open-atom-club/atomgit-cli-win32-arm64": "0.6.0",
36
- "@hust-open-atom-club/atomgit-cli-win32-x64": "0.6.0"
31
+ "@hust-open-atom-club/atomgit-cli-darwin-arm64": "0.7.0",
32
+ "@hust-open-atom-club/atomgit-cli-darwin-x64": "0.7.0",
33
+ "@hust-open-atom-club/atomgit-cli-linux-arm64": "0.7.0",
34
+ "@hust-open-atom-club/atomgit-cli-linux-loong64": "0.7.0",
35
+ "@hust-open-atom-club/atomgit-cli-linux-x64": "0.7.0",
36
+ "@hust-open-atom-club/atomgit-cli-win32-arm64": "0.7.0",
37
+ "@hust-open-atom-club/atomgit-cli-win32-x64": "0.7.0"
37
38
  },
38
39
  "devDependencies": {
39
40
  "adm-zip": "^0.6.0",