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

package/skills/nadou/node-types/json-contract.md

@@ -0,0 +1,275 @@
+# 画布节点 JSON 公共结构与读写边界
+
+## 路由安全不变量
+
+节点来源是权威的溯源信息。上传节点即使带有提示词字段也不会变成生成节点，不得修改 `imageNodeOrigin` 或 `isCustomNode` 来改变界面呈现。只有 `canvas node generate` 提交成功后才能写入生成运行态字段；回调管理的 URL 和元数据不属于普通 Graph 更新范围。
+
+本页说明 Nadou CLI 对外可使用、可读取的**公共**节点 JSON。它不是后端内部数据结构，也不承诺所有节点类型的 `data` 都有一份静态完整参数结构；类型专有字段见各类型页的“字段表（已确认/已观察）”。
+
+使用节点 JSON 时，请先区分三个场景：创建节点、读取实时 Graph、修改已有节点。三者字段名和可写范围并不完全相同。
+
+## 创建节点：稳定、可写的公共结构
+
+### 上传图片的来源契约
+
+如果节点来源是用户上传图片，优先使用
+`nadou canvas node create-image-upload`。它会在初始 CREATE_NODE 中同时写入：
+
+```json
+{"isCustomNode":true,"imageNodeOrigin":"upload"}
+```
+
+这两个字段是 UI 的来源标记，不是生成任务字段。普通 `canvas node create` 仍保留为通用 Graph 能力；不要通过 PATCH 补写或伪造来源，也不要把上传节点写成 `generated`。
+
+Graph 写入时，`id`、`type` 和 `data.label` 是稳定必填字段；但调用
+`canvas node create` 时应省略 `id`，由 CLI 生成 Web 兼容 ID。只有批量 Graph 需要提前建立引用时，才先用
+`canvas node new-id --json` 取得 `id`。下面示例展示一个带尺寸、层级和固定坐标的完整已确认结构，
+其中 `<generated-node-id>` 必须来自该命令，不是语义名称：
+
+```json
+{
+  "id": "<generated-node-id>",
+  "type": "text",
+  "position": { "x": 0, "y": 0 },
+  "width": 360,
+  "height": 180,
+  "zIndex": 0,
+  "data": {
+    "label": "角色设定",
+    "text": "角色设定正文",
+    "prompt": ""
+  }
+}
+```
+
+### 创建请求公共字段（逐项）
+
+下表是所有当前公开节点类型共享的创建请求体字段。`data` 中只允许使用本页或对应类型页明确列出的字段；
+它不是“把实时 Graph 返回原样写回”的容器。
+
+| 字段 | JSON 类型 | 是否必填 | 含义与写入规则 |
+| --- | --- | --- | --- |
+| `id` | string | Graph 必填；`node create` 输入可省略 | CLI 自动生成，或在批量 Graph 前通过 `canvas node new-id` 取得；禁止 Agent 按标签自造语义 ID。已有 ID 仍是不透明字符串。 |
+| `type` | string | 是 | 节点类型，例如 `text`、`image`、`video`；决定可用的类型页和生成路由。 |
+| `data` | object | 是 | 节点属性容器；最少含 `label`。生成节点还应先写入与本次任务一致的提示词和模型配置。不能放入未确认的业务参数结构或回调字段。 |
+| `data.label` | string | 是 | 用户可读的基础标签；后续可以通过 `dataPatch` 修改。 |
+| `data.text` | string | text 节点必填 | text 节点的正文；不能用 `data.label` 代替。 |
+| `data.prompt` | string | 文本、图片/视频生成节点必填 | 文本节点没有关联提示词时使用空字符串；生成节点保存本次生成提示词，`canvas node generate` 会校验它与请求一致。 |
+| `data.modelName` / `data.modelType` / `data.taskType` | string | 生成节点必填 | 由当前模型目录和任务场景确定的真实模型与任务类型。 |
+| `data.modelParams` | object | 生成节点必填 | `model` 必须等于 `data.modelName`；其余字段来自当前模型参数结构的完整动态参数，提交请求必须保持一致。 |
+| `position` | object `{x,y}` | 否 | 调用方明确指定的画布坐标；与 `placement` 二选一。根级节点省略两者时，CLI 注入稳定服务端 `placement`；同批写入包含指向新节点的依赖边时使用 `RIGHT_OF_NODE`。 |
+| `placement` | object | 否 | 服务端裁决的自动布局输入；根级使用 `CANVAS_ORIGIN` / `RIGHT_OF_NODE`，组内使用 `parentNode` + `IN_GROUP_AUTO`；与 `position` 二选一。 |
+| `width` / `height` | number | 否 | 节点显示尺寸；必须同时省略或同时传入有限正数。由 `material upload` 放入画布的图片/视频节点必须根据上传响应的 `data.metadata.width` / `data.metadata.height` 计算并写入，禁止臆造固定尺寸（如 `640×360`）；同时按下节上传素材允许列表写入媒体 `data.metadata`。 |
+| `extent` | 不支持 | — | Web/Y.Doc 展示字段，不属于 Graph 创建请求；CLI 在触网前拒绝。 |
+| `zIndex` | number | 否 | 显示层级；创建请求使用 camelCase，读取投影为 `z_index`。 |
+| `parentNode` | string | 否 | 已存在 group 的节点 ID；表达分组归属，读取投影为 `parent_node`。 |
+| `anchorNodeId` | string | 否 | 公开 Graph 操作支持的锚点节点标识；仅在调用方已明确其布局意图时传入，不能按标签猜测。 |
+
+`placement` 的已确认结构为 `mode`、`layout`、`sectionKey`、`columns`，可选一致的 `gapX`、`gapY`、
+`avoidCollision`；CLI 自动补充的根级 `CANVAS_ORIGIN`、依赖相对 `RIGHT_OF_NODE` 与普通组内
+`IN_GROUP_AUTO` 布局会固定带上 `avoidCollision=true`，具体约束与完整命令见 [Canvas 文档](../commands/canvas.md)。
+
+`position` 用于固定坐标；普通根级创建不需要手写默认坐标，省略即可由 CLI 注入
+`CANVAS_ORIGIN`。批量创建“参考图 → 结果图”这类依赖关系时，在同批 Graph 操作中创建边，
+CLI 会注入带依赖源节点 ID 的 `RIGHT_OF_NODE`。两种转换都不读取实时 Graph，以保持幂等恢复请求
+稳定。只提供 `parentNode` 的新子节点会由 CLI 注入普通 `IN_GROUP_AUTO`；如果希望由服务端将子节点放入分类网格，
+应由调用方完整提供 `SECTION_GRID` placement，两者不能同时传递：
+
+```json
+{
+  "id": "<generated-node-id>",
+  "type": "text",
+  "parentNode": "<existing-group-node-id>",
+  "placement": {
+    "mode": "IN_GROUP_AUTO",
+    "layout": "SECTION_GRID",
+    "sectionKey": "characters",
+    "columns": 5
+  },
+  "data": {
+    "label": "角色设定",
+    "text": "角色设定正文",
+    "prompt": ""
+  }
+}
+```
+
+创建分组后才能以 `parentNode` 将节点放入该分组。创建请求使用 camelCase：`parentNode`、`zIndex`、`anchorNodeId`。
+
+### 将已上传本地素材作为图片/视频节点
+
+使用 `material upload --file <path> --canvas-id <canvas-id>` 成功后，使用返回的 `data.url` 创建对应
+`image` 或 `video` 节点，并同时用上传响应的 `data.metadata` 设置显示尺寸与媒体预览字段（与前端上传落盘对齐）：
+
+1. 根级 `width` / `height`：按真实宽高比换算为画布显示尺寸。短边固定为 `260`（与前端媒体节点一致）：横图/横视频
+   `height=260`、`width=round(260 * meta_w / meta_h)`；竖图/竖视频 `width=260`、
+   `height=round(260 * meta_h / meta_w)`；再各加 `2` 作为边框（例如 `2560×1440` → `464×262`）。
+   图片使用 `create-image-upload` 时，未显式提供 `--width/--height` 且上传元数据缺失或非法会在写入前失败，
+   不会回退到 1:1；显式尺寸用于覆盖自动计算。
+2. `data.metadata`：只从**同次**上传响应按允许列表抄入有值键；**禁止臆造**，也**禁止**把
+   `creator` / `createId` / `createTime` / doubao* 等无关字段整包复制进节点。缺省为 `null` 或不存在的键直接省略。
+3. 上传响应缺少有效正数宽高时，图片 `create-image-upload` 必须显式提供 `--width`/`--height`，否则在写入前失败；
+   视频等其他上传节点继续按各自命令契约处理。仍禁止写死 `640×360` 这类与素材无关的默认值。多档预览 URL
+   与 `assetId` 有值时仍应写入。
+
+**上传素材 `data.metadata` 允许列表（有值才写）**
+
+| 键 | 来源 | 用途 |
+| --- | --- | --- |
+| `width` / `height` | 上传 `data.metadata.width` / `height` | 真实像素尺寸；驱动显示比例与工具面板 |
+| `thumbnailUrl` | 上传 `data.metadata.thumbnailUrl` | 小缩略图；画布低质量预览、参考标签 |
+| `mediumThumbnailUrl` | 上传 `data.metadata.mediumThumbnailUrl` | 中图；画布默认节点封面/预览 |
+| `previewUrl` | 上传 `data.metadata.previewUrl` | 预览档；全屏等场景 |
+| `assetId` | 上传 `data.material_id` 或 `data.metadata.assetId` | 素材身份；存空间等 |
+| `assetName` | 上传 `data.file_name` 或 `data.metadata.assetName` | 下载/存空间默认文件名 |
+| `watermarkUrl` / `brandWatermarkUrl` / `combinedWatermarkUrl` | 上传元数据中的同名键 | 仅当上传返回非空字符串时写入 |
+| `firstFrameUrl` | 上传 `data.metadata.firstFrameUrl` | 视频首帧封面；视频优先写入 |
+| `duration` | 上传 `data.metadata.duration` | 视频时长，单位与上传响应一致（毫秒） |
+| `fps` / `isContainAudio` / `channelCount` | 上传元数据中的同名键 | 视频技术元数据；有值才写 |
+
+多档 URL 必须写在 `data.metadata` 下，不要摊平到 `data` 根级。
+
+- 图片展示优先：`mediumThumbnailUrl` → `thumbnailUrl` → `data.url`
+- 视频封面优先：`mediumThumbnailUrl` → `firstFrameUrl` → `thumbnailUrl`（缺少封面时节点只能靠原视频 `url`）
+
+图片示例：
+
+```json
+{
+  "id": "<generated-image-node-id>",
+  "type": "image",
+  "width": 464,
+  "height": 262,
+  "data": {
+    "label": "本地参考图",
+    "url": "<material-upload-data.url>",
+    "metadata": {
+      "width": 2560,
+      "height": 1440,
+      "assetId": 1401392,
+      "assetName": "reference.png",
+      "thumbnailUrl": "<upload-metadata.thumbnailUrl>",
+      "mediumThumbnailUrl": "<upload-metadata.mediumThumbnailUrl>",
+      "previewUrl": "<upload-metadata.previewUrl>"
+    }
+  }
+}
+```
+
+视频示例：
+
+```json
+{
+  "id": "<generated-video-node-id>",
+  "type": "video",
+  "width": 464,
+  "height": 262,
+  "data": {
+    "label": "本地参考视频",
+    "url": "<material-upload-data.url>",
+    "metadata": {
+      "width": 1920,
+      "height": 1080,
+      "duration": 5000,
+      "fps": 24,
+      "assetId": 1401393,
+      "assetName": "reference.mp4",
+      "thumbnailUrl": "<upload-metadata.thumbnailUrl>",
+      "mediumThumbnailUrl": "<upload-metadata.mediumThumbnailUrl>",
+      "firstFrameUrl": "<upload-metadata.firstFrameUrl>",
+      "previewUrl": "<upload-metadata.previewUrl>",
+      "isContainAudio": 1
+    }
+  }
+}
+```
+
+这不是任务回调的结果写入：它是图片/视频创建时的初始素材 URL 与上传媒体元数据。CLI 只允许
+`type=image|video` 的 `CREATE_NODE` 携带 `url`，并复用素材上传结果的公网地址校验（仅 HTTP(S)，拒绝本机、私网和已知内网域名）。`nodeStatus`
+和 `taskStatus` 仍不能通过创建或通用修改写入；任何普通 `node patch` / `PATCH_NODE` 也不能改 `url`，也不应事后伪造补齐
+上传元数据。例外仅为 `canvas node generate` 在 `/task/submit` 成功后的一次受控运行态补丁：它写入
+`aiTaskId`、`jobId`（若返回）、实际 `taskStatus`、`taskCreateTime`、`taskEstimatedTime`、
+`nodeStatus=taskRunning`、`isGenerating=true`、`imageNodeOrigin=generated` 和 `submitTaskParams`；该 PATCH 只初始化
+运行态，不携带 `url`、`metadata`、`assetId` 等终态/产物字段，任务终态和产物仍由回调权威写入。
+
+## 实时 Graph 读取：运行时状态，不是回写模板
+
+`nadou canvas get --canvas-id <canvas-id> --raw --json` 返回的是指定画布的 CLI 稳定读取投影。它使用 snake_case：`parent_node`、`z_index`。图片和视频等生成节点完成后，`data` 中可能出现任务和产物字段。
+
+```json
+{
+  "id": "<existing-image-node-id>",
+  "type": "image",
+  "position": { "x": 420, "y": 0 },
+  "parent_node": "<existing-group-node-id>",
+  "width": 360,
+  "height": 640,
+  "z_index": 1,
+  "data": {
+    "label": "角色形象",
+    "url": "<callback-managed-url>",
+    "nodeStatus": "idle",
+    "taskStatus": "COMPLETED",
+    "aiTaskId": "<task-id>",
+    "jobId": "<job-id>",
+    "metadata": {}
+  }
+}
+```
+
+`url` 通常是回调写入的当前媒体产物地址；但图片/视频创建时可提供已上传素材的初始 URL，规则见上节。`nodeStatus` 是画布节点自身状态，`taskStatus` 才是关联任务状态，两者不能混为一谈，且都不能作为普通创建或修改请求的 `data` 输入。任务 ID、作业 ID、`metadata` 等运行时信息同样应从 Graph 读取，用于观察和关联结果，而不是通过通用更新自行伪造或回写；只有上述受控生成写入可以使用本次真实任务提交响应。不同节点类型、不同模型以及不同任务阶段返回的 `data` 字段可能不同；读取到的字段不等于全部可写字段。图片和视频的逐字段定义见各自的类型页。
+
+### 实时读取公共字段（逐项）
+
+`canvas get` 的稳定输出是**读取投影**，字段采用蛇形命名；不能复制为创建或更新请求体。
+
+| 字段 | JSON 类型 | 含义 |
+| --- | --- | --- |
+| `id` | string | 节点的稳定标识；后续读取或修改时显式使用它。 |
+| `type` | string | 实际节点类型；选择对应类型页，不要根据 `label` 推断类型。 |
+| `position` | object `{x,y}` 或省略 | 当前读取到的节点坐标；它不是服务端承诺的完整布局参数结构。 |
+| `parent_node` | string 或省略 | 当前分组父节点 ID；对应创建请求体中的 `parentNode`。 |
+| `width` / `height` | number 或省略 | 当前投影的节点显示尺寸。 |
+| `z_index` | number 或省略 | 当前投影的显示层级；对应创建请求体中的 `zIndex`。 |
+| `data` | object | 节点数据和可能存在的运行时回填字段；仅把其中已公开、明确可写的字段用于后续更新。 |
+
+## 修改节点：直接 PATCH 与 Graph 批量编辑
+
+直接修改单个节点时，使用顶层 `id`：
+
+```json
+{
+  "id": "<existing-text-node-id>",
+  "expectedType": "text",
+  "rootPatch": { "position": { "x": 40, "y": 20 } },
+  "dataPatch": { "label": "角色设定（已确认）" }
+}
+```
+
+使用 `nadou canvas graph mutate --canvas-id <canvas-id>` 的 `PATCH_NODE` 操作时，该操作对象使用 `nodeId`。这是批量 Graph 操作的字段名，不应与直接 `PATCH` 的顶层 `id` 混用。修改前先读取当前 Graph；写入请求只发送一次，结果不确定时再次读取确认，不自动重放写请求。
+
+| 直接 `node patch` 字段 | JSON 类型 | 含义与规则 |
+| --- | --- | --- |
+| `id` | string | 必填，目标节点 ID；误传 `nodeId` 会在触网前得到纠正诊断。 |
+| `expectedType` | string | 可选的类型防护；目标类型不符时拒绝修改。 |
+| `rootPatch` | object | 可选的根结构改动，例如 `position`、尺寸或层级；先读取后再提交。 |
+| `dataPatch` | object | 可选的 `data` 浅合并；只包含对应类型页确认可写的字段，嵌套对象必须完整保留同级字段。 |
+
+## 类型字段与模型参数
+
+所有已公开节点类型都确认支持 `data.label` 作为创建时的基础标签。除本页和各类型页明确列出的字段外，不应假设 `data` 中存在可写的类型专有字段。
+
+图片和视频生成节点在创建时应保存本次生成语义配置：`prompt`、`modelName`、`modelType`、`taskType` 和完整 `modelParams`。文本生成节点至少保存 `prompt` 与 `modelParams.model`；历史文本节点可省略 `modelName`、`modelType` 和 `taskType`，CLI 会按当前 LLM 和图片入边补齐 `TEXT2TEXT`/`IMG2TEXT` 的 Canvas 请求。先通过 `nadou model schema <model-id> --json` 获取当前模型的动态参数结构，把 `schema.defaults` 作为动态参数基础，再显式加入 `"model":"<model-id>"` 后写入节点；若文本节点同时存在 `modelName`，`modelParams.model` 必须与其一致。`canvas node generate` 默认会从目标节点和入边依赖 URL 派生请求，并在估价或提交前再次校验模型锚点。任务结果会异步写入同一节点，文本结果由 callback 写入 `data.text`。除 `model` 选择锚点外，模型参数会随模型变化，不能写死进节点类型文档。本页的画布节点 JSON 契约不定义独立音频参数；独立音频按 [音频命令](../commands/audio.md) 和动态 `model schema` 执行，不能从本页推导参数。
+
+| 节点类型 | 已确认可写 `data` | 读取时可能出现的类型相关内容 |
+| --- | --- | --- |
+| `text` | `label`、Markdown 原文 `text`、`prompt`、`modelParams`，可选 `modelName`/`taskType` | `label` 是短标题，正文必须写入 `text`；文本生成请求使用 `modelName=canvas`/`modelType=CANVAS`，任务成功后 callback 回填 `data.text`；CLI 不限制正文字数、不转换 HTML 或编辑器私有 JSON |
+| `image` | `label`；生成节点的 `prompt`、`modelName`、`modelType`、`taskType`、`modelParams`；仅创建时可用已校验的初始 `url`；由上传创建时可附带允许列表中的 `metadata`（像素宽高、多档预览 URL、`assetId`/`assetName` 等，见上节） | 生成任务状态、产物 URL 和任务元数据 |
+| `video` | `label`；生成节点的 `prompt`、`modelName`、`modelType`、`taskType`、`modelParams`；仅创建时可用已校验的初始 `url`；由上传创建时可附带允许列表中的 `metadata`（像素宽高、封面/预览 URL、`duration`/`fps`、`assetId`/`assetName` 等，见上节） | 生成任务状态、产物 URL 和任务元数据 |
+| `audio` | `label` | 媒体任务状态和结果，以实时 Graph 为准 |
+| `group` | `label` | 子节点关系和布局由 Graph 结构表达 |
+| `storyboard` | `label` | 类型专有业务字段以实时 Graph 为准 |
+| `clip` | `label` | 类型专有业务字段以实时 Graph 为准 |
+| `director3d` | `label` | 类型专有业务字段以实时 Graph 为准 |
+
+各类型的用途、可执行命令和安全路由见 [节点类型索引](index.md)。

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

