@aswless_854771076/ai_short_studio_cli 0.1.159 → 0.1.161

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.
Files changed (26) hide show
  1. package/README.md +12 -0
  2. package/dist/commands/canvas/asset/audit.d.ts +14 -0
  3. package/dist/commands/canvas/asset/audit.js +90 -0
  4. package/dist/commands/canvas/document/save.d.ts +1 -0
  5. package/dist/commands/canvas/document/save.js +14 -0
  6. package/dist/commands/preflight.js +28 -0
  7. package/dist/commands/skill/diff.d.ts +16 -0
  8. package/dist/commands/skill/diff.js +17 -0
  9. package/dist/domain/canvas-asset-audit.d.ts +53 -0
  10. package/dist/domain/canvas-asset-audit.js +112 -0
  11. package/dist/domain/canvas-document-contract.d.ts +49 -0
  12. package/dist/domain/canvas-document-contract.js +94 -0
  13. package/dist/skill/skill-manager.d.ts +64 -0
  14. package/dist/skill/skill-manager.js +69 -5
  15. package/package.json +1 -1
  16. package/scripts/postinstall.mjs +6 -1
  17. package/skills/using-vvicat-ai-short-studio-cli/SKILL.md +3 -3
  18. package/skills/using-vvicat-ai-short-studio-cli/references/assets-and-storyboard.md +8 -0
  19. package/skills/using-vvicat-ai-short-studio-cli/references/commands/assets-and-tasks.md +3 -0
  20. package/skills/using-vvicat-ai-short-studio-cli/references/commands/project.md +3 -1
  21. package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/SKILL.md +3 -3
  22. package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/modules/define-drama-brief/prompts/drama_brief.en.txt +3 -3
  23. package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/assets/modules/define-drama-brief/prompts/drama_brief.zh.txt +3 -3
  24. package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/module-map.json +130 -0
  25. package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/pipeline.md +25 -0
  26. package/skills/using-vvicat-ai-short-studio-cli/references/short-drama/prompt/seedance-prompting.md +1 -1
package/README.md CHANGED
@@ -183,6 +183,14 @@ ai-short-studio skill update --target codex --json
183
183
 
184
184
  手动恢复或安装到其他 Agent 时,可使用 `--target agents`;自定义全部内置 Skills 的父目录使用 `--root <path>`。旧版 `--directory <path>` 保留为兼容入口,只把主 CLI Skill 精确安装到该目录。自动安装对应使用 `VVICAT_SKILLS_ROOT`;旧变量 `VVICAT_SKILL_DIRECTORY` 仍保持主 Skill 精确目录语义。CLI 会记录版本和 SHA-256;已安装 Skill 被用户修改后,更新默认停止,只有显式 `--force` 才覆盖。自动安装可通过 `VVICAT_SKIP_SKILL_INSTALL=1` 跳过。
185
185
 
186
+ 自动安装被跳过时,`skill status`、`skill update`、`skill diff` 和 postinstall 输出都会带上 `state` 与跳过原因,避免 CLI 升级后 Skill 悄悄停在旧版本:`current` 表示版本与校验和都与随包一致;`outdated` 表示托管目录的清单版本低于当前 CLI;`modified` 表示目录内容与安装时记录的校验和不一致(用户改动或混入其他文件);`unmanaged` 表示目录没有 CLI 清单;`missing` 表示未安装。
187
+
188
+ ```bash
189
+ ai-short-studio skill diff --target codex --json
190
+ ```
191
+
192
+ `skill diff` 对照随包版本列出 `changed`(内容不同)、`extra`(本地新增)和 `missing`(随包有而本地没有)的文件,供用户决定手工合并还是 `skill install --force` 覆盖。`preflight --json` 会返回 `skill` 块,其中 `skillReady` 只有在 `state === "current"` 时为真;未就绪时 `nextAction` 给出下一步命令,Agent 应在处理完 Skill 版本前停止创作。
193
+
186
194
  ## 发布
187
195
 
188
196
  使用具有发布权限并允许 bypass 2FA 的 npm Granular Access Token:
@@ -229,6 +237,10 @@ npm run release:ci:test -- --version 0.1.1-beta.0
229
237
 
230
238
  新项目先运行 `canvas documents` 和 `canvas workflow status`,由 Agent 在无限画布创建 自由画布 JSON 文档;用 `canvas document save` 追加版本,用 `canvas document status` 检查上游选版。`canvas node diagnose <nodeId>` 仅用于历史媒体节点的恢复,不是新流程入口。完整操作见随包 Skill 的 自由画布文档流程。
231
239
 
240
+ `canvas document save` 在发出任何远程请求前按随包 `module-map.json` 的 `documents` 合同核对正文:登记的文档键缺少必需顶层字段,或 `non_empty` 字段为空时直接失败,并指出应先读取的模板路径。阶段状态只看文档键、版本和来源快照,不校验正文,因此只写摘要一类的占位文档会让阶段显示 `ready` 却向下游传递空分析。只有用户明确要求保存半成品草稿时才加 `--allow-partial`,该版本会被警告为不得作为阶段依据。
241
+
242
+ `canvas asset audit --project <projectId> --json` 补齐资产生成前的机器门禁:读取已就绪的资产计划文档和画布节点、连线,按人物、场景、道具逐类核对是否使用了对应的设定板节点(`character-turnaround`、`location-image`、`prop-turnaround`),而不是透明边界的 `image-generate`;同时检查设定板的 `prompt` 端口是否来自结构化设定节点、是否接线、是否手写了 `config.prompt`。存在失败项时退出码为 7,`errors[].nodeIds` 直接指出要重建的节点;计划文档未就绪时返回 `blocked: "asset-plan-not-ready"`。同一项目有多份资产计划时用 `--document-key` 指定。该命令只做跨节点事实核对——缺少必需端口由服务端在提交时拒绝,不在本命令范围内。
243
+
232
244
  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.
233
245
 
234
246
  Agent 可直接在 `text-resource` 节点保存剧本、导演本和制作计划等自由画布文档(文档结构由平台画布统一校验);每次保存都通过 `--input` 固化上游版本,审核使用独立 `canvas.review.v1` 文档。历史 `screenplay-resource` 和 `storyboard-draft` 只用于迁移旧项目,不得用于新项目。
