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

package/skills/nadou/commands/task.md

@@ -0,0 +1,229 @@
+# 任务
+
+高层生成命令本身支持可恢复事件流：
+
+```sh
+nadou image --prompt-file prompt.txt --wait --compact --jsonl --no-interactive --profile <profile>
+nadou video --prompt-file prompt.txt --wait --compact --jsonl --no-interactive --profile <profile>
+nadou audio --prompt-file prompt.txt --wait --compact --jsonl --no-interactive --profile <profile>
+```
+
+首个 `generation_submitted` 事件包含任务 ID；进度事件只是本次 CLI
+轮询观察到的状态变化，不代表服务端 SSE 或可恢复游标。若
+`estimated_completion_overdue=true`，仅说明预计完成时间已过，CLI 会在默认策略下
+把轮询间隔从 4 秒逐步放宽到最多 10 秒，任务状态仍以服务端为准。
+入口 Agent 对付费图片、视频和音频不从这些直接提交示例开始，必须先执行下方费用预检。
+
+`status/wait/events` 与高层生成的 JSON/JSONL 精简模式共享稳定观察字段：后端原值 `task_state`、
+粗粒度 `stage`、`stage_source=task_state`、`stage_authoritative=false`、可选线性
+`progress_percent`（此时 `estimated=true`）、`next_poll_ms`、`terminal`、`next_action` 和
+`suggested_actions`。这些只是 CLI 轮询观察，不是排队、模型加载、推理或 OSS 上传的内部进度。
+
+`task` 是面向高级用户和自动化的低层接口。提交前从当前目录动态生成请求 JSON，
+不要复用旧环境的模型参数。请求构造先读取 [task-request.md](task-request.md)：
+
+```sh
+nadou task estimate --profile <profile> --body-file request.json --no-interactive --json
+nadou task submit --profile <profile> --body-file request.json --no-interactive --json
+```
+
+`estimate` 只估算请求积分，不提交任务；后端明确返回 `points=0` 时输出精确的
+`points=0, estimable=true`，不附加 `reason`。缺失、负数或非数值积分按后端契约错误处理。
+提交仍需单独执行且只执行一次。原子图片/视频/音频必须先读取
+[task-request.md](task-request.md)，以同一个请求文件完成余额查询、估价、费用确认和提交；
+估价不锁价，确认前不得提交。
+
+用户最初的生成意图、`--no-interactive` 和现有 `--yes` 都不构成费用授权。产品尚未定义统一
+高成本阈值前，预计消耗大于零的交互式图片/视频/音频任务都需要估价后确认；明确的任务级积分上限
+只能约束当前请求、账号配置和计费空间。请求发生变化、余额未知或不足、估价不明确、用户拒绝
+或没有回答时停止，不能执行 `task submit`。
+
+提交成功后只使用返回的任务 ID：
+
+```sh
+nadou task status <task-id> --profile <profile> --no-interactive --json
+nadou task wait <task-id> --profile <profile> --no-interactive --json
+nadou task wait <task-id-a> <task-id-b> --profile <profile> --no-interactive --jsonl
+nadou task outputs --task-id <task-id> --profile <profile> --no-interactive --json
+```
+
+独立图片、视频或音频未预先指定交付目录时，成功产物读取后由入口 Skill 报告
+`generation_status=COMPLETED`，使用提交前绑定的用户选择/显式目录执行空间交付。只有已处于
+`delivery_status=AWAITING_DESTINATION` 的任务才恢复目录选择。
+这是入口编排状态，不改变本页低层命令响应封装。未选择目录、目录候选不完整或非交互调用没有目标时
+不得执行 `space artifact deliver`；后续只使用原任务/作业/产物恢复目录发现与交付，不重提生成。
+
+只有成功媒体任务的 `outputs` 返回的 URL 才能作为媒体产物；成功 `TEXT2TEXT` 的正文读取
+`text` 字段。对于 `IMG2TEXT`，`nadou text --scenario image_to_text` 将正文投影到
+`text`；通用 `nadou task outputs` 为兼容调用方保留 `url` 承载，但该值是正文，绝不能
+下载或交付为媒体。失败、超时、部分成功或没有产物时必须如实报告，不能从请求、回调
+metadata、字符串外形或错误响应中猜测产物。
+当前 `schema_version=1` 保持这一低层兼容；Agent 应使用高层文本入口，不能预判其他主版本字段。
+`task outputs --signed` 和 `task download` 会跳过这类正文承载，不能用下载命令读取图生文正文。
+
+Agent 不需要诊断原始后端字段时，为 `status/wait/outputs` 增加 `--compact --json`；
+事件流使用 `events --compact --jsonl`。默认输出保持兼容，精简模式只删除 `raw`。
+
+把成功产物下载到本地时，使用任务范围的下载命令；它只接受该任务经过服务端签发的
+产物，不提供任意 URL 下载：
+
+```sh
+nadou task download --task-id <task-id> --output-dir ./outputs --profile <profile> --no-interactive --json
+```
+
+默认不覆盖同名文件；确需替换时显式传 `--overwrite`。下载中断不会留下最终文件，
+签名 URL 也不会写入恢复信息。已有文件与已成功下载的其他产物需要人工核对后再决定
+是否重跑命令。
+
+`outputs` 必须显式携带 `--task-id`；它与 `download` 都通过 `batch_get` 按任务 ID 读取
+`jobList`，不会扫描项目或画布的历史产物分页。缺少任务 ID 时 CLI 在认证和网络请求前
+失败；当前不提供无上下文的全局任务历史。服务端返回重复任务、重复作业或超过 `jobCount` 的作业列表时，CLI 默认
+停止并报告后端响应错误。只有 `TEXT2AUDIO`/`AUDIO2AUDIO` 且实际作业数不超过权威
+`generateCount` 时才兼容音频聚合计数，并为展开后的每项产物返回稳定 `output_index`；不会继续签发或下载范围不明确的产物。每个产物的 `raw` 会保留
+任务级扩展字段，并把 `metadataMap` 中该 URL 对应的 metadata 合并到当前产物。
+
+多作业任务逐项保留作业 ID、真实状态、失败原因和产物。整体 `outcome` 为
+`SUCCESS/PARTIAL_SUCCESS/FAILED/CANCELED/OUTCOME_UNKNOWN`，但绝不覆盖九个后端状态原值。
+机器证据保留重复 URL 的不同来源；仅人类展示去重。失败和费用字段的可信度、恢复动作见
+[失败阶段与费用状态](../guides/failure-cost-presentation.md)。
+
+后端已接受 `task submit` 的幂等设计，但请求头和状态查询尚未发布：同一次业务提交必须生成并持续复用同一个
+幂等键；请求 ID 只用于链路追踪，每次 HTTP 请求可以不同。超时、处理中或结果不确定时只查询
+原幂等键的状态，不能换新键、自动重提或轮询出另一个业务提交。若请求体发生变化，则它是新的业务提交，
+必须重新估价、确认并生成新键。当前发布版尚未发送该键，也没有状态查询命令，因此仍保持一次提交、
+结果未知即停止；在后端发布 Swagger 和 CLI 允许列表获批前，不得把本地契约描述成已上线能力。
+
+`status`、`wait` 和按任务 ID 的 `outputs` 遇到短暂网络故障或 408/5xx 查询失败时，CLI 最多
+再读取两次；每次都保留原任务 ID，绝不重提、取消或更换任务。三次读取仍无法获得状态时，输出
+会保留任务 ID、请求 ID、读取次数和恢复命令，当前状态应表述为“未知”。业务拒绝、认证或权限
+错误不重试。单次等待到期只结束本次本地观察，随后继续用同一任务 ID 执行 `status` 或 `wait`。
+
+定时默认关闭。服务端定时仍通过同一个 `task submit` 提交带未来 `scheduledTime` 的请求；画布定时执行时间必须
+按用户时区落在每小时 `00` 或 `30` 分钟卡点且秒数为 `00`，
+普通服务端定时沿用服务端既有时间规则；
+本地定时则由 `schedule worker` 到点提交不含该字段的冻结请求。两种模式都不改变提交
+无业务幂等键的事实；完整模式选择、状态和恢复规则见 [schedule.md](schedule.md)。
+`schedule cancel/update/list` 只管理尚未提交的本地计划。已知服务端任务 ID 的定时管理使用：
+
+```bash
+nadou task reschedule <task-id> --scheduled-at <time> --timezone <IANA> --no-interactive --json
+nadou task cancel-scheduled <task-id> --yes --no-interactive --json
+```
+
+如果任务来自 Canvas 节点，改期确认后还需要让画布界面显示新时间时，必须同时传入权威画布和节点：
+
+```bash
+nadou task reschedule <task-id> --scheduled-at <time> --timezone <IANA> --no-interactive \
+  --workflow-id <canvas-id> --node-id <node-id> --json
+nadou task cancel-scheduled <task-id> --workflow-id <canvas-id> \
+	--node-id <node-id> --yes --no-interactive --json
+```
+
+CLI 会在服务端任务改期确认后，通过既有 Graph 运行态补丁只更新该节点的 `scheduledTime`，并要求写入响应或
+只读回读确认。取消在调用服务端前先读取精确节点，校验任务归属、权威锁状态并保存原 `scheduledTime`；预检失败时
+不会发送取消请求。服务端回读到 `CANCELED` 后，再通过独立受控补丁把同一节点精确同步为
+`taskStatus=CANCELED`、`nodeStatus=idle`、`isGenerating=false`。同步前时间较预检发生变化时停止 Graph 写，
+成功响应或回读也必须保留预检时间。该补丁不能写产物、元数据、其他任务状态或执行时间。节点不存在、任务 ID
+不匹配、锁状态不可确认或回读不一致时，CLI 不会再次改期/取消任务，也不会重放 Graph 写入；未知写会返回
+request/mutation 标识及可直接执行的 `nadou canvas node mutation-status --canvas-id ... --mutation-id ...`。
+未提供 `--node-id` 时仍可改期独立任务或仅管理服务端任务，但 CLI 不承诺同步 Canvas GUI 投影。
+
+两个命令都要求写前状态为 `SCHEDULED`，最多发送一次写请求并回读同一任务 ID。改期只有回读仍为
+`SCHEDULED` 且 `scheduledTime` 等于目标时间才确认；取消只有回读 `CANCELED` 才确认。未知结果或
+回读不匹配时不得自动重写。`cancel-scheduled` 不得回退到 `terminate`，且空成功响应不能证明积分已退款。
+上下文任务仍要求项目、画布或会话上下文至少一个：任务状态返回权威项目 ID 时 CLI 自动复用；否则调用方必须
+显式传 `--workflow-id`、`--thread-id` 或 `--project-id`。独立任务的 `reschedule` 可以三者都为空，服务端
+按任务 ID 和当前用户归属校验；独立任务的 `cancel-scheduled` 仍返回 `TASK_CONTEXT_REQUIRED`。CLI 不得
+把当前空间或可读关系猜成旧工作台项目。
+服务端 `/task/page` 和 DAG 计划仍未接入。
+
+停止运行中任务使用 `task terminate <task-id>`。这是远端破坏性写操作，交互模式必须确认，
+非交互模式必须显式传 `--yes --no-interactive`；命令只表示服务端接受终止请求，随后仍需
+用同一任务 ID 查询最终状态，不得把确认响应解释为进程已立即停止。
+
+任务进入失败、版权/内容限制或其他非成功终态时，停止后续生成和交付，但保留已上传素材、已完成
+作业及其任务 ID。反馈必须包含失败阶段、服务端可理解的原因、已有结果和可修改项。用户明确同意
+新的方案后，重新走余额、估价与确认；这才是新的单次提交，不能把查询失败、等待超时或结果未知称为
+“重新生成”。
+
+`task wait` 可接收一个或多个互不重复的显式任务 ID。单 ID 保持原有 `task_wait` 结果；多 ID 每轮只发一次
+`batch_get`，按输入顺序返回 `task_batch_wait.tasks`。`--jsonl` 先逐任务输出本轮观察到的进度响应封装，最后输出
+批量结果；同批其他任务仍运行时，已经终态的任务不会重复输出终态事件。缺少、重复或额外响应任务会失败，
+不会猜测或改写任务。
+
+多作业任务部分成功时，逐项交付可信成功产物，并分别报告成功项、失败项和可补做项；在需要重新生成
+或改动参数前询问用户。已完成项不得因同批失败被覆盖，也不得自动再提交整批任务。
+
+### 等待超时优先级
+
+`task wait` 在首次读取到非终态任务后，只根据已返回的 `model_type` / `task_type` 选择**本地**观察窗口，
+不会为识别媒体类型额外发送读取请求，也不会提交、取消或重试任务。优先级从高到低如下：
+
+1. 命令显式 `--timeout`（包括全局或 `task wait` 的命令参数）；
+2. 用户在账号配置中显式配置的 `timeout`；
+3. 未设置上述超时时，已识别的视频或音频任务使用 10 分钟；混合批次只要包含视频或音频，也使用该较长窗口；
+4. 图片、未知媒体类型或不含视频/音频的批次使用系统生成的账号配置默认值。
+
+因此，用户配置的较短账号超时不会被视频默认值覆盖；任务 ID、提示词或其他调用方字段不能用于猜测媒体类型。
+
+定时任务处于 `SCHEDULED` 时，CLI 会依据服务端 `scheduledTime` 降低查询频率，并在
+接近执行时间后恢复普通轮询。等待远期任务时，`--timeout` 应大于“距执行时间 + 预计
+执行耗时”。`PAUSED` 和 `CANCELED` 会分别返回 `TASK_PAUSED`、`TASK_CANCELED`，不能
+当作仍在运行或自动重提的依据。
+
+定时取消、改期的服务端恢复合同以 `taskState` 和服务端 `scheduledTime` 为准，`isScheduled` 只表示任务曾
+设置定时，不能作为当前状态：取消后读到 `CANCELED` 才算成功；改期后仍为 `SCHEDULED` 且时间等于目标值才
+算成功，仍为旧时间说明未生效；已经进入 `INIT/RUNNING` 或任一终态则已越过取消/改期窗口。取消只面向尚未
+执行的 `SCHEDULED`，`terminate` 面向已进入执行阶段，两者不能混用。CLI 可以创建并管理已知 ID 的
+图片/视频服务端定时和单画布节点服务端定时，但不提供服务端全局列表或 DAG 请求。
+
+需要观察状态变化时使用：
+
+```sh
+nadou task events <task-id> --profile <profile> --jsonl
+```
+
+`task wait --json` 会在结果中返回 `elapsed_ms`；`text`（默认等待）和
+`image/video --wait --json` 会额外返回生成请求快照与 `timing`（发现、构建、提交、等待、
+产物查询和总耗时）。文本的错误恢复信息不回显请求快照或完整提示词，只保留任务 ID 等恢复证据。
+`events` 是 CLI 轮询时观察到的状态变化序列，不代表服务端提供 SSE 或可恢复事件游标。
+
+## 多任务报告、项目历史与可恢复批量下载
+
+```sh
+nadou task report <task-id-a> <task-id-b> --profile <profile> --no-interactive --json
+nadou task report <task-id> --output ./diagnostics/task-report.json --profile <profile> --no-interactive --json
+nadou task history --project-id <project-id> --page 0 --size 20 --profile <profile> --no-interactive --json
+nadou task download-batch --task-id <task-id-a> --task-id <task-id-b> \
+  --manifest ./delivery/download-manifest.json --output-dir ./delivery/artifacts \
+  --profile <profile> --json
+nadou task download-batch \
+  --resume-manifest ./delivery/download-manifest.json --profile <profile> --json
+```
+
+- `task report` 接受 1～100 个任务 ID，按输入顺序保留每个任务、作业、真实状态、失败原因和产物；只读取
+  一次批量状态，不等待、不下载、不交付，也不把部分成功压扁成整体成功或失败。
+- `task history` 固定为“显式项目 + 当前本人”范围，不提供跨项目全局历史。条目缺少可操作任务 ID 时会
+  标为不可操作，不能据此签发或下载产物。
+- `download-batch` 创建模式只下载已知任务 ID 的成功产物；相同规范化源 URL 只下载一次，但
+  `sources` 保留全部任务/作业/产物来源，`task_results` 同时保留失败、取消和未完成作业的事实。
+  即使全部任务失败且没有产物，也会形成零下载、可审计清单。清单只保存稳定源身份、本地相对路径、
+  大小和 SHA-256，不保存短期签名下载 URL。
+- 下载默认不覆盖；中断或部分失败后只用 `--resume-manifest` 读取原清单、复核已完成文件并重新签发待下载项。
+  恢复绝不创建或重新提交生成任务。
+
+独立图片、视频和音频默认不下载本地；只有用户明确要求本地文件时才使用单个任务的 `download-batch`，
+即使只有一个产物也创建清单。清单路径和输出目录必须在显式下载前披露并获授权，恢复只用
+`--resume-manifest`，不得用 `--overwrite` 代替恢复。该显式下载复用原任务/作业/产物，不会重新生成。
+
+生成证据可以从同一批报告创建并独立校验：
+
+```sh
+nadou evidence generation --task-id <task-id-a> --task-id <task-id-b> \
+  --output ./delivery/generation-evidence.json --profile <profile> --json
+nadou evidence validate --input ./delivery/generation-evidence.json --json
+```
+
+`task report --output <file>` 会先进行本地目标文件预检，再执行只读任务查询；默认拒绝覆盖。报告写入失败不会改变远端任务状态，也不会重新提交生成任务。机器模式错误读取 `meta.request_id`、`error.details.phase`、`request_outcome`、`task_id` 和 `suggested_actions`；普通模式的标准错误会显示请求 ID，并在事实已知时显示任务 ID 与恢复动作。
+
+所有证据文件默认拒绝覆盖，不得包含 token、Cookie、Authorization、短期签名 URL 或内部推理。

