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

package/skills/nadou/guides/failure-cost-presentation.md

@@ -0,0 +1,42 @@
+# 失败阶段、费用状态与恢复动作
+
+本页规定如何解释 CLI 返回的失败信息、费用信息、结果状态和后续操作。后端公开任务响应目前只有
+任务/作业状态和 `reasonForIncompletion`，没有内部执行阶段、实际扣费或退款确认；不得把 CLI 投影
+描述成服务端结算事实。
+
+## 失败阶段
+
+| `failure.stage` | 可表达的事实 | 安全恢复 |
+| --- | --- | --- |
+| `PREFLIGHT` | 本地参数、身份、空间或请求预检失败，未发业务写请求 | 修正输入后重新预览 |
+| `ESTIMATE` | 余额/估价不可用、不明确或超上限，未提交任务 | 重新读取事实并重新确认 |
+| `SUBMIT` | 提交明确拒绝，或响应未知 | 明确拒绝可修正后重新确认；未知结果只核对请求证据，禁止重提 |
+| `REMOTE_EXECUTION` | 后端任务/作业进入非成功终态 | 保留任务/作业；需要重做时明确选择具体项并重新估价确认 |
+| `OUTPUT_ACCESS` | 已知任务的产物读取失败 | 只重试同一任务 ID 的 `outputs` 查询 |
+| `DOWNLOAD` | 已选择产物的本地下载失败 | 核对已完成文件后，只恢复同一任务/输出的下载 |
+| `DELIVERY` | 空间交付明确失败或写结果未知 | 明确失败按用户决定重新交付；未知结果禁止自动再写 |
+| `CANCELED` | 后端真实状态为 `CANCELED` | 结束；如需生成必须创建并确认新任务 |
+
+远端失败只能归入 `REMOTE_EXECUTION`，不得补造排队、模型加载、推理、内容审核或 OSS 上传等后端未返回的
+内部阶段。`failure.authoritative=true` 只说明该阶段有明确本地证据或直接后端状态，不代表原因之外的推断。
+
+## 费用状态
+
+`NOT_CHARGED/UNKNOWN/REFUND_EXPECTED/REFUND_ACCEPTED/NO_REFUND_EXPECTED/CHARGE_EXPECTED` 用于表达
+“已知、未知或预期”。当前任务终态没有服务端结算字段，因此默认 `cost.authoritative=false`；尤其不能因
+`FAILED`/`CANCELED` 推断已经退款，也不能因产物存在推断已经扣费。`REFUND_ACCEPTED` 只有未来服务端返回
+权威退款证据时才能使用。本地在发出任何业务写前拒绝时，可以把 `NOT_CHARGED` 标记为本地权威。
+
+## 汇总结果与逐项作业
+
+`SUCCESS/PARTIAL_SUCCESS/FAILED/CANCELED/OUTCOME_UNKNOWN` 是汇总，不覆盖后端九状态原值。存在多个作业时逐项
+保留作业 ID、状态、失败原因和产物数；优先使用作业原因，缺失时才使用任务原因。部分成功同时交付已有成功
+产物并列出失败项，不自动重做整批。
+
+## 后续操作
+
+- 已知任务 ID：只继续 `status/wait/outputs/download` 或显式交付。
+- 提交未返回任务 ID 且结果未知：保存请求 ID、请求摘要和确认摘要，执行人工或后端对账；不要重建任务。
+- 查询失败可重试查询，不能写成“重新提交”。
+- 用户要求重做时，明确选择任务、作业或镜头，重新生成唯一请求并完成余额、估价和费用确认。
+- 生成、下载和交付分别报告；任一阶段失败不得覆盖其他阶段已经确认的事实。

package/skills/nadou/guides/intent-templates.md

