docs(agents): document downstream fork sync workflow

Describe the upstream->private mirror chain, the v<version>-lofyer branch
naming for appearance customizations, and how to run scripts/sync-github.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -3,3 +3,47 @@
 This project keeps a single source of truth for agent/contributor conventions in [`CLAUDE.md`](./CLAUDE.md). **Read [`CLAUDE.md`](./CLAUDE.md) and follow it.**
 
 @CLAUDE.md
+
+## Downstream fork workflow
+
+This repo is a **downstream fork** that customizes the product appearance on top of
+upstream `gpustack/gpustack-ui`. The mirror chain is:
+
+```
+upstream  https://github.com/gpustack/gpustack-ui.git
+   |  (fetch)
+origin    ssh://git@192.168.0.23:11022/root/gpustack-ui.git   (private registry, also https://git.digiman.live)
+```
+
+### Goal
+
+Track upstream releases. When upstream changes, we pull it in, then apply our own
+appearance/customization changes on a dedicated branch so we keep our look-and-feel
+on top of the latest upstream product.
+
+### Branch naming
+
+Customization work lives on `v<upstream-version>-lofyer` branches (e.g.
+`v2.2.0-lofyer`). Each time upstream ships a new version we want to follow, create a
+new `v<version>-lofyer` branch from the corresponding upstream tag/branch and re-apply
+(or rebase) our customizations onto it.
+
+### Syncing from upstream
+
+`scripts/sync-github` mirrors upstream into the private `origin` (full mirror, force
+push of all branches + tags). It auto-configures the `upstream` remote on first run.
+
+```bash
+# preview only, no push
+DRY_RUN=1 ./scripts/sync-github
+
+# real sync (force-pushes every upstream branch + tag to origin)
+./scripts/sync-github
+
+# also delete origin branches that no longer exist upstream (true mirror, destructive)
+PRUNE_BRANCHES=1 ./scripts/sync-github
+```
+
+Env knobs: `UPSTREAM_URL`, `ORIGIN_REMOTE`, `UPSTREAM_REMOTE`, `PRUNE_BRANCHES`,
+`DRY_RUN`. After syncing, branch a fresh `v<version>-lofyer` off the updated upstream
+ref and apply the appearance changes there.

scripts/sync-github

@@ -0,0 +1,83 @@
+#!/bin/bash
+#
+# sync-github: 从上游 GitHub 拉取最新源码，并全量镜像同步到 192.168.0.23 私有源。
+#
+# 默认行为（全量镜像 / 强制）：
+#   1. 确保存在 upstream remote 指向 GitHub（不存在则自动添加，URL 不一致则更新）。
+#   2. 从 upstream 抓取所有分支与 tag（--prune 清理已删除的远端引用）。
+#   3. 将上游每个分支强制推送到私有源同名分支（force push）。
+#   4. 将上游所有 tag 强制推送到私有源。
+#
+# 可用环境变量：
+#   UPSTREAM_URL     上游 GitHub 仓库地址（默认 https://github.com/gpustack/gpustack-ui.git）
+#   ORIGIN_REMOTE    私有源 remote 名称（默认 origin）
+#   UPSTREAM_REMOTE  上游 remote 名称（默认 upstream）
+#   PRUNE_BRANCHES   设为 1 时，删除私有源上「上游已不存在」的分支（真·镜像，破坏性，默认关闭）
+#   DRY_RUN          设为 1 时，仅打印将要执行的推送动作，不实际推送
+#
+set -e
+
+UPSTREAM_URL="${UPSTREAM_URL:-https://github.com/gpustack/gpustack-ui.git}"
+ORIGIN_REMOTE="${ORIGIN_REMOTE:-origin}"
+UPSTREAM_REMOTE="${UPSTREAM_REMOTE:-upstream}"
+PRUNE_BRANCHES="${PRUNE_BRANCHES:-0}"
+DRY_RUN="${DRY_RUN:-0}"
+
+log() { echo -e "\033[1;34m[sync-github]\033[0m $*"; }
+warn() { echo -e "\033[1;33m[sync-github]\033[0m $*" >&2; }
+
+run() {
+  if [[ "${DRY_RUN}" == "1" ]]; then
+    echo "  (dry-run) git $*"
+  else
+    git "$@"
+  fi
+}
+
+# 1. 确保 upstream remote 指向 GitHub。
+if git remote get-url "${UPSTREAM_REMOTE}" >/dev/null 2>&1; then
+  current_url=$(git remote get-url "${UPSTREAM_REMOTE}")
+  if [[ "${current_url}" != "${UPSTREAM_URL}" ]]; then
+    log "更新 ${UPSTREAM_REMOTE} 地址: ${current_url} -> ${UPSTREAM_URL}"
+    git remote set-url "${UPSTREAM_REMOTE}" "${UPSTREAM_URL}"
+  fi
+else
+  log "添加 upstream remote: ${UPSTREAM_REMOTE} -> ${UPSTREAM_URL}"
+  git remote add "${UPSTREAM_REMOTE}" "${UPSTREAM_URL}"
+fi
+
+origin_url=$(git remote get-url "${ORIGIN_REMOTE}")
+log "上游 (拉取): ${UPSTREAM_URL}"
+log "私有源 (推送): ${origin_url}"
+
+# 2. 抓取上游所有分支与 tag。
+log "抓取上游分支与 tag..."
+git fetch --prune --tags "${UPSTREAM_REMOTE}"
+
+# 3. 逐个分支强制推送到私有源。
+log "强制同步分支到私有源..."
+upstream_branches=$(git for-each-ref --format='%(refname:strip=3)' "refs/remotes/${UPSTREAM_REMOTE}/" | grep -v '^HEAD$')
+
+for branch in ${upstream_branches}; do
+  log "  -> ${branch}"
+  run push --force "${ORIGIN_REMOTE}" \
+    "refs/remotes/${UPSTREAM_REMOTE}/${branch}:refs/heads/${branch}"
+done
+
+# 4. 强制同步所有 tag。
+log "强制同步 tag 到私有源..."
+run push --force --tags "${ORIGIN_REMOTE}"
+
+# 5. 可选：删除私有源上、上游已不存在的分支（真·镜像）。
+if [[ "${PRUNE_BRANCHES}" == "1" ]]; then
+  warn "PRUNE_BRANCHES=1：将删除私有源上上游已不存在的分支"
+  origin_branches=$(git ls-remote --heads "${ORIGIN_REMOTE}" | sed 's@.*refs/heads/@@')
+  for branch in ${origin_branches}; do
+    if ! echo "${upstream_branches}" | grep -qx "${branch}"; then
+      warn "  删除私有源分支: ${branch}"
+      run push "${ORIGIN_REMOTE}" --delete "${branch}"
+    fi
+  done
+fi
+
+log "同步完成。"