package/skills/nadou/commands/text.md

@@ -0,0 +1,81 @@
+# 文本
+
+`nadou text` 提供不依赖项目、画布或空间目录的原子文本生成。它不会创建画布节点，也不会把正文保存为素材。
+
+## 模型发现
+
+普通文本模型来自当前账号运行时目录中的 `TEXT_TO_TEXT_MODEL_CONFIG`；图片理解模型来自
+`IMG_TO_TEXT_MODEL_CONFIG`。先按明确场景发现，不在两个目录间回退：
+
+```sh
+nadou model list --type text --profile <profile> --json
+nadou model list --scenario image_to_text --profile <profile> --json
+```
+
+不要在 Skill 中写死模型名称。需要指定模型时，只使用本次目录返回的真实 `name`：
+
+```sh
+nadou text "写一段上海雨夜的电影旁白" \
+  --model <text-model> --profile <profile> --json
+```
+
+## 输入与预览
+
+普通 `text2text` 的位置参数、`--prompt`、`--prompt-file`、`--stdin` 必须且只能使用一个。长文本优先通过 UTF-8 文件或标准输入传入：
+
+```sh
+nadou text --prompt-file prompt.txt --profile <profile> --dry-run --json
+cat prompt.txt | nadou text --stdin --profile <profile> --dry-run --json
+```
+
+非交互或 `--json/--jsonl` 机器模式的正式提交必须带 `--submit`；优先使用显式 `--prompt`、
+`--prompt-file` 或 `--stdin`，位置提示词仅在已明确带 `--submit` 时接受；
+位置参数仅用于交互式调用或 `--dry-run` 预览。不要把 `nadou text models` 当作模型发现命令，
+模型目录必须使用 `nadou model list`。
+
+`--dry-run` 完成动态模型和参数校验，但不提交任务。公开预览使用 `model_type=text` 和
+`scenario=text2text`；请求中的后端兼容路由字段不是项目或画布绑定。
+
+## 图生文（`image_to_text`）
+
+读取一张或多张图片并返回正文时，使用有序 `--reference`；不能把它放入 `nadou image`：
+
+```sh
+nadou text "概括画面内容" --scenario image_to_text \
+  --reference <trusted-image-url> --model <runtime-model> \
+  --profile <profile> --dry-run --json
+```
+
+`image_to_text` 对应目录 `IMG_TO_TEXT_MODEL_CONFIG` 和任务类型 `IMG2TEXT`。至少需要一张可信
+HTTPS 图片，数量按当前模型 `max_images/maxImages` 校验；只有所选模型实时声明
+`hasPromptFreeSubmit=true` 时才允许省略提示词。`--reference`
+不接受本地路径，也不会隐式上传，本地图片必须先显式执行 `nadou material upload` 获取可信 URL。
+无写预览不创建项目、画布、节点或空间素材，也不执行媒体下载。
+
+## 默认等待与正文
+
+`nadou text` 默认等待完成，不需要额外增加 `--wait`：
+
+```sh
+nadou text "写一句克制的生日祝福" --profile <profile> --compact --json
+```
+
+正文位于 `data.outputs.outputs[].text`，不能从 `url`、下载地址或素材字段猜测。任务完成但没有非空
+`text` 时属于产物契约错误，必须保留原任务 ID 进行排查。
+
+对于权威任务类型 `IMG2TEXT`，正文可能承载在 `productUrl/url` 字段；
+`nadou text --scenario image_to_text` 高层入口会把它投影到 `text` 并清空媒体 `url`，即使正文外形
+像 HTTPS 地址也不改变语义。通用 `nadou task outputs` 为兼容调用方保留 `url` 字段，
+但 Agent 必须把它视为正文且不得下载。普通图片和视频任务仍按 URL 投影。后端额外编码的一层 JSON
+字符串只解一层。
+
+显式使用 `--wait=false` 时只提交一次并返回任务 ID：
+
+```sh
+nadou text "写一句克制的生日祝福" --profile <profile> --wait=false --json
+nadou task wait <task-id> --profile <profile> --json
+nadou task outputs --task-id <task-id> --profile <profile> --json
+```
+
+提交成功后的等待或产物读取错误不得触发重新提交；始终使用返回的原任务 ID 恢复。文本正文不执行
+`space artifact deliver`，当前版本只直接输出文本。