@@ -0,0 +1,53 @@
+# 创作意图与产品模板
+
+本页是 Nadou Skill 的统一入口模板。它只路由已确认能力，不把相近能力、其他平台能力或本地
+文件冒充为 Nadou 平台能力。任何图片、视频或音频生成仍须遵守根 Skill 的费用预检和单次提交规则。
+
+独立图片、视频和音频默认交付已核实的在线产物与用户确认的空间目录；本地下载只在用户明确要求时执行。
+用户未指定交付目录时，必须在估价和提交确认前读取真实目录候选，让用户在同一次确认中选择目录并确认费用；
+未选择目录时不得提交，不能先生成再补问目录，也不能默认使用个人空间根目录。
+
+| 用户意图或关键词 | 已确认的处理模板 | 当前边界与呈现方式 |
+| --- | --- | --- |
+| 文本 | 读取 [文本](../commands/text.md)，用 `nadou text` 生成并直接返回正文。 | 不创建项目、画布、节点或空间素材；不能说成已保存到素材库。 |
+| 图片、参考图、多图 | 无参考图用 `text2img`；明确以一张或多张图片参考时读取 [图片](../commands/image.md)，用 `image_ref`。 | 本地图片必须先显式上传；多张引用的上限、顺序和参数以实时参数结构为准。 |
+| 已有图片的打光、补光、改光照、调整光线 | 在画布中按图生图编辑处理：读取源图片节点，创建新的图片结果节点，使用 `IMG_REF`，建立源图 → 结果图，再按画布节点流程估价、确认、生成和等待。 | 原图不覆盖；新节点是编辑结果。提示词可以承载用户的打光诉求，但不能把它描述成未公开的独立打光接口。 |
+| 视频、首帧、尾帧、首尾帧 | 读取 [视频](../commands/video.md)；无参考图用 `text2video`，首尾帧只在用户明确提出时用 `first_last_frame`，并用 `--first-frame/--last-frame` 表达角色。 | 不以文件数量猜场景；三种组合按实时 `onlyFirstFrame/onlyLastFrame` 规则筛选模型；未知或矛盾目录失败关闭。 |
+| 视频、多参考图、短剧、影视、MV、广告 | 默认读取 [画布优先工作流](canvas-first-complex-workflow.md)：先在画布建立空节点、依赖边和工作流，补齐各节点提示词/模型配置，批量估价后按依赖波次执行；只有用户明确选择独立素材和本地线性后处理时才读取 [一键成片](../recipes/one-click-film.md)。 | 这不是平台时间线、发布或导出。模型或剪辑节点不支持时列出事实并等待选择，不能先单点生成再补挂画布、静默降级或宣称已成片导出。 |
+| 视频语义编辑、动作控制 | 读取 [高级视频](../commands/video-advanced.md)，使用 `video_edit` 或 `motion_control`。 | 必须使用对应角色的上传素材 URL；不把本地剪辑说成模型编辑。 |
+| 音频 | 读取 [音频](../commands/audio.md)。独立生成使用当前账号动态目录实际开放的 `nadou audio --scenario text2audio|audio2audio`；用户明确要求在既有画布音频节点内生成时，改走 `canvas node estimate → canvas node generate → canvas node wait`。 | 独立音频和画布音频是两条不同路由；配音、音色转换、音频编辑等未开放能力仍须停止，不得把本地音频处理或独立 `nadou audio` 冒充画布节点生成。 |
+| 素材、空间 | 读取 [素材](../commands/material.md) 或 [空间](../commands/space.md)，按用户的明确范围查询、上传、删除或交付。 | 不按素材名称猜身份；写操作结果未知时先对账。 |
+| 项目、文件夹、目录 | 产品所称“项目”按空间文件夹处理：读取 [空间](../commands/space.md) 发现个人或团队目录；用户明确要求新建目录时，可使用 `space directory create` 单次创建并按返回 ID 回读确认。产物可交付到用户确认的目录，并以画布承载多步骤创作。 | 已有文件夹可直接使用：携带该文件夹的 `group_id` 与 `directory_id` 可直接创建画布。目录创建结果未知时不得按名称猜测或自动重试；CLI 不接入工作台项目绑定、迁移或复制。 |
+| 画布、节点、分镜 | 读取 [画布](../commands/canvas.md) 和相应节点类型；明确画布 ID 后在该画布内读写节点和边。 | 分镜节点可表达结构，但其专有生成/编辑参数结构未公开；复杂画布语义不能猜测或伪造。 |
+| 本地剪辑 | 读取 [本地媒体](../commands/media.md)，仅执行 CLI 已提供的本地检查、字幕、拼接、规范化或合成。 | 不把本地产物解释为画布回填。 |
+| 画布剪辑/时间线合成/导出 | 读取 [画布媒体](../commands/canvas-media.md) 和 [画布依赖图](canvas-dependency-graph.md)，先核对每个 `源节点 -> clip` 输入边；网页展示若输入是 `{openId, assets}`，先用 `timeline initialize`（需审查时先 `timeline init`）生成完整工程 Timeline，再 `web-read`/`web-write`；组合式 CLI/后端导出先使用 `timeline export-write → export-read`，再执行 `backend-submit`；后者会由代码按条件自动补齐网页 `node-data`，并返回同步动作和状态/回填证据。 | `validate` 只是离线补全，不能替代写入和回读；网页 `web-write` 不接受缺少工程信封的通用 Timeline，两条路径不暴露可混选的持久化参数，隐藏的通用 `timeline write/read` 在本地阻断；导出前只修复明确缺失、全空或与请求语义一致的 `bare-timeline`，提交收据终态后再次核对并按需恢复 Web 信封；非空不一致、收据身份/状态不明、回读失败或无主轨时停止，结果未知时不做后写。只有当前环境提供组合式导出契约时执行；否则报告具体能力阻塞，不切换本地路径冒充平台结果。 |
+| 定时任务 | 读取 [定时](../commands/schedule.md)：图片/视频可选本地或服务端模式，独立 `TEXT2TEXT` 仅限本地模式，单画布节点仅限服务端模式；创建后以原任务 ID 观察 `SCHEDULED` 等真实状态。已知服务端任务 ID 可使用 `task reschedule/cancel-scheduled`；独立任务仅支持无上下文改期，取消仍需上下文。 | 默认关闭且模式不自动切换；服务端仅支持已知任务 ID 的取消/改期，任务列表和 DAG 未批准，本地管理不能冒充服务端管理。 |
+| 积分 | 读取 [积分](../commands/points.md)；图片、视频和音频先取得余额和服务端估价。 | 估价不锁价，用户初始创作意图不是扣费确认。 |
+| 模型 | 读取 [模型](../commands/model.md)，用 `model list` 和 `model schema` 获取当前账号的事实。 | 不写死、猜测或跨账号复用模型和参数。 |
+| 独立任务导出/下载 | 对任务产物先使用 `task outputs` 读取可信在线结果，并按提交前确认的目标执行空间交付；只有用户明确要求本地文件时才使用 `task download` / `task download-batch`，需要本地后处理时再读取 `nadou media`。 | 在线结果、空间交付和显式本地下载分别报告；不把独立任务结果解释为画布成片或画布回填。 |
+
+### 画布视频模式选择
+
+当用户说“使用角色图、场景图或风格图作为参考”时，Agent 必须在画布视频节点上显式设置 `multi_reference`；只有用户明确说首帧、尾帧或首尾帧时才设置 `first_last_frame`。不能依据参考图片数量推断模式，也不能只因为模型名是 `minimax-h3` 就选择某个模式。
+
+推荐顺序：创建或读取视频节点 → `canvas node set-scenario` → 回读 `data.taskType` → estimate → generate。多参考对应 `MULTI_REF_IMG2VIDEO`，首尾帧对应 `IMG2VIDEO`。
+
+## 跨回合恢复与部分成功
+
+用户要继续此前的任务时，先索取或确认原 `task_id`（涉及画布时还需要原 `canvas_id`）。随后只用
+该 ID 执行 `task status`、`task wait`、`task outputs`，以及在需要时的显式交付；不要重新生成。
+
+输出至少区分以下状态：
+
+| 结果 | 必须说明 |
+| --- | --- |
+| 全部成功 | 原任务 ID、每个可信产物及其交付状态。 |
+| 部分成功 | 哪些作业/产物已生成或已交付，哪些失败、缺失或仍未知；不把整体称为完全成功。 |
+| 等待超时或网络中断 | 已观察到的状态、原任务 ID 和恢复命令；不重新提交。 |
+| 不支持或契约未确认 | 缺失的能力/契约及不能执行的原因；不模拟结果。 |
+
+`task events` 只表示本次 CLI 轮询观察到的状态变化，不是服务端事件订阅或可恢复历史。完整的
+轮询、终态和单次写入规则以 [任务](../commands/task.md) 为准。
+
+结束时读取 [产物呈现](artifact-presentation.md)，按真实产物、空间交付回读和本地下载结果生成
+不重复的最终回复；不得自行拼接链接或路径。

