@iqiyi-intl-nadoupro/nadoupro-cli 1.0.0-test.2

package/skills/nadou/commands/video.md

@@ -0,0 +1,247 @@
+# 视频
+
+## 条件参数与有效请求
+
+视频参数先取当前账号的基础参数结构，再按首尾帧组合、分辨率、参考视频时长和音频事实应用本地条件规则。首帧、尾帧和首尾帧是不同输入语义，必须由参数或明确角色表达，不能按数量静默猜测。`--dry-run` 预演与实际提交复用同一有效参数；条件事实未知时不伪造元数据，显式指定受影响字段会在提交前失败关闭。
+
+## 路径选择
+
+`nadou video` 始终是独立路径，不会写入 Canvas Graph 状态。对于明确的 Canvas 请求，
+应依次使用 `canvas node estimate` 和 `canvas node generate`（默认立即执行）。不得把
+下载/上传/创建媒体作为生成节点的回退方式，也不得修改 `imageNodeOrigin` 或
+`isCustomNode` 来改变来源。
+
+> **入口编排约定**：本命令只生成原子视频，不隐式写空间或本地文件。提交前入口 Agent
+> 先解析显式目录或列出空间目录候选，完成余额/估价、用户选择目录和一次确认后才提交；取得可信产物后使用同一目标
+> 执行一次 `space artifact deliver`。本地下载状态与空间交付状态独立报告。
+
+`nadou video` 是独立原子生视频命令。提示词优化当前为 `deferred`，默认直接提交用户原始提示词，
+不询问是否优化，也不调用未开放的优化能力。
+
+长提示词优先使用文件或标准输入，避免正文进入进程参数：
+
+```sh
+nadou video --prompt-file prompt.txt --profile <profile> --dry-run --json
+cat prompt.txt | nadou video --stdin --profile <profile> --dry-run --json
+```
+
+位置参数、`--prompt`、`--prompt-file`、`--stdin` 必须且只能选择一个；文件和标准输入最多
+1 MiB。`--compact` 仅用于 `--json/--jsonl`，保留恢复所需的任务 ID、状态、
+产物 URL 和耗时，不回显提示词、完整请求或后端 `raw`。
+
+非交互或 `--json/--jsonl` 机器模式的正式提交必须带 `--submit`；优先使用显式 `--prompt`、
+`--prompt-file` 或 `--stdin`，位置提示词仅在已明确带 `--submit` 时接受；
+位置参数仅用于交互式调用或 `--dry-run` 预览。不要把 `nadou video models` 当作模型发现命令，
+模型目录必须使用 `nadou model list`。
+
+费用确认后的 `task submit` 会立即给出任务 ID。后续使用该任务 ID 执行
+`task status`、`task wait` 和 `task outputs`。预计完成时间超期只表示服务端估计已过，
+CLI 会降低轮询频率但不会把任务判为失败；任何后续错误都应使用原任务 ID 恢复，
+不得重新提交。
+
+比例支持把全角冒号和空白规范化（如 `16：9`、`16 : 9` → `16:9`）；
+不支持的比例会返回当前模型目录中的 `suggested_values`，CLI 不自动替换创作选择。
+
+`nadou video` 仍是可独立调用的原子命令，但入口 Agent 不直接跳到付费提交。先预览唯一请求：
+
+```sh
+nadou video "小猫跳到桌子上，镜头缓慢推近" --profile <profile> --dry-run --json
+```
+
+将返回的 `data.request` 字段保存为 `request.json`，再严格按照
+[task-request.md](task-request.md) 执行 `points summary`、`task estimate`、费用确认和
+使用同一个请求文件的 `task submit`。确认前不得提交；估价不锁价，确认后不得重新运行
+`nadou video` 来重建请求。
+
+`nadou video` 始终提交独立任务，不接受 `--canvas-id`，也不会隐式创建或修改节点。在画布上下文中
+不建议用它代替画布节点生成：应显式创建或选择视频目标节点，以已有节点和入边表达参考素材，
+再执行 `nadou canvas node generate --canvas-id <canvas-id>`。独立任务的
+`--reference <url>` 只用于独立视频任务，不读取 Agent 会话中的 Canvas ID。
+
+定时默认关闭。服务端定时只在用户明确选择后使用：
+
+```sh
+nadou video --prompt-file prompt.txt \
+  --schedule-mode server --scheduled-at "2026-08-03T21:30:00" \
+  --timezone Asia/Shanghai --profile <profile> --dry-run --json
+```
+
+画布定时只能使用每小时 `00` 或 `30` 分钟的本地时间卡点，秒数必须为 `00`；其他分钟会在网络请求前被拒绝。
+普通视频服务端定时沿用服务端既有时间规则。
+
+该命令只生成带唯一 `scheduledTime` 的请求预览；保存 `data.request` 后仍需用同一文件完成余额、
+估价、费用确认和一次提交。本地定时先生成不含定时参数的普通预览请求，再按
+[schedule.md](schedule.md) 创建计划和运行显式执行程序。`local` 与 `server` 不自动切换。
+
+## 提交前确定交付目录
+
+`nadou video` 只生成独立视频任务。用户没有明确指定画布、空间目录或仅下载时，入口在费用确认前
+通过 `space current` 和 `space directory list` 列出目标空间全部目录候选，不得把个人空间根目录直接当作默认目标。
+用户必须在同一条确认中选择目录并确认费用；只有已处于 `delivery_status=AWAITING_DESTINATION` 的任务才恢复目录选择与交付。
+
+```sh
+nadou space current --profile <profile> --no-interactive --json
+nadou space directory list --group-id <data.personal.id> --profile <profile> --no-interactive --json
+```
+
+使用服务端返回的 `data.personal.id`，解析全部目录名称、完整层级、`directory_id`、`parent_id` 和 `root_id`；
+同名目录必须附层级和 ID。未指定目录时不得直接选择根目录，不使用当前团队空间、按名称猜测目录或切换当前空间。
+
+当前激活空间是积分余额的计费空间，提交前绑定的个人目录是交付目标；两者必须分别报告。
+用户生成前明确指定个人目录或团队目录时沿用该目标并跳过选择；不得同时创建个人空间副本。
+
+任务完成后，对每个成功产物分别执行：
+
+```sh
+nadou space artifact deliver \
+  --task-id <task-id> --job-id <job-id> --output-index <index> \
+  --group-id <data.personal.id> --directory-id <selected-directory-id> \
+  --mode copy --profile <profile> --no-interactive --json
+```
+
+`job-id` 和 `output-index` 必须取自同一次 `task outputs` 结果并同时传入，使后续查询顺序变化时
+安全失败而不是选错产物。每个成功产物一条命令，每条命令最多一次写请求。任务产物交付不是
+`material upload`，不得重新上传生成结果。生成状态与交付状态必须分别报告；交付失败或未知时不得
+自动重试或改投其他目录。目录解析失败时在提交前停止；非交互调用未给目标时仅列出候选并停止，
+不得解析或绑定个人根目录。
+未等待完成时，素材状态必须报告为尚未交付，并使用原任务 ID 继续 `task wait`、`task outputs` 和显式交付，
+不能重新提交视频任务。已处于 `delivery_status=AWAITING_DESTINATION` 的任务只恢复目录选择/交付。`media inspect`、
+缩放、规范化和转码都不是默认动作；用户明确提到画布时进入画布节点流程，不同时创建个人空间副本。
+
+空间交付和服务端在线结果是视频入口默认交付。本原子命令不会自动下载或创建本地清单；
+只有用户明确要求本地文件时，才在费用/执行摘要中披露绝对目标目录和不覆盖规则，并获得单独授权。
+取得可信任务/作业/产物后，显式下载时执行：
+
+```sh
+nadou task download-batch --task-id <task-id> \
+  --output-dir <absolute-target>/artifacts \
+  --manifest <absolute-target>/download-manifest.json \
+  --profile <profile> --json
+```
+
+部分失败后只使用 `task download-batch --resume-manifest <manifest>` 恢复，不使用 `--overwrite`，也不重新
+提交视频任务。`local_delivery_status`、空间 `delivery_status` 与生成状态分别报告。未明确要求本地下载时不创建清单、
+不报告本地路径；明确画布、仅生成或仅空间交付时同样跳过本地下载。
+
+视频任务建议显式使用 10 分钟观察窗口：
+
+```sh
+nadou task wait <task-id> --profile <profile> --timeout 10m --json
+```
+
+可选地指定动态目录中的模型：
+
+```sh
+nadou video "雨夜街道上霓虹灯倒映在水面" --model <video-model> --profile <profile> --dry-run --json
+```
+
+先通过 `nadou model list --scenario text2video` 从当前账号的动态目录中选择
+`<video-model>`，不要猜测或复用其他账号的值。
+
+使用首尾帧或多参考图时必须显式选择场景，并重复传入已经上传后的 HTTPS 素材 URL：
+
+```sh
+nadou model list --scenario multi_reference --profile <profile> --json
+nadou model schema <model-id> --scenario multi_reference --profile <profile> --json
+nadou video "四镜头生日情景喜剧" --scenario multi_reference \
+  --reference-image "https://assets.example/role-1.png" \
+  --reference-image "https://assets.example/role-2.png" \
+  --reference-image "https://assets.example/scene.png" \
+  --model <model-id> --duration <runtime-value> --ratio <runtime-value> \
+  --resolution <runtime-value> \
+  --audio on --profile <profile> --dry-run --json
+```
+
+`text2video` 不接受参考图；`first_last_frame` 接受一到两张；`multi_reference`
+至少一条参考素材，可按当前模型参数结构混合图片、视频和音频，并分别服从
+`max_images/maxImages`、`max_videos/maxVideos` 和 `max_audios/maxAudios`。本地参考音频在上传前必须
+通过 `nadou media inspect --input <audio> --json` 读取时长，再按当前模型 Schema 的
+`audio_duration`（单位秒，含边界）校验；远程音频 URL 无法读取时长时，仍由服务端最终确认。
+不要把参考音频时长和最终生成视频的 `--duration` 离散值或范围规则混淆；后者始终从当前目录读取。
+`--reference` 不会隐式上传本地文件。可信 HTTPS
+素材直接复用；只有本地素材会进入最终请求且模型必须接收服务端 URL 时，才在说明远端写入后通过
+`nadou material upload` 上传一次，用户拒绝时停止。确认后移除 `--dry-run`
+重新执行会重建请求，入口 Agent 不采用该方式；必须保存 `data.request`，完成余额、
+估价和费用确认后，用同一个请求文件执行一次 `task submit`。
+
+### 多参考素材的显式角色与音频约束
+
+长期稳定的多参考调用优先使用显式角色参数：
+
+```sh
+nadou video "让主体沿着参考视频的动作奔跑" --scenario multi_reference \
+  --reference-video "https://assets.example/motion.mp4" \
+  --reference-image "https://assets.example/subject.png" \
+  --reference-audio "https://assets.example/voice.wav" \
+  --model <model-id> --profile <profile> --dry-run --json
+```
+
+`--reference-video`、`--reference-image` 和 `--reference-audio` 可重复使用，分别表达视频、
+图片和音频角色。CLI 按 video → image → audio 的跨角色顺序展开，并在同一角色内保持命令行
+出现顺序；`params.image`、`form.referenceImages` 和 `form.thumbsOrder` 三处必须完全一致。
+它们不能与旧的无角色 `--reference` 混用；旧参数仍保留，用于兼容已有只传有序图片的自动化。
+
+视频任务提交前会预检最终请求中的每个媒体 URL，确认 URL 没有被截断、重复引用字段没有错位、地址可访问且不是明显错误页；图片引用还会读取有限响应片段验证可解码。预检不根据内网/外网域名直接拒绝，也不会猜测修复 URL；失败时在远端任务写入前停止，并返回 `MEDIA_REFERENCE_PREFLIGHT_FAILED` 与脱敏诊断。
+
+多参考包含视频时，不要手工打开生成音频。CLI 只有在当前账号模型目录和媒体事实都确认适用时
+才发送 `generateAudio`；未知媒体类型时会省略该默认字段，显式 `--audio on/off` 则在提交前
+失败关闭，避免把目录默认值 `true` 发送给不接受视频音频开关的模型。CLI 不根据 URL 后缀
+猜测无角色素材类型，也不修改 NadouAI 后端或调用边界。
+
+### 首帧、首尾帧和仅尾帧
+
+首尾帧模型能力必须从当前账号的 `model list/schema --scenario first_last_frame` 动态读取，不能按模型名称或参考图数量猜测。目录标记的组合规则为：
+
+| `onlyFirstFrame` | `onlyLastFrame` | 支持的输入 |
+|---|---|---|
+| `false` | `false` | 仅首帧、首尾帧 |
+| `true` | `false` | 仅首帧 |
+| `false` | `true` | 仅首帧、首尾帧、仅尾帧 |
+
+CLI 通过 `--first-frame <url>` 和 `--last-frame <url>` 明确角色；两者可单独或同时使用。仅尾帧必须保留空首帧槽位，不得把尾帧 URL 压缩为首帧。兼容参数 `--reference` 继续支持有序的仅首帧/首尾帧语义，但不能与角色参数混用。能力字段缺失、类型异常或两个标记同时为 `true` 时失败关闭，不提交任务。
+
+```sh
+nadou video "从首帧过渡到尾帧" --scenario first_last_frame \
+  --first-frame "https://assets.example/first.png" \
+  --last-frame "https://assets.example/last.png" --model <compatible-model> \
+  --profile <profile> --dry-run --json
+
+nadou video "平滑抵达尾帧" --scenario first_last_frame \
+  --last-frame "https://assets.example/last.png" --model <only-last-model> \
+  --profile <profile> --dry-run --json
+```
+
+`model list`/`model schema` 的 `frame_capabilities.modes` 是当前目录的事实投影；如果模型没有该字段，Agent 不得宣称其支持额外帧组合。
+
+场景选择以用户意图为准：
+
+- 普通参考图片用于人物、场景、道具或风格一致性，且没有声明帧角色：优先
+  `multi_reference`。
+- 用户明确说首帧、尾帧或首尾帧：使用 `first_last_frame`，不得改成多参考。
+- 没有参考图片：使用 `text2video`，不得构造空多参考请求。
+- 不得根据参考图片数量猜测多参考或首尾帧语义。
+- 视频语义编辑或动作控制读取 [video-advanced.md](video-advanced.md)。
+
+费用确认后的低层提交只执行一次并返回任务 ID，适合稍后恢复：
+
+```sh
+nadou task submit --body-file request.json --profile <profile> --no-interactive --json
+nadou task wait <task-id> --profile <profile> --json
+nadou task outputs --task-id <task-id> --profile <profile> --json
+```
+
+独立视频的团队目录交付若返回 `PERMISSION_DENIED` 或 `DELIVERY_PERMISSION_DENIED` 且 `fallback_eligible=true`，必须使用 `atomic_media_permission_fallback_prompt`：先展示原团队目录和个人目录候选，等待 `fallback_confirmation_required` 的明确确认；确认前不得写个人空间。拒绝时遵循 `fallback_confirmation_declined`，非交互无预授权时遵循 `non_interactive_fallback_blocked`，确认后仅按 `original_task_reuse_only` 复用原任务/作业/产物，不重新生视频。
+
+时长（离散值或 `min`/`max`/`step` 范围）、比例、清晰度、音频和数量使用当前模型的服务端默认值。模型错误时重新运行
+`model list --scenario <scenario>`，不要猜测枚举值。若等待超时，使用返回的原任务 ID 继续查询，
+不要重新提交。模型、场景、提示词、参考素材、时长、比例、清晰度、音频、数量、账号配置、
+当前计费空间或请求发生变化时，旧估价和任务级积分上限授权失效，必须重新预检。
+`estimable=false`、余额未知或余额不足时停止。
+### 独立富文本提示词
+
+只有在 `--scenario multi_reference` 的提示词是含 `reference-tag` 元素的网页编辑器
+HTML 时，才使用 `--prompt-format rich`。必须从唯一一个 UTF-8 `--prompt-file` 或
+`--stdin` 读取；不接受位置提示词。每个标签的 `data-url` 必须与显式、有序的
+`--reference` URL 匹配；UI 标签中的 `data-id` 会在独立请求前移除，重复标签保留在描述中，
+但任务引用参数按首次出现顺序去重。CLI 会校验并保留该 HTML；`prompt-format` 仅供本地使用，
+不会发送给 NadouAI。默认仍使用纯文本提示词。