package/skills/nadou/commands/video-advanced.md

@@ -0,0 +1,96 @@
+# 高级视频
+
+本参考只描述独立原子任务中的 `video_edit` 和 `motion_control`。它们是 NadouAI
+模型生成能力，不是 `nadou media` 的本地视频处理（裁剪、拼接、字幕或转码）。用户明确
+提到画布时，改走画布节点流程。
+
+两个场景都必须先动态发现模型和参数结构：
+
+```sh
+nadou model list --scenario video_edit --profile <profile> --json
+nadou model list --scenario motion_control --profile <profile> --json
+nadou model schema <model-id> --scenario <scenario> --profile <profile> --json
+```
+
+不得在 Skill 中固定模型、时长、分辨率、声音、方向或输入数量。场景目录为空、组合限制
+无法读取或显式参数不在参数结构时，在提交前停止，不得切换到其他视频场景。
+
+## 视频语义编辑（`video_edit`）
+
+`video_edit` 对应远端模型驱动的视频重新生成/语义编辑，至少需要一段源视频和非空提示词：
+
+```sh
+nadou video "<edit prompt>" --scenario video_edit \
+  --source-video <trusted-video-url> \
+  [--reference-image <trusted-image-url>] \
+  [--reference-audio <trusted-audio-url>] \
+  [--audio-setting <runtime-value>] \
+  --model <model-id> --profile <profile> --dry-run --json
+```
+
+`--source-video`、`--reference-image`、`--reference-audio` 均可重复，但只有当前模型
+参数结构明确支持对应类型和数量时才能提供。不得使用无角色的 `--reference` 代替这些参数。
+
+## 动作控制（`motion_control`）
+
+`motion_control` 必须明确区分一张主体图片和一段动作参考视频；提示词可省略：
+
+```sh
+nadou video --scenario motion_control \
+  --subject-image <trusted-image-url> \
+  --motion-video <trusted-video-url> \
+  [--keep-original-sound <runtime-value>] \
+  [--character-orientation <runtime-value>] \
+  [--resolution <runtime-value>] \
+  --model <model-id> --profile <profile> --dry-run --json
+```
+
+主体图片和动作视频不可互换；不得使用无角色的 `--reference` 静默猜测。CLI 会拒绝 URL
+扩展名已经能证明角色错误的输入；无法从 URL 权威判断类型时，角色由显式参数保留，服务端
+做最终媒体校验。
+
+运行时目录中的 `audioSetting`、`characterOrientation` 是面向用户的展示值；CLI 在请求
+边界分别转换为 NadouAI 协议值 `auto/origin` 与 `image/video`，不得把展示文本直接发送给
+任务接口。`--dry-run` 返回的 `server_validated_constraints` 会列出仅凭远端 URL 无法证明
+的输入视频时长、输入音频时长、视频音轨存在性或方向兼容性。`valid=true` 只表示本地角色、
+地址、数量和动态枚举校验通过，不代表这些媒体事实已由服务端确认。
+
+## 素材、费用和恢复
+
+生成命令不会隐式上传。可信 HTTPS 素材直接复用，不重复上传；只有本地图片、视频或音频会进入最终
+请求且所选场景必须接收服务端 URL 时，才在说明远端写入原因和范围后分别执行一次，用户拒绝时停止：
+
+```sh
+nadou material upload --file <local-media> --profile <profile> --json
+```
+
+该独立输入上传不是个人空间交付，也不自动关联画布。用上传结果的可信 URL 构造预览请求。随后按
+[task-request.md](task-request.md) 使用同一个
+`data.request` 查询 `points summary`、执行 `task estimate`、展示估价与余额并获得费用
+确认，最后用请求文件执行一次 `task submit`。任一角色输入、顺序、模型、参数、配置环境、
+计费空间或交付目标变化都使旧确认失效。
+
+提交未知、等待超时或产物读取失败时，保存请求 ID 和原任务 ID，只运行
+`task status`、`task wait`、`task outputs`、`task download` 恢复，不得重新提交。
+
+按三个阶段分别报告：
+
+1. `submitted`：报告请求 ID、任务 ID、已提交状态和用户选定的计划目标；未选择目录的请求不得进入 `submitted`。
+2. `generated`：仅在任务终态成功且 `task outputs` 返回同一任务/作业下的可信视频时报告；
+   此时 `generation_status=COMPLETED`；交付状态沿用提交前绑定的目标。已处于 `delivery_status=AWAITING_DESTINATION` 的任务恢复目录选择。任务完成但没有
+   可信视频产物属于契约错误，不能报告生成成功。
+3. `delivered`：仅在用户选择的个人目录或已指定空间交付成功，且目录按 `resource_id` 回读命中后报告；
+   此时才把 `delivery_status` 更新为 `SUCCEEDED`。
+
+任务完成后通过任务 ID、作业 ID、产物索引选择可信视频，显式运行 `space artifact deliver` 并执行
+`space directory contents` 回读。交付目标必须是提交前由用户选择或明确指定的目录；
+任务产物交付不是 `material upload`，不得重新上传生成结果。回读前只报告计划目标；
+生成成功但交付失败时分别报告生成和交付状态。生成前确认计划空间和目录存在；
+交付命令使用服务端空间类型、明确的 `manager/member/viewer` 目录角色和稳定权限错误做写前
+失败关闭，不得根据名称、当前用户身份或本地化消息猜权限，也不得试写。需要个人空间保底时显式传入
+`--fallback-to-personal`；结果未知时禁止自动回退。
+
+只有交付成功且目录按资源 ID 回读命中后，才报告实际 `space_id`、`directory_id`、服务端目录
+路径、`resource_id`，以及服务端权威返回的 `material_url`（若有）。服务端未返回页面地址时，
+不得自行拼接或伪造 URL。用户明确选择画布时使用画布节点流程，不同时创建个人空间副本；本地下载和
+媒体处理都不是默认动作，只有用户明确要求时执行。