@@ -0,0 +1,14 @@
1
+ import { BaseCommand } from '../../../base-command.js';
2
+ export default class CanvasAssetAudit extends BaseCommand {
3
+ static description: string;
4
+ static flags: {
5
+ project: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
6
+ 'document-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
7
+ 'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
8
+ json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
9
+ locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
10
+ profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
11
+ episode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
12
+ };
13
+ run(): Promise<void>;
14
+ }
@@ -0,0 +1,90 @@
1
+ import { Flags } from '@oclif/core';
2
+ import { BaseCommand } from '../../../base-command.js';
3
+ import { commandApi, projectFlag } from '../../../command-helpers.js';
4
+ import { auditAssets } from '../../../domain/canvas-asset-audit.js';
5
+ function isAssetPlanKey(key, requested) {
6
+ if (requested)
7
+ return key === requested || key.endsWith(`.${requested}`);
8
+ return key === 'asset-plan' || key.endsWith('.asset-plan');
9
+ }
10
+ function selectedVersionText(payload) {
11
+ const asset = payload.asset && typeof payload.asset === 'object' && !Array.isArray(payload.asset)
12
+ ? payload.asset : null;
13
+ const version = asset?.selectedVersion && typeof asset.selectedVersion === 'object' && !Array.isArray(asset.selectedVersion)
14
+ ? asset.selectedVersion : null;
15
+ const text = version?.textContent;
16
+ if (typeof text !== 'string')
17
+ throw new Error('资产计划文档没有选定版本正文');
18
+ return text;
19
+ }
20
+ export default class CanvasAssetAudit extends BaseCommand {
21
+ static description = '按资产计划核对画布设定板节点,拦截用 image-generate 冒充资产设定';
22
+ static flags = {
23
+ ...BaseCommand.baseFlags,
24
+ project: projectFlag,
25
+ 'document-key': Flags.string({ description: '资产计划文档键;默认匹配以 asset-plan 结尾的文档' }),
26
+ };
27
+ async run() {
28
+ const { flags } = await this.parse(CanvasAssetAudit);
29
+ const { api } = await commandApi(flags);
30
+ const payload = await api.canvasDocuments(flags.project);
31
+ const documents = Array.isArray(payload.documents) ? payload.documents : [];
32
+ const candidates = documents.filter((item) => typeof item.documentKey === 'string'
33
+ && isAssetPlanKey(item.documentKey, flags['document-key']));
34
+ if (candidates.length === 0) {
35
+ this.print({
36
+ ok: true,
37
+ skipped: 'no-asset-plan',
38
+ message: '画布上没有资产计划文档;资产阶段开始前无需核对。',
39
+ });
40
+ return;
41
+ }
42
+ const ready = candidates.find((item) => item.status?.ready === true);
43
+ const document = ready ?? candidates[0];
44
+ if (!document || typeof document.nodeId !== 'string')
45
+ throw new Error('资产计划文档缺少节点 ID');
46
+ if (document.status?.ready !== true) {
47
+ // 用未就绪的计划做核对会给出假的通过结论,必须先修文档来源。
48
+ this.print({
49
+ ok: false,
50
+ blocked: 'asset-plan-not-ready',
51
+ nodeId: document.nodeId,
52
+ documentKey: document.documentKey,
53
+ reason: document.status?.reason ?? null,
54
+ message: '资产计划文档未就绪(缺少版本、来源快照过期或正文无效);先修复该文档再核对资产节点。',
55
+ });
56
+ this.error('资产计划文档未就绪,资产门禁未执行', { exit: 7 });
57
+ }
58
+ const node = await api.node(flags.project, document.nodeId);
59
+ if (node.kind !== 'text-resource' || typeof node.refId !== 'string')
60
+ throw new Error('资产计划节点不是已保存的画布文档');
61
+ const assetPayload = await api.asset(flags.project, node.refId);
62
+ const textContent = selectedVersionText(assetPayload);
63
+ let plan;
64
+ try {
65
+ plan = JSON.parse(textContent);
66
+ }
67
+ catch {
68
+ throw new Error('资产计划文档正文不是合法 JSON');
69
+ }
70
+ const canvas = await api.inspectCanvas(flags.project, { includes: ['nodes', 'edges'] });
71
+ const nodes = (Array.isArray(canvas.nodes) ? canvas.nodes : [])
72
+ .map((item) => ({
73
+ id: String(item.id),
74
+ kind: String(item.kind),
75
+ title: typeof item.title === 'string' ? item.title : undefined,
76
+ config: item.data?.config,
77
+ }));
78
+ const edges = (Array.isArray(canvas.edges) ? canvas.edges : [])
79
+ .map((item) => ({
80
+ sourceNodeId: String(item.sourceNodeId),
81
+ targetNodeId: String(item.targetNodeId),
82
+ targetHandle: typeof item.targetHandle === 'string' ? item.targetHandle : null,
83
+ }));
84
+ const result = auditAssets({ nodes, edges, plan });
85
+ this.print({ ...result, documentKey: document.documentKey, documentNodeId: document.nodeId });
86
+ if (!result.ok) {
87
+ this.error(`资产门禁未通过:${result.errors.map((item) => item.code).join('、')}`, { exit: 7 });
88
+ }
89
+ }
90
+ }
@@ -11,6 +11,7 @@ export default class CanvasDocumentSave extends BaseCommand {
11
11
  'schema-key': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
12
12
  'document-key': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
13
13
  input: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
14
+ 'allow-partial': import("@oclif/core/interfaces").BooleanFlag<boolean>;
14
15
  'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
15
16
  json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
16
17
  locale: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
@@ -2,6 +2,7 @@ import { Args, Flags } from '@oclif/core';
2
2
  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
+ import { validateCanvasDocumentContent } from '../../../domain/canvas-document-contract.js';
5
6
  export default class CanvasDocumentSave extends BaseCommand {
6
7
  static description = '将 JSON 保存为画布文本资源的不可变文档版本';
7
8
  static args = { nodeId: Args.string({ required: true }) };
@@ -13,6 +14,10 @@ export default class CanvasDocumentSave extends BaseCommand {
13
14
  'schema-key': Flags.string({ required: true, description: '画布文档结构版本,例如 canvas.brief.v1' }),
14
15
  'document-key': Flags.string({ required: true, description: '项目内稳定文档键,例如 brief 或 ep-001.script' }),
15
16
  input: Flags.string({ multiple: true, description: '依据的上游节点 ID,可重复指定' }),
17
+ 'allow-partial': Flags.boolean({
18
+ description: '仅保存用户明确要求的不完整草稿时使用;保存后该版本不得作为阶段依据',
19
+ default: false,
20
+ }),
16
21
  };
17
22
  async run() {
18
23
  const { args, flags } = await this.parse(CanvasDocumentSave);
@@ -22,6 +27,15 @@ export default class CanvasDocumentSave extends BaseCommand {
22
27
  this.warn(`--schema-key 的旧前缀已归一化为 ${schemaKey},请改用 canvas.* 合同键。`);
23
28
  }
24
29
  const content = await readJsonInput(flags.file);
30
+ // 阶段状态只核对文档键和来源快照,不看正文;在本地按随包模板拦下占位文档。
31
+ const validation = await validateCanvasDocumentContent({
32
+ documentKey: flags['document-key'],
33
+ schemaKey,
34
+ content,
35
+ allowPartial: flags['allow-partial'],
36
+ });
37
+ for (const warning of validation.warnings)
38
+ this.warn(warning);
25
39
  const { api } = await commandApi(flags);
26
40
  const node = await api.node(flags.project, args.nodeId);
27
41
  if (node.kind !== 'text-resource')
@@ -4,6 +4,7 @@ import { ProfileStore } from '../config/profiles.js';
4
4
  import { VvicatApi } from '../domain/vvicat-api.js';
5
5
  import { createRuntime, DEFAULT_BASE_URL } from '../runtime.js';
6
6
  import { compareStableVersions, fetchBootstrap, inspectCreationConfig, readCurrentPackageIdentity, updateCliPackage, } from '../preflight.js';
7
+ import { skillGate } from '../skill/skill-manager.js';
7
8
  export default class Preflight extends BaseCommand {
8
9
  static description = '创作前检查 CLI、服务连接、认证和模型配置';
9
10
  static flags = {
@@ -30,11 +31,21 @@ export default class Preflight extends BaseCommand {
30
31
  latestVersion: bootstrap.cli.latestVersion,
31
32
  };
32
33
  if (version.restartRequired) {
34
+ // 刚升级的 CLI 尚未由新进程执行过 postinstall,Skill 很可能仍是旧版;这里直接暴露状态。
35
+ const pendingSkill = await skillGate();
33
36
  this.print({
34
37
  connected: true,
35
38
  profile: selected?.name ?? null,
36
39
  baseUrl,
37
40
  version,
41
+ skill: {
42
+ state: pendingSkill.state,
43
+ target: pendingSkill.target,
44
+ installedVersion: pendingSkill.installedVersion,
45
+ packageVersion: pendingSkill.packageVersion,
46
+ modified: pendingSkill.modified,
47
+ skillReady: pendingSkill.skillReady,
48
+ },
38
49
  ready: false,
39
50
  nextAction: '重新运行 ai-short-studio preflight --json',
40
51
  });
@@ -43,6 +54,7 @@ export default class Preflight extends BaseCommand {
43
54
  const runtime = await createRuntime(flags);
44
55
  await runtime.client.request('/api/auth/session');
45
56
  const readiness = inspectCreationConfig(await new VvicatApi(runtime.client).config());
57
+ const skill = await skillGate();
46
58
  this.print({
47
59
  connected: true,
48
60
  profile: selected?.name ?? null,
@@ -50,6 +62,22 @@ export default class Preflight extends BaseCommand {
50
62
  authenticated: true,
51
63
  updateAvailable: hasUpdate,
52
64
  version,
65
+ // CLI 升级不会自动覆盖用户改过的 Skill;这里把"CLI 新、Skill 旧"变成显式停止条件。
66
+ skill: {
67
+ state: skill.state,
68
+ target: skill.target,
69
+ installedVersion: skill.installedVersion,
70
+ packageVersion: skill.packageVersion,
71
+ modified: skill.modified,
72
+ skillReady: skill.skillReady,
73
+ },
74
+ ...(skill.skillReady
75
+ ? {}
76
+ : {
77
+ nextAction: skill.state === 'missing'
78
+ ? '运行 ai-short-studio skill install --target <codex|agents> 后再创作'
79
+ : '先运行 ai-short-studio skill diff 核对差异,再决定保留并手工合并或 skill install --force;不得在旧 Skill 上继续创作',
80
+ }),
53
81
  ...readiness,
54
82
  });
55
83
  }
@@ -0,0 +1,16 @@
1
+ import { BaseCommand } from '../../base-command.js';
2
+ export default class SkillDiff extends BaseCommand {
3
+ static description: string;
4
+ static flags: {
5
+ target: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
6
+ directory: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
7
+ root: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
8
+ skill: 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,17 @@
1
+ import { BaseCommand } from '../../base-command.js';
2
+ import { diffSkill } from '../../skill/skill-manager.js';
3
+ import { resolveSkillsRoot, selectedSkillNames, skillFlags } from '../../skill/command-flags.js';
4
+ import { join } from 'node:path';
5
+ export default class SkillDiff extends BaseCommand {
6
+ static description = '列出已安装 Skill 相对随包版本缺失、多出和内容不同的文件';
7
+ static flags = { ...BaseCommand.baseFlags, ...skillFlags };
8
+ async run() {
9
+ const { flags } = await this.parse(SkillDiff);
10
+ const root = resolveSkillsRoot(flags);
11
+ const results = [];
12
+ for (const name of selectedSkillNames(flags.skill)) {
13
+ results.push(await diffSkill(flags.directory ?? join(root, name)));
14
+ }
15
+ this.print(results.length === 1 && flags.directory ? results[0] : { root, skills: results });
16
+ }
17
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * 资产阶段的结构性核对。
3
+ *
4
+ * 服务端在提交生成时只校验单节点的必需端口(例如 `CANVAS_REQUIRED_INPUT_MISSING:prompt`),
5
+ * 看不到"资产计划声明了 12 个人物,画布上却一个 character-turnaround 都没有"这类跨节点事实,
6
+ * 也看不出设定资产被塞进了透明的 image-generate 节点。这里把这些事实做成可复现的失败项,
7
+ * 让资产门禁能在付费提交之前失败,而不是等用户在成片里看到不像同一张脸。
8
+ */
9
+ export interface AssetAuditNode {
10
+ id: string;
11
+ kind: string;
12
+ title?: string;
13
+ config?: Record<string, unknown>;
14
+ }
15
+ export interface AssetAuditEdge {
16
+ sourceNodeId: string;
17
+ targetNodeId: string;
18
+ targetHandle?: string | null;
19
+ }
20
+ export interface AssetAuditPlan {
21
+ characters?: unknown;
22
+ scenes?: unknown;
23
+ props?: unknown;
24
+ }
25
+ export interface AssetAuditIssue {
26
+ code: string;
27
+ severity: 'error' | 'warning';
28
+ message: string;
29
+ nodeIds: string[];
30
+ }
31
+ export interface AssetAuditResult {
32
+ ok: boolean;
33
+ errors: AssetAuditIssue[];
34
+ warnings: AssetAuditIssue[];
35
+ counts: {
36
+ planned: {
37
+ characters: number;
38
+ scenes: number;
39
+ props: number;
40
+ };
41
+ sheets: {
42
+ characters: number;
43
+ scenes: number;
44
+ props: number;
45
+ };
46
+ imageGenerate: number;
47
+ };
48
+ }
49
+ export declare function auditAssets(input: {
50
+ nodes: AssetAuditNode[];
51
+ edges: AssetAuditEdge[];
52
+ plan: AssetAuditPlan;
53
+ }): AssetAuditResult;
@@ -0,0 +1,112 @@
1
+ /**
2
+ * 资产阶段的结构性核对。
3
+ *
4
+ * 服务端在提交生成时只校验单节点的必需端口(例如 `CANVAS_REQUIRED_INPUT_MISSING:prompt`),
5
+ * 看不到"资产计划声明了 12 个人物,画布上却一个 character-turnaround 都没有"这类跨节点事实,
6
+ * 也看不出设定资产被塞进了透明的 image-generate 节点。这里把这些事实做成可复现的失败项,
7
+ * 让资产门禁能在付费提交之前失败,而不是等用户在成片里看到不像同一张脸。
8
+ */
9
+ // 资产种类到设定板节点、允许的结构化设定来源的固定对应;改这里等于改资产门禁。
10
+ const ASSET_CATEGORIES = [
11
+ {
12
+ category: 'characters',
13
+ label: '人物',
14
+ sheetKind: 'character-turnaround',
15
+ sourceKinds: ['character-visual-design', 'character-resource', 'character-design'],
16
+ },
17
+ {
18
+ category: 'scenes',
19
+ label: '场景',
20
+ sheetKind: 'location-image',
21
+ sourceKinds: ['location-resource', 'location-design'],
22
+ },
23
+ {
24
+ category: 'props',
25
+ label: '道具',
26
+ sheetKind: 'prop-turnaround',
27
+ sourceKinds: ['prop-resource', 'prop-design'],
28
+ },
29
+ ];
30
+ const TRANSPARENT_IMAGE_KIND = 'image-generate';
31
+ function planCount(plan, category) {
32
+ const value = plan[category];
33
+ return Array.isArray(value) ? value.length : 0;
34
+ }
35
+ function hasPromptInput(nodeId, edges) {
36
+ // 旧画布可能没有 targetHandle,此时任何入边都按已接线处理,避免误报。
37
+ return edges.some((edge) => edge.targetNodeId === nodeId
38
+ && (edge.targetHandle === 'prompt' || !edge.targetHandle));
39
+ }
40
+ function promptSourceKind(nodeId, edges, kindById) {
41
+ const edge = edges.find((item) => item.targetNodeId === nodeId
42
+ && (item.targetHandle === 'prompt' || !item.targetHandle));
43
+ return edge ? kindById.get(edge.sourceNodeId) ?? null : null;
44
+ }
45
+ export function auditAssets(input) {
46
+ const kindById = new Map(input.nodes.map((node) => [node.id, node.kind]));
47
+ const errors = [];
48
+ const warnings = [];
49
+ const imageGenerateIds = input.nodes.filter((node) => node.kind === TRANSPARENT_IMAGE_KIND).map((node) => node.id);
50
+ const counts = {
51
+ planned: { characters: 0, scenes: 0, props: 0 },
52
+ sheets: { characters: 0, scenes: 0, props: 0 },
53
+ imageGenerate: imageGenerateIds.length,
54
+ };
55
+ for (const { category, label, sheetKind, sourceKinds } of ASSET_CATEGORIES) {
56
+ const planned = planCount(input.plan, category);
57
+ const sheets = input.nodes.filter((node) => node.kind === sheetKind);
58
+ counts.planned[category] = planned;
59
+ counts.sheets[category] = sheets.length;
60
+ if (planned === 0)
61
+ continue;
62
+ if (sheets.length === 0) {
63
+ const transparent = imageGenerateIds.length > 0
64
+ ? `画布现有 ${imageGenerateIds.length} 个 image-generate 节点(${imageGenerateIds.slice(0, 5).join('、')}${imageGenerateIds.length > 5 ? ' 等' : ''});透明边界不会追加${label}设定板合同,不能代替。`
65
+ : '';
66
+ errors.push({
67
+ code: 'sheet-node-missing',
68
+ severity: 'error',
69
+ message: `资产计划声明了 ${planned} 个${label},画布上没有 ${sheetKind} 节点。${transparent}`,
70
+ nodeIds: transparent ? imageGenerateIds : [],
71
+ });
72
+ continue;
73
+ }
74
+ if (sheets.length < planned) {
75
+ warnings.push({
76
+ code: 'sheet-coverage-partial',
77
+ severity: 'warning',
78
+ message: `资产计划声明了 ${planned} 个${label},当前只有 ${sheets.length} 个 ${sheetKind} 节点;分批生成可以接受,但不得用 image-generate 补齐剩余项。`,
79
+ nodeIds: [],
80
+ });
81
+ }
82
+ for (const sheet of sheets) {
83
+ const prompt = sheet.config?.prompt;
84
+ if (typeof prompt === 'string' && prompt.trim()) {
85
+ warnings.push({
86
+ code: 'sheet-config-prompt',
87
+ severity: 'warning',
88
+ message: `${sheetKind} 节点 ${sheet.id} 手写了 config.prompt 正文;设定正文应经 prompt 端口由结构化设定节点提供,手写内容不会得到${label}设定板合同的保证。`,
89
+ nodeIds: [sheet.id],
90
+ });
91
+ }
92
+ const sourceKind = promptSourceKind(sheet.id, input.edges, kindById);
93
+ if (sourceKind && !sourceKinds.includes(sourceKind)) {
94
+ warnings.push({
95
+ code: 'sheet-prompt-source',
96
+ severity: 'warning',
97
+ message: `${sheetKind} 节点 ${sheet.id} 的 prompt 端口来自 ${sourceKind},不是${label}结构化设定节点(${sourceKinds.join(' / ')});确认这是有意的,否则先补结构化设定。`,
98
+ nodeIds: [sheet.id],
99
+ });
100
+ }
101
+ if (!hasPromptInput(sheet.id, input.edges)) {
102
+ warnings.push({
103
+ code: 'sheet-prompt-unconnected',
104
+ severity: 'warning',
105
+ message: `${sheetKind} 节点 ${sheet.id} 的 prompt 端口没有入边;服务端会在提交时以 CANVAS_REQUIRED_INPUT_MISSING 拒绝,提前接线可省一次失败提交。`,
106
+ nodeIds: [sheet.id],
107
+ });
108
+ }
109
+ }
110
+ }
111
+ return { ok: errors.length === 0, errors, warnings, counts };
112
+ }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * 画布文档的内容合同。
3
+ *
4
+ * `canvas workflow status` 只按 `document-key` 找到已保存版本,并核对 `--input` 快照是否
5
+ * 过期,不检查正文结构:一份只有 summary 的占位文档同样会让阶段变成 ready。历史问题里
6
+ * Agent 就是先存了这种占位文档,再继续生成资产,事后无法从阶段状态看出分析是空的。
7
+ *
8
+ * 因此把"哪些文档必须包含哪些顶层字段"登记在随包 `module-map.json` 的 `documents`,由 CLI
9
+ * 在发出保存请求前本地核对。字段清单只从该文件读取一次;读取失败时放行并给出警告,避免
10
+ * Skill 目录被用户改动后阻塞与内容无关的保存流程。
11
+ */
12
+ export type CanvasDocumentContract = {
13
+ module: string;
14
+ template_stem: string;
15
+ stage?: string;
16
+ required_fields: string[];
17
+ non_empty_fields?: string[];
18
+ };
19
+ type DocumentContractMap = Record<string, CanvasDocumentContract>;
20
+ /**
21
+ * 按服务端同一套规则解析文档键:先精确匹配登记键,再匹配 `ep-001.script` 这类带分集前缀的键。
22
+ * 与 `documentForModule` 保持一致,避免 CLI 放行、阶段却始终 missing。
23
+ */
24
+ export declare function matchDocumentContract(map: DocumentContractMap, documentKey: string): CanvasDocumentContract | null;
25
+ export declare function templatePathOf(contract: CanvasDocumentContract): string;
26
+ export type DocumentContentCheck = {
27
+ contract: null;
28
+ } | {
29
+ contract: CanvasDocumentContract;
30
+ missing: string[];
31
+ empty: string[];
32
+ };
33
+ export declare function checkDocumentContent(map: DocumentContractMap, documentKey: string, content: unknown): DocumentContentCheck;
34
+ /**
35
+ * 文档键的 schema-key 约定:`canvas.<document-key 末段>.v1`;审核记录统一用 `canvas.review.v1`。
36
+ * 服务端只校验 `canvas.*` 形状,写错不会报错,所以这里给出可修正的提示。
37
+ */
38
+ export declare function expectedSchemaKey(documentKey: string): string;
39
+ export type DocumentContentValidation = {
40
+ contract: CanvasDocumentContract | null;
41
+ warnings: string[];
42
+ };
43
+ export declare function validateCanvasDocumentContent(input: {
44
+ documentKey: string;
45
+ schemaKey: string;
46
+ content: unknown;
47
+ allowPartial?: boolean;
48
+ }): Promise<DocumentContentValidation>;
49
+ export {};
@@ -0,0 +1,94 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ import { bundledSkillPath } from '../skill/skill-manager.js';
4
+ const MODULE_MAP_PATH = join(bundledSkillPath(), 'references', 'short-drama', 'module-map.json');
5
+ let contractsPromise = null;
6
+ async function loadContracts() {
7
+ try {
8
+ const raw = JSON.parse(await readFile(MODULE_MAP_PATH, 'utf8'));
9
+ if (!raw.documents || typeof raw.documents !== 'object' || Array.isArray(raw.documents))
10
+ return {};
11
+ return raw.documents;
12
+ }
13
+ catch {
14
+ return null;
15
+ }
16
+ }
17
+ function contracts() {
18
+ contractsPromise ??= loadContracts();
19
+ return contractsPromise;
20
+ }
21
+ /**
22
+ * 按服务端同一套规则解析文档键:先精确匹配登记键,再匹配 `ep-001.script` 这类带分集前缀的键。
23
+ * 与 `documentForModule` 保持一致,避免 CLI 放行、阶段却始终 missing。
24
+ */
25
+ export function matchDocumentContract(map, documentKey) {
26
+ if (map[documentKey])
27
+ return map[documentKey];
28
+ const key = Object.keys(map).find((candidate) => documentKey.endsWith(`.${candidate}`));
29
+ return key ? map[key] : null;
30
+ }
31
+ function isPlainObject(value) {
32
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
33
+ }
34
+ function isPresent(value) {
35
+ return value !== undefined && value !== null;
36
+ }
37
+ function isEmptyValue(value) {
38
+ if (Array.isArray(value))
39
+ return value.length === 0;
40
+ if (typeof value === 'string')
41
+ return value.trim().length === 0;
42
+ if (isPlainObject(value))
43
+ return Object.keys(value).length === 0;
44
+ return false;
45
+ }
46
+ export function templatePathOf(contract) {
47
+ return `references/short-drama/assets/modules/${contract.module}/prompts/${contract.template_stem}.zh.txt`;
48
+ }
49
+ export function checkDocumentContent(map, documentKey, content) {
50
+ const contract = matchDocumentContract(map, documentKey);
51
+ if (!contract)
52
+ return { contract: null };
53
+ if (!isPlainObject(content))
54
+ return { contract, missing: [...contract.required_fields], empty: [] };
55
+ const missing = contract.required_fields.filter((field) => !isPresent(content[field]));
56
+ const empty = (contract.non_empty_fields ?? []).filter((field) => isPresent(content[field]) && isEmptyValue(content[field]));
57
+ return { contract, missing, empty };
58
+ }
59
+ /**
60
+ * 文档键的 schema-key 约定:`canvas.<document-key 末段>.v1`;审核记录统一用 `canvas.review.v1`。
61
+ * 服务端只校验 `canvas.*` 形状,写错不会报错,所以这里给出可修正的提示。
62
+ */
63
+ export function expectedSchemaKey(documentKey) {
64
+ const segment = documentKey.split('.').pop() ?? documentKey;
65
+ return `canvas.${segment}.v1`;
66
+ }
67
+ export async function validateCanvasDocumentContent(input) {
68
+ const warnings = [];
69
+ const map = await contracts();
70
+ if (!map) {
71
+ warnings.push('未找到随包 module-map.json 的文档合同,已跳过正文结构核对。');
72
+ return { contract: null, warnings };
73
+ }
74
+ const check = checkDocumentContent(map, input.documentKey, input.content);
75
+ if (!check.contract)
76
+ return { contract: null, warnings };
77
+ const expected = expectedSchemaKey(input.documentKey);
78
+ if (input.schemaKey !== expected && input.schemaKey !== 'canvas.review.v1') {
79
+ warnings.push(`--schema-key ${input.schemaKey} 与文档键 ${input.documentKey} 不一致,建议使用 ${expected}。`);
80
+ }
81
+ if (!check.missing.length && !check.empty.length)
82
+ return { contract: check.contract, warnings };
83
+ const problems = [
84
+ check.missing.length ? `缺少顶层字段:${check.missing.join('、')}` : '',
85
+ check.empty.length ? `以下字段为空:${check.empty.join('、')}` : '',
86
+ ].filter(Boolean).join(';');
87
+ const message = `文档 ${input.documentKey} 不符合 ${templatePathOf(check.contract)} 的输出合同:${problems}。`
88
+ + `先完整读取该模板,按它声明的顶层字段生成正文;只写摘要的占位文档会让后续阶段建立在空分析上。`;
89
+ if (input.allowPartial) {
90
+ warnings.push(`${message}(已按 --allow-partial 保存,该版本不得作为阶段依据)`);
91
+ return { contract: check.contract, warnings };
92
+ }
93
+ throw new Error(message);
94
+ }
@@ -11,6 +11,8 @@ export declare function skillStatus(target: string): Promise<{
11
11
  installed: boolean;
12
12
  managed: boolean;
13
13
  current: boolean;
14
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
15
+ outdated: boolean;
14
16
  packageVersion: string;
15
17
  installedVersion: string | null;
16
18
  modified: boolean;
@@ -29,16 +31,21 @@ export declare function installSkills(input: {
29
31
  installed: boolean;
30
32
  managed: boolean;
31
33
  current: boolean;
34
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
35
+ outdated: boolean;
32
36
  packageVersion: string;
33
37
  installedVersion: string | null;
34
38
  modified: boolean;
35
39
  } | {
36
40
  action: "skipped";
41
+ skipReason: "unmanaged" | "modified";
37
42
  name: "using-vvicat-ai-short-studio-cli";
38
43
  target: string;
39
44
  installed: boolean;
40
45
  managed: boolean;
41
46
  current: boolean;
47
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
48
+ outdated: boolean;
42
49
  packageVersion: string;
43
50
  installedVersion: string | null;
44
51
  modified: boolean;
@@ -49,6 +56,8 @@ export declare function installSkills(input: {
49
56
  installed: boolean;
50
57
  managed: boolean;
51
58
  current: boolean;
59
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
60
+ outdated: boolean;
52
61
  packageVersion: string;
53
62
  installedVersion: string | null;
54
63
  modified: boolean;
@@ -64,16 +73,21 @@ export declare function autoInstallSkills(root: string): Promise<{
64
73
  installed: boolean;
65
74
  managed: boolean;
66
75
  current: boolean;
76
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
77
+ outdated: boolean;
67
78
  packageVersion: string;
68
79
  installedVersion: string | null;
69
80
  modified: boolean;
70
81
  } | {
71
82
  action: "skipped";
83
+ skipReason: "unmanaged" | "modified";
72
84
  name: "using-vvicat-ai-short-studio-cli";
73
85
  target: string;
74
86
  installed: boolean;
75
87
  managed: boolean;
76
88
  current: boolean;
89
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
90
+ outdated: boolean;
77
91
  packageVersion: string;
78
92
  installedVersion: string | null;
79
93
  modified: boolean;
@@ -84,6 +98,8 @@ export declare function autoInstallSkills(root: string): Promise<{
84
98
  installed: boolean;
85
99
  managed: boolean;
86
100
  current: boolean;
101
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
102
+ outdated: boolean;
87
103
  packageVersion: string;
88
104
  installedVersion: string | null;
89
105
  modified: boolean;
@@ -98,6 +114,8 @@ export declare function skillStatuses(rootInput: string): Promise<{
98
114
  installed: boolean;
99
115
  managed: boolean;
100
116
  current: boolean;
117
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
118
+ outdated: boolean;
101
119
  packageVersion: string;
102
120
  installedVersion: string | null;
103
121
  modified: boolean;
@@ -112,6 +130,8 @@ export declare function installSkill(input: {
112
130
  installed: boolean;
113
131
  managed: boolean;
114
132
  current: boolean;
133
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
134
+ outdated: boolean;
115
135
  packageVersion: string;
116
136
  installedVersion: string | null;
117
137
  modified: boolean;
@@ -122,6 +142,8 @@ export declare function autoInstallSkill(target: string): Promise<{
122
142
  installed: boolean;
123
143
  managed: boolean;
124
144
  current: boolean;
145
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
146
+ outdated: boolean;
125
147
  packageVersion: string;
126
148
  installedVersion: string | null;
127
149
  modified: boolean;
@@ -132,21 +154,63 @@ export declare function autoInstallSkill(target: string): Promise<{
132
154
  installed: boolean;
133
155
  managed: boolean;
134
156
  current: boolean;
157
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
158
+ outdated: boolean;
135
159
  packageVersion: string;
136
160
  installedVersion: string | null;
137
161
  modified: boolean;
138
162
  action: "skipped";
163
+ skipReason: "unmanaged" | "modified";
139
164
  } | {
140
165
  name: "using-vvicat-ai-short-studio-cli";
141
166
  target: string;
142
167
  installed: boolean;
143
168
  managed: boolean;
144
169
  current: boolean;
170
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
171
+ outdated: boolean;
145
172
  packageVersion: string;
146
173
  installedVersion: string | null;
147
174
  modified: boolean;
148
175
  action: "updated" | "installed";
149
176
  }>;
177
+ /**
178
+ * 对比已安装 Skill 与随包版本,列出本地相对随包新增、缺失和内容不同的文件。
179
+ * 版本落后且被手工修改时,这是用户决定"合并还是覆盖"的唯一依据。
180
+ */
181
+ export declare function diffSkill(target: string): Promise<{
182
+ missing: string[];
183
+ extra: string[];
184
+ changed: string[];
185
+ comparedWith: "bundled";
186
+ bundledPath: string;
187
+ name: "using-vvicat-ai-short-studio-cli";
188
+ target: string;
189
+ installed: boolean;
190
+ managed: boolean;
191
+ current: boolean;
192
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
193
+ outdated: boolean;
194
+ packageVersion: string;
195
+ installedVersion: string | null;
196
+ modified: boolean;
197
+ }>;
198
+ /**
199
+ * 创作前的 Skill 状态摘要。preflight 用它把"CLI 已升级、Skill 停在旧版"暴露出来。
200
+ */
201
+ export declare function skillGate(environment?: NodeJS.ProcessEnv): Promise<{
202
+ skillReady: boolean;
203
+ name: "using-vvicat-ai-short-studio-cli";
204
+ target: string;
205
+ installed: boolean;
206
+ managed: boolean;
207
+ current: boolean;
208
+ state: "missing" | "unmanaged" | "modified" | "current" | "outdated";
209
+ outdated: boolean;
210
+ packageVersion: string;
211
+ installedVersion: string | null;
212
+ modified: boolean;
213
+ }>;
150
214
  export declare function withLegacySkillFields<T extends {
151
215
  root: string;
152
216
  current: boolean;
@@ -24,11 +24,21 @@ async function statusFor(name, target) {
24
24
  const installed = await exists(target);
25
25
  const manifest = installed ? await readManifest(target) : null;
26
26
  const installedChecksum = installed ? await directoryChecksum(target) : null;
27
+ const current = Boolean(manifest && manifest.packageVersion === packageVersion && installedChecksum === bundledChecksum);
28
+ const modified = Boolean(manifest && installedChecksum !== manifest.checksum);
29
+ const outdated = Boolean(manifest && manifest.packageVersion !== packageVersion);
30
+ // state 是给调用方和 Agent 的判断依据:自动更新只允许无修改的 outdated,其余必须由用户决定。
31
+ const state = !installed ? 'missing'
32
+ : !manifest ? 'unmanaged'
33
+ : modified ? 'modified'
34
+ : current ? 'current' : 'outdated';
27
35
  return {
28
36
  name, target, installed, managed: Boolean(manifest),
29
- current: Boolean(manifest && manifest.packageVersion === packageVersion && installedChecksum === bundledChecksum),
37
+ current,
38
+ state,
39
+ outdated,
30
40
  packageVersion, installedVersion: manifest?.packageVersion ?? null,
31
- modified: Boolean(manifest && installedChecksum !== manifest.checksum),
41
+ modified,
32
42
  };
33
43
  }
34
44
  export async function skillStatus(target) {
@@ -70,7 +80,8 @@ export async function installSkills(input) {
70
80
  continue;
71
81
  }
72
82
  if (current.installed && !input.force && (!current.managed || current.modified)) {
73
- results.push({ ...current, action: 'skipped' });
83
+ // 静默跳过会让 CLI 升级后 Skill 长期停在旧版本,必须把原因带回调用方。
84
+ results.push({ ...current, action: 'skipped', skipReason: current.managed ? 'modified' : 'unmanaged' });
74
85
  continue;
75
86
  }
76
87
  results.push({ ...await installOne(name, target), action: current.installed ? 'updated' : 'installed' });
@@ -101,10 +112,63 @@ export async function autoInstallSkill(target) {
101
112
  const current = await statusFor(name, target);
102
113
  if (current.current)
103
114
  return { action: 'unchanged', ...current };
104
- if (current.installed && (!current.managed || current.modified))
105
- return { action: 'skipped', ...current };
115
+ if (current.installed && (!current.managed || current.modified)) {
116
+ return { action: 'skipped', skipReason: current.managed ? 'modified' : 'unmanaged', ...current };
117
+ }
106
118
  return { action: current.installed ? 'updated' : 'installed', ...await installOne(name, target) };
107
119
  }
120
+ /**
121
+ * 对比已安装 Skill 与随包版本,列出本地相对随包新增、缺失和内容不同的文件。
122
+ * 版本落后且被手工修改时,这是用户决定"合并还是覆盖"的唯一依据。
123
+ */
124
+ export async function diffSkill(target) {
125
+ const name = BUNDLED_SKILL_NAMES[0];
126
+ const status = await statusFor(name, target);
127
+ const bundledRoot = bundledSkillPath(name);
128
+ const empty = { missing: [], extra: [], changed: [] };
129
+ if (!status.installed)
130
+ return { ...status, comparedWith: 'bundled', bundledPath: bundledRoot, ...empty };
131
+ const bundledFiles = new Set((await filesBelow(bundledRoot)).map((file) => relative(bundledRoot, file)));
132
+ const installedFiles = new Set((await filesBelow(target))
133
+ .map((file) => relative(target, file))
134
+ .filter((file) => file !== MANIFEST));
135
+ const missing = [...bundledFiles].filter((file) => !installedFiles.has(file)).sort();
136
+ const extra = [...installedFiles].filter((file) => !bundledFiles.has(file)).sort();
137
+ const changed = [];
138
+ for (const file of bundledFiles) {
139
+ if (!installedFiles.has(file))
140
+ continue;
141
+ const [bundledContent, installedContent] = await Promise.all([
142
+ readFile(join(bundledRoot, file)),
143
+ readFile(join(target, file)),
144
+ ]);
145
+ if (!bundledContent.equals(installedContent))
146
+ changed.push(file);
147
+ }
148
+ return { ...status, comparedWith: 'bundled', bundledPath: bundledRoot, missing, extra, changed: changed.sort() };
149
+ }
150
+ /**
151
+ * 创作前的 Skill 状态摘要。preflight 用它把"CLI 已升级、Skill 停在旧版"暴露出来。
152
+ */
153
+ export async function skillGate(environment = process.env) {
154
+ // 显式指定目录/根目录时只看该位置:用户已经用环境变量固定了 Skill 来源,不能再回退到默认目录。
155
+ if (environment.VVICAT_SKILL_DIRECTORY) {
156
+ return gateFor([environment.VVICAT_SKILL_DIRECTORY]);
157
+ }
158
+ if (environment.VVICAT_SKILLS_ROOT) {
159
+ const target = join(normalizeSkillsRoot(environment.VVICAT_SKILLS_ROOT), BUNDLED_SKILL_NAMES[0]);
160
+ return gateFor([target]);
161
+ }
162
+ return gateFor([defaultSkillTarget('codex'), defaultSkillTarget('agents')]);
163
+ }
164
+ async function gateFor(candidates) {
165
+ for (const target of candidates) {
166
+ const status = await statusFor(BUNDLED_SKILL_NAMES[0], target);
167
+ if (status.installed)
168
+ return { ...status, skillReady: status.current };
169
+ }
170
+ return { ...await statusFor(BUNDLED_SKILL_NAMES[0], candidates[0]), skillReady: false };
171
+ }
108
172
  export function withLegacySkillFields(result) {
109
173
  return { ...result.skills[0], root: result.root, allCurrent: result.current, skills: result.skills };
110
174
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aswless_854771076/ai_short_studio_cli",
3
- "version": "0.1.159",
3
+ "version": "0.1.161",
4
4
  "description": "VVICAT 无限画布项目命令行工具",
5
5
  "license": "MIT",
6
6
  "private": false,
@@ -24,7 +24,12 @@ export async function main(environment = process.env) {
24
24
  }
25
25
  : await autoInstallSkills(environment.VVICAT_SKILLS_ROOT || defaultSkillsRoot('codex'))
26
26
  for (const skill of result.skills) {
27
- process.stdout.write(`VVICAT Skill ${skill.name} ${skill.action}: ${skill.target}\n`)
27
+ // 跳过必须说明原因,否则 CLI 升级后 Skill 会静默停在旧版本。
28
+ const reason = skill.action !== 'skipped' ? ''
29
+ : skill.skipReason === 'modified'
30
+ ? ` (本地 Skill ${skill.installedVersion ?? '未知'} 已被手工修改,未覆盖为 ${skill.packageVersion};运行 ai-short-studio skill diff 查看差异,确认后再 skill install --force)`
31
+ : ` (目录不由 CLI 托管,未覆盖为 ${skill.packageVersion};运行 ai-short-studio skill diff 核对差异)`
32
+ process.stdout.write(`VVICAT Skill ${skill.name} ${skill.action}: ${skill.target}${reason}\n`)
28
33
  }
29
34
  } catch (error) {
30
35
  process.stderr.write(`VVICAT CLI 已安装,Skill 自动安装已跳过:${error instanceof Error ? error.message : String(error)}\n`)
@@ -56,11 +56,11 @@ description: Use when an agent needs to inspect or operate VVICAT infinite-canva
56
56
 
57
57
  ## 主流程
58
58
 
59
- 1. **预检与实时节点目录门禁**:运行 `preflight --json`;更新后重跑。再读取 `config get`、目标项目、`canvas documents` 和 `canvas workflow status`,并在创建或配置任何节点前读取 `canvas node types --json`。config 只写实时 `configSchema.properties` 声明的键;`title`、坐标和连线身份属于节点属性(`canvas node add --title`、`canvas node update --title`),不写入 `config`,`music-generate` 的 `title` 只是 Suno 模型参数,不得复制到其他节点;服务端或调用方拒绝未知配置字段时,删除该字段并按实时 schema 重试,不猜字段名。结构化短剧节点的输出按 `structuredOutputSchema` 组织,不能从 `TEXT`/`SCRIPT` 端口猜 JSON。`skill status --target codex` 非 current 时先询问再更新,禁止强制覆盖用户修改。
59
+ 1. **预检与实时节点目录门禁**:运行 `preflight --json`;更新后重跑。再读取 `config get`、目标项目、`canvas documents` 和 `canvas workflow status`,并在创建或配置任何节点前读取 `canvas node types --json`。config 只写实时 `configSchema.properties` 声明的键;`title`、坐标和连线身份属于节点属性(`canvas node add --title`、`canvas node update --title`),不写入 `config`,`music-generate` 的 `title` 只是 Suno 模型参数,不得复制到其他节点;服务端或调用方拒绝未知配置字段时,删除该字段并按实时 schema 重试,不猜字段名。结构化短剧节点的输出按 `structuredOutputSchema` 组织,不能从 `TEXT`/`SCRIPT` 端口猜 JSON。**Skill 版本门禁**:`preflight --json` 返回的 `skill.state` 不是 `current`(`outdated`、`modified`、`unmanaged`、`missing` 都算)时,停止创作并先处理——`modified`/`outdated` 先运行 `ai-short-studio skill diff --target codex --json`,把 `changed`/`extra`/`missing` 文件展示给用户,让其决定"保留改动并手工合并"还是"`skill install --force` 覆盖";`missing` 先 `skill install`。CLI 升级不会覆盖用户改过的 Skill,因此 CLI 版本新、Skill 停在旧版时,你运行的是旧规则,不得继续创作,也不得强制覆盖用户修改。
60
60
  2. **项目语言门禁**:新建项目前必须从用户确认交付语言,并用 `project create --language <BCP47>` 写入;界面 `--locale` 不能代替内容语言。创建后回读 `project get` 与 `canvas settings get`,确认两者语言一致且不可修改。项目语言约束剧本、分镜、台词、配音、画面文字和字幕;验收须区分剧情内容与制作信息:项目语言允许正常外语穿插和规范英文摄影术语,不按字符种类判死;道具文字和剧情内界面遵循来源原文。存在实际语言合同冲突时停止并说明。
61
61
  3. **项目配置门禁**:项目初始化时必须向用户展示并确认创作配置,不得只采用账户默认值:交付语言、画幅、目标时长、画风、分镜板策略、分析/文本模型、图片模型及其厂商、视频模型及其厂商、视频提示词协议、音频/配乐模型及其厂商、声音一致性方式、分辨率、画质、候选数量、参考素材和预计请求范围。先读取 `canvas settings get`,展示 `currentValue`、`effectiveValue`、`source`、建议值和实时 options;确认 `imageResolution`、`imageQuality` 和 `videoResolution` 后,再按标准创作门禁用 `--file settings.json` 原子写入并携带 `expectedVersion`,回读一致前不得创建或运行付费节点。`$ART_STYLE_ID` 必须解析实时 `option.value`。节点确需不同参数时才按实时能力覆盖,并记录覆盖原因;`automation_mode` 只能省略已确认且未变化的重复询问,不能替用户确认模型/厂商或付费范围。
62
- 4. **创作链路与自由画布文档**:按 `canvas workflow status` 返回的 `currentStage` 依次生成来源分析 → 创作简报 → 故事设定 → 分集大纲 → 单集剧本 → Humanizer 自然化 → 剧本审校 → 导演手册 → 资产计划;每步用 `canvas document save` 写入 `canvas.<module>.v1`,用 `--input` 固化上游选版,审核必须另存为 `canvas.review.v1` 并绑定被审核版本。无需先调用固定节点或生成模型,不要创建没有版本的文档空壳。已有自由画布文档直接复用;历史 `screenplay-resource` 或结构化资源先迁移成 自由画布文档,再继续流程。需要创作微短剧时,按需读取 `references/short-drama/`,再完整读取 [官方 Humanizer 快照](references/humanizer/humanizer.md)(来源见 [快照说明](references/humanizer/SOURCE.md))和 [短剧适配层](references/short-drama/creation/humanizer.md) 去除 AI 味;不得改动已经确认的剧情事实,剧本审校 P0/P1 未清零不得进入导演与资产阶段,润色后回到短剧 reference 复核。确认目标集数后,只生产该集实际需要的资产。
63
- 5. **资产门禁**:先完成人物、场景、道具及其派生版本。资产图分别用 `character-turnaround`、`location-image`(`locationImagePurpose: location-sheet`)、`prop-turnaround`,`prompt` 端口连接结构化设定节点;默认模板 `character_asset_sheet`、`scene_asset_sheet`、`prop_generate` 是参考正文,不得删除,也不得改用 `image-generate` 代替设定板。每批生成完成后必须用 `canvas asset download` 或等效预览能力取得真实候选,并在当前对话中展示候选缩略图/文件链接、资产 key、版本和用途;用户确认后才能写入 selected version。只在用户看过候选且确认后选版。执行资产—剧情匹配审计;缺失、多余、错版、stale、错边未清零时拆镜前门禁失败。
62
+ 4. **创作链路与自由画布文档**:按 `canvas workflow status` 返回的 `currentStage` 依次生成来源分析 → 创作简报 → 故事设定 → 分集大纲 → 单集剧本 → Humanizer 自然化 → 剧本审校 → 导演手册 → 资产计划。每步固定四件事,缺一步不算完成:①从 [文档键与内容合同](references/short-drama/pipeline.md#文档键与内容合同) 取登记的 `--document-key`,不能按节点标题或 module ID 自行拼写;②完整读取 `references/short-drama/assets/modules/<module>/prompts/` 下该模块的模板,按它声明“顶层必须且只能包含”的字段生成严格 JSON,不得只写 `summary`、`source_type` 一类自造字段或空数组;③用 `canvas document save` 写入 `canvas.<module>.v1`,并用 `--input` 固化上游选版;④用 `canvas documents` 和 `canvas document get` 回读,逐项确认必需字段是真实分析而不是占位。`canvas document save` 会按随包合同拦下缺字段和空字段文档,报错时补正文并重读模板,不得用 `--allow-partial` 把占位文档当成阶段产物。审核必须另存为 `canvas.review.v1` 并绑定被审核版本。无需先调用固定节点或生成模型,不要创建没有版本的文档空壳,也不要先铺一批空 `text-resource` 节点再补正文。已有自由画布文档直接复用;历史 `screenplay-resource` 或结构化资源先迁移成 自由画布文档,再继续流程。需要创作微短剧时,按需读取 `references/short-drama/`,再完整读取 [官方 Humanizer 快照](references/humanizer/humanizer.md)(来源见 [快照说明](references/humanizer/SOURCE.md))和 [短剧适配层](references/short-drama/creation/humanizer.md) 去除 AI 味;不得改动已经确认的剧情事实,剧本审校 P0/P1 未清零不得进入导演与资产阶段,润色后回到短剧 reference 复核。确认目标集数后,只生产该集实际需要的资产。
63
+ 5. **资产门禁**:先完成人物、场景、道具及其派生版本。资产图分别用 `character-turnaround`、`location-image`(`locationImagePurpose: location-sheet`)、`prop-turnaround`,`prompt` 端口连接结构化设定节点;默认模板 `character_asset_sheet`、`scene_asset_sheet`、`prop_generate` 是参考正文,不得删除,也不得改用 `image-generate` 代替设定板:它是透明边界,服务端不会为它追加三视图或九视角合同。提交资产生成前先运行 `canvas node list --project <projectId> --json` 逐项核对 `kind` 与 `prompt` 端口;出现用 `image-generate` 生成的人物、场景或道具图,必须用对应设定板节点重建并回读,旧候选只留作历史,不选版、不进入分镜和视频。**机器门禁**:资产计划文档保存并回读后、提交任何资产生成前,必须运行 `ai-short-studio canvas asset audit --project <projectId> --json`;只有 `ok: true` 才能继续,`errors` 非空(例如 `sheet-node-missing`,即计划里有资产却全部用 `image-generate`)时按 `nodeIds` 重建设定板节点后重跑,不得跳过或用手工核对代替。`warnings` 要逐条读并修正(手写 `config.prompt`、`prompt` 端口来源不是结构化设定节点、端口未接线、覆盖不全),`blocked: asset-plan-not-ready` 说明资产计划文档还没保存或未审核,回到第 4 步。每批生成完成后必须用 `canvas asset download` 或等效预览能力取得真实候选,并在当前对话中展示候选缩略图/文件链接、资产 key、版本和用途;用户确认后才能写入 selected version。只在用户看过候选且确认后选版。执行资产—剧情匹配审计;缺失、多余、错版、stale、错边未清零时拆镜前门禁失败。
64
64
  6. **拆镜与制作计划**:先执行 [拆镜模式与交付范围](references/assets-and-storyboard.md#拆镜模式与交付范围) 和 [语言匹配门禁](references/assets-and-storyboard.md#拆镜语言匹配门禁)。短剧新建默认专业拆镜,显式设置 `sourceFormat` 与 `storyboardPipelineVersion: 2`,不自动新增首帧节点。结构化分镜之后依次生成逐镜制作计划和跨镜连续性计划;只有前镜已审核且选版时才允许 previous-tail。视频提交前必须完成素材连线、镜头逻辑和上下镜连续性审计。
65
65
  7. **分镜图与逐镜审计**:Agent 先读取每镜 `storyboard_strategy`,按制作目标选择单幅分镜图、时间故事版、镜头分镜板、专项板或 Blender;已选择一种板型时不得自动补生成另一种。只审核实际生成的板型,并让视频提示词只引用真实存在且已审核的分镜资产。逐镜审计 P0/P1 未清零不得写入视频提示词或提交视频。用户的停止阶段优先于 [滚动异步调度](references/async-pipeline.md):仅分镜图任务完成实际选择的板型并通过审核后停止,不运行视频提示词和视频。
66
66
  8. **视频规划、提示词与 H3 生成门禁**:读取实时 `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。`videoModel` 为 `comfly::minimax-h3` 或 `runninghub::minimax-h3-reference-to-video` 时,同次设置 `videoPromptType: "h3"`;仅有效的节点 `promptType` 可覆盖项目值,旧 `seedance` 覆盖必须清除并回读,否则不得执行视频生成或写入提示词。Agent 编写 H3 提示词时读取 `references/short-drama/prompt/h3-prompt-writing.md`,写入后回读提示词选版;进入生成前必须读取 [H3 成片规则](references/h3-video-delivery.md)。
@@ -39,6 +39,14 @@
39
39
 
40
40
  这些资产不得用 `image-generate` 生成:它是透明边界,只组合用户直填或连入的文本,不追加设定板或分镜板合同。每项资产使用独立节点和独立资产版本,`count` 的多结果不能拼图。模板变量必须由已选资产计划、已确认档案和完整画风对象填充,不保留占位符,不把临时 URL、节点标题或未选版素材写进正文。
41
41
 
42
+ 提交资产生成前执行节点类型核对,避免用错节点白付一次生成:
43
+
44
+ 1. 运行 `canvas node list --project <projectId> --json`,逐项读取 `kind`:人物只能是 `character-turnaround`,场景只能是 `location-image`,道具只能是 `prop-turnaround`,分镜板只能是 `storyboard-grid-image`、`storyboard-board-image` 或 `storyboard-image`。
45
+ 2. 人物、场景、道具的 `prompt` 必须来自结构化设定节点连线(`character-visual-design`、`location-resource`、`prop-resource`);`config.prompt` 不手写外观描述冒充设定,否则服务端合同与手写正文会互相拉扯。
46
+ 3. 发现 `image-generate` 承载上述任一资产时按错节点处理:新建正确节点、重连端口、回读新节点的 `kind` 与端口,再提交生成;已生成的候选只作历史,不选版、不进入分镜和视频。修改标题或补写 `config.prompt` 不能把普通生图补成设定板。
47
+ 4. 资产计划文档保存并回读后运行 `canvas asset audit --project <projectId> --json`:这是本节的机器门禁,命令会对照资产计划逐类统计设定板节点,`ok: false` 时按 `errors[].nodeIds` 重建设定板节点后重跑;`warnings` 中的 `sheet-config-prompt`、`sheet-prompt-source`、`sheet-prompt-unconnected`、`sheet-coverage-partial` 逐条修正,不能用手工核对替代。`blocked: asset-plan-not-ready` 表示资产计划文档未保存或未审核,先回到资产计划阶段。
48
+ 5. 生成后回读 `prompt` 与 `reference` 端口,确认没有悬空、临时 URL 或未选版素材,再下载真实候选交给用户确认。
49
+
42
50
  专业镜头的 `assetNodeRefs` 与 `visualAssetBindings` 共用镜头选版。通过下文专业增量修订流程,为每项设定来源绑定实际 `imageNodeId`,并把这些图片接到已选择板型的 `reference` 端口;不能按节点标题猜归属。每个绑定图片节点只能代表一个选定媒体,多候选需使用单项资源节点。服务端在付费板图前检查全部声明资产、上游真实设定边、选版与实际上送图片;提示词按实际数组编译身份和参考序号。修改绑定会使已选择板型及下游 stale;设定换版或文字投影变化同样使旧来源失效。所有已选择板型都审核通过仍要比较实际参考集合,差异不能由文字批准覆盖;引用覆盖不代表图像像素已符合设定。
43
51
 
44
52
  1. 只生产目标集实际出现的人物及形象版本、场景/子场景、关键道具及叙事版本。每项任务成功后展示真实预览,让用户确认并设置 selected version。
@@ -3,6 +3,7 @@
3
3
  ## 资产
4
4
 
5
5
  ```bash
6
+ ai-short-studio canvas asset audit --project <projectId> --json
6
7
  ai-short-studio canvas asset list --project <projectId> --json
7
8
  ai-short-studio canvas asset get <assetId> --project <projectId> --json
8
9
  ai-short-studio canvas asset upload <file> --project <projectId> --json
@@ -10,6 +11,8 @@ ai-short-studio canvas asset select-version <assetId> --version <versionId> --pr
10
11
  ai-short-studio canvas asset download <assetId> --project <projectId> --output <directory>
11
12
  ```
12
13
 
14
+ `canvas asset audit` 是提交资产生成前的机器门禁:读取已就绪的资产计划文档和画布节点、连线,按人物/场景/道具逐类核对是否使用 `character-turnaround`、`location-image`、`prop-turnaround`,并检查 `prompt` 端口来源。`ok: false` 或退出码 7 时按 `errors[].nodeIds` 修正后重跑;`warnings` 必须逐条处理;`blocked: asset-plan-not-ready` 表示资产计划文档未保存或未审核。`--document-key` 只在同一项目存在多份资产计划时用于指定具体文档。
15
+
13
16
  下载前确认 `selectedOutputVersionId`。原始视频按镜号保存为 `S001.mp4`、`S002.mp4`,manifest 至少记录 `shotNumber`、`nodeId`、`assetId`、`versionId`、`fileName`。
14
17
 
15
18
  ## 执行和等待
@@ -5,12 +5,14 @@
5
5
  ```bash
6
6
  ai-short-studio preflight --json
7
7
  ai-short-studio skill status --target codex --json
8
+ ai-short-studio skill diff --target codex --json
9
+ ai-short-studio skill install --target codex --force
8
10
  ai-short-studio auth login
9
11
  ai-short-studio auth status --json
10
12
  ai-short-studio auth logout
11
13
  ```
12
14
 
13
- 更新 CLI 后重跑 preflight。CLI 默认通过 MemHub 浏览器授权登录。
15
+ 更新 CLI 后重跑 preflight。CLI 默认通过 MemHub 浏览器授权登录。`preflight` 返回的 `skill` 块给出 Skill 状态和 `skillReady`;`state` 不是 `current` 时不得继续创作。`skill diff` 对照随包版本列出 `changed`、`extra`、`missing`,用于在“手工合并用户改动”和 `skill install --force` 覆盖之间做决定;`--force` 会丢弃用户改过的 Skill,只在用户明确同意后使用。
14
16
 
15
17
  ## 项目与供应商
16
18
 
@@ -16,9 +16,9 @@ description: 短剧全流程唯一入口。用于原创短剧的创建、恢复
16
16
  2. 新项目读取 [项目管理模块](operations/manage-drama-projects.md) 后初始化;AI Short Studio 项目先运行 `canvas documents` 和 `canvas workflow status`。
17
17
  3. 运行 `ai-short-studio canvas workflow status --project <projectId> --json`,以远程画布状态和文档版本作为唯一事实来源;不要用本地状态文件覆盖。
18
18
  4. 对返回的每个 `module_id`,从本目录 `module-map.json` 读取唯一 `path`(相对插件根目录),完整读取该 reference 后执行其输入、输出、失败关闭和验收合同。
19
- 5. 文本由 Codex 生成;只有图片、视频、声音和媒体变换调用 Provider。所有提示词使用 `assets/modules/<module_id>/prompts/` 中登记的模板。
20
- 6. 每个模块完成后,把实际输入、已选版本和验收证据保存为新的 `canvas.<module>.v1` 文档版本,并用 `--input` 记录上游版本;不得用本地状态文件或本地完成标记代替服务端版本。
21
- 7. 运行 `canvas workflow status` 复核当前阶段;只有当前及已完成阶段的文档、资产、审核和选版证据全部有效时才进入下一阶段。修改上游事实时回退受影响阶段并追加新版本,不手改完成状态。
19
+ 5. 文本由 Codex 生成;只有图片、视频、声音和媒体变换调用 Provider。所有提示词使用 `references/short-drama/assets/modules/<module_id>/prompts/` 中登记的模板。生成文档正文前必须完整读取该模块的模板,输出以其“顶层必须且只能包含”的字段为准;不得按节点标题或自己的摘要字段臆造结构。
20
+ 6. 每个模块完成后,把实际输入、已选版本和验收证据保存为新的 `canvas.<module>.v1` 文档版本,并用 `--input` 记录上游版本;不得用本地状态文件或本地完成标记代替服务端版本。文档键取 [文档键与内容合同](pipeline.md#文档键与内容合同) 的登记值,`canvas document save` 会按合同核对正文,缺字段时先补正文而不是改用 `--allow-partial`。
21
+ 7. 运行 `canvas workflow status` 复核当前阶段;只有当前及已完成阶段的文档、资产、审核和选版证据全部有效时才进入下一阶段。修改上游事实时回退受影响阶段并追加新版本,不手改完成状态。`ready` 只表示文档键、版本和来源快照有效,不证明正文有分析内容;推进前用 `canvas document get` 回读正文并对照模板字段。
22
22
 
23
23
  ## 九阶段基础路由
24
24
 
@@ -14,10 +14,10 @@ Execution role: short-drama production planner. Turn the source analysis and use
14
14
  {market_inspiration}
15
15
 
16
16
  Rules:
17
- 1. Put every unresolved parameter that changes the creative result in open_questions, use null for its field, and set approved to false.
18
- 2. Use BCP 47 language tags and record output text, spoken dialogue, and subtitle language separately.
17
+ 1. For every unresolved parameter that changes the creative result, set its field to null and add one open_questions item naming the field and the open question; open_questions must be an array and approved must be false.
18
+ 2. language and subtitle_language are BCP 47 strings for delivery/dialogue language and subtitle language; use null for an unconfirmed subtitle language and add an open_questions item when dialogue and delivery languages differ.
19
19
  3. Never choose episode count, duration, aspect ratio, platform, rating, or ending type from convention. episode_duration_seconds is a planning target, not an exact frame-level cutoff; treat it as a hard maximum only when the platform explicitly imposes one.
20
- 4. Keep adaptation_mode consistent with source-analysis and record adaptation boundaries in creative_constraints.
20
+ 4. adaptation_mode is exactly original, faithful_adaptation, or authorized_adaptation, and must match source-analysis; record adaptation boundaries in creative_constraints.
21
21
  5. approved may be true only after open_questions is empty and the user has confirmed the whole brief.
22
22
  6. Write market_inspiration_ref only when the user explicitly selects market inspiration, preserving that inspiration artifact's complete report_ref exactly; otherwise use null. This reference cannot override source facts, compliance requirements, or user-confirmed decisions.
23
23
 
@@ -14,10 +14,10 @@
14
14
  {market_inspiration}
15
15
 
16
16
  规则:
17
- 1. 未由用户确认且会改变创作结果的参数写入 open_questions,对应字段用 null,approved 必须为 false。
18
- 2. 语言使用 BCP 47;分别记录交付文本、人物说话和字幕语言。
17
+ 1. 未由用户确认且会改变创作结果的参数,对应字段用 null,并把字段名和待确认问题作为一项写入 open_questions;open_questions 必须是数组,approved 必须为 false。
18
+ 2. language 与 subtitle_language 使用 BCP 47 字符串,分别记录交付/对白语言与字幕语言;字幕语言未确认时为 null,对白与交付语言不同时写入 open_questions。
19
19
  3. episode_count、episode_duration_seconds、画幅、平台、分级和结局类型不得从行业惯例自动代选。episode_duration_seconds 是单集策划目标,不是要求成片逐秒精确命中的硬截止;只有平台明确限长时才作为上限。
20
- 4. adaptation_mode 和 source-analysis 一致;改编边界写入 creative_constraints。
20
+ 4. adaptation_mode 只能是 original、faithful_adaptation 或 authorized_adaptation,并与 source-analysis 一致;改编边界写入 creative_constraints。
21
21
  5. approved 只有在 open_questions 为空且用户已确认整份简报后才能为 true。
22
22
  6. 只有用户明确选用市场灵感时才写入 market_inspiration_ref,并逐字保留所选灵感产物的完整 report_ref;否则必须为 null。该引用不能代替来源事实、合规要求或用户确认的决定。
23
23
 
@@ -401,6 +401,136 @@
401
401
  "edit-deliver-drama"
402
402
  ]
403
403
  },
404
+ "documents": {
405
+ "source-analysis": {
406
+ "module": "analyze-drama-source",
407
+ "template_stem": "source_analysis",
408
+ "stage": "analysis",
409
+ "required_fields": [
410
+ "source_scope",
411
+ "adaptation_mode",
412
+ "facts",
413
+ "timeline",
414
+ "characters",
415
+ "locations",
416
+ "props",
417
+ "conflicts",
418
+ "themes",
419
+ "visual_challenges",
420
+ "content_constraints",
421
+ "user_requirements",
422
+ "contradictions",
423
+ "open_questions",
424
+ "coverage"
425
+ ]
426
+ },
427
+ "bible": {
428
+ "module": "design-drama-bible",
429
+ "template_stem": "ai_story_expand",
430
+ "stage": "analysis",
431
+ "required_fields": [
432
+ "premise",
433
+ "genre",
434
+ "tone",
435
+ "themes",
436
+ "world_rules",
437
+ "ending",
438
+ "characters",
439
+ "relationships",
440
+ "three_act",
441
+ "conflict_ladder",
442
+ "promises_and_payoffs",
443
+ "foreshadowing",
444
+ "continuity_rules",
445
+ "adaptation_constraints",
446
+ "open_questions"
447
+ ]
448
+ },
449
+ "outline": {
450
+ "module": "outline-drama-series",
451
+ "template_stem": "episode_split",
452
+ "stage": "analysis",
453
+ "required_fields": [
454
+ "episodes"
455
+ ],
456
+ "non_empty_fields": [
457
+ "episodes"
458
+ ]
459
+ },
460
+ "script": {
461
+ "module": "write-drama-episode",
462
+ "template_stem": "screenplay_conversion",
463
+ "stage": "script",
464
+ "required_fields": [
465
+ "clip_id",
466
+ "original_text",
467
+ "scenes",
468
+ "unresolved"
469
+ ],
470
+ "non_empty_fields": [
471
+ "scenes"
472
+ ]
473
+ },
474
+ "director-book": {
475
+ "module": "write-drama-director-book",
476
+ "template_stem": "director_book",
477
+ "stage": "director-book",
478
+ "required_fields": [
479
+ "episode_key",
480
+ "source_script_version",
481
+ "scenes",
482
+ "continuity_ledger",
483
+ "open_questions"
484
+ ],
485
+ "non_empty_fields": [
486
+ "scenes"
487
+ ]
488
+ },
489
+ "asset-plan": {
490
+ "module": "plan-drama-assets",
491
+ "template_stem": "asset_analysis",
492
+ "stage": "asset-analysis",
493
+ "required_fields": [
494
+ "episode_key",
495
+ "characters",
496
+ "scenes",
497
+ "props",
498
+ "unresolved"
499
+ ]
500
+ },
501
+ "production-plan": {
502
+ "module": "plan-drama-production",
503
+ "template_stem": "production_plan",
504
+ "stage": "production-plan",
505
+ "required_fields": [
506
+ "episode_key",
507
+ "source_versions",
508
+ "shots",
509
+ "totals",
510
+ "unresolved",
511
+ "approved"
512
+ ],
513
+ "non_empty_fields": [
514
+ "shots"
515
+ ]
516
+ },
517
+ "continuity-plan": {
518
+ "module": "plan-shot-continuity",
519
+ "template_stem": "continuity_plan",
520
+ "stage": "production-plan",
521
+ "required_fields": [
522
+ "episode_key",
523
+ "source_versions",
524
+ "scenes",
525
+ "shots",
526
+ "unresolved",
527
+ "approved"
528
+ ],
529
+ "non_empty_fields": [
530
+ "shots"
531
+ ]
532
+ }
533
+ },
404
534
  "provider_prompts": [
405
535
  "character_asset_sheet",
406
536
  "scene_asset_sheet",
@@ -23,6 +23,31 @@
23
23
 
24
24
  进入媒体或剪辑阶段前运行 `ai-short-studio preflight --json`。每次付费生成前重新核对当前阶段、全部上游门禁、模型实时能力和用户确认范围;失败发生在提交付费请求之前。
25
25
 
26
+ ## 文档键与内容合同
27
+
28
+ 阶段状态只按 `document-key` 匹配文档:不按节点标题、`schema-key` 或创建顺序判断,键写错时该阶段会一直显示 `missing`。以下键与必需顶层字段以 `module-map.json` 的 `documents` 为唯一机器事实;`canvas document save` 在发出请求前按同一合同核对正文,缺字段或非空字段为空时直接失败并指出要读的模板路径。
29
+
30
+ | 文档键 | 模块 | 说明 |
31
+ | --- | --- | --- |
32
+ | `source-analysis` | `analyze-drama-source` | 来源分析,15 个顶层字段全部必填,`coverage` 记录逐份来源覆盖 |
33
+ | `bible` | `design-drama-bible` | 故事设定,三幕、人物弧、冲突阶梯与伏笔回收 |
34
+ | `outline` | `outline-drama-series` | 分集大纲,`episodes` 不得为空 |
35
+ | `script` | `write-drama-episode` | 单集剧本,保存时使用 `ep-001.script` 这类带分集前缀的键,`scenes` 不得为空 |
36
+ | `director-book` | `write-drama-director-book` | 导演本,逐场摄影与表演决定 |
37
+ | `asset-plan` | `plan-drama-assets` | 资产计划,人物、场景、道具与未决问题 |
38
+ | `production-plan` | `plan-drama-production` | 逐镜制作计划,`shots` 不得为空 |
39
+ | `continuity-plan` | `plan-shot-continuity` | 跨镜连续性计划,`shots` 不得为空 |
40
+
41
+ 其余阶段文档键固定为 `brief`、`humanized`、`script.review`、`art-style`、`asset-selection`、`storyboard`、`storyboard-images`、`video-prompts`、`videos`、`shot-review`、`edit-plan`、`delivery-review`;审核类文档另存为 `canvas.review.v1`,正文按 [画布命令](../commands/canvas.md) 的审核形状写 `decision` 与 `issues`,不能写成模板里的 `approved` 字段。
42
+
43
+ 保存顺序固定为:读取 `module-map.json` 的文档合同 → 完整读取对应 `assets/modules/<module>/prompts/<template_stem>.zh.txt` 模板 → 按模板声明的顶层字段生成 JSON → `canvas document save --document-key <登记键> --schema-key canvas.<键末段>.v1 --input <上游节点>` → `canvas documents` 与 `canvas document get` 回读必需字段和来源快照。
44
+
45
+ - 只写摘要、`source_type` 一类自造字段或空数组的占位文档不是阶段产物:它会让 `workflow status` 变成 ready,但下游拿到的是空分析。这类文档必须重写,不能用 `--allow-partial` 绕过。
46
+ - `--allow-partial` 只用于用户明确要求保存的半成品草稿;该版本不得作为阶段依据,也不得下游继承。
47
+ - 不要先铺一批空的 `text-resource` 节点再补正文;只有实际写出正文并保存版本的文档才创建节点,或直接复用已有节点。
48
+ - 文档键与 `--input` 快照必须同时正确:键对而来源缺失、来源选版变化都会让阶段重新变为不可用。
49
+
50
+
26
51
  ## 资产与媒体
27
52
 
28
53
  图片、音频和视频生成成功后,必须立即下载或回读真实产物,登记为画布资产版本并记录 SHA-256、来源和任务信息,再允许选版或进入下游。远程 URL 只是临时传输结果,不得作为最终资产;未选版、未审核或带过期链接的素材不得写入下游节点。
@@ -1,6 +1,6 @@
1
1
  # Seedance 2.0 逐镜提示词规范
2
2
 
3
- 本文件是随包内置的 Seedance 提示词检查层,不依赖外部站点或社区仓库。正式提交模板是 `assets/modules/write-drama-video-prompts/prompts/seedance2_video.zh.txt` 与 `.en.txt`;本文件只规定编译前的判断、素材用途、动作、镜头、表演、声音、连续性和返工顺序。类型决策、描述维度和质量分级见 [通用提示词规范](prompt-craft.md)。模型参数、素材上限和输入模式以实时 Provider schema 为准,模板与实时能力冲突时先修正路由。
3
+ 本文件是随包内置的 Seedance 提示词检查层,不依赖外部站点或社区仓库。正式提交模板是 `references/short-drama/assets/modules/write-drama-video-prompts/prompts/seedance2_video.zh.txt` 与 `.en.txt`;本文件只规定编译前的判断、素材用途、动作、镜头、表演、声音、连续性和返工顺序。类型决策、描述维度和质量分级见 [通用提示词规范](prompt-craft.md)。模型参数、素材上限和输入模式以实时 Provider schema 为准,模板与实时能力冲突时先修正路由。
4
4
 
5
5
  ## 先定本镜任务
6
6