@@ -0,0 +1,35 @@
+# 3D 资产节点 `model3d`
+
+`model3d` 表示可生成 GLB 资产的画布节点，与场景规划节点 `director3d` 是两个独立类型。
+当前仅支持既有 Canvas 节点生成，不提供独立的 `nadou 3d` 原子命令。
+
+## 配置与场景
+
+先从运行时目录读取模型及参数：
+
+```sh
+nadou model list --scenario text_to_3d --profile <profile> --json
+nadou model schema tripo3d-h --scenario text_to_3d --profile <profile> --json
+```
+
+节点 `data` 保存 `modelName`、`modelType=model_3d`、`taskType` 和 `modelParams`。`modelParams.type`
+使用目录的类型化枚举：白膜 `0`、绘图 `1`、真实 `2`；`generateCount` 为 `1..4`。
+
+- `TEXT23D`：无图片入边，必须有非空提示词。
+- `IMG23D`：恰好一条图片入边，提示词可空。
+- `MULTI23D`：二至四条图片入边，按 Graph 入边顺序提交，依次表达 front、left、back、right。
+
+非图片依赖、重复/缺失 URL、超过四张图、未知材质值都会在提交前失败。请求使用
+`modelName=tripo3d-h`、`modelType=model_3d`，参数直接位于 `params`，不携带 `form`。
+
+## 最小流程
+
+```sh
+nadou canvas node template --type model3d --json
+nadou canvas node estimate --canvas-id <canvas-id> --node-id <node-id> --profile <profile> --json
+nadou canvas node generate --canvas-id <canvas-id> --node-id <node-id> --profile <profile> --json
+nadou canvas node wait --canvas-id <canvas-id> --node-id <node-id> --profile <profile> --json
+```
+
+生成完成后，GLB 地址保留在节点产物 URL 中，预览图保留在
+`data.metadata.model3DPreviewUrl`。这些 callback 字段只读，不得通过普通 patch 回写。

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

