{"id":"5394da85-f94d-426b-9a2a-49f1a976ebf9","entityType":"agent","slug":"clawhub-tencent-adm-workrally","name":"WorkRally","canonicalUrl":"https://www.xpersona.co/agent/clawhub-tencent-adm-workrally","canonicalPath":"/agent/clawhub-tencent-adm-workrally","generatedAt":"2026-10-10T05:39:39.007Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T21:38:55.672Z","emptyReason":null},"description":"WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with WorkRally platform via command line. Skill: WorkRally Owner: tencent-adm Summary: WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s171cxjdnjyqjxa91pj2bfmr6x83gyg1:workrally","sourceUrl":"https://clawhub.ai/tencent-adm/workrally","homepage":"https://clawhub.ai/tencent-adm/skills/workrally","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/tencent-adm/workrally","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/tencent-adm/skills/workrally","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":66,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use whe"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:38:55.672Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:38:55.672Z","emptyReason":null},"stars":null,"forks":null,"downloads":1970,"packageName":null,"latestVersion":"2.10.1","tractionLabel":"2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:38:55.672Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T21:38:55.672Z","lastCrawledAt":"2026-10-09T21:38:55.672Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T21:38:55.672Z","lastVerifiedAt":null,"highlights":[{"version":"2.10.1","createdAt":"2026-09-29T15:04:46.488Z","changelog":"- 不带 `--token` 时：PKCE + `127.0.0.1` 回调，保存 access / refresh token；access token 临近过期自动续期 - `--token` 与 `WORKRALLY_API_KEY` 仍是 API Key，环境变量优先于配置文件里的 OAuth 登录态 - 无终端环境不打开浏览器，提示改用 API Key - access token 仍为服务端的 4 小时，refresh token 30 天并轮转 - 回调页在响应写完前不关端口，避免浏览器把 `127.0.0.1/callback` 显示成无法访问","fileCount":10,"zipByteSize":33094},{"version":"2.9.0","createdAt":"2026-09-09T20:33:21.269Z","changelog":"- MCP：场次补参考音频/延长视频/quality/MJ/passthrough；`tools/call` 仅允许核心白名单；`/mcp/full` 与 core 一致 - CLI：删除 `workrally tools call`；`shotlist list/get` 改走 `shotlist_manage`；`project delete` 为正式子命令 - Skill：去掉透传调用；关键帧/配音/动效请用 Web - 版本统一 **2.9.0**","fileCount":10,"zipByteSize":33342},{"version":"2.8.0","createdAt":"2026-09-01T15:35:41.866Z","changelog":"- MCP：新增音频/音乐、混元 3D 模型（非世界/贴图）；视频补 SmartEdit、ExtendVideo、Wan 3.0 文档参考；场次补 SmartEdit/视频超分，核心工具 35 → 39 - CLI：新增 `generate audio|music|3d`（`--asset-id`）、对应音频模型列表及 `shotlist upscale-video` - 兼容：MiniMax 动态字段/双桶 passthrough、queued 占位节点、媒资筛选对齐 Web 可见字段、material delete - Skill：补齐音频/音乐/混元3D/SmartEdit/ExtendVideo/视频超分流程 - 版本统一 **2.8.0**","fileCount":10,"zipByteSize":32589},{"version":"2.7.0","createdAt":"2026-08-19T11:02:50.383Z","changelog":"- MCP：移除 7 个旧 `shot_*` 工具与实现/单测；核心工具 42 → 35 - CLI：移除 `workrally shot` 命令、映射、`shot-e2e.sh`；帮助示例改用 `shotlist` - Skill：删除 `shot-guide.md` 与 legacy 引导；场次统一走 `shotlist-guide.md` - 配置/生成统一为 `extra.gen_config` + 任务通道 + 音频（对齐 `anime-new-shot`）","fileCount":10,"zipByteSize":30823},{"version":"2.6.2","createdAt":"2026-08-17T16:22:20.435Z","changelog":"- `canvas_optimize_prompt` / `generate optimize-prompt` 新增 `first_frame_url` / `last_frame_url` / `reference_image_urls` - 写入 `contents[].image_info.type`：`first_frame` / `last_frame` / `reference_image`（不是 R2V 顶层 `ref_images` / `frames`） - `--image-url` 保留为单张参考图兼容入参 - contents 顺序：文本 → 视频 → 首帧 → 尾帧 → 参考图 - Skill / MCP / CLI 版本统一升至 **2.6.2**","fileCount":11,"zipByteSize":39182},{"version":"2.6.1","createdAt":"2026-08-13T15:48:46.971Z","changelog":"- 新增 `workrally shotlist`（含生音频）与 `references/shotlist-guide.md`；旧 `workrally shot` 仅作兼容，同一剧集不要混用 - 新增 `workrally generate content-models` / `optimize-prompt`：视频提示词优化，`--poll` 成功后读 `output_text` - 生图支持 `--quality`、`--extra-params`；生视频默认开音效，关闭用 `--no-enable-sound`（`VideoEdit` 不要传） - 生图 `--resolution` 推荐 protobuf 枚举（`image-models` 的 `resolution_options[]`，常见 4/5/6），旧档位 0/1/2 仍兼容 - 版本号由 2.4.1 升级到 2.6.1","fileCount":11,"zipByteSize":38793},{"version":"2.4.1","createdAt":"2026-06-24T09:29:32.359Z","changelog":"- AI 生视频驱动模式由 4 种精简为 3 种，移除 FrameSequence（序列帧）模式 - AI 生视频新增 --aspect-ratio 和 --resolution 通用选项，支持指定宽高比与分辨率 - video-models 返回新增 resolution_options[] 字段，展示模型可用分辨率列表 - 版本号由 2.4.0 升级到 2.4.1","fileCount":10,"zipByteSize":31236},{"version":"2.4.0","createdAt":"2026-05-15T09:56:50.536Z","changelog":"- 新增顶级命令 `workrally series`（5 个子命令）和 `workrally shot`（14 个子命令），完整覆盖剧集/场次的 CRUD、模型配置、AI 生图/生视频、角色识别、资产绑定与结果查询 - 新增深度参考文档 `references/shot-guide.md`，覆盖场次全生命周期工作流与易错点 - 版本号由 2.3.1 升级到 2.4.0","fileCount":10,"zipByteSize":31017}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171cxjdnjyqjxa91pj2bfmr6x83gyg1:workrally","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T05:39:39.004Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tencent-adm-workrally/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T21:38:55.672Z","emptyReason":null},"readme":"Skill: WorkRally\n\nOwner: tencent-adm\n\nSummary: WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with WorkRally platform via command line.\n\nTags: latest:2.10.1\n\nVersion history:\n\nv2.10.1 | 2026-09-29T15:04:46.488Z | user\n\n- 不带 `--token` 时：PKCE + `127.0.0.1` 回调，保存 access / refresh token；access token 临近过期自动续期\n- `--token` 与 `WORKRALLY_API_KEY` 仍是 API Key，环境变量优先于配置文件里的 OAuth 登录态\n- 无终端环境不打开浏览器，提示改用 API Key\n- access token 仍为服务端的 4 小时，refresh token 30 天并轮转\n- 回调页在响应写完前不关端口，避免浏览器把 `127.0.0.1/callback` 显示成无法访问\n\nv2.9.0 | 2026-09-09T20:33:21.269Z | user\n\n- MCP：场次补参考音频/延长视频/quality/MJ/passthrough；`tools/call` 仅允许核心白名单；`/mcp/full` 与 core 一致\n- CLI：删除 `workrally tools call`；`shotlist list/get` 改走 `shotlist_manage`；`project delete` 为正式子命令\n- Skill：去掉透传调用；关键帧/配音/动效请用 Web\n- 版本统一 **2.9.0**\n\nv2.8.0 | 2026-09-01T15:35:41.866Z | user\n\n- MCP：新增音频/音乐、混元 3D 模型（非世界/贴图）；视频补 SmartEdit、ExtendVideo、Wan 3.0 文档参考；场次补 SmartEdit/视频超分，核心工具 35 → 39\n- CLI：新增 `generate audio|music|3d`（`--asset-id`）、对应音频模型列表及 `shotlist upscale-video`\n- 兼容：MiniMax 动态字段/双桶 passthrough、queued 占位节点、媒资筛选对齐 Web 可见字段、material delete\n- Skill：补齐音频/音乐/混元3D/SmartEdit/ExtendVideo/视频超分流程\n- 版本统一 **2.8.0**\n\nv2.7.0 | 2026-08-19T11:02:50.383Z | user\n\n- MCP：移除 7 个旧 `shot_*` 工具与实现/单测；核心工具 42 → 35\n- CLI：移除 `workrally shot` 命令、映射、`shot-e2e.sh`；帮助示例改用 `shotlist`\n- Skill：删除 `shot-guide.md` 与 legacy 引导；场次统一走 `shotlist-guide.md`\n- 配置/生成统一为 `extra.gen_config` + 任务通道 + 音频（对齐 `anime-new-shot`）\n\nv2.6.2 | 2026-08-17T16:22:20.435Z | user\n\n- `canvas_optimize_prompt` / `generate optimize-prompt` 新增 `first_frame_url` / `last_frame_url` / `reference_image_urls`\n- 写入 `contents[].image_info.type`：`first_frame` / `last_frame` / `reference_image`（不是 R2V 顶层 `ref_images` / `frames`）\n- `--image-url` 保留为单张参考图兼容入参\n- contents 顺序：文本 → 视频 → 首帧 → 尾帧 → 参考图\n- Skill / MCP / CLI 版本统一升至 **2.6.2**\n\nv2.6.1 | 2026-08-13T15:48:46.971Z | user\n\n- 新增 `workrally shotlist`（含生音频）与 `references/shotlist-guide.md`；旧 `workrally shot` 仅作兼容，同一剧集不要混用\n- 新增 `workrally generate content-models` / `optimize-prompt`：视频提示词优化，`--poll` 成功后读 `output_text`\n- 生图支持 `--quality`、`--extra-params`；生视频默认开音效，关闭用 `--no-enable-sound`（`VideoEdit` 不要传）\n- 生图 `--resolution` 推荐 protobuf 枚举（`image-models` 的 `resolution_options[]`，常见 4/5/6），旧档位 0/1/2 仍兼容\n- 版本号由 2.4.1 升级到 2.6.1\n\nv2.4.1 | 2026-06-24T09:29:32.359Z | user\n\n- AI 生视频驱动模式由 4 种精简为 3 种，移除 FrameSequence（序列帧）模式\n- AI 生视频新增 --aspect-ratio 和 --resolution 通用选项，支持指定宽高比与分辨率\n- video-models 返回新增 resolution_options[] 字段，展示模型可用分辨率列表\n- 版本号由 2.4.0 升级到 2.4.1\n\nv2.4.0 | 2026-05-15T09:56:50.536Z | user\n\n- 新增顶级命令 `workrally series`（5 个子命令）和 `workrally shot`（14 个子命令），完整覆盖剧集/场次的 CRUD、模型配置、AI 生图/生视频、角色识别、资产绑定与结果查询\n- 新增深度参考文档 `references/shot-guide.md`，覆盖场次全生命周期工作流与易错点\n- 版本号由 2.3.1 升级到 2.4.0\n\nv2.3.1 | 2026-04-24T14:06:26.748Z | user\n\n- AI 生图支持 4K 分辨率\n- 版本号由 2.3.0 升级到 2.3.1\n\nv2.3.0 | 2026-04-21T13:54:06.451Z | user\n\n- 媒资 URL 短链化：`asset search` / `asset get` / `asset create` 等工具返回的 `url`、`download_url` 替换为短链形式，相较原始带签名地址最高可压缩 100 倍以上，显著节省 Agent 上下文\n- 短链对 Agent 透明：可直接作为任意 URL 类参数传入生图/生视频/入库等工具，由服务端自动还原为原始地址，无需手动处理\n- 短链访问失败体验优化：失效或格式非法的短链返回专属 404 页面（原地显示，URL 不跳转），命中时仍正常重定向到原始素材\n- 命令帮助抽象化：SKILL 规则 9、各指南文档不再硬编码具体域名/URL 格式，平台侧调整对 Agent 使用完全透明\n- 生图/生视频任务并发语义同步：`--count 1-4` 命令帮助文案明确\"后端一个任务生成 1 张/个，count>1 会并发发起 N 个任务\"\n- `workrally download` 对重定向响应更健壮：兼容相对路径 302，失效 URL 返回清晰的 HTTP 状态提示，不再静默保存错误响应\n- 版本号由 2.2.0 升级到 2.3.0\n\nv2.2.0 | 2026-04-20T03:15:08.213Z | user\n\n- 新增 URL 白名单规则（规则 9）：所有 URL 类参数仅接受 zenvideo-pro.gtimg.com 域名，本地/第三方 URL 必须先 upload\n- 版本号由 2.1.0 升级到 2.2.0\n\nv2.1.0 | 2026-04-15T11:12:55.047Z | user\n\n- 品牌重命名 ZenStudio → WorkRally，CLI 命令由 zencli 改为 workrally\n- 环境变量全面更新：ZENSTUDIO_* → WORKRALLY_*，旧变量保持兼容\n- 新增 4 份深度指南：画布操作、上传资产、AI 生成、常见错误\n- 修复 material add 文档与 CLI 实际接口不匹配\n- 新增预发布品牌泄漏检测（源码 + 构建产物双层扫描）\n- 版本号由 1.3.6 升级到 2.1.0\n\nArchive index:\n\nArchive v2.10.1: 10 files, 33094 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1616b), references/ai-generation-guide.md (16509b), references/canvas-guide.md (10826b), references/common-pitfalls.md (8590b), references/shotlist-guide.md (11094b), references/upload-and-assets-guide.md (7895b), skill-card.md (2115b), SKILL.md (19242b), _meta.json (129b)\n\nFile v2.10.1:SKILL.md\n\n---\nname: workrally\nslug: workrally\ndisplayName: WorkRally\ndisplay_name: WorkRally\ndisplay_name_en: WorkRally\ndescription: WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with WorkRally platform via command line.\ndescription_zh: 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集，支持 AI 生图/生视频/生音频、项目剧集场次管理、资产库与无限画布。\ndescription_en: End-to-end AIGC comic-drama creation toolkit for AI Agents—image/video/audio generation, project/series/shot management, asset library, and infinite canvas.\ntags: [AIGC, CLI, 漫剧, 生图, 生视频, 生音频, 项目, 剧集, 场次, 画布, 资产库]\nversion: 2.10.1\nlicense: MIT-0\nauthor: WorkRally Team\nhomepage: https://workrally.qq.com\nuser-invocable: true\nmetadata: {\"openclaw\":{\"emoji\":\"🎬\",\"requires\":{\"bins\":[\"workrally\"],\"env\":[\"WORKRALLY_API_KEY\",\"WORKRALLY_ENDPOINT\",\"WORKRALLY_CONFIG_DIR\",\"WORKRALLY_NO_UPDATE_CHECK\"]},\"primaryEnv\":\"WORKRALLY_API_KEY\",\"credentials\":{\"storage\":\"~/.workrally/config.json\",\"configDirEnv\":\"WORKRALLY_CONFIG_DIR\",\"description\":\"workrally auth login 写入的登录态：API Key，或 OAuth access/refresh token，以及 endpoint。非持久化容器中可通过 WORKRALLY_CONFIG_DIR 环境变量指定配置目录\"},\"install\":[{\"id\":\"npm\",\"kind\":\"node\",\"package\":\"workrally\",\"bins\":[\"workrally\"],\"label\":\"Install WorkRally CLI (npm)\"}],\"category\":\"AIGC\",\"tags\":[\"workrally\",\"aigc\",\"cli\",\"video-generation\",\"image-generation\",\"ai-tools\",\"story\",\"shot\",\"series\"]}}\n---\n\n# WorkRally CLI (workrally)\n\n面向 AI Agent 的 AIGC 漫剧视频创作全流程命令行工具，封装 WorkRally 平台 30+ 核心能力，支持项目/剧集/场次的完整 CRUD、AI 生图/生视频、画布、资产库、媒资管理、文件上传等。\n\n## 安装 & 配置\n\n```bash\nnpm install -g workrally\n\n# 配置登录。Agent / CI 只用 API Key，不要自己实现 OAuth，也不要请求 127.0.0.1 回调。\nworkrally auth login --token # Agent / CI\nexport WORKRALLY_API_KEY= # 环境变量优先于配置文件\nworkrally auth login # 仅人在本机终端使用，CLI 自己打开浏览器\n# ↑ auth login 自动将 Token 写入配置文件：\n# 若 WORKRALLY_CONFIG_DIR 已设置 → $WORKRALLY_CONFIG_DIR/config.json\n# 否则 → ~/.workrally/config.json\n\nworkrally auth status # 验证登录状态\n```\n\nAPI Key 申请：[龙虾配置](https://workrally.qq.com/open-api)\n\n## 命令速查\n\n```bash\n# === 项目（project）— list / get / create / update / delete ===\nworkrally project list [--search \"关键词\"] # 列出/搜索项目\nworkrally project get # 项目详情\nworkrally project create \"项目名\" # 创建项目\nworkrally project update --name \"新名称\" # 更新项目\nworkrally project delete # 软删除（→回收站；恢复请到 Web）\n\n# === 剧集（series）— 全新命令组（CRUD 完整） ===\nworkrally series list --project-id # 剧集列表\nworkrally series get --project-id # 剧集详情\nworkrally series create --project-id --name \"第一集\" # 创建剧集\nworkrally series update --project-id --name \"新名称\" # 更新剧集\nworkrally series delete # 软删除（→回收站）\n\n# === 场次（shotlist）— 对齐 Web /shot 批量制作（含音频生成）===\n# --- CRUD ---\nworkrally shotlist list --series-id # 场次列表\nworkrally shotlist get # 场次详情\nworkrally shotlist create --series-id --json-list '[{\"image_prompt\":\"...\"}]' # 批量创建\nworkrally shotlist update --image-prompt \"...\" --animation-prompt \"...\" # 单条更新\nworkrally shotlist update --batch '[{\"story_id\":\"...\",\"image_prompt\":\"...\"}]' # 批量更新\nworkrally shotlist delete # 软删除（→回收站）\nworkrally shotlist sort --series-id --order id1,id2,id3 # 重排\n# --- 模型 & 配置（写入 extra.gen_config）---\nworkrally shotlist models --category image,video,videoSmartEdit,upscale,audio # ⭐ 统一模型列表\nworkrally shotlist set-model [--story-ids id1,id2] --image-model --image-aspect-ratio 16:9 [--image-quality high] [--mj-params '{}']\nworkrally shotlist set-model [--story-ids id1,id2] --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9\nworkrally shotlist set-model [--story-ids id1,id2] --extra-mode extendVideo --extend-source-id --duration 4 # 延长视频\nworkrally shotlist set-model [--story-ids id1,id2] --audio-model [--audio-config '{}'] # 配置音频\nworkrally shotlist bind --story-id --type audio --file ./voice.wav --project-id # 本地素材：上传→入库→绑定\nworkrally shotlist bind --story-id --type image --assets '[{...}]' # 已入库素材绑定（audio→独立字段）\nworkrally shotlist recognize --series-id --project-id [--scope both] [--match-rule symbol_text] # 识别（含音频路）\n# --- 生成（仅提交；查结果用 get-result [--watch]）---\nworkrally shotlist generate-image --project-id --story-ids id1,id2 [--count N] # 生图 → get-result --type image\nworkrally shotlist generate-video --project-id --story-ids id1,id2 # 生视频 → get-result --type video\nworkrally shotlist upscale-video --project-id --story-ids id1,id2 --model # 已选视频超分\nworkrally shotlist generate-audio --project-id --story-ids id1,id2 [--count N] # ⭐ 生音频 → get-result --type audio\nworkrally shotlist get-result --story-id --type image|video|audio [--watch] # 查进度与产物\n\n# === 上传 / 下载 ===\nworkrally upload ./file.png -o json # 上传文件 (COS SDK 直传)\nworkrally download [-d ./output/] # 下载素材 (自动处理访问凭证)\n\n# === AI 生图 ===\nworkrally generate image-models # 查看可用模型（必须先调用！）\nworkrally generate image --prompt \"描述\" --model [--aspect-ratio 16:9] [--resolution 5] [--quality high] [--input-images \"url\"] --poll\n# --resolution 推荐用 image-models 的 resolution_options[].value（常见 4=1080P/5=1440P/6=2160P）；旧档位 0/1/2 仍可用\n# --quality 仅当 image-models 该模型返回了 infer_quality_options 时才传（取值用其中的 value）\n# --extra-params '{\"midjourney\":{\"stylize\":100}}' 扩展参数 JSON 对象；CLI 传 extraParams，服务端写成 extra_params\n\n# === AI 生视频 (6 种驱动模式) ===\nworkrally generate video-models # 查看可用模型（必须先调用！）\nworkrally generate video --prompt \"描述\" --model --poll # 纯文生视频（默认 Text 模式）\nworkrally generate video --prompt \"描述\" --model --single-image-url \"url\" --poll # 图生视频（Text 模式 + 参考图）\nworkrally generate video --mode FirstLastFrame --prompt \"描述\" --model --first-frame-url \"url\" --poll # 首尾帧\nworkrally generate video --mode VideoEdit --prompt \"描述\" --model --origin-video --poll # 视频编辑\n# 其他模式: SubjectToVideo(--reference-assets)\nworkrally generate video --mode SmartEdit --model --source-video --source-width 1920 --source-height 1080 --source-duration 5000 --poll\nworkrally generate video --mode ExtendVideo --model --source-video --duration 8 --poll\n# SubjectToVideo 的 --reference-assets 支持 file 文档（Wan 3.0）：{\"type\":\"file\",\"asset_id\":\"...\",\"name\":\"brief.pdf\"}\n# --mode 默认 Text；通用选项: --aspect-ratio <比例> --resolution <枚举> --duration <秒> --count 1-4 --poll\n# 音效默认开启（与前端一致）；关闭用 --no-enable-sound。VideoEdit 不要传音效相关参数\n# --aspect-ratio 默认 16:9；--resolution 不传取模型首个可用(枚举见 video-models 的 resolution_options)\n\n# === 画布生音频 / 音乐（对齐 Web 画布音频生成器）===\nworkrally generate audio-models # 查看 audio_models / music_models（必须先调用！）\nworkrally generate audio --prompt \"雨声和脚步\" --model --poll\nworkrally generate music --prompt \"摇滚吉他\" --model --lyrics-mode none --poll\nworkrally generate music --prompt \"流行\" --model --lyrics-mode input --lyrics \"啦啦啦\" --poll\n# MiniMax 音频模型不要传 --ref-audios；动态音色参数从模型 fields 获取后用 --audio-fields JSON 传入\n\n# === 混元 3D 模型（对齐 Web 关键帧混元3D，不是世界生成/贴图）===\nworkrally generate 3d --asset-id <参考图asset_id> --poll\n# 须先 asset search / asset create 得到 asset_id；模型固定 hunyuan-3d-v3.0\n# ⚠️ --project-id 是短番项目ID，不是画布ID\n\n# === 视频提示词优化（gen_content，产物是文本不是视频）===\nworkrally generate content-models # 查看可用模型（必须先调用！严禁硬编码 MiniMax H3 等 ID）\nworkrally generate optimize-prompt --prompt \"将视频从尾帧延长5秒\" --model \\\n [--video-url ] [--first-frame-url ] [--last-frame-url ] \\\n [--reference-image-urls \"url1,url2\"] [--audio-url ] [--audio-urls \"a.mp3,b.mp3\"] --poll\n# 图片语义写在 image_info.type：first_frame / last_frame / reference_image；音频写在 audio_info.url（type=3）\n# 成功后从 generate task 的 output_text 读取优化后的提示词（output_type=\"text\"），不要找 output_assets\n\n# === 媒资库 (asset) — 项目级媒体文件池 ===\nworkrally asset create --url --project-id -o json # 入库（返回可访问 URL）\nworkrally asset search --project-id [--type image] [--audit-status 5] [--auth-status 1]\nworkrally asset get # 详情\nworkrally asset update --name \"新名称\" # 更新素材 (目前仅支持改名)\n\n# === 资产库 (material) — 树形管理：人物/道具/场景/网盘 ===\nworkrally material list role_person # 人物 | role_prop 道具 | role_scene 场景 | root 网盘文件夹\nworkrally material add ... # 创建素材/文件夹（从媒资库挂载）\nworkrally material get # 素材详情\nworkrally material delete # 删除（不可恢复，须用户确认）\nworkrally role get # 角色详情（LoRA/提示词/版本）\n\n# === 画布 ===\nworkrally canvas list # 列出画布\nworkrally canvas create \"名称\" # 创建画布\nworkrally canvas build-draft --file nodes.json # 增量合并（默认保留已有节点）\nworkrally canvas build-draft --nodes '[...]' # 同上，直接传 JSON\nworkrally canvas build-draft -d \"id1,id2\" # 删除指定节点\nworkrally canvas build-draft -n '[...]' -d \"old1\" # 同时增删改\nworkrally canvas build-draft -n '[...]' --mode overwrite # 全量覆盖（清空后重建）\n\n# === 任务查询 ===\nworkrally generate task [--poll] # 查询/轮询生成任务状态\n# 生图/生视频成功：output_type=\"assets\"，产物在 output_assets\n# 提示词优化成功：output_type=\"text\"，产物在 output_text（不要找 output_assets / output_products）\n\n# === 通用（仅查看白名单，禁止透传调用）===\nworkrally tools list # 列出核心白名单工具\nworkrally tools describe # 查看参数 schema\n# 不要使用 tools call；未列出的 MCP 工具已禁止调用。关键帧/配音/动效请用 Web。\n\n# === URL / 升级 ===\nworkrally url build \"页面名\" [--params '{}'] # 构建 WorkRally 前端链接\nworkrally url parse # 解析 URL\nworkrally upgrade [--check] # 升级 / 仅检查\n```\n\n输出格式: `-o json`(默认, Agent 推荐) | `-o table`(人类阅读) | `-o text`(管道/脚本) | `workrally config set output_format `\n\n## 关键工作流：上传文件\n\n**概念**：媒资库(asset) = 项目级文件池；资产库(material) = 树形目录(人物/道具/场景/网盘文件夹)。资产库的素材只能从媒资库挂载。\n\n```bash\n# 步骤 1: 上传 → CDN URL\nworkrally upload ./character.png -o json\n# 步骤 2: 入媒资库（必须！返回 asset_id + asset_details）\nworkrally asset create --url --project-id -o json\n# 步骤 3（按需）: 挂载到资产库（必传 asset_id + 完整 asset_details）\nworkrally material add --json-list '[{\"material_id\":\"\",\"material_name\":\"名称\",\"material_type\":2,\"parent_id\":\"\",\"material_detail\":}]' \\\n --project-ids \n```\n\n> **步骤 1→2 强制绑定**，上传后必须入媒资库。视频/音频为私有读，需经媒资库才能正常访问。\n>\n> **步骤 3 由 Agent 判断**：\"上传文件\" → 两步 | \"上传到角色/道具/场景/文件夹\" → 三步 | \"媒资素材添加到资产库\" → 仅步骤 3\n\n## 关键工作流：场次创作（`shotlist`，对齐 Web /shot）\n\n**概念层级**：项目 (project) → 剧集 (series) → 场次 (shot/story)。一个场次含 图片 / 视频 / **音频** 三条生成线，核心由提示词承载：`image_prompt`（图片）、`animation_prompt`（视频）、`extra.audio_prompt`（音频，音色用 `<音色名>` 引用）。生成配置聚合在 `extra.gen_config.{image,video,audio}`。\n\n```bash\n# 1) 建剧集 + 批量创建场次（按用户意图填提示词）\nworkrally series create --project-id --name \"第一集\" -o json\nworkrally shotlist create --series-id --json-list '[{\"image_prompt\":\"古风庭院\",\"animation_prompt\":\"镜头缓推\"}]'\n\n# 2) 识别角色资产（三路：image/animation/audio；音色用 <> 时加 --match-rule symbol_text）\nworkrally shotlist recognize --series-id --project-id \n\n# 3) 选模型 → 写配置（模型 id 来自 shotlist models，勿硬编码）\nworkrally shotlist models --category image,video,audio -o json\nworkrally shotlist set-model --series-id --image-model --image-aspect-ratio 16:9 \\\n --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9 --audio-model \n\n# 4) 生成（多场次传 --story-ids id1,id2,id3；均需 --project-id）\nworkrally shotlist generate-image --project-id --story-ids \nworkrally shotlist generate-video --project-id --story-ids \nworkrally shotlist generate-audio --project-id --story-ids \n\n# 5) 查结果（image/video/audio 三条独立进度，分别 watch）\nworkrally shotlist get-result --story-id --type image --watch\nworkrally shotlist get-result --story-id --type video --watch\nworkrally shotlist get-result --story-id --type audio --watch\n```\n\n> **生成前先确认配置**：用 `shotlist get ` 检查 `extra.gen_config` 是否已设对应模型；缺则回到步骤 3。生成只返回提交结果，不返回可轮询的画布 task_id，进度一律用 `shotlist get-result`。\n\n## ⚠️ 重要规则\n\n1. **前端链接必须用 `workrally url build` 生成**，严禁自行拼接 URL\n2. **模型 ID 必须动态获取**：`image-models` / `video-models` / `audio-models` / `content-models`，严禁猜测或硬编码。场次批量制作使用 `shotlist models`；音频模型返回的 `capabilities/fields/restrictions` 也应一并用于配置。混元 3D 固定 hunyuan-3d-v3.0，只需 `--asset-id`\n3. **`canvas` ≠ `project`**：画布用 `canvas`，项目用 `project`，两者 ID 不能互换\n4. **`build-draft` 实时协同**：写入后所有在线用户立即看到变更，默认增量合并（只传变更节点），支持多人并发安全操作\n5. **`build-draft` 节点校验**：8种节点类型各有必填字段，详见 [`canvas-guide.md`](references/canvas-guide.md)\n6. **AI 生成自动占位**：`generate image/video` 传入 `--project-id`（画布ID）后自动在画布创建占位节点，**无需**再手动 `build-draft`\n7. **素材命名**：`--name` 传入\"画布名_素材特征\"（画布场景）或 prompt 关键词（非画布场景）\n8. **不确定参数时**用 `--help` 或 `tools describe` 自行探索\n9. **URL 白名单**：所有 URL 类参数（生图/生视频的 `--*-url` / `--*-assets` / `--*-images`、`asset create --url` 等）仅接受 WorkRally 官方媒资 URL。合法来源：① `workrally upload` 返回值 ② `asset get/search` 返回值（可直接传入） ③ 用户已提供的官方 URL。本地文件或第三方 URL 必须先 `workrally upload`。如遇\"非法或已过期\"提示，通过 `asset get/search` 重新获取即可。\n\n## 📚 深度指南 (references/)\n\n本 Skill 附带详细参考文档，覆盖复杂工作流：\n\n| 文档 | 内容 |\n|------|------|\n| [`references/shotlist-guide.md`](references/shotlist-guide.md) | ⭐ **场次批量制作**（对齐 Web `/shot`）— CRUD、gen_config、生图/生视频/**生音频**、结果查询、符号识别 |\n| [`references/canvas-guide.md`](references/canvas-guide.md) | 无限画布操作 — 8种节点类型、画板嵌套、build-draft 增量/覆盖模式、协同编辑 |\n| [`references/upload-and-assets-guide.md`](references/upload-and-assets-guide.md) | 上传与素材管理 — 三步上传流程、媒资库 vs 资产库、树形目录操作 |\n| [`references/ai-generation-guide.md`](references/ai-generation-guide.md) | AI 生成 — Kontext 生图、4种视频驱动模式、画布音频/音乐、混元 3D 模型、提示词优化、模型动态获取、任务轮询 |\n| [`references/common-pitfalls.md`](references/common-pitfalls.md) | 常见易错点 — 项目/画布混淆、模型硬编码、上传缺步骤等典型错误 |\n\n> 遇到画布、上传、AI生成相关的复杂操作时，请优先查阅对应的参考文档。\n\n## 环境变量\n\n- `WORKRALLY_API_KEY` — API Key (Bearer Token)。设置后优先于 `auth login` 保存的 OAuth 登录态\n- `WORKRALLY_ENDPOINT` — API 端点 (默认 `https://workrally.qq.com/zenstudio/api/mcp`)\n- `WORKRALLY_CONFIG_DIR` — 配置文件目录 (默认 `~/.workrally`，非持久化容器建议指向持久卷)\n- `WORKRALLY_NO_UPDATE_CHECK=1` — 禁用自动版本检查 (CI/CD 推荐)\n\nFile v2.10.1:README.md\n\n# WorkRally CLI — Agent Skill\n\n🎬 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。\n\n本目录是 WorkRally CLI 的 Agent Skill 定义。\n\n## 目录结构\n\n```\nskill/\n├── SKILL.md ← Skill 入口（元数据 + 指令），ClawHub 解析此文件\n├── LICENSE.txt ← 许可证\n└── references/ ← 深度参考文档，AI Agent 按需加载\n ├── ai-generation-guide.md AI 生成指南\n ├── canvas-guide.md 无限画布操作指南\n ├── common-pitfalls.md 常见易错点\n ├── shotlist-guide.md 场次批量制作（对齐 Web /shot）\n └── upload-and-assets-guide.md 上传与素材管理指南\n```\n\n## 核心能力\n\n- **AI 生图** — Kontext 模型，支持多参考图、可选推理质量\n- **AI 生视频** — 4 种驱动模式（文本/首尾帧/参考主体/视频编辑）\n- **提示词优化** — gen_content 文本任务，产物为 `output_text`\n- **无限画布** — Yjs 协同编辑，8 种节点类型，实时同步\n- **项目 & 媒资管理** — 项目 CRUD、素材上传入库、资产库树形管理\n- **通用透传** — 可调用 WorkRally MCP Server 全部工具\n\n## 第三方商店\n\n- [SkillHub](https://skillhub.cn/skills/workrally)\n- [ClawHub](https://clawhub.ai/tencent-adm/workrally)\n- [Skills](https://skills.sh/tencent/workrally/workrally)\n\n## 快速开始\n\n```bash\nnpm install -g workrally\nworkrally auth login\nworkrally auth status\n```\n\n详细用法、命令速查、工作流指南请参阅 **[SKILL.md](./SKILL.md)**。\n\nFile v2.10.1:_meta.json\n\n{\n \"ownerId\": \"kn77cw5hbmapf54rv89jdqwp7x835m4k\",\n \"slug\": \"workrally\",\n \"version\": \"2.10.1\",\n \"publishedAt\": 1790694286488\n}\n\nFile v2.10.1:references/ai-generation-guide.md\n\n# AI 生成指南（图片 / 视频 / 音频 / 音乐 / 3D）\n\n本文档帮助 AI Agent 正确使用 WorkRally 的 AI 图片、视频、音频、音乐与混元 3D 模型生成能力。\n\n---\n\n## 1. 核心规则\n\n> ⚠️ **模型 ID 必须动态获取，严禁猜测或硬编码！**\n> 模型列表是动态下发的，不同环境（开发/预发/正式）的可用模型可能完全不同。\n\n> 🔒 所有 URL 类参数仅接受 WorkRally 官方媒资 URL，详见 SKILL.md 规则 9。\n\n```bash\n# 生图前必须先获取模型列表\nworkrally generate image-models -o json\n\n# 生视频前必须先获取模型配置\nworkrally generate video-models -o json\n\n# 提示词优化前必须先获取 gen_content 模型列表\nworkrally generate content-models -o json\n\n# 画布生音频/音乐前必须先获取模型\nworkrally generate audio-models -o json\n```\n\n---\n\n## 2. 图片生成 (Kontext)\n\n### 2.1 获取可用模型\n\n```bash\nworkrally generate image-models -o json\n```\n\n返回包含：\n- `models[]` — 每个模型的 `model_id`、`name`、`resolution_options`、`kontext_config`、`infer_quality_options`\n- `aspect_ratios[]` — 全局可用宽高比列表（如 \"1:1\", \"16:9\", \"9:16\" 等）\n- `resolution_options[]` — 所有模型支持的 protobuf 分辨率并集（**推荐**，传给 `--resolution`）\n- `resolutions[]` — 旧档位 0/1/2 并集（兼容）\n- `count_options[]` — 可选的生成数量\n\n**关键字段**：\n- `model_id` → 传给 `--model` 参数\n- `kontext_config.max_input_images` → 该模型允许的最大参考图数量（不同模型不同，不要写死）\n- `resolution_options[]` → `{value, label}`，value 为 protobuf 枚举（常见 4=1080P、5=1440P、6=2160P）。**`generate image --resolution` 用这里的 value**\n- `kontext_config.support_resolutions` → 旧档位 0=1K / 1=2K / 2=4K（兼容已有脚本，新调用不要再用）\n- `infer_quality_options[]` → 推理质量选项（可能为空）。非空时才可传 `--quality=`（如 `high`/`medium`/`low`）；空列表时不要传 `--quality`\n\n### 2.2 纯文生图\n\n```bash\nworkrally generate image \\\n --prompt \"一只橘猫坐在樱花树下\" \\\n --model \\\n --aspect-ratio 16:9 \\\n --poll\n```\n\n### 2.3 参考图生图\n\n通过 `--input-images` 传入参考主体图片 URL，在 prompt 中用 \"第一张图片\"、\"第二张图片\" 引用：\n\n```bash\nworkrally generate image \\\n --prompt \"第一张图片趴在第二张图片路中间\" \\\n --model \\\n --input-images \"https://cat.png,https://shrine.png\" \\\n --poll\n```\n\n> 📌 `--input-images` 的最大数量取决于模型配置中的 `kontext_config.max_input_images`，不要写死。\n> 📌 **只允许图片类型的素材**作为参考图。\n\n### 2.4 在画布中生图\n\n```bash\nworkrally generate image \\\n --prompt \"描述\" \\\n --model \\\n --project-id <画布ID> \\\n --poll\n```\n\n传入 `--project-id`（画布 ID）后：\n- 系统会**自动**在画布中创建 running 状态的占位节点（橙色边框 + 进度条）\n- **无需**再手动调用 `build-draft` 放置生成器节点\n- 生成完成后，前端自动更新节点状态\n\n> ⚠️ `--project-id` 此处是**画布 ID**（通过 `canvas list` 获取），**不是项目 ID**！\n\n### 2.5 参数说明\n\n| 参数 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--prompt` | ✅ | — | 图片描述 |\n| `--model` | ✅ | — | 模型 ID（从 `image-models` 获取） |\n| `--aspect-ratio` | — | `16:9` | 宽高比 |\n| `--resolution` | — | 模型首个可用 | **推荐** protobuf 枚举，取值来自 `image-models` 的 `resolution_options[].value`（常见 4=1080P、5=1440P、6=2160P）。兼容旧档位 0=1K、1=2K、2=4K。⚠️ 生图的 1/2 仍是 2K/4K，不是视频的 480P/540P |\n| `--quality` | — | 不下发 | 推理质量。取值必须来自该模型 `infer_quality_options[].value`；列表为空时不要传 |\n| `--count` | — | `1` | 生成数量 1-4（后端一个任务生成 1 张，count>1 会并发发起 N 个独立任务并返回 task_ids 数组） |\n| `--input-images` | — | — | 参考图 URL（逗号分隔） |\n| `--project-id` | — | — | 画布 ID（传入后自动创建占位节点） |\n| `--short-series-project-id` | — | — | 项目 ID |\n| `--name` | — | — | 素材名称 |\n| `--extra-params` | — | — | JSON 对象。CLI 传 MCP `extraParams`；服务端写入 `graph_input.extra_params` 且将每个 value 序列化为字符串。例如 MJ：`'{\"midjourney\":{\"stylize\":100}}'`。不要在 CLI 侧再 stringify 一层 |\n| `--poll` | — | false | 自动轮询直到完成 |\n| `--poll-interval` | — | `3` | 轮询间隔（秒） |\n\n---\n\n## 3. 视频生成\n\n### 3.1 获取可用模型配置\n\n```bash\nworkrally generate video-models -o json\n```\n\n返回按**驱动模式**分组：\n- `text_providers[]` — Text（单图/纯文）模式\n- `first_last_frame_providers[]` — 首尾帧模式\n- `subject_to_video_providers[]` — 参考主体模式\n- `video_edit_providers[]` — 视频编辑模式（VideoEdit）\n- `smart_edit_providers[]` — 智能编辑模式（SmartEdit）\n\n参考主体模型还可能返回 `extend_duration_range`、`extend_video_max_duration`、文档限制与 `support_erase_subtitles`；只在配置明确支持时使用。\n\n每个模型包含：\n- `provider` → 传给 `--model` 参数\n- `label` — 模型显示名称\n- `duration_options[]` — 可用时长列表（秒）\n- `resolution_options[]` — 支持的分辨率列表（`{value, label}`，value 为 protobuf 枚举值），传给 `--resolution`\n- `can_upload_image/video/audio` — 支持的输入类型\n- `max_image_count/video_count/audio_count` — 各类型最大数量\n- `support_audio` — 是否支持音效\n\n### 3.2 四种驱动模式\n\n#### Text 模式（默认）— 纯文生视频 / 单图驱动\n\n```bash\n# 纯文生视频（不传图片）\nworkrally generate video \\\n --prompt \"夕阳下海浪拍打沙滩\" \\\n --model \\\n --poll\n\n# 图生视频（传入参考图）\nworkrally generate video \\\n --prompt \"图片中的角色缓缓转身\" \\\n --model \\\n --single-image-url \"https://example.com/character.png\" \\\n --poll\n```\n\n#### FirstLastFrame 模式 — 首尾帧驱动\n\n```bash\nworkrally generate video \\\n --mode FirstLastFrame \\\n --prompt \"角色从左走到右\" \\\n --model \\\n --first-frame-url \"https://example.com/start.png\" \\\n --last-frame-url \"https://example.com/end.png\" \\\n --poll\n```\n\n> 可以只传首帧或只传尾帧（至少一个）。\n\n#### VideoEdit 模式 — 视频编辑\n\n`model` 必须来自 `video-models` 的 `video_edit_providers[]`。必须传 `--origin-video <原视频素材ID>`（asset_id，不是 URL）。此模式 **不要** 传 `--enable-sound` / `--no-enable-sound`（下游 graph_input 不带该字段）。\n\n```bash\nworkrally generate video \\\n --mode VideoEdit \\\n --prompt \"将背景替换成蓝天\" \\\n --model \\\n --origin-video \\\n --poll\n```\n\n#### SubjectToVideo 模式 — 参考主体驱动\n\n```bash\nworkrally generate video \\\n --mode SubjectToVideo \\\n --prompt \"角色在场景中行走\" \\\n --model \\\n --reference-assets '[{\"type\":\"image\",\"url\":\"https://character.png\"},{\"type\":\"video\",\"url\":\"https://bg.mp4\"}]' \\\n --poll\n```\n\n### 3.3 通用选项\n\n| 参数 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--prompt` | 通常必填 | — | SmartEdit/ExtendVideo 可省略 |\n| `--model` | ✅ | — | Provider ID（从 `video-models` 获取） |\n| `--mode` | — | `Text` | Text/FirstLastFrame/SubjectToVideo/VideoEdit/SmartEdit/ExtendVideo |\n| `--aspect-ratio` | — | `16:9` | 宽高比: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 等 |\n| `--resolution` | — | 模型首个可用 | 分辨率枚举: 1=480P 2=540P 3=720P 4=1080P 5=1440P 6=2160P 7=4320P 8=360P（具体支持见 `video-models` 的 `resolution_options`） |\n| `--duration` | — | — | 视频时长（秒），可选值取决于模型 |\n| `--count` | — | `1` | 生成数量 1-4（后端一个任务生成 1 个视频，count>1 会并发发起 N 个独立任务并返回 task_ids 数组） |\n| `--enable-sound` | — | 服务端默认 true | 生成音效（仅部分模型支持）。**不传则默认开启**（与前端一致）；关闭请用 `--no-enable-sound`。VideoEdit 不要传 |\n\nSmartEdit 需传 `--source-video/--source-width/--source-height/--source-duration`；`source-duration` 单位毫秒。ExtendVideo 的 `--duration` 表示延长秒数。Wan 3.0 文档参考仅 SubjectToVideo 支持，`--reference-assets` 中传 `{\"type\":\"file\",\"asset_id\":\"...\",\"name\":\"brief.pdf\"}`。\n| `--no-enable-sound` | — | — | 显式关闭音效（`enable_sound=false`） |\n| `--extra-params` | — | — | JSON 对象。CLI 传 MCP `extraParams`；服务端写入 `graph_input.extra_params` 且将每个 value 序列化为字符串 |\n| `--project-id` | — | — | 画布 ID（传入后自动创建占位节点） |\n| `--short-series-project-id` | — | — | 项目 ID |\n| `--name` | — | — | 素材名称 |\n| `--poll` | — | false | 自动轮询直到完成 |\n| `--poll-interval` | — | `5` | 轮询间隔（秒） |\n\n### 3.4 在画布中生视频\n\n与生图类似，传入 `--project-id`（画布 ID）即可自动创建占位：\n\n```bash\nworkrally generate video \\\n --prompt \"海浪翻涌\" \\\n --model \\\n --project-id <画布ID> \\\n --poll\n```\n\n---\n\n## 3.5 画布音频 / 音乐\n\n对齐 Web 无限画布「生成音频」：`mode=audio`（台词/音效）或 `music`（文生音乐）。\n\n```bash\nworkrally generate audio-models -o json\n# 返回 audio_models[] / music_models[]，is_minimax=true 的音频模型不要传 --ref-audios\n\n# 音频\nworkrally generate audio --prompt \"雨声和脚步\" --model --poll\n\n# MiniMax：先读取 audio_models[].fields，再传动态字段\nworkrally generate audio --prompt \"你好\" --model \\\n --audio-fields '{\"voice\":\"voice_id\",\"audio_speech_rate\":1.1}' --poll\n\n# 纯器乐\nworkrally generate music --prompt \"摇滚吉他\" --model --lyrics-mode none --poll\n\n# 传入歌词\nworkrally generate music --prompt \"流行\" --model --lyrics-mode input --lyrics \"啦啦啦\" --poll\n```\n\n传入 `--project-id`（画布 ID）时自动创建 audio 占位节点。场次批量配音请用 `shotlist generate-audio`，不要与画布音频混淆。\n\n---\n\n## 3.6 混元 3D 模型生成\n\n对齐 Web 关键帧结果里的混元 3D（`usePose` / `hunyuan3d`）。**不是** 3D 世界，也不是模型贴图。输入是已入库参考图 `asset_id`，模型固定 `hunyuan-3d-v3.0`。\n\n```bash\nworkrally asset search --project-id --type image -o json\nworkrally generate 3d --asset-id --poll\n```\n\n成功后用 `generate task` 读 `output_assets` / `output_products`（网格模型 URL）。`--project-id` 是短番项目 ID。\n\n---\n\n## 4. 视频提示词优化（gen_content）\n\n用于视频延长/编辑前，把自然语言指令 + 可选参考视频/图片交给模型，生成适合下游视频生成的结构化提示词（如 `subject_definitions`）。\n\n> ⚠️ 这是**异步文本任务**，不是生视频。成功后读 `output_text`，**不会**返回 `output_assets`。\n> ⚠️ **model 必须来自 `generate content-models`**，严禁硬编码 MiniMax H3 等 ID。\n\n```bash\n# 1. 获取模型\nworkrally generate content-models -o json\n\n# 2. 提交优化（建议 --poll）\nworkrally generate optimize-prompt \\\n --prompt \"将视频从尾帧延长5秒\" \\\n --model \\\n --video-url <参考视频CDN_URL> \\\n --first-frame-url <首帧CDN_URL> \\\n --last-frame-url <尾帧CDN_URL> \\\n --reference-image-urls \"<参考图1>,<参考图2>\" \\\n --audio-url <参考音频CDN_URL> \\\n --poll\n```\n\n媒体写入 `messages[0].contents`，**不是**生视频那套 `ref_images` / `frames`。图片语义在 `image_info.type`，音频在 `audio_info.url`：\n\n| CLI | graph_input |\n|-----|-------------|\n| `--video-url` | `contents.type=2` + `video_info.url` |\n| `--first-frame-url` | `contents.type=1` + `image_info.type=\"first_frame\"` |\n| `--last-frame-url` | `contents.type=1` + `image_info.type=\"last_frame\"` |\n| `--reference-image-urls` | 每张 `contents.type=1` + `image_info.type=\"reference_image\"` |\n| `--image-url` | 兼容旧参数，等价于一张 `reference_image` |\n| `--audio-url` / `--audio-urls` | 每条 `contents.type=3` + `audio_info.url` |\n\ncontents 顺序：文本 → 视频 → 首帧 → 尾帧 → 参考图 → 音频。\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--prompt` | ✅ | 待优化的自然语言指令 |\n| `--model` | ✅ | 来自 `content-models` 的 `model_id` |\n| `--video-url` | — | 参考视频 CDN URL（官方媒资） |\n| `--first-frame-url` | — | 首帧图片 CDN URL |\n| `--last-frame-url` | — | 尾帧图片 CDN URL |\n| `--reference-image-urls` | — | 参考图 CDN URL，逗号分隔，可多张 |\n| `--image-url` | — | 单张参考图（兼容旧参数） |\n| `--audio-url` | — | 参考音频 CDN URL |\n| `--audio-urls` | — | 参考音频 CDN URL，逗号分隔，可多条 |\n| `--aspect-ratio` | — | 如 `16:9`（写入比例分量，不是像素） |\n| `--resolution` | — | **protobuf 枚举**（1=480P…），与 `generate image/video` 相同。生图另兼容旧档位 0/1/2 |\n| `--duration` | — | 目标时长秒数，不传服务端默认 5 |\n| `--temperature` | — | 采样温度（可选） |\n| `--seed` | — | 随机种子（可选） |\n| `--extra-params` | — | 扩展参数 JSON 对象 |\n| `--short-series-project-id` | — | 短番项目 ID |\n| `--name` | — | 任务名称 |\n| `--poll` | — | 完成后从结果读取 `output_text` |\n\n与 `polishing_prompt` / `generate_animation_prompt` 的区别：本命令走 TaskGateway `gen_content`，面向视频模型，产物为文本。\n\n---\n\n## 5. 任务轮询\n\n### 5.1 使用 --poll 自动轮询（推荐）\n\n```bash\nworkrally generate image --prompt \"...\" --model --poll\n```\n\n使用 `--poll` 后，CLI 自动：\n1. 提交生成任务\n2. 每隔 N 秒查询状态（默认3秒/图片，5秒/视频）\n3. 显示进度条和状态（排队中/运行中/成功/失败）\n4. 完成后输出最终结果\n\n### 5.2 手动查询任务\n\n```bash\n# 单次查询\nworkrally generate task -o json\n\n# 手动轮询\nworkrally generate task --poll\n```\n\n### 5.3 任务状态\n\n| state | 含义 | 说明 |\n|-------|------|------|\n| 1 | 排队中 (QUEUED) | 等待资源 |\n| 2 | 运行中 (RUNNING) | 正在生成 |\n| 3 | 暂停 (PAUSED) | 暂停中 |\n| 4 | 成功 (SUCCESS) | 媒资任务看 `output_assets`（`output_type=\"assets\"`）；文本任务（optimize-prompt）看 `output_text`（`output_type=\"text\"`）。不要找已废弃的 `output_products` |\n| 5 | 失败 (FAILED) | `error_message` 包含错误信息 |\n| 6 | 已取消 (CANCELLED) | 用户取消 |\n\n### 5.4 多任务并发\n\n后端「一个任务只生成 1 个素材」，当 `--count` > 1 时，CLI 会并发发起 N 个独立任务，返回的 `task_ids` 是长度为 N 的数组，每个 task 产出 1 个素材。使用 `--poll` 时 CLI 会自动并发轮询所有任务，总耗时约等于单任务耗时。\n\n---\n\n## 6. 素材命名最佳实践\n\n### 画布内生成\n\n使用 `--name` 传入\"画布名称_素材特征\"：\n```bash\n# 先获取画布名称\nworkrally canvas get -o json\n# 生成时传入有意义的名称\nworkrally generate image --prompt \"蓝色运动鞋\" --model --project-id \\\n --name \"产品设计画布_蓝色运动鞋\" --poll\n```\n\n### 非画布生成\n\n从 prompt 中提取核心关键词作为名称：\n```bash\nworkrally generate image --prompt \"一只可爱的橘猫在夕阳下奔跑\" --model \\\n --name \"橘猫_夕阳奔跑\" --poll\n```\n\n---\n\n## 7. 生成后素材处理\n\nAI 生成的图片/视频会**自动入库到媒资系统**（后台自动完成，无需额外调用 `asset create`）。\n\n### 如果需要上传到资产库\n\n```bash\n# 1. 生成完成后，从结果中获取 asset_id\n# 2. 获取 asset_details\nworkrally asset get -o json\n# 3. 挂载到资产库\nworkrally material add --json-list '[{\"material_id\":\"\",\"material_name\":\"角色名\",\"material_type\":2,\"parent_id\":\"\",\"material_detail\":}]' \\\n --project-ids \n```\n\n### 如果需要在画布上展示\n\n传入 `--project-id` 即可，系统自动处理。无需手动调用 `build-draft`。\n\nFile v2.10.1:references/canvas-guide.md\n\n# 无限画布操作指南\n\n本文档帮助 AI Agent 正确操作 WorkRally 无限画布（Infinite Canvas）。画布基于 Yjs 协同编辑引擎，CLI 写入的内容会**实时同步**给所有在线用户，无需刷新页面。\n\n---\n\n## 1. 核心概念\n\n### 两种\"项目\"（容易混淆，务必区分）\n\n| 概念 | 管理命令 | 用途 | 必要性 |\n|------|---------|------|--------|\n| **项目** (project) | `workrally project list/create/get` | 所有素材都必须归属一个项目，范围更大 | **必须** — 素材不关联项目则在 web 端不可见 |\n| **画布** (canvas) | `workrally canvas list/create/get` | 无限画布空间，可在其中排布节点 | **可选** — 仅当用户要在画布中操作时才需要 |\n\n> ⚠️ **两者的 ID 不能互相替代！**\n> - `workrally project list` 返回的是项目 ID\n> - `workrally canvas list` 返回的是画布 ID\n> - 在画布场景下，素材需要**同时关联两者**\n\n### 判断用户意图\n\n| 用户说 | 含义 | 使用命令 |\n|--------|------|---------|\n| \"我的项目\"、\"项目列表\" | 项目 | `workrally project list` |\n| \"我的画布\"、\"画布列表\" | 无限画布 | `workrally canvas list` |\n| \"在画布上生成图片\" | 画布 + AI 生成 | `workrally generate image --project-id <画布ID>` |\n| \"上传到项目\" | 仅入媒资库 | `upload` → `asset create` |\n| \"在画布上展示素材\" | 需要 build-draft | `upload` → `asset create` → `canvas build-draft` |\n\n---\n\n## 2. 画布节点类型 (8 种)\n\n### 类型一览\n\n| type | 说明 | 必填 data 字段 | 可放入画板 |\n|------|------|---------------|-----------|\n| `image` | 图片素材 | `data.asset.id` (已有素材) 或 `data.task` (生成中占位) | ✅ |\n| `video` | 视频素材 | `data.asset.id` 或 `data.task` | ✅ |\n| `audio` | 音频素材 | `data.asset.id` (**必须**，音频无生成器) | ✅ |\n| `imageGenerator` | 图片生成器 | 无必填（params 可选） | ❌ |\n| `videoGenerator` | 视频生成器 | 无必填（params 可选） | ❌ |\n| `artboard` | 画板容器 | 无（建议设置 `style.width/height`） | ❌ (画板不可嵌套) |\n| `text` | 文本 | `data.text.content` (字符串，最大90000字符) | ❌ |\n| `freehand` | 画笔涂鸦 | `data.freehand.points` + `data.freehand.initialSize` | ❌ |\n\n### 节点通用结构\n\n```json\n{\n \"id\": \"node_unique_id\",\n \"type\": \"image\",\n \"position\": { \"x\": 100, \"y\": 200 },\n \"data\": { },\n \"style\": { \"width\": 512, \"height\": 512 },\n \"parentId\": \"artboard_id\",\n \"measured\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n**字段说明**：\n- `id` — 节点唯一标识，可使用任意唯一字符串\n- `position` — 节点左上角坐标（缺失时堆叠在原点 0,0）\n- `style` — 节点显示尺寸\n- `parentId` — 仅画板内子节点需要，指向父画板的 id\n- `measured` — 渲染尺寸，可选，缺失时服务端自动补全\n\n---\n\n## 3. 各节点类型详细说明\n\n### 3.1 图片/视频节点 (image / video)\n\n两种来源：\n1. **已有素材** — 必须有 `data.asset.id`\n2. **生成中占位** — 必须有 `data.task`（由 AI 生成命令自动创建，通常不需要手动构造）\n\n```json\n{\n \"id\": \"img_001\",\n \"type\": \"image\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_abc123\" }\n },\n \"style\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n**带生成任务标记的节点**（用于\"再次编辑\"功能）：\n```json\n{\n \"id\": \"gen_img_001\",\n \"type\": \"image\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_abc123\" },\n \"task\": { \"taskId\": \"task_xyz789\", \"status\": \"success\" }\n },\n \"style\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n> 💡 `data.task` 字段决定前端是否显示\"再次编辑\"按钮。AI 生成的图片/视频应包含此字段。\n\n### 3.2 音频节点 (audio)\n\n音频**没有生成器**，不支持 task 占位，必须有 `data.asset.id`。\n\n```json\n{\n \"id\": \"audio_001\",\n \"type\": \"audio\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_audio_456\" }\n },\n \"style\": { \"width\": 260, \"height\": 80 }\n}\n```\n\n> 建议尺寸 **260×80**（与前端默认一致）。\n\n### 3.3 画板节点 (artboard)\n\n画板是**容器**，子节点通过 `parentId` 关联到画板。\n\n```json\n{\n \"id\": \"board_001\",\n \"type\": \"artboard\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {},\n \"style\": { \"width\": 600, \"height\": 800 }\n}\n```\n\n**画板子节点示例** — 在画板内放置一张图片：\n```json\n{\n \"id\": \"img_in_board\",\n \"type\": \"image\",\n \"position\": { \"x\": 20, \"y\": 20 },\n \"data\": { \"asset\": { \"id\": \"asset_abc123\" } },\n \"style\": { \"width\": 256, \"height\": 256 },\n \"parentId\": \"board_001\"\n}\n```\n\n**画板规则**：\n- ✅ `image`、`video`、`audio` 可以放入画板\n- ❌ `imageGenerator`、`videoGenerator`、`text`、`freehand` 不可放入画板\n- ❌ 画板不可嵌套（画板内不能放画板）\n- ❌ **不要设置 `extent: \"parent\"`**，否则子节点会被锁定在画板内无法拖出\n- 画板缺少尺寸时自动补全为 **600×800**\n\n### 3.4 文本节点 (text)\n\n```json\n{\n \"id\": \"text_001\",\n \"type\": \"text\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"text\": {\n \"content\": \"这是一段文本\",\n \"fontSize\": 24,\n \"fontWeight\": 400,\n \"textAlign\": \"left\",\n \"color\": \"#ffffff\"\n }\n },\n \"style\": { \"width\": 200 }\n}\n```\n\n**必填**: `data.text.content`（字符串，最大90000字符）\n**可选**（有默认值）: `fontSize`(24), `fontWeight`(400, 加粗用700), `textAlign`(\"left\"), `color`(\"#ffffff\")\n建议设置 `style.width`（默认200）。\n\n### 3.5 画笔涂鸦节点 (freehand)\n\n```json\n{\n \"id\": \"freehand_001\",\n \"type\": \"freehand\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"freehand\": {\n \"points\": [[10, 20, 0.5], [30, 40, 0.7], [50, 60, 0.5]],\n \"initialSize\": { \"width\": 200, \"height\": 200 },\n \"color\": \"rgba(242,72,34,1)\",\n \"size\": 7\n }\n }\n}\n```\n\n**必填**: `data.freehand.points`（二维数组，每个点为 `[x, y, pressure]`）、`data.freehand.initialSize`（`{width, height}`）\n**可选**: `color`（默认红色 `rgba(242,72,34,1)`）、`size`（画笔粗细 1-100，默认7）\n`pressure` 值范围 0-1，超出自动截断。\n\n### 3.6 生成器节点 (imageGenerator / videoGenerator)\n\n> ⚠️ **通常不需要手动创建！** `workrally generate image/video --project-id <画布ID>` 会**自动**在画布中创建 running 状态的占位节点。\n\n仅在极特殊场景（如手动构建已完成的生成器节点）才需要：\n\n```json\n{\n \"id\": \"gen_001\",\n \"type\": \"imageGenerator\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"task\": { \"taskId\": \"task_abc\", \"status\": \"success\" },\n \"params\": {}\n },\n \"style\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n---\n\n## 4. build-draft 操作模式\n\n### 4.1 增量合并（默认模式）\n\n```bash\nworkrally canvas build-draft --nodes '[...]'\n```\n\n规则：\n- **同 id → 覆盖更新**：传入的节点 id 与已有节点相同时，用新数据替换旧数据\n- **新 id → 追加**：已有画布中不存在的 id 会被添加\n- **未提及 → 保留**：已有节点不在传入列表中的，原样保留\n\n### 4.2 删除节点\n\n```bash\nworkrally canvas build-draft --delete-node-ids \"id1,id2\"\n```\n\n可与 `--nodes` 同时使用（先删除，再合并新节点）：\n\n```bash\nworkrally canvas build-draft --nodes '[...]' --delete-node-ids \"old1,old2\"\n```\n\n### 4.3 全量覆盖\n\n```bash\nworkrally canvas build-draft --nodes '[...]' --mode overwrite\n```\n\n**清空画布**后仅保留传入的节点。传 `--nodes '[]' --mode overwrite` 可清空整个画布。\n\n> ⚠️ 全量覆盖会删除所有已有节点，包括其他用户的内容。在多人协作场景下应优先使用增量合并。\n\n### 4.4 从文件加载节点\n\n```bash\nworkrally canvas build-draft --file nodes.json\n```\n\n适合节点数据量大或结构复杂的场景。\n\n---\n\n## 5. 常见工作流示例\n\n### 场景 A：在画布上排列已有素材\n\n```bash\n# 1. 搜索项目中的素材\nworkrally asset search --project-id -o json\n\n# 2. 从搜索结果中获取 asset_id，构建节点写入画布\nworkrally canvas build-draft --nodes '[\n {\"id\":\"n1\",\"type\":\"image\",\"position\":{\"x\":0,\"y\":0},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":512,\"height\":512}},\n {\"id\":\"n2\",\"type\":\"image\",\"position\":{\"x\":600,\"y\":0},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":512,\"height\":512}}\n]'\n```\n\n### 场景 B：创建画板并放入多张图片\n\n```bash\nworkrally canvas build-draft --nodes '[\n {\"id\":\"board\",\"type\":\"artboard\",\"position\":{\"x\":0,\"y\":0},\"data\":{},\"style\":{\"width\":800,\"height\":600}},\n {\"id\":\"img1\",\"type\":\"image\",\"position\":{\"x\":20,\"y\":20},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":350,\"height\":250},\"parentId\":\"board\"},\n {\"id\":\"img2\",\"type\":\"image\",\"position\":{\"x\":420,\"y\":20},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":350,\"height\":250},\"parentId\":\"board\"}\n]'\n```\n\n### 场景 C：更新画布中某个节点的位置\n\n```bash\n# 只传需要修改的节点，其他节点自动保留\nworkrally canvas build-draft --nodes '[\n {\"id\":\"existing_node_id\",\"type\":\"image\",\"position\":{\"x\":300,\"y\":400},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":512,\"height\":512}}\n]'\n```\n\n### 场景 D：删除部分节点并添加新节点\n\n```bash\nworkrally canvas build-draft \\\n --nodes '[{\"id\":\"new1\",\"type\":\"text\",\"position\":{\"x\":0,\"y\":0},\"data\":{\"text\":{\"content\":\"新标题\",\"fontSize\":48,\"fontWeight\":700,\"color\":\"#00ff00\"}},\"style\":{\"width\":400}}]' \\\n --delete-node-ids \"old_node_1,old_node_2\"\n```\n\n---\n\n## 6. 服务端自动修正\n\n服务端会对传入的节点进行以下自动修正（不需要 Agent 操心）：\n\n| 场景 | 自动行为 |\n|------|---------|\n| 画板缺少 style | 补全 600×800 |\n| 文本节点缺少样式属性 | 补全 fontSize=24, fontWeight=400, textAlign=left, color=#ffffff |\n| 文本节点缺少 style.width | 补全 200 |\n| 文本内容为空 | 填充\"在此输入文本\" |\n| 画笔节点缺少颜色/大小 | 补全 color=rgba(242,72,34,1), size=7 |\n| 画笔 size 超出范围 | 截断到 1-100 |\n| 画笔 pressure 超出范围 | 截断到 0-1 |\n| 子节点设置了 extent | 自动清除（防止锁定） |\n\n**但以下关键字段缺失会被拒绝**：\n\n| 场景 | 错误 |\n|------|------|\n| image/video 既没有 asset.id 也没有 task | ❌ 空节点 |\n| audio 没有 asset.id | ❌ 音频无生成器 |\n| text 没有 data.text.content 或类型非字符串 | ❌ |\n| text 内容超过 90000 字符 | ❌ |\n| freehand 缺少 points 或 initialSize | ❌ |\n| 不允许的节点类型（如 group） | ❌ |\n| 画板子节点类型不是 image/video/audio | ❌ |\n\nFile v2.10.1:references/common-pitfalls.md\n\n# 常见问题与易错点\n\n本文档汇总 AI Agent 使用 WorkRally CLI 时最容易犯的错误和混淆点，帮助避免常见陷阱。\n\n---\n\n## ❌ 错误 1：混淆\"项目\"和\"画布\"\n\n### 问题\n\n```bash\n# ❌ 错误：把项目 ID 当画布 ID 用\nworkrally generate image --prompt \"...\" --model --project-id \n```\n\n### 正确做法\n\n```bash\n# ✅ 先获取画布 ID\nworkrally canvas list -o json\n# 再传画布 ID\nworkrally generate image --prompt \"...\" --model --project-id \n```\n\n### 区分规则\n\n| 获取方式 | 返回的是 | 传给谁 |\n|----------|---------|--------|\n| `workrally project list` | 项目 ID | `asset create --project-id`、`asset search --project-id` |\n| `workrally canvas list` | 画布 ID | `generate image --project-id`、`generate video --project-id`、`canvas build-draft` |\n\n---\n\n## ❌ 错误 2：硬编码模型 ID\n\n### 问题\n\n```bash\n# ❌ 错误：猜测或硬编码模型 ID\nworkrally generate image --prompt \"...\" --model \"kontext_v2\"\n```\n\n### 正确做法\n\n```bash\n# ✅ 动态获取\nworkrally generate image-models -o json\n# 从返回结果中读取 model_id\nworkrally generate image --prompt \"...\" --model <从返回结果中获取的model_id>\n```\n\n> 模型列表是**动态下发**的，不同环境的可用模型可能完全不同。\n> 生视频用 `generate video-models`；生音频/音乐用 `generate audio-models`；提示词优化用 `generate content-models`（不要硬编码 MiniMax H3）。混元 3D 用 `generate 3d --asset-id`，不要查 3d-models。\n\n---\n\n## ❌ 错误 3：自行拼接前端 URL\n\n### 问题\n\n```bash\n# ❌ 错误：自己拼接 URL（域名和路由因环境而异）\necho \"https://workrally.qq.com/workrally/toolbox/canvas/abc123\"\n```\n\n### 正确做法\n\n```bash\n# ✅ 使用 url build 命令\nworkrally url build \"无限画布\" --params '{\"id\":\"abc123\"}'\n```\n\n---\n\n## ❌ 错误 4：生成后手动调用 build-draft\n\n### 问题\n\n```bash\n# ❌ 不必要：在画布中生成图片后，又手动创建节点\nworkrally generate image --prompt \"...\" --model --project-id --poll\n# 然后又调用 build-draft 创建节点 ← 多余操作\nworkrally canvas build-draft --nodes '[...]'\n```\n\n### 正确理解\n\n传入 `--project-id` 后，系统**自动**在画布创建 running 状态的占位节点。**无需手动 build-draft。**\n\n### build-draft 的正确使用场景\n\n- 在画布上放置**已有素材**（非 AI 生成的图片/视频/音频）\n- 管理**画板布局**（创建画板、调整子节点位置）\n- 添加**文本**或**涂鸦**节点\n- **删除**画布上的节点\n- **重新排列**已有节点\n\n---\n\n## ❌ 错误 5：上传素材缺少入库步骤\n\n### 问题\n\n```bash\n# ❌ 错误：上传后直接使用 CDN URL\nworkrally upload ./file.png -o json\n# 然后直接把 cdn_url 作为 asset_id 用 ← 这不是 asset_id！\n```\n\n### 正确做法\n\n```bash\n# ✅ 上传后必须入媒资库\nworkrally upload ./file.png -o json\nworkrally asset create --url --project-id -o json\n# 现在才有 asset_id\n```\n\n> 上传只是把文件传到 CDN，**必须**调用 `asset create` 入库才能被系统使用。\n\n---\n\n## ❌ 错误 6：资产库挂载缺少关键字段\n\n### 问题\n\n```bash\n# ❌ 错误：JSON 中缺少 material_id 或 material_detail\nworkrally material add --json-list '[{\"material_name\":\"素材\",\"material_type\":2,\"parent_id\":\"role_person\"}]'\n# 素材不会在资产库列表中显示！\n```\n\n### 正确做法\n\n```bash\n# ✅ 必须在 JSON 中传 material_id（=asset_id）和完整的 material_detail（=asset_details）\nworkrally material add --json-list '[{\n \"material_id\": \"\",\n \"material_name\": \"素材名\",\n \"material_type\": 2,\n \"parent_id\": \"\",\n \"material_detail\": <完整的 asset_details 对象>\n}]' --project-ids \n```\n\n---\n\n## ❌ 错误 7：画板内放入不允许的节点类型\n\n### 问题\n\n```bash\n# ❌ 错误：把文本节点放入画板\nworkrally canvas build-draft --nodes '[\n {\"id\":\"board\",\"type\":\"artboard\",\"position\":{\"x\":0,\"y\":0},\"data\":{},\"style\":{\"width\":600,\"height\":800}},\n {\"id\":\"txt\",\"type\":\"text\",\"position\":{\"x\":20,\"y\":20},\"data\":{\"text\":{\"content\":\"标题\"}},\"parentId\":\"board\"}\n]'\n# 服务端会拒绝！\n```\n\n### 正确理解\n\n画板只接受 `image`、`video`、`audio` 类型的子节点。\n\n---\n\n## ❌ 错误 8：给画板子节点设置 extent\n\n### 问题\n\n```json\n{\n \"id\": \"img1\",\n \"type\": \"image\",\n \"parentId\": \"board\",\n \"extent\": \"parent\"\n}\n```\n\n### 后果\n\n子节点被 ReactFlow 锁定在画板内，用户无法拖出。服务端会自动清除此属性，但不要主动设置。\n\n---\n\n## ❌ 错误 9：混淆 material_id 和 role_id\n\n### 问题\n\n```bash\n# ❌ 错误：用 material_id 查角色详情\nworkrally role get \"abc_0\"\n# material_id 格式: \"abc_0\" (带后缀)\n# role_id 格式: \"abc\" (不带后缀)\n```\n\n### 正确做法\n\n```bash\n# ✅ 先获取 role_id\nworkrally material get \"abc_0\" -o json\n# 从返回结果中找到 role_id 字段\nworkrally role get \"abc\" -o json\n```\n\n---\n\n## ❌ 错误 10：音视频 URL 使用 original_url\n\n### 问题\n\n```bash\n# ❌ 错误：音视频使用 original_url（不含访问凭证）\n# original_url 是原始 CDN 路径，音视频无法直接访问\n```\n\n### 正确做法\n\n始终使用 `url` 或 `download_url`，这些是可直接访问的临时 URL。过期后通过 `asset get` 重新获取即可，返回的新 URL 可直接作为其他工具的 URL 参数传入。\n\n---\n\n## ❌ 错误 11：生图 `--resolution 1/2` 当成视频枚举\n\n### 问题\n\n```bash\n# ❌ 错误：以为和 generate video 一样，2=540P\nworkrally generate image --prompt \"...\" --model --resolution 2\n# 生图里 2 仍是旧档位 4K，不是 540P\n```\n\n### 正确做法\n\n```bash\nworkrally generate image-models -o json\n# 用该模型 resolution_options[].value（常见 4=1080P、5=1440P、6=2160P）\nworkrally generate image --prompt \"...\" --model --resolution 5\n```\n\n旧脚本继续传 `0/1/2` 仍然有效（映射为 1080P/1440P/2160P），新调用不要混用两套数字。\n\n---\n\n## ❌ 错误 12：提示词优化任务去找 output_assets\n\n### 问题\n\n```bash\nworkrally generate optimize-prompt --prompt \"延长5秒\" --model --poll\n# ❌ 在结果里找 output_assets / output_products —— 文本任务没有媒资产物\n```\n\n### 正确做法\n\n```bash\n# ✅ 先拿模型\nworkrally generate content-models -o json\n# ✅ 轮询成功后读 output_text（output_type=\"text\"）\nworkrally generate optimize-prompt --prompt \"将视频从尾帧延长5秒\" --model \\\n --video-url --first-frame-url --last-frame-url \\\n --reference-image-urls \"url1,url2\" --audio-url --poll\n```\n\n| 任务 | output_type | 产物字段 |\n|------|-------------|----------|\n| 生图 / 生视频 | `assets` | `output_assets` |\n| 提示词优化 | `text` | `output_text` |\n\n---\n\n## 常见判断速查表\n\n| 场景 | 需要什么 |\n|------|---------|\n| \"上传一张图片\" | `upload` → `asset create` (2步) |\n| \"上传到人物角色\" | `upload` → `asset create` → `material add` (3步) |\n| \"在画布上生成图片\" | `generate image --project-id <画布ID> --poll` (1步) |\n| \"把已有图片放到画布上\" | `asset search` → `canvas build-draft` |\n| \"生成4张图片\" | `generate image --count 4 --poll` |\n| \"查看生成进度\" | `generate task --poll` |\n| \"优化视频提示词\" | `generate content-models` → `generate optimize-prompt --poll`（读 `output_text`） |\n| \"创建一个画板放三张图\" | `canvas build-draft` (一次传画板+3个子节点) |\n| \"删除画布上的某个节点\" | `canvas build-draft --delete-node-ids \"node_id\"` |\n| \"清空整个画布\" | `canvas build-draft --nodes '[]' --mode overwrite` |\n| \"查看角色的 LoRA 版本\" | `material get` → `role get` |\n| \"搜索项目中的视频素材\" | `asset search --project-id ` |\n\n---\n\n## 查看白名单工具\n\n只能使用 `tools list` / `tools describe` 和已封装的 CLI 子命令。**不要**透传调用未列出的 MCP 工具（`tools call` 已移除）。\n\n```bash\nworkrally tools list -o json\nworkrally tools describe \n```\n\n---\n\n## 输出格式建议\n\n| 格式 | 用途 | 命令 |\n|------|------|------|\n| `json` | **Agent 推荐** — 结构化数据便于解析 | `-o json` |\n| `table` | 人类阅读 — 表格格式 | `-o table` |\n| `text` | 管道/脚本 — 纯文本 | `-o text` |\n\n设置全局默认格式：\n```bash\nworkrally config set output_format json\n```\n\nFile v2.10.1:references/shotlist-guide.md\n\n# 场次操作指南（shotlist · 对齐 Web /shot 批量制作）\n\n本文档帮助 AI Agent 通过 `workrally shotlist` / `workrally series` 完成场次全生命周期管理，对应前端 `/shot`（`anime-new-shot`）批量制作能力：\n\n- **生成走统一任务通道**（`TvShortSeriesTask.SubmitTask/BatchSubmitTask`）\n- **配置聚合在 `shot.extra.gen_config.{image,video,audio}`**\n- **模型统一来自 `shotlist models`（GetTaskModelList，画布同源）**\n- **支持生图 / 生视频 / 生音频**，结果查询 `--type image|video|audio`\n\n---\n\n## 1. 概念图谱\n\n```\n项目 (project)\n └─ 剧集 (series)\n └─ 场次 (shot/story)\n ├─ ⭐ 图片提示词 (image_prompt) ← 决定关键帧画面\n ├─ ⭐ 视频提示词 (animation_prompt) ← 决定动效/运镜\n ├─ ⭐ 音频提示词 (extra.audio_prompt) ← 音色用 <音色名> 引用\n ├─ 参考资产 (video_role_data_json) ← 图片+视频统一存放\n ├─ 音频参考 (extra.audio_role_data_json) ← 仅音频，独立字段\n └─ 生成配置 (extra.gen_config.{image,video,audio}) ← 模型/比例/时长/分辨率等\n```\n\n---\n\n## 2. 标准工作流（唯一推荐）\n\n`series create` → `shotlist create` → `shotlist recognize` → `shotlist models` → `shotlist set-model` → `shotlist generate-image / generate-video / generate-audio` → `shotlist get-result --type image|video|audio --watch`\n\n```bash\n# 1) 新建剧集\nSERIES_ID=$(workrally series create --project-id $PROJECT_ID --name \"第一集\" -o json | jq -r '.series_id')\n\n# 2) 批量创建场次（按用户意图填提示词：仅图 / 仅视频 / 图+视频）\nworkrally shotlist create --series-id $SERIES_ID --json-list \\\n '[{\"image_prompt\":\"古风庭院全景\",\"animation_prompt\":\"镜头缓推\"},\n {\"image_prompt\":\"两位侠客对峙\",\"animation_prompt\":\"推近脸部特写\"}]'\n\n# 3) 识别角色/资产（三路：image/animation/audio）\nworkrally shotlist recognize --series-id $SERIES_ID --project-id $PROJECT_ID\n\n# 4) 选模型（勿硬编码）→ 写配置\nworkrally shotlist models --category image,video,audio -o json\nworkrally shotlist set-model --series-id $SERIES_ID \\\n --image-model --image-aspect-ratio 16:9 \\\n --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9 \\\n --audio-model \n\n# 5) 生成（多场次一起；均需 --project-id）\nSTORY_IDS=$(workrally shotlist list --series-id $SERIES_ID -o json | jq -r '[.story_list[].story_id] | join(\",\")')\nworkrally shotlist generate-image --project-id $PROJECT_ID --story-ids \"$STORY_IDS\"\nworkrally shotlist generate-video --project-id $PROJECT_ID --story-ids \"$STORY_IDS\"\nworkrally shotlist generate-audio --project-id $PROJECT_ID --story-ids \"$STORY_IDS\"\n\n# 6) 查结果（image/video/audio 三条独立进度，分别 watch）\nfor sid in $(echo \"$STORY_IDS\" | tr ',' ' '); do\n workrally shotlist get-result --story-id $sid --type image --watch\n workrally shotlist get-result --story-id $sid --type video --watch\n workrally shotlist get-result --story-id $sid --type audio --watch\ndone\n```\n\n---\n\n## 3. 模型与生成配置（`extra.gen_config`）\n\n> ⚠️ 模型来自 `shotlist models`（GetTaskModelList，画布同源），返回的 `id` 直接写入 `gen_config`；\n> 旧 `shot image-models`（Kontext en_name）/ `shot video-models`（Wuji provider）**不适用于 shotlist**。\n\n```bash\n# 拉可用模型（category 逗号分隔）\nworkrally shotlist models --category image,video,videoSingle,videoFrame,audio -o json\n# 返回每模型：id / name / aspect_ratios / resolutions(enum_value) / durations（audio 含 restrictions）\n```\n\n`set-model` 把配置写入 `extra.gen_config`（不传 `--story-ids` 则对 `--series-id` 全剧集生效）：\n\n| 维度 | flags | 写入字段 |\n|------|-------|---------|\n| 图片 | `--image-model` / `--image-aspect-ratio` / `--image-resolution` / `--image-count` / `--image-quality` / `--mj-params` | `gen_config.image` |\n| 视频 | `--video-mode`(SubjectToVideo\\|Text\\|FirstLastFrame\\|SmartEdit) + 对应模型；`--single-assets` / `--first-last-assets` / `--extra-mode extendVideo` / `--extend-source-id`；支持 `--no-enable-sound` / `--erase-subtitles` | `gen_config.video` |\n| 音频 | `--audio-model` / `--audio-count` / `--audio-config` / `--audio-fields` / `--audio-capabilities` | `gen_config.audio` |\n\n**视频四种主模式 + 延长子模式**（模型字段互不通用，切模式要用对应类别的模型）：\n- `SubjectToVideo`（参考主体，默认）：模型写 `model`；资产走 `video_role_data_json`。\n- `Text`（单图）：模型写 `textModel`；资产走 `gen_config.video.singleAssets`（CLI `--single-assets`）。\n- `FirstLastFrame`（首尾帧）：模型写 `firstLastModel`；资产走 `gen_config.video.firstLastAssets`（CLI `--first-last-assets`）。\n- `SmartEdit`（智能编辑）：模型写 `smartEditModel`；需 `smartEditSourceVideo`（含 asset_id/width/height/duration），提示词可空。\n- **延长视频**：`mode=SubjectToVideo` + `extraMode=extendVideo` + `__extendSourceId`（源片 asset_id）+ `duration`（延长秒数，不是成片总时长）；生成走 `graph_template=extend_video`。\n\n> Auto 智能路由模型（capability 111）**暂不支持** MCP/CLI 自动分流，请用 `shotlist models` 选具体模型 id。\n\n---\n\n## 4. 资产识别（recognize）\n\n底层仍是 `Material.MatchContentRole`，但新版支持**符号分词**与**音频路**：\n\n```bash\n# 默认：both（图片+视频+音频三路）、text 规则、仅本项目资产库\nworkrally shotlist recognize --series-id --project-id \n\n# 只识别某一路\nworkrally shotlist recognize --series-id --project-id --scope image\nworkrally shotlist recognize --series-id --project-id --scope audio\n\n# 符号+文字识别：【角色】=图片/状态，<音色>=音频\nworkrally shotlist recognize --series-id --project-id --match-rule symbol_text\n\n# 全资产库范围\nworkrally shotlist recognize --series-id --recognize-scope all\n```\n\n- `--scope`：`image | animation | audio | both`（识别哪条 prompt；默认 both）。\n- `--match-rule`：`text`（默认，去掉 `【】<>` 全部当图片）/ `symbol_text`（区分图片与音色）。**音频路内部强制 `symbol_text`**。\n- `--recognize-scope`：`project`（默认，仅本项目）/ `all`（全资产库）。\n- 落库：图片/视频路写 `role_data_json` + `video_role_data_json`（统一）+ prompt 占位 + `extra.*_prompt_json`；音频路写 `extra.audio_role_data_json` + `extra.audio_prompt` + `extra.audio_prompt_json`。\n\n> ⚠️ `--scope` 控制识别路（image/animation/audio/both），`--recognize-scope` 控制资产库范围（project/all），二者勿混用。\n\n---\n\n## 5. 生成与结果查询\n\n> ⚠️ `shotlist generate-*` **仅提交任务**，不返回可轮询的画布 task_id；进度归属「场次 + 类型」，用 `shotlist get-result` 查。\n> 三个生成命令都需要 `--project-id`（短番项目ID，SubmitTask 需要）。\n\n```bash\n# 生图（每场次 count 张）\nworkrally shotlist generate-image --project-id --story-ids st_1,st_2 --count 2\n# 生视频（按各场次 gen_config.video.mode 分支，每场次 1 条）\nworkrally shotlist generate-video --project-id --story-ids st_1,st_2\n# 对已选定视频超分（model 来自 models --category upscale）\nworkrally shotlist upscale-video --project-id --story-ids st_1,st_2 --model --scale 2\n# 生音频（按模型能力走 reference_to_audio 或 text_to_audio，每场次 count 条）\nworkrally shotlist generate-audio --project-id --story-ids st_1,st_2\n\n# 查结果（--type image|video|audio；--watch 轮询至 state=all_done）\nworkrally shotlist get-result --story-id st_1 --type audio --watch --interval 5\n```\n\n`get-result` 返回关键字段：`state`(all_done/running/no_data) / `doing_count` / `done_count` / `failed_count` / `results[]` / `doing_tasks[]` / `failed_tasks[]`。`doing_count===0` 即该类型任务全部结束。\n\n---\n\n## 6. 音频生成（新增能力）\n\n1. 在 `image/animation` 之外，场次可独立生成音频（配音/音效）。参考音频模型（如 Seed Audio）走 `reference_to_audio`；能力列表含 `106` 的 MiniMax 模型走 `text_to_audio` 且不接收参考音频。\n2. 音频提示词存 `extra.audio_prompt`；**音色用 `<音色名>` 引用**，参考资产仅音频（`extra.audio_role_data_json`），与视频/图片参考完全隔离。\n3. 流程：`shotlist models --category audio` 选模型 → `shotlist set-model --audio-model ` → （可选 `shotlist recognize --scope audio --match-rule symbol_text` 识别音色）→ `shotlist generate-audio --project-id --story-ids ` → `shotlist get-result --type audio --watch`。\n\n---\n\n## 7. 资产绑定（bind）\n\n```bash\n# 图片/视频参考 → 统一写入 video_role_data_json\nworkrally shotlist bind --story-id st_1 --type image --assets '[{\"asset_id\":\"a1\",\"url\":\"https://...\"}]'\nworkrally shotlist bind --story-id st_1 --type video --assets '[{...}]'\n# 音频参考 → 独立写入 extra.audio_role_data_json\nworkrally shotlist bind --story-id st_1 --type audio --assets '[{\"asset_id\":\"au1\",\"url\":\"https://...\"}]'\n# 本地参考音频 → CLI 自动完成上传、媒资入库、绑定\nworkrally shotlist bind --story-id st_1 --type audio --file ./voice.wav --project-id \n# 替换而非追加\nworkrally shotlist bind --story-id st_1 --type image --mode replace --assets '[...]'\n```\n\n---\n\n## 8. 易错点\n\n| 错误 | 正确做法 |\n|------|----------|\n| 用 `shot image-models/video-models` 给 shotlist 配模型 | 新版用 `shotlist models --category ...`（GetTaskModelList），id 直接写 gen_config |\n| `shot` 与 `shotlist` 混用同一剧集 | 配置字段不互通（扁平字段 vs gen_config），一个剧集固定用一套 |\n| `generate-*` 不传 `--project-id` | 新版走 SubmitTask，必须传短番项目 ID |\n| 等 `generate-*` 返回 task_id 去轮询 | MCP 会返回 `task_ids`；CLI 仍建议用 `shotlist get-result --type image\\|video\\|audio [--watch]` |\n| 一次 `get-result` 同时查三类 | image/video/audio 是三条独立进度，分别用 `--type` 查 |\n| 音色识别不出来 | 音色要用 `<音色名>` 且 `--match-rule symbol_text`（音频路已强制） |\n| 本地参考音频不能直接绑定 | 使用 `shotlist bind --type audio --file --project-id `，CLI 会自动上传并入库 |\n| 已绑定音频生成时没有进入 `ref_audios` | 绑定项需有 `asset_id/assetId` 或 URL；新版 bind 会自动补齐 `fileType=audio` |\n| 延长视频提交失败 | 需 `--extra-mode extendVideo` + `--extend-source-id` + `--duration`（延长秒数），且 mode 为 SubjectToVideo |\n| Auto 模型生成结果不符合预期 | MCP/CLI 不会走前端 task_router，请改选具体模型 |\n| 硬编码模型 id | 必须先 `shotlist models` 动态获取 |\n\nFile v2.10.1:references/upload-and-assets-guide.md\n\n# 上传与素材管理指南\n\n本文档帮助 AI Agent 正确执行文件上传和素材管理流程。WorkRally 有两套素材体系，理解它们的关系是正确操作的前提。\n\n---\n\n## 1. 两套素材体系\n\n### 媒资库 (Asset) — 项目级文件池\n\n- **管理命令**: `workrally asset search/create/get/update`\n- **本质**: 扁平的文件列表，每个素材必须归属一个项目\n- **特点**: 视频/音频为**私有读存储**，必须入库后才能正常访问\n- **何时使用**: 所有素材都**必须**经过媒资库（`asset create`）才能被系统使用\n\n### 资产库 (Material) — 树形目录管理\n\n- **管理命令**: `workrally material list/add/update/get/breadcrumb`\n- **本质**: 树形文件夹结构，对媒资库素材的**组织视图**\n- **三个预设根目录**: `role_person`(人物)、`role_prop`(道具)、`role_scene`(场景)\n- **附加根目录**: `root`(用户自建网盘文件夹)\n- **何时使用**: 仅当用户要将素材\"归档到角色/道具/场景/文件夹\"时才需要\n\n### 数据层次关系\n\n```\n资产 (material_type=0)\n └─ 角色状态 (material_type=5)\n ├─ 图片素材 (material_type=2)\n ├─ 视频素材 (material_type=3)\n └─ 音频素材 (material_type=4)\n```\n\n---\n\n## 2. 三步上传流程\n\n这是 WorkRally 最核心的文件处理流程，**严格按顺序执行**：\n\n### 步骤 1: 上传文件到 CDN\n\n```bash\nworkrally upload ./character.png -o json\n```\n\n返回：\n```json\n{\n \"url\": \"https://cdn.example.com/path/to/file.png\",\n \"original_url\": \"https://cdn.example.com/path/to/file.png\",\n \"signed_url\": \"https://cdn.example.com/path/to/file.mp4?sign=...\"\n}\n```\n\n**URL 字段说明**：\n- `url` — 可直接访问的地址。图片为公开 URL；音视频为临时访问 URL\n- `original_url` — 原始 CDN 路径（不含访问凭证），图片可直接访问，音视频无法直接访问\n- `signed_url` — 仅音视频返回，与 `url` 相同\n\n> ⚠️ 音视频文件为私有读存储，**必须使用 `url` 或 `signed_url`**，不要使用 `original_url`。\n\n### 步骤 2: 入媒资库（必须！）\n\n> 🔒 `--url` 仅接受 WorkRally 官方媒资 URL（即 `upload` 返回值或媒资库 URL），详见 SKILL.md 规则 9。\n\n```bash\nworkrally asset create --url --project-id -o json\n```\n\n返回：\n```json\n{\n \"id\": \"asset_abc123\",\n \"asset_details\": {\n \"url\": \"https://signed.url/...\",\n \"download_url\": \"https://signed.download.url/...\",\n \"width\": 1024,\n \"height\": 1024,\n \"format\": \"png\"\n }\n}\n```\n\n**重要返回值**：\n- `id` — 即 `asset_id`，后续所有操作都需要这个 ID\n- `asset_details` — 完整素材元数据，**步骤 3 必须完整传入**\n\n> ⚠️ `asset_details.url` 和 `asset_details.download_url` 为临时访问 URL，过期后需通过 `workrally asset get` 重新获取。获取到的 URL 可直接作为其他工具的 URL 参数传入。\n\n### 步骤 3: 挂载到资产库（按需）\n\n```bash\nworkrally material add --json-list '[{\n \"material_id\": \"\",\n \"material_name\": \"角色名_状态\",\n \"material_type\": 2,\n \"parent_id\": \"<目标位置的 material_id>\",\n \"material_detail\": <完整的 asset_details 对象>\n}]' --project-ids \n```\n\n**关键字段**（JSON 数组中每个对象）：\n- `material_id` — **必须**传 `asset_id`（步骤 2 返回的 `id`）\n- `material_detail` — **必须**传完整的 `asset_details`（步骤 2 返回的 `asset_details` 对象）\n- `material_type` — 素材类型：`2`=图片，`3`=视频，`4`=音频，`1`=文件夹\n- `parent_id` — 目标位置：`role_person`/`role_prop`/`role_scene` 或已有文件夹/状态的 `material_id`\n\n> ⚠️ 步骤 3 如果 JSON 中缺少 `material_id` 或 `material_detail`，素材不会在资产库列表中显示！\n\n---\n\n## 3. 判断需要几步\n\n| 用户意图 | 所需步骤 | 说明 |\n|----------|---------|------|\n| \"上传文件\" / \"上传图片\" | 步骤 1 → 2 | 入媒资库即可在 web 端查看 |\n| \"上传到角色/道具/场景\" | 步骤 1 → 2 → 3 | 还需挂载到资产库树形目录 |\n| \"上传到文件夹\" | 步骤 1 → 2 → 3 | 同上，parent_id 为文件夹的 material_id |\n| \"把媒资素材添加到资产库\" | 仅步骤 3 | 素材已在媒资库，只需挂载 |\n| \"在画布上放一张已有图\" | 无需上传 | 直接 `asset search` 找到 asset_id → `canvas build-draft` |\n| \"上传并放到画布上\" | 步骤 1 → 2 → `build-draft` | 入媒资库后用 build-draft 写入画布 |\n\n---\n\n## 4. 画布场景下的素材上传\n\n画布素材需要**同时关联项目和画布**：\n\n```bash\n# 步骤 1: 上传\nworkrally upload ./file.png -o json\n\n# 步骤 2: 入媒资库（必须传 project-id）\nworkrally asset create --url --project-id <项目ID> -o json\n\n# 步骤 3: 写入画布节点（使用返回的 asset_id）\nworkrally canvas build-draft <画布ID> --nodes '[\n {\"id\":\"node1\",\"type\":\"image\",\"position\":{\"x\":0,\"y\":0},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":512,\"height\":512}}\n]'\n```\n\n> 📌 项目 ID 通过 `workrally project list` 获取。用户未指定项目时，查找名为\"默认项目\"的项目。\n\n---\n\n## 5. 资产库目录操作\n\n### 查看各根目录下的内容\n\n```bash\n# 查看人物列表\nworkrally material list role_person -o json\n# 查看道具列表\nworkrally material list role_prop -o json\n# 查看场景列表\nworkrally material list role_scene -o json\n# 查看网盘文件夹列表\nworkrally material list root -o json\n```\n\n### 查看角色的状态列表\n\n```bash\n# parent-id 传角色的 material_id\nworkrally material list <角色的material_id> -o json\n```\n\n### 查看某状态下的素材文件\n\n```bash\n# parent-id 传状态的 material_id\nworkrally material list <状态的material_id> -o json\n```\n\n### 创建文件夹\n\n```bash\nworkrally material add --json-list '[{\"material_name\":\"新文件夹\",\"material_type\":1,\"parent_id\":\"role_person\"}]'\n```\n\n### 获取角色详情（含 LoRA/提示词）\n\n```bash\n# 注意：role get 需要 role_id，不是 material_id\n# material_id 格式如 \"abc_0\"，role_id 格式如 \"abc\"\n# 先通过 material get 获取 role_id\nworkrally material get -o json\n# 返回中有 role_id 字段，再查角色详情\nworkrally role get -o json\n```\n\n> ⚠️ `material_id`（如 \"abc_0\"，带 `_0` 后缀）≠ `role_id`（如 \"abc\"）。如果只有 `material_id`，先通过 `material get` 获取 `role_id`。\n\n---\n\n## 6. 素材 URL 访问说明\n\n| 素材类型 | 存储策略 | URL 行为 |\n|----------|---------|---------|\n| 图片 | **公开读** | `url` 可直接访问 |\n| 视频 | **私有读** | `url` 为临时访问地址，过期后需重新获取 |\n| 音频 | **私有读** | `url` 为临时访问地址，过期后需重新获取 |\n\n> 📎 媒资 API 返回的素材 URL 可直接作为其他工具的 URL 参数传入，**无需手动处理**。如遇\"非法或已过期\"提示，通过下列命令重新获取即可。\n\n过期后重新获取：\n```bash\nworkrally asset get -o json\n# 返回中的 url 和 download_url 为新的可访问地址\n```\n\n---\n\n## 7. 批量操作\n\n### 批量创建素材到资产库\n\n`material add` 支持 `--json-list` 参数传入 JSON 数组，一次添加多个素材：\n\n```bash\nworkrally material add --project-ids --source 1 --json-list '[\n {\"material_id\":\"asset_id_1\",\"material_name\":\"素材1\",\"material_type\":2,\"parent_id\":\"<状态ID>\",\"material_detail\":{...}},\n {\"material_id\":\"asset_id_2\",\"material_name\":\"素材2\",\"material_type\":3,\"parent_id\":\"<状态ID>\",\"material_detail\":{...}}\n]'\n```\n\n### 批量获取素材详情\n\n```bash\nworkrally asset get -o json\n# 最多 50 个 ID\n```\n\n### 搜索媒资库\n\n```bash\nworkrally asset search --project-id -o json\n# 可选筛选: --keyword \"关键词\" --type image/video/audio\n```\n\nFile v2.10.1:skill-card.md\n\n## Description:\n\nHelps agents create AI-generated images, video, audio, and 3D assets and manage WorkRally projects, shots, materials, and collaborative canvases.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tencent-adm](https://clawhub.ai/user/tencent-adm)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nCreators and developers use this skill to guide an agent through media generation, production planning, file uploads, and asset and canvas management in WorkRally.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Account credentials grant access to WorkRally content.\n\nMitigation: Install the WorkRally CLI only if trusted, use a scoped API key where possible, and protect the credentials directory.\n\nRisk: Uploading local files shares their contents with a remote service.\n\nMitigation: Obtain explicit user confirmation before uploading files.\n\nRisk: Deleting materials or overwriting shared canvases can affect collaborators.\n\nMitigation: Obtain explicit user confirmation before deleting, clearing, or overwriting remote content.\n\n## Reference(s):\n\n- [WorkRally on ClawHub](https://clawhub.ai/tencent-adm/skills/workrally)\n- [WorkRally](https://workrally.qq.com)\n- [AI generation guide](references/ai-generation-guide.md)\n- [Shotlist guide](references/shotlist-guide.md)\n- [Canvas guide](references/canvas-guide.md)\n- [Upload and assets guide](references/upload-and-assets-guide.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, JSON, Media asset links]\n\n**Output Format:** [Markdown guidance with CLI commands and JSON examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Generated media and edited projects reside in the user's WorkRally account.]\n\n## Skill Version(s):\n\n2.10.1 (source: ClawHub release and skill frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.10.1:LICENSE.txt\n\nTencent is pleased to support the open source community by making workrally available. \n\nCopyright (C) 2026 Tencent. All rights reserved. \n\nworkrally is licensed under the MIT-0.\n\n\nTerms of the MIT-0:\n--------------------------------------------------------------------\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nArchive v2.9.0: 10 files, 33342 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1616b), references/ai-generation-guide.md (16509b), references/canvas-guide.md (10823b), references/common-pitfalls.md (8590b), references/shotlist-guide.md (11094b), references/upload-and-assets-guide.md (7895b), skill-card.md (2979b), SKILL.md (19030b), _meta.json (128b)\n\nFile v2.9.0:SKILL.md\n\n---\nname: workrally\nslug: workrally\ndisplayName: WorkRally\ndisplay_name: WorkRally\ndisplay_name_en: WorkRally\ndescription: WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with WorkRally platform via command line.\ndescription_zh: 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集，支持 AI 生图/生视频/生音频、项目剧集场次管理、资产库与无限画布。\ndescription_en: End-to-end AIGC comic-drama creation toolkit for AI Agents—image/video/audio generation, project/series/shot management, asset library, and infinite canvas.\nversion: 2.9.0\nlicense: MIT-0\nauthor: WorkRally Team\nhomepage: https://workrally.qq.com\nuser-invocable: true\nmetadata: {\"openclaw\":{\"emoji\":\"🎬\",\"requires\":{\"bins\":[\"workrally\"],\"env\":[\"WORKRALLY_API_KEY\",\"WORKRALLY_ENDPOINT\",\"WORKRALLY_CONFIG_DIR\",\"WORKRALLY_NO_UPDATE_CHECK\"]},\"primaryEnv\":\"WORKRALLY_API_KEY\",\"credentials\":{\"storage\":\"~/.workrally/config.json\",\"configDirEnv\":\"WORKRALLY_CONFIG_DIR\",\"description\":\"workrally auth login 写入的 API Key 持久化文件，JSON 格式，仅存储 api_key 和 endpoint。非持久化容器中可通过 WORKRALLY_CONFIG_DIR 环境变量指定配置目录\"},\"install\":[{\"id\":\"npm\",\"kind\":\"node\",\"package\":\"workrally\",\"bins\":[\"workrally\"],\"label\":\"Install WorkRally CLI (npm)\"}],\"category\":\"AIGC\",\"tags\":[\"workrally\",\"aigc\",\"cli\",\"video-generation\",\"image-generation\",\"ai-tools\",\"story\",\"shot\",\"series\"]}}\n---\n\n# WorkRally CLI (workrally)\n\n面向 AI Agent 的 AIGC 漫剧视频创作全流程命令行工具，封装 WorkRally 平台 30+ 核心能力，支持项目/剧集/场次的完整 CRUD、AI 生图/生视频、画布、资产库、媒资管理、文件上传等。\n\n## 安装 & 配置\n\n```bash\nnpm install -g workrally\n\n# 配置 API Key（三选一）\nworkrally auth login # 交互式登录（推荐）\nworkrally auth login --token # 命令行传入\nexport WORKRALLY_API_KEY= # 环境变量（仅推荐 CI/CD，Agent/子进程可能读不到 shell 配置）\n# ↑ auth login 自动将 Token 写入配置文件：\n# 若 WORKRALLY_CONFIG_DIR 已设置 → $WORKRALLY_CONFIG_DIR/config.json\n# 否则 → ~/.workrally/config.json\n\nworkrally auth status # 验证登录状态\n```\n\nAPI Key 申请：[龙虾配置](https://workrally.qq.com/open-api)\n\n## 命令速查\n\n```bash\n# === 项目（project）— list / get / create / update / delete ===\nworkrally project list [--search \"关键词\"] # 列出/搜索项目\nworkrally project get # 项目详情\nworkrally project create \"项目名\" # 创建项目\nworkrally project update --name \"新名称\" # 更新项目\nworkrally project delete # 软删除（→回收站；恢复请到 Web）\n\n# === 剧集（series）— 全新命令组（CRUD 完整） ===\nworkrally series list --project-id # 剧集列表\nworkrally series get --project-id # 剧集详情\nworkrally series create --project-id --name \"第一集\" # 创建剧集\nworkrally series update --project-id --name \"新名称\" # 更新剧集\nworkrally series delete # 软删除（→回收站）\n\n# === 场次（shotlist）— 对齐 Web /shot 批量制作（含音频生成）===\n# --- CRUD ---\nworkrally shotlist list --series-id # 场次列表\nworkrally shotlist get # 场次详情\nworkrally shotlist create --series-id --json-list '[{\"image_prompt\":\"...\"}]' # 批量创建\nworkrally shotlist update --image-prompt \"...\" --animation-prompt \"...\" # 单条更新\nworkrally shotlist update --batch '[{\"story_id\":\"...\",\"image_prompt\":\"...\"}]' # 批量更新\nworkrally shotlist delete # 软删除（→回收站）\nworkrally shotlist sort --series-id --order id1,id2,id3 # 重排\n# --- 模型 & 配置（写入 extra.gen_config）---\nworkrally shotlist models --category image,video,videoSmartEdit,upscale,audio # ⭐ 统一模型列表\nworkrally shotlist set-model [--story-ids id1,id2] --image-model --image-aspect-ratio 16:9 [--image-quality high] [--mj-params '{}']\nworkrally shotlist set-model [--story-ids id1,id2] --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9\nworkrally shotlist set-model [--story-ids id1,id2] --extra-mode extendVideo --extend-source-id --duration 4 # 延长视频\nworkrally shotlist set-model [--story-ids id1,id2] --audio-model [--audio-config '{}'] # 配置音频\nworkrally shotlist bind --story-id --type audio --file ./voice.wav --project-id # 本地素材：上传→入库→绑定\nworkrally shotlist bind --story-id --type image --assets '[{...}]' # 已入库素材绑定（audio→独立字段）\nworkrally shotlist recognize --series-id --project-id [--scope both] [--match-rule symbol_text] # 识别（含音频路）\n# --- 生成（仅提交；查结果用 get-result [--watch]）---\nworkrally shotlist generate-image --project-id --story-ids id1,id2 [--count N] # 生图 → get-result --type image\nworkrally shotlist generate-video --project-id --story-ids id1,id2 # 生视频 → get-result --type video\nworkrally shotlist upscale-video --project-id --story-ids id1,id2 --model # 已选视频超分\nworkrally shotlist generate-audio --project-id --story-ids id1,id2 [--count N] # ⭐ 生音频 → get-result --type audio\nworkrally shotlist get-result --story-id --type image|video|audio [--watch] # 查进度与产物\n\n# === 上传 / 下载 ===\nworkrally upload ./file.png -o json # 上传文件 (COS SDK 直传)\nworkrally download [-d ./output/] # 下载素材 (自动处理访问凭证)\n\n# === AI 生图 ===\nworkrally generate image-models # 查看可用模型（必须先调用！）\nworkrally generate image --prompt \"描述\" --model [--aspect-ratio 16:9] [--resolution 5] [--quality high] [--input-images \"url\"] --poll\n# --resolution 推荐用 image-models 的 resolution_options[].value（常见 4=1080P/5=1440P/6=2160P）；旧档位 0/1/2 仍可用\n# --quality 仅当 image-models 该模型返回了 infer_quality_options 时才传（取值用其中的 value）\n# --extra-params '{\"midjourney\":{\"stylize\":100}}' 扩展参数 JSON 对象；CLI 传 extraParams，服务端写成 extra_params\n\n# === AI 生视频 (6 种驱动模式) ===\nworkrally generate video-models # 查看可用模型（必须先调用！）\nworkrally generate video --prompt \"描述\" --model --poll # 纯文生视频（默认 Text 模式）\nworkrally generate video --prompt \"描述\" --model --single-image-url \"url\" --poll # 图生视频（Text 模式 + 参考图）\nworkrally generate video --mode FirstLastFrame --prompt \"描述\" --model --first-frame-url \"url\" --poll # 首尾帧\nworkrally generate video --mode VideoEdit --prompt \"描述\" --model --origin-video --poll # 视频编辑\n# 其他模式: SubjectToVideo(--reference-assets)\nworkrally generate video --mode SmartEdit --model --source-video --source-width 1920 --source-height 1080 --source-duration 5000 --poll\nworkrally generate video --mode ExtendVideo --model --source-video --duration 8 --poll\n# SubjectToVideo 的 --reference-assets 支持 file 文档（Wan 3.0）：{\"type\":\"file\",\"asset_id\":\"...\",\"name\":\"brief.pdf\"}\n# --mode 默认 Text；通用选项: --aspect-ratio <比例> --resolution <枚举> --duration <秒> --count 1-4 --poll\n# 音效默认开启（与前端一致）；关闭用 --no-enable-sound。VideoEdit 不要传音效相关参数\n# --aspect-ratio 默认 16:9；--resolution 不传取模型首个可用(枚举见 video-models 的 resolution_options)\n\n# === 画布生音频 / 音乐（对齐 Web 画布音频生成器）===\nworkrally generate audio-models # 查看 audio_models / music_models（必须先调用！）\nworkrally generate audio --prompt \"雨声和脚步\" --model --poll\nworkrally generate music --prompt \"摇滚吉他\" --model --lyrics-mode none --poll\nworkrally generate music --prompt \"流行\" --model --lyrics-mode input --lyrics \"啦啦啦\" --poll\n# MiniMax 音频模型不要传 --ref-audios；动态音色参数从模型 fields 获取后用 --audio-fields JSON 传入\n\n# === 混元 3D 模型（对齐 Web 关键帧混元3D，不是世界生成/贴图）===\nworkrally generate 3d --asset-id <参考图asset_id> --poll\n# 须先 asset search / asset create 得到 asset_id；模型固定 hunyuan-3d-v3.0\n# ⚠️ --project-id 是短番项目ID，不是画布ID\n\n# === 视频提示词优化（gen_content，产物是文本不是视频）===\nworkrally generate content-models # 查看可用模型（必须先调用！严禁硬编码 MiniMax H3 等 ID）\nworkrally generate optimize-prompt --prompt \"将视频从尾帧延长5秒\" --model \\\n [--video-url ] [--first-frame-url ] [--last-frame-url ] \\\n [--reference-image-urls \"url1,url2\"] [--audio-url ] [--audio-urls \"a.mp3,b.mp3\"] --poll\n# 图片语义写在 image_info.type：first_frame / last_frame / reference_image；音频写在 audio_info.url（type=3）\n# 成功后从 generate task 的 output_text 读取优化后的提示词（output_type=\"text\"），不要找 output_assets\n\n# === 媒资库 (asset) — 项目级媒体文件池 ===\nworkrally asset create --url --project-id -o json # 入库（返回可访问 URL）\nworkrally asset search --project-id [--type image] [--audit-status 5] [--auth-status 1]\nworkrally asset get # 详情\nworkrally asset update --name \"新名称\" # 更新素材 (目前仅支持改名)\n\n# === 资产库 (material) — 树形管理：人物/道具/场景/网盘 ===\nworkrally material list role_person # 人物 | role_prop 道具 | role_scene 场景 | root 网盘文件夹\nworkrally material add ... # 创建素材/文件夹（从媒资库挂载）\nworkrally material get # 素材详情\nworkrally material delete # 删除（不可恢复，须用户确认）\nworkrally role get # 角色详情（LoRA/提示词/版本）\n\n# === 画布 ===\nworkrally canvas list # 列出画布\nworkrally canvas create \"名称\" # 创建画布\nworkrally canvas build-draft --file nodes.json # 增量合并（默认保留已有节点）\nworkrally canvas build-draft --nodes '[...]' # 同上，直接传 JSON\nworkrally canvas build-draft -d \"id1,id2\" # 删除指定节点\nworkrally canvas build-draft -n '[...]' -d \"old1\" # 同时增删改\nworkrally canvas build-draft -n '[...]' --mode overwrite # 全量覆盖（清空后重建）\n\n# === 任务查询 ===\nworkrally generate task [--poll] # 查询/轮询生成任务状态\n# 生图/生视频成功：output_type=\"assets\"，产物在 output_assets\n# 提示词优化成功：output_type=\"text\"，产物在 output_text（不要找 output_assets / output_products）\n\n# === 通用（仅查看白名单，禁止透传调用）===\nworkrally tools list # 列出核心白名单工具\nworkrally tools describe # 查看参数 schema\n# 不要使用 tools call；未列出的 MCP 工具已禁止调用。关键帧/配音/动效请用 Web。\n\n# === URL / 升级 ===\nworkrally url build \"页面名\" [--params '{}'] # 构建 WorkRally 前端链接\nworkrally url parse # 解析 URL\nworkrally upgrade [--check] # 升级 / 仅检查\n```\n\n输出格式: `-o json`(默认, Agent 推荐) | `-o table`(人类阅读) | `-o text`(管道/脚本) | `workrally config set output_format `\n\n## 关键工作流：上传文件\n\n**概念**：媒资库(asset) = 项目级文件池；资产库(material) = 树形目录(人物/道具/场景/网盘文件夹)。资产库的素材只能从媒资库挂载。\n\n```bash\n# 步骤 1: 上传 → CDN URL\nworkrally upload ./character.png -o json\n# 步骤 2: 入媒资库（必须！返回 asset_id + asset_details）\nworkrally asset create --url --project-id -o json\n# 步骤 3（按需）: 挂载到资产库（必传 asset_id + 完整 asset_details）\nworkrally material add --json-list '[{\"material_id\":\"\",\"material_name\":\"名称\",\"material_type\":2,\"parent_id\":\"\",\"material_detail\":}]' \\\n --project-ids \n```\n\n> **步骤 1→2 强制绑定**，上传后必须入媒资库。视频/音频为私有读，需经媒资库才能正常访问。\n>\n> **步骤 3 由 Agent 判断**：\"上传文件\" → 两步 | \"上传到角色/道具/场景/文件夹\" → 三步 | \"媒资素材添加到资产库\" → 仅步骤 3\n\n## 关键工作流：场次创作（`shotlist`，对齐 Web /shot）\n\n**概念层级**：项目 (project) → 剧集 (series) → 场次 (shot/story)。一个场次含 图片 / 视频 / **音频** 三条生成线，核心由提示词承载：`image_prompt`（图片）、`animation_prompt`（视频）、`extra.audio_prompt`（音频，音色用 `<音色名>` 引用）。生成配置聚合在 `extra.gen_config.{image,video,audio}`。\n\n```bash\n# 1) 建剧集 + 批量创建场次（按用户意图填提示词）\nworkrally series create --project-id --name \"第一集\" -o json\nworkrally shotlist create --series-id --json-list '[{\"image_prompt\":\"古风庭院\",\"animation_prompt\":\"镜头缓推\"}]'\n\n# 2) 识别角色资产（三路：image/animation/audio；音色用 <> 时加 --match-rule symbol_text）\nworkrally shotlist recognize --series-id --project-id \n\n# 3) 选模型 → 写配置（模型 id 来自 shotlist models，勿硬编码）\nworkrally shotlist models --category image,video,audio -o json\nworkrally shotlist set-model --series-id --image-model --image-aspect-ratio 16:9 \\\n --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9 --audio-model \n\n# 4) 生成（多场次传 --story-ids id1,id2,id3；均需 --project-id）\nworkrally shotlist generate-image --project-id --story-ids \nworkrally shotlist generate-video --project-id --story-ids \nworkrally shotlist generate-audio --project-id --story-ids \n\n# 5) 查结果（image/video/audio 三条独立进度，分别 watch）\nworkrally shotlist get-result --story-id --type image --watch\nworkrally shotlist get-result --story-id --type video --watch\nworkrally shotlist get-result --story-id --type audio --watch\n```\n\n> **生成前先确认配置**：用 `shotlist get ` 检查 `extra.gen_config` 是否已设对应模型；缺则回到步骤 3。生成只返回提交结果，不返回可轮询的画布 task_id，进度一律用 `shotlist get-result`。\n\n## ⚠️ 重要规则\n\n1. **前端链接必须用 `workrally url build` 生成**，严禁自行拼接 URL\n2. **模型 ID 必须动态获取**：`image-models` / `video-models` / `audio-models` / `content-models`，严禁猜测或硬编码。场次批量制作使用 `shotlist models`；音频模型返回的 `capabilities/fields/restrictions` 也应一并用于配置。混元 3D 固定 hunyuan-3d-v3.0，只需 `--asset-id`\n3. **`canvas` ≠ `project`**：画布用 `canvas`，项目用 `project`，两者 ID 不能互换\n4. **`build-draft` 实时协同**：写入后所有在线用户立即看到变更，默认增量合并（只传变更节点），支持多人并发安全操作\n5. **`build-draft` 节点校验**：8种节点类型各有必填字段，详见 [`canvas-guide.md`](references/canvas-guide.md)\n6. **AI 生成自动占位**：`generate image/video` 传入 `--project-id`（画布ID）后自动在画布创建占位节点，**无需**再手动 `build-draft`\n7. **素材命名**：`--name` 传入\"画布名_素材特征\"（画布场景）或 prompt 关键词（非画布场景）\n8. **不确定参数时**用 `--help` 或 `tools describe` 自行探索\n9. **URL 白名单**：所有 URL 类参数（生图/生视频的 `--*-url` / `--*-assets` / `--*-images`、`asset create --url` 等）仅接受 WorkRally 官方媒资 URL。合法来源：① `workrally upload` 返回值 ② `asset get/search` 返回值（可直接传入） ③ 用户已提供的官方 URL。本地文件或第三方 URL 必须先 `workrally upload`。如遇\"非法或已过期\"提示，通过 `asset get/search` 重新获取即可。\n\n## 📚 深度指南 (references/)\n\n本 Skill 附带详细参考文档，覆盖复杂工作流：\n\n| 文档 | 内容 |\n|------|------|\n| [`references/shotlist-guide.md`](references/shotlist-guide.md) | ⭐ **场次批量制作**（对齐 Web `/shot`）— CRUD、gen_config、生图/生视频/**生音频**、结果查询、符号识别 |\n| [`references/canvas-guide.md`](references/canvas-guide.md) | 无限画布操作 — 8种节点类型、画板嵌套、build-draft 增量/覆盖模式、协同编辑 |\n| [`references/upload-and-assets-guide.md`](references/upload-and-assets-guide.md) | 上传与素材管理 — 三步上传流程、媒资库 vs 资产库、树形目录操作 |\n| [`references/ai-generation-guide.md`](references/ai-generation-guide.md) | AI 生成 — Kontext 生图、4种视频驱动模式、画布音频/音乐、混元 3D 模型、提示词优化、模型动态获取、任务轮询 |\n| [`references/common-pitfalls.md`](references/common-pitfalls.md) | 常见易错点 — 项目/画布混淆、模型硬编码、上传缺步骤等典型错误 |\n\n> 遇到画布、上传、AI生成相关的复杂操作时，请优先查阅对应的参考文档。\n\n## 环境变量\n\n- `WORKRALLY_API_KEY` — API Key (Bearer Token)\n- `WORKRALLY_ENDPOINT` — API 端点 (默认 `https://workrally.qq.com/zenstudio/api/mcp`)\n- `WORKRALLY_CONFIG_DIR` — 配置文件目录 (默认 `~/.workrally`，非持久化容器建议指向持久卷)\n- `WORKRALLY_NO_UPDATE_CHECK=1` — 禁用自动版本检查 (CI/CD 推荐)\n\nFile v2.9.0:README.md\n\n# WorkRally CLI — Agent Skill\n\n🎬 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。\n\n本目录是 WorkRally CLI 的 Agent Skill 定义。\n\n## 目录结构\n\n```\nskill/\n├── SKILL.md ← Skill 入口（元数据 + 指令），ClawHub 解析此文件\n├── LICENSE.txt ← 许可证\n└── references/ ← 深度参考文档，AI Agent 按需加载\n ├── ai-generation-guide.md AI 生成指南\n ├── canvas-guide.md 无限画布操作指南\n ├── common-pitfalls.md 常见易错点\n ├── shotlist-guide.md 场次批量制作（对齐 Web /shot）\n └── upload-and-assets-guide.md 上传与素材管理指南\n```\n\n## 核心能力\n\n- **AI 生图** — Kontext 模型，支持多参考图、可选推理质量\n- **AI 生视频** — 4 种驱动模式（文本/首尾帧/参考主体/视频编辑）\n- **提示词优化** — gen_content 文本任务，产物为 `output_text`\n- **无限画布** — Yjs 协同编辑，8 种节点类型，实时同步\n- **项目 & 媒资管理** — 项目 CRUD、素材上传入库、资产库树形管理\n- **通用透传** — 可调用 WorkRally MCP Server 全部工具\n\n## 第三方商店\n\n- [SkillHub](https://skillhub.cn/skills/workrally)\n- [ClawHub](https://clawhub.ai/tencent-adm/workrally)\n- [Skills](https://skills.sh/tencent/workrally/workrally)\n\n## 快速开始\n\n```bash\nnpm install -g workrally\nworkrally auth login\nworkrally auth status\n```\n\n详细用法、命令速查、工作流指南请参阅 **[SKILL.md](./SKILL.md)**。\n\nFile v2.9.0:_meta.json\n\n{\n \"ownerId\": \"kn77cw5hbmapf54rv89jdqwp7x835m4k\",\n \"slug\": \"workrally\",\n \"version\": \"2.9.0\",\n \"publishedAt\": 1788986001269\n}\n\nFile v2.9.0:references/ai-generation-guide.md\n\n# AI 生成指南（图片 / 视频 / 音频 / 音乐 / 3D）\n\n本文档帮助 AI Agent 正确使用 WorkRally 的 AI 图片、视频、音频、音乐与混元 3D 模型生成能力。\n\n---\n\n## 1. 核心规则\n\n> ⚠️ **模型 ID 必须动态获取，严禁猜测或硬编码！**\n> 模型列表是动态下发的，不同环境（开发/预发/正式）的可用模型可能完全不同。\n\n> 🔒 所有 URL 类参数仅接受 WorkRally 官方媒资 URL，详见 SKILL.md 规则 9。\n\n```bash\n# 生图前必须先获取模型列表\nworkrally generate image-models -o json\n\n# 生视频前必须先获取模型配置\nworkrally generate video-models -o json\n\n# 提示词优化前必须先获取 gen_content 模型列表\nworkrally generate content-models -o json\n\n# 画布生音频/音乐前必须先获取模型\nworkrally generate audio-models -o json\n```\n\n---\n\n## 2. 图片生成 (Kontext)\n\n### 2.1 获取可用模型\n\n```bash\nworkrally generate image-models -o json\n```\n\n返回包含：\n- `models[]` — 每个模型的 `model_id`、`name`、`resolution_options`、`kontext_config`、`infer_quality_options`\n- `aspect_ratios[]` — 全局可用宽高比列表（如 \"1:1\", \"16:9\", \"9:16\" 等）\n- `resolution_options[]` — 所有模型支持的 protobuf 分辨率并集（**推荐**，传给 `--resolution`）\n- `resolutions[]` — 旧档位 0/1/2 并集（兼容）\n- `count_options[]` — 可选的生成数量\n\n**关键字段**：\n- `model_id` → 传给 `--model` 参数\n- `kontext_config.max_input_images` → 该模型允许的最大参考图数量（不同模型不同，不要写死）\n- `resolution_options[]` → `{value, label}`，value 为 protobuf 枚举（常见 4=1080P、5=1440P、6=2160P）。**`generate image --resolution` 用这里的 value**\n- `kontext_config.support_resolutions` → 旧档位 0=1K / 1=2K / 2=4K（兼容已有脚本，新调用不要再用）\n- `infer_quality_options[]` → 推理质量选项（可能为空）。非空时才可传 `--quality=`（如 `high`/`medium`/`low`）；空列表时不要传 `--quality`\n\n### 2.2 纯文生图\n\n```bash\nworkrally generate image \\\n --prompt \"一只橘猫坐在樱花树下\" \\\n --model \\\n --aspect-ratio 16:9 \\\n --poll\n```\n\n### 2.3 参考图生图\n\n通过 `--input-images` 传入参考主体图片 URL，在 prompt 中用 \"第一张图片\"、\"第二张图片\" 引用：\n\n```bash\nworkrally generate image \\\n --prompt \"第一张图片趴在第二张图片路中间\" \\\n --model \\\n --input-images \"https://cat.png,https://shrine.png\" \\\n --poll\n```\n\n> 📌 `--input-images` 的最大数量取决于模型配置中的 `kontext_config.max_input_images`，不要写死。\n> 📌 **只允许图片类型的素材**作为参考图。\n\n### 2.4 在画布中生图\n\n```bash\nworkrally generate image \\\n --prompt \"描述\" \\\n --model \\\n --project-id <画布ID> \\\n --poll\n```\n\n传入 `--project-id`（画布 ID）后：\n- 系统会**自动**在画布中创建 running 状态的占位节点（橙色边框 + 进度条）\n- **无需**再手动调用 `build-draft` 放置生成器节点\n- 生成完成后，前端自动更新节点状态\n\n> ⚠️ `--project-id` 此处是**画布 ID**（通过 `canvas list` 获取），**不是项目 ID**！\n\n### 2.5 参数说明\n\n| 参数 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--prompt` | ✅ | — | 图片描述 |\n| `--model` | ✅ | — | 模型 ID（从 `image-models` 获取） |\n| `--aspect-ratio` | — | `16:9` | 宽高比 |\n| `--resolution` | — | 模型首个可用 | **推荐** protobuf 枚举，取值来自 `image-models` 的 `resolution_options[].value`（常见 4=1080P、5=1440P、6=2160P）。兼容旧档位 0=1K、1=2K、2=4K。⚠️ 生图的 1/2 仍是 2K/4K，不是视频的 480P/540P |\n| `--quality` | — | 不下发 | 推理质量。取值必须来自该模型 `infer_quality_options[].value`；列表为空时不要传 |\n| `--count` | — | `1` | 生成数量 1-4（后端一个任务生成 1 张，count>1 会并发发起 N 个独立任务并返回 task_ids 数组） |\n| `--input-images` | — | — | 参考图 URL（逗号分隔） |\n| `--project-id` | — | — | 画布 ID（传入后自动创建占位节点） |\n| `--short-series-project-id` | — | — | 项目 ID |\n| `--name` | — | — | 素材名称 |\n| `--extra-params` | — | — | JSON 对象。CLI 传 MCP `extraParams`；服务端写入 `graph_input.extra_params` 且将每个 value 序列化为字符串。例如 MJ：`'{\"midjourney\":{\"stylize\":100}}'`。不要在 CLI 侧再 stringify 一层 |\n| `--poll` | — | false | 自动轮询直到完成 |\n| `--poll-interval` | — | `3` | 轮询间隔（秒） |\n\n---\n\n## 3. 视频生成\n\n### 3.1 获取可用模型配置\n\n```bash\nworkrally generate video-models -o json\n```\n\n返回按**驱动模式**分组：\n- `text_providers[]` — Text（单图/纯文）模式\n- `first_last_frame_providers[]` — 首尾帧模式\n- `subject_to_video_providers[]` — 参考主体模式\n- `video_edit_providers[]` — 视频编辑模式（VideoEdit）\n- `smart_edit_providers[]` — 智能编辑模式（SmartEdit）\n\n参考主体模型还可能返回 `extend_duration_range`、`extend_video_max_duration`、文档限制与 `support_erase_subtitles`；只在配置明确支持时使用。\n\n每个模型包含：\n- `provider` → 传给 `--model` 参数\n- `label` — 模型显示名称\n- `duration_options[]` — 可用时长列表（秒）\n- `resolution_options[]` — 支持的分辨率列表（`{value, label}`，value 为 protobuf 枚举值），传给 `--resolution`\n- `can_upload_image/video/audio` — 支持的输入类型\n- `max_image_count/video_count/audio_count` — 各类型最大数量\n- `support_audio` — 是否支持音效\n\n### 3.2 四种驱动模式\n\n#### Text 模式（默认）— 纯文生视频 / 单图驱动\n\n```bash\n# 纯文生视频（不传图片）\nworkrally generate video \\\n --prompt \"夕阳下海浪拍打沙滩\" \\\n --model \\\n --poll\n\n# 图生视频（传入参考图）\nworkrally generate video \\\n --prompt \"图片中的角色缓缓转身\" \\\n --model \\\n --single-image-url \"https://example.com/character.png\" \\\n --poll\n```\n\n#### FirstLastFrame 模式 — 首尾帧驱动\n\n```bash\nworkrally generate video \\\n --mode FirstLastFrame \\\n --prompt \"角色从左走到右\" \\\n --model \\\n --first-frame-url \"https://example.com/start.png\" \\\n --last-frame-url \"https://example.com/end.png\" \\\n --poll\n```\n\n> 可以只传首帧或只传尾帧（至少一个）。\n\n#### VideoEdit 模式 — 视频编辑\n\n`model` 必须来自 `video-models` 的 `video_edit_providers[]`。必须传 `--origin-video <原视频素材ID>`（asset_id，不是 URL）。此模式 **不要** 传 `--enable-sound` / `--no-enable-sound`（下游 graph_input 不带该字段）。\n\n```bash\nworkrally generate video \\\n --mode VideoEdit \\\n --prompt \"将背景替换成蓝天\" \\\n --model \\\n --origin-video \\\n --poll\n```\n\n#### SubjectToVideo 模式 — 参考主体驱动\n\n```bash\nworkrally generate video \\\n --mode SubjectToVideo \\\n --prompt \"角色在场景中行走\" \\\n --model \\\n --reference-assets '[{\"type\":\"image\",\"url\":\"https://character.png\"},{\"type\":\"video\",\"url\":\"https://bg.mp4\"}]' \\\n --poll\n```\n\n### 3.3 通用选项\n\n| 参数 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--prompt` | 通常必填 | — | SmartEdit/ExtendVideo 可省略 |\n| `--model` | ✅ | — | Provider ID（从 `video-models` 获取） |\n| `--mode` | — | `Text` | Text/FirstLastFrame/SubjectToVideo/VideoEdit/SmartEdit/ExtendVideo |\n| `--aspect-ratio` | — | `16:9` | 宽高比: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 等 |\n| `--resolution` | — | 模型首个可用 | 分辨率枚举: 1=480P 2=540P 3=720P 4=1080P 5=1440P 6=2160P 7=4320P 8=360P（具体支持见 `video-models` 的 `resolution_options`） |\n| `--duration` | — | — | 视频时长（秒），可选值取决于模型 |\n| `--count` | — | `1` | 生成数量 1-4（后端一个任务生成 1 个视频，count>1 会并发发起 N 个独立任务并返回 task_ids 数组） |\n| `--enable-sound` | — | 服务端默认 true | 生成音效（仅部分模型支持）。**不传则默认开启**（与前端一致）；关闭请用 `--no-enable-sound`。VideoEdit 不要传 |\n\nSmartEdit 需传 `--source-video/--source-width/--source-height/--source-duration`；`source-duration` 单位毫秒。ExtendVideo 的 `--duration` 表示延长秒数。Wan 3.0 文档参考仅 SubjectToVideo 支持，`--reference-assets` 中传 `{\"type\":\"file\",\"asset_id\":\"...\",\"name\":\"brief.pdf\"}`。\n| `--no-enable-sound` | — | — | 显式关闭音效（`enable_sound=false`） |\n| `--extra-params` | — | — | JSON 对象。CLI 传 MCP `extraParams`；服务端写入 `graph_input.extra_params` 且将每个 value 序列化为字符串 |\n| `--project-id` | — | — | 画布 ID（传入后自动创建占位节点） |\n| `--short-series-project-id` | — | — | 项目 ID |\n| `--name` | — | — | 素材名称 |\n| `--poll` | — | false | 自动轮询直到完成 |\n| `--poll-interval` | — | `5` | 轮询间隔（秒） |\n\n### 3.4 在画布中生视频\n\n与生图类似，传入 `--project-id`（画布 ID）即可自动创建占位：\n\n```bash\nworkrally generate video \\\n --prompt \"海浪翻涌\" \\\n --model \\\n --project-id <画布ID> \\\n --poll\n```\n\n---\n\n## 3.5 画布音频 / 音乐\n\n对齐 Web 无限画布「生成音频」：`mode=audio`（台词/音效）或 `music`（文生音乐）。\n\n```bash\nworkrally generate audio-models -o json\n# 返回 audio_models[] / music_models[]，is_minimax=true 的音频模型不要传 --ref-audios\n\n# 音频\nworkrally generate audio --prompt \"雨声和脚步\" --model --poll\n\n# MiniMax：先读取 audio_models[].fields，再传动态字段\nworkrally generate audio --prompt \"你好\" --model \\\n --audio-fields '{\"voice\":\"voice_id\",\"audio_speech_rate\":1.1}' --poll\n\n# 纯器乐\nworkrally generate music --prompt \"摇滚吉他\" --model --lyrics-mode none --poll\n\n# 传入歌词\nworkrally generate music --prompt \"流行\" --model --lyrics-mode input --lyrics \"啦啦啦\" --poll\n```\n\n传入 `--project-id`（画布 ID）时自动创建 audio 占位节点。场次批量配音请用 `shotlist generate-audio`，不要与画布音频混淆。\n\n---\n\n## 3.6 混元 3D 模型生成\n\n对齐 Web 关键帧结果里的混元 3D（`usePose` / `hunyuan3d`）。**不是** 3D 世界，也不是模型贴图。输入是已入库参考图 `asset_id`，模型固定 `hunyuan-3d-v3.0`。\n\n```bash\nworkrally asset search --project-id --type image -o json\nworkrally generate 3d --asset-id --poll\n```\n\n成功后用 `generate task` 读 `output_assets` / `output_products`（网格模型 URL）。`--project-id` 是短番项目 ID。\n\n---\n\n## 4. 视频提示词优化（gen_content）\n\n用于视频延长/编辑前，把自然语言指令 + 可选参考视频/图片交给模型，生成适合下游视频生成的结构化提示词（如 `subject_definitions`）。\n\n> ⚠️ 这是**异步文本任务**，不是生视频。成功后读 `output_text`，**不会**返回 `output_assets`。\n> ⚠️ **model 必须来自 `generate content-models`**，严禁硬编码 MiniMax H3 等 ID。\n\n```bash\n# 1. 获取模型\nworkrally generate content-models -o json\n\n# 2. 提交优化（建议 --poll）\nworkrally generate optimize-prompt \\\n --prompt \"将视频从尾帧延长5秒\" \\\n --model \\\n --video-url <参考视频CDN_URL> \\\n --first-frame-url <首帧CDN_URL> \\\n --last-frame-url <尾帧CDN_URL> \\\n --reference-image-urls \"<参考图1>,<参考图2>\" \\\n --audio-url <参考音频CDN_URL> \\\n --poll\n```\n\n媒体写入 `messages[0].contents`，**不是**生视频那套 `ref_images` / `frames`。图片语义在 `image_info.type`，音频在 `audio_info.url`：\n\n| CLI | graph_input |\n|-----|-------------|\n| `--video-url` | `contents.type=2` + `video_info.url` |\n| `--first-frame-url` | `contents.type=1` + `image_info.type=\"first_frame\"` |\n| `--last-frame-url` | `contents.type=1` + `image_info.type=\"last_frame\"` |\n| `--reference-image-urls` | 每张 `contents.type=1` + `image_info.type=\"reference_image\"` |\n| `--image-url` | 兼容旧参数，等价于一张 `reference_image` |\n| `--audio-url` / `--audio-urls` | 每条 `contents.type=3` + `audio_info.url` |\n\ncontents 顺序：文本 → 视频 → 首帧 → 尾帧 → 参考图 → 音频。\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--prompt` | ✅ | 待优化的自然语言指令 |\n| `--model` | ✅ | 来自 `content-models` 的 `model_id` |\n| `--video-url` | — | 参考视频 CDN URL（官方媒资） |\n| `--first-frame-url` | — | 首帧图片 CDN URL |\n| `--last-frame-url` | — | 尾帧图片 CDN URL |\n| `--reference-image-urls` | — | 参考图 CDN URL，逗号分隔，可多张 |\n| `--image-url` | — | 单张参考图（兼容旧参数） |\n| `--audio-url` | — | 参考音频 CDN URL |\n| `--audio-urls` | — | 参考音频 CDN URL，逗号分隔，可多条 |\n| `--aspect-ratio` | — | 如 `16:9`（写入比例分量，不是像素） |\n| `--resolution` | — | **protobuf 枚举**（1=480P…），与 `generate image/video` 相同。生图另兼容旧档位 0/1/2 |\n| `--duration` | — | 目标时长秒数，不传服务端默认 5 |\n| `--temperature` | — | 采样温度（可选） |\n| `--seed` | — | 随机种子（可选） |\n| `--extra-params` | — | 扩展参数 JSON 对象 |\n| `--short-series-project-id` | — | 短番项目 ID |\n| `--name` | — | 任务名称 |\n| `--poll` | — | 完成后从结果读取 `output_text` |\n\n与 `polishing_prompt` / `generate_animation_prompt` 的区别：本命令走 TaskGateway `gen_content`，面向视频模型，产物为文本。\n\n---\n\n## 5. 任务轮询\n\n### 5.1 使用 --poll 自动轮询（推荐）\n\n```bash\nworkrally generate image --prompt \"...\" --model --poll\n```\n\n使用 `--poll` 后，CLI 自动：\n1. 提交生成任务\n2. 每隔 N 秒查询状态（默认3秒/图片，5秒/视频）\n3. 显示进度条和状态（排队中/运行中/成功/失败）\n4. 完成后输出最终结果\n\n### 5.2 手动查询任务\n\n```bash\n# 单次查询\nworkrally generate task -o json\n\n# 手动轮询\nworkrally generate task --poll\n```\n\n### 5.3 任务状态\n\n| state | 含义 | 说明 |\n|-------|------|------|\n| 1 | 排队中 (QUEUED) | 等待资源 |\n| 2 | 运行中 (RUNNING) | 正在生成 |\n| 3 | 暂停 (PAUSED) | 暂停中 |\n| 4 | 成功 (SUCCESS) | 媒资任务看 `output_assets`（`output_type=\"assets\"`）；文本任务（optimize-prompt）看 `output_text`（`output_type=\"text\"`）。不要找已废弃的 `output_products` |\n| 5 | 失败 (FAILED) | `error_message` 包含错误信息 |\n| 6 | 已取消 (CANCELLED) | 用户取消 |\n\n### 5.4 多任务并发\n\n后端「一个任务只生成 1 个素材」，当 `--count` > 1 时，CLI 会并发发起 N 个独立任务，返回的 `task_ids` 是长度为 N 的数组，每个 task 产出 1 个素材。使用 `--poll` 时 CLI 会自动并发轮询所有任务，总耗时约等于单任务耗时。\n\n---\n\n## 6. 素材命名最佳实践\n\n### 画布内生成\n\n使用 `--name` 传入\"画布名称_素材特征\"：\n```bash\n# 先获取画布名称\nworkrally canvas get -o json\n# 生成时传入有意义的名称\nworkrally generate image --prompt \"蓝色运动鞋\" --model --project-id \\\n --name \"产品设计画布_蓝色运动鞋\" --poll\n```\n\n### 非画布生成\n\n从 prompt 中提取核心关键词作为名称：\n```bash\nworkrally generate image --prompt \"一只可爱的橘猫在夕阳下奔跑\" --model \\\n --name \"橘猫_夕阳奔跑\" --poll\n```\n\n---\n\n## 7. 生成后素材处理\n\nAI 生成的图片/视频会**自动入库到媒资系统**（后台自动完成，无需额外调用 `asset create`）。\n\n### 如果需要上传到资产库\n\n```bash\n# 1. 生成完成后，从结果中获取 asset_id\n# 2. 获取 asset_details\nworkrally asset get -o json\n# 3. 挂载到资产库\nworkrally material add --json-list '[{\"material_id\":\"\",\"material_name\":\"角色名\",\"material_type\":2,\"parent_id\":\"\",\"material_detail\":}]' \\\n --project-ids \n```\n\n### 如果需要在画布上展示\n\n传入 `--project-id` 即可，系统自动处理。无需手动调用 `build-draft`。\n\nFile v2.9.0:references/canvas-guide.md\n\n# 无限画布操作指南\n\n本文档帮助 AI Agent 正确操作 WorkRally 无限画布（Infinite Canvas）。画布基于 Yjs 协同编辑引擎，CLI 写入的内容会**实时同步**给所有在线用户，无需刷新页面。\n\n---\n\n## 1. 核心概念\n\n### 两种\"项目\"（容易混淆，务必区分）\n\n| 概念 | 管理命令 | 用途 | 必要性 |\n|------|---------|------|--------|\n| **项目** (project) | `workrally project list/create/get` | 所有素材都必须归属一个项目，范围更大 | **必须** — 素材不关联项目则在 web 端不可见 |\n| **画布** (canvas) | `workrally canvas list/create/get` | 无限画布空间，可在其中排布节点 | **可选** — 仅当用户要在画布中操作时才需要 |\n\n> ⚠️ **两者的 ID 不能互相替代！**\n> - `workrally project list` 返回的是项目 ID\n> - `workrally canvas list` 返回的是画布 ID\n> - 在画布场景下，素材需要**同时关联两者**\n\n### 判断用户意图\n\n| 用户说 | 含义 | 使用命令 |\n|--------|------|---------|\n| \"我的项目\"、\"项目列表\" | 项目 | `workrally project list` |\n| \"我的画布\"、\"画布列表\" | 无限画布 | `workrally canvas list` |\n| \"在画布上生成图片\" | 画布 + AI 生成 | `workrally generate image --project-id <画布ID>` |\n| \"上传到项目\" | 仅入媒资库 | `upload` → `asset create` |\n| \"在画布上展示素材\" | 需要 build-draft | `upload` → `asset create` → `canvas build-draft` |\n\n---\n\n## 2. 画布节点类型 (8 种)\n\n### 类型一览\n\n| type | 说明 | 必填 data 字段 | 可放入画板 |\n|------|------|---------------|-----------|\n| `image` | 图片素材 | `data.asset.id` (已有素材) 或 `data.task` (生成中占位) | ✅ |\n| `video` | 视频素材 | `data.asset.id` 或 `data.task` | ✅ |\n| `audio` | 音频素材 | `data.asset.id` (**必须**，音频无生成器) | ✅ |\n| `imageGenerator` | 图片生成器 | 无必填（params 可选） | ❌ |\n| `videoGenerator` | 视频生成器 | 无必填（params 可选） | ❌ |\n| `artboard` | 画板容器 | 无（建议设置 `style.width/height`） | ❌ (画板不可嵌套) |\n| `text` | 文本 | `data.text.content` (字符串，最大2000字符) | ❌ |\n| `freehand` | 画笔涂鸦 | `data.freehand.points` + `data.freehand.initialSize` | ❌ |\n\n### 节点通用结构\n\n```json\n{\n \"id\": \"node_unique_id\",\n \"type\": \"image\",\n \"position\": { \"x\": 100, \"y\": 200 },\n \"data\": { },\n \"style\": { \"width\": 512, \"height\": 512 },\n \"parentId\": \"artboard_id\",\n \"measured\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n**字段说明**：\n- `id` — 节点唯一标识，可使用任意唯一字符串\n- `position` — 节点左上角坐标（缺失时堆叠在原点 0,0）\n- `style` — 节点显示尺寸\n- `parentId` — 仅画板内子节点需要，指向父画板的 id\n- `measured` — 渲染尺寸，可选，缺失时服务端自动补全\n\n---\n\n## 3. 各节点类型详细说明\n\n### 3.1 图片/视频节点 (image / video)\n\n两种来源：\n1. **已有素材** — 必须有 `data.asset.id`\n2. **生成中占位** — 必须有 `data.task`（由 AI 生成命令自动创建，通常不需要手动构造）\n\n```json\n{\n \"id\": \"img_001\",\n \"type\": \"image\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_abc123\" }\n },\n \"style\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n**带生成任务标记的节点**（用于\"再次编辑\"功能）：\n```json\n{\n \"id\": \"gen_img_001\",\n \"type\": \"image\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_abc123\" },\n \"task\": { \"taskId\": \"task_xyz789\", \"status\": \"success\" }\n },\n \"style\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n> 💡 `data.task` 字段决定前端是否显示\"再次编辑\"按钮。AI 生成的图片/视频应包含此字段。\n\n### 3.2 音频节点 (audio)\n\n音频**没有生成器**，不支持 task 占位，必须有 `data.asset.id`。\n\n```json\n{\n \"id\": \"audio_001\",\n \"type\": \"audio\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_audio_456\" }\n },\n \"style\": { \"width\": 260, \"height\": 80 }\n}\n```\n\n> 建议尺寸 **260×80**（与前端默认一致）。\n\n### 3.3 画板节点 (artboard)\n\n画板是**容器**，子节点通过 `parentId` 关联到画板。\n\n```json\n{\n \"id\": \"board_001\",\n \"type\": \"artboard\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {},\n \"style\": { \"width\": 600, \"height\": 800 }\n}\n```\n\n**画板子节点示例** — 在画板内放置一张图片：\n```json\n{\n \"id\": \"img_in_board\",\n \"type\": \"image\",\n \"position\": { \"x\": 20, \"y\": 20 },\n \"data\": { \"asset\": { \"id\": \"asset_abc123\" } },\n \"style\": { \"width\": 256, \"height\": 256 },\n \"parentId\": \"board_001\"\n}\n```\n\n**画板规则**：\n- ✅ `image`、`video`、`audio` 可以放入画板\n- ❌ `imageGenerator`、`videoGenerator`、`text`、`freehand` 不可放入画板\n- ❌ 画板不可嵌套（画板内不能放画板）\n- ❌ **不要设置 `extent: \"parent\"`**，否则子节点会被锁定在画板内无法拖出\n- 画板缺少尺寸时自动补全为 **600×800**\n\n### 3.4 文本节点 (text)\n\n```json\n{\n \"id\": \"text_001\",\n \"type\": \"text\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"text\": {\n \"content\": \"这是一段文本\",\n \"fontSize\": 24,\n \"fontWeight\": 400,\n \"textAlign\": \"left\",\n \"color\": \"#ffffff\"\n }\n },\n \"style\": { \"width\": 200 }\n}\n```\n\n**必填**: `data.text.content`（字符串，最大2000字符）\n**可选**（有默认值）: `fontSize`(24), `fontWeight`(400, 加粗用700), `textAlign`(\"left\"), `color`(\"#ffffff\")\n建议设置 `style.width`（默认200）。\n\n### 3.5 画笔涂鸦节点 (freehand)\n\n```json\n{\n \"id\": \"freehand_001\",\n \"type\": \"freehand\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"freehand\": {\n \"points\": [[10, 20, 0.5], [30, 40, 0.7], [50, 60, 0.5]],\n \"initialSize\": { \"width\": 200, \"height\": 200 },\n \"color\": \"rgba(242,72,34,1)\",\n \"size\": 7\n }\n }\n}\n```\n\n**必填**: `data.freehand.points`（二维数组，每个点为 `[x, y, pressure]`）、`data.freehand.initialSize`（`{width, height}`）\n**可选**: `color`（默认红色 `rgba(242,72,34,1)`）、`size`（画笔粗细 1-100，默认7）\n`pressure` 值范围 0-1，超出自动截断。\n\n### 3.6 生成器节点 (imageGenerator / videoGenerator)\n\n> ⚠️ **通常不需要手动创建！** `workrally generate image/video --project-id <画布ID>` 会**自动**在画布中创建 running 状态的占位节点。\n\n仅在极特殊场景（如手动构建已完成的生成器节点）才需要：\n\n```json\n{\n \"id\": \"gen_001\",\n \"type\": \"imageGenerator\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"task\": { \"taskId\": \"task_abc\", \"status\": \"success\" },\n \"params\": {}\n },\n \"style\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n---\n\n## 4. build-draft 操作模式\n\n### 4.1 增量合并（默认模式）\n\n```bash\nworkrally canvas build-draft --nodes '[...]'\n```\n\n规则：\n- **同 id → 覆盖更新**：传入的节点 id 与已有节点相同时，用新数据替换旧数据\n- **新 id → 追加**：已有画布中不存在的 id 会被添加\n- **未提及 → 保留**：已有节点不在传入列表中的，原样保留\n\n### 4.2 删除节点\n\n```bash\nworkrally canvas build-draft --delete-node-ids \"id1,id2\"\n```\n\n可与 `--nodes` 同时使用（先删除，再合并新节点）：\n\n```bash\nworkrally canvas build-draft --nodes '[...]' --delete-node-ids \"old1,old2\"\n```\n\n### 4.3 全量覆盖\n\n```bash\nworkrally canvas build-draft --nodes '[...]' --mode overwrite\n```\n\n**清空画布**后仅保留传入的节点。传 `--nodes '[]' --mode overwrite` 可清空整个画布。\n\n> ⚠️ 全量覆盖会删除所有已有节点，包括其他用户的内容。在多人协作场景下应优先使用增量合并。\n\n### 4.4 从文件加载节点\n\n```bash\nworkrally canvas build-draft --file nodes.json\n```\n\n适合节点数据量大或结构复杂的场景。\n\n---\n\n## 5. 常见工作流示例\n\n### 场景 A：在画布上排列已有素材\n\n```bash\n# 1. 搜索项目中的素材\nworkrally asset search --project-id -o json\n\n# 2. 从搜索结果中获取 asset_id，构建节点写入画布\nworkrally canvas build-draft --nodes '[\n {\"id\":\"n1\",\"type\":\"image\",\"position\":{\"x\":0,\"y\":0},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":512,\"height\":512}},\n {\"id\":\"n2\",\"type\":\"image\",\"position\":{\"x\":600,\"y\":0},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":512,\"height\":512}}\n]'\n```\n\n### 场景 B：创建画板并放入多张图片\n\n```bash\nworkrally canvas build-draft --nodes '[\n {\"id\":\"board\",\"type\":\"artboard\",\"position\":{\"x\":0,\"y\":0},\"data\":{},\"style\":{\"width\":800,\"height\":600}},\n {\"id\":\"img1\",\"type\":\"image\",\"position\":{\"x\":20,\"y\":20},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":350,\"height\":250},\"parentId\":\"board\"},\n {\"id\":\"img2\",\"type\":\"image\",\"position\":{\"x\":420,\"y\":20},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":350,\"height\":250},\"parentId\":\"board\"}\n]'\n```\n\n### 场景 C：更新画布中某个节点的位置\n\n```bash\n# 只传需要修改的节点，其他节点自动保留\nworkrally canvas build-draft --nodes '[\n {\"id\":\"existing_node_id\",\"type\":\"image\",\"position\":{\"x\":300,\"y\":400},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":512,\"height\":512}}\n]'\n```\n\n### 场景 D：删除部分节点并添加新节点\n\n```bash\nworkrally canvas build-draft \\\n --nodes '[{\"id\":\"new1\",\"type\":\"text\",\"position\":{\"x\":0,\"y\":0},\"data\":{\"text\":{\"content\":\"新标题\",\"fontSize\":48,\"fontWeight\":700,\"color\":\"#00ff00\"}},\"style\":{\"width\":400}}]' \\\n --delete-node-ids \"old_node_1,old_node_2\"\n```\n\n---\n\n## 6. 服务端自动修正\n\n服务端会对传入的节点进行以下自动修正（不需要 Agent 操心）：\n\n| 场景 | 自动行为 |\n|------|---------|\n| 画板缺少 style | 补全 600×800 |\n| 文本节点缺少样式属性 | 补全 fontSize=24, fontWeight=400, textAlign=left, color=#ffffff |\n| 文本节点缺少 style.width | 补全 200 |\n| 文本内容为空 | 填充\"在此输入文本\" |\n| 画笔节点缺少颜色/大小 | 补全 color=rgba(242,72,34,1), size=7 |\n| 画笔 size 超出范围 | 截断到 1-100 |\n| 画笔 pressure 超出范围 | 截断到 0-1 |\n| 子节点设置了 extent | 自动清除（防止锁定） |\n\n**但以下关键字段缺失会被拒绝**：\n\n| 场景 | 错误 |\n|------|------|\n| image/video 既没有 asset.id 也没有 task | ❌ 空节点 |\n| audio 没有 asset.id | ❌ 音频无生成器 |\n| text 没有 data.text.content 或类型非字符串 | ❌ |\n| text 内容超过 2000 字符 | ❌ |\n| freehand 缺少 points 或 initialSize | ❌ |\n| 不允许的节点类型（如 group） | ❌ |\n| 画板子节点类型不是 image/video/audio | ❌ |\n\nFile v2.9.0:references/common-pitfalls.md\n\n# 常见问题与易错点\n\n本文档汇总 AI Agent 使用 WorkRally CLI 时最容易犯的错误和混淆点，帮助避免常见陷阱。\n\n---\n\n## ❌ 错误 1：混淆\"项目\"和\"画布\"\n\n### 问题\n\n```bash\n# ❌ 错误：把项目 ID 当画布 ID 用\nworkrally generate image --prompt \"...\" --model --project-id \n```\n\n### 正确做法\n\n```bash\n# ✅ 先获取画布 ID\nworkrally canvas list -o json\n# 再传画布 ID\nworkrally generate image --prompt \"...\" --model --project-id \n```\n\n### 区分规则\n\n| 获取方式 | 返回的是 | 传给谁 |\n|----------|---------|--------|\n| `workrally project list` | 项目 ID | `asset create --project-id`、`asset search --project-id` |\n| `workrally canvas list` | 画布 ID | `generate image --project-id`、`generate video --project-id`、`canvas build-draft` |\n\n---\n\n## ❌ 错误 2：硬编码模型 ID\n\n### 问题\n\n```bash\n# ❌ 错误：猜测或硬编码模型 ID\nworkrally generate image --prompt \"...\" --model \"kontext_v2\"\n```\n\n### 正确做法\n\n```bash\n# ✅ 动态获取\nworkrally generate image-models -o json\n# 从返回结果中读取 model_id\nworkrally generate image --prompt \"...\" --model <从返回结果中获取的model_id>\n```\n\n> 模型列表是**动态下发**的，不同环境的可用模型可能完全不同。\n> 生视频用 `generate video-models`；生音频/音乐用 `generate audio-models`；提示词优化用 `generate content-models`（不要硬编码 MiniMax H3）。混元 3D 用 `generate 3d --asset-id`，不要查 3d-models。\n\n---\n\n## ❌ 错误 3：自行拼接前端 URL\n\n### 问题\n\n```bash\n# ❌ 错误：自己拼接 URL（域名和路由因环境而异）\necho \"https://workrally.qq.com/workrally/toolbox/canvas/abc123\"\n```\n\n### 正确做法\n\n```bash\n# ✅ 使用 url build 命令\nworkrally url build \"无限画布\" --params '{\"id\":\"abc123\"}'\n```\n\n---\n\n## ❌ 错误 4：生成后手动调用 build-draft\n\n### 问题\n\n```bash\n# ❌ 不必要：在画布中生成图片后，又手动创建节点\nworkrally generate image --prompt \"...\" --model --project-id --poll\n# 然后又调用 build-draft 创建节点 ← 多余操作\nworkrally canvas build-draft --nodes '[...]'\n```\n\n### 正确理解\n\n传入 `--project-id` 后，系统**自动**在画布创建 running 状态的占位节点。**无需手动 build-draft。**\n\n### build-draft 的正确使用场景\n\n- 在画布上放置**已有素材**（非 AI 生成的图片/视频/音频）\n- 管理**画板布局**（创建画板、调整子节点位置）\n- 添加**文本**或**涂鸦**节点\n- **删除**画布上的节点\n- **重新排列**已有节点\n\n---\n\n## ❌ 错误 5：上传素材缺少入库步骤\n\n### 问题\n\n```bash\n# ❌ 错误：上传后直接使用 CDN URL\nworkrally upload ./file.png -o json\n# 然后直接把 cdn_url 作为 asset_id 用 ← 这不是 asset_id！\n```\n\n### 正确做法\n\n```bash\n# ✅ 上传后必须入媒资库\nworkrally upload ./file.png -o json\nworkrally asset create --url --project-id -o json\n# 现在才有 asset_id\n```\n\n> 上传只是把文件传到 CDN，**必须**调用 `asset create` 入库才能被系统使用。\n\n---\n\n## ❌ 错误 6：资产库挂载缺少关键字段\n\n### 问题\n\n```bash\n# ❌ 错误：JSON 中缺少 material_id 或 material_detail\nworkrally material add --json-list '[{\"material_name\":\"素材\",\"material_type\":2,\"parent_id\":\"role_person\"}]'\n# 素材不会在资产库列表中显示！\n```\n\n### 正确做法\n\n```bash\n# ✅ 必须在 JSON 中传 material_id（=asset_id）和完整的 material_detail（=asset_details）\nworkrally material add --json-list '[{\n \"material_id\": \"\",\n \"material_name\": \"素材名\",\n \"material_type\": 2,\n \"parent_id\": \"\",\n \"material_detail\": <完整的 asset_details 对象>\n}]' --project-ids \n```\n\n---\n\n## ❌ 错误 7：画板内放入不允许的节点类型\n\n### 问题\n\n```bash\n# ❌ 错误：把文本节点放入画板\nworkrally canvas build-draft --nodes '[\n {\"id\":\"board\",\"type\":\"artboard\",\"position\":{\"x\":0,\"y\":0},\"data\":{},\"style\":{\"width\":600,\"height\":800}},\n {\"id\":\"txt\",\"type\":\"text\",\"position\":{\"x\":20,\"y\":20},\"data\":{\"text\":{\"content\":\"标题\"}},\"parentId\":\"board\"}\n]'\n# 服务端会拒绝！\n```\n\n### 正确理解\n\n画板只接受 `image`、`video`、`audio` 类型的子节点。\n\n---\n\n## ❌ 错误 8：给画板子节点设置 extent\n\n### 问题\n\n```json\n{\n \"id\": \"img1\",\n \"type\": \"image\",\n \"parentId\": \"board\",\n \"extent\": \"parent\"\n}\n```\n\n### 后果\n\n子节点被 ReactFlow 锁定在画板内，用户无法拖出。服务端会自动清除此属性，但不要主动设置。\n\n---\n\n## ❌ 错误 9：混淆 material_id 和 role_id\n\n### 问题\n\n```bash\n# ❌ 错误：用 material_id 查角色详情\nworkrally role get \"abc_0\"\n# material_id 格式: \"abc_0\" (带后缀)\n# role_id 格式: \"abc\" (不带后缀)\n```\n\n### 正确做法\n\n```bash\n# ✅ 先获取 role_id\nworkrally material get \"abc_0\" -o json\n# 从返回结果中找到 role_id 字段\nworkrally role get \"abc\" -o json\n```\n\n---\n\n## ❌ 错误 10：音视频 URL 使用 original_url\n\n### 问题\n\n```bash\n# ❌ 错误：音视频使用 original_url（不含访问凭证）\n# original_url 是原始 CDN 路径，音视频无法直接访问\n```\n\n### 正确做法\n\n始终使用 `url` 或 `download_url`，这些是可直接访问的临时 URL。过期后通过 `asset get` 重新获取即可，返回的新 URL 可直接作为其他工具的 URL 参数传入。\n\n---\n\n## ❌ 错误 11：生图 `--resolution 1/2` 当成视频枚举\n\n### 问题\n\n```bash\n# ❌ 错误：以为和 generate video 一样，2=540P\nworkrally generate image --prompt \"...\" --model --resolution 2\n# 生图里 2 仍是旧档位 4K，不是 540P\n```\n\n### 正确做法\n\n```bash\nworkrally generate image-models -o json\n# 用该模型 resolution_options[].value（常见 4=1080P、5=1440P、6=2160P）\nworkrally generate image --prompt \"...\" --model --resolution 5\n```\n\n旧脚本继续传 `0/1/2` 仍然有效（映射为 1080P/1440P/2160P），新调用不要混用两套数字。\n\n---\n\n## ❌ 错误 12：提示词优化任务去找 output_assets\n\n### 问题\n\n```bash\nworkrally generate optimize-prompt --prompt \"延长5秒\" --model --poll\n# ❌ 在结果里找 output_assets / output_products —— 文本任务没有媒资产物\n```\n\n### 正确做法\n\n```bash\n# ✅ 先拿模型\nworkrally generate content-models -o json\n# ✅ 轮询成功后读 output_text（output_type=\"text\"）\nworkrally generate optimize-prompt --prompt \"将视频从尾帧延长5秒\" --model \\\n --video-url --first-frame-url --last-frame-url \\\n --reference-image-urls \"url1,url2\" --audio-url --poll\n```\n\n| 任务 | output_type | 产物字段 |\n|------|-------------|----------|\n| 生图 / 生视频 | `assets` | `output_assets` |\n| 提示词优化 | `text` | `output_text` |\n\n---\n\n## 常见判断速查表\n\n| 场景 | 需要什么 |\n|------|---------|\n| \"上传一张图片\" | `upload` → `asset create` (2步) |\n| \"上传到人物角色\" | `upload` → `asset create` → `material add` (3步) |\n| \"在画布上生成图片\" | `generate image --project-id <画布ID> --poll` (1步) |\n| \"把已有图片放到画布上\" | `asset search` → `canvas build-draft` |\n| \"生成4张图片\" | `generate image --count 4 --poll` |\n| \"查看生成进度\" | `generate task --poll` |\n| \"优化视频提示词\" | `generate content-models` → `generate optimize-prompt --poll`（读 `output_text`） |\n| \"创建一个画板放三张图\" | `canvas build-draft` (一次传画板+3个子节点) |\n| \"删除画布上的某个节点\" | `canvas build-draft --delete-node-ids \"node_id\"` |\n| \"清空整个画布\" | `canvas build-draft --nodes '[]' --mode overwrite` |\n| \"查看角色的 LoRA 版本\" | `material get` → `role get` |\n| \"搜索项目中的视频素材\" | `asset search --project-id ` |\n\n---\n\n## 查看白名单工具\n\n只能使用 `tools list` / `tools describe` 和已封装的 CLI 子命令。**不要**透传调用未列出的 MCP 工具（`tools call` 已移除）。\n\n```bash\nworkrally tools list -o json\nworkrally tools describe \n```\n\n---\n\n## 输出格式建议\n\n| 格式 | 用途 | 命令 |\n|------|------|------|\n| `json` | **Agent 推荐** — 结构化数据便于解析 | `-o json` |\n| `table` | 人类阅读 — 表格格式 | `-o table` |\n| `text` | 管道/脚本 — 纯文本 | `-o text` |\n\n设置全局默认格式：\n```bash\nworkrally config set output_format json\n```\n\nFile v2.9.0:references/shotlist-guide.md\n\n# 场次操作指南（shotlist · 对齐 Web /shot 批量制作）\n\n本文档帮助 AI Agent 通过 `workrally shotlist` / `workrally series` 完成场次全生命周期管理，对应前端 `/shot`（`anime-new-shot`）批量制作能力：\n\n- **生成走统一任务通道**（`TvShortSeriesTask.SubmitTask/BatchSubmitTask`）\n- **配置聚合在 `shot.extra.gen_config.{image,video,audio}`**\n- **模型统一来自 `shotlist models`（GetTaskModelList，画布同源）**\n- **支持生图 / 生视频 / 生音频**，结果查询 `--type image|video|audio`\n\n---\n\n## 1. 概念图谱\n\n```\n项目 (project)\n └─ 剧集 (series)\n └─ 场次 (shot/story)\n ├─ ⭐ 图片提示词 (image_prompt) ← 决定关键帧画面\n ├─ ⭐ 视频提示词 (animation_prompt) ← 决定动效/运镜\n ├─ ⭐ 音频提示词 (extra.audio_prompt) ← 音色用 <音色名> 引用\n ├─ 参考资产 (video_role_data_json) ← 图片+视频统一存放\n ├─ 音频参考 (extra.audio_role_data_json) ← 仅音频，独立字段\n └─ 生成配置 (extra.gen_config.{image,video,audio}) ← 模型/比例/时长/分辨率等\n```\n\n---\n\n## 2. 标准工作流（唯一推荐）\n\n`series create` → `shotlist create` → `shotlist recognize` → `shotlist models` → `shotlist set-model` → `shotlist generate-image / generate-video / generate-audio` → `shotlist get-result --type image|video|audio --watch`\n\n```bash\n# 1) 新建剧集\nSERIES_ID=$(workrally series create --project-id $PROJECT_ID --name \"第一集\" -o json | jq -r '.series_id')\n\n# 2) 批量创建场次（按用户意图填提示词：仅图 / 仅视频 / 图+视频）\nworkrally shotlist create --series-id $SERIES_ID --json-list \\\n '[{\"image_prompt\":\"古风庭院全景\",\"animation_prompt\":\"镜头缓推\"},\n {\"image_prompt\":\"两位侠客对峙\",\"animation_prompt\":\"推近脸部特写\"}]'\n\n# 3) 识别角色/资产（三路：image/animation/audio）\nworkrally shotlist recognize --series-id $SERIES_ID --project-id $PROJECT_ID\n\n# 4) 选模型（勿硬编码）→ 写配置\nworkrally shotlist models --category image,video,audio -o json\nworkrally shotlist set-model --series-id $SERIES_ID \\\n --image-model --image-aspect-ratio 16:9 \\\n --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9 \\\n --audio-model \n\n# 5) 生成（多场次一起；均需 --project-id）\nSTORY_IDS=$(workrally shotlist list --series-id $SERIES_ID -o json | jq -r '[.story_list[].story_id] | join(\",\")')\nworkrally shotlist generate-image --project-id $PROJECT_ID --story-ids \"$STORY_IDS\"\nworkrally shotlist generate-video --project-id $PROJECT_ID --story-ids \"$STORY_IDS\"\nworkrally shotlist generate-audio --project-id $PROJECT_ID --story-ids \"$STORY_IDS\"\n\n# 6) 查结果（image/video/audio 三条独立进度，分别 watch）\nfor sid in $(echo \"$STORY_IDS\" | tr ',' ' '); do\n workrally shotlist get-result --story-id $sid --type image --watch\n workrally shotlist get-result --story-id $sid --type video --watch\n workrally shotlist get-result --story-id $sid --type audio --watch\ndone\n```\n\n---\n\n## 3. 模型与生成配置（`extra.gen_config`）\n\n> ⚠️ 模型来自 `shotlist models`（GetTaskModelList，画布同源），返回的 `id` 直接写入 `gen_config`；\n> 旧 `shot image-models`（Kontext en_name）/ `shot video-models`（Wuji provider）**不适用于 shotlist**。\n\n```bash\n# 拉可用模型（category 逗号分隔）\nworkrally shotlist models --category image,video,videoSingle,videoFrame,audio -o json\n# 返回每模型：id / name / aspect_ratios / resolutions(enum_value) / durations（audio 含 restrictions）\n```\n\n`set-model` 把配置写入 `extra.gen_config`（不传 `--story-ids` 则对 `--series-id` 全剧集生效）：\n\n| 维度 | flags | 写入字段 |\n|------|-------|---------|\n| 图片 | `--image-model` / `--image-aspect-ratio` / `--image-resolution` / `--image-count` / `--image-quality` / `--mj-params` | `gen_config.image` |\n| 视频 | `--video-mode`(SubjectToVideo\\|Text\\|FirstLastFrame\\|SmartEdit) + 对应模型；`--single-assets` / `--first-last-assets` / `--extra-mode extendVideo` / `--extend-source-id`；支持 `--no-enable-sound` / `--erase-subtitles` | `gen_config.video` |\n| 音频 | `--audio-model` / `--audio-count` / `--audio-config` / `--audio-fields` / `--audio-capabilities` | `gen_config.audio` |\n\n**视频四种主模式 + 延长子模式**（模型字段互不通用，切模式要用对应类别的模型）：\n- `SubjectToVideo`（参考主体，默认）：模型写 `model`；资产走 `video_role_data_json`。\n- `Text`（单图）：模型写 `textModel`；资产走 `gen_config.video.singleAssets`（CLI `--single-assets`）。\n- `FirstLastFrame`（首尾帧）：模型写 `firstLastModel`；资产走 `gen_config.video.firstLastAssets`（CLI `--first-last-assets`）。\n- `SmartEdit`（智能编辑）：模型写 `smartEditModel`；需 `smartEditSourceVideo`（含 asset_id/width/height/duration），提示词可空。\n- **延长视频**：`mode=SubjectToVideo` + `extraMode=extendVideo` + `__extendSourceId`（源片 asset_id）+ `duration`（延长秒数，不是成片总时长）；生成走 `graph_template=extend_video`。\n\n> Auto 智能路由模型（capability 111）**暂不支持** MCP/CLI 自动分流，请用 `shotlist models` 选具体模型 id。\n\n---\n\n## 4. 资产识别（recognize）\n\n底层仍是 `Material.MatchContentRole`，但新版支持**符号分词**与**音频路**：\n\n```bash\n# 默认：both（图片+视频+音频三路）、text 规则、仅本项目资产库\nworkrally shotlist recognize --series-id --project-id \n\n# 只识别某一路\nworkrally shotlist recognize --series-id --project-id --scope image\nworkrally shotlist recognize --series-id --project-id --scope audio\n\n# 符号+文字识别：【角色】=图片/状态，<音色>=音频\nworkrally shotlist recognize --series-id --project-id --match-rule symbol_text\n\n# 全资产库范围\nworkrally shotlist recognize --series-id --recognize-scope all\n```\n\n- `--scope`：`image | animation | audio | both`（识别哪条 prompt；默认 both）。\n- `--match-rule`：`text`（默认，去掉 `【】<>` 全部当图片）/ `symbol_text`（区分图片与音色）。**音频路内部强制 `symbol_text`**。\n- `--recognize-scope`：`project`（默认，仅本项目）/ `all`（全资产库）。\n- 落库：图片/视频路写 `role_data_json` + `video_role_data_json`（统一）+ prompt 占位 + `extra.*_prompt_json`；音频路写 `extra.audio_role_data_json` + `extra.audio_prompt` + `extra.audio_prompt_json`。\n\n> ⚠️ `--scope` 控制识别路（image/animation/audio/both），`--recognize-scope` 控制资产库范围（project/all），二者勿混用。\n\n---\n\n## 5. 生成与结果查询\n\n> ⚠️ `shotlist generate-*` **仅提交任务**，不返回可轮询的画布 task_id；进度归属「场次 + 类型」，用 `shotlist get-result` 查。\n> 三个生成命令都需要 `--project-id`（短番项目ID，SubmitTask 需要）。\n\n```bash\n# 生图（每场次 count 张）\nworkrally shotlist generate-image --project-id --story-ids st_1,st_2 --count 2\n# 生视频（按各场次 gen_config.video.mode 分支，每场次 1 条）\nworkrally shotlist generate-video --project-id --story-ids st_1,st_2\n# 对已选定视频超分（model 来自 models --category upscale）\nworkrally shotlist upscale-video --project-id --story-ids st_1,st_2 --model --scale 2\n# 生音频（按模型能力走 reference_to_audio 或 text_to_audio，每场次 count 条）\nworkrally shotlist generate-audio --project-id --story-ids st_1,st_2\n\n# 查结果（--type image|video|audio；--watch 轮询至 state=all_done）\nworkrally shotlist get-result --story-id st_1 --type audio --watch --interval 5\n```\n\n`get-result` 返回关键字段：`state`(all_done/running/no_data) / `doing_count` / `done_count` / `failed_count` / `results[]` / `doing_tasks[]` / `failed_tasks[]`。`doing_count===0` 即该类型任务全部结束。\n\n---\n\n## 6. 音频生成（新增能力）\n\n1. 在 `image/animation` 之外，场次可独立生成音频（配音/音效）。参考音频模型（如 Seed Audio）走 `reference_to_audio`；能力列表含 `106` 的 MiniMax 模型走 `text_to_audio` 且不接收参考音频。\n2. 音频提示词存 `extra.audio_prompt`；**音色用 `<音色名>` 引用**，参考资产仅音频（`extra.audio_role_data_json`），与视频/图片参考完全隔离。\n3. 流程：`shotlist models --category audio` 选模型 → `shotlist set-model --audio-model ` → （可选 `shotlist recognize --scope audio --match-rule symbol_text` 识别音色）→ `shotlist generate-audio --project-id --story-ids ` → `shotlist get-result --type audio --watch`。\n\n---\n\n## 7. 资产绑定（bind）\n\n```bash\n# 图片/视频参考 → 统一写入 video_role_data_json\nworkrally shotlist bind --story-id st_1 --type image --assets '[{\"asset_id\":\"a1\",\"url\":\"https://...\"}]'\nworkrally shotlist bind --story-id st_1 --type video --assets '[{...}]'\n# 音频参考 → 独立写入 extra.audio_role_data_json\nworkrally shotlist bind --story-id st_1 --type audio --assets '[{\"asset_id\":\"au1\",\"url\":\"https://...\"}]'\n# 本地参考音频 → CLI 自动完成上传、媒资入库、绑定\nworkrally shotlist bind --story-id st_1 --type audio --file ./voice.wav --project-id \n# 替换而非追加\nworkrally shotlist bind --story-id st_1 --type image --mode replace --assets '[...]'\n```\n\n---\n\n## 8. 易错点\n\n| 错误 | 正确做法 |\n|------|----------|\n| 用 `shot image-models/video-models` 给 shotlist 配模型 | 新版用 `shotlist models --category ...`（GetTaskModelList），id 直接写 gen_config |\n| `shot` 与 `shotlist` 混用同一剧集 | 配置字段不互通（扁平字段 vs gen_config），一个剧集固定用一套 |\n| `generate-*` 不传 `--project-id` | 新版走 SubmitTask，必须传短番项目 ID |\n| 等 `generate-*` 返回 task_id 去轮询 | MCP 会返回 `task_ids`；CLI 仍建议用 `shotlist get-result --type image\\|video\\|audio [--watch]` |\n| 一次 `get-result` 同时查三类 | image/video/audio 是三条独立进度，分别用 `--type` 查 |\n| 音色识别不出来 | 音色要用 `<音色名>` 且 `--match-rule symbol_text`（音频路已强制） |\n| 本地参考音频不能直接绑定 | 使用 `shotlist bind --type audio --file --project-id `，CLI 会自动上传并入库 |\n| 已绑定音频生成时没有进入 `ref_audios` | 绑定项需有 `asset_id/assetId` 或 URL；新版 bind 会自动补齐 `fileType=audio` |\n| 延长视频提交失败 | 需 `--extra-mode extendVideo` + `--extend-source-id` + `--duration`（延长秒数），且 mode 为 SubjectToVideo |\n| Auto 模型生成结果不符合预期 | MCP/CLI 不会走前端 task_router，请改选具体模型 |\n| 硬编码模型 id | 必须先 `shotlist models` 动态获取 |\n\nFile v2.9.0:references/upload-and-assets-guide.md\n\n# 上传与素材管理指南\n\n本文档帮助 AI Agent 正确执行文件上传和素材管理流程。WorkRally 有两套素材体系，理解它们的关系是正确操作的前提。\n\n---\n\n## 1. 两套素材体系\n\n### 媒资库 (Asset) — 项目级文件池\n\n- **管理命令**: `workrally asset search/create/get/update`\n- **本质**: 扁平的文件列表，每个素材必须归属一个项目\n- **特点**: 视频/音频为**私有读存储**，必须入库后才能正常访问\n- **何时使用**: 所有素材都**必须**经过媒资库（`asset create`）才能被系统使用\n\n### 资产库 (Material) — 树形目录管理\n\n- **管理命令**: `workrally material list/add/update/get/breadcrumb`\n- **本质**: 树形文件夹结构，对媒资库素材的**组织视图**\n- **三个预设根目录**: `role_person`(人物)、`role_prop`(道具)、`role_scene`(场景)\n- **附加根目录**: `root`(用户自建网盘文件夹)\n- **何时使用**: 仅当用户要将素材\"归档到角色/道具/场景/文件夹\"时才需要\n\n### 数据层次关系\n\n```\n资产 (material_type=0)\n └─ 角色状态 (material_type=5)\n ├─ 图片素材 (material_type=2)\n ├─ 视频素材 (material_type=3)\n └─ 音频素材 (material_type=4)\n```\n\n---\n\n## 2. 三步上传流程\n\n这是 WorkRally 最核心的文件处理流程，**严格按顺序执行**：\n\n### 步骤 1: 上传文件到 CDN\n\n```bash\nworkrally upload ./character.png -o json\n```\n\n返回：\n```json\n{\n \"url\": \"https://cdn.example.com/path/to/file.png\",\n \"original_url\": \"https://cdn.example.com/path/to/file.png\",\n \"signed_url\": \"https://cdn.example.com/path/to/file.mp4?sign=...\"\n}\n```\n\n**URL 字段说明**：\n- `url` — 可直接访问的地址。图片为公开 URL；音视频为临时访问 URL\n- `original_url` — 原始 CDN 路径（不含访问凭证），图片可直接访问，音视频无法直接访问\n- `signed_url` — 仅音视频返回，与 `url` 相同\n\n> ⚠️ 音视频文件为私有读存储，**必须使用 `url` 或 `signed_url`**，不要使用 `original_url`。\n\n### 步骤 2: 入媒资库（必须！）\n\n> 🔒 `--url` 仅接受 WorkRally 官方媒资 URL（即 `upload` 返回值或媒资库 URL），详见 SKILL.md 规则 9。\n\n```bash\nworkrally asset create --url --project-id -o json\n```\n\n返回：\n```json\n{\n \"id\": \"asset_abc123\",\n \"asset_details\": {\n \"url\": \"https://signed.url/...\",\n \"download_url\": \"https://signed.download.url/...\",\n \"width\": 1024,\n \"height\": 1024,\n \"format\": \"png\"\n }\n}\n```\n\n**重要返回值**：\n- `id` — 即 `asset_id`，后续所有操作都需要这个 ID\n- `asset_details` — 完整素材元数据，**步骤 3 必须完整传入**\n\n> ⚠️ `asset_details.url` 和 `asset_details.download_url` 为临时访问 URL，过期后需通过 `workrally asset get` 重新获取。获取到的 URL 可直接作为其他工具的 URL 参数传入。\n\n### 步骤 3: 挂载到资产库（按需）\n\n```bash\nworkrally material add --json-list '[{\n \"material_id\": \"\",\n \"material_name\": \"角色名_状态\",\n \"material_type\": 2,\n \"parent_id\": \"<目标位置的 material_id>\",\n \"material_detail\": <完整的 asset_details 对象>\n}]' --project-ids \n```\n\n**关键字段**（JSON 数组中每个对象）：\n- `material_id` — **必须**传 `asset_id`（步骤 2 返回的 `id`）\n- `material_detail` — **必须**传完整的 `asset_details`（步骤 2 返回的 `asset_details` 对象）\n- `material_type` — 素材类型：`2`=图片，`3`=视频，`4`=音频，`1`=文件夹\n- `parent_id` — 目标位置：`role_person`/`role_prop`/`role_scene` 或已有文件夹/状态的 `material_id`\n\n> ⚠️ 步骤 3 如果 JSON 中缺少 `material_id` 或 `material_detail`，素材不会在资产库列表中显示！\n\n---\n\n## 3. 判断需要几步\n\n| 用户意图 | 所需步骤 | 说明 |\n|----------|---------|------|\n| \"上传文件\" / \"上传图片\" | 步骤 1 → 2 | 入媒资库即可在 web 端查看 |\n| \"上传到角色/道具/场景\" | 步骤 1 → 2 → 3 | 还需挂载到资产库树形目录 |\n| \"上传到文件夹\" | 步骤 1 → 2 → 3 | 同上，parent_id 为文件夹的 material_id |\n| \"把媒资素材添加到资产库\" | 仅步骤 3 | 素材已在媒资库，只需挂载 |\n| \"在画布上放一张已有图\" | 无需上传 | 直接 `asset search` 找到 asset_id → `canvas build-draft` |\n| \"上传并放到画布上\" | 步骤 1 → 2 → `build-draft` | 入媒资库后用 build-draft 写入画布 |\n\n---\n\n## 4. 画布场景下的素材上传\n\n画布素材需要**同时关联项目和画布**：\n\n```bash\n# 步骤 1: 上传\nworkrally upload ./file.png -o json\n\n# 步骤 2: 入媒资库（必须传 project-id）\nworkrally asset create --url --project-id <项目ID> -o json\n\n# 步骤 3: 写入画布节点（使用返回的 asset_id）\nworkrally canvas build-draft <画布ID> --nodes '[\n {\"id\":\"node1\",\"type\":\"image\",\"position\":{\"x\":0,\"y\":0},\"data\":{\"asset\":{\"id\":\"\"}},\"style\":{\"width\":512,\"height\":512}}\n]'\n```\n\n> 📌 项目 ID 通过 `workrally project list` 获取。用户未指定项目时，查找名为\"默认项目\"的项目。\n\n---\n\n## 5. 资产库目录操作\n\n### 查看各根目录下的内容\n\n```bash\n# 查看人物列表\nworkrally material list role_person -o json\n# 查看道具列表\nworkrally material list role_prop -o json\n# 查看场景列表\nworkrally material list role_scene -o json\n# 查看网盘文件夹列表\nworkrally material list root -o json\n```\n\n### 查看角色的状态列表\n\n```bash\n# parent-id 传角色的 material_id\nworkrally material list <角色的material_id> -o json\n```\n\n### 查看某状态下的素材文件\n\n```bash\n# parent-id 传状态的 material_id\nworkrally material list <状态的material_id> -o json\n```\n\n### 创建文件夹\n\n```bash\nworkrally material add --json-list '[{\"material_name\":\"新文件夹\",\"material_type\":1,\"parent_id\":\"role_person\"}]'\n```\n\n### 获取角色详情（含 LoRA/提示词）\n\n```bash\n# 注意：role get 需要 role_id，不是 material_id\n# material_id 格式如 \"abc_0\"，role_id 格式如 \"abc\"\n# 先通过 material get 获取 role_id\nworkrally material get -o json\n# 返回中有 role_id 字段，再查角色详情\nworkrally role get -o json\n```\n\n> ⚠️ `material_id`（如 \"abc_0\"，带 `_0` 后缀）≠ `role_id`（如 \"abc\"）。如果只有 `material_id`，先通过 `material get` 获取 `role_id`。\n\n---\n\n## 6. 素材 URL 访问说明\n\n| 素材类型 | 存储策略 | URL 行为 |\n|----------|---------|---------|\n| 图片 | **公开读** | `url` 可直接访问 |\n| 视频 | **私有读** | `url` 为临时访问地址，过期后需重新获取 |\n| 音频 | **私有读** | `url` 为临时访问地址，过期后需重新获取 |\n\n> 📎 媒资 API 返回的素材 URL 可直接作为其他工具的 URL 参数传入，**无需手动处理**。如遇\"非法或已过期\"提示，通过下列命令重新获取即可。\n\n过期后重新获取：\n```bash\nworkrally asset get -o json\n# 返回中的 url 和 download_url 为新的可访问地址\n```\n\n---\n\n## 7. 批量操作\n\n### 批量创建素材到资产库\n\n`material add` 支持 `--json-list` 参数传入 JSON 数组，一次添加多个素材：\n\n```bash\nworkrally material add --project-ids --source 1 --json-list '[\n {\"material_id\":\"asset_id_1\",\"material_name\":\"素材1\",\"material_type\":2,\"parent_id\":\"<状态ID>\",\"material_detail\":{...}},\n {\"material_id\":\"asset_id_2\",\"material_name\":\"素材2\",\"material_type\":3,\"parent_id\":\"<状态ID>\",\"material_detail\":{...}}\n]'\n```\n\n### 批量获取素材详情\n\n```bash\nworkrally asset get -o json\n# 最多 50 个 ID\n```\n\n### 搜索媒资库\n\n```bash\nworkrally asset search --project-id -o json\n# 可选筛选: --keyword \"关键词\" --type image/video/audio\n```\n\nFile v2.9.0:skill-card.md\n\n## Description:\n\nWorkRally helps agents use the workrally CLI to create and manage AI-generated image, video, audio, music, 3D, project, shot, asset, upload, and download workflows on the WorkRally platform.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tencent-adm](https://clawhub.ai/user/tencent-adm)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users, developers, and content production teams use this skill to operate WorkRally creative workflows from an agent, including media generation, project and shot management, canvas updates, uploads, downloads, and asset organization.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill relies on a globally installed, unpinned workrally npm package with broad authenticated access.\n\nMitigation: Install only from a trusted publisher and prefer a pinned, reviewed package version before granting credentials.\n\nRisk: API keys may be exposed if passed on the command line or reused with broad account privileges.\n\nMitigation: Use interactive login where possible, store credentials in the configured WorkRally config directory, and use narrowly scoped or revocable API keys.\n\nRisk: The skill can delete projects, series, shots, materials, or canvas nodes and can overwrite collaborative canvas state.\n\nMitigation: Require explicit user confirmation before deletes, overwrite-mode canvas updates, uploads, downloads, or bulk project changes.\n\nRisk: Incorrect IDs, expired media URLs, or hard-coded model IDs can send operations to the wrong WorkRally object or fail generation tasks.\n\nMitigation: Resolve project, canvas, asset, and model IDs dynamically with the documented list/get commands before executing mutating or generation commands.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/tencent-adm/skills/workrally)\n- [WorkRally homepage](https://workrally.qq.com)\n- [WorkRally Open API](https://workrally.qq.com/open-api)\n- [AI generation guide](references/ai-generation-guide.md)\n- [Infinite canvas guide](references/canvas-guide.md)\n- [Shotlist guide](references/shotlist-guide.md)\n- [Upload and asset management guide](references/upload-and-assets-guide.md)\n- [Common pitfalls](references/common-pitfalls.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown responses with inline shell commands and JSON snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May submit authenticated WorkRally operations and asynchronous media generation tasks when the agent follows the skill.]\n\n## Skill Version(s):\n\n2.9.0 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.9.0:LICENSE.txt\n\nTencent is pleased to support the open source community by making workrally available. \n\nCopyright (C) 2026 Tencent. All rights reserved. \n\nworkrally is licensed under the MIT-0.\n\n\nTerms of the MIT-0:\n--------------------------------------------------------------------\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nArchive v2.8.0: 10 files, 32589 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1616b), references/ai-generation-guide.md (16509b), references/canvas-guide.md (10823b), references/common-pitfalls.md (8703b), references/shotlist-guide.md (9589b), references/upload-and-assets-guide.md (8027b), skill-card.md (2895b), SKILL.md (18253b), _meta.json (128b)\n\nFile v2.8.0:SKILL.md\n\n---\nname: workrally\ndescription: >-\n WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。\n 支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。\n Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts,\n manage projects, series, shots, upload files, download assets, manage materials, or\n interact with WorkRally platform via command line.\nversion: 2.8.0\nlicense: MIT-0\nauthor: WorkRally Team\nhomepage: https://workrally.qq.com\nuser-invocable: true\nmetadata: {\"openclaw\":{\"emoji\":\"🎬\",\"requires\":{\"bins\":[\"workrally\"],\"env\":[\"WORKRALLY_API_KEY\",\"WORKRALLY_ENDPOINT\",\"WORKRALLY_CONFIG_DIR\",\"WORKRALLY_NO_UPDATE_CHECK\"]},\"primaryEnv\":\"WORKRALLY_API_KEY\",\"credentials\":{\"storage\":\"~/.workrally/config.json\",\"configDirEnv\":\"WORKRALLY_CONFIG_DIR\",\"description\":\"workrally auth login 写入的 API Key 持久化文件，JSON 格式，仅存储 api_key 和 endpoint。非持久化容器中可通过 WORKRALLY_CONFIG_DIR 环境变量指定配置目录\"},\"install\":[{\"id\":\"npm\",\"kind\":\"node\",\"package\":\"workrally\",\"bins\":[\"workrally\"],\"label\":\"Install WorkRally CLI (npm)\"}],\"category\":\"AIGC\",\"tags\":[\"workrally\",\"aigc\",\"cli\",\"video-generation\",\"image-generation\",\"ai-tools\",\"story\",\"shot\",\"series\"]}}\n---\n\n# WorkRally CLI (workrally)\n\n面向 AI Agent 的 AIGC 漫剧视频创作全流程命令行工具，封装 WorkRally 平台 30+ 核心能力，支持项目/剧集/场次的完整 CRUD、AI 生图/生视频、画布、资产库、媒资管理、文件上传等。\n\n## 安装 & 配置\n\n```bash\nnpm install -g workrally\n\n# 配置 API Key（三选一）\nworkrally auth login # 交互式登录（推荐）\nworkrally auth login --token # 命令行传入\nexport WORKRALLY_API_KEY= # 环境变量（仅推荐 CI/CD，Agent/子进程可能读不到 shell 配置）\n# ↑ auth login 自动将 Token 写入配置文件：\n# 若 WORKRALLY_CONFIG_DIR 已设置 → $WORKRALLY_CONFIG_DIR/config.json\n# 否则 → ~/.workrally/config.json\n\nworkrally auth status # 验证登录状态\n```\n\nAPI Key 申请：[龙虾配置](https://workrally.qq.com/open-api)\n\n## 命令速查\n\n```bash\n# === 项目（project）— list / get / create / update（软删除无子命令，见下） ===\nworkrally project list [--search \"关键词\"] # 列出/搜索项目\nworkrally project get # 项目详情\nworkrally project create \"项目名\" # 创建项目\nworkrally project update --name \"新名称\" # 更新项目\nworkrally tools call project_delete --json-args '{\"project_id\":\"\"}' # 软删除单个项目（→回收站）\n# 批量：workrally tools describe project_delete # 使用 project_ids 数组\n\n# === 剧集（series）— 全新命令组（CRUD 完整） ===\nworkrally series list --project-id # 剧集列表\nworkrally series get --project-id # 剧集详情\nworkrally series create --project-id --name \"第一集\" # 创建剧集\nworkrally series update --project-id --name \"新名称\" # 更新剧集\nworkrally series delete # 软删除（→回收站）\n\n# === 场次（shotlist）— 对齐 Web /shot 批量制作（含音频生成）===\n# --- CRUD ---\nworkrally shotlist list --series-id # 场次列表\nworkrally shotlist get # 场次详情\nworkrally shotlist create --series-id --json-list '[{\"image_prompt\":\"...\"}]' # 批量创建\nworkrally shotlist update --image-prompt \"...\" --animation-prompt \"...\" # 单条更新\nworkrally shotlist update --batch '[{\"story_id\":\"...\",\"image_prompt\":\"...\"}]' # 批量更新\nworkrally shotlist delete # 软删除（→回收站）\nworkrally shotlist sort --series-id --order id1,id2,id3 # 重排\n# --- 模型 & 配置（写入 extra.gen_config）---\nworkrally shotlist models --category image,video,videoSmartEdit,upscale,audio # ⭐ 统一模型列表\nworkrally shotlist set-model [--story-ids id1,id2] --image-model --image-aspect-ratio 16:9 # 配置图片\nworkrally shotlist set-model [--story-ids id1,id2] --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9 # 配置视频\nworkrally shotlist set-model [--story-ids id1,id2] --audio-model # 配置音频\nworkrally shotlist bind --story-id --type image --assets '[{...}]' # 绑定参考（audio→独立字段）\nworkrally shotlist recognize --series-id --project-id [--scope both] [--match-rule symbol_text] # 识别（含音频路）\n# --- 生成（仅提交；查结果用 get-result [--watch]）---\nworkrally shotlist generate-image --project-id --story-ids id1,id2 [--count N] # 生图 → get-result --type image\nworkrally shotlist generate-video --project-id --story-ids id1,id2 # 生视频 → get-result --type video\nworkrally shotlist upscale-video --project-id --story-ids id1,id2 --model # 已选视频超分\nworkrally shotlist generate-audio --project-id --story-ids id1,id2 [--count N] # ⭐ 生音频 → get-result --type audio\nworkrally shotlist get-result --story-id --type image|video|audio [--watch] # 查进度与产物\n\n# === 上传 / 下载 ===\nworkrally upload ./file.png -o json # 上传文件 (COS SDK 直传)\nworkrally download [-d ./output/] # 下载素材 (自动处理访问凭证)\n\n# === AI 生图 ===\nworkrally generate image-models # 查看可用模型（必须先调用！）\nworkrally generate image --prompt \"描述\" --model [--aspect-ratio 16:9] [--resolution 5] [--quality high] [--input-images \"url\"] --poll\n# --resolution 推荐用 image-models 的 resolution_options[].value（常见 4=1080P/5=1440P/6=2160P）；旧档位 0/1/2 仍可用\n# --quality 仅当 image-models 该模型返回了 infer_quality_options 时才传（取值用其中的 value）\n# --extra-params '{\"midjourney\":{\"stylize\":100}}' 扩展参数 JSON 对象；CLI 传 extraParams，服务端写成 extra_params\n\n# === AI 生视频 (6 种驱动模式) ===\nworkrally generate video-models # 查看可用模型（必须先调用！）\nworkrally generate video --prompt \"描述\" --model --poll # 纯文生视频（默认 Text 模式）\nworkrally generate video --prompt \"描述\" --model --single-image-url \"url\" --poll # 图生视频（Text 模式 + 参考图）\nworkrally generate video --mode FirstLastFrame --prompt \"描述\" --model --first-frame-url \"url\" --poll # 首尾帧\nworkrally generate video --mode VideoEdit --prompt \"描述\" --model --origin-video --poll # 视频编辑\n# 其他模式: SubjectToVideo(--reference-assets)\nworkrally generate video --mode SmartEdit --model --source-video --source-width 1920 --source-height 1080 --source-duration 5000 --poll\nworkrally generate video --mode ExtendVideo --model --source-video --duration 8 --poll\n# SubjectToVideo 的 --reference-assets 支持 file 文档（Wan 3.0）：{\"type\":\"file\",\"asset_id\":\"...\",\"name\":\"brief.pdf\"}\n# --mode 默认 Text；通用选项: --aspect-ratio <比例> --resolution <枚举> --duration <秒> --count 1-4 --poll\n# 音效默认开启（与前端一致）；关闭用 --no-enable-sound。VideoEdit 不要传音效相关参数\n# --aspect-ratio 默认 16:9；--resolution 不传取模型首个可用(枚举见 video-models 的 resolution_options)\n\n# === 画布生音频 / 音乐（对齐 Web 画布音频生成器）===\nworkrally generate audio-models # 查看 audio_models / music_models（必须先调用！）\nworkrally generate audio --prompt \"雨声和脚步\" --model --poll\nworkrally generate music --prompt \"摇滚吉他\" --model --lyrics-mode none --poll\nworkrally generate music --prompt \"流行\" --model --lyrics-mode input --lyrics \"啦啦啦\" --poll\n# MiniMax 音频模型不要传 --ref-audios；动态音色参数从模型 fields 获取后用 --audio-fields JSON 传入\n\n# === 混元 3D 模型（对齐 Web 关键帧混元3D，不是世界生成/贴图）===\nworkrally generate 3d --asset-id <参考图asset_id> --poll\n# 须先 asset search / asset create 得到 asset_id；模型固定 hunyuan-3d-v3.0\n# ⚠️ --project-id 是短番项目ID，不是画布ID\n\n# === 视频提示词优化（gen_content，产物是文本不是视频）===\nworkrally generate content-models # 查看可用模型（必须先调用！严禁硬编码 MiniMax H3 等 ID）\nworkrally generate optimize-prompt --prompt \"将视频从尾帧延长5秒\" --model \\\n [--video-url ] [--first-frame-url ] [--last-frame-url ] \\\n [--reference-image-urls \"url1,url2\"] [--audio-url ] [--audio-urls \"a.mp3,b.mp3\"] --poll\n# 图片语义写在 image_info.type：first_frame / last_frame / reference_image；音频写在 audio_info.url（type=3）\n# 成功后从 generate task 的 output_text 读取优化后的提示词（output_type=\"text\"），不要找 output_assets\n\n# === 媒资库 (asset) — 项目级媒体文件池 ===\nworkrally asset create --url --project-id -o json # 入库（返回可访问 URL）\nworkrally asset search --project-id [--type image] [--audit-status 5] [--auth-status 1]\nworkrally asset get # 详情\nworkrally asset update --name \"新名称\" # 更新素材 (目前仅支持改名)\n\n# === 资产库 (material) — 树形管理：人物/道具/场景/网盘 ===\nworkrally material list role_person # 人物 | role_prop 道具 | role_scene 场景 | root 网盘文件夹\nworkrally material add ... # 创建素材/文件夹（从媒资库挂载）\nworkrally material get # 素材详情\nworkrally material delete # 删除（不可恢复，须用户确认）\nworkrally role get # 角色详情（LoRA/提示词/版本）\n\n# === 画布 ===\nworkrally canvas list # 列出画布\nworkrally canvas create \"名称\" # 创建画布\nworkrally canvas build-draft --file nodes.json # 增量合并（默认保留已有节点）\nworkrally canvas build-draft --nodes '[...]' # 同上，直接传 JSON\nworkrally canvas build-draft -d \"id1,id2\" # 删除指定节点\nworkrally canvas build-draft -n '[...]' -d \"old1\" # 同时增删改\nworkrally canvas build-draft -n '[...]' --mode overwrite # 全量覆盖（清空后重建）\n\n# === 任务查询 ===\nworkrally generate task [--poll] # 查询/轮询生成任务状态\n# 生图/生视频成功：output_type=\"assets\"，产物在 output_assets\n# 提示词优化成功：output_type=\"text\"，产物在 output_text（不要找 output_assets / output_products）\n\n# === 通用透传（调用任意 MCP 工具）===\nworkrally tools list # 列出所有工具\nworkrally tools describe # 查看参数 schema\nworkrally tools call --arg key=value [--json-args '{}']\n\n# === URL / 升级 ===\nworkrally url build \"页面名\" [--params '{}'] # 构建 WorkRally 前端链接\nworkrally url parse # 解析 URL\nworkrally upgrade [--check] # 升级 / 仅检查\n```\n\n输出格式: `-o json`(默认, Agent 推荐) | `-o table`(人类阅读) | `-o text`(管道/脚本) | `workrally config set output_format `\n\n## 关键工作流：上传文件\n\n**概念**：媒资库(asset) = 项目级文件池；资产库(material) = 树形目录(人物/道具/场景/网盘文件夹)。资产库的素材只能从媒资库挂载。\n\n```bash\n# 步骤 1: 上传 → CDN URL\nworkrally upload ./character.png -o json\n# 步骤 2: 入媒资库（必须！返回 asset_id + asset_details）\nworkrally asset create --url --project-id -o json\n# 步骤 3（按需）: 挂载到资产库（必传 asset_id + 完整 asset_details）\nworkrally material add --json-list '[{\"material_id\":\"\",\"material_name\":\"名称\",\"material_type\":2,\"parent_id\":\"\",\"material_detail\":}]' \\\n --project-ids \n```\n\n> **步骤 1→2 强制绑定**，上传后必须入媒资库。视频/音频为私有读，需经媒资库才能正常访问。\n>\n> **步骤 3 由 Agent 判断**：\"上传文件\" → 两步 | \"上传到角色/道具/场景/文件夹\" → 三步 | \"媒资素材添加到资产库\" → 仅步骤 3\n\n## 关键工作流：场次创作（`shotlist`，对齐 Web /shot）\n\n**概念层级**：项目 (project) → 剧集 (series) → 场次 (shot/story)。一个场次含 图片 / 视频 / **音频** 三条生成线，核心由提示词承载：`image_prompt`（图片）、`animation_prompt`（视频）、`extra.audio_prompt`（音频，音色用 `<音色名>` 引用）。生成配置聚合在 `extra.gen_config.{image,video,audio}`。\n\n```bash\n# 1) 建剧集 + 批量创建场次（按用户意图填提示词）\nworkrally series create --project-id --name \"第一集\" -o json\nworkrally shotlist create --series-id --json-list '[{\"image_prompt\":\"古风庭院\",\"animation_prompt\":\"镜头缓推\"}]'\n\n# 2) 识别角色资产（三路：image/animation/audio；音色用 <> 时加 --match-rule symbol_text）\nworkrally shotlist recognize --series-id --project-id \n\n# 3) 选模型 → 写配置（模型 id 来自 shotlist models，勿硬编码）\nworkrally shotlist models --category image,video,audio -o json\nworkrally shotlist set-model --series-id --image-model --image-aspect-ratio 16:9 \\\n --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9 --audio-model \n\n# 4) 生成（多场次传 --story-ids id1,id2,id3；均需 --project-id）\nworkrally shotlist generate-image --project-id --story-ids \nworkrally shotlist generate-video --project-id --story-ids \nworkrally shotlist generate-audio --project-id --story-ids \n\n# 5) 查结果（image/video/audio 三条独立进度，分别 watch）\nworkrally shotlist get-result --story-id --type image --watch\nworkrally shotlist get-result --story-id --type video --watch\nworkrally shotlist get-result --story-id --type audio --watch\n```\n\n> **生成前先确认配置**：用 `shotlist get ` 检查 `extra.gen_config` 是否已设对应模型；缺则回到步骤 3。生成只返回提交结果，不返回可轮询的画布 task_id，进度一律用 `shotlist get-result`。\n\n## ⚠️ 重要规则\n\n1. **前端链接必须用 `workrally url build` 生成**，严禁自行拼接 URL\n2. **模型 ID 必须动态获取**：`image-models` / `video-models` / `audio-models` / `content-models`，严禁猜测或硬编码。混元 3D 固定 hunyuan-3d-v3.0，只需 `--asset-id`\n3. **`canvas` ≠ `project`**：画布用 `canvas`，项目用 `project`，两者 ID 不能互换\n4. **`build-draft` 实时协同**：写入后所有在线用户立即看到变更，默认增量合并（只传变更节点），支持多人并发安全操作\n5. **`build-draft` 节点校验**：8种节点类型各有必填字段，详见 [`canvas-guide.md`](references/canvas-guide.md)\n6. **AI 生成自动占位**：`generate image/video` 传入 `--project-id`（画布ID）后自动在画布创建占位节点，**无需**再手动 `build-draft`\n7. **素材命名**：`--name` 传入\"画布名_素材特征\"（画布场景）或 prompt 关键词（非画布场景）\n8. **不确定参数时**用 `--help` 或 `tools describe` 自行探索\n9. **URL 白名单**：所有 URL 类参数（生图/生视频的 `--*-url` / `--*-assets` / `--*-images`、`asset create --url` 等）仅接受 WorkRally 官方媒资 URL。合法来源：① `workrally upload` 返回值 ② `asset get/search` 返回值（可直接传入） ③ 用户已提供的官方 URL。本地文件或第三方 URL 必须先 `workrally upload`。如遇\"非法或已过期\"提示，通过 `asset get/search` 重新获取即可。\n\n## 📚 深度指南 (references/)\n\n本 Skill 附带详细参考文档，覆盖复杂工作流：\n\n| 文档 | 内容 |\n|------|------|\n| [`references/shotlist-guide.md`](references/shotlist-guide.md) | ⭐ **场次批量制作**（对齐 Web `/shot`）— CRUD、gen_config、生图/生视频/**生音频**、结果查询、符号识别 |\n| [`references/canvas-guide.md`](references/canvas-guide.md) | 无限画布操作 — 8种节点类型、画板嵌套、build-draft 增量/覆盖模式、协同编辑 |\n| [`references/upload-and-assets-guide.md`](references/upload-and-assets-guide.md) | 上传与素材管理 — 三步上传流程、媒资库 vs 资产库、树形目录操作 |\n| [`references/ai-generation-guide.md`](references/ai-generation-guide.md) | AI 生成 — Kontext 生图、4种视频驱动模式、画布音频/音乐、混元 3D 模型、提示词优化、模型动态获取、任务轮询 |\n| [`references/common-pitfalls.md`](references/common-pitfalls.md) | 常见易错点 — 项目/画布混淆、模型硬编码、上传缺步骤等典型错误 |\n\n> 遇到画布、上传、AI生成相关的复杂操作时，请优先查阅对应的参考文档。\n\n## 环境变量\n\n- `WORKRALLY_API_KEY` — API Key (Bearer Token)\n- `WORKRALLY_ENDPOINT` — API 端点 (默认 `https://workrally.qq.com/zenstudio/api/mcp`)\n- `WORKRALLY_CONFIG_DIR` — 配置文件目录 (默认 `~/.workrally`，非持久化容器建议指向持久卷)\n- `WORKRALLY_NO_UPDATE_CHECK=1` — 禁用自动版本检查 (CI/CD 推荐)\n\nFile v2.8.0:README.md\n\n# WorkRally CLI — Agent Skill\n\n🎬 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。\n\n本目录是 WorkRally CLI 的 Agent Skill 定义。\n\n## 目录结构\n\n```\nskill/\n├── SKILL.md ← Skill 入口（元数据 + 指令），ClawHub 解析此文件\n├── LICENSE.txt ← 许可证\n└── references/ ← 深度参考文档，AI Agent 按需加载\n ├── ai-generation-guide.md AI 生成指南\n ├── canvas-guide.md 无限画布操作指南\n ├── common-pitfalls.md 常见易错点\n ├── shotlist-guide.md 场次批量制作（对齐 Web /shot）\n └── upload-and-assets-guide.md 上传与素材管理指南\n```\n\n## 核心能力\n\n- **AI 生图** — Kontext 模型，支持多参考图、可选推理质量\n- **AI 生视频** — 4 种驱动模式（文本/首尾帧/参考主体/视频编辑）\n- **提示词优化** — gen_content 文本任务，产物为 `output_text`\n- **无限画布** — Yjs 协同编辑，8 种节点类型，实时同步\n- **项目 & 媒资管理** — 项目 CRUD、素材上传入库、资产库树形管理\n- **通用透传** — 可调用 WorkRally MCP Server 全部工具\n\n## 第三方商店\n\n- [SkillHub](https://skillhub.cn/skills/workrally)\n- [ClawHub](https://clawhub.ai/tencent-adm/workrally)\n- [Skills](https://skills.sh/tencent/workrally/workrally)\n\n## 快速开始\n\n```bash\nnpm install -g workrally\nworkrally auth login\nworkrally auth status\n```\n\n详细用法、命令速查、工作流指南请参阅 **[SKILL.md](./SKILL.md)**。\n\nFile v2.8.0:_meta.json\n\n{\n \"ownerId\": \"kn77cw5hbmapf54rv89jdqwp7x835m4k\",\n \"slug\": \"workrally\",\n \"version\": \"2.8.0\",\n \"publishedAt\": 1788276941866\n}\n\nFile v2.8.0:references/ai-generation-guide.md\n\n# AI 生成指南（图片 / 视频 / 音频 / 音乐 / 3D）\n\n本文档帮助 AI Agent 正确使用 WorkRally 的 AI 图片、视频、音频、音乐与混元 3D 模型生成能力。\n\n---\n\n## 1. 核心规则\n\n> ⚠️ **模型 ID 必须动态获取，严禁猜测或硬编码！**\n> 模型列表是动态下发的，不同环境（开发/预发/正式）的可用模型可能完全不同。\n\n> 🔒 所有 URL 类参数仅接受 WorkRally 官方媒资 URL，详见 SKILL.md 规则 9。\n\n```bash\n# 生图前必须先获取模型列表\nworkrally generate image-models -o json\n\n# 生视频前必须先获取模型配置\nworkrally generate video-models -o json\n\n# 提示词优化前必须先获取 gen_content 模型列表\nworkrally generate content-models -o json\n\n# 画布生音频/音乐前必须先获取模型\nworkrally generate audio-models -o json\n```\n\n---\n\n## 2. 图片生成 (Kontext)\n\n### 2.1 获取可用模型\n\n```bash\nworkrally generate image-models -o json\n```\n\n返回包含：\n- `models[]` — 每个模型的 `model_id`、`name`、`resolution_options`、`kontext_config`、`infer_quality_options`\n- `aspect_ratios[]` — 全局可用宽高比列表（如 \"1:1\", \"16:9\", \"9:16\" 等）\n- `resolution_options[]` — 所有模型支持的 protobuf 分辨率并集（**推荐**，传给 `--resolution`）\n- `resolutions[]` — 旧档位 0/1/2 并集（兼容）\n- `count_options[]` — 可选的生成数量\n\n**关键字段**：\n- `model_id` → 传给 `--model` 参数\n- `kontext_config.max_input_images` → 该模型允许的最大参考图数量（不同模型不同，不要写死）\n- `resolution_options[]` → `{value, label}`，value 为 protobuf 枚举（常见 4=1080P、5=1440P、6=2160P）。**`generate image --resolution` 用这里的 value**\n- `kontext_config.support_resolutions` → 旧档位 0=1K / 1=2K / 2=4K（兼容已有脚本，新调用不要再用）\n- `infer_quality_options[]` → 推理质量选项（可能为空）。非空时才可传 `--quality=`（如 `high`/`medium`/`low`）；空列表时不要传 `--quality`\n\n### 2.2 纯文生图\n\n```bash\nworkrally generate image \\\n --prompt \"一只橘猫坐在樱花树下\" \\\n --model \\\n --aspect-ratio 16:9 \\\n --poll\n```\n\n### 2.3 参考图生图\n\n通过 `--input-images` 传入参考主体图片 URL，在 prompt 中用 \"第一张图片\"、\"第二张图片\" 引用：\n\n```bash\nworkrally generate image \\\n --prompt \"第一张图片趴在第二张图片路中间\" \\\n --model \\\n --input-images \"https://cat.png,https://shrine.png\" \\\n --poll\n```\n\n> 📌 `--input-images` 的最大数量取决于模型配置中的 `kontext_config.max_input_images`，不要写死。\n> 📌 **只允许图片类型的素材**作为参考图。\n\n### 2.4 在画布中生图\n\n```bash\nworkrally generate image \\\n --prompt \"描述\" \\\n --model \\\n --project-id <画布ID> \\\n --poll\n```\n\n传入 `--project-id`（画布 ID）后：\n- 系统会**自动**在画布中创建 running 状态的占位节点（橙色边框 + 进度条）\n- **无需**再手动调用 `build-draft` 放置生成器节点\n- 生成完成后，前端自动更新节点状态\n\n> ⚠️ `--project-id` 此处是**画布 ID**（通过 `canvas list` 获取），**不是项目 ID**！\n\n### 2.5 参数说明\n\n| 参数 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--prompt` | ✅ | — | 图片描述 |\n| `--model` | ✅ | — | 模型 ID（从 `image-models` 获取） |\n| `--aspect-ratio` | — | `16:9` | 宽高比 |\n| `--resolution` | — | 模型首个可用 | **推荐** protobuf 枚举，取值来自 `image-models` 的 `resolution_options[].value`（常见 4=1080P、5=1440P、6=2160P）。兼容旧档位 0=1K、1=2K、2=4K。⚠️ 生图的 1/2 仍是 2K/4K，不是视频的 480P/540P |\n| `--quality` | — | 不下发 | 推理质量。取值必须来自该模型 `infer_quality_options[].value`；列表为空时不要传 |\n| `--count` | — | `1` | 生成数量 1-4（后端一个任务生成 1 张，count>1 会并发发起 N 个独立任务并返回 task_ids 数组） |\n| `--input-images` | — | — | 参考图 URL（逗号分隔） |\n| `--project-id` | — | — | 画布 ID（传入后自动创建占位节点） |\n| `--short-series-project-id` | — | — | 项目 ID |\n| `--name` | — | — | 素材名称 |\n| `--extra-params` | — | — | JSON 对象。CLI 传 MCP `extraParams`；服务端写入 `graph_input.extra_params` 且将每个 value 序列化为字符串。例如 MJ：`'{\"midjourney\":{\"stylize\":100}}'`。不要在 CLI 侧再 stringify 一层 |\n| `--poll` | — | false | 自动轮询直到完成 |\n| `--poll-interval` | — | `3` | 轮询间隔（秒） |\n\n---\n\n## 3. 视频生成\n\n### 3.1 获取可用模型配置\n\n```bash\nworkrally generate video-models -o json\n```\n\n返回按**驱动模式**分组：\n- `text_providers[]` — Text（单图/纯文）模式\n- `first_last_frame_providers[]` — 首尾帧模式\n- `subject_to_video_providers[]` — 参考主体模式\n- `video_edit_providers[]` — 视频编辑模式（VideoEdit）\n- `smart_edit_providers[]` — 智能编辑模式（SmartEdit）\n\n参考主体模型还可能返回 `extend_duration_range`、`extend_video_max_duration`、文档限制与 `support_erase_subtitles`；只在配置明确支持时使用。\n\n每个模型包含：\n- `provider` → 传给 `--model` 参数\n- `label` — 模型显示名称\n- `duration_options[]` — 可用时长列表（秒）\n- `resolution_options[]` — 支持的分辨率列表（`{value, label}`，value 为 protobuf 枚举值），传给 `--resolution`\n- `can_upload_image/video/audio` — 支持的输入类型\n- `max_image_count/video_count/audio_count` — 各类型最大数量\n- `support_audio` — 是否支持音效\n\n### 3.2 四种驱动模式\n\n#### Text 模式（默认）— 纯文生视频 / 单图驱动\n\n```bash\n# 纯文生视频（不传图片）\nworkrally generate video \\\n --prompt \"夕阳下海浪拍打沙滩\" \\\n --model \\\n --poll\n\n# 图生视频（传入参考图）\nworkrally generate video \\\n --prompt \"图片中的角色缓缓转身\" \\\n --model \\\n --single-image-url \"https://example.com/character.png\" \\\n --poll\n```\n\n#### FirstLastFrame 模式 — 首尾帧驱动\n\n```bash\nworkrally generate video \\\n --mode FirstLastFrame \\\n --prompt \"角色从左走到右\" \\\n --model \\\n --first-frame-url \"https://example.com/start.png\" \\\n --last-frame-url \"https://example.com/end.png\" \\\n --poll\n```\n\n> 可以只传首帧或只传尾帧（至少一个）。\n\n#### VideoEdit 模式 — 视频编辑\n\n`model` 必须来自 `video-models` 的 `video_edit_providers[]`。必须传 `--origin-video <原视频素材ID>`（asset_id，不是 URL）。此模式 **不要** 传 `--enable-sound` / `--no-enable-sound`（下游 graph_input 不带该字段）。\n\n```bash\nworkrally generate video \\\n --mode VideoEdit \\\n --prompt \"将背景替换成蓝天\" \\\n --model \\\n --origin-video \\\n --poll\n```\n\n#### SubjectToVideo 模式 — 参考主体驱动\n\n```bash\nworkrally generate video \\\n --mode SubjectToVideo \\\n --prompt \"角色在场景中行走\" \\\n --model \\\n --reference-assets '[{\"type\":\"image\",\"url\":\"https://character.png\"},{\"type\":\"video\",\"url\":\"https://bg.mp4\"}]' \\\n --poll\n```\n\n### 3.3 通用选项\n\n| 参数 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--prompt` | 通常必填 | — | SmartEdit/ExtendVideo 可省略 |\n| `--model` | ✅ | — | Provider ID（从 `video-models` 获取） |\n| `--mode` | — | `Text` | Text/FirstLastFrame/SubjectToVideo/VideoEdit/SmartEdit/ExtendVideo |\n| `--aspect-ratio` | — | `16:9` | 宽高比: 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 等 |\n| `--resolution` | — | 模型首个可用 | 分辨率枚举: 1=480P 2=540P 3=720P 4=1080P 5=1440P 6=2160P 7=4320P 8=360P（具体支持见 `video-models` 的 `resolution_options`） |\n| `--duration` | — | — | 视频时长（秒），可选值取决于模型 |\n| `--count` | — | `1` | 生成数量 1-4（后端一个任务生成 1 个视频，count>1 会并发发起 N 个独立任务并返回 task_ids 数组） |\n| `--enable-sound` | — | 服务端默认 true | 生成音效（仅部分模型支持）。**不传则默认开启**（与前端一致）；关闭请用 `--no-enable-sound`。VideoEdit 不要传 |\n\nSmartEdit 需传 `--source-video/--source-width/--source-height/--source-duration`；`source-duration` 单位毫秒。ExtendVideo 的 `--duration` 表示延长秒数。Wan 3.0 文档参考仅 SubjectToVideo 支持，`--reference-assets` 中传 `{\"type\":\"file\",\"asset_id\":\"...\",\"name\":\"brief.pdf\"}`。\n| `--no-enable-sound` | — | — | 显式关闭音效（`enable_sound=false`） |\n| `--extra-params` | — | — | JSON 对象。CLI 传 MCP `extraParams`；服务端写入 `graph_input.extra_params` 且将每个 value 序列化为字符串 |\n| `--project-id` | — | — | 画\n\nArchive v2.7.0: 10 files, 30823 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1616b), references/ai-generation-guide.md (14311b), references/canvas-guide.md (10823b), references/common-pitfalls.md (8594b), references/shotlist-guide.md (9331b), references/upload-and-assets-guide.md (8027b), skill-card.md (2448b), SKILL.md (16614b), _meta.json (128b)\n\nArchive v2.6.2: 11 files, 39182 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1588b), references/ai-generation-guide.md (13877b), references/canvas-guide.md (10823b), references/common-pitfalls.md (8572b), references/shot-guide.md (22476b), references/shotlist-guide.md (9611b), references/upload-and-assets-guide.md (8027b), skill-card.md (2627b), SKILL.md (17282b), _meta.json (128b)\n\nArchive v2.6.1: 11 files, 38793 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1588b), references/ai-generation-guide.md (12918b), references/canvas-guide.md (10823b), references/common-pitfalls.md (8486b), references/shot-guide.md (22476b), references/shotlist-guide.md (9611b), references/upload-and-assets-guide.md (8027b), skill-card.md (2720b), SKILL.md (17079b), _meta.json (128b)\n\nArchive v2.4.1: 10 files, 31236 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1527b), references/ai-generation-guide.md (9148b), references/canvas-guide.md (10823b), references/common-pitfalls.md (6943b), references/shot-guide.md (22010b), references/upload-and-assets-guide.md (8027b), skill-card.md (2854b), SKILL.md (12754b), _meta.json (128b)\n\nArchive v2.4.0: 10 files, 31017 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1380b), references/ai-generation-guide.md (9102b), references/canvas-guide.md (10823b), references/common-pitfalls.md (6943b), references/shot-guide.md (22010b), references/upload-and-assets-guide.md (8027b), skill-card.md (2700b), SKILL.md (12623b), _meta.json (128b)\n\nArchive v2.3.1: 8 files, 20858 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1380b), references/ai-generation-guide.md (9102b), references/canvas-guide.md (10823b), references/common-pitfalls.md (6943b), references/upload-and-assets-guide.md (8027b), SKILL.md (9403b), _meta.json (128b)\n\nArchive v2.3.0: 8 files, 20826 bytes\n\nFiles: LICENSE.txt (1128b), README.md (1380b), references/ai-generation-guide.md (8988b), references/canvas-guide.md (10823b), references/common-pitfalls.md (6943b), references/upload-and-assets-guide.md (8027b), SKILL.md (9403b), _meta.json (128b)","readmeExcerpt":"Skill: WorkRally Owner: tencent-adm Summary: WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npm install -g workrally\n\n# 配置登录。Agent / CI 只用 API Key，不要自己实现 OAuth，也不要请求 127.0.0.1 回调。\nworkrally auth login --token # Agent / CI\nexport WORKRALLY_API_KEY= # 环境变量优先于配置文件\nworkrally auth login # 仅人在本机终端使用，CLI 自己打开浏览器\n# ↑ auth login 自动将 Token 写入配置文件：\n# 若 WORKRALLY_CONFIG_DIR 已设置 → $WORKRALLY_CONFIG_DIR/config.json\n# 否则 → ~/.workrally/config.json\n\nworkrally auth status # 验证登录状态"},{"language":"bash","snippet":"# === 项目（project）— list / get / create / update / delete ===\nworkrally project list [--search \"关键词\"] # 列出/搜索项目\nworkrally project get # 项目详情\nworkrally project create \"项目名\" # 创建项目\nworkrally project update --name \"新名称\" # 更新项目\nworkrally project delete # 软删除（→回收站；恢复请到 Web）\n\n# === 剧集（series）— 全新命令组（CRUD 完整） ===\nworkrally series list --project-id # 剧集列表\nworkrally series get --project-id # 剧集详情\nworkrally series create --project-id --name \"第一集\" # 创建剧集\nworkrally series update --project-id --name \"新名称\" # 更新剧集\nworkrally series delete # 软删除（→回收站）\n\n# === 场次（shotlist）— 对齐 Web /shot 批量制作（含音频生成）===\n# --- CRUD ---\nworkrally shotlist list --series-id # 场次列表\nworkrally shotlist get # 场次详情\nworkrally shotlist create --series-id --json-list '[{\"image_prompt\":\"...\"}]' # 批量创建\nworkrally shotlist update --image-prompt \"...\" --animation-prompt \"...\" # 单条更新\nworkrally shotlist update --batch '[{\"story_id\":\"...\",\"image_prompt\":\"...\"}]' # 批量更新\nworkrally shotlist delete # 软删除（→回收站）\nworkrally shotlist sort --series-id --order id1,id2,id3 # 重排\n# --- 模型 & 配置（写入 extra.gen_config）---\nworkrally shotlist models --category image,video,videoSmartEdit,upscale,audio # ⭐ 统一模型列表\nworkrally shotlist set-model [--story-ids id1,id2] --image-model --image-aspect-ratio 16:9 [--image-quality high] [--mj-params '{}']\nworkrally shotlist set-model [--story-ids id1,id2] --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9\nworkrally shotlist set-model [--story-ids id1,id2] --extra-mode extendVideo --extend-source-id --project-id -o json\n# 步骤 3（按需）: 挂载到资产库（必传 asset_id + 完整 asset_details）\nworkrally material add --json-list '[{\"material_id\":\"\",\"material_name\":\"名称\",\"material_type\":2,\"parent_id\":\"\",\"material_detail\":}]' \\\n --project-ids "},{"language":"bash","snippet":"# 1) 建剧集 + 批量创建场次（按用户意图填提示词）\nworkrally series create --project-id --name \"第一集\" -o json\nworkrally shotlist create --series-id --json-list '[{\"image_prompt\":\"古风庭院\",\"animation_prompt\":\"镜头缓推\"}]'\n\n# 2) 识别角色资产（三路：image/animation/audio；音色用 <> 时加 --match-rule symbol_text）\nworkrally shotlist recognize --series-id --project-id \n\n# 3) 选模型 → 写配置（模型 id 来自 shotlist models，勿硬编码）\nworkrally shotlist models --category image,video,audio -o json\nworkrally shotlist set-model --series-id --image-model --image-aspect-ratio 16:9 \\\n --video-mode SubjectToVideo --video-model --duration 5 --video-aspect-ratio 16:9 --audio-model \n\n# 4) 生成（多场次传 --story-ids id1,id2,id3；均需 --project-id）\nworkrally shotlist generate-image --project-id --story-ids \nworkrally shotlist generate-video --project-id --story-ids \nworkrally shotlist generate-audio --project-id --story-ids \n\n# 5) 查结果（image/video/audio 三条独立进度，分别 watch）\nworkrally shotlist get-result --story-id --type image --watch\nworkrally shotlist get-result --story-id --type video --watch\nworkrally shotlist get-result --story-id --type audio --watch"},{"language":"text","snippet":"skill/\n├── SKILL.md ← Skill 入口（元数据 + 指令），ClawHub 解析此文件\n├── LICENSE.txt ← 许可证\n└── references/ ← 深度参考文档，AI Agent 按需加载\n ├── ai-generation-guide.md AI 生成指南\n ├── canvas-guide.md 无限画布操作指南\n ├── common-pitfalls.md 常见易错点\n ├── shotlist-guide.md 场次批量制作（对齐 Web /shot）\n └── upload-and-assets-guide.md 上传与素材管理指南"},{"language":"bash","snippet":"npm install -g workrally\nworkrally auth login\nworkrally auth status"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: workrally\nslug: workrally\ndisplayName: WorkRally\ndisplay_name: WorkRally\ndisplay_name_en: WorkRally\ndescription: WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with WorkRally platform via command line.\ndescription_zh: 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集，支持 AI 生图/生视频/生音频、项目剧集场次管理、资产库与无限画布。\ndescription_en: End-to-end AIGC comic-drama creation toolkit for AI Agents—image/video/audio generation, project/series/shot management, asset library, and infinite canvas.\ntags: [AIGC, CLI, 漫剧, 生图, 生视频, 生音频, 项目, 剧集, 场次, 画布, 资产库]\nversion: 2.10.1\nlicense: MIT-0\nauthor: WorkRally Team\nhomepage: https://workrally.qq.com\nuser-invocable: true\nmetadata: {\"openclaw\":{\"emoji\":\"🎬\",\"requires\":{\"bins\":[\"workrally\"],\"env\":[\"WORKRALLY_API_KEY\",\"WORKRALLY_ENDPOINT\",\"WORKRALLY_CONFIG_DIR\",\"WORKRALLY_NO_UPDATE_CHECK\"]},\"primaryEnv\":\"WORKRALLY_API_KEY\",\"credentials\":{\"storage\":\"~/.workrally/config.json\",\"configDirEnv\":\"WORKRALLY_CONFIG_DIR\",\"description\":\"workrally auth login 写入的登录态：API Key，或 OAuth access/refresh token，以及 endpoint。非持久化容器中可通过 WORKRALLY_CONFIG_DIR 环境变量指定配置目录\"},\"install\":[{\"id\":\"npm\",\"kind\":\"node\",\"package\":\"workrally\",\"bins\":[\"workrally\"],\"label\":\"Install WorkRally CLI (npm)\"}],\"category\":\"AIGC\",\"tags\":[\"workrally\",\"aigc\",\"cli\",\"video-generation\",\"image-generation\",\"ai-tools\",\"story\",\"shot\",\"series\"]}}\n---\n\n# WorkRally CLI (workrally)\n\n面向 AI Agent 的 AIGC 漫剧视频创作全流程命令行工具，封装 WorkRally 平台 30+ 核心能力，支持项目/剧集/场次的完整 CRUD、AI 生图/生视频、画布、资产库、媒资管理、文件上传等。\n\n## 安装 & 配置\n\n```bash\nnpm install -g workrally\n\n# 配置登录。Agent / CI 只用 API Key，不要自己实现 OAuth，也不要请求 127.0.0.1 回调。\nworkrally auth login --token # Agent / CI\nexport WORKRALLY_API_KEY= # 环境变量优先于配置文件\nworkrally auth login # 仅人在本机终端使用，CLI 自己打开浏览器\n# ↑ auth login 自动将 Token 写入配置文件：\n# 若 WORKRALLY_CONFIG_DIR 已设置 → $WORKRALLY_CONFIG_DIR/config.json\n# 否则 → ~/.workrally/config.json\n\nworkrally auth status # 验证登录状态\n```\n\nAPI Key 申请：[龙虾配置](https://workrally.qq.com/open-api)\n\n## 命令速查\n\n```bash\n# === 项目（project）— list / get / create / update / delete ===\nworkrally project list [--search \"关键词\"] # 列出/搜索项目\nworkrally project get # 项目详情\nworkrally project create \"项目名\" # 创建项目\nworkrally project update --name \"新名称\" # 更新项目\nworkrally project delete # 软删除（→回收站；恢复请到 Web）\n\n# === 剧集（series）— 全新命令组（CRUD 完整） ===\nworkrally series list --project-id # 剧集列表\nworkrally series get --project-id # 剧集详情\nworkrally series create --project-id --name \"第一集\" # 创建剧集\nworkrally series update --project-id ⚠️ **模型 ID 必须动态获取，严禁猜测或硬编码！**\n> 模型列表是动态下发的，不同环境（开发/预发/正式）的可用模型可能完全不同。\n\n> 🔒 所有 URL 类参数仅接受 WorkRally 官方媒资 URL，详见 SKILL.md 规则 9。\n\n```bash\n# 生图前必须先获取模型列表\nworkrally generate image-models -o json\n\n# 生视频前必须先获取模型配置\nworkrally generate video-models -o json\n\n# 提示词优化前必须先获取 gen_content 模型列表\nworkrally generate content-models -o json\n\n# 画布生音频/音乐前必须先获取模型\nworkrally generate audio-models -o json\n```\n\n---\n\n## 2. 图片生成 (Kontext)\n\n### 2.1 获取可用模型\n\n```bash\nworkrally generate image-models -o json\n```\n\n返回包含：\n- `models[]` — 每个模型的 `model_id`、`name`、`resolution_options`、`kontext_config`、`infer_quality_options`\n- `aspect_ratios[]` — 全局可用宽高比列表（如 \"1:1\", \"16:9\", \"9:16\" 等）\n- `resolution_options[]` — 所有模型支持的 protobuf 分辨率并集（**推荐**，传给 `--resolution`）\n- `resolutions[]` — 旧档位 0/1/2 并集（兼容）\n- `count_options[]` — 可选的生成数量\n\n**关键字段**：\n- `model_id` → 传给 `--model` 参数\n- `kontext_config.max_input_images` → 该模型允许的最大参考图数量（不同模型不同，不要写死）\n- `resolution_options[]` → `{value, label}`，value 为 protobuf 枚举（常见 4=1080P、5=1440P、6=2160P）。**`generate image --resolution` 用这里的 value**\n- `kontext_config.support_resolutions` → 旧档位 0=1K / 1=2K / 2=4K（兼容已有脚本，新调用不要再用）\n- `infer_quality_options[]` → 推理质量选项（可能为空）。非空时才可传 `--quality=`（如 `high`/`medium`/`low`）；空列表时不要传 `--quality`\n\n### 2.2 纯文生图\n\n```bash\nworkrally generate image \\\n --prompt \"一只橘猫坐在樱花树下\" \\\n --model \\\n --aspect-ratio 16:9 \\\n --poll\n```\n\n### 2.3 参考图生图\n\n通过 `--input-images` 传入参考主体图片 URL，在 prompt 中用 \"第一张图片\"、\"第二张图片\" 引用：\n\n```bash\nworkrally generate image \\\n --prompt \"第一张图片趴在第二张图片路中间\" \\\n --model \\\n --input-images \"https://cat.png,https://shrine.png\" \\\n --poll\n```\n\n> 📌 `--input-images` 的最大数量取决于模型配置中的 `kontext_config.max_input_images`，不要写死。\n> 📌 **只允许图片类型的素材**作为参考图。\n\n### 2.4 在画布中生图\n\n```bash\nworkrally generate image \\\n --prompt \"描述\" \\\n --model \\\n --project-id <画布ID> \\\n --poll\n```\n\n传入 `--project-id`（画布 ID）后：\n- 系统会**自动**在画布中创建 running 状态的占位节点（橙色边框 + 进度条）\n- **无需**再手动调用 `build-draft` 放置生成器节点\n- 生成完成后，前端自动更新节点状态\n\n> ⚠️ `--project-id` 此处是**画布 ID**（通过 `canvas list` 获取），**不是项目 ID**！\n\n### 2.5 参数说明\n\n| 参数 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--prompt` | ✅ | — | 图片描述 |\n| `--model` | ✅ | — | 模型 ID（从 `image-models` 获取） |\n| `--aspect-ratio` | — | `16:9` | 宽高比 |\n| `--resolution` | — | 模型首个可用 | **推荐** protobuf 枚举，取值来自 `image-models` 的 `resolution_options[].value`（常见 4=1080P、5=1440P、6=2160P）。兼容旧档位 0=1K、1=2K、2=4K。⚠️ 生图的 1/2 仍是 2K/4K，不是视频的 480P/540P |\n| `--quality` | — | 不下发 | 推理质量。取值必须来自该模型 `infer_quality_options[].value`；列表为空时不要传 |\n| `--count` | — | `1` | 生成数量 1-4（后端一个任务生成 1 张，count>1 会并发发起 N 个独立任务并返回 task_ids 数组） |\n| `--input-images` | — | — | 参考图 URL（逗号分隔） |\n| `--project-id` | — | — | 画布 ID（传入后自动创建占位节点） |\n| `--short-series-project-id` | — | — | 项目 ID |\n| `--name` | — | — | 素材名称 |\n| `--extra-params` | — | — | JSON 对象。CLI 传 MCP `extraParams`；服务端写入 `graph_input.extra_params` 且将每个 value 序列化为字符串。例如 MJ：`'{\"midj"},{"path":"references/canvas-guide.md","content":"# 无限画布操作指南\n\n本文档帮助 AI Agent 正确操作 WorkRally 无限画布（Infinite Canvas）。画布基于 Yjs 协同编辑引擎，CLI 写入的内容会**实时同步**给所有在线用户，无需刷新页面。\n\n---\n\n## 1. 核心概念\n\n### 两种\"项目\"（容易混淆，务必区分）\n\n| 概念 | 管理命令 | 用途 | 必要性 |\n|------|---------|------|--------|\n| **项目** (project) | `workrally project list/create/get` | 所有素材都必须归属一个项目，范围更大 | **必须** — 素材不关联项目则在 web 端不可见 |\n| **画布** (canvas) | `workrally canvas list/create/get` | 无限画布空间，可在其中排布节点 | **可选** — 仅当用户要在画布中操作时才需要 |\n\n> ⚠️ **两者的 ID 不能互相替代！**\n> - `workrally project list` 返回的是项目 ID\n> - `workrally canvas list` 返回的是画布 ID\n> - 在画布场景下，素材需要**同时关联两者**\n\n### 判断用户意图\n\n| 用户说 | 含义 | 使用命令 |\n|--------|------|---------|\n| \"我的项目\"、\"项目列表\" | 项目 | `workrally project list` |\n| \"我的画布\"、\"画布列表\" | 无限画布 | `workrally canvas list` |\n| \"在画布上生成图片\" | 画布 + AI 生成 | `workrally generate image --project-id <画布ID>` |\n| \"上传到项目\" | 仅入媒资库 | `upload` → `asset create` |\n| \"在画布上展示素材\" | 需要 build-draft | `upload` → `asset create` → `canvas build-draft` |\n\n---\n\n## 2. 画布节点类型 (8 种)\n\n### 类型一览\n\n| type | 说明 | 必填 data 字段 | 可放入画板 |\n|------|------|---------------|-----------|\n| `image` | 图片素材 | `data.asset.id` (已有素材) 或 `data.task` (生成中占位) | ✅ |\n| `video` | 视频素材 | `data.asset.id` 或 `data.task` | ✅ |\n| `audio` | 音频素材 | `data.asset.id` (**必须**，音频无生成器) | ✅ |\n| `imageGenerator` | 图片生成器 | 无必填（params 可选） | ❌ |\n| `videoGenerator` | 视频生成器 | 无必填（params 可选） | ❌ |\n| `artboard` | 画板容器 | 无（建议设置 `style.width/height`） | ❌ (画板不可嵌套) |\n| `text` | 文本 | `data.text.content` (字符串，最大90000字符) | ❌ |\n| `freehand` | 画笔涂鸦 | `data.freehand.points` + `data.freehand.initialSize` | ❌ |\n\n### 节点通用结构\n\n```json\n{\n \"id\": \"node_unique_id\",\n \"type\": \"image\",\n \"position\": { \"x\": 100, \"y\": 200 },\n \"data\": { },\n \"style\": { \"width\": 512, \"height\": 512 },\n \"parentId\": \"artboard_id\",\n \"measured\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n**字段说明**：\n- `id` — 节点唯一标识，可使用任意唯一字符串\n- `position` — 节点左上角坐标（缺失时堆叠在原点 0,0）\n- `style` — 节点显示尺寸\n- `parentId` — 仅画板内子节点需要，指向父画板的 id\n- `measured` — 渲染尺寸，可选，缺失时服务端自动补全\n\n---\n\n## 3. 各节点类型详细说明\n\n### 3.1 图片/视频节点 (image / video)\n\n两种来源：\n1. **已有素材** — 必须有 `data.asset.id`\n2. **生成中占位** — 必须有 `data.task`（由 AI 生成命令自动创建，通常不需要手动构造）\n\n```json\n{\n \"id\": \"img_001\",\n \"type\": \"image\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_abc123\" }\n },\n \"style\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n**带生成任务标记的节点**（用于\"再次编辑\"功能）：\n```json\n{\n \"id\": \"gen_img_001\",\n \"type\": \"image\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_abc123\" },\n \"task\": { \"taskId\": \"task_xyz789\", \"status\": \"success\" }\n },\n \"style\": { \"width\": 512, \"height\": 512 }\n}\n```\n\n> 💡 `data.task` 字段决定前端是否显示\"再次编辑\"按钮。AI 生成的图片/视频应包含此字段。\n\n### 3.2 音频节点 (audio)\n\n音频**没有生成器**，不支持 task 占位，必须有 `data.asset.id`。\n\n```json\n{\n \"id\": \"audio_001\",\n \"type\": \"audio\",\n \"position\": { \"x\": 0, \"y\": 0 },\n \"data\": {\n \"asset\": { \"id\": \"asset_audio_456\" }\n },\n \"style\": { \"width\": 260, \"height\": 80 }\n}\n```\n\n> 建议尺寸 **260×80**（与前端默认一致）。\n\n### 3.3 画板节点 (artboard)\n\n画板是**容器**，子节点通过 `parentId` 关联到画板。\n\n```json\n{\n \"id\": \"board_001\",\n \"type\""}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with WorkRally platform via command line. Skill: WorkRally Owner: tencent-adm Summary: WorkRally CLI (workrally) — 面向 AI Agent 的 AIGC 漫剧视频创作全流程工具集。支持 AI 生图、AI 生视频、视频提示词优化、画布生音频/音乐、混元 3D 模型生成、AI 生音频、项目/剧集/场次/分镜的完整 CRUD、资产库、媒资管理、无限画布、文件上传下载等。Use when user asks to generate images, generate videos, generate audio, generate music, generate 3d, optimize video prompts, manage projects, series, shots, upload files, download assets, manage materials, or interact with","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":979,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T21:38:55.672Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T21:38:55.672Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:39:39.007Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}