Merge remote-tracking branch 'origin/main' into rename

skills/builder/README.md

@@ -17,6 +17,7 @@
 
 1. 用 create-makefile skill 生成或修正 Makefile（目标 `help/build/clean/version`
    + 条件 `deb/docker/push*`，变量 `ARCH/VERSION/DIST_DIR/PROJECT_NAME`）。
+   `VERSION` 通过 `include <builder>/scripts/version.mk` 从 Git 推导。
 2. 运行 `python3 -I -S <builder>/scripts/check.py .` 直到全部 PASS。
 3. 在项目根 `.env` 配置发布环境变量：
 
@@ -29,12 +30,62 @@ DOCKER_REGISTRY=registry.example.com
 
 4. 日常发布就是两条命令：`make deb && make push-deb`、`make push-docker`。
 
+## 版本号
+
+产物版本从 **当前 HEAD 的 Git 祖先** 推导，不调用 manage-release。
+正式 tag 仍由 manage-release 创建；builder 只读取。完整规则见
+[contract.md「版本号」](references/contract.md#版本号)。
+
+| 谁 | 做什么 |
+| --- | --- |
+| manage-release | 选定下一个正式 SemVer，打 annotated tag `vX.Y.Z` |
+| builder | 读 HEAD：落在稳定 tag 上则打正式产物，否则打测试产物 |
+| `make version` | 输出一行规范版本（无 `v` 前缀），DEB / Docker 都从它渲染 |
+
+**不要**用 `git tag \| sort -V \| tail -1` 取全仓库最大号，也不要把
+`git describe --dirty` 的原始字符串写进 DEB 或镜像 tag。
+
+### 正式（HEAD 恰好是稳定 tag `v1.4.2`）
+
+```text
+Git tag      v1.4.2
+规范版本     1.4.2
+DEB          foo_1.4.2_amd64.deb          Version: 1.4.2
+Docker       registry/ns/foo:1.4.2
+```
+
+稳定 tag 仅匹配 `v<major>.<minor>.<patch>`，不含 `-rc`、`-app-N` 等后缀。
+不是 exact-match 就不是正式包。
+
+### 测试（其它任何 commit）
+
+基线 = 祖先上最近的那颗稳定 tag（没有则为 `0.0.0`），再加上清洗后的
+分支名、相对距离、短 SHA。测试与正式进**同一个** apt / Docker 仓库，
+所以 DEB 必须用 `~`，保证测试包不会 `apt upgrade` 盖住正式包。
+
+分支 `feat/login-v2`，相对 `v1.4.2` 第 7 个 commit，SHA `abc1234`：
+
+```text
+规范 / DEB   1.4.2~feat-login-v2.7+gabc1234
+文件名       foo_1.4.2~feat-login-v2.7+gabc1234_amd64.deb
+Docker       registry/ns/foo:1.4.2-feat-login-v2.7.gabc1234
+```
+
+Docker tag 由规范版本映射：`~` → `-`，`+g` → `.g`（Docker 不允许 `~`）。
+安装测试包必须显式指定版本或完整 tag，不能靠无参 `apt upgrade`。
+
+### 分支名清洗
+
+小写；`/`、`_` 改为 `-`；去掉其它非法字符；压缩连续 `-`；过长截断。
+detached HEAD 用 `detached`，CI 可注入 `BUILD_BRANCH` / `CI_COMMIT_BRANCH` /
+`GITHUB_REF_NAME`。脏工作树不把 `-dirty` 写进版本（发布本身会拒绝）。
+
 ## 使用示例
 
 ```text
 用 builder 检查这个项目的 Makefile 是否符合契约。
 用 builder 构建当前版本的 DEB 和镜像，先不要上传。
-用 builder 把 dist/example_1.2.3_amd64.deb 发布到项目已配置的测试仓库。
+用 builder 把当前 commit 的产物发布到项目已配置的仓库。
 用 builder 发布多平台 linux/amd64,linux/arm64 镜像。
 ```
 
@@ -43,6 +94,8 @@ DOCKER_REGISTRY=registry.example.com
 | 脚本 | 用途 |
 |------|------|
 | `scripts/check.py` | 校验项目 Makefile 是否符合契约（`--build` 实构核对产物） |
+| `scripts/version.sh` | 从 Git 祖先稳定 tag 推导规范版本 / Docker tag |
+| `scripts/version.mk` | 项目 Makefile `include`，设置 `VERSION` 与 `IMAGE_TAG` |
 | `scripts/upload_deb.sh` | 上传 `.deb` 到 HTTP 包仓库（multipart package/token/repository_name） |
 | `scripts/publish_docker.sh` | buildx 构建 + 推送镜像，远端 digest 验证 |
 | `scripts/verify_deb.sh` | 核对包元数据、内容与 SHA-256 |