dsh-agnes-create 0.4.1 → 0.7.0

package/README.md

@@ -53,8 +53,11 @@ Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认
 
 1. 侧边栏点 **Agnes创作**
 2. 顶部选择 **图片** 或 **视频**
-3. 输入提示词，`Cmd/Ctrl + Enter` 或点按钮生成
-4. 结果直接显示在面板里；图片用 `<img>`、视频用 `<video>` 播放（支持拖动进度条）
+3. 输入提示词，`Cmd/Ctrl + Enter` 或点按钮生成；提示词上方有 6 个风格预设（写实摄影 / 水彩 / 3D 渲染 / 海报 / 夜景霓虹 / 极简），点一下追加到末尾，不会冲掉已写的主体
+4. 想放弃等待就点生成按钮旁的 **取消**（只是停止本地等待，服务端任务可能仍在跑）
+5. 结果直接显示在面板里；图片用 `<img>`、视频用 `<video>` 播放（支持拖动进度条）
+6. 结果下方三个按钮：**复制路径**（写到剪贴板）、**在访达中显示**（定位到文件）、**下载**（另存一份到「下载」目录）；如果结果本身是图片，还会多出 **设为首帧** / **设为尾帧**，一键把它变成下一段视频的关键帧
+7. 生成过的内容记在面板底部「最近生成」里，最多 24 条，落盘到 `~/.dsh/agnes-create/history.json`，重启应用也不丢
 
 提示词建议按「主体 + 场景 + 动作/镜头 + 光线 + 风格 + 构图」组织，例如：
 
@@ -67,7 +70,7 @@ Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认
 | 类型 | 尺寸 | 宽高比 | 其它 |
 | --- | --- | --- | --- |
 | 图片 | `1K` `2K` `3K` `4K` | `1:1` `3:4` `4:3` `16:9` `9:16` `2:3` `3:2` `21:9` | 可选 1–8 张参考图（图生图 / 多图合成） |
-| 视频 | 固定 `720P` | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` | 时长 4–12 秒 |
+| 视频 | 固定 `720P` | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` | 时长 4–12 秒，可选首帧 / 尾帧，可选 seed |
 
 ### 图生图 / 多图合成
 
@@ -91,6 +94,42 @@ Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认
 - 校验在前端和内核各做一次：只接受 `http(s)` 或 `data:image/…;base64`，超过 8 张、空串、非图片类型都会直接报错，不会把脏数据发给上游
 - 本地文件路径**不会**被读取或上传到别处：文件内容只在内存里转成 base64 随请求发给 Agnes
 
+### 图生视频（首帧 / 尾帧）
+
+视频模式多出「关键帧」一栏，可以给**首帧**、**尾帧**各选一张图片，也可以只给一张。图片来源有三种：
+
+- **＋ 本地** —— 从磁盘选（PNG / JPEG / WebP / GIF）
+- **＋ 结果** —— 从「最近生成」里已经出过的图片中挑一张（没有生成过图片时按钮是灰的）
+- **结果下方「设为首帧 / 设为尾帧」** —— 当前这张结果图直接变成关键帧，切回视频模式就能看到
+
+| 给了什么 | 实际行为 |
+| --- | --- |
+| 都不给 | 纯文生视频（和以前一样） |
+| 只给首帧 | 从这张图开始动 |
+| 只给尾帧 | 向这张图收尾 |
+| 首帧 + 尾帧 | 从首帧过渡到尾帧（时长决定过渡的快慢） |
+
+- 关键帧同样在浏览器侧压到长边 1280 再编码成 data URI，**直接以 base64 发给上游**，不需要先传到公网图床，本地图片可以直接用
+- 「种子」是可选的非负整数：同一个提示词配同一个 seed 更容易得到相近的结果，留空则由服务端随机；结果下方会显示实际用的 seed
+
+> 关键帧只在视频模式出现；图片模式用的是上面的「参考图」。
+
+### 提示词随图保存
+
+出图时会把这次的提示词写进图片文件本身（PNG 用 iTXt 块、JPEG 用 COM 段），所以：
+
+- 在面板里把鼠标移到结果图上，底部会浮出当初的提示词，点「复制」就能拿到；
+- 用系统看图软件、Photoshop、exiftool 打开也能看到这段文字——不依赖本插件；
+- 只对新生成的图片生效；视频不写（mp4 元数据没有通用写法）。
+
+### 浏览输出目录
+
+结果卡片右上角的 **输出目录** 按钮会把输出目录里已经存在的文件列成缩略图：
+
+- 分「图片 / 视频」两页，各带数量；
+- 点任意一张就把它显示到上方结果区，图片会连带读回当初写在文件里的提示词；
+- 只读不写，不会改动或删除你的文件；「刷新」用于同步新生成的文件。
+
 ## 关于费用
 
 插件的费用由 Agnes AI 账号结算，本插件不涉及任何计费。
