@uzooai/anime-ai-cli 0.0.0-stage → 0.6.0

package/.agents/skills/uzoo-anime-cli/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: uzoo-anime-cli
+description: Use Uzoo Anime CLI for canvas and node operations, material upload and library reuse, image cropping, annotation and background removal, video trimming and frame capture, Seedance material review, segment remakes, authorized ordinary generation and recovery through the Anime AI Engine API.
+---
+
+# Uzoo Anime CLI
+
+Video repaint is paused. Use retained commands only when explicitly asked to inspect or download an existing result or diagnose an existing failure. Do not submit a new task or write to a canvas as part of that inspection. Segment remake is separate.
+
+Historical video repaint scope was the canvas workflow only. The separate 视频转绘 page and its standalone generation-preparation/material-selection flow are not integrated and are not planned for implementation now. Shared API helpers or historical upload tests do not establish page support.
+
+Use `uzoo-anime --version` for the installed version and `uzoo-anime skill path` to locate this bundled skill; both are local and need no login. Plain npm installation or upgrading does not register or update a separately copied host skill. The optional `install` command can install the CLI and its matching skill into user-selected local hosts; use `install --help` or `install --dry-run` for discovery. Do not invoke installation automatically for a creative task.
+
+Use the installed `uzoo-anime` command. Read only the references needed for the task.
+
+## Check for updates
+
+On first actual use in a conversation, read `uzoo-anime --version` and, unless the user opts out or an operation is already in progress, query the public stable version with `npm view @uzooai/anime-ai-cli@latest version --json --registry=https://registry.npmjs.org/ --fetch-retries=0 --fetch-timeout=5000`. Compare as semantic versions. Do this at most once per conversation unless asked to check again. If the query fails or there is no newer stable version, continue normally without blocking the user's task.
+
+If a newer stable version exists, show the installed and available versions and let the user choose to keep using the current version or update. Use a host choice card when available. No answer is not consent. Before any installation, confirm the exact version and whether to update only the CLI or also the selected Agent Skills. Use the confirmed version in the npm command; never switch channels or overwrite a modified Skill without the user's decision. If an operation is active or its outcome is unknown, finish or reconcile it first. After updating, verify the CLI version and, if selected, the host Skill; keep the same profile and operation records.
+
+| Task | Reference |
+|---|---|
+| Missing user choices, interactive cards, cost confirmation and continuing the same task | [Shared interaction workflow](references/interaction-workflow.md) — read for every real task |
+| Command arguments, JSON fields, output and errors | [Commands](references/commands.md) |
+| Timeouts, disconnects, gateway errors or internal API errors | Run service status first, then query the original operation; [Commands](references/commands.md#后端连接与异常排查) |
+| Download originals, signed-reference renewal or download permission errors | [Commands](references/commands.md#下载与文件凭证) |
+| Personal/team space, canvas discovery and creation | [Canvas workflow](references/canvas-workflow.md) |
+| Create or update ordinary nodes | [Node workflow](references/node-workflow.md) |
+| Explain node purposes, toolbar tools or missing CLI features | [Node capabilities](references/node-capabilities.md) |
+| Upload, save node results to library, reuse assets, download material originals, arrange/group and connect nodes | [Material and graph workflow](references/material-graph-workflow.md) |
+| Prepare references, estimate, generate, synchronize/recover results, finalize an existing Seedance draft, or select/add ordinary image/video history | [Generation workflow](references/generation-workflow.md) |
+| Automatically apply sd25-pe while preparing Seedance 2.5 video generation; no explicit skill invocation needed | [Prompt handoff](references/generation-workflow.md#seedance-25提示词优化sd25-pe) |
+| Explicit Seedance image/video material review, status and recovery | [Material review workflow](references/seedance-review-workflow.md) |
+| Account consent, first use/updated agreement or API code 4401 | [Agreement workflow](references/agreement-workflow.md) |
+| Paused repaint: historical behavior, or explicitly requested original-result query/download and diagnosis | [Repaint workflow](references/repaint-workflow.md) |
+| Derive a segment remake configuration, estimate and authorize one remake, query/sync its independent result | [Remake workflow](references/remake-workflow.md) |
+| Trim an existing video or capture 1–3 frames, save material nodes and recover | [Video tools workflow](references/video-tools-workflow.md) |
+| Crop/annotate an existing image, or remove its background and recover a known result | [Image tools workflow](references/image-tools-workflow.md) |
+
+## Authentication
+
+- Prefer `auth login`: it opens the normal website for the user to sign in and explicitly approve a separate CLI session; no extension or token copying is needed. This requires the matching 3A frontend and backend to be deployed and enabled. `auth import` remains a legacy manual fallback.
+- `auth login-url` only prints a website URL; it does not start an authorization request or callback listener.
+- Keep access and refresh tokens out of prompts, logs, commits, and generated reports.
+- The CLI obtains the short-lived S1 signing session from `/auth/sign-session` and keeps the signing secret in memory only.
+
+## Workflow
+
+For every real task, follow the [shared interaction workflow](references/interaction-workflow.md). Use available host cards for missing canvas/model/parameter/material/plan decisions and each cost approval. Keep the task pending while awaiting input; do not end with a final response asking for confirmation. Never treat a preselection, silence or timeout as consent. Reuse explicit choices; ordinary non-billable commands need no repeated permission.
+
+Before CLI canvas operations, confirm that the target canvas browser tabs are closed, following [canvas tab closure confirmation](references/interaction-workflow.md#画布标签关闭确认). This temporary user-required workaround applies until the frontend conflict fix is verified; pausing editing or returning to the workspace is insufficient. Reuse an explicit confirmation within the same uninterrupted task. Read-only queries and standalone material downloads do not need this confirmation.
+
+Consult the capability reference before proposing a web tool as a CLI action. Implementation, frontend compatibility and live acceptance are separate states. Account consent and material review are separate workflows.
+
+Team balances are shared by team members; ordinary members can see only their own consumption records. Other members can reduce the balance while the current account submits nothing and has no new visible charge. Report the current task's actual billing separately from the shared balance snapshot; follow [team wallet verification](references/generation-workflow.md#团队共享钱包与费用核验). A balance delta does not establish this CLI task's cost, and an unchanged balance does not resolve an unknown submission.
+
+For features requiring local tools, check their declared dependencies before processing and reuse installed tools or provided paths. If tools are missing, explain the names/purpose and a concrete installation source/scope, then ask whether to install and continue. Wait for explicit consent before installation; a task request or processing `--yes` does not authorize installation. Reuse an existing explicit approval for the same installation. Respect host execution approvals. After installation, recheck tools and continue the original task/operation at its known stage; keep paid-generation and unknown-upload recovery constraints. If declined, leave this feature pending. Execution/format/permission errors are not proof of missing dependencies. Current local-tool requirements and the installation flow are in [video tools](references/video-tools-workflow.md#本机依赖与按需安装).
+
+When a service operation fails, check backend connectivity/readiness before attributing it to a feature. Keep the original HTTP/API error and request ID; a healthy probe now does not prove the earlier request succeeded or failed without side effects. Never replay a write just because connectivity recovered. Use the original operation recovery contract.
+
+Follow the currently supported website behavior for node controls, parameter defaults, reference filtering and workflow order. Model discovery supplies current values and capability limits; a catalog/admin/provider field alone does not establish a user control. Do not invent controls such as `generate_audio`. Use only parameters already supported by this CLI's implementation of the web flow; report missing routes as unavailable/pending. The CLI runs independently through APIs and must not require the website to remain open. Maintainers verify frontend behavior during development; installed users do not need frontend source access.
+
+Saving a generation/processing result to the canvas does not save it to the material library. Do not add automatic library saving after generation, review, trimming or recovery. Enter material save only when the user requests it or its test; reuse a confirmed space, but require the user to choose the destination folder or explicitly delegate that choice. Discover folder IDs from the actual list; if the choice is missing, ask even when a title or sole candidate seems suitable. Reuse an already explicit choice without asking again. Library-to-canvas import is another separate action and does not follow saving automatically.
+
+1. Reuse the current service and profile. Set the API base URL only if needed with `config set --base-url <url>`; do not assume a development URL or require a local frontend for installed users.
+2. Check `auth status` and reuse valid credentials. Only if login is needed, run `auth login`; let the user complete normal website login and explicitly approve the CLI request. Do not automate CAPTCHA or SMS verification or suppress the site's environment checks. Never ask them to paste credentials into chat.
+3. Before business discovery or writes, ask whether to use personal or team space unless the user already chose it for this task. Do not infer personal space from missing flags or an empty list. For team space, resolve the user's choice against actual account `teams`; if there is only one available team, announce and use it; if several remain possible, show names/UIDs and ask which. No available team means stop, not fallback to personal. Confirm a project only when relevant, never guess its ID. Keep the confirmed choice for this task; ask again when the user switches context.
+4. Follow the [canvas workflow](references/canvas-workflow.md) to list the chosen scope and ask via a card whether to create or use an existing canvas when the target is unspecified. For creation, obtain a name or explicit acceptance of the suggested name; then create once and read back ownership. A canvas-only request ends there: no model discovery, nodes, uploads or generation. For node creation, follow the [node workflow](references/node-workflow.md); directly create ordinary nodes only, and interpret “all nodes” as all ordinary node types. Derived nodes must come from a real workflow, not empty placeholders or injected roles. A node-only request ends after read-back verification, without requiring models or materials for empty ordinary nodes. For a generation request, use model options in that same space, collect the model and applicable settings through cards unless already specified or explicitly delegated, save the selected node configuration and run generation prepare. Do not hand-assemble an ordinary generation request to bypass preparation. Dedicated workflows use their own verified request builders. Use `node update` for input/position changes; read [commands](references/commands.md) for the node patch schema. Team model visibility and promotions can differ.
+5. Before node writes, upload, estimation, submission or recovery, read the target canvas and verify its team_uid matches the confirmed space/team (personal means no team_uid). Stop on mismatch; do not transfer ownership or silently switch wallets. A generation uses the canvas’s actual ownership, not a client billing override. After the user selects node parameters, use a confirmation card to show the space, team/project, personal or team wallet source and estimated OO cost and wait for the user’s confirmation for each submission. Changed parameters or price require confirmation again. Never retry a timed-out submission blindly.
+6. Poll an existing generation with `generation wait <id>` and download only after the task is completed.
+
+The following segmentation procedure is retained for historical maintenance and explicit future resumption only; it is not an active development or acceptance task while repaint is paused. Follow the repaint reference instead of improvising API calls or generic node writes. `repaint start` first persists a preview of the actual wallet and analysis fee; require explicit approval before `--yes`. Review the real segment plan before `repaint confirm --yes`, then wait for CLI to save the derived chain. A segment chain contains video generation nodes, not generated videos. Further paid actions need their own parameters, estimate and approval.
+
+Ask only for missing decisions that affect this task: space, ambiguous team/project, canvas name/target, relevant model parameters or materials, and each generation's cost approval. Reuse explicit choices and existing creation authorization. Group related missing questions; do not ask users for IDs the CLI can discover, irrelevant model choices for a canvas-only task, or repeated permission for already requested non-billable creation. Host execution approvals remain separate and must be respected.
+
+## Output
+
+Use `--format json` for agent workflows and preserve IDs, statuses, request errors, and URLs exactly. Use table output only for a human-facing quick check.
+
+## Limitations
+
+Business commands call HTTP APIs independently; browser authorization is separate. See the capability reference for unavailable tools and the repaint reference for single-segment video generation and the remaining prompt/reference/batch limits. Do not fabricate derived nodes or treat standalone generation as a completed derived workflow. Closing the website is supported; after CLI exits, submitted backend tasks can continue but canvas synchronization requires the corresponding wait/recover/sync command on the same profile and operation. Writes use full snapshots and version CAS: preserve other content, stop on conflicts or unknown results, and never rebuild a deleted node automatically. Audio generation is unsupported. Web and CLI sessions are separate; a new CLI login replaces the previous CLI session. Windows credentials use CurrentUser DPAPI; never fall back to plaintext. Keep the original operation during recovery. `--yes` means execute and requires the user's authorization.
+
+For background image matting, follow [the local worker workflow](references/image-tools-workflow.md#抠图独立后台执行与本地查询). The worker only caches the original response; use the same operation for local status and explicit canvas recovery. Background status is not a server task-progress or current canvas verification.
+
+For the new server-side matting job API, use [the asynchronous job workflow](references/image-tools-workflow.md#服务端异步抠图任务). Persist the received job_id in the original operation; matting-get queries the server, while matting-status remains local. Do not replay a submission whose response lost the job ID. Legacy local-worker operations keep their original recovery path.
+
+For asynchronous matting, recover with the original job and operation. Never resubmit when acceptance is unknown.

package/.agents/skills/uzoo-anime-cli/references/agreement-workflow.md

@@ -0,0 +1,41 @@
+# Seedance 视频协议签署与继续原任务
+
+用户决定、方案与费用确认统一遵循 [交互流程](interaction-workflow.md)：沿用已明确选择，缺项优先用卡片收集，等待回复后继续原任务；本路线的执行、签署与恢复边界仍按下文，不扩展功能。
+
+需要 Seedance 系列视频生成、接口返回 4401，或用户询问《统一协议》《Seedance2.0模型使用承诺书》时读取。本协议是生成提交前置条件；首次使用或运营更新协议版本后可能需要用户重新签署。以当前账号服务端 required/agreed/version 为准，不靠本机缓存或根据账号注册时间推断。
+
+## 正确识别与报告
+
+- `generation protocol-status` 只读查询 `/video/protocol-agreement`，保留 required、agreed、version；增加 status 与 api_code。required=true 且 agreed=false 时报告“等待签署《统一协议》中的《Seedance2.0模型使用承诺书》”，不报模型生成失败。
+- 后端拒绝响应可为 HTTP 200，业务 code=4401，data.protocol 带当前版本状态；不能因为 HTTP 200 就判成功，也不能丢掉错误码后当作网络断线或未知生成提交。
+- CLI 协议等待的结构化状态为 awaiting_agreement；退出码 7 表示签署未完成、被拒绝、超时或需要重新核对。TASK_FAILED 只用于已存在的任务执行失败。operation 的 blocked_agreement 不代表后台已有视频任务。
+- 费用确认与协议签署分别处理。Agent 不勾选、不代填 protocol_agreed，不因用户确认 OO 币就代签，不把聊天中泛泛的“继续”写成同意记录。
+
+## 浏览器签署
+
+`generation protocol-open [--browser default|msedge|chrome] [--timeout MS]` 打开本机专用阅读确认页，默认最多等待 5 分钟。CLI 从当前服务公开 `/content` 中选择 terms_of_service、标题匹配 Seedance 的当前承诺书，并加载其 content_url 原文；找不到唯一正文、正文加载失败时停止，不能用模板或自行总结的条款替代。
+
+原 API URL 返回 JSON，直接在浏览器打开并不是可签署页面。CLI 的本机页面展示服务、当前 CLI 账号、协议标题/版本与完整已发布正文，不重新打开画布，也不要求把登录令牌粘贴到网页。用户亲自勾选后点击才由 CLI 调用 `POST /video/protocol-agreement`（agreed=true）；CLI 之后必须通过 GET 读回核验当前账号/版本状态。独立 protocol-open 不提交生成、不扣生成费用。
+
+正文与外层使用统一深色样式，仅调整隔离阅读副本的显示，原文与签署核验摘要不变。服务端确认并读回核验成功后，立即通知等待中的 CLI，同时尝试关闭当前协议页；CLI 不等待页面关闭。浏览器若限制自动关闭，页面保留“已同步 CLI，可关闭此页”，用户可手动关闭，无需再签署或重复执行命令。接口响应丢失时只读查询确认成功后也按此处理；拒绝、版本变化或结果未核实不会按成功关闭。
+
+本机页面只在该 CLI 进程存活时有效；打开失败会打印一次性链接供用户手工打开，不能承诺进程退出后链接仍可用。用户不签署或超时就结束等待；原生成 operation 保留，不能换新 operation。用户可能已在正式网页签署，CLI 读回服务端已同意当前版本即可，不要求重复勾选。
+
+## 签署后继续同一次生成
+
+1. 按 [生成流程](generation-workflow.md) 确认实际画布归属、输入/模型参数、付款钱包及 OO 币。已获得原任务当次授权就沿用；禁止因等待签署而重新创建收费意图。
+2. `generation submit --input request.json --operation NAME` 预览会带协议状态，不打开页面或签署。获得费用授权后执行同一命令加 `--yes --expected-cost COST`。如果需要签署，CLI 持久化原请求、原幂等键和 blocked_agreement 状态，再打开阅读页；可选 --browser 与 --agreement-timeout MS。
+3. 已有被协议拦截的 operation 使用 `generation recover NAME --yes --expected-cost COST`，同样可打开页面并等待。已知 task ID 时直接查询原任务，不重复提交或要求重新签署。
+4. 用户确认后，CLI 重新核验服务端同意状态、版本、账号、画布空间/目标节点/上游及费用；输入或价格变化时停止并说明需重新确认。仅在条件仍符合且费用授权仍有效时，使用原请求和原幂等键继续一次提交。不设置 protocol_agreed 代替服务端确认记录。
+5. 用户选择不同意、取消/超时、正文或版本变化、账号变化、签署结果不明时，不继续生成。签署 POST 没有盲目重试；结果未知只读 GET 确认。若版本在真正提交前又变化，4401 再次报告等待签署，保留原操作，不自动循环重提。
+6. 任务建立后按原 task ID 查询、同步结果与交付，区分签署成功、生成提交成功、任务完成与画布结果保存；不能把协议签署成功当作视频生成通过。
+
+当前后端签署 POST 只接受 agreed，没有期望版本字段。CLI 在签署前后都核验正文与版本，发现变化就停止继续生成；这不等同后端已具备“按版本条件写入同意”的原子契约，该极短窗口的后端增强另行记录。
+
+## 画布并发与断线记录
+
+若网页开着画布并自动保存，同时后端断线/重连，可能出现旧快照覆盖或状态不同步。记录为观察与待核实原因，不直接归咎网页实现或把结果显示缺失当作生成失败。先读原任务状态与最新画布，协调暂停/关闭该画布编辑；用户允许后仅同步原真实结果，不重新扣费生成，也不自动恢复用户主动删除的节点。
+
+## 明确拒绝与未知响应
+
+签署接口明确业务2001或HTTP401/403拒绝时，页面显示安全错误并终止等待，CLI报AGREEMENT_REJECTED、agreement_rejected，保留实际api_code及HTTP/request_id，不冒充4401或签署成功。请求未知仍只读GET，不自动重POST。聊天表示已签不能替代服务端agreed；本人点击被拒绝时记录交接，不反复要求用户点击。无余额／团队不自动充值、入队或切付款方。

package/.agents/skills/uzoo-anime-cli/references/canvas-workflow.md

@@ -0,0 +1,53 @@
+# 画布创建与空间选择
+
+用户要求创建画布时读取本文件。创建画布不要求先查询模型、创建节点或在网页操作；完成本次创建后停止。所有命令使用安装后的 `uzoo-anime`，源码开发时才替换为 `node src/cli.js`。
+
+## 先确定什么
+
+1. 确认可用的 `uzoo-anime` 命令和本次 profile/服务，已有上下文就沿用。必要时查看 `uzoo-anime --help`；不要为每次业务重新安装 CLI、启动前端或修改地址。无服务配置时才询问网站/API 地址并执行 `config set --base-url URL`，不套用开发机地址。
+2. 运行 `uzoo-anime --profile PROFILE auth status`，确认实际账号及 `teams`。有效登录直接复用；缺少/撤销登录态时才 `auth login`，由用户完成网页登录、滑块与授权。新 CLI 登录会替换原 CLI 会话；不要通过反复登录排查业务权限错误。
+3. 用户未选空间时问“本次使用个人空间还是团队空间？”。已选个人就使用 `--space personal`，即使账号返回默认 `teamUid` 也不能自动改成团队。团队仅从实际 `teams` 中选择：指定名称/UID时匹配；只有一个可用团队时告知名称后使用；多个且未指定时展示名称/UID供用户选择；零个或指定团队不可用时停止说明，不能改成个人。
+4. 用户未指定目标画布时，先查询所选空间列表，再用交互卡片提供“新建画布”和真实已有画布；列表较长按真实 cursor 分页选择，不能只展示部分就断言没有其他画布。选择新建后，用卡片让用户输入名称或明确接受 Agent 建议名称，再创建；选择已有则解析真实 ID 并读回核验。用户已明确目标、名称或明确委托选择时沿用，不重复询问。不因用户提出创作需求就直接创建新画布。
+5. 取得画布名称；用户已给出的名称原样保留。团队项目仅在用户要求归入项目或当前任务明确需要时确认，使用已核实的项目 ID；不猜 ID，不为了创建普通团队画布额外询问项目。
+
+交互卡片与等待续接统一遵循 [交互流程](interaction-workflow.md)。账户、空间、团队、项目和名称中的独立缺项可以一次询问；可通过查询解决的项先查询。同一任务沿用已确认选择，用户切换个人/团队时重新核对归属。
+
+团队空间使用成员共享钱包，普通成员仅能看到本人消费记录。余额随其他成员使用变化，本次任务费用按 [团队钱包核验](generation-workflow.md#团队共享钱包与费用核验) 单独确认；创建画布不因此进入生成或账单调查流程。
+
+## 执行与核验
+
+命令中的 `PROFILE`、`TEAM_UID` 和 `DOC_ID` 替换为本次真实值，不使用历史测试账号和 ID。
+
+个人：
+
+```powershell
+uzoo-anime --profile PROFILE canvas list --space personal --limit 100
+uzoo-anime --profile PROFILE canvas create --space personal --name "用户指定的名称"
+uzoo-anime --profile PROFILE canvas get DOC_ID
+```
+
+团队：
+
+```powershell
+uzoo-anime --profile PROFILE canvas list --space team --team-uid TEAM_UID --limit 100
+uzoo-anime --profile PROFILE canvas create --space team --team-uid TEAM_UID --name "用户指定的名称"
+uzoo-anime --profile PROFILE canvas get DOC_ID
+```
+
+若已确认团队项目，list/create 均附 `--project-id PROJECT_ID`。list 返回 `next_cursor` 时继续带 `--cursor CURSOR` 查询，不能只查第一页就断言无同名项。
+
+- 创建前查当前范围列表，防止重复执行。列表不证明名称唯一：若发现同名，核对 ID、归属及当前任务记录；确认为本任务已创建就读取验证并复用，否则询问复用还是另建同名画布。用户已明确要求另建时不重复询问。
+- 用户明确要求创建且名称、空间已确定，直接执行一次 create。不要再要求用户去网页创建，也不要把创建授权理解为生成授权。
+- 从 create 实际响应取得 `id`，再 get 验证名称、创建者、归属和保存结果：个人 `team_uid` 必须为空；团队必须与选定 UID 相同；指定项目时项目 ID 也应一致。新画布应为 `nodes: []`、`edges: []`，且有有效版本。
+- 报告名称、所属个人/团队和画布 ID。用户可刷新网页查看，但网页检查不作为 CLI 操作的前置条件。未提交生成时说明未产生生成消耗。
+
+## 失败后做什么
+
+- 登录态错误：按错误提示恢复授权后继续原任务；账号不符先向用户确认，不换账号写入。
+- 团队权限/画布数量或权益限制：报告实际错误并询问可行选择，不擅自换空间、项目或删除画布。
+- create 超时、断连或结果不明：停止重复 POST；按相同范围 list（必要时翻页），结合名称、创建者和时间找到候选再 get。不能确认唯一结果时请用户核对，不能声称创建失败后再盲目创建。
+- create 已返回 ID 但 get 失败：保留该 ID，仅重试读取；报告“创建已返回成功，核验待完成”。归属不符时停止后续写入，不自动删除或迁移。
+
+## 后续任务
+
+仅当用户要求继续准备或生成时，才按 [generation-workflow.md](generation-workflow.md) 核对画布归属、查询对应空间模型、补齐节点及参数、上传必要素材、预估并等待当次费用确认。创建画布本身不需要选择模型或预估生成费用。

package/.agents/skills/uzoo-anime-cli/references/commands.md

@@ -0,0 +1,242 @@
+# CLI 命令契约
+
+**范围**：转绘暂停。只在用户明确要求查询／下载原结果或排障时使用旧命令，不提交新任务或自动恢复画布写入。
+
+安装后使用 `uzoo-anime`，需要 Node.js 22+。创建画布与异常恢复见 [画布流程](canvas-workflow.md)。
+
+业务命令支持 `--profile NAME --format json|table --request-timeout MS`。本地`--version`／`-v`仅单独输出版本；`version`和`skill path`只接受--format，不读凭据、不锁profile、不联网。默认 JSON，失败在 stderr 输出 `{ "error": { "code", "message" } }`，退出码非零。查询输出保留 API 原有字段；列表通常为 `items` 和 `next_cursor`，翻页时传回游标。无通用业务重试，扣费提交不会自动重试。
+
+| 命令 | 参数与结果 |
+|---|---|
+| `--version` / `-v` | 纯本地版本字符串；不能与业务参数混用 |
+| `version` | 可选--format json，返回name/version/node_required，来自包内manifest |
+| `skill path` | 返回随包directory/entry及registered=false，不自动注册或覆盖；npm升级后由用户同步宿主skill |
+| `config set` | `--base-url URL`；远端必须 HTTPS，切换服务使用新 profile 或先退出 |
+| `service status` | 可选 --timeout MS（默认 8000，上限 60000）；读取当前 profile 配置但无需解密登录凭据，不发送认证头，查询同源 health/live 与 health/ready；返回 ready/not_ready/unreachable/unknown、HTTP 与数据库/Redis状态，非 ready 退出码 3；不重发业务请求 |
+| `auth login` | 在普通浏览器登录并确认 CLI 授权，CLI 通过本机回调接收授权码并加密保存独立会话。可带 `--web-url URL --browser default|msedge|chrome --timeout MS`；默认 5 分钟。服务端和前端须启用对应功能 |
+| `auth import` | 推荐 `--input FILE`；文件字段 `accessToken`、可选 `refreshToken`、`cookie`、`deviceId`。用户在本机导入，勿让其把凭据贴入聊天 |
+| `auth login-url` | `--web-url URL`；只打印登录地址，不创建授权请求。需要授权时用 `auth login` |
+| `auth status` / `account info` | 获取当前账号，保留 uid，用于确认身份 |
+| `auth logout` | 独立 CLI 会话先远程撤销再清除本地凭据，不影响网页会话或 operation 记录；旧导入会话仅清理本地 |
+| `model list` | 必填 `--space personal` 或 `--space team --team-uid UID`；可选 `--type image/video/text/audio`；以返回 `items[].label` 为模型名称，按目录能力选择参数 |
+| `canvas list` / `canvas get ID` | 列表必填 `--space personal` 或 `--space team --team-uid UID`，可带 `--project-id ID --cursor CURSOR --limit 1..100`；个人空间不能带团队/项目；生成使用已有或 CLI 创建的文档和节点 |
+| `canvas create` | 必填 `--name NAME` 及 `--space personal` 或 `--space team --team-uid UID`；团队可选 `--project-id ID`（映射 canvas_project_id）；返回完整画布及 id/version，不发起生成 |
+| `node add` | `--doc ID --type TYPE`；仅支持普通节点 text/image/video/audio、image_upload/video_upload/audio_upload、video-repaint；可选 `--node-id ID --input node-patch.json`；默认生成 UUID 节点 ID，返回 doc_id/node_id/version/node；派生节点由真实业务流程创建 |
+| `node update` | `--doc ID --node-id ID --input node-patch.json`；只更新指定节点，不改 id/type，返回同上 |
+| `resource upload` | `--file FILE --doc ID --type image|video|audio --mime MIME`；普通素材节点加 `--node ID`，成功后补齐网页持久化引用，检查 canvas_bound；旧画布资产接口的图片加 `--asset-type character|scene|prop --name NAME`。返回 API 的资源引用，按实际返回字段使用 |
+| `resource bind` | `--doc ID --node ID --input upload-response.json`；复用真实上传响应，补齐普通素材节点的持久化媒体字段，不重新上传 |
+| `material folders/list/get ID` | 必填 `--space personal` 或 `--space team --team-uid UID`；list 可带 `--folder-id ID --keyword TEXT --limit 1..200 --offset N`，get 返回同空间素材 |
+| `material download ID` | 必填空间参数及--output FILE，可选--sha256 HEX；核对目录/素材归属，再请求素材专属download入口，匿名下载原格式完整url，返回output/bytes/sha256/asset_id/format/可选filename及无画布/生成/入库副作用标记。仅original，不支持自定义服务端名称或转换；拒绝不回退list/get的URL |
+| `material upload` | `--file FILE --mime MIME --folder-id ID --name NAME` 及空间参数；上传到独立素材空间，先核对实时限制和目标目录 |
+| `material use ID` | `--doc ID --node-id FIXED_ID` 及空间参数；可选 `--input position.json`；从库导入普通素材节点，复用真实引用，不重传 |
+| `material save` | `--input save.json --operation NAME` 默认只预检；加 --yes 直接保存原节点结果到素材库。输入 doc_id/node_id/space、团队 team_uid、folder_id，可选 name/description；限同空间已完成图片/视频真实任务；持久化原请求/幂等键，不写画布 |
+| `material save-get NAME` | 查询原入库 operation，已有 asset_id 时核验原素材，返回 state/task_id/folder_id/asset_id/asset/可选 last_failure；不发保存 POST |
+| `material save-recover NAME` | 默认只查询；未知结果且没有 asset_id 时，明确恢复才加 --yes 沿用原请求与幂等键。已知 asset_id 仅查询，rejected 不自动重提；账号/服务/来源改变停止 |
+| `video clip` | --input clip.json --operation NAME 默认仅预检，加 --yes 前检查后端就绪后单次截取并保存新视频素材/连线。输入 doc_id/node_id/space、团队 team_uid、start_ms/end_ms，区间 500–120000ms，不扣生成费用；无自动 POST 重试 |
+| `video clips` | 可选 --limit 1..200、--offset N；查询当前账号真实片段列表，不截取或保存画布 |
+| `video clip-get NAME` | 查询原剪辑和当前来源，保留片段 ID/真实 canvas_task_id 与同步状态；已删/变更结果报告 canvas_changed，不自动修复 |
+| `video clip-recover NAME` | 已有 clip 只恢复保存；丢失提交响应时，经核对真实列表后可传 --clip-id ID 关联原产物。不重新 POST 截取、不重建已删节点/连线；先检查后端就绪 |
+| `video tools` | 无需解密登录态，检查本机 FFmpeg/FFprobe；可选 --ffmpeg PATH --ffprobe PATH。缺失返回 MEDIA_UNAVAILABLE 和 error.dependency（所需/缺失工具、各项状态、安装须确认）；Agent 询问是否安装后继续，CLI 不自动安装 |
+| `video frame` | --input frames.json --operation NAME 默认仅预检；输入 doc_id/node_id/space、团队 team_uid、times_ms（1–3 个整数毫秒）。加 --yes 检查 ready 后原尺寸 JPEG 截帧、上传、新素材节点和系统线；可选 --ffmpeg/--ffprobe。预检在签名引用不同需流式读取媒体作摘要比对，不写画布/本地 operation |
+| `video frame-get NAME` | 只查原截帧和当前画布，返回 state、generation_submitted=false、library_saved=false、items（node_id/time_ms/frame_time_ms/state/canvas_bound/task_id/width/height）；不重新处理 |
+| `video frame-recover NAME` | 默认只查，--yes 才恢复原阶段；可选 --ffmpeg/--ffprobe。未知 complete 仅查询唯一真实原上传任务，不再次 complete；已删除/改换节点停止 |
+| `image tools` | 与 video tools 共用本机 FFmpeg/FFprobe 检查，不解密登录、不自动安装；缺少时由 Agent 按依赖流程取得安装同意 |
+| `image crop` | --input crop.json --operation NAME 默认预检，加 --yes 才导出 PNG、上传及保存新图片素材/来源线。输入 doc_id/node_id/space、团队 team_uid，rect 原图整数像素或 aspect_ratio（最大居中比例）二选一；可选 --ffmpeg/--ffprobe；真实输出尺寸受最长边4096/1600万像素限制 |
+| `image crop-get NAME` | 只查原裁剪与当前画布，返回 state、原图source、裁剪rect、实际output及items（node_id/state/canvas_bound/task_id/width/height）；不再次处理 |
+| `image crop-recover NAME` | 默认只查，加 --yes 才恢复原阶段；未知 complete 仅查询唯一原真实上传任务，不重传/重发complete，已删除/改换节点停止；可选工具路径 |
+| `image annotate` | --input annotations.json --operation NAME默认预检，加--yes本地合成PNG/上传/落图；输入doc_id/node_id/space、团队team_uid、commands及文字可选font_file。rect/ellipse/line/brush/text使用原图像素；图形旋转支持、文字旋转不支持；可选--ffmpeg/--ffprobe |
+| `image annotate-get NAME` | 只查原标注/当前画布，返回state/source/output/output_type/command_count/command_types/items，不再次处理 |
+| `image annotate-recover NAME` | 默认只查，加--yes恢复原阶段，不重发未知complete；可选工具路径。账号/源类型/任务变化或结果删除停止，不重建 |
+| `graph apply` | `--input graph.json`；直接保存 layout/group-create/connect/group-connect；组输出展开成员，按类型/模型过滤，返回 connected/skipped |
+| `model options` | 必填 `--type text/image/video` 及空间参数；只读实时目录，返回模型 selectable、controls（前端普通节点已接入字段）、node_path/mirror_node_paths、建议值及固定/模式适用条件；只用于普通生成，非专用流程参数；不创建/估价/提交，不是请求体或用户授权。generation_modes 是能力信息，须按实际拓扑核验；不包含供应商/admin额外字段 |
+| `generation prepare` | `--doc ID --node ID` 及空间参数，可选 `--output request.json`；只读当前普通文本/图片/视频节点与上游，返回完整 request，不预估或提交，文件不覆盖 |
+| `generation history` | 必填--doc ID --node ID及空间参数；普通图片/视频节点历史，--status queued/processing/completed/failed/retrying/cancelled、--limit 1..100（默认30）、--offset N（默认0）；返回items/has_more，非cursor分页，只读 |
+| `generation history-select` | --input FILE --operation NAME；输入doc_id/node_id/space、团队team_uid及task_id正安全整数，默认本地预览，用户明确选择后同输入加--yes；恢复所选历史结果和相应历史配置，一次CAS保存，不提交生成/入库 |
+| `generation history-get NAME` / `generation history-recover NAME` | 核验原选择operation与当前画布，只查询远端并更新本地状态，不重发PUT；检查state/selection_verified/canvas_matches_selection，canvas_changed保留当前编辑。详见[历史选择](generation-workflow.md#普通图片与视频历史选择) |
+| `generation list` | 必填 `--doc ID`；可选 `--node ID --status STATUS --cursor ID --limit 1..100` |
+| `generation protocol-status` | 只读查询视频《统一协议》及《Seedance2.0模型使用承诺书》的 required/agreed/version；status=awaiting_agreement 与 api_code=4401 表示待签署 |
+| `generation protocol-open` | 打开独立本机协议阅读确认页；可选 --browser default/msedge/chrome --timeout MS；本人勾选点击后记录并查询核验，不提交生成 |
+| `generation estimate` | `--input request.json`；保留文档/节点上下文，返回费用和 `will_intercept` |
+| `generation submit` | `--input request.json --operation NAME` 默认只预估；Seedance 预览额外返回 protocol；--yes 在需要协议时打开阅读页并等待本人确认，核验后继续原操作；可选 --browser 和 --agreement-timeout；首次 --yes 必须带 `--expected-cost OO` 与当次确认费用严格比对，不一致停止；返回 `{operation, estimate, task}`。保存 operation，任务 ID 是 `task.task_id` |
+| `generation recover NAME` | 有已知任务 ID 时只查询该任务；未知提交结果时默认只预估，加 `--yes` 以原请求和原幂等键恢复；原记录无确认金额或价格变化时必须重新卡片确认并带 `--expected-cost OO`，已有有效金额且报价未变可沿用。新授权金额先落原记录，不改请求或键。不得改用新 operation |
+| `generation operations` | 列出本地 operation、taskId、状态与创建时间；失败时包含脱敏 lastFailure（HTTP/业务错误码），不输出原始请求 |
+| `generation get ID` / `logs ID` | 原样返回任务或日志，用于调查失败，不触发重新生成 |
+| `generation wait ID` | `--interval MS` 默认 3000，`--timeout MS` 默认 600000；轮询原任务，completed 后将真实结果同步普通生成节点；不再次提交任务 |
+| `generation sync ID` | 读取原任务及最新画布，保存真实任务 ID/状态/媒体结果或文本输出；无生成提交；CAS 冲突或节点关联变化停止 |
+| `generation download ID` | `--output FILE`；可选 `--sha256 HEX` 比对预期摘要，返回本地路径、bytes、sha256、filename。--output省略时优先采用实际文件响应Content-Disposition的安全文件名，再回退业务响应filename；显式路径保留。已有文件不覆盖 |
+| `review start` | `--input review.json --operation NAME` 默认只预检；明确审核范围后加 `--yes`，仅审核素材，不提交生成。输入 doc_id/node_id/space、团队 team_uid，mode 为 current/upstream；同 operation 不重发 POST |
+| `review get NAME` | 查询原审核并更新本地记录，不保存画布；返回 operation/state/canvas_synced/items（task_id/source_node_ids/status/review/可选 last_failure） |
+| `review recover NAME` | 查询并按最新画布版本回填审核状态/引用关联，不重新提交审核；素材/任务/账号/服务变化停止 |
+| `review wait NAME` | 可选 --interval MS（默认 3000）、--timeout MS（默认 180000）；轮询并回填，active/failed/rejected/unknown 时返回，超时继续原 operation |
+| `repaint start` | `--input repaint.json --operation NAME`；默认只查询分析费用、核对空间/素材并保存本地预估。取得当次确认后同命令加 `--yes`，从真实源节点读取视频、分片上传并提交分析，保存任务关联与分段详情 |
+| `repaint get NAME` | 查询原 operation 的任务；不写画布、不推进方案、不提交任务 |
+| `repaint plan NAME` | `--input plan.json` 展示拟修改切点；加 `--yes` 保存当前待确认方案。输入为 `plan_version` 和 `boundaries_ms`，保存后版本变化 |
+| `repaint confirm NAME` | 必填 `--plan-version N`；先展示真实方案，加 `--yes` 才确认并启动切片。不提交反推、提示词或视频生成 |
+| `repaint wait NAME` | `--interval MS` 默认 3000，`--timeout MS` 默认 600000；分析到 awaiting_review 时同步详情并返回；切片到 completed 时保存片段/提示词/视频生成节点、系统连线和分组 |
+| `repaint recover NAME` | 读取原任务并同步；不再次complete/confirm。详情被删除默认停止；用户明确授权后可加`--restore-detail`预览原待审核详情恢复，再加`--yes`执行，仅恢复原详情和系统线，不重建已切片链 |
+| `repaint operations` | 只列 operation、状态、任务 ID、创建时间，不输出原始素材地址；无需读取凭据 |
+| `repaint reverse PARENT` | 必填`--segment-index N --operation NAME`；默认只预估，按真实首轮权益及实时单价计算。用户当次确认后加`--yes --expected-cost OO`单次确认片段并反推，不自动做最终提示词或视频 |
+| `repaint reverse-get NAME` | 只读原反推operation的job/segment状态、真实费用和提示词 |
+| `repaint reverse-recover NAME` | 查询并同步已明确接收的原结果；不重发反推，节点编辑/删除或未知提交停止 |
+| `repaint reverse-wait NAME` | 可选`--interval MS`默认2000、`--timeout MS`默认180000，等待原反推并回填对应节点；超时不重做 |
+| `repaint delivery PARENT` | 必填`--segment-index N --operation NAME`，可选`--input rules.json`；默认只预估，用户当次确认后加`--yes --expected-cost OO`保存现有全局设置并单次处理最终提示词，不生成视频 |
+| `repaint delivery-get NAME` | 只读原job/segment状态、billing、delivery_prompt及fallback/warning |
+| `repaint delivery-recover NAME` | 仅恢复已接收原结果；未知提交不重发，原文/规则/用户内容或关联变化停止 |
+| `repaint delivery-wait NAME` | 可选`--interval MS`默认2000、`--timeout MS`默认180000；完成回填原最终提示词节点，completed_fallback须报告回退而非正常处理成功 |
+| `repaint video-options PARENT` | 必填`--segment-index N`；只读原片段无额外参考的当前可选模型及参数，供交互卡片选择 |
+| `repaint video PARENT` | 必填`--segment-index N --input video.json --operation NAME`；输入model_name/duration/aspect_ratio/resolution。默认双接口预估，确认后加`--yes --expected-cost OO`单次提交；可用`--browser/--agreement-timeout`本人签署协议 |
+| `repaint video-get NAME` | 只读原任务/计费；无接收ID的未知提交不认领观察到的其他任务 |
+| `repaint video-recover NAME` | 核验原关联并同步已接收任务状态/结果，不再次提交生成；目标编辑/删除/旧快照覆盖停止 |
+| `repaint video-wait NAME` | `--interval MS`默认3000、`--timeout MS`默认600000；等待并保存原生成节点结果，超时继续原operation |
+| `repaint video-download NAME` | 必填`--output FILE`；必须通过原任务download权限接口，遵循当前部署的可见性/审计；新版取消白名单，不凭2001推定具体原因；受限与生成成功分开报告 |
+| `repaint export NAME` | --type reverse/delivery/video --output FILE，可选--source remote/archive（默认remote）；核验原关联后导出UTF-8文本或经专用download接口下载视频；不写画布/不重做。archive仅文本且必须有先前已核验快照，仍在线核验账号归属；结果不可用/快照缺失或损坏返回相应REPAINT_*错误；文件存在拒绝覆盖 |
+| `repaint sequence PARENT` | --input FILE --operation NAME；本地保存1–100项steps清单并核验同一父任务。每项type/segment_index/operation，delivery/video必须明确input；不批量提交、不写画布 |
+| `repaint sequence-get NAME` | 只读核验并返回steps、next_step；输入/方案/规则/附件变化停止，未完成步骤不跳过 |
+| `repaint sequence-next NAME` | 默认只准备当前项并返回result参数/估价/钱包。单项当次确认后--yes --step CHILD_OPERATION --expected-cost OO，只执行该项；可带视频协议browser/agreement-timeout；旧step不授权下一项 |
+| `repaint sequence-recover NAME` | 必须--step CHILD_OPERATION；只恢复当前原子operation的已知阶段，不提交处理/生成、不跳过未知或失败项 |
+| `repaint history NAME` | 必填`--type reverse/delivery/video`，NAME为对应阶段的原operation；配置变化后只读核验原接收结果/费用及当前配置差异，不写画布/记录、不下载、不提交。提示词当前轮不匹配返回original_result_unavailable，不能仅凭退出0认定找回；不支持--yes。见[历史查询](repaint-workflow.md#原运行只读查询) |
+| `repaint settings-get PARENT` | 只读原全局节点/后端文字与附件同步状态，不提交处理 |
+| `repaint settings PARENT` | 必填`--input settings.json --operation NAME`，只支持custom_prompt纯文本；默认预览，已授权免费编辑加`--yes`同步原后端设置和全局节点，不重处理结果 |
+| `repaint settings-operation NAME` | 只读原保存operation与两端状态，未知记录不自动重发 |
+| `repaint settings-recover NAME` | 查询原POST是否生效后恢复画布同步；不重复保存设置，目标/附件/绑定变化停止，SAVE_UNKNOWN/SYNC_PENDING退出4 |
+| `repaint materials PARENT` | 只读任务素材池真实ID/分类/文件引用，非普通素材库 |
+| `repaint reference-upload PARENT` | `--input reference.json --operation NAME [--yes]`；输入file/kind/category，默认准备，执行原会话分片上传和任务素材注册，不自动选择或生成 |
+| `repaint attachment-upload PARENT` | `--input attachment.json --operation NAME [--yes]`；输入file，默认准备，执行独立附件上传/注册/原全局设置及节点挂载，不处理提示词；operation最长55字符 |
+| `repaint upload-get NAME` | 只读原上传记录及绑定；不能仅凭退出成功认定state已完成 |
+| `repaint upload-recover NAME` | 默认只查；`--yes`继续已知阶段，未知会话创建/complete/注册不重发，REPAINT_UPLOAD_UNKNOWN退出4；已完成不重复写入 |
+
+历史选择错误：NODE_HISTORY_UNAVAILABLE（退出2）表示没有可绑定的已完成普通历史；NODE_HISTORY_SAVE_PENDING（退出4）表示保存未确认，先查询原operation，不自动重发。历史选择恢复的是该条历史参数，不是此前编辑快照；当前参考/其他节点/下游结果保留。
+
+退出码：2 参数/配置/存储错误，3 API 错误（含 REVIEW_REQUEST_REJECTED/MATERIAL_SAVE_REJECTED），4 提交或保存结果未确认（含 REVIEW_SUBMISSION_UNKNOWN/REVIEW_SYNC_PENDING/MATERIAL_SAVE_UNKNOWN），5 等待或请求超时，6 任务失败，7 协议签署未完成/需重新核验（awaiting_agreement，不是生成执行失败），130 用户中断。收到 4 或 5 后先恢复查询；不要因退出码非零而新建生成。查询返回的 state 也必须检查，不能只看命令是否退出成功；审核见 [素材审核](seedance-review-workflow.md)，入库见 [素材流程](material-graph-workflow.md#已有节点结果直接存素材库)。错误保留服务提供的安全 request_id，不复制原始错误正文或凭据。
+
+上传使用独立预签名 URL，不携带 API Authorization/Cookie；失败时不自动执行 complete。普通 resource upload 不做分片断点续传；截帧独立 operation 可复用已知原会话/分片阶段，complete 未知仅查询原任务恢复，不重传。匿名文件GET支持最多5次307引用续期，逐跳核验地址且不携带API凭据；业务API/上传仍拒绝跳转。下载拒绝HTML/JSON错误页和非预期的206/202响应，流式写入临时文件，验证长度与可选摘要后落盘。文本产物若下载接口不提供文件，应从 `generation get` 的结果读取。
+
+## 后端连接与异常排查
+
+超时、断连、网关 502/503/504、HTTP 200 内的 code 5000/3000 等异常，先运行 service status，再检查原 operation、任务/片段、目标画布/目录，最后定位功能本身。CLI 错误输出会对服务/网络类异常追加同源探针结果，保留原 code、HTTP/业务码和 request_id，不将所有异常改成“网络错误”。明确参数、权限或协议签署错误按原类处理。
+
+live 只证明进程能响应；ready 真查数据库和 Redis；ready 也不证明对象存储、队列、ffmpeg 或业务事务正常。unknown 可表示当前部署缺少探针或响应不兼容，不直接说后端已断开。静态 health 或返回 HTTP 200 都不能替代 ready 内容判定。已恢复连接不代表先前无副作用，更不能自动重发写入；入库/剪辑实际提交前非 ready 会停止，其他路线按各自恢复约束和该排查顺序执行。
+
+material save/save-recover --yes、video clip --yes、video clip-recover、video frame/frame-recover --yes、image crop/crop-recover --yes 会先要求后端 ready；探针不支持时先核对当前部署兼容性，不切换 API 或绕过写入前检查。异常诊断有超时上限，不循环等待或重启服务。
+
+剪辑/截帧步骤与恢复边界见 [视频素材工具](video-tools-workflow.md)。SERVICE_UNAVAILABLE 为退出码 3，MEDIA_UNAVAILABLE 为 2，CLIP_RESULT_UNKNOWN/CLIP_SYNC_PENDING/FRAME_UPLOAD_UNKNOWN/FRAME_SYNC_PENDING 为 4。查询命令仍须检查返回 state，不凭退出码零认定任务已完成。
+
+裁剪步骤、格式/导出限制及原产物恢复见 [图片素材工具](image-tools-workflow.md)；CROP_UPLOAD_UNKNOWN/CROP_SYNC_PENDING 为退出码4。处理请求不自动入库、审核或生成。
+
+标注参数/依赖及两类输出见[图片标注](image-tools-workflow.md#图片标注)；ANNOTATION_UPLOAD_UNKNOWN/ANNOTATION_SYNC_PENDING为退出码4。image annotate/annotate-recover --yes同样先检查ready；文字字体或drawvg/drawtext缺失按MEDIA_UNAVAILABLE依赖信息处理，先询问安装/更新，不自动下载。image tools成功不代表所有标注过滤器/字体已具备。
+
+本机依赖缺失时读取 `error.dependency`：status=awaiting_dependency_installation、package=FFmpeg、required_tools、missing_tools、checks、installation_requires_confirmation=true、installation_performed=false、next=ask_user_to_install_or_provide_paths。Agent 按 [依赖安装流程](video-tools-workflow.md#本机依赖与按需安装) 准备具体方案并取得安装同意。status=dependency_unavailable/next=check_existing_tools 表示有工具执行/响应异常，先排查，不因 MEDIA_UNAVAILABLE 一律要求安装。`--yes` 只执行原业务操作，不授权安装软件。
+
+## 节点输入与并发保存
+
+`node add/update --input` 接受 `{ "position": {"x":120,"y":130}, "width":400, "height":300, "data": {"title":"图片节点","model_name":"实际模型label","prompt":"提示词","extra":{"aspect_ratio":"1:1"}} }`。字段均可省略；update 必须提供文件。data 使用 API 原生字段，按键合并；extra 再按一层键合并，其他嵌套对象如提供则整体替换。可配置项按前端实际使用并由 CLI 已接入的范围，具体可选值与限制查询实时目录，不会自动补选模型。修改节点不触发生成；需要从当前节点及拓扑准备请求时显式使用 generation prepare，它仅提取对应类型已接入的生成参数，不透传整包节点元数据。手写请求未知参数会报错，generate_audio 不支持；具体字段和历史操作处理见 [生成流程](generation-workflow.md#参数与前端使用范围)。图操作 JSON 与类型过滤见 [素材与分组流程](material-graph-workflow.md)。
+
+基础节点使用 API 类型 text/image/video/audio，非网页内部 textNode/imageNode。素材和视频转绘入口会补齐协议标记，完整映射见 [节点流程](node-workflow.md)；返回的 node.type 是保存后的 API 类型。video-remake/video-split-detail 已移出直接创建入口，传普通类型并注入派生标记、或更新普通节点为派生节点也会被拒绝。已有真实派生节点随快照保留，不通过空占位模拟流程。创建、修改均读取最新快照并携带版本 CAS 保存，保留名称、其他节点、边、视口与 meta；封面字段不传，按后端契约保留。409/code 3002 停止并提示重新读取；不自动合并冲突或覆盖。写入无自动重试，超时/断连先用 canvas list/get 核对。固定 --node-id 便于识别未知创建结果，重名时拒绝而不是重复追加。画布创建受账号权益/权限限制。
+
+## 空间确认
+
+先询问用户本次使用个人还是团队；已有明确选择可沿用，不逐条命令重复问。团队从 account info/auth status 的 teams 确认名称及 UID；仅一个可用团队时告知后使用，多个候选才询问，零个则停止。项目需要时再确认。CLI 模型查询、画布列表和创建强制显式 --space；团队还要求 12 位 --team-uid，个人拒绝团队和项目参数。缺少选择会报错，不做隐藏交互提示，便于 skill 先询问再调用。
+
+现有画布命令按 doc_id 操作，CLI 不保存全局空间状态，也不会因 --space 自动转移画布。skill 必须先 canvas get 检查 team_uid，再执行节点写入、上传、生成和恢复；选择不一致时停止。预估和生成的实际付款方由后端按画布归属决定，展示 OO 币时同时说明个人钱包或具体团队钱包；不同团队不复用模型权益判断或估价结果。
+
+账号返回的团队余额是成员共享钱包快照，普通成员的消费记录仅涵盖本人；其他成员使用也会减少共享余额。核验本次费用按原任务实际计费与本人可见记录，不将余额差额当作CLI消费，不凭本人无记录判定团队无人消费。完整口径见 [团队钱包核验](generation-workflow.md#团队共享钱包与费用核验)。
+
+## 视频分段输入
+
+`repaint`只承接画布转绘，必须绑定原画布/源节点/派生链。独立「视频转绘」页面未接入，暂不实现。现有materials/reference-upload等底层命令与历史测试不等于独立页面已接入，不自动续接该页面的选择/排序/生成。
+
+`repaint` 的输入、费用确认和中断条件见 [视频分段流程](repaint-workflow.md)。`repaint start` 接受 `doc_id`、`source_node_id`、`entry_node_id`、`space`、团队时的 `team_uid`、`segmentation_mode`（默认 intelligent；另支持 uniform）以及 uniform 时必填的 `uniform_interval_seconds`（4–15）。其他字段拒绝。源节点必须是有真实可读视频地址的普通 video/video_upload；入口是普通 video-repaint，不能使用历史占位详情或重拍节点。CLI 从该源节点读取实际文件，不接受另一个本地文件偷偷替换源素材。
+
+`repaint` 的 operation 与 generation operation 分开存储，均绑定账号和 API 服务。本地记录包含任务关联、上传会话/预签名地址及素材摘要，勿分享或提交。分片只传到接口返回的 URL，不携带 API 凭据。已确认分析以预分配 job_id 查询恢复，不依赖该接口存在未声明的 Idempotency-Key 契约。恢复保存采用最新完整画布和 CAS；版本冲突停止，任务保留，先读取/核对后显式 recover。
+
+## 图片抠图
+
+`image matting-submit NAME [--yes]`提交已预览的异步任务；原 matting-get 查状态，完成后原 matting-recover --yes 取回并落图。matting-status 是本地快照。见[异步流程](image-tools-workflow.md#服务端异步抠图任务)。
+
+`image matting-start NAME [--yes]`：先有同operation预览，确认后独立后台仅缓存PNG；`image matting-status NAME`：本地／离线只读状态，不取凭据、不争profile锁。后台operation的matting-get同为本地查询；matting-recover [--yes]仍需联网核验，确认后恢复落图。重复启动／未知响应不重POST。详见[后台流程](image-tools-workflow.md#抠图独立后台执行与本地查询)。
+
+`image matting-check --input FILE`仅只读预检，status=preflight_only。`image matting --input FILE --operation NAME`先本地预览，同输入加--yes只提交一次固定general免费抠图；输入doc_id/node_id/space/team_uid，无threshold／model／expected-cost开关。`image matting-get NAME`只读核验，`image matting-recover NAME [--yes]`恢复已知原结果／缓存或核对保存，不重发未知处理／保存。较慢处理可设置全局--request-timeout 180000。实际返回稳定结果引用、透明PNG、原字节缓存、0 OO及CAS读回，不入库。未知提交无结果引用时服务端查回仍未接入。详见[抠图流程](image-tools-workflow.md#图片抠图)。
+
+## 单片段重拍
+
+- `remake prepare --input remake.json --operation NAME [--yes]`：输入doc_id/node_id/space/team_uid/start_ms/end_ms/model_name/resolution/prompt。默认预检；--yes仅保存真实源视频绑定的重拍配置/来源线。区间整数毫秒，1–120秒内且受源时长与模型min/max约束。
+- `remake submit NAME [--yes --expected-cost OO --browser default|msedge|chrome --agreement-timeout MS]`：默认预估，先存报价再当次确认。--yes重新比价和核对协议/配置；没有公开提交幂等契约，不自动重发。
+- `remake get NAME`只查原任务/画布；`remake recover NAME [--yes]`默认只查，加--yes恢复原配置或已知任务结果保存；`remake wait NAME [--interval MS --timeout MS]`只轮询原任务，终态后同步原结果。不重新生成、不自动入库。
+
+任务ID可为UUID，读取/保存clip-redraw来源和结果关联，不作为普通canvas任务ID伪造。已保留ID的响应校验失败可读原任务恢复；无ID的未知提交停止。REMAKE_SUBMISSION_UNKNOWN/REMAKE_SYNC_PENDING退出4，协议走现有AGREEMENT_*退出7。详细输入、限制及恢复见[重拍流程](remake-workflow.md)。
+
+## 转绘任务素材与全局附件
+
+转绘仅限[原运行只读查询](repaint-workflow.md#原运行只读查询)和原结果下载；不使用旧附件或处理命令继续生成。
+
+DELIVERY_ATTACHMENT_ADDRESS_UNUSABLE是CLI预检错误（退出2），不是后端任务失败码。预览仍返回有效费用分项及submission_available=false，不能仅凭退出0执行收费；真实处理地址阻止时不再上传、不猜公网域名。附件超额按每段每次一口价，单段估价交叉核验实时pricing和job/billing-estimate，规则与恢复见上述指南。
+
+## 下载与文件凭证
+
+- 普通生成先调用 `GET /canvas/generations/{task_id}/download`，CLI自动带X-Client-Source: canvas；转绘先核验原operation，再调用 `GET /video-segmentation/{job_id}/redraw-tasks/{task_id}/download`，没有额外/jobs层。两者均无filename/format参数，不能把素材空间专属参数加进来。
+- 业务响应检查HTTP和JSON code，再匿名读取服务端返回的完整url，保留相对/绝对地址及全部查询参数，不用file_ref重拼丢失format。文件请求只跟随有效307续期，最多5次，共用本次请求超时；逐跳拒绝账号密码、非HTTP(S)、远程HTTP或HTTPS降级。API认证/签名/Cookie/设备信息不发送到文件或续期地址。
+- 文件流不是JSON链接响应；即使HTTP200也要拒绝错误JSON，保留安全业务码/HTTP/request_id，不输出原错误正文或完整签名凭证。原文件传输必须为200且完整；CLI未实现Range/断点续传或预览下载，不把206片段、202预览状态当作原文件。原文件/视频成品导出流式校验长度/摘要，已有目标拒绝覆盖，失败不留下最终文件。
+- 新说明取消团队素材及转绘下载白名单；访问仍由业务端按归属、活跃成员、公开/私有任务、完成与下架状态判断，不能把获取链接成功当作后续传输必然成功。code2001不单独证明白名单问题；核对当前服务版本、账号和原任务可见性，禁止改用缓存result.url绕过业务拒绝。原expires_at=null不代表永久有效。引用不能续期时通过同一有权限的业务入口重新获取，不重新生成。
+- 素材空间专属原文件下载已接material download；服务端命名按实际响应交付，读取Content-Disposition不是设置服务端名称；当前不支持格式转换，没有相应CLI参数或预览命令。旧前端素材下载尚无新命名/格式控件，不将后端可接收的format自动扩成CLI选项。服务端转换依赖服务器FFmpeg，与CLI本机截帧/裁剪的按需依赖不同；不得因此要求用户安装本机工具。转换失败不自动改下原文件或重试转码。
+
+## 普通分组重命名
+
+graph rename-group --input rename.json 默认只读预览，不写画布；输入doc_id、space、团队时team_uid、group_id、name。预览返回原名称、新名称和expected_version。用户已明确重命名目标与名称时沿用授权，否则先展示影响收集选择。将expected_version加入同一输入，执行graph rename-group --input rename.json --yes。
+
+只修改指定普通组的名称。相同名称不写入。冲突或保存结果不明，先用 canvas get 核对，不重放。
+
+组重命名会在预览前检查完整画布/分组结构；保存后另行GET确认当前目标组名，成功返回rename_verified=true。读回失败或不一致时明确报告未确认/内容变化，不自动重放保存；保留服务端当前版本。
+
+## 普通拆组
+
+uzoo-anime graph ungroup --input ungroup.json 默认预览；输入doc_id、space、团队时team_uid、group_id，可选expected_version。展示被移除组与membership_changes（其他组active/exited成员前后变化）；用户确认具体范围后将预览expected_version写回输入，加--yes执行。已有明确任务授权沿用，不重复询问。
+
+拆组只删除普通组元数据，保留节点、位置、连线和引用。版本变化、冲突或结果未知，先用 canvas get 核对，不重放。
+
+## 普通断线
+
+graph disconnect --input disconnect.json 默认只读预览；输入doc_id、space、团队时team_uid、edge_id，执行时增加预览expected_version并传--yes。预览列源/目标节点、提示词前后、引用ID前后及模式变化。用户已明确指定连线和范围时沿用授权；有引用/模式影响时展示实际预览，不隐藏。
+
+仅删除指定普通边；还有同源同目标连线时保留引用。最后一条断开后同步清理有效持久引用及已有存储位置；手动@@{ref:ID}移除，自动@{ref:ID}还原名称。按剩余拓扑和当前模型调整生成模式，不静默换模型。系统线、派生流程和不支持的配置协议停止；原生成/审核结果保留，断线不是取消远程任务。保存前版本变化或CAS冲突停止，结果未知/读回不一致不自动重放，先canvas get。
+
+当前断线前端codec/removeEdge/模式对照4例通过；范围未覆盖删除节点、复制节点、撤销重做。素材引用仍由prepare最终请求与reference_mapping核对。
+
+## 同画布单文本节点复制
+
+node copy --input copy.json 默认只读预览；输入doc_id、space、团队team_uid、node_id、new_node_id、position。按用户授权目标和位置执行，--yes须带预览expected_version。新ID固定，重复目标拒绝，防止未知保存后再追加。
+
+仅普通文本节点，保留文本/配置；原上游与持久参考合并为新节点持久引用，外部节点ID保持，不复制连线/分组、不触发生成。进行中任务、派生和媒体节点拒绝；非完成状态清理运行任务绑定。前端媒体复制还有来源历史协议，不能把本命令称为全节点复制。版本冲突或读回失败停止，先查固定新ID，不自动重放。
+
+## 普通节点删除
+
+node delete --input delete.json 默认只读预览；输入doc_id、space、团队team_uid、node_ids，实际执行增加预览expected_version并传--yes。展示节点列表、removed_edge_ids、group_changes、retained_references及mode_changes，用户明确授权具体删除范围后执行。不能把笼统开发请求当作删除业务节点的授权。
+
+删除普通节点及其入出边，按前端规则更新组成员；保留其他节点对已删除源的持久参考与提示词，retained_references明确列出这些目标。它不同于graph disconnect的引用清理语义；不取消/删除远程生成任务、素材库或文件。下游模式按剩余拓扑调整，涉及换模型时停止，不静默切换。系统线、派生流程、进行中节点不支持普通删除。
+
+CAS或预览版本变化停止；保存结果未知先查询原ID是否存在，不自动重放。当前不提供CLI撤销删除命令；执行前需明确选择。真实删除/网页验收按实际记录，不将模拟对照当真实通过。
+
+## 同画布多文本复制
+
+node copy-batch --input copies.json 默认只读预览，输入doc_id、space、团队team_uid、copies及执行时expected_version。copies每项为node_id/new_node_id/position。整批只保存一次，任一目标不合规则全部停止；重复新ID停止，保存未知先按固定ID查询，不自动重放。
+
+限普通文本，继承上游/持久引用，不复制边或组。批内引用ID与稳定提示词标记同时映射到新ID，保留手动@@标记；外部引用不变。相较当前本地前端仅映射references的实现，CLI额外同步prompt中的稳定标记，避免副本中引用对象与提示词不一致；预览显示prompt前后。原节点保持；媒体来源历史和跨画布复制未接入。
+
+## 媒体复制、分组编辑与样片转正片补充
+
+- `node copy --input FILE [--yes]`：同画布普通文本/图片视频生成及三类素材；`node copy-batch`：copies数组1–100项，支持混合类型和批内引用重映射。预览/expected_version/一次CAS；派生或进行中成员停止。
+- `graph move-group --input FILE [--yes]`：公共doc_id/space/team_uid/group_id，加position；`graph resize-group`加size及可选position，仅改组框；`graph layout-group`加layout=horizontal/vertical/grid。执行须预览expected_version；详见[分组编辑](material-graph-workflow.md#普通分组移动组框调整与组内重排)。
+- `draft prepare --input FILE --operation NAME`：专用父任务报价及本地计划；输入doc_id/node_id/space/team_uid。`draft submit NAME [--yes --expected-cost OO]`：确认后派生正片素材节点并专用提交；不带--yes只重新预估。`draft get NAME`只查询；`draft recover NAME`查询并同步原任务；`draft wait NAME [--interval MS --timeout MS]`等待并回填。DRAFT_SUBMISSION_UNKNOWN、DRAFT_SYNC_PENDING退出码4，不重提未知任务；协议错误退出码7，通过generation protocol-open由本人签署。详见[样片转正片](generation-workflow.md#样片转正片draft)。
+
+复制来源任务仅为source_task_id，不是副本的last_task_id。生成历史查询分开返回copied_history与远端items；复制来源历史不可普通history-select。上述新增样片流程目前仅模拟/前端codec通过，尚无有效样片真实闭环证据。
+
+## 将普通历史结果添加为新节点
+
+`generation history-add --input history-add.json --operation NAME` 默认保存本地预览，输入为普通历史选择字段再加 `new_node_id`、`position:{"x":0,"y":0}`，可选 `title`、`expected_version`。只接受源普通图片／视频生成节点自身可见、完整交付的已完成历史；不接受其他来源、素材或派生任务。
+
+确认来源和新节点位置后，同输入／operation加 `--yes`：重新验证账号、服务、完整预览快照与历史身份，一次CAS追加节点并独立GET读回。预览后任何画布变化均停止，重新预览核对；显式expected_version也必须匹配。不暂时切换原节点，不新生成、上传、入库，不复制边／组。原节点不变；新节点只带成品、历史模型／配置和去除自动素材准备段的提示词，引用列表为空，不继承审核授权、轮询／提交状态或样片可转正片状态。提示词中留下的@编号不表示请求恢复了输入素材，重新生成前须重新prepare配置。
+
+新节点last_task_id为空，source_task_id和copied_generation_history仅表示来源，不能查询成新节点自己的任务。来源历史保存原任务的模式、时间和原提示词，不将新增节点的无素材默认模式误称为原任务模式。`history-add-get NAME`／`history-add-recover NAME`仅查询原operation和服务端节点；保存未知、冲突均不重发PUT。add_verified核验原新增节点，canvas_preserved／source_unchanged另报当前快照与原保存基线的差异；后续合法编辑其他节点不会自动否认原新增。新节点被改／删则停止，不自动覆盖或重建。
+
+## 服务未开放 CLI 授权
+
+授权接口返回 cli_auth_disabled 时，说明所连服务没有开放 CLI 授权。使用服务支持的正常网页登录，不复制网页令牌或其他服务的凭据。