feat(runtime): add cloud image build support

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

Author: 117503445

README.md

@@ -13,7 +13,7 @@ agents that you configure declaratively without writing or deploying any runtime
 
 - **One-command super agent** — `ar super-agent run` creates a hosted agent and drops you into a chat REPL in seconds.
 - **Declarative deployment** — Kubernetes-style YAML (`ar sa apply -f superagent.yaml`) for reproducible, version-controlled agents.
-- **Runtime declarative deploy** — `ar runtime apply -f runtime.yaml` builds an Agent Runtime from a container image and waits for it to reach `READY`.
+- **Runtime declarative deploy** — `ar runtime apply -f runtime.yaml` deploys an Agent Runtime from an image, or cloud-builds that image first when the YAML defines `cloudBuild` and the tag is missing.
 - **Seven resource groups** — `config`, `model`, `sandbox`, `tool`, `skill`, `super-agent`, `runtime`, all following the same `ar <group> <action>` pattern.
 - **Multi-profile config** — store multiple sets of credentials in `~/.agentrun/config.json` and switch with `--profile`.
 - **Multiple output formats** — `json` (default), `table`, `yaml`, and `quiet` for shell piping.
@@ -191,6 +191,25 @@ EOF
 ar runtime apply -f runtime.yaml
 ```
 
+To cloud-build the image only when the target tag is missing, add `cloudBuild`:
+
+```bash
+cat > runtime-build.yaml <<EOF
+apiVersion: agentrun/v1
+kind: AgentRuntime
+metadata: {name: my-agent}
+spec:
+  container:
+    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+    cloudBuild:
+      dir: .
+      setupScript: scripts/setup.sh
+EOF
+ar runtime apply -f runtime-build.yaml
+# or build without deploying:
+# ar runtime cloud-build -f runtime-build.yaml
+```
+
 ## Command groups
 
 | Group | Alias | Purpose | Docs |
@@ -201,7 +220,7 @@ ar runtime apply -f runtime.yaml
 | `tool` |  | MCP and FunctionCall tools | [en](./docs/en/tool.md) · [zh](./docs/zh/tool.md) |
 | `skill` |  | Platform skill packages + local execution | [en](./docs/en/skill.md) · [zh](./docs/zh/skill.md) |
 | `super-agent` | `sa` | Quickstart / CRUD / declarative / conversation | [en](./docs/en/super-agent.md) · [zh](./docs/zh/super-agent.md) |
-| `runtime` | `rt` | Declarative Agent Runtime deploy (container mode) | [en](./docs/en/runtime.md) · [zh](./docs/zh/runtime.md) |
+| `runtime` | `rt` | Declarative Agent Runtime deploy and optional cloud image build | [en](./docs/en/runtime.md) · [zh](./docs/zh/runtime.md) |
 
 ## Documentation
 

README_zh.md

@@ -12,7 +12,7 @@ Agent）**：一种由平台托管、用户只需声明配置、无需编写或
 
 - **一键拉起超级 Agent** — `ar super-agent run` 一条命令创建托管 Agent 并进入 REPL 对话。
 - **声明式部署** — Kubernetes 风格 YAML（`ar sa apply -f superagent.yaml`），可版本化、可重复部署。
-- **Runtime 声明式部署** — `ar runtime apply -f runtime.yaml` 从容器镜像创建 Agent Runtime 并等待 `READY`。
+- **Runtime 声明式部署** — `ar runtime apply -f runtime.yaml` 从镜像部署 Agent Runtime；YAML 写了 `cloudBuild` 且目标 tag 不存在时，会先云上构建该镜像。
 - **七大资源组** — `config`、`model`、`sandbox`、`tool`、`skill`、`super-agent`、`runtime`，统一 `ar <group> <action>` 模式。
 - **多 Profile 配置** — `~/.agentrun/config.json` 支持多套凭证，通过 `--profile` 切换。
 - **多种输出格式** — 默认 `json`，支持 `table` / `yaml` / `quiet`（适合 shell 管道）。
@@ -187,6 +187,25 @@ EOF
 ar runtime apply -f runtime.yaml
 ```
 
