tilebox-workflow-releases

发布和部署 Tilebox 工作流

使用此技能初始化工作流项目，将工作流代码更改转为不可变版本，并将这些版本部署到一个或多个 Tilebox 集群。任务代码请使用 tilebox-workflow-authoring，项目脚手架、配置、发布、部署和运行器迭代请使用此技能。

Agent 发布循环

日常迭代时，采用最小且安全的循环：

1. 对于新项目，先按照以下策略选择一个可复用的能力名称，然后在手动创建项目文件前运行 tilebox workflow init --name "Scene QA" --json 进行一次初始化。只有当当前目录已有合适的、基于能力的名称时，才省略 --name。
2. 编辑工作流代码，并确保更改的文件包含在 [build].include 中且未被排除。
3. 可选的本地验证：tilebox workflow build-release --debug --json。
4. 发布：tilebox workflow publish-release --json。
5. 部署新版本。要快速获得首批结果，可省略 --cluster，使用 API 默认集群，而不必让用户选择。
6. 如果用户要求实际生成的产物，则部署后使用 tilebox-workflow-jobs 提交并验证一个具有代表性的任务；仅部署不会生成产物。
7. 如果没有兼容的运行器处于活动状态，且适合本地执行，则为同一集群启动动态运行器；省略 --cluster 同样会使用 API 默认集群。

对于类似生产环境的目标，优先使用指定的版本 ID；仅在可以接受的情况下，于开发迭代中使用 --latest。

如果现有任务因兼容的任务代码缺陷而失败，优先部署修复后的版本并重试失败任务，而不是从头提交新任务。

隐式地理空间项目的部署意图

当 tilebox 路由器通过隐式项目路由接受面向实现的地球观测或地理空间提示词时，除非用户限制范围，否则应将该提示词视为授权初始化远程工作流、发布版本并将其部署到非生产目标。

遵守以下边界：

• 对于常规的首批结果，若现有已配置的开发目标显然适用，则使用该目标；否则省略 --cluster，使用组织的 API 默认集群。不要仅仅为了运行一个小型工作流，就要求新用户选择或创建集群。
• 不要根据一般性的、以结果为导向的提示词推断或选择生产目标。必须有明确的生产意图。
• 遵守“仅代码”“本地原型”“不要发布”或“不要部署”等限制。
• 如果用户正在配置基础设施、推出专用集群，或在实质不同的执行环境之间进行选择，应解释集群概念并询问目标拓扑。
• 如果身份验证、合适的集群或运行器不可用，则尽可能完成并验证本地项目，然后报告具体的操作阻碍。不要声称已完成实际未发生的发布、部署或输出生成。
• 如果用户要求的结果是地图、动画、检测集、统计数据或其他生成产品，则部署后使用 tilebox-workflow-jobs。

初始化前，检查项目上下文。复用现有的 tilebox.workflow.toml。直接初始化空项目根目录或显然用于此项目的根目录；如果根目录中已有无关仓库，且工作流应独立存在，则使用基于能力的子目录，避免生成的工作流文件覆盖或混入无关项目文件。

选择可复用的工作流标识

工作流是可复用的程序；任务是该程序的一次实例。工作流名称应描述所有有效任务都适用的行为，而不是第一个提示词中要求的具体结果。对于独立的项目目录，也应遵循相同策略，因为省略 --name 时，workflow init 会从该目录派生名称。

初始化前，先确定根任务的预期输入和默认值。工作流名称中应排除：

• 具体输入值，例如地点、AOI、坐标、日期、时长、事件、场景 ID 和场景数量；
• 可配置选项的标签，例如 seasonal、monthly、sentinel-2、ndvi 或 gif，前提是任务输入可以选择频率、来源、算法／产品或输出格式；以及
• 不会限制后续任务可提交内容的首次运行或客户背景信息。

