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

package/skills/nadou/commands/canvas-node.md

@@ -0,0 +1,228 @@
+# 画布节点
+
+## 节点 ID 生成约定
+
+未来由 CLI 创建的新节点统一使用与 `nadouai-web` 相同的
+`<Unix 毫秒时间戳>-<5 位小写 base36>` 格式，例如 `1786851600248-48pqw`。
+
+- `canvas node create-image-upload`、`canvas node create-video`、Canvas 模式的 `image-tool` 和
+  `canvas media export prepare`：没有复用既有节点的明确需求时，省略对应 node ID 参数，让 CLI 生成。
+- `canvas node create`：新节点 JSON 省略顶层 `id`，CLI 会在 Graph 写入前生成，并在响应
+  `created_node_ids` 中返回真实 ID；后续操作只使用该返回值。
+- `canvas graph mutate`：同批边或 `parentNode` 必须提前引用新节点时，先分别执行
+  `nadou canvas node new-id --json`，把返回的 `data.node_id` 放入操作。Agent 不得按节点名称生成
+  `image-wedding-dress`、`text-brief` 等语义 ID，也不得自行实现随机算法。
+- 显式传入的既有 ID 和实时 Graph 返回的历史 ID 继续合法；把它们当作不透明字符串原样使用，
+  不按新格式解析或迁移。
+
+## 视频模式的显式控制
+
+画布视频节点的模式必须由 CLI 显式控制，不能根据连接了几张图片来猜测。`minimax-h3` 同时可能出现在首尾帧和多参考模型目录中，模型名本身不能代表模式。
+
+创建节点时可以直接持久化模式：
+
+```sh
+nadou canvas node create-video --canvas-id <canvas-id> \
+  --scenario multi_reference --profile <profile> --json
+```
+
+已有视频节点切换模式时使用：
+
+```sh
+nadou canvas node set-scenario --canvas-id <canvas-id> --node-id <node-id> \
+  --scenario multi_reference --profile <profile> --json
+```
+
+模式映射为：
+
+| CLI 场景 | 画布 `data.taskType` | 语义 |
+| --- | --- | --- |
+| `text2video` | `TEXT2VIDEO` | 文生视频 |
+| `first_last_frame` | `IMG2VIDEO` | 首帧、尾帧或首尾帧 |
+| `multi_reference` | `MULTI_REF_IMG2VIDEO` | 角色、场景等有序多参考 |
+
+设置后先回读节点，确认 `data.taskType` 与用户意图一致，再执行 `canvas node estimate` 和 `canvas node generate`。CLI 会沿用节点中已保存的任务类型；两张参考图不会被 CLI 自动改写成首尾帧。若节点模式冲突，应先显式执行 `set-scenario`，不自动重新生成或重试。
+
+## 路径预览与节点语义
+
+Canvas 生成属于生成节点路径，除非明确请求服务端定时，否则报告
+`creation_mode=canvas_generated`、`node_origin=generated` 和
+`schedule_mode=disabled`。`create-media` 属于上传/自定义路径；它必须保持
+`node_origin=upload`，且不承诺提供生成节点提示词界面。现有任务产物挂载走显式
+`copy_to_space → materialId attach` 专用合同，绝不回退到下载重传、通用 URL 节点或伪造来源字段。
+
+先读取 `node-types/index.md` 和具体类型参考。节点创建、修改、删除、比例调整都经有序 Graph 操作完成。删除需要确认。
+
+需要读取某一类型的**全部**实时节点（包括作为参考输入、已有出边或尚未回填产物 URL 的 video 节点）时使用：
+
+```sh
+nadou canvas node list --canvas-id <canvas-id> --type video --profile <profile> --json
+```
+
+该命令以一次 `graph/query` 读取后在本地按 `type` 筛选，返回完整节点 `data`。它不是素材库，也不按 URL、任务状态或连线方向过滤；不要使用 `canvas assets list --type video` 替代此场景，后者只列视频产物，可能排除作为输入的上传视频。
+
+创建与修改的 JSON 默认通过 `--stdin` 使用内嵌文档；仅大批量或需留盘复现时用 `--body-file`。输入载体约定见
+[canvas.md](canvas.md)。
+普通新节点和自动布局流程统一给 `canvas node create` 增加 `--auto-layout-only`：该模式发现
+`CREATE_NODE.position` 会在触网前拒绝，显式 `placement` 或完全省略布局字段仍合法。固定几何、Group
+包裹等高级流程不使用该开关，并且必须明确说明为何需要坐标；`PATCH_NODE.position` 不受该开关影响。
+创建根级节点时，如果请求体未提供 `position` / `placement`，CLI 会注入稳定的服务端
+`CANVAS_ORIGIN` 布局；如果同批 Graph 变更里有从依赖节点到新节点的边，则改用
+`RIGHT_OF_NODE` 并携带依赖节点 ID，且自动布局带 `avoidCollision=true`。该转换只依赖有序
+操作，不读取实时 Graph，因此同一变更 ID 的显式恢复可以重建相同请求。只有用户明确要求固定坐标时才手写 `position`。
+`RIGHT_OF_NODE + avoidCollision=true` 只保证从锚点右侧寻找最近空位并避免重叠；多个同锚点节点可能形成多行多列，
+不保证竖直单列。`gapX` / `gapY` 只能调整间距；精确单列需要先读 Graph 后传明确 `position`，且不再传 `placement`。
+新建节点只提供 `parentNode` 时，CLI 会注入普通 `IN_GROUP_AUTO + avoidCollision=true`；普通组内自动摆放可省略
+`layout`。只有显式选择 `layout=SECTION_GRID` 时才需要同时提供 `sectionKey`（`characters`、
+`scenes` 或 `items`）和 1–100 的整数 `columns`，CLI 不会替用户猜测分类。
+`width` / `height` 必须同时省略或同时传入有限正数，媒体节点应使用真实展示尺寸；Graph 创建不得传 `extent`。
+
+```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":"在这里填写简报正文。","prompt":""}}
+EOF
+```
+
+text 节点的 `data.label` 只保存简短标题，正文必须写入 `data.text`；不要为了省略字段而把整段正文放入
+`label`。没有关联生成提示词时，`data.prompt` 使用空字符串。
+
+提交前可按明确的节点 ID 估算一个或多个文本、图片或视频节点的整体积分：
+
+```sh
+nadou canvas node estimate --canvas-id <canvas-id> \
+  --node-id <node-a> --node-id <node-b> \
+  --profile <profile> --no-interactive --json
+```
+
+CLI 只读取一次所选节点及其连线，按需批量补读缺失的上游依赖，再用与 `generate` 相同的规则为每个节点
+构造请求并逐项调用积分估算。它不提交任务、不修改 Graph。只有所有条目都可估算时才返回
+`total_points`；后端明确返回 `points=0` 的条目是可估算的精确零值，单条或汇总可返回
+`total_points=0, estimable=true`，不附加 `reason`。缺失、负数或非数值积分按后端契约错误处理。
+节点 ID 不得重复，一次最多 20 个。估价是提交前预览，不锁定价格；后续 `generate` 会重新读取实时 Graph。
+
+视频需求明确包含对白、音乐、现场声或音效时，单节点估价增加 `--audio-intent required`；用户明确要求静音时使用
+`--audio-intent forbidden`。成功响应的 `audio_intent` 会给出最终 `generateAudio` 与一致性结论。生成时必须传相同参数；
+CLI 在任务提交前重新检查，字段缺失或冲突均返回 `CANVAS_AUDIO_INTENT_CONFLICT`，且 `request_sent=false`。
+`auto` 仅保持兼容，不代表 CLI 已理解自然语言提示词。
+
+`canvas node generate` 有两种互斥模式：
+
+- **立即生成（默认 `--schedule-mode disabled`）**：先执行 `canvas node estimate` 做预算预览，确认后直接执行
+  `canvas node generate`。不要传 `--dry-run`、`--max-points`、`--scheduled-at`、`--timezone` 或
+  `--confirm-preview-sha256`；这些参数只属于服务端定时流程。多节点任务的总预算以估价返回的
+  `total_points` 与用户授权比较，不能把每个命令的 `--max-points` 相加或当作立即模式的总预算。
+- **服务端定时（`--schedule-mode server`）**：必须指定执行时间和时区，先用 `--dry-run` 预览，再用
+  `--confirm-preview-sha256` 与 `--max-points` 正式提交。不要把该流程当成立即生成。
+
+在既有节点生成使用 `canvas node generate --canvas-id <canvas-id> --node-id <id>`；它使用显式画布 ID且不创建节点。
+默认情况下 CLI 会读取目标节点、入边依赖与依赖节点产物 URL，自动构建任务请求并提交。
+任务请求文件不是普通画布生成路径；高级回放需要显式启用隐藏选项，且仍会校验请求与节点配置一致。
+目标图片/视频节点必须已经在 `data` 中保存与请求一致的生成配置（`prompt`、`modelName`、
+`modelType`、`taskType`、完整 `modelParams`）。文本节点至少需要非空 `prompt` 与 `modelParams.model`；
+	历史文本节点可省略 `modelName`、`modelType`、`taskType`，CLI 会从当前节点和入边补齐。`model schema` 的 `defaults` 只包含动态参数；
+	写入图片/视频/音频节点时还必须在 `modelParams.model` 加入同一个真实模型 ID，并确保它与 `modelName` 完全一致。文本节点的
+	`modelParams.model` 是 LLM 选择锚点，历史节点可省略 `data.modelName`。
+缺失或不一致时，创建、估价和生成都会在本地拒绝，不会发送任务。图生图、图生视频或多参考任务还必须先创建从参考节点到
+目标节点的边；连线判定按 [画布依赖图](../guides/canvas-dependency-graph.md) 执行，CLI 不会因为 URL 或节点类型自动补边。
+CLI 会从已核对的入边源节点读取 `data.url` / `outputUrls` 作为参考输入。提交成功后，CLI 会用同一次
+成功响应把 `aiTaskId`、`jobId`、实际 `taskStatus`、`taskCreateTime`、`taskEstimatedTime`、
+`nodeStatus=taskRunning`、`isGenerating=true`、`imageNodeOrigin=generated` 和
+`submitTaskParams` 写入目标节点；该更新只初始化运行态，不携带 `url`、`metadata`、`assetId` 等终态/产物字段。
+它适用于图片/视频/音频节点，是 `canvas node generate` 的受控 Graph 写，不开放给通用 `node patch`。文本节点不写入这组媒体运行态字段；
+它直接依赖 `task/submit` 的 `workflowId + nodeId` 关联和后端 callback 回填 `data.text`。若写入超时，
+CLI 先查询原 `mutationId` 的 `graph/mutation/status`，再只读查询节点，不更换变更 ID、不重提任务。随后保存响应中的任务 ID，再用
+`canvas node wait --task-id <task-id>` 协调观察任务状态和回调。该命令默认观察 10 分钟；
+可用 `--timeout` 显式覆盖观察窗口；
+到期时任务仍为 `INIT` / `SCHEDULED` / `RUNNING` 会返回成功的非终态结果
+（`observation_timed_out=true`），不表示任务失败，也不得重新提交。任务完成但回调尚未写回时同样返回
+`canvas_synced=false`，可稍后用同一组画布/节点/任务 ID 继续观察。`template` 仅输出最小本地模板，
+不是完整后端参数结构。
+
+文本节点生成无图片入边时使用 `TEXT2TEXT`；显式图片入边且节点场景为 `IMG2TEXT` 时使用该路由。请求固定携带
+`modelName=canvas`、`modelType=CANVAS`、`workflowId`、`nodeId` 和当前 LLM 的顶层及 `params.llmModelName`，
+`form` 为空对象。`canvas node wait` 在任务成功后重新读取 Graph，只有发现目标 `data.text` 已由 callback 更新才报告
+`canvas_synced=true`；不得用独立 `nadou text` 或普通 `node patch` 替代该关联路径。
+
+单个既有节点需要服务端定时生成时，必须显式选择服务端模式，并先做只读预览。执行时间按用户时区的 30 分钟卡点填写
+（例如 `21:00` 或 `21:30`），且秒数必须为 `00`：
+
+Agent 在对话中索取该时间时，示例只能使用 `YYYY-MM-DD HH:00` 或 `YYYY-MM-DD HH:30`，例如
+`2026-08-06 21:00`、`2026-08-06 21:30` 或 `2026-08-06 22:00`。不得提示其他分钟的时间；
+用户输入其他分钟时必须停止并请用户重新选择，不能自动四舍五入或改写成邻近卡点。
+
+```sh
+nadou canvas node generate --canvas-id <canvas-id> --node-id <node-id> \
+  --schedule-mode server --scheduled-at <local-time> --timezone <IANA> \
+  --dry-run --profile <profile> --json
+```
+
+核对预览中的实时 Graph 请求、`workflowId/nodeId/scheduledTime`、身份、目标/计费空间、模型/数量、
+估价、余额、预计余额和不锁价说明后，使用相同时间参数并传
+`--confirm-preview-sha256 <digest> --max-points <authorized-points>`。正式调用会重新读取事实；任何漂移均
+在提交前停止。通过后只发送一次普通任务提交，结果未知时保留请求证据且不得重提。
+画布归属前置校验对显式 `canvas-id` 使用 `GET /apis/nadouai/canvas/workflow/detail?workflowId=<canvas-id>`，
+只读取 `data.groupId`、`data.groupType`、`data.directoryId`；接口返回的 graph 忽略，节点和连线仍以
+`graph/query` 为准。归属字段为空时不推断当前默认空间/目录，而是失败关闭；归属结果不长期缓存。
+画布节点不支持本地模式，当前也不提供服务端列表/更新/取消或 DAG 计划。
+
+Agent 不应手工转抄上传响应来创建图片节点。使用 `canvas node upload-image --canvas-id <id> --file <path>`
+可把本地图片按目标 workflow 范围上传并创建 upload 类型节点；使用
+`canvas node import-image-url --canvas-id <id> --url <url>` 可让服务端把 URL 素材登记到目标 workflow，再创建对应画布节点。
+两种来源都返回 `material_scope=workflow`，并使用服务端返回的真实媒体类型做校验；不会仅凭文件扩展名或 URL 后缀判断。
+两条命令都在进程内传递素材 ID、可信公网 URL 与 metadata，并明确执行“素材登记 → Graph 节点创建”两个单次写入阶段；
+任一写入结果未知时停止。素材阶段已成功而节点阶段失败时，按返回的素材 ID 和原 mutation 恢复，不得重新上传或重新导入。
+
+需要处理视频或音频时使用通用入口，必须显式声明素材角色，CLI 不根据扩展名或 URL 猜测：
+
+```text
+nadou canvas node upload-media --canvas-id <id> --file <path> --media-type image|video|audio
+nadou canvas node import-media-url --canvas-id <id> --url <url> --media-type image|video|audio
+```
+
+`image` 分支创建与网页端一致的 upload 来源图片节点；`video`/`audio` 分支创建现有
+`create-media` 自定义媒体节点。文件上传或 URL 素材登记后，CLI 会先核对服务端权威 `fileType` 与显式
+`--media-type`；不一致时保留素材 ID/URL 并停止，绝不继续创建错误节点。两个通用命令都支持
+`--node-id`、`--label`、`--position`/`--placement`、`--idempotency-key` 和
+`--return-snapshot`，并返回 `media_type`、素材 ID/URL/范围、节点 ID 与 mutation 证据。
+素材登记和节点写入各最多一次；节点阶段失败时保留素材事实，后续只查询 Graph 或 mutation receipt。
+
+底层兼容命令仍可用：本地图片或视频素材先通过 `material upload` 上传，再使用响应中的公网 `data.url` 创建对应图片/视频
+节点。图片上传使用 `canvas node create-image-upload` 时，若未显式传入 `--width/--height`，必须把同次
+上传响应的 `data.metadata.width` / `data.metadata.height` 传入 `--metadata`，CLI 会按短边 260 保比例、再加
+2px 边框计算节点显示 `width`/`height`；缺少或非法像素尺寸时在写入前失败，不静默创建 1:1 节点。显式
+`--width/--height` 优先于自动计算。同时在创建请求的 `data.metadata` 中按上传素材允许列表写入像素宽高、多档预览/封面 URL
+（`thumbnailUrl` / `mediumThumbnailUrl` / `previewUrl` / `firstFrameUrl`）以及 `assetId` / `assetName`
+（视频另写入 `duration` / `fps` 等；有值才写；禁止整包复制上传响应）。该 URL 仅允许出现在图片/视频的
+`CREATE_NODE.data.url`；通用 `node patch` 和 `PATCH_NODE` 仍不得修改 URL 或任务运行态。只有生成任务已被
+`task/submit` 接受后，CLI 才能通过上述受控补丁写入运行中投影；任务产物 URL、终态状态和完整回调
+元数据继续由回调管理。完整结构见 [节点 JSON 公共契约](../node-types/json-contract.md)。
+## Canvas 音频节点生成
+
+对既有音频节点，使用：
+
+```text
+nadou canvas node estimate --canvas-id <canvas-id> --node-id <audio-node-id> --json
+nadou canvas node generate --canvas-id <canvas-id> --node-id <audio-node-id> --json
+nadou canvas node wait --canvas-id <canvas-id> --node-id <audio-node-id> --task-id <task-id> --json
+```
+
+没有音频入边时使用 `TEXT2AUDIO`；只有一条显式音频入边时使用 `AUDIO2AUDIO`。
+出现图片/视频依赖、提示词缺失、动态配置不完整或 URL 不可信时，在提交前失败。
+CLI 不会创建节点/连线，也不会把 Canvas 结果复制到个人空间；URL、元数据和运行时状态由回调维护。
+
+## Canvas 3D 资产节点生成
+
+`model3d` 节点使用相同的 `estimate/generate/wait` 链路。根据图片入边数量选择 `TEXT23D`（0）、
+`IMG23D`（1）或 `MULTI23D`（2..4）；依赖必须都是图片节点且保持入边顺序。材质 `type` 从
+运行时 schema 读取并以数字 `0/1/2` 提交，请求 `modelType` 为 `model_3d` 且不带 `form`。
+完整约束和结果字段见 [3D 资产节点](../node-types/model3d.md)。
+### 媒体参考提示词契约
+
+当生成图片/视频节点存在媒体入边时，CLI 会推导有序源节点，并在提交前将与网页端兼容的
+`reference-tag` 元素写入任务描述。现有标签会保留，纯文本会转义，生成的标签与描述放在
+同一段落中。如果源标签能标识描述中的主体（例如 `人物参考图` 和 `人物在草原上奔跑`），
+标签会紧跟在该主体之后，使 `@label` 与指令形成同一条语义提示词。如果无法推断主体锚点，
+CLI 会确定性地把标签放在段首，而不是猜测位置。每个标签都携带源节点 ID、可信产物 URL、
+标签和媒体类别；增强后的提示词会在任务提交前通过一次确定性的 Graph 更新写入目标节点。
+更新失败时通过只读 Graph 查询核对；只有更新成功或确认已经存在时才提交任务。

