fix(runtime): validate cloud-build inputs and checksum

Signed-off-by: 117503445 <t117503445@gmail.com>

Author: 117503445

docs/en/runtime.md

@@ -114,13 +114,19 @@ ar runtime cloud-build -f FILE
 Runs only the `spec.container.cloudBuild` step and does not create or update the
 runtime. For each document, the command invokes docker-image-builder and reports
 `completed` when the builder exits successfully. The builder skips existing
-target tags by default.
+target tags by default. For multi-document YAML (`---` separated), every
+document must define `spec.container.cloudBuild`; otherwise the command fails
+before invoking any builder process.
 
 `cloud-build` uses the same credentials as `apply`: AgentRun profile values for
 Aliyun UID/AK/SK, and `DOCKER_IMAGE_BUILDER_USERNAME` /
 `DOCKER_IMAGE_BUILDER_PASSWORD` for registry auth unless the YAML overrides them
 under `cloudBuild.registry`.
 
+When the CLI downloads docker-image-builder automatically, it verifies the
+sibling `.sha256` file before caching or running the binary. Set
+`DOCKER_IMAGE_BUILDER_BINPATH` to use an explicit local builder binary.
+
 ### Examples
 
 ```bash

docs/zh/runtime.md

@@ -109,12 +109,16 @@ ar runtime cloud-build -f FILE
 
 只执行 `spec.container.cloudBuild` 构建步骤，不创建或更新 runtime。每篇文档都会调用
 docker-image-builder；builder 成功退出时输出 `completed`。docker-image-builder
-默认会跳过已存在的目标 tag。
+默认会跳过已存在的目标 tag。对于用 `---` 分隔的多文档 YAML，每篇都必须声明
+`spec.container.cloudBuild`；否则命令会在启动任何 builder 进程前失败。
 
 `cloud-build` 使用与 `apply` 相同的凭据来源：阿里云 UID/AK/SK 读取 AgentRun profile；
 镜像仓库用户名和密码优先读 YAML 的 `cloudBuild.registry`，否则读取
 `DOCKER_IMAGE_BUILDER_USERNAME` / `DOCKER_IMAGE_BUILDER_PASSWORD`。
 
+CLI 自动下载 docker-image-builder 时，会先校验同名 `.sha256` 文件，再缓存或执行该
+二进制。设置 `DOCKER_IMAGE_BUILDER_BINPATH` 可以使用显式指定的本地 builder。
+
 ### Examples
 
 ```bash

src/agentrun_cli/_utils/cloud_build.py

@@ -10,12 +10,13 @@
 import time
 import urllib.request
 from dataclasses import dataclass
+from hashlib import sha256
 from pathlib import Path
 from typing import Any
 
 from agentrun_cli._utils.agentruntime_yaml import ParsedAgentRuntime, ParsedCloudBuild
 
-BUILDER_RELEASE_TAG = "v0.0.0-20260527-022927-3f8907ca6b2f"
+BUILDER_RELEASE_TAG = "latest"
 BUILDER_BASE_URL = "https://images.devsapp.cn/docker-image-builder"
 
 
@@ -206,14 +207,17 @@ def ensure_builder_binary() -> str:
     tag = os.getenv("DOCKER_IMAGE_BUILDER_BINTAG", "").strip() or BUILDER_RELEASE_TAG
     install_dir = Path.home() / ".docker-image-builder" / tag
     target = install_dir / _executable_name()
-    if _is_executable(target):
-        return str(target)
 
     install_dir.mkdir(parents=True, exist_ok=True)
     tmp = install_dir / f"{_executable_name()}.tmp-{os.getpid()}"
-    url = f"{BUILDER_BASE_URL}/{tag}/{_artifact_name()}"
+    artifact = _artifact_name()
+    url = f"{BUILDER_BASE_URL}/{tag}/{artifact}"
     try:
+        expected_sha256 = _download_sha256(f"{url}.sha256", artifact)
+        if _is_executable(target) and _sha256_file(target) == expected_sha256:
+            return str(target)
         _download_binary(url, tmp)
