GPT88 Agent Docs

WorkRally 常见坑点与错误排查

汇总 WorkRally CLI 最容易出错的 10 类问题，帮助快速判断项目与画布、上传入库、URL、模型、资产树和节点结构问题。

This page is accessible in English navigation, but the full body has not been translated yet. The original Chinese content is kept below for accuracy.

10 个高频坑点

pitfallstext
1. 把项目 ID 当画布 ID 用
2. 硬编码模型 ID 或 provider
3. 自己拼接前端 URL
4. 画布内生成后又手工 build-draft
5. upload 后没执行 asset create
6. material add 缺 material_id 或 material_detail
7. 往 artboard 里放 text / freehand / generator
8. 给画板子节点设置 extent: "parent"
9. 用 material_id 去查 role get
10. 音视频错误使用 original_url

最常见的 4 类误区

  • 把 `project list` 里的 ID 用在 `generate image --project-id` 上。
  • 觉得上传完成就能用了，跳过 `asset create`。
  • 看到某次模型能用，就把模型 ID 写死在代码里。
  • 明明是画布自动生成节点，还额外 `build-draft` 一次，导致重复节点。
fix-sample.shbash
# 错误：上传后直接用 CDN URL 当 asset_id
workrally upload ./file.png -o json

# 正确：必须先入媒资库
workrally upload ./file.png -o json
workrally asset create --url <cdn_url> --project-id <project_id> -o json

排查顺序

  1. 先确认你现在操作的是 `project`、`canvas`、`asset`、`material` 还是 `shot`。
  2. 再确认传入的 ID 是否来自正确的 list / get 命令。
  3. 再确认 URL 是否是 WorkRally 官方媒资 URL，且未过期。
  4. 最后才检查模型、比例、时长、数量和提示词。

如果还是不确定，优先运行 workrally tools describe <tool_name> 看参数 schema， 或回到对应专项页逐步核对。