CI 证据补充（GitCode Actions，run 459）：

• head SHA: a08c2d2ad512f11e2c416fa4bf9ae8cab9c0fbc2
• 状态: COMPLETED，PR mergeable_state.ci_state_passed = true
• Jobs: Lint / Secret Scan / Test / Build / Package 全部 COMPLETED
• run URL: https://gitcode.com/atomgit-cli/cli/actions/runs/a9583cf01e1345f88a3b40f2c7062bbd

本机预置失败的 TestInspectReportsInterruptedInstallLeftovers（Windows symlink 探针）在 CI Linux 环境通过，进一步确认其为本地环境预置问题，与本次改动无关。

[REQUEST CHANGES] ## 评审结论：request changes

• PR head: a08c2d2ad512f11e2c416fa4bf9ae8cab9c0fbc2
• 本地验证：GitHub mirror CI run 41175813154 全绿
• 结论：不建议合入。CI 通过说明工程质量没问题，但当前实现还没有满足 “支持 agc 命令别名” 的功能目标。

P1：agc 没有随任何正式安装渠道提供

普通安装后没有 agc 命令；只有手动设置 GITCODE_CLI_COMMAND_NAME=agc，或者把二进制改名为 agc.exe，才会生效。

证据：

• npm/package.json:33 的 bin 只有 gc / gitcode
• pyproject.toml:35 的 console scripts 只有 gc / gitcode
• .goreleaser.yaml:104 只安装 gc，并只创建 gitcode symlink
• nfpm-amd64.yaml:21 / nfpm-arm64.yaml:21 只安装 gc / gitcode
• docs/COMMANDS.md:31 和 pkg/cmd/root/root.go:169 已经把 agc 当成可直接使用的命令推荐给用户

这造成两个问题：

1. 用户安装后无法直接运行 agc
2. 文档和帮助文案却已经把它当成可直接使用的命令来推荐

推荐修复路径：把 agc 做成真实可用的安装命令

1. npm 渠道

需要同时改两处：

• npm/package.json
  • 在 bin 里新增：

    "agc": "bin/gc.js"
    

  • 保持 gc、gitcode 不变
• npm/lib/install.js
  • 目前 bootstrap 安装器只写 gc 和 gitcode
  • 需要新增 agc 的安装逻辑，和 gitcode 一样指向同一个二进制
  • Windows 下应生成 agc.exe
  • POSIX 下可以生成 symlink 或复制文件，但要和现有 gitcode 的处理保持一致
  • 安装摘要里的文案也应从 “Installed gc and gitcode” 改成三名

自测建议：

npm pack --prefix npm
# 或直接本地安装
npm install -g ./npm
agc --version
gc --version
gitcode --version

验收标准：

• agc --version、gc --version、gitcode --version 三者都能直接运行
• agc doctor install --json 里能看到 agc 的 PATH 解析结果
• npm 安装器输出中不再只提双命令名

2. wheel / PyPI 渠道

修改 pyproject.toml：

• 在 [project.scripts] 里新增：

  agc = "gc_cli.wrapper:main"
  

• 保持 gc、gitcode 不变

自测建议：