package/skills/nadou/guides/artifact-presentation.md

@@ -0,0 +1,146 @@
+# 产物呈现与最终回复
+
+## 原子媒体提交前确定目录
+
+独立图片/视频/音频的原子 `image/video/audio` 只生成。未预先指定目录时，提交确认前列出权威空间全部目录
+候选，等待用户选择后把计划目标写入摘要；生成完成后仅向确认目标执行
+`space artifact deliver`。只有交付成功且目录回读确认后，才能展示实际空间路径、资源 ID 或服务端素材 URL。
+
+### 提交确认前的强制结果模板
+
+入口 Agent 在调用任务提交前，必须先展示以下信息并等待费用/任务确认，不得跳过目标确认：
+
+```text
+生成前计划：generation_status=PLANNED
+可选交付目录：<候选目录的完整层级路径和 ID>
+用户选择：<directory_id，未选择时不得提交>
+下一步：在同一条回复中选择目录并确认费用；确认后只提交一次，完成后写入所选目标并回读
+```
+
+目录名、ID 和层级只能来自同一轮 `space current`/`space directory list` 响应。目录查询失败、空间不唯一、
+目录层级不完整或用户未选择时在提交前失败关闭，不切换到其他空间或自动选根目录。
+
+失败/未知状态保留 `generation_status=COMPLETED` 和原任务/作业/产物。恢复只查询原任务、重新发现
+目录或交付未完成产物，禁止重新生成、自动重试未知写入、改投个人空间根目录或伪造链接。显式个人/团队
+目录、画布和仅下载目标跳过个人目录默认解析。只有已处于 `AWAITING_DESTINATION` 的任务才恢复目录选择；正常提交必须在生成前绑定目录。
+
+独立图片、视频和音频默认只展示服务端在线产物和空间交付结果，不披露或创建本地下载目录、清单或媒体文件。
+只有用户明确要求本地下载时，才披露绝对目标目录并通过单任务的 `task download-batch` 持久清单写入；本地路径
+必须在下载成功且清单校验完整后才展示。显式下载失败只用原清单执行 `--resume-manifest`，不得使用 `--overwrite`
+恢复，不重新生成，也不把目标目录、临时文件或签名 URL 当作本地结果。
+
+本页规定 Agent 在一次 Nadou 操作结束时如何呈现**已经观察到**的产物。它只消费 CLI 或服务端
+实际返回的任务、产物、空间交付、目录回读、画布和本地下载事实；不拼接页面地址、空间路径或
+产物链接，也不把任务页、缩略图、请求参数或计划目标冒充成产物。
+
+## 统一规则
+
+1. 最终回复中的每个产物、画布入口或本地下载入口只出现一次。相同产物有多个状态时合并为一条，
+   不在普通节点进度和最终汇总中重复发送。
+2. 图片、视频和音频的最终交付以服务端确认的空间路径为必需事实：空间、目录、服务端路径和权威
+   入口只能使用 `space artifact deliver` 成功后目录回读得到的真实字段。文件仍存在时应优先提供
+   该长期有效的空间入口。未完成空间交付时不得用本地文件替代空间结果。
+3. 本地路径或下载入口只能在用户明确授权且对应下载命令成功完成并校验后提供；默认不创建
+   `task download-batch` 清单。不得把目标目录、临时文件或签名下载地址当作本地文件。
+   不要输出签名 URL。
+4. 一个真实产物可按宿主能力提供图片预览、播放器或“查看/下载”入口；宿主不能渲染时使用同一条
+   返回的权威入口作文本链接。不得以缩略图、任务页或 canvas 节点替代视频/音频的真实播放或下载入口。
+   为避免不同宿主把外链图片渲染成占位图，图片默认使用普通 Markdown 查看链接
+   `[查看图片](https://example.invalid/image.jpg)`（实际替换为权威 URL），不得把图片预览语法作为唯一交付形式；链接目标仍必须来自
+   服务端真实返回。`space artifact deliver` 成功响应中的 `online_url`（若有）是已选任务输出的在线查看链接；
+   没有该字段时，回读同一 `task outputs` 的 `url`，不得使用 `download_url` 或自行拼接链接。用户未询问本地下载时，
+   最终回复不补充“未下载到本地”等否定说明，只呈现真实在线结果和空间交付事实。
+5. 模型、实际消耗、时长、画布、保存位置和服务端错误码均为条件字段：只在本次真实返回或本地
+   验证已获得时展示。缺失时明确未返回，不推测、不补造。
+6. 最终回复必须区分生成、在线结果、下载和空间交付。生成成功不等于已下载或已交付；目录回读或保存验证失败
+   时按失败处理，不能用任务完成覆盖该失败。
+   `local_delivery_status` 和空间 `delivery_status` 是入口 Skill 组合流程状态，不得伪装成底层媒体命令字段。
+7. 画布入口必须来自服务端响应。后端只返回画布 ID 时只展示该 ID，不得根据配置、API 主机、
+   环境名称或既有页面样例自行拼接 Web 地址。
+8. 多作业机器结果保留每个作业的状态、原因和产物来源；人类最终回复才对完全相同 URL 去重。整体
+   `PARTIAL_SUCCESS` 必须同时列出成功项和失败项，不能用任一侧覆盖另一侧。
+9. 失败只说明 CLI 能观察的阶段及可信来源；费用没有服务端结算证据时写未知或预期，不得从失败、
+   取消或产物存在推导“已扣费”或“已退款”。恢复动作只查询、下载或交付原任务，不自动生成新任务。
+
+## 单张图片
+
+成功时提供一条真实图片产物记录：
+
+- 图片预览**或**查看入口（二选一）；
+- 服务端确认的空间/目录/实际路径（如已交付）；
+- 模型、实际消耗和已完成下载的本地路径（如本次返回）；
+- 同一真实入口在整段最终回复中只出现一次。
+
+若没有可信产物，不能写“已生成”；说明任务观察到的状态、没有产物的原因和原任务 ID。
+
+## 多张图片
+
+成功时报告实际成功数量，并为每张真实图片各提供一条不重复的产物记录及其空间路径。若批量下载
+已经完成，可额外给出一个真实本地下载目录；目录不能替代逐张产物事实。
+
+没有产物或只有部分产物时，报告成功数和失败/缺失数，逐项说明可观察到的失败或未知状态；不得把
+请求数量、缩略图数量或预计数量称为实际产物数。
+
+## 视频与音频
+
+每个真实媒体产物提供一个播放或下载入口，以及已确认的空间路径。仅在获得真实事实时补充时长、
+画布入口和已完成下载的本地路径。一个媒体入口只出现一次；缩略图和任务页只能作为辅助诊断，
+不能作为成片或音频的交付物。
+
+没有真实媒体产物时，说明任务、失败/取消/非终态原因及可恢复动作，而不是展示缩略图或宣称成片。
+
+## 文本与复杂画布
+
+- 文本任务直接呈现服务端返回的正文；若来自画布，再提供真实画布节点入口。文本不强制附 URL。
+  没有保存到画布或空间时，要说明未保存原因，不能把正文称为素材。
+- 复杂画布只在最终阶段汇总：最终成片（如真实存在）、空间路径、画布名称及真实画布入口；同时列出
+  用户要求保留的阶段性产物。普通节点状态变化后不重复发送这些入口。
+- 画布没有形成最终产物时，列出已完成与未完成阶段及各自真实状态，不把画布结构或节点模板说成成片。
+
+## 部分成功、删除与完成态
+
+部分成功时，分别列出成功项、失败项以及每个已保存项的真实位置；只返回真实成功产物。说明下一步
+补做方案及其**已估价**的预计消耗；没有服务端估价时，只说明费用尚未确认，不估算。最后询问用户
+是否要补做，且不得自动重试或重新提交。
+
+文件或原任务已删除时，用用户可理解的话说明，并保留服务端原始错误码供定位（若本次响应提供）。
+任务或交付完成时，分别说明原计划的团队/空间、服务端确认的实际团队（如有）、实际空间与实际路径，
+以及存在时的回退原因；实际位置始终以交付回读或保存验证结果为准。
+
+## 最终回复骨架
+
+按实际情况省略没有证据的字段，不要填占位符：
+
+## 原子媒体团队交付被拒后的呈现
+
+对独立 `image`、`video`、`audio` 任务，先分别呈现 `generation_status`、原团队 `requested_destination`、服务端拒绝原因和 `fallback_eligible`。仅当用户明确确认个人目录后，才执行一次复用原 `task_id/job_id/output-index` 的交付；拒绝、非交互无预授权或未知结果不得静默切换空间、重复写入或重新生成。个人目录回读确认成功后再报告 `actual_destination`，否则保留生成成功与交付失败或待恢复的分离状态。
+
+```text
+结果：<完成 / 部分成功 / 未生成 / 未交付>
+任务：<task_id，若有>
+
+产物：
+- <类型与名称>：<预览、播放、查看或下载入口之一>
+  <服务端确认的空间 / 目录 / 实际路径，若有>
+  <模型、实际消耗、时长、画布入口或本地路径，若有>
+
+未完成：<失败、取消、未知、未保存或未交付的真实原因，若有>
+恢复：<使用原 task ID 的观察、下载或显式交付动作；部分成功时先询问是否补做>
+```
+
+链接、路径、画布入口、实际消耗和错误码都必须来自本次已观察到的结果。若没有产物，删除“产物”段，
+并明确说明为什么没有可交付物。
+
+## 多任务本地交付证据
+
+当用户明确要求本地批量下载或 1～10 分钟多片段成片时，最终呈现优先引用版本化本地文件：
+
+- `generation-evidence.json`：逐任务/作业的真实终态、部分成功、失败与稳定源产物身份；
+- `download-manifest.json`：去重下载项、全部来源关系、本地相对路径、大小、SHA-256 和恢复状态；
+- `subtitle_validation` / `audio_mix_plan`：实际使用时的字幕与混音技术契约；
+- 完整的 `media verify --json` 响应封装：最终文件的技术规格证据；
+- `delivery-manifest.json`：上述引用、最终媒体哈希值与三项显式人工确认。
+
+先执行 `nadou evidence validate --input <file>`。只有 `DeliveryManifest` 完整且所有引用、哈希值和最终媒体身份
+一致时，才能说“本地交付完成”。任务成功不等于已下载，下载完成不等于已后期，技术核验通过也不等于
+叙事、角色或字幕创意验收通过。部分失败时保留成功文件和原清单，只建议恢复读取/下载；不得自动重提任务。