@@ -104,9 +143,9 @@ Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认
 
 - 视频为**异步任务**：提交后轮询，通常需要 1–4 分钟；队列繁忙时提交会返回 `503`，插件会自动重试
 - 查询接口有频率限制，触发 `429` 时面板会显示「限流重试中…」并退避，任务不会因此失败
-- 视频只支持**文生视频**：暂无首尾帧、参考音频与视频输入（Flash 版接口本身不支持这些）
+- 视频暂不支持参考音频与参考视频输入（Flash 版接口本身不支持）；图生视频目前只走首帧 / 尾帧关键帧
 - 参考图最多 8 张；单张在浏览器侧压到长边 1280，细节极多的小字参考图重绘后可能看不清
-- 生成结果只保留最近 8 条（本次会话内），刷新页面后历史清空；文件本身在输出目录里不会丢
+- 生成历史保留最近 24 条，落盘到 `~/.dsh/agnes-create/history.json`；点「清空」会同时清掉磁盘记录，但已生成的文件仍在输出目录里
 
 ## 开发
 

package/lib/agnes.js

@@ -12,7 +12,7 @@
  * API Key 永远从文件读，不进代码、不进日志。
  */
 
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, readdir, stat, access } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, basename } from 'node:path';
 
@@ -26,8 +26,12 @@ export const DEFAULT_BASE = 'https://api.agnes-ai.cn/v1'; // 中国站
    配置存于 ~/.dsh/agnes-image/config.json，由面板里的「设置」卡片写入。
    ========================================================================== */
 
-export const CONFIG_DIR = join(homedir(), '.dsh', 'agnes-image');
+export const CONFIG_DIR = join(homedir(), '.dsh', 'agnes-create');
 export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+/** 旧目录：包名改名前配置存在 ~/.dsh/agnes-image/，读的时候回退，写只写新路径。 */
+export const LEGACY_CONFIG_FILE = join(homedir(), '.dsh', 'agnes-image', 'config.json');
+/** 生成历史落盘位置（面板重启后仍能看到最近的结果）。 */
+export const HISTORY_FILE = join(CONFIG_DIR, 'history.json');
 export const DEFAULT_KEY_FILE = join(homedir(), '.agnes-key.txt');
 export const DEFAULT_OUT_DIR = join(homedir(), 'Desktop', 'Agnes出图');
 
@@ -83,10 +87,24 @@ export function expandHome(p) {
  */
 export async function resolvePaths() {
   let stored = {};
+  let configFile = CONFIG_FILE;
   try {
     const raw = JSON.parse(await readFile(CONFIG_FILE, 'utf8'));
     if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) stored = raw;
-  } catch { /* 无配置文件或解析失败 → 用默认 */ }
+  } catch {
+    // 新路径没有 → 读旧路径（改名前的配置），迁移到新目录
+    try {
+      const raw = JSON.parse(await readFile(LEGACY_CONFIG_FILE, 'utf8'));
+      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(() => { /* 迁移失败不影响本次读取 */ });
+      }
+    } catch { /* 旧配置也没有 → 用默认 */ }
+  }
 
   const storedKey = typeof stored.keyFile === 'string' && stored.keyFile.trim() !== ''
     ? expandHome(stored.keyFile) : null;
