feat(builder): support project-local distribution scripts

skills/builder/references/contract.md

@@ -4,6 +4,10 @@
 check.py，本文档跟随。所有接入项目按同一套 make 目标、产物形状和环境变量执行，
 builder 脚本只做发布，不做项目特定的构建逻辑。
 
+配置边界按 Git 项目根生效：`makefile.builder` 所在仓库就是 builder 项目根。
+如果父仓库通过 submodule 引入另一个项目，submodule 的构建、`.env.builder` 和
+`.pouch/builder/` 分发脚本属于 submodule；父仓库不得替它承载这些配置。
+
 分工原则：**make 管构建（项目内、确定性），skill 脚本管发布（跨项目 SSOT），
 Agent 只保留授权判断和歧义处理。**
 
@@ -41,7 +45,7 @@ make -f makefile.builder <target>
 | `arches` | 可选（新模板必备） | 打印一行空格分隔的 `ARCHES`；无此目标视为存量 makefile，隐式单架构 |
 | `push-deb` | 同时有多种发布轨道的项目 | 仅调 builder 的 `upload_deb.sh`。未指定 `ARCH=` 时上传 `ARCHES` 中每一项对应的 `.deb`；指定了则只上传那一个 |
 | `push-docker` | 同时有多种发布轨道的项目 | 仅调 builder 的 `publish_docker.sh` |
-| `push-copy` | 同时有多种发布轨道的项目 | 仅调 builder 的 `copy_artifact.sh` |
+| `push-copy` | 同时有多种发布轨道的项目 | 仅调 builder 的 `copy_artifact.sh`；由它按配置选择内置拷贝或自定义脚本 |
 | `push` | 单一产物类型时必备；多产物项目为聚合 | 依序调用对应 push-* 或直接调脚本；是发布的唯一 make 入口 |
 
 规则：
@@ -49,7 +53,8 @@ make -f makefile.builder <target>
 1. 项目有 DEB 产物的判据：`makefile.builder` 配方引用 `dpkg-deb`/`debuild` 或产出 `.deb`。
    有镜像的判据：项目根存在 `Dockerfile`。
    Android 判据：配方产出 `.apk` / `.aab`。iOS 判据：配方产出 `.ipa`。
-   拷贝发布判据：配方调用 `copy_artifact.sh`。
+   拷贝发布判据：配方调用 `copy_artifact.sh`。`copy_artifact.sh` 是稳定入口，具体分发可由
+   `COPY_SCRIPT` 接管。
 2. 多于一种发布轨道必须拆 `push-deb` / `push-docker` / `push-copy`，`push` 依序聚合；
    单轨道项目一个 `push` 即可。
 3. `docker` 目标只能本地构建。多平台镜像无法拆成"make 构建 + 单独推送"
@@ -139,10 +144,25 @@ include $(HOME)/.pouch/skills/builder/scripts/version.mk
 
 | 变量 | 必填 | 说明 |
 |---|---|---|
-| `COPY_DEST` | 是 | 本地目录，或 Docker 目标 `container:/absolute/dir`（`docker cp`） |
+| `COPY_DEST` | 与 `COPY_SCRIPT` 至少配置一个 | 内置后备目标：本地目录，或 Docker 目标 `container:/absolute/dir`（`docker cp`） |
+| `COPY_SCRIPT` | 与 `COPY_DEST` 至少配置一个 | 推荐 `.pouch/builder/` 下的项目相对路径，也可用绝对路径；必须是可执行文件，同时配置时优先于 `COPY_DEST` |
 | `COPY_AS` | 否 | 第一份文件的额外 basename，逗号或空格分隔 |
 
-`copy_artifact.sh FILE [FILE ...]` 把已构建文件拷到 `COPY_DEST`，校验目标存在后打印 SHA-256。不读 `.env`。脏工作树默认拒绝，`ALLOW_UNCOMMITTED=1` 放行。
+`copy_artifact.sh FILE [FILE ...]` 是 APK/IPA 等产物的统一分发入口。不读 `.env`，脏工作树默认拒绝，
+`ALLOW_UNCOMMITTED=1` 放行。
+
+未配置 `COPY_SCRIPT` 时，入口把文件拷到 `COPY_DEST`，校验目标存在后打印 SHA-256。
+配置 `COPY_SCRIPT=.pouch/builder/publish-apk.sh` 时，入口按项目根解析、先校验每个文件存在，然后直接执行：
+
+```text
+/absolute/path/to/publish-script FILE [FILE ...]
+```
+
+相对路径只允许位于项目的 `.pouch/builder/` 下；绝对路径仍支持外部脚本。不经过 shell 字符串求值，
+不把 token 放进参数。脚本通过位置参数接收原始产物绝对路径，自行负责重命名、上传、远端校验和通知；
+当前项目根以 `BUILDER_PROJECT_ROOT` 环境变量提供。
+脚本返回非零即视为分发失败；成功后入口只报告脚本成功和本地 SHA-256，不宣称远端已校验。
+`--dry-run` 只打印将调用的脚本与文件，不执行自定义脚本。
 
 ### Docker 轨道