# 拿到产物（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，也不创建分支。

## 命令

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

成功打印：

```text
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 | 项目 CI 状态脚本无法查询 | 停；回到初始化补 `CI_STATUS_SCRIPT`，或用**已打开且已登录**的同 host Orca tab 查流水线。禁止新开未登录页 |

## `ci` 规则

- 只认该 SHA 的 pipeline，不认默认分支「最新一次绿」。
- 不触发流水线。
- 查询命令是项目 `.pouch/builder/ci-status.sh`（`CI_STATUS_SCRIPT`），初始化时按 tea / glab / gh / curl 写好。凭据仍放 `.env.builder`。
- 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。