dsh-agnes-create 0.7.0 → 0.11.0

package/README.md

@@ -53,10 +53,10 @@ Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认
 
 1. 侧边栏点 **Agnes创作**
 2. 顶部选择 **图片** 或 **视频**
-3. 输入提示词，`Cmd/Ctrl + Enter` 或点按钮生成；提示词上方有 6 个风格预设（写实摄影 / 水彩 / 3D 渲染 / 海报 / 夜景霓虹 / 极简），点一下追加到末尾，不会冲掉已写的主体
+3. 输入提示词，`Cmd/Ctrl + Enter` 或点按钮生成；提示词上方有 6 个内置风格预设（写实摄影 / 水彩 / 3D 渲染 / 海报 / 夜景霓虹 / 极简），点一下追加到末尾，不会冲掉已写的主体；也可以把自己的常用提示词存成预设，或者点 **扩写** 让模型把那句简短描述补全
 4. 想放弃等待就点生成按钮旁的 **取消**（只是停止本地等待，服务端任务可能仍在跑）
 5. 结果直接显示在面板里；图片用 `<img>`、视频用 `<video>` 播放（支持拖动进度条）
-6. 结果下方三个按钮：**复制路径**（写到剪贴板）、**在访达中显示**（定位到文件）、**下载**（另存一份到「下载」目录）；如果结果本身是图片，还会多出 **设为首帧** / **设为尾帧**，一键把它变成下一段视频的关键帧
+6. 结果下方四个按钮：**复制路径**（写到剪贴板）、**在访达中显示**（定位到文件）、**下载**（另存一份到「下载」目录）、**新窗口打开**（在浏览器新标签页里看原图 / 播放原视频）；如果结果本身是图片，还会多出 **设为首帧** / **设为尾帧**，一键把它变成下一段视频的关键帧
 7. 生成过的内容记在面板底部「最近生成」里，最多 24 条，落盘到 `~/.dsh/agnes-create/history.json`，重启应用也不丢
 
 提示词建议按「主体 + 场景 + 动作/镜头 + 光线 + 风格 + 构图」组织，例如：
@@ -114,6 +114,20 @@ Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认
 
 > 关键帧只在视频模式出现；图片模式用的是上面的「参考图」。
 
+### 参考生视频（参考图，最多 5 张）
+
+视频模式还有一栏「参考图」，用来给上游参考**风格、主体或构图**，而不是指定起止画面。最多 5 张，来源同样是「＋ 本地」和「＋ 结果」。
+
+| 给了什么 | 实际行为 |
+| --- | --- |
+| 只有参考图 | 按参考图的风格 / 主体 / 构图生成新视频（`mode: reference`） |
+| 参考图 + 首帧或尾帧 | 按关键帧生成，**参考图本次不生效**（面板会提示） |
+| 什么都不给 | 纯文生视频 |
+
+同样以 data URI 直接发给上游，不需要图床。结果信息里会标注「参考生视频」，和「图生视频」「纯文生视频」区分开。
+
+> 三种模式的优先级：关键帧 > 参考图 > 纯文本。
+
 ### 提示词随图保存
 
 出图时会把这次的提示词写进图片文件本身（PNG 用 iTXt 块、JPEG 用 COM 段），所以：
@@ -130,6 +144,37 @@ Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认
 - 点任意一张就把它显示到上方结果区，图片会连带读回当初写在文件里的提示词；
 - 只读不写，不会改动或删除你的文件；「刷新」用于同步新生成的文件。
 