package/skills/nadou/commands/canvas.md

@@ -0,0 +1,123 @@
+# 自由画布入口
+
+本页只负责路由，不重复定义参数和 Graph 契约。用户明确提出画布、给出画布 ID/URL、指定画布节点，
+或明确要让生成结果进入当前已选择画布时，进入自由画布路径；普通图片或视频创作使用独立模型任务。
+
+## 先选择参考
+
+| 意图 | 读取 |
+| --- | --- |
+| 创建、列表、重命名、移动、删除或恢复画布 | [canvas-management.md](canvas-management.md) |
+| 读取实时画布结构（摘要/原始数据/焦点邻接） | [canvas-management.md](canvas-management.md) |
+| 多节点、多连线，或同事务节点+连线写入 | [canvas-graph.md](canvas-graph.md) |
+| 单个节点的创建、修改、删除、生成或等待 | [canvas-node.md](canvas-node.md) 与 [../node-types/index.md](../node-types/index.md) |
+| 单条连线的连接、修改或删除 | [canvas-edge.md](canvas-edge.md) |
+| 用户语义到依赖图、已有素材映射和自动连线判定 | [../guides/canvas-dependency-graph.md](../guides/canvas-dependency-graph.md) |
+| Web Timeline 校验、画布时间轴合成、成片导出与回填观察 | [canvas-media.md](canvas-media.md) |
+
+同一事务若需要创建或修改 **≥2 个节点**、连接 **≥2 条边**，或同时写入 **节点与连线**（例如多个参考图节点 + 一个生成目标 + 入边），必须先读 [canvas-graph.md](canvas-graph.md)，用一次 `canvas graph mutate` 提交有序 `operations`。禁止拆成多次 `canvas node create` / `canvas edge connect`，也禁止并发多次写请求。`node` / `edge` 子命令只用于确实只有单个节点或单条连线的改动；生成与等待仍走 `canvas node generate` / `wait`。
+
+## 共同边界
+
+- 新建节点时不得按标签或用途自造 `image-wedding-dress`、`video-main` 等语义 ID。专用创建命令省略
+  `--node-id`，通用 `canvas node create` 省略 JSON 的 `id`，统一由 CLI 生成
+  `<Unix 毫秒时间戳>-<5 位小写 base36>`。批量 Graph 需要预先引用 ID 时，先为每个新节点调用
+  `nadou canvas node new-id --json`，使用返回的 `node_id`；不要自行拼接时间戳或随机串。
+- 已有节点的 ID 是不透明字符串；读取、修改、等待和恢复时必须原样使用实时 Graph 返回值。不要因为历史
+  ID 不符合新格式而改写、迁移或拒绝它。
+- `canvas get/graph/node/edge/assets/rename/move/delete/restore` 每次都必须显式传 `--canvas-id <canvas-id>`；CLI 不把画布写入账号配置。
+- Agent 只在当前会话中保留用户明确给出的 Canvas ID；切换会话、账号或用户明确切换画布时不得沿用旧值。
+- 普通发现默认使用 `canvas get`；它读取当前画布 Graph，不按名称或类型猜节点，也不暴露后端实时协作实现。
+- `nadou image` / `nadou video` 始终提交独立任务且不接受画布上下文；在画布工作流中不建议用快捷命令代替节点生成。
+- 画布内生成应显式创建或选择包含 `prompt`、`modelName`、`modelType`、`taskType`、完整 `modelParams` 的图片/视频/音频目标节点；文本节点至少应包含非空 `prompt` 与 `modelParams.model`，历史文本节点可由 CLI 按当前节点和图片入边补齐 `TEXT2TEXT` 或 `IMG2TEXT`。所有节点通过入边表达参考素材，再执行 `canvas node generate`。
+- 扣费前先执行 `canvas node estimate --node-id <id>`；它读取实时节点与入边，只发送 `taskType/modelName/modelType/generateCount/params` 的精简估价请求，不提交任务、不写 Graph。视频明确需要对白/音乐/音效时附加 `--audio-intent required`，明确要求静音时使用 `--audio-intent forbidden`；估价与生成必须使用相同意图。CLI 只校验显式意图与最终 `generateAudio`，不靠提示词关键词猜测。立即生成使用默认的 `disabled` 模式，估价后执行 `canvas node generate` 时不要附带 `--dry-run` 或 `--max-points` 等服务端定时参数；这些参数只用于 `--schedule-mode server`。节点中的 `generateAudio`（开/关）、`keepOriginalSound`（是/否）、`cutType`（开/关）、`quality`（快速/平衡/高质量）、MJ 模式、`audioSetting`、`characterOrientation` 和 `spaceSize` 会在出站副本中转换为后端值，节点原始数据不变。
+- `canvas node generate` 与估价不是同一请求体：生成仍发送包含 `workflowId/nodeId` 和 `form` 的完整任务请求，供后端回调写回目标节点。不得把精简估价体用于提交，也不得把完整提交体直接用于估价。
+- `canvas get` 只收敛 CLI 输出，不减少后端 Graph 查询载荷。
+- 写操作只发送一次；未知结果先实时回读并保留画布、节点、变更、任务和请求证据，不自动重试。
+- `url`、`nodeStatus`、`taskStatus` 等回调管理字段不得由通用 Graph 更新写入。唯一的运行态例外是
+  `canvas node generate` 在 `/task/submit` 已成功后使用一次仅初始化运行态的受控补丁；它不携带 URL、metadata、assetId 等终态字段，也不改变
+  任务提交一次、终态回调权威写回和未知结果不自动重试的规则。
+- 文本节点生成使用既有 `/task/submit` 的 `workflowId + nodeId` 关联，提交请求固定使用 `modelName=canvas`、
+  `modelType=CANVAS`、当前 LLM 的 `llmModelName` 和空 `form`；不写媒体运行态补丁，成功结果由 callback 回填目标 `data.text`。
+  `canvas node wait` 必须用同一 task ID 观察任务，再通过 Graph 回读确认正文变化。
+- `canvas node create-media`、`canvas node mutation-status` 与 `canvas node attach-output` 已接入公开允许列表。
+  独立/跨空间任务产物必须先使用 `space artifact deliver --mode copy` 复制到目标画布目录，再把返回的新
+  `materialId` 作为 selector 挂载；`allOutputs=true` 不执行复制。只有 attach 返回外层 `C00001`、结构化子码
+  `ATTACH_READBACK_PENDING` 且 workflow/mutation 身份匹配时，CLI 才查询原 receipt；`C00009` 保持确定性终态，
+  泛化网络 UNKNOWN 也不自动轮询。成功后仍需按 [画布依赖图](../guides/canvas-dependency-graph.md) 显式建立真实来源边。
+  详细流程见 [任务产物绑定契约](canvas-attachment.md)。
+
+## 协作安全（Agent Graph 门禁）
+
+节点锁语义以服务端锁投影为准，CLI 坚持失败关闭；本机不依据时间推断锁是否过期：
+
+- Graph 查询将返回服务端 `observedAt`（毫秒）且只投影 `expiresAt > observedAt` 的有效锁；CLI 不用本机时间判断锁是否过期。
+- 字段缺失或未知不等于未锁定；服务端观察值缺失、回调正在更新或无法确认时，都不得写入目标节点；不解析未确认的 Graph 字段，也不依据 `data` 中的未知属性猜锁。
+- 确认已锁定后，不得对该节点修改文本/参数或提交生成任务；无关节点必须分别完成最新服务端读取和显式规划后才能继续。
+- Graph 写由后端对全部受影响节点原子检查；group 删除包含递归后代与受连线变化影响的节点，任一锁冲突则整体失败。
+- 带 `workflowId + nodeId` 的任务提交当前由 CLI 在提交前读取目标锁；锁定、投影缺失或未知时停止。独立任务不检查。通用 `task/submit` 尚无已确认的服务端原子锁校验，CLI 不创建、续期或释放服务端锁。
+- `NODE_LOCKED` 必须从后端 `data.details` 保留节点 ID、持有人安全表示、`expiresAt`、`observedAt`；CLI 报告后不自动重试。
+- `C00009` 或其他聚合冲突不等同于某个节点已锁定。保留画布、节点、变更、任务、请求证据，由调用方显式回读后再决定；不自动重试、回滚或补写。
+- “创建新节点”规避冲突、连线/分组操作及混合锁定后代的行为未经当前契约确认，不得当作安全替代方案。若 `nodeLockProjectionAvailable=false`，当前环境的 Agent 写入应停止并记录服务端错误，不得切换到已停用的 `/graph/mutate`。
+
+## 协同冲突与锁
+
+若后端返回 `NODE_LOCKED`，CLI 保留 nodeIds、持有人、expiresAt 与 observedAt，并停止写入；若锁投影不可用或返回未知协同错误，
+CLI 也不能把它当作“未锁定”，不能自动绕开后新建节点，也不能回退到已停用的 Graph 写入口。
+遇到冲突时保留原节点、变更和请求证据，先 `canvas get` 回读；未受影响的其他工作只有在用户或
+调用方提供明确的独立节点范围时才能继续。在后端双用户锁竞态与通用 `task/submit` 原子校验完成前，
+CLI 的本地失败关闭门禁不能被表述为完整的端到端锁保护。
+
+## JSON 输入载体
+
+`canvas node create/patch`、`canvas edge connect/patch`、`canvas graph mutate` 的载荷用
+`--stdin` 或 `--body-file`（二者互斥），不要把 JSON 展开进命令行参数。
+
+| 场景 | 用法 |
+| --- | --- |
+| 单个节点/连线、短 `dataPatch`、少量操作 | 优先写入 UTF-8 文件并使用 `--body-file`；只有能保证标准输入字节编码时才使用 `--stdin` |
+| 大批量变更、从快照导出的长操作、需留盘复现的大载荷 | 才写临时 JSON，再用 `--body-file` |
+
+Agent 通过命令执行工具封装调用时，`--stdin` 与实际标准输入内容必须在同一次工具调用中成对提供：
+工具支持独立 `stdin` 字段时，把完整 JSON 写入该字段；工具只接收命令字符串时，把内嵌文档一并写入命令字符串。
+禁止只传带有 `--stdin` 的裸命令后另行补充载荷，也不要并发启动尚未绑定标准输入的命令。
+若调用封装无法可靠传递标准输入，先把完整 JSON 写入临时文件，再改用 `--body-file`。
+
+JSON 输入必须是 UTF-8。Windows PowerShell 不要把包含中文的内嵌字符串直接管道到 `--stdin`，因为字符串管道可能在 CLI 收到数据前把中文替换为 `?`。应使用 UTF-8 文件（可无 BOM 或带 BOM）配合 `--body-file`；CLI 会在 JSON 解析和后端请求前拒绝非法 UTF-8。若写入后需要确认文本未被改变，可同时使用 `--return-snapshot --verify-text`，发现不一致时 CLI 会停止且不会自动重试。
+
+`canvas node generate` 默认不接收任务 JSON，而是从目标节点配置和入边依赖自动派生请求。
+`task submit/estimate` 仍只接受 `--body-file`；独立任务或高级回放见 [task-request.md](task-request.md)。
+## Canvas 音频节点生成
+
+既有音频节点可使用 `canvas node estimate/generate/wait` 执行 `TEXT2AUDIO` 或
+`AUDIO2AUDIO`。入口 Agent 根据显式音频连线选择场景，动态发现模型和参数结构，完成余额查询、
+估价及确认后只提交一次。不得把 Canvas 音频改写为独立 `nadou audio`，不得隐式创建节点/连线，
+也不得把 Canvas 结果交付到个人空间。
+
+## Canvas 3D 资产节点生成
+
+既有 `model3d` 节点可使用 `canvas node estimate/generate/wait` 执行 `TEXT23D`、`IMG23D` 或
+`MULTI23D`。入口 Agent 根据显式图片入边数量选择场景，并从运行时 3D 配置读取材质和数量参数。
+`model3d` 与 `director3d` 不可互换；当前没有独立原子 3D 命令。详见
+[3D 资产节点](../node-types/model3d.md)。
+
+## 上传媒体节点
+
+当用户明确要把本地文件或可访问的媒体 URL 直接作为新节点写入画布时，优先使用以下两阶段命令：
+
+```text
+nadou canvas node upload-media --canvas-id <id> --file <path> --media-type image|video|audio
+nadou canvas node import-media-url --canvas-id <id> --url <url> --media-type image|video|audio
+```
+
+`--media-type` 必须显式指定，不能根据扩展名或 URL 推断。图片会创建 Web 兼容的上传/自定义节点，
+并写入 `isCustomNode=true` 与 `imageNodeOrigin=upload`；视频和音频使用仅接收 `materialId` 的
+`canvas node create-media` 契约。CLI 会校验素材服务返回的媒体类型，类型不一致时在画布写入前失败。
+
+已有的 `material upload` + `create-image-upload`/`create-media`，以及图片专用直传命令仍保留，
+可用于低层兼容流程；图片作为参考节点时不得先创建普通图片节点再修改来源。
+
+## Canvas 成功输出
+
+Canvas 操作成功后，只报告已核验的 Canvas/节点事实和可信任务产物，不要附加个人空间交付消息。
+只有用户明确要求另行交付到空间，或该交付失败/结果未知时，才展示空间信息。

