dsh-agnes-create 0.7.0 → 0.10.3

package/README.md

@@ -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,26 @@ 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 个可选时仍然显示为纯文本，不弹空下拉
+
+### 在对话里直接出图 / 出视频
+
+除了侧边栏面板，插件还把三个模型工具交给宿主，所以你直接对 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,96 @@ export async function clearHistory() {
   return { entries: [], file: HISTORY_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-')),
+  };
+}
+
 export async function readKey(file) {
   const target = file ?? (await resolvePaths()).keyFile;
   let raw;
@@ -696,6 +833,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 +862,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 +898,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 +918,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 +937,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;