feat(builder): declare multi-arch builds with ARCHES

Project architecture lists belong in makefile.builder, not .env.builder.
deb/push-deb fan out when ARCH is omitted; Docker platforms derive from
ARCHES. Legacy makefiles without ARCHES keep the old single-arch behavior.

skills/builder/README.md

@@ -38,8 +38,9 @@ pouch add builder -g       # 全局
 不改用户已有的 `Makefile` 或 `.env`。
 
 1. `makefile.builder` 目标：`help/build/clean/version` + 条件 `deb/docker/push*`，
-   变量 `ARCH/VERSION/DIST_DIR/PROJECT_NAME`。
+   变量 `ARCHES/ARCH/VERSION/DIST_DIR/PROJECT_NAME`。
    `VERSION` 通过 `include <builder>/scripts/version.mk` 从 Git 推导。
+   多架构清单是 `ARCHES`，见下方「多架构」。
 2. 运行 `python3 -I -S <builder>/scripts/check.py . --ready` 直到构建项 PASS。
    缺发布键只挡住上传，不挡住构建。
 3. 在项目根 `.env.builder` 配置发布环境变量（不要写进 `.env`）：
@@ -54,6 +55,51 @@ DOCKER_REGISTRY=registry.example.com
 4. 日常发布就是两条命令：
    `make -f makefile.builder deb && make -f makefile.builder push-deb`、
    `make -f makefile.builder push-docker`。
+   写了 `ARCHES=amd64 arm64` 时，这两条会打出并上传两个 DEB；镜像一次推多平台。
+
+## 多架构
+
+项目要发哪些 CPU 架构，写在**已提交的** `makefile.builder` 里，不要写进
+`.env.builder`（那是密钥，换机器会丢）。
+
+```makefile
+ARCHES ?= amd64 arm64
+```
+
+`ARCH` 是「这一次」：默认等于清单第一项。不传 `ARCH=` 时，`deb` / `push-deb`
+按清单逐个做完；`push-docker` 把清单映射成 `linux/amd64,linux/arm64`。
+只做其中一个：`make -f makefile.builder deb ARCH=arm64`。
+
+合法值只有 `amd64` 和 `arm64`（空格分隔）。不要默认写成双架构：本机编不出
+另一边时，只留一项。
+
+```bash
+make -s -f makefile.builder arches    # 打印清单，例如 amd64 arm64
+make -f makefile.builder deb          # 打出两个 .deb
+make -f makefile.builder push-deb     # 两个都上传（需你授权发布）
+make -f makefile.builder push-docker  # 一次 buildx 推两个平台
+```
+
+产物：
+
+```text
+dist/<name>_<version>_amd64.deb
+dist/<name>_<version>_arm64.deb
+```
+
+`build` 配方必须用 `$(ARCH)`，否则两个包内容会一样。初始化时 Agent 按仓库里
+已有命令来写（Go 一般是 `GOOS=linux GOARCH=$(ARCH) go build …`），不另做一套
+运行时探测脚本。看不出交叉编法就不要写双架构。
+
+`packaging/DEBIAN/control` 的 `Architecture:` 必须随 `$(ARCH)` 变，不要写死
+`amd64`。模板会先拷到 `dist/packaging-$(ARCH)` 再改这一行。
+
+本机临时只推一个平台，可以在 `.env.builder` 设 `PLATFORMS=linux/amd64`，这是
+覆盖不是清单。项目清单始终以 `ARCHES` 为准。
+
+存量 `makefile.builder` 没有 `ARCHES` 时行为与以前相同（默认 `amd64`，
+`ARCH=arm64` 仍合法）。要改成双架构：加上面那一行，确认 `build` 吃 `$(ARCH)`，
+再跑 `python3 -I -S <builder>/scripts/check.py . --ready`。
 
 ## 版本号
 
@@ -119,11 +165,12 @@ detached HEAD 用 `detached`，CI 可注入 `BUILD_BRANCH` / `CI_COMMIT_BRANCH`
 用 builder 构建当前版本的 DEB 和镜像，先不要上传。
 用 builder 把当前 commit 的产物发布到项目已配置的仓库。
 用 builder 发布多平台 linux/amd64,linux/arm64 镜像。
+用 builder 把当前版本的 amd64 和 arm64 DEB 打出来并发布。
 ```
 
 ## Agent 会做什么
 
-1. 初始化：探测 DEB / Docker 轨道，写出 `makefile.builder` 和 `.env.builder` 骨架，不改你已有的 `Makefile` 或 `.env`。
+1. 初始化：探测 DEB / Docker 轨道，写出 `makefile.builder` 和 `.env.builder` 骨架，按仓库证据填 `ARCHES`（不默认双架构），不改你已有的 `Makefile` 或 `.env`。
 2. 检查：只跑 `scripts/check.py --ready`，不改文件。
 3. 构建：走 `make -f makefile.builder`；只获构建授权时不走会自动上传的目标。
 4. 发布：先校验产物，再上传。缺发布键、未授权、或可能覆盖同版本时停下问你。