package/skills/nadou/guides/canvas-dependency-graph.md

@@ -0,0 +1,101 @@
+# 画布依赖图与自动连线判定
+
+本页是画布资产依赖和自动连线的统一判定口径。这里的“自动连线”不是 CLI 或后端按节点类型自动猜边，
+而是 Agent 先从用户目标和实时输入证据生成依赖图，再调用公开的 `CREATE_EDGE`/`canvas edge connect` 显式写入。
+
+## 一、先区分五类关系
+
+| 关系 | 画布边 | 说明 |
+| --- | --- | --- |
+| 资产消费 | 必须有 `A -> B` | A 产出、提供或承载的图片/视频/音频被 B 引用、编辑或生成使用 |
+| 合成输入 | 每个 `Aᵢ -> C` | 多个片段/素材进入同一 `clip`、剪辑台或合成节点 C |
+| 承接/参考 | `A -> B` | B 明确基于、承接、参考、使用 A 的产物 |
+| 时间顺序 | 通常不新增边 | 时间线的 `targetTimerange.start`/`duration` 表达片段先后，边不表达顺序 |
+| 分组/布局 | 只写 `parentNode` | 分组、摆放、展示、整理不是资产依赖，不能用边替代或用 `parentNode` 冒充边 |
+
+导出节点是一个单独的结果关系：在支持的 `canvas media export prepare` 或 `backend-submit` 流程中，
+`clip -> output-video` 由对应导出 Graph 写入创建；Agent 必须回读确认，但不能再次创建重复边。
+导出命令不会替 Agent 创建缺失的 `source-video -> clip` 输入边。
+
+## 二、从用户语义判断是否应连线
+
+下面的表达已经明确了依赖方向，Agent 不需要再问“要不要连线”：
+
+| 用户表达 | 依赖图 |
+| --- | --- |
+| “用 A 作为 B 的参考/首帧/尾帧/输入/素材” | `A -> B` |
+| “A 生成后交给/流入/接到 B” | `A -> B` |
+| “B 基于/承接/延续 A” | `A -> B` |
+| “把 A、B 拼接/合成/剪辑/混音/导出成 C” | `A -> C`、`B -> C` |
+| “把多个片段放进剪辑台或片段 C” | 每个片段 `-> C` |
+| “片段 2 承接片段 1” | `片段 1 -> 片段 2`；若两者还进入 C，再分别 `片段 1 -> C`、`片段 2 -> C` |
+
+只有“放在一起、分组、展示、整理”或“两个节点在同一画布”时，不建立资产边。
+“片段 1、片段 2 依次播放”本身只确定时间线顺序；除非用户还表达“片段 2 承接/基于片段 1”，
+否则不要额外创建 `片段 1 -> 片段 2`。
+
+## 三、已有节点和时间线的输入映射
+
+在现有画布中补边时，按以下证据强度从高到低匹配源节点，不按名称相似或位置猜测：
+
+1. 用户或时间线明确给出的节点 ID；
+2. 时间线 `materials.*[].id`、片段 `materialId`、`meta.materialId`、节点记录中的 `materialId`/`assetId` 或原始任务 ID 完全一致；
+3. 节点回调的产物 URL 与时间线 `url` 完全一致；
+4. 唯一的素材元数据（例如文件名和尺寸/时长组合）完全匹配。
+
+只有一个候选时才算“已匹配”。零候选或多个候选都必须停下并报告候选，不得用标签、节点类型、左右位置、创建时间或
+“看起来像同一素材”补猜。回调管理的 URL、元数据、`taskStatus` 只能读取，不能通过 Graph 更新补造。
+
+对于页面剪辑台的 `node-data` 时间线，匹配完成后还要把身份写回正确的层级：
+`materials.*[].id` 是时间线内部材料键，片段的 `materialId` 引用该键；`materials.*[].meta.materialId`
+使用已匹配的源素材节点 ID。Graph 中的数值 `assetId` 是回填元数据，不在页面契约明确要求时充当 `meta.materialId`。
+只复用 URL 或只把 `assetId` 写入时间线，会出现“时间轴有片段但素材缺失”的半成功状态。
+
+时间线的 `materials`/URL 是渲染输入，不是 Graph 边。对于“两个视频合成一个视频”的场景，即使时间线已经写入，
+只要能够唯一匹配两个源节点，就仍必须在 Graph 中建立两个 `源节点 -> clip` 边。素材边表达“进入合成”，
+时间线的片段才表达“从哪一段、放在什么时间”。
+
+## 四、写入与验收算法
+
+每次需要自动连线时都遵循以下顺序：
+
+1. `canvas get --raw` 读取实时节点和边；保留用户明确的画布 ID，不能按画布名称猜。
+2. 把用户语义翻译成有向依赖计划，列出 `source`、`target`、匹配依据和本次预期新增边。
+3. 去重：实时 Graph 已有完全相同的 `source -> target` 边就视为满足，不重复创建；`source == target` 或会形成明显依赖环时停止。
+4. 新建节点和边放进同一次有序 `canvas graph mutate`，先 `CREATE_NODE` 后 `CREATE_EDGE`；已有节点的多条缺边也一次提交。
+5. 写后重新 `canvas get --raw`，逐条核对节点 ID、边的 `source`/`target` 和预期数量；缺边、错边、额外边或结果不确定时停止，
+   不继续估价、生成、时间线写入或导出，也不自动补写/重试。
+6. 若写响应结果未知，只用原变更 ID 做只读对账；确认未应用后才允许调用方显式决定是否复用完全相同的请求。
+
+当关系已经由用户语义明确、且节点 ID 已从实时 Graph 或同批创建结果确认时，不需要额外询问用户；询问只针对身份、
+候选节点或关系方向仍不明确的情况。
+
+CLI 的节点生成/素材创建接口不接收 `sourceNodeId` 作为隐式连线参数，也不会因为输入 URL 自动补入边；
+`sourceNodeId` 不存在或不受支持时，仍按本页算法使用公开 Graph 变更建立依赖。
+
+## 五、典型结构
+
+### 两段视频合成 20 秒成片
+
+```text
+video-part-1  ->  clip-20s  ->  output-video
+video-part-2  ->  clip-20s
+```
+
+如果用户还说“第二段承接第一段”，再增加：
+
+```text
+video-part-1  ->  video-part-2
+```
+
+但不能因为两个节点名称相似或在画布上上下排列就自动增加这条边。`clip -> output-video` 由受支持的导出命令写入后，
+只验证它是否存在；`video-part-1/2 -> clip-20s` 则必须在时间线写入或导出前由 Agent 创建或确认。
+
+### 参考图生成视频
+
+```text
+reference-image  ->  generated-video
+```
+
+先建立并回读边，再执行 `canvas node estimate`/`generate`；CLI 会从目标节点的入边读取可信参考 URL，
+不会因为用户传了一个 URL 就替代画布边。

