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

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

@@ -0,0 +1,152 @@
+# 生成与恢复
+
+所有选择和费用确认先遵循 [统一交互流程](interaction-workflow.md)。缺失模型先用 `model options --space personal --type image`（团队带真实 team UID，其他类型相应替换）取得可展示选项，再通过卡片选择模型及适用参数；建议值不代表已选择。普通请求必须优先保存选择到节点并使用 `generation prepare` 构造，不能为了省步骤手写请求或跳过前端约束。
+
+以下命令均以安装后的 `uzoo-anime --profile PROFILE` 为前缀，本任务保持同一 profile。
+
+1. 运行 `auth status` 确认当前账号并复用有效登录；按 [画布流程](canvas-workflow.md) 确定空间、必要团队/项目及目标画布，本任务内沿用明确选择。核对画布 team_uid 与选择一致。用 `model list --space personal` 或 `model list --space team --team-uid UID` 读取实际模型能力，在前端已使用且 CLI 已接入的节点参数范围内，根据用户目标确认缺少的模型、提示词、比例/分辨率/时长、数量与素材；已明确的不要重复询问。目录字段不自动等于可配置开关，不擅自承诺“无声”等未接入能力。缺少目标画布时按画布流程用卡片选择新建/已有及名称，再创建或读取；缺少对应类型节点时执行 `node add --doc ID --type image`（文本/视频换相应类型），再保存选定参数，不需要网页准备。没有生成请求时不要进入本流程。
+2. 有素材时按 [素材与分组流程](material-graph-workflow.md) 上传到普通素材节点或从同空间素材库导入，核验可读取媒体及持久化引用。需要 Seedance 素材审核时先按 [审核流程](seedance-review-workflow.md) 完成并回填原素材。用 `generation prepare --doc DOC_ID --node NODE_ID --space personal --output request.json` 准备请求（团队须改用已确认团队参数）；它读取当前合法上游输出及持久参考，核对模型、参数、参考及审核关联后再预估。没有连线但有持久参考也可准备；不要把本地路径当服务端 URL，不擅自设置 `protocol_agreed` 等用户同意字段。
+3. 将 generation prepare 输出的 request 原样保存为本地 UTF-8 JSON 文件；专用路线使用专用预检/构造器。下方仅解释结构，不作为 Agent 手工拼装请求的操作模板，文档、节点、模型须来自实际查询：
+
+   ```json
+   { "doc_id": "已有文档ID", "node_id": "已有图片节点ID", "segment_type": "image", "model_name": "模型目录的label", "prompt": "一只坐在窗边的猫" }
+   ```
+
+4. `generation estimate --input request.json` 或 `generation submit --input request.json --operation cat-window-001` 查看费用。`will_intercept=true` 时停止并调整参数。费用为预估，最终计费由后端决定；卡片区分预估、实际预扣与结算，不将 --expected-cost 说成最终扣费上限。
+5. 每次先通过交互确认卡片向用户展示个人/团队归属、具体付款钱包、节点、参数和本次预估 OO 币，等待用户当次确认后，执行 `generation submit --input request.json --operation cat-window-001 --yes --expected-cost 已确认的数值`。缺少授权时先向用户展示具体请求和预估。保留 operation 和返回的 task ID。
+6. `generation wait TASK_ID`；完成后 CLI 自动将真实任务结果回填普通生成节点；已完成旧任务或同步中断用 `generation sync TASK_ID`，仅恢复原任务结果，不再次生成。读回节点的 last_task_id/result/status（文本还需 output），再下载与交付。任务与节点、模型不符、已有其他任务、版本冲突时停止，保留用户编辑；不能将任务 completed 等同画布已落结果。超时继续等待同一 ID，失败查看 get/logs，不自动重新生成。
+
+生成结果回填画布不等于存入素材库。当前前端没有自动入库，生成/恢复成功后不追加 material save；只有用户要求保存到库时，才按 [素材入库流程](material-graph-workflow.md#已有节点结果直接存素材库) 明确目标空间及目录选择，再独立执行。
+
+## 团队共享钱包与费用核验
+
+- 团队 OO 币余额由团队成员共用。普通成员只能看到自己的消费记录，不能查看其他成员的消费；本人没有执行消费任务或没有新增本人消费记录时，余额仍可能因其他成员同时使用而减少。这是用户明确的产品规则，不把成员可见账单当作团队全部账单。
+- 费用报告区分本次预估、本次任务实际计费和共享余额快照。核对原 task ID、账号/画布及付款团队，读取实际 `credit_cost`、`billing_status` 等字段，并结合本人可见消费记录；字段缺失、仅有预估或提交结果未知时保留待核验。不要用共享余额起止差额替代本次任务实际费用，也不能把余额不变作为未提交/未扣费的唯一证据。
+- 查询余额时注明团队及查询时点；其他成员消费可能使余额在预估、确认和实际提交之间变化。沿用用户已确认的参数/费用约束，余额不足按真实接口处理；不因此改用个人钱包、换团队或重提任务。
+- 出现“共享余额下降、本人没有新增消费记录”时，先按共享使用与成员可见范围解释；仅此现象不立为 CLI 扣费异常。若调查某笔具体费用，只报告实际能核验的原任务和本人记录，不猜测某个成员/任务。接口费用、原任务重复计费等有独立证据时按相应问题调查；未知提交仍走原 operation 查询/恢复，不因余额变化盲目重试。
+
+可采用的报告口径：“本次任务实际计费 X OO（任务返回）；团队共享余额 Y OO（查询时点）。余额还会受到其他成员使用影响，当前成员只能查看本人消费记录。”没有实际计费证据时将第一项标为待核验，不用预估填充实际消费。
+
+## 参数与前端使用范围
+
+CLI 按当前前端普通节点及请求构造器已使用的字段维护生成参数，不从目录或供应商配置猜测新开关。`generation prepare` 提取对应节点类型已接入的参数；画布中的素材引用、显示样式及其他元数据保留在画布，不整包透传为生成参数。手写请求的未知字段或不适用于该类型的 extra 会在预估/提交前报错，不静默删字段后提交。
+
+当前 extra 字段范围：文本为 context_texts/max_tokens/temperature；图片为 aspect_ratio/resolution/quality/generation_mode/image_count；视频为 aspect_ratio/resolution/generation_mode/draft_preview。字段允许传输不等于相应完整业务路线已验收，仍须遵守本 skill 已标明的模式、模型能力与待完善限制。前端当前没有普通视频声音开关，顶层或 extra.generate_audio/generateAudio 均不支持；不要以是否连接参考音频推断成片是否有声。
+
+历史 operation 已有 task ID 时继续只读查询原任务；尚无 task ID 的旧请求若含不支持参数则停止。不得修改原记录/请求/幂等键来绕过校验，先说明差异并核对原提交副作用。
+
+## 请求准备的参考与默认值
+
+- 持久参考读取优先级为 meta.node_references[node_id]、data.references、data.extra.references，与前端读回顺序一致。视频合并当前入边与持久参考，仍存在的源节点优先使用当前媒体；图片按当前前端优先采用配置的图片参考列表。空输出、上传未完成、本地 blob/data 地址和未解析标记会停止，不复活已清空的旧文本结果。
+- 稳定的 `@{ref:源节点ID}`（ID 可 URL 编码）、前端序号标记及自动标题识别按最终媒体顺序转换为 @图片N/@视频N/@音频N；同名歧义不自动匹配。自动识别可按节点已保存的设置关闭；检查素材准备段和最终提示词，避免断线/改引用后序号含义改变。
+- 文本将上游文字放入 extra.context_texts，与节点自身 prompt 分开；默认 max_tokens=4096、temperature=0.7。图片 quality 在模型允许时默认 medium，asset_type 默认 character；仅支持单张准备。比例/分辨率使用已保存值并核对当前模型选项，缺少视频时长时要求先选定，不自行猜测。
+- Seedance 视频的比例/分辨率按前端放在顶层；图片和其他视频模型按前端放入 extra。prepare 不补用户协议同意；active 审核可生成 reference_canvas_task_ids，素材引用与保存的审核不一致时停止。
+- 当前前端普通图片运行路径以入边判断模式，但参考列表可包含断线保留素材，因此可能出现有 reference_image_urls 而模式为 text2image。CLI 保留该差异并展示实际请求；这不是对服务端能成功执行该组合的保证。需要图生图时先核对实际模型和合法连线，不静默更换模式或丢弃参考。
+
+上述行为通过真实前端 codec、节点 payload 和请求构造器的对照用例，不代表所有模型和真实生成已验收。节点设置来源按前端持久化协议，不以接受某个 extra 字段就宣称支持全部业务流程。
+
+## 视频协议前置检查
+
+Seedance 首次使用或协议更新时，按 [协议签署与继续原任务](agreement-workflow.md) 查询当前 required/agreed/version。HTTP 200 + code 4401 表示《统一协议》中《Seedance2.0模型使用承诺书》待签署，是生成前置条件，不是生成任务失败。
+
+`generation protocol-open` 可单独打开本机阅读确认页，不提交生成。已获当次费用确认的 submit/recover --yes 在需要签署时会打开同样页面，用户本人阅读、勾选并确认后，CLI 核验账号/版本/输入/费用，再以原请求与幂等键继续一次。独立页面不重新打开画布，不向网页暴露 CLI 令牌。正文不可用、用户不同意/超时、版本或参数/费用变化时停止，保留原 operation。不得代填 protocol_agreed 或自动同意。
+
+## 提交中断
+
+遇到超时、断连、网关或内部业务错误时先运行 service status，优先判断当前后端连接和数据库/Redis就绪，再查原 operation/任务和画布副作用。CLI 会对网络/服务类异常追加同源诊断，但保留原错误；ready 不代表对象存储/队列/业务事务都正常，也不证明先前没有提交。连接恢复不构成重发或另一次生成授权。
+
+`generation operations` 找到原 operation。已知 task ID 直接 `get/wait`；也可 `generation recover NAME` 查询。
+
+若状态为 unknown/submitting/prepared 且没有 task ID，当前后端没有按幂等键查询的公开端点。`recover NAME --yes` 会使用持久化的原请求和原幂等键再次调用提交端点，以取得原任务；授权仅限恢复原提交，不能换 key 或改请求。若后端并发任务刚提交尚不可见，等待一段时间后再恢复，避免并发调用。CLI 对同一 profile 使用排他锁。
+
+operation 绑定 API 地址、账号与请求摘要；绑定不匹配时停止调查，不删除记录绕过校验。只有用户明确要求另一次生成时才创建新 operation。默认本地记录含提示词与资源引用，保存在用户配置目录，不写入仓库。
+
+## 普通图片与视频历史选择
+
+这一路线读取普通图片/视频生成节点的真实历史并将所选结果及历史配置写回原节点。素材、文本、转绘/重拍等派生节点、样片转正片未通过本选择命令处理；历史新增节点使用下节history-add。转绘原运行只读查询/导出继续使用 [转绘流程](repaint-workflow.md#原运行只读查询)，不能用普通历史选择代替。
+
+1. 沿用已确认账号、空间和画布；先读取目标节点，再运行 `generation history --doc DOC_ID --node NODE_ID --space personal --status completed --limit 30 --offset 0`。团队换用 `--space team --team-uid UID`。该列表使用 offset/has_more 分页，不用 cursor；has_more=true 时递增 offset 继续。确认目标为该节点可见的已完成普通任务，不能用 redraw 等其他来源的同号任务替代。团队可见历史不等于当前成员可查看全部团队消费。
+2. 用户选定实际 task_id 后，将 `{ "doc_id":"真实画布ID", "node_id":"真实节点ID", "space":"personal", "task_id":123 }` 保存为 UTF-8 JSON；团队改为 team 并补 team_uid。执行 `generation history-select --input history.json --operation NAME`，只保存本地预览，不写画布。
+3. 展示当前结果与所选历史的模型、提示词、比例/分辨率、图片数量或视频时长及样片状态差异。选择会恢复历史结果和相应历史参数；再次选择旧 task_id 也会恢复其历史配置，不恢复切换前另行编辑的配置快照。当前输入参考/审核元数据及其他节点/连线保留，下游已有结果不会重新生成。历史条目中的 credit_cost/billing_status 是原任务计费信息，不是本次切换报价。
+4. 用户明确选择并了解覆盖范围后，沿用同一输入和 operation 加 `--yes`。既有明确选择不重复确认。多人协作时协调暂停同画布编辑，CLI 再读最新快照并按版本仅保存一次；目标节点、历史内容或归属变化立即停止。进行中任务不得切换。切换不提交生成、不扣新的生成费、不另存素材库；历史签名引用改变时可能匿名流式读取原媒体作大小/SHA-256比对，不导出文件或绕过权限。
+5. 检查 state=applied、selection_verified=true，读回 task_id、结果及历史配置。用 `generation history-get NAME` 或 `generation history-recover NAME` 核验原选择；两者仅查询服务/画布并更新本地核验状态，不重发画布 PUT。保存响应丢失或 CAS 冲突时返回 NODE_HISTORY_SAVE_PENDING（退出4），仍查询原 operation。canvas_changed 或 selection_verified=false 时保留当前内容，不自动恢复、重建或换键覆盖；新的选择需重新预览并获得相应授权。不能只凭退出0判定选择仍在画布上。
+
+普通视频历史切换并恢复已完成真实验收；普通图片已完成真实切换与恢复，并在2026-11-03完成网页采用旧项／保存重开／恢复2071再次重开；不新增付费生成。
+
+## 下载原文件
+
+`generation download TASK_ID --output FILE [--sha256 HEX]`先请求原任务业务下载入口，再匿名读取返回的完整url。支持最多5次307引用续期，不向文件地址发送登录凭据；HTTP200中的错误JSON、HTML、不完整流及非预期206/202都停止，不留下最终文件。filename/format不是该业务入口的参数；任务没有文件时从get读取文本结果。下载拒绝不等于生成失败，不重新生成或改用缓存媒体地址绕过；详细边界见[下载与文件凭证](commands.md#下载与文件凭证)。
+
+## Seedance 2.5提示词优化（sd25-pe）
+
+用户指定sd25-pe作为Agent生成Seedance 2.5视频时自动使用的提示词指导。已确定使用Seedance 2.5并进入视频创作流程时，Agent主动读取该skill，在准备生成请求前按其规则形成合适的Prompt，不要求用户主动调用、输入斜杠命令或额外确认是否优化。它不是CLI运行依赖或生成命令，不自动切换用户已选的2.0/mini或其他模型。用户明确要求提示词原样使用时尊重该要求。
+
+### 安装与发现
+
+在用户项目目录执行：
+
+    npx --yes skills@latest add https://arkdocs.tos-cn-beijing.volces.com/skills/ --skill sd25-pe --yes
+
+由宿主发现项目技能目录中的sd25-pe并读取实际SKILL.md。npm安装本CLI不会自动安装或注册它；缺少时说明可选安装方法，取得安装授权后执行。官方skill的自更新步骤遵循宿主权限，失败按其本地版本降级策略继续，不因更新扩展产品能力。本CLI包不内嵌或改写第三方skill。
+
+### 提示词与CLI交接
+
+1. 只优化提示词时不写画布、不估价、不提交，按sd25-pe输出合同交付。实际生成仍遵循空间/画布/模型参数、审核、协议和当次费用确认。
+2. 保留用户明确的角色、数量、台词、因果及素材职责。只读素材，不虚构未读取内容；不要把令牌、签名URL、file_ref或资产凭证交给额外外部服务。优化时可保留不可读素材的原有标签；提交前真实素材必须可绑定且通过校验。
+3. 稳定标记@{ref:节点ID}作为运行环境等价标签交给sd25-pe，保留原样。用户使用@图片N/@视频N/@音频N时，按实际请求的各媒体数组建立映射，不按文件名、混合总顺序或资产ID猜号。优化不得静默改号或删除用户已有引用。
+4. 已有完整节点配置时，先generation prepare核对request、references和source_node_ids；原提示词不完整时先读取节点/拓扑/持久引用，不为预检写占位内容。优化后按用户授权通过node update保存，再次prepare核对最终引用顺序、提示词和审核任务关联；不要提交外部skill手拼的请求JSON。
+5. Prompt中的【未采用素材】不等于从CLI请求移除素材。需要调整实际连线/持久参考时先明确选择并使用已支持操作；普通连线使用graph disconnect预览引用/提示词/模式变化后按授权执行；系统线或纯持久引用无连线的移除不在此命令范围，不通过覆盖快照绕过。保留素材但限制用途与实际移除素材分开报告。
+6. 时长、比例、分辨率与Prompt分开；官方skill描述的素材上限、视频编辑/延长/首尾帧/音频编辑能力不等于当前CLI已接。实际参数以model options、产品已用链路和CLI校验交集为准，不增加generate_audio等未提供控件。
+7. 不默认添加用户未要求的水印/字幕/画质负向包。干净Prompt交给生成流程，素材/参数提示留在说明中。参数或请求变化后重新估价，原未知提交不得因提示词优化换键重提。
+
+正常入口是用户的视频创作请求。Agent在已确认模型、创作意图与素材职责后自动应用sd25-pe，再保存用户授权的节点提示词、prepare核验并估价；无需用户知道该skill名称。只因提示词优化本身不增加一次确认，但核心创作意图有歧义、参数变化或费用提交仍按既有流程确认。已提交/恢复/查询/下载任务不重新优化原请求。
+
+### 协议优先与素材映射
+
+sd25-pe只提供提示词参考，不能覆盖产品前后端请求协议。prepare输出reference_mapping，逐项列marker、media_type、request_field、request_index（从0开始）及source_node_ids，编号取自最终客户端URL数组，不从skill文本猜测。reference_mapping_scope明确为client_request_before_backend_resolution，不等于供应商最终收件顺序。用户已确认当前连接后端修复视频审核引用重排问题；CLI不再为旧前后端问题设置混合审核状态拦截，也不强制统一审核。CLI按当前协议维护媒体数组、稳定节点标记、同类型编号和审核任务关联，审核状态不能改变素材顺序。素材审核本身仍按当前产品要求执行。不要以Prompt说明替代请求校验或改写用户素材职责。
+
+## 样片转正片（draft）
+
+`draft prepare --input FILE --operation NAME`读取同画布普通视频节点和原任务，核验已完成/已结算且draft.step=preview、可用状态、有效期与一致文件引用；用真实draft_task_id专用报价。只保存本地计划，不写画布或提交生成。输入仅doc_id/node_id/space/team_uid，模型、提示词、素材、时长、比例继承样片，正片按产品1080p契约，不增加自定义参数。仅模型名含Draft而任务draft为空不能转正片。
+
+向用户展示计划中的真实父任务、继承输入参数、实际付款钱包及最新报价，取得当次确认后执行`draft submit NAME --yes --expected-cost OO`。提交前重读父任务/归属并重新报价；价格或来源变化停止。协议未签时由用户本人通过generation protocol-open签署，再在请求/费用授权仍有效时沿用原operation继续，不代签。
+
+CLI先一次CAS创建带extra.draft_finalize(parent_node_id/parent_task_id)的素材结果节点及专用来源线，并读回验证；再用固定幂等键调用专用draft-finalize端点。`draft get NAME`查询原计划/任务；`draft recover NAME`查询并同步已知原任务，可能写画布，先确认相关标签关闭；`draft wait NAME`等待原任务并回填独立正片结果。不会自动入库；下载使用已知原task_id的generation download。
+
+提交未知只查询专属输出节点的任务列表并核对doc/node/父任务，唯一匹配才认领；未找到或歧义保持未知，不重POST、不换operation、不删除派生节点。后端可能在幂等查询前校验样片有效期/权益，不能靠重提交恢复。保存未知先读固定节点和来源线，不重放；节点删除/改绑后停止，不重建。模拟恢复与前端待处理/完成资产编解码通过；任务1989并非真实样片；后续已获当次授权并完成2072样片→2073正片的真实CLI闭环及网页重开／完整播放。
+
+## 来源历史与当前验收边界
+
+普通复制节点的`generation history`另列copied_history、copied_history_selectable=false；它是来源历史，不混入该副本自己的远端任务分页，不能将原任务作为副本的普通history-select。普通图片历史验收优先复用已有多历史节点，不擅自付费补造。普通图片／视频均已完成真实服务切换与恢复；图片网页采用、恢复及保存重开已于2026-11-03通过。
+
+普通图片prepare及直接estimate/submit均只支持数值image_count=1，多张／零张／字符串数量在预估前拒绝。当前部署图片设置只有比例/清晰度，高级设置为自动识别引用；未找到数量控件及多结果保存/历史/入库完整契约。目录上限或底层image_count字段不等于多张生成已接入。
+
+代表性Seedance 2.0 mini、图片+视频、双active审核关联、4秒/1:1/480p/组合参考已完成一次真实生成、回填、下载和网页播放；三类媒体组合另完成真实prepare，音频未纳入该次收费请求。网页播放与可解码结果不能证明所有模型或创意效果等效。
+
+样片确认参数从绑定原任务的完成历史读取，包含原提示词、时长及三类素材；不使用已编辑节点的当前输入冒充。任务GET省略这些字段时也不会因本地JSON省略undefined而误判请求变化。
+
+## 同节点再次生成的回填保护
+
+首次确认提交前，CLI在原operation记录目标节点快照syncBaseline。完成后若节点仍显示旧任务，只有原账号/服务/任务operation唯一、节点与提交前快照完全一致、目标任务晚于旧任务且服务端该节点最新任务就是目标时，才允许回填；后续编辑、历史切换、其他新任务或缺少旧记录证据均停止。旧operation不补造快照、不重提生成；可明确选择真实完成历史恢复原产物。下载每次从原业务入口重新取链。
+
+## Draft样片完成回填与基础模型名称
+
+真实样片任务可返回基础模型名；CLI仅在真实preview元数据、节点Draft选择和当前目录对应一致时允许回填，普通模型变更仍停止。精简目录只支持已核对的Seedance 2.5 Draft→Seedance 2.5关系，不泛化去掉任意Draft后缀。extra.draft须保留有效期／状态，重复sync不重写。图片节点新任务切换后旧审核不适用于新成品；prepare拒绝时审核当前真实任务，不能复用旧任务关联。样片生成／正片提交分别确认费用，已生成样片不自动转正片。
+
+## 样片认可后再渲染正片的交互顺序
+
+样片模式用于先以较低画质验证内容、减少试错成本。完成低画质样片并交付后，等待用户认可该视频；用户认可后才进入原样片的draft prepare，核对父任务、有效期及继承参数，并另行展示高画质正片的实际钱包与报价。认可样片内容不自动等于授权扣正片费用，样片费用也不擅自视为抵扣。费用确认后沿用原样片专用finalize接口，保存独立结果节点及父子来源线，完成后查询实际两阶段费用、下载和核验画质。已完成2072→2073真实CLI闭环，重复恢复无新任务或画布写入；正片网页重开、1440×1440／4.064秒完整播放及无解码错误已于2026-11-03通过。
+
+## 将普通历史结果添加为新节点
+
+`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另报当前快照与原保存基线的差异；后续合法编辑其他节点不会自动否认原新增。新节点被改／删则停止，不自动覆盖或重建。
+
+2026-11-03：图片1986与视频2069各新增一次真实通过，网页显示／保存重开通过，视频完整播放通过；没有新生成费。原图片两条历史采用1986、离开重开、恢复2071再次重开及独立服务端读回通过。2073正片网页1440×1440、4.064秒完整播放、无解码错误；CLI父子任务／费用核验见原记录。
+
+## 2026-11-04 新协议v3真实续接通过
+
+猫猫队实际v3未签状态下，CLI先持久化blocked_agreement（无生成POST／远端任务）；本人阅读签署后，通过原recover复核账号、请求及报价，以原operation和同一幂等键提交一次，任务2078完成、实际16 OO，回填／下载／完整解码通过；再次recover无新提交。此项更新v2独立签署后“尚缺收费原任务续接”的历史状态。未向生成接口故意跳过前检制造4401；并发版本变化的服务端4401分支仍为模拟覆盖。正文版本更新必须重读当前服务端状态，不能把本次v3已签当作未来版本同意。

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

@@ -0,0 +1,175 @@
+# 图片素材工具：裁剪、标注与抠图
+
+用户决定、方案与费用确认统一遵循 [交互流程](interaction-workflow.md)：沿用已明确选择，缺项优先用卡片收集，等待回复后继续原任务；本路线的执行、签署与恢复边界仍按下文，不扩展功能。
+
+用于普通图片生成/图片素材节点的已有图片裁剪或标注。运行 `uzoo-anime --profile PROFILE`；当前支持静态 PNG/JPEG、同画布真实已完成图片任务。真实裁剪为768×1024 PNG、生成图面部红框标注为1024×1024 PNG，新增节点/来源线、真实0 OO上传任务及下载查看均通过；裁剪及矩形标注网页显示已由用户2026-11-02确认；其他格式/带方向元数据图片及跨画布来源仍未验证。抠图已接同步／本地后台及服务端异步job，2026-11-05正式202、进程退出后原job恢复、0 OO、透明PNG／落图／用户网页重开通过；没有job_id的未知提交仍不重发，见下文。
+
+## 依赖与输入
+
+- 裁剪/标注在本机需要 FFmpeg 软件包内的 `ffmpeg`、`ffprobe`，复用已有工具；`image tools` 检测，可用 `--ffmpeg PATH --ffprobe PATH` 指定路径。缺失先按 [按需安装](video-tools-workflow.md#本机依赖与按需安装) 告知具体方案并询问，用户同意后 Agent 才安装。CLI 不捆绑/自动下载；业务 --yes 不代表安装授权。抠图由服务端推理，不要求用户安装本机抠图软件。当前仅 Windows 实机通过。
+- 沿用已确认空间、团队、画布与源图，核对实际 team_uid。普通 image/image_upload 必须有同画布真实完成图片任务，当前引用与任务对应；任务重新签发引用时通过实际媒体大小/SHA-256 判断同一内容。不以预览图、节点显示尺寸、同名文件或原图审核标记替代真实来源。
+- 明确裁剪范围：用户可给原图像素矩形，或明确宽高比以取最大居中区域。不要将“裁剪”自动解释成某个比例；不确定需询问，用户已选区域/比例则沿用。CLI 没有画布拖动交互，矩形输入对应前端最终确认的原图区域。
+
+UTF-8 crop.json（团队示例，个人移除 team_uid）：
+
+```json
+{
+  "doc_id": "DOC_ID",
+  "node_id": "SOURCE_NODE_ID",
+  "space": "team",
+  "team_uid": "TEAM_UID",
+  "aspect_ratio": "3:4"
+}
+```
+
+也可用 `"rect":{"left":128,"top":0,"width":768,"height":1024}` 替代 aspect_ratio，两者只能选一项。rect 为原图整数像素，左上角为原点，起点非负、尺寸为正，不能越界。aspect_ratio 支持 3:4 等宽高比，范围 1:20–20:1；取最大居中区域，按前端几何规则四舍五入，不模拟进入网页裁剪态时的临时内缩框。前端也支持自由/固定/自定义区域，本输入是其确认区域的 CLI 表达。
+
+## 预检与执行
+
+1. `image crop --input crop.json --operation crop-001` 默认预检，返回真实原图尺寸、像素 rect、预计输出尺寸和 image/png；不创建 operation、上传或保存画布。签名引用不同可能匿名流式读取媒体作摘要核验。先检测依赖，核对预检是否符合用户目标，并协调暂停同画布旧页面编辑。
+2. 加 `--yes` 执行。CLI 检查后端 ready，绑定账号/服务/原任务/引用/尺寸/区域，下载原图并核验实际尺寸。不是重新生成内容，不扣 AI 生成费用。当前解码仅接入 PNG/JPEG，已识别的旋转/镜像方向及其他编码停止，不宣称全部浏览器图片格式已等效。
+3. 以原图像素裁剪，保留透明通道并导出 PNG。按前端导出限制，最长边 4096、总像素 1600 万，超过时等比缩小、不放大；源图暂限 6400 万像素、下载上限 500MB。预检展示实际输出尺寸，不一概承诺原尺寸导出。FFmpeg 与浏览器的色彩/缩放实现可能有差异，不承诺逐字节相同。
+4. 创建下游图片素材准备节点，标题“原图标题（裁剪）”、文件名“原图标题.png”（本地不合法字符会替换），位置为源节点右侧 width+80、同 y；与前端裁剪一致，保存源→结果的 image-edit-link 系统线。原图、原提示词/任务和其他节点保留；不把裁剪当作普通图片生成或标注产物。
+5. 通过普通节点 upload-session、预签名 PUT、单次 complete 上传，取得真实 local-upload 任务并补齐 URL/file_ref/last_task_id/尺寸与 uploading=false。只有 state=completed、canvas_bound=true 才算完成；准备节点不冒充成功结果。
+6. `image crop-get crop-001` 核对原操作和当前画布，读取真实任务的完成/费用字段，下载核验 PNG、尺寸、原图和来源线；后续重新打开网页人工验收显示。不会自动入素材库、审核或接着生成。裁剪产物是新素材，原图 Seedance 审核不自动继承；用于后续生成时按实际素材重新审核并估价确认。
+
+## 查询与恢复
+
+- 错误先查 service status，再查原 operation、节点和任务，保留原 HTTP/业务码/request_id。`image crop-recover crop-001` 默认只查询，加 --yes 才恢复已知阶段；重复 crop --yes 同样只查询，不换 operation 绕过未知结果。
+- 本地记录位于用户配置目录 image-crops/PROFILE，保存源文件/PNG摘要及原上传阶段；含真实引用和图片，不提交或公开分享。原产物已导出不重新裁剪，文件被修改则停止。仅查已完成结果或恢复已缓存 PNG 的上传不要求重新安装工具。
+- 会话创建未知不创建第二份；已知原分片会话可复用。complete未知绝不再次complete/重传，只查询原doc/node下唯一可核验的已完成图片上传任务且文件名/尺寸匹配后绑定；显示名转换时核验上传回填的task_id/file_ref和0费用charged证据，详见下方标注恢复。没有唯一结果保持upload_unknown，不能据空查询断言没有副作用。
+- 绑定 CAS 冲突只恢复原响应保存，保存丢响应先读回已分配节点/线。明确 CAS 拒绝可用最新快照恢复；节点已缺失/被删、线被删或素材被替换则停止，不重建、不覆盖用户修改。账号、服务、源任务/引用/尺寸变化也停止。
+- CROP_UPLOAD_UNKNOWN/CROP_SYNC_PENDING 退出码4，依赖错误 MEDIA_UNAVAILABLE 为2。查询命令仍需检查 state（含 canvas_changed/upload_unknown/sync_pending），不能只按退出码判断完成。
+
+## 图片标注
+
+已实现矩形、椭圆、直线、画笔点列、单行文字的PNG合成；图形旋转可用，文字旋转明确不可用（待完善）。输入均为原图像素，按数组顺序叠加，不重新生成图像。真实验收仅覆盖生成图面部红框；其他工具、中文字形、透明通道及素材源产出通过本地/前端兼容测试，尚未逐项真实上传。
+
+### 依赖和输入选择
+
+- 复用本机FFmpeg/FFprobe；图形还需FFmpeg构建具备drawvg过滤器，文字需drawtext和包含本次字形的字体文件。实际annotate预检会检查用到的过滤器/字体；image tools仅检查基础工具，不代表标注全部能力已就绪。缺能力时先说明并询问是否更新兼容构建或提供已有路径，依然先同意后安装，不能把已有FFmpeg不含过滤器误报为“没装”。
+- 无文字的标注不要求字体。文字可在输入font_file给本机字体路径；Windows默认尝试已安装微软雅黑msyh.ttc，其他系统须提供字体。检查字体文件及实际文字的Unicode字形，不以缺字方框宣称完成；缺字体先让用户选择已有字体或确认具体安装方案，不自动下载。当前跨平台、其他字体/复杂文字排版未实机验收。
+- 用户明确图形/文字及目标位置后，Agent可依据原图准备坐标，不需要用户逐字段给像素。定位含糊会影响结果时再澄清。不要默认把“标注”当AI编辑、加收费模型、自动入库或审核。
+
+UTF-8 annotations.json示例（团队；个人移除team_uid；ID替换为本次实际值）：
+
+```json
+{
+  "doc_id": "DOC_ID",
+  "node_id": "SOURCE_NODE_ID",
+  "space": "team",
+  "team_uid": "TEAM_UID",
+  "commands": [
+    {"type":"rect","x":100,"y":100,"width":200,"height":250,"color":"#ff4d4f","strokeWidth":6}
+  ]
+}
+```
+
+| type | 字段与含义 |
+|---|---|
+| rect / ellipse | x/y/width/height，原图像素；负宽高会转为相应正向包围框，尺寸不能为0 |
+| line | x/y起点、x2/y2终点 |
+| brush | points为至少2个{x,y}点的折线；圆端点/圆连接，不自动平滑改写轨迹 |
+| text | x/y为文字盒左上角，text为非空单行，fontSize默认16原图像素；基线为y+fontSize，文字旋转暂不支持 |
+
+所有类型可选color（默认前端红色#ff4d4f，支持#RRGGBB/#RRGGBBAA）。图形可选strokeWidth（默认1、1–512像素）和rotation（默认0、-360至360度，围绕图形包围框中心）；文字fontSize范围1–1024。一次1–100条指令、画笔累计最多20000点；输入坐标不可超原图边界，旋转/线宽扩展边缘按画布裁切。未知字段停止，不接受渲染脚本。不会复现网页撤销/重做的内存历史。
+
+### 标注执行与产出
+
+1. `image annotate --input annotations.json --operation annotate-001`仅预检，展示原图/输出尺寸、规范化commands及output_type，不建operation或远端节点。确认源图/标注位置并暂停同画布旧页面编辑；相同参数加--yes执行。每次来源归属和依赖均核验，写入前要求后端ready。
+2. CLI下载原PNG/JPEG、核对真实尺寸，在本机合成PNG。最长边4096、总像素1600万等比缩小、不放大，原图保留。已识别的方向元数据和其他格式停止；FFmpeg/Cairo/字体与浏览器的抗锯齿、色彩、字重等可能不同，不承诺逐像素或字节相同。文字字号/基线按前端语义，当前不提供用户可调字体字重控件。
+3. **生成图源image → 下游普通image，extra.node_kind=generation；素材图源image_upload → 下游image_upload，node_kind=asset。** 两者标题“原图标题（标注）”、文件名“原图标题.png”、位于源右侧width+80同y，保存image-edit-link。不得将生成图标注产出错误保存为素材节点；后端上传及前端识别也须保留正确marker。
+4. 用普通upload-session/PUT/单次upload-complete上传，绑定真实任务/引用与完成状态。普通图片结果必须写入generation marker，否则前端可能按文件信息误判成asset；不复制源图的原任务/审核状态。上传后查询模型名可能是“生成模型”等显示标签，这不是本次调用AI生成的证据；本地合成、上传端点、真实任务计费分别核验。
+5. `image annotate-get annotate-001`查原结果，state=completed且canvas_bound=true后，读回节点类型、last_task_id、媒体、来源线并下载PNG查看。费用读取原任务credit_cost/billing_status，团队余额只列当前共享快照，不以差额归因；不自动保存素材库、继承原图审核或发起后续生成。
+
+### 标注恢复与边界
+
+- `image annotate-recover annotate-001`默认只查，加--yes才恢复已知阶段。重复annotate --yes不创建第二次；原账号/服务/来源节点类型、任务、引用和尺寸变化停止。本地源图/PNG及文字字体摘要保护，已导出结果不重画；仅恢复缓存上传不要求重新安装渲染工具。
+- 会话未知不申请第二份；complete未知不重传/重发，只查原doc/node下唯一完成图片任务，匹配文件名及尺寸。可用真实local-upload标识；模型名被转为显示标签时，必须同时匹配后端upload-complete回填的节点task_id/file_ref及0费用charged证据，不按中文标签猜上传任务。缺少证据停在未知状态。
+- CAS/绑定丢响应只恢复原产物；节点/线被删、结果被替换则停止，不自动重建。错误先查服务和原操作。记录与缓存位于用户配置目录image-annotations/PROFILE，包含媒体/本机路径，勿提交/公开分享。ANNOTATION_UPLOAD_UNKNOWN/ANNOTATION_SYNC_PENDING退出码4，MEDIA_UNAVAILABLE为2，查询还需检查state。
+
+## 图片抠图
+
+`image matting-check --input FILE`只读核对服务、归属、真实原图与钱包，status=preflight_only，不探测推理。输入只接受doc_id/node_id/space，团队另带team_uid，不开放model／threshold／价格参数。
+
+`image matting --input FILE --operation NAME`先保存本地预览；用户明确选择原图并确认画布关闭／离开保存后，同输入和operation加`--yes`仅提交一次。较慢处理可设置全局`--request-timeout 180000`，超时不代表可以重发。仅接入同画布普通图片／图片素材中的已完成PNG/JPEG任务。
+
+请求固定general、签名multipart字段file_ref/model/scope/team_uid，不传threshold、不重传原图、不安装本机推理软件。用户已确认当前产品免费，预览expected_credit_cost=0依据该产品约定，不冒称有独立报价接口。返回必须为PNG、正确源引用、X-Result-Ref和X-Credit-Cost=0；不符合时缓存原字节、停止落图、不重发。余额0不阻止免费处理，不以余额差额证明费用。
+
+原字节缓存后核验PNG签名／CRC／完整像素及透明背景／有效前景、尺寸与原图一致。目前支持6400万像素内非交错8位RGBA静态PNG；不支持的编码或无有效透明前景时保留结果、不转码或重做。无需FFmpeg依赖。
+
+成功后一次CAS新增image_upload素材与matting-link，独立GET读回并核对其他内容保持。成品不认领原上传／生成任务、不继承审核、不自动入库。output为原PNG缓存路径，image包含字节／摘要／alpha统计。
+
+`image matting-get NAME`只读核验；`image matting-recover NAME`默认只查询，`--yes`仅恢复已知结果／尚未尝试保存的落图。已知成功响应有原结果引用而缓存丢失时，可GET原引用恢复，绝不重新POST。submitting/submission_unknown无结果引用时没有可靠服务端查询，保持未知、不重发，不用源任务ID冒充抠图任务，也不认领最新同源结果。rejected／receipt_unverified／result_unverified不自动重做。
+
+保存未知／CAS冲突只读核对固定结果及来源线，不重PUT；被删、改绑、改名或缺来源线时保留当前画布、不重建。网页补默认字段、精简JSON或调整位置尺寸不会误报失败：canvas_verified核对稳定成品引用、身份、文件名大小及来源关系；canvas_exactly_matches另报是否逐字段相等。原operation不能改绑服务／账号。
+
+2026-11-04正式站原图7738真实免费执行、透明PNG、CAS落图、原结果GET／缓存核验及用户确认网页保存重开通过。42组完整模拟及实际前端factory／codec重开对照通过；无引用的未知提交服务端查回仍未接入。详见包内docs/图片抠图接入与验收-20261104.md。
+
+## 图片抠图只读预检
+
+原预检入口保持，具体执行与恢复见上节。以下日期条目保留历史阶段记录，以2026-11-04真实执行更新为准。
+
+## 2026-11-03 用户确认的抠图部署边界
+
+用户明确当前抠图为免费服务，但开发部署没有抠图服务，只有正式部署才有；这更新前述待核价历史记录。本轮不调用开发服务POST探测、不切换正式服务，也不再将收费报价作为该免费服务的当前阻塞。正式部署验收仍需核对真实入口、免费约束、结果引用、透明通道、原结果查询与未知提交恢复；有图片返回不等于完整闭环。不自动安装推理依赖或把模型目录当作可用部署。
+
+2026-11-03正式站补验：用户指定https://uzooai.com，使用独立本地加密profile准备本人网页登录授权；实际创建授权请求返回2110/cli_auth_disabled，未打开有效授权页、未取得正式站令牌。用户选择暂不启用，停止该路线，不导入开发站凭据、不探测推理POST。开发源码不能证明正式版协议，执行与原结果查询／未知恢复仍未接入；这不否定正式站网页抠图可用或免费。
+
+## 2026-11-04 正式站接入更新
+
+当前用户指定实际服务为https://uzooai.com，使用独立uzooai-online profile。用户启用授权后本人正常登录／授权及账号读回成功，历史2110/cli_auth_disabled阻塞已解除。正式站实际账号／团队与开发站不同，操作前重新查询并绑定实际对象，不迁移旧operation的服务地址。抠图已接入单次免费执行及已知原结果／缓存恢复，正式站真实处理和用户确认网页重开通过；未知响应无结果引用时仍无法服务端查回，不重发。免费处理不以余额0判不可用。
+
+## 同步响应、节点回填与3秒复查
+
+当前未变更接口是POST等待完成返回PNG／结果头，前端收到后更新结果节点并保存；可选后端内部排队仍返回原HTTP响应，不等于后台直接回填画布。页面processing/0→completed/100也不等于有实时进度查询接口。用户提供常见执行约3秒（不含排队），可作为已知节点的首次只读复查建议间隔；未出结果仍保留等待，不按3秒判失败。CLI／前端仍收到响应并完成保存，或者保存结果未知时，可读固定结果节点核验；原处理响应丢失且没有结果引用时，画布尚无可回填PNG，单靠等3秒读画布不能恢复。不新增请求绑定字段或重POST来掩盖此限制。
+
+## 抠图独立后台执行与本地查询
+
+为避免Agent或启动命令退出中断等待，可在完成同一operation的matting预览后使用：
+
+```sh
+uzoo-anime --profile PROFILE image matting --input matting.json --operation matting-001
+uzoo-anime --profile PROFILE --request-timeout 180000 image matting-start matting-001 --yes
+uzoo-anime --profile PROFILE image matting-status matting-001
+uzoo-anime --profile PROFILE image matting-recover matting-001 --yes
+```
+
+先取得本次原图／免费处理授权。matting-start默认只预览，加--yes才启动独立Node进程；后台只接收并缓存原PNG，不自动保存画布。约3秒后查询同一operation，未完成继续等待；3秒不是总时限，request-timeout包含排队及响应等待。后台启动参数仅含profile／operation／本地worker标识／超时，凭据由受保护profile加载。
+
+matting-status始终只读本地记录，不联网、不取凭据、不等待profile锁；后台operation的matting-get也返回同样本地状态。local_only=true／account_verified_online=false，不能据此宣称当前画布已保存或账号在线验证通过。worker_alive和心跳只说明本地进程，progress=null；没有服务端细分进度／后台任务查询接口。finished表示接收流程结束，仍需检查state=result_ready、known_result_reference与PNG核验。
+
+result_ready后按交互流程确认画布关闭／离开保存（本连续任务已有确认且未重开则沿用），再用原matting-recover --yes核验来源和最新画布并一次CAS回填；保存未知不重放。matting-recover不加--yes可做服务端只读核验。不要为后台缓存完成自动重开网页或偷偷写画布。完成并读回后，可从新标签打开验收。
+
+后台等待时持有该profile锁，其他联网命令可能提示正在使用；用matting-status查询即可，不删除活跃锁或并行登录。正常结束自动解锁。强杀／关机后不会自动重启；若留下锁，先确认原进程确已退出，再按原profile锁规则处理，保留operation／PNG／worker记录。只有尚未attempted且来源版本仍匹配的原operation可显式重新启动；attempted后重复启动只查状态，绝不重POST。submission_unknown或中断且无原结果引用时仍无法服务端查回，不以读画布／最新同源产物冒充恢复。桌面宿主若强制杀掉全部子进程，也不保证后台存活；本机已验证启动命令正常退出后的独立进程存活。
+
+## 服务端异步抠图任务
+
+用户于2026-11-04提供的新接口说明：POST /matting/jobs以表单提交，HTTP202返回job_id；GET /matting/jobs/{job_id}仅提交者可查，状态queued／processing／succeeded／failed／cancelled，成功返回result_ref／result_url／credit_cost。旧POST /matting仍直接返回PNG。前端已按用户要求从3d3a2a84安全快进到origin/master 919c71b8，工作区保持干净；实际nodeActionService调用createAndPoll，表单、202与job_id、五种status及裸／code-data包装响应已逐段核对，并用实际service只读加载对照通过。正式站一次实际提交返回HTTP200／业务码3001且无job_id，后续job查询与任意不存在路由同为“请求的资源不存在”；成功任务与完整恢复真实验收仍受部署／原请求核验阻塞，不宣称正式通过。
+
+优先使用服务端job可让已接收任务在CLI／Agent退出后继续执行，不再需要本地worker持有原PNG连接：
+
+```sh
+uzoo-anime --profile PROFILE image matting --input matting.json --operation matting-job-001
+uzoo-anime --profile PROFILE image matting-submit matting-job-001 --yes
+uzoo-anime --profile PROFILE image matting-get matting-job-001
+uzoo-anime --profile PROFILE image matting-recover matting-job-001 --yes
+```
+
+先确认原图及本次免费处理；默认matting-submit仅预览，--yes才入队，固定general、原file_ref与显式scope；团队带team_uid，个人不带。收到job_id立即持久保存到原operation，随后校验HTTP202；非202但已知ID仍保留供原ID查询，不重提。入队不创建空画布节点，不自动落图／入库。
+
+matting-get联网查询原job并保存本地状态，不写画布、不下载PNG；queued／processing约3秒后继续原ID查询，不显示臆造的进度百分比。succeeded必须有合法result_ref和实际credit_cost=0，若响应同时带job_id／source_ref必须匹配。结果通过当前可信服务的/api/v1/files/{result_ref}匿名GET取得，沿用307续期、PNG／CRC／尺寸／alpha／缓存摘要核验，不向result_url发送凭据。异常费用保留本地reported_credit_cost、停止落图，不静默当免费。
+
+完成后按交互流程确认目标画布关闭并保存，再原matting-recover --yes取回PNG、重新核验账号／团队／来源、最新快照与一次CAS读回。重复recover只核验已有节点；保存未知／冲突不重PUT、用户删除不重建。失败／取消保留原job，不自动换键或重新处理。
+
+异步operation的matting-status仍是无需凭据和profile锁的本地快照，job_id／job_status不代表本次已联网；matting-get才是服务端查询。同步旧operation仍按旧接口恢复，本地worker旧operation的matting-get仍只查本地；不迁移已提交记录、不改绑传输模式。matting-submit不能抢占已有本地后台预留operation。
+
+提交响应真正丢失且未拿到job_id时，当前说明没有提供幂等提交／按请求键找回契约，仍为submission_unknown，不重POST，也不认领最新同源job。新增查询只解决已知job_id后的恢复，不能将旧同步未知operation自动转换为新任务。
+
+2026-11-05更新后真实只读检查为HTTP403／2001“CLI 无权调用此接口”，不是生成协议／登录失效，也不能以网页令牌绕过。需维护者允许精确POST app.api.v1.matting.submit_matting_job、GET app.api.v1.matting.get_matting_job，并保留资源权限；确认旧未知request_id的副作用后再继续。CLI实现不因部署变化自动重提。当前真实成功仍未通过，详见包内docs/异步抠图CLI权限交接-20261105.md。
+
+2026-11-05用户随后决定等待其通知后端修复更新，并说明仓库后端不是最新版：本异步真实补验暂停等待，不自动轮询／拉取／重提；旧快照中的函数权限键只作交接参考，不能作为最新实现或部署证明。收到通知后重查实际契约／权限及旧未知请求副作用，再按原operation恢复；画布写入另需当时有效的关闭确认。
+
+## 2026-11-05 异步路线实际验收更新
+
+用户已通知权限修复并确认旧请求经服务端核验未入队，且重新确认画布关闭；此前等待决定已解除。正式站一次新关联operation确认202并保留job_id，提交进程退出后新CLI进程查询同job成功、实际credit_cost=0；原recover取回透明PNG并一次CAS、重复恢复不重放通过。用户确认本次结果显示正常、保存重开后结果和来源线仍在；随后服务端只读核验通过，网页规范化不要求全JSON相等。旧同步／本地后台记录继续原路径，不篡改旧未知记录。无job_id的未知提交仍不能自动重发；已确认未执行后如需新提交，应保留旧诊断、明确记录关联与核验来源。仓库旧权限键仅作历史参考，实际权限以当前部署正常CLI响应核对。详见包内docs/异步抠图真实验收-20261105.md；真实排队／失败／跨账号等仍未专项验证。

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

@@ -0,0 +1,67 @@
+# 真实任务的交互卡片与续接
+
+适用于本技能所有真实任务：创建/编辑画布节点、创作生成、素材上传/入库/复用、裁剪/标注/截帧/剪辑、审核、分段方案、反推/最终提示词与重拍。只询问当前任务缺失且影响结果的决定；只读查询、用户已明确或已明确委托的选择直接沿用，不将每条命令变成确认环节。各专用流程的能力、协议、依赖和原操作恢复边界继续适用。
+
+## 卡片与等待
+
+- 优先使用当前宿主实际提供的选择/自由文本交互工具，例如可用的 request_user_input_async；遵守工具适用模式与权限限制。不要把命令行 JSON 输出说成已显示了宿主卡片。宿主没有适用工具时，明确说明并退回简短文字询问，保留当前任务。
+- 独立问题可以同卡片分组；有依赖的选择分步进行，例如先选择模型，再展示该模型参数。卡片不支持联动表单时拆卡，不虚构动态表单能力。
+- 卡片发出后保持任务处于等待输入阶段：有独立的只读工作可继续，没有则使用宿主允许的等待/让出机制接收回答，不发送 final/最终回复询问“确认吗”来结束任务，也不要求用户再输入“继续”。收到回复后自动继续原任务。宿主生命周期限制不能由 skill 改写；能力不足时如实说明，不声称可保证永久保持同一运行回合。
+- 选择、费用和安装等明确授权未到时不执行依赖动作。预选项、空答、超时、卡片关闭都不是同意，也不能当作委托 Agent 选择。取消则停止对应动作；再次打开时沿用已核验状态。
+- 选项来自当前服务、账号和所选空间的真实查询。名称重复时显示名称与简短 ID/项目等区分信息，内部绑定完整 ID；不要要求用户手抄 ID。长列表按实际分页或接口已支持的搜索继续展示，不能隐藏其余候选或声称第一页是全部。
+- 保留当前阶段、已明确选择、画布/节点、请求文件、预估和原 operation/task ID；收到中途修改时只回退受影响步骤。未提交且专用 operation 尚未绑定配置时更新配置并重新准备/估价；已绑定预检配置的分段/重拍等按专用修改契约处理，确认原操作未执行后才可为新配置建立新 operation，不删除或篡改原记录。保留同一业务任务不等于强制所有阶段共用一个 operation；已提交或结果未知时先查原任务，不因用户修改就再收费或换键重试。
+
+## 画布标签关闭确认
+
+2026-11-02用户要求：前端保存冲突暂只记录，使用关闭画布页标签的临时规避方式。在CLI执行画布操作前，先通过卡片向用户确认目标画布页标签已关闭。说明原因：网页可能保留旧内容，自动保存会覆盖CLI结果；只停止编辑或退回工作台不足以规避。
+
+- 对已有画布的节点/连线/配置修改、上传绑定、历史切换、工具产物落图和生成结果回填，在首次执行前确认。`generation wait`、sync/recover等可能写回画布的命令同样适用；不能按命令名将其视作纯查询。
+- 卡片写明目标画布，询问“是否已关闭该画布的所有相关网页标签（包括其他窗口/设备，并协调其他编辑者）并等待离开保存完成，且在CLI完成前保持关闭？”可选“已关闭并完成保存”“尚未关闭，先等待”。未明确回复不执行依赖的画布操作，可继续独立只读工作；不自动关闭用户页面。
+- 本次连续任务已有明确关闭确认、且未重新打开时直接沿用，不逐命令重复问。仅有此前日期的“暂停编辑”不满足本次确认；目标切换、页面重开或状态不明时重新确认。新建画布尚无对应网页标签时不要求先打开再关闭，创建后保持关闭。
+- 关闭后的离开保存也可能提交旧内容，所以确认后先重新读取最新画布、核对来源与版本，再执行原授权操作。来源变化、节点缺失或CAS冲突时停止，不自动恢复、覆盖或重传。
+- CLI完成并读回核验后，提示从新标签页打开，确保重新加载服务端内容；不要复用工作台中保留旧画布状态的页面。这是临时协作措施，不是冲突根因已修复或并发安全保证。
+- 纯只读list/get/history、状态查询、以及不读取或写入画布的素材库下载无需关闭确认。费用、依赖安装与原业务授权仍按各自规则处理。
+
+## 先确定任务目标
+
+| 决定 | 何时询问及展示内容 |
+|---|---|
+| 空间/团队/必要项目 | 未选个人或团队时用卡片问；团队来自真实 teams，用户选团队且仅一个可用时告知后复用；多团队卡片选择。项目仅任务需要时询问 |
+| 目标画布 | 未明确目标时先查询所选范围，再提供新建/已有画布选择；已有画布按真实分页列表选择并 get 核验。用户明确指定目标则直接核验 |
+| 新画布名称 | 用户选择新建但未给名称时，卡片允许自由输入或明确接受建议名称；显示建议不等于用户接受，不能先创建后再问 |
+| 节点/素材/素材库目录 | 有多个来源或目标且无法从任务确定时卡片选择；不得自行挑私人文件。入库目录须用户指定或明确委托，即使唯一也不能擅定；结果落画布不自动入库 |
+| 模型和参数 | 普通创作按下节处理；不需要模型的剪辑、入库、纯节点创建等不问模型。专用分析/反推等服务固定模型不增加虚构模型开关 |
+| 处理范围/方案 | 裁剪区域或比例、截帧时间、剪辑区间、分段模式/间隔、切点方案版本、重拍源片与范围等缺项用卡片收集；已有明确要求不重复问 |
+
+创建/写入只在目标与必要选择明确后执行，用户授权范围内不收费的节点创建不额外逐条审批。画布-only、node-only、只读预检任务在所请求范围完成即交付，不进入无关估价或生成。
+
+## 模型与参数选择及标准请求
+
+1. 运行 `model options --space personal --type image`，团队替换为 `--space team --team-uid UID`，文本/视频替换 type。它投影实时目录中的普通节点控件，返回完整模型 label、selectable、controls、node_path、建议值；`model list` 保留原始能力信息，用于参考限制核对。不可用模型可说明原因，但不能作为可执行选项。若未指定模型，卡片展示真实候选，不自行挑第一个；含多个版本的模糊名称需解析。
+2. 用户选定模型后展示适用参数：图片比例/分辨率/模型实际提供的质量、当前仅支持的单张；视频比例/分辨率/时长等。已有指定值沿用并校验，尚未明确的可变项让用户选择或明确接受列出的默认方案。只有一个合法值可告知并纳入最终配置，不做无意义单选。Agent 可以推荐，但建议/预选不等于接受；“按你建议的配置”才属于明确委托。
+3. 可选范围是实时能力、前端实际控件与 CLI 已接入功能的交集。model options 仅针对 ordinary_generation，不替代重拍/分段等专用控件；not_applicable_modes 所列模式隐藏对应参数，fixed 值只展示不要求用户更改；样片名称与目录能力不一致的模型标为不可选。`controls.suggested` 仅供展示，实际已有节点值优先；模型变更后重新校验保留项，不静默替换无效值。图片数量不能按模型 max_images_per_request 暗中开放批量；文本目前不因目录/prepare内部字段自行新增参数控件。
+4. `generation_modes` 是能力信息，不是可直接生成的模式列表。实际素材/连线、图生图开关、样片固定分辨率、视频编辑/延长等约束必须按现有前端行为和专用流程处理；模式选择若有歧义仅展示当前输入合法的选项。不因目录出现 output_formats/provider/admin 字段增加生成开关；没有前端声音开关就不问或发送 generate_audio。
+5. 将选择保存到原节点，使用返回的 node_path 对应持久 API 字段（模型为 data.model_name；不要误写成网页内部的 data.model）。普通生成运行 `generation prepare --doc ID --node ID --space ... --output request.json`。节点修改、画布读回与请求构造必须核验原归属；文件 UTF-8，不覆盖另一请求。按每个 control.node_path 和 mirror_node_paths 同步保存，避免历史顶层/extra重复值覆盖本次选择；保存后逐项核对用户选择＝节点生效值＝prepare请求，不一致则停止估价。存在旧 generation_config 等更高优先级字段时先核对真实前端读回，不盲目覆盖历史配置。模型和字段值从查询/用户决定取得，不手工拼接请求体替代 prepare，也不把卡片字段原样发到 API。
+6. 专用路线用各自的 prepare/start/plan 预检及既有请求构造器，不能以普通 generation 命令代替分段、重拍、素材工具。生成请求及引用准备后，与已确认参数逐项核对；自动解析引用或模式得出的实际差异须在执行前展示，必要时重新选择。
+
+运行时不读取前端源码；开发维护时只读对照前端控件、持久化 codec、payload 与请求构造器，再补 CLI 兼容验证。不允许通过运行接口是否接受 extra 来扩展控件。
+
+## 费用卡片与执行
+
+参数与素材确定后，调用本路线真实预估/预检。确认卡片展示：执行动作及范围、目标画布/节点或素材目录、个人/团队/必要项目、实际付款钱包、模型和完整生效参数、当前预估 OO 币、适用权益/预扣规则（仅接口确有提供时）。收费服务字段缺失时保留“费用待核验”，禁止提供可执行费用确认或运行 --yes，不能把 null 当免费。提供“确认执行（预估 X OO）”“修改配置”“取消”。零 OO 的生成/独立分析阶段也展示真实范围，不将其扩成后续收费授权。
+
+- 取得这张卡片的明确回复后才运行对应 `--yes`。普通生成首次提交必须带 --expected-cost，旧恢复记录缺确认金额时同样必须先确认并带该参数；其他支持该参数的路线也带入确认数值。报价或输入变化时停止提交、重估并重新确认，不沿用旧卡片。批量或分阶段费用必须按已接入范围逐步确认，不以总任务要求授权所有后续消费。
+- 普通节点创建/已授权的免费处理不用额外制造收费确认；若专用流程要求方案或执行确认，卡片承担该步骤，不重复询问同一次决定。实际本机软件安装要单独展示方案并取得安装授权。
+- 预估、实际预扣和最终结算分别报告，不能把估价或 expected-cost 描述为保证最终费用上限；团队余额差额不代表本次消费。
+- 卡片授权与系统命令执行审批独立。执行权限继续走宿主审批工具；用户协议必须通过既有阅读签署流程由本人确认，聊天卡片不能代签。
+- 确认后执行同一 operation，保留幂等键和 task ID，自动查询、同步、下载并交付。等待超时继续查询原任务；响应未知先查原副作用再按专用恢复规则处理，不换键重提。不要在提交成功或排队时就结束整个创作任务。
+
+## 验收情景
+
+- “画一张图”且无目标：询问画布新建/已有和模型参数，不能默认新建、默认模型后只问费用。
+- “在已有画布 X，用 Sunburst，2K，16:9，默认质量画一张”：核验目标和配置后估价，用费用卡片确认，不重复问已明确项。
+- “新建画布”而未给名称：卡片输入或接受建议名称，创建核验后结束，不问模型或扣费。
+- “截取视频 1–3 秒”：核验明确素材和画布，走剪辑预检，不新增模型选择；缺源则卡片询问。
+- “把这张结果存素材库”：查真实目录并卡片选择，除非已有明确目录/委托；不重新生成。
+- “智能分析并分段”：分析估价卡片确认后执行；真实方案到达后用方案卡片确认当前版本，不自动确认切片或继续反推/生成。
+- 等待费用卡片时用户改模型：旧卡片报价作废，重新准备及预估；不提交旧请求。卡片取消/无答复不执行依赖该卡片的新动作；此前已授权保存或上传的结果保留，不自动删除或回滚。