refactor(ci,docs): gitcode 镜像仓名收为单一定义点，取值 HomeAgent（实测 200）

gitcode 镜像目标仓名此前在 3 个文件里各写死多份字面量，改名时要遍改且极
易漏（漏一处 = 一个静默死链，而且失败面在 release 里只有一格）。本批只做
「收成单点」，不改任何取值、不碰代码。

三个定义点（每个文件恰好 1 处，消费点全部走变量）：
1. .github/workflows/ci.yml → job `sync-gitcode-main` 的 env.GC_REPO:232
   消费点 2 处命令行：git ls-remote 探测、git push main。
2. .github/workflows/release.yml → job `sync-gitcode` 的 env.GC_REPO:375
   消费点 4 处命令行：git ls-remote 探测、push tag、POST /releases、
   upload_assets.py 的 GITCODE_REPO 传入。
   （两个 workflow 是独立文件，不能共享 env，故各自一处定义。）
3. deploy/scripts/upload_assets.py → os.environ.get("GITCODE_REPO", ...) 默认值。
   手工跑脚本时的兜底，与两个 workflow 同值。

为什么取值 JianFeeeee/HomeAgent 而不是 HologramAgent：
GitHub 主仓已改名 HologramAgent，但 **gitcode 侧镜像仓没有跟着改名**。
curl 直连实测（2026-10-21）：
  https://gitcode.com/JianFeeeee/HomeAgent      → 200   ← 当前取值
  https://gitcode.com/JianFeeeee/HologramAgent  → 404
指向 HologramAgent 会让每次发版/推 main 都在镜像同步这步红掉，且国内镜像
停止更新。

两个 job 的失败面不同（容易搞混，此处写明）：
- release.yml 的 sync-gitcode：needs [prepare, publish]。探测 exit 1 ⇒
  **只红「镜像同步」这一格**；GitHub 侧 release 产物已经发出去了。
- ci.yml 的 sync-gitcode-main：needs [go, race, cross, gui, csrc, docs] 全绿
  后才跑。探测 exit 1 ⇒ **main 的整条 CI 红**（不是一格）。
所以仓名写错的真实后果是「必红一格 + 国内镜像不更新」，不是「发不出包」。

何时切回 HologramAgent：等 gitcode 上把镜像仓真正改名/新建成功、
https://gitcode.com/JianFeeeee/HologramAgent 返回 200 之后，
**只改上面这三行**即可，两个 workflow 的消费点与 runbook 均无需再动。

docs/zh/ci-cd-runbook.md 同步三节：单点化表格（定义处/消费点）、当前取值与
200/404 实测依据、两个 job 的失败面差异；并把 §3.4 的 curl 验活地址与
upload_assets 手工调用示例同步到 HomeAgent（原写法是已 404 的死链）。

判据（含变异，全部实跑）：
- 两个 workflow 可被 yaml.safe_load 解析；每个 jobs[..].env.GC_REPO 恰好 1 处
- 每个 step 的 run 块抽出来喂 bash -n，全部无语法错
- 可执行形态里的 gitcode 目标仓名不含 HologramAgent（注释行豁免）
- 变异：把任一 GC_REPO 定义改回 HologramAgent、或把某消费点还原成字面量，
  判据均报红
- 零代码改动：git status 无 .go/.lua/go.mod/go.sum；go build ./... 通过

.github/workflows/ci.yml

@@ -226,6 +226,29 @@ jobs:
     needs: [go, race, cross, gui, csrc, docs]
     if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     timeout-minutes: 10