只有在某个术语描述固定的工作流行为或真正的实现边界时，才保留它。优先采用简洁的能力名称，例如 rgb-timelapse、cloud-masked-composite 或 sar-change-detection。对每个拟用词语都进行可复用性测试：其他有效提交能否在不更改工作流代码的情况下改变这个词？ 如果可以，就从工作流名称和 slug 中省略该词。将这些细节放入根任务输入中，并在适当时放入任务名称。

例如，假设首次运行请求维也纳、过去三年和每季一帧，而根任务接受 aoi、start、end 和 cadence。请将工作流初始化为：

mkdir rgb-timelapse
cd rgb-timelapse
tilebox workflow init --name "RGB Timelapse" --json

不要使用 vienna-seasonal-timelapse：vienna 是一个 AOI 值，seasonal 是一种频率选项。如果实现始终按季节对影像分组，且不提供频率选项，那么 seasonal-rgb-timelapse 就合适，因为此时 seasonal 描述的是固定行为。

初始化工作流项目

对于新的 Python 工作流项目，请先运行 tilebox workflow init，再创建 pyproject.toml、tilebox.workflow.toml、runner.py、源代码包或测试。不要手动编写初始工作流项目脚手架。

tilebox workflow init 会创建服务端工作流，将 API 返回的 slug 写入 tilebox.workflow.toml，生成本地项目文件脚手架，添加 tilebox Python 依赖，并运行 uv sync，使项目可以进行 build-release、publish-release、deploy-release、提交作业以及本地 release-runner 测试。它不会添加 ODC Geo、Shapely、Rasterio 或 async-geotiff 等特定任务的可选库；请声明工作流代码中导入的所有包，并重新运行 uv sync。

初始化时会有意使用精简的 runner.py。它只是脚手架，并不意味着建议将所有工作流代码都放在一个文件中。对于复杂工作流，请遵循 tilebox-workflow-authoring，将任务和处理逻辑移到结构清晰的包模块中，同时让 runner 入口点仅负责任务注册和 runner 级配置。如果入口点发生变更，请更新 [workflow].runner，并确保 [build].include 包含完整的包目录树。

工作流初始化、release 构建／发布验证以及 tilebox runner start 都要求 uv 位于 PATH 中。如果缺少 uv，请先修复 uv 安装，然后重新运行 tilebox workflow init。不要仅仅因为起初无法使用 uv 就改为手动搭建脚手架。

tilebox workflow init --json

如果目录名称并非你希望 Agent 和用户看到的名称，请明确提供可复用的能力名称：

tilebox workflow init --name "Scene QA" --json

CLI 实现中的初始化语义：

• 仅初始化当前目录。
• 如果 tilebox.workflow.toml、pyproject.toml、runner.py 或 uv.lock 中的任何一个已存在，则中止。
• 要求 uv 位于 PATH 中。
• 如果提供了 --name，则从中派生本地项目 slug；否则从当前目录名称派生。
• 将项目名称转换为 slug，并将其截断至最多 40 个字符，尽量保留完整单词。
• 创建远程 Tilebox 工作流，并将 API 返回的工作流 slug 写入 tilebox.workflow.toml。
• 生成 tilebox.workflow.toml、pyproject.toml 和 runner.py。
• 将 tilebox 添加为 pyproject.toml 依赖。
• 运行 uv sync，此操作会创建 uv.lock 和本地环境。

在自动化中依赖输出字段之前，请先刷新架构：

tilebox agent-context workflow init --output-schema

绑定现有或手动创建的工作流项目

仅在以下任一情况成立时使用此路径：

• 该目录是一个无法顺利初始化的现有工作流/代码库；
• 用户明确要求绑定现有 Tilebox 工作流 slug；
• 已尝试运行 tilebox workflow init，已诊断出失败原因，并且手动绑定是最小且安全的恢复方案。

对于新项目，不要先使用 tilebox workflow create。新项目应使用 tilebox workflow init，然后再逐步完善生成的文件。

对于现有或手动创建的工作流项目，请先在服务端手动创建工作流，然后在项目根目录中创建或更新 tilebox.workflow.toml。CLI 会从当前目录向上查找最近的配置文件，因此可以在子目录中运行命令。

