@aswless_854771076/ai_short_studio_cli 0.1.136 → 0.1.137

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 CHANGED
@@ -222,3 +222,13 @@ npm run release:ci:test -- --version 0.1.1-beta.0
222
222
  `release:ci` 会依次运行测试和类型检查、发布 npm、等待 registry 可见,再从 npm 安装该精确版本并验证 CLI 与配套 Skill。无需配置自有 Runner;只有访问内网或需要固定出口 IP 时才使用自有构建集群。
223
223
 
224
224
  专业拆镜增量修订:`canvas node revise-storyboard <parentNodeId> --project <projectId> --json` 读取当前版本、来源合同、资产白名单及软提示;`--file patch.json --dry-run` 预览差异、硬错误和下游影响,移除 `--dry-run` 原子保存指定镜头。请求必须携带画布、父版本及镜头基础版本;409 不自动重试。来源、原文、镜号与顺序只读,跨镜合同需同时修改两侧。未改镜头和历史媒体保留,受影响下游标记待更新。专业模式中的节奏、突出比例及建议预算只提示,硬错误最多纠错三轮;细化失败保留合法规划与完成批次。
225
+
226
+ ### Agent 恢复 / Agent recovery
227
+
228
+ `canvas node diagnose <nodeId> --project <projectId> --json` 读取节点输入、当前版本、任务状态及修复入口,不运行模型。`canvas node storyboard-draft <nodeId>` 可读取未批准拆镜草稿;用 `--file` 提交 edit/promote,`--dry-run` 预览。内容错误可保存在草稿,正式批准仍需完整校验;保存不切选版、不生成媒体。完整操作见随包 Skill 的 `references/agent-recovery.md`。
229
+
230
+ Use `canvas node diagnose` to inspect inputs, selected versions, task status and recovery actions without running a model. `canvas node storyboard-draft` reads an unapproved planning draft; `--file` submits explicit edit/promote requests and `--dry-run` previews them. Content errors do not prevent draft saves. Promotion validates the complete plan; draft saves neither change the formal selection nor generate media. See the bundled Skill's `references/agent-recovery.md`. Image quality is inspected by a person or Agent; the platform checks review records and provenance, rather than detecting visual defects automatically.
231
+
232
+ Agent 可直接通过 `canvas node add screenplay-resource --config screenplay-node.json` 写入剧本,并用 `canvas node storyboard-draft --file create.json`(`action: "create"`)手写镜头草稿;读取来源合同后预览、保存、修复,显式批准为正式镜头,无需先调用模型。
233
+
234
+ Agents can author screenplay resources and initial storyboard drafts without a model call. Use `storyboard-draft` with `action: "create"`, inspect server diagnostics, revise and explicitly promote to materialize shot nodes. See the bundled Agent recovery guide for the complete workflow.
@@ -0,0 +1,16 @@
1
+ import { BaseCommand } from '../../../base-command.js';
2
+ export default class CanvasNodeDiagnose 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
+ 'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
10
+ json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
11
+ locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
12
+ profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
13
+ episode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
14
+ };
15
+ run(): Promise<void>;
16
+ }
@@ -0,0 +1,13 @@
1
+ import { Args } from '@oclif/core';
2
+ import { BaseCommand } from '../../../base-command.js';
3
+ import { commandApi, projectFlag } from '../../../command-helpers.js';
4
+ export default class CanvasNodeDiagnose extends BaseCommand {
5
+ static description = '只读检查节点、输入、选版和失败状态,返回可执行的自修复入口';
6
+ static args = { nodeId: Args.string({ required: true }) };
7
+ static flags = { ...BaseCommand.baseFlags, project: projectFlag };
8
+ async run() {
9
+ const { args, flags } = await this.parse(CanvasNodeDiagnose);
10
+ const { api } = await commandApi(flags);
11
+ this.print(await api.diagnoseNode(flags.project, args.nodeId));
12
+ }
13
+ }
@@ -0,0 +1,18 @@
1
+ import { BaseCommand } from '../../../base-command.js';
2
+ export default class CanvasNodeStoryboardDraft 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
+ file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
10
+ 'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
11
+ 'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
12
+ json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
13
+ locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
14
+ profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
15
+ episode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
16
+ };
17
+ run(): Promise<void>;
18
+ }
@@ -0,0 +1,20 @@
1
+ import { Args, Flags } from '@oclif/core';
2
+ import { BaseCommand } from '../../../base-command.js';
3
+ import { commandApi, projectFlag, readJsonInput } from '../../../command-helpers.js';
4
+ export default class CanvasNodeStoryboardDraft extends BaseCommand {
5
+ static description = '创建、读取、预览和修订未批准分镜草稿,或显式批准;不调用模型';
6
+ static args = { nodeId: Args.string({ required: true }) };
7
+ static flags = { ...BaseCommand.baseFlags, project: projectFlag,
8
+ file: Flags.string({ description: '草稿请求 JSON(action 为 create、edit 或 promote);省略时读取草稿与诊断' }),
9
+ 'dry-run': Flags.boolean({ description: '仅预览差异、硬错误和剩余提示,不写入' }) };
10
+ async run() {
11
+ const { args, flags } = await this.parse(CanvasNodeStoryboardDraft);
12
+ const { api } = await commandApi(flags);
13
+ if (!flags.file) {
14
+ this.print(await api.storyboardDraft(flags.project, args.nodeId));
15
+ return;
16
+ }
17
+ const input = await readJsonInput(flags.file);
18
+ this.print(await api.storyboardDraft(flags.project, args.nodeId, { ...input, ...(flags['dry-run'] ? { dryRun: true } : {}) }));
19
+ }
20
+ }
@@ -113,6 +113,8 @@ export declare class VvicatApi {
113
113
  }): Promise<JsonObject>;