+如果目标镜像 tag 不存在时需要先云上构建，可增加 `cloudBuild`：
+
+```bash
+cat > runtime-build.yaml <<EOF
+apiVersion: agentrun/v1
+kind: AgentRuntime
+metadata: {name: my-agent}
+spec:
+  container:
+    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+    cloudBuild:
+      dir: .
+      setupScript: scripts/setup.sh
+EOF
+ar runtime apply -f runtime-build.yaml
+# 或者只构建不部署：
+# ar runtime cloud-build -f runtime-build.yaml
+```
+
 ## 命令组总览
 
 | 命令组 | 别名 | 用途 | 文档 |
@@ -197,7 +216,7 @@ ar runtime apply -f runtime.yaml
 | `tool` |  | MCP 与 FunctionCall 工具 | [en](./docs/en/tool.md) · [zh](./docs/zh/tool.md) |
 | `skill` |  | 平台技能包 + 本地执行 | [en](./docs/en/skill.md) · [zh](./docs/zh/skill.md) |
 | `super-agent` | `sa` | 一键拉起 / CRUD / 声明式 / 会话管理 | [en](./docs/en/super-agent.md) · [zh](./docs/zh/super-agent.md) |
-| `runtime` | `rt` | 声明式 Agent Runtime 部署（容器模式） | [en](./docs/en/runtime.md) · [zh](./docs/zh/runtime.md) |
+| `runtime` | `rt` | 声明式 Agent Runtime 部署，可选云上镜像构建 | [en](./docs/en/runtime.md) · [zh](./docs/zh/runtime.md) |
 
 ## 文档
 

agentruntime.yaml

@@ -20,6 +20,9 @@ metadata:
 spec:
   container:
     image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+    # cloudBuild:                         # optional; build only if image tag is missing
+    #   dir: .                            # source directory uploaded to builder
+    #   setupScript: scripts/setup.sh     # empty string skips setup
     # command: ["python", "app.py"]       # optional, overrides image CMD/ENTRYPOINT
     # port: 9000                          # optional; spec.port below also works
 

docs/en/runtime-yaml.md

