@aswless_854771076/ai_short_studio_cli 0.1.241 → 0.1.243

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,6 +3,7 @@ import { Flags } from '@oclif/core';
3
3
  import { CliApiError } from './client/errors.js';
4
4
  import { createRuntime } from './runtime.js';
5
5
  import { VvicatApi } from './domain/vvicat-api.js';
6
+ import { readCanvasNodeSelectedVersionId } from './domain/canvas-node-selection.js';
6
7
  export const projectFlag = Flags.string({ description: '无限画布项目 ID', required: true });
7
8
  export async function commandApi(flags) {
8
9
  const runtime = await createRuntime(flags);
@@ -22,18 +23,16 @@ export function canvasEditConflictReason(error) {
22
23
  return reason === 'CANVAS_VERSION_CONFLICT' || reason === 'ASSET_VERSION_RACE' ? reason : null;
23
24
  }
24
25
  export async function resolveCanvasNodeVersionId(api, projectId, node) {
25
- // 普通媒体和结构化资源都可固定节点选版,不能被资产全局选版替代。
26
- const selectedOutputVersionId = node.data.selectedOutputVersionId;
27
- if (typeof selectedOutputVersionId === 'string' && selectedOutputVersionId) {
26
+ const selectedOutputVersionId = readCanvasNodeSelectedVersionId(node, null);
27
+ if (selectedOutputVersionId !== null)
28
28
  return selectedOutputVersionId;
29
- }
30
29
  if (typeof node.refId !== 'string' || !node.refId)
31
30
  return '';
32
31
  const payload = await api.asset(projectId, node.refId);
33
32
  const asset = payload.asset && typeof payload.asset === 'object' && !Array.isArray(payload.asset)
34
33
  ? payload.asset
35
34
  : {};
36
- return typeof asset.selectedVersionId === 'string' ? asset.selectedVersionId : '';
35
+ return readCanvasNodeSelectedVersionId(node, asset) ?? '';
37
36
  }
38
37
  export async function mapConcurrent(values, concurrency, transform) {
39
38
  const results = new Array(values.length);
@@ -1,5 +1,5 @@
1
1
  import { basename, join } from 'node:path';
2
- import { mkdir, rename, writeFile } from 'node:fs/promises';
2
+ import { mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
3
3
  import { Args, Flags } from '@oclif/core';
4
4
  import { BaseCommand } from '../../../base-command.js';
5
5
  import { commandApi, projectFlag } from '../../../command-helpers.js';
@@ -38,10 +38,21 @@ export default class CanvasAssetDownload extends BaseCommand {
38
38
  }
39
39
  await mkdir(flags.output, { recursive: true });
40
40
  const target = join(flags.output, filename);
41
- const partial = `${target}.part`;
42
- await writeFile(partial, Buffer.from(await response.arrayBuffer()));
43
- await rename(partial, target);
41
+ // 每次下载独占临时目录,避免同名下载互相覆盖或跟随既有 part 软链接。
42
+ const temporary = await mkdtemp(join(flags.output, '.canvas-download-'));
43
+ try {
44
+ const partial = join(temporary, 'content');
45
+ await writeFile(partial, Buffer.from(await response.arrayBuffer()), { flag: 'wx' });
46
+ await rename(partial, target);
47
+ }
48
+ finally {
49
+ await rm(temporary, { recursive: true, force: true });
50
+ }
44
51
  this.print({ assetId: args.assetId, versionId, path: target });
45
52
  }
46
53
  }
47
- function safeName(value) { return value.replace(/[\\/:*?"<>|]/g, '_') || 'download.bin'; }
54
+ function safeName(value) {
55
+ const name = value.replace(/[\\/:*?"<>|]/g, '_');
56
+ // 点路径不能作为文件名,否则拼接后会指向输出目录本身或它的父目录。
57
+ return !name || name === '.' || name === '..' ? 'download.bin' : name;
58
+ }
@@ -0,0 +1,21 @@
1
+ import { BaseCommand } from '../../base-command.js';
2
+ export default class CanvasDirector extends BaseCommand {
3
+ static description: string;
4
+ static args: {
5
+ nodeId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
6
+ };
7
+ static flags: {
8
+ project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
9
+ operation: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
10
+ query: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
11
+ 'asset-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
12
+ file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
13
+ 'request-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
14
+ 'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
15
+ json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
16
+ locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
17
+ profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
18
+ episode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
19
+ };
20
+ run(): Promise<void>;
21
+ }
@@ -0,0 +1,36 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { randomUUID } from 'node:crypto';
3
+ import { Args, Flags } from '@oclif/core';
4
+ import { BaseCommand } from '../../base-command.js';
5
+ import { commandApi, projectFlag } from '../../command-helpers.js';
6
+ export default class CanvasDirector extends BaseCommand {
7
+ static description = '查询、预检和编排导演台 v3 原生工程;导出由用户在页面操作。';
8
+ static args = { nodeId: Args.string({ required: true }) };
9
+ static flags = { ...BaseCommand.baseFlags, project: projectFlag,
10
+ operation: Flags.string({ default: 'document.read', options: ['capabilities.read', 'document.validate', 'document.read', 'document.replace', 'entity.upsert', 'entity.delete', 'scene.update'] }),
11
+ query: Flags.string({ description: '能力查询关键词(ID、名称、分组或别名)' }),
12
+ 'asset-id': Flags.string({ description: '能力查询中读取完整原生实体模板的资产 ID' }),
13
+ file: Flags.string({ description: 'UTF-8 JSON 请求文件;写操作包含 expectedVersionId、expectedCanvasVersion 和对应操作字段' }),
14
+ 'request-id': Flags.string({ description: '工程写入请求 UUID' }),
15
+ };
16
+ async run() {
17
+ const { args, flags } = await this.parse(CanvasDirector);
18
+ const { api } = await commandApi(flags);
19
+ const operation = flags.operation;
20
+ if (operation === 'capabilities.read') {
21
+ this.print(await api.directorV3(flags.project, args.nodeId, 'GET', undefined, false, undefined, { view: 'capabilities', ...(flags.query ? { query: flags.query } : {}), ...(flags['asset-id'] ? { assetId: flags['asset-id'] } : {}) }));
22
+ return;
23
+ }
24
+ if (operation === 'document.read') {
25
+ this.print(await api.directorV3(flags.project, args.nodeId));
26
+ return;
27
+ }
28
+ const body = flags.file ? JSON.parse(await readFile(flags.file, 'utf8')) : {};
29
+ if (!body || Array.isArray(body) || typeof body !== 'object')
30
+ throw Error('请求文件必须为 JSON 对象');
31
+ const requestId = flags['request-id'] || (typeof body.requestId === 'string' ? body.requestId : undefined);
32
+ if (!Number.isInteger(body.expectedCanvasVersion))
33
+ throw Error('写操作需要 expectedCanvasVersion');
34
+ this.print(await api.directorV3(flags.project, args.nodeId, 'POST', { ...body, operation, requestId: requestId ?? randomUUID() }));
35
+ }
36
+ }
@@ -1,6 +1,7 @@
1
1
  import { Args } from '@oclif/core';
2
2
  import { BaseCommand } from '../../../base-command.js';
3
3
  import { commandApi, projectFlag } from '../../../command-helpers.js';
4
+ import { readCanvasNodeSelectedVersionId } from '../../../domain/canvas-node-selection.js';
4
5
  export default class CanvasDocumentGet extends BaseCommand {
5
6
  static description = '读取画布文档当前选定版本及原始 JSON';
6
7
  static args = { nodeId: Args.string({ required: true }) };
@@ -16,10 +17,14 @@ export default class CanvasDocumentGet extends BaseCommand {
16
17
  ? assetPayload.asset : null;
17
18
  if (!asset)
18
19
  throw new Error('画布文档资产不存在');
19
- const selectedVersion = asset.selectedVersion && typeof asset.selectedVersion === 'object' && !Array.isArray(asset.selectedVersion)
20
- ? asset.selectedVersion : null;
20
+ const selectedVersionId = readCanvasNodeSelectedVersionId(node, asset);
21
+ const versions = [asset.selectedVersion, ...(Array.isArray(asset.versions) ? asset.versions : [])];
22
+ const selectedVersion = versions.find((version) => Boolean(selectedVersionId !== null && version && typeof version === 'object' && !Array.isArray(version)
23
+ && 'id' in version && version.id === selectedVersionId));
24
+ if (selectedVersionId !== null && !selectedVersion)
25
+ throw new Error('画布文档选定版本不存在,请重新读取节点选版');
21
26
  this.print({ nodeId: args.nodeId, assetId: node.refId, metadata: asset.metadata ?? null,
22
- selectedVersionId: asset.selectedVersionId ?? selectedVersion?.id ?? null,
27
+ selectedVersionId,
23
28
  textContent: selectedVersion?.textContent ?? null,
24
29
  generationParams: selectedVersion?.generationParams ?? null });
25
30
  }
@@ -3,6 +3,7 @@ import { BaseCommand } from '../../../base-command.js';
3
3
  import { commandApi, projectFlag, readJsonInput } from '../../../command-helpers.js';
4
4
  import { assertCanvasSchemaKey } from '../../../domain/canvas-schema-key.js';
5
5
  import { validateCanvasDocumentContent } from '../../../domain/canvas-document-contract.js';
6
+ import { readCanvasNodeSelectedVersionId } from '../../../domain/canvas-node-selection.js';
6
7
  export default class CanvasDocumentSave extends BaseCommand {
7
8
  static description = '将 JSON 保存为画布文本资源的不可变文档版本';
8
9
  static args = { nodeId: Args.string({ required: true }) };
@@ -45,14 +46,13 @@ export default class CanvasDocumentSave extends BaseCommand {
45
46
  const response = assetId ? await api.asset(flags.project, assetId) : null;
46
47
  const asset = response?.asset && typeof response.asset === 'object'
47
48
  ? response.asset : null;
48
- const selectedVersionId = typeof node.data?.selectedOutputVersionId === 'string' ? node.data?.selectedOutputVersionId
49
- : typeof asset?.selectedVersionId === 'string' ? asset.selectedVersionId : null;
49
+ const selectedVersionId = readCanvasNodeSelectedVersionId(node, asset);
50
50
  const inputs = await Promise.all((flags.input ?? []).map(async (nodeId) => {
51
51
  const source = await api.node(flags.project, nodeId);
52
52
  const sourceAsset = typeof source.refId === 'string' ? await api.asset(flags.project, source.refId) : null;
53
53
  const selectedAsset = sourceAsset?.asset && typeof sourceAsset.asset === 'object'
54
54
  ? sourceAsset.asset : null;
55
- const versionId = source.data?.selectedOutputVersionId ?? selectedAsset?.selectedVersionId;
55
+ const versionId = readCanvasNodeSelectedVersionId(source, selectedAsset);
56
56
  if (typeof versionId !== 'string' || !versionId)
57
57
  throw new Error(`上游节点没有选版:${nodeId}`);
58
58
  return { nodeId, versionId };
@@ -75,16 +75,6 @@ function planCount(plan, category) {
75
75
  const value = plan[category];
76
76
  return Array.isArray(value) ? value.length : 0;
77
77
  }
78
- function hasPromptInput(nodeId, edges) {
79
- // 旧画布可能没有 targetHandle,此时任何入边都按已接线处理,避免误报。
80
- return edges.some((edge) => edge.targetNodeId === nodeId
81
- && (edge.targetHandle === 'prompt' || !edge.targetHandle));
82
- }
83
- function promptSourceKind(nodeId, edges, kindById) {
84
- const edge = edges.find((item) => item.targetNodeId === nodeId
85
- && (item.targetHandle === 'prompt' || !item.targetHandle));
86
- return edge ? kindById.get(edge.sourceNodeId) ?? null : null;
87
- }
88
78
  function connectedResourceKeys(node, edge, resourceTypes, sourceKinds) {
89
79
  if (!node)
90
80
  return [];
@@ -96,7 +86,21 @@ function connectedResourceKeys(node, edge, resourceTypes, sourceKinds) {
96
86
  return sourceKinds.includes(node.kind) ? node.resourceKeys ?? [] : [];
97
87
  }
98
88
  export function auditAssets(input) {
89
+ const nodeById = new Map(input.nodes.map(node => [node.id, node]));
99
90
  const kindById = new Map(input.nodes.map((node) => [node.id, node.kind]));
91
+ const promptInputsByNodeId = new Map();
92
+ const promptInputByNodeId = new Map();
93
+ // 历史空端口仍算提示词输入;保留首条匹配边,避免后续连接覆盖原来源诊断。
94
+ for (const edge of input.edges) {
95
+ if (edge.targetHandle && edge.targetHandle !== 'prompt')
96
+ continue;
97
+ const targetNodeId = edge.targetNodeId;
98
+ const inputs = promptInputsByNodeId.get(targetNodeId) ?? [];
99
+ inputs.push(edge);
100
+ promptInputsByNodeId.set(targetNodeId, inputs);
101
+ if (!promptInputByNodeId.has(targetNodeId))
102
+ promptInputByNodeId.set(targetNodeId, edge);
103
+ }
100
104
  const errors = [];
101
105
  const warnings = [];
102
106
  const imageGenerateIds = input.nodes.filter((node) => node.kind === TRANSPARENT_IMAGE_KIND).map((node) => node.id);
@@ -153,9 +157,9 @@ export function auditAssets(input) {
153
157
  continue;
154
158
  }
155
159
  const suppliedKeys = new Set(sheets.flatMap(sheet => {
156
- const sources = input.edges.filter(edge => edge.targetNodeId === sheet.id && (edge.targetHandle === 'prompt' || !edge.targetHandle));
160
+ const sources = promptInputsByNodeId.get(sheet.id) ?? [];
157
161
  return sources.flatMap(edge => {
158
- const node = input.nodes.find(node => node.id === edge.sourceNodeId);
162
+ const node = nodeById.get(edge.sourceNodeId);
159
163
  return connectedResourceKeys(node, edge, resourceTypes, sourceKinds);
160
164
  });
161
165
  }));
@@ -181,10 +185,10 @@ export function auditAssets(input) {
181
185
  nodeIds: [sheet.id],
182
186
  });
183
187
  }
184
- const sourceKind = promptSourceKind(sheet.id, input.edges, kindById);
185
- const source = input.edges.find(edge => edge.targetNodeId === sheet.id && (edge.targetHandle === 'prompt' || !edge.targetHandle));
186
- const embeddedSource = sourceKind === 'text-resource' && source
187
- && connectedResourceKeys(input.nodes.find(node => node.id === source.sourceNodeId), source, resourceTypes, sourceKinds).length > 0;
188
+ const promptInput = promptInputByNodeId.get(sheet.id);
189
+ const sourceKind = promptInput ? kindById.get(promptInput.sourceNodeId) ?? null : null;
190
+ const embeddedSource = sourceKind === 'text-resource' && promptInput
191
+ && connectedResourceKeys(nodeById.get(promptInput.sourceNodeId), promptInput, resourceTypes, sourceKinds).length > 0;
188
192
  if (sourceKind && !sourceKinds.includes(sourceKind) && !embeddedSource) {
189
193
  warnings.push({
190
194
  code: 'sheet-prompt-source',
@@ -193,7 +197,7 @@ export function auditAssets(input) {
193
197
  nodeIds: [sheet.id],
194
198
  });
195
199
  }
196
- if (!hasPromptInput(sheet.id, input.edges)) {
200
+ if (!promptInput) {
197
201
  warnings.push({
198
202
  code: 'sheet-prompt-unconnected',
199
203
  severity: 'warning',
@@ -0,0 +1,3 @@
1
+ export declare function readCanvasNodeSelectedVersionId(node: {
2
+ data?: unknown;
3
+ }, asset: Record<string, unknown> | null): string | null;
@@ -0,0 +1,12 @@
1
+ export function readCanvasNodeSelectedVersionId(node, asset) {
2
+ const data = node.data && typeof node.data === 'object' && !Array.isArray(node.data)
3
+ ? node.data : null;
4
+ // 节点选版独立于资产全局选版;显式固定版本不能因缺失而借用其他版本。
5
+ if (typeof data?.selectedOutputVersionId === 'string')
6
+ return data.selectedOutputVersionId;
7
+ if (typeof asset?.selectedVersionId === 'string')
8
+ return asset.selectedVersionId;
9
+ const selected = asset?.selectedVersion;
10
+ return selected && typeof selected === 'object' && !Array.isArray(selected) && 'id' in selected && typeof selected.id === 'string'
11
+ ? selected.id : null;
12
+ }
@@ -157,6 +157,7 @@ export declare class VvicatApi {
157
157
  }): Promise<JsonObject>;
158
158
  patchCanvas(projectId: string, input: JsonObject): Promise<JsonObject>;
159
159
  updateStoryboardShot(projectId: string, nodeId: string, input: JsonObject): Promise<JsonObject>;
160
+ directorV3(projectId: string, nodeId: string, method?: 'GET' | 'POST', body?: JsonObject, render?: boolean, requestId?: string, query?: Record<string, string>): Promise<JsonObject>;
160
161
  directorDeskRead(projectId: string, nodeId: string): Promise<JsonObject>;
161
162
  directorDeskApply(projectId: string, nodeId: string, input: JsonObject): Promise<JsonObject>;
162
163
  directorSceneAnalyze(projectId: string, input: JsonObject): Promise<JsonObject>;
@@ -263,6 +263,11 @@ export class VvicatApi {
263
263
  });
264
264
  }
265
265
  // 新版完整状态与旧版兼容投影同时返回,调用方不得用投影覆盖完整工程。
266
+ directorV3(projectId, nodeId, method = 'GET', body, render = false, requestId, query) {
267
+ const params = new URLSearchParams({ ...query, ...(requestId ? { requestId } : {}) }).toString();
268
+ const path = `/api/projects/${encodeURIComponent(projectId)}/canvas/nodes/${encodeURIComponent(nodeId)}/director-desk-v3${render ? '/render' : ''}${params ? `?${params}` : ''}`;
269
+ return this.client.request(path, { method, ...(body ? { body } : {}) });
270
+ }
266
271
  directorDeskRead(projectId, nodeId) {
267
272
  return this.client.request(`/api/projects/${encodeURIComponent(projectId)}/canvas/nodes/${encodeURIComponent(nodeId)}/director-desk`);
268
273
  }
@@ -379,8 +384,9 @@ export class VvicatApi {
379
384
  if (!node)
380
385
  throw new Error(`节点不存在:${update.nodeId}`);
381
386
  const definitionVersionId = typeof node.data.definitionVersionId === 'string' ? node.data.definitionVersionId : null;
382
- const definition = catalog.nodeTypes.find((item) => item.kind === node.kind)
383
- ?? (definitionVersionId ? canvas.nodeTypesByVersionId?.[definitionVersionId] : undefined);
387
+ // 已有动态节点按绑定版本校验,目录升级不能改变历史节点的配置合同。
388
+ const definition = (definitionVersionId ? canvas.nodeTypesByVersionId?.[definitionVersionId] : undefined)
389
+ ?? catalog.nodeTypes.find((item) => item.kind === node.kind);
384
390
  if (!definition)
385
391
  throw new Error(`未知节点类型:${node.kind}`);
386
392
  const configPatch = update.set ?? {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aswless_854771076/ai_short_studio_cli",
3
- "version": "0.1.241",
3
+ "version": "0.1.243",
4
4
  "description": "VVICAT 无限画布项目命令行工具",
5
5
  "license": "MIT",
6
6
  "private": false,
@@ -17,7 +17,7 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
17
17
 
18
18
  - GIF、循环动图、Image 2.6 的渠道限制:优先使用 StarRouter Image 2.6,读取 [动图合同](references/short-drama/generation/image26-animation.md),以实时能力为准,当前渠道帧数上限为 16,frameCount/frameDurationMs 控制新生成的帧数和速度,完成后核对真实帧延迟;已实测支持通过参考图生成 GIF,须保留设定图输入并核对返回身份;已有 GIF 逐帧编辑仍属能力缺口。
19
19
  - 项目创建、settings、批处理、目录或安全边界:[references/project-and-canvas.md](references/project-and-canvas.md)
20
- - 轻量 3D 预演场景读取、结构化编辑、显式渲染与工程导出:[references/canvas-previs.md](references/canvas-previs.md)
20
+ - 导演台 v3 新增节点、原生工程编排与人工导出交接:[references/canvas-previs.md](references/canvas-previs.md)
21
21
  - 人物/场景/道具、拆镜、分镜图和生成前审计:[references/assets-and-storyboard.md](references/assets-and-storyboard.md)
22
22
  - MiniMax H3 视频、原生音频、遮挡转场、单镜与成片验收:[references/h3-video-delivery.md](references/h3-video-delivery.md)
23
23
  - 资产、分镜图、视频提示词和视频的滚动异步调度:[references/async-pipeline.md](references/async-pipeline.md)
@@ -59,7 +59,7 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
59
59
 
60
60
  生产环境认证优先使用 MemHub;CLI 通过浏览器 PKCE 登录或个人 API Key 访问,只有本地明确关闭 MemHub 时才使用 Supabase 兼容登录。
61
61
 
62
- 把 `ai-short-studio` 当作机器可读的远程控制接口。目标、素材含义、平台、语言、画幅、时长、风格、人物、场景、道具、模型、实时 schema、候选版本、付费范围或覆盖影响存在未知、缺失或矛盾时,合并询问最少必要问题;得到答复前只做只读检查。不得用示例值替用户作创作决定。节点 `prompt` 只能补充创作意图,服务端会把语言与最终结构合同追加在它之后,冲突时以后置合同为准。
62
+ 把 `ai-short-studio` 当作机器可读的远程控制接口。目标、素材含义、平台、语言、画幅、时长、风格、人物、场景、道具、模型、实时 schema、候选版本、付费范围或覆盖影响存在未知、缺失或矛盾时,按决策依赖分批询问必要问题;得到答复前只做只读检查。不得用示例值替用户作创作决定。节点 `prompt` 只能补充创作意图,服务端会把语言与最终结构合同追加在它之后,冲突时以后置合同为准。
63
63
 
64
64
  优先使用一次 `canvas inspect` 聚合查询。同阶段可合并的 settings、节点和连线分别使用 `canvas settings set --file`、`canvas apply`、`canvas node update-many`。生成链使用单个调度循环滚动提交,不用 `--wait` 把整批阶段串行化:节点一完成就刷新画布并立即提交它已就绪的下游节点。默认每类并发 4、总并发上限 16;同一节点同一输入指纹只允许一个在途任务,不并发启动多个相互竞争的调度器。409 重读并审阅差异;schema 和业务检查错误进入恢复链路,能修正的自主修正后继续。401/403、供应商余额等无法自主修正的问题报告准确原因,继续不依赖该节点的工作。
65
65
 
@@ -90,3 +90,13 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
90
90
  任务成功只代表服务端完成,不代表创作合格。每批产物都要回读任务、画布、连线、资产和最终配置并查看真实预览;完成来源、区间和渲染技术校验即可交付文件;未做内容审计时如实标注,不等待审核批准。
91
91
 
92
92
  分镜图完成后不会自动添加 `storyboard-video-prompt` 节点。只有用户制作范围需要视频提示词时,按实时节点目录按需添加并连接;仅生成分镜图时不创建该节点。项目列表的封面可能回退到首个已有图片资产,仅用于展示,不表示项目已设置封面或已通过审核。
93
+
94
+ 导演台 v3 的原生工程编排和保存使用 `canvas director`;操作前读取 `references/canvas-previs.md` 的「导演台 v3」合同,新建和 Skill 只提供 v3,v2 历史工程由网页兼容查看。
95
+
96
+ 导演台只提供新增 v3 节点后工程编排的方案,不引导轻量后端预演。Agent 不执行图片或视频导出,保存回读后请用户打开导演台,通过原有导出窗口选择画布(默认)或本地下载。
97
+
98
+ ## 制作选择与提问节奏
99
+
100
+ 每题只处理一个独立决策,不能把模型、分辨率、字幕、配乐等捆绑成一道题或套餐选项。常规每批 1–3 问,每次最多 4 问;超过时按依赖分多批,前批真实作答后再根据答案提出下一批。不要一次列出所有后续问题,也不要并发堆积待答批次。已确认选项和自由文本中的明确选择在后续及会话恢复时复用;未作答不是接受推荐值。
101
+
102
+ 首次确定视频生成方案前,先读取实时模型、分辨率选项及 video-upscale 专用节点能力,核对用户已有选择。方案未确认时必须询问是否采用“低分辨率生成后超分”;只提供真实可用的“低分辨率生成后超分”“直接以支持的较高分辨率生成”“保持低分辨率、不超分”选项,说明增加处理步骤、源画面细节与超分效果的取舍,不编造价格、耗时或输出尺寸保证。用户已明确选择或授权采用推荐方案时沿用,不重复提问;能力变化使方案不可用时只询问替代选择。选择记录在现有制作计划和对话中,不自造画布配置字段。
@@ -1,217 +1,54 @@
1
- # 轻量预演
1
+ # 导演台 v3 工程编排
2
2
 
3
- 深度图与法线图现在统一使用黑色空背景,排除 HDR 天空、渐变和主图底色;辅助通道渲染成功或失败后都会恢复原材质、背景和光晕可见性。正式后台渲染专项覆盖雕刻、内置 HDR、独立灯具和光晕,验证主图变化且辅助通道不受照明污染;验证范围为主机软件 Chromium,未替代 Alpine 或真实任务队列验收。
3
+ 导演台需求只新增 director-compose 节点并设置 config.editorVersion="v3",不向用户提供轻量后端预演或后台渲染方案。
4
4
 
5
+ ## 导演台 v3:原生编排与浏览器导出
5
6
 
6
- 原生修复候选与提示补丁的评分已包含冻结场景中的附着体碰撞:使用同一世界变换和原生 `compareQa` 规则,附着诊断与原生诊断共同参与候选接受/拒绝判定;仍保留原生总严重度与问题组的取舍规则,不保证每项诊断单独下降。`compilation.repair.qaScope=native-and-frozen-scene-attachments`,`attachmentRepairCandidates=false` 表示目前复用原生候选,不生成移动附着点、解除附着或新的抓取约束补丁。附着诊断仍为只读 `qa.attachments`,只汇总一次;最终时间编辑后的 QA 仍另行重测,不宣称自动修复后处理或多人约束。
7
+ 新建导演台统一使用 v3,复用 `director-compose`,在新节点 `data.config` 设置 `editorVersion: "v3"`。不要新建 kind,不转换已有 v2 工程。人工入口是新增菜单「导演台 v3」,页面为项目下 `director-desk-v3?canvasNodeId=<真实节点ID>`。
7
8
 
9
+ 1. `canvas director <nodeId> --project <projectId>` 读取 `document`、`versionId`;未保存节点返回 `template` 供首次编排。写入前 inspect 真实画布版本。
10
+ 2. `canvas director <nodeId> --project <projectId> --operation document.replace --file request.json`。文件包含 `{expectedCanvasVersion,expectedVersionId,document}`;首次 `expectedVersionId` 为 null,document 采用回读的原生工程。其 format 是 director-desk,version 是 3;不要与上游软件版本 0.5.2 或 v2 工程混淆。
11
+ 3. 局部操作使用同一命令的 `entity.upsert`(完整 `entity`)、`entity.delete`(`entityId`)、`scene.update`(`scene` 补丁),可指定 `sceneId`,默认当前场景;都携带读取后的双版本基线。实体保持原生字段,姿态在 pose/poseKeys、动作在 clips、走位在 path,机位参数在 camera,切镜在场景 cuts。先读取真实结构,不猜字段、内置资产 ID、动作 ID 或单位。删除仍被引用的实体会被拒绝,需显式修改相关引用。
8
12
 
9
- 多动作帧图、视频和导出现在对全部冻结动作的最终时间线重测人物胶囊碰撞,报告为 `previs-motion-set-qa.v1`,`scope=person-capsules-only`、`fullMotionQaRechecked=false`、`autoRepair=false`。每个角色使用自己的正式编译规格及接触允许项,不修改源动作 QA。完整报告只保存于第一个正式输出版本,节点回执只保存汇总;任何来源选版变化使报告 `available=false`。网页输出节点提供报告入口;CLI 使用 `canvas previs read <nodeId> --project <projectId> --qa --json`,内置助手使用 `canvas_previs_read` 的 `mode=qa`。必须检查 `available`、逐角色 `uncheckedCharacterIds` 和问题组,不能把未测代理角色或人物胶囊通过当成完整动作 QA、联合求解或自动修复通过。该入口仅对实际生成联合报告的帧图、视频和导出节点有效;单动作使用原有 `--motion`/`mode=motion` 报告。任务总预算在骨骼采样前检查,超出时报 `PREVIS_PEOPLE_BUDGET_EXCEEDED`。
13
+ 完整模型包存于平台对象存储,读取时恢复并执行原版校验;不手写临时 URL。本地新模型导入目前由网页完成,CLI 没有独立文件上传子命令。导出的媒体登记在导演台节点版本,现有 scene 图片端口和 video 视频端口可直接连接下游。
10
14
 
15
+ 原生 v3 写入校验要点:保留顶层 `format:"director-desk",version:3,name,activeSceneId,resources,scenes`。每个戏段只含 `id,name,state`(可选 `origin`),`references` 属于 `state`,不是戏段顶层。完整保留回读的房间、灯光、实体字段及空数组。路径格式为 `{smooth:false,points:[{time:0,position:[x,y,z]},{time:3,position:[x,y,z]}]}`,时间单位为秒,不能使用 `{x,y,z}` 点。实体 `rotation` 为弧度,`pose/poseKeys` 的关节角度为度,不得将属性面板显示的旋转度数直接写入实体;新增非机位实体的 `camera` 必须为 null。格式错误返回 `DIRECTOR_V3_DOCUMENT_INVALID` 和原生 `reason`,先修正结构再发新调用;只有明确失败才能重试,unknown 必须先核对原调用回执。
11
16
 
12
- 预演帧图/视频/导出节点的 motion 端口现允许连接最多16个不同角色的正式动作节点。所有动作必须来自同一冻结场景,统一24 fps且最终帧数一致;重复角色、重复来源、同一物体的多个驱动、错版或附件总量超过128 MiB明确拒绝。任务冻结并复核每个来源,任一来源换版使旧结果失效。人物骨骼、物体轨道、骨骼附着和镜头目标按同一合并时间线采样。导出按相同顺序保存全部引用及 motion-001/002 等报告和附件,原单动作文件名保持不变;导出总字节上限仍为64 MiB。媒体来源按完整动作版本组匹配,连线顺序可不同。物理预览仍只接受单动作;多人联合碰撞QA见上方最新说明,联合求解尚未完成。 使用现有节点创建/连线和执行入口;不把多个动作附件直接写入节点配置。
13
17
 
14
- 用 `canvas node types` 核对当前开放节点。创建和连线复用画布命令,不使用旧导演台。
15
18
 
16
- `canvas previs read <nodeId> --project <projectId> --json` 返回场景和 `base`。把完整 base 原样写入操作文件,运行 `canvas previs apply <nodeId> --project <projectId> --file edit.json --json`。
19
+ v3 当前原版为 Shotloom React 编辑器(平台仍称 v3),工程容器仍是 `format:"director-desk",version:3`。机位可在 `camera.focalKeys` 写入 `[{time:0,value:40},{time:4,value:24}]`,时间为秒、焦距为 8~300 mm;通过完整实体 `entity.upsert` 保留其余字段。人物参考模型随平台提供,既有姿态和动作驱动其骨骼;不能把 GLB 内嵌动画名称当成原生动作 ID。截图和视频仍需打开对应页面、处理未保存编辑,并确认媒体登记成功;模型加载失败会阻止宿主导出。旧本地备份仅显式恢复,不能据本地备份完成宣称服务端保存成功。
17
20
 
18
- 文件结构为 `{ "base": { "canvasVersion": 1, "nodeVersion": 0, "sceneVersionId": null }, "actions": [{ "type": "project.rename", "name": "预演" }] }`。示例版本必须替换成实际读取结果。历史恢复用 `restoreVersionId` 替代 actions。共享服务严格拒绝未知操作、字段和任意脚本;409 后重读并审阅,不自动换基线重试。
21
+ ### v3 能力发现与无副作用预检
19
22
 
20
- 保存追加不可变版本;下游已有结果保持可用,不自动渲染。帧图和视频执行复用 `canvas node execute`;只使用实际生成的输出角色,不把首尾帧和辅助通道混为第一张图。预演不自动成为身份依据或审核通过记录。
23
+ `canvas director <nodeId> --project <projectId> --operation capabilities.read --query <关键词>` 查询原版资产目录、动作、单位和示例;默认最多25条,检查 total/truncated。`--asset-id <真实ID>` 返回 `asset.template` 完整实体和资产能力;摄影机使用 camera。模板 id 必须替换为工程内唯一值,保留其余原生字段;不要猜测资产名称或动作 ID。actions 同时提供推荐单次 duration 和 loop。
21
24
 
22
- `canvas previs upload <nodeId> <imageFile> --project <projectId> --base base.json` 上传 PNG/JPEG/WebP 参考图,最多 16 MiB,`base.json` 仅保存 read 返回的完整 base 对象。服务端重新解码为 PNG 并按正式字节计算内容哈希,素材资产、来源版本和场景绑定同事务保存。移除绑定提交 `asset.remove {assetId}`,assetId 是场景 assets 中的绑定 id;不删除历史素材。参考图用于存档和工程导出,不自动进入画面;仅存档的参考图不会阻止已适配场景渲染。模型和 HDR 需走各自的正式适配入口。
25
+ 道具优先复用原生资产:先按物体名称及同义词查询目录,检查 total/truncated,再取真实 ID 的完整模板。库中有适合的自行车、车辆、货架、桌椅等模型时,直接使用该模型,不用 cube/cylinder 等基础几何重新拼造;仅在没有合适资产或需要特定建筑尺寸时使用灰模,并说明原因。替换拼装件需显式清理旧组件与引用,核对真实边界、落地、前进朝向和人物接触;模型存在不代表自动具备踩踏、抓把或上下车约束,仍须检查实际画面。
23
26
 
24
- 内置助手已吸收相同版本、冲突、角色及审核规则,使用 `canvas_previs_read`、`canvas_previs_apply` 和 `canvas_execute`。内置助手不能直接上传本地文件;动作编译及导出可通过对应节点的现有创建、配置、连线和执行入口完成。
27
+ `--operation document.validate --file candidate.json` 预检完整候选。文件包含 document、expectedVersionId、expectedCanvasVersion。返回 valid、issues(path/entityId/reason)、nativeReason 和当前版本;不保存、不上传资源、不推进画布版本。valid=false 按字段修正;valid=true 后另行 document.replace 保存并回读。原生校验为最终依据;预检不能代替保存时权限/资源哈希/版本检查或视觉审核。
25
28
 
26
- 导出创建 `previs-export`,将场景连到 scene、匹配的可选动作连到 motion。config.previs 为 `{sceneId,formats:["project"|"otio"|"usd-camera"|"media"|"frame-pack"],shotIds?:string[]}`,formats 至少一项且不重复。省略 shotIds 导出全部镜头;工程保留全部场景,筛选只影响 OTIO/USD。使用 `canvas node execute` 显式提交并等待成功,再用 `canvas previs read <nodeId> --project <projectId> --export --json` 取得 file(ZIP)和 manifest(JSON)的真实版本及短期下载链接;不能同时传 --motion。链接到期后重新读取,不写入工程。工程格式的 ZIP 包含全部正式绑定的原始素材文件、平台场景合同和原生 cclayproject;原生工程内嵌实际引用的物体模型、纹理和 HDR,保留来源版本及完整动作 QA。角色 FBX 原字节随包保存,但原生角色恢复仍需对应模型加载器,manifest.nativeWarnings 会明确标记。来源字节合计最多64 MiB,逐个核验权限、冻结版本和实际 SHA-256;不支持的绑定拒绝导出。骨骼根路径的 OTIO 布局须连接匹配动作,纯工程可保留未编译的路径意图;keys/follow/rail 相机使用正式共享采样;媒体和首尾帧包通过对应的 image、start-frame、end-frame、depth、normal、video、contact-sheet 输入接收正式预演帧图/视频节点的同名输出(可多连);不接受普通生图/视频节点或角色串接。media 保存原始媒体,frame-pack 为每个所选镜头生成原生帧包,clip 必须有准确起止帧,still 仅需起始帧并保留 hold。视频须覆盖完整所选镜头,辅助通道须采样镜头起始帧,分辨率须一致;缺端点、歧义角色、未消费输入及来源场景/动作不匹配均拒绝。绑定与实际字节 SHA-256 冻结到任务,来源节点编辑或换版后旧任务不能回写;缺少历史媒体哈希时需重新渲染,不猜测或补造哈希。帧包灰模只提供构图/运动参考,camera.json 标记 identityReference=false,prompt.txt 只是已写镜头备注,不是已通过模型门禁的最终提示词。助手已吸收配置、执行、版本和缺口规则,用 `canvas_previs_read {nodeId,mode:"export"}` 读取文件版本及大小;助手工具不提供下载链接或本地文件保存,不能照搬 CLI 参数。
29
+ Clip 完整必填形态为 `{id:"walk-1",action:"walk",start:0,end:3,speed:1}`。单次跳跃等按 actions 推荐时长编排,不将一段 jump 任意拉长;根路径位移与姿态动画分别处理,避免腾空位移重复叠加。转弯使用过渡途经点,停步/骑乘/蹲身避免持续沿路滑行。
27
30
 
28
- 动作编译:创建 `previs-motion`,将已保存场景的 `scene` 输出连到动作节点 `scene` 输入。节点 `config.previs` 使用类型目录返回的 schema,指定 sceneId、characterId、model(x-bot-tpose/y-bot-tpose)和原生 24 fps spec,可选 repair、probes 和 bake(yaw 单位为度)。调用现有 `canvas node execute` 显式编译;保存配置不会执行。`canvas previs read <motionNodeId> --project <projectId> --motion --json` 返回正式报告、完整 QA、available 和 capabilities。available 只表示版本有效,QA 失败不变成通过,报告不代表素材已审核。场景换版后应重新编译;网页动作节点可显式打开有效版本的编译动作播放,提供 24 fps 播放、暂停和跳帧;播放不提交任务。
31
+ 复刻参考视频先按时间采样并明确动作/道具/切镜,不默认压缩时长或固定间隔切镜。内置助手不能直接接收视频附件或上传本地GLB;应提供带时间戳采样图,明确未观察区间和近似部分。关键帧图片实际观察通过后再导出整段;媒体成功登记和视觉还原质量分别验收,导出成功不能代替画面审核。
29
32
 
33
+ V3 的 asset.poseContract 返回真实关节、角度单位与可校验示例。俯身、摆臂和屈膝使用以关节名为键的 pose、{time,pose} 的 poseKeys,不能套用 v2 bones/rootY 外壳;姿态叠加在原生动作上,需另行观察脚部接触与身体朝向。
30
34
 
31
- 角色模型上传:`canvas previs upload <nodeId> <model.fbx> --project <projectId> --base base.json --scene <sceneId> --character <characterId> --model x-bot-tpose`,也可显式指定 y-bot-tpose。目标角色须已保存在场景中,三个绑定参数必须同时提供;二进制 FBX 上限 32 MiB。仅上传有权使用的素材,不自动下载或随平台分发第三方模型。服务端隔离进程校验文件结构、解压预算、蒙皮与固定骨架,拒绝贴图和外链资源;通过后原子创建 FILE 来源版本、更新角色型号并保存场景。替换绑定保留历史来源。已有模型绑定时,不能通过 character.update 把型号改为另一个骨架,须上传替换模型或先显式移除旧绑定。原生角色的静态姿态已可走正式帧图/视频节点后台渲染:任务按场景绑定的固定来源版本读取模型,核验权限与实际字节哈希,经隔离进程送入软件 Chromium;素材当前选版不影响冻结来源。仅支持当前已适配的原生 X/Y 灰模与姿态;网页已能从正式绑定加载静态角色;网页动作节点可显式打开有效版本的编译动作播放,提供 24 fps 播放、暂停和跳帧;播放不提交任务。
35
+ - V3 道具布局先查询 asset.localBounds:它是原生默认工厂几何在实体变换前的真实 min/max/size。不同资产原点不一定居中,不能统一按半高度设置 position.y;根据边界、缩放及旋转安排落地、门洞净空和通道宽度。参数改变后默认边界不代表当前尺寸,最终仍需截图检查。
32
36
 
37
+ ### v3 自然度审计与脚部接触
33
38
 
34
- 编译动作渲染:读取动作报告确认 available=true,并如实保留 QA;将同一已保存场景的 scene 输出接到帧图/视频节点的 scene 输入,将动作节点的 motion 输出接到它的可选 motion 输入,再显式执行渲染。一次最多一份编译动作,角色必须已有正式 X/Y 模型绑定。采样帧和视频结束帧必须小于动作 frameCount;不自动循环、裁剪或换用其他场景。任务冻结场景、动作及模型来源版本,任一来源换版或节点编辑后旧结果不能覆盖当前输出。QA 可失败,渲染成功也不表示已审核。
39
+ 能力查询的 actions.cycleDuration 是真实原生步态周期,duration 是推荐片段长度,两者不能混淆;motionContract 同时声明 actionBlend(0–2秒,默认0.2)与脚部接触范围。审计应联合检查实际路径米/秒、片段 speed、姿态、heading 和原视频抽帧。
35
40
 
41
+ 内置 crouch 只是低姿态保持,不是蹲行。穿低门可用 walk 叠加随时间变化的躯干/髋膝姿态,再显式设 entity.footContact=true。嵌入模式参考人体仅在平地内置 walk/run 上启用有限的支撑脚约束;walk 屈膝姿态按鞋底落地,奔跑保持腾空。此约束不改根路径,修正受腿长及 min(0.35m,height*0.2) 限制,未覆盖斜坡/外部动画,也不做碰撞检测,仍须观察实片。人工无需新增 Agent 文档或审批。
36
42
 
37
- 动作报告的 playback 能力表示网页可用的只读预览;CLI/助手没有图形播放工具,仍通过正式执行生成媒体供检查。预览会核验冻结场景、角色、模型和动作附件;过期版本或场景时间线不足会拒绝,不自动裁剪、换版或重新编译。新动作或场景选版生效后须重新读取 available,旧 QA 可以查看但不能作为当前输出。
43
+ 离座先转移重心与落脚,再离开座垫、加速,不能让 standup 在高速移动中冒充下车;转角增加路线和 heading 过渡,摄影机沿可通行区域跟进;多人工作区按原片时间校验站位与道具接触。只调步频无法保证支撑脚不滑,静帧不能证明连续自然度。
38
44
 
45
+ 连续同速同动作的路段优先合并片段,不按机位或路径路点重新 start,避免步态周期与落脚约束重启。必须保留原生拆分时,同步保留 offset、progressOffset、sourceDuration,预检后检查拆分前后的相位;不能只加大 actionBlend 掩盖相位错误。
39
46
 
40
- 原生角色静态 FK:用共享 `character.update {sceneId,characterId,patch:{pose}}` 写入姿态。pose 为 `{id,label,prompt,bones,rootY?}`;bones 键使用 hips/spine/chest/upperChest/neck/head、lShoulder/rShoulder、lArm/rArm、lForeArm/rForeArm、lHand/rHand、lUpLeg/rUpLeg、lLeg/rLeg、lFoot/rFoot,每个值为 XYZ 原生弧度三元组,rootY 为模型骨盆局部高度偏移(厘米)。代理角色不支持骨骼姿态。不要把网页显示的角度直接写成弧度,也不把静态姿态当成已编译动作。
47
+ 完整 v3 工程必须保留 document.read 返回的 format: director-desk 与 version: 3,按回读对象修改,不能重组时遗漏根版本。多戏段格式被拒绝时先检查 issues 的 format/version 路径;这不表示不支持完整工程预检,也不能据此跳过校验或静默补版本。只改少量实体可用正式 entity.upsert,但仍须保留其余字段并回读确认。
41
48
 
42
- 项目姿态库使用 `pose-library.save {pose}` 按显式 ID 保存/更新,`pose-library.remove {poseId}` 删除;两者均不带 sceneId,仍使用完整 base 保存为新工程版本。读取 `scene.project.poseLibrary` 后复制完整姿态到目标角色即可应用;角色持有独立快照,库修改/删除不会改变已经摆好的角色。最多 500 条,不使用 localStorage 或 IndexedDB 作为正式来源。网页支持关节数值编辑、自然/绑定姿态、另存和删除;动作范围关键帧和姿态照片制作仍待适配。
43
49
 
50
+ 人物 pose/poseKeys 是追加角度,必须从原生动作基线求差,不能把最终目标角度直接写成增量。例如当前原生 sit 的肩 X=-24°、肘=-66°、髋=-88°、膝=90°;再追加肩 +45° 会变成 +21°、把手臂转向后方,追加膝 +75° 会过度折叠到165°。肩向前伸和肘屈曲的 X 方向为负;通过实际截图核对手与车把、臀与座垫、鞋与踏板,不把“手抬起”当作接触成功。接触约束按当前源动作区间判定平地,前段骑乘升降不禁用后段平地;当前斜坡和高度过冲仍不锁脚。
44
51
 
45
- 静态 IK 使用 `character.solve-ik {sceneId,characterId,track,kind,target}`:track 为 leftHand/rightHand/leftFoot/rightFoot,kind 为 end(手腕/脚踝)或 mid(手肘/膝盖),target 为世界坐标米制 XYZ 三元组。只支持固定 X/Y 原生骨架,保留角色位移、朝向、比例、根高度及无关关节,结果存为静态 FK 姿态,可再保存到项目姿态库。原生求解器限制不可达目标;不自动避碰、贴地、审核或改写编译动作。操作同样需要读取后的三重基线,冲突须重新读取,渲染仍显式调用正式节点执行。
52
+ 新建入口和 Skill 只提供 v3 操作;v2 历史工程保留网页兼容,不通过助手改写或自动迁移。跑步先使用原生 run 动作,避免骑乘/下蹲的肩肘髋膝姿态叠加到跑步段;取完整步态周期的前、侧视图核对对侧摆臂、屈肘和支撑/腾空相位。
46
53
 
47
-
48
- 网页可显式启用「视口摆姿态」:四肢末端圆点、肘/膝方点沿当前相机平面拖动,方向键每次移动 5 厘米;松手生成一条相同的 character.solve-ik 操作。手势中临时预览不保存,Esc、指针取消或失焦恢复原姿态,单步撤销可回退整次手势。画面黑边不计入目标坐标,控件不写入导出的图像。附着角色暂不支持 IK;当前 still 镜头有 cast 覆盖时须显式选择镜头范围,基础范围不会覆盖它;此入口不修正编译动作。CLI/助手继续提交世界坐标操作,没有鼠标手势工具。
49
-
50
-
51
- 静帧镜头姿态:`shot-cast.update {sceneId,shotId,characterId,patch}` 只接受 x/z(米)、rot(度)、posture 和 pose;必须是存在的 still 镜头与场景角色。创建覆盖会补齐上游要求的 x/z/rot,保留其他人物、镜头、基础角色和已有部门字段。`patch:{pose:null}` 仅移除该镜头的姿态覆盖,继承基础姿态并保留位置;`shot-cast.remove {sceneId,shotId,characterId}` 清除该人物的整个镜头覆盖。`character.solve-ik` 可显式带 shotId,按该镜头覆盖后的位置求解并保存到该镜头;省略 shotId 始终编辑场景基础姿态,不根据当前播放头猜写入范围。网页数值和拖动共用该规则,基础姿态被当前镜头覆盖时会提示。镜头不存在、非 still 或附着角色的 IK 明确拒绝;所有写入仍走三重版本校验,旧动作结果随场景换版过期。
52
-
53
- 对象与角色分组已接入共享操作:`object.set-parent {sceneId,objectId,parentId}`、`character.set-parent {sceneId,characterId,parentId}`;parentId 为同场景对象 ID,null 回到根级。分组保留世界坐标,移动/旋转父级带动成员,缩放独立;隐藏父级会隐藏后代,删除父级将直属成员提升到根级并保留位置。网页父级选择、层级列表与撤销使用同一合同,循环、悬空父级及冲突附着明确拒绝;分组角色暂不支持静态 IK,需先解除分组。动作附着/碰撞约束仍未闭环。
54
-
55
- 物体路径使用 `object.set-path {sceneId,objectId,path}`,path:null 清除路径但保留基础变换。path.points 为 2~64 个世界坐标米制 {x,y,z},x/z 在 ±240、y 在 0~60;speed=0 铺满场景时间线,正速度为 0.01~50 米/秒,faceTravel/loop/extend 控制朝向、循环及终点延伸。可传最多 6 个递增 marks(t 弧长比例,端点间距至少 0.03,bank/pitch 为 ±90 度)及 timing(递增 cuts[{t,d}]、每段非负 envelopes)。白名单校验后复用原生 Catmull-Rom、弧长及速度归一化;不接受脚本和未知字段。网页数值编辑点位和开关,高级区编辑 marks/timing,应用到草稿后再保存。基础位置平移会连同路径一起移动,分组成员随原生刚体矩阵运动,编译物体轨道优先;不会自动渲染、避碰或生成动作。附着物体须先解除附着;人物根路径见下述路径点合同;命名抓取插槽见下述合同;附着感知自动修复仍待接入。
56
-
57
- 人物根路径通过 `character-waypoint.set {sceneId,characterId,waypoint:{id,frame,x,z,heading?}}` 按稳定 ID 创建/修改,remove 用 waypointId,clear 清空。layer.waypoints 最多32点,x/z 为米制±11,帧从1开始且小于场景总帧数、同帧唯一,24 fps;点间至少8帧、移动速度0.5~3米/秒,5厘米内可停留。代理角色继续使用原生路径插值并优先于 still 覆盖。X/Y骨骼角色保存路径点后不自动平移骨骼或生成步态,静态编辑预览不代表动作;请显式编写原生 standIdle/walkTo 等动作规格并执行 previs-motion,帧数必须覆盖全部路径点。编译 qa.rootPath 比较帧0和每个路径点的真实渲染骨骼根位置(容差0.1米)及显式 heading(容差10度);heading:null 不要求朝向。位置/朝向未满足会合并总 QA,原生 QA 不被覆盖,报告 scope=authored-waypoint-frames-only、autoRepair=false;不是连续轨迹拟合或自动修复。父组的运行时路径随原生携带矩阵作用于目标及动作,静态编辑父组仍保留世界路径点,不能拿旧动作当新版本。正式出图和 OTIO 布局须连接匹配动作;帧图/视频/导出可连接多角色动作,多角色骨骼路径缺动作会明确拒绝。纯工程导出保留路径意图,可不带动作。没有原生外部路径生成服务,不调用或下载第三方模型。
58
-
59
-
60
- 运镜共享操作:`camera-block.set {sceneId,shotId,camera}` 整体设置镜头的原生 Camera Block,mode 为 keys/follow/rail;保留镜头关键帧,切回 keys 可继续编辑。follow 默认跟随场景首位角色(原生 charA 语义),读取分组后的世界位置及编译动作髋部。followCam 支持 distance(0.5~15 米)、height(至少 0.2 米)、response(0.1~3 秒)、lead(0~1 秒)、railStartMode(head/nearest)、maxDollySpeed(0.2~40 米/秒)、pitchOffsetDeg(±170)、orbitOffsetDeg(±180)。rail 必须给 cameraRail 的 2~512 个非退化世界 x/z 点;railFollow 可省略/null(全镜头)、`{mode:"range",startFrame,endFrame}`(镜头内相对帧,24 fps,至少 10 帧)或 `{mode:"off"}`。轨道区间外、关闭或镜头不足 10 帧时使用保留的关键帧。craneHeight 为 `{points:[{t,height}]}`,2~8 个严格递增标记,t 从 0 到 1、高度至少 0.1 米;dollyTiming 使用 cuts/envelopes 的原生速度曲线结构。aim 可为 `{ids:[演员或物体ID],height?}`(最多四个且不重复)或 `{point:{x,y,z}}`;focalMm 为正毫米焦距。缺失目标、非法模式/范围/参数、退化轨道明确拒绝,不执行脚本。相机离线积分与网页、后台、OTIO/USD 和帧包共享;轨道准备限制 frameCount×(物体数+人数)不超过 2,000,000,超限须拆场景。网页有模式和跟随参数控件,高级轨道配置用 JSON;应用到草稿后仍需显式保存和执行,保存不触发渲染。CLI/助手走现有操作入口与三重基线,不需打开面板,也没有鼠标绘制轨道工具。
61
-
62
-
63
- 故事板/联系表:帧图和视频节点的 config.previs 支持 `contactSheet:{columns:1..6,shotIds?:string[]}`,省略 shotIds 选择全部镜头;最多 96 镜,按时间顺序冻结实际镜头 ID,以每镜起始帧采样。联系表每格 320×180,输出实际尺寸为 columns×320 和 ceil(镜头数/columns)×180,任一边不超过 8192;空列表、缺失/重复/越界镜头和超尺寸明确拒绝。可以只配置 `captures:[]` 与 contactSheet,不必额外生成 image。正式图片版本使用独立 `contact-sheet` 输出,不能把它当首帧/尾帧;连到预演导出的同名输入,配合 formats:["media"] 可保存原始联系表,不参与 frame-pack 端点选择。联系表包含名称、时长与镜头备注,格线、编号、文字和界面元素不得带入最终图片/视频;板型仍由项目 storyboard_strategy 决定,灰模不提供人物身份、不自动审核。
64
-
65
- 视频节点可显式配置 `animatic:true`:still 镜头在其原生区间内保持整个起始场景图(人物、背景物体和相机一起保持),clip 继续按 24 fps 采样;false/省略维持原有逐帧预演。必须有 video 区间,区间内不能有空白镜头;动作附件仍须满足正式帧范围,不循环或静默延长。标题/备注只进入联系表,视频没有板线和控件。网页提供联系表、列数、镜头 ID 与 animatic 配置;CLI/助手使用现有节点配置、canvas_execute 和正式版本读取,无鼠标编辑或本地下载能力。全部操作仍需先保存正式场景、冻结版本、显式执行;配置保存不启动渲染。
66
-
67
-
68
- 基础几何体材质通过共享 `object.update {sceneId,objectId,patch:{material,finish}}` 编辑,保存仍需三重基准版本。material 可选 clay、wood、straw、stone、brick、concrete、metal、glass、ceramic、plastic、rubber、fabric、paper、foliage;finish 可选 matte、satin、gloss。传 null 仅清除相应覆盖,未传字段保持原值;基础色仍由 patch.color 控制,默认灰采用原生材质底色。空组不接受材质,不把该能力用于代理角色或 FBX 蒙皮材质。纹理颗粒、玻璃厚度和反射由原生材质实现,渲染仍须显式执行。内置 HDR 另由 stage.update 设置;外部 HDR 使用正式素材绑定。
69
-
70
-
71
- 灯光通过同一 actions 入口编辑:`stage.apply-lighting {sceneId,preset,keep?}` 应用 studio、day、overcast、golden、dusk、night、interior、stage 八种原生预设;keep 可保留 keyLight.position/intensity/color,或 lighting.sky/skyTop/ambient/hemiSky/hemiGround/fill/fog/exposure/shadowSoftness/envLight/ao/hdr。保留 lighting.hdr 同时保留 HDR 选择、旋转、强度及背景开关,外部 HDR 还须有正式素材绑定。未保留的项目按原生预设重置。
72
-
73
- 局部修改使用 `stage.update {sceneId,patch:{keyLight:{x?,y?,z?,intensity?,warmth?,color?},lighting:{sky?,skyTop?,hemiSky?,hemiGround?,ambient?,fill?,fog?,exposure?,shadowSoftness?,envLight?,ao?,hdr?,hdrRotation?,hdrIntensity?,hdrBackground?}}}`;两个嵌套对象只合并已传字段,不整体覆盖其他设置。位置用米;x/z 为 -30..30,y 为 0.5..30;主光强度 0..4,暖度 0..1;ambient/fill 为 0..3,雾/阴影柔度/AO 为 0..1,曝光为 0.2..3,环境贴图光强为 0..2。颜色为 #rrggbb;keyLight.color 为 null 恢复暖度控制,sky 为 null 恢复默认背景,skyTop 为 null 关闭渐变,半球颜色不接受 null。程序化天空环境、渐变和 AO 共享前后台渲染,辅助深度/法线不经过 AO。内置 hdr 仅允许 builtin:night-street、builtin:overcast-field、builtin:studio-softbox,null 关闭;hdrRotation 为 -180..180 度(180 规范为 -180),hdrIntensity 为 0..4,hdrBackground 为布尔值。背景亮度由 hdrIntensity 控制,表面环境光由 hdrIntensity × envLight 控制;关闭背景仍保留环境照明。内置环境由固定源码程序生成,不下载模型或贴图。外部环境贴图使用已正式绑定的 hdr- 加32位哈希 ID;仅可选择当前工程 assets 中 purpose=hdr 的绑定,禁止 URL 或未上传 ID。支持 HDR/EXR/PNG/JPEG,最大32 MiB、16,777,216像素;解码宽度最多2048,原文件字节及来源版本固定,签名链接执行时生成。关闭 HDR 保留绑定,asset.remove 会清除引用它的场景选择;保存不自动渲染。
74
-
75
-
76
- 独立灯具通过 `object.add {sceneId,kind:"point-light"|"spot-light",placement?}` 创建,使用已有对象位置、旋转、隐藏、分组及路径操作。灯具没有几何体,不能设置材质。用 `object.update {sceneId,objectId,patch:{light:{type?,color?,intensity?,range?,angle?,softness?,shadow?,flicker?,aim?}}}` 局部修改;不向普通对象写入 light。type 为 point 或 spot,color 为 #rrggbb;intensity 0..1000,range 0..100 米(0 表示不限距离),angle 1..89 度为聚光半角,softness/flicker 0..1,shadow 为布尔值,aim 为世界坐标 `{x,y,z}` 或 null(恢复灯具自身下方向)。只有聚光灯使用 angle/softness/aim;切换类型保留已有数值。闪烁按对象 ID 和 24 fps 帧地址确定,不依赖播放历史。
77
-
78
- 最多两盏未隐藏的独立灯具投影,按工程对象顺序决定;其余仍照明,工程中 shadow 请求保持为 true,读取和保存回执的 warnings 用 SHADOW_CAP 列出受限灯具(附 sceneId/id/message,沿用上游每次最多四项)。网页同时显示完整受限列表。保存不自动渲染;自发光另用共享 glow 操作,见下文。辅助深度/法线不包含灯具标记,不随灯光强度或闪烁改变。
79
-
80
-
81
- 物体自发光通过 `object.update {sceneId,objectId,patch:{glow:{color?,intensity?,halo?}}}` 编辑。color 为 #rrggbb,intensity 为 0..20,halo 为 0..4;首次提供任一字段后,其余沿用原生默认值,后续局部合并;`glow:null` 关闭并恢复基础材质和投影。适用于基础几何体、空组及独立灯具,不写入 character。光晕大小随物体原生尺寸及缩放计算,空组/灯具使用原生点状半径。开启 glow 后物体不投影,光晕不写深度,不进入深度/法线;它只让自身发亮,不照明其他物体,需要照明时另加点光源或聚光灯。灯具上的 glow 随该灯的 24 fps 闪烁与动作 level 变化;其他物体随动作 level 变化。保存不自动渲染,不修改模型或提示词。
82
-
83
- 程序化雕刻使用共享 `sculpt.add {sceneId,name?,recipe,placement?}` 创建,已有雕刻用 `object.update {sceneId,objectId,patch:{recipe}}` 替换配方;普通对象不能写 recipe。recipe 遵守固定上游 v1 合同,含 parts、11 种形状、parent、mirror、颜色/渐变、材质、detail、scatter,以及子工具的 subtract/intersect。位置以米、旋转以度表示;完整配方必须通过共享校验,不接受脚本或未知参数。替换保留对象身份与外部变换,并重算占地尺寸。网页“程序化雕刻”页签与实体配方框使用同一操作,非法输入保留当前草稿和正式工程;撤销生成既有版本流程的新当前版本。布尔构建失败明确拒绝渲染,不静默跳过切割交付缺损参考。保存不自动编译或渲染。参考图比较与自动拟合尚未接入;助手无本地文件上传工具。
84
-
85
- 轮廓比较通过 `canvas previs compare <nodeId> --project <projectId> --file compare.json --json` 显式执行。JSON 为 `{base,sceneId,objectId,references:[{assetId,yaw?,weight?}],options?:{yaw?,elevation?,candidates?:[{label,edits}]}}`,base 必须来自最新 read;仅比较已保存的雕刻。references 使用工程已绑定的参考素材 ID,不能给 URL、data URL、任意媒体 ID 或本地路径;最多4图,多图每项必须给 yaw,单图省略 yaw 时沿用原生 -45..45 度寻角。yaw 为 -180..180,elevation 为 -60..60;weight 为0..1,未给时原生前/侧/后权重为0.6/0.25/0.15,比例偏离前视图35%以上的视图权重为0。最多12组候选,每组最多48项 `{set:id,...字段}`/`{add:part}`/`{remove:id}` 编辑,只排名不应用;拒绝的候选单独列出,sheetLabel 指明对照图使用的候选,report.iou 仍为当前配方得分。返回 base、authored:false、数值报告、轮廓测量和 PNG sheetDataUrl。轮廓为原生近似正交投影,不检查布尔孔洞、材质、身份或审核状态;不能用高 IoU 代替成片或模型 QA。灰色重合、红色缺失、蓝色多余。无主体、零有效权重、版本冲突明确报错,不自动换基准或应用赢家。计算在不携带主站凭据的可终止子进程中进行,60秒超时;保存不自动比较。网页实体面板使用同一入口;草稿未保存时不可比较。
86
-
87
-
88
- OBJ/GLB/FBX 物体素材通过 `canvas previs upload <nodeId> <model-file> --project <projectId> --base base.json --scene <sceneId> --object <objectId>` 显式上传,限 32 MiB;不能混用角色参数。不存在的物体 ID 会创建 mesh,已有 mesh 会换源并保留位置、旋转、缩放和历史来源,其他类型不能覆盖。上传前保存草稿并读取最新完整 base,冲突不自动重试。正式场景 assets 的 meshTarget 保存 sceneId/objectId,物体 assetId 指向绑定 ID;平台场景合同不内嵌模型字节,project 导出包携带原始素材。OBJ/GLB/FBX 由受限子进程检查,GLB 内嵌 PNG/JPEG/WebP 在像素预算内解码;拒绝外部 URI、未知必要扩展与未支持压缩。OBJ 的 MTL 名称只作元数据,不下载材质或贴图。网页按需预览与帧图/视频节点共享对应格式的解析和原生拟合;后台只读取固定正式版本,权限、MIME、大小和实际哈希均须通过。删除物体同时移除当前绑定,历史来源保留。通用物体 FBX 使用 --object,与需要 --model/--character 的角色 FBX 合同分开,接受二进制 FBX 或 7000–7700 版本 ASCII FBX,支持有界内嵌 PNG/JPEG/WebP 图片(每张最多 1600 万像素、合计 3200 万像素、最多 128 张);保留原生 UV、采样与颜色空间,拒绝外部图片。角色 FBX 入口仍要求无纹理二进制。独立 glTF、GLB 的 AVIF/data URI、FBX 的其他图片格式和外部 MTL/纹理尚未接入,不伪造绑定代替上传。
89
-
90
- 已绑定 mesh 另支持 `object.update {sceneId,objectId,patch:{height,clay}}`:height 为正数米值,按原生规则同步缩放占地,clay 为布尔值;其他物体类型不接受这两个字段。网页提供同一高度和灰模控制,编辑不重下素材,仍须保存并显式执行渲染。
91
-
92
-
93
- 文字物体使用共享操作 `object.add {sceneId,kind:"text",text?:{value,size,depth,align}}` 创建;`object.update {sceneId,objectId,patch:{text:{...}}}` 局部编辑已有文字。value 最多 200 个字符、8 行且不能全空白;size 为 0.02–10 米,depth 为 0–2 米,align 为 left/center/right。尺寸由原生排版测量,不手写 footprint;文字面向本地 +z,底部为 y=0。depth 大于零且全部为可打印 ASCII 时使用立体字,包含中文或其他字符时按原生行为保留平面文字。变换、分组、物体路径、保存、撤销和显式帧图/视频执行沿用现有合同;保存不会自动渲染。网页提供文字类型与内容、字高、厚度、对齐面板;助手通过现有 canvas_previs_apply 操作,无需打开面板。文字不能写到其他物体,未知字段和超预算输入拒绝。字体来自固定上游版本并保留原授权;目标镜像的中文字体仍须实际验收。
94
-
95
-
96
- 粒子效果通过共享 `object.add {sceneId,kind:"effect",effect?:{preset,...}}` 创建,`object.update {sceneId,objectId,patch:{effect:{...}}}` 局部编辑;不能把 effect 写到其他物体。preset 为 smoke、exhale、steam、fire、sparks、dust、rain、snow、trail。更换预设采用原生默认值并保留种子,显式参数覆盖新默认值;wind/area 支持 x/y/z 局部修改。参数包括 rate(0–2000/秒)、life(0.05–12秒)、size(0.001–5米)、grow(0.05–20)、speed(0–60米/秒)、spread(0–1)、gravity(-30–30米/秒²)、opacity(0–1)、width(0–10米)、seed(0–2147483647整数)、color(#rrggbb)、additive(布尔)、wind(各轴-20–20米/秒)、area(各轴0–100米)。拖尾配合 object.set-path 使用。效果按24 fps和种子确定采样,发射后的粒子保持世界空间运动,发射器缩放不改变粒子米制尺寸。全场景最多显示2000粒子和512段拖尾,超限由原生模拟器均匀抽稀;显示上限不代表CPU耗时上限。效果不进入深度/法线,不照明其他物体,也不包含操作标记。网页属性面板支持这些参数;CLI和助手走现有apply入口,渲染仍显式执行。当前绑定角色骨骼的发射器和正式逐帧效果统计读取尚未接通,不得伪造这些结果;这里只能读取工程配置和正式渲染产物。
97
-
98
-
99
- 道具套件使用 `object.create-kit {sceneId,kit,name?,position?:{x,y,z,rot}}`;kit 仅接受 cigarette、lighter、exhale、bat、ball、sword、pistol。整组原生零件一次创建且可整批撤销;根对象是握持点,所有零件保持原生米制比例和父组。返回 `actionOutputs`,其中 rootId、parts、bind、props(若有)和 skill(若有)可用于后续动作配置;这些结果随同正式场景版本存档,不能猜测 ID。按既有 motion 节点合同显式配置和编译,创建/保存不会执行任务。燃烧、枪口闪光等 showOnlyInTake 零件及呼气套件静态不可见;真实角色/队列/目标容器验收尚未完成,不能仅凭创建回执宣称动作已成功。删除根节点按原生分组行为提升子对象,不级联删除整套道具。
100
-
101
-
102
- 套件动作配置已验证共享采样链路:创建 cigarette、lighter、exhale 后,使用回执的 rootId 分别填入原生 `spec.use` 的 `{skill:"smokeCigarette",f0:1,args:{kit:{cig,lighter,exhale}}}`。该技能前必须有姿态,例如 `{skill:"standIdle",f0:0,args:{at:[x,z],heading:角度}}`;完整示例采用 266 帧、24 fps。动作节点仍按正式场景版本显式编译,并把 motion 输出连到帧图/视频节点。握持与跟随使用编译物体轨道;纯显隐/亮度轨道不能覆盖父组运动,showOnlyInTake 只有通道驱动时显示。X/Y 骨架的数学采样及共享 WebGL 已验证,但合成测试骨架不代表真实角色皮肤、实际队列或生产容器验收;任意 object.attach 的编辑与逐帧跟随规则见下文。
103
-
104
- 固定吸烟示例在 X 骨架的原生 QA 通过,在 Y 骨架报告右前臂与躯干穿插(本基准 72 个逐帧问题、2 组 BODY);必须读取当前实际 QA、按报告修正后重编译,不得因已出图而标记通过,也不能把这个基准数字当作所有动作的固定结果。
105
-
106
-
107
- 骨骼附着:`object.set-attach {sceneId,objectId,attach,frame}` 使用同场景 X/Y 角色,`attach:{characterId,bone}` 或 null 解除;bone 使用原生 SCENE_ATTACH_BONES ID,null 为动画根部。frame 为场景内的整数帧,换骨骼与解除按该帧的场景姿态保持世界变换;此编辑操作不读取独立动作版本。附着后 object.update 的 XYZ 为局部米制坐标,允许负高度;分组子对象保留原生世界坐标语义,不自动跟随附着父物体。移除或替换角色前必须先解除所有附着。网页选择、CLI 与助手共用操作合同;静态/编译动作渲染和 OTIO blocking 导出共用逐帧骨骼采样。物体路径须先清除再附着;效果粒子已按出生帧骨骼位置采样,拖尾、显隐和亮度使用原生模拟,不积攒全视频帧;附着体的原生身体胶囊/OBB 碰撞已逐帧补测,抓取约束与自动修正仍待适配,不能把渲染跟随视为交互 QA 通过。合成 X/Y 骨架测试不替代真实模型、队列和目标容器验收。
108
-
109
-
110
- 附着碰撞补测:新编译报告的 `qa.attachments`(存在实体附着碰撞体时才有)使用最终动作逐帧采样,复用原生身体胶囊、物体 OBB 和允许穿透阈值。其问题合并到 qa.ok/total/problems/groups;不能因主动作已编译或渲染成功忽略新增 COLLIDE。支持原生 checks.allow 的 part/object/depth;自己的握持手与前臂允许贴合。报告列出 objectIds、characterIds、uncheckedCharacterIds 和 scope;代理角色不在这份胶囊补测范围,不能宣称全场景接触验证完成。补测不自动修正,抓取/接触约束仍由原生动作 spec 声明;同一物体不能同时由骨骼 attach 和独立运动轨道驱动,须先解除附着。历史报告没有 qa.attachments 不等于已通过新检查,必要时重编译。CLI 和助手均可通过现有 motion 读取入口查看完整报告,无需新增写入工具。
111
-
112
-
113
- 网页动作预览新增只读物理诊断:重心、支撑面、腾空轨迹和弹簧物体最近24帧末端拖尾。默认关闭,勾选后按需加载,不更改工程、撤销历史、任务、媒体版本或审核状态;关闭面板释放叠加层。测量保持冻结动作的原生编译坐标;叠加随角色位姿和缩放显示,不重新计算动力学。纯测量报告列出 excludedAttachedObjectIds 和 unmeasuredPathObjectIds;附着碰撞须另读 qa.attachments,路径支撑不在本诊断范围,普通导出任务不启用它,深度/法线始终排除诊断标记。诊断颜色和轨迹用于理解动作,不代表完整 QA 或已审核。完整 QA 仍通过 motion 读取。逐帧只读报告包含 frame、space=compiled-world-metres、placement(16项显示矩阵)、com、support、当前腾空段 arcs 的实测 point/拟合 fit 及 float/worst、弹簧 trails(最多最近24帧)和未测物体 ID 清单;不返回整段腾空数组,不创建版本、不触发渲染,也不批准素材。float/worst 描述整个腾空段,point/fit 只对应当前帧;placement 仅用于显示 com/support/arcs,trails 是物体世界轨道,不再套角色变换。帧号从0开始,必须小于动作帧数。换版/画布编辑返回409,重新读取正式回执后再决定是否检查新版本,不自动重试;取消不交付迟到结果。超出192 KiB报告预算会显式失败,不裁剪数据。没有远程开关浏览器叠加的工具,不能把原生 motion.physicsOverlay 当作正式编辑操作。 先用 `canvas previs read <motionNodeId> --motion --project <projectId> --json` 获取 receipt.versionId,再执行 `canvas previs physics <motionNodeId> --project <projectId> --motion-version <receipt.versionId> --frame <frame> --json`。
114
-
115
-
116
- 抓取插槽通过共享 `object.update {sceneId,objectId,patch:{grasp}}` 整表替换,`grasp:null` 清除。grasp 是1~8个命名插槽的对象,名称为1~32位字母、数字、下划线或连字符;每项 `{at:[x,y,z],axis?,from?,thumb?}`,at 是相对物体底部枢轴的米制坐标(各轴±10),可选方向为各轴±1000的非零向量并按原生规则归一化。非法字段、零方向或超限会拒绝保存,原工程不变。空对象不表示清除。分组自己的插槽与零件插槽保留原生名称空间,零件名为 `<objectId>.<socketName>`;局部插槽随物体运动。网页实体面板可编辑、替换、清除及撤销重做。
117
-
118
- 使用时在现有 previs-motion 的 config.previs.spec 定义 `anchors.grip={kind:"object",object:真实对象ID,grasp:"power",socket:"handle"}`、`fits:[{side:"l",anchor:"grip",effector:{joints:["LeftHand"]}}]`,关键帧 set 中显式开启 `w_grip_l:1` 和 `armw_l:1`;grasp 可选 power/pinch/hook/palm/spherical,side 为 l/r,骨骼使用 LeftHand/RightHand 等原生名称。可以用 checks.contacts 的 joint/anchor 引用和 when 检查接触;保留原生 CONTACT、抓取与修正 QA,缺失插槽明确报错。请根据实际物体位置和动作规格验证接触结果,不把示例直接视为成功握持。通过现有配置与执行工具显式编译,再读取完整 QA;保存插槽不自动执行抓取、附着、动作或渲染。场景骨骼附着体仍不能作为静态抓取目标;附着碰撞后验 QA 不自动修复。多动作联合QA与附着感知修复仍待接入。
119
-
120
-
121
- 动作裁切和变速保存到 previs-motion 的 `config.previs.timing={sourceFrameCount,segments:[{id,sourceStart,sourceEnd,speed}]}`。sourceFrameCount 取当前编译报告 `motion.compilation.timing.sourceFrameCount`,未编辑时取 `motion.frameCount`;不能根据场景总帧数猜测。sourceStart/sourceEnd 为闭区间源帧,speed 为0.1~4,ID唯一,最多128段;每段时长为 max(1,round((sourceEnd-sourceStart+1)/speed)),总编辑长度最多20000帧,所有源区间须在实际编译源内。字段严格校验,改规格导致源长度变化时须重新审阅剪辑。原生分段支持切分、删除、裁切、重排和重复源区间(各段仍需不同ID),不隐式补帧或调用生成模型。
122
-
123
- 例如48帧动作的 timing 为 `{sourceFrameCount:48,segments:[{id:"first",sourceStart:0,sourceEnd:23,speed:0.5},{id:"last",sourceStart:24,sourceEnd:47,speed:1}]}`,结果72帧。网页在动作配置中提供切分、分段速度、删除、闭区间裁切和恢复完整时间;这些按钮先改本地配置草稿,仍须保存动作配置并显式执行。速度按钮按原生0.1步长取整。CLI/助手使用现有节点配置写入和执行入口;没有新增 motion.cut 等命令或预演场景 action。工具包独立 timing 入口提供同一原生映射及编辑函数。恢复时移除 timing,或保存全范围1倍速段并执行;全范围恒等映射不额外保存剪辑状态。
124
-
125
- 正式附件保留完整未改写的原始骨骼/根位移/物体轨道和 edit 描述;统一解码入口按原生规则一次性采样编辑后数组。骨骼四元数按原生最短向归一化插值,位移/亮度线性插值,显隐/握持/世界标记取最近源帧。网页预览、CPU渲染、物理测量、OTIO布局和工程包消费同一结果,输出采样帧按编辑后时间线。元数据 frameCount 为编辑后长度,compilation.timing 保留源帧合同;元数据与附件的剪辑描述不符会拒绝,媒体附件仍受128MiB上限。
126
-
127
- 源编译、修正、接触、附着碰撞与根路径QA仍保留源时间线,存于 `qa.source`;使用剪辑后 `qa.frameSpace="mixed"`,汇总分组各自标记source或edited,`qa.timing` 同时返回源长度、编辑后长度、完整分段布局、`qaScope="source-compile-and-source-post-checks"` 和 `editedDynamicsRechecked=false`。不能把源QA帧号当成成片帧号,也不能把源QA通过当成变速后的动力学或审核通过。物理逐帧入口测量的是实际编辑后姿态;源编译 timeline/probes/observations 不自动改写为新的动作意图。时间编辑后的动作须覆盖渲染请求,并与场景正式版本匹配;扩长动作超过场景长度时应先调整场景时间线,再重编译,不自动扩工程。
128
-
129
- 动作区间 IK 使用动作节点 `config.previs.rangePins={frameCount,timing?,pins:[{id,track,startFrame,endFrame,blend,reach?,target}]}`;不是预演场景 action。frameCount 是最终编辑后的动作长度,timing 必须与同一配置中的时间映射精确一致(未编辑时省略);裁切或变速后不能沿用旧基准。track 为 leftHand/rightHand/leftFoot/rightFoot,闭区间帧号在最终动作内,blend 为1~240帧,reach 为 limb(默认)或 body(移动髋部并重新保持支撑脚)。target 为 `{space:"world",position:[x,y,z]}` 或 `{space:"object",objectId,local:[x,y,z]}`,坐标米制,物体目标沿冻结场景的完整世界变换采样;不支持目标直接附着在正在求解的角色上。ID唯一、最多32条、累计最多20000约束帧;共享拥有轨道的区间不得重叠,body 拥有髋部、双脚及所选末端。未知字段、缺失目标、错误基准明确拒绝。
130
-
131
- 网页区间面板可选择四肢/全身、帧段、过渡及世界目标,添加/移除/清空只改本地配置草稿;物体局部目标可用完整 JSON 配置。保存后显式执行动作编译。CLI/内置助手使用已有节点配置写入和 canvas_execute,没有新增 mouse、motion.pin 或 scene action。删除 rangePins 并重新编译恢复原始动作。编译在可终止子进程完成,正式附件保留源数组、时间映射与 `ikBake` 最终骨骼/髋部及逐帧残差;统一解码先应用时间映射,再一次性使用修正数组,重复烘焙回存及元数据不匹配被拒绝。网页、后台渲染和工程导出读取同一附件。
132
-
133
- `qa.rangePins` 以最终编辑帧测量每条目标误差,body 另含支撑脚误差;完整 Float32 残差在 `artifact.ikBake.residuals`,报告含最差帧、米制误差、1厘米容差和失败分组。后续约束改变先前结果时以最终姿态重新测量,不把中间求解结果当成最终QA。不可达目标不会伪装通过。源编译仍在修正前执行;修正后的接触/抓取补测范围见 qa.postEdit.contacts,完整动力学尚未闭环,`sourceChecksBeforeRangePins=true`、`fullMotionQaRechecked=false`;物体轨道仍是原始编译轨道,抓取跟随及完整避碰不能据此宣称完成或审核通过。其他角色目标使用冻结静态姿态,尚无多动作联合求解。
134
-
135
-
136
- 时间编辑或区间 IK 后新增 `qa.postEdit`:frameSpace="edited",frameCount 为最终帧数。collisions 按最终骨骼胶囊与实际场景 OBB 补测全部支持的碰撞体,包含附着、物体路径、分组和编译轨道;物体对至少有一方发生运动才计入,静态布景已有相交不重复归因。隐藏角色/父组和编辑后的显隐轨道参与筛选,checks.allow 保留;自身附着手/前臂允许贴合。原生编译 carry 依据技能展开后的主手合同及重采样后的 hold 标记,仅在实际握持帧豁免主手/前臂,compiledCarryHandExemptions="primary-hand-and-forearm-while-hold-flag";带 carryQa 附件的新编译结果 secondHandAndNearSupportExemptions=true:第二手只豁免 hand 胶囊,须有原生第二手诊断且达到0.5握持权重,或最终手掌位于道具盒内;前臂仍检查。原生抓取支撑归属被冻结,nearSupportFrames=3按源帧的抓放窗口映射到最终时间线;重复剪辑分别生效。旧附件缺 carryQa 时该字段为false并保守检测,不隐式补写;不据此自动修复。工作量按最终帧数×碰撞体数×(支持角色数×胶囊数+所有支持人物双脚探针数+2×运动记录数)估算,超过2,000,000时以 PREVIS_SCENE_COLLISION_BUDGET_EXCEEDED 拒绝,需拆分场景或动作。
137
-
138
- postEdit.rootPath 在场景原定帧0及每个骨骼路径点检查最终髋部位置/朝向,沿用0.1米/10度容差,不随裁切、变速隐式移动路径合同。剪短后不存在的路径点记入 missingFrames 和 ROOT_PATH_MISSING_FRAME 失败,不采样夹紧到镜尾;frameContract="authored-scene-frames-no-implicit-remap"。源编译及源附着/路径报告完整保存在 qa.source(source 帧空间);汇总 qa.frameSpace="mixed",每个 qa.groups 条目单独标记 source 或 edited,不能统一用一个帧空间跳转。任一源检查、区间残差或最终补测失败都会令总 ok=false;计数包含各检查阶段,不能把源/最终重复问题相加理解为独立事件数。未编辑动作继续保持原报告格式。postEdit.fullMotionQaRechecked=false:完整最终 QA 尚未闭环;接触/抓取补测范围见 qa.postEdit.contacts,不能把补测通过当作审核通过。旧正式版本缺少 postEdit 时须显式重新编译取得新证据。
139
-
140
- `qa.postEdit.body` 另按最终骨骼复用原生皮肤碰撞、手指活动范围/指间碰撞与双手重叠检查,失败进入总 QA。scope="native-skin-fingers-and-anatomy",坐标为编译单位骨架米制,scenePlacementRechecked=false;保留 checks.allow/limits,不复用源命中诊断。fullMotionQaRechecked=false,尚不包含抓取、手持道具、完整接触与动力学复验;不是自动修复或审核通过。
141
-
142
- `qa.postEdit.kinematics` 按最终编辑帧复用原生 POP 突跳检查,并只在 checks.limits 明确声明时检查 speedCore/speedLimb(米/帧)、accCore/accLimb(米/帧²)及 knee(度)。scope="native-pop-speed-acceleration-knee",declaredLimits 返回实际启用的风格限值;速度未声明时不判超速。变速、拼接或区间 IK 后重新测量,失败合并总 QA,每组 frameSpace="edited";正式附件回读可重测同一结果。坐标为编译单位骨架,不测显示放缩或场景携带产生的速度;平衡/支撑/腾空由下述 postEdit.support 补测;接触/抓取另见 postEdit.contacts,其余完整动力学仍待验收,fullMotionQaRechecked=false,不能把部分检查通过当作完整动作验收。
143
-
144
- `qa.postEdit.support` 以正式渲染的世界骨骼和场景盒子补测 GROUND(脚底穿过地面)、SLIDE(着地脚滑动)、FLOAT(不少于4帧腾空且缺少重力减速),并仅在 checks.limits.balance 显式声明时检查 BALANCE。scope="native-world-ground-slide-balance-float",coordinateSpace="rendered-world-metres",scenePlacementRechecked=true;实际角色缩放、父组/物体路径、编译物体轨道、显隐和脚底朝向参与测量,checks.supports 支持物按最终世界位置判定。自己的骨骼附着体及原生 carry/follow 物体排除为支撑,excludedObjectIds/candidateObjectIds 明确列出。
145
-
146
- 保持原生世界坐标脚滑语义,slideSpace="world-no-support-velocity-subtraction":不扣除支撑物水平速度,运动平台上的水平随动仍可能报告 SLIDE;不是相对平台的摩擦仿真。平衡距离/穿透/支撑阈值以世界米计,重力按24 fps计算。工作量按 最终帧数×(骨骼数+支持场景盒子数+1)×12 估算;超过2,000,000以 PREVIS_SUPPORT_BUDGET_EXCEEDED 拒绝,需拆分场景或片段。报告失败并入总 QA;fullMotionQaRechecked=false、autoRepair=false,接触/抓取补测另见 postEdit.contacts,完整场景接触与其余约束仍待验收,不能视为审核通过。
147
-
148
- `qa.postEdit.contacts` 在时间编辑/区间 IK 后,以最终骨骼与冻结物体轨道复跑原生声明的 CONTACT、ORIENT、BELOW、CLEARANCE、APPEAR,以及抓握指尖/支撑、手腕与手持道具检查;失败进入总 QA。身体锚点使用最终髋部位置/朝向,重复剪辑逐段映射接触及握持区间;抓握开关和主手归属按最近源帧采样,数值通道插值。scope="native-declared-constraints-grasp-wrist-held-props-goals-load-and-keys",正式编译 coordinateSpace="rendered-world-metres"、scenePlacementRechecked=true,frozenObjectTracks=true。完整编译上下文仅保存在本地编译过程中,不进入 Worker 消息或正式附件;重测需要相同编译上下文与附件,不能只凭附件重建声明语义。超过逐帧骨骼/物体预算以 PREVIS_CONTACT_BUDGET_EXCEEDED 拒绝。源报告仍在 qa.source;fullMotionQaRechecked=false、autoRepair=false,附着感知修复、完整最终原生约束及多动作联合求解仍未完成,不代表审核通过。
149
-
150
- 附件 carryQa 只包含版本1、源帧数、携带物/抓放时刻/原生支撑ID及第二手离散状态(0无诊断、1低于0.5、2达到0.5);不包含闭包、密钥或完整逐帧诊断。第二手使用最近源帧,支撑窗口使用连续源时间,遵循原生端点保持的变速映射;不能简单将帧号乘速度倒数。非法版本、长度、状态及字段在附件解码时拒绝,PREVIS_CARRY_QA_CONTEXT_INVALID;旧附件仍可读取。该信息只用于碰撞豁免,不驱动动画、不授权素材、不改变审核状态;完整最终QA与附着感知修复仍待完成。
151
-
152
- 正式编译的 `qa.postEdit.contacts` 现以 coordinateSpace="rendered-world-metres"、scenePlacementRechecked=true 测量:与渲染共用骨骼和物体采样,角色放缩、父组/路径、编译物体轨道及实际显隐参与判定。world 锚点保持绝对位置;身体/骨骼/道具相对绑定随所属坐标系移动,物体锚点保留原编译选定的插槽,不重新求解道具以追随手部。CONTACT/ORIENT/BELOW/CLEARANCE/APPEAR、抓握与手持道具问题进入总QA;隐藏角色不生成可见接触问题。手腕仍使用原生局部关节角,wristCoordinateSpace="compiled-world-metres"。胶囊半径按最大世界轴放缩(capsuleScale="maximum-world-axis-conservative"),boxTransform="decomposed-world-obb";非均匀放缩/剪切仍是保守胶囊/OBB近似,不是三角网格碰撞。原生不等轴球体的盒子近似继续保留。完整重测需要相同本地编译上下文、最终附件和正式场景;纯运行时未传场景时仍只测编译坐标。预算同时计入骨骼、物体、分组、锚点、声明检查和fit数量,超限拒绝。正式生产的多动作联合QA、完整最终原生QA及自动修复仍未完成,不能把该报告当作审核通过。
153
-
154
- `qa.postEdit.body` 的 scope 现为 native-skin-fingers-and-anatomy,anatomyChecks 列出 FACE/SELF/KNEE/ELBOW/FLIP/LENGTH:除皮肤、手指及双手重叠外,还检查膝反折/膝肘折叠极限、腿部相交、弯曲平面逐帧突翻和骨长漂移,失败合并总QA。仍按编译单位骨架测量,不能把角色显示放缩当成骨骼拉伸;骨长沿用原生整段最大漂移及帧0归因。正式世界 contacts 另检查手部/手持道具进入头部,头部椭球和探针半径随最大世界轴放缩,保留 checks.mouthPoints 对明确道具点的豁免。原生 generalChecks 在固定原文回放中逐条一致。fullMotionQaRechecked 仍为 false:最终求解目标/对象键残差、抓取与接球事件及多人约束仍需完成最终复验,不能因上述检查通过宣称完整动作QA已闭环。
155
-
156
- 最终场景碰撞报告 scope="native-body-capsules-feet-and-object-boxes",footCollisionsRechecked=true:除身体胶囊外,沿用原生拟合脚部皮肤探针(无拟合体时使用脚底探针),检测脚趾穿入台阶侧面。脚踩盒顶沿用 groundAllow,侧面沿用 allow,checks.allow 对 foot_l/foot_r 可单独覆盖;不豁免自身携带物与脚的碰撞。角色实际放缩影响探针,原生分组仍只传递刚性运动、不传递缩放。隐藏物体/角色和显隐轨道不生成可见碰撞问题;失败进入总QA,未启用自动修复。工作量预算增加所有支持人物的双脚探针总数,仍以 PREVIS_SCENE_COLLISION_BUDGET_EXCEEDED 拒绝超过2,000,000的估算。历史报告需重新编译,不自动改写。
157
-
158
- 最终动作目标在 qa.postEdit.contacts.goals 逐项返回 name/kind/ok/value/at/need,GOAL 失败进入总QA。near、above、moved、still、speed 沿用原生判定,物体表面/杯口与嘴部地标保持原生引用语义,嘴部偏移按完整世界变换取样。goalWindowSampling="source-interval-membership":源目标区间映射到每次出现的最终帧,重复片段分别测量,中间无关区间排除;goalEventSpace="edited-timeline":after/before 使用最终时间线的首次满足事件,点位移从事件切窗内首个实际目标帧起算。速度按最终24fps重测。目标区间完全被剪掉、引用无法测量或事件窗无可测结果时显式失败,不能静默当通过。目标区间被部分裁切时只测保留下来的映射帧,不声称被删掉的源帧仍满足。重测仍需要原编译上下文和正式附件,完整最终QA、多动作联合求解与自动修复仍待完成。
159
-
160
- 最终负载在 qa.postEdit.contacts.load 返回原生每手的 object/mass/maxNm/at/frames,LOAD 问题进入总QA。力矩按最终肩腕水平距离×质量×9.81计算,单手超过25 N·m且缺少原生第二手权重支持时失败;第二手锚点权重必须严格大于0.5,权重从源通道映射到每个最终帧。loadMassBasis="original-motion-spec-and-scene":质量仍取原生显式mass或源场景体积估算,人物显示放缩不会自动改写物体质量;世界肩腕距离包含实际人物放缩和路径。loadSecondHandBasis="native-declared-anchor-weight":这是原生声明权重规则,不是新的接触力求解或已验证第二手实际接触;接触/抓握由同一总QA的其他检查负责。fix=false或fix.grasp=false时按原生规则禁用负载物理,load为null。重复剪辑、变速和IK后的最终帧重新测量,不重新下垂、重新抓握或自动修复。预算另计携带体数量×(锚点数量+1)的逐帧扫描开销,超过既有总预算以 PREVIS_CONTACT_BUDGET_EXCEEDED 拒绝。对象键/求解目标残差、抓取/接球事件、完整多人约束及修复仍待完成。
161
-
162
- 最终持物关键帧残差在 qa.postEdit.contacts.keyedResiduals 报告:以原生源曲线和物体源尺寸角点,对比最终冻结轨道的位置及朝向;REACH 失败进入总 QA,不从修正后的手部重新生成物体。重复片段逐次检测,变速按分数源帧采样曲线。原生弹簧摆动不属于 REACH,按源 drawn-to-base 相对偏移扣除,额外冻结轨道变化仍可检测。整个关键帧窗口被剪掉时仅列入 unmeasuredObjectIds,不宣称已测通过。重测依赖原编译上下文;此项不替代求解目标残差、抓取事件、多人约束及修复。证据见 validation/p2-key-qa.json。
163
-
164
- 脚部求解目标补测见 qa.postEdit.contacts.solverTargets:scope=native-leg-and-arm-solver-targets,以最终 LeftFoot/RightFoot 骨骼端点对比源编译帧 foot_l/foot_r 目标,不沿用源 leg_miss 诊断;超出原生 reach 容差的 REACH 合并总 QA。重复区间各自测量,目标数值线性插值,是否启用按最近源帧判定;没有目标时不生成零目标。坐标明确为 compiled-world-metres,不包含人物显示缩放、父组或路径的世界变换;同报告其他接触检查仍可使用渲染世界坐标。measuredFrames 列出每侧实际测量帧数,armTargetsRechecked=true、heldTargetsRechecked=true,autoRepair=false。手臂目标的原生语义见下述补测说明。证据见 validation/p2-foot-target-qa.json。
165
-
166
- 手臂与握持求解目标已接入 qa.postEdit.contacts.solverTargets:scope=native-leg-and-arm-solver-targets,armTargetsRechecked=true、heldTargetsRechecked=true。源编译器只记录混合、避障、负载、软可达修正后的实际 IK 目标,以及最后一次握持迭代目标,不改变求解结果。最终帧直接测量手腕到冻结目标的距离;目标保留原生后续抓握/握持造成的手腕位移(armTargetBasis=captured-native-solver-target-with-downstream-pose-offset),避免将制作步骤误报为后处理漂移。普通 IK 误差乘以原生 1-hold.w,完整握持时由握持目标负责;armWeightBasis=native-one-minus-hold-weight。arm_miss_l/r、hold_miss_l/r 的 REACH 进入总 QA,measuredFrames 列出各项启用帧数。重复/变速采用数值线性插值及最近源帧启用规则;依赖原始本地编译上下文,缺少目标记录时报 PREVIS_SOLVER_TARGET_CONTEXT_MISSING,正式附件不保存这些闭包或目标记录。坐标仍为 compiled-world-metres,不重新解析经过显示缩放、父组或路径移动后的实时锚点;渲染世界接触由其他补测负责。autoRepair=false;抓放事件、完整多人约束及修复仍未完成。证据见 validation/p2-arm-target-qa.json。
167
-
168
- 抓取/接球事件在 qa.postEdit.contacts.grabEvents 返回:eligibleObjectIds、events 和 unmeasuredObjectIds。复用原生抓取前静止/下落轨迹,以最终 prop.origin 骨骼均值到原实体盒表面的距离测量,不使用已经跟手的持物轨道;GRAB 使用 checks.limits.grab(默认0.03米),CATCH 保留原生速度标记判定及固定0.03米阈值。首帧即持有、未声明 grab 或抓取前原生可见通道隐藏的物体按原生规则免检。每段重复剪辑先用原生 sourceToTimeline 映射,再按附件的最近源帧握持采样规则定位首个实际抓取帧;events 同时记录 sourceFrame、最终 frame、sampledSourceFrame、gap、limit、ok,变速采样可能不恰好落在源事件帧。整个事件被剪掉或压缩后未采到抓取仅列为未测,不宣称通过。失败合并总 QA,预算含携带组内实体数量。正式场景测量返回 coordinateSpace=rendered-world-metres、scenePlacementRechecked=true、targetBasis=rendered-native-resting-before-grab:手部使用实际显示缩放与父组/人物路径,抓取前实体按最终时间线的父组路径移动,并保留原尺寸及下落姿态;分组逐成员实体测量,隐藏人物或无可见成员的目标列为未测。分组携带保持原生刚体语义,不额外继承父组尺寸。仅提供编译上下文时仍返回 compiled-world-metres、scenePlacementRechecked=false。autoRepair=false,完整多人约束、世界求解目标和修复仍待完成。证据见 validation/p2-world-grab-qa.json;原编译事件基准见 validation/p2-grab-event-qa.json。
169
-
170
- 人物之间的碰撞补测在 qa.people(源动作)和 qa.postEdit.people(时间编辑/区间 IK 后)返回,失败为 PERSON 并合并总 QA。复用原生身体胶囊与线段距离、checks.allow 的 part 前缀和 object:"person:<id>" 规则,允许深度仍为米制;胶囊半径及远距粗筛包含实际人物放缩。其他角色按正式场景的姿态/父组/人物路径逐帧采样,父组显隐读取最终附件轨道。scope=native-person-capsules-against-scene-poses、coordinateSpace=rendered-world-metres、visibilitySampling=scene-hidden-and-final-track。personIds 为候选 X/Y 角色;hiddenCharacterIds 为工程静态隐藏角色;其他可见代理角色列入 uncheckedCharacterIds,不得宣称它们碰撞通过。单动作编译报告仍为otherMotionVersionsRechecked=false;多动作任务另存上方联合人物胶囊报告,不包含联合求解。工作量预算为最终帧数×候选人数×胶囊数平方×9,超过2,000,000抛 PREVIS_PEOPLE_BUDGET_EXCEEDED。胶囊为保守近似,autoRepair=false;完整多人交互、附着感知修复和目标容器验收仍待完成。证据见 validation/p2-people-qa.json。
171
-
172
- 环境贴图上传:`canvas previs upload <nodeId> sky.hdr --project <projectId> --base base.json --hdr --scene <sceneId> --json`,也支持 .exr/.png/.jpg/.jpeg;不能与 --model/--character/--object 混用。网页在灯光页上传,须先保存草稿;上传会保存新来源版本及场景版本并选中该环境。
173
-
174
- ## 场景纸片
175
-
176
- 参考图上传只存档,不自动进入场景。使用 `cutout.add {sceneId,objectId,assetId,aspect,height?,name?,placement?}` 显式创建:assetId 必须是当前工程已有 purpose=reference、format=png 的正式绑定;objectId 为同场景唯一对象 ID;aspect 为图片宽高比(0.02~50),height 为米(至少0.05,默认1.8),placement 为 x/y/z/rot。网页从正式媒体记录的图片尺寸读取比例;Agent 应从已知图片尺寸取得比例,不凭空声明尺寸,未知时先确认构图意图。
177
-
178
- 尺寸使用 `object.update {sceneId,objectId,patch:{height?,width?,stretch?}}`:width 为目标米制宽度,stretch 为0.1~10的宽度倍率,宽度优先于同次 stretch;底部枢轴和占地由原生实现重算。位置、旋转、分组、路径及骨骼附着沿用已有操作。删除所有场景中引用它的纸片后才能 `asset.remove`,否则返回 PREVIS_ASSET_IN_USE;删除纸片保留正式图片及历史版本。保存仍用 read 返回的三重版本,不自动渲染;渲染显式执行。纸片只提供空间/构图参考,不自动建立人物身份或审核记录。深度/法线保留透明孔洞,闲置参考图不进入渲染清单。网页支持按需打开画笔,以原图像素进行背景取样及擦除/恢复;预览不保存,须显式提交新版本。原生复制尚未接入,不能宣称已具备该入口。
179
-
180
-
181
- 显式抠图与蒙版重编辑使用同一编辑合同:`{base,matte:{sceneId,objectId,selection:"auto"|"saved",options:{...}}}`,与 actions/restoreVersionId 互斥。先读取当前已保存场景和纸片 ID;保留完整 base,不自动重读替换。auto 默认按边缘颜色选择背景,也可给 points 原图像素坐标(1~128点)及 tolerance=0.01~0.9;saved 使用已有原尺寸蒙版,不接受 points/tolerance。options 可设 shrink/feather 整数0~8、trim 布尔值,以及最多4096条 strokes:`{x,y,radius,value}`,x/y 为原图像素,radius>0且<=512,value=1 擦除、-1 恢复。输入不接受 URL、媒体ID或任意脚本;原图、选区、渲染图保留各自不可变版本。裁剪沿用原生全图高度补偿,重复操作不累乘比例;操作会保存场景新版本;下游已有结果保持可用,不自动渲染或审核。409 后重新读取并审阅;结果未知时查询原回执,不能盲目重试。
182
-
183
- CLI 用 `ai-short-studio canvas previs apply <nodeId> --project <projectId> --file matte.json --json` 提交此合同。
184
-
185
- 网页画笔与远程抠图共用像素处理合同:画笔预览始终显示全幅原图坐标,trim 只影响正式输出的包围盒。取样和笔画不是人物身份或审核证据;Agent 不操作网页画笔,而是用已支持的结构化 points/strokes。已有蒙版保持源图尺寸,saved 禁止自动取样参数。网页预览可清空本次笔画,关闭预览保留当前面板的编辑;切换对象、恢复版本或离开编辑器时,未保存笔画需要用户明确丢弃。关闭预览或改变参数会终止旧 Worker,预览失败不自动提交或降级。原生边缘清理可能删除触边的小孤立区域,恢复笔画不绕过该规则。
186
-
187
- 当前 strokes 为原图像素修补,不代表上游区域生长画笔已接入;原生区域笔画、选区局部历史和缩放平移仍有缺口。PREVIS_MATTE_EMPTY 不产生正式版本;网页可显示原图供修正,但不能将该原图当作成功抠图产物。
188
-
189
-
190
- 帧图和视频渲染位置:`previs-frame` 与 `previs-video` 支持 `config.previs.executionLocation=auto|client|server`。网页及内置助手的 auto 任务优先由当前用户打开的本项目画布页面领取,客户端不可用或断线后可后台接管。client 必须保持画布页面打开,无法领取、断线或编码失败会失败;server 使用后台。CLI 默认 auto 且没有网页能力声明时使用后台;显式 client 会等待网页。内置助手仍通过 canvas_execute 提交,无需再次点击运行。客户端 WebGL 使用 GPU,视频按固定 24fps 时间戳使用 WebCodecs 编码 H.264 MP4,优先硬件编码,实际设备由浏览器决定;软件 WebGL 不作为客户端 GPU 路径。单帧、首尾帧、深度、法线、联系表和视频使用同一冻结版本及角色合同。正式媒体由服务端验证执行权、来源、PNG 尺寸、MP4 编码/帧数/帧率/时长并解码后提交;客户端上传不等于审核通过。工程导出继续后台。
191
-
192
- ## 3D 导演台完整工程与图片预排版
193
-
194
- `canvas director read <nodeId> --project <projectId> --json` 返回 `base.canvasVersion`、`base.versionId` 和 `panel.directorState`。后者是完整新版状态(format=pixelshort-director-state、schemaVersion=1),包含 project 与 settings;directorLayout 只是兼容投影。尚未保存的新节点返回 initialState 和 base.versionId=null,首次写入显式传 expectedVersionId:null;CLI prelayout 自动携带这份初始工程。历史已保存但缺少完整工程时,需在网页检查后保存,不静默降级。
195
-
196
- `canvas director prelayout <nodeId> --project <projectId> --image ./scene.png --kind scene --json` 上传一张 PNG/JPEG/WebP(最多25 MiB),通过后台视觉分析任务生成对象和参考机位,等待完成后按读取时基线追加到工程。分镜图使用 `--kind storyboard --panel 2` 指定阅读顺序中的一格(1~16),不会把不同镜头混成一个场景;不重建格线、编号、箭头或水印。`--analyze-only` 只返回结果,`--timeout 600` 控制等待时长。单图尺度、深度与遮挡为粗估,仍需检查站位、机位和连续性,不代表审核或渲染通过。
197
-
198
- `canvas director apply <nodeId> --project <projectId> --file operation.json --json` 接受 `{operation:"layout.apply",expectedVersion:<base.canvasVersion>,expectedVersionId:<base.versionId>,layout:{scene,objects,cameras,notes}}`。scene 包含 backgroundColor、groundColor(#RRGGBB)与 groundHeight(-10~10米);objects 为1~24个 `{id,kind:"character"|"prop",name,color,transform:{position,rotation,scale}}`,向量为三元数组、旋转为弧度;可选 assetRefId 必须是工程现存模型,geometryType 仅 box/sphere/cylinder/cone/pyramid/torus。cameras 为0~16个 `{id,name,position,target,fov}`,fov=10~120。ID 不能与工程已有对象或机位冲突。解析回执的 sourceSha256、imageKind、panelIndex、limitations 不放入 layout。
199
-
200
- 完整编辑使用 `operation:"project.update"`,传相同版本基线和完整 standaloneState;保留所有未编辑配置、素材、动作和截图,不用旧投影覆盖。写入生成新文档版本;409 后重新读取并审阅,不自动替换基线重发。旧快照/运动记录操作只作用于兼容投影,不等同于新版路线编辑。本地模型上传仍用网页正式素材入口;blob/data/director-asset 临时引用不可写入。历史缺失信息只能从现存备份恢复。
201
-
202
- 图片预排版可用 `--model <model-key>` 显式选择视觉模型。该模型必须在已发布能力中声明 `llm.visionInput=true`;省略时校验项目分析模型,不支持图片则在上传前报错,不自动改用其他模型。网页提供独立视觉模型选择。
203
-
204
- 图片预排版会按有效画面包围框和画幅拟合站位,尺寸先按基础几何体归一化,再写入实际 transform;人物使用等比缩放并带 characterRig 站立/坐姿/迈步控制。正式 layout.apply 可选 aspectRatio(1:1、2:1、3:4、4:3、16:9、21:9、9:16)和对象 characterRig={rigType:"mannequin",posePresetId:"stand"|"sit"|"walk",controls:{关节字段:角度}}。posePresetId 只标记姿态,真实关节必须写 controls;不能仅改名字。transform.position 是运行时原点,scale 是倍率,不能把模型返回的包围盒中心和米制尺寸直接写入。单图仍是粗预演,应回看参考机位检查人物出画、接地和遮挡。
205
-
206
- layout.cameras[].position 为光学观察位置,写入时会转换为摄像机支架位置(镜头偏移1.82米);不要再手工添加偏移。画幅会同步到工作设置,第一视角按取景框进行投影,而非铺满视口再裁切。
207
-
208
-
209
- 新版导演台运镜和人物路线必须用 project.update 改刚读到的完整 standaloneState,不能使用 motion.recording.upsert / camera.recording.upsert。standaloneState 直接是 {format:"pixelshort-director-state",schemaVersion:1,project,settings},不再套文档外壳;原样保留 scene/assets/settings 等全部字段。
210
-
211
- - 人物路线写 project.objects[].motionPath={interpolation:"linear"|"smooth",keyframes:[{id,time,transform:{position,rotation,scale},facingMode:"manual"|"path",actionPresetId?:string|null}]}。time 是0~1的归一化进度,不是秒;6秒的起中末为0、0.5、1。路线共享活动机位的duration。保持朝向时用manual并保留正确rotation;path按行进方向转身,不能将它用于倒退。
212
- - 运镜写 project.cameras[].motionPath={duration:6,loop:false,interpolation:"smooth",easing:"ease-in-out",keyframes:[{id,time,position,target,fov}]},每帧必须有唯一id、0~1的time、三元position/target和数值fov。这里position直接是光学观察位置,不套layout.apply的支架偏移;不要用cam.transform.position直接充当首帧观察位置。保持原有机位支架transform,设置project.activeCameraId为编辑的机位、settings.viewMode="camera"。
213
- - 人偶关节名例如leftHip.pitch、rightHip.pitch、leftKnee.bend、rightKnee.bend、leftShoulder.pitch、rightShoulder.pitch、leftElbow.bend、rightElbow.bend、head.yaw,值为度。hip_l/knee_l等缩写不受运行时驱动。坐姿双髋-90、双膝90;迈步可用双髋-20/20、双膝12/4和双肩20/-20。保持等比缩放。+Z朝镜头,向画面左yaw=-π/2,向右=π/2。
214
-
215
- 写入前检查完整工程和全部关键帧,成功后回读核对duration、keyframes、人物位移和当前活动机位。渲染/播放工具缺失时必须如实说明,不能把保存成功当成播放验收通过。
216
-
217
- 人物沿路线持续迈步需要真实动作预设:正常行走为 `walk-cycle`(约1.1秒循环),写入 `characterRig.actionPresetId` 以及路线起点和后续关键帧的 `actionPresetId`。仅设置 `posePresetId:"walk"` 或静态关节角只形成姿态,不构成持续步态;不能把沿路平移描述成已验收的行走。运动方向与朝向独立,侧退/倒退保持manual。播放需检查腿部相位和足滑,不能仅凭路径关键帧通过。
54
+ Agent 仅预检、保存和回读工程,不发起图片或视频渲染。完成后请用户打开节点,在原有导出图片/导出视频窗口中选择画布(默认),或选择本地下载。用户导出完成后,再查询独立素材节点供下游固定引用;不等待页面心跳、不查询或重发渲染请求。
@@ -4,7 +4,7 @@
4
4
 
5
5
  本文件是 CLI 与内置助手共用的制作经验。执行接口由当前入口提供,不能从经验正文推导出不存在的工具或权限。
6
6
 
7
- 1. 先确定用户目标、当前项目与目标集,只处理本次范围。创作语言、画幅、时长、素材含义或停止阶段存在关键歧义时,合并提出最少必要问题;等待期间只做可以独立完成的只读检查。
7
+ 1. 先确定用户目标、当前项目与目标集,只处理本次范围。创作语言、画幅、时长、素材含义或停止阶段存在关键歧义时,按决策依赖分批提出必要问题;等待期间只做可以独立完成的只读检查。
8
8
  2. 以持久画布、实时节点目录、任务终态、资产及不可变版本为事实。选区是操作线索,不证明节点已经保存、可访问或适用于当前目标。
9
9
  3. 只加载当前阶段的资料。检查画布先读共享的画布检查流程;需要写图、生成、编辑、选版或审片时,先确认当前入口有真实能力与对应合同。工具缺失时明确说明当前阶段不支持,不能使用 shell、猜测接口或将操作伪装成普通配置修改。
10
10
  4. 上游输入、资产选版、审核来源或模型能力改变后,重新核对受影响阶段。专业镜头即使只补资产绑定,也可能同步追加父分镜汇总版本;按真实回执与选版核对父汇总和完整计划来源,不能因未直接编辑父节点就推定计划仍有效。读取版本冲突时重读并核对,不把旧分析直接应用到新内容。节点拖动不等于创作内容变化。
@@ -32,7 +32,7 @@ PRODUCTION_VIDEO_SOURCE_STALE 先核对错误中的具体文档和 staleInputs
32
32
 
33
33
  PRODUCTION_VIDEO_PROMPT_STALE 按 mismatchedFields 定位实际差异;references 不一致时成对核对正式提示词 storyboard 来源与视频真实图片输入,previous-tail 两处必须使用同一尾帧。修正真实连线后重写提示词,不用重选旧视频或刷新无关图片试错。
34
34
 
35
- 采用首次有效视频声音作为人物基准时,每批视频完成后、下一批提交前,逐说话人核对待绑定状态。已有清晰对白及可信的实际时间证据时,先提取该人物样本、回读声音计划绑定,再核对后续模型的参考音频能力与真实输入;不能连续多批沿用 reference=null 的首镜占位合同。首镜对白错误、ASR 与来源冲突或没有可分离区间时,不把它作为声音基准,也不凭剧本猜时间;使用首个可核对的有效样本,保留首次候选不可用的原因。ASR 仅提供转写和区间证据,不证明试听或声纹通过。绑定使计划版本变化后,重新核对受影响节点与来源,不能用旧 expectedNodeVersion 提交。
35
+ 采用首次有效视频声音作为人物基准时,建议每批视频完成后、下一批提交前,逐说话人核对待绑定状态。已有清晰对白及可信的实际时间证据时,优先提取该人物样本、回读声音计划绑定,再核对后续模型的参考音频能力与真实输入;暂无可用样本或用户选择先继续生成时,保留 reference=null、具体限制和后续取样计划,说明一致性尚未验证,不以未取样阻断人工操作或整个 Agent 流程。首镜对白错误、ASR 与来源冲突或没有可分离区间时,不把它作为声音基准,也不凭剧本猜时间;使用首个可核对的有效样本,保留首次候选不可用的原因。ASR 仅提供转写和区间证据,不证明试听或声纹通过。绑定使计划版本变化后,重新核对受影响节点与来源,不能用旧 expectedNodeVersion 提交。
36
36
 
37
37
  声音补绑只允许把原先为空的逐人物参考补齐,不能替换已有声线、台词或其他制作约定。已生成视频保留其生成时的声音计划版本与未验证限制;可在来源校验通过后与补绑后的新镜头共同剪辑,不能把旧音轨冒认为使用了新参考。一般改写仍须修复失效来源;不要为了版本号一致重复生成旧视频。
38
38
 
@@ -57,3 +57,11 @@ PRODUCTION_VIDEO_SOURCE_STALE/预检错误的 blockers 列出同时发现的文
57
57
  ## 资源状态与媒体版本
58
58
 
59
59
  资源不再具有过期状态。编辑上游文档、配置、镜头、连线或选版,不会把下游标成 stale,也不要求为消除旧标记而重新选版或生成。历史 stale 标记按已有选版使用;媒体是否存在、归属、明确选择的版本和任务身份仍须核验。当前选中版本、最新生成候选与历史版本保持区别,切版仍走正式入口,旧任务不能覆盖新任务。
60
+
61
+ ## 制作选择与提问节奏
62
+
63
+ 每题只处理一个独立决策,不能把模型、分辨率、字幕、配乐等捆绑成一道题或套餐选项。常规每批 1–3 问,每次最多 4 问;超过时按依赖分多批,前批真实作答后再根据答案提出下一批。不要一次列出所有后续问题,也不要并发堆积待答批次。已确认选项和自由文本中的明确选择在后续及会话恢复时复用;未作答不是接受推荐值。
64
+
65
+ 首次确定视频生成方案前,先读取实时模型、分辨率选项及 video-upscale 专用节点能力,核对用户已有选择。方案未确认时必须询问是否采用“低分辨率生成后超分”;只提供真实可用的“低分辨率生成后超分”“直接以支持的较高分辨率生成”“保持低分辨率、不超分”选项,说明增加处理步骤、源画面细节与超分效果的取舍,不编造价格、耗时或输出尺寸保证。用户已明确选择或授权采用推荐方案时沿用,不重复提问;能力变化使方案不可用时只询问替代选择。选择记录在现有制作计划和对话中,不自造画布配置字段。
66
+
67
+ 新建或修订剪辑计划会显式保存 effects.burn_subtitles,默认 true;用户明确不要字幕时保存 false。历史计划不补写默认。交付核对真实渲染回执的 effects 与字幕条数,不以“含字幕”的节点标题代替烧录证据。ASR 整体空结果和部分来源缺失均须报告具体来源,不伪称无对白,不改用剧本文字或关闭字幕绕过。
@@ -20,3 +20,5 @@
20
20
  视频去字幕使用 `recreation-subtitle-remove`,深度视频使用 `depth-video`,片段截取使用 `recreation-shot-extract`,抽帧使用 `video-frame-extract`,音频提取使用 `video-audio-extract`,转写/翻译使用 `recreation-transcribe`。逐项读取各自端口与配置;本地截片不依赖生成模型。工具栏独有且目录未暴露的操作,明确报告能力缺口,不用相似节点伪造执行。
21
21
 
22
22
  旧厂商 SeedVR2.5、MuseTalk/PainterAV2V 等入口仍不恢复;历史 RunningHub 或 MuseTalk 配置不能作为新提交依据。旧提示词模板 `2d_to_live_action` 和 `image_prompt_modify` 仅保留历史项目读取含义。默认制作不额外引入内容审核门禁;用户明确要求审核时按对应合同执行。
23
+
24
+ 首次确定视频生成方案前,先读取实时模型、分辨率选项及 video-upscale 专用节点能力,核对用户已有选择。方案未确认时必须询问是否采用“低分辨率生成后超分”;只提供真实可用的“低分辨率生成后超分”“直接以支持的较高分辨率生成”“保持低分辨率、不超分”选项,说明增加处理步骤、源画面细节与超分效果的取舍,不编造价格、耗时或输出尺寸保证。用户已明确选择或授权采用推荐方案时沿用,不重复提问;能力变化使方案不可用时只询问替代选择。选择记录在现有制作计划和对话中,不自造画布配置字段。
@@ -8,7 +8,7 @@ Seedance 的逐镜检查按 [Seedance 2.0 逐镜提示词规范](../prompt/seeda
8
8
 
9
9
  ## 无限画布 Agent 写入路径
10
10
 
11
- 默认由 Agent 在真实选版的分镜、已选择的板型、声音计划和审核记录上逐镜编写最终提示词。先用纸面镜头表核对机位一侧、人物位置与朝向、视线、主动作、其他可见人物的持续行为、光线、道具持有的手及镜尾可见状态;内部表格不复制进模型提示词。每个参考素材先绑定实际用途,不发明未上传的 `@` 标签。Agent 使用 `canvas node write-video-prompt <节点ID> --project <项目ID> --file <UTF-8文件> --type h3|seedance --expected-version <画布版本>` 保存成品,回读文本资源及选版后才提交视频。新镜头使用自由 `video-generate` 节点作为写入目标,不再创建或执行 `storyboard-video-prompt` 生成节点;正式提示词保存为不可变普通文本资源并接入自由视频的 prompt。首次 basedOnVersionId 为空,改稿使用 canvas_inspect 返回的 videoPrompt.versionId(CLI 完整节点为 data.agentPromptVersionId),不能传视频选版。历史提示词生成节点仅兼容回读和改稿,不主动迁移或删除历史结果。
11
+ 默认由 Agent 在真实选版的分镜、已选择的板型、声音计划和审核记录上逐镜编写最终提示词。先用纸面镜头表核对机位一侧、人物位置与朝向、视线、主动作、其他可见人物的持续行为、光线、道具持有的手及镜尾可见状态;内部表格不复制进模型提示词。每个参考素材先绑定实际用途,不发明未上传的 `@` 标签。Agent 使用 `canvas node write-video-prompt <节点ID> --project <项目ID> --file <UTF-8文件> --type h3|seedance --expected-version <画布版本>` 保存成品,回读视频节点内提示词正文及正式提示词版本后才提交视频。新镜头使用自由 `video-generate` 节点作为写入目标,不再创建或执行 `storyboard-video-prompt` 生成节点;正式提示词保存为视频节点所属的不可变资产版本,在该视频节点内编辑,不新增文本节点或 prompt 连线。首次 basedOnVersionId 为空,改稿使用 canvas_inspect 返回的 videoPrompt.versionId(CLI 完整节点为 data.agentPromptVersionId),不能传视频选版。历史提示词生成节点仅兼容回读和改稿,不主动迁移或删除历史结果。
12
12
 
13
13
  H3 使用 Ref2VA 六段英文正文,保留原文对白,最终发给 Provider 的文本不得超过 7000 字符。Seedance 使用中文“本镜元数据与实际素材用途 → 画面和表演 → 镜尾”;对白保持原文。每个可见人物只写本镜可读的动作、注意对象、反应触发和结果,听者与说话者在同一段交叠表演。提示词长度由必要信息决定,不按任意字数填充;先删重复画质词和已由参考图表达的背景,再考虑调整动作密度。
14
14