devcontainer: opt-in CN apt mirror via AGENTENV_CN_MIRROR=1

Pulls the mirror-swap logic out of devcontainer.json into a
postcreate.sh script. AGENTENV_CN_MIRROR flows in from the host via
containerEnv interpolation; when =1, rewrite /etc/apt sources to
mirrors.aliyun.com so apt-get doesn't stall on deb.debian.org. Default
empty → no-op for OSS contributors outside China.

Author: css521

.devcontainer/devcontainer.json

@@ -18,15 +18,18 @@
 
   // No `features` block: the MS Go devcontainer image already ships the
   // vscode user, sudo, git, curl, zsh, oh-my-zsh, and everything else
-  // common-utils would have installed — adding the feature just re-runs
-  // a 2-minute apt-get for nothing (and stalls behind deb.debian.org on
-  // slow networks).
+  // common-utils would have installed.
   //
-  // libbtrfs-dev lets you build with `-tags btrfs` (the optional fast-path
-  // backend that needs cgo); the default static build needs nothing.
-  // `sudo` because lifecycle commands run as remoteUser (vscode), and the
-  // base image's vscode user has passwordless sudo configured.
-  "postCreateCommand": "sudo apt-get update && sudo apt-get install -y -qq libbtrfs-dev make",
+  // postcreate.sh installs libbtrfs-dev + make (so `-tags btrfs` builds
+  // work), and — if AGENTENV_CN_MIRROR=1 was set on the host — swaps
+  // /etc/apt sources to mirrors.aliyun.com so apt-get doesn't stall
+  // behind deb.debian.org from mainland China. The env var flows in via
+  // containerEnv below; OSS users outside China leave it unset and the
+  // mirror swap is a no-op.
+  "postCreateCommand": ".devcontainer/postcreate.sh",
+  "containerEnv": {
+    "AGENTENV_CN_MIRROR": "${localEnv:AGENTENV_CN_MIRROR}"
+  },
   // Show the Makefile target list every time the container is attached, so a new
   // contributor immediately sees what they can do (build / test / verify / demo).
   "postAttachCommand": "make help",

.devcontainer/postcreate.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Devcontainer postCreate hook.
+#
+# Two responsibilities:
+#  1. If $AGENTENV_CN_MIRROR=1 (passed in from the host's env via
+#     devcontainer.json's containerEnv block), rewrite Debian's apt sources
+#     to mirrors.aliyun.com so apt-get doesn't stall on deb.debian.org.
+#     Useful inside mainland China — OSS contributors elsewhere skip it.
+#  2. Install the optional build deps libbtrfs-dev (for `-tags btrfs`
+#     builds — the default pure-Go build needs nothing) and make.
+
+set -e
+
+if [ "$AGENTENV_CN_MIRROR" = "1" ]; then
+  echo "[postcreate] AGENTENV_CN_MIRROR=1 → switching apt sources to mirrors.aliyun.com"
+  # `*.sources` is Debian's modern deb822 format (trixie/sid); older releases
+  # still use the single-line sources.list. Rewrite whichever is present.
+  sudo sed -ri 's|http(s)?://(deb|security)\.debian\.org|http\1://mirrors.aliyun.com|g' \
+    /etc/apt/sources.list.d/*.sources /etc/apt/sources.list 2>/dev/null || true
+fi
+
+sudo apt-get update
+sudo apt-get install -y -qq libbtrfs-dev make

CONTRIBUTING.md

@@ -16,6 +16,10 @@ Most of agentenv is Linux-only (namespaces, pivot_root). On macOS you can edit a
 cross-compile (`GOOS=linux CGO_ENABLED=0 go build ./...`) and run the portable
 unit tests, but exercise the runtime in a Linux VM or Docker.
 
+The `.devcontainer/` config is opt-in to a mainland-China apt mirror — set
+`AGENTENV_CN_MIRROR=1` on your host before "Reopen in Container" if
+deb.debian.org is slow for you; leave it unset everywhere else.
+
 ## Before opening a PR
 
 ```bash