dsh-agnes-create 0.0.0-stage → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-agnes-create contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# dsh-agnes-create
 
-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.
+在 DeepSeek Harness（dsh）里直接**出图**和**出视频**的侧边栏插件。侧边栏点一下「Agnes创作」，输入提示词就能出片，结果自动保存到本地并可在面板里回看。
+
+> 仓库：<https://github.com/zxygithub/dsh-agnes-create>　·　npm：`dsh-agnes-create`
+
+- 出图：`agnes-image-2.5-flash` — 支持 `1K`/`2K`/`3K`/`4K` 与 8 种宽高比
+- 出视频：`agnes-video-2.5-flash` — 720P，4–12 秒，异步任务带百分比进度
+- Key 文件位置、输出目录都能在界面里改，改完即时生效
+- 最近 8 条生成结果可回看，一键清空界面（不删文件）
+
+## 安装
+
+在插件市场里搜 `dsh-agnes-create` 安装，或命令行：
+
+```bash
+dsh plugin --profile <profile> add dsh-agnes-create
+```
+
+装好后面板出现在左侧边栏，标签为 **Agnes创作**。
+
+## 准备 API Key
+
+插件从文件读取 Key，**不接受把 Key 写在配置里或代码里**。默认路径：
+
+```
+~/.agnes-key.txt
+```
+
+文件里只放 Key 本身，不要带 `Bearer ` 前缀、不要加引号：
+
+```
+sk-xxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认走中国站 `https://api.agnes-ai.cn/v1`。
+
+## 配置
+
+面板底部的「设置」卡片可以改两项，保存后立即生效（不用重启）：
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| Key 文件路径 | `~/.agnes-key.txt` | 支持 `~/` 开头或绝对路径 |
+| 输出目录 | `~/Desktop/Agnes出图` | 图片和视频都存这里，不存在会自动创建 |
+
+- 输入框留空并保存 = 回退到默认值
+- 配置存在 `~/.dsh/agnes-image/config.json`
+- 优先级：显式传参 > 已保存配置 > 环境变量（`AGNES_KEY_FILE` / `AGNES_OUT_DIR`）> 默认值
+- 配置文件损坏时会静默回退默认值，不会让插件加载失败
+
+## 用法
+
+1. 侧边栏点 **Agnes创作**
+2. 顶部选择 **图片** 或 **视频**
+3. 输入提示词，`Cmd/Ctrl + Enter` 或点按钮生成
+4. 结果直接显示在面板里；图片用 `<img>`、视频用 `<video>` 播放（支持拖动进度条）
+
+提示词建议按「主体 + 场景 + 动作/镜头 + 光线 + 风格 + 构图」组织，例如：
+
+```
+一只胖乎乎的橘色虎斑猫坐在木质窗台上，午后暖阳斜射，窗外虚化的街景，浅景深，写实摄影，中景构图，高细节
+```
+
+参数范围：
+
+| 类型 | 尺寸 | 宽高比 | 其它 |
+| --- | --- | --- | --- |
+| 图片 | `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 秒 |
+
+### 图生图 / 多图合成
+
+「参考图」区有两种来源，可以混着加，最多 8 张：
+
+- **＋ 本地图片** —— 从磁盘选一个或多个文件（PNG / JPEG / WebP / GIF）
+- **＋ 生成结果** —— 从下方「最近生成」里挑一张（视频不能当参考图）
+
+加好之后提示词写「想怎么改」，按钮会变成 **图生图**：
+
+| 参考图数量 | 实际行为 |
+| --- | --- |
+| 0 张 | 纯文生图 |
+| 1 张 | 图生图（按参考图重绘 / 改风格 / 换背景） |
+| 2–8 张 | 多图合成（把多张图的元素 / 配色融合） |
+
+实现细节：
+
+- 图片在**浏览器侧先下采样到长边 1280** 再编码成 data URI（PNG 优先保留透明通道，超过 800 KB 自动转 JPEG），所以一张 4K 原图发出的请求也只有几百 KB
+- 参考图走接口的 `extra_body.image`；多图就是往这个数组里放多条
+- 校验在前端和内核各做一次：只接受 `http(s)` 或 `data:image/…;base64`，超过 8 张、空串、非图片类型都会直接报错，不会把脏数据发给上游
+- 本地文件路径**不会**被读取或上传到别处：文件内容只在内存里转成 base64 随请求发给 Agnes
+
+## 关于费用
+
+插件的费用由 Agnes AI 账号结算，本插件不涉及任何计费。
+
+- 图片：1K 刊例价约 `$0.010/张`，2K 约 `$0.018/张`
+- 视频：`$0.025/秒`（4 秒约 `$0.10`）
+
+官方文档标注当前为体验价（`$0`）。具体以平台公告为准。
+
+## 已知限制
+
+- 视频为**异步任务**：提交后轮询，通常需要 1–4 分钟；队列繁忙时提交会返回 `503`，插件会自动重试
+- 查询接口有频率限制，触发 `429` 时面板会显示「限流重试中…」并退避，任务不会因此失败
+- 视频只支持**文生视频**：暂无首尾帧、参考音频与视频输入（Flash 版接口本身不支持这些）
+- 参考图最多 8 张；单张在浏览器侧压到长边 1280，细节极多的小字参考图重绘后可能看不清
+- 生成结果只保留最近 8 条（本次会话内），刷新页面后历史清空；文件本身在输出目录里不会丢
+
+## 开发
+
+包内是纯 ESM，**没有构建步骤**：`lib/client.js` 是手写的客户端 bundle（`window.__ModuleLoader__.load` 包装），宿主侧 `lib/index.js` 注册 HTTP 路由，`lib/agnes.js` 是与命令行共用的内核。
+
+```
+lib/
+├── agnes.js    内核：请求构造、视频任务轮询、落盘、配置解析
+├── index.js    宿主半：/agnes/health /agnes/config /agnes/generate /agnes/video /agnes/media
+└── client.js   客户端半：侧边栏入口 + 面板 UI
+cordis.patch.yml  把插件行插入 profile
+```
+
+改动后无需构建，重载窗口即可生效；宿主路由的改动需要重启应用。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-agnes-create bundle for DeepSeek Harness.
+# 安装后本 patch 自动把插件行插入 profile 组合；插件通过 profile 的 node_modules 按包名解析。
+- insert:
+    - id: dsh-agnes-create
+      name: 'dsh-agnes-create'

package/lib/agnes.js

@@ -0,0 +1,525 @@
+/**
+ * Agnes 出图内核 —— 被宿主插件（lib/index.js）和 CLI（agnes-image.mjs）共用。
+ *
+ * 文档：https://www.agnes-ai.com/zh-Hans/docs/agnes-image-25-flash
+ *
+ * 硬约束（别改错，都是文档里写死的坑）：
+ *   · POST {base}/images/generations
+ *   · 文生图必填 model / prompt / size
+ *   · response_format 只能放 extra_body 内，放顶层会报错
+ *   · 图生图输入放 extra_body.image（URL 或 data URI）
+ *
+ * API Key 永远从文件读，不进代码、不进日志。
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, basename } from 'node:path';
+
+export const MODEL = 'agnes-image-2.5-flash';
+export const DEFAULT_BASE = 'https://api.agnes-ai.cn/v1'; // 中国站
+
+/* ==========================================================================
+   可配置路径：Key 文件位置 / 输出目录
+   --------------------------------------------------------------------------
+   优先级：显式传参 > 已保存配置 > 环境变量 > 内置默认。
+   配置存于 ~/.dsh/agnes-image/config.json，由面板里的「设置」卡片写入。
+   ========================================================================== */
+
+export const CONFIG_DIR = join(homedir(), '.dsh', 'agnes-image');
+export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+export const DEFAULT_KEY_FILE = join(homedir(), '.agnes-key.txt');
+export const DEFAULT_OUT_DIR = join(homedir(), 'Desktop', 'Agnes出图');
+
+/** 兼容旧引用（skill / CLI 用它展示默认值）。生效值请用 resolvePaths()。 */
+export const KEY_FILE = process.env.AGNES_KEY_FILE || DEFAULT_KEY_FILE;
+export const OUT_DIR = process.env.AGNES_OUT_DIR || DEFAULT_OUT_DIR;
+
+export const TIMEOUT_MS = 300_000; // 文档建议 60s–360s
+
+export const SIZES = ['1K', '2K', '3K', '4K'];
+export const RATIOS = ['1:1', '3:4', '4:3', '16:9', '9:16', '2:3', '3:2', '21:9'];
+
+/** 图生图 / 多图合成：一次最多几张参考图。文档没写上限，8 张是面板与请求体的安全值。 */
+export const MAX_REF_IMAGES = 8;
+
+/** data URI 只接受图片 MIME，其余一律拒绝（防止把任意 base64 塞进上游请求）。 */
+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) {
+  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} 张`);
+  }
+  return images.map((value, i) => {
+    if (typeof value !== 'string' || value.trim() === '') {
+      throw new Error(`第 ${i + 1} 张参考图不是有效字符串`);
+    }
+    const s = value.trim();
+    if (/^https?:\/\//i.test(s)) return s;
+    if (DATA_URI_RE.test(s)) return s;
+    const kind = s.slice(0, 30).replace(/\s+/g, ' ');
+    throw new Error(`第 ${i + 1} 张参考图只接受 http(s) 链接或 data:image/…;base64，收到：${kind}`);
+  });
+}
+
+/** 把开头的 ~ 展开成家目录；其余原样返回。 */
+export function expandHome(p) {
+  const s = String(p ?? '').trim();
+  if (s === '~') return homedir();
+  if (s.startsWith('~/')) return join(homedir(), s.slice(2));
+  return s;
+}
+
+/**
+ * 解析生效配置。
+ * 配置文件不存在或内容损坏时一律退回默认值 —— 配置坏了不该把插件拖死。
+ */
+export async function resolvePaths() {
+  let stored = {};
+  try {
+    const raw = JSON.parse(await readFile(CONFIG_FILE, 'utf8'));
+    if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) stored = raw;
+  } catch { /* 无配置文件或解析失败 → 用默认 */ }
+
+  const storedKey = typeof stored.keyFile === 'string' && stored.keyFile.trim() !== ''
+    ? expandHome(stored.keyFile) : null;
+  const storedOut = typeof stored.outDir === 'string' && stored.outDir.trim() !== ''
+    ? expandHome(stored.outDir) : null;
+
+  return {
+    keyFile: storedKey ?? (process.env.AGNES_KEY_FILE || DEFAULT_KEY_FILE),
+    outDir: storedOut ?? (process.env.AGNES_OUT_DIR || DEFAULT_OUT_DIR),
+    configFile: CONFIG_FILE,
+    defaults: { keyFile: DEFAULT_KEY_FILE, outDir: DEFAULT_OUT_DIR },
+    stored: { keyFile: storedKey, outDir: storedOut },
+  };
+}
+
+/**
+ * 保存配置，只覆盖传进来的字段；传 null 表示清除该字段、回退默认。
+ * 校验：必须是绝对路径；输出目录立刻创建 —— 写不进去现在报错，
+ * 而不是等到出图时才失败。
+ */
+export async function saveConfig(patch = {}) {
+  const current = await resolvePaths();
+
+  const next = {
+    keyFile: patch.keyFile === undefined ? current.stored.keyFile : patch.keyFile,
+    outDir: patch.outDir === undefined ? current.stored.outDir : patch.outDir,
+  };
+
+  for (const [field, label] of [['keyFile', 'Key 文件路径'], ['outDir', '输出目录']]) {
+    const v = next[field];
+    if (v === null) continue; // 允许清空回默认
+    if (typeof v !== 'string' || v.trim() === '') throw new Error(`${label}不能为空`);
+    const expanded = expandHome(v);
+    if (!expanded.startsWith('/')) throw new Error(`${label}必须是绝对路径（或以 ~/ 开头）`);
+    next[field] = expanded;
+  }
+
+  await mkdir(next.outDir ?? current.outDir, { recursive: true });
+
+  const payload = {};
+  if (typeof next.keyFile === 'string') payload.keyFile = next.keyFile;
+  if (typeof next.outDir === 'string') payload.outDir = next.outDir;
+
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(CONFIG_FILE, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+
+  return resolvePaths();
+}
+
+/** 读 Key。不传 file 则按当前配置解析。 */
+export async function readKey(file) {
+  const target = file ?? (await resolvePaths()).keyFile;
+  let raw;
+  try {
+    raw = await readFile(target, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      throw new Error(`找不到 key 文件：${target}。把 Key 写进该文件（只放 key 本身，不要带 "Bearer"）。`);
+    }
+    throw e;
+  }
+  const key = raw.trim();
+  if (!key) throw new Error(`key 文件是空的：${target}`);
+  if (/^bearer\s+/i.test(key)) throw new Error('key 文件里不要带 "Bearer " 前缀');
+  return key;
+}
+
+export async function keyStatus(file) {
+  const target = file ?? (await resolvePaths()).keyFile;
+  try {
+    const key = await readKey(target);
+    return { present: true, file: target, length: key.length, masked: key.slice(0, 3) + '***' + key.slice(-3) };
+  } catch (e) {
+    return { present: false, file: target, error: e.message };
+  }
+}
+
+export function buildBody({ prompt, size = '1K', ratio = '1:1', model = MODEL, fmt = 'url', images = [] }) {
+  const body = {
+    model,
+    prompt,
+    size,
+    ratio,
+    // 文档明确要求：response_format 只能在 extra_body 内
+    extra_body: { response_format: fmt === 'b64' ? 'b64_json' : 'url' },
+  };
+  if (images.length > 0) body.extra_body.image = images;
+  return body;
+}
+
+async function post({ baseUrl, key, body }) {
+  const url = `${baseUrl.replace(/\/+$/, '')}/images/generations`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (e) {
+    const detail = e.name === 'TimeoutError' ? `超时（${TIMEOUT_MS / 1000}s）` : `${e.name}: ${e.message}`;
+    throw new Error(`请求失败 — ${detail}`);
+  }
+
+  const text = await res.text();
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new Error(`HTTP ${res.status}，响应非 JSON：${text.slice(0, 300)}`);
+  }
+  if (!res.ok) {
+    const msg = payload?.error?.message || payload?.message || text.slice(0, 300);
+    throw new Error(`HTTP ${res.status} — ${msg}`);
+  }
+  const item = payload?.data?.[0];
+  if (!item) throw new Error(`响应缺少 data[0]：${text.slice(0, 300)}`);
+  return { payload, item };
+}
+
+function stamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+}
+
+/** 只允许安全的文件名，防止路径穿越。 */
+export function safeName(name) {
+  const b = basename(String(name || ''));
+  return /^[A-Za-z0-9._-]+$/.test(b) ? b : null;
+}
+
+/**
+ * 生成一张图并落盘。
+ * @returns {Promise<{ok:true, filename:string, path:string, bytes:number, transport:string,
+ *                    elapsedSec:number, size:string, ratio:string, model:string,
+ *                    revisedPrompt:string|null, remoteUrl:string|null}>}
+ */
+export async function generate({
+  prompt,
+  size = '1K',
+  ratio = '1:1',
+  model = MODEL,
+  baseUrl = DEFAULT_BASE,
+  fmt = 'url',
+  images = [],
+  outDir,
+  filename,
+} = {}) {
+  if (typeof prompt !== 'string' || prompt.trim() === '') throw new Error('prompt 不能为空');
+  if (!SIZES.includes(size)) throw new Error(`size 必须是 ${SIZES.join(' / ')}`);
+  if (!RATIOS.includes(ratio)) throw new Error(`ratio 必须是 ${RATIOS.join(' / ')}`);
+
+  // 有参考图 → 图生图 / 多图合成；没有 → 纯文生图。校验在发请求之前做完。
+  const refs = normalizeRefs(images);
+
+  const key = await readKey();
+  const started = Date.now();
+
+  let { payload, item } = await post({ baseUrl, key, body: buildBody({ prompt, size, ratio, model, fmt, images: refs }) });
+
+  const dir = outDir ?? (await resolvePaths()).outDir;
+  const name = filename || `agnes-${stamp()}.png`;
+  const path = join(dir, name);
+  await mkdir(dir, { recursive: true });
+
+  let buf;
+  let transport;
+  let remoteUrl = item.url || null;
+
+  if (fmt === 'url' && item.url) {
+    try {
+      const r = await fetch(item.url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+      if (!r.ok) throw new Error(`下载返回 HTTP ${r.status}`);
+      buf = Buffer.from(await r.arrayBuffer());
+      if (buf.length === 0) throw new Error('下载到 0 字节');
+      transport = 'url → 下载';
+    } catch (e) {
+      // 存储域名不可达时自动回退 base64，避免白跑一次
+      ({ payload, item } = await post({
+        baseUrl, key, body: buildBody({ prompt, size, ratio, model, fmt: 'b64', images }),
+      }));
+      if (!item.b64_json) throw new Error(`回退 b64 后仍无 b64_json（原下载错误：${e.message}）`);
+      buf = Buffer.from(item.b64_json, 'base64');
+      transport = `url 失败(${e.message}) → b64 回退`;
+      remoteUrl = null;
+    }
+  } else if (item.b64_json) {
+    buf = Buffer.from(item.b64_json, 'base64');
+    transport = item.url ? 'b64（服务端附带 url）' : 'b64';
+  } else if (item.url) {
+    const r = await fetch(item.url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!r.ok) throw new Error(`下载返回 HTTP ${r.status}`);
+    buf = Buffer.from(await r.arrayBuffer());
+    transport = 'url → 下载';
+  } else {
+    throw new Error('响应里既没有 url 也没有 b64_json');
+  }
+
+  if (!buf || buf.length === 0) throw new Error('图片数据为空');
+  await writeFile(path, buf);
+
+  return {
+    ok: true,
+    filename: name,
+    path,
+    bytes: buf.length,
+    transport,
+    elapsedSec: Number(((Date.now() - started) / 1000).toFixed(1)),
+    size,
+    ratio,
+    model,
+    // 有参考图 = 图生图 / 多图合成；没有 = 文生图。面板据此显示模式。
+    mode: refs.length > 0 ? 'img2img' : 'text2img',
+    refCount: refs.length,
+    revisedPrompt: item.revised_prompt ?? null,
+    remoteUrl,
+  };
+}
+
+/* ==========================================================================
+   媒体读取（图片 + 视频）
+   ========================================================================== */
+const MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mov': 'video/quicktime',
+};
+
+export async function readMedia(name, outDir) {
+  const safe = safeName(name);
+  if (safe === null) throw new Error('非法文件名');
+  const dir = outDir ?? (await resolvePaths()).outDir;
+  const path = join(dir, safe);
+  const buf = await readFile(path);
+  const dot = safe.lastIndexOf('.');
+  const ext = dot < 0 ? '' : safe.slice(dot).toLowerCase();
+  return { path, buf, mime: MIME[ext] ?? 'application/octet-stream' };
+}
+
+/** 兼容旧调用：只取字节。 */
+export async function readImage(name, outDir) {
+  const { path, buf } = await readMedia(name, outDir);
+  return { path, buf };
+}
+
+/* ==========================================================================
+   视频（agnes-video-2.5-flash）
+   --------------------------------------------------------------------------
+   和图片的「一次请求就出结果」完全不同，这是异步任务制：
+
+     POST {base}/videos                      → 提交，拿 video_id
+     GET  {origin}/agnesapi?video_id=...     → 轮询，status=completed 时取顶层 url
+
+   ⚠ /agnesapi 挂在域名根上，不在 /v1 之下，所以必须从 baseUrl 剥出 origin。
+
+   Flash 专属硬约束（违反直接 400，且不产生费用）：
+     · size 只能是字符串 "720P"
+     · seconds 是字符串 "4"–"12"
+     · 不支持 videos 输入
+   ========================================================================== */
+
+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';
+export const VIDEO_TIMEOUT_MS = 600_000;
+
+/** 从 baseUrl 剥出域名根：/agnesapi 不在 /v1 下。 */
+export function apiOrigin(baseUrl = DEFAULT_BASE) {
+  return new URL(baseUrl).origin;
+}
+
+/** 提交文生视频任务，返回 video_id。队列满(503)/限流(429) 会自动重试。 */
+export async function submitVideo({
+  prompt,
+  seconds = '5',
+  ratio = '16:9',
+  model = VIDEO_MODEL,
+  baseUrl = DEFAULT_BASE,
+  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 });
+    } catch (e) {
+      lastError = e;
+      const msg = e instanceof Error ? e.message : String(e);
+      // 只有队列满/限流才值得重试；参数错、鉴权错重试无用
+      const retriable = /\b503\b|\b429\b|队列已满|rate limit/i.test(msg);
+      if (!retriable || attempt === retries) throw e;
+      await new Promise((r) => setTimeout(r, retryDelayMs));
+    }
+  }
+  throw lastError ?? new Error('提交任务失败');
+}
+
+async function submitVideoOnce({ prompt, seconds, ratio, model, baseUrl }) {
+  if (typeof prompt !== 'string' || prompt.trim() === '') throw new Error('prompt 不能为空');
+  const sec = String(seconds);
+  if (!VIDEO_SECONDS.includes(sec)) {
+    throw new Error(`seconds 必须是字符串 "${VIDEO_SECONDS[0]}"–"${VIDEO_SECONDS[VIDEO_SECONDS.length - 1]}"`);
+  }
+  if (!VIDEO_RATIOS.includes(ratio)) throw new Error(`aspect_ratio 必须是 ${VIDEO_RATIOS.join(' / ')}`);
+
+  const key = await readKey();
+  const url = `${baseUrl.replace(/\/+$/, '')}/videos`;
+  const body = {
+    model,
+    prompt,
+    seconds: sec,
+    mode: 'text',
+    size: VIDEO_SIZE,   // Flash 只认 720P
+    aspect_ratio: ratio,
+  };
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (e) {
+    const detail = e.name === 'TimeoutError' ? `超时（${TIMEOUT_MS / 1000}s）` : `${e.name}: ${e.message}`;
+    throw new Error(`提交任务失败 — ${detail}`);
+  }
+
+  const text = await res.text();
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new Error(`HTTP ${res.status}，响应非 JSON：${text.slice(0, 300)}`);
+  }
+  if (!res.ok) {
+    const msg = payload?.detail || payload?.error?.message || payload?.message || text.slice(0, 300);
+    throw new Error(`HTTP ${res.status} — ${msg}`);
+  }
+
+  // 文档：id / task_id 是任务 ID，video_id 才是查询用的
+  const videoId = payload?.video_id ?? payload?.id ?? payload?.task_id;
+  if (typeof videoId !== 'string' || videoId === '') {
+    throw new Error(`响应里没有 video_id：${text.slice(0, 300)}`);
+  }
+  return { videoId, taskId: payload?.task_id ?? null, model, baseUrl };
+}
+
+/** 查询一次任务状态。429/503 属于瞬时限流，自动退避重试。 */
+export async function queryVideo({
+  videoId,
+  model = VIDEO_MODEL,
+  baseUrl = DEFAULT_BASE,
+  key,
+  retries = 2,
+  retryDelayMs = 4_000,
+} = {}) {
+  let lastError = null;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      return await queryVideoOnce({ videoId, model, baseUrl, key });
+    } catch (e) {
+      lastError = e;
+      const msg = e instanceof Error ? e.message : String(e);
+      // 实测查询接口会返回 429「查询过于频繁」，这里的重试是必须的
+      const retriable = /\b429\b|\b503\b|频繁|队列已满|rate limit/i.test(msg);
+      if (!retriable || attempt === retries) throw e;
+      await new Promise((r) => setTimeout(r, retryDelayMs * (attempt + 1)));
+    }
+  }
+  throw lastError ?? new Error('查询任务失败');
+}
+
+async function queryVideoOnce({ videoId, model, baseUrl, key }) {
+  if (typeof videoId !== 'string' || videoId === '') throw new Error('缺少 videoId');
+  const k = key ?? (await readKey());
+
+  const url = new URL(`${apiOrigin(baseUrl)}/agnesapi`);
+  url.searchParams.set('video_id', videoId);
+  url.searchParams.set('model_name', model);
+
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: { Authorization: `Bearer ${k}` },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (e) {
+    const detail = e.name === 'TimeoutError' ? `超时（${TIMEOUT_MS / 1000}s）` : `${e.name}: ${e.message}`;
+    throw new Error(`查询任务失败 — ${detail}`);
+  }
+
+  const text = await res.text();
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new Error(`HTTP ${res.status}，响应非 JSON：${text.slice(0, 300)}`);
+  }
+  if (!res.ok) {
+    const msg = payload?.detail || payload?.error?.message || text.slice(0, 300);
+    throw new Error(`HTTP ${res.status} — ${msg}`);
+  }
+
+  return {
+    status: String(payload?.status ?? 'pending'),
+    progress: Number(payload?.progress ?? 0) || 0,
+    url: typeof payload?.url === 'string' && payload.url !== '' ? payload.url : null,
+    error: payload?.error ?? null,
+    seconds: payload?.seconds ?? null,
+  };
+}
+
+/** 把已完成的视频下载到本地。 */
+export async function saveVideo({ url, outDir, filename } = {}) {
+  if (typeof url !== 'string' || url === '') throw new Error('缺少视频地址');
+  const dir = outDir ?? (await resolvePaths()).outDir;
+  const name = filename || `agnes-video-${stamp()}.mp4`;
+  const path = join(dir, name);
+  await mkdir(dir, { recursive: true });
+
+  const res = await fetch(url, { signal: AbortSignal.timeout(VIDEO_TIMEOUT_MS) });
+  if (!res.ok) throw new Error(`下载视频返回 HTTP ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length === 0) throw new Error('视频下载到 0 字节');
+  await writeFile(path, buf);
+
+  return { filename: name, path, bytes: buf.length };
+}