标准作业流程（SOP）

本专题手工维护。本文把工具串成可照做的流程（每条都给工具序列 + 判据 + 常见坑）。

规矩细节见 03-调用规范（画布寻址·端口·参数·提示词）.md；工具说明见 02-工具全景与现查方法.md。

SOP-0 每次开工的 10 秒检查（所有流程共用）

uc_do_gain_agent_overview   → 系统理解（会话首次）
uc_do_gain_canvas_rules     → 读规则 + 登记已读（写操作前置）
uc_do_health                → 要跑本地引擎时：comfyui=true ？
uc_do_sheet_templates       → 目标模板 enabled=true ？

⛔ 缺任何一步都可能白跑一轮（尤其是 enabled 与 health）。

SOP-1 最小可用：出一张图

uc_do_new_canvas                                  → canvasId
uc_do_sheet_templates / uc_do_gain_template_guide → 选模板，看 parameters
uc_do_create_node(workflowId, canvasId=…)         → nodeId
uc_do_write_node_params(nodeId, {宽度/高度/…})     → 按模板 parameters 校验
uc_do_write_node_prompt(nodeId, prompt)           → 提示词（先查 prompt_rules）
uc_do_run_node(nodeId)                            → jobId
uc_do_wait_for_job(jobId)                         → 等完成
uc_do_gain_node_result(nodeId)                    → 产物本地路径 ✓

判据：uc_do_gain_node_result 返回了文件路径（且文件真的存在）⇒ 才算成功。

坑：enabled=false 的模板创建不出来；api 引擎模板受「API 节点开关」约束（见 05-…）。

SOP-2 一段视频：参考图 + 分镜提示词

（SOP-0 检查）
uc_do_upload_asset(参考图路径)                     → 素材节点
uc_do_suggest_prompt(workflowId, [参考图…], 运动提示) → 分镜式提示词（首选）
uc_do_create_node(视频模板, canvasId=…)            → nodeId
uc_do_write_node_prompt(nodeId, 上一步提示词)
uc_do_write_node_params(nodeId, {时长/分辨率/…})
uc_do_connect_nodes(素材节点, 模板节点, targetPort='references' 或具体输入口)
uc_do_run_node → uc_do_wait_for_job → uc_do_gain_node_result

坑：

• 多参考必须同一主体（同一人物/物体的不同角度）；提示词写动作/运动，⛔ 不写"图1切到图2"
• upload 节点输出端口恒为 result；text/image/video/audio 是类型不是端口 id
• 复合端口（海螺 references）按连接顺序组装 ⇒ 顺序＝你的连线顺序

SOP-3 多镜头/短剧：成组批量

uc_do_new_canvas                                  → 一张专用画布（⛔ 别在用户画布上堆）
（逐镜）uc_do_create_media_node(templateId/mediaRole/mode/inputAssets/groupName) → 直填参考免连线
（逐镜）uc_do_write_media_node_patch(nodeId, {prompt, params…})
（逐镜）uc_do_run_node + uc_do_wait_for_job
uc_do_gain_group_nodes(groupName)                 → 看每个镜头的 status / result.files

• 分组：建节点时给 groupName，或用 uc_do_ensure_group(groupName, [nodeId…]) 后补归组
• 逐镜验收：用 uc_do_gain_group_nodes 点名谁没出/失败，再单独重跑那一个（⛔ 别整批重跑）
• 创作者画布（folder_creator）：先 uc_do_gain_canvas_globals 读导演台计划（assets/shots/engines/ui），按计划逐镜执行；蓝图类任务用

uc_do_gain_blueprint_spec → uc_do_validate_blueprint → uc_do_preflight_engine → uc_do_director_run

SOP-4 素材盘点与审片

uc_do_sheet_assets                       → 本机资产库（选材入口）
uc_do_inventory_media(…, 每视频 N 帧)     → 批量抽帧盘点
uc_do_extract_frame(视频, 时间点)          → 抽一帧存 jpg（审片留证）
uc_do_analyze_image(图片路径)             → 反推成详细提示词描述（可复用为提示词）

坑：uc_do_analyze_image 走 ComfyUI 运行（约 30~60 秒，会自动清理临时节点）⇒ 别当成"秒回"的工具。

SOP-5 知识库与技能维护

uc_do_kb_sheet                  → 先看规模/结构
uc_do_kb_search(关键词) → uc_do_kb_get(id)   → 检索到取全文
uc_do_kb_skill_list → _get → _add / _edit / _del（删除＝停用，可复活）
uc_do_kb_consolidate            → 知识树整合
uc_do_kb_write                  → ⚠ 这是**提工单**（不是写知识条目）
uc_do_kb_ticket_state / _list / _review / _rate  → 跟进工单

坑：⛔ 别把 uc_do_kb_write 当"写知识"。要落地一条技能用 uc_do_kb_skill_add（去重后再加，避免同名多条）。

SOP-6 失败任务的处理顺序

1) uc_do_gain_job_status(jobId)        看状态与错误
2) uc_do_health()                      引擎/服务是否掉线（comfyui / api）
3) uc_do_gain_node(nodeId)             看该节点的参数/提示词/资产是否齐全
4) uc_do_gain_template_guide + prompt_rules   参数名/提示词是否合规范
5) 修好后**只重跑这一个节点**（uc_do_run_node）

• 上游没出产物 ⇒ 先修上游（下游会一直等）
• 排队久：uc_do_sheet_jobs() 看是否有别的任务占着
• 必要时 uc_do_cancel_job(jobId) 再重来（⛔ 取消不是"清空画布"）

SOP-7 交付与归档（收尾别省）

uc_do_save_text              长文本 ⇒ 落成真实文件交付
uc_do_gain_node_result       产物路径（把**绝对路径**回给用户，别只说"跑好了"）
uc_do_ensure_group           产出归组，便于用户按项目/镜头查看

• 报告里给：任务名、画布（canvasId）、用了哪些模板、产物绝对路径、失败的镜头及原因 ✓