+    env:
+      # ══════════════════════════════════════════════════════════════════
+      # ★★ gitcode 镜像目标仓名 —— **本 job 的唯一定义处**。
+      #    改 gitcode 仓名时只改这一行；下面推 main 的消费点走 ${GC_REPO}。
+      #    与 release.yml 的 sync-gitcode 保持同值（两处各自独立定义，
+      #    因为它们是不同的 workflow —— 改的时候两个文件都要改，但每个
+      #    文件内部只有一个定义处）。
+      #
+      # 取值依据（实测 2026-10-21，curl 直连，非推测）：
+      #   https://gitcode.com/JianFeeeee/HomeAgent         → 200  ← 当前用这个
+      #   https://gitcode.com/JianFeeeee/HologramAgent     → 404
+      #
+      # 背景：GitHub 主仓已改名 HologramAgent，gitcode 侧镜像仓未改名。
+      #
+      # ⚠ 失败面（与 release.yml 不同，别搞混）：
+      #   本 job 的 needs 是 [go, race, cross, gui, csrc, docs]。前置检查
+      #   exit 1 ⇒ 本 job 红 ⇒ **main 的整条 CI 红**（不是只红一格）。
+      #   而 release.yml 的 sync-gitcode 只红在镜像同步这一格，GitHub 侧
+      #   release 产物已经发出去了。
+      #
+      # 何时改回 HologramAgent：gitcode 上仓真正存在且返回 200 后，只改这一行。
+      # ══════════════════════════════════════════════════════════════════
+      GC_REPO: JianFeeeee/HomeAgent
     steps:
       - id: tok
         name: 检查 gitcode 凭据
@@ -253,7 +276,7 @@ jobs:
         run: |
           set -euo pipefail
           GC_URL="https://JianFeeeee:${GC_TOKEN}@gitcode.com"