114
114
  patchCanvas(projectId: string, input: JsonObject): Promise<JsonObject>;
115
115
  updateStoryboardShot(projectId: string, nodeId: string, input: JsonObject): Promise<JsonObject>;
116
+ diagnoseNode(projectId: string, nodeId: string): Promise<JsonObject>;
117
+ storyboardDraft(projectId: string, nodeId: string, input?: JsonObject): Promise<JsonObject>;
116
118
  storyboardRevision(projectId: string, nodeId: string, input?: JsonObject): Promise<JsonObject>;
117
119
  updateStructuredResource(projectId: string, nodeId: string, input: JsonObject): Promise<JsonObject>;
118
120
  nodeTypes(): Promise<{
@@ -85,14 +85,6 @@ export class VvicatApi {
85
85
  }
86
86
  async createProject(input) {
87
87
  const outputLanguage = normalizeRequiredOutputLanguage(input.outputLanguage);
88
- const config = await this.config();
89
- const defaultModels = config.defaultModels;
90
- const analysisModel = defaultModels && typeof defaultModels === 'object' && !Array.isArray(defaultModels)
91
- ? defaultModels.analysisModel
92
- : null;
93
- if (typeof analysisModel !== 'string' || !analysisModel.trim()) {
94
- throw new Error('创建项目前请先配置默认分析模型');
95
- }
96
88
  return this.client.request('/api/projects', {
97
89
  method: 'POST',
98
90
  body: { ...input, outputLanguage, type: 'INFINITE_CANVAS' },
@@ -208,6 +200,12 @@ export class VvicatApi {
208
200
  method: 'PATCH', body: input,
209
201
  });
210
202
  }
203
+ diagnoseNode(projectId, nodeId) {
204
+ return this.client.request(`/api/projects/${projectId}/canvas/nodes/${nodeId}/diagnose`);
205
+ }
206
+ storyboardDraft(projectId, nodeId, input) {
207
+ return this.client.request(`/api/projects/${projectId}/canvas/nodes/${nodeId}/storyboard-draft`, input ? { method: 'PATCH', body: input } : {});
208
+ }
211
209
  storyboardRevision(projectId, nodeId, input) {
212
210
  return this.client.request(`/api/projects/${projectId}/canvas/nodes/${nodeId}/storyboard-revision`, input ? { method: 'PATCH', body: input } : {});
213
211
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aswless_854771076/ai_short_studio_cli",
3
- "version": "0.1.136",
3
+ "version": "0.1.137",
4
4
  "description": "VVICAT 无限画布项目命令行工具",
5
5
  "license": "MIT",
6
6
  "private": false,
@@ -5,6 +5,8 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
5
5
 
6
6
  # 使用 VVICAT AI Short Studio CLI
7
7
 
8
+ 所有画布制作都先遵循 [Agent 恢复链路](references/agent-recovery.md)。节点失败或审核待办不是结束整个任务的条件:读取具体诊断,修正输入或产物,保存并复查,仅继续受影响步骤。平台不自动看图审核质量;Agent 须观察真实媒体并如实提交记录。不要把缺少审核记录当成检测出图片缺陷。已授权范围内自主修复,不因同一操作重复索取确认;单镜问题不阻塞无依赖的其他镜头。
9
+
8
10
  ## 按需读取
9
11
 
10
12
  `SKILL.md` 只保留路由和主流程。按实际进度逐阶段读取命中的资料;长任务可以先后读取多份,但不要在开始时一次加载全部:
@@ -42,21 +44,20 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
42
44
  `drama-source-analysis → drama-brief → drama-bible → drama-outline → drama-episode → drama-script-review → drama-director-book → drama-asset-analysis → storyboard-breakdown → drama-production-plan → drama-continuity-plan → drama-audio-plan → drama-shot-review → drama-edit-plan → drama-delivery-review`
43
45
 
44
46
  人物、场景、道具生成节点接在 `drama-asset-analysis` 后;视频提示词、分镜图和视频节点必须消费连续性计划及逐镜审计结果。仅有参考资料而没有对应画布节点或阶段证据时,不得声称该阶段已完成。
45
-
46
47
  ## 核心原则
47
48
 
48
49
  生产环境认证优先使用 MemHub;CLI 通过浏览器 PKCE 登录或个人 API Key 访问,只有本地明确关闭 MemHub 时才使用 Supabase 兼容登录。
49
50
 
50
51
  把 `ai-short-studio` 当作机器可读的远程控制接口。目标、素材含义、平台、语言、画幅、时长、风格、人物、场景、道具、模型、实时 schema、候选版本、付费范围或覆盖影响存在未知、缺失或矛盾时,合并询问最少必要问题;得到答复前只做只读检查。不得用示例值替用户作创作决定。短剧结构化节点的 `canvas node types` 结果包含 `structuredOutputSchema`;创建或运行前必须按该字段组织输出,不能从 `TEXT`/`SCRIPT` 字符串端口猜 JSON。节点 `prompt` 只能补充创作意图,服务端会把语言与最终结构合同追加在它之后,冲突时以后置合同为准。
51
52
 
52
- 优先使用一次 `canvas inspect` 聚合查询。同阶段可合并的 settings、节点和连线分别使用 `canvas settings set --file`、`canvas apply`、`canvas node update-many`。生成链使用单个调度循环滚动提交,不用 `--wait` 把整批阶段串行化:节点一完成就刷新画布并立即提交它已就绪的下游节点。默认每类并发 4、总并发上限 16;同一节点同一输入指纹只允许一个在途任务,不并发启动多个相互竞争的调度器。409 重读并确认,401/403、schema、业务门禁和付费错误必须停下修正。
53
+ 优先使用一次 `canvas inspect` 聚合查询。同阶段可合并的 settings、节点和连线分别使用 `canvas settings set --file`、`canvas apply`、`canvas node update-many`。生成链使用单个调度循环滚动提交,不用 `--wait` 把整批阶段串行化:节点一完成就刷新画布并立即提交它已就绪的下游节点。默认每类并发 4、总并发上限 16;同一节点同一输入指纹只允许一个在途任务,不并发启动多个相互竞争的调度器。409 重读并审阅差异;schema 和业务检查错误进入恢复链路,能修正的自主修正后继续。401/403、供应商余额等无法自主修正的问题报告准确原因,继续不依赖该节点的工作。
53
54
 
54
55
  ## 主流程
55
56
 
56
57
  1. **预检**:运行 `preflight --json`;更新后重跑。再读取 `config get`、实时 `canvas node types` 和目标项目。`skill status --target codex` 非 current 时先询问再更新,禁止强制覆盖用户修改。
57
58
  2. **项目语言门禁**:新建项目前必须从用户确认交付语言,并用 `project create --language <BCP47>` 写入;界面 `--locale` 不能代替内容语言。创建后回读 `project get` 与 `canvas settings get`,确认两者语言一致且不可修改。项目语言约束剧本、分镜、台词、配音、画面文字和字幕;验收须区分剧情内容与制作信息:项目语言允许正常外语穿插和规范英文摄影术语,不按字符种类判死;道具文字和剧情内界面遵循来源原文。存在实际语言合同冲突时停止并说明。
58
59
  3. **项目配置门禁**:读取 `canvas settings get`,展示 `currentValue`、`effectiveValue`、`source`、建议值和实时 options。确认 `aspectRatio`、`artStyle`、`visualBible`、`storyboardImageType`、`outputLanguage`、`analysisModel`、`imageModel`、`imageResolution`、`imageQuality` 和 `videoResolution`,以及 `editModel`、`videoModel`、`videoPromptType`、`audioModel`、`musicModel`;`$ART_STYLE_ID` 必须解析实时 `option.value`。标准创作门禁使用 `--file settings.json` 原子写入并携带 `expectedVersion`,回读一致前不得创建或运行付费节点。节点确需不同参数时才按实时能力覆盖。
59
- 4. **剧本和目标集**:已有专业剧本时直接复用,不得重复执行 `novel-to-script`。需要创作微短剧时,按需读取 `references/short-drama/`,再读取 `references/humanizer/` 去除 AI 味;不得改动已经确认的剧情事实,润色后回到短剧 reference 复核。确认目标集数后,只生产该集实际需要的资产。
60
+ 4. **剧本和目标集**:Agent 可直接创建 `screenplay-resource`(`config.text`),并通过专业父节点的 `storyboard-draft action:create` 编写镜头草稿,再预览—保存—复查—批准为正式镜头;完整步骤见 [直接创建剧本与镜头](references/agent-recovery.md#agent-直接创建剧本与镜头不调用模型)。无需先调用生成模型,不要创建没有版本的镜头空壳。已有专业剧本时直接复用,不得重复执行 `novel-to-script`。需要创作微短剧时,按需读取 `references/short-drama/`,再读取 `references/humanizer/` 去除 AI 味;不得改动已经确认的剧情事实,润色后回到短剧 reference 复核。确认目标集数后,只生产该集实际需要的资产。
60
61
  5. **资产门禁**:先完成人物、场景、道具及其派生版本,展示真实预览并确认 selected version。执行资产—剧情匹配审计;缺失、多余、错版、stale、错边未清零时拆镜前门禁失败。
61
62
  6. **拆镜和滚动生成**:先执行 [拆镜模式与交付范围](references/assets-and-storyboard.md#拆镜模式与交付范围) 和 [语言匹配门禁](references/assets-and-storyboard.md#拆镜语言匹配门禁)。短剧新建默认专业拆镜,显式设置 `sourceFormat` 与 `storyboardPipelineVersion: 2`,默认只复用每镜时间宫格和镜头故事版,不自动新增首帧节点;已有首帧可保留,额外单图参考仅在用户需要时添加;不得因片长短、失败、仅生成分镜图或 `count: 1` 改走普通模式或覆盖 `imageLayout: single`。逐镜核对来源、时长、语言、布局与真实双板,P0/P1 未清零不得继续。用户的停止阶段优先于 [滚动异步调度](references/async-pipeline.md):仅分镜图任务在双板验收后停止,不运行视频提示词和视频。允许视频时,已就绪镜头滚动提交,单镜失败不阻塞其他镜头。
62
63
  7. **视频规划**:视频生成前依次完成素材连线、镜头逻辑和上下镜连续性审计。读取实时 `durationOptions`;只有选项恰为 5、10、15 秒时才按这三档向上取整。RunningHub MiniMax H3 支持纯文本和 0–9 张参考图、0–2 个参考视频、0–2 个参考音频,5–15 秒逐秒可选,1–4 秒归一为 5 秒;参考视频只传画面。画幅为 16:9 / 9:16,分辨率为 480p / 720p / 1K / 2K。
@@ -73,6 +74,6 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
73
74
 
74
75
  ## 安全与完成条件
75
76
 
76
- 不把密码、Token 或 API Key 写入参数、日志、Skill 或仓库。删除项目、覆盖画布、切换模型、重新付费生成或覆盖用户选版前,必须明确目标和影响并取得授权。临时项目在所有结束路径清理;既有项目不得擅自删除。
77
+ 不把密码、Token 或 API Key 写入参数、日志、Skill 或仓库。删除项目、覆盖画布、切换模型、重新付费生成或覆盖用户选版须在用户已授权的目标和范围内;只有超出既有授权才补充确认。临时项目在所有结束路径清理;既有项目不得擅自删除。
77
78
 
78
79
  任务成功只代表服务端完成,不代表创作合格。每批产物都要回读任务、画布、连线、资产和最终配置并查看真实预览;只有阶段门禁、逐镜四项验收和最终成片验收全部通过,才可交付。
@@ -0,0 +1,93 @@
1
+ # Agent 制作恢复:所有画布节点必读
2
+
3
+ 遇到制作失败、审核待办、stale 或版本冲突时,继续定位和修正;不要仅转述错误后结束任务。既有用户授权持续有效,同一授权范围内的修复无需重复征求同意;超出模型调用、媒体数量或项目修改范围时才需要补充授权。只读诊断、草稿预览和草稿保存不调用模型。
4
+
5
+ ## 平台审核和 Agent 的分工
6
+
7
+ 平台不自动看图判断换手、缺道具、白胡须、构图或角色是否正确。人或 Agent 必须查看实际当前选版,提交每项 `criteria` 的状态和具体观察;服务端检查记录结构、来源版本、媒体摘要和技术指标,并据真实记录计算批准,调用方不能填写 `approved`。没有审核记录与实际质量不合格是两种不同状态,不能混为“平台检测到图片错误”。
8
+
9
+ 双板流程:先读取 `canvas asset review-context`,实际查看时间板和镜头板各自图片,按返回的 `requiredDimensions` 提交 `canvas asset review`。视频须完整看画面并听音轨,检查真实起中末及实际时长,提交相应播放证据。不能把技术探测、抽帧、ASR 或提示词当作完整观看;没有观察能力时明确指出缺口,不填虚假通过。不把失败改写为通过来绕过审核。
10
+
11
+ ## 所有节点的共同恢复入口
12
+
13
+ ```bash
14
+ ai-short-studio canvas node diagnose "$NODE_ID" --project "$PROJECT_ID" --json
15
+ ```
16
+
17
+ 返回节点配置、实时输入端口、上游当前版本及正文、最近任务状态和 `recoveryActions`。它是只读检查,不是执行成功或创作质量证明。按实时节点 schema 修正配置,按精确 edge ID 修正接线;字段修改使用 `canvas node update --set` 或 `--config`,批量修改使用 `update-many` 的 `set/unset`,不要传被忽略的 `config` 包装。
18
+
19
+ | 问题所在位置 | 恢复方法 |
20
+ | --- | --- |
21
+ | 原始剧本、人物、场景、道具输入 | 原始资源修改 `config.text`;生成的结构化资源用 `edit-resource` 追加修订版本;身份不确定时请求用户澄清,不替换成相似角色 |
22
+ | 首次专业规划失败且有完整草稿 | 使用下述草稿接口继续修改,不重新运行整集,也不改走普通拆镜 |
23
+ | 已批准的专业分镜 | 父节点 `revise-storyboard` 读取—预览—保存—复查;跨镜合同同批修改 |
24
+ | 提示词、摄影、表演或其他文本节点 | 读取当前产物及其上游;修正支持的输入、附加指令或来源版本,仅重跑受影响节点 |
25
+ | 图片质量缺陷 | 先检查输入冲突、参考图、导演合同和具体格号;改输入或改选真实合格候选,必要时在授权范围内重生受影响图片并复审 |
26
+ | 视频质量、音轨或剪辑缺陷 | 定位镜头/时间点,修正声音计划、参考来源、提示词或剪辑区间;只重跑受影响节点,重新实际播放 |
27
+ | 没有有效审核记录 | 查看实际媒体并如实提交,不能把“缺审核”解释为图片已经检测不合格 |
28
+ | 来源已换版或产物 stale | 回读当前来源,核对变更,重编译受影响下游并重新审核,不复用旧版本的批准 |
29
+ | 409 / 节点运行中 | 等待已有任务或重新读取基线和差异;不自动覆盖用户修改,不启动竞争任务 |
30
+ | 权限、供应商能力或余额问题 | 保留准确诊断并说明需要用户或管理员处理;其他独立就绪节点可继续 |
31
+
32
+ ## Agent 直接创建剧本与镜头(不调用模型)
33
+
34
+ 空画布项目不要求预先配置分析模型;模型缺失在真正运行生成节点时修正,不阻止手工创建、草稿修订和预览。已有或 Agent 写好的剧本,不必运行生成节点。先按实时 `canvas node types` 的 `screenplay.v1` 结构准备正文,写入配置文件:
35
+
36
+ ```json
37
+ {"text":"{\"scenes\":[{\"scene_number\":1,\"heading\":\"室内 日\",\"characters\":[],\"content\":[{\"type\":\"action\",\"text\":\"门缓缓打开。\"}]}]}"}
38
+ ```
39
+
40
+ ```bash
41
+ ai-short-studio canvas node add screenplay-resource --project "$PROJECT_ID" --config screenplay-node.json --json
42
+ ai-short-studio canvas node add storyboard-breakdown --project "$PROJECT_ID" --source-format screenplay-json.v1 --json
43
+ ai-short-studio canvas edge add --project "$PROJECT_ID" --from "$SCRIPT_ID:script" --to "$BREAKDOWN_NODE_ID:script" --json
44
+ ```
45
+
46
+ 按需要把真实人物、场景、道具资源连到对应输入,随后读取 `storyboard-draft`,取得服务端解析的来源合同、资产白名单和当前画布版本。没有草稿时返回 `available:false`,并不要求先执行模型任务。
47
+
48
+ 创建请求(`shots` 内每个 `panel` 按实时专业分镜 schema 填写,来源 ID 使用刚读取的合同;空数组也可先保存再逐步补齐):
49
+
50
+ ```json
51
+ {
52
+ "action":"create",
53
+ "expectedCanvasVersion":12,
54
+ "basedOnDraftVersionId":null,
55
+ "requestId":"unique-create-request",
56
+ "shots":[]
57
+ }
58
+ ```
59
+
60
+ 用下节同一命令分别 `--dry-run` 和正式提交。提交后回读,使用 `edit` 和 `replace-range` 创建/拆分/合并镜头草稿,再显式 `promote` 生成正式镜头节点及双板制作节点。批准不生成图片或视频。不要只添加空 `storyboard-shot` 外壳或伪造 `artifact`,那没有可供下游读取的镜头版本。初始镜头不需要平台先调用模型生成。
61
+
62
+ 若已有草稿,要整体重新规划必须显式带当前 `basedOnDraftVersionId`;不能以 `null` 覆盖。来源变更后可基于当前连线重新 `create`,旧版本仍保留;不从客户端提交或覆盖来源合同和资产白名单。正式镜头的后续字段修改用受控 `revise-storyboard`,不要用创建动作绕过父子同步。
63
+
64
+ ## 未批准专业草稿:读取—预览—保存—复查—批准
65
+
66
+ ```bash
67
+ ai-short-studio canvas node storyboard-draft "$BREAKDOWN_NODE_ID" --project "$PROJECT_ID" --json
68
+ ai-short-studio canvas node storyboard-draft "$BREAKDOWN_NODE_ID" --project "$PROJECT_ID" --file draft-edit.json --dry-run --json
69
+ ai-short-studio canvas node storyboard-draft "$BREAKDOWN_NODE_ID" --project "$PROJECT_ID" --file draft-edit.json --json
70
+ ai-short-studio canvas node storyboard-draft "$BREAKDOWN_NODE_ID" --project "$PROJECT_ID" --json
71
+ ```
72
+
73
+ 编辑请求示例(版本与 ID 必须来自刚读取的结果):
74
+
75
+ ```json
76
+ {
77
+ "expectedCanvasVersion": 12,
78
+ "basedOnDraftVersionId": "current-draft-version",
79
+ "requestId": "unique-edit-request",
80
+ "action": "edit",
81
+ "operations": [
82
+ {"type":"patch","shotId":"stable-draft-shot-id","patch":{"duration":10,"edit_plan":{"intended_duration":9}}}
83
+ ]
84
+ }
85
+ ```
86
+
87
+ `replace-range` 使用当前连续区间的 `shotIds` 和替换 `shots:[{id,panel}]`;可以增删、拆分和合并,新增镜头使用新唯一 ID,保留镜头沿用其 ID。提供完整目标镜头,镜号由服务端重算;来源单元可重新分配,来源定义和原文不可改写。相邻转场、双板、镜头组及连续性联动修正。数组整体替换,对象字段合并;未知字段报错,409 后重新读取再审阅。只读来源变化时旧草稿仅可查看,须重新规划。
88
+
89
+ `blockingIssues` 阻止批准,不阻止草稿保存。保存后检查服务端新诊断、差异和版本,不能由 Agent 自行宣布问题已解决。没出现完整解析结果时 `available:false`,可用 `create` 主动编写草稿,不得声称模型已生成。
90
+
91
+ 修复后单独提交 `action:"promote"`,`operations:[]`,并携带当前画布/草稿版本及新 `requestId`。批准失败仍保留草稿和诊断;批准成功才更新正式父子版本并派生双板节点,不调用生成模型。软建议不阻断批准;不得从资产历史直接选中未批准草稿。
92
+
93
+ 规划内置最多三轮;后续模型输出无效时上一完整草稿仍可修复,不自动追加第四轮。需要拆镜重组的时长问题,应按完整来源单元拆分,并更新素材时长与剪辑保留时长;不要删词、加速或静默夹取到15秒。草稿批准没有运行的摄影、表演、细化阶段如实标为跳过,不宣称已完成独立设计。
@@ -20,7 +20,7 @@
20
20
 
21
21
  先用 `canvas asset review-context <assetId> --project <projectId> --node <nodeId> --version <versionId> --stage board|video|delivery --json` 读取当前选版、真实 SHA-256、来源版本和必需维度。查看真实板图或完整播放并复听视频后,使用 `canvas asset review <assetId> --project <projectId> --file review.json --json` 提交;省略文件则读 stdin。
22
22
 
23
- 请求包含上下文的 `nodeId/versionId/stage/shotKey/sourceVersionIds/media` 和逐项 `criteria`(`dimension/status/observation`)。不得直接提交整个上下文或批量伪造 passed,不发送 `approved` 或自报审核人。视频批准还需要 `watchEvidence` 的人工完整播放声明及实际时长/起中末定位;技术探测、抽帧和 ASR 都不能替代观看。不会自动触发生成或修改媒体选版,新增审核文档保留历史;换版或来源变化需重审。当前记录能力不能单独证明视频生成、剪辑或交付的强制门禁已经接通。
23
+ 请求包含上下文的 `nodeId/versionId/stage/shotKey/sourceVersionIds/media` 和逐项 `criteria`(`dimension/status/observation`)。不得直接提交整个上下文或批量伪造 passed,不发送 `approved` 或自报审核人。视频批准还需要 `watchEvidence` 的人工完整播放声明及实际时长/起中末定位;技术探测、抽帧和 ASR 都不能替代观看。不会自动触发生成或修改媒体选版,新增审核文档保留历史;换版或来源变化需重审。当前专业视频、剪辑和交付链路已检查对应审核记录;缺少或失效记录时按 [Agent 恢复链路](agent-recovery.md) 读取实际版本并补充真实观察,不把缺审核当作平台自动看图判失败。
24
24
 
25
25
  专业双板到视频:在视频提示词节点连接本镜 `shot`、主 `storyboard`、两板 `temporalBoard/shotBoard` 和当前 `shotReview/continuityPlan`。预检的正式批准字段分别为 `summary.approved`、`approved`,必须覆盖原始 `shot_key`,没有未决问题或连续性冲突。视频节点使用 `references` 连接两张独立板和可选单帧参考,并连接同版本的提示词与两份预检;不要混连 start-frame/end-frame。模型参考图数量上限必须已知且足够,超限不能删参考硬跑。服务端提交与 Worker 调用前均复核当前板版本、真实摘要和各自审核,任务保存实际参考顺序。专业提示词/视频回写前再核对文件摘要,并在结果事务锁内复核选版和审核;已失效结果只追加历史版本,不自动选中或覆盖新任务。任务结果 `historical: true` 和版本 `generationParams.productionResultState: stale` 表示仅归档,需回读原资产版本列表及节点状态。额外图片参考须绑定同画布来源节点、选版和实际摘要;专业关键帧须匹配本镜及父拆镜。首尾帧提取记录源视频选版、位置和实际字节摘要,源视频改变会阻止继续使用;没有来源记录的旧提帧须重新提取。两板和关键帧生图绑定镜头、父拆镜及实际图片参考快照,生图前、返回后及锁内回写复核;来源变化仅归档历史结果。审核继续复核这些来源,没有来源快照的旧板图须重新生成后取得新批准。剪辑交付仍待闭合,不宣称完整生产链路已通过。
26
26
 
@@ -91,7 +91,7 @@ P0/P1 必须清零;只修复受影响镜头或边,禁止全量重建掩盖
91
91
 
92
92
  ## 分镜图后验
93
93
 
94
- 每批完成后回读任务、节点、连线、资产、最终配置和 selected version,并实际查看所有图片。检查身份、肢体、道具、构图、画幅、裁切、文字、连续性和空结果。缺陷需再次付费生成或改选版本时,先展示问题并取得确认。
94
+ 每批完成后回读任务、节点、连线、资产、最终配置和 selected version,并实际查看所有图片。检查身份、肢体、道具、构图、画幅、裁切、文字、连续性和空结果。缺陷需再次付费生成或改选版本时,遵循已有授权;超出用户已确认的生成数量或修改范围才补充确认。
95
95
 
96
96
  专业双板的 `storyboard_strategy.frame_plan` 必须登记 `beats:[{id,sourceUnitIds,description}]`,来源并集恰好等于本镜 `sourceUnitIds`;`temporal_cells` 与 `shot_cells` 各为 `frame_count` 个 `{beat_id,visible_change}`,各自覆盖全部节拍且不重复填格。时间格按节拍顺序,空间格表达几何证据,不能复制同一计划。`overflow_strategy` 固定 `return-to-breakdown`;容量不足退回拆镜,不截断、不借邻镜来源。旧策略可读,重新生成/审核前须补计划;`STORYBOARD_BOARD_FRAME_PLAN_*` 指出计划缺陷。专业镜头按下文“读取—预览—保存—复查”通过 `canvas node revise-storyboard` 保存策略补丁,改格数时同步两类计划及两板节点配置。结构校验不证明语义或像素符合预期。
97
97
 
@@ -150,8 +150,8 @@ P0/P1 必须清零;只修复受影响镜头或边,禁止全量重建掩盖
150
150
  专业拆镜若仅剩双板策略硬错误,服务端在原有三轮上限内只纠正报错镜头的策略;不改其他镜头、来源或对白。失败诊断按格号和节拍定位时间逆序、双板重复等具体问题;不能靠自动排序、补格或放宽硬校验交付,也不自动反复提交原任务。
151
151
 
152
152
 
153
- 终场纯“黑场/切黑/CUT TO BLACK/FADE OUT”按剪辑结束状态处理,保留来源ID并与同场景前一叙事来源同镜,不单独制作两张全黑宫格。黑场单独对应一个节拍,只占一个最终时间格和一个空间格,其余格继续按真实剧情与空间证据填写;不得删黑场来源、虚构黑场动作或改写对白。服务端返回 STORYBOARD_EDITORIAL_CUE_INVALID 时需要重新规划来源归属,不能用Agent单镜修订入口修改只读来源绕过。
153
+ 终场纯“黑场/切黑/CUT TO BLACK/FADE OUT”按剪辑结束状态处理,保留来源ID并与同场景前一叙事来源同镜,不单独制作两张全黑宫格。黑场单独对应一个节拍,只占一个最终时间格和一个空间格,其余格继续按真实剧情与空间证据填写;不得删黑场来源、虚构黑场动作或改写对白。服务端返回 STORYBOARD_EDITORIAL_CUE_INVALID 时需要重新规划来源归属,已批准单镜入口不能改来源;未批准草稿可用 storyboard-draft 调整来源归属和镜头拓扑,保留完整原文并复查。
154
154
 
155
155
  规划内置纠错最多三轮:仅双板问题修策略;来源集合合法且目标镜数可保留时,结构或终场分配问题仅替换报错镜头(必要时含前一镜),不改目标外镜头,目标来源集合保持不变并重跑整集校验。原始规划没有合法来源覆盖,或终场合并后无法保留目标镜数时,回到完整规划;不得为了维持镜数补空镜。不要为了“必须25镜”等数量要求补无来源空镜;模型新增的assetNodeRefs_note等未知字段继续拒绝,不静默忽略。每轮诊断记录full/board/panel模式与目标镜号;验收报告要区分通过硬校验、细化完成和实际媒体合格,不自动追加第四轮或重生。
156
156
 
157
- 资产校验失败须读取 `problems` 中镜号、字段、实际值和允许名称/节点 ID,不按 `STORYBOARD_ASSET_INVALID` 汇总代码猜测缺图或替换身份。`shot_group.role` 只允许 setup/action/reaction/bridge/payoff;build/turn/climax/release 属于 `rhythm_plan.beat_role`,不能混用。语音校验同时约束素材时长与剪辑保留时长;需要超过 15 秒时,应在规划阶段重分配完整来源单元并更新双板/相邻合同,不能只拉到 15 秒、快进或删词。单个不可分来源本身超过上限时,报告来源约束;Agent 增量入口仍不得改来源或镜头拓扑。
157
+ 资产校验失败须读取 `problems` 中镜号、字段、实际值和允许名称/节点 ID,不按 `STORYBOARD_ASSET_INVALID` 汇总代码猜测缺图或替换身份。`shot_group.role` 只允许 setup/action/reaction/bridge/payoff;build/turn/climax/release 属于 `rhythm_plan.beat_role`,不能混用。语音校验同时约束素材时长与剪辑保留时长;需要超过 15 秒时,应在规划阶段重分配完整来源单元并更新双板/相邻合同,不能只拉到 15 秒、快进或删词。单个不可分来源本身超过上限时,报告来源约束;正式分镜增量入口不得改来源或镜头拓扑;未批准草稿可用 storyboard-draft 在只读来源合同内重分配来源并增删拆并镜头。
@@ -70,3 +70,11 @@ ai-short-studio canvas continuity analyze --project <projectId> --apply-ready --
70
70
  ```
71
71
 
72
72
  handle 来自实时节点目录。只删除精确 edge ID;`--apply-ready` 只在用户确认连续性建议后执行。
73
+
74
+ ## 节点诊断和未批准草稿
75
+
76
+ `canvas node diagnose <nodeId> --project <projectId> --json` 只读返回当前输入、版本、最近任务与恢复动作。所有节点失败先走此入口。
77
+
78
+ `canvas node storyboard-draft <nodeId> --project <projectId> [--file request.json] [--dry-run] --json`:无文件读取草稿;文件支持 edit 与 promote。先 dry-run,再保存、复读,合法后单独批准;完整请求见 [Agent 恢复链路](../agent-recovery.md)。这些命令不调用模型。
79
+
80
+ 剧本与镜头可由 Agent 直接编写,无需先运行模型:见 [直接创建流程](../agent-recovery.md#agent-直接创建剧本与镜头不调用模型)。`storyboard-draft --file` 支持 `create/edit/promote`;`create` 必须提交 `shots`、画布版本、基础草稿版本(首次为 null)及唯一 requestId。
@@ -6,7 +6,7 @@
6
6
 
7
7
  微短剧从选题或方案开始时,先用 `short-drama` 完成方案、角色、分集、目标单集剧本和 review,再用 `humanizer` 只润色表达,最后回到 short-drama 复核。已有专业剧本直接创建 screenplay resource。
8
8
 
9
- 专业纯文本拆镜给 `storyboard-breakdown` 显式配置 `storyboardPipelineVersion: 2`、来源格式、非空平台和合法画幅,且只连接一条剧本。Markdown 使用 `sourceFormat: screenplay-markdown.v1`;结构化单集剧本使用 `screenplay-json.v1`,其 `scenes[].content[]` 支持 action/text、dialogue/character/lines 和 voiceover/text,parenthetical 保留为表演提示。JSON 每句台词生成独立来源单元,未知内容类型或空台词须修正源剧本。内容语言取项目 `outputLanguage`,画幅优先取画布设置;节点旧 `targetLanguage` 不覆盖项目语言。执行前按 [拆镜语言匹配门禁](assets-and-storyboard.md#拆镜语言匹配门禁) 核对来源;CLI `--locale` 只控制界面消息。仅执行拆镜测试时只验收分镜文本和镜头资产,不生成图片、音频或视频;失败时确认没有持久化半成品。
9
+ 专业纯文本拆镜给 `storyboard-breakdown` 显式配置 `storyboardPipelineVersion: 2`、来源格式、非空平台和合法画幅,且只连接一条剧本。Markdown 使用 `sourceFormat: screenplay-markdown.v1`;结构化单集剧本使用 `screenplay-json.v1`,其 `scenes[].content[]` 支持 action/text、dialogue/character/lines 和 voiceover/text,parenthetical 保留为表演提示。JSON 每句台词生成独立来源单元,未知内容类型或空台词须修正源剧本。内容语言取项目 `outputLanguage`,画幅优先取画布设置;节点旧 `targetLanguage` 不覆盖项目语言。执行前按 [拆镜语言匹配门禁](assets-and-storyboard.md#拆镜语言匹配门禁) 核对来源;CLI `--locale` 只控制界面消息。仅执行拆镜测试时只验收分镜文本和镜头资产,不生成图片、音频或视频;失败时检查是否保留未批准草稿;正式选版和下游不应被非法规划覆盖,完整草稿可按 agent-recovery.md 继续修复。
10
10
 
11
11
  ## 独立 TTS 音频
12
12