+### 顶部直接切换模型
+
+标题栏「Agnes 创作」右边的模型名可以点开：图片模式列图片模型、视频模式列视频模型，选中后**立刻保存**，不用进设置。
+
+- 选项优先用「设置 → 测试连接」探测到的上游真实清单（更可信），没测过时用内置清单
+- 内置清单：图片 `agnes-image-2.5-flash` / `agnes-image-2.1-flash`，视频 `agnes-video-2.5-flash` / `agnes-video-2.5`
+- 只有 1 个可选时仍然显示为纯文本，不弹空下拉
+
+### 自定义提示词预设与扩写
+
+提示词上方那排 chip 里，除了 6 个内置风格，还能放自己的：
+
+- **＋ 存为预设** —— 把当前输入的整段提示词存下来。会展开一个输入框让你取名字（留空则取提示词前 10 个字），回车或点「保存」即存，存完立刻出现在 chip 里
+- 点自己的预设 = 追加到当前提示词末尾（和内置预设的拼接规则一样：先去掉尾部标点，再用「，」连接），不会覆盖已经写好的主体
+- 预设 chip 右侧的 **×** 删除它，点了就生效，没有二次确认
+- **扩写** —— 把一句话变成一段完整的画面描述：图片模式补主体外观、环境、光线、镜头与构图；视频模式补动作推进、镜头运动、景别与氛围。扩写结果直接替换输入框内容，多花一次文本模型的调用（约 160 tokens，几分钱）
+
+预设落盘到 `~/.dsh/agnes-create/presets.json`，重启应用不丢；最多 40 条，名称截到 20 字、内容截到 600 字，同名再存会覆盖并置顶。
+
+### 在对话里直接出图 / 出视频
+
+除了侧边栏面板，插件还把三个模型工具交给宿主，所以你直接对 agent 说「画一只坐在窗台上的橘猫」它就能出图：
+
+| 工具 | 作用 | 主要参数 |
+| --- | --- | --- |
+| `agnes_image` | 出图，等结果落盘后返回路径 | `prompt`、`size`（1K–4K）、`ratio`、`images`（≤8，URL 或 data URI） |
+| `agnes_video` | 提交视频任务，**立刻返回任务号**（不阻塞） | `prompt`、`seconds`（4–12）、`ratio`、`seed`、`first_frame`、`last_frame`、`reference_images`（≤5） |
+| `agnes_video_status` | 查视频任务进度 / 取结果路径 | `task_id`（留空则列出最近的几笔） |
+
+视频任务由宿主推进，工具只负责提交与查询，所以 agent 不必一直挂着等。宿主没有工具服务时，这三个工具会自动不注册，面板照常可用。
+
 ## 关于费用
 
 插件的费用由 Agnes AI 账号结算，本插件不涉及任何计费。

package/lib/agnes.js

@@ -19,6 +19,11 @@ import { join, basename } from 'node:path';
 export const MODEL = 'agnes-image-2.5-flash';
 export const DEFAULT_BASE = 'https://api.agnes-ai.cn/v1'; // 中国站
 
+/** 画图模型候选：上游 /models 目前只列出这两个图像模型（2.0 已下架）。 */
+export const IMAGE_MODELS = ['agnes-image-2.5-flash', 'agnes-image-2.1-flash'];
+/** 视频模型候选。 */
+export const VIDEO_MODELS = ['agnes-video-2.5-flash', 'agnes-video-2.5'];
+
 /* ==========================================================================
    可配置路径：Key 文件位置 / 输出目录
    --------------------------------------------------------------------------
@@ -55,11 +60,11 @@ const DATA_URI_RE = /^data:image\/(png|jpe?g|webp|gif);base64,[A-Za-z0-9+/=]+$/i
  * 文档要求 extra_body.image 里是「公共图像 URL 或 Data URI Base64」，
  * 所以这里只放行 http(s) 与 data:image 两种，别的直接报错而不是透传给上游。
  */