package/skills/nadou/guides/model-rules.md

@@ -0,0 +1,7 @@
+# 条件模型参数规则
+
+模型目录提供基础 Schema；CLI 会按模型、场景、首尾帧角色、参数和已知参考素材事实
+计算有效请求。`model schema` 中的 `conditional_rules` 只用于解释规则，不替代动态
+目录和服务端校验。远程素材事实未知时不伪造元数据；显式指定受影响参数会在提交前
+失败关闭。URL 后缀不能证明媒体类型、时长或音轨；两个无角色图片也不能静默解释为
+首尾帧。估价、dry-run、提交和画布节点生成必须复用同一份有效参数。

package/skills/nadou/guides/utf8-input-safety.md

@@ -0,0 +1,13 @@
+# UTF-8 输入安全
+
+画布节点、`Graph` 变更、`Timeline` 和任务 JSON 必须使用 UTF-8 字节。Windows PowerShell 不要把包含中文的 `here-string` 直接通过管道传给 `nadou --stdin`，因为命令解释器可能在 CLI 收到数据前把中文替换为 `?`。
+
+优先使用 UTF-8 文件：
+
+```powershell
+$utf8 = New-Object System.Text.UTF8Encoding($false)
+[System.IO.File]::WriteAllText("$pwd\request.json", $json, $utf8)
+nadou canvas node create --body-file "$pwd\request.json" --json
+```
+
+CLI 会在 JSON 解析和后端请求前校验 UTF-8，并兼容 UTF-8 BOM。校验失败时不会发出写请求。合法问号不会被当成乱码；如果上游命令解释器已经把中文转换成 `?`，CLI 无法恢复原文，因此画布写入应启用 `--return-snapshot --verify-text` 做写后回读校验。

package/skills/nadou/node-types/audio.md

@@ -0,0 +1,66 @@
+# 音频节点
+
+## 用途
+
+表示音频素材。
+
+## JSON 字段
+
+完整创建、读取和修改结构见 [JSON 结构与读写边界](json-contract.md)。创建时确认可写的 `data` 字段为
+`label`。既有音频节点支持下文的画布音频生成路由；模型与任务参数结构必须从当前环境动态读取，
+运行时媒体状态和回调结果只从 Graph 读取。
+
+### 字段表（已确认/已观察）
+
+| 字段 | 类型 | 位置 | 状态与用法 |
+| --- | --- | --- | --- |
+| `label` | string | `data.label` | **已确认可写**；创建时必填 |
+| 媒体、任务或产物字段 | 未公开 | 实时 Graph `data` | **未形成公开类型参数结构**；先读取，回调管理的字段不得手工回写 |
+
+## 最小可复制示例
+
+```sh
+nadou canvas node create --canvas-id <canvas-id> --stdin \
+  --auto-layout-only --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"type":"audio","data":{"label":"氛围音频"}}
+EOF
+nadou canvas get --canvas-id <canvas-id> --node-id <created-audio-node-id> --profile <profile> --json
+```
+
+## 已确认操作
+
+- 使用通用 Graph 命令创建、读取、更新或删除。
+- 创建前可读取最小本地模板：`nadou canvas node template --type audio --json`。
+- 创建时省略 `id` 让 CLI 生成，补全 `type="audio"` 和非空 `data.label`，再通过 `canvas node create` 提交。
+
+## 编辑与结果边界
+
+结构位置走 `rootPatch`，业务数据走 `dataPatch`。运行态回填以实时 Graph 和公开契约为准；不要写
+`url`、元数据、任务或节点状态等回调字段。
+
+## 本地音频自定义节点（`materialId` 契约）
+
+本地音频同样先用现有 `material upload --file <path> --canvas-id <canvas-id>` 上传；专用创建仅接受正整数
+`materialId`，不接受 URL、元数据或任务状态。默认尺寸为 `462 × 260`；`width`/`height` 必须同时省略或同时为
+有限正数。不传 `position` 时使用画布原点并避碰。`canvas node create-media` 不接受 `sourceNodeId`，也不自动连线；用户明确资产关系时按
+[画布依赖图](../guides/canvas-dependency-graph.md) 另用 Graph 写入。
+
+先用 `canvas node new-id --json` 取得节点 ID，再使用
+`canvas node create-media --node-id <generated-node-id> --material-id <material-id>` 发送仅包含 `materialId` 的请求，并用
+`canvas node mutation-status` 对账；URL、元数据、媒体类型和任务状态由后端维护。目标环境若返回
+`B00001/INVALID_ARGUMENT`，保留素材和原变更，不重新上传或盲目重发。该本地素材路径与下方“AI 音频生成”是两项独立能力。
+
+## 运行时边界
+
+画布音频生成只覆盖 `estimate`、`generate` 和 `wait`。模型、任务参数结构、节点输入输出与回调
+事实均以当前 Nadou 环境的动态目录和实时 Graph 为准；不要根据其他产品的音频节点行为扩展技术契约。
+
+## 画布音频生成
+
+既有 `audio` 节点支持 `canvas node estimate`、`canvas node generate` 和 `canvas node wait`。节点配置必须来自当前账号的动态模型与参数目录，并包含非空提示词。
+
+- 没有明确的音频输入边：使用 `TEXT2AUDIO`，并将 `params.image` 设为空数组
+- 只有一条明确的音频输入边：使用 `AUDIO2AUDIO`；源节点必须是音频节点，其可信 HTTPS 产物 URL 写入 `params.image`
+- 存在图片/视频依赖、缺少产物、来源不明确或 URL 不可信时，在提交前失败
+- 复用现有的估价、确认和单次提交任务契约；结果未知时只观察和恢复，不自动重新提交
+- 回调管理的 URL、元数据、`taskStatus` 和 `nodeStatus` 对 CLI 只读；此路由不创建节点或边，也不执行独立空间交付

