@gensor/gensor-drama 0.0.0-stage → 0.1.1

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.
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "gensor",
3
+ "plugins": [{
4
+ "name": "gensor-agent",
5
+ "source": { "source": "local", "path": "./gensor-agent" },
6
+ "policy": { "installation": "AVAILABLE", "authentication": "ON_USE" },
7
+ "category": "Productivity"
8
+ }]
9
+ }
package/README.md CHANGED
@@ -1,3 +1,138 @@
1
- # Temporary Holding Version
1
+ # AI炸城 Codex 插件(正式版)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 在 Codex 对话中生成图片、视频和语音,并将结果下载到用户项目。用户在对话中提供 **API Key**,由小炸保存到本机。提交、查询、素材上传共用同一枚 Key;提交使用平台 URL,素材上传统一使用图片上传域名,查询按任务类型分流。
4
+
5
+ ## 接口约定与边界
6
+
7
+ 小炸提交以下格式的任务:
8
+
9
+ | 操作 | POST 路径 | 请求 |
10
+ |---|---|---|
11
+ | 提交 | `/api/webtask` | `TASK_API` + `taskParams: { model, basePayload }` |
12
+
13
+ 提交、查询和素材上传使用同一枚 Key;素材上传使用统一域名,查询按任务类型分流,失败不轮流尝试域名。
14
+
15
+ 生成任务请求示例:
16
+
17
+ ```http
18
+ POST /api/webtask
19
+ Authorization: Bearer <用户平台 API Key>
20
+ Content-Type: application/json
21
+ ```
22
+
23
+ ```json
24
+ {
25
+ "taskType": "TASK_API",
26
+ "taskParams": {
27
+ "model": "gpt-image-2",
28
+ "basePayload": {
29
+ "prompt": "雨夜中的未来城市",
30
+ "imageUrls": [],
31
+ "resolution": "2k",
32
+ "aspectRatio": "16:9"
33
+ }
34
+ }
35
+ }
36
+ ```
37
+
38
+ ## 一键安装(npm 发布后)
39
+
40
+ 需要 Node.js 22+、npm,以及已安装且支持 `codex plugin` 命令的 Codex CLI。
41
+
42
+ ```bash
43
+ npx -y @gensor/gensor-drama@latest
44
+ ```
45
+
46
+ 安装器会将插件及运行依赖保存到 `~/.local/share/gensor-drama`(支持 XDG_DATA_HOME),配置本机 MCP 启动路径,再通过 Codex CLI 注册市场并安装插件。不需要全局安装 MCP 服务。重复执行同一命令可更新或重装;API Key 和任务记录保持在原有配置目录。
47
+
48
+ 可指定安装目录:
49
+
50
+ ```bash
51
+ npx -y @gensor/gensor-drama@latest --install-dir /绝对路径/gensor-drama
52
+ ```
53
+
54
+ 执行 `--help` 查看用法,`--version` 查看安装器版本。安装过程只配置插件,不创建生成任务。当前源码准备了发布包,正式发布到 npm 后上述命令才可用于其他电脑。
55
+
56
+ ## 源码安装
57
+
58
+ 在 `codex-plugin` 目录执行:
59
+
60
+ ```bash
61
+ npm ci
62
+ node bin/cli.mjs
63
+ ```
64
+
65
+ 新建 Codex 对话,输入:
66
+
67
+ ```text
68
+ 配置小炸的 API Key
69
+ ```
70
+
71
+ 小炸缺少配置时会请用户直接在对话中提供 API Key,再调用 `gensor_set_api_key` 保存;不打开网页、不要求填写平台 URL。用户也可以直接说“把小炸的 API Key 更新为……”来更换凭据。Key 会进入当前对话及配置工具调用,回复和工具结果不回显 Key。
72
+
73
+ 配置保存在 `~/.config/gensor-agent/config.json`(支持 XDG_CONFIG_HOME / GENSOR_CONFIG_DIR),目录默认 700、文件 600,凭据以明文受文件权限保护。本地已保存 Key 优先,未保存时兼容 `GENSOR_API_KEY` 环境变量。保存状态不代表已在线鉴权,不会自动创建收费任务。更换 Key 会切换本地任务记录的凭据作用域。
74
+
75
+ ## 发布到 npm
76
+
77
+ 发布包名为 `@gensor/gensor-drama`,发布入口在本目录的 `package.json`。`gensor-agent/server/package.json` 保留为本地开发配置,无须单独发布。
78
+
79
+ ```bash
80
+ # 在 codex-plugin 目录
81
+ npm ci
82
+ npm ci --prefix gensor-agent/server
83
+ npm test
84
+ npm run test:package
85
+ npm pack --dry-run
86
+ npm login
87
+ npm whoami
88
+ npm publish --access public
89
+ ```
90
+
91
+ 使用有 `gensor` scope 发布权限的 npm 账号登录;如 npm 要求二次验证,按提示完成。`test:package` 会打包真实 tarball,在临时 CODEX_HOME 中用 npm exec 执行安装与重装,再验证持久 MCP 可启动;不修改当前用户的插件配置,不提交生成任务。
92
+
93
+ 发布前核对 `npm pack --dry-run` 文件清单。发布包含安装器、插件清单、skills、图标和 MCP 源码,不包含本机配置、Key、开发测试或 node_modules。后续用 `npm version patch` 等更新根包版本,再测试并发布;安装器会同步安装副本中的插件版本。每次安装保留独立运行目录,更新失败时可重新执行安装命令;旧运行目录不会自动清理。
94
+
95
+ ## 使用
96
+
97
+ ```text
98
+ 用小炸生成一张未来城市的图片,保存到当前项目。
99
+ 用小炸把 /绝对路径/reference.png 做成视频。
100
+ 继续查询之前的 小炸 任务,并把结果下载到当前项目。
101
+ ```
102
+
103
+ 插件包含两个独立 skill,均由插件的 `./skills/` 目录发现:
104
+
105
+ - **director(短剧与短片导演)**:需求梳理与选择题确认、剧本拆解、人物/场景/道具资产表、分镜、对白时间核算、独立可投喂的提示词与生成计划。已有剧本可直接拆解,无须从头访谈。
106
+ - **execute(生成执行)**:配置、素材上传、图片/视频/语音生成、任务查询与下载;现有调用名称保持兼容。
107
+
108
+ 例如:
109
+
110
+ ```text
111
+ 用短剧导演帮我把这个故事做成 60 秒短片,缺少的信息尽量让我做选择题。
112
+ 把这份剧本拆成人物、场景和分镜,先只输出提示词,不生成。
113
+ 用 drama-3.5 重写这段对话镜头,保留台词原文,检查每句话能否说完。
114
+ ```
115
+
116
+ 导演先交付制作计划,再输出每个生成单元的 prompt、时长与素材映射。仅做前期创作不需要配置 Key;用户授权生成后衔接执行 skill。`wan-3.0` 等名称为本插件模型 ID,接口时长上限不等于推荐镜头长度。原生对白需逐字验收,不能承诺仅凭提示词解决口型或台词准确度;逐字准确优先时可规划配音与口型后期,当前 MCP 可通过 `voice_clone` 生成独立配音,但没有口型修复或剪辑工具。
117
+
118
+ 语音使用 `voice_clone`:支持纯提示词或参考音色(`audioUrls` 最多 3 项、每项 10MB),可选 `speech_rate` 范围 −50 到 100。语音不使用视频的时长、画幅或分辨率参数,也不要求 `audioDurations`。例如:“用小炸生成普通话女性配音,朗读:你早就知道了,对不对?”
119
+
120
+ 工具共八个:`gensor_get_config_status`、`gensor_set_api_key`、`gensor_list_models`、`gensor_upload_media`、`gensor_create_task`、`gensor_list_tasks`、`gensor_get_task`、`gensor_download_outputs`。
121
+
122
+ 任务记录只在本地保存,不包含 Key。查询缺省立即返回;生图最多等待 5 分钟,视频和音频最多等待 20 分钟。状态支持 pending/processing/completed/failed/canceled;缺失的 `errorCode` 不会被当成任务失败。提交不自动重试,也不声称上游支持幂等键;提交结果不确定时通过本地请求编号和平台记录核对。成功得到 taskId 后,即使本地记录写入失败也会返回 ID。
123
+
124
+ 下载使用流式写入,单文件最大 512 MiB,一次下载工具总下载时间上限 50 秒(不含先查询的时间)。下载请求不携带平台 Key,支持多个结果、有限重定向、部分失败报告,不覆盖现有文件。下载失败可用原 taskId 重试,不重新收费生成。大型视频的下载时间/大小限制后续可按需求放宽,并同步调整 MCP tool_timeout。
125
+
126
+ 提交时本地记录保存 `taskKind`:image 表示生图,other 表示其他类型;旧记录也能根据已知模型名推导类型。`gensor_get_task` 和 `gensor_download_outputs` 对本机没有记录的任务要求传入 taskKind,并在首次查询后保存;不猜测类型或对两个域名分别探测。
127
+
128
+ 本地记录按 API 地址与 Key 的指纹隔离;恢复旧任务需要使用原 Key。只会列出本机记录,不能冒充平台完整任务列表。
129
+
130
+ ## 开发与验证
131
+
132
+ ```bash
133
+ cd codex-plugin/gensor-agent/server
134
+ npm ci
135
+ npm test
136
+ ```
137
+
138
+ 测试使用本机模拟 HTTP 平台与 MCP stdio client,不使用真实 Key,也不提交真实收费任务。发布前仍需使用实际平台地址、有效用户 Key 做一次真实图片和视频联调,核对平台扣费与模型参数。
package/bin/cli.mjs ADDED
@@ -0,0 +1,118 @@
1
+ #!/usr/bin/env node
2
+ import { cp, mkdir, readFile, writeFile, rm, mkdtemp, realpath } from 'node:fs/promises';
3
+ import { homedir } from 'node:os';
4
+ import path from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { spawn } from 'node:child_process';
7
+
8
+ const packageRoot = fileURLToPath(new URL('../', import.meta.url));
9
+
10
+ export function run(command, args, { cwd, env = process.env, capture = false } = {}) {
11
+ return new Promise((resolve, reject) => {
12
+ // Pass arguments directly; never interpolate paths into a shell command.
13
+ const child = spawn(command, args, { cwd, env, stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit' });
14
+ let stdout = ''; let stderr = '';
15
+ if (capture) {
16
+ child.stdout.on('data', chunk => { stdout += chunk; });
17
+ child.stderr.on('data', chunk => { stderr += chunk; });
18
+ }
19
+ child.on('error', error => reject(new Error(`无法运行 ${command}:${error.message}`)));
20
+ child.on('close', code => code === 0 ? resolve(stdout) : reject(new Error(`${command} ${args.join(' ')} 执行失败(${code})。${stderr.trim()}`)));
21
+ });
22
+ }
23
+
24
+ export function parseArgs(args) {
25
+ const options = {};
26
+ for (let i = 0; i < args.length; i++) {
27
+ if (args[i] === '--help' || args[i] === '-h') options.help = true;
28
+ else if (args[i] === '--version' || args[i] === '-v') options.version = true;
29
+ else if (args[i] === '--install-dir') {
30
+ if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error('--install-dir 需要目录路径。');
31
+ options.installDir = path.resolve(args[++i]);
32
+ } else throw new Error(`未知参数:${args[i]}。使用 --help 查看用法。`);
33
+ }
34
+ return options;
35
+ }
36
+
37
+ export async function install({ installDir, source = packageRoot, execute = run, env = process.env, log = console.log } = {}) {
38
+ if (Number(process.versions.node.split('.')[0]) < 22) throw new Error('需要 Node.js 22 或更新版本。');
39
+ const manifest = JSON.parse(await readFile(path.join(source, 'package.json'), 'utf8'));
40
+ await execute('codex', ['--version'], { capture: true, env });
41
+ await execute('codex', ['plugin', 'marketplace', 'add', '--help'], { capture: true, env });
42
+ const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
43
+ await execute(npm, ['--version'], { capture: true, env });
44
+ const root = installDir || path.join(env.XDG_DATA_HOME || path.join(homedir(), '.local', 'share'), 'gensor-drama');
45
+ await mkdir(path.join(root, 'releases'), { recursive: true });
46
+ // A unique release preserves the previous runtime, even during same-version reinstalls.
47
+ const release = await mkdtemp(path.join(root, 'releases', `${manifest.version}-`));
48
+ try {
49
+ log(`正在准备 AI炸城 ${manifest.version}…`);
50
+ await writeFile(path.join(release, 'package.json'), `${JSON.stringify(manifest, null, 2)}\n`);
51
+ for (const item of ['bin', 'gensor-agent']) {
52
+ await cp(path.join(source, item), path.join(release, item), {
53
+ recursive: true,
54
+ filter: file => !['node_modules', 'test', '.DS_Store'].includes(path.basename(file)),
55
+ });
56
+ }
57
+ await execute(npm, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false'], { cwd: release, env });
58
+ const pluginRoot = path.join(release, 'gensor-agent');
59
+ const pluginManifest = JSON.parse(await readFile(path.join(pluginRoot, '.codex-plugin', 'plugin.json'), 'utf8'));
60
+ pluginManifest.version = manifest.version;
61
+ await writeFile(path.join(pluginRoot, '.codex-plugin', 'plugin.json'), `${JSON.stringify(pluginManifest, null, 2)}\n`);
62
+ const mcp = { mcpServers: { 'gensor-agent': {
63
+ command: process.execPath,
64
+ args: [path.join(pluginRoot, 'server', 'src', 'index.mjs')],
65
+ startup_timeout_sec: 20,
66
+ tool_timeout_sec: 1260,
67
+ } } };
68
+ await writeFile(path.join(pluginRoot, '.mcp.json'), `${JSON.stringify(mcp, null, 2)}\n`);
69
+ // Publish the marketplace only after the runtime has been prepared successfully.
70
+ const marketplaceRoot = root;
71
+ const marketDir = path.join(marketplaceRoot, '.agents', 'plugins');
72
+ await mkdir(marketDir, { recursive: true });
73
+ const marketFile = path.join(marketDir, 'marketplace.json');
74
+ let previous;
75
+ try { previous = await readFile(marketFile); } catch (error) { if (error.code !== 'ENOENT') throw error; }
76
+ const marketplace = { name: 'gensor', plugins: [{ name: 'gensor-agent', source: { source: 'local', path: `./${path.relative(root, pluginRoot).split(path.sep).join('/')}` }, policy: { installation: 'AVAILABLE', authentication: 'ON_USE' }, category: 'Productivity' }] };
77
+ await writeFile(marketFile, `${JSON.stringify(marketplace, null, 2)}\n`);
78
+ try {
79
+ const markets = JSON.parse(await execute('codex', ['plugin', 'marketplace', 'list', '--json'], { capture: true, env }));
80
+ const existing = markets.marketplaces?.find(market => market.name === 'gensor');
81
+ if (existing) {
82
+ const currentRoot = await realpath(existing.root).catch(() => path.resolve(existing.root));
83
+ if (currentRoot !== await realpath(marketplaceRoot)) {
84
+ await execute('codex', ['plugin', 'marketplace', 'remove', 'gensor'], { env });
85
+ }
86
+ }
87
+ await execute('codex', ['plugin', 'marketplace', 'add', marketplaceRoot], { env });
88
+ const state = JSON.parse(await execute('codex', ['plugin', 'list', '--marketplace', 'gensor', '--json'], { capture: true, env }));
89
+ if (state.installed?.some(plugin => plugin.pluginId === 'gensor-agent@gensor')) {
90
+ await execute('codex', ['plugin', 'remove', 'gensor-agent@gensor'], { env });
91
+ }
92
+ await execute('codex', ['plugin', 'add', 'gensor-agent@gensor'], { env });
93
+ } catch (error) {
94
+ if (previous) await writeFile(marketFile, previous);
95
+ else await rm(marketFile, { force: true });
96
+ // Keep prepared files: Codex may already have cached references to them.
97
+ throw new Error(`${error.message}\n运行文件保留在 ${release};修复 Codex 配置后可重新运行安装命令。`);
98
+ }
99
+ log(`AI炸城 ${manifest.version} 安装完成。请新建 Codex 对话,输入“小炸,帮我梳理创作需求”。`);
100
+ log(`安装目录:${root}`);
101
+ return { release, marketplaceRoot };
102
+ } catch (error) {
103
+ throw error;
104
+ }
105
+ }
106
+
107
+ export async function main(args = process.argv.slice(2)) {
108
+ const options = parseArgs(args);
109
+ const manifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
110
+ if (options.help) {
111
+ console.log('AI炸城安装器\n\n用法:npx -y @gensor/gensor-drama@latest [--install-dir <目录>]\n\n需要 Node.js 22+、npm 和支持插件命令的 Codex CLI。\n重复执行可更新或重装,不修改已保存的 API Key 与任务记录。');
112
+ } else if (options.version) console.log(manifest.version);
113
+ else await install(options);
114
+ }
115
+
116
+ if (process.argv[1] && await realpath(process.argv[1]).catch(() => '') === fileURLToPath(import.meta.url)) {
117
+ main().catch(error => { console.error(`安装失败:${error.message}`); process.exitCode = 1; });
118
+ }
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "gensor-agent",
3
+ "version": "0.1.1",
4
+ "description": "AI炸城:由小炸完成导演编排及图片、视频和语音生成。",
5
+ "skills": "./skills/",
6
+ "mcpServers": "./.mcp.json",
7
+ "composerIcon": "./assets/icon.png",
8
+ "logo": "./assets/icon.png",
9
+ "interface": {
10
+ "displayName": "AI炸城",
11
+ "shortDescription": "短剧短片导演、分镜提示词与图片视频语音生成。",
12
+ "defaultPrompt": [
13
+ "用短剧导演帮我梳理创意、拆解剧本并制作可执行的视频提示词",
14
+ "使用 小炸 生成一张图片",
15
+ "配置 小炸 平台 API Key",
16
+ "查询 小炸 视频任务并下载结果"
17
+ ]
18
+ }
19
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "mcpServers": {
3
+ "gensor-agent": {
4
+ "command": "gensor-agent-mcp",
5
+ "startup_timeout_sec": 20,
6
+ "tool_timeout_sec": 1260
7
+ }
8
+ }
9
+ }
Binary file
@@ -0,0 +1,84 @@
1
+ import { readFile, stat } from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { redact } from './config.mjs';
4
+ import { normalizeTask } from './models.mjs';
5
+
6
+ export const QUERY_BASE_URLS = Object.freeze({
7
+ image: 'https://www.runninghub.ai',
8
+ other: 'https://www.runninghub.cn',
9
+ });
10
+
11
+ export class ApiError extends Error {
12
+ constructor(message, status) { super(message); this.status = status; }
13
+ }
14
+
15
+ export class PlatformApi {
16
+ constructor(config, { fetchImpl = fetch } = {}) { this.config = config; this.fetch = fetchImpl; }
17
+ async request(endpoint, { json, form, timeoutMs = 30000, signal, baseUrl = this.config.apiBaseUrl, apiKey = this.config.apiKey } = {}) {
18
+ const redactCredentials = value => redact(redact(value, apiKey), this.config.apiKey);
19
+ let response;
20
+ try {
21
+ response = await this.fetch(`${baseUrl}${endpoint}`, {
22
+ method: 'POST',
23
+ headers: { Authorization: `Bearer ${apiKey}`, ...(json ? { 'Content-Type': 'application/json' } : {}) },
24
+ body: form || JSON.stringify(json),
25
+ redirect: 'error',
26
+ signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
27
+ });
28
+ } catch (error) {
29
+ throw new ApiError(`平台请求未获得确定结果(未自动重试):${redactCredentials(error.message)}`);
30
+ }
31
+ let data;
32
+ try { data = await response.json(); }
33
+ catch { throw new ApiError(`平台返回了非 JSON 响应(HTTP ${response.status})。`, response.status); }
34
+ // Ensure a provider echo cannot copy the credential into task journals or MCP output.
35
+ const scrub = value => typeof value === 'string' ? redactCredentials(value)
36
+ : Array.isArray(value) ? value.map(scrub)
37
+ : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, item]) => [redactCredentials(key), scrub(item)]))
38
+ : value;
39
+ data = scrub(data);
40
+ if (!response.ok) throw new ApiError(`HTTP ${response.status}: ${data.errorMessage || data.msg || '平台请求失败'}`, response.status);
41
+ if (data.code !== undefined && ![0, '0', null].includes(data.code)) {
42
+ throw new ApiError(data.errorMessage || data.msg || `平台错误 ${data.code}`, response.status);
43
+ }
44
+ return data;
45
+ }
46
+ async submit(generation, signal) {
47
+ const data = await this.request(generation.endpoint, { json: generation.payload, signal });
48
+ if (typeof data.taskId !== 'string' || !data.taskId.trim()) {
49
+ throw new ApiError('平台没有返回有效 taskId,提交结果不确定;请核对平台记录,勿自动重新提交。');
50
+ }
51
+ return { taskId: data.taskId, status: 'processing' };
52
+ }
53
+ async query(taskId, taskKind, signal) {
54
+ const baseUrl = QUERY_BASE_URLS[taskKind];
55
+ if (typeof baseUrl !== 'string') throw new Error('查询需要明确任务类型:image(生图)或 other(其他任务)。');
56
+ const data = await this.request('/openapi/v2/query', {
57
+ json: { taskId }, signal, baseUrl, ...(taskKind === 'image' ? {} : { apiKey: 'bd5df121c4d343579acd0fcf1fed4d87' })
58
+ });
59
+ if (data.taskId && data.taskId !== taskId) throw new ApiError('查询结果的 taskId 与请求不一致。');
60
+ return normalizeTask(data, taskId);
61
+ }
62
+ async upload(filePath, signal) {
63
+ if (!path.isAbsolute(filePath)) throw new Error('素材路径必须是绝对路径。');
64
+ const types = {
65
+ '.png': ['image/png', 'image'], '.jpg': ['image/jpeg', 'image'], '.jpeg': ['image/jpeg', 'image'], '.webp': ['image/webp', 'image'],
66
+ '.mp4': ['video/mp4', 'video'], '.mov': ['video/quicktime', 'video'], '.webm': ['video/webm', 'video'],
67
+ '.mp3': ['audio/mpeg', 'audio'], '.wav': ['audio/wav', 'audio'], '.m4a': ['audio/mp4', 'audio'],
68
+ };
69
+ const [type, mediaType] = types[path.extname(filePath).toLowerCase()] || [];
70
+ if (!type) throw new Error('参考素材支持 PNG/JPEG/WebP 图片、MP4/MOV/WebM 视频及 MP3/WAV/M4A 音频。');
71
+ const info = await stat(filePath);
72
+ if (!info.isFile() || info.size < 1 || info.size > 30 * 1024 * 1024) throw new Error('参考素材必须是非空文件且不超过 30 MiB;voice_clone 参考音频另限每段 10MB。');
73
+ const form = new FormData();
74
+ form.append('file', new Blob([await readFile(filePath)], { type }), path.basename(filePath));
75
+ const baseUrl = QUERY_BASE_URLS['image'];
76
+ const data = await this.request('/openapi/v2/media/upload/binary', { form, timeoutMs: 60000, signal, baseUrl });
77
+ const url = data.data?.download_url;
78
+ try {
79
+ const parsed = new URL(url);
80
+ if (parsed.protocol !== 'https:' || parsed.username || parsed.password) throw new Error();
81
+ } catch { throw new ApiError('上传结果缺少有效的 HTTPS download_url。'); }
82
+ return { url, mediaType };
83
+ }
84
+ }
@@ -0,0 +1,71 @@
1
+ import { mkdir, readFile, writeFile, rename, chmod, rm } from 'node:fs/promises';
2
+ import { homedir } from 'node:os';
3
+ import path from 'node:path';
4
+ import { createHash, randomUUID } from 'node:crypto';
5
+
6
+ export const PLATFORM_BASE_URL = 'https://www.gensor.cn';
7
+
8
+ export async function writePrivateJson(file, data) {
9
+ await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
10
+ const temp = `${file}.${randomUUID()}.tmp`;
11
+ try {
12
+ await writeFile(temp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
13
+ await rename(temp, file);
14
+ await chmod(file, 0o600);
15
+ } finally { await rm(temp, { force: true }); }
16
+ }
17
+
18
+ export class ConfigStore {
19
+ constructor({ env = process.env, root } = {}) {
20
+ this.env = env;
21
+ this.root = root || env.GENSOR_CONFIG_DIR || path.join(env.XDG_CONFIG_HOME || path.join(homedir(), '.config'), 'gensor-agent');
22
+ if (!path.isAbsolute(this.root)) throw new Error('GENSOR_CONFIG_DIR 必须是绝对路径。');
23
+ this.file = path.join(this.root, 'config.json');
24
+ }
25
+ async read({ required = true } = {}) {
26
+ let saved = {};
27
+ try { saved = JSON.parse(await readFile(this.file, 'utf8')); }
28
+ catch (error) { if (error.code !== 'ENOENT') throw new Error('本地配置无法读取,请重新配置。'); }
29
+ const apiKey = saved.apiKey || this.env.GENSOR_API_KEY;
30
+ if (!apiKey) {
31
+ if (required) throw new Error('小炸尚未配置 API Key。请用户在对话中提供 Key,再调用 gensor_set_api_key 保存。');
32
+ return null;
33
+ }
34
+ return this.validate({ apiKey });
35
+ }
36
+ validate({ apiKey }) {
37
+ if (typeof apiKey !== 'string' || !apiKey.trim() || /\s/.test(apiKey) || apiKey.length > 4096) {
38
+ throw new Error('API Key 不能为空,也不能包含空白字符。');
39
+ }
40
+ return { apiKey, apiBaseUrl: PLATFORM_BASE_URL };
41
+ }
42
+ async save(value) {
43
+ const config = this.validate(value);
44
+ await writePrivateJson(this.file, config);
45
+ return this.status();
46
+ }
47
+ async hasSavedKey() {
48
+ try { return Boolean(JSON.parse(await readFile(this.file, 'utf8')).apiKey); }
49
+ catch { return false; }
50
+ }
51
+ async status() {
52
+ const config = await this.read({ required: false });
53
+ return {
54
+ configured: Boolean(config),
55
+ apiBaseUrl: PLATFORM_BASE_URL,
56
+ credentialSource: config ? ((await this.hasSavedKey()) ? 'local-file' : 'environment') : undefined,
57
+ onlineValidated: false,
58
+ note: '配置状态不代表在线鉴权成功;首次上传、提交或查询由平台验证同一枚 Key。',
59
+ };
60
+ }
61
+ }
62
+
63
+ export function scopeId(config) {
64
+ return createHash('sha256').update(`${config.apiBaseUrl}\0${config.apiKey}`).digest('hex');
65
+ }
66
+
67
+ export function redact(message, key) {
68
+ let text = String(message);
69
+ if (key) text = text.split(key).join('[REDACTED]');
70
+ return text.replace(/Bearer\s+[^\s"'<>]+/gi, 'Bearer [REDACTED]');
71
+ }
@@ -0,0 +1,78 @@
1
+ import { mkdir, open, link, unlink } from 'node:fs/promises';
2
+ import { Readable, Transform } from 'node:stream';
3
+ import { pipeline } from 'node:stream/promises';
4
+ import { randomUUID } from 'node:crypto';
5
+ import path from 'node:path';
6
+
7
+ const EXTENSIONS = {
8
+ 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif',
9
+ 'video/mp4': 'mp4', 'video/webm': 'webm', 'video/quicktime': 'mov',
10
+ 'audio/mpeg': 'mp3', 'audio/mp3': 'mp3', 'audio/wav': 'wav', 'audio/x-wav': 'wav',
11
+ 'audio/mp4': 'm4a', 'audio/x-m4a': 'm4a', 'audio/aac': 'aac', 'audio/ogg': 'ogg', 'audio/flac': 'flac',
12
+ };
13
+ function mediaUrl(value) {
14
+ const url = new URL(value);
15
+ const local = ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
16
+ if ((url.protocol !== 'https:' && !(local && url.protocol === 'http:')) || url.username || url.password) {
17
+ throw new Error('结果 URL 必须使用 HTTPS,且不能包含用户凭据。');
18
+ }
19
+ return url;
20
+ }
21
+ async function fetchMedia(value, fetchImpl, signal) {
22
+ let url = mediaUrl(value);
23
+ for (let redirects = 0; redirects <= 3; redirects++) {
24
+ // Deliberately no Authorization header on CDN requests, including redirects.
25
+ const response = await fetchImpl(url, { redirect: 'manual', signal });
26
+ if ([301, 302, 303, 307, 308].includes(response.status)) {
27
+ await response.body?.cancel();
28
+ if (!response.headers.get('location')) throw new Error('下载重定向缺少地址。');
29
+ url = mediaUrl(new URL(response.headers.get('location'), url).toString());
30
+ continue;
31
+ }
32
+ if (!response.ok || !response.body) throw new Error(`结果下载失败(HTTP ${response.status})。`);
33
+ return { response, url };
34
+ }
35
+ throw new Error('结果下载重定向次数过多。');
36
+ }
37
+
38
+ export async function downloadResults(results, { taskId, outputDir, signal, fetchImpl = fetch, maxBytes = 512 * 1024 * 1024 }) {
39
+ if (!path.isAbsolute(outputDir)) throw new Error('下载目录必须是用户项目中的绝对路径。');
40
+ if (!Array.isArray(results) || !results.length) throw new Error('任务完成但未返回结果文件,请稍后查询或检查平台任务。');
41
+ await mkdir(outputDir, { recursive: true });
42
+ const files = [];
43
+ const totalTimeout = AbortSignal.timeout(50000);
44
+ const downloadSignal = signal ? AbortSignal.any([signal, totalTimeout]) : totalTimeout;
45
+ for (const [index, result] of results.entries()) {
46
+ let temp;
47
+ try {
48
+ const { response, url } = await fetchMedia(result.url, fetchImpl, downloadSignal);
49
+ const contentType = response.headers.get('content-type')?.split(';')[0].trim().toLowerCase();
50
+ let extension = EXTENSIONS[contentType];
51
+ if (!extension && (!contentType || contentType === 'application/octet-stream')) {
52
+ const candidate = path.extname(url.pathname).slice(1).toLowerCase();
53
+ if (Object.values(EXTENSIONS).includes(candidate)) extension = candidate;
54
+ }
55
+ if (!extension) { await response.body.cancel(); throw new Error('结果不是支持的图片、视频或音频文件。'); }
56
+ const length = Number(response.headers.get('content-length') || 0);
57
+ if (length > maxBytes) { await response.body.cancel(); throw new Error('结果超过单文件下载大小限制。'); }
58
+ temp = path.join(outputDir, `.gensor-${randomUUID()}.part`);
59
+ const handle = await open(temp, 'wx', 0o600);
60
+ let bytes = 0;
61
+ const limit = new Transform({ transform(chunk, encoding, callback) {
62
+ bytes += chunk.length;
63
+ callback(bytes > maxBytes ? new Error('结果超过单文件下载大小限制。') : null, chunk);
64
+ } });
65
+ await pipeline(Readable.fromWeb(response.body), limit, handle.createWriteStream(), { signal: downloadSignal });
66
+ if (!bytes) throw new Error('结果文件为空。');
67
+ const safeId = taskId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
68
+ const destination = path.join(outputDir, `gensor-${safeId}-${index + 1}-${randomUUID().slice(0, 8)}.${extension}`);
69
+ // Atomic publication without overwriting existing files or following a destination symlink.
70
+ await link(temp, destination);
71
+ await unlink(temp); temp = null;
72
+ files.push({ path: destination, bytes });
73
+ } catch (error) {
74
+ files.push({ index, error: error.message });
75
+ } finally { if (temp) await unlink(temp).catch(() => {}); }
76
+ }
77
+ return { taskId, files, complete: files.every(file => Boolean(file.path)), note: '下载失败可重试下载;不要重新提交生成任务。' };
78
+ }
@@ -0,0 +1,65 @@
1
+ #!/usr/bin/env node
2
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
+ import { z } from 'zod';
5
+ import { ConfigStore, redact } from './config.mjs';
6
+ import { PlatformApi } from './api.mjs';
7
+ import { MODELS } from './models.mjs';
8
+ import { TaskService } from './tasks.mjs';
9
+ import { downloadResults } from './downloads.mjs';
10
+
11
+ const store = new ConfigStore();
12
+ const tasks = new TaskService(store, config => new PlatformApi(config));
13
+ const server = new McpServer({ name: 'gensor-agent', version: '0.1.0' });
14
+ const taskIdSchema = z.string().trim().min(1).max(512);
15
+ function register(name, description, inputSchema, annotations, handler) {
16
+ server.registerTool(name, { description, inputSchema, annotations }, async (args, extra) => {
17
+ try {
18
+ const result = await handler(args, extra.signal);
19
+ return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
20
+ } catch (error) {
21
+ const config = await store.read({ required: false }).catch(() => null);
22
+ return { isError: true, content: [{ type: 'text', text: redact(redact(error.message, args.apiKey), config?.apiKey) }] };
23
+ }
24
+ });
25
+ }
26
+ const readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
27
+ register('gensor_get_config_status', '检查本地配置;不返回 Key,不发起付费任务。configured 不等于在线验证。', {}, { ...readOnly, openWorldHint: false }, () => store.status());
28
+ register('gensor_set_api_key', '保存用户在对话中明确提供的小炸 API Key。不回显 Key,不发起在线验证或收费任务。', {
29
+ apiKey: z.string().min(1).max(4096).describe('用户明确提供的 API Key'),
30
+ }, { destructiveHint: false, openWorldHint: false }, ({ apiKey }) => store.save({ apiKey }));
31
+ register('gensor_list_models', '列出 webtask.js 支持的模型名称;不代表平台实时可用性、价格或参数范围。', {}, { ...readOnly, openWorldHint: false }, async () => ({ models: MODELS, note: '分辨率、比例、时长以平台说明为准。提交使用平台 /api/webtask,由服务端验证API Key。' }));
32
+ register('gensor_upload_media', '将用户指定的本地参考图片、视频或音频上传到所配置的平台,返回 HTTPS URL 和媒体类型。', {
33
+ filePath: z.string().min(1),
34
+ }, { destructiveHint: false, openWorldHint: true, idempotentHint: false }, async ({ filePath }, signal) => new PlatformApi(await store.read()).upload(filePath, signal));
35
+ register('gensor_create_task', '提交一次图片、视频或语音生成(可能收费);仅返回任务 ID。发生超时或不确定结果时禁止自动重新提交。', {
36
+ model: z.enum(MODELS.map(model => model.id)),
37
+ prompt: z.string().trim().min(1).max(30000),
38
+ imageUrls: z.array(z.string().url()).max(16).optional(),
39
+ videoUrls: z.array(z.string().url()).max(16).optional(),
40
+ audioUrls: z.array(z.string().url()).max(16).optional(),
41
+ speech_rate: z.number().min(-50).max(100).optional().describe('仅 voice_clone:语速,0 原速、-50 为 0.5 倍、100 为 2 倍;无参考音频也可用'),
42
+ audioDurations: z.array(z.number().positive().max(15)).max(16).optional(),
43
+ resolution: z.string().min(1).max(40).optional(),
44
+ aspectRatio: z.string().min(1).max(40).optional(),
45
+ duration: z.string().min(1).max(20).optional(),
46
+ }, { destructiveHint: false, openWorldHint: true, idempotentHint: false }, (args, signal) => tasks.create(args, signal));
47
+ register('gensor_list_tasks', '列出当前平台地址和 Key 对应的最近 50 个本机任务,以便中断后恢复;不查询平台也不返回 Key。', {}, { ...readOnly, openWorldHint: false }, () => tasks.list());
48
+ register('gensor_get_task', '通过 V2 query 查询任务,使用提交时同一 Key;生图最多等待 5 分钟,视频和音频最多等待 20 分钟。查询不会重新提交任务。', {
49
+ taskId: taskIdSchema,
50
+ taskKind: z.enum(['image', 'other']).optional().describe('本机没有记录的任务必须指定;已有记录自动识别'),
51
+ waitSeconds: z.number().int().min(0).max(1200).optional(),
52
+ }, readOnly, ({ taskId, waitSeconds, taskKind }, signal) => tasks.query(taskId, { waitSeconds, taskKind, signal }));
53
+ register('gensor_download_outputs', '查询任务后将所有结果下载到指定本地绝对路径;保留现有文件,不向结果 CDN 发送 API Key。', {
54
+ taskId: taskIdSchema,
55
+ taskKind: z.enum(['image', 'other']).optional().describe('本机没有记录的任务必须指定;已有记录自动识别'),
56
+ outputDir: z.string().min(1),
57
+ }, { destructiveHint: false, openWorldHint: true }, async ({ taskId, outputDir, taskKind }, signal) => {
58
+ const task = await tasks.query(taskId, { taskKind, signal });
59
+ if (task.status !== 'completed') return { taskId, status: task.status, error: task.error, downloaded: false };
60
+ return downloadResults(task.results, { taskId, outputDir, signal });
61
+ });
62
+
63
+ await server.connect(new StdioServerTransport());
64
+ process.on('SIGINT', () => { void server.close(); });
65
+ process.on('SIGTERM', () => { void server.close(); });
@@ -0,0 +1,76 @@
1
+ // Public model names from cloud-functions/api/webtask.js. Provider routing stays server-side.
2
+ // This is a declared catalogue, not a live claim about model availability.
3
+ export const MODELS = Object.freeze([
4
+ { id: 'voice_clone', kind: 'audio' },
5
+ { id: 'gpt-image-2', kind: 'image' },
6
+ { id: 'gpt-image-2.5', kind: 'image' },
7
+ { id: 'wan-3.0', kind: 'video', duration: [4, 30] },
8
+ { id: 'seedance-2.5-token', kind: 'video', duration: [4, 30] },
9
+ { id: 'sparkvideo-2.0', kind: 'video', duration: [5, 15] },
10
+ { id: 'drama-3.5', kind: 'video', duration: [4, 30]},
11
+ ]);
12
+
13
+ export function buildGeneration({ model, prompt, imageUrls = [], videoUrls = [], audioUrls = [], audioDurations = [], resolution, aspectRatio, duration, speech_rate }) {
14
+ const adapter = MODELS.find(item => item.id === model);
15
+ if (!adapter) throw new Error('不支持该模型;请先调用 gensor_list_models。');
16
+ if (typeof prompt !== 'string' || !prompt.trim()) throw new Error('prompt 不能为空。');
17
+ const references = [imageUrls, videoUrls, audioUrls];
18
+ if (references.some(values => !Array.isArray(values) || values.length > 16 || values.some(value => {
19
+ try { const u = new URL(value); return u.protocol !== 'https:' || Boolean(u.username || u.password); }
20
+ catch { return true; }
21
+ }))) throw new Error('参考素材必须先上传,或使用有效的 HTTPS URL。');
22
+ if (duration !== undefined && adapter.duration) {
23
+ const value = Number(duration);
24
+ if (!Number.isFinite(value) || value < adapter.duration[0] || value > adapter.duration[1]) {
25
+ throw new Error(`${model} 的有效时长范围是 ${adapter.duration[0]}-${adapter.duration[1]} 秒。`);
26
+ }
27
+ }
28
+ if (model === 'voice_clone') {
29
+ if (imageUrls.length || videoUrls.length) throw new Error('voice_clone 仅支持参考音频,不接受图片或视频参考。');
30
+ if (audioUrls.length > 3) throw new Error('voice_clone 最多支持 3 段参考音频,每段不超过 10MB。');
31
+ if ([resolution, aspectRatio, duration].some(value => value !== undefined)) throw new Error('voice_clone 不支持视频时长、画幅或分辨率参数。');
32
+ }
33
+ if (speech_rate !== undefined) {
34
+ if (model !== 'voice_clone') throw new Error('speech_rate 仅适用于 voice_clone。');
35
+ if (typeof speech_rate !== 'number' || !Number.isFinite(speech_rate) || speech_rate < -50 || speech_rate > 100) {
36
+ throw new Error('speech_rate 必须是 -50 到 100 之间的数值。');
37
+ }
38
+ }
39
+ if (audioUrls.length > 0 && model !== 'voice_clone') {
40
+ if (!Array.isArray(audioDurations) || audioDurations.length !== audioUrls.length) {
41
+ throw new Error('每个音频参考都需要提供对应的 audioDurations,且不能超过 15 秒。');
42
+ }
43
+ if (audioDurations.some(value => !Number.isFinite(Number(value)) || Number(value) <= 0 || Number(value) > 15)) {
44
+ throw new Error('音频参考的有效时长不能超过 15 秒。');
45
+ }
46
+ }
47
+ const basePayload = { prompt };
48
+ if (speech_rate !== undefined) basePayload.speech_rate = speech_rate;
49
+ if (resolution !== undefined) basePayload.resolution = resolution;
50
+ if (aspectRatio !== undefined) basePayload.aspectRatio = aspectRatio;
51
+ if (duration !== undefined) basePayload.duration = String(duration);
52
+ if (imageUrls.length) basePayload.imageUrls = imageUrls;
53
+ if (videoUrls.length) basePayload.videoUrls = videoUrls;
54
+ if (audioUrls.length) basePayload.audioUrls = audioUrls;
55
+ // Do not send userId: the platform will derive the identity from the Bearer API Key.
56
+ return {
57
+ endpoint: '/api/webtask',
58
+ payload: {
59
+ taskType: 'TASK_API',
60
+ taskParams: { model, basePayload },
61
+ },
62
+ kind: adapter.kind,
63
+ };
64
+ }
65
+
66
+ export function normalizeTask(result, requestedTaskId) {
67
+ const states = { QUEUED: 'pending', RUNNING: 'processing', SUCCESS: 'completed', FAILED: 'failed', CANCELED: 'canceled', CANCELLED: 'canceled' };
68
+ const hasErrorCode = ![undefined, null, '', 0, '0'].includes(result.errorCode);
69
+ if (!states[result.status] && !hasErrorCode) throw new Error('平台返回了未知任务状态,未将其误判为完成或失败。');
70
+ return {
71
+ taskId: result.taskId || requestedTaskId,
72
+ status: hasErrorCode ? 'failed' : states[result.status],
73
+ results: Array.isArray(result.results) ? result.results : [],
74
+ error: result.failedReason?.exception_message || result.errorMessage || undefined,
75
+ };
76
+ }
@@ -0,0 +1,81 @@
1
+ import { readFile, readdir } from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { createHash, randomUUID } from 'node:crypto';
4
+ import { scopeId, writePrivateJson } from './config.mjs';
5
+ import { buildGeneration, MODELS } from './models.mjs';
6
+ import { setTimeout as delay } from 'node:timers/promises';
7
+
8
+ export const MAX_WAIT_SECONDS = Object.freeze({ image: 5 * 60, other: 20 * 60 });
9
+
10
+ export class TaskService {
11
+ constructor(store, apiFactory) { this.store = store; this.apiFactory = apiFactory; }
12
+ file(id) { return path.join(this.store.root, 'tasks', `${createHash('sha256').update(id).digest('hex')}.json`); }
13
+ async load(id) {
14
+ try { return JSON.parse(await readFile(this.file(id), 'utf8')); }
15
+ catch (error) { if (error.code === 'ENOENT') return null; throw error; }
16
+ }
17
+ async list() {
18
+ const config = await this.store.read();
19
+ let names;
20
+ try { names = await readdir(path.join(this.store.root, 'tasks')); }
21
+ catch (error) { if (error.code === 'ENOENT') return { tasks: [] }; throw error; }
22
+ const items = new Map();
23
+ for (const name of names) {
24
+ if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
25
+ const record = JSON.parse(await readFile(path.join(this.store.root, 'tasks', name), 'utf8'));
26
+ if (record.scope !== scopeId(config)) continue;
27
+ const { taskId, requestId, model, taskKind, status, createdAt } = record;
28
+ const id = taskId || requestId;
29
+ if (!items.has(id) || record.updatedAt) items.set(id, { taskId, requestId, model, taskKind, status, createdAt });
30
+ }
31
+ return { tasks: [...items.values()].sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || '')).slice(0, 50) };
32
+ }
33
+ async create(input, signal) {
34
+ const config = await this.store.read();
35
+ const generation = buildGeneration(input);
36
+ const requestId = randomUUID();
37
+ const record = { requestId, scope: scopeId(config), model: input.model, taskKind: generation.kind === 'image' ? 'image' : 'other', status: 'submitting', createdAt: new Date().toISOString() };
38
+ await writePrivateJson(this.file(requestId), record);
39
+ let submitted;
40
+ try { submitted = await this.apiFactory(config).submit(generation, signal); }
41
+ catch (error) {
42
+ await writePrivateJson(this.file(requestId), { ...record, status: 'submission-unknown' });
43
+ throw new Error(`${error.message} 本地请求编号 ${requestId};请核对平台任务记录,不要自动重提。`);
44
+ }
45
+ const task = { ...record, ...submitted };
46
+ try {
47
+ await writePrivateJson(this.file(submitted.taskId), task);
48
+ await writePrivateJson(this.file(requestId), task);
49
+ } catch {
50
+ // Submission succeeded: always return the paid task ID even if journaling fails.
51
+ return { ...submitted, requestId, taskKind: record.taskKind, warning: '任务已提交,但本地记录写入失败;请保留 taskId 用于继续查询。' };
52
+ }
53
+ return { ...submitted, requestId, taskKind: record.taskKind, note: '已提交,不代表已生成。请使用此 taskId 查询或下载;不要重新创建任务。' };
54
+ }
55
+ async query(taskId, { waitSeconds = 0, taskKind, signal } = {}) {
56
+ const config = await this.store.read();
57
+ const saved = await this.load(taskId);
58
+ if (saved && saved.scope !== scopeId(config)) throw new Error('该任务属于其他 API 地址或 Key,请恢复原配置再查询。');
59
+ // Support records created before taskKind was persisted by deriving it from a known model.
60
+ const savedModel = MODELS.find(model => model.id === saved?.model);
61
+ const savedKind = saved?.taskKind || (savedModel ? (savedModel.kind === 'image' ? 'image' : 'other') : undefined);
62
+ if (taskKind && !['image', 'other'].includes(taskKind)) throw new Error('taskKind 必须是 image 或 other。');
63
+ if (savedKind && taskKind && savedKind !== taskKind) throw new Error('传入的任务类型与本地记录不一致,未向其他域名查询。');
64
+ const queryKind = savedKind || taskKind;
65
+ if (!queryKind) throw new Error('本机没有该任务的类型记录,请提供 taskKind:image(生图)或 other(其他任务)。');
66
+ const maxWaitSeconds = MAX_WAIT_SECONDS[queryKind];
67
+ if (waitSeconds < 0 || waitSeconds > maxWaitSeconds) {
68
+ throw new Error(`${queryKind === 'image' ? '生图' : '视频/音频'}任务最多等待 ${maxWaitSeconds / 60} 分钟。`);
69
+ }
70
+ const api = this.apiFactory(config);
71
+ const deadline = Date.now() + waitSeconds * 1000;
72
+ let result;
73
+ do {
74
+ result = { ...await api.query(taskId, queryKind, signal), taskKind: queryKind };
75
+ await writePrivateJson(this.file(taskId), { ...saved, ...result, scope: scopeId(config), createdAt: saved?.createdAt || new Date().toISOString(), updatedAt: new Date().toISOString() });
76
+ if (['completed', 'failed', 'canceled'].includes(result.status) || Date.now() >= deadline) break;
77
+ await delay(Math.min(30000, deadline - Date.now()), undefined, { signal });
78
+ } while (Date.now() < deadline);
79
+ return result;
80
+ }
81
+ }
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: execute
3
+ description: 使用小炸工具执行图片、视频和语音生成、上传参考素材、查询任务及下载结果。适用于已有提示词的直接生成和任务恢复;需求确认、剧本拆解与分镜提示词编排使用 short-film-director。
4
+ ---
5
+
6
+ # 小炸 图片、视频与语音执行
7
+
8
+ 通过插件的 `gensor_*` MCP 工具完成生成。提交、查询和素材上传使用配置的同一枚 Bearer API Key;Key 仅用于 gensor_set_api_key 的 apiKey 参数和本地凭据保存,不放进生成提示词、日志或回复中。
9
+
10
+ 需要前期创作、角色场景识别或改善镜头与对白提示词时,先使用同插件的 [短剧与短片导演](../short-film-director/SKILL.md)。已有完整提示词的直接生成不必重新访谈。
11
+
12
+ ## 配置
13
+
14
+ 先调用 `gensor_get_config_status`。缺少 Key 时请用户直接在对话中提供;收到用户明确提供的 Key 后,调用 `gensor_set_api_key({ apiKey })` 保存。用户主动要求更新 Key 时也使用此工具,不打开配置网页,不使用 shell 命令传递 Key,不回显完整或部分 Key。保存只写本地配置,不自动创建任务验证。
15
+
16
+ `configured` 只代表本地存在配置,不代表平台已在线鉴权成功。提交、查询和上传首次真正访问平台时才会验证 Key。
17
+
18
+ 路由规则如下,不要自动探测、切换或轮询其他域名:
19
+
20
+ - **提交任务**:调用 `/api/webtask`。
21
+ - **图片/视频/音频素材上传**:本地素材需先上传获取HTTPS URL后,作为对应参数值使用。
22
+ - **查询路径**:`/openapi/v2/query`,请求 JSON 为 `{"taskId":"..."}`。
23
+ - **上传路径**:`/openapi/v2/media/upload/binary`,使用 multipart 字段 `file`。
24
+
25
+ 提交请求使用 `Authorization: Bearer <配置的 API Key>` 和 JSON:
26
+
27
+ ```json
28
+ {
29
+ "taskType": "TASK_API",
30
+ "taskParams": {
31
+ "model": "模型名称",
32
+ "basePayload": {
33
+ "prompt": "提示词",
34
+ "imageUrls": [],
35
+ "resolution": "2k",
36
+ "aspectRatio": "16:9"
37
+ }
38
+ }
39
+ }
40
+ ```
41
+
42
+ 由平台服务端根据 Bearer Key 校验用户、执行额度检查、计费和回调。
43
+
44
+ ## 生成
45
+
46
+ 1. 先调用 `gensor_list_models` 获取本地模型清单。清单不代表平台实时可用性、价格、尺寸、比例或时长范围;用户已指定的参数原样传递,未确认的可选参数省略。
47
+ 2. 用户未指定模型时,图片默认 `gpt-image-2`,视频默认 `drama-3.5`,语音使用 `voice_clone`。如用户明确指定 `seedance-2.5-token`,使用该模型,不自动改用其他模型。
48
+ 3. 图片可传 `resolution`(例如 `2k`)和 `aspectRatio`(例如 `16:9`);视频可传 `resolution`(例如 `480p`)、`aspectRatio`(例如 `9:16`)和 `duration`。`drama-3.5`、`wan-3.0`、`seedance-2.5-token` 的时长范围是 4–30 秒;`sparkvideo-2.0` 的时长范围是 5–15 秒。
49
+ 4. 用户请求生成即授权对应的单次生成。按用户明确的数量提交,不自行增加样片、变体或测试任务。提交前简短说明采用的模型和关键参数。
50
+ 5. 使用本地参考图、视频或音频时,需先上传拿到 URL;调用 `gensor_upload_media`,根据返回的 `mediaType` 把 URL 放入 `imageUrls`、`videoUrls` 或 `audioUrls`。视频生成的音频参考单段 1-15 秒且总时长 ≤15 秒;`voice_clone` 使用下方独立限制。不上传无关文件。
51
+ 6. 用 `gensor_create_task` 只提交一次,保存 `taskId`。Task ID 只表示已提交,不表示已生成。
52
+ 7. 若提交超时、网络异常或响应不确定,禁止自动重试付费提交;保留并报告本地请求编号,让用户核对平台任务记录。
53
+
54
+ ## 模型参数
55
+
56
+ - 生图类模型 `gpt-image-2`、`gpt-image-2.5`,参考图 `imageUrls` 最多10项,没有参考图时可不传。
57
+ - 生图提示词 `prompt` 文本长度限制: 1 - 20000
58
+ - 生图支持 `resolution` 参数,值为 `1k`、`2k`、`4k`, 默认 `1k`。
59
+ - 生图支持 `aspectRatio` 参数,值为 `1:1`、`2:3`、`3:2`、`4:5`、`5:4`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`9:21`、`2:1`、`1:2`、`3:1`、`1:3`,默认 `9:16`。
60
+
61
+ - 视频生成类模型 `drama-3.5`、`wan-3.0`、`seedance-2.5-token`、`sparkvideo-2.0` 默认 `drama-3.5`
62
+ - 视频时长`duration` String类型时长范围为 4–30 秒,`sparkvideo-2.0` 为 5–15 秒,默认 `"10"` 。
63
+ - 视频提示词 `prompt` 正向提示词(中英文均可)。可用「视频1 / 图1 / 音频1」按上传顺序指代参考素材。
64
+ - 视频支持 `resolution` 参数,值为 `480p`、`720p`、`1080p`, 默认 `720p`。
65
+ - 视频支持 `aspectRatio` 参数,值为 `adaptive`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`,默认 `adaptive`,根据意图与输入媒体自动推荐。
66
+ - 参考音频,最多 5 段,单段 1-15 秒且总时长 ≤15 秒,参考视频要求也一样;图片参考最多支持 10 项,每张 20 MB 以内,用于锁定角色、道具或场景。
67
+
68
+ ## 语音生成(voice_clone)
69
+
70
+ 支持直接按提示词生成语音,或根据用户提供的参考音色生成指定内容。沿用 `gensor_create_task`,模型固定为 `voice_clone`,提交后按音频任务查询、下载。
71
+
72
+ - `prompt` 必填。明确待说文本、语言、音色、语气及必要停顿;将台词与表演要求分开,不擅自改写用户原文。用户明确指定逐字朗读时,把原文用引号隔离,下载后仍需审听核对。
73
+ - 无参考音频:省略 `audioUrls`,直接描述声音与朗读内容,不要求用户先上传音色。
74
+ - 参考音色:先上传用户指定的 MP3/WAV/M4A 文件,使用返回的 HTTPS URL 填入 `audioUrls`,最多 3 项,每项最大 10MB。上传前检查本地文件大小;现有上传工具通用上限为 30 MiB,不等于该模型允许 30 MiB。外部 URL 无法核验大小时说明待平台验证。
75
+ - 不套用视频参考的 15 秒规则,不要求 `audioDurations`;该接口未声明语音参考时长限制,不自行编造。
76
+ - 可选 `speech_rate` 为数值,范围 `[-50, 100]`,默认 0;-50 为 0.5 倍速,100 为 2 倍速,无参考音频也可指定。用户未要求调速时省略。
77
+ - 不传 `imageUrls`、`videoUrls`、`duration`、`aspectRatio` 或 `resolution`。不把平台内部的 `audio_url`、模型类型或厂商路由作为 MCP 参数。
78
+ - 多个角色分别生成并记录角色→台词→参考音色→taskId;多段参考是声音参考,不据此保证自动多角色分轨。仅按用户授权的数量生成。
79
+
80
+ 纯提示词调用示例:
81
+
82
+ ```json
83
+ {
84
+ "model": "voice_clone",
85
+ "prompt": "普通话,成年女性,声音克制而略带质问,只朗读引号内的原文,不朗读说明:\"你早就知道了,对不对?\" 逗号处短暂停顿。",
86
+ "speech_rate": 0
87
+ }
88
+ ```
89
+
90
+ 克隆音色时,在以上参数中加入 `audioUrls`,值为真实上传返回的 URL 列表,并在 prompt 中说明参考音色与朗读内容;不要发送示例占位地址。参考音色相似度与逐字准确性需要成品验收,生成音频不等于已完成视频口型同步、音轨合成或剪辑。
91
+
92
+ ## 查询、下载和恢复
93
+
94
+ - 使用同一 `taskId` 调用 `gensor_get_task`;生图任务需要等待时 `waitSeconds` 最多 300 秒(5 分钟),视频和音频任务最多 1200 秒(20 分钟)。不需要等待时省略该参数或传 `0`。
95
+ - 查询报错不等于生成失败。遇到 401/403 时提示检查配置,不重复请求。
96
+ - 任务本地记录保存 `taskKind`,查询会自动选择图片 `.ai` 或视频/音频 `.cn` 域名。
97
+ - 没有本机记录时,必须明确任务类型,并传 `taskKind: image` 或 `taskKind: other`;不要从 taskId 猜测,也不要轮询两个域名。
98
+ - `submission-unknown` 且没有 `taskId` 的记录只能去平台核对,不能拿本地 `requestId` 冒充 `taskId`。
99
+ - 任务成功后调用 `gensor_download_outputs`,`outputDir` 使用当前项目下的绝对路径,默认 `outputs/gensor`。下载失败只重试下载,不重新生成。
100
+ - 下载不向 CDN 请求发送 API Key。返回图片、视频或音频的绝对路径后,用 Markdown 媒体语法展示可预览结果;音频同样使用 `![语音](/绝对路径/文件.mp3)`。
101
+ - 平台任务失败时报告平台错误,不擅自更换模型、提示词或参数再次收费。
@@ -0,0 +1,71 @@
1
+ ---
2
+ name: director
3
+ description: 为小炸短剧、短片及商业数字人口播创作梳理并确认需求,将故事或剧本拆成角色场景资产、分镜、对白和可执行的视频生成提示词。适用于从创意到生成计划、剧本拆解、商业推广口播与 B-roll 编排、导演提示词优化及对白失准排查;已有提示词的直接生成和任务查询交给 execute。
4
+ ---
5
+
6
+ # 短剧与短片导演
7
+
8
+ 把创作需求变成用户能确认、生成工具能执行的制作方案。按用户当前阶段切入:已有剧本就直接拆解;只要改提示词就直接诊断并重写,不强制重新走需求访谈。用户给定的题材、风格、模型、台词和参考素材优先,不把所有作品限定为真人、都市或竖屏。
9
+
10
+ ## 1. 确认最少必要的创作需求
11
+
12
+ 提取已有信息:作品类型、故事核心/已有剧本或推广文案、观众与平台、总时长/集数、画幅、视觉风格、模型、已有素材、对白准确度和交付范围。缺项分成阻塞项与可假设项;每轮最多问三个会改变方案的问题,不重复问已回答内容。
13
+
14
+ 尽量用选择题,注明推荐与取舍,允许自填。环境提供交互选择工具且可用时使用;否则列出编号选项,让用户用“1A、2B”回答。不要调用当前模式禁止使用的交互工具。可参考:
15
+
16
+ - 作品方向:A 短剧(人物冲突驱动)/B 短片(完整视听叙事)/C 商业数字人(推广口播与 B-roll)/D 自填。
17
+ - 对白交付:A 原生对白试生成(方便,但须验收字句和口型)/B 逐字准确优先(保留原文,规划配音与口型后期)/C 无对白,以动作叙事。
18
+ - 执行范围:A 只输出剧本与提示词/B 先制作人物、场景参考图/C 按约定数量生成视频。
19
+
20
+ 推荐项随用户目标变化,不能总把原生对白设为推荐。可假设项给出简短默认值并继续,例如“暂按单集 60 秒、9:16、真人写实制作,可调整”。锁定用户已确认的创作简报;有实质分歧再确认,不为每个镜头加一道批准流程。用户要求托管或直接执行时,在已授权范围内继续。
21
+
22
+ 商业数字人、品牌推广、产品讲解或带货口播,先读取 [商业数字人规则](references/commercial-avatar.md),补齐产品、受众、推广目标、核心卖点与行动引导;按商业信息结构编排,不强制套用戏剧冲突。
23
+
24
+ ## 2. 拆剧本与建立资产
25
+
26
+ 没有剧本时,先给一句话故事、起因→目标→阻力→转折→结果,再写可拍摄的场景。保留用户原始台词;删改、压缩、添加台词须明确列为建议,未经同意不得当成原文。未知角色、关系、场景标记“待确认”,不要伪称从原文识别出来。
27
+
28
+ 输出紧凑的制作表:
29
+
30
+ - 角色 C01…:姓名、叙事功能、可见外形、服装/饰品、语言习惯、素材状态。
31
+ - 场景 S01…:内外景、时间/天气、门窗与关键家具位置、主光方向、出入口。
32
+ - 道具 P01…:持有人、摆放位置、开合/破损等状态。
33
+ - 声音 V01…:说话人、语言/口音、音色描述、参考音频是否真实存在。
34
+
35
+ 使用稳定 ID;同一人物换服装用状态版本,不误建新角色。缺参考素材时提供人物定妆图、空场景图、必要关键帧的生图提示词,标明“待制作”,不虚构图号或已上传 URL。人物和场景分别生成便于复用;需要同框构图时另做关键帧。只为当前作品需要的资产建表。
36
+
37
+ ## 3. 分段与导演设计
38
+
39
+ 读取 [references/prompt-and-dialogue.md](references/prompt-and-dialogue.md),按动作节拍和对白负荷拆段。叙事段落可以含多个生成单元;每个单元以一个主动作、一次情绪转折为中心。不要把平台时长上限当成推荐长度。模型范围来自当前插件的 `gensor_list_models` 及执行 skill;不得让 30 秒模板覆盖其他模型的限制。
40
+
41
+ 每个镜头说明:景别与构图、机位/主要运动、主体可见动作、视线/站位、表情变化、对白/声音、结束状态。表演用“看向门口→手停在杯沿→压低声音”等可拍动作,避免一口气堆叠多个微表情。切镜服务信息揭示、反应或动作结果;对白准确优先时避免说话中途快速切镜和频繁大幅转头。
42
+
43
+ 连续性按“本段起始状态→动作结果→下一段继承状态”记录,覆盖服装、道具、屏幕方向、进出场、光线。每个实际投喂的单元重复必要资产描述,不能只写“同上”“延续上一段”。
44
+
45
+ 动作、打斗或武侠段落另读 [动作戏编排规则](references/prompt-and-dialogue.md#动作戏与武侠段落),优先交代交锋空间、发力与受力、环境反馈及动作结果;风格与奇观服务剧情,不压过动作可读性。
46
+
47
+ 商业数字人须按 [商业数字人规则](references/commercial-avatar.md)同步设计 A-roll 人物口播、逐句声音时间线与 B-roll 插入点,区分画内说话与同音色画外旁白,保证卖点、画面证据与转化引导对应。
48
+
49
+ ## 4. 输出两层交付物
50
+
51
+ 先交付可审阅的制作计划(角色/场景表、分镜、台词清单、连续性和待确认事项);再给每个单元一块可直接复制的 `prompt` 与生成参数。用户只要提示词时可省略完整制作册,但保留必要的缺项说明。
52
+
53
+ 模板及完整示例见 [references/delivery-example.md](references/delivery-example.md)。执行文本只放模型需要的画面、动作、声音与素材绑定;预算、风险、导演解释、验收结果放在制作计划中。不要把长篇规则、所有镜头表、所有角色资料机械塞进每次请求。
54
+
55
+ ## 5. 对接 小炸 执行
56
+
57
+ 仅规划或改写时不要求配置 Key、不上传素材、不创建任务。需要生图/视频时读取同插件的 [execute 执行说明](../gensor-generate/SKILL.md),使用实际可用的 `gensor_*` 工具;工具缺失时交付计划并明确当前未提交。
58
+
59
+ 保持用户指定模型。将模型名视为插件适配器 ID;没有对应平台证据时,不把 `drama-3.5` 等 ID 推断为某厂商公开模型版本或宣称具备精确台词/声音克隆能力。
60
+
61
+ 按素材类型分别上传,把返回的 HTTPS URL 放进 `imageUrls`、`videoUrls`、`audioUrls`;图1、图2按本次 `imageUrls` 顺序,音频1按本次 `audioUrls` 顺序,视频1按本次 `videoUrls` 顺序重新绑定。内部 C01/S01/V01 ID 不等于接口素材编号。音频不能写成“音频参考图”;未实际传入的参考不出现在执行提示词中。
62
+
63
+ 提示词与参数保持同一时长、画幅和模型。每个任务单独列 `model`、`prompt`、`duration`(字符串)、`aspectRatio` 和实际可用素材;其他字段按执行说明传递。不臆造 `seed`、`negative_prompt`、口型修复、剪辑、字幕移除、音色绑定等工具参数。参考音频存在不代表能精确复述文本或锁定说话人。
64
+
65
+ 用户授权生成后按明确数量提交,不擅自增加样片或收费重试。拿到 taskId 记录“已提交”,只有查询完成并取得结果才称“已生成”。长片分批执行并保存每段 ID 与素材对应关系;提交结果不确定时遵循执行 skill 的恢复规则。
66
+
67
+ ## 6. 交付前与生成后验收
68
+
69
+ 提交前检查:时间线无重叠/缺口、参数时长符合模型范围、台词可在窗口内说完、说话人和素材顺序正确、单镜头动作可执行、连续性无冲突。参考编号缺失或台词超时须先修正,不靠负向词掩盖。
70
+
71
+ 生成后如可查看视频/听音频,检查角色身份、动作结果、镜头完成度、逐字对白、串话/抢话、音画同步及尾句截断;不可检查时标记“未验收”,不得声称台词正确。发现漏字/改字,报告具体句子与偏差;原台词不变时优先简化镜头、减少同屏说话人、延长窗口或拆单元。用户要求重试才提交新增任务。需要独立配音时使用执行 skill 的 voice_clone,按角色及台词生成并审听;口型修复与剪辑仍需外部工具,交付后期清单并明确尚未执行的环节。
@@ -0,0 +1,73 @@
1
+ # 商业数字人短片
2
+
3
+ 用于品牌推广、产品介绍、服务讲解、企业宣传及带货口播。目标是让观众听懂价值、看见对应展示并知道下一步动作;具体语气按品牌和投放场景确定,不统一写成夸张叫卖或电影预告片。
4
+
5
+ ## 创作简报与节奏
6
+
7
+ 沿用主 skill 的最少提问原则,提取:产品/品牌、目标人群及使用场景、推广目标、已确认的卖点与素材、渠道/画幅/时长、数字人形象/音色、最终行动引导(CTA)。缺少关键内容时优先选择题,例如:
8
+
9
+ - 目标:A 产品认知/B 使用讲解/C 咨询或购买转化。
10
+ - 口播状态:A 专业可信/B 亲切分享/C 有活力的促销;按品牌给推荐。
11
+ - 呈现:A 人物口播与产品展示交替/B 人物主讲、少量展示/C 展示为主、同音色旁白。
12
+
13
+ 只使用用户提供或确认的功能、价格、优惠和效果,不编造销量、认证、客户评价、前后对比或产品能力。缺失内容标为待确认,不塞进正式口播。已有品牌话术/台词先保留;改写给对照建议。是否使用字幕、Logo、配乐按品牌需求明确,不沿用短剧的全局“禁止文字/无 BGM”。未指定可暂按干净画面、无配乐编排,并说明可调整。
14
+
15
+ 整体采用“相关问题/吸引点→核心价值→使用展示或证据→行动引导”的可调结构。短片只保留一个主卖点,较长片再展开辅助卖点;每个节拍传递一条信息,不固定几秒一切。产品展示须留够辨认或操作时间,CTA 留够完整说完和视线停留的时间。先做全片声音时间线,再安排切镜,不能为追求快节奏裁掉词尾。
16
+
17
+ ## 人物口播 A-roll
18
+
19
+ 每个单元明确:身份/参考素材、服装与布景、景别、视线、姿态、微笑强度、语气、逐字台词、发声窗口、重音/停顿与收尾状态。
20
+
21
+ - 默认眼平中近景、直视镜头,嘴部清晰可见;肩颈放松、呼吸自然。讲解像在对一个真实客户说话。
22
+ - 手势与一个信息点对应,位于胸腹区域、幅度克制;避免持续挥手、机械点头、固定露齿笑、朗诵腔或过度戏剧表演。促销可提高能量,但句子仍须听清。
23
+ - 用 `[重读]`、`[停顿约0.3秒]` 等标注放在制作台词表,实际 prompt 写成引号外的导演指令;引号内只有要说的原文,防止把指令念出声。
24
+ - 中文先按每秒约 3–4 汉字核算,再加停顿与呼吸;数字、英文品牌、价格、单位按实际读法计时。若已生成配音,以审听后的音频实长重新校准。
25
+ - 情绪随信息推进:开头建立联系,卖点清楚有重点,展示解释自然,结尾引导明确;切回人物时延续同一音色、服装、光线和交流状态。
26
+
27
+ ## B-roll 与声音衔接
28
+
29
+ B-roll 是承接正在讲述内容的产品、操作或使用场景画面。每段说明“对应哪句台词/哪个卖点→画面展示什么→如何接回人物”,不插无关风景或纯装饰素材。
30
+
31
+ - 产品外形、配色、包装、关键配件绑定真实素材;操作展示具体起始状态、步骤和结果,不让手遮住关键部位。准确界面、参数、品牌字样优先使用用户提供的真实素材。
32
+ - 镜头可用产品全貌、细节、手部操作或真实使用场景,按信息需要选择;不把所有 B-roll 都做成旋转悬浮产品与快速炫光。
33
+ - 默认人物切出后,同一口播音轨作为画外旁白连续播放;B-roll 内不再生成另一套人声,不重复、漏掉或更换卖点台词。切回人物在句间或自然停顿处,避免同一句话被再次开口复述。
34
+ - 声音连续可在后期让旁白跨越切点;生成单元的声音限制写清“无新增人声”,需要环境声时单列。配乐若采用,保持不掩盖口播,具体音量处理交给后期,不承诺生成器精确混音。
35
+ - 商品名称、价格、优惠、按钮/二维码等准确文字列入后期叠加清单,给构图留位置;不要依赖视频模型生成可读文字。用户现有 Logo/界面可直接作为待剪辑素材,不声称当前工具已完成叠加。
36
+
37
+ ## 必须交付的商业分镜表
38
+
39
+ | 全片区间 | 信息目的 | A-roll/B-roll及具体画面 | 台词ID与逐字原文 | 发声方式/窗口/停顿重音 | 切点与素材 | 结束状态 |
40
+ |---|---|---|---|---|---|---|
41
+
42
+ 表后分别输出人物口播 prompt、B-roll prompt、配音脚本及合成说明;用户只需提示词时可精简,但仍保留台词和声音归属。全片时间轴与生成 prompt 的本地 0 秒时间轴分别注明。剪辑使用的 2–3 秒片段可能来自更长的生成素材,不提交低于模型最小时长的请求;总片长按实际使用的片段计算。
43
+
44
+ 原生音画方案要逐句验收;独立配音方案用 `voice_clone`,同角色沿用音色参考及语速设置,按句段生成后审听。独立配音不代表人物嘴型已对齐;镜头合成、口型修复、精确字幕和音乐混合仍是当前插件未执行的后期步骤。没有对应工具时交付素材、时间表和待处理项,不报告已合成商业成片。
45
+
46
+ ## 精简示例:30秒桌面收纳盒推广
47
+
48
+ 假设用户已确认:产品有分区、能放入笔和便签;目标是产品认知,结尾引导查看详情;专业亲切、9:16、无配乐。下列文案为新创作示例,实际项目优先保留用户确认的台词。产品与人物参考图待提供,本例不虚构素材编号。
49
+
50
+ | 全片区间 | 画面/信息 | 完整台词与声音 | 表演/节奏 |
51
+ |---|---|---|---|
52
+ | 0–8秒 | A-roll,人物中近景建立需求 | 0.5–7秒,画内:“桌上的笔和便签,总是找不到?试试分区收纳。” | 直视镜头、轻微微笑;问句后停约0.4秒;结尾留反应 |
53
+ | 8–16秒 | B-roll,桌面俯拍,依次放入笔、便签 | 8.5–15.5秒,同音色旁白:“把笔放在这里,便签放在旁边,常用的小物各有位置。” | 画面动作跟随物品名称,摆放完留时间看清 |
54
+ | 16–24秒 | B-roll,整理后全貌→取笔使用 | 16.5–23.5秒,同音色旁白:“整理好,桌面更清楚;要用的时候,伸手就能拿到。” | 全貌先展示,再取笔;不变出额外配件 |
55
+ | 24–30秒 | A-roll,回到同一人物与布景 | 24.5–29秒,画内:“适合你的桌面吗?点开详情看看。” | 自然邀请、不催喊;句末闭口,视线保持至结束 |
56
+
57
+ A-roll 单元示例(8秒,本地时间):
58
+
59
+ ```text
60
+ 9:16,明亮整洁的办公布景,专业亲切的商业产品讲解。人物外形与服装使用已确认设定,眼平中近景,固定机位,嘴部无遮挡,直视镜头,肩颈放松。
61
+ 0–0.5秒自然吸气并建立目光交流;0.5–7秒用普通话清楚说:“桌上的笔和便签,总是找不到?试试分区收纳。”问句后稍停,后半句温和肯定;只在说到分区收纳时做一次小幅开放手势。7–8秒闭口,保持自然微笑。
62
+ 只有该人物说话,声音清晰,无配乐,无自动生成的叠加文字。
63
+ ```
64
+
65
+ B-roll 单元示例(8秒,本地时间,对应全片8–16秒):
66
+
67
+ ```text
68
+ 9:16,同一办公环境与光线,真实商业产品展示。分区收纳盒置于桌面中央,产品外观使用用户确认的素材。固定俯拍,关键格口清晰可见。
69
+ 0–1秒展示空置格口;1–4秒一只手将笔放入对应分区,再把便签放进旁边格口;4–8秒手退出,保留整理后的全貌。物体位置稳定,不新增配件。
70
+ 无生成对白或旁白,无配乐;本段人声由后期叠加已确认的同音色口播音轨。
71
+ ```
72
+
73
+ 以上是独立素材的目标编排,不代表已合成;实际使用前核算对白、审听并按需要调整窗口或片长。
@@ -0,0 +1,52 @@
1
+ # 交付模板与对白示例
2
+
3
+ ## 制作计划模板
4
+
5
+ 创作简报:类型 / 一句话故事 / 总时长 / 画幅 / 风格 / 模型 / 对白方案 / 执行范围。
6
+
7
+ | 单元 | 场景及戏剧功能 | 目标时长 | 镜头与可见动作 | 台词 ID / 窗口 | 起始→结束状态 |
8
+ |---|---|---|---|---|---|
9
+ | U01 | … | … | … | … | … |
10
+
11
+ 资产表记录 C/S/P/V ID、内容和真实素材状态。对白表记录 D ID、说话人、原文、发声类型、语言、窗口、是否可改写。片段之间记录服装、站位、光线、道具结果。计划时间轴可用全片时间,投喂时间轴必须从本单元 0 秒开始。
12
+
13
+ ## 示例:把“她质问他有没有早知道”变成一次可执行请求
14
+
15
+ 用户已指定:真人都市短剧、9:16、wan-3.0、原生普通话对白、一个 8 秒视频。对白原文:“你早就知道了,对不对?”不允许改写。当前只有一张女主定妆图和一张客厅参考图,均已上传;没有声音参考。
16
+
17
+ 资产映射:C01 林岚(黑色齐肩发、米白针织衫)→图1;S01 客厅(沙发在后景,门位于画面右侧)→图2。P01 白色信封从开始到结束压在林岚左手下。对手在镜头外的画面右侧,不虚构第二张人物参考图。
18
+
19
+ 对白 D01:林岚,画内普通话,原文 10 汉字,1.5–5.5 秒目标窗口,留足停顿。音色是本次描述目标,无参考声纹保证。
20
+
21
+ 可复制 prompt:
22
+
23
+ ```text
24
+ 8秒,9:16,真人都市短剧,自然肤质与柔和室内侧光。图1是林岚的外形与服装参考:黑色齐肩发,米白针织衫。图2是客厅空间参考:沙发在后景,房门位于画面右侧。林岚坐在桌前,左手压住白色信封,身体朝向画面右侧的镜外对手。
25
+ 全段一个眼平中近景,机位缓慢轻推,保持脸与嘴部清晰可见,不切镜。
26
+ 0–1.5秒:她看向画面右侧的对手,指尖停在信封上,下颌略收紧,吸一口气。
27
+ 1.5–5.5秒:只有林岚开口,用普通话、压低而克制的声音说:“你早就知道了,对不对?”前半句试探,逗号处短暂停顿,句尾质问。镜外对手全程不说话。
28
+ 5.5–8秒:她闭口等待回答,目光保持在对手方向,左手仍压住信封。
29
+ 保留轻微室内底噪与衣料声,无配乐,无叠加字幕、Logo或水印。服装、信封位置与主光方向全段稳定。
30
+ ```
31
+
32
+ 提交参数示意(下方占位 URL 不能直接提交,执行时替换为真实上传结果):
33
+
34
+ ```json
35
+ {
36
+ "model": "wan-3.0",
37
+ "prompt": "使用上方完整 prompt 文本",
38
+ "duration": "8",
39
+ "aspectRatio": "9:16",
40
+ "imageUrls": ["<C01实际HTTPS地址>", "<S01实际HTTPS地址>"]
41
+ }
42
+ ```
43
+
44
+ 本例无音频,不生成 `audioUrls` 或 `audioDurations`。若后来添加真实音频参考,单独绑定“音频1”为林岚音色参考,按执行工具要求提供对应时长,不能把它叫作“图3中的音色”。
45
+
46
+ 验收:逐字核对 D01、检查嘴部与声音同步、确认信封没有移动或增殖。此文件只是编排示例,不代表已调用模型或成片已通过验收。
47
+
48
+ ## 多人及长台词变体
49
+
50
+ 若对手回答“我只是想保护你”,新建 U02 与独立素材映射,继承客厅与信封状态;重复必要设定,不引用“同上”。回答者参考图缺失时先标记待补,或说明本次仅按文字描述,不能假设它已在 imageUrls 中。
51
+
52
+ 若用户要求一段长独白 8 秒内说完,先核算字数与停顿,再给出选择:A 延长或拆段并保持原文(准确优先时推荐);B 允许压缩台词(给出改写对照);C 保留音频并改为画外音/反应镜头(须用户接受视听变化)。不直接提交超载提示词。
@@ -0,0 +1,76 @@
1
+ # 镜头、对白与模型适配
2
+
3
+ ## 将粗提示词变成可执行指令
4
+
5
+ 优先级:本镜头的叙事动作 → 主体与空间 → 可观察的表演 → 景别和运动 → 对白窗口 → 少量风格约束。一个主要运镜即可,避免同一时刻推、拉、绕、摇。镜头数量由可执行性决定,不强求每段正反打,也不强迫长对白一镜多切。
6
+
7
+ 写清左右与视线的参照系(例如画面左侧、朝画面右侧看),用关键空间点维持轴线。数字时间轴是编排目标,不承诺生成器严格按帧执行。时间特别敏感的切镜可拆成独立请求、留给后期剪辑。
8
+
9
+ 风格沿用用户选择。真人写实可用自然肤质、单一光向、真实材质等少量具体锚点;动画则按其视觉体系设计。摄影机和镜头型号仅在有明确视觉作用时使用。负向约束聚焦本单元易错项,如“另一人保持闭口、无叠加字幕、手中只有一份文件”,不要用几十条禁令挤占动作和台词指令。接口没有独立负向字段时,必要限制写在 prompt 内。
10
+
11
+ ## 台词清单与时长核算
12
+
13
+ 为每句建立 D01…:说话人、原文、发声类型(画内/画外/旁白)、语言与口音、情绪、可用秒数、是否允许改写。台词用引号隔离,只出现一次,不把导演说明放进引号。不能同时要求同一角色说两句不相容的文本。
14
+
15
+ 中文可以先按每秒 3–4 个汉字粗估正常对白,犹豫、哭泣、强调需更慢,再加停顿与表演余量;这是编排启发式,不是模型能力保证。标点不按发音字数计,数字/缩写按实际读法展开核算;英语等语言按口读/音节或实际音频时长估算。已有录音用实际时长优先。
16
+
17
+ 例:“你早就知道了,对不对?”共 10 个汉字,正常口读约 2.5–3.4 秒,另留停顿和反应;若分配 1 秒应判定超载。窗口不足时先延长、拆镜头或提出压缩建议,不能擅自改掉原台词。全段还须留出起势、收尾与反应时间,不把全部时长填满说话。
18
+
19
+ ## 原生对白尝试
20
+
21
+ - 优先单一说话人近景/中近景,脸部稳定可见、嘴无遮挡,听者闭口;为回答单独安排镜头或生成单元。
22
+ - 说明语言、说话人和完整短句,给足发声窗口,顺序为开口准备→完整说完→停顿反应。
23
+ - 说话时避免复杂走位、奔跑、多人同时动作和快速切镜。保留必要戏剧表演,不把角色做成机械播报员。
24
+ - 音色参考、对白文本与镜头三者分别描述。没有音频则用音色描述,不伪造参考。
25
+ - 这套约束只能降低任务复杂度,不能保证生成器逐字、口型或声纹准确。不得写“已保证台词无误”。
26
+
27
+ ## 逐字准确优先
28
+
29
+ 冻结对白原文,输出逐句配音脚本及时间窗口。可规划已审听的真人录音/TTS,再做对口型与剪辑;这些是制作步骤,只有有对应工具且已执行后才能报告完成。当前插件可通过 voice_clone 按提示词或参考音色生成独立语音,具体参数见执行 skill;仍没有转写、口型修复或剪辑工具。先审听生成的语音,再规划后续音画制作。
30
+
31
+ 若用户提供录音,可上传作参考,但不把参考音频视为强制音轨或口型驱动的保证。需要口型准确且当前工具无法确认支持时,明确保留后期环节。画外音/听者反应镜头可以降低可见口型要求,但会改变视听设计,作为用户可选方案而非悄悄替换画内对白。
32
+
33
+ ## drama-3.5 的使用策略
34
+
35
+ 仓库适配器为 `drama-3.5` 接受 4–30 秒;该范围只反映本插件校验,不证明平台实时能力或原生语音质量。先读取实际模型清单和执行说明。
36
+
37
+ 针对用户反馈的台词、镜头失准,建议从 6–10 秒、一个主动作、一名主要说话人、固定或轻推机位开始设计。这是本工作流的保守起点,不是上游官方硬限制;根据台词长度和用户目标调整。多人对话拆成“说话→听者反应→回答”,不要在一个请求塞满整场戏。用户指定其他模型时保留同样的负荷检查,不能据此无依据排名或自动切模型。
38
+
39
+ ## 失败诊断
40
+
41
+ | 可观察问题 | 优先调整 | 验收要点 |
42
+ |---|---|---|
43
+ | 漏字、改字、尾句截断 | 原文冻结、扩大对白窗口、缩短非语言动作 | 逐句对照原文 |
44
+ | 串话、两人同时开口 | 每单元单说话人、明确听者闭口 | 声音与角色对应 |
45
+ | 运镜和剧情都没完成 | 减少切镜与动作,只保留本段核心节拍 | 起始→动作→结束可见 |
46
+ | 人脸/服装漂移 | 修正实际素材顺序与构图,减少遮挡 | 与资产表/参考对照 |
47
+ | 口型不匹配 | 降低转头和遮挡;准确优先转后期方案 | 可见发音与音轨对应 |
48
+
49
+ 不能查看或收听时,只报告待核验项;不能用提示词自检代替成片验收。
50
+
51
+
52
+ ## 动作戏与武侠段落
53
+
54
+ 按需要采用以下规则,保持提示词简洁;具体地点、人物、摄影器材和视觉风格随项目确定。
55
+
56
+ 1. **风格用可见特征表达**:东方武侠可采用对称构图、仪式感站位、克制色彩与关键瞬间慢动作;真人方向保留皮肤、布料和环境材质。摄影机、焦距或渲染器名称按视觉需要选用,不堆叠为画质口号,也不把这套美学套给所有动作片。
57
+ 2. **先锁身份与空间**:固定角色 ID、外观、服装、武器及关键饰物;交锋双方与神兽分别绑定真实素材。先用建立镜头交代距离、左右、落脚点、障碍和高差;明确场景结构图与全景构图图各自用途。后续不得互换攻防者、无故掉帽或改变平台尺度。
58
+ 3. **动作写成因果链**:准备姿态→蹬地/转胯等发力→出招方向与目标→接触或闪避→失衡/后退→结束姿态。交代重心、支撑脚及力量传递,衣摆、发丝和持物随惯性响应,避免只有“激烈打斗”和无落点的挥舞。腾空、掌力等超现实动作遵循作品已设定的规则。
59
+ 4. **让镜头看懂动作**:全/中景交代交锋,近景强调蓄力、接触或反应;动作方向和视线维持轴线。每镜保留主要动作与主要运镜,慢动作只强调关键拍点。快速攻击与慢速反应分配不同时间,不把长过程塞进半秒。
60
+ 5. **特效有来源与反馈**:标明能量由谁、从何处发出、沿何方向到达何目标;设定生物/能量的大小、距离及出现消退顺序。光效只影响邻近皮肤、衣料与地面;雪、尘、水及布料的变化对应风、冲击或能量,不随意爆闪、全景过曝或大量粒子遮住动作。
61
+ 6. **反转要留反应时间**:先建立力量预期,再揭示真实结果,再给人物反应;冷幽默用严肃表演、停顿和尺度反差。神兽若从威严特写揭示为微型,应说明先前是构图误导,实际尺寸稳定;随后位置、附着状态、积雪或伤痕持续承接。
62
+ 7. **声音跟随动作**:按节拍写呼吸、脚步、衣料、碰撞、气流及环境声;用户要求无 BGM 时,每个执行单元明确无配乐。对白另留完整窗口,不与复杂出招挤在同一瞬间;长对白可先用 voice_clone 制作独立配音,音画同步仍需验收或后期。
63
+ 8. **先修冲突再投喂**:原稿角色称谓/参考图矛盾时列出冲突,阻塞身份的用选择题确认;检查动作、对白、反应是否都能在窗口内完成。制作表的零点几秒剪辑镜头不等于独立生成请求,按目标模型时长范围合理组合或延长,不强行保留过密时间码。
64
+
65
+ 精简投喂骨架:
66
+
67
+ ```text
68
+ [时长/画幅/视觉风格]。图1绑定角色C01,图2绑定角色C02;[场景素材及必要外观]。
69
+ 空间:[双方画面位置、距离、支撑面及光向]。
70
+ 前段:[景别/机位],C01[准备→发力→出招方向],C02[防守或闪避]。
71
+ 中段:[接触/落空→受力结果],伴随[有来源的雪尘/布料/光照反馈]。
72
+ 后段:[结束姿态/反应],承接[道具、角色与环境状态]。
73
+ 声音:[对应动作声与台词窗口];[按用户要求无配乐]。
74
+ ```
75
+
76
+ 按实际上传顺序重写图号,未提供的素材绑定需删除或标为待补;骨架中的前中后段按动作与对白核算具体窗口。
package/package.json CHANGED
@@ -1,6 +1,33 @@
1
1
  {
2
2
  "name": "@gensor/gensor-drama",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "AI炸城:小炸短剧短片导演与图片、视频、语音生成插件,一键安装到 Codex",
5
+ "type": "module",
6
+ "bin": {
7
+ "gensor-drama": "./bin/cli.mjs"
8
+ },
9
+ "files": [
10
+ "bin/",
11
+ ".agents/plugins/marketplace.json",
12
+ "gensor-agent/.codex-plugin/plugin.json",
13
+ "gensor-agent/.mcp.json",
14
+ "gensor-agent/assets/",
15
+ "gensor-agent/skills/",
16
+ "gensor-agent/server/src/"
17
+ ],
18
+ "engines": {
19
+ "node": ">=22"
20
+ },
21
+ "publishConfig": {
22
+ "access": "public"
23
+ },
24
+ "scripts": {
25
+ "test": "node --test test/*.test.mjs && npm test --prefix gensor-agent/server",
26
+ "test:installer": "node --test test/*.test.mjs",
27
+ "test:package": "node scripts/smoke-package.mjs"
28
+ },
29
+ "dependencies": {
30
+ "@modelcontextprotocol/sdk": "1.32.2",
31
+ "zod": "4.6.7"
32
+ }
33
+ }