-export function normalizeRefs(images) {
+export function normalizeRefs(images, limit = MAX_REF_IMAGES) {
   if (images === undefined || images === null) return [];
   if (!Array.isArray(images)) throw new Error('参考图必须是数组');
-  if (images.length > MAX_REF_IMAGES) {
-    throw new Error(`参考图最多 ${MAX_REF_IMAGES} 张，收到 ${images.length} 张`);
+  if (images.length > limit) {
+    throw new Error(`参考图最多 ${limit} 张，收到 ${images.length} 张`);
   }
   return images.map((value, i) => {
     if (typeof value !== 'string' || value.trim() === '') {
@@ -81,6 +86,13 @@ export function expandHome(p) {
   return s;
 }
 
+/** 只接受候选表里的模型名：配置里写了乱七八糟的值就当没写，回退默认。 */
+function pickModel(value, choices) {
+  if (typeof value !== 'string') return null;
+  const name = value.trim();
+  return choices.includes(name) ? name : null;
+}
+
 /**
  * 解析生效配置。
  * 配置文件不存在或内容损坏时一律退回默认值 —— 配置坏了不该把插件拖死。
@@ -98,10 +110,15 @@ export async function resolvePaths() {
       if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) {
         stored = raw;
         configFile = CONFIG_FILE;
-        await saveConfig({
-          keyFile: typeof raw.keyFile === 'string' ? raw.keyFile : null,
-          outDir: typeof raw.outDir === 'string' ? raw.outDir : null,
-        }).catch(() => { /* 迁移失败不影响本次读取 */ });
+        // 直接写文件，别调 saveConfig()：saveConfig 内部会先 resolvePaths()，
+        // 而此刻新配置还没落盘，于是又走到这里 —— 无限递归。
+        const migrated = {};
+        if (typeof raw.keyFile === 'string' && raw.keyFile.trim() !== '') migrated.keyFile = raw.keyFile.trim();
+        if (typeof raw.outDir === 'string' && raw.outDir.trim() !== '') migrated.outDir = raw.outDir.trim();
+        if (typeof raw.imageModel === 'string') migrated.imageModel = raw.imageModel;
+        if (typeof raw.videoModel === 'string') migrated.videoModel = raw.videoModel;
+        await mkdir(CONFIG_DIR, { recursive: true });
+        await writeFile(CONFIG_FILE, JSON.stringify(migrated, null, 2) + '\n', 'utf8');
       }
     } catch { /* 旧配置也没有 → 用默认 */ }
   }
@@ -111,14 +128,29 @@ export async function resolvePaths() {
   const storedOut = typeof stored.outDir === 'string' && stored.outDir.trim() !== ''
     ? expandHome(stored.outDir) : null;
 
+  const storedImageModel = pickModel(stored.imageModel, IMAGE_MODELS);
+  const storedVideoModel = pickModel(stored.videoModel, VIDEO_MODELS);
+
   return {
     keyFile: storedKey ?? (process.env.AGNES_KEY_FILE || DEFAULT_KEY_FILE),
     outDir: storedOut ?? (process.env.AGNES_OUT_DIR || DEFAULT_OUT_DIR),
+    imageModel: storedImageModel ?? MODEL,
+    videoModel: storedVideoModel ?? VIDEO_MODEL,
     configFile,
     legacyConfigFile: LEGACY_CONFIG_FILE,
     historyFile: HISTORY_FILE,
-    defaults: { keyFile: DEFAULT_KEY_FILE, outDir: DEFAULT_OUT_DIR },
-    stored: { keyFile: storedKey, outDir: storedOut },
+    defaults: {
+      keyFile: DEFAULT_KEY_FILE,
+      outDir: DEFAULT_OUT_DIR,
+      imageModel: MODEL,
+      videoModel: VIDEO_MODEL,
+    },
+    stored: {
+      keyFile: storedKey,
+      outDir: storedOut,
+      imageModel: storedImageModel,
+      videoModel: storedVideoModel,
+    },
   };
 }
 
@@ -133,8 +165,22 @@ export async function saveConfig(patch = {}) {
   const next = {
     keyFile: patch.keyFile === undefined ? current.stored.keyFile : patch.keyFile,
     outDir: patch.outDir === undefined ? current.stored.outDir : patch.outDir,
+    imageModel: patch.imageModel === undefined ? current.stored.imageModel : patch.imageModel,
+    videoModel: patch.videoModel === undefined ? current.stored.videoModel : patch.videoModel,
   };
 
+  for (const [field, label, choices] of [
+    ['imageModel', '图片模型', IMAGE_MODELS],
+    ['videoModel', '视频模型', VIDEO_MODELS],
+  ]) {
+    const v = next[field];
+    if (v === null) continue; // 清空 = 回退默认
+    if (typeof v !== 'string' || !choices.includes(v.trim())) {
+      throw new Error(`${label}不在可选范围内：${choices.join(' / ')}`);
+    }
+    next[field] = v.trim();
+  }
+
   for (const [field, label] of [['keyFile', 'Key 文件路径'], ['outDir', '输出目录']]) {
     const v = next[field];
     if (v === null) continue; // 允许清空回默认
@@ -149,6 +195,8 @@ export async function saveConfig(patch = {}) {
   const payload = {};
   if (typeof next.keyFile === 'string') payload.keyFile = next.keyFile;
   if (typeof next.outDir === 'string') payload.outDir = next.outDir;
+  if (typeof next.imageModel === 'string') payload.imageModel = next.imageModel;
+  if (typeof next.videoModel === 'string') payload.videoModel = next.videoModel;
 
   await mkdir(CONFIG_DIR, { recursive: true });
   await writeFile(CONFIG_FILE, JSON.stringify(payload, null, 2) + '\n', 'utf8');
@@ -218,7 +266,229 @@ export async function clearHistory() {
   return { entries: [], file: HISTORY_FILE };
 }
 
+/* ==========================================================================
+   自定义提示词预设
+   --------------------------------------------------------------------------
+   内置的 6 个风格 chip 写死在客户端（纯展示，不用存）；用户自己存的走这里，
+   落到 ~/.dsh/agnes-create/presets.json —— 跨会话、重启都还在。
+   同名视为覆盖（存两次同一名字不会出现两条）。
+   ========================================================================== */
+
+export const PRESETS_FILE = join(CONFIG_DIR, 'presets.json');
+export const PRESET_MAX = 40;
+export const PRESET_LABEL_MAX = 20;
+export const PRESET_TEXT_MAX = 600;
+
+function sanitizePreset(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const label = typeof raw.label === 'string' ? raw.label.trim().replace(/\s+/g, ' ') : '';
+  const text = typeof raw.text === 'string' ? raw.text.trim() : '';
+  if (label === '' || text === '') return null;
+  return { label: label.slice(0, PRESET_LABEL_MAX), text: text.slice(0, PRESET_TEXT_MAX) };
+}
+
+export async function readPresets() {
+  try {
+    const raw = JSON.parse(await readFile(PRESETS_FILE, 'utf8'));
+    const list = Array.isArray(raw) ? raw : (Array.isArray(raw?.presets) ? raw.presets : []);
+    const seen = new Set();
+    const presets = [];
+    for (const item of list) {
+      const clean = sanitizePreset(item);
+      if (clean === null || seen.has(clean.label)) continue;
+      seen.add(clean.label);
+      presets.push(clean);
+    }
+    return { presets: presets.slice(0, PRESET_MAX), file: PRESETS_FILE };
+  } catch {
+    return { presets: [], file: PRESETS_FILE };
+  }
+}
+
+/** 存一条预设（同名覆盖并置顶）。返回最新列表。 */
+export async function savePreset(entry) {
+  const clean = sanitizePreset(entry);
+  if (clean === null) throw new Error('预设需要名称和内容');
+  const { presets } = await readPresets();
+  const next = [clean, ...presets.filter((p) => p.label !== clean.label)].slice(0, PRESET_MAX);
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(PRESETS_FILE, JSON.stringify(next, null, 2) + '\n', 'utf8');
+  return { presets: next, file: PRESETS_FILE };
+}
+
+/** 删一条预设。名字不存在时也返回成功（幂等），列表不变。 */
+export async function removePreset(label) {
+  const name = typeof label === 'string' ? label.trim() : '';
+  if (name === '') throw new Error('缺少预设名称');
+  const { presets } = await readPresets();
+  const next = presets.filter((p) => p.label !== name);
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(PRESETS_FILE, JSON.stringify(next, null, 2) + '\n', 'utf8');
+  return { presets: next, file: PRESETS_FILE };
+}
+
+/* ==========================================================================
+   视频任务（落盘 + 宿主侧轮询）
+   --------------------------------------------------------------------------
+   从前轮询在前端，刷新 / 关面板 / 崩溃就丢；现在任务表在宿主进程里，
+   写进 tasks.json，应用重启后把「排队中 / 生成中」的任务重新接管。
+   ========================================================================== */
+
+export const TASKS_FILE = join(CONFIG_DIR, 'tasks.json');
+export const TASK_MAX = 50;
+
+/** 还在跑、需要继续轮询的状态。 */
+export const TASK_ACTIVE = ['queued', 'running'];
+
+const TASK_STATUS = ['queued', 'running', 'completed', 'failed', 'cancelled'];
+
+function sanitizeTask(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const id = typeof raw.id === 'string' ? raw.id.trim() : '';
+  if (id === '') return null;
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+  const status = TASK_STATUS.includes(raw.status) ? raw.status : 'queued';
+  return {
+    id,
+    kind: 'video',
+    status,
+    progress: num(raw.progress) ?? 0,
+    videoId: str(raw.videoId),
+    mode: raw.mode === 'keyframe' ? 'keyframe' : 'text',
+    prompt: str(raw.prompt)?.slice(0, 500) ?? null,
+    seconds: str(raw.seconds),
+    ratio: str(raw.ratio),
+    seed: num(raw.seed),
+    filename: str(raw.filename),
+    path: str(raw.path),
+    bytes: num(raw.bytes),
+    error: str(raw.error),
+    createdAt: str(raw.createdAt) ?? new Date().toISOString(),
+    updatedAt: str(raw.updatedAt) ?? new Date().toISOString(),
+  };
+}
+
+export async function readTasks() {
+  try {
+    const raw = JSON.parse(await readFile(TASKS_FILE, 'utf8'));
+    const list = Array.isArray(raw) ? raw : (Array.isArray(raw?.tasks) ? raw.tasks : []);
+    return list.map(sanitizeTask).filter((x) => x !== null).slice(0, TASK_MAX);
+  } catch {
+    return [];
+  }
+}
+
+export async function writeTasks(tasks) {
+  const list = (Array.isArray(tasks) ? tasks : []).map(sanitizeTask).filter((x) => x !== null).slice(0, TASK_MAX);
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(TASKS_FILE, JSON.stringify(list, null, 2) + '\n', 'utf8');
+  return list;
+}
+
 /** 读 Key。不传 file 则按当前配置解析。 */
+/**
+ * 问上游要模型清单，用来做「测试连接」和填下拉选项。
+ * 顺带区分三种失败：Key 不对（401/403）、额度/限流（429）、网络或服务异常。
+ */
+export async function listModels({ baseUrl = DEFAULT_BASE, key } = {}) {
+  const k = key ?? (await readKey());
+  if (!k) throw new Error('没有找到 API Key，先确认 Key 文件路径');
+  let res;
+  try {
+    res = await fetch(`${baseUrl.replace(/\/+$/, '')}/models`, {
+      headers: { Authorization: `Bearer ${k}` },
+      signal: AbortSignal.timeout(20_000),
+    });
+  } catch (e) {
+    throw new Error(`连不上上游：${e && e.message ? e.message : String(e)}`);
+  }
+  if (res.status === 401 || res.status === 403) throw new Error('Key 无效或已过期（HTTP ' + res.status + '）');
+  if (res.status === 429) throw new Error('上游限流（HTTP 429），稍后再试');
+  if (!res.ok) throw new Error('上游返回 HTTP ' + res.status);
+
+  const payload = await res.json().catch(() => null);
+  const rows = payload && Array.isArray(payload.data) ? payload.data : [];
+  const ids = rows.map((r) => (r && typeof r.id === 'string' ? r.id : '')).filter(Boolean);
+  return {
+    models: ids,
+    image: ids.filter((id) => id.startsWith('agnes-image-')),
+    video: ids.filter((id) => id.startsWith('agnes-video-')),
+  };
+}
+
+/* ==========================================================================
+   提示词扩写（借上游文本模型）
+   --------------------------------------------------------------------------
+   实测契约（2026-11-12）：POST /v1/chat/completions，OpenAI 兼容；
+   model=agnes-2.5-flash 可用，正文在 choices[0].message.content，约 160 tokens/次。
+   图片与视频的扩写侧重不同，所以按 kind 换系统提示。
+   ========================================================================== */
+
+export const EXPAND_MODEL = 'agnes-2.5-flash';
+export const EXPAND_MAX_INPUT = 1000;
+export const EXPAND_MAX_OUTPUT = 1200;
+export const EXPAND_TIMEOUT_MS = 60_000;
+
+const EXPAND_SYSTEM_IMAGE =
+  '你是图像提示词工程师。把用户给的简短想法扩写成一段具体的画面描述：'
+  + '补上主体外观与动作、环境细节、光线方向与质感、镜头视角与构图。'
+  + '只输出这一段中文描述，不要解释，不要分点，不要加引号，不要写「提示词：」这类前缀。';
+
+const EXPAND_SYSTEM_VIDEO =
+  '你是视频提示词工程师。把用户给的简短想法扩写成一段可执行的视频描述：'
+  + '包含主体动作的推进、镜头运动（推拉摇移或固定）、景别变化、光线与氛围，'
+  + '时长按 5 秒左右的节奏来写，不要出现分镜编号或时间码。'
+  + '只输出这一段中文描述，不要解释，不要分点，不要加引号。';
+
+/** 把一句话扩写成一段提示词。kind: 'image' | 'video'。 */
+export async function expandPrompt(prompt, { kind = 'image', model = EXPAND_MODEL, key, baseUrl = DEFAULT_BASE } = {}) {
+  const text = typeof prompt === 'string' ? prompt.trim() : '';
+  if (text === '') throw new Error('先写一句想画什么，再来扩写');
+  if (text.length > EXPAND_MAX_INPUT) throw new Error(`提示词太长（上限 ${EXPAND_MAX_INPUT} 字）`);
+  const k = key ?? (await readKey());
+  if (!k) throw new Error('没有找到 API Key，先确认 Key 文件路径');
+
+  const system = kind === 'video' ? EXPAND_SYSTEM_VIDEO : EXPAND_SYSTEM_IMAGE;
+  let res;
+  try {
+    res = await fetch(`${baseUrl.replace(/\/+$/, '')}/chat/completions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${k}` },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: 'system', content: system },
+          { role: 'user', content: text },
+        ],
+        max_tokens: 400,
+      }),
+      signal: AbortSignal.timeout(EXPAND_TIMEOUT_MS),
+    });
+  } catch (e) {
+    throw new Error(`连不上上游：${e && e.message ? e.message : String(e)}`);
+  }
+  if (res.status === 401 || res.status === 403) throw new Error('Key 无效或已过期（HTTP ' + res.status + '）');
+  if (res.status === 429) throw new Error('上游限流（HTTP 429），稍后再试');
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`上游返回 HTTP ${res.status}${body ? '：' + body.slice(0, 120) : ''}`);
+  }
+
+  const payload = await res.json().catch(() => null);
+  const content = payload && payload.choices && payload.choices[0]
+    ? payload.choices[0].message && payload.choices[0].message.content
+    : '';
+  // 有的模型会自带一对引号或收尾换行，剥掉再返回
+  const out = (typeof content === 'string' ? content : '')
+    .trim()
+    .replace(/^[「“"'`]+/, '')
+    .replace(/[」”"'`]+$/, '')
+    .trim();
+  if (out === '') throw new Error('上游没有返回内容，再试一次');
+  return { prompt: out.slice(0, EXPAND_MAX_OUTPUT), model, usage: (payload && payload.usage) || null };
+}
+
 export async function readKey(file) {
   const target = file ?? (await resolvePaths()).keyFile;
   let raw;
@@ -696,6 +966,9 @@ export const VIDEO_MODEL = 'agnes-video-2.5-flash';
 export const VIDEO_SECONDS = ['4', '5', '6', '7', '8', '9', '10', '11', '12'];
 export const VIDEO_RATIOS = ['21:9', '16:9', '4:3', '1:1', '3:4', '9:16'];
 export const VIDEO_SIZE = '720P';
+
+/** 视频 reference 模式的参考图上限（上游文档：images 最多 5 张）。 */
+export const MAX_VIDEO_REF_IMAGES = 5;
 export const VIDEO_TIMEOUT_MS = 600_000;
 
 /** 从 baseUrl 剥出域名根：/agnesapi 不在 /v1 下。 */
@@ -722,13 +995,14 @@ export async function submitVideo({
   seed = null,
   firstFrame = null,
   lastFrame = null,
+  referenceImages = [],
   retries = 3,
   retryDelayMs = 15_000,
 } = {}) {
   let lastError = null;
   for (let attempt = 0; attempt <= retries; attempt += 1) {
     try {
-      return await submitVideoOnce({ prompt, seconds, ratio, model, baseUrl, seed, firstFrame, lastFrame });
+      return await submitVideoOnce({ prompt, seconds, ratio, model, baseUrl, seed, firstFrame, lastFrame, referenceImages });
     } catch (e) {
       lastError = e;
       const msg = e instanceof Error ? e.message : String(e);
@@ -757,7 +1031,17 @@ function normalizeSeed(seed) {
   return n;
 }
 
-async function submitVideoOnce({ prompt, seconds, ratio, model, baseUrl, seed, firstFrame, lastFrame }) {
+async function submitVideoOnce({
+  prompt,
+  seconds,
+  ratio,
+  model,
+  baseUrl,
+  seed,
+  firstFrame,
+  lastFrame,
+  referenceImages = [],
+}) {
   if (typeof prompt !== 'string' || prompt.trim() === '') throw new Error('prompt 不能为空');
   const sec = String(seconds);
   if (!VIDEO_SECONDS.includes(sec)) {
@@ -767,7 +1051,9 @@ async function submitVideoOnce({ prompt, seconds, ratio, model, baseUrl, seed, f
 
   const first = normalizeFrame(firstFrame, '首帧图');
   const last = normalizeFrame(lastFrame, '尾帧图');
-  const mode = first !== null || last !== null ? 'keyframe' : 'text';
+  const refs = normalizeRefs(referenceImages, MAX_VIDEO_REF_IMAGES);
+  // 关键帧优先：给了首/尾帧就是 keyframe；否则有参考图走 reference；都没有才是纯文本
+  const mode = first !== null || last !== null ? 'keyframe' : refs.length > 0 ? 'reference' : 'text';
   const seedValue = normalizeSeed(seed);
 
   const key = await readKey();
@@ -784,6 +1070,7 @@ async function submitVideoOnce({ prompt, seconds, ratio, model, baseUrl, seed, f
     if (first !== null) body.first_frame = first;
     if (last !== null) body.last_frame = last;
   }
+  if (mode === 'reference') body.images = refs;
   if (seedValue !== null) body.seed = seedValue;
 
   let res;