docs: gitcode 镜像仓为什么不会自己更新（附实测证据与触发方式）

用户（2026-09-14）：「git@gitcode.com:JianFeeeee/MailUI4Agents.git 这个镜像仓
怎么也没更新？」

查下来三件事，写进文档免得下一个人再查一遍：

① 它是 gitcode 的**导入/镜像项目**，上游就是我们自己的 Gitea
   （`import_url=https://gitea.jianfgit.xyz/jianf/MailUI4Agents.git`，
   从项目页的 Nuxt payload 里读出来的）。
② **推不进去**，两条路都是服务端拒绝：
   SSH  `<CH.00905401> This operation is not allowed because the repository is an
        image repository.`
   HTTPS 403 `<CH.00905403>`（同样的措辞）。
   「image repository」是它那边的「镜像项目」类型，不是容器镜像；语义是**单向**的。
③ **没有自动同步，也没有 API**：那个页面自己写着「对于滞后的提交，你可以通过
   拉取更新从源项目获取最新的代码」—— 是手动一键操作。6 种猜测的 API 端点全部 404。

我们这边实测是好的：上游公网可达（直连 101.201.37.155 拿到 info/refs，HEAD
就是 d78f19f）、公网 DNS 有记录、匿名可克隆。镜像停在 c19eea5（09-12），落后 114 个提交，
纯粹是那边没人点「拉取」。

本机无法代点：动作要以仓库所有者身份登录，而共享浏览器 profile 里只有 gitcode 的
匿名 Cookie，没有登录态。文档里给了网页入口和「想自动化就只能换成普通项目由我们推」
这条替代路（会改 URL，属对外契约变更，要先问）。

docs/GITCODE-MIRROR.md

@@ -0,0 +1,98 @@
+# gitcode 镜像仓：为什么它不会自己更新
+
+**结论：gitcode 上的 `JianFeeeee/MailUI4Agents` 是「导入 / 镜像」项目，只能从 gitcode
+网页上点一次「拉取」来更新。我们这边推不进去（服务端拒绝），也没有 API 能触发。**
+
+用户（2026-09-14）：「git@gitcode.com:JianFeeeee/MailUI4Agents.git 这个镜像仓怎么也没更新？」
+
+## 它是什么
+
+| | |
+|---|---|
+| 网页 | https://gitcode.com/JianFeeeee/MailUI4Agents |
+| 类型 | 导入 / 镜像项目（`import_status=finished`） |
+| 上游（`import_url`） | `https://gitea.jianfgit.xyz/jianf/MailUI4Agents.git` —— 就是**我们自己的 Gitea** |
+| 公开性 | public（匿名可 clone） |
+
+`import_url` 是从项目页的 Nuxt payload 里读出来的（页面上直接写着）：
+
+```bash
+curl -s https://gitcode.com/JianFeeeee/MailUI4Agents \
+  | grep -o '"https:[^"]*\.git"'          # → gitea.jianfgit.xyz/jianf/MailUI4Agents.git
+```
+
+## 为什么推不进去
+
+两条路都试过，都是 gitcode 服务端拒绝：
+
+```bash
+git push --dry-run git@gitcode.com:JianFeeeee/MailUI4Agents.git main
+#   fatal: <CH.00905401> This operation is not allowed because the repository is an image repository.
+
+git push --dry-run https://gitcode.com/JianFeeeee/MailUI4Agents.git main
+#   remote: <CH.00905403> ... 403
+```
+
+「image repository」是 gitcode 的**措辞**（中文那套就叫「镜像」），指的是它那边的
+**镜像项目**类型，**不是**容器镜像（虽然这个项目的 `container_registry_enabled` 也是 true）。
+镜像项目的语义是**单向**的：只从上游拉，不接受推送。
+
+## 为什么没有自动同步
+
+那个页面自己的文案就是答案（同样是 Nuxt payload 里的字面量）：
+
+- 「对于滞后的提交，你可以通过**拉取更新**从源项目获取最新的代码」
+- 「使用**同步源项目**的一键操作，即可获取源项目的最新代码提交和更新。」
+- 「拉取全部分支更新」
+- 「同步源项目所有分支的最新代码可能导致当前提交的代码丢失，请确认是否继续？」
+
+也就是这是**手动一键操作**，不是定时任务。API 侧也没有这个能力 —— 下面 6 种端点形状
+全部 404（`Authorization: Bearer <~/.git-credentials 里的 token>`）：
+
+```
+POST /api/v5/repos/{owner}/{repo}/mirror/pull
+POST /api/v5/repos/{owner}/{repo}/import/pull
+POST /api/v5/repos/{owner}/{repo}/sync_source
+POST /api/v5/repos/{owner}/{repo}/pull
+POST /api/v5/projects/{id}/mirror/pull
+POST /api/v5/projects/{id}/import/pull
+```
+
+## 我们这边是好的（已实测，别再怀疑上游）
+
+```bash
+# ① 上游公网可达，且报的 HEAD 就是我们最新的提交
+curl -s --resolve gitea.jianfgit.xyz:443:101.201.37.155 \
+  "https://gitea.jianfgit.xyz/jianf/MailUI4Agents.git/info/refs?service=git-upload-pack"
+#   → d78f19f…（等于本地 HEAD 与 origin/main）
+
+# ② 公网 DNS 有记录（不是只在内网 DNS 里有）
+curl -s -H 'accept: application/dns-json' \
+  "https://dns.alidns.com/resolve?name=gitea.jianfgit.xyz&type=A"
+#   → 101.201.37.155
+
+# ③ 镜像仓落后了多少个提交
+git ls-remote git@gitcode.com:JianFeeeee/MailUI4Agents.git
+git rev-list --count <镜像的 sha>..HEAD
+```
+
+即：**上游是最新的、公网能克隆、域名能解析**。镜像停在第 N 个提交上，纯粹是因为
+gitcode 那边没有人去点「拉取」。
+
+## 要让镜像更新
+
+打开 https://gitcode.com/JianFeeeee/MailUI4Agents ，页面上会给出一键「拉取 / 同步源项目」
+（对滞后的提交会主动提示），点它并确认即可。**需要以仓库所有者身份登录** —— 本机的
+共享浏览器 profile（`/home/newqqagent/browser_profiles/shared`）里只有 gitcode 的匿名
+Cookie（`_frid` / `uuid_tt_dd` / `Hm_lvt_*` 之类），没有登录态，所以这条动作没法由
+agent 代点。
+
+## 如果希望它别再掉队
+
+镜像项目的单向语义决定了「推着它走」这条路是堵死的。想自动化只有换一种镜像方式：
+
+1. 在 gitcode 上建一个**普通项目**（不是导入 / 镜像项目），然后由我们这边推
+   （本地 `git remote add` + 每次提交后推，或定时推）。这条路可自动化，代价是 URL 变了。
+2. 保持现状：需要对外可见时，人工点一次「拉取」。
+
+选 1 之前先问 —— 换 URL 是对外契约的变更。