mcpField
T
tilebox-workflow-jobs

tilebox-workflow-jobs

github.com/tilebox云与 DevOps083 次安装今天更新
代码仓库

关于 tilebox-workflow-jobs

为使用 Tilebox Workflows 的 Agent 提供作业操作指南，涵盖提交、查询、排错、重试与取消，并说明任务输入和日志追踪方法。

主要功能

  1. 01提交及等待作业
  2. 02筛选和检查作业状态
  3. 03查看日志与执行跨度
  4. 04重试失败任务或取消作业
  5. 05校验任务标识与输入格式

适用场景

  1. 01向集群提交工作流任务
  2. 02排查任务失败及运行时序
  3. 03检查进度并决定重试或取消

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tilebox/skills --skill tilebox-workflow-jobs

安装后在 Claude Code 中输入/tilebox-workflow-jobs确认已加载。

详细介绍

管理 Tilebox 作业

使用此技能通过 tilebox job 和 tilebox cluster 执行运维工作。对于 Agent，除非明确要输出供人阅读的内容，否则每条作业命令都要使用 --json。

刷新 CLI 元数据

在依赖记忆操作前，先检查已安装 CLI 的准确标志和架构：

tilebox agent-context job --output-schema
tilebox agent-context cluster --output-schema

相关文档概念：

  • Tilebox Workflows 是用于跨集群处理任务的并行处理引擎。
  • 提交作业后会启动一条跟踪；每次任务运行都会创建一个跨度。
  • 任务日志会关联作业、任务、运行器、服务、跟踪和跨度元数据。
  • 在活动跨度中发出的日志也会作为跨度事件显示在跟踪视图中。

命令选择

  • 开始工作：tilebox job submit --name ... --task ... --input ... --json。
  • 查找作业：tilebox job list --last 7d --json，或使用 --state、--task-state、--name 进行筛选。
  • 检查单个作业：tilebox job get <job-id> --json。
  • 等待作业完成、失败或取消：tilebox job wait <job-id> --json。
  • 检查作业日志消息：tilebox job logs <job-id> --sort desc --limit 100 --json。
  • 调试耗时时检查作业跟踪和跨度：tilebox job spans <job-id> --sort asc --json。
  • 修复原因后，重试符合条件的失败任务：tilebox job retry <job-id> --json。
  • 停止待处理或正在运行的工作：tilebox job cancel <job-id> --json。

如果不清楚某条命令的参数或输出格式，请使用 tilebox agent-context job <subcommand> --output-schema。agent-context 始终返回 JSON；不要为它添加 --json。

提交作业

基本格式：

tilebox job submit \
  --name <job-name> \
  --task <task-identifier-name> \
  --version v0.0 \
  --input '<json-or-plain-text>' \
  --json

重要标志：

  • --name：必需的作业名称。它用于标识一次执行，可包含有用的运行上下文，例如位置、时段或执行频率。不要将特定实例的作业名称用作工作流名称或 slug。
  • --task：必需的任务标识符名称。
  • --version：默认为 v0.0。
  • --input：内联 JSON 或纯文本。有效的 JSON 会直接传递；非 JSON 文本会转换为 JSON 字符串。
  • --input-file：从文件读取输入；使用 - 表示标准输入。
  • --cluster：可选的集群 slug；省略时使用默认集群。
  • --max-retries：根任务的重试次数，默认为 0。
  • --wait：提交后等待，效果类似于 tilebox job wait <new-job-id>。

只有在确认有兼容的运行器可用且预期会执行该任务时，才使用 --wait。否则，请在不使用 --wait 的情况下提交，然后通过 job get、job logs 或 job spans 检查。

示例：

tilebox job submit --name process-scene --task ProcessScene --input S2A_001 --json
tilebox job submit --name process-count --task ProcessCount --input 5 --json
tilebox job submit --name process-count --task ProcessCount --input '"5"' --json
tilebox job submit --name structured --task tilebox.com/process_scene --version v1.0 --input '{"scene_id":"S2A_001","other_arg":3}' --json
tilebox job submit --name from-file --task ProcessScenes --input-file scenes.json --json
cat scenes.json | tilebox job submit --name from-stdin --task ProcessScenes --input-file - --json

提交 Python CronTask 或 StorageEventTask 时，请使用 tilebox-workflow-automations 技能。这些任务需要使用 --automation 来构造自动化触发器封装。

Python 任务标识符和输入

Python Task 类默认使用 <ClassName>@v0.0 作为标识符，除非定义了显式的 identifier() 方法。请与运行器注册的确切任务名称和版本保持一致。

输入必须符合 Python serialize_task(task) / deserialize_task(TaskClass, bytes) 的要求：

  • 无字段：省略输入或提交 {}。
  • 一个字段：直接提交字段值。
    • scene_id: str -> --input S2A_001 会提交 JSON 字符串 "S2A_001"。
    • count: int -> --input 5 会提交 JSON 数字 5；若要提交字符串 "5"，请使用 --input '"5"'。
    • scene_ids: list[str] -> 提交 JSON 数组，而非对象。
  • 多个字段：提交以字段名为键的 JSON 对象。

不确定时，请使用 Python 生成准确的负载：

/path/to/.venv/bin/python - <<'PY' > task-input.json
from test import ProcessScenes
from tilebox.workflows.task import serialize_task, deserialize_task

task = ProcessScenes(["S2A_001", "S2B_002"])
payload = serialize_task(task)
assert deserialize_task(ProcessScenes, payload).scene_ids == task.scene_ids
print(payload.decode())
PY

tilebox job submit --name process-scenes --task ProcessScenes --input-file task-input.json --json

列出、检查和等待

tilebox job list --last 7d --limit 100 --json
tilebox job list --state failed --after 2026-05-01 --before 2026-06-01 --json
tilebox job list --name landsat --task-state failed,failed_optional --json
tilebox job get <job-id> --json
tilebox job wait <job-id> --stalled-timeout 5m --json

对于分页列表输出，请保持筛选条件和排序不变，并将 next_cursor 传给 --cursor，直到其为空。

在 job get 中，先检查 state、execution_stats、task_summaries 和 progress。

日志、跨度、重试和取消

tilebox job logs <job-id> --sort desc --limit 100 --json
tilebox job logs <job-id> --include-runner-attributes --json
tilebox job spans <job-id> --sort asc --limit 100 --json
tilebox job spans <job-id> --include-runner-attributes --json
tilebox job retry <job-id> --json
tilebox job cancel <job-id> --json

使用日志查看应用程序消息和错误。使用跨度查看耗时、顺序、父子关系和属性。只有在根本问题已修复后才重试。如果不应继续执行工作，请取消；已排队的任务不会被领取，而已在运行的任务可能会完成。

调试流程

  1. 使用 tilebox job get <job-id> --json 检查状态和任务数量。
  2. 如果失败，请检查失败任务的摘要和近期日志。
  3. 如果需要关注耗时、顺序或运行器／运行时属性，请使用 spans。
  4. 只有在修复代码、数据、凭据或基础设施后，才重试。
  5. 如果应停止任务而不是重试，请取消任务。

评论

支持 Markdown