@@ -96,7 +114,9 @@ export async function resolvePaths() {
   return {
     keyFile: storedKey ?? (process.env.AGNES_KEY_FILE || DEFAULT_KEY_FILE),
     outDir: storedOut ?? (process.env.AGNES_OUT_DIR || DEFAULT_OUT_DIR),
-    configFile: CONFIG_FILE,
+    configFile,
+    legacyConfigFile: LEGACY_CONFIG_FILE,
+    historyFile: HISTORY_FILE,
     defaults: { keyFile: DEFAULT_KEY_FILE, outDir: DEFAULT_OUT_DIR },
     stored: { keyFile: storedKey, outDir: storedOut },
   };
@@ -136,6 +156,68 @@ export async function saveConfig(patch = {}) {
   return resolvePaths();
 }
 
+/* ==========================================================================
+   生成历史（落盘）
+   --------------------------------------------------------------------------
+   面板重启 / 切面板 / 关掉再打开都能看到最近生成的东西。
+   只存可序列化的标量字段：文件本体在磁盘上，这里只有描述信息。
+   ========================================================================== */
+
+export const HISTORY_MAX = 24;
+
+/** 只保留白名单里的标量字段，防止把乱七八糟的东西写进磁盘。 */
+function sanitizeHistoryEntry(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const name = typeof raw.filename === 'string' ? raw.filename.trim() : '';
+  if (name === '') return null;
+  const kind = raw.kind === 'video' ? 'video' : 'image';
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+  return {
+    filename: basename(name),
+    kind,
+    bytes: num(raw.bytes),
+    size: str(raw.size),
+    ratio: str(raw.ratio),
+    seconds: str(raw.seconds),
+    path: str(raw.path),
+    mode: str(raw.mode),
+    refCount: num(raw.refCount),
+    elapsedSec: num(raw.elapsedSec),
+    wallSec: str(raw.wallSec),
+    prompt: str(raw.prompt)?.slice(0, 500) ?? null,
+    createdAt: str(raw.createdAt) ?? new Date().toISOString(),
+  };
+}
+
+export async function readHistory() {
+  try {
+    const raw = JSON.parse(await readFile(HISTORY_FILE, 'utf8'));
+    const list = Array.isArray(raw) ? raw : (Array.isArray(raw?.entries) ? raw.entries : []);
+    const entries = list.map(sanitizeHistoryEntry).filter((x) => x !== null);
+    return { entries: entries.slice(0, HISTORY_MAX), file: HISTORY_FILE };
+  } catch {
+    return { entries: [], file: HISTORY_FILE };
+  }
+}
+
+/** 追加一条到历史最前面（按 filename 去重）。返回最新的完整列表。 */
+export async function appendHistory(entry) {
+  const clean = sanitizeHistoryEntry(entry);
+  if (clean === null) throw new Error('历史记录缺少 filename');
+  const { entries } = await readHistory();
+  const next = [clean, ...entries.filter((x) => x.filename !== clean.filename)].slice(0, HISTORY_MAX);
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(HISTORY_FILE, JSON.stringify(next, null, 2) + '\n', 'utf8');
+  return { entries: next, file: HISTORY_FILE };
+}
+
+export async function clearHistory() {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(HISTORY_FILE, '[]\n', 'utf8');
+  return { entries: [], file: HISTORY_FILE };
+}
+
 /** 读 Key。不传 file 则按当前配置解析。 */
 export async function readKey(file) {
   const target = file ?? (await resolvePaths()).keyFile;
@@ -288,6 +370,10 @@ export async function generate({
   if (!buf || buf.length === 0) throw new Error('图片数据为空');
   await writeFile(path, buf);
 
+  // 把提示词写进图片自身，之后从磁盘上任意时候读回来都知道这张图是怎么来的。
+  // 失败不影响出图结果：元数据只是附加值。
+  const meta = await embedPrompt(path, prompt);
+
   return {
     ok: true,
     filename: name,
@@ -301,6 +387,7 @@ export async function generate({
     // 有参考图 = 图生图 / 多图合成；没有 = 文生图。面板据此显示模式。
     mode: refs.length > 0 ? 'img2img' : 'text2img',
     refCount: refs.length,
+    promptMeta: meta,
     revisedPrompt: item.revised_prompt ?? null,
     remoteUrl,
   };
@@ -337,6 +424,258 @@ export async function readImage(name, outDir) {
   return { path, buf };
 }
 
+/* ==========================================================================
+   把提示词写进图片文件本身
+   --------------------------------------------------------------------------
+   直接改文件结构，不依赖任何三方库：
+
+     PNG → 插入 iTXt 块（keyword="prompt"，UTF-8，中文安全）
+     JPEG → SOI 之后插入 COM 段（原始 UTF-8 字节）
+     其它格式（webp/gif/mp4…）→ 不支持，跳过
+
+   这样图片被拷到别处、被历史记录忘掉之后，提示词依然跟着文件走。
+   ========================================================================== */
+
+const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+// 用自己的命名空间，别用通用名 "prompt"：ComfyUI / A1111 也往 tEXt 里写 prompt，
+// 那是工作流 JSON，混进来会被当成提示词显示成一堆花括号。
+const META_KEYWORD = 'dsh-agnes-prompt';
+const META_PREFIX = 'dsh-agnes-prompt: ';
+const LIB_MAX = 200;
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i += 1) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** 按 PNG 规范拼一个块：长度 + 类型 + 数据 + CRC(类型+数据)。 */
+function pngChunk(type, data) {
+  const head = Buffer.alloc(4);
+  head.writeUInt32BE(data.length, 0);
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const tail = Buffer.alloc(4);
+  tail.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([head, body, tail]);
+}
+
+/** 把整张 PNG 切成块序列，方便插入 / 覆盖 / 查找。 */
+function pngChunks(buf) {
+  const out = [];
+  let off = PNG_SIG.length;
+  while (off + 8 <= buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString('ascii', off + 4, off + 8);
+    const end = off + 12 + len;
+    if (end > buf.length || len < 0) break;
+    out.push({ type, start: off, end });
+    off = end;
+    if (type === 'IEND') break;
+  }
+  return out;
+}
+
+/** 组一个 iTXt 块（不做压缩，关键字固定 prompt）。 */
+function itxtChunk(text) {
+  const data = Buffer.concat([
+    Buffer.from(META_KEYWORD, 'latin1'),
+    Buffer.from([0]),      // 关键字结束
+    Buffer.from([0, 0]),   // 压缩标志 0 / 压缩方法 0
+    Buffer.from([0]),      // 语言标签（空）
+    Buffer.from([0]),      // 翻译关键字（空）
+    Buffer.from(text, 'utf8'),
+  ]);
+  return pngChunk('iTXt', data);
+}
+
+/**
+ * 从 PNG 里读 prompt：优先取我们自己写的 iTXt，其次兼容 tEXt。
+ * 旧的 0.7.0 早期版本用的是通用关键字 "prompt"，只在 iTXt 里认它——
+ * ComfyUI / A1111 写的是 tEXt["prompt"]（工作流 JSON），不能当提示词读出来。
+ */
+function readPngPrompt(buf) {
+  let legacy = null;
+  for (const c of pngChunks(buf)) {
+    if (c.type === 'iTXt') {
+      const data = buf.subarray(c.start + 8, c.end - 4);
+      const keyEnd = data.indexOf(0);
+      if (keyEnd < 0) continue;
+      const key = data.toString('latin1', 0, keyEnd);
+      const text = data.subarray(keyEnd + 5); // 跳关键字\0 + 压缩标志\0 + 方法\0 + 语言\0 + 翻译\0
+      if (key === META_KEYWORD) return text.toString('utf8').replace(/\0+$/, '');
+      if (key === 'prompt' && legacy === null) legacy = text.toString('utf8').replace(/\0+$/, '');
+      continue;
+    }
+    if (c.type === 'tEXt') {
+      const data = buf.subarray(c.start + 8, c.end - 4);
+      const keyEnd = data.indexOf(0);
+      if (keyEnd < 0) continue;
+      if (data.toString('latin1', 0, keyEnd) !== META_KEYWORD) continue;
+      return data.toString('latin1', keyEnd + 1).replace(/\0+$/, '');
+    }
+  }
+  return legacy;
+}
+
+/** 重写 PNG：删掉旧的 prompt 块，把新的插在 IEND 之前。 */
+function withPngPrompt(buf, text) {
+  const chunks = pngChunks(buf);
+  const keep = [];
+  for (const c of chunks) {
+    if (c.type !== 'iTXt' && c.type !== 'tEXt') { keep.push(c); continue; }
+    const data = buf.subarray(c.start + 8, c.end - 4);
+    const keyEnd = data.indexOf(0);
+    const key = keyEnd < 0 ? '' : data.toString('latin1', 0, keyEnd);
+    if (key !== META_KEYWORD) keep.push(c); // 别人的元数据原样保留
+  }
+  const iend = keep.find((c) => c.type === 'IEND');
+  const parts = [PNG_SIG];
+  for (const c of keep) {
+    if (c === iend) parts.push(itxtChunk(text));
+    parts.push(buf.subarray(c.start, c.end));
+  }
+  if (iend === undefined) parts.push(itxtChunk(text));
+  return Buffer.concat(parts);
+}
+
+function isPng(buf) {
+  return buf.length > 12 && buf.subarray(0, 8).equals(PNG_SIG);
+}
+
+function isJpeg(buf) {
+  return buf.length > 4 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff;
+}
+
+/** JPEG：在 SOI 之后插一个 COM 段（已存在就替换）。 */
+function withJpegPrompt(buf, text) {
+  const seg = (() => {
+    // COM 段没有关键字位置，用前缀标记所有权，避免覆盖/误读相机或别家写的注释
+    const payload = Buffer.from(META_PREFIX + text, 'utf8');
+    const head = Buffer.alloc(4);
+    head[0] = 0xff; head[1] = 0xfe;              // COM
+    head.writeUInt16BE(payload.length + 2, 2);   // 长度包含自身 2 字节
+    return Buffer.concat([head, payload]);
+  })();
+  // 先看 SOI 后面是不是已经有一个 COM，是就换掉
+  if (buf.length > 6 && buf[2] === 0xff && buf[3] === 0xfe) {
+    const len = buf.readUInt16BE(4);
+    return Buffer.concat([buf.subarray(0, 2), seg, buf.subarray(4 + len)]);
+  }
+  return Buffer.concat([buf.subarray(0, 2), seg, buf.subarray(2)]);
+}
+
+function readJpegPrompt(buf) {
+  let off = 2;
+  while (off + 4 <= buf.length) {
+    if (buf[off] !== 0xff) break;
+    const marker = buf[off + 1];
+    if (marker === 0xda || marker === 0xd9) break; // SOS / EOI 之后不再有段
+    const len = buf.readUInt16BE(off + 2);
+    if (len < 2) break;
+    if (marker === 0xfe) {
+      const text = buf.toString('utf8', off + 4, off + 2 + len).replace(/\0+$/, '');
+      // 只认自己写的（带前缀）；别人的 COM 注释原样留着，不当提示词
+      if (!text.startsWith(META_PREFIX)) return null;
+      return text.slice(META_PREFIX.length);
+    }
+    off += 2 + len;
+  }
+  return null;
+}
+
+/**
+ * 把提示词写进图片文件。失败不抛（元数据只是附加价值，不该影响出图）。
+ * @returns {Promise<{embedded:boolean, format?:string, reason?:string}>}
+ */
+export async function embedPrompt(filePath, prompt) {
+  const text = typeof prompt === 'string' ? prompt.trim() : '';
+  if (text === '') return { embedded: false, reason: '没有提示词' };
+  try {
+    const buf = await readFile(filePath);
+    let next = null;
+    let format = null;
+    if (isPng(buf)) { next = withPngPrompt(buf, text); format = 'png'; }
+    else if (isJpeg(buf)) { next = withJpegPrompt(buf, text); format = 'jpeg'; }
+    else return { embedded: false, reason: '该格式不支持写入元数据' };
+    if (next !== null && next.length > 0) await writeFile(filePath, next);
+    return { embedded: true, format };
+  } catch (e) {
+    return { embedded: false, reason: e.message };
+  }
+}
+
+/** 从图片文件里读回提示词；读不到返回 null。 */
+export async function readEmbeddedPrompt(filePath) {
+  try {
+    const buf = await readFile(filePath);
+    if (isPng(buf)) return readPngPrompt(buf);
+    if (isJpeg(buf)) return readJpegPrompt(buf);
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
+const VIDEO_EXT = new Set(['.mp4', '.webm', '.mov']);
+
+export function kindOf(name) {
+  const dot = name.lastIndexOf('.');
+  const ext = dot < 0 ? '' : name.slice(dot).toLowerCase();
+  if (IMAGE_EXT.has(ext)) return 'image';
+  if (VIDEO_EXT.has(ext)) return 'video';
+  return null;
+}
+
+/** 文件还在不在（历史里可能有被删掉或被挪走的文件）。 */
+export async function fileExists(path) {
+  try { await access(path); return true; } catch { return false; }
+}
+
+/**
+ * 列出输出目录里已有的图片 / 视频，供面板「加载输出目录」用。
+ * prompt 优先从文件元数据读，读不到就留 null（前端可再看历史）。
+ */
+export async function listLibrary(outDir) {
+  const entries = await readdir(outDir, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const ent of entries) {
+    if (!ent.isFile()) continue;
+    const kind = kindOf(ent.name);
+    if (kind === null) continue;
+    const full = join(outDir, ent.name);
+    let info = null;
+    try { info = await stat(full); } catch { continue; }
+    files.push({
+      filename: ent.name,
+      name: ent.name,        // 面板侧沿用自己的 name，两种叫法都给出
+      kind,
+      bytes: info.size,
+      mtime: info.mtimeMs,
+      path: full,
+    });
+  }
+  files.sort((a, b) => b.mtime - a.mtime);
+  const top = files.slice(0, LIB_MAX);
+  // 只给最新的若干张读元数据，避免目录很大时逐个开文件拖慢面板
+  for (const f of top.slice(0, 60)) {
+    if (f.kind !== 'image') continue;
+    const prompt = await readEmbeddedPrompt(f.path);
+    if (prompt !== null) f.prompt = prompt;
+  }
+  return top;
+}
+
 /* ==========================================================================
    视频（agnes-video-2.5-flash）
    --------------------------------------------------------------------------
@@ -364,20 +703,32 @@ export function apiOrigin(baseUrl = DEFAULT_BASE) {
   return new URL(baseUrl).origin;
 }
 
-/** 提交文生视频任务，返回 video_id。队列满(503)/限流(429) 会自动重试。 */
+/**
+ * 提交视频任务，返回 video_id。队列满(503)/限流(429) 会自动重试。
+ *
+ * 三种模式（由是否给关键帧决定，不用调用方自己传 mode）：
+ *   - 纯文本 prompt                → mode: 'text'
+ *   - 给 firstFrame / lastFrame    → mode: 'keyframe'（两者至少一个）
+ *
+ * 关键帧接受公网 http(s) 图片 URL，也接受 data:image/... 的 base64 —— 后者
+ * 已实测被上游接受，所以本地磁盘里的图片可以直接当首帧，不用先传到公网。
+ */
 export async function submitVideo({
   prompt,
   seconds = '5',
   ratio = '16:9',
   model = VIDEO_MODEL,
   baseUrl = DEFAULT_BASE,
+  seed = null,
+  firstFrame = null,
+  lastFrame = null,
   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 });
+      return await submitVideoOnce({ prompt, seconds, ratio, model, baseUrl, seed, firstFrame, lastFrame });
     } catch (e) {
       lastError = e;
       const msg = e instanceof Error ? e.message : String(e);
@@ -390,7 +741,23 @@ export async function submitVideo({
   throw lastError ?? new Error('提交任务失败');
 }
 
-async function submitVideoOnce({ prompt, seconds, ratio, model, baseUrl }) {
+/** 单个关键帧校验：只放行 http(s) 与 data:image，空值归为 null。 */
+function normalizeFrame(frame, label) {
+  if (frame === null || frame === undefined || frame === '') return null;
+  const refs = normalizeRefs([frame]); // 复用参考图校验：单张也要过同一套 URL/data URI 白名单
+  if (refs.length !== 1) throw new Error(`${label}无效`);
+  return refs[0];
+}
+
+/** seed 校验：允许空；给了就必须是非负整数。 */
+function normalizeSeed(seed) {
+  if (seed === null || seed === undefined || seed === '') return null;
+  const n = typeof seed === 'number' ? seed : Number(String(seed).trim());
+  if (!Number.isInteger(n) || n < 0) throw new Error('seed 必须是非负整数');
+  return n;
+}
+
+async function submitVideoOnce({ prompt, seconds, ratio, model, baseUrl, seed, firstFrame, lastFrame }) {
   if (typeof prompt !== 'string' || prompt.trim() === '') throw new Error('prompt 不能为空');
   const sec = String(seconds);
   if (!VIDEO_SECONDS.includes(sec)) {
@@ -398,16 +765,26 @@ async function submitVideoOnce({ prompt, seconds, ratio, model, baseUrl }) {
   }
   if (!VIDEO_RATIOS.includes(ratio)) throw new Error(`aspect_ratio 必须是 ${VIDEO_RATIOS.join(' / ')}`);
 
+  const first = normalizeFrame(firstFrame, '首帧图');
+  const last = normalizeFrame(lastFrame, '尾帧图');
+  const mode = first !== null || last !== null ? 'keyframe' : 'text';
+  const seedValue = normalizeSeed(seed);
+
   const key = await readKey();
   const url = `${baseUrl.replace(/\/+$/, '')}/videos`;
   const body = {
     model,
     prompt,
     seconds: sec,
-    mode: 'text',
+    mode,
     size: VIDEO_SIZE,   // Flash 只认 720P
     aspect_ratio: ratio,
   };
+  if (mode === 'keyframe') {
+    if (first !== null) body.first_frame = first;
+    if (last !== null) body.last_frame = last;
+  }
+  if (seedValue !== null) body.seed = seedValue;
 
   let res;
   try {
@@ -439,7 +816,7 @@ async function submitVideoOnce({ prompt, seconds, ratio, model, baseUrl }) {
   if (typeof videoId !== 'string' || videoId === '') {
     throw new Error(`响应里没有 video_id：${text.slice(0, 300)}`);
   }
-  return { videoId, taskId: payload?.task_id ?? null, model, baseUrl };
+  return { videoId, taskId: payload?.task_id ?? null, model, baseUrl, mode };
 }
 
 /** 查询一次任务状态。429/503 属于瞬时限流，自动退避重试。 */