-          GC_REPO="JianFeeeee/HologramAgent"
+          # GC_REPO 来自 job 级 env（唯一定义处），此处不重复字面量。
           # 用 ls-remote 探测：与后面那次 push 走同一个 URL、同一套凭据，
           # 比另调一次 API 更贴近真实失败面。
           if out=$(GIT_TERMINAL_PROMPT=0 git ls-remote --heads \
@@ -295,6 +318,7 @@ jobs:
         run: |
           set -euo pipefail
           GC_URL="https://JianFeeeee:${GC_TOKEN}@gitcode.com"
-          git push "${GC_URL}/JianFeeeee/HologramAgent.git" \
+          # GC_REPO 来自 job 级 env（唯一定义处），此处不重复字面量。
+          git push "${GC_URL}/${GC_REPO}.git" \
             "refs/heads/main:refs/heads/main"
           echo "  gitcode/main 已快进到 ${GITHUB_SHA}"

.github/workflows/release.yml

@@ -352,6 +352,27 @@ jobs:
     if: needs.prepare.outputs.exists == 'false'
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    env:
+      # ══════════════════════════════════════════════════════════════════
+      # ★★ gitcode 镜像目标仓名 —— **本 job 的唯一定义处**。
+      #    改 gitcode 仓名时只改这一行；下面所有消费点都走 ${GC_REPO}。
+      #
+      # 取值依据（实测 2026-10-21，curl 直连，非推测）：
+      #   https://gitcode.com/JianFeeeee/HomeAgent         → 200  ← 当前用这个
+      #   https://gitcode.com/JianFeeeee/HologramAgent     → 404
+      #   https://gitcode.com/JianFeeeee/homeagent-sdk     → 200
+      #   https://gitcode.com/JianFeeeee/hologramagentsdk  → 200
+      #   https://gitcode.com/JianFeeeee/homeagentsdk      → 404
+      #
+      # 背景：GitHub 主仓已由 HomeAgent 改名为 HologramAgent，但 **gitcode 侧
+      # 的镜像仓没有跟着改名**，gitcode 上 HologramAgent 仍是 404。因此这里
+      # 必须指向仍然存在的 HomeAgent，否则每次发版都会红在镜像同步这一格。
+      #
+      # 何时改回 HologramAgent：在 gitcode 上把镜像仓真正改名/新建成功、
+      # 且 https://gitcode.com/JianFeeeee/HologramAgent 返回 200 之后，
+      # **只改这一行**即可，无需再动其他文件。
+      # ══════════════════════════════════════════════════════════════════
+      GC_REPO: JianFeeeee/HomeAgent
     steps:
       - uses: actions/checkout@v7
       - id: tok
@@ -379,7 +400,7 @@ jobs:
         run: |
           set -euo pipefail
           GC_URL="https://JianFeeeee:${GC_TOKEN}@gitcode.com"
-          GC_REPO="JianFeeeee/HologramAgent"
+          # GC_REPO 来自 job 级 env（唯一定义处），此处不重复字面量。
           if out=$(GIT_TERMINAL_PROMPT=0 git ls-remote --heads \
                      "${GC_URL}/${GC_REPO}.git" 2>&1); then
             echo "  目标仓可访问：gitcode.com/${GC_REPO}"
@@ -419,7 +440,7 @@ jobs:
           TAG: ${{ needs.prepare.outputs.tag }}
         run: |
           set -euo pipefail
-          GC_REPO="JianFeeeee/HologramAgent"
+          # GC_REPO 来自 job 级 env（唯一定义处），此处不重复字面量。
           GC_URL="https://JianFeeeee:${GC_TOKEN}@gitcode.com"
           # 1) 推 tag（附件上传前 release 条目必须先存在）
           git config user.name  "github-actions[bot]"
@@ -439,5 +460,5 @@ jobs:
           # 不传文件名时它扫描 ASSET_DIR 并按后缀识别发布产物 —— 这里正合适
           # （.deb/.tar.gz/SHA256SUMS 都在白名单里）。
           # 不要传 "./x" 或 "dist/x"：那会拼成 dist/dist/x。
-          ASSET_DIR=. GITCODE_REPO=JianFeeeee/HologramAgent \
+          ASSET_DIR=. GITCODE_REPO="${GC_REPO}" \
             python3 ../deploy/scripts/upload_assets.py "$TAG" "$GC_TOKEN"

deploy/scripts/upload_assets.py

@@ -5,7 +5,13 @@
 不传 file 时上传 dist/release/ 下全部发布产物。
 
 环境变量：
-  GITCODE_REPO  目标仓库，默认 JianFeeeee/HologramAgent（SDK 仓传 JianFeeeee/homeagent-sdk）
+  GITCODE_REPO  目标仓库，默认 JianFeeeee/HomeAgent（SDK 仓传 JianFeeeee/homeagent-sdk）
+                这是 gitcode 镜像仓名的**唯一定义处**（workflow 里通过 job 级
+                env.GC_REPO 传入同一个值）。改 gitcode 仓名时改这里 + 两个
+                workflow 的 GC_REPO，共三处（每个文件各一个定义点）。
+                取值依据（实测 2026-10-21）：gitcode 上 JianFeeeee/HomeAgent
+                返回 200，JianFeeeee/HologramAgent 返回 404 —— GitHub 主仓
+                已改名 HologramAgent，但 gitcode 侧镜像仓未跟着改。
   ASSET_DIR     资产目录，默认 <repo>/dist/release
 
 为何两步：gitcode 的 release 附件不走 API 直传，而是先向
@@ -20,7 +26,7 @@ import urllib.error
 import urllib.parse
 import urllib.request
 
-REPO = os.environ.get("GITCODE_REPO", "JianFeeeee/HologramAgent")
+REPO = os.environ.get("GITCODE_REPO", "JianFeeeee/HomeAgent")
 API = "https://gitcode.com/api/v5/repos"
 
 # 发布产物后缀。注意 Windows 安装器是 HomeAgent_v*_win64.exe，

docs/zh/ci-cd-runbook.md

@@ -10,7 +10,7 @@
 | --- | --- | --- | --- |
 | 主仓 HologramAgent | `github.com/JianFeeeee/HologramAgent`（公开） | `ci.yml` + `release.yml` | push / PR、`release/**` push |
 | SDK 仓 homeagentsdk | `github.com/JianFeeeee/homeagentsdk`（公开） | `release.yml` | `release/**` push |
-| gitcode 镜像 | 同名仓库 | 无（由主仓 Release 的 sync job 同步） | — |
+| gitcode 镜像 | `gitcode.com/JianFeeeee/HomeAgent`（**不与主仓同名**） | 无（由主仓 Release 的 sync job 同步） | — |
 
 **分支保护**（main，公开仓免费）：10 项必须检查（Go build/vet/test、Race、
 cross×5、GUI、C gates、Docs）+ `strict`（必须与 main 同步）+ 禁 force push。
@@ -19,6 +19,34 @@ cross×5、GUI、C gates、Docs）+ `strict`（必须与 main 同步）+ 禁 for
 **gitcode 的角色**：只读镜像（git push 同步）。Release 附件由 sync job 自动
 补传，或手工跑 `deploy/scripts/upload_assets.py`（见 §3.4）。
 
+**gitcode 仓名的单点化**（2026-10-21 加）：gitcode 镜像目标仓名曾在多处写死，
+改名时要遍改且易漏（漏一处就是一个小死链）。现在收继到**每文件一个定义处**，
+消费点全部走变量：
+
+| 定义处 | 形式 | 消费点 |
+| --- | --- | --- |
+| `.github/workflows/release.yml` | `env.GC_REPO`（job 级） | `${GC_REPO}` ×4 |
+| `.github/workflows/ci.yml` | `env.GC_REPO`（job 级） | `${GC_REPO}` ×2 |
+| `deploy/scripts/upload_assets.py` | `GITCODE_REPO` 环境变量默认值 | 脚本自身 |
+
+两个 workflow 是独立 workflow，因此各自一个定义（不能跨文件共享 env）。
+**gitcode 侧真正把仓改名成 HologramAgent 之后，只改这三个定义点即可**。
+
+**当前取值 `JianFeeeee/HomeAgent`**，而不是 `HologramAgent`。实测（2026-10-21，
+curl 直连）：`gitcode.com/JianFeeeee/HomeAgent` → **200**，
+`gitcode.com/JianFeeeee/HologramAgent` → **404**。GitHub 主仓已改名，
+gitcode 侧镜像仓没跟着改。指向 HologramAgent 会让每次发版都红在镜像同步。
+
+**失败面（两个 job 不一样，别搞混）**：
+
+- `release.yml` 的 `sync-gitcode`：`needs: [prepare, publish]`。前置检查 `exit 1`
+  ⇒ **只红镜像同步这一格**；GitHub 侧 release 产物已经发出去了。
+- `ci.yml` 的 `sync-gitcode-main`：`needs` 全绿（go/race/cross/gui/csrc/docs）后才跑。
+  前置检查 `exit 1` ⇒ 该 job 红 ⇒ **main 的整条 CI 红**。
+
+所以仓名写错的实际后果是「每次 release/main CI 必红一格 + 国内镜像不更新」，
+**不是**「发不出包」。
+
 ## 1. CI（ci.yml）—— 每次推送到 main / release/** / PR 都跑
 
 六个 job，**全部命令均本地实测过**（原则：不写"应该有用"的未验证步骤）：
@@ -181,8 +209,11 @@ gh secret list --repo JianFeeeee/HologramAgent | grep GITCODE_TOKEN
 # ② token 有效
 curl -s "https://gitcode.com/api/v5/user?access_token=$TOKEN"
 # ③ job 用的 private-token 头可读 release（两仓都测）
+#    ⚠ gitcode 侧主仓镜像名是 HomeAgent（不是 HologramAgent）——
+#      实测 2026-10-21：/repos/JianFeeeee/HomeAgent→400（带 token 可读）、
+#      /repos/JianFeeeee/HologramAgent→404。写成 HologramAgent 是死链。
 curl -s -H "private-token: $TOKEN" \
-  "https://gitcode.com/api/v5/repos/JianFeeeee/HologramAgent/releases/tags/v1.3.13"
+  "https://gitcode.com/api/v5/repos/JianFeeeee/HomeAgent/releases/tags/v1.3.13"
 ```
 
 ★ **token 是宽范围的个人令牌**（可读 92 仓/48 私有、有写权限），而 CI 只需要这两个仓。
@@ -193,7 +224,8 @@ curl -s -H "private-token: $TOKEN" \
 
 ```bash
 # token 放 ~/.git-credentials（https://JianFeeeee:<token>@gitcode.com）
-ASSET_DIR=<产物目录> GITCODE_REPO=JianFeeeee/HologramAgent \
+# GITCODE_REPO 是 gitcode 镜像仓名（当前 HomeAgent），与 GitHub 侧仓名无关。
+ASSET_DIR=<产物目录> GITCODE_REPO=JianFeeeee/HomeAgent \
   python3 deploy/scripts/upload_assets.py <tag> <token>
 # release 条目必须先存在（脚本向 releases/<tag>/upload_url 取 OBS 签名 URL）
 ```