WORKFLOW_SLUG=$(tilebox workflow create "Scene QA" \
  --description "Processes new scenes" \
  --json | jq -r '.slug')

cat > tilebox.workflow.toml <<EOF
[workflow]
slug = "$WORKFLOW_SLUG"
root = "."
runner = "scene_qa.runner:runner"

[build]
include = [
  "pyproject.toml",
  "uv.lock",
  "src/**",
]
exclude = [
  ".venv/**",
  "**/__pycache__/**",
  "**/*.pyc",
  ".pytest_cache/**",
]
use_gitignore = true

[targets.dev]
clusters = ["dev-cluster"]

[targets.production]
clusters = ["prod-a", "prod-b"]
EOF

CLI 实现中的配置规则：

• 文件名必须为 tilebox.workflow.toml。
• 必须设置 [workflow].slug。
• [workflow].root 可选，默认为 "."；所有构建路径都相对于该根目录。
• 以下两项必须且只能设置一项：
  • runner = "module:object"，会以 uv run python -m tilebox.workflows.runner module:object 的形式运行。
  • command = ["uv", "run", "python", "-m", "my_workflow.worker"]，用于指定自定义 worker 进程命令。
• 必须设置 [build].include，且至少包含一个模式。
• [build].exclude 可选。生成的 <workflow-slug>.tar.zst 归档也会自动从构建产物中排除。
• [build].use_gitignore 默认为 true。
• [targets.<name>].clusters 用于定义可重复使用的集群 slug 列表。--target 和 --cluster 只能使用其中一个，不能同时使用。
• 未知的 TOML 键会导致配置加载失败；请保持结构完全一致。

对于 runner = "module:object"，模块必须提供一个 runner 对象，且导入时不能启动该对象：

# scene_qa/runner.py
from tilebox.workflows import Runner
from tilebox.workflows.cache import LocalFileSystemCache

from scene_qa.tasks import SceneQA, SomeSubtask

runner = Runner(tasks=[SceneQA, SomeSubtask], cache=LocalFileSystemCache())

构建是可选的验证步骤

publish-release 会在上传前进行构建和验证，因此如果你希望在发布前获得更详细的反馈，build-release 是一个可选的检查步骤。

需要验证或运行 Python worker 运行时的工作流发布命令都要求 PATH 中存在 uv，包括 tilebox workflow build-release 和 tilebox workflow publish-release。如果缺少 uv，请先安装或修复 uv，然后重试发布命令。

tilebox workflow build-release --debug --json

构建命令会：

• 使用 [build].include、[build].exclude 和（启用时的）.gitignore，从 [workflow].root 解析要包含的文件；
• 创建确定性的本地 .tar.zst 构建产物和 SHA-256 摘要；
• 将构建产物解压到本地 Tilebox 构建产物缓存中；
• 启动已配置的 worker 运行时并调用任务发现；
• 返回内容指纹、任务标识符、文件，以及构建产物的摘要/路径。

如果构建失败，请先修复配置或运行时，再进行发布。常见修复方法：包含 pyproject.toml、uv.lock 和完整的工作流包目录树，例如 src/** 或 scene_qa/**；排除 .venv/**；确保从解压后的构建产物中可以解析 runner 导入路径。修复所有 Python 导入错误。

避免将大型运行时资源打包进发布版本

工作流发布包应包含代码和少量配置，而不是庞大的运行时资源。不要将模型检查点、嵌入权重、参考栅格、大型查找表、生成的缓存或下载的提供方数据包含在 [build].include 中。

如果项目可能包含大型本地资源，请添加明确的排除项：

[build]
exclude = [
  ".venv/**",
  ".cache/**",
  "models/**",
  "checkpoints/**",
  "data/**",
  "**/*.ckpt",
  "**/*.pt",
  "**/*.pth",
  "**/*.onnx",
]

对于 ML 检查点等可复用的运行时资源，请改为实现仅在运行器本地延迟加载：