package/skills/nadou/commands/evidence.md

@@ -0,0 +1,30 @@
+# 本地证据与交付清单
+
+`nadou evidence` 只生成或校验版本化本地 JSON；除 `generation` 为读取已知任务 ID 外，不发业务网络请求。
+所有输出默认拒绝覆盖，不记录令牌、Cookie、Authorization、短期签名下载 URL 或内部推理。
+
+```sh
+nadou evidence generation --task-id <id> [--task-id <id> ...] \
+  --output ./delivery/generation-evidence.json --profile <profile> --json
+nadou evidence validate --input ./delivery/generation-evidence.json --json
+```
+
+`GenerationEvidence` 保留逐任务/作业/产物的真实状态、部分成功、失败和稳定产物来源，但移除原始响应与
+短期下载地址。结果未知或非终态可以留证，却不能标记为已交付。
+
+最终媒体先保存完整的成功 `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
+```
+
+`DeliveryManifest` 只在生成结果可交付、下载清单完整、所有本地哈希值一致、校验确实针对同一最终媒体且
+三项人工确认都存在时完整。可选 `--audio-plan` 与 `--subtitle-report` 也必须是同一清单目录内的有效引用。
+引用缺失、使用绝对/越界路径、文件被修改、验证响应封装拼接伪造或未来版本不兼容时失败关闭。
+
+校验只说明证据结构和技术引用一致；不会代替创意评价，也不会触发任务重提、下载恢复、空间交付或画布写入。