package/skills/nadou/node-types/clip.md

@@ -0,0 +1,43 @@
+# Clip 节点
+
+## 用途
+
+表达视频片段或剪辑数据。
+
+## JSON 字段
+
+完整创建、读取和修改结构见 [JSON 结构与读写边界](json-contract.md)。创建时确认可写的 `data` 字段为 `label`；片段专有业务字段以实时 `Graph` 读取为准，不假设存在可写参数结构。
+
+### 字段表（已确认/已观察）
+
+| 字段 | 类型 | 位置 | 状态与用法 |
+| --- | --- | --- | --- |
+| `label` | string | `data.label` | **已确认可写**；创建时必填 |
+| 剪辑、时间线或合成数据 | 未公开 | 实时 `Graph` 的 `data` | **未形成公开类型参数结构**；不得根据未公开字段或合成语义猜测写入 |
+
+## 最小可复制示例
+
+```sh
+nadou canvas node create --canvas-id <canvas-id> --stdin \
+  --auto-layout-only --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"type":"clip","data":{"label":"开场片段"}}
+EOF
+nadou canvas get --canvas-id <canvas-id> --node-id <created-clip-node-id> --profile <profile> --json
+```
+
+## 已确认操作
+
+- 当前 CLI 可将其作为已知节点类型创建或读取。
+- 创建前可读取最小本地模板：`nadou canvas node template --type clip --json`。
+- 创建时省略 ID 让 CLI 生成并保存 `created_node_ids`，补全类型与标签后提交明确结构。
+
+## 编辑与结果边界
+
+不要伪造 URL、`metadata` 或任务状态。任何已有片段的修改都应先读取实时 `Graph`；不要把未公开的时间线字段或
+`clip` 类型专属连接 `handle`/数量规则当作已确认能力。对于用户明确的资产输入关系，仍按
+[画布依赖图](../guides/canvas-dependency-graph.md) 建立通用 `source -> clip` 边；CLI 不会按类型自动补边。
+
+## 待确认
+
+片段专属业务参数结构、时间线字段和独立生成/合成能力仍以 `commands/canvas-media.md` 的已部署契约为准；
+类型专属连接 `handle`、数量和顺序规则尚未确认。通用资产依赖边不属于待确认项。

package/skills/nadou/node-types/director3d.md

@@ -0,0 +1,41 @@
+# Director3D 节点
+
+## 用途
+
+表达 3D 导演或空间编排信息。
+
+## JSON 字段
+
+完整创建、读取和修改结构见 [JSON 结构与读写边界](json-contract.md)。创建时确认可写的 `data` 字段为 `label`；3D 导演专有业务字段以实时 `Graph` 读取为准，不假设存在可写参数结构。
+
+### 字段表（已确认/已观察）
+
+| 字段 | 类型 | 位置 | 状态与用法 |
+| --- | --- | --- | --- |
+| `label` | string | `data.label` | **已确认可写**；创建时必填 |
+| 3D 导演专有数据 | 未公开 | 实时 `Graph` 的 `data` | **未形成公开类型参数结构**；不能据此推断存在独立 3D 生成或编辑字段 |
+
+## 最小可复制示例
+
+```sh
+nadou canvas node create --canvas-id <canvas-id> --stdin \
+  --auto-layout-only --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"type":"director3d","data":{"label":"3D 场景规划"}}
+EOF
+nadou canvas get --canvas-id <canvas-id> --node-id <created-director3d-node-id> --profile <profile> --json
+```
+
+## 已确认操作
+
+- 当前 CLI 可将其作为已知节点类型创建或读取。
+- 创建前可读取最小本地模板：`nadou canvas node template --type director3d --json`。
+- 创建时省略 ID 让 CLI 生成并保存 `created_node_ids`，补全类型与标签后提交明确结构。
+
+## 编辑与结果边界
+
+不要写任务回填管辖字段，也不要绕开 `nadou` CLI 补全本类型能力。
+
+## 待确认
+
+类型专属字段、生成能力和连接 `handle`/数量规则均未确认。它不能被视为已经具备独立 3D 生成或编辑能力；
+用户明确的资产从属关系仍按 [画布依赖图](../guides/canvas-dependency-graph.md) 建立通用依赖边。

package/skills/nadou/node-types/group.md