• 首次使用时才获取资源，不要在导入、构建或发布期间获取。
• 对于私有模型权重等私有资源，请将其存储在已部署的运行器可访问的私有存储桶中，然后从该存储桶延迟加载。如果不存在运行器可访问的私有存储桶，请先让用户设置一个，再实现工作流。
• 将其缓存在确定性路径中，例如 ~/.cache/tilebox/models/<name>/<version>/...，这样在同一运行器上更换工作流发布版本后，缓存仍可保留。
• 使用前验证缓存文件，最好使用校验和；至少检查预期大小。删除损坏或不完整的文件并重新下载。
• 使用 functools.lru_cache 或等效的进程本地缓存封装开销较大的内存初始化，确保每个工作进程只加载一次模型。
• 发布包中仅保留用于定位、获取、验证和加载资源的代码。

示例结构：

from functools import lru_cache
from pathlib import Path


@lru_cache(maxsize=1)
def load_model() -> Model:
    checkpoint = ensure_cached_file(
        url=MODEL_URL,
        path=Path.home() / ".cache/tilebox/models/clay/v1.5/model.ckpt",
        min_size_bytes=900_000_000,
    )
    return Model.load_from_checkpoint(checkpoint)

将运行器本地缓存视为一种优化。工作流必须能在缓存为空的冷启动运行器上正常工作。

为运行器兼容的 wheel 固定 uv 源

动态运行器可能会在 Linux CPU 节点上解析并运行依赖项，即使本地开发是在硬件或软件包索引不同的机器上进行的。请在 pyproject.toml 中明确指定特定平台的 wheel 源，将 uv.lock 包含在发布包中，并避免依赖 CUDA/GPU wheel，除非能保证目标运行器集群支持它们。

对于 PyTorch 等依赖项，请在适当时固定为兼容 CPU 的 Linux 源：

dependencies = [
    "claymodel==1.5.0",
    "torch==2.4.0",
    "torchvision==0.19.0",
]

[tool.uv.sources]
torch = { index = "pytorch-cpu", marker = "sys_platform == 'linux'" }
torchvision = { index = "pytorch-cpu", marker = "sys_platform == 'linux'" }

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

如果运行器上的 uv sync 或发布验证失败，请检查锁文件或源索引是否是针对仅限本地的硬件生成的，而不是针对已部署的运行器平台生成的。

发布版本

发布会验证项目，在需要时上传资源，并创建不可变的工作流发布版本。对于相同的发布内容和资源摘要，发布操作具有幂等性：CLI 会返回现有发布版本，而不是创建重复项。

发布需要在 PATH 中找到 uv，因为它会在上传前构建并验证 Python 工作流运行时。

RELEASE_ID=$(tilebox workflow publish-release --debug --json | tee /tmp/workflow-release.json | jq -r '.id')
jq '{id, message, fingerprint, tasks, files}' /tmp/workflow-release.json

需要时，可从其他项目目录发布：

tilebox workflow publish-release ./path/to/project --json

在自动化中依赖输出字段之前，请使用以下命令刷新架构：

tilebox agent-context workflow publish-release --output-schema

通过发布新版本并重试来修复失败的任务

如果大型工作流因任务实现中的错误而失败，请勿立即重新提交整个作业。Tilebox 作业重试会将失败的任务重新排入队列，并从失败处继续，因此已完成的任务无需再次运行。

请按以下步骤操作：

1. 修复任务实现。
2. 保持任务标识符不变，并使用兼容的版本。对于向后兼容的修复，请提升次版本号；运行器可以用 v1.5 执行以 v1.3 提交的任务。
3. 将新工作流发布版本发布并部署到与失败作业相同的集群。
4. 重试失败的作业。

RELEASE_ID=$(tilebox workflow publish-release --json | jq -r '.id')
tilebox workflow deploy-release --release "$RELEASE_ID" --cluster "$CLUSTER" --json
tilebox job retry "$JOB_ID" --json

