.pouch/skills/builder/references/obtain.md

拿到产物（obtain）

Builder 的交付入口是 按精确 Git commit 拿到产物，不是「在哪台机器编译」。 docker / deb / android / ios / copy 仍是轨道；BUILD_VENUE 只说明构建发生在本机还是 CI。

谁来调用

• short-ship / long-ship 和 ACK 走到 delivery-loop 的 artifact_built 时。
• 用户说「看构建」「监听 CI」「拿到镜像」时。
• make -f makefile.builder obtain 或 push-docker（BUILD_VENUE=ci）。

代码必须已经推到远端（ci 时流水线由 git ref 触发）。Builder 不代替 releaser 打 tag，也不创建分支。

命令

<builder>/scripts/obtain.sh --sha <full-sha> [--branch <name>] [--root <project>] [--timeout 1200]

成功打印：

ARTIFACT=harbor.example.com/ns/name:1.4.2
DIGEST=sha256:…
SHA=<full-sha>
VENUE=ci
TAG=1.4.2

镜像 tag 对该 SHA 跑 version.sh --docker（可 --branch 注入 CI_COMMIT_BRANCH），禁止 git describe。

退出码

码	含义	调用方
0	产物已核验	artifact_built 完成
1	该 SHA 无流水线、job 失败、超时、inspect 失败	标 failed，不得 publish/deploy
2	用法或配置错误	标 blocked
3	glab/gh/curl 缺失或读不到该项目	停；可用已打开且已登录的同 host Orca tab 查流水线。禁止新开未登录页

ci 规则

• 只认该 SHA 的 pipeline，不认默认分支「最新一次绿」。
• 不触发流水线。
• Gitea 使用 Actions REST API 的 head_sha 精确过滤，并读取每个 workflow run 的 jobs；私有仓库可在 .env.builder 配置 GITEA_TOKEN。自定义 Gitea host 可设置 BUILDER_CI_FORGE=gitea，API 前缀默认是 https://<origin-host>/api/v1，也可用 GITEA_API_URL 覆盖。
• job 变绿不够，docker 轨道必须 inspect 到 digest。
• 合进 main 若项目不构建，no_pipeline 是正确失败。预览走项目会构建的 ref（如 dev/*），正式走 tag。

Agent

1. 固化 source revision 为完整 SHA。
2. 跑 obtain.sh --sha <sha>。
3. 退出 0：记录 ARTIFACT/DIGEST/SHA。venue=ci 且 job 已 push 时，published 视为已满足，不要本机再 publish_docker.sh。
4. 退出 1/2：停止 delivery-loop，报告 pipeline URL 或 no_pipeline。
5. 退出 3：先说明 CLI 身份不对；只有已有同 host 登录 tab 时才用来读 pipeline。