@@ -0,0 +1,59 @@
+# Group 节点
+
+## 用途
+
+组织子节点和布局；它不是普通生成任务的结果目标。
+
+## JSON 字段
+
+完整创建、读取和修改结构见 [JSON 结构与读写边界](json-contract.md)。分组自身确认可写的 `data` 字段为 `label`；子节点通过创建请求中的 `parentNode` 关联到分组。需要自动网格落位时，子节点使用 `placement`，不能同时传 `position`。
+
+### 字段表（已确认/已观察）
+
+| 字段 | 类型 | 位置 | 状态与用法 |
+| --- | --- | --- | --- |
+| `label` | string | `group` 的 `data.label` | **已确认可写**；创建时必填 |
+| `parentNode` | string | 子节点创建请求根字段 | **已确认可写**；指向已创建的 `group`，不属于 `group` 自身的 `data` |
+| `placement` | object | 子节点创建请求根字段 | **已确认可写**；组内自动布局输入；与 `position` 二选一 |
+
+## 最小可复制示例
+
+```sh
+nadou canvas node create --canvas-id <canvas-id> --stdin \
+  --auto-layout-only --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"type":"group","data":{"label":"创作规划"}}
+EOF
+nadou canvas get --canvas-id <canvas-id> --node-id <created-group-node-id> --profile <profile> --json
+```
+
+## 已确认操作
+
+- 使用通用 `Graph` 命令创建、读取、修改或删除。
+- `parentNode` 可表达子节点的分组关系；需要组内自动布局时按 `commands/canvas.md` 的
+  `IN_GROUP_AUTO` / `SECTION_GRID` 约定提供完整输入。
+- 删除 `group` 可能递归删除后代，必须显式使用 `canvas node delete ... --yes`。
+
+## 已有节点打组时的边界
+
+根节点的 `position` 是画布坐标；写入 `parentNode` 后，子节点的 `position` 是相对 `group`
+的坐标。给已有节点打组时，必须先读取实时 `Graph`，按所有所选节点的
+`x/y + width/height` 计算 `group` 的联合边界，然后在同一批变更中同时写入：
+
+```json
+{"type":"PATCH_NODE","nodeId":"child-id","rootPatch":{"parentNode":"group-id","position":{"x":37.5,"y":382}}}
+```
+
+上例的相对坐标等于 `childAbsolute - groupPosition`；不能只写 `parentNode`，也不能把原始根
+坐标直接复制到 `rootPatch.position`。已有节点不使用 `IN_GROUP_AUTO`，因为那会把“保持原位置”
+和“交给服务端重排”混为一谈。写后必须回读并验证每个子节点的绝对右下边界仍在 `group` 内；
+位置或尺寸缺失时停止，不凭名称或节点类型猜测边界。
+
+## 编辑与结果边界
+
+布局或根结构修改使用 `rootPatch`，业务数据修改使用 `dataPatch`。服务端仍裁决 `placement` 与完整布局语义；
+不要把 `group` 作为 `canvas node generate` 的普通任务目标，也不要写回填字段。
+
+## 待确认
+
+分组专属参数结构、全部子类型限制和类型专属连接规则尚未由公开契约完整定义；`parentNode` 只表达布局层级。
+用户明确的资产依赖仍按 [画布依赖图](../guides/canvas-dependency-graph.md) 建立 `source -> target`，不能用分组关系代替。

package/skills/nadou/node-types/image.md