+        _verify_sha256(tmp, expected_sha256)
         tmp.chmod(tmp.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
         tmp.replace(target)
     except Exception as exc:
@@ -233,6 +237,66 @@ def _download_binary(url: str, target: Path) -> None:
         target.write_bytes(resp.read())
 
 
+def _download_sha256(url: str, artifact_name: str) -> str:
+    """Download and parse a SHA256 checksum file.
+
+    Args:
+        url: Checksum URL.
+        artifact_name: Expected release artifact name.
+    """
+    with urllib.request.urlopen(url, timeout=30) as resp:  # noqa: S310
+        text = resp.read().decode("utf-8")
+    return _parse_sha256(text, artifact_name)
+
+
+def _parse_sha256(text: str, artifact_name: str) -> str:
+    """Parse a SHA256 checksum file.
+
+    Args:
+        text: Checksum file content.
+        artifact_name: Expected release artifact name.
+    """
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        digest = parts[0].lower()
+        if len(digest) != 64 or any(ch not in "0123456789abcdef" for ch in digest):
+            continue
+        if len(parts) == 1 or parts[-1].lstrip("*") == artifact_name:
+            return digest
+    raise CloudBuildError(f"invalid sha256 checksum file for {artifact_name}")
+
+
+def _verify_sha256(path: Path, expected_sha256: str) -> None:
+    """Verify a local file against an expected SHA256 digest.
+
+    Args:
+        path: File path to verify.
+        expected_sha256: Expected SHA256 digest.
+    """
+    actual_sha256 = _sha256_file(path)
+    if actual_sha256 != expected_sha256:
+        raise CloudBuildError(
+            "checksum mismatch for docker-image-builder: "
+            f"expected {expected_sha256}, got {actual_sha256}"
+        )
+
+
+def _sha256_file(path: Path) -> str:
+    """Compute the SHA256 digest of a local file.
+
+    Args:
+        path: File path to hash.
+    """
+    digest = sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
 def _is_executable(path: Path) -> bool:
     """Return whether the path is an executable file.
 

src/agentrun_cli/commands/runtime/cloud_build_cmd.py

@@ -7,6 +7,7 @@
 import click
 
 from agentrun_cli._utils.agentruntime_yaml import (
+    ParsedAgentRuntime,
     YamlSchemaError,
     parse_yaml_file,
 )
@@ -34,6 +35,27 @@ def _parse_file(path: str):
         raise SystemExit(EXIT_BAD_INPUT) from exc
 
 
+def _require_cloud_build_blocks(docs: list[ParsedAgentRuntime]) -> None:
+    """Validate that all runtime documents declare cloud build config.
+
+    Args:
+        docs: Parsed runtime documents.
+    """
+    missing = [
+        f"Document #{idx + 1} runtime {parsed.name!r}"
+        for idx, parsed in enumerate(docs)
+        if parsed.container.cloud_build is None
+    ]
+    if not missing:
+        return
+    echo_error(
+        "InvalidYaml",
+        "All runtime documents must define spec.container.cloudBuild before "
+        f"cloud-build starts; missing: {'; '.join(missing)}.",
+    )
+    raise SystemExit(EXIT_BAD_INPUT)
+
+
 @click.command(
     "cloud-build",
     help="Build Agent Runtime images in the cloud from YAML.",
@@ -49,18 +71,14 @@ def _parse_file(path: str):
 @handle_errors
 def cloud_build_cmd(ctx, file_path):
     load_dotenv()
+    docs = _parse_file(file_path)
+    _require_cloud_build_blocks(docs)
+
     profile, region = ctx_cfg(ctx)
     cfg = build_sdk_config(profile_name=profile, region=region)
-    docs = _parse_file(file_path)
 
     results = []
     for parsed in docs:
-        if parsed.container.cloud_build is None:
-            echo_error(
-                "InvalidYaml",
-                f"runtime {parsed.name!r} does not define spec.container.cloudBuild.",
-            )
-            raise SystemExit(EXIT_BAD_INPUT)
         result = build_runtime_image(parsed, cfg)
         if result is None:
             continue

tests/integration/test_runtime_cmd.py

@@ -70,6 +70,20 @@ def test_runtime_group_registered():
         image: registry.example.com/ns/worker:tag
 """
 
+MULTI_DOC_PARTIAL_CLOUD_BUILD_YAML = (
+    CLOUD_BUILD_YAML
+    + """
+---
+apiVersion: agentrun/v1
+kind: AgentRuntime
+metadata:
+  name: plain-agent
+spec:
+  container:
+    image: registry.example.com/ns/plain:v1
+"""
+)
+
 
 def test_render_outputs_rendered_input():
     fake_input = MagicMock()
@@ -172,6 +186,34 @@ def test_cloud_build_command_requires_cloud_build_block():
     assert result.exit_code == 2
 
 
+def test_cloud_build_command_prescans_all_docs_before_building():
+    result_obj = CloudBuildResult(
+        name="my-agent",
+        image="registry.example.com/ns/app:v1",
+        build_status="completed",
+        elapsed_seconds=0.1,
+    )
+    with (
+        patch(
+            "agentrun_cli.commands.runtime.cloud_build_cmd.build_sdk_config",
+            return_value=MagicMock(),
+        ) as cfg_mock,
+        patch(
+            "agentrun_cli.commands.runtime.cloud_build_cmd.build_runtime_image",
+            return_value=result_obj,
+        ) as build_mock,
+    ):
+        runner = CliRunner()
+        with runner.isolated_filesystem():
+            with open("rt.yaml", "w") as f:
+                f.write(MULTI_DOC_PARTIAL_CLOUD_BUILD_YAML)
+            result = runner.invoke(_root(), ["runtime", "cloud-build", "-f", "rt.yaml"])
+    assert result.exit_code == 2
+    assert "plain-agent" in result.output
+    cfg_mock.assert_not_called()
+    build_mock.assert_not_called()
+
+
 def test_cloud_build_command_no_results_exit_code_2():
     with (
         patch(