@@ -0,0 +1,43 @@
+# Storyboard 节点
+
+## 用途
+
+表达分镜结构。
+
+## 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":"storyboard","data":{"label":"分镜提纲"}}
+EOF
+nadou canvas get --canvas-id <canvas-id> --node-id <created-storyboard-node-id> --profile <profile> --json
+```
+
+## 已确认操作
+
+- 当前 CLI 可将其作为已知节点类型创建或读取。
+- 创建前可读取最小本地模板：`nadou canvas node template --type storyboard --json`。
+- 创建时省略 ID 让 CLI 生成并保存 `created_node_ids`，补全类型与标签后提交明确结构。
+
+## 编辑与结果边界
+
+不要将任务回填字段作为 `storyboard` 节点的普通修改写入。若需要修改已有节点，先读取实时 `Graph`，并且只修改
+已被公开契约确认的结构字段。
+
+## 待确认
+
+分镜专属字段、自动布局、与 `text`/`image`/`video` 的类型专属连接规则，以及是否存在独立生成语义均待确认；不要把未经公开
+确认的分镜规则迁入 Nadou。用户明确分镜文本、参考图或视频之间存在资产从属关系时，仍按
+[画布依赖图](../guides/canvas-dependency-graph.md) 建立通用依赖边。

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

@@ -0,0 +1,93 @@
+# Text 节点
+
+## 用途
+
+保存提示词、脚本或说明文字，也支持通过既有 `task/submit` 能力在原节点上执行文生文或图生文。
+`label` 是画布上的短标题，正文写入 `text`，两者不能混用。生成任务的输入提示词写入 `prompt`，
+任务成功后由后端 callback 把结果回填到同一节点的 `data.text`。
+
+## JSON 字段
+
+完整创建、读取和修改结构见 [JSON 结构与读写边界](json-contract.md)。文本正文以 Markdown 原文存入
+`data.text`；前端画布使用其正常 Markdown 编辑器渲染，CLI 不把正文转换成 HTML、富文本 `delta`
+或编辑器内部 JSON。文本编辑确认可写的 `data` 字段为 `label`、`text` 和 `prompt`；生成配置还支持
+`modelParams.model` 及可选的 `modelName`/`taskType`。产品当前不限制正文字数，因此 CLI 不设置本地长度上限，
+其他编辑器专有字段以实时 Graph 读取为准。
+
+### 字段表（已确认/已观察）
+
+| 字段 | 类型 | 位置 | 状态与用法 |
+| --- | --- | --- | --- |
+| `label` | string | `data.label` | **已确认可写**；创建时必填，只保存简短的节点标题，不能承载正文 |
+| `text` | string | `data.text` | **可写 Markdown 正文**；创建和修改时均与 `label` 分开；CLI 不限制正文字数 |
+| `prompt` | string | `data.prompt` | **已确认可写**；保存文本节点关联的生成提示词；没有提示词时使用空字符串 |
+| `modelParams.model` | string | `data.modelParams.model` | **文本生成模型选择**；必须是当前已配置的 LLM 模型 ID |
+| `modelName` | string | `data.modelName` | **可选兼容字段**；存在时必须与 `modelParams.model` 一致；历史节点可省略 |
+| `taskType` | string | `data.taskType` | **可选场景字段**；`TEXT2TEXT` 或 `IMG2TEXT`；历史节点省略时按是否有图片入边推导 |
+
+## 最小可复制示例
+
+```sh
+nadou canvas node create --canvas-id <canvas-id> --stdin \
+  --auto-layout-only --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"type":"text","data":{"label":"创作简报","text":"# 人物设定\n\n- 姓名：阿遥\n- 性格：冷静、果断","prompt":""}}
+EOF
+# 保存响应 created_node_ids[0]，再以该真实 ID 回读
+nadou canvas get --canvas-id <canvas-id> --node-id <created-text-node-id> --profile <profile> --json
+```
+
+## 已确认操作
+
+- 使用通用 `Graph` 命令创建、读取、修改或删除。
+- 创建前可读取最小本地模板：`nadou canvas node template --type text --json`。
+- `canvas get --node-id <text-node-id>` 在显式聚焦读取时可返回 `prompt` 或文本摘要。
+
+创建时省略 `id` 让 CLI 生成，只补全 `type="text"`、简短且非空的 `data.label`、正文 `data.text`
+和 `data.prompt`，再通过
+`canvas node create --canvas-id <canvas-id> --stdin` 提交到显式指定的画布（大载荷才用 `--body-file`）。
+
+若要直接生成，可在同一个创建请求中保存 `prompt` 和 `modelParams.model`。历史文本节点只保存
+`modelParams.model` 也可直接生成；CLI 会将它作为 `llmModelName`。
+
+## 文本生成
+
+先完成 `canvas node estimate`，确认积分后执行：
+
+```sh
+nadou canvas node estimate --canvas-id <canvas-id> --node-id <text-node-id> --profile <profile> --json
+nadou canvas node generate --canvas-id <canvas-id> --node-id <text-node-id> --profile <profile> --json
+nadou canvas node wait --canvas-id <canvas-id> --node-id <text-node-id> --task-id <task-id> --profile <profile> --json
+```
+
+没有图片入边时使用 `TEXT2TEXT`；有明确图片入边且节点 `taskType=IMG2TEXT` 时使用 `IMG2TEXT`，历史节点省略
+`taskType` 时 CLI 按图片入边补齐。
+CLI 提交 `modelName=canvas`、`modelType=CANVAS`、`workflowId`、`nodeId` 和当前 LLM 的
+`llmModelName`，不会把独立 `nadou text` 任务当作画布生成，也不会在提交后手工 patch `data.text`。
+任务成功后，`canvas node wait` 通过任务状态和 Graph 回读确认 callback 已更新目标节点正文。
+
+## 编辑与结果边界
+
+结构位置走 `rootPatch`，文本正文走 `dataPatch.text`，标题走 `dataPatch.label`。`dataPatch` 是浅合并；
+修改嵌套对象前必须先读取完整同级对象。不要把正文写入 `label`，也不要写 `url`、`nodeStatus`、
+`taskStatus` 或其他回填字段。
+
+修改标签或 Markdown 正文时使用顶层节点 `id` 和 `dataPatch`：
+
+```sh
+nadou canvas node patch --canvas-id <canvas-id> --stdin \
+  --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"id":"<existing-text-node-id>","expectedType":"text","dataPatch":{"label":"更新后的创作简报","text":"## 人物设定\n\n- 姓名：阿遥\n- 状态：已确认"}}
+EOF
+nadou canvas get --canvas-id <canvas-id> --node-id <existing-text-node-id> --profile <profile> --json
+```
+
+`dataPatch` 是浅合并：只更新本次给出的 `label`/`text`。正文必须是字符串，CLI 不限制正文字数。
+`Graph` 回读仍以 `data.text` 原文为准；是否支持某一项 Markdown 语法由画布当前编辑器决定，
+CLI 不自行扩展语法。
+
+文本转图片等组合仍必须由调用方显式创建节点与连线，再向既有目标 `image`/`video` 节点提交任务；
+`text` 节点的文生文/图生文只回填自身的 `data.text`。
+
+## 边界
+
+其他文本编辑器专有字段，以及与其他节点的合法连接数量和顺序，仍以公开后端契约为准。

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

@@ -0,0 +1,119 @@
+# 视频节点
+
+## 来源与提示词语义
+
+`imageNodeOrigin` 表示来源，不是界面开关。`generated` 只属于 `canvas node generate` 生命周期；上传或自定义节点仍是上传节点，不承诺具备生成节点的提示词界面。应使用受支持的生成生命周期，不得修改来源、自定义标记、回调字段、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 | 模型类型，例如 `VIDEO` | **可以**；应与请求一致 |
+| `taskType` | string | 任务类型，例如 `TEXT2VIDEO` / `IMG2VIDEO` | **可以**；参考图/多参考视频必须使用与参考输入一致的任务类型 |
+| `modelParams` | object | 模型选择锚点与当前视频模型的完整动态参数 | **可以**；创建生成节点时写入完整对象，`model` 必须等于 `modelName`；`canvas node set-ratio` 也会先读完整对象、保留同级字段后更新比例，禁止手写局部更新 |
+| `url` | string | 视频创建时的初始已上传素材地址，或回调写入的当前视频产物地址；是否出现取决于创建输入或任务是否产生可用视频 | **仅创建时可以**；仅 `type=video` 的 `CREATE_NODE` 可传（与图片同类例外），且必须是通过公网校验的 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 | 本次任务提交时记录的参数摘要 | **通用更新不可以**；任务提交成功后由受控补丁写入模型名、`VIDEO` 类型和任务类型 |
+
+生成请求中的字段由当前模型决定：先运行 `nadou model schema <model-id> --json`，以返回的
+`schema.defaults` 为动态参数基础，并额外写入 `"model":"<model-id>"`；它必须与节点
+`modelName` 完全一致。默认 `canvas node generate` 会从节点配置和入边依赖自动构建请求；普通 Agent 流程不要构造请求文件。
+
+## 最小可复制示例
+
+```sh
+nadou canvas node create-video --canvas-id <canvas-id> \
+  --label "主镜头" --idempotency-key <new-mutation-id> --profile <profile> --json
+```
+
+也可使用 `nadou canvas node template --type video --json`，省略 ID 由 CLI 生成后通过
+`node create --stdin` 提交（大型请求载荷才用 `--body-file`）。
+
+本地视频先上传，再用上传响应的 `data.url` 创建视频节点；这个 URL 是初始素材，不是回调结果。
+创建时必须读取上传响应的 `data.metadata.width` / `data.metadata.height`：根级 `width`/`height`
+按短边 `260` 保持比例换算显示尺寸（再各加 `2` 边框）。`data.metadata` 除像素宽高外，
+还必须按允许列表抄入同次上传返回的封面/预览 URL、时长与素材身份（有值才写）；
+`duration` 单位与上传响应一致（毫秒）。禁止臆造固定尺寸。完整规则见
+[json-contract.md](json-contract.md)。
+
+```sh
+nadou material upload --file ./reference.mp4 --profile <profile> --json
+# 假设上传返回 metadata.width=1920、metadata.height=1080 → 显示尺寸 464×262
+# 同时抄入 firstFrameUrl / mediumThumbnailUrl / thumbnailUrl / duration / fps / assetId / assetName（有值才写）
+nadou canvas node create --canvas-id <canvas-id> --stdin \
+  --auto-layout-only --idempotency-key <new-mutation-id> --profile <profile> --json <<'EOF'
+{"type":"video","width":464,"height":262,"data":{"label":"本地参考视频","url":"<upload-data.url>","metadata":{"width":1920,"height":1080,"duration":5000,"fps":24,"assetId":"<upload-data.material_id>","assetName":"<upload-data.file_name>","thumbnailUrl":"<upload-metadata.thumbnailUrl>","mediumThumbnailUrl":"<upload-metadata.mediumThumbnailUrl>","firstFrameUrl":"<upload-metadata.firstFrameUrl>","previewUrl":"<upload-metadata.previewUrl>"}}}
+EOF
+```
+
+## 已确认操作
+
+- 使用通用 Graph 命令创建、读取、更新或删除。
+- 可读取最小本地模板：`nadou canvas node template --type video --json`；也可用
+  `canvas node create-video --canvas-id <canvas-id>` 在显式指定的画布创建基础视频节点。
+- 对既有且明确指定且已保存提示词和模型配置的视频节点，可使用 `canvas node generate` 提交一次任务，并用
+  `canvas node wait --task-id <task-id>` 只读观察任务并确认回调。
+- `canvas node set-ratio` 是保留服务端返回 `modelParams` 的基础比例修改辅助；它不替代模型参数结构。
+
+生成前先读取本次可用模型和场景，并把提示词和模型配置写入目标节点：
+
+```sh
+nadou model list --type video --profile <profile> --json
+nadou model schema <model-id> --profile <profile> --json
+nadou canvas node estimate --canvas-id <canvas-id> --node-id <video-node-id> \
+  --audio-intent <auto|required|forbidden> --profile <profile> --json
+nadou canvas node generate --canvas-id <canvas-id> --node-id <video-node-id> \
+  --audio-intent <same-value-used-for-estimate> --profile <profile> --json
+```
+
+`--audio-intent required` 表示创作要求必须产生模型音频，`forbidden` 表示明确要求静音；CLI 将它与最终出站
+`generateAudio` 对账。模型没有显式返回该字段时不能证明意图成立，因此失败关闭。未明确音频需求时使用 `auto`，
+CLI 不根据提示词中的自然语言关键词自行判断。
+
+```sh
+nadou canvas node set-ratio --canvas-id <canvas-id> --node-id <existing-video-node-id> --ratio 9:16 \
+  --idempotency-key <new-mutation-id> --profile <profile> --json
+```
+
+## 编辑与结果边界
+
+运行态投影只在显式聚焦时返回受限字段。任务产物 URL、完整元数据、任务状态和产物列表只由
+回调维护；普通更新不得伪造这些值。`canvas node generate` 在提交成功后还会写入
+`isGenerating=true`、`imageNodeOrigin=generated`、`taskCreateTime` 和 `taskEstimatedTime`，使视频节点
+进入 Web 的运行中预览与历史入口。视频创建时的初始 `url` 与上传素材允许列表中的元数据
+是前述窄例外：只允许从同次 `material upload` 响应抄入已列键，不能扩展为任意元数据回写或事后臆造补丁。
+
+## 本地视频自定义节点（`materialId` 契约）
+
+本地视频先用现有 `material upload --file <path> --canvas-id <canvas-id>` 上传；专用创建只接受上传响应中的
+正整数 `data.id` 作为 `materialId`。CLI 不传 URL、元数据或任务状态；后端校验素材、画布权限和媒体类型，
+并写入受管素材身份。默认尺寸为 `260 × 260`；自定义 `width`/`height` 必须同时提供且为有限正数。不传 `position`
+时使用画布原点并避碰。`canvas node create-media` 不接收 `sourceNodeId`，不自动创建入边；需要连线时按
+[画布依赖图](../guides/canvas-dependency-graph.md) 另用明确 Graph 写。这表示 CLI 不隐式补边，不表示用户明确的参考/输入关系可以省略。
+
+先用 `canvas node new-id --json` 取得节点 ID，再使用
+`canvas node create-media --node-id <generated-node-id> --material-id <material-id>` 创建，随后用
+`canvas node mutation-status` 对账。服务端若返回 `B00001/INVALID_ARGUMENT`，当前只能报告后端阻塞；
+节点创建失败时保留已上传素材，不自动删除或重新上传。
+
+## 待确认
+
+视频模型参数、参考素材、时长/比例业务字段，以及上游、下游和数量规则均以实时 `model schema` 与后续
+公开画布契约为准。

package/skills/nadou/policies/core-safety.md

@@ -0,0 +1,35 @@
+# 核心安全边界
+
+本页是所有模式共享的安全政策。它定义边界，不替代具体工作流和当前 CLI 契约。
+
+## 事实优先级
+
+1. 当前安装版本的 `nadou capability list/describe --json` 决定命令是否公开、作用域和副作用。
+2. 当前命令的 `--help` 决定命令路径、位置参数和命令选项；文档示例与帮助冲突时停止并以帮助为准。
+3. 当前配置环境的 CLI 响应决定账号、模型参数结构、空间、目录、画布、节点、任务、素材、权限和状态。
+4. 本技能的政策决定智能体编排与停止条件；工作流和配方不能放宽政策，示例也不能证明后端能力已开放。
+
+## 后端与凭据
+
+- 所有 NadouAI 业务请求都通过已安装的 `nadou` 执行。不得使用临时脚本、自定义 HTTP 客户端、浏览器会话或相邻服务绕过 CLI 与后端许可清单。
+- 仓库维护者的 `cli-agent-eval` 只读评测例外不属于本 Skill 的能力，Agent 不得继承、调用或扩展该例外。
+- 不读取、复制、保存、索要或展示 `Cookie`、`token`、`Authorization`、登录 URL 参数等凭据。登录只走 `nadou auth login` 的现有浏览器授权。
+- `auth status` 为 `authenticated` 时直接继续；只有状态明确为缺失、过期或需要重新授权时才登录一次。凭据存储不可用、状态目录错误或诊断失败不是未登录，不自动反复打开浏览器。
+- `capability` 未公开、命令本地阻断或契约未确认时，说明限制并停止。不得借用相近命令、原始 `Graph` 字段、本地文件或其他平台伪造成功。
+
+## 身份与目标
+
+- 配置环境只选择本地配置，不能代替用户选择账号、个人/团队空间、目录、画布、节点或素材。
+- ID 必须来自本轮权威响应。候选为空、多个候选无法区分、父子关系不完整或权限不明确时停止询问，不按名称、列表顺序、URL 或旧缓存猜测。
+- 画布 ID 与节点 ID 每次显式传入；不跨会话继承。普通任务、空间素材和 Canvas `Graph` 是不同作用域，成功状态不能互相推导。
+
+## 模式与来源
+
+- 独立原子生成、Canvas 生成节点、上传/自定义节点、本地处理和已有任务恢复必须保持各自来源语义。
+- `nadou image/video/audio` 不创建或修改画布节点；`canvas node generate` 不创建个人空间副本；本地媒体命令不回填 Canvas。
+- 上传素材的 URL 只按上传响应和具体创建契约使用。回填管理的 URL、`metadata`、任务状态和节点状态不由通用修改写入。
+- 用户指定其他平台时，不将 Nadou 结果冒充为该平台结果；需要切换平台或降级时先取得明确选择。
+
+## 副作用
+
+执行前读取能力描述中的 `effects`，分别识别远端读取、远端写入、本地读取、本地写入和破坏性操作。某些看似查询的账号/空间命令可能带服务端附加写入，只在流程需要时调用，不用于高频轮询。任何未披露的副作用都不能由“全自动”或 `--no-interactive` 默认为已授权。