@@ -0,0 +1,137 @@
+# 图片节点
+
+## 来源与提示词语义
+
+`imageNodeOrigin` 表示来源，不是界面开关。`generated` 只属于 `canvas node generate` 生命周期；即使上传或自定义节点的素材旁保存了提示词，它仍是上传节点。不得通过普通 Graph 更新修改来源、自定义标记、回调字段、URL 或元数据，以暴露生成节点的提示词界面。
+
+## 用途
+
+表示图片素材或图片生成结果。
+
+## JSON 字段
+
+完整创建、读取和修改结构见 [JSON 结构与读写边界](json-contract.md)。创建时确认可写的 `data` 字段为 `label`、生成语义配置（`prompt`、`modelName`、`modelType`、`taskType`、`modelParams`），以及经过公网 URL 校验的初始 `url`；任务生成后的 `url`、`nodeStatus`、`taskStatus` 由回调写入，只读观察。
+
+### 字段表（已确认/已观察）
+
+下表中的运行时字段只会在 `canvas get --raw --json` 的节点 `data` 中按实际状态出现；它们不是创建请求的模板。
+
+| 字段 | 类型 | 具体含义 | 可否写入 |
+| --- | --- | --- | --- |
+| `label` | string | 节点在画布上的基础标签 | **可以**；创建时必填，后续通过 `dataPatch` 修改 |
+| `prompt` | string | 该生成节点准备提交的提示词 | **可以**；新建生成节点时先写入，`canvas node generate` 会校验它与请求一致 |
+| `modelName` | string | 该生成节点准备使用的真实模型 ID | **可以**；来自当前模型目录，不按展示名猜测 |
+| `modelType` | string | 模型类型，例如 `IMAGE` | **可以**；应与请求一致 |
+| `taskType` | string | 任务类型，例如 `TEXT2IMG` / `IMG_REF` | **可以**；图生图、风格化、改绘必须使用与参考输入一致的任务类型 |
+| `modelParams` | object | 模型选择锚点与当前模型参数结构允许的完整动态参数 | **可以**；`model` 必须等于 `modelName`，其余字段来自当前参数结构，后续提交请求必须一致 |
+| `url` | string | 图片创建时的初始已上传素材地址，或回调写入的当前图片产物地址；是否出现取决于创建输入或任务是否产生可用图片 | **仅创建时可以**；仅 `type=image` 的 `CREATE_NODE` 可传（视频同类例外见 [video.md](video.md)），且必须是通过公网校验的 HTTP(S) 地址。`node patch` / `PATCH_NODE` 一律禁止改 URL；需下载任务产物时使用原任务的产物能力 |
+| `nodeStatus` | string | 画布节点自身的运行/展示状态 | **通用更新不可以**；`canvas node generate` 仅在任务提交成功后由受控运行态补丁写入 `taskRunning` |
+| `taskStatus` | string | 与该节点关联的生成任务状态 | **通用更新不可以**；受控补丁写入提交响应的实际状态，终态仍由回调管理 |
+| `aiTaskId` | string 或 number | NadouAI 任务标识，用于关联原任务和恢复证据 | **通用更新不可以**；受控补丁使用本次提交返回的任务 ID |
+| `jobId` | string 或 number | 任务执行作业标识，用于诊断和关联 | **通用更新不可以**；有返回值时由受控补丁写入，缺失时清掉旧值 |
+| `metadata` | object | 回调附带的产物元数据；内部键随任务和产物变化 | **通用更新不可以**；运行态受控补丁不携带元数据，终态由回调管理 |
+| `submitTaskParams` | object | 本次任务提交时记录的参数摘要 | **通用更新不可以**；任务提交成功后由受控补丁写入模型名、`IMAGE` 类型和任务类型 |
+
+生成请求中的字段由当前模型决定：先运行 `nadou model schema <model-id> --json`，以返回的
+`schema.defaults` 为动态参数基础，并额外写入 `"model":"<model-id>"`。节点的
+`modelParams.model` 与 `modelName` 必须完全一致。默认 `canvas node generate` 会从节点配置和入边依赖自动构建请求；普通 Agent 流程不要构造请求文件。
+
+生成节点示例：
+
+```json
+{
+  "id": "<generated-node-id>",
+  "type": "image",
+  "data": {
+    "label": "概念图",
+    "prompt": "<生成提示词>",
+    "modelName": "<model-id>",
+    "modelType": "IMAGE",
+    "taskType": "TEXT2IMG",
+    "modelParams": {
+      "model": "<model-id>",
+      "<schema-default-key>": "<schema-default-value>"
+    }
+  }
+}
+```
+
+## 最小可复制示例
+
+```sh
+nadou canvas node create --canvas-id <canvas-id> --stdin \
+  --auto-layout-only --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"type":"image","data":{"label":"概念图"}}
+EOF
+```
+
+本地文件先上传，再用上传响应的 `data.url` 创建图片节点；这个 URL 是初始素材，不是回调结果。
+创建时必须读取上传响应的 `data.metadata.width` / `data.metadata.height`：根级 `width`/`height`
+按短边 `260` 保持比例换算显示尺寸（再各加 `2` 边框）。`data.metadata` 除像素宽高外，
+还必须按允许列表抄入同次上传返回的多档预览 URL 与素材身份（有值才写），供画布缩略展示与存空间；
+禁止臆造 `640×360` 等与素材无关的固定尺寸。完整规则见
+[json-contract.md](json-contract.md)。
+
+```sh
+nadou material upload --file ./reference.png --profile <profile> --json
+# 假设上传返回 metadata.width=2560、metadata.height=1440 → 显示尺寸 464×262
+# 同时抄入 thumbnailUrl / mediumThumbnailUrl / previewUrl / assetId / assetName（有值才写）
+nadou canvas node create --canvas-id <canvas-id> --stdin \
+  --auto-layout-only --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"type":"image","width":464,"height":262,"data":{"label":"本地参考图","url":"<upload-data.url>","metadata":{"width":2560,"height":1440,"assetId":"<upload-data.material_id>","assetName":"<upload-data.file_name>","thumbnailUrl":"<upload-metadata.thumbnailUrl>","mediumThumbnailUrl":"<upload-metadata.mediumThumbnailUrl>","previewUrl":"<upload-metadata.previewUrl>"}}}
+EOF
+```
+
+## 已确认操作
+
+- 使用通用 Graph 命令创建、读取、更新或删除。
+- 创建前可读取最小本地模板：`nadou canvas node template --type image --json`。
+- 对**既有且明确指定**的图片节点，可使用 `canvas node generate` 提交一次任务，并用
+  `canvas node wait --task-id <task-id>` 只读观察任务并确认回调。
+- 对画布中既有图片做图生图、风格化、改绘或多模型对比时，先为每个目标模型创建新的图片结果节点，
+  在节点 `data` 写入本次提示词和模型配置，并创建从参考图片节点到结果节点的边，再对结果节点执行 `canvas node generate`。不得先用独立任务生成图片，
+  再把产物上传或创建为普通素材节点来替代画布节点生成。
+- “打光、补光、改光照、调整光线”属于上述已有图片的图生图编辑，不是原图节点的就地修改：新建结果节点，写入用户的打光诉求和当前 `IMG_REF` 配置，建立源图片节点 → 结果节点的边，再按费用确认和回调流程生成。原图保持不变，结果节点承载新的图片产物。
+
+生成前先读取本次可用模型，并把提示词和模型配置写入目标节点：
+
+```sh
+nadou model list --type image --profile <profile> --json
+nadou model schema <model-id> --profile <profile> --json
+nadou canvas node generate --canvas-id <canvas-id> --node-id <image-node-id> \
+  --profile <profile> --json
+```
+
+本地图片需要保持为上传型画布参考节点时，先执行 `nadou material upload`，再执行：
+
+```sh
+nadou canvas node create-image-upload \
+  --canvas-id <canvas-id> --material-id <material-id> \
+  --url <upload-data.url> --profile <profile> --json
+```
+
+该命令会在 `CREATE_NODE` 阶段写入 `isCustomNode=true` 和 `imageNodeOrigin=upload`，使 Web UI
+把节点显示为不带生成面板的上传节点。创建后不得修改这些来源字段，也不得通过 Graph 命令隐式上传本地文件。
+
+对于已经在个人或团队空间中的图片，不要把目录默认结果中的 `material_url` 当作完整预览元数据。
+先执行 `nadou space directory contents --include-metadata --type image`，将同一条目返回的安全
+`metadata`（尤其是 `width`、`height`、`thumbnail_url`、`medium_thumbnail_url`）按字段名转换为
+`create-image-upload --metadata` 所需的 camelCase JSON，再创建节点。默认目录查询不输出 metadata；
+不能调用未批准的元数据接口、重新上传同一素材、或自行拼接缩略图 URL。
+
+模型参数以该次 `model schema` 输出为准；输入素材来自指向目标节点的入边源节点 URL。参考/输入关系的边按
+[画布依赖图](../guides/canvas-dependency-graph.md) 由 Agent 显式创建，CLI 不因 URL 或节点类型自动补边。
+不要手写通用任务外壳，也不要把其他产品的图片字段复制进节点请求体。
+
+## 编辑与结果边界
+
+受限运行上下文在显式聚焦时可返回提示词、模型、任务/作业/素材、状态和产物可用性。
+任务产物 URL、完整元数据和终态状态由回调写入；普通 Graph 更新不得伪造这些值。`canvas node generate`
+在提交成功后会额外写入 `isGenerating=true`、`imageNodeOrigin=generated`、`taskCreateTime` 和
+`taskEstimatedTime`，供 Web 展示运行中预览和历史入口；这些字段只能由该受控流程产生。
+图片创建时的初始 `url` 与上传素材允许列表中的元数据是前述窄例外：只允许从同次 `material upload`
+响应抄入已列键；其中有效的 `thumbnailUrl`、`mediumThumbnailUrl`、`previewUrl` 会同时作为初始预览字段保留，不能扩展为任意元数据回写或事后臆造补丁。
+
+## 待确认
+
+图片节点完整业务参数结构，以及除已验证场景外的连线约束仍待公开契约确认。

