Skip to content

Formerly KrillinAI, VideoTranslation and Dubbing Tool for 120+ Languages. Open-source AI workspace for creators, powered by Codex. Video downloader, video translation, create videos, images, audios, and edits with Agents in one place. For your Social Media like YouTube, TikTok, Instagram, etc.

feat(creator): add preflight checks before stage execution

MijaelXca198d7e8e71
diff --git a/apps/daemon/src/api/routes.creator.ts b/apps/daemon/src/api/routes.creator.ts
index 39986be2..0725c978 100644
--- a/apps/daemon/src/api/routes.creator.ts
+++ b/apps/daemon/src/api/routes.creator.ts
@@ -46,6 +46,7 @@ import {
} from '../creator/templates/video-translation-actions.js';
import type { CreatorProjectCoverService } from '../creator/project-cover.js';
import type { CreatorStageRunner } from '../creator/stage-runner.js';
+import { CreatorPreflightError, type CreatorPreflight } from '../creator/preflight.js';
import {
CreatorArtifactImportError,
type CreatorArtifactImportService
@@ -76,6 +77,7 @@ export async function registerCreatorRoutes(
artifactImportService?: CreatorArtifactImportService;
jobsRoot: string;
dispatcher: CreatorCommandDispatcher;
+ preflight?: Pick<CreatorPreflight, 'check'>;
stageRunner?: Pick<CreatorStageRunner, 'cancel'>;
}
): Promise<void> {
@@ -195,6 +197,24 @@ export async function registerCreatorRoutes(
}))
}));
+ server.get<{ Params: { id: string }; Querystring: { stageId?: string } }>(
+ '/creator/jobs/:id/preflight',
+ async (request, reply) => {
+ try {
+ const job = requireCreatorJob(service, request.params.id);
+ if (options.preflight === undefined) {
+ return reply.code(503).send(apiError('creator_preflight_unavailable' as RuntimeErrorCode, 'Creator preflight is unavailable'));
+ }
+ const stageId = readString(request.query.stageId, 'stageId');
+ const stage = service.templates.get(job.templateId, job.templateVersion).stages.find(candidate => candidate.id === stageId);
+ if (stage === undefined) throw new CreatorServiceError('creator_stage_not_found', 'Creator stage was not found');
+ return options.preflight.check(job, stage);
+ } catch (error) {
+ return sendCreatorError(reply, error);
+ }
+ }
+ );
+
server.post<{ Body: unknown }>('/creator/jobs', async (request, reply) => {
try {
const body = readObject(request.body);
@@ -339,6 +359,12 @@ export async function registerCreatorRoutes(
'Creator job has no canceled or interrupted stage to resume'
);
}
+ if (options.preflight !== undefined) {
+ const stage = service.templates.get(job.templateId, job.templateVersion).stages.find(candidate => candidate.id === latest.stageId);
+ if (stage === undefined) throw new CreatorServiceError('creator_stage_not_found', 'Creator stage was not found');
+ const preflight = await options.preflight.check(job, stage);
+ if (!preflight.canStart) throw new CreatorPreflightError(preflight);
+ }
if (job.templateId === 'video-translation' && options.videoTranslationWorkflow !== undefined) {
try {
await options.videoTranslationWorkflow.validateStage(job, latest.stageId);
@@ -485,6 +511,18 @@ export async function registerCreatorRoutes(
payload: { revision: latest.revision }
});
}
+ if (
+ options.preflight !== undefined
+ && error instanceof VideoTranslationWorkflowError
+ && (error.code === 'creator_llm_config_missing' || error.code === 'creator_tts_config_missing')
+ ) {
+ const stageId = readString(actionInput.stageId, 'stageId');
+ const stage = service.templates.get(jobBeforeAction.templateId, jobBeforeAction.templateVersion).stages.find(candidate => candidate.id === stageId);
+ if (stage !== undefined) {
+ const preflight = await options.preflight.check(jobBeforeAction, stage);
+ if (!preflight.canStart) throw new CreatorPreflightError(preflight);
+ }
+ }
throw error;
}
}
@@ -510,6 +548,13 @@ export async function registerCreatorRoutes(
throw error;
}
}
+ if (action === 'run-stage' && options.preflight !== undefined) {
+ const stageId = readString(actionInput.stageId, 'stageId');
+ const stage = service.templates.get(jobBeforeAction.templateId, jobBeforeAction.templateVersion).stages.find(candidate => candidate.id === stageId);
+ if (stage === undefined) throw new CreatorServiceError('creator_stage_not_found', 'Creator stage was not found');
+ const preflight = await options.preflight.check(jobBeforeAction, stage);
+ if (!preflight.canStart) throw new CreatorPreflightError(preflight);
+ }
const expectedRevision = readInteger(body.expectedRevision, 'expectedRevision');
const result = options.dispatcher.dispatch(id, {
idempotencyKey: typeof body.idempotencyKey === 'string'
diff --git a/apps/daemon/src/api/server.ts b/apps/daemon/src/api/server.ts
index bae31f6b..ba1d7be2 100644
--- a/apps/daemon/src/api/server.ts
+++ b/apps/daemon/src/api/server.ts
@@ -69,6 +69,7 @@ import {
type CreatorSourceUploadService
} from '../creator/source-upload.js';
import { createCreatorArtifactImportService } from '../creator/artifact-import.js';
+import { createCreatorPreflight } from '../creator/preflight.js';
import { validateMediaFile, type MediaProbe } from '../creator/validators/media.js';
import {
createCoverWorkflow,
@@ -510,6 +511,7 @@ export async function buildServer(input: BuildServerInput) {
let creatorFfmpegPath: string | undefined;
let creatorFfprobePath: string | undefined;
let creatorYtDlpUpdateManager = input.creatorYtDlpUpdateManager;
+ let getYtDlpRuntime: (() => ReturnType<typeof resolveYtDlpRuntime>) | undefined;
try {
const runtimeManifest = readKrillinRuntimeManifest(creatorRuntimeRoot);
verifyKrillinRuntimeManifest(creatorRuntimeRoot, runtimeManifest);
@@ -545,7 +547,7 @@ export async function buildServer(input: BuildServerInput) {
console.warn(`yt-dlp updater is unavailable: ${formatError(error)}`);
}
}
- const getYtDlpRuntime = () =>
+ getYtDlpRuntime = () =>
creatorYtDlpUpdateManager?.getRuntime() ?? ytDlp;
if (input.creatorExecutors === undefined) {
creatorExecutors.push(createKrillinExecutor({
@@ -567,7 +569,7 @@ export async function buildServer(input: BuildServerInput) {
ytDlpPath: ytDlp.executable,
ytDlpPrefixArgs: ytDlp.prefixArgs,
ytDlpEnv: ytDlp.env,
- getYtDlpRuntime: () => getYtDlpRuntime()!,
+ getYtDlpRuntime: () => getYtDlpRuntime!()!,
ffmpegPath: creatorFfmpegPath,
ffprobePath: creatorFfprobePath
}));
@@ -578,7 +580,7 @@ export async function buildServer(input: BuildServerInput) {
ytDlpPath: ytDlp.executable,
ytDlpPrefixArgs: ytDlp.prefixArgs,
ytDlpEnv: ytDlp.env,
- getYtDlpRuntime: () => getYtDlpRuntime()!
+ getYtDlpRuntime: () => getYtDlpRuntime!()!
}));
}
if (input.creatorExecutors === undefined && creatorFfmpegPath && creatorFfprobePath) {
@@ -611,6 +613,17 @@ export async function buildServer(input: BuildServerInput) {
}));
}
}
+ const creatorPreflight = createCreatorPreflight({
+ configStore: creatorServicesConfigStore,
+ readCapabilities: () => krillinDependencyLoader.capabilities(),
+ resourceRoot: creatorRuntimeRoot,
+ jobsRoot: creatorJobsRoot,
+ ffmpegPath: creatorFfmpegPath,
+ ffprobePath: creatorFfprobePath,
+ ...(getYtDlpRuntime === undefined ? {} : { getYtDlpRuntime }),
+ executorIds: creatorExecutors.map(executor => executor.id),
+ validateRuntimeAssets: input.creatorExecutors === undefined
+ });
const creatorProjectCoverService = createCreatorProjectCoverService({
jobsRoot: creatorJobsRoot,
...(creatorFfmpegPath === undefined ? {} : { ffmpegPath: creatorFfmpegPath })
@@ -787,6 +800,7 @@ export async function buildServer(input: BuildServerInput) {
threads: threadManager,
contextBuilder: creatorAgentContextBuilder,
runtime: creatorAgentRuntime,
+ preflight: creatorPreflight,
onEvent(event) {
const job = creatorService.getJob(event.jobId);
if (job === undefined) return;
@@ -1023,6 +1037,7 @@ export async function buildServer(input: BuildServerInput) {
sourceUploadService: creatorSourceUploadService,
artifactImportService: creatorArtifactImportService,
dispatcher: creatorCommandDispatcher,
+ preflight: creatorPreflight,
stageRunner: creatorStageRunner
});
await registerAttachmentRoutes(server, attachmentService, {
diff --git a/apps/daemon/src/creator/agent/agent-service.ts b/apps/daemon/src/creator/agent/agent-service.ts
index 615681ce..cc45e8a9 100644
--- a/apps/daemon/src/creator/agent/agent-service.ts
+++ b/apps/daemon/src/creator/agent/agent-service.ts
@@ -21,6 +21,7 @@ import {
import { CreatorServiceError, type CreatorService } from '../service.js';
import type { AgentContextBuilder } from './context-builder.js';
import { normalizeCreatorRuntimeEvent } from './event-normalizer.js';
+import { CreatorPreflightError, type CreatorPreflight } from '../preflight.js';
import { createCreatorAgentReconciler } from './reconciler.js';
import type { CreatorAgentRepository } from './repository.js';
import type { AgentRuntimeAdapter } from './runtime-adapter.js';
@@ -41,6 +42,7 @@ export function createCreatorAgentService(input: {
threads: Pick<ThreadManager, 'createThread' | 'getThread' | 'updateThread'>;
contextBuilder: AgentContextBuilder;
runtime: AgentRuntimeAdapter;
+ preflight?: Pick<CreatorPreflight, 'check'>;
now?(): string;
onEvent?(event: CreatorAgentEvent): void;
}) {
@@ -177,6 +179,19 @@ export function createCreatorAgentService(input: {
});
if (runtimeResult.action === undefined) break;
try {
+ if (runtimeResult.action.action === 'run-stage' && input.preflight !== undefined) {
+ const requestedStage = runtimeResult.action.input.stageId;
+ if (typeof requestedStage === 'string') {
+ const latestJob = input.creator.getJob(jobId);
+ const stage = latestJob === undefined
+ ? undefined
+ : input.creator.templates.get(latestJob.templateId, latestJob.templateVersion).stages.find(candidate => candidate.id === requestedStage);
+ if (latestJob !== undefined && stage !== undefined) {
+ const result = await input.preflight.check(latestJob, stage);
+ if (!result.canStart) throw new CreatorPreflightError(result);
+ }
+ }
+ }
const dispatched = input.dispatcher.dispatch(jobId, {
...runtimeResult.action,
idempotencyKey: `${assistantTurn.id}:action:${conflictAttempt}`
diff --git a/apps/daemon/src/creator/preflight.ts b/apps/daemon/src/creator/preflight.ts
new file mode 100644
index 00000000..fc51ae60
--- /dev/null
+++ b/apps/daemon/src/creator/preflight.ts
@@ -0,0 +1,313 @@
+import type {
+ CreatorJob,
+ CreatorPreflightCheck,
+ CreatorPreflightExecutionMode,
+ CreatorPreflightResponse,
+ CreatorServicesCapabilitiesResponse,
+ CreatorServicesConfig
+} from '@opencreator/protocol';
+import { access, mkdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import type { CreatorTemplateStage } from './templates/types.js';
+import type { CreatorServicesConfigStore } from '../creator-services/config-store.js';
+import { preflightKrillinDependencies } from './krillin/dependency-preflight.js';
+import type { YtDlpRuntime } from './yt-dlp/runtime.js';
+import { supportsReferenceImage } from './templates/cover-actions.js';
+
+export type CreatorPreflight = ReturnType<typeof createCreatorPreflight>;
+
+export class CreatorPreflightError extends Error {
+ constructor(readonly result: CreatorPreflightResponse) {
+ super('Creator preflight blocked this stage');
+ this.name = 'CreatorPreflightError';
+ }
+
+ get code(): string {
+ const ids = new Set(this.result.blocked.map(item => item.id));
+ const id = ids.has('llm') ? 'llm'
+ : ids.has('tts') ? 'tts'
+ : ids.has('image-provider') ? 'image-provider'
+ : ids.has('video-provider') ? 'video-provider'
+ : ids.has('reference-image-capability') ? 'reference-image-capability'
+ : this.result.blocked[0]?.id;
+ if (id === 'llm') return 'creator_llm_config_missing';
+ if (id === 'tts') return 'creator_tts_config_missing';
+ if (id === 'image-provider') return 'creator_image_config_missing';
+ if (id === 'video-provider') return 'VIDEO_GENERATION_CONFIG_REQUIRED';
+ if (id === 'reference-image-capability') return 'unsupported_capability';
+ return 'creator_preflight_blocked';
+ }
+}
+
+export function createCreatorPreflight(input: {
+ configStore: Pick<CreatorServicesConfigStore, 'read'>;
+ readCapabilities(): CreatorServicesCapabilitiesResponse;
+ resourceRoot: string;
+ jobsRoot: string;
+ ffmpegPath?: string;
+ ffprobePath?: string;
+ getYtDlpRuntime?(): YtDlpRuntime | undefined;
+ executorIds?: Iterable<string>;
+ validateRuntimeAssets?: boolean;
+}) {
+ const executorIds = new Set(input.executorIds ?? []);
+
+ async function check(job: CreatorJob, stage: CreatorTemplateStage): Promise<CreatorPreflightResponse> {
+ const ready: CreatorPreflightCheck[] = [];
+ const warning: CreatorPreflightCheck[] = [];
+ const blocked: Array<CreatorPreflightCheck & { repair: NonNullable<CreatorPreflightCheck['repair']> }> = [];
+ const mode = executionMode(stage, job);
+ const add = (
+ status: 'ready' | 'warning' | 'blocked',
+ item: Omit<CreatorPreflightCheck, 'executionMode'> & { executionMode?: CreatorPreflightExecutionMode },
+ repair?: CreatorPreflightCheck['repair']
+ ) => {
+ const value = { ...item, executionMode: item.executionMode ?? mode };
+ if (status === 'ready') ready.push(value);
+ else if (status === 'warning') warning.push(value);
+ else blocked.push({ ...value, repair: repair ?? { label: '打开设置', deepLink: '#/settings?tab=diagnostics' } });
+ };
+
+ if (executorIds.size > 0 && !executorIds.has(stage.executor)) {
+ add('blocked', {
+ id: 'executor',
+ title: '执行器不可用',
+ message: `当前 Runtime 未加载 ${stage.executor} 执行器。`,
+ executionMode: mode
+ }, { label: '打开诊断', deepLink: '#/settings?tab=diagnostics' });
+ } else {
+ add('ready', { id: 'executor', title: '执行器', message: `${stage.executor} 已加载`, executionMode: mode });
+ }
+
+ const config = await input.configStore.read();
+ checkProviderConfig(job, stage, config, input.readCapabilities(), add);
+ await checkInputs(job, stage, add);
+ await checkRuntimeDependencies(job, stage, config, add);
+ await checkManagedDirectory(add);
+
+ return {
+ templateId: job.templateId,
+ templateVersion: job.templateVersion,
+ stageId: stage.id,
+ executionMode: mode,
+ canStart: blocked.length === 0,
+ ready,
+ warning,
+ blocked,
+ checkedAt: new Date().toISOString()
+ };
+ }
+
+ return { check };
+
+ async function checkManagedDirectory(
+ add: (status: 'ready' | 'warning' | 'blocked', item: Omit<CreatorPreflightCheck, 'executionMode'> & { executionMode?: CreatorPreflightExecutionMode }, repair?: CreatorPreflightCheck['repair']) => void
+ ) {
+ try {
+ await mkdir(input.jobsRoot, { recursive: true });
+ await access(input.jobsRoot, constants.W_OK);
+ add('ready', { id: 'managed-directory', title: '受管目录', message: '任务目录可写。', executionMode: 'local' });
+ } catch {
+ add('blocked', {
+ id: 'managed-directory',
+ title: '受管目录不可写',
+ message: 'OpenCreator 无法写入任务目录,无法安全保存 Artifact。',
+ executionMode: 'local'
+ }, { label: '打开诊断', deepLink: '#/settings?tab=diagnostics' });
+ }
+ }
+
+ async function checkRuntimeDependencies(
+ job: CreatorJob,
+ stage: CreatorTemplateStage,
+ config: CreatorServicesConfig,
+ add: (status: 'ready' | 'warning' | 'blocked', item: Omit<CreatorPreflightCheck, 'executionMode'> & { executionMode?: CreatorPreflightExecutionMode }, repair?: CreatorPreflightCheck['repair']) => void
+ ) {
+ const needsMediaTools = input.validateRuntimeAssets !== false
+ && (['download', 'clip', 'stickman'].includes(stage.executor) || stage.executor === 'krillinai');
+ if (needsMediaTools) {
+ for (const [id, path, label] of [
+ ['ffmpeg', input.ffmpegPath, 'FFmpeg'],
+ ['ffprobe', input.ffprobePath, 'ffprobe']
+ ] as const) {
+ if (path === undefined) add('blocked', {
+ id,
+ title: `${label} 不可用`,
+ message: `当前 Runtime 未找到 ${label},该阶段无法执行。`,
+ executionMode: 'local'
+ }, { label: '打开运行组件设置', deepLink: '#/settings?tab=local-components' });
+ else add('ready', { id, title: label, message: `${label} 已就绪。`, executionMode: 'local' });
+ }
+ }
+ if (input.validateRuntimeAssets !== false && (stage.executor === 'download' || (stage.executor === 'krillinai' && job.state.sourceType !== 'file'))) {
+ let runtime: YtDlpRuntime | undefined;
+ try { runtime = input.getYtDlpRuntime?.(); } catch { runtime = undefined; }
+ if (runtime === undefined) add('blocked', {
+ id: 'yt-dlp',
+ title: 'yt-dlp 不可用',
+ message: '当前 Runtime 未找到 yt-dlp,无法处理远程媒体。',
+ executionMode: 'local'
+ }, { label: '打开运行组件设置', deepLink: '#/settings?tab=local-components' });
+ else add('ready', { id: 'yt-dlp', title: 'yt-dlp', message: `已就绪(${runtime.version})。`, executionMode: 'local' });
+ }
+ if (input.validateRuntimeAssets !== false && stage.executor === 'krillinai') {
+ try {
+ preflightKrillinDependencies(input.resourceRoot, config);
+ add('ready', { id: 'krillin-runtime', title: 'KrillinAI Runtime', message: '运行资源校验通过。', executionMode: 'local' });
+ } catch (error) {
+ add('blocked', {
+ id: 'krillin-runtime',
+ title: 'KrillinAI Runtime 不完整',
+ message: error instanceof Error ? error.message : 'KrillinAI 运行资源校验失败。',
+ executionMode: 'local'
+ }, { label: '打开运行组件设置', deepLink: '#/settings?tab=local-components' });
+ }
+ }
+ if (stage.executor === 'krillinai' && (job.state.sourceType === 'file' || job.state.preferPlatformCaptions === false) && ['whisper.cpp', 'whisperkit', 'faster-whisper'].includes(config.transcription.provider)) {
+ const provider = input.readCapabilities().transcription.providers.find(candidate => candidate.provider === config.transcription.provider);
+ if (provider?.available !== true) add('blocked', {
+ id: 'transcription-capability',
+ title: '语音识别能力不可用',
+ message: `${config.transcription.provider} 在当前 Runtime 不可用。`,
+ executionMode: 'local'
+ }, { label: '打开 AI 服务设置', deepLink: '#/settings?tab=ai-services&section=transcription' });
+ }
+ }
+}
+
+function checkProviderConfig(
+ job: CreatorJob,
+ stage: CreatorTemplateStage,
+ config: CreatorServicesConfig,
+ capabilities: CreatorServicesCapabilitiesResponse,
+ add: (status: 'ready' | 'warning' | 'blocked', item: Omit<CreatorPreflightCheck, 'executionMode'> & { executionMode?: CreatorPreflightExecutionMode }, repair?: CreatorPreflightCheck['repair']) => void
+): void {
+ const needs = new Set<string>();
+ if (stage.executor === 'krillinai') {
+ if (stage.id === 'subtitle') needs.add('llm');
+ if (stage.id === 'tts' && job.state.dubbing === true) needs.add('tts');
+ }
+ if (stage.executor === 'clip' || stage.executor === 'stickman') needs.add('llm');
+ if (stage.executor === 'image') {
+ needs.add('image');
+ if (stage.id === 'analyze-source') needs.add('llm');
+ }
+ if (stage.executor === 'video') needs.add('video');
+ if (stage.executor === 'smart-dubbing') needs.add('tts');
+ if (stage.executor === 'stickman' && stage.id === 'narration') needs.add('tts');
+
+ if (needs.has('llm')) checkOpenAi(config.llm, 'llm', '文本模型', '#/settings?tab=ai-services&section=text', add);
+ if (needs.has('tts')) {
+ const provider = readTtsProvider(job, config);
+ if (provider === 'edge-tts') add('ready', { id: 'tts', title: '配音服务', message: 'Edge TTS 不需要 API Key。', executionMode: 'remote' });
+ else checkTts(config, provider, add);
+ }
+ if (needs.has('image')) {
+ const provider = readImageProvider(job, config);
+ const settings = config.image[provider];
+ const hasKey = providerCredentials(settings, provider);
+ if (!hasKey || !settings.model.trim() || !settings.baseUrl.trim()) add('blocked', {
+ id: 'image-provider', title: '图像服务配置不完整', message: `请配置 ${provider} 的 Base URL、模型和凭据。`, executionMode: 'remote'
+ }, { label: '打开 AI 服务设置', deepLink: '#/settings?tab=ai-services&section=image' });
+ else add('ready', { id: 'image-provider', title: '图像服务', message: `${provider} / ${settings.model} 已配置。`, executionMode: 'remote' });
+ const hasReference = stage.inputArtifacts.some(item => item.kind === 'reference_image')
+ && typeof job.state.referenceImageArtifactId === 'string';
+ if (hasReference && !supportsReferenceImage(provider)) add('blocked', {
+ id: 'reference-image-capability', title: '参考图能力不匹配', message: `${provider} 不支持当前阶段的参考图编辑。`, executionMode: 'remote'
+ }, { label: '选择支持参考图的服务', deepLink: '#/settings?tab=ai-services&section=image' });
+ }
+ if (needs.has('video')) {
+ const provider = readVideoProvider(job, config);
+ const settings = config.video[provider];
+ const hasKey = providerCredentials(settings, provider);
+ if (!hasKey || !settings.model.trim() || !settings.baseUrl.trim()) add('blocked', {
+ id: 'video-provider', title: '视频服务配置不完整', message: `请配置 ${provider} 的 Base URL、模型和凭据。`, executionMode: 'remote'
+ }, { label: '打开 AI 服务设置', deepLink: '#/settings?tab=ai-services&section=video' });
+ else add('ready', { id: 'video-provider', title: '视频服务', message: `${provider} / ${settings.model} 已配置。`, executionMode: 'remote' });
+ }
+ if (stage.executor === 'krillinai' && stage.id === 'subtitle' && (job.state.sourceType === 'file' || job.state.preferPlatformCaptions === false)) {
+ const provider = capabilities.transcription.providers.find(candidate => candidate.provider === config.transcription.provider);
+ if (provider?.available !== true) return;
+ if (config.transcription.provider === 'openai' && !config.transcription.openai.apiKey.trim()) {
+ checkOpenAi(config.transcription.openai, 'transcription', '语音识别', '#/settings?tab=ai-services&section=transcription', add);
+ } else if (config.transcription.provider === 'aliyun' && (!config.transcription.aliyun.speech.accessKeyId.trim() || !config.transcription.aliyun.speech.accessKeySecret.trim() || !config.transcription.aliyun.speech.appKey.trim())) {
+ add('blocked', { id: 'transcription-config', title: '语音识别凭据缺失', message: '请补全阿里云语音识别凭据。', executionMode: 'remote' }, { label: '打开 AI 服务设置', deepLink: '#/settings?tab=ai-services&section=transcription' });
+ } else add('ready', { id: 'transcription-config', title: '语音识别', message: `${config.transcription.provider} 已配置。`, executionMode: provider.kind === 'local' ? 'local' : 'remote' });
+ }
+}
+
+function checkOpenAi(
+ value: { baseUrl: string; apiKey: string; model: string },
+ id: string,
+ title: string,
+ deepLink: string,
+ add: Parameters<typeof checkProviderConfig>[4]
+) {
+ if (!value.baseUrl.trim() || !value.model.trim() || !value.apiKey.trim()) add('blocked', { id, title: `${title}配置不完整`, message: `请补全 ${title} 的 Base URL、模型和 API Key。`, executionMode: 'remote' }, { label: '打开 AI 服务设置', deepLink });
+ else add('ready', { id, title, message: `${value.model} 已配置。`, executionMode: 'remote' });
+}
+
+function checkTts(config: CreatorServicesConfig, provider: Exclude<CreatorServicesConfig['tts']['provider'], 'edge-tts'>, add: Parameters<typeof checkProviderConfig>[4]) {
+ const value = config.tts[provider];
+ if (!value.baseUrl.trim() || !value.model.trim() || !value.apiKey.trim()) add('blocked', { id: 'tts', title: '配音服务配置不完整', message: `请补全 ${provider} 的 Base URL、模型和 API Key。`, executionMode: 'remote' }, { label: '打开 AI 服务设置', deepLink: '#/settings?tab=ai-services&section=tts' });
+ else add('ready', { id: 'tts', title: '配音服务', message: `${provider} / ${value.model} 已配置。`, executionMode: 'remote' });
+}
+
+async function checkInputs(job: CreatorJob, stage: CreatorTemplateStage, add: Parameters<typeof checkProviderConfig>[4]): Promise<void> {
+ if (job.state.sourceType === 'file' && stage.executor === 'krillinai' && typeof job.state.sourceArtifactId !== 'string') {
+ add('blocked', { id: 'input-file', title: '输入文件缺失', message: '请选择要处理的本地视频文件。', executionMode: 'local' }, { label: '选择输入文件', deepLink: '#/settings?tab=diagnostics' });
+ return;
+ }
+ const paths = stage.inputArtifacts.filter(item => item.selector === 'state-artifact-id').map(item => job.state[item.stateKey ?? '']);
+ if (job.state.sourceType === 'file' && stage.executor === 'krillinai') paths.push(job.state.sourceArtifactId);
+ for (const input of stage.inputArtifacts.filter(item => !item.optional && item.selector === 'latest-completed')) {
+ const artifact = [...job.artifacts].reverse().find(candidate => candidate.kind === input.kind && candidate.status === 'completed');
+ if (artifact === undefined) {
+ add('blocked', { id: `input-artifact:${input.kind}`, title: '前置产物缺失', message: `请先生成 ${input.kind},再启动 ${stage.id}。`, executionMode: 'local' }, { label: '返回上一步', deepLink: '#/settings?tab=diagnostics' });
+ }
+ }
+ for (const value of paths) {
+ if (typeof value !== 'string') continue;
+ const artifact = job.artifacts.find(candidate => candidate.id === value && candidate.status === 'completed');
+ if (artifact?.path === null || artifact === undefined) {
+ add('blocked', { id: 'input-file', title: '输入文件不可用', message: '所选输入文件不存在或不可读。', executionMode: 'local' }, { label: '重新选择输入文件', deepLink: '#/settings?tab=diagnostics' });
+ continue;
+ }
+ try {
+ await access(artifact.path, constants.R_OK);
+ add('ready', { id: `input-file:${artifact.id}`, title: '输入文件', message: '输入文件存在且可读。', executionMode: 'local' });
+ } catch {
+ add('blocked', { id: 'input-file', title: '输入文件不可读', message: '所选输入文件不存在或不可读。', executionMode: 'local' }, { label: '重新选择输入文件', deepLink: '#/settings?tab=diagnostics' });
+ }
+ }
+}
+
+function readTtsProvider(job: CreatorJob, config: CreatorServicesConfig): CreatorServicesConfig['tts']['provider'] {
+ const value = job.state.ttsProvider;
+ return value === 'openai' || value === 'aliyun' || value === 'edge-tts' || value === 'minimax' ? value : config.tts.provider;
+}
+function readImageProvider(job: CreatorJob, config: CreatorServicesConfig): CreatorServicesConfig['image']['provider'] {
+ const value = job.state.provider;
+ return value === 'openai' || value === 'jimeng' || value === 'kling' || value === 'gemini' ? value : config.image.provider;
+}
+function readVideoProvider(job: CreatorJob, config: CreatorServicesConfig): CreatorServicesConfig['video']['provider'] {
+ const value = job.state.provider;
+ return value === 'seedance' || value === 'kling' || value === 'veo' ? value : config.video.provider;
+}
+function executionMode(stage: CreatorTemplateStage, job: CreatorJob): CreatorPreflightExecutionMode {
+ if (stage.executor === 'image' || stage.executor === 'video' || stage.executor === 'smart-dubbing') return 'remote';
+ if (stage.executor === 'krillinai' && job.state.sourceType !== 'file') return 'mixed';
+ return 'local';
+}
+
+function providerCredentials(
+ settings: { model: string; apiKey?: string; accessKey?: string; secretKey?: string },
+ provider: 'openai' | 'jimeng' | 'kling' | 'gemini' | 'seedance' | 'veo'
+): boolean {
+ if (provider === 'kling') {
+ return (settings.accessKey?.trim().length ?? 0) > 0
+ && (settings.secretKey?.trim().length ?? 0) > 0;
+ }
+ return (settings.apiKey?.trim().length ?? 0) > 0;
+}
diff --git a/apps/daemon/test/integration/creator-api.test.ts b/apps/daemon/test/integration/creator-api.test.ts
index eede5904..677c923b 100644
--- a/apps/daemon/test/integration/creator-api.test.ts
+++ b/apps/daemon/test/integration/creator-api.test.ts
@@ -365,11 +365,11 @@ describe('creator api', () => {
expectedRevision: 1,
input: { stageId: 'subtitle' }
});
- expect(started.statusCode).toBe(200);
- expect(started.json().job.artifacts).toContainEqual(expect.objectContaining({
- kind: 'source_video',
- status: 'completed'
- }));
+ expect(started.statusCode).toBe(400);
+ expect(started.json()).toMatchObject({
+ error: { preflight: { canStart: false } }
+ });
+ expect((await request('GET', `/creator/jobs/${job.id}`)).json().job.stages).toEqual([]);
});
it('starts subtitles without requiring TTS configuration up front', async () => {
@@ -391,16 +391,11 @@ describe('creator api', () => {
expectedRevision: 0,
input: { stageId: 'subtitle' }
});
- expect(started.statusCode).toBe(200);
+ expect(started.statusCode).toBe(400);
expect(started.json()).toMatchObject({
- commandReceipt: {
- stageRunId: expect.any(String)
- },
- job: {
- revision: 1,
- status: 'running'
- }
+ error: { preflight: { canStart: false } }
});
+ expect((await request('GET', `/creator/jobs/${job.id}`)).json().job.stages).toEqual([]);
});
it('requires text translation configuration before starting subtitles', async () => {
@@ -416,6 +411,18 @@ describe('creator api', () => {
});
const job = created.json().job;
+ const preflight = await request('GET', `/creator/jobs/${job.id}/preflight?stageId=subtitle`);
+ expect(preflight.statusCode).toBe(200);
+ expect(preflight.json()).toMatchObject({
+ canStart: false,
+ blocked: expect.arrayContaining([expect.objectContaining({
+ id: 'llm',
+ repair: expect.objectContaining({
+ deepLink: '#/settings?tab=ai-services&section=text'
+ })
+ })])
+ });
+
const started = await request('POST', `/creator/jobs/${job.id}/actions`, {
action: 'run-stage',
expectedRevision: 0,
@@ -424,8 +431,12 @@ describe('creator api', () => {
expect(started.statusCode).toBe(400);
expect(started.json()).toMatchObject({
- error: { code: 'creator_llm_config_missing' }
+ error: {
+ code: 'creator_llm_config_missing',
+ preflight: { canStart: false }
+ }
});
+ expect((await request('GET', `/creator/jobs/${job.id}`)).json().job.stages).toEqual([]);
});
it('returns the persisted Agent timeline and resolves approvals by generation', async () => {
@@ -599,6 +610,7 @@ async function setupServer(options: {
tempDir = mkdtempSync(join(tmpdir(), 'creator-api-'));
const config = createDefaultCreatorServicesConfig();
if (options.llmConfigured !== false) {
+ config.llm.baseUrl = 'https://api.openai.com/v1';
config.llm.apiKey = 'test-llm-key';
config.llm.source = 'custom';
}
diff --git a/apps/daemon/test/unit/creator-preflight.test.ts b/apps/daemon/test/unit/creator-preflight.test.ts
new file mode 100644
index 00000000..21493dc9
--- /dev/null
+++ b/apps/daemon/test/unit/creator-preflight.test.ts
@@ -0,0 +1,110 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createDefaultCreatorServicesConfig, type CreatorJob, type CreatorJson } from '@opencreator/protocol';
+import { createCreatorPreflight } from '../../src/creator/preflight.js';
+import { createImageGenerationTemplate } from '../../src/creator/templates/image-generation.js';
+import { createVideoDownloadTemplate } from '../../src/creator/templates/video-download.js';
+import { createKrillinCreatorServicesCapabilities } from '../../src/creator/krillin/capabilities.js';
+
+let root = '';
+
+afterEach(async () => {
+ if (root) await rm(root, { recursive: true, force: true });
+ root = '';
+});
+
+describe('creator preflight', () => {
+ it('blocks a stage with missing provider credentials and provides a settings repair', async () => {
+ root = await mkdtemp(join(tmpdir(), 'creator-preflight-'));
+ const config = createDefaultCreatorServicesConfig();
+ const job = fakeJob('image-generation', { provider: 'openai', prompt: 'test' });
+ const result = await createCreatorPreflight({
+ configStore: { read: async () => config },
+ readCapabilities: () => createKrillinCreatorServicesCapabilities('win32', 'x64'),
+ resourceRoot: join(root, 'runtime'),
+ jobsRoot: join(root, 'jobs'),
+ executorIds: ['image']
+ }).check(job, createImageGenerationTemplate().stages[0]!);
+
+ expect(result.canStart).toBe(false);
+ expect(result.blocked).toEqual(expect.arrayContaining([
+ expect.objectContaining({
+ id: 'image-provider',
+ repair: expect.objectContaining({ deepLink: '#/settings?tab=ai-services&section=image' })
+ })
+ ]));
+ });
+
+ it('reports local dependency failures before creating a download stage', async () => {
+ root = await mkdtemp(join(tmpdir(), 'creator-preflight-'));
+ const job = fakeJob('video-download', { sourceUrl: 'https://youtu.be/example' });
+ const result = await createCreatorPreflight({
+ configStore: { read: async () => createDefaultCreatorServicesConfig() },
+ readCapabilities: () => createKrillinCreatorServicesCapabilities('win32', 'x64'),
+ resourceRoot: join(root, 'runtime'),
+ jobsRoot: join(root, 'jobs'),
+ executorIds: ['download'],
+ validateRuntimeAssets: true
+ }).check(job, createVideoDownloadTemplate().stages[0]!);
+
+ expect(result.canStart).toBe(false);
+ expect(result.blocked.map(item => item.id)).toEqual(expect.arrayContaining(['ffmpeg', 'ffprobe', 'yt-dlp']));
+ expect(result.blocked.every(item => item.repair.label.length > 0)).toBe(true);
+ });
+
+ it('blocks a reference image when the configured provider cannot edit images', async () => {
+ root = await mkdtemp(join(tmpdir(), 'creator-preflight-'));
+ const referencePath = join(root, 'reference.png');
+ await writeFile(referencePath, 'image');
+ const config = createDefaultCreatorServicesConfig();
+ config.image.jimeng.apiKey = 'test-key';
+ const job = fakeJob('image-generation', {
+ provider: 'jimeng',
+ prompt: 'test',
+ referenceImageArtifactId: 'reference-image'
+ });
+ job.artifacts.push({
+ id: 'reference-image',
+ jobId: job.id,
+ kind: 'reference_image',
+ status: 'completed',
+ version: 1,
+ path: referencePath,
+ sourceArtifactIds: [],
+ metadata: {},
+ createdAt: new Date(0).toISOString()
+ });
+
+ const result = await createCreatorPreflight({
+ configStore: { read: async () => config },
+ readCapabilities: () => createKrillinCreatorServicesCapabilities('win32', 'x64'),
+ resourceRoot: join(root, 'runtime'),
+ jobsRoot: join(root, 'jobs'),
+ executorIds: ['image']
+ }).check(job, createImageGenerationTemplate().stages[0]!);
+
+ expect(result.blocked).toEqual(expect.arrayContaining([
+ expect.objectContaining({ id: 'reference-image-capability' })
+ ]));
+ });
+});
+
+function fakeJob(templateId: string, state: Record<string, CreatorJson>): CreatorJob {
+ return {
+ id: 'job-preflight',
+ projectId: 'project-preflight',
+ templateId,
+ templateVersion: templateId === 'image-generation' ? 2 : 2,
+ status: 'draft',
+ revision: 0,
+ state,
+ agentThreadId: null,
+ stages: [],
+ artifacts: [],
+ activities: [],
+ createdAt: new Date(0).toISOString(),
+ updatedAt: new Date(0).toISOString()
+ };
+}
diff --git a/apps/web/src/features/dashboard/CreatorCollaborationPanel.test.tsx b/apps/web/src/features/dashboard/CreatorCollaborationPanel.test.tsx
index 580661ec..d12fb8ad 100644
--- a/apps/web/src/features/dashboard/CreatorCollaborationPanel.test.tsx
+++ b/apps/web/src/features/dashboard/CreatorCollaborationPanel.test.tsx
@@ -1,5 +1,6 @@
import type { CreatorJob } from '@opencreator/protocol';
-import { render, screen } from '@testing-library/react';
+import { useEffect } from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
import { describe, expect, it, vi } from 'vitest';
import { LanguageProvider } from '../../i18n/LanguageProvider.js';
import CreatorCollaborationPanel from './CreatorCollaborationPanel.js';
@@ -9,9 +10,68 @@ import {
videoDownloadPanelAdapter,
videoGenerationPanelAdapter
} from './creator-panel-adapters.js';
-import { CreatorSessionProvider } from './creator-session-store.js';
+import { CreatorSessionProvider, useCreatorSession } from './creator-session-store.js';
+
+function PreflightHarness(props: { stageId: string }) {
+ const session = useCreatorSession();
+ useEffect(() => {
+ void session.runPreflight(props.stageId).catch(() => undefined);
+ }, [props.stageId, session]);
+ return null;
+}
describe('CreatorCollaborationPanel', () => {
+ it('Browser/Desktop 使用同一份 preflight 结果,且不渲染 Desktop-only 修复入口', async () => {
+ const preflight = {
+ templateId: 'cover',
+ templateVersion: 2,
+ stageId: 'generate',
+ executionMode: 'remote' as const,
+ canStart: false,
+ ready: [],
+ warning: [],
+ blocked: [{
+ id: 'image-provider',
+ title: '图像服务配置不完整',
+ message: '请配置图像服务。',
+ executionMode: 'remote' as const,
+ repair: {
+ label: '打开 AI 服务设置',
+ deepLink: '#/settings?tab=ai-services&section=image'
+ }
+ }],
+ checkedAt: '2026-09-18T00:00:00.000Z'
+ };
+ const service = {
+ applyAction: vi.fn(),
+ runAgentTurn: vi.fn(),
+ preflight: vi.fn(async () => preflight)
+ };
+ const results: string[] = [];
+
+ for (let platform = 0; platform < 2; platform += 1) {
+ const view = render(
+ <LanguageProvider initialPreference="zh-CN">
+ <CreatorSessionProvider initialJob={coverJob()} service={service as never}>
+ <PreflightHarness stageId="generate" />
+ <CreatorCollaborationPanel
+ adapter={coverPanelAdapter}
+ stepLabel="正在生成封面"
+ contextSummary="2 个方案"
+ />
+ </CreatorSessionProvider>
+ </LanguageProvider>
+ );
+ await waitFor(() => expect(screen.getByText('请配置图像服务。')).toBeInTheDocument());
+ results.push(screen.getByRole('region', { name: '启动前体检' }).textContent ?? '');
+ expect(screen.queryByText(/Desktop-only|原生/)).not.toBeInTheDocument();
+ view.unmount();
+ }
+
+ expect(results[0]).toBe(results[1]);
+ expect(service.preflight).toHaveBeenCalledWith('cover_job', 'generate');
+ });
+
it('语义化并合并封面动态,同时显示标准 Stage 进度', () => {
const job = coverJob();
const { container } = render(
diff --git a/apps/web/src/features/dashboard/CreatorCollaborationPanel.tsx b/apps/web/src/features/dashboard/CreatorCollaborationPanel.tsx
index 5684b77f..ab3040c0 100644
--- a/apps/web/src/features/dashboard/CreatorCollaborationPanel.tsx
+++ b/apps/web/src/features/dashboard/CreatorCollaborationPanel.tsx
@@ -230,6 +230,31 @@ export default function CreatorCollaborationPanel(props: {
</span>
</div>
+ {session?.preflight !== null && session?.preflight !== undefined ? (
+ <section className="creator-collaboration-preflight" aria-label={l('启动前体检', 'Preflight check')}>
+ <strong>{l('启动前体检', 'Preflight check')}</strong>
+ <span>{session.preflight.executionMode === 'local'
+ ? l('本地服务', 'Local services')
+ : session.preflight.executionMode === 'remote'
+ ? l('远程服务', 'Remote services')
+ : l('本地 + 远程服务', 'Local + remote services')}</span>
+ {session.preflight.blocked.length > 0 ? (
+ <ul>
+ {session.preflight.blocked.map(item => (
+ <li key={item.id}>
+ <span>{item.message}</span>
+ {item.repair.deepLink === undefined ? null : (
+ <a href={item.repair.deepLink}>{item.repair.label}</a>
+ )}
+ </li>
+ ))}
+ </ul>
+ ) : (
+ <span>{l('已通过,可以启动阶段。', 'Ready to start this stage.')}</span>
+ )}
+ </section>
+ ) : null}
+
{session === null ? (
<div className="creator-collaboration-unavailable" role="alert">
<ServerOff size={16} aria-hidden="true" />
diff --git a/apps/web/src/features/dashboard/creator-session-store.tsx b/apps/web/src/features/dashboard/creator-session-store.tsx
index 1c63a569..5e931113 100644
--- a/apps/web/src/features/dashboard/creator-session-store.tsx
+++ b/apps/web/src/features/dashboard/creator-session-store.tsx
@@ -10,6 +10,7 @@ import type {
CreatorEventEnvelope,
CreatorJob,
CreatorJson,
+ CreatorPreflightResponse,
CreatorStageRun
} from '@opencreator/protocol';
import {
@@ -30,6 +31,8 @@ type CreatorSessionContextValue = {
state: Record<string, CreatorJson>;
conflictedFields: string[];
error: CreatorSessionError | null;
+ preflight: CreatorPreflightResponse | null;
+ runPreflight(stageId: string): Promise<CreatorPreflightResponse>;
updateDraft(
patch: Record<string, CreatorJson>,
options?: { semantic?: boolean; persist?: boolean }
@@ -63,6 +66,13 @@ export type CreatorSessionError = {
message: string;
};
+export class CreatorPreflightBlockedError extends Error {
+ constructor(readonly result: CreatorPreflightResponse) {
+ super('Creator preflight blocked this stage');
+ this.name = 'CreatorPreflightBlockedError';
+ }
+}
+
const CreatorSessionContext = createContext<CreatorSessionContextValue | null>(null);
export function CreatorSessionProvider(props: {
@@ -81,6 +91,7 @@ export function CreatorSessionProvider(props: {
| 'uploadSourceVideo'
| 'cancelJob'
| 'resumeJob'
+ | 'preflight'
| 'subscribeJobEvents'>>;
children: ReactNode;
}) {
@@ -89,6 +100,7 @@ export function CreatorSessionProvider(props: {
const [dirtyFields, setDirtyFields] = useState<Set<string>>(() => new Set());
const [conflictedFields, setConflictedFields] = useState<string[]>([]);
const [error, setError] = useState<CreatorSessionError | null>(null);
+ const [preflight, setPreflight] = useState<CreatorPreflightResponse | null>(null);
const [agentSession, setAgentSession] = useState<CreatorAgentSession | null>(null);
const [turns, setTurns] = useState<CreatorAgentTurn[]>([]);
const [items, setItems] = useState<CreatorAgentItem[]>([]);
@@ -239,6 +251,18 @@ export function CreatorSessionProvider(props: {
const clearError = useCallback(() => setError(null), []);
+ const runPreflight = useCallback(async (stageId: string) => {
+ if (props.service.preflight === undefined) {
+ throw new Error('Creator preflight is unavailable');
+ }
+ await flush();
+ await ensurePersistedJob();
+ const result = await props.service.preflight(confirmedRef.current.id, stageId);
+ setPreflight(result);
+ if (!result.canStart) throw new CreatorPreflightBlockedError(result);
+ return result;
+ }, [ensurePersistedJob, flush, props.service]);
+
const applyRemoteSnapshot = useCallback((next: CreatorJob) => {
const conflicts = [...dirtyRef.current].filter(field => (
JSON.stringify(next.state[field]) !== JSON.stringify(draftRef.current[field])
@@ -331,6 +355,10 @@ export function CreatorSessionProvider(props: {
await flush();
await ensurePersistedJob();
requestRevision = confirmedRef.current.revision;
+ if (request.action === 'run-stage' && props.service.preflight !== undefined) {
+ const stageId = request.input.stageId;
+ if (typeof stageId === 'string') await runPreflight(stageId);
+ }
const response = await props.service.applyAction(confirmedRef.current.id, {
...request,
expectedRevision: requestRevision
@@ -345,7 +373,7 @@ export function CreatorSessionProvider(props: {
}
throw cause;
}
- }, [ensurePersistedJob, flush, props.service]);
+ }, [ensurePersistedJob, flush, props.service, runPreflight]);
const uploadSourceVideo = useCallback(async (file: File) => {
if (props.service.uploadSourceVideo === undefined) {
@@ -541,6 +569,8 @@ export function CreatorSessionProvider(props: {
state: { ...confirmedJob.state, ...draft },
conflictedFields,
error,
+ preflight,
+ runPreflight,
updateDraft,
flush,
clearError,
@@ -560,7 +590,7 @@ export function CreatorSessionProvider(props: {
steerAgentTurn,
interruptAgentTurn,
respondAgentApproval
- }), [agentBusy, agentSession, applyAction, applyRemoteSnapshot, approvals, cancelJob, clearError, confirmedJob, conflictedFields, draft, error, flush, interruptAgentTurn, items, openArtifact, respondAgentApproval, resumeJob, runAgentTurn, steerAgentTurn, turns, updateDraft, uploadReferenceImage, uploadSourceVideo]);
+ }), [agentBusy, agentSession, applyAction, applyRemoteSnapshot, approvals, cancelJob, clearError, confirmedJob, conflictedFields, draft, error, flush, interruptAgentTurn, items, openArtifact, preflight, respondAgentApproval, resumeJob, runAgentTurn, runPreflight, steerAgentTurn, turns, updateDraft, uploadReferenceImage, uploadSourceVideo]);
return (
<CreatorSessionContext.Provider value={value}>
diff --git a/apps/web/src/services/creator-service.ts b/apps/web/src/services/creator-service.ts
index 04ca2ca7..d20761e2 100644
--- a/apps/web/src/services/creator-service.ts
+++ b/apps/web/src/services/creator-service.ts
@@ -14,6 +14,7 @@ import type {
CreatorEventEnvelope,
CreatorJob,
CreatorJobListResponse,
+ CreatorPreflightResponse,
CreatorStageRun,
CreatorSourceUploadResponse,
CreatorTemplateListResponse
@@ -56,6 +57,9 @@ export function createCreatorService(client: ClientLike) {
getJob(jobId: string): Promise<{ job: CreatorJob }> {
return client.get(`/creator/jobs/${encodeURIComponent(jobId)}`) as Promise<{ job: CreatorJob }>;
},
+ preflight(jobId: string, stageId: string): Promise<CreatorPreflightResponse> {
+ return client.get(`/creator/jobs/${encodeURIComponent(jobId)}/preflight?stageId=${encodeURIComponent(stageId)}`) as Promise<CreatorPreflightResponse>;
+ },
deleteJob(jobId: string, options: { deleteFiles?: boolean } = {}): Promise<void> {
const query = options.deleteFiles === true ? '?deleteFiles=true' : '';
return client.delete(`/creator/jobs/${encodeURIComponent(jobId)}${query}`) as Promise<void>;
diff --git a/packages/protocol/src/creator-services.ts b/packages/protocol/src/creator-services.ts
index 7a2d1ef9..eb89b770 100644
--- a/packages/protocol/src/creator-services.ts
+++ b/packages/protocol/src/creator-services.ts
@@ -122,6 +122,34 @@ export type CreatorServicesCapabilitiesResponse = {
};
};
+export type CreatorPreflightExecutionMode = 'local' | 'remote' | 'mixed';
+
+export type CreatorPreflightRepair = {
+ label: string;
+ deepLink?: string;
+ capability?: string;
+};
+
+export type CreatorPreflightCheck = {
+ id: string;
+ title: string;
+ message: string;
+ executionMode: CreatorPreflightExecutionMode;
+ repair?: CreatorPreflightRepair;
+};
+
+export type CreatorPreflightResponse = {
+ templateId: string;
+ templateVersion: number;
+ stageId: string;
+ executionMode: CreatorPreflightExecutionMode;
+ canStart: boolean;
+ ready: CreatorPreflightCheck[];
+ warning: CreatorPreflightCheck[];
+ blocked: Array<CreatorPreflightCheck & { repair: CreatorPreflightRepair }>;
+ checkedAt: string;
+};
+
export type CreatorServicesCredentialField =
| 'llm.apiKey'
| 'transcription.openai.apiKey'