@@ -15,6 +15,7 @@ rejected (see [Validation rules](#validation-rules)).
 - [CLI auto-injection](#cli-auto-injection)
 - [`metadata`](#metadata)
 - [`spec.container`](#speccontainer)
+- [`spec.container.cloudBuild`](#speccontainercloudbuild)
 - [`spec` resource & runtime knobs](#spec-resource--runtime-knobs)
 - [`spec.protocol`](#specprotocol)
 - [`spec.network`](#specnetwork)
@@ -77,7 +78,8 @@ Required block. Defines the container image and registry credentials.
 
 | Key | Type | Required | Notes |
 |---|---|---|---|
-| `image` | string | ✓ | OCI image reference. |
+| `image` | string | ✓ | OCI image reference. When `cloudBuild` is set, this is also the target image pushed by the builder and must include an explicit tag. |
+| `cloudBuild` | mapping |  | Build the image in the cloud when `image` is missing from the registry. Existing tags are never rebuilt or overwritten. |
 | `command` | list<string> |  | Overrides image `ENTRYPOINT`/`CMD`. |
 | `port` | int |  | Container listen port. If set, wins over `spec.port`. |
 | `imageRegistryType` | enum |  | One of `ACR`, `ACREE`, `CUSTOM`. |
@@ -103,6 +105,44 @@ registryConfig:
 All three sub-blocks (`auth`, `cert`, `network`) are individually optional, but
 `registryConfig` itself is mandatory under `CUSTOM`.
 
+
+## `spec.container.cloudBuild`
+
+Optional block. It asks `ar runtime apply` or `ar runtime cloud-build` to build
+`spec.container.image` with docker-image-builder **only when that image tag does
+not already exist**. The target image is always `spec.container.image`.
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `dir` | string | `.` | Local source directory to upload. Relative paths are resolved from the current working directory. |
+| `setupScript` | string | `scripts/setup.sh` | Script executed in the builder before packaging. Empty string skips setup. |
+| `timeoutMinutes` | string/number | `20` | Setup script timeout in minutes. Worker creation, upload and push are not counted. |
+| `cpu` | string/number | `4` | Builder worker CPU, for example `4` or `4c`. |
+| `memory` | string/number | `8192` | Builder worker memory in MB. |
+| `region` | string | AgentRun region / `cn-hangzhou` | FC region for the builder worker. |
+| `registry` | mapping | env vars | Optional target registry auth; see below. |
+
+Only standard OCI registry mode is supported. Do not write `registryMode`,
+`baseImage`, `baseAcrInstanceId`, or `baseRegistry` in this block.
+
+```yaml
+cloudBuild:
+  dir: .
+  setupScript: scripts/setup.sh
+  timeoutMinutes: 20
+  cpu: 4
+  memory: 8192
+  registry:
+    username: deploy-bot
+    password: ${DOCKER_IMAGE_BUILDER_PASSWORD}
+```
+
+`registry.username` and `registry.password` are optional. If omitted, the CLI
+reads `DOCKER_IMAGE_BUILDER_USERNAME` and `DOCKER_IMAGE_BUILDER_PASSWORD` from
+the environment or `.env`. Aliyun UID/AK/SK are resolved from the active
+AgentRun profile and passed to docker-image-builder through environment
+variables.
+
 ## `spec` resource & runtime knobs
 
 | Key | Type | Default | Notes |
@@ -274,6 +314,8 @@ for the parser (`src/agentrun_cli/_utils/agentruntime_yaml.py`).
 | `metadata.name` missing or fails `[a-z0-9-]{1,63}` |  |
 | `spec.container` missing or not a mapping |  |
 | `spec.container.image` missing or empty |  |
+| `spec.container.cloudBuild` is set but `image` is not `registry/repository:tag` | The builder target must be deterministic. |
+| `spec.container.cloudBuild` has unsupported fields | Only OCI mode is supported; ACREE/base-registry builder fields are rejected. |
 | `spec.container.imageRegistryType` not in `ACR|ACREE|CUSTOM` |  |
 | `imageRegistryType=CUSTOM` but `registryConfig` missing |  |
 | `metadata.tags` present | SDK 0.0.200 removed the field. |
@@ -320,6 +362,28 @@ spec:
 # system_tags=["x-agentrun-cli"], artifact_type=Container
 ```
 
+
+### Cloud build when image is missing
+
+```yaml
+apiVersion: agentrun/v1
+kind: AgentRuntime
+metadata:
+  name: my-agent
+spec:
+  container:
+    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+    cloudBuild:
+      dir: .
+      setupScript: scripts/setup.sh
+  env:
+    LOG_LEVEL: info
+```
+
+`ar runtime apply -f runtime.yaml` checks the image tag first. If it exists, the
+build step is skipped. If it does not exist, the CLI invokes docker-image-builder
+and then deploys the same `image` value.
+
 ### Production — ACREE + private network + NAS + canary endpoint
 
 ```yaml
@@ -406,6 +470,7 @@ For users who need to cross-reference the SDK
 | `spec.container.imageRegistryType` | `container_configuration.image_registry_type` |
 | `spec.container.acrInstanceId` | `container_configuration.acr_instance_id` |
 | `spec.container.registryConfig.*` | `container_configuration.registry_config.*` |
+| `spec.container.cloudBuild.*` | CLI-only build plan; not sent to AgentRun SDK. |
 | `spec.cpu / memory / port / diskSize` | `cpu / memory / port / disk_size` |
 | `spec.enableSessionIsolation` | `enable_session_isolation` |
 | `spec.protocol.type` | `protocol_configuration.type` |

docs/en/runtime.md

@@ -2,10 +2,11 @@
 
 # ar runtime
 
-Manage **Agent Runtimes** declaratively from a YAML file. The CLI only supports
-container-mode runtimes (you supply an OCI image; building the image is out of
-scope for this command group). Endpoints are embedded in the same YAML; the
-default behaviour is to inject one named `default` (`targetVersion=LATEST`).
+Manage **Agent Runtimes** declaratively from a YAML file. The CLI supports
+container-mode runtimes from an existing OCI image, and can optionally build a
+missing image in the cloud before deployment through `spec.container.cloudBuild`.
+Endpoints are embedded in the same YAML; the default behaviour is to inject one
+named `default` (`targetVersion=LATEST`).
 
 Also available as the alias `ar rt`.
 
@@ -15,7 +16,8 @@ Also available as the alias `ar rt`.
 
 ## Commands
 
-- [apply](#apply) — create-or-update from YAML, with status polling.
+- [apply](#apply) — build a missing image if needed, then create-or-update from YAML.
+- [cloud-build](#cloud-build) — build missing images from YAML without deploying.
 - [render](#render) — dry-run validate + render to SDK input.
 - [get](#get) — fetch one runtime by name.
 - [list](#list) — list runtimes; filter by `--created-by-cli` or `--workspace`.
@@ -49,7 +51,10 @@ ar runtime apply -f FILE [--wait/--no-wait] [--timeout DURATION]
 
 The CLI injects sensible defaults for `cpu` (2 cores), `memory` (4096 MB) and
 `port` (9000) when the YAML omits them — the backend rejects null values for
-these three fields with HTTP 400.
+these three fields with HTTP 400. If `spec.container.cloudBuild` is present,
+`apply` first checks whether `spec.container.image` exists in the registry. It
+only runs the cloud build when that image tag is missing, then deploys the same
+image reference. Existing images are never rebuilt or overwritten.
 
 ### Examples
 
@@ -65,6 +70,20 @@ spec:
 EOF
 ar runtime apply -f runtime.yaml
 
+# Build in the cloud only if the target image tag is missing, then deploy.
+cat > runtime-build.yaml <<EOF
+apiVersion: agentrun/v1
+kind: AgentRuntime
+metadata: {name: my-agent}
+spec:
+  container:
+    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+    cloudBuild:
+      dir: .
+      setupScript: scripts/setup.sh
+EOF
+ar runtime apply -f runtime-build.yaml
+
 # Non-blocking submit (CI-friendly):
 ar runtime apply -f runtime.yaml --no-wait
 
@@ -75,6 +94,38 @@ ar runtime apply -f runtime.yaml --timeout 20m
 ar runtime apply -f runtime.yaml --no-prune-endpoints
 ```
 
+
+---
+
+## cloud-build
+
+```
+ar runtime cloud-build -f FILE
+```
+
+### Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `-f`, `--file` | path | yes |  | YAML file path (supports multi-document). |
+
+Runs only the `spec.container.cloudBuild` step and does not create or update the
+runtime. For each document, the command checks `spec.container.image` first; if
+the tag already exists, it reports `skippedExisting`, otherwise it invokes
+`docker-image-builder` and reports `built`.
+
+`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`.
+
+### Examples
+
+```bash
+# Build only; do not deploy the runtime.
+ar runtime cloud-build -f runtime-build.yaml
+```
+
 ---
 
 ## render
@@ -91,8 +142,10 @@ ar runtime render -f FILE
 
 Validates the YAML, applies CLI auto-injection (`system_tags=["x-agentrun-cli"]`,
 `artifact_type=Container`, default endpoint when `spec.endpoints` is omitted),
-and prints the SDK create-input as JSON without calling the server. Use this to
-preview changes before `apply`.
+and prints the SDK create-input as JSON without calling the server. When the
+YAML includes `cloudBuild`, `render` also prints a `cloudBuildPlan` preview but
+does not check the registry or build anything. Use this to preview changes
+before `apply`.
 
 ---