package/skills/nadou/node-types/index.md

@@ -0,0 +1,77 @@
+# 画布节点类型索引
+
+仅在用户明确要求在画布中创建、读取或编辑节点时阅读本目录。执行
+`nadou canvas get --canvas-id <canvas-id>`；在当前 Agent 会话中保留用户明确给出的画布 ID
+与选中的节点 ID，每次画布命令都显式传入，不要按标签猜节点。
+
+先阅读 [节点 JSON 公共结构与读写边界](json-contract.md)：其中区分创建请求、实时 Graph 读取和节点修改，明确回调维护字段不能回写。各类型页再说明该类型已确认的 `data` 字段和运行时字段。
+
+## 先选能力，再选类型
+
+1. 先读取实时结构并确认目标画布/节点 ID；创建时再读取该类型的最小本地模板：
+
+   ```sh
+   nadou canvas node template --type <type> --json
+   ```
+
+2. 使用 `canvas node create --canvas-id <canvas-id> --stdin`（内嵌文档）向显式指定的画布提交明确的节点结构；
+   新节点省略 JSON `id`，由 CLI 生成 Web 兼容 ID，并保存响应 `created_node_ids`；仅大批量或需留盘复现时
+   改用 `--body-file`。模板只保证本地最小形状，不是完整后端业务参数结构。
+3. 既有文本、图片、视频节点均可使用已确认的生成路径：先通过 `model list` / `model schema`
+   选择模型和场景，把提示词和模型配置写入目标节点；只要用户目标中存在参考、输入、分段或合成的资产从属关系，
+   由 Agent 为每条关系创建必要依赖边，最后运行 `canvas node generate`。CLI 默认从节点和入边依赖派生请求，任务结果由回调写入节点。
+4. 读取或编辑节点使用 `canvas get` 和 `canvas node patch`。直接更新
+   的请求体使用 `id`、`rootPatch`、`dataPatch`；不要把 Graph 操作的 `nodeId` 误写到顶层。
+
+## 能力矩阵
+
+“结构编辑”仅指已确认的通用 Graph 创建、读取、更新、删除能力；不等于类型专属字段、连线语义或生成能力已经确认。
+
+| 类型 | 结构编辑 | 已确认生成/等待 | 本地辅助 | 类型说明 |
+| --- | --- | --- | --- | --- |
+| 文本 `text` | 创建、读取、更新、删除 | `node generate` + `node wait`（`TEXT2TEXT`/`IMG2TEXT`） | `node template --type text` | [text.md](text.md) |
+| 图片 `image` | 创建、读取、更新、删除 | `node generate` + `node wait` | `node template --type image` | [image.md](image.md) |
+| 视频 `video` | 创建、读取、更新、删除 | `node generate` + `node wait` | 模板、`create-video`、`set-ratio` | [video.md](video.md) |
+| 音频 `audio` | 创建、读取、更新、删除 | `node generate` + `node wait` | `node template --type audio` | [audio.md](audio.md) |
+| 3D 资产 `model3d` | 创建、读取、更新、删除 | `node generate` + `node wait`（`TEXT23D`/`IMG23D`/`MULTI23D`） | `node template --type model3d` | [model3d.md](model3d.md) |
+| 分组 `group` | 创建、读取、更新、删除 | 无 | 删除必须 `--yes` | [group.md](group.md) |
+| 分镜 `storyboard` | 创建、读取 | 未确认 | `node template --type storyboard` | [storyboard.md](storyboard.md) |
+| 片段 `clip` | 创建、读取 | 未确认 | `node template --type clip` | [clip.md](clip.md) |
+| 3D 导演 `director3d` | 创建、读取 | 未确认 | `node template --type director3d` | [director3d.md](director3d.md) |
+
+## 公共约定
+
+| 字段或概念 | 已确认含义 |
+| --- | --- |
+| `id`、`type`、`data.label` | Graph 节点的最小公共信息；`node create` 输入可省略 `id` 由 CLI 生成，批量 Graph 用 `node new-id` 预生成；既有 ID 原样保留 |
+| text 节点的 `data.text` / `data.prompt` | `label` 仅作短标题；正文写入 `text`，关联生成提示词写入 `prompt`，没有提示词时传空字符串 |
+| `data.prompt` / `data.modelName` / `data.modelType` / `data.taskType` / `data.modelParams` | 文本/image/video/audio/model3d 生成节点的受控语义配置；文本历史节点可只保存 `prompt` 与 `modelParams.model`，提交时由 CLI 补齐 Canvas 路由字段 |
+| `position` / `placement` | 二选一的布局输入；根级创建省略时 CLI 注入 `CANVAS_ORIGIN`，带同批依赖边的新根节点使用 `RIGHT_OF_NODE`，带 `parentNode` 的新子节点使用 `IN_GROUP_AUTO`；均带 `avoidCollision=true` |
+| `parentNode` | 可选的分组关系；分组删除会递归影响后代 |
+| `rootPatch` / `dataPatch` | 前者修改节点根结构，后者浅合并 `data`；修改嵌套对象前先读取并保留完整同级对象 |
+| Graph 写 | 显式传入当前会话的 `--canvas-id` 和变更 ID；每次命令只发送一次；短 JSON 用 `--stdin`，大型请求载荷才用 `--body-file` |
+| 任务生成 | 目标节点必须已存在并保存生成配置，再通过 `canvas node generate` 提交任务；默认请求由 CLI 从节点和入边依赖派生 |
+| 回调字段 | `nodeStatus`、`taskStatus`、完整元数据和产物列表由后端任务回填，不能作为普通更新写入；图片/视频在创建时可提供经过公网校验的初始 `data.url`，但该节点只表示上传/自定义输入，不得同时携带提示词、模型/任务配置或生成来源标记，也不得作为依赖边 `target`；同次 `material upload` 可按允许列表写入显示尺寸与媒体 `metadata`（像素宽高、多档预览/封面 URL、`assetId`/`assetName`，视频另含 `duration`/`fps`/`firstFrameUrl` 等），`PATCH` 仍禁止改 URL |
+
+连接的类型专属 `handle`、数量上限、顺序约束和其他业务字段并未由当前公开契约完整定义；这不影响通用资产依赖规则。
+用户目标或产品规则已经明确资产从属关系时，Agent 必须按 [画布依赖图](../guides/canvas-dependency-graph.md) 显式建边。
+除此之外未在本目录明确说明的字段或连线规则均为**待确认**，不得由 Agent 猜测，也不得仅凭节点类型、标签或位置猜测。
+
+## 创建、修改与读取：字段落点速查
+
+这张表说明 Nadou 已确认的公共字段落点。Nadou 不把模型参数和节点 `data` 合成一个静态参数结构：生成参数通过模型参数结构和任务请求体提交，节点属性通过创建或更新操作的 `data` 或根结构提交。
+
+| 目的 | 写入或读取位置 | 已确认字段 / 规则 |
+| --- | --- | --- |
+| 创建节点 | 创建请求体根字段 | `type`、`data.label` 必填；单节点 `node create` 省略 `id` 由 CLI 生成，批量 Graph 的 `id` 先用 `node new-id` 获取；文本节点还要写入正文 `data.text` 和 `data.prompt`（无提示词时为空字符串）；图片/视频生成节点还要在 `data` 中写入提示词和模型配置；可选 `position` 或 `placement`（二选一）、成对有限正数 `width`/`height`、`zIndex`、`parentNode`、`anchorNodeId`；根级节点不传位置时 CLI 注入 `CANVAS_ORIGIN`，依赖目标使用 `RIGHT_OF_NODE`，新建 Group 子节点使用 `IN_GROUP_AUTO`；Graph 创建拒绝 `extent`；仅图片/视频上传/自定义节点可提供经过公网校验的初始 `data.url`，且不得与生成配置混写 |
+| 修改结构 | `rootPatch` | 位置、尺寸、层级等根结构；修改前先读取 |
+| 修改节点属性 | `dataPatch` | 浅合并 `data`；只写当前类型页标为“已确认可写”的字段；嵌套对象必须先读取并完整保留同级字段 |
+| 提交生成 | `canvas node generate` | 先查 `model schema <model-id>`；默认由 CLI 从目标节点提示词、模型配置和入边依赖 URL 派生图片、视频、音频或 3D 请求；普通 Agent 不构造请求文件 |
+| 读取节点状态 | `canvas get --raw --json` 或 `canvas get --node-id <id> --json` | Graph 输出是运行时投影；任务、产物与回调字段只能读取，不能回写 |
+
+创建请求使用 `parentNode`、`zIndex` 等 `camelCase` 字段；`canvas get --raw --json` 的稳定输出使用 `parent_node`、`z_index` 等 `snake_case` 字段。通用 JSON 示例和 `PATCH` 字段名见 [json-contract.md](json-contract.md)。
+
+每个类型页都在“最小可复制示例”中附有其紧邻字段说明的创建与读取命令；无需再读取独立案例目录。
+## 画布音频生成
+
+既有 `audio` 节点在没有输入边时使用 `TEXT2AUDIO`，在有一条明确的音频输入边时使用 `AUDIO2AUDIO`。两条路径都会动态发现模型和参数结构，执行估价与确认，只提交一次，并通过 `canvas node wait` 观察回调。节点创建、边写入和空间交付仍是相互独立的操作。