如果任务输入参数相同或向后兼容，并且失败作业所依赖的工作流结构/依赖关系图没有发生重大变化，此方法即可奏效。对于会导致输入或行为不兼容的更改，请勿依赖重试旧作业；应提升任务主版本号并提交新作业。

如果命令标志或输出结构会影响自动化，请先刷新作业 CLI 架构：

tilebox agent-context job retry --output-schema

部署或取消部署发布版本

部署会将工作流发布版本映射到集群，但本身不会提交作业。在包含 tilebox.workflow.toml 的项目中运行时，可省略 --workflow；CLI 会使用 [workflow].slug。

部署刚刚发布的版本：

tilebox workflow deploy-release --release "$RELEASE_ID" --target dev --json

将最新版本部署到开发／默认集群：

tilebox workflow deploy-release --latest --target dev --json
tilebox workflow deploy-release --latest --cluster dev-cluster --json
tilebox workflow deploy-release --latest --json  # API default cluster

将指定发布版本部署到多个显式指定的集群：

tilebox workflow deploy-release \
  --workflow "$WORKFLOW_SLUG" \
  --release "$RELEASE_ID" \
  --cluster cluster-a,cluster-b \
  --json

取消部署遵循相同的选择器规则，并移除当前生效的发布版本映射：

tilebox workflow undeploy-release --latest --target dev --json
tilebox workflow undeploy-release --release "$RELEASE_ID" --cluster cluster-a --json

选择器规则：

• 必须且只能传入 --release <uuid> 或 --latest 其中之一。
• --release 必须是 UUID。
• --target <name> 需要本地存在 tilebox.workflow.toml，且该目标必须存在于 [targets] 中。
• --cluster 使用逗号分隔，且不能与 --target 同时使用。
• 如果省略 --cluster 和 --target，API 将使用默认集群。

检查状态：

tilebox workflow get --json
tilebox workflow get "$WORKFLOW_SLUG" --json
tilebox cluster get dev-cluster --json

在本地启动动态运行器

动态运行器会为部署到集群的发布版本执行任务。它会轮询集群部署状态，下载并解压缺失的构件，验证发布版本中的任务注册，启动 Python 工作进程运行时，并持续运行。日志输出到 stderr，且不会输出 JSON。

tilebox runner start 需要 PATH 中有 uv，才能从工作流发布构件启动 Python 工作进程运行时。如果缺少 uv，请先安装或修复 uv，再启动运行器。

终端 1：

tilebox runner start --cluster dev-cluster --debug

省略 --cluster，使用 API 默认集群：

tilebox runner start --debug

在继续导出 Tilebox 日志的同时，静默控制台日志：

tilebox runner start --cluster dev-cluster --quiet

在终端 2 中，将发布版本部署到同一集群后，提交一个根任务：

tilebox job submit \
  --name scene-qa-test \
  --task tilebox.com/example/SceneQA \
  --version v1.0 \
  --cluster dev-cluster \
  --input '{"scene_id":"S2A_001"}' \
  --wait \
  --json

用于调试的运行器说明：

• 没有已部署的工作流时，运行器会在本地空闲运行并记录警告。
• 部署变更会通过轮询发现，间隔约为 10 秒，另加随机抖动。
• 无效的已部署发布版本会被跳过，有效发布版本仍可运行。
• 如果两个已部署的发布版本公开了冲突的任务标识符，运行器不会公布存在歧义的发布版本。
• 运行器会处理中断：第一次中断会停止认领新任务并尝试正常关闭；第二次中断会快速退出。

安全的自动化模式

当用户要求发布并部署当前项目时，请在 Agent 脚本中使用以下 Shell 结构：

set -euo pipefail

release_json=$(tilebox workflow publish-release --json)
release_id=$(jq -r '.id' <<<"$release_json")
test -n "$release_id" && test "$release_id" != "null"

tilebox workflow deploy-release --release "$release_id" --target dev --json

如果未配置目标，请使用显式指定的集群：

tilebox workflow deploy-release --release "$release_id" --cluster dev-cluster-a,dev-cluster-b --json