gitcode-cli 0.10.3__tar.gz → 0.11.0__tar.gz

{gitcode_cli-0.10.3/gitcode_cli.egg-info → gitcode_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitcode-cli
-Version: 0.10.3
+Version: 0.11.0
 Summary: GitCode CLI - Command line tool for GitCode
 Author-email: GitCode CLI Contributors <support@gitcode.com>
 Maintainer-email: GitCode CLI Contributors <support@gitcode.com>
@@ -67,6 +67,17 @@ GitCode CLI 把仓库、Issue、PR、Release 和 Actions 带回终端，让开
 
 ## 安装
 
+推荐只让一个全局安装渠道拥有 `gc` / `gitcode`。Windows 普通用户和 Node/AI 环境优先使用 npm；macOS 优先 Homebrew；Debian/Ubuntu 优先 DEB；RHEL/Fedora 优先 RPM。Python wheel 建议放入 `pipx` 或虚拟环境，CI 建议固定版本并校验 checksum。
+
+安装或升级后可离线检查实际命令来源和全部 PATH 候选：
+
+```bash
+gitcode doctor install
+gitcode doctor install --json
+```
+
+诊断只读取公开的可执行文件、PATH 和本地安装 manifest，不读取认证配置或 Token，也不会卸载其他渠道或修改 PATH。
+
 ### 从源码构建
 
 **前置要求:**
@@ -83,11 +94,8 @@ go build -o gc ./cmd/gc
 mkdir -p ~/.local/bin
 mv gc ~/.local/bin/
 
-# 方式二：使用 make build（带完整版本标签）
-make build
-# 安装
-mkdir -p ~/.local/bin
-mv bin/gc ~/.local/bin/
+# 方式二：构建并安装 gc/gitcode（带完整版本标签）
+make install PREFIX="$HOME/.local"
 
 # 添加到 PATH
 export PATH="$HOME/.local/bin:$PATH"
@@ -103,10 +111,10 @@ export PATH="$HOME/.local/bin:$PATH"
 
 ```bash
 # 从 Releases 下载 .deb 包
-wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gc_0.10.3_amd64.deb
+wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gc_0.11.0_amd64.deb
 
 # 安装
-sudo dpkg -i gc_0.10.3_amd64.deb
+sudo dpkg -i gc_0.11.0_amd64.deb
 ```
 
 DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
@@ -115,15 +123,15 @@ DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
 
 ```bash
 # 从 Releases 下载 .rpm 包
-wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gc-0.10.3-1.x86_64.rpm
+wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gc-0.11.0-1.x86_64.rpm
 
 # 安装
-sudo rpm -i gc-0.10.3-1.x86_64.rpm
+sudo rpm -i gc-0.11.0-1.x86_64.rpm
 ```
 
 DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
 
-### Wheel 包（跨平台，推荐）
+### Wheel 包（跨平台、隔离安装）
 
 从 Release 归档下载 wheel 包安装，**内置全平台二进制**（Linux x64/ARM、macOS Intel/Apple Silicon、Windows x64）：
 
@@ -134,7 +142,7 @@ source .venv/bin/activate  # Linux/macOS
 # .\.venv\Scripts\Activate.ps1  # Windows PowerShell
 
 # 安装（一行命令）
-pip install https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gitcode_cli-0.10.3-py3-none-any.whl
+pip install https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gitcode_cli-0.11.0-py3-none-any.whl
 
 # Windows PowerShell 中推荐使用 gitcode，避免 gc 被内置 Get-Content 别名覆盖
 gitcode version
@@ -143,6 +151,7 @@ gitcode version
 说明：
 - wheel 会同时安装 `gc` 和 `gitcode` 两个命令入口，功能相同。
 - DEB/RPM 包也会同时安装 `gc` 和 `gitcode`；Linux 上二者功能相同。
+- 不建议让 pip user install 与 DEB/RPM/Homebrew/npm 同时提供全局命令。已混用时先运行 `gitcode doctor install` 确认实际选中路径，再由用户明确选择调整 PATH、升级原渠道或卸载旧渠道；CLI 不会代替用户调用其他包管理器。
 - Windows 使用 `py -m pip install --user ...` 时，脚本会安装到 Python user scheme 的 `Scripts` 目录。请运行 `py -c "import os, sysconfig; print(sysconfig.get_path('scripts', os.name + '_user'))"` 获取准确路径，将其加入用户 `PATH` 后重新打开终端；配置前可直接运行 `py -m gc_cli version`。
 - Windows PowerShell 预置 `gc` 作为 `Get-Content` 别名；如果 `gc version` 被解析为读取文件，请改用 `gitcode version`、`gc.exe version` 或 `py -m gc_cli version`。
 - Windows PowerShell 中通过 `--body-file -` / `--comment-file -` 管道传入中文或其他非 ASCII 正文时，推荐使用 UTF-8 文件；如果必须直接管道，先设置 `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)`。CLI 会拦截疑似已被 PowerShell 损坏成 `???` 的输入并提示正确用法。
@@ -163,7 +172,7 @@ source .venv/bin/activate  # Linux/macOS
 # .\.venv\Scripts\Activate.ps1  # Windows PowerShell
 
 # 固定版本安装，避免 PyPI 尚未同步时安装旧版本
-python -m pip install -i https://pypi.org/simple/ gitcode-cli==0.10.3
+python -m pip install -i https://pypi.org/simple/ gitcode-cli==0.11.0
 
 # Windows PowerShell 中推荐使用 gitcode
 gitcode version
@@ -185,13 +194,16 @@ gitcode version
 ```bash
 chmod +x gc_linux_amd64
 mv gc_linux_amd64 ~/.local/bin/gc
+ln -s gc ~/.local/bin/gitcode
 gc version
 ```
 
-Windows 和 macOS 用户建议使用上方 wheel 包；wheel 内置 Linux、macOS 和 Windows 二进制，并同时提供 `gc` 与 `gitcode` 两个命令入口。
+需要与系统包管理器隔离时可使用上方 wheel；需要免安装直接部署时使用独立二进制。二者都应先确认平台架构受支持。
 
 ### Docker 镜像
 
+> **用途说明**：本仓库 Docker 配置面向开发/构建环境。`docker compose up gc` 默认执行 `gc --help` 展示用法后退出（CLI 工具非长期服务）。交互式使用 `docker run -it --entrypoint bash gitcode/gc:dev`（进入 shell）或 `docker run -it gitcode/gc:dev <子命令>`（如 `auth login`）。
+
 仓库已提供 `Dockerfile`、`docker-compose.yml` 和 Makefile 目标：
 
 ```bash
@@ -227,6 +239,7 @@ brew upgrade gc
 ```
 
 shell 补全（bash/zsh/fish）随安装自动配置，无需额外操作。
+Homebrew 同时提供 `gc` 与 `gitcode`；升级后可运行 `gitcode doctor install` 检查是否仍被 pip/npm 旧入口遮蔽。
 
 ### npm (跨平台)
 
@@ -240,10 +253,39 @@ npx @gitcode-cli/cli@latest install
 
 ```bash
 npm install -g @gitcode-cli/cli
-gc version
+gitcode version
 ```
 
-包内置 Linux/macOS/Windows 多平台二进制；shell 补全（bash/zsh/fish）由 `install` 子命令自动配置。
+如果 `gitcode version` 仍显示旧的 pip/wheel 版本，先直接调用 npm 安装目录中的新入口诊断，不必先卸载 pip：
+
+```powershell
+# Windows PowerShell
+& "$(npm prefix -g)\gitcode.cmd" doctor install --json
+```
+
+```bash
+# Linux/macOS
+"$(npm prefix -g)/bin/gitcode" doctor install --json
+```
+
+包内置 Linux/macOS/Windows 多平台二进制。Windows bootstrap 同时安装 `gc.exe` 和 `gitcode.exe`，PowerShell 请使用 `gitcode`，避免内置 `gc`/`Get-Content` alias。
+
+npm global 与 npm bootstrap 默认使用 `notify` 模式：命令本身立即执行，24 小时 TTL 到期后在后台检查 stable `latest`，发现新版后在下一次启动提示 `gitcode update`，不会自动安装，也不会改变刚完成命令的退出码。需要自动应用的用户可明确启用 `auto`；该模式具有跨进程锁、版本健康检查和失败回滚。
+
+```bash
+gitcode update --check       # 只检查
+gitcode update               # 显式更新当前 npm 渠道
+gitcode update --json
+
+gitcode config set update.mode auto
+gitcode config set update.mode notify
+gitcode config set update.mode off
+
+gitcode --no-update-check version   # 单次禁用
+GC_NO_UPDATE_CHECK=1 gitcode version
+```
+
+`CI=true`、`--no-interactive`、`--no-update-check` 或 `GC_NO_UPDATE_CHECK=1` 会禁用后台检查。更新器仅从官方 `https://registry.npmjs.org` 获取精确 stable 版本，安装时禁用生命周期脚本，并以最小环境启动；它不会调用 pip、Homebrew、apt、dnf，也不会静默修改 PATH。npm 生命周期脚本被组织策略禁用时，可直接运行 npm prefix 中的 `gitcode` 再执行 `doctor install`；wrapper 会在首次直接运行时补建来源 metadata。
 
 ### 规划中的安装方式
 
@@ -381,6 +423,9 @@ gitcode actions artifact download <artifact-id> -R owner/repo --output artifact.
 # 删除 artifact
 gitcode actions artifact delete <artifact-id> -R owner/repo --yes
 
+# 校验 workflow YAML
+gitcode actions yaml validate --file .gitcode/workflows/ci.yml -R owner/repo
+
 # 调用 GitCode API 原始响应
 gitcode api repos/owner/repo
 

{gitcode_cli-0.10.3 → gitcode_cli-0.11.0}/README.md

@@ -38,6 +38,17 @@ GitCode CLI 把仓库、Issue、PR、Release 和 Actions 带回终端，让开
 
 ## 安装
 
+推荐只让一个全局安装渠道拥有 `gc` / `gitcode`。Windows 普通用户和 Node/AI 环境优先使用 npm；macOS 优先 Homebrew；Debian/Ubuntu 优先 DEB；RHEL/Fedora 优先 RPM。Python wheel 建议放入 `pipx` 或虚拟环境，CI 建议固定版本并校验 checksum。
+
+安装或升级后可离线检查实际命令来源和全部 PATH 候选：
+
+```bash
+gitcode doctor install
+gitcode doctor install --json
+```
+
+诊断只读取公开的可执行文件、PATH 和本地安装 manifest，不读取认证配置或 Token，也不会卸载其他渠道或修改 PATH。
+
 ### 从源码构建
 
 **前置要求:**
@@ -54,11 +65,8 @@ go build -o gc ./cmd/gc
 mkdir -p ~/.local/bin
 mv gc ~/.local/bin/
 
-# 方式二：使用 make build（带完整版本标签）
-make build
-# 安装
-mkdir -p ~/.local/bin
-mv bin/gc ~/.local/bin/
+# 方式二：构建并安装 gc/gitcode（带完整版本标签）
+make install PREFIX="$HOME/.local"
 
 # 添加到 PATH
 export PATH="$HOME/.local/bin:$PATH"
@@ -74,10 +82,10 @@ export PATH="$HOME/.local/bin:$PATH"
 
 ```bash
 # 从 Releases 下载 .deb 包
-wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gc_0.10.3_amd64.deb
+wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gc_0.11.0_amd64.deb
 
 # 安装
-sudo dpkg -i gc_0.10.3_amd64.deb
+sudo dpkg -i gc_0.11.0_amd64.deb
 ```
 
 DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
@@ -86,15 +94,15 @@ DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
 
 ```bash
 # 从 Releases 下载 .rpm 包
-wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gc-0.10.3-1.x86_64.rpm
+wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gc-0.11.0-1.x86_64.rpm
 
 # 安装
-sudo rpm -i gc-0.10.3-1.x86_64.rpm
+sudo rpm -i gc-0.11.0-1.x86_64.rpm
 ```
 
 DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
 
-### Wheel 包（跨平台，推荐）
+### Wheel 包（跨平台、隔离安装）
 
 从 Release 归档下载 wheel 包安装，**内置全平台二进制**（Linux x64/ARM、macOS Intel/Apple Silicon、Windows x64）：
 
@@ -105,7 +113,7 @@ source .venv/bin/activate  # Linux/macOS
 # .\.venv\Scripts\Activate.ps1  # Windows PowerShell
 
 # 安装（一行命令）
-pip install https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gitcode_cli-0.10.3-py3-none-any.whl
+pip install https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gitcode_cli-0.11.0-py3-none-any.whl
 
 # Windows PowerShell 中推荐使用 gitcode，避免 gc 被内置 Get-Content 别名覆盖
 gitcode version
@@ -114,6 +122,7 @@ gitcode version
 说明：
 - wheel 会同时安装 `gc` 和 `gitcode` 两个命令入口，功能相同。
 - DEB/RPM 包也会同时安装 `gc` 和 `gitcode`；Linux 上二者功能相同。
+- 不建议让 pip user install 与 DEB/RPM/Homebrew/npm 同时提供全局命令。已混用时先运行 `gitcode doctor install` 确认实际选中路径，再由用户明确选择调整 PATH、升级原渠道或卸载旧渠道；CLI 不会代替用户调用其他包管理器。
 - Windows 使用 `py -m pip install --user ...` 时，脚本会安装到 Python user scheme 的 `Scripts` 目录。请运行 `py -c "import os, sysconfig; print(sysconfig.get_path('scripts', os.name + '_user'))"` 获取准确路径，将其加入用户 `PATH` 后重新打开终端；配置前可直接运行 `py -m gc_cli version`。
 - Windows PowerShell 预置 `gc` 作为 `Get-Content` 别名；如果 `gc version` 被解析为读取文件，请改用 `gitcode version`、`gc.exe version` 或 `py -m gc_cli version`。
 - Windows PowerShell 中通过 `--body-file -` / `--comment-file -` 管道传入中文或其他非 ASCII 正文时，推荐使用 UTF-8 文件；如果必须直接管道，先设置 `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)`。CLI 会拦截疑似已被 PowerShell 损坏成 `???` 的输入并提示正确用法。
@@ -134,7 +143,7 @@ source .venv/bin/activate  # Linux/macOS
 # .\.venv\Scripts\Activate.ps1  # Windows PowerShell
 
 # 固定版本安装，避免 PyPI 尚未同步时安装旧版本
-python -m pip install -i https://pypi.org/simple/ gitcode-cli==0.10.3
+python -m pip install -i https://pypi.org/simple/ gitcode-cli==0.11.0
 
 # Windows PowerShell 中推荐使用 gitcode
 gitcode version
@@ -156,13 +165,16 @@ gitcode version
 ```bash
 chmod +x gc_linux_amd64
 mv gc_linux_amd64 ~/.local/bin/gc
+ln -s gc ~/.local/bin/gitcode
 gc version
 ```
 
-Windows 和 macOS 用户建议使用上方 wheel 包；wheel 内置 Linux、macOS 和 Windows 二进制，并同时提供 `gc` 与 `gitcode` 两个命令入口。
+需要与系统包管理器隔离时可使用上方 wheel；需要免安装直接部署时使用独立二进制。二者都应先确认平台架构受支持。
 
 ### Docker 镜像
 
+> **用途说明**：本仓库 Docker 配置面向开发/构建环境。`docker compose up gc` 默认执行 `gc --help` 展示用法后退出（CLI 工具非长期服务）。交互式使用 `docker run -it --entrypoint bash gitcode/gc:dev`（进入 shell）或 `docker run -it gitcode/gc:dev <子命令>`（如 `auth login`）。
+
 仓库已提供 `Dockerfile`、`docker-compose.yml` 和 Makefile 目标：
 
 ```bash
@@ -198,6 +210,7 @@ brew upgrade gc
 ```
 
 shell 补全（bash/zsh/fish）随安装自动配置，无需额外操作。
+Homebrew 同时提供 `gc` 与 `gitcode`；升级后可运行 `gitcode doctor install` 检查是否仍被 pip/npm 旧入口遮蔽。
 
 ### npm (跨平台)
 
@@ -211,10 +224,39 @@ npx @gitcode-cli/cli@latest install
 
 ```bash
 npm install -g @gitcode-cli/cli
-gc version
+gitcode version
 ```
 
-包内置 Linux/macOS/Windows 多平台二进制；shell 补全（bash/zsh/fish）由 `install` 子命令自动配置。
+如果 `gitcode version` 仍显示旧的 pip/wheel 版本，先直接调用 npm 安装目录中的新入口诊断，不必先卸载 pip：
+
+```powershell
+# Windows PowerShell
+& "$(npm prefix -g)\gitcode.cmd" doctor install --json
+```
+
+```bash
+# Linux/macOS
+"$(npm prefix -g)/bin/gitcode" doctor install --json
+```
+
+包内置 Linux/macOS/Windows 多平台二进制。Windows bootstrap 同时安装 `gc.exe` 和 `gitcode.exe`，PowerShell 请使用 `gitcode`，避免内置 `gc`/`Get-Content` alias。
+
+npm global 与 npm bootstrap 默认使用 `notify` 模式：命令本身立即执行，24 小时 TTL 到期后在后台检查 stable `latest`，发现新版后在下一次启动提示 `gitcode update`，不会自动安装，也不会改变刚完成命令的退出码。需要自动应用的用户可明确启用 `auto`；该模式具有跨进程锁、版本健康检查和失败回滚。
+
+```bash
+gitcode update --check       # 只检查
+gitcode update               # 显式更新当前 npm 渠道
+gitcode update --json
+
+gitcode config set update.mode auto
+gitcode config set update.mode notify
+gitcode config set update.mode off
+
+gitcode --no-update-check version   # 单次禁用
+GC_NO_UPDATE_CHECK=1 gitcode version
+```
+
+`CI=true`、`--no-interactive`、`--no-update-check` 或 `GC_NO_UPDATE_CHECK=1` 会禁用后台检查。更新器仅从官方 `https://registry.npmjs.org` 获取精确 stable 版本，安装时禁用生命周期脚本，并以最小环境启动；它不会调用 pip、Homebrew、apt、dnf，也不会静默修改 PATH。npm 生命周期脚本被组织策略禁用时，可直接运行 npm prefix 中的 `gitcode` 再执行 `doctor install`；wrapper 会在首次直接运行时补建来源 metadata。
 
 ### 规划中的安装方式
 
@@ -352,6 +394,9 @@ gitcode actions artifact download <artifact-id> -R owner/repo --output artifact.
 # 删除 artifact
 gitcode actions artifact delete <artifact-id> -R owner/repo --yes
 
+# 校验 workflow YAML
+gitcode actions yaml validate --file .gitcode/workflows/ci.yml -R owner/repo
+
 # 调用 GitCode API 原始响应
 gitcode api repos/owner/repo
 

{gitcode_cli-0.10.3 → gitcode_cli-0.11.0}/gc_cli/__init__.py

@@ -4,7 +4,7 @@ GitCode CLI - Command line tool for GitCode.
 This package provides a Python wrapper for the gc binary.
 """
 
-__version__ = "0.10.3"
+__version__ = "0.11.0"
 __author__ = "GitCode CLI Contributors"
 __all__ = ["__version__", "main"]
 

{gitcode_cli-0.10.3 → gitcode_cli-0.11.0}/gc_cli/wrapper.py

@@ -12,6 +12,9 @@ import sys
 from pathlib import Path
 
 COMMAND_NAME_ENV = "GITCODE_CLI_COMMAND_NAME"
+DISTRIBUTION_ENV = "GITCODE_CLI_DISTRIBUTION"
+ENTRYPOINT_ENV = "GITCODE_CLI_ENTRYPOINT"
+BINARY_ENV = "GITCODE_CLI_BINARY"
 
 
 def get_binary_name() -> str:
@@ -26,14 +29,16 @@ def get_binary_name() -> str:
         "aarch64": "arm64",
         "arm64": "arm64",
     }
-    arch = arch_map.get(machine, "amd64")
+    arch = arch_map.get(machine)
+    if arch is None:
+        raise RuntimeError(f"Unsupported platform: {system} {machine}")
 
     # Map system to binary name
     if system == "linux":
         return f"gc-linux-{arch}"
     elif system == "darwin":
         return f"gc-darwin-{arch}"
-    elif system == "windows":
+    elif system == "windows" and arch == "amd64":
         return "gc-windows-amd64.exe"
     else:
         raise RuntimeError(f"Unsupported platform: {system} {machine}")
@@ -80,6 +85,9 @@ def main() -> int:
         ensure_executable(binary_path)
         env = os.environ.copy()
         env.setdefault(COMMAND_NAME_ENV, get_command_name())
+        env.setdefault(DISTRIBUTION_ENV, "pypi")
+        env.setdefault(ENTRYPOINT_ENV, str(Path(sys.argv[0]).resolve()))
+        env.setdefault(BINARY_ENV, str(binary_path.resolve()))
 
         # Run the binary with all arguments
         result = subprocess.run(

{gitcode_cli-0.10.3 → gitcode_cli-0.11.0/gitcode_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitcode-cli
-Version: 0.10.3
+Version: 0.11.0
 Summary: GitCode CLI - Command line tool for GitCode
 Author-email: GitCode CLI Contributors <support@gitcode.com>
 Maintainer-email: GitCode CLI Contributors <support@gitcode.com>
@@ -67,6 +67,17 @@ GitCode CLI 把仓库、Issue、PR、Release 和 Actions 带回终端，让开
 
 ## 安装
 
+推荐只让一个全局安装渠道拥有 `gc` / `gitcode`。Windows 普通用户和 Node/AI 环境优先使用 npm；macOS 优先 Homebrew；Debian/Ubuntu 优先 DEB；RHEL/Fedora 优先 RPM。Python wheel 建议放入 `pipx` 或虚拟环境，CI 建议固定版本并校验 checksum。
+
+安装或升级后可离线检查实际命令来源和全部 PATH 候选：
+
+```bash
+gitcode doctor install
+gitcode doctor install --json
+```
+
+诊断只读取公开的可执行文件、PATH 和本地安装 manifest，不读取认证配置或 Token，也不会卸载其他渠道或修改 PATH。
+
 ### 从源码构建
 
 **前置要求:**
@@ -83,11 +94,8 @@ go build -o gc ./cmd/gc
 mkdir -p ~/.local/bin
 mv gc ~/.local/bin/
 
-# 方式二：使用 make build（带完整版本标签）
-make build
-# 安装
-mkdir -p ~/.local/bin
-mv bin/gc ~/.local/bin/
+# 方式二：构建并安装 gc/gitcode（带完整版本标签）
+make install PREFIX="$HOME/.local"
 
 # 添加到 PATH
 export PATH="$HOME/.local/bin:$PATH"
@@ -103,10 +111,10 @@ export PATH="$HOME/.local/bin:$PATH"
 
 ```bash
 # 从 Releases 下载 .deb 包
-wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gc_0.10.3_amd64.deb
+wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gc_0.11.0_amd64.deb
 
 # 安装
-sudo dpkg -i gc_0.10.3_amd64.deb
+sudo dpkg -i gc_0.11.0_amd64.deb
 ```
 
 DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
@@ -115,15 +123,15 @@ DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
 
 ```bash
 # 从 Releases 下载 .rpm 包
-wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gc-0.10.3-1.x86_64.rpm
+wget https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gc-0.11.0-1.x86_64.rpm
 
 # 安装
-sudo rpm -i gc-0.10.3-1.x86_64.rpm
+sudo rpm -i gc-0.11.0-1.x86_64.rpm
 ```
 
 DEB/RPM packages install both `gc` and `gitcode`; on Linux they are equivalent.
 
-### Wheel 包（跨平台，推荐）
+### Wheel 包（跨平台、隔离安装）
 
 从 Release 归档下载 wheel 包安装，**内置全平台二进制**（Linux x64/ARM、macOS Intel/Apple Silicon、Windows x64）：
 
@@ -134,7 +142,7 @@ source .venv/bin/activate  # Linux/macOS
 # .\.venv\Scripts\Activate.ps1  # Windows PowerShell
 
 # 安装（一行命令）
-pip install https://gitcode.com/gitcode-cli/cli/releases/download/v0.10.3/gitcode_cli-0.10.3-py3-none-any.whl
+pip install https://gitcode.com/gitcode-cli/cli/releases/download/v0.11.0/gitcode_cli-0.11.0-py3-none-any.whl
 
 # Windows PowerShell 中推荐使用 gitcode，避免 gc 被内置 Get-Content 别名覆盖
 gitcode version
@@ -143,6 +151,7 @@ gitcode version
 说明：
 - wheel 会同时安装 `gc` 和 `gitcode` 两个命令入口，功能相同。
 - DEB/RPM 包也会同时安装 `gc` 和 `gitcode`；Linux 上二者功能相同。
+- 不建议让 pip user install 与 DEB/RPM/Homebrew/npm 同时提供全局命令。已混用时先运行 `gitcode doctor install` 确认实际选中路径，再由用户明确选择调整 PATH、升级原渠道或卸载旧渠道；CLI 不会代替用户调用其他包管理器。
 - Windows 使用 `py -m pip install --user ...` 时，脚本会安装到 Python user scheme 的 `Scripts` 目录。请运行 `py -c "import os, sysconfig; print(sysconfig.get_path('scripts', os.name + '_user'))"` 获取准确路径，将其加入用户 `PATH` 后重新打开终端；配置前可直接运行 `py -m gc_cli version`。
 - Windows PowerShell 预置 `gc` 作为 `Get-Content` 别名；如果 `gc version` 被解析为读取文件，请改用 `gitcode version`、`gc.exe version` 或 `py -m gc_cli version`。
 - Windows PowerShell 中通过 `--body-file -` / `--comment-file -` 管道传入中文或其他非 ASCII 正文时，推荐使用 UTF-8 文件；如果必须直接管道，先设置 `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)`。CLI 会拦截疑似已被 PowerShell 损坏成 `???` 的输入并提示正确用法。
@@ -163,7 +172,7 @@ source .venv/bin/activate  # Linux/macOS
 # .\.venv\Scripts\Activate.ps1  # Windows PowerShell
 
 # 固定版本安装，避免 PyPI 尚未同步时安装旧版本
-python -m pip install -i https://pypi.org/simple/ gitcode-cli==0.10.3
+python -m pip install -i https://pypi.org/simple/ gitcode-cli==0.11.0
 
 # Windows PowerShell 中推荐使用 gitcode
 gitcode version
@@ -185,13 +194,16 @@ gitcode version
 ```bash
 chmod +x gc_linux_amd64
 mv gc_linux_amd64 ~/.local/bin/gc
+ln -s gc ~/.local/bin/gitcode
 gc version
 ```
 
-Windows 和 macOS 用户建议使用上方 wheel 包；wheel 内置 Linux、macOS 和 Windows 二进制，并同时提供 `gc` 与 `gitcode` 两个命令入口。
+需要与系统包管理器隔离时可使用上方 wheel；需要免安装直接部署时使用独立二进制。二者都应先确认平台架构受支持。
 
 ### Docker 镜像
 
+> **用途说明**：本仓库 Docker 配置面向开发/构建环境。`docker compose up gc` 默认执行 `gc --help` 展示用法后退出（CLI 工具非长期服务）。交互式使用 `docker run -it --entrypoint bash gitcode/gc:dev`（进入 shell）或 `docker run -it gitcode/gc:dev <子命令>`（如 `auth login`）。
+
 仓库已提供 `Dockerfile`、`docker-compose.yml` 和 Makefile 目标：
 
 ```bash
@@ -227,6 +239,7 @@ brew upgrade gc
 ```
 
 shell 补全（bash/zsh/fish）随安装自动配置，无需额外操作。
+Homebrew 同时提供 `gc` 与 `gitcode`；升级后可运行 `gitcode doctor install` 检查是否仍被 pip/npm 旧入口遮蔽。
 
 ### npm (跨平台)
 
@@ -240,10 +253,39 @@ npx @gitcode-cli/cli@latest install
 
 ```bash
 npm install -g @gitcode-cli/cli
-gc version
+gitcode version
 ```
 
-包内置 Linux/macOS/Windows 多平台二进制；shell 补全（bash/zsh/fish）由 `install` 子命令自动配置。
+如果 `gitcode version` 仍显示旧的 pip/wheel 版本，先直接调用 npm 安装目录中的新入口诊断，不必先卸载 pip：
+
+```powershell
+# Windows PowerShell
+& "$(npm prefix -g)\gitcode.cmd" doctor install --json
+```
+
+```bash
+# Linux/macOS
+"$(npm prefix -g)/bin/gitcode" doctor install --json
+```
+
+包内置 Linux/macOS/Windows 多平台二进制。Windows bootstrap 同时安装 `gc.exe` 和 `gitcode.exe`，PowerShell 请使用 `gitcode`，避免内置 `gc`/`Get-Content` alias。
+
+npm global 与 npm bootstrap 默认使用 `notify` 模式：命令本身立即执行，24 小时 TTL 到期后在后台检查 stable `latest`，发现新版后在下一次启动提示 `gitcode update`，不会自动安装，也不会改变刚完成命令的退出码。需要自动应用的用户可明确启用 `auto`；该模式具有跨进程锁、版本健康检查和失败回滚。
+
+```bash
+gitcode update --check       # 只检查
+gitcode update               # 显式更新当前 npm 渠道
+gitcode update --json
+
+gitcode config set update.mode auto
+gitcode config set update.mode notify
+gitcode config set update.mode off
+
+gitcode --no-update-check version   # 单次禁用
+GC_NO_UPDATE_CHECK=1 gitcode version
+```
+
+`CI=true`、`--no-interactive`、`--no-update-check` 或 `GC_NO_UPDATE_CHECK=1` 会禁用后台检查。更新器仅从官方 `https://registry.npmjs.org` 获取精确 stable 版本，安装时禁用生命周期脚本，并以最小环境启动；它不会调用 pip、Homebrew、apt、dnf，也不会静默修改 PATH。npm 生命周期脚本被组织策略禁用时，可直接运行 npm prefix 中的 `gitcode` 再执行 `doctor install`；wrapper 会在首次直接运行时补建来源 metadata。
 
 ### 规划中的安装方式
 
@@ -381,6 +423,9 @@ gitcode actions artifact download <artifact-id> -R owner/repo --output artifact.
 # 删除 artifact
 gitcode actions artifact delete <artifact-id> -R owner/repo --yes
 
+# 校验 workflow YAML
+gitcode actions yaml validate --file .gitcode/workflows/ci.yml -R owner/repo
+
 # 调用 GitCode API 原始响应
 gitcode api repos/owner/repo
 

{gitcode_cli-0.10.3 → gitcode_cli-0.11.0}/gitcode_cli.egg-info/SOURCES.txt

@@ -16,4 +16,5 @@ gitcode_cli.egg-info/SOURCES.txt
 gitcode_cli.egg-info/dependency_links.txt
 gitcode_cli.egg-info/entry_points.txt
 gitcode_cli.egg-info/top_level.txt
+tests/test_verify_remote_facts.py
 tests/test_wrapper.py

{gitcode_cli-0.10.3 → gitcode_cli-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitcode-cli"
-version = "0.10.3"
+version = "0.11.0"
 description = "GitCode CLI - Command line tool for GitCode"
 readme = "README.md"
 license = "MIT"

gitcode_cli-0.11.0/tests/test_verify_remote_facts.py

@@ -0,0 +1,46 @@
+import importlib.util
+import json
+import sys
+import unittest
+from pathlib import Path
+from unittest import mock
+
+# verify-remote-facts.py has a hyphen in its name so it cannot be imported
+# normally; load it via importlib and register it so mock.patch can find it.
+_spec = importlib.util.spec_from_file_location(
+    "verify_remote_facts",
+    Path(__file__).parent.parent / "scripts" / "verify-remote-facts.py",
+)
+vrf = importlib.util.module_from_spec(_spec)
+sys.modules["verify_remote_facts"] = vrf
+_spec.loader.exec_module(vrf)
+
+
+class VerifyRemoteFactsEncodingTests(unittest.TestCase):
+    def test_run_json_decodes_utf8_chinese(self):
+        """run_json must decode UTF-8 Chinese JSON output (Windows GBK fix #479)."""
+        chinese_json = json.dumps({"title": "修复中文测试", "state": "closed"})
+        mock_result = mock.Mock(returncode=0, stdout=chinese_json, stderr="")
+        with mock.patch("verify_remote_facts.subprocess.run", return_value=mock_result) as run:
+            data = vrf.run_json(["./gc", "issue", "view", "1", "--json"])
+        self.assertEqual(data["title"], "修复中文测试")
+        _, kwargs = run.call_args
+        self.assertEqual(kwargs.get("encoding"), "utf-8")
+
+    def test_run_json_raises_on_nonzero_exit(self):
+        mock_result = mock.Mock(returncode=1, stdout="", stderr="boom")
+        with mock.patch("verify_remote_facts.subprocess.run", return_value=mock_result):
+            with self.assertRaises(SystemExit):
+                vrf.run_json(["./gc", "issue", "view", "1", "--json"])
+
+    def test_merged_in_main_uses_utf8_encoding(self):
+        """merged_in_main must pass encoding=utf-8 (#479)."""
+        mock_result = mock.Mock(returncode=0, stdout="", stderr="")
+        with mock.patch("verify_remote_facts.subprocess.run", return_value=mock_result) as run:
+            self.assertTrue(vrf.merged_in_main("abc123"))
+        _, kwargs = run.call_args
+        self.assertEqual(kwargs.get("encoding"), "utf-8")
+
+
+if __name__ == "__main__":
+    unittest.main()

{gitcode_cli-0.10.3 → gitcode_cli-0.11.0}/tests/test_wrapper.py

@@ -15,6 +15,18 @@ class WrapperTests(unittest.TestCase):
             with mock.patch("platform.machine", return_value="AMD64"):
                 self.assertEqual(wrapper.get_binary_name(), "gc-windows-amd64.exe")
 
+    def test_unknown_architecture_is_rejected(self):
+        with mock.patch("platform.system", return_value="Linux"):
+            with mock.patch("platform.machine", return_value="riscv64"):
+                with self.assertRaisesRegex(RuntimeError, "Unsupported platform: linux riscv64"):
+                    wrapper.get_binary_name()
+
+    def test_windows_arm64_is_rejected_until_a_binary_is_shipped(self):
+        with mock.patch("platform.system", return_value="Windows"):
+            with mock.patch("platform.machine", return_value="ARM64"):
+                with self.assertRaisesRegex(RuntimeError, "Unsupported platform: windows arm64"):
+                    wrapper.get_binary_name()
+
     def test_ensure_executable_skips_windows_execute_bit_check(self):
         with tempfile.NamedTemporaryFile() as tmp:
             path = Path(tmp.name)
@@ -48,6 +60,8 @@ class WrapperTests(unittest.TestCase):
             self.assertEqual(args[0], [str(binary), "version"])
             self.assertEqual(kwargs["cwd"], os.getcwd())
             self.assertEqual(kwargs["env"][wrapper.COMMAND_NAME_ENV], "gitcode")
+            self.assertEqual(kwargs["env"][wrapper.DISTRIBUTION_ENV], "pypi")
+            self.assertEqual(kwargs["env"][wrapper.BINARY_ENV], str(binary.resolve()))
 
     def test_command_name_defaults_to_gitcode_for_python_module_on_windows(self):
         with mock.patch("platform.system", return_value="Windows"):