package/skills/nadou/guides/canvas-first-complex-workflow.md

@@ -0,0 +1,83 @@
+# 复杂任务的画布优先工作流
+
+本页适用于多镜头、多片段、多参考、角色一致性、短剧、MV、广告和影视等需要多个节点协作的目标。
+产品要求是“先建工作流，再执行生成”：不能先用独立 `nadou image/video` 逐个生成素材，最后才回画布猜哪些节点需要连线。
+
+## 适用边界
+
+- 用户明确要求画布，或任务天然需要多个节点、资产依赖和阶段性回看时，默认使用本流程。
+- 用户明确只要本地独立素材和线性后处理时，才使用 [一键短片](../recipes/one-click-film.md)；该路径不会事后把独立任务补挂到画布。
+- 需要 `clip` 专属字段、平台时间线或云端合成但当前契约未开放时，停止并报告阻塞；不得伪造“剪辑台”节点，
+  也不得用独立任务绕过画布流程。
+
+## 六个阶段
+
+### 1. 先做工作流计划
+
+从用户目标整理出：节点清单、每个节点的提示词/模型配置、资产输入、依赖方向、执行顺序、预期产物和费用范围。
+依赖方向和“是否需要连线”统一按 [画布依赖图](canvas-dependency-graph.md) 判定；不要把时间顺序、分组或相邻摆放误当成资产依赖。
+把“谁产出资产、谁消费资产”写成有向关系；例如两个片段进入合成节点，就计划两条
+`片段 1 -> 合成节点`、`片段 2 -> 合成节点`。关系不明确时先询问，不创建或生成。
+
+### 2. 先创建空结构
+
+确认配置、空间和画布 ID 后，读取实时 Graph。使用一次有序 `canvas graph mutate` 创建本轮需要的结构节点，
+并在同一批操作中创建已确认的依赖边；节点只表达结构，不提交任务、不写回调字段。
+节点与边写入后立即回读，确认节点 ID、边方向和数量。未完成这一步时不得执行任何 `canvas node generate` 或独立
+`nadou image/video`。
+
+### 3. 再填提示词和模型配置
+
+对已确认的图片/视频节点写入 `prompt`、`modelName`、`modelType`、`taskType` 和完整 `modelParams`，使用实时
+`model list` 和 `model schema`，不要把展示名或上一次任务参数直接复制。可以用一次有序 Graph 变更批量更新多个节点；写后重新读取，
+确认每个目标节点配置完整且与入边依赖一致。
+
+### 4. 一次性做批量预检
+
+使用可重复的 `canvas node estimate --node-id ...`（最多 20 个图片/视频节点）取得逐项费用和总预计积分，
+一次展示本轮节点、模型、依赖、预计消耗和计费空间。任一节点不可估价、依赖缺失、关系方向错误或 Graph 结果未知时，
+整批停在预检阶段；不得先提交其中一部分再补规划。
+
+### 5. 按依赖波次执行
+
+当前 CLI 的 `canvas node generate` 是单节点、单次提交原子能力，没有未经批准的服务端批量提交接口。Agent 仍要把它
+作为一个**已规划的批量执行**：只对第 2～4 阶段已验收的节点按拓扑顺序逐项调用，记录每个任务 ID，再统一观察这一波结果。
+独立的源节点可以同一波执行；必须先取得源节点可信产物 URL 的下游节点，放到下一波。不能临时发现一个素材就单点生成，
+也不能因为某个节点失败而自动重提整批。
+
+### 6. 对账和交付
+
+每个任务只用原任务 ID 观察，确认回调已写入预期节点；每一波结束后读取 Graph，核对节点状态、产物和依赖边。
+结果未知、缺边、回调未同步或下游输入未就绪时停止后续波次并报告恢复证据。最终只呈现真实的画布入口和产物，
+不把空节点、计划节点或“已提交”称为成片。
+
+已有素材或已有时间线不能跳过建边：如果源视频/图片/音频节点已经生成，或时间线已经写入但 Graph 中没有对应
+的 `源节点 -> 消费节点` 边，先按 [画布连线](../commands/canvas-edge.md) 的语义矩阵补齐并回读，再继续下游生成或导出。
+
+## 20 秒视频拆分示例
+
+“两个 10 秒片段 + 一个合成节点”应先建立并核对：
+
+```text
+video-segment-1  ->  video-composition
+video-segment-2  ->  video-composition
+```
+
+在画布成片场景中，完整关系还包括：
+
+```text
+video-segment-1  ->  clip-20s  ->  clip-export-video
+video-segment-2  ->  clip-20s
+```
+
+`clip -> clip-export-video` 可由受支持的导出 Graph 写入创建，但两条源片段到 `clip` 的边仍由 Agent 根据用户的
+“两个片段合成一个视频”语义显式创建并在导出前核对。
+
+随后填好两个片段的提示词和模型配置，先对两个片段做总估价，再按波次生成。源节点回填 URL 后，把两段素材写入 `clip` 的时间线主轨，依次执行
+`canvas media timeline validate`，再按目标执行固定路径的 `canvas media timeline web-write` → `web-read`（只展示网页）或
+`canvas media timeline export-write` → `export-read`（组合式 CLI/后端导出证据），确认回读与预期语义一致且主轨含有两个片段；
+随后由 `backend-submit` 在代码层自动检查网页 `node-data`：导出前只修复缺失、全空或与请求语义一致的裸 Timeline，提交收据明确终态后再核对并按需恢复 Web 信封；收据身份错配、状态未知或超时不做后写。该收据对账不等待成片。两条手工路径不可混选，隐藏的通用 `timeline write/read` 会在本地阻断。
+再执行导出；主轨为空或回读不一致是停止条件，不得只因为素材池显示素材就提交。
+
+只有产品已提供并批准 `clip`/时间线
+合成契约时，才继续执行合成节点；否则应明确报告合成阶段阻塞，而不是先生成两个独立视频后再猜连线。