python -m build --wheel
pip install dist/*.whl
agc --version
gc --version
gitcode --version

验收标准：

• wheel 安装后 agc 可直接执行
• python -m gc_cli --help 的命令名说明仍保持现有行为

3. goreleaser / DEB / RPM 渠道

需要同步以下文件：

• .goreleaser.yaml
  • 目前只安装 gc 并创建 gitcode symlink
  • 需要新增 agc 的安装方式，建议与 gitcode 一致，使用 symlink
• nfpm-amd64.yaml
  • 在 contents 里新增 agc 目标
• nfpm-arm64.yaml
  • 同上

示例方向：

- src: /usr/bin/gc
  dst: /usr/bin/agc

自测建议：

go build -o gc ./cmd/gc
nfpm package -f nfpm-amd64.yaml -p deb
# 安装后检查
agc --version

验收标准：

• DEB/RPM 安装后 agc 可直接执行
• 包内三个命令名等价
• doctor install 能识别 agc

4. Homebrew 渠道

如果本 PR 声称支持正式别名，Homebrew 也应同步：

• 在 formula 中为 gc 创建 agc symlink
• 或至少说明 Homebrew 暂不提供 agc，并在 PR 描述里列为已知边界

自测建议：

brew install ./homebrew/gc.rb
agc --version

验收标准：

• agc 在 Homebrew 安装后可用，或明确列为暂不支持

可选修复路径：明确降级为 opt-in 命令名解析支持

如果你不想在本 PR 里改所有安装渠道，请把范围收窄，并做以下修改：

1. PR 标题改成：

   feat: support opt-in agc command-name resolution
   

2. PR 描述明确说明：
   • agc 不会随安装器自动提供
   • 只在 GITCODE_CLI_COMMAND_NAME=agc 或二进制改名为 agc 时生效
3. docs/COMMANDS.md 和 README.md 中删除“推荐直接使用 agc”的表述
4. npm/README.md 说明：
   • 会安装 agc 补全
   • 但不会自动安装 agc 命令
5. pkg/cmd/root/root.go 的 Windows 提示中，把 agc 从直接推荐列表里移除，或注明 “if you enable it”

P2：doctor install 帮助文案未同步

pkg/cmd/doctor/install/install.go:52 仍写：

every gc or gitcode candidate

但实现已经扫描 gc / gitcode / agc 三个命令。

请同步更新为三名，例如：

every gc, gitcode, and agc candidate

P2：npm README 仍写“双命令名补全”

npm/README.md:40 仍写：

completions for both gc and gitcode

但实现已经安装 gc / gitcode / agc 三名补全。

请同步更新为三名，并说明：

• 会安装 agc 补全
• agc 命令本身是否自动安装，取决于你选择的路径 A 或路径 B

P2：包元数据 homepage 未迁移

以下文件仍指向 gitcode.com，与 version 输出的 atomgit.com 不一致：

• npm/package.json:7
  • homepage
  • bugs.url
• pyproject.toml:39
  • Homepage
  • Documentation
  • Repository
  • Issues
• .goreleaser.yaml:100
  • homepage
• nfpm-amd64.yaml:15
  • homepage
• nfpm-arm64.yaml:15
  • homepage

建议统一改为：

https://atomgit.com/atomgit-cli/cli

如果某些链接必须保留 gitcode.com（例如 API host），请在 PR 描述里逐条说明保留原因。

测试补充

建议至少补以下测试：

• npm 安装器测试
  • 断言安装后存在 agc 入口
  • 断言安装摘要包含三名
• wheel 安装测试
  • 断言 pyproject.toml 的 scripts 包含 agc
• goreleaser/nfpm 配置测试或打包冒烟
  • 断言 agc 被安装
• doctor install 测试
  • help 文案包含 agc

后续验收清单

我们会按以下清单验收：

1. agc --version 在目标安装渠道可直接运行
2. doctor install --help / --json 正确包含三名
3. npm README、docs、AGENTS 与实际行为一致
4. npm/package.json、pyproject.toml、.goreleaser.yaml、nfpm 的命令入口和 homepage 一致
5. go test ./...
6. go test -race ./...
7. npm test --prefix npm
8. pre-commit run --all-files
9. 镜像仓 CI 全绿
10. PR 标题、描述和实际功能边界一致

结论

如果你选择“补齐安装入口”，请把 agc 做成正式命令，并同步所有安装渠道和文档。
如果你选择“降级为 opt-in”，请把 PR 标题、描述和文档改为明确的 opt-in 语义，避免用户误以为安装后可以直接输入 agc。

感谢详细的评审意见。已采纳推荐修复路径 A：把 agc 做成随所有正式安装渠道提供的真实命令（新 head 3194114，23 files，+1710/−52）。

P1：agc 安装入口（按渠道逐项修复）

npm 渠道

• npm/package.json bin 新增 "agc": "bin/gc.js"（gc/gitcode 保持不变）
• bootstrap 安装器（npm/lib/install.js）：新增 bootstrapCommandFiles() 纯函数，安装事务写入第三入口 agc（Windows 为 agc.exe，POSIX 与 gitcode 一致走同一别名迁移/事务/回滚路径），checksum 校验覆盖 agc；安装摘要改为 "Installed gc, gitcode, and agc to ..."；中断安装残留扫描（LEFTOVER_PREFIXES）与 Windows PATH 遮蔽诊断（windowsPathShadowing）均补 agc
• 冒烟：npm pack 产物 package.json 的 bin 为 {"gc","gitcode","agc"} → bin/gc.js 三入口

wheel / PyPI 渠道

• pyproject.toml [project.scripts] 新增 agc = "gc_cli.wrapper:main"（行为与 gc/gitcode 入口一致）

goreleaser / Homebrew 渠道

• .goreleaser.yaml brews：bin.install_symlink "gc" => "agc"，bash/zsh/fish 补全三命令名全装，test 块断言 agc version
• homebrew/gc.rb 同步生成 DSL
• 补全产物来源：make completions 现在用 GITCODE_CLI_COMMAND_NAME={gitcode,agc} 由 CLI 原生生成 completions/{gitcode,agc}.{bash,zsh,fish}（6 个新文件入库，release archive 的 completions/* 自动包含）；prepare-package-assets.sh 由 sed 改写改为直接 stage（消除与 cobra 输出的漂移风险）

DEB / RPM 渠道

• nfpm-amd64.yaml / nfpm-arm64.yaml：/usr/bin/agc symlink + agc 命名补全（bash/zsh/fish）

P2 修复

• doctor install help 文案改为 "every gc, gitcode, and agc candidate"
• npm/README.md：bootstrap 描述、Windows agc.exe、--target-dir、Uninstall 清单均更新为三命令名
• docs/COMMANDS.md / README.md：DEB/RPM/wheel/Homebrew 描述更新为三名等价
• npm/package.json homepage/bugs.url → atomgit.com
• 说明：pyproject.toml URLs、.goreleaser.yaml/nfpm 的 homepage 在中间提交（docs: migrate presentation references to atomgit.com，PR head 历史可见）已完成迁移，评审所列证据对应旧 head

查漏补缺（评审未点到的同类问题）

• Go 侧 transactionLeftoverPrefixes（doctor 的中断安装残留报告）与 npm 侧 LEFTOVER_PREFIXES 注释明确要求保持同步，但首轮只改了 npm 侧——本次两侧均已补 agc 前缀，并同步更新对应测试断言

测试补充

• npm：新增 bootstrapCommandFiles 单元测试（posix/Windows 三入口断言）；isTransactionLeftoverName 断言扩展 agc 备份/临时文件
• doctor install：新增 TestInstallHelpMentionsAllCommandNames（help 含三命令名）；TestInspectReportsInterruptedInstallLeftovers 输入与断言补 agc 残留项
• 升级冒烟脚本 scripts/test-npm-install-upgrade.js：补全文件断言扩为 9 个（含 agc 三件，头部命令名锚定）

自测证据

• go build + go test ./...：除 TestInspectReportsInterruptedInstallLeftovers 外全绿；该测试本机失败根因已定位为 Windows 环境怪癖（os.Symlink 返回错误但符号链接实际被创建，报告比期望多 1 项），上轮 CI Linux 已通过该测试，本轮以 CI 结果为准
• node --test npm/test/install.test.js：新增断言全部通过；本机其余失败经 git stash 对照确认为沙箱拦截 symlink/临时目录所致，与改动无关（CI Linux 全量执行）
• 真实命令验证：gc doctor install --help 输出三命令名；npm pack 冒烟通过
• 未覆盖项：本机无 Python/nfpm/goreleaser，wheel/DEB/RPM 打包冒烟以 CI（package job 含 wheel 入口冒烟）为准

CI 结果出来后将在本 PR 补充证据。

CI 证据补充（GitCode Actions，run 473，对应评审修复 head 3194114）：

• head SHA: 31941149b68cc184734171e44dff99927bea035c
• 状态: COMPLETED，PR mergeable_state.ci_state_passed = true
• Jobs: Lint / Secret Scan / Test / Build / Package 全部 COMPLETED
  • Test job 含 Run npm wrapper tests（npm 侧新增 agc 断言全部通过）与 Run Python unit tests
  • Package job 含 Generate completions（含本次新增的 gitcode/agc 补全生成）与 Wheel entrypoint smoke test（pyproject scripts agc 入口冒烟通过）
• run URL: https://atomgit.com/atomgit-cli/cli/actions/runs/ca6aac8c62d8417aad6dede268df1aa8

至此评审人验收清单中的 CI 项已在新 head 上全绿，等待复核。