package/skills/nadou/commands/image-tools.md

@@ -0,0 +1,88 @@
+# 图像工具
+
+## 定位
+
+`nadou image-tool` 调用服务端现有的确定性图像工具协议。它与 `nadou image --scenario ...`
+分层：后者的模型和参数来自当前账号动态目录；工具的 task/model 标识是 Web 与 NadouAI 的固定
+路由契约，用户不能用 `--model` 覆盖。
+
+当前支持：
+
+- `nadou image-tool relight`：打光效果。
+- `nadou image-tool multi-angle`：指定水平/垂直角度、景别和镜头效果。
+- `nadou image-tool portrait-quality`：人像质感参数调整。
+- `nadou image-tool upscale`：2K/4K/8K 超清。
+- `nadou image-tool multi-grid`：角色、场景、剧情和分镜宫格。
+
+全景生成和三视图仍属于动态模型场景，分别使用 `nadou image --scenario panorama` 与
+`nadou image --scenario three_view`；不要改走本页工具。
+
+## 原子边界
+
+- `--source-image` 只接受可信 HTTPS URL；本地文件先经用户授权显式执行 `material upload`。
+- 工具不会隐式上传、创建/修改画布节点、交付空间或下载本地文件。
+- 用户要求放入画布时，工具完成后再依据可信 task/job/output 显式执行现有画布 attachment；
+  不把上传节点 patch 成 generated 来源。
+- 每次工具命令最多提交一次。超时或输出读取失败时保留 task ID，执行 `task status/wait/outputs`。
+
+## 费用与提交
+
+先预览唯一请求：
+
+```sh
+nadou image-tool relight \
+  --source-image <trusted-https-url> \
+  --light-direction front --light-intensity 70 \
+  --profile <profile> --dry-run --json
+```
+
+## 画布模式
+
+为了让结果像网页端生成节点一样可编辑、可连线，同时传入 `--canvas-id`，并通过
+`--source-node-id` 指定已有上传源节点 ID。命令会创建图片生成目标节点（显式提供 `--node-id` 时复用该 ID），
+并在提交任务前建立源节点到目标节点的边。任务请求随后携带相同的 `workflowId` 与 `nodeId`，CLI 会按工具类型
+写入对应的 `imageNodeOrigin`，并设置 `isCustomNode=false`。省略 `--width` 和 `--height` 时，画布模式读取
+源节点的可信元数据，把同一组宽高用于工具请求和目标节点预览元数据；缺少尺寸时失败关闭，不静默生成方图。
+任务状态和结果 URL 仍由服务端回调维护。该流程不会下载或重新上传素材，也不会把上传节点修改为生成节点。
+
+```sh
+nadou image-tool relight --source-image <trusted-https-url> \
+  --canvas-id <canvas-id> --source-node-id <uploaded-image-node-id> \
+  --wait --profile <profile>
+```
+
+未同时提供两个画布参数时，命令保持为独立图像工具任务。
+
+画布模式的 `portrait-quality` 会在目标节点 `submitTaskParams` 中保留
+`enhance_portrait_quality` 任务，但展示来源沿用现有的 `upscale`。这是用于隐藏普通文生图底部面板的
+Web 兼容标记，不会把实际请求操作改为图像放大。
+
+将 `data.request` 原样保存，按 `points summary` → `task estimate` 展示预计积分并取得本轮确认。
+估价不锁价；确认前零提交。确认后使用相同参数执行工具命令且只执行一次；请求、profile、计费
+空间或参数发生变化时必须重新估价确认。`--yes`、`--no-interactive` 和用户最初的创作意图不等于费用授权。
+
+## 示例
+
+```sh
+nadou image-tool multi-angle --source-image <url> \
+  --horizontal-angle 45 --vertical-angle 0 --shot-size medium-shot \
+  --mode fine --profile <profile> --dry-run --json
+
+nadou image-tool portrait-quality --source-image <url> \
+  --skin-roughness -50 --facial-blemishes 50 --sharpness 50 \
+  --profile <profile> --dry-run --json
+
+nadou image-tool upscale --source-image <url> --resolution 4K \
+  --profile <profile> --dry-run --json
+
+# 默认使用专业模式；VLM 模式必须显式指定模型。
+nadou image-tool upscale --source-image <url> --resolution 4K \
+  --mode VLM --model-name "IGI 2" --profile <profile> --dry-run --json
+
+nadou image-tool multi-grid --source-image <url> \
+  --type character_expression_nine_grid \
+  --profile <profile> --dry-run --json
+```
+
+具体允许值以 `nadou image-tool <name> --help` 为准。多宫格未知类型必须失败关闭，不根据自然语言
+猜任务键；Agent 应先读取帮助或 `capability describe image-tool.multi-grid`。