package/skills/nadou/guides/execution-interaction.md

@@ -0,0 +1,54 @@
+# 执行交互门禁
+
+本页把智能体的“先问再做”规则固定为可执行门禁。适用于图片、视频、文本、素材、空间、画布、
+本地媒体处理和任务恢复；命令本身存在不代表可以跳过本页规定的询问。所有提问都应给出可选项和
+推荐项，记录已选择的值、依据和适用范围。这里的“自动化可跳过”只允许跳过**该项阶段确认**：
+它绝不替代费用授权、删除/覆盖确认、画布写入确认或参数结构校验。
+
+| 触发条件 | 询问时机与必须说明 | 用户未回答时 | 自动化可跳过 |
+| --- | --- | --- | --- |
+| 首次授权后个人/团队空间不唯一 | 登录成功并验证身份后、任何生成或写入前；列出 `space list` 的真实 ID、名称、类型和当前标记，让用户选择当前空间 | 停在选择步骤，不执行后续命令 | 否；只有服务端只返回一个空间时才可直接记录 |
+| 个人/团队空间、目录或画布不唯一 | 任何写入或生成前；列出同一登录身份下的可选项和推荐项。 | 停在当前步骤，不执行。 | 否；调用方必须提供唯一 ID 或已批准的选择规则。 |
+| 模型必填参数缺失或存在歧义 | 费用预检和提交前；说明缺失项、可用默认值及其影响。 | 不提交。 | 可以，但只能采用实时参数结构的明确默认值或调用方提供的完整值，并在记录中写明。 |
+| 首帧/尾帧不明确 | 已确认用户要使用首尾帧模式后、生成视频前；说明两张图片各自的帧角色和传入顺序。 | 不提交。 | 可以；仅当调用方明确标注每张图的 `first`/`last` 角色和顺序。 |
+| 批量、预计高成本或余额未知 | 提交前；说明每项预计消耗、总数、当前余额和不足/未知影响。 | 不提交。 | 可以；仍须有当前请求、配置环境与计费空间绑定的明确预算授权，并通过余额和估价校验。 |
+| 方案、模型、分段或交付方式变化 | 采用新方案前；并列原方案、新方案和变化原因。 | 保持原方案；原方案无法继续时停止。 | 可以；调用方须事先授权该变更范围，且变化不使既有费用估价或确认失效；否则重新预检。 |
+| 剧本或分镜已完成 | 生成关键视觉前；展示故事、镜头、时长、比例和声音方案，说明可修改项。 | 不进入下一阶段。 | 可以；可省略该阶段复核，但不省略费用预检。 |
+| 关键视觉已完成 | 提交高成本视频前；展示中间产物及可修改项。 | 不提交视频。 | 可以；可省略该阶段复核，但仍须满足本次视频的费用授权。 |
+| 删除、覆盖或移动 | 动作执行前；说明对象、范围和影响。 | 不执行。 | 可以，但仅限命令已有的显式非交互确认与调用方已给定的精确对象/范围；结果未知时仍先对账。 |
+| 协同锁冲突 | 收到 `NODE_LOCKED` 或锁状态不完整时；展示服务端返回的受影响节点和安全冲突证据。 | 停止本次写入并等待回读或用户决策。 | **始终不能跳过**；不得重试、绕锁、修改或删除锁定节点。 |
+| 当前能力不支持、需要换平台或降级 | 改变原目标前；说明缺失能力和不改变事实的替代方案。 | 不伪装执行；维持原方案或停止。 | 可以；调用方必须明确允许该平台切换或降级，且输出必须如实标注执行平台和能力边界。 |
+| 失败后需要重新提交 | 任何重新提交前；说明失败阶段、已有结果、修改方案和预计消耗。 | 保留已有结果并停止。 | 可以；调用方须为本次重提提供明确预算/重试策略。网络结果未知时不是重提场景，先用原 ID 恢复或对账。 |
+
+## 统一执行顺序
+
+1. 先读取实时事实：身份、空间/目录/画布 ID、模型参数结构、任务状态或本地输入；不得按名称、
+   缓存或上一次会话猜测。
+2. 命中上表任一条件时，先展示所需信息并等待；不要把“用户想生成”解释为对默认值、费用、目标
+   范围或破坏性动作的确认。
+3. 只有在表中允许的自动化前提已被调用方明确提供时才跳过询问，并在输出中说明跳过的规则、
+   选值和适用范围。缺少任何一项即按“未回答时”处理。
+4. 写入、生成或重新提交后保留请求 ID、任务 ID、画布 ID 和已确认结果；等待超时、网络中断、
+   部分成功或未知结果只恢复/对账原对象，绝不自动再提交。
+
+## 费用与阶段确认的关系
+
+阶段确认（例如分镜、关键视觉）可以由已授权的自动化策略跳过；费用确认不能因此跳过。图片和视频
+仍严格执行根技能的 `dry-run → points summary → task estimate → 明确确认/预算授权 → 单次 task submit`
+流程。模型、提示词、参考素材、时长、比例、清晰度、音频、数量、配置环境、计费空间或请求内容变化时，
+旧估价和确认失效，必须重新预检。
+
+提交前确认摘要至少展示：账号/当前配置、当前计费空间、目标空间/画布/节点、模型、影响费用的关键参数、
+生成数量、预计积分、当前余额、按当前估价推算的预计余额、交付目标，以及“估价不锁价、不预占积分”。
+确认必须绑定唯一请求摘要；请求关键字段、账号、计费空间、目标或估价变化后旧确认失效。
+`--yes` 和 `--no-interactive` 只影响各自已有交互语义，不能替代费用授权。
+
+## 失败与冲突
+
+失败、冲突和结果未知必须分开描述：失败可以在用户或已授权的自动化策略确认新方案后重新提交；
+冲突必须先展示冲突范围并等待选择；结果未知只能查询、恢复或人工对账，不能以“重试”名义再次写入。
+
+批量本地交付按“任务 ID 检查点 → 报告 → `DownloadManifest` → 本地后期 → 核验 → 人工确认 →
+`DeliveryManifest`”推进。清单输出已存在时必须先停止并让用户选择新路径或显式覆盖；下载恢复只能使用原清单。
+混音、字幕和证据写入都是独立本地输出，不授权远程任务重提。需要重做具体镜头时，先列出对应
+任务/作业/镜头、已有成功产物和新的费用摘要，再等待新的明确授权。