@aswless_854771076/ai_short_studio_cli 0.1.60 → 0.1.62
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.
- package/README.md +4 -2
- package/dist/commands/canvas/node/types.js +1 -1
- package/dist/commands/canvas/settings/set.js +1 -1
- package/package.json +1 -1
- package/skills/using-vvicat-ai-short-studio-cli/SKILL.md +32 -306
- package/skills/using-vvicat-ai-short-studio-cli/references/assets-and-storyboard.md +57 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/async-pipeline.md +33 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/commands/assets-and-tasks.md +24 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/commands/canvas.md +50 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/commands/project.md +65 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/commands.md +13 -211
- package/skills/using-vvicat-ai-short-studio-cli/references/editing-delivery.md +48 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/h3-video-delivery.md +73 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/project-and-canvas.md +34 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/special-workflows.md +25 -0
- package/skills/using-vvicat-ai-short-studio-cli/references/troubleshooting.md +30 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# 滚动异步生成流水线
|
|
2
|
+
|
|
3
|
+
用于资产派生图、分镜图、视频提示词和视频生成。目标是让每个镜头独立向前流动，消除“等整批图片完成后才开始提示词”的阶段屏障。
|
|
4
|
+
|
|
5
|
+
## 调度模型
|
|
6
|
+
|
|
7
|
+
只运行一个调度器。生成命令只负责提交，不携带 `--wait`；调度器以短轮询读取画布和任务终态，并维护每个节点的 `nodeId / inputFingerprint / taskId / status / attempt / selectedVersionId / downstreamSubmitted`。轮询间隔通常 3–10 秒；长时间无变化时退避到 15–30 秒，状态变化后恢复短轮询。
|
|
8
|
+
|
|
9
|
+
镜头状态机：
|
|
10
|
+
|
|
11
|
+
`storyboard-image ready → image running → image done → image audit → storyboard-video-prompt running → prompt done → prompt audit → video config gate → video running → video audit → edit ready`
|
|
12
|
+
|
|
13
|
+
资产阶段同样异步提交人物、场景和道具派生图；但拆镜依赖本集全部必需资产确认，因此资产到拆镜之间保留一个明确 barrier。不存在依赖关系的资产不得互相等待。
|
|
14
|
+
|
|
15
|
+
## 即时触发规则
|
|
16
|
+
|
|
17
|
+
1. 分镜图进入 `done` 后立即刷新画布，定位服务端自动物化的图片资源和该镜 `storyboard-video-prompt`。先查看真实分镜图并执行该镜 P0/P1 审计；通过后立刻提交提示词，不等待其他分镜图。
|
|
18
|
+
2. 视频提示词进入 `done` 后立即读取真实文本，核对有效 `promptType=h3`、引用标签、镜头时长、逐字人声、声线、闭口约束、环境音、BGM 和转场。声音时间表放不下时只暂停该镜并修正；其他镜头继续。
|
|
19
|
+
3. 提示词通过后，在同一次 `canvas node update-many` 中给新物化的 `video-generate` 显式写入 `generateAudio: true`、分辨率和合法时长，逐节点回读，再立即提交视频。
|
|
20
|
+
4. 视频完成后立即下载真实 selected 版本，执行视觉、音频、转场、字幕四项验收；通过即进入剪辑候选池，失败只回退该镜。
|
|
21
|
+
|
|
22
|
+
## 并发、幂等与恢复
|
|
23
|
+
|
|
24
|
+
- 每类默认并发 4，总在途任务不超过 16；用户明确要求“全部提交”时可提高提交并发，但仍服从服务端能力、费用范围和全局上限。
|
|
25
|
+
- 同一 `nodeId + inputFingerprint` 已有 queued/running 任务时不得重复提交。任务完成后若 selected 版本、输入指纹或下游节点未变化，也不得重复触发。
|
|
26
|
+
- 服务端物化下游节点可能有短暂延迟；先刷新和重试查询，不手工创建重复节点。
|
|
27
|
+
- 网络、上传、`External task gone` 等可恢复错误只重试对应节点，使用有限指数退避；默认最多 3 次自动重试。内容审核、余额、权限、schema、模型能力和付费门禁错误禁止自动换模型或无限重试。
|
|
28
|
+
- 一个镜头失败不得阻塞无依赖的镜头。只有共享资产错误、全局配置错误、语言契约错误或用户要求停止时才暂停整条流水线。
|
|
29
|
+
- 用户要求停止时，先停止调度器，再读取所有 queued/running `taskId` 并逐个 `task cancel --yes`；取消后再次刷新，直到运行任务为 0。任务 API 已 404 但节点仍显示 running 时，报告为服务端残留状态，不再提交新任务。
|
|
30
|
+
|
|
31
|
+
## 进度汇报
|
|
32
|
+
|
|
33
|
+
按阶段报告 `完成 / 运行 / 失败 / 待提交` 数量，并说明自动重试和人工暂停镜头。不要把“已提交”写成“已完成”，也不要因为轮询仍在进行而重复提交任务。
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# 资产与任务命令
|
|
2
|
+
|
|
3
|
+
## 资产
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
ai-short-studio canvas asset list --project <projectId> --json
|
|
7
|
+
ai-short-studio canvas asset get <assetId> --project <projectId> --json
|
|
8
|
+
ai-short-studio canvas asset upload <file> --project <projectId> --json
|
|
9
|
+
ai-short-studio canvas asset select-version <assetId> --version <versionId> --project <projectId> --json
|
|
10
|
+
ai-short-studio canvas asset download <assetId> --project <projectId> --output <directory>
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
下载前确认 `selectedOutputVersionId`。原始视频按镜号保存为 `S001.mp4`、`S002.mp4`，manifest 至少记录 `shotNumber`、`nodeId`、`assetId`、`versionId`、`fileName`。
|
|
14
|
+
|
|
15
|
+
## 执行和等待
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
ai-short-studio canvas node run --project <projectId> --node <node1> --node <node2> --concurrency 4 --wait --json
|
|
19
|
+
ai-short-studio task get <taskId> --json
|
|
20
|
+
ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 --json
|
|
21
|
+
ai-short-studio task cancel <taskId> --yes --json
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
互不依赖的节点在一个 CLI 进程内批量运行；有依赖时分批。任务成功后仍需回读资产并查看真实产物，不能把成功状态当作质量验收。
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# 画布、节点与连线命令
|
|
2
|
+
|
|
3
|
+
## 聚合读取与补丁
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
ai-short-studio canvas inspect --project <projectId> --include summary --include nodes --include edges --include assets --include settings --include node-types --json
|
|
7
|
+
ai-short-studio canvas apply --project <projectId> --canvas-id <canvasId> --expected-version <version> --file patch.json --json
|
|
8
|
+
ai-short-studio canvas node types --json
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
常见审计优先通过 `inspect` 的 `--kind`、`--status`、`--search`、`--operation`、`--resource-type`、`--producer-node` 过滤。同阶段多个图变更用一次 `apply`；409 后重读并合并。
|
|
12
|
+
|
|
13
|
+
## 节点
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
ai-short-studio canvas node list --project <projectId> --json
|
|
17
|
+
ai-short-studio canvas node get <nodeId> --project <projectId> --json
|
|
18
|
+
ai-short-studio canvas node add <kind> --project <projectId> --config node.json --json
|
|
19
|
+
ai-short-studio canvas node update <nodeId> --project <projectId> --set 'gridSize=9' --json
|
|
20
|
+
ai-short-studio canvas node update-many --project <projectId> --file updates.json --json
|
|
21
|
+
ai-short-studio canvas node edit-shot <nodeId> --project <projectId> --file shot.json --json
|
|
22
|
+
ai-short-studio canvas node edit-resource <nodeId> --project <projectId> --file resource.json --json
|
|
23
|
+
ai-short-studio canvas node delete <nodeId> --project <projectId> --yes --json
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
`update` 只改普通 config、标题和坐标；结构化 artifact 必须用 `edit-shot` / `edit-resource` 追加版本。身份字段不可修改，409 后重新读取当前选版。
|
|
27
|
+
|
|
28
|
+
H3 批量启用原生音频的 `updates.json`：
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{
|
|
32
|
+
"updates": [
|
|
33
|
+
{ "nodeId": "<videoNodeId>", "set": { "generateAudio": true } }
|
|
34
|
+
]
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
提交前以实时命令 schema 为准，提交后逐节点 `get` 回读。
|
|
39
|
+
|
|
40
|
+
## 连线与连续性
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
ai-short-studio canvas edge list --project <projectId> --json
|
|
44
|
+
ai-short-studio canvas edge add --project <projectId> --from <sourceNodeId>:<sourceHandle> --to <targetNodeId>:<targetHandle> --json
|
|
45
|
+
ai-short-studio canvas edge delete <edgeId> --project <projectId> --yes --json
|
|
46
|
+
ai-short-studio canvas continuity analyze --project <projectId> --json
|
|
47
|
+
ai-short-studio canvas continuity analyze --project <projectId> --apply-ready --json
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
handle 来自实时节点目录。只删除精确 edge ID；`--apply-ready` 只在用户确认连续性建议后执行。
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# 项目与配置命令
|
|
2
|
+
|
|
3
|
+
## 预检、Skill 与认证
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
ai-short-studio preflight --json
|
|
7
|
+
ai-short-studio skill status --target codex --json
|
|
8
|
+
ai-short-studio auth signup --email user@example.com --password-stdin
|
|
9
|
+
ai-short-studio auth login --google
|
|
10
|
+
ai-short-studio auth login --email user@example.com --password-stdin
|
|
11
|
+
ai-short-studio auth status --json
|
|
12
|
+
ai-short-studio auth logout
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
更新 CLI 后重跑 preflight。邮箱密码只从隐藏输入或安全 stdin 读取；`confirmationRequired: true` 时先完成邮件确认。
|
|
16
|
+
|
|
17
|
+
## 项目与供应商
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
ai-short-studio project list --json
|
|
21
|
+
ai-short-studio project get <projectId> --json
|
|
22
|
+
ai-short-studio project create --name <name> [--description <text>] --json
|
|
23
|
+
ai-short-studio project update <projectId> [--name <name>] [--description <text>] --json
|
|
24
|
+
ai-short-studio project delete <projectId> --yes --json
|
|
25
|
+
ai-short-studio project provider get <projectId> --json
|
|
26
|
+
ai-short-studio project provider set <projectId> --json
|
|
27
|
+
ai-short-studio project provider test <projectId> --json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`provider set` 的 Key 只从安全 stdin 或秘密管理器提供。删除既有项目必须取得明确授权。
|
|
31
|
+
|
|
32
|
+
## Settings
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
ai-short-studio canvas settings get --project "$PROJECT_ID" --json
|
|
36
|
+
ai-short-studio canvas settings set --project "$PROJECT_ID" --file settings.json --json
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
标准文件包含最近读取的版本和全部已确认变更：
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"expectedVersion": 3,
|
|
44
|
+
"values": {
|
|
45
|
+
"outputLanguage": "zh",
|
|
46
|
+
"aspectRatio": "9:16",
|
|
47
|
+
"imageResolution": "2K",
|
|
48
|
+
"imageQuality": "high",
|
|
49
|
+
"videoModel": "runninghub::minimax-h3-reference-to-video",
|
|
50
|
+
"videoPromptType": "h3",
|
|
51
|
+
"videoResolution": "1K"
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`null` 或空字符串清除项目覆盖。409 后重新读取、展示变化并确认，不盲目覆盖。
|
|
57
|
+
|
|
58
|
+
## 账户配置
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
ai-short-studio config get --json
|
|
62
|
+
ai-short-studio config set --file config.json --json
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`config set` 只接受个人默认模型、能力默认值和并发；供应商、密钥与全局模型目录只能由管理员维护。
|
|
@@ -1,219 +1,21 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 命令路由
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
只读取当前操作对应的命令文件：
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
- 预检、认证、项目、供应商、settings、账户配置：[commands/project.md](commands/project.md)
|
|
6
|
+
- 画布聚合、节点、连线、结构化编辑和连续性：[commands/canvas.md](commands/canvas.md)
|
|
7
|
+
- 资产、选版、下载、异步任务和批量执行：[commands/assets-and-tasks.md](commands/assets-and-tasks.md)
|
|
8
|
+
- 滚动提交与任务恢复策略：[async-pipeline.md](async-pipeline.md)
|
|
9
|
+
- 剪辑、字幕、声音和最终渲染：[editing-delivery.md](editing-delivery.md)
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
所有命令支持 `--base-url`、`--profile`、`--locale zh|en` 和 `--json`。`--locale` 只控制 CLI 消息，不控制剧本、拆镜、H3 人声或字幕语言。
|
|
8
12
|
|
|
9
|
-
|
|
10
|
-
ai-short-studio --version
|
|
11
|
-
ai-short-studio preflight --json
|
|
12
|
-
ai-short-studio preflight --no-update --json
|
|
13
|
-
```
|
|
13
|
+
## 跨流程硬规则
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
项目配置先运行 `canvas settings get`，核对 `currentValue`、`effectiveValue`、`source` 和实时 options。`$ART_STYLE_ID` 必须解析 `option.value`。标准创作门禁必须用 `canvas settings set --file settings.json` 并携带 `expectedVersion`，写后回读；不得用账户 config、项目描述或节点 prompt 代替。
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
最终 `videoModel.effectiveValue` 为 `comfly::minimax-h3` 或 `runninghub::minimax-h3-reference-to-video` 时，必须写入 `videoPromptType: "h3"`；仅有效的节点 `promptType` 可覆盖项目值，旧 `seedance` 必须清除并回读，否则不得执行视频提示词或视频生成。实时能力 `generateAudioOptions` 必须包含 `true`，H3 节点显式设置并回读 `generateAudio: true`。
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
ai-short-studio skill path --json
|
|
21
|
-
ai-short-studio skill install --target codex --json
|
|
22
|
-
ai-short-studio skill status --target codex --json
|
|
23
|
-
ai-short-studio skill update --target codex --json
|
|
24
|
-
```
|
|
19
|
+
视频时长读取实时 `durationOptions`。只有实时选项恰为 5、10、15 秒时才按这三档向上取整。RunningHub MiniMax H3 支持纯文本，5–15 秒逐秒可选，1–4 秒归一为 5 秒；画幅为 16:9 / 9:16，分辨率为 480p / 720p / 1K / 2K。
|
|
25
20
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
## 认证
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
ai-short-studio auth signup --email user@example.com --password-stdin
|
|
32
|
-
ai-short-studio auth login --google
|
|
33
|
-
ai-short-studio auth login --email user@example.com --password-stdin
|
|
34
|
-
ai-short-studio auth status --json
|
|
35
|
-
ai-short-studio auth logout
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
Google 登录会打开浏览器并通过本机环回地址完成 PKCE 回调。Windows 直接调用系统 URL Handler，避免授权 URL 中 `&` 后的 `redirect_to` 和 PKCE 参数被命令解释器截断；若授权后仍跳到站点默认地址，先更新 CLI 并重试。
|
|
39
|
-
邮箱注册的密码只从隐藏输入或 stdin 读取。`confirmationRequired: true` 时需先完成邮件验证再登录；为 `false` 时 CLI 已保存会话。
|
|
40
|
-
邮箱注册确认链接由当前 profile 的 `baseUrl` 和 `--locale` 生成，格式为同域的 `/{locale}/auth/callback`。Supabase Redirect URLs 必须允许对应环境的 `/**`，无需为本地或测试注册修改全局 Site URL。
|
|
41
|
-
|
|
42
|
-
## 项目
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
ai-short-studio project list --json
|
|
46
|
-
ai-short-studio project get <projectId> --json
|
|
47
|
-
ai-short-studio project create --name <name> [--description <text>] --json
|
|
48
|
-
ai-short-studio project update <projectId> [--name <name>] [--description <text>] --json
|
|
49
|
-
ai-short-studio project delete <projectId> --yes --json
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
创建操作固定写入 `INFINITE_CANVAS`；列表也只返回该类型。
|
|
53
|
-
|
|
54
|
-
### 项目素材供应商
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
ai-short-studio project provider get <projectId> --json
|
|
58
|
-
ai-short-studio project provider set <projectId> --json
|
|
59
|
-
ai-short-studio project provider test <projectId> --json
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
`provider set` 从 stdin 读取 `{ "enabled": true, "apiKey": "..." }`，也可用 `--file`。真实 Key 只能来自安全 stdin 或秘密管理器；不得把它写入命令参数、仓库文件或文档。省略 `apiKey` 会保留已保存的 Key，只更新启用状态。读取命令只返回遮罩状态。
|
|
63
|
-
|
|
64
|
-
### 项目配置
|
|
65
|
-
|
|
66
|
-
```bash
|
|
67
|
-
ai-short-studio canvas settings get --project "$PROJECT_ID" --json
|
|
68
|
-
ai-short-studio canvas settings set --project "$PROJECT_ID" --field aspectRatio --value 9:16 --json
|
|
69
|
-
ai-short-studio canvas settings set --project "$PROJECT_ID" --field artStyle --value "$ART_STYLE_ID" --json
|
|
70
|
-
ai-short-studio canvas settings set --project "$PROJECT_ID" --field imageResolution --value 2K --json
|
|
71
|
-
ai-short-studio canvas settings set --project "$PROJECT_ID" --field outputLanguage --value en --json
|
|
72
|
-
ai-short-studio canvas settings set --project "$PROJECT_ID" --file settings.json --json
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
`settings get` 返回 `canvasId`、`version` 和各配置字段。每个字段包含项目覆盖值 `currentValue`、继承后的最终值 `effectiveValue` 与来源 `source`。画风、画幅、分镜类型、格数和模型候选从实时 `options` 读取；`visualBible` 返回 `schema`，不返回 `options`。CLI 和 Agent 都不得硬编码服务端枚举。示例中的 `$ART_STYLE_ID` 必须从 `artStyle.options` 选择并解析实时 `option.value`。
|
|
76
|
-
|
|
77
|
-
`settings set` 只修改 `values` 中出现的字段。标准创作门禁必须用 `--file` 或 stdin 一次原子写入，并把最近一次 `settings get` 返回的 `version` 填入请求的 `expectedVersion`；`--field/--value` 只适合已确认无并发写入的交互式便利操作：
|
|
78
|
-
|
|
79
|
-
```json
|
|
80
|
-
{
|
|
81
|
-
"expectedVersion": 3,
|
|
82
|
-
"values": {
|
|
83
|
-
"aspectRatio": "9:16",
|
|
84
|
-
"storyboardGridSize": 6,
|
|
85
|
-
"imageResolution": "2K",
|
|
86
|
-
"imageQuality": "high",
|
|
87
|
-
"videoResolution": "1080p",
|
|
88
|
-
"videoModel": "runninghub::minimax-h3-reference-to-video",
|
|
89
|
-
"videoPromptType": "h3"
|
|
90
|
-
}
|
|
91
|
-
}
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
最终生效的 `videoModel.effectiveValue` 为 `comfly::minimax-h3` 或 `runninghub::minimax-h3-reference-to-video` 时，必须和 `videoPromptType: "h3"` 在同一次批量设置中写入；非 H3 模型按用户确认值写入或保留提示词类型。运行既有 `storyboard-video-prompt` 前读取节点原始 config；仅有效的节点 `h3` / `seedance` 值优先于项目设置。H3 项目中的 `seedance` 必须清除；非法值不会覆盖项目值，但也应清除。用一次 `canvas node update-many` 提交 `{ "updates": [{ "nodeId": "<id>", "unset": ["promptType"] }] }` 并回读确认。任一模型、项目类型或有效节点覆盖不一致时不得执行视频提示词或视频生成节点。
|
|
95
|
-
|
|
96
|
-
`null` 或空字符串会清除项目覆盖并恢复账户默认或系统默认继承。设置 `artStyle` 时，服务端会把画风当前关联的 `visualBible` 保存为项目快照；画风库后续修改不会反向更新既有项目。同一请求显式提供 `visualBible` 时，显式值覆盖画风快照。
|
|
97
|
-
|
|
98
|
-
所有者和管理员可执行 `settings set`，协作者只能执行 `settings get`。批量写入是原子的；建议携带最近一次读取的 `expectedVersion`，遇到 409 后重新运行 `settings get`、核对变化并取得确认，再携带新版本重试，不得盲目覆盖。Pexels 配置仍由 `project provider get|set|test` 管理，不属于 canvas settings。
|
|
99
|
-
|
|
100
|
-
## 画布和节点
|
|
101
|
-
|
|
102
|
-
```bash
|
|
103
|
-
ai-short-studio canvas get --project <projectId> --json
|
|
104
|
-
ai-short-studio canvas inspect --project <projectId> --include summary --include nodes --include edges --include assets --include settings --include node-types --json
|
|
105
|
-
ai-short-studio canvas inspect --project <projectId> --kind storyboard-image --status stale --operation image-resource --json
|
|
106
|
-
ai-short-studio canvas apply --project <projectId> --canvas-id <canvasId> --expected-version <version> --file <patch.json> --json
|
|
107
|
-
ai-short-studio canvas node types --json
|
|
108
|
-
ai-short-studio canvas node list --project <projectId> --json
|
|
109
|
-
ai-short-studio canvas node get <nodeId> --project <projectId> --json
|
|
110
|
-
ai-short-studio canvas node add <kind> --project <projectId> [--x N] [--y N] [--title <text>] [--config <config.json>] --json
|
|
111
|
-
ai-short-studio canvas node update <nodeId> --project <projectId> --config <config.json> --json
|
|
112
|
-
ai-short-studio canvas node update <nodeId> --project <projectId> --set 'gridSize=9' --unset legacyField --title <text> --json
|
|
113
|
-
ai-short-studio canvas node update-many --project <projectId> --file <updates.json> --json
|
|
114
|
-
ai-short-studio canvas node edit-shot <nodeId> --project <projectId> [--file <shot.json>] --json
|
|
115
|
-
ai-short-studio canvas node edit-resource <nodeId> --project <projectId> [--file <resource.json>] --json
|
|
116
|
-
ai-short-studio canvas node delete <nodeId> --project <projectId> --yes --json
|
|
117
|
-
ai-short-studio canvas node run --project <projectId> --node <node1> --node <node2> --concurrency 4 --wait --json
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
`canvas inspect` 一次读取画布并聚合常见审计结果。`--include` 可重复指定 summary、nodes、edges、assets、settings、node-types；`--kind`、`--status`、`--search`、`--operation`、`--resource-type`、`--producer-node` 用于筛选。覆盖这些条件的查询不再编写临时脚本。
|
|
121
|
-
|
|
122
|
-
`canvas apply` 的 JSON 可以通过 `--file` 读取；省略文件时从 stdin 读取。若已有画布快照，传入 `--canvas-id` 和 `--expected-version` 后不会额外预读全图；缺少任一参数时保持兼容，CLI 自动读取版本。该命令保留给节点、连线、删除、视口等低层画布图补丁；常规项目配置使用 `canvas settings get|set`。同一阶段存在两个及以上可合并的图变更时，默认用一次 `canvas apply` 提交 `upsertNodes`、`upsertEdges`、`deleteNodeIds` 和 `deleteEdgeIds` 等完整差异，成功后统一回读；批量入口不存在、服务不支持，或合法请求仍因批量粒度失败时，才回退对应的 node/edge 单条命令并只处理尚未生效项。409 应重读、合并并确认后继续重试批量；401/403、参数、schema、业务门禁或付费确认错误必须先修正，不能通过单条命令绕过。
|
|
123
|
-
|
|
124
|
-
`canvas node update --set key=<JSON> --unset key` 只修改指定 config 字段，也可同时更新标题与坐标；`--config` 保持兼容。`update-many` 输入 `{ "updates": [...] }`，一次读取画布和 schema 后原子更新多个节点。结构化生成资源仍必须走 `edit-resource` 或 `edit-shot`。批量节点执行和任务等待默认并发 4、上限 16，优先在一个进程内运行。`storyboardGridSize` 仅在节点级 `gridSize` 无法使用的异常回退中经用户确认后写入；正常流程继续按镜头复杂度设置各节点的 `gridSize`。
|
|
125
|
-
|
|
126
|
-
## 连线
|
|
127
|
-
|
|
128
|
-
```bash
|
|
129
|
-
ai-short-studio canvas edge list --project <projectId> --json
|
|
130
|
-
ai-short-studio canvas edge add --project <projectId> --from <sourceNodeId>:<sourceHandle> --to <targetNodeId>:<targetHandle> --json
|
|
131
|
-
ai-short-studio canvas edge delete <edgeId> --project <projectId> --yes --json
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
网页增量保存使用 `Prefer: return=minimal` 获取固定大小回执；CLI 的后续命令依赖完整画布，因此显式使用 `Prefer: return=representation`。正常保存前不额外读取全图；发生 409 时重新读取最新画布、合并本地补丁并确认后重试。
|
|
135
|
-
|
|
136
|
-
`canvas node edit-shot` 的文件或 stdin 内容是镜头字段对象，可编辑 `photographyPlan` 对象和 `actingNotes` 对象或数组。命令读取当前画布版本和当前资产选版后追加一个人工 DOCUMENT 版本；`shotKey`、`shotIndex` 和来源身份不可修改，旧版本不会被覆盖或删除。
|
|
137
|
-
|
|
138
|
-
`canvas node edit-resource` 的文件或 stdin 内容是剧本、人物、人物视觉、场景、子场景或道具资源的 JSON 对象。命令读取最新画布版本与目标节点的 `selectedOutputVersionId`，在该版本的完整父文档中只替换 `resourceKey` 对应实体，再追加并固定当前节点的新选版；名称、资源键、ID、所属人物或场景等身份字段不可修改，兄弟资源节点保持原选版，下游递归标记 stale。缺少稳定 `operation/resourceKey/resourceType` 的旧节点只读，不能按标题猜测。该写入不属于 `canvas apply`；409 后重新读取画布与选版并确认，不得盲目覆盖。
|
|
139
|
-
|
|
140
|
-
首尾帧提取使用实时目录中的 `video-frame-extract`，配置为 `{"position":"first"}` 或 `{"position":"last"}`。输入连接 `video`，输出 `image` 是独立 IMAGE 资产版本并记录来源视频版本。`previous-tail` 只记录连续性需求，不自动物化尾帧拓扑；用户可确认预检建议或手动建立节点与连线。创建这些节点与连线不会自动执行或付费。
|
|
141
|
-
|
|
142
|
-
原始视频交付先按镜号读取视频节点的 `selectedOutputVersionId`，再逐个执行 `canvas asset download`，保存为 `S001.mp4`、`S002.mp4`……。同时生成逐行 `manifest`，每行包含 `shotNumber`、`nodeId`、`assetId`、`versionId`、`fileName`。只下载 selected 原始 MP4；字幕单独交付，不混入分镜图、音频中间件或烧录字幕版本。
|
|
143
|
-
|
|
144
|
-
handle 名称来自节点类型目录中的输入输出 schema，不要自行推断。
|
|
145
|
-
|
|
146
|
-
## 镜头连续性
|
|
147
|
-
|
|
148
|
-
```bash
|
|
149
|
-
ai-short-studio canvas continuity analyze --project <projectId> --json
|
|
150
|
-
ai-short-studio canvas continuity analyze --project <projectId> --apply-ready --json
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
该命令用于新旧镜头的连续性分析和人工审计。新规划镜头直接读取 `independent` 或 `previous-tail`，但服务端不会自动创建尾帧节点或 `start-frame` 连线，也不会因依赖未完成阻止后镜独立生成。前镜视频完成后，用户可确认建议再显式执行 `--apply-ready`。
|
|
154
|
-
|
|
155
|
-
### Meme 专属节点流程
|
|
156
|
-
|
|
157
|
-
Meme 视频默认使用 `meme-scene-analysis` → `meme-material-search` → `cat-meme-video`，禁止静默改用 `storyboard-*` 或通用 `video-generate`。项目中的 Seedance 等 `videoModel` 不参与 `cat-meme-video` 合成；只有用户明确要求生成式视频并确认额外费用与画风变化后，才可使用通用视频节点。
|
|
158
|
-
|
|
159
|
-
1. 连接 `text.text → meme-scene-analysis.story`，运行并等待任务终态。
|
|
160
|
-
2. 刷新画布，复用自动创建的计划资源和 `meme-material-search`；不要手工添加重复节点。
|
|
161
|
-
3. 运行素材检索。即使不使用外部素材也不能跳过：Pexels 可关闭，内置背景、内置道具和库外道具图片生成仍在该节点完成。
|
|
162
|
-
4. 刷新画布，复用自动创建的 `cat-meme-video`，核对原故事、计划和素材包三条输入边，并确认素材包没有无法复用的必显道具缺失项。
|
|
163
|
-
5. 按实时 schema 设置节点的 `aspectRatio: "1:1" | "9:16" | "16:9"` 和 `resolution: "720p" | "1080p"`，运行并等待终态，再下载和审计真实视频。
|
|
164
|
-
|
|
165
|
-
错误恢复固定为：`CAT_MEME_REQUIRED_PROP_MISSING` 回到素材检索；`CAT_MEME_DISPLAY_CONTENT_REQUIRED` 修复计划；`CAT_MEME_FFMPEG_FAILED` 修复或部署渲染器后重试。不得把失败当作切换通用视频生成的授权。
|
|
166
|
-
|
|
167
|
-
项目级默认参数使用 `canvas settings set` 写入 `imageResolution`、`imageQuality`、`videoResolution`；候选值读取 `settings get` 对应字段的实时 `options`。通用 `image-generate`、`image-edit` 节点只在需要偏离项目默认时，才在 `config` 写入字符串 `resolution`、`quality`；`video-generate` 同理可覆盖 `resolution`。节点覆盖值必须来自当前节点模型 `capabilities`，没有对应能力声明时不写入。
|
|
168
|
-
|
|
169
|
-
RunningHub MiniMax H3 的实时 `aspectRatio` 只有 16:9、9:16，`resolution` 只有 480p、720p、1K、2K，默认为 1K。
|
|
170
|
-
|
|
171
|
-
## 资产与下载
|
|
172
|
-
|
|
173
|
-
```bash
|
|
174
|
-
ai-short-studio canvas asset list --project <projectId> --json
|
|
175
|
-
ai-short-studio canvas asset get <assetId> --project <projectId> --json
|
|
176
|
-
ai-short-studio canvas asset upload <file> --project <projectId> --json
|
|
177
|
-
ai-short-studio canvas asset select-version <assetId> --version <versionId> --project <projectId> --json
|
|
178
|
-
ai-short-studio canvas asset download <assetId> --project <projectId> --output <directory>
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
`canvas asset upload` 会按文件扩展名为常见图片、视频和音频设置 MIME 类型；未知扩展名使用 `application/octet-stream`。
|
|
182
|
-
|
|
183
|
-
## 异步任务
|
|
184
|
-
|
|
185
|
-
```bash
|
|
186
|
-
ai-short-studio task get <taskId> --json
|
|
187
|
-
ai-short-studio task wait <taskId> [--interval 1000] --json
|
|
188
|
-
ai-short-studio task wait --task <task1> --task <task2> --concurrency 4 [--interval 1000] --json
|
|
189
|
-
ai-short-studio task cancel <taskId> --yes --json
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
## 模型配置
|
|
193
|
-
|
|
194
|
-
```bash
|
|
195
|
-
ai-short-studio config get --json
|
|
196
|
-
ai-short-studio config set --file <config.json> --json
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
`config set` 只接受 `defaultModels`、`capabilityDefaults`、`workflowConcurrency` 的部分对象；CLI 与服务端都会拒绝 `providers` 或 `models`。Provider 密钥和全局模型目录只能由管理员后台维护。预检仅缺 `capabilityDefaults.<modelKey>.<field>` 时，先用 `config get` 核对实时 options，优先复用目标项目有效设置，其次使用服务端模型默认值，否则使用 options 第一项；合并写入后回读并重跑 preflight，不先把可自动修复项反馈给用户。账户级 `config set` 不得代替项目的 canvas settings。
|
|
200
|
-
|
|
201
|
-
## 标准创作命令顺序
|
|
202
|
-
|
|
203
|
-
先执行 `preflight`；若只缺可确定的账户能力默认值，立即用一次 `config set` 自动补齐、回读并重跑。通过后继续 `config get` → `canvas node types` → `project list`。新项目随后按“确认名称/用途 → `project create` → `project get` + 一次 `canvas inspect` 聚合查询”继续，不要求创建前读取不存在的项目或画布；既有项目读取同样的已有资源。只有聚合结果缺少专用命令独有字段时才补充单项查询。
|
|
204
|
-
|
|
205
|
-
取得配置后，向用户展示项目名称/用途，并逐项确认 `aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`analysisModel`、`imageModel`、`imageResolution`、`imageQuality`、`editModel`、`videoModel`、`videoPromptType`、`videoResolution`、`audioModel` 的 `currentValue`、`effectiveValue`、建议值与 `source`；候选值和视觉圣经结构分别以实时 `options` 与 `schema` 为准。用户未指定分镜类型时推荐 `storyboardImageType: grid`（分镜板/宫格分镜），不推荐 `storyboard`（故事版）。模型可项目覆盖，也可由用户明确确认继承账户默认，但必须明确最终生效且可用的具体模型。`storyboardGridSize` 仅在异常回退时确认。同一阶段的多个画布写操作默认合并到一次 `canvas apply`，批量不可用或合法批量请求仍因批量粒度失败时才回退单条 node/edge 命令。
|
|
206
|
-
|
|
207
|
-
项目名称和用途先由用户确认；新项目用 `project create` 保存，既有项目需要变更时仅用 `project update` 修改用户确认的项目字段。把确认的配置用一次 `canvas settings set` 原子写入并携带 `expectedVersion`，随后再次 `settings get` 回读。只有结果与确认一致且所需模型可用，才执行 node add/edge add/node run。写入、权限、冲突、回读或模型校验失败时停在配置阶段，不触发付费任务。账户级 `config set` 自动修复只补预检缺失的能力默认值，不能替代项目 settings；项目 `description`、节点 `prompt`/`config` 和低层 `canvas apply` 同样不能替代。
|
|
208
|
-
|
|
209
|
-
执行 `storyboard-breakdown` 前，必须先完成本次故事涉及的全部人物、场景、道具等素材节点：互不依赖的节点用一次 `canvas node run` 重复传 `--node`，需要同步等待时加 `--wait`；已有多个任务 ID 时用一次 `task wait` 重复传 `--task`。有上游依赖的节点按依赖顺序分批执行，不得为了等待单个任务而串行提交其他独立素材。全部任务成功后，用聚合查询或 `canvas asset get/list` 核对并在用户确认后设置 selected version。随后依据实时 schema 连接素材，并用一次 `canvas inspect` 核对无遗漏。任一素材任务未成功、selected version 为空或对应连线缺失时，都不得执行分镜拆解；素材范围不清楚时先询问用户。即使服务端 schema 把人物、场景或道具输入标为可选，标准创作流程也不能跳过本次故事实际涉及且已确认使用的素材。
|
|
210
|
-
|
|
211
|
-
专业 Markdown 纯文本拆镜使用 `{"storyboardPipelineVersion":2,"sourceFormat":"screenplay-markdown.v1","targetLanguage":"en","platform":"TikTok","aspectRatio":"9:16"}`，阿语集把语言改为 `ar`。只连接一条剧本与该集实际涉及的文字资产。该模式不执行声音、TTS、图片、音频或视频生成；完成后用任务、画布和资产回读确认只新增分镜文本/镜头，失败时零分镜持久化。
|
|
212
|
-
|
|
213
|
-
生成 `storyboard-image` 前，用 `canvas asset get/list` 取得素材 selected version，必要时通过 `canvas asset download` 下载，并向用户实际展示人物、场景、道具等预览；用户确认后才可执行。用户未指定布局时推荐并使用 `imageLayout: grid`（分镜板/宫格分镜），`storyboard`（故事版）与 `single` 仅在用户明确选择时使用。逐镜头根据需要独立呈现的动作、表情、主体关系、视角和空间调度状态选择最小够用的 `gridSize`，不得沿用统一格数或仅按时长推算；先用实时节点 schema 核对允许值，再向用户列出“镜号、复杂度依据、建议格数”，确认后逐个更新对应 `storyboard-image` 节点。生成视频前，同样取得并展示实际分镜图或可访问预览，确认分镜图和视频镜头范围后才可执行 `storyboard-video-prompt` / `video-generate`。仅输出资产 ID、URL、文件路径或成功状态不能代替展示；任一确认缺失时停止并询问。
|
|
214
|
-
|
|
215
|
-
用户未指定画幅时，角色、道具、场景/背景、分镜图及其他视觉参考素材统一使用 `16:9`；实时 schema 支持 `aspectRatio` 时显式写入节点，避免继承项目中的其他画幅。视频时长以当前模型实时 `durationOptions` 为准。只有实时模型仅提供 5、10、15 秒时，才按镜头目标时长向上取这三档，并保留原目标时长供剪辑裁切；其他模型使用经用户确认的实时合法值。RunningHub MiniMax H3 暴露 5–15 秒的每个整数，支持不连任何媒体的纯文本生成，服务端会把 1–4 秒归一为 5 秒。参考音频仍不能作为唯一媒体输入；纯文本是零媒体，不是 audio-only。
|
|
216
|
-
|
|
217
|
-
每批生成完成后都必须自我审计：重新读取任务、画布、节点、连线和资产，核对终态、selected version、输入引用、最终有效画幅、视频时长仍属于实时 `durationOptions` 的合法值、模型与布局，并实际查看预览中的身份、场景、道具、动作、连续性及黑帧、拉伸、裁切、破音或空结果。输出通过项、缺陷、失败项和未决项；再次付费生成、改选版本或覆盖用户内容前先取得确认。
|
|
218
|
-
|
|
219
|
-
`storyboard-breakdown`、`storyboard-image` 和 `storyboard-video-prompt` 成功后会由服务端物化下游节点。每步完成后先重新 `canvas get` 或 `canvas node list` 获取真实 ID，禁止照示例伪造 ID 或重复建节点。
|
|
21
|
+
结构化资源使用 `canvas node edit-resource`，镜头使用 `canvas node edit-shot`。Meme 使用 `meme-scene-analysis → meme-material-search → cat-meme-video`，禁止静默切换通用视频；`CAT_MEME_REQUIRED_PROP_MISSING` 返回素材检索修复。
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# 剪辑与交付流程
|
|
2
|
+
|
|
3
|
+
涉及时间线、字幕、转场、音频处理或渲染时，先加载 `remotion-best-practices`，并按实际需要读取其中 captions、markup 和 rendering 参考。H3 人声、旁白、环境音与 BGM 仍以每镜原生整轨为唯一来源；允许轻量修整，不允许外部 TTS、配音或音乐覆盖原生失败。
|
|
4
|
+
|
|
5
|
+
## 1. 入库与选镜
|
|
6
|
+
|
|
7
|
+
- 只下载逐镜四项验收通过的 selected 视频版本；保留原文件，不在源文件上覆盖写入。
|
|
8
|
+
- 用媒体探针记录分辨率、帧率、时长、编码、音频采样率、声道和实际响度；坏帧、黑帧、冻结、闪烁、静音或损坏文件不得入时间线。
|
|
9
|
+
- 建立 manifest：镜号、shot/node/task/asset/version、源文件、入出点、时间线起止、转场、字幕、音频处理、验收结论和重跑记录。
|
|
10
|
+
|
|
11
|
+
## 2. 粗剪与节奏
|
|
12
|
+
|
|
13
|
+
- 先按叙事因果和镜头设计建立粗剪，再裁掉模型常见的无效开头、重复动作、动作回弹和空白尾帧；不得截断对白、呼吸、关键拟音或转场遮挡余量。
|
|
14
|
+
- 优先在动作峰值、视线落点、对白意群结束、声音瞬态或构图匹配点切换。反应镜头至少保留可感知的停顿，不为追求快节奏删掉情绪落点。
|
|
15
|
+
- 相邻镜使用 J-cut 或 L-cut 延续环境声、旁白或对白尾韵时，确保说话者归属清楚、口型不冲突；H3 原生整轨只能做短重叠和增益包络，不能拆出伪造的新对白。
|
|
16
|
+
|
|
17
|
+
## 3. 字幕与介绍角标
|
|
18
|
+
|
|
19
|
+
- 字幕必须以实际成片音轨的转写和人工复核为准，不能直接把提示词当转写。逐句核对文本、语言、说话者、起止时间和漏字；实际人声错误应重跑镜头，不用字幕掩盖。
|
|
20
|
+
- 默认烧录对白与旁白字幕，同时输出 UTF-8 SRT 和 ASS。字幕按语义断句，避免孤立标点和过长单行；通常最多两行，并保留移动端与横屏安全区。对白与旁白用一致但可区分的样式，不遮挡脸、手、关键道具和画面内文字。
|
|
21
|
+
- 人物首次清晰出现时显示 2–4 秒人物角标，可含姓名和必要身份；场景首次建立时显示 2–4 秒地点/时间角标。信息来自已确认资产和剧本，不凭空补职业、地点或日期。重复出现不反复介绍，快速切镜可顺延到首个稳定构图。
|
|
22
|
+
- 角标使用克制的淡入/淡出或短位移动画，不与对白字幕争抢同一区域；片头、章节卡、片尾署名仅在项目确有需求时添加。
|
|
23
|
+
|
|
24
|
+
## 4. 镜头衔接
|
|
25
|
+
|
|
26
|
+
- **硬切**：对白反应、信息揭示、节奏冲击和已具备构图连续性的镜头优先。
|
|
27
|
+
- **动作切 / 视线切 / 构图匹配**：在同一动作、视线方向、主体位置或形状上切换，优先于通用特效。
|
|
28
|
+
- **遮挡匹配**：按 H3 生成前设计的遮挡点重叠约 0.2–0.5 秒，对齐方向、速度、亮度和声音桥。
|
|
29
|
+
- **短淡化或叠化**：只用于时间流逝、地点转换、记忆、梦境或明确的情绪停顿。常规衔接约 6–12 帧；首镜可淡入、末镜可淡出。不得给每一镜统一套淡入淡出，也不得用长叠化掩盖人物、机位或动作不连续。
|
|
30
|
+
- 转场期间检查双影、闪白、黑场、方向反转、台词被截断和两个 BGM 同时争抢；不成立时回到受影响镜头或切点修正。
|
|
31
|
+
|
|
32
|
+
## 5. 声音平衡
|
|
33
|
+
|
|
34
|
+
- 先统一对白/旁白可懂度，再处理环境音、动作音和 BGM。用短增益包络让对白出现时原生 BGM 适度让位，保留空间感和关键拟音，不把所有底噪压成真空。
|
|
35
|
+
- 允许对每镜原生整轨做轻微增益、EQ、降噪、压缩、限幅、去爆音和首尾淡化；处理必须整轨可逆并记录在 manifest，不得改变说话者或用外部声音补洞。
|
|
36
|
+
- 相邻镜匹配感知响度、底噪和空间混响，J/L-cut 处避免音量突跳。平台无特殊要求时，全片目标约 -14 至 -16 LUFS，true peak 不高于 -1 dBTP；最终以完整试听无削波、泵动、破音和人声被盖为准。
|
|
37
|
+
|
|
38
|
+
## 6. 画面统一与精剪
|
|
39
|
+
|
|
40
|
+
- 统一画幅、帧率、色彩空间和像素长宽比；缩放与裁切不得切掉头顶、手、关键道具、画内文字或字幕安全区。
|
|
41
|
+
- 只做必要的曝光、白平衡、饱和度和镜间色彩匹配，保持视觉圣经的叙事色彩变化；不使用统一滤镜抹平有意的冷暖转折。
|
|
42
|
+
- 检查轴线、视线、运动方向、人物左右位置、服装、道具状态和场景时间连续性。必要时可用经过审核的轻微变速、定格或裁切修复节奏，但不得伪造关键动作或掩盖 P0/P1 生成错误。
|
|
43
|
+
|
|
44
|
+
## 7. 渲染与验收
|
|
45
|
+
|
|
46
|
+
- 先输出低码率审片版，逐镜检查字幕、角标、切点、转场和音频；问题清零后再渲染交付版。渲染过程必须可由 manifest 和项目文件复现。
|
|
47
|
+
- 完整观看并听完最终文件，检查叙事、画面、声音、转场、字幕和技术参数；抽帧或任务成功不能替代完整验收。
|
|
48
|
+
- 交付至少包括：批准版视频、SRT、ASS、manifest、逐镜版本清单和必要的审核记录。临时缓存与源素材分开；不得删除用户已有资产或未批准版本。
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# MiniMax H3 原生音频、转场与成片验收
|
|
2
|
+
|
|
3
|
+
凡是 MiniMax H3 视频任务或包含 H3 镜头的成片，必须完整读取并执行本文件。
|
|
4
|
+
|
|
5
|
+
## 1. 原生音频唯一来源
|
|
6
|
+
|
|
7
|
+
生成前读取实时模型能力和 `video-generate.configSchema`。目标 H3 模型的 `generateAudioOptions` 必须包含 `true`，节点 schema 必须允许 `generateAudio`；否则停止并报告模型能力缺口，不得回退外部 TTS。用一次 `canvas node update-many` 给本批全部 H3 `video-generate` 显式设置 `generateAudio: true`，随后逐节点回读；任一节点不是显式 `true` 都禁止运行，不能依赖默认值。
|
|
8
|
+
|
|
9
|
+
每个 `video-generate` 在同一提示词中完整设计四层声音：
|
|
10
|
+
|
|
11
|
+
1. **人物对白**：写明说话者、语言、逐字台词、表演情绪、声线锚点和口型要求。画面内说话者必须可见且口型同步。
|
|
12
|
+
2. **旁白/画外音**：写明说话者或叙述者、逐字内容、声线锚点及“画外音期间画面人物闭口”，避免模型把旁白错误赋给画面人物。
|
|
13
|
+
3. **环境音与动作音**：写明空间底噪、关键动作拟音、远近关系和需要静音的区域；不要只写“有环境音”。
|
|
14
|
+
4. **BGM**：写明配器、节奏、情绪曲线、起止和跨镜延续母题；对白出现时降低存在感，不盖住人声。
|
|
15
|
+
|
|
16
|
+
同一角色跨镜复用稳定的声线描述；相邻镜明确上一镜声音如何延续、衰减或被新声音接管。参考视频只提供画面，不能假设其中音轨会自动进入 H3。
|
|
17
|
+
|
|
18
|
+
## 2. 人声时长与跨镜声音计划
|
|
19
|
+
|
|
20
|
+
运行前逐镜输出声音时间表：`镜头时长 / 人物对白起止 / 旁白起止 / 无人声反应段 / 环境音 / BGM 状态 / 转场声音桥`。对白和旁白必须按目标语言自然试读或使用已有时长估算能力，全部落在合法镜头时长内，并为开场建立、表演反应和尾部遮挡保留实际余量。文本放不下时优先拆镜或删减经用户确认的非关键信息，不通过加速语速、吞掉停顿或剪断句尾硬塞。
|
|
21
|
+
|
|
22
|
+
同一场景建立一份共享音乐锚点：配器、速度、调性/音区、节奏型、情绪曲线和禁止元素。每个转场指定 `outgoing|incoming` 中哪一侧拥有重叠区的主导音乐；另一侧在提示词中要求保持稀疏、尾奏或延后进入，避免两段独立 BGM 同时争抢。相邻生成结果仍不连续时重跑音频不合格的一镜，不得铺外部音乐遮盖。
|
|
23
|
+
|
|
24
|
+
禁止为 H3 成片运行 `voice-design`、`voice-clone`、`tts`、Edge TTS 或其他外部 TTS 后覆盖人物说话或旁白，也禁止用外部 BGM/环境音替换 H3 原生设计。后期只允许对原生整轨做轻微音量、均衡、降噪、响度和首尾淡化；原生语音失败必须重写提示词并重跑受影响镜头，不能用外部配音遮盖。
|
|
25
|
+
|
|
26
|
+
## 3. 遮挡/遮罩转场设计
|
|
27
|
+
|
|
28
|
+
转场必须在生成前成对设计，而不是生成后用特效补救：
|
|
29
|
+
|
|
30
|
+
- 前镜最后约 0.3–0.8 秒安排有动机的前景物完整或近完整遮挡画面，例如人物衣摆、门框、车辆、墙柱、暗部、强光或快速贴近镜头的物体。
|
|
31
|
+
- 后镜从形状、运动方向、速度、亮度或色彩相近的遮挡状态开始，再揭示新场景；遮挡物要服务剧情和空间，不添加无关物体。
|
|
32
|
+
- 分镜和 H3 提示词都明确“结束遮挡 / 开始遮挡 / 揭示方向 / 声音桥 / 可裁切余量”。若前后遮挡无法匹配，生成前改镜头设计，不把问题留给剪辑。
|
|
33
|
+
- 硬切可用于明确节奏点；需要顺滑衔接时默认使用遮挡匹配，不依赖长叠化、花哨插件或全局统一转场。
|
|
34
|
+
|
|
35
|
+
后期只做轻微重叠拼接：默认重叠 0.2–0.5 秒，在遮挡最充分处对齐；仅做短透明度/音量交叉淡化或直接切换。不得用长叠化把两个不匹配画面糊在一起，也不得因重叠截掉台词首尾。
|
|
36
|
+
|
|
37
|
+
生成前逐对记录转场表：`前镜 / 后镜 / 前镜遮挡 / 后镜同源遮挡 / 方向 / 亮度与色彩 / 声音桥 / 预计重叠 / 主导音轨`。该表是审核记录，不是虚构的节点 config；实际写入字段仍以实时 schema 为准。
|
|
38
|
+
|
|
39
|
+
## 4. 每镜四项后验验收
|
|
40
|
+
|
|
41
|
+
每个镜头任务成功后，先下载或打开真实视频，从头到尾观看并听完，再输出以下四项结果。任务成功、元数据正确或首帧截图都不能替代验收。
|
|
42
|
+
|
|
43
|
+
### 视觉
|
|
44
|
+
|
|
45
|
+
核对人物身份、年龄、服装、脸、手、道具版本和状态、场景、动作顺序、机位、轴线、画幅、黑帧、冻结、闪烁、拉伸、裁切、模型幻觉和非预期文字。关键叙事动作必须真实可见。
|
|
46
|
+
|
|
47
|
+
### 音频
|
|
48
|
+
|
|
49
|
+
核对人物对白和旁白的逐字内容、说话者、语言、声线连续性、口型/闭口状态；检查环境音、动作音、BGM 是否存在且层级合理，有无漏字、重复、异常停顿、断裂、破音、削波、静音、杂音、陌生人声或 BGM 盖人声。任何人声缺失或来源错误为 P0/P1，必须重跑该镜，禁止外部 TTS 补洞。
|
|
50
|
+
|
|
51
|
+
### 转场
|
|
52
|
+
|
|
53
|
+
同时查看前镜尾部和本镜头部，确认遮挡真实覆盖、形状/方向/亮度/速度可匹配，并保留足够重叠余量；检查声音桥是否自然。转场条件不成立时重跑受影响的一侧，不直接进入剪辑。
|
|
54
|
+
|
|
55
|
+
### 字幕
|
|
56
|
+
|
|
57
|
+
字幕以验收通过的实际原生人声为准。先从实时节点目录寻找可用的转写/字幕能力；存在时转写 selected 视频音轨并人工复核，不存在时必须完整听写，不能假装已自动转写。将结果与语言契约和剧本逐句比较，核对逐字内容、说话者、分句、时间码、可读时长、安全区和语言。提示词文本不能直接当作已验收转写；若实际语义或语言错误，重跑视频，不用错误字幕伪装正确对白。原始视频不烧录字幕，成片层再排版。
|
|
58
|
+
|
|
59
|
+
逐镜记录 shot/node/task/asset/version、四项结论、问题级别和处理动作。P0/P1 未清零不得选入剪辑；P2 可在不改变内容的轻量后期范围内修复并复验。
|
|
60
|
+
|
|
61
|
+
## 5. 完整成片验收
|
|
62
|
+
|
|
63
|
+
只使用逐镜四项验收通过的 selected 版本。涉及 Remotion 时先加载 `remotion-best-practices`，保留每镜 H3 原生音轨，以遮挡点轻微重叠拼接；不要另铺外部旁白、对白、环境音或 BGM 覆盖原生轨。
|
|
64
|
+
|
|
65
|
+
渲染后必须从头到尾完整观看并听完，再检查：
|
|
66
|
+
|
|
67
|
+
- **叙事与画面**：镜序、总时长、节奏、人物/服化道/空间连续性，无黑帧、冻结、坏帧、意外裁切或视觉跳变。
|
|
68
|
+
- **声音**：对白、旁白、环境音和 BGM 跨镜连续，无重复、吞字、断裂、突跳、削波或被转场截断；平台无特殊要求时可把整片响度控制在约 -14 至 -16 LUFS，true peak 不高于 -1 dBTP。
|
|
69
|
+
- **转场**：逐个慢看遮挡交界帧，确认重叠发生在遮挡最充分处，无双影、闪白、方向反转或长叠化拖影。
|
|
70
|
+
- **字幕**：全片逐句核对实际人声、时间码、说话者、断句、错字、遮挡和安全区；标题、介绍和字幕风格统一。
|
|
71
|
+
- **技术**：用媒体探针核对分辨率、画幅、帧率、时长、视频/音频编码、采样率和声道；文件可从头播放到尾且交付目录只含批准版本。
|
|
72
|
+
|
|
73
|
+
任一 P0/P1 失败都回到对应镜头或剪辑点修复并重新渲染、重新完整观看。最终报告列出成片路径、技术参数、镜头版本、四类全片验收结论和仍获用户接受的 P2；未完成完整观看不得声称“成片完成”。
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# 项目与画布规则
|
|
2
|
+
|
|
3
|
+
仅在创建/恢复项目、修改 settings、目录、节点或连线时读取本文件。
|
|
4
|
+
|
|
5
|
+
## 初始化和配置
|
|
6
|
+
|
|
7
|
+
1. `preflight --json` 检查地址、CLI 版本、认证和标准能力；`restartRequired` 为真时重跑。仅缺可确定的账户 `capabilityDefaults` 时，从实时 options、目标项目有效值或模型默认值补齐并回读；模型不可用或候选缺失时停下询问。
|
|
8
|
+
2. `config get` 只管理个人默认模型、能力默认值和工作流并发。供应商、密钥和全局模型目录由管理员维护。
|
|
9
|
+
3. 新项目按“确认名称/用途 → `project create` → `project get` + 一次 `canvas inspect`”执行；既有项目先聚合读取。项目配置回读通过前不得创建创作节点。
|
|
10
|
+
4. `canvas settings get` 必须确认项目覆盖值、继承后的有效值、来源和实时候选。默认推荐 `storyboardImageType: grid`；`visualBible` 按实时 schema 构造。`outputLanguage` 必须与用户确认的交付语言一致；“自动”只适合用户明确要求跟随输入且源剧本语言单一的普通拆镜。CLI `--locale` 只影响命令界面和输出消息，不代表内容语言。
|
|
11
|
+
5. `imageResolution`、`imageQuality`、`videoResolution` 优先由项目统一设置；节点只有确需不同且实时能力允许时才覆盖。H3 模型必须与 `videoPromptType: "h3"` 同次写入。
|
|
12
|
+
6. 用一次 `canvas settings set --file` 原子写入全部确认项并携带最近的 `expectedVersion`。409 后重新读取、展示变化并确认；写后立即回读。
|
|
13
|
+
|
|
14
|
+
## 查询与批处理
|
|
15
|
+
|
|
16
|
+
- 常规查询先用一次 `canvas inspect`，通过 `--include`、`--kind`、`--status`、`--search`、`--operation`、`--resource-type`、`--producer-node` 表达；现有命令不能表达时才写临时脚本。
|
|
17
|
+
- 同阶段两个及以上图变更用一次 `canvas apply --canvas-id ... --expected-version ...`。只改 config/title/位置时，单节点用 `node update`，多节点用 `node update-many`。
|
|
18
|
+
- 同批已就绪的独立节点用一次 `node run` 提交；跨阶段生成按 [滚动异步流水线](async-pipeline.md) 由单个调度器轮询并即时触发下游，不用一次 `task wait` 阻塞整批。不要 shell 并发多个相互竞争的 CLI 调度进程。
|
|
19
|
+
- 批量命令缺失或合法批量请求因粒度失败时，只回退尚未生效的单项。不得用单项调用绕过权限、schema、业务或付费门禁。
|
|
20
|
+
|
|
21
|
+
## 资产目录
|
|
22
|
+
|
|
23
|
+
先用 `canvas episode list/create` 确认分集，再用 `canvas folder list` 取得真实目录 ID。预设的道具、人物、场景、配音、分镜目录不可重命名、移动或删除；用户子目录最多 32 层，删除后有 30 天恢复窗口。移动不得形成环，删除被引用目录前先解除引用。跨项目复制只复制资产及版本，不复制目录结构，写后用目标项目回读。
|
|
24
|
+
|
|
25
|
+
## 不可变编辑和并发
|
|
26
|
+
|
|
27
|
+
- `canvas node edit-shot` 只编辑镜头内容，不能改 `shotKey`、`shotIndex` 或来源身份。
|
|
28
|
+
- `canvas node edit-resource` 只替换完整父文档中的目标实体，不能改名称、资源键、ID 或所属关系；兄弟资源保持原选版。
|
|
29
|
+
- 两类编辑都基于当前 `selectedOutputVersionId` 追加版本并使下游 stale。409 后重读画布和选版，不覆盖历史。
|
|
30
|
+
- `canvas apply` 只处理节点、边、删除和视口，不代替 settings 或结构化 artifact 编辑。
|
|
31
|
+
|
|
32
|
+
## 安全边界
|
|
33
|
+
|
|
34
|
+
refresh token 只保存在系统钥匙串；密码和 API Key 只从交互式隐藏输入、stdin 或秘密管理器提供。不得读取、复制或删除本地认证缓存规避认证。项目供应商读取只返回遮罩状态，写入 Key 必须使用安全 stdin。删除既有项目、覆盖完整画布或改模型前先确认影响。
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# 专项流程
|
|
2
|
+
|
|
3
|
+
只读取当前任务命中的小节。
|
|
4
|
+
|
|
5
|
+
## 专业剧本和纯文本拆镜
|
|
6
|
+
|
|
7
|
+
微短剧从选题或方案开始时，先用 `short-drama` 完成方案、角色、分集、目标单集剧本和 review，再用 `humanizer` 只润色表达，最后回到 short-drama 复核。已有专业剧本直接创建 screenplay resource。
|
|
8
|
+
|
|
9
|
+
用户明确要求专业 Markdown 纯文本拆镜测试时，给 `storyboard-breakdown` 配置 `storyboardPipelineVersion: 2`、`sourceFormat: screenplay-markdown.v1`、任意规范 BCP 47 `targetLanguage`、平台和画幅，且只连接一条剧本。执行前按 [拆镜语言匹配门禁](assets-and-storyboard.md#拆镜语言匹配门禁) 验证每个本地化块；`targetLanguage` 不能被项目 `outputLanguage` 或 CLI `--locale` 替代。该模式只验收分镜文本和镜头资产，不执行声音设计、TTS、图片、音频或视频生成；失败时确认没有持久化半成品。
|
|
10
|
+
|
|
11
|
+
## 独立 TTS 音频
|
|
12
|
+
|
|
13
|
+
本节只适用于用户明确要求独立音频文件、无 H3 视频的声音资产或非 H3 工作流。H3 成片的人物对白、旁白、环境音和 BGM 必须遵守 [h3-video-delivery.md](h3-video-delivery.md)，不得用本节覆盖。
|
|
14
|
+
|
|
15
|
+
先读取实时 `audioModel` 和 `tts` / `voice-design` / `voice-clone` schema。声音设计和克隆必须先生成真实音色 ID，再连接到 TTS；不得把任务 ID、节点 ID 或预置音色名当音色 ID。CosyVoice v3.5 plus/flash 只接受同型号设计或克隆音色。运行后等待终态并试听完整音频，检查语言、文本、音色、语速、音调、时长、空音频和破音；按错误码修正，不盲目换音色重试。
|
|
16
|
+
|
|
17
|
+
## Meme
|
|
18
|
+
|
|
19
|
+
标准链路固定为 `meme-scene-analysis → meme-material-search → cat-meme-video`。即使禁用外部素材，也要运行 material search 解析内置素材和必显道具。刷新画布后复用自动创建的计划、搜索和视频节点，不手工重复创建。
|
|
20
|
+
|
|
21
|
+
`CAT_MEME_REQUIRED_PROP_MISSING` 返回素材检索补道具；`CAT_MEME_DISPLAY_CONTENT_REQUIRED` 修复场景计划；`CAT_MEME_FFMPEG_FAILED` 修复或部署渲染器后重试。不得把失败当作切换通用 `video-generate` 的授权。
|
|
22
|
+
|
|
23
|
+
## AI 剪辑
|
|
24
|
+
|
|
25
|
+
涉及时间线、裁切、字幕、转场、音频编排或渲染时，必须先加载 `remotion-best-practices`，然后完整执行 [剪辑与交付流程](editing-delivery.md)。只使用已确认的 selected 资产；原始镜头和 manifest 单独保留。H3 成片只对原生整轨做轻量处理，禁止另铺外部 TTS、旁白、对白、环境音或 BGM 覆盖。
|