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

package/skills/nadou/commands/image.md

@@ -0,0 +1,273 @@
+# 图片
+
+图片生成与图片工具是两个层级：`nadou image` 从当前账号动态模型目录选择模型并生成；
+Web 同款的打光、多视角、人像质感、超清和多宫格使用独立的
+[`nadou image-tool`](image-tools.md)。不要把工具的固定服务路由当作动态模型，也不要用普通
+`image_ref` 提示词模拟工具参数。
+
+## 路径选择
+
+`nadou image` 始终是独立路径，不会创建或修改 Canvas 节点。如果用户明确指定 Canvas，
+应改用现有的 `canvas node estimate` → `canvas node generate` 路径。不得通过下载后
+重新上传，把独立结果伪装成 Canvas 生成节点；上传/自定义节点的来源与生成节点的提示词界面
+属于不同契约。
+
+> **入口编排约定**：本命令只生成原子图片，不隐式写空间。提交前入口 Agent
+> 先解析显式目录或列出空间目录候选，完成余额/估价、用户选择目录和一次确认后才提交；取得可信产物后使用同一目标
+> 执行一次 `space artifact deliver`。本地下载状态与空间交付状态独立报告。
+
+`nadou image` 是独立原子生图命令。提示词优化当前为 `deferred`，默认直接提交用户原始提示词，
+不询问是否优化，也不调用未开放的优化能力。
+
+长提示词优先使用文件或标准输入，避免正文进入进程参数：
+
+```sh
+nadou image --prompt-file prompt.txt --profile <profile> --dry-run --no-interactive --json
+cat prompt.txt | nadou image --stdin --profile <profile> --dry-run --no-interactive --json
+```
+
+位置参数、`--prompt`、`--prompt-file`、`--stdin` 必须且只能选择一个；文件和标准输入最多
+1 MiB。`--compact` 仅用于 `--json/--jsonl`，会保留任务 ID、状态、产物 URL
+和耗时，但不回显提示词、完整请求或后端 `raw`。
+
+非交互或 `--json/--jsonl` 机器模式的正式提交必须带 `--submit`；优先使用显式 `--prompt`、
+`--prompt-file` 或 `--stdin`，位置提示词仅在已明确带 `--submit` 时接受；
+位置参数仅用于交互式调用或 `--dry-run` 预览。不要把 `nadou image models` 当作模型发现命令，
+模型目录必须使用 `nadou model list`。
+
+费用确认后的 `task submit` 会立即给出任务 ID。后续使用该任务 ID 执行
+`task status`、`task wait` 和 `task outputs`；中断或失败时继续从同一个任务 ID
+恢复，不得重新提交生成请求。
+
+`nadou image` 仍是可独立调用的原子命令，但入口 Agent 不直接跳到付费提交。先预览唯一请求：
+
+```sh
+nadou image "一只白色小猫坐在未来感工作台旁" --profile <profile> --dry-run --no-interactive --json
+```
+
+将返回的 `data.request` 字段保存为 `request.json`，再严格按照
+[task-request.md](task-request.md) 执行 `points summary`、`task estimate`、费用确认和
+使用同一个请求文件的 `task submit`。确认前不得提交；估价不锁价，确认后不得重新运行
+`nadou image` 来重建请求。
+
+`nadou image` 始终提交独立任务，不接受 `--canvas-id`，也不会隐式创建或修改节点。在画布上下文中
+不建议用它代替画布节点生成：应显式创建或选择图片目标节点，并带同一 `--canvas-id` 执行
+`nadou canvas node generate --canvas-id <canvas-id>`，让状态和产物由回调写回同一节点。
+`--dry-run` 只预览独立任务请求，不预览或写入画布节点。
+
+定时默认关闭。服务端定时只在用户明确选择后使用：
+
+```sh
+nadou image --prompt-file prompt.txt \
+  --schedule-mode server --scheduled-at "2026-08-03T21:30:00" \
+  --timezone Asia/Shanghai --profile <profile> --dry-run --no-interactive --json
+```
+
+画布定时只能使用每小时 `00` 或 `30` 分钟的本地时间卡点，秒数必须为 `00`；其他分钟会在网络请求前被拒绝。
+普通图片服务端定时沿用服务端既有时间规则。
+
+该入口必须保留 `--dry-run`，再从 `data.request` 落盘并执行同请求费用预检和一次提交。本地定时
+不要在图片请求中上传定时参数：先生成普通预览请求，再按
+[schedule.md](schedule.md) 执行 `schedule create` 和显式执行程序。
+
+## 提交前确定交付目录
+
+`nadou image` 只生成独立图片任务。用户没有明确指定画布、空间目录或仅下载时，入口在费用确认前
+通过 `space current` 和 `space directory list` 列出目标空间全部目录候选，不得把个人空间根目录直接当作默认目标。
+用户必须在同一条确认中选择目录并确认费用；只有已处于 `delivery_status=AWAITING_DESTINATION` 的任务才恢复目录选择与交付。
+
+入口 Agent 的最终回复必须先给出目录选择提示，不能在拿到图片 URL 后直接结束：
+
+```text
+生成前计划：generation_status=PLANNED
+可选交付目录：<目录候选及完整层级路径>
+用户选择：<directory_id，未选择时不得提交>
+下一步：在同一条回复中选择目录并确认费用；确认后只提交一次，完成后写入所选目标并回读
+```
+
+目录候选来自本次 `space current` 和 `space directory list` 的真实响应；完整层级和 ID 不能凭名称猜测。
+候选查询失败或用户未选择时不得提交任务。用户确认后，才使用原任务/作业/产物执行一次交付并
+回读确认。
+
+```sh
+nadou space current --profile <profile> --no-interactive --json
+nadou space directory list --group-id <data.personal.id> --profile <profile> --no-interactive --json
+```
+
+从 `space current` 的 `data.personal.id` 取得个人空间 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`，不得重新上传生成结果。生成状态与交付状态分别报告；某个产物交付失败或结果未知，
+不得覆盖已经确认的生成成功，不得自动重试、改投其他目录或切换当前空间。用户取消、目录不完整或
+非交互调用未给目标时仅列出候选并停止，不解析或绑定个人根目录；未使用 `--wait` 时只报告计划目标，并提供
+`task wait`、`task outputs`、`space artifact deliver` 恢复步骤。交付失败/未知时保持生成成功，不重提或改投。
+空间交付和服务端在线结果是入口默认交付。本原子命令不会自动下载或创建本地清单；
+只有用户明确要求本地文件时，才在费用/执行摘要中披露绝对目标目录和不覆盖规则，并获得单独授权。
+
+用户明确要求本地下载后，取得可信产物并以原任务 ID 创建持久清单：
+
+```sh
+nadou task download-batch \
+  --task-id <task-id> \
+  --manifest <absolute-target>/download-manifest.json \
+  --output-dir <absolute-target>/artifacts \
+  --profile <profile> --json
+```
+
+即使只有一个输出也使用该命令；多产物部分失败后只执行
+`task download-batch --resume-manifest <absolute-target>/download-manifest.json`。默认拒绝覆盖，
+不得使用 `--overwrite` 恢复，也不得重新生成。`local_delivery_status`、空间 `delivery_status` 与生成状态
+是入口 Skill 组合流程状态，不是本命令 JSON 响应封装的字段。未明确要求本地下载时不创建清单、不报告本地路径；
+用户明确提到画布、仅生成或仅空间交付时同样跳过本地下载，画布流程不同时创建个人空间副本。
+
+可选地指定动态目录中的模型：
+
+```sh
+nadou image "古典园林里的薄雾和红灯笼" --model <image-model> --profile <profile> --dry-run --no-interactive --json
+```
+
+先通过 `nadou model list --scenario text2img` 从当前账号的动态目录中选择
+`<image-model>`，不要猜测或复用其他账号的值。
+
+## 图片融图（`image_ref`）
+
+用户明确要求参考一张或多张图片生成新图时，使用独立 `image_ref`；它不会创建画布：
+
+```sh
+nadou model list --scenario image_ref --profile <profile> --no-interactive --json
+nadou model schema <model-id> --scenario image_ref --profile <profile> --no-interactive --json
+nadou image "<prompt>" --scenario image_ref \
+  --reference <trusted-image-url-1> \
+  --reference <trusted-image-url-2> \
+  --model <model-id> --profile <profile> --dry-run --no-interactive --json
+```
+
+`image_ref` 对应服务端 `IMG_REF`，至少需要一项有序 `--reference`；最大图片数、比例、
+清晰度和生成数量全部读取所选模型当前参数结构。普通文生图不得携带引用。已知视频或音频
+扩展名的 URL 不能放入图片角色；无法从 URL 权威识别的媒体类型仍由服务端最终校验。
+
+### 融图富文本提示词
+
+当提示词需要明确表达“哪一张参考图对应哪段描述”时，可使用独立任务的 Web 富文本引用格式：
+
+```bash
+nadou image --scenario image_ref --prompt-format rich \
+  --prompt-file prompt.html \
+  --reference https://assets.example/beach.png \
+  --dry-run --no-interactive --json
+```
+
+例如，`prompt.html` 可以把引用标签直接放在对应语义前：
+
+```html
+<p><span data-type="reference-tag" data-value="海边背景"
+data-url="https://assets.example/beach.png" class="reference-tag image-tag">
+<span class="reference-tag-text">@海边背景</span></span>作为背景，生成一个女孩在沙滩上奔跑。</p>
+```
+
+`prompt.html` 必须是 UTF-8，并包含覆盖 `--reference` 唯一 URL 集合且首次出现顺序一致的
+`data-type="reference-tag"` 标签；同一 URL 可以重复出现。每个标签需要有可信 HTTPS `data-url`、可见的
+`reference-tag-text`；UI 标签可以携带画布专用的 `data-id`，CLI 会在独立请求前移除它并保留该 HTML，
+同时继续提交 `params.image`、`form.referenceImages` 和 `form.thumbsOrder`；不会把
+`prompt-format` 作为后端字段发送。
+
+普通位置参数和 `--prompt-format plain` 行为保持不变。CLI 不会根据普通文本猜测引用位置，
+也不会在融图命令中隐式上传本地文件。富文本校验失败时在提交前停止。
+
+`--reference` 不接受本地路径，也不会隐式上传。可信 HTTPS 素材直接复用；只有本地图片会进入最终
+请求且所选模型必须接收服务端 URL 时，才在说明远端写入后显式上传一次。用户拒绝时停止：
+
+```sh
+nadou material upload --file <local-image> --profile <profile> --no-interactive --json
+```
+
+### Web 富文本引用兼容
+
+独立模式的 `image_ref --prompt-format rich` 接受 Web 编辑器的参考标签 HTML。标签包含
+`data-id` 时，CLI 会先把其中的 `data-url` 与显式 `--reference` 匹配，再移除这项 UI/Canvas 元数据。
+重复标签保留在描述中，任务媒体参数则按首次出现顺序使用去重后的 URL。禁用、空值、不可信或未声明的
+引用都会在提交前失败。画布提示词保留 `data-id`，并根据实时 Graph 校验，不按独立输入处理。
+
+上传写结果未知时先核对素材，不能重新上传；取得可信 URL 后再重新执行融图预演。
+引用的内容或顺序变化会使旧估价和确认失效。用户明确提到画布时不使用本节流程，改走
+画布图片节点和 `canvas node generate`。
+
+## 全景与三视图
+
+全景和主体三视图分别从当前账号专属目录发现，不复用普通文生图或融图参数结构：
+
+```sh
+nadou model list --scenario panorama --profile <profile> --no-interactive --json
+nadou model list --scenario three_view --profile <profile> --no-interactive --json
+
+nadou image "未来城市的 360 度街景" --scenario panorama \
+  --reference <trusted-image-url> --space-size more_spacious --quality high \
+  --model <runtime-model> --profile <profile> --dry-run --json
+
+nadou image "保持角色一致，生成正面、侧面、背面三视图" --scenario three_view \
+  --reference <trusted-image-url> --model <runtime-model> \
+  --profile <profile> --dry-run --no-interactive --json
+```
+
+`panorama` 对应 `PANORAMA_GENERATION_MODEL_CONFIG` / `PANORAMA_GENERATION`，`three_view`
+对应 `THREE_VIEW_GENERATION_MODEL_CONFIG` / `THREE_VIEW_GENERATION`。二者提示词必填，参考图
+可为空；存在参考图时保持顺序，并按所选模型当前参数结构校验图片类型和数量。比例、清晰度与数量
+均来自目录。`--space-size` 只属于 `panorama`；所选图片模型参数结构声明 `quality` 时，普通
+`text2img`、`image_ref`、`panorama`、`three_view` 和 `inpaint` 都会把 `快速/平衡/高质量` 转换成
+`low/medium/high`，普通图片场景也允许显式使用 `--quality`。MJ 模型的 `MJ 7/Niji 7`、`Standard/Raw`
+展示值转换为任务布尔值；不能将展示标签直接写入任务。
+
+## 图片局部重绘（`inpaint`）
+
+局部重绘必须显式区分源图和遮罩，不允许使用无角色的 `--reference` 猜顺序：
+
+```sh
+nadou model list --scenario inpaint --profile <profile> --no-interactive --json
+nadou image "将遮罩区域改成霓虹机械结构" --scenario inpaint \
+  --source-image <trusted-source-url> --mask <trusted-mask-url> \
+  --model <runtime-model> --profile <profile> --dry-run --no-interactive --json
+```
+
+`inpaint` 对应 `CANVAS_IMG_REDRAW` / `IMG_INPAINT`。`--source-image` 和 `--mask` 各且仅一个，
+都必须是可信 HTTPS 图片 URL；重复、缺失、本地路径和已知非图片类型均在提交前失败。模型、数量和
+默认参数从当前目录动态读取，不写死重绘模型；目录中的 `MJ 7/Niji 7`、`Standard/Raw` 展示值在
+请求边界转换为后端布尔值，无法解释的默认值失败关闭。
+
+局部重绘只生成独立结果图片，不创建 Canvas Graph 节点，不写回调/修订状态，也不替换源图。
+本地源图和遮罩分别先显式执行 `nadou material upload`；提交确认前绑定已确认的空间目录，
+并按用户明确授权以单个任务的 `task download-batch` 清单下载到用户指定的本地目录。
+用户指定团队目录时替换空间目标，
+本地下载状态与空间交付状态分别报告。
+远端实际图片内容以及源图/遮罩尺寸兼容性由服务端提交最终验证。
+
+费用确认后的低层提交只执行一次并返回任务 ID，适合稍后恢复：
+
+```sh
+nadou task submit --body-file request.json --profile <profile> --no-interactive --json
+nadou task wait <task-id> --profile <profile> --no-interactive --json
+nadou task outputs --task-id <task-id> --profile <profile> --no-interactive --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` 复用原任务/作业/产物，不重新生图。
+
+模型比例、清晰度和数量使用服务端目录默认值。需要构造低层独立任务请求或高级回放
+`request.json` 时，读取 [task-request.md](task-request.md)，优先用 `--dry-run --json`
+获得当前 CLI 构造的 `data.request`，不要手写请求外壳。模型、提示词、参考素材、比例、
+清晰度、数量、账号配置、当前计费空间或请求发生变化时，旧估价和任务级积分上限授权失效，
+必须重新预检。`estimable=false`、余额未知或余额不足时停止。画布节点生成默认由
+`canvas node generate` 从节点配置和依赖边派生请求。

package/skills/nadou/commands/material.md

@@ -0,0 +1,59 @@
+# 本地素材上传与删除
+
+把一个本地图片、视频或音频上传为独立素材，或显式归属到画布：
+
+```sh
+nadou material upload --file <path> \
+  --profile <profile> --no-interactive --json --timeout 10m
+```
+
+不要把素材上传作为每次创作的固定前置步骤。可信 HTTPS 素材直接复用，不重复上传；只有用户明确要求
+使用本地素材、该素材会进入最终请求且所选能力必须接收服务端 URL 时，Agent 才说明远端写入原因、
+素材范围和独立上传语义，然后上传实际引用素材一次。用户拒绝时停止，不上传无关素材，也不通过空间
+交付或画布上传绕过。独立输入上传不是个人空间交付，不保证素材出现在个人空间或界面素材库。
+
+未传 `--canvas-id` 时，这是**独立上传**：CLI 在普通上传以及分片初始化、分片、完成的每一阶段都省略
+`workflowId`，返回 `scope.type=standalone` 与可供独立 `nadou video --reference <url>` 使用的公网 `url`。它不创建、选择或修改画布。
+
+显式传入 `--canvas-id <canvas-id>` 时，这是**画布归属上传**：CLI 将该值写入协议字段
+`workflowId`。`--workflow` 不是别名。需要服务端添加水印时增加 `--add-watermark`。
+CLI 不在本地复制后端的格式、尺寸或时长规则，服务端仍执行最终校验。
+
+成功时读取正整数 `data.id` 为 `material_id`，并读取经过公网地址校验的 `data.url` 作为后续任务请求的素材 URL；本机、私网和已知内网
+域名会被拒绝。若接着创建画布图片或视频节点，还必须使用 `data.metadata.width` / `data.metadata.height`
+计算节点显示尺寸，不得臆造固定长宽；并按 [json-contract.md](../node-types/json-contract.md) 的上传素材
+允许列表，把同次响应中的多档预览/封面 URL（`thumbnailUrl` / `mediumThumbnailUrl` / `previewUrl` /
+`firstFrameUrl`）以及 `assetId` / `assetName`（视频另含 `duration` / `fps` 等）有值键写入创建请求的
+`data.metadata`，不要整包复制上传元数据。
+`data.file_name` 只包含文件名，`data.file_size`、`data.scope` 和 `data.upload_mode=single|multipart`
+用于对账。CLI 不输出 `innerUrl`、本地绝对路径或上传会话内部标识。
+
+文件小于 5 MiB 时只发送一次普通上传；大于等于 5 MiB 时按初始化、顺序分片、完成执行，
+分片为 5 MiB。`--timeout` 覆盖从 `init` 到 `complete` 的完整上传流程，不会按分片重新计时。
+每个阶段最多发送一次，不自动重试。遇到 `REQUEST_OUTCOME_UNKNOWN` 时保留 `request_id`、
+`phase`、文件名/大小和作用域：普通上传/完成阶段需要请 NadouAI 支持通过后端日志确认写入
+结果；初始化/分片阶段的上传会话当前无法由 CLI 安全对账、恢复或续传，不得直接重跑或自动重启。
+
+上传只创建素材记录并返回公网 URL；即使选择画布归属，也不会创建或修改画布节点，
+也不保证记录自动显示在界面素材库。所有上传都通过 `nadou material upload` 完成。
+
+删除上传后的单个素材必须使用返回的 `material_id`：
+
+```sh
+nadou material delete <material-id> --profile <profile> --no-interactive --json
+```
+
+默认把素材移入回收站。逻辑永久删除必须由用户明确要求，并在非交互模式同时传入：
+
+```sh
+nadou material delete <material-id> --permanent --yes \
+  --profile <profile> --no-interactive --json
+```
+
+删除只调用已批准的 `/apis/nadouai/material/disable`，不使用 URL、任务 ID 或作业 ID 扩大匹配范围；
+也不代表物理擦除 OSS 文件。每条删除命令只发送一次写请求。若返回
+`REQUEST_OUTCOME_UNKNOWN`，保留请求 ID 和素材 ID，先在 NadouAI 中核对素材状态，
+不得自动重试。
+
+交互模式的上传进度只写标准错误；`--json`、`--jsonl` 或 `--no-interactive` 不输出进度，标准输出
+始终只承载最终结果信封。

package/skills/nadou/commands/media.md

@@ -0,0 +1,156 @@
+# 本地媒体命令
+
+`nadou media` 只处理本地文件，不发送 NadouAI 或其他网络请求。所有命令默认不修改输入；
+写命令生成独立输出并默认拒绝覆盖，媒体检查和交付核验只读。
+
+普通原子生成不调用本地媒体命令。只有用户明确要求技术验收，或明确选择的下载、字幕、合成和最终
+交付确实需要媒体事实时，才运行只读检查；只读技术检查不授权媒体变换。只有用户明确要求适配，或
+已选择的下游目标存在实际不兼容时，才运行缩放、规范化或转码，并在执行前说明原因、输入和独立
+输出。已满足目标约束时不重复规范化；需要改变构图时也不得把等比补边冒充用户授权的裁切。
+
+## 交付预设
+
+规范化、线性成片和核验必须显式选择以下版本化预设之一，不能根据首个片段猜测画幅：
+
+- `landscape-1080p-v1`：1920×1080；
+- `portrait-1080p-v1`：1080×1920；
+- `square-1080p-v1`：1080×1080。
+
+三者统一为 MP4、H.264、yuv420p、30fps、AAC-LC、48kHz、双声道。
+
+## 检查本地媒体
+
+```sh
+nadou media inspect --input ./outputs/final.mp4 --json
+```
+
+稳定结果包含：
+
+- `input_path`、`size_bytes` 和 `duration_ms`；
+- 音频-only 输入返回 `media_type=audio`；视频输入保持既有投影，并包含主视频流的 `width`、`height` 和约分后的 `ratio`；
+- `has_audio`、`stream_count` 和全部稳定流字段；
+- `tool=ffprobe`。
+
+检查只需要 ffprobe，不要求 FFmpeg 同时可用。缺失时返回 `MEDIA_TOOL_MISSING`，先执行
+`nadou doctor --json` 查看诊断。损坏文件、无音频/视频流、无有效时长或视频无有效尺寸返回
+`MEDIA_PROBE_FAILED`。不要把未执行或失败的检查描述为通过。
+
+多参考视频在上传本地音频前，必须先检查音频时长：
+
+```sh
+nadou media inspect --input ./references/voice.mp3 --json
+```
+
+再将 `duration_ms` 与当前账号模型 Schema 的 `audio_duration` 区间比较。以模型返回的
+`[2000,15000]` 为例，边界包含在内；超出范围时停止，不执行 `material upload`、估价或任务提交。
+远程 HTTPS 音频没有本地时长事实时，继续标记为服务端校验，不得根据文件名或 URL 猜测。
+
+## 烧录双语字幕
+
+```sh
+nadou media subtitle --input ./outputs/raw.mp4 --cues ./subtitles.json \
+  --output ./outputs/final.mp4 --font "Microsoft YaHei" --json
+```
+
+字幕条目的 `version` 可写成 JSON 数字 `1` 或字符串 `"1"`，两者统一按版本 1 处理；每项包含
+`start_ms/end_ms/zh/en`。输入和输出不能是同一文件；
+默认拒绝覆盖，确需替换已有输出时显式使用 `--overwrite`。
+
+## 兼容片段拼接
+
+```sh
+nadou media concat --input ./shot-1.mp4 --input ./shot-2.mp4 \
+  --output ./outputs/joined.mp4 --json
+```
+
+命令严格保留输入顺序，只做流复制。流参数不兼容时返回
+`MEDIA_INCOMPATIBLE_INPUTS`，不自动转码，也不调用云端合并服务。
+
+## 规范化不兼容片段
+
+```sh
+nadou media normalize --profile landscape-1080p-v1 \
+  --input ./shot-1.mp4 --input ./shot-2.mp4 \
+  --output-dir ./normalized --json
+```
+
+命令先探测全部输入，再将画面等比缩放、居中补黑边并统一编码；没有音频的片段补等长静音。
+该命令被用户显式调用后，即使源文件已经符合预设，也会生成独立输出并报告
+`source_compatible=true`；因此 Agent 必须先判断它是否为下游目标所需，不能把命令行为当作默认流程。
+只有结果中的
+`comparison.matches=true` 才表示容器、视频和音频技术规格均复查通过。
+
+## 按清单线性成片
+
+```sh
+nadou media compose --manifest ./edit-manifest.json \
+  --output ./outputs/final.mp4 --json
+```
+
+清单的 `version` 可写成 JSON 数字 `1` 或字符串 `"1"`，包含显式账号配置和有序
+`segments`；每段可选 `in_ms/out_ms`，
+并可提供一份现有格式的双语字幕条目文档作为 `subtitles`。相对路径以清单目录为基准。
+命令不支持转场、多轨、背景音乐或自动混音。多片段在拼接后会执行一次最终时间戳、固定帧率
+和音频重采样归一化，再按同一账号配置严格验证；不会用放宽验证掩盖不合格产物。预检、转码、
+拼接、硬字幕和最终探测任一步失败，
+都不得把临时文件报告为最终交付。
+
+## 代表帧与技术核验
+
+```sh
+nadou media frames --input ./outputs/final.mp4 --count 5 \
+  --output-dir ./review --json
+
+nadou media verify --input ./outputs/final.mp4 \
+  --profile landscape-1080p-v1 --json
+```
+
+`frames` 使用确定性时间点均匀覆盖主视频流有效时长，并返回每张 JPEG 的来源和
+`timestamp_ms`。当音频或容器尾部比视频轨更长时，以主视频流时长为边界并预留一个视频帧
+周期；只有流时长不可用时才回退容器时长，不通过失败后递减时间点重试。
+`verify` 只调用 ffprobe，将实际媒体事实与显式预设逐项对照。两者始终返回
+`creative_review_required=true`：技术通过不等于剧情、角色一致性或画面创意已经通过。
+
+## 本地多轨混音
+
+```sh
+nadou media mix --manifest ./delivery/audio-mix-plan.json \
+  --output ./delivery/mixed.mp4 --dry-run --json
+nadou media mix --manifest ./delivery/audio-mix-plan.json \
+  --output ./delivery/mixed.mp4 --json
+```
+
+`audio_mix_plan` 是严格的版本 1 JSON，只接受清单目录内的相对视频/音频路径。每条音轨显式声明
+`narration/music/effect`、起点、裁剪、音量和淡入淡出；可配置旁白区间内的音乐压低与目标响度。
+`--dry-run` 只探测输入并返回确定性滤镜计划，不创建最终媒体。正式混音保持原视频完整时长，默认拒绝
+覆盖；失败只清理临时文件，不把局部输出称为交付物。
+
+## 字幕校验与导出
+
+```sh
+nadou media subtitle validate --cues ./subtitles.json \
+  --input ./delivery/mixed.mp4 --font "Microsoft YaHei" \
+  --report-output ./delivery/subtitle-report.json --json
+nadou media subtitle export --cues ./subtitles.json --format srt \
+  --output ./delivery/subtitles.srt --json
+nadou media subtitle export --cues ./subtitles.json --format ass \
+  --output ./delivery/subtitles.ass --font "Microsoft YaHei" --json
+```
+
+校验会一次报告非法时间范围、乱序、重叠、越过媒体时长、双语缺失和字体可用性。显式字体不可用为
+阻塞错误；默认字体无法确认时保守警告。`--report-output` 显式保存可供 `evidence delivery` 引用的裸
+版本 1 报告；未指定时校验零写入。报告、导出与烧录均默认不覆盖。
+
+最终交付使用完整的 `media verify --json` 成功响应封装，并与生成证据、下载清单和人工确认共同生成：
+
+```sh
+nadou evidence delivery --generation ./delivery/generation-evidence.json \
+  --download ./delivery/download-manifest.json --media ./delivery/final.mp4 \
+  --verification ./delivery/media-verify.json \
+  --confirm-narrative --confirm-characters --confirm-subtitles \
+  --output ./delivery/delivery-manifest.json --json
+nadou evidence validate --input ./delivery/delivery-manifest.json --json
+```
+
+技术校验不能代替叙事、角色一致性和字幕人工确认；任一引用缺失、越界、哈希值不符或来源文件不一致时，
+交付证据必须失败关闭。

package/skills/nadou/commands/model.md

@@ -0,0 +1,103 @@
+# 模型
+
+## 基础 Schema 与有效 Schema
+
+目录返回的是基础 Schema。Web 还会根据模型、场景、首尾帧角色、已选参数和参考素材事实应用条件规则；CLI 在本地使用纯规则评估器生成有效参数。`model schema` 对已知模型额外返回 `conditional_rules`，用于说明受影响字段，但不替代当前账号目录或服务端最终校验。远程素材事实未知时，CLI 不会伪造事实；用户显式指定受影响参数时会在提交前失败关闭。
+
+模型发现有两个入口：知道**真实模型 ID**时使用 `model get/schema/scenarios`；只知道
+展示名（例如“Happy Horse 1.1”）时，先读取模型族。模型族按运行时目录中明确的
+“供应商 → `versions` → 版本”路径归并，不根据 `-txt`、`-ref` 或 `-img` 等 ID 后缀猜测：
+
+```sh
+nadou model family "Happy Horse 1.1" --profile <profile> --no-interactive --json
+```
+
+输出的 `variants[]` 保留每个真实 `model_id`、`scenario`、`config_key` 和独立 `schema`。
+选定能力后，后续 `model schema` 或生成仍必须使用该 `model_id`；CLI 不会把一个
+场景的真实模型 ID 自动改成同族的另一个变体。
+
+如果同一展示名来自多个供应商，命令会返回候选而不猜测；传明确的供应商消歧：
+
+```sh
+nadou model family "同名模型" --provider "供应商名" --profile <profile> --no-interactive --json
+```
+
+同一**真实模型 ID**也可能出现在多个创作场景。此时先查询目录中的真实场景键，再传给
+`model get/schema --scenario`：
+
+```sh
+nadou model scenarios <model-id> --profile <profile> --no-interactive --json
+```
+
+若精确 ID 省略了必需的 `--scenario`，`INVALID_ARGUMENT` 的
+`details.scenarios` 会返回同一组候选；不要依据展示名或媒体类型猜测。
+
+查看当前环境可用的图片和视频模型。默认返回压缩摘要 `models[]`
+（`name`/`label`/`defaults`），不要把整份配置树塞进上下文：
+
+```sh
+nadou model list --profile <profile> --type image --no-interactive --json
+nadou model list --profile <profile> --type video --no-interactive --json
+nadou model list --profile <profile> --type audio --no-interactive --json
+```
+
+只有排查原始目录时才加 `--raw`。
+
+创作请求应优先按场景发现，避免把同一展示模型在不同场景下的参数混在一起：
+
+```sh
+nadou model list --scenario text2img --profile <profile> --no-interactive --json
+nadou model list --scenario image_ref --profile <profile> --no-interactive --json
+nadou model list --scenario multi_reference --profile <profile> --no-interactive --json
+nadou model list --scenario video_edit --profile <profile> --no-interactive --json
+nadou model list --scenario motion_control --profile <profile> --no-interactive --json
+```
+
+`--scenario` 与 `--type`、`--raw` 互斥。场景不存在时停止，不得退化到其他场景。
+
+## 查看单个模型（摘要/参数结构）
+
+`model get` 返回单个模型的摘要，`model schema` 返回该模型在某创作场景下可提交的
+参数视图（`defaults`/`enums`/`limits`），两者都带 `source`、`catalog_revision`、
+`fetched_at` 溯源字段，数据源始终是运行时 `task/configs`：
+
+```sh
+nadou model get vidu-q2 --profile <profile> --no-interactive --json
+nadou model schema vidu-q2 --profile <profile> --no-interactive --json
+```
+
+同一 `value` 可能出现在多个创作场景。
+未指定场景且存在多个时会返回 `scenarios[]` 供消歧，用 `--scenario` 选择：
+
+```sh
+nadou model schema <model-id> --scenario text2video --profile <profile> --no-interactive --json
+nadou model list --scenario text2audio --profile <profile> --no-interactive --json
+nadou model schema <model-id> --scenario audio2audio --profile <profile> --no-interactive --json
+nadou model schema <model-id> --scenario first_last_frame --profile <profile> --no-interactive --json
+```
+
+首尾帧模型的参数结构可能包含动态的 `frame_capabilities`：
+`onlyFirstFrame=false,onlyLastFrame=false` 支持仅首帧和首尾帧；
+`true,false` 仅支持首帧；`false,true` 支持仅首帧、首尾帧和仅尾帧。
+字段缺失或两个标记同时为 `true` 时，CLI 失败关闭，不根据模型名猜测能力。
+
+## 绑定默认模型
+
+把摘要返回的 `name` 绑定为默认模型：
+
+```sh
+nadou model use image <runtime-image-model-id> --profile <profile> --no-interactive --json
+nadou model use video <runtime-video-model-id> --profile <profile> --no-interactive --json
+```
+
+绑定只保存模型标识，不保存模型参数。每次快捷生成都会重新读取目录和该模型的 `default`；
+也可以在单次命令中覆盖：
+
+```sh
+nadou image "一只白色小猫" --model <runtime-image-model-id> --profile <profile> --dry-run --no-interactive --json
+```
+
+入口 Agent 将该预览的 `data.request` 保存后，按 [task-request.md](task-request.md)
+完成余额、同请求估价、费用确认和同请求单次提交；不能从模型示例直接跳过费用预检。
+
+不要把显示名称、供应商名称或旧环境中的值当作模型 `value`。

package/skills/nadou/commands/points.md

@@ -0,0 +1,43 @@
+# 积分
+
+查询当前账号在当前环境下的剩余积分（只读，不扣减、不需要确认）：
+
+```sh
+nadou points summary --profile <profile> --no-interactive --json
+```
+
+`points` 是顶层余额命令；不存在 `nadou canvas points`。Canvas 内的待生成费用必须在目标节点已存在、
+必要依赖边已建立并完成回读后，使用 `nadou canvas node estimate --canvas-id <canvas-id> --node-id <node-id>` 估算。
+后者是未来生成费用预览，不是当前余额、画布历史消耗或所有节点的默认汇总。
+
+输出为稳定响应封装，`data` 字段：
+
+- `balance.value`：可进行数值比较时为非负整数；不采用数值余额语义时为 `null`。
+- `balance.display`：面向用户的稳定展示；与 `value` 对应的十进制文本，或 `∞`。
+- 普通数值余额同时返回兼容字段 `remain_points`，以及服务端提供时的
+  `free_remain_points`、`recharge_remain_points`；Agent 必须优先读取 `balance`。
+- 当 `balance.value=null` 时，用户可读输出只显示“剩余积分：∞”；不返回没有真实数值语义的兼容余额字段和分类明细，不得把它改写为
+  `0`、任意大整数、`Infinity` 或本地额度上限。
+
+余额按当前激活空间自动结算（团队空间查团队钱包，个人空间查个人钱包），无需传参。展示策略同样
+以当前空间优先：团队空间遵循该团队的权威余额属性，个人账号属性不能覆盖团队；只有个人空间才采用
+个人账号的余额语义。切换空间后必须重新查询；策略无法确定时失败关闭。Agent 只读取公开的
+`balance.value/display`，不得探测、展示或解释形成该投影的内部账号/团队分类。该命令只反映服务端
+权威余额，不复制任何计价规则；单次任务的预计消耗请用 `nadou task estimate`，两者用途不同，不可互相替代。
+
+原子图片或视频费用预检时，先用高层命令预演得到唯一请求，再执行一次 `space current` 获取
+当前激活计费空间的权威身份，随后查询本页余额并对同一个请求执行 `task estimate`。本命令只返回余额，
+不返回空间 ID 或名称，Agent 不得据此猜测计费空间。向用户分别展示当前激活空间的计费范围和媒体
+交付目标：未指定目录时在确认前列出个人/目标空间的全部目录候选，等待用户选择；这不表示使用个人钱包计费；明确个人或团队
+目录时保留该目标。必要输入上传、本地下载、画布和媒体处理仍需
+分别披露，生成费用确认不授权后续空间写入。
+
+数值余额的 `balance.value - estimated_points` 只能标记为“按当前估价推算”的执行后余额；
+`balance.value=null` 时，当前余额和预计执行后余额都展示为 `∞`，只跳过客户端数值余额不足比较。
+两种余额都必须保留服务端估价、费用确认和任务级积分上限；估价不锁价、不预占积分，服务端最终校验
+仍是任务能否提交和执行的权威。余额策略无法权威确定时失败关闭，不得自行推断。
+
+本地定时计划创建时也会查询当前权威余额并对冻结请求估价，但这不锁价、不扣费。到期工作进程
+会在同一账号和计费空间下重新读取权威余额语义、重新估价，并要求结果不超过计划的 `max-points`
+才进入唯一提交。数值余额仍执行不足校验；非数值余额仍执行预算与服务端最终校验。账号、空间、
+余额策略或估价变化导致 `BLOCKED` 时不得自动改用其他空间、放宽上限或重提。