dsh-image-video 0.3.1 → 1.0.1

package/README.md

@@ -9,9 +9,12 @@
 - **图片单次提交与幂等找回** — `imageTransport: auto` 优先使用异步任务；提交超时/5xx 时只按 `request_id` 反查原任务，默认不盲目重提、不换模型、不生成候选，异步端点未启用时安全降级同步单次提交
 - **统一品牌水印后处理** — 图片在写入 `outputsDir` 和附件前以内存方式叠加可配置水印，桌面交互流直接展示最终水印图，并透出传输方式、提交次数与后处理元数据
 - **两个工具，自然语言触发** — 模型在对话中自主决策何时调用 `generate_image` / `generate_video`，无需手动指令
-- **四家服务商 + 按模型家族自动路由** — Threerouter（聚合器，默认）、万象 wanx（阿里云百炼）、MiniMax 官方平台、Seedance2.5（火山引擎）；显式指定模型时按家族关键词自动选择直连商，Threerouter 永远兜底，回退链透明写入 notes
+- **四家服务商 + 按模型家族自动路由** — Threevideo（聚合器，默认）、万象 wanx（阿里云百炼）、MiniMax 官方平台、Seedance2.5（火山引擎）；显式指定模型时按家族关键词自动选择直连商，Threevideo 永远兜底，回退链透明写入 notes
 - **异步任务不阻塞对话** — `TaskManager` 基于 `ctx.effect()` 托管轮询生命周期，插件卸载时自动取消排队任务、清理定时器，杜绝内存泄漏
 - **图片内嵌渲染** — 图片字节经 attachment 服务持久化，附件引用走 `presentationMeta` UI-only 通道，模型只见文本摘要，纯文本模型照常工作
+- **参考图自动瘦身** — 本地参考图大于 4MB 时先等比缩到长边 2560、转 JPEG(q88) 再提交，避免手机原图的 data URL 撞网关体积上限/超时；小图与远程 URL 原样透传
+- **凭证缝引用，不内联明文** — 每个服务商可只声明 `apiKeyEnv`（凭证引用名），生成时经 `ctx.credentials` 现读；桌面端登录写入的 Key 因此可直接复用，明文 `apiKey` 仍优先于引用
+- **媒体模式注入** — composer 切到「图片 / 视频」tab 时，插件在用户轮次进入模型请求前追加一条指令（`agent/pre-step`），要求模型直接调用生成工具并带出当前生效参数；子代理不继承该模式
 - **统一异常分类** — `GenerationError` 五类错误（auth / quota / task / timeout / network），可重试错误指数退避，不可重试错误即时中止
 - **声明式服务依赖** — `inject = ['tools']` 顶部声明 + `ctx.inject(['attachments'])` 显式注入，不假设其他插件内部实现
 
@@ -19,14 +22,14 @@
 
 | 工具 | 能力 | 服务商 | 异步轮询 | 对话渲染 |
 |---|---|---|---|---|
-| `generate_image` | 文生图 + **图生图**（可选 `image` 参考图入参） | **Threerouter**（默认）/ 万象 wanx / MiniMax 官方 / Seedance2.5 | 同步或异步（自动适配） | 图片经 `presentationMeta` 内嵌渲染；模型只见文本摘要 |
-| `generate_video` | 文生短视频 + 图生视频（首帧驱动，上限 10s） | **Threerouter**（默认）/ 万象 wanx / MiniMax 官方 / Seedance2.5 | 始终异步轮询，不阻塞对话 | 本地文件路径 + 源地址 |
+| `generate_image` | 文生图 + **图生图**（可选 `image` 参考图入参） | **Threevideo**（默认）/ 万象 wanx / MiniMax 官方 / Seedance2.5 | 同步或异步（自动适配） | 图片经 `presentationMeta` 内嵌渲染；模型只见文本摘要 |
+| `generate_video` | 文生短视频 + 图生视频（首帧驱动，上限 30s）+ **视频编辑**（`media[].video` 参考视频 + 编辑意图提示词，保留原片动作换主体） | **Threevideo**（默认）/ 万象 wanx / MiniMax 官方 / Seedance2.5 | 始终异步轮询，不阻塞对话 | 本地文件路径 + 源地址 |
 
 ## Provider 矩阵
 
 | 服务商 | 渠道 | 文生图 | 图生图 | 文生视频 | 备注 |
 |---|---|---|---|---|---|
-| **Threerouter**（默认，聚合器） | threerouter.com Bearer Key | ✅ `/images/generations` 同步（默认 `qwen-image-3.0`） | ✅ 同端点 `image` 参考图字段（默认 `qwen-image-3.0-pro`；2026-09 文档：/images/edits 已移除） | ✅ 已验证（MiniMax-H3 / wan 系） | 生图走 OpenAI Images 标准结构（url/b64_json 双形态 + 顶层 url 兼容）；视频走 `/v1/media/generations` + 轮询 |
+| **Threevideo**（默认，聚合器） | threevideo.com Bearer Key | ✅ `/images/generations` 同步（默认 `qwen-image-3.0`） | ✅ 同端点 `image` 参考图字段（默认 `qwen-image-3.0-pro`；2026-09 文档：/images/edits 已移除） | ✅ 已验证（MiniMax-H3 / wan 系） | 生图走 OpenAI Images 标准结构（url/b64_json 双形态 + 顶层 url 兼容）；视频走 `/v1/media/generations` + 轮询 |
 | **万象 wanx**（阿里云百炼） | DashScope `sk-` Key | ✅ 已验证（wanx2.1-t2i-turbo） | ✅ **已实测**（wanx2.1-imageedit，`base_image_url` 字段，参考图宽度须 512–4096px） | ✅ 已验证（wan2.2-t2v-plus） | i2i 为 description_edit 异步任务；图片同步/异步自适应；视频始终异步 |
 | **MiniMax 官方平台** | platform.minimaxi.com Key | ✅ `image-01`（待 key 实测） | ✅ `subject_reference` 主体一致性（待 key 实测） | ✅ 适配器已实现（video-generation v2，待 key 实测） | 图片同步返回 **base64**（无 URL），插件直接落盘；i2i 语义为「保留主体换场景」，每次仅 1 张参考图；Hailuo 系视频；缺省注入 `768P` |
 | **Seedance2.5**（火山引擎 Ark） | ARK API Key | ✅ 适配器已实现（即梦 3.0） | ✅ Seedream 4.0 `image` 入参（待 key 实测） | ✅ 适配器已实现 | 图片同步返回 URL（24h 有效立即下载）；i2i 默认模型自动切换 Seedream 4.0（3.0 不支持参考图）；显式关组图与水印；视频走异步任务 |
@@ -37,15 +40,15 @@
 
 | model 含关键词 | 家族 | 候选服务商（有序） |
 |---|---|---|
-| `minimax` / `hailuo` | MiniMax | `minimax`（官方直连）→ `threerouter`（图片+视频） |
-| `doubao` / `seedance` / `seedream` | 火山方舟 | `seedance`（直连）→ `threerouter` |
-| `wan`（覆盖 `wan*` 与 `wanx*`） | 通义万相 | `wanx`（百炼直连）→ `threerouter` |
-| 无命中（自定义模型） | 未知 | 仅配置链 + `threerouter` |
+| `minimax` / `hailuo` | MiniMax | `minimax`（官方直连）→ `threevideo`（图片+视频） |
+| `doubao` / `seedance` / `seedream` | 火山方舟 | `seedance`（直连）→ `threevideo` |
+| `wan`（覆盖 `wan*` 与 `wanx*`） | 通义万相 | `wanx`（百炼直连）→ `threevideo` |
+| 无命中（自定义模型） | 未知 | 仅配置链 + `threevideo` |
 
-候选序列 = **配置链服务商**（composer 会话选定 > 配置默认 > 激活服务商，配置优先）→ 家族直连商 → **threerouter 聚合器兜底**（其目录覆盖所有家族的模型）。回退规则：
+候选序列 = **配置链服务商**（composer 会话选定 > 配置默认 > 激活服务商，配置优先）→ 家族直连商 → **threevideo 聚合器兜底**（其目录覆盖所有家族的模型）。回退规则：
 
 - 仅在提交阶段的「模型不被该服务商接受」类错误（模型不存在 / 能力缺失，判定见 `isModelNotAcceptedError`）时回退下一候选；
-- 403 **分组/模型未开通该能力**（threerouter 实测：`permission_error`「Image generation is not enabled for this group」，文档语义 403=无该分组/模型权限或未开通生图 `allow_image_generation`）视为「该候选无法服务此请求」，同样回退下一候选；
+- 403 **分组/模型未开通该能力**（threevideo 实测：`permission_error`「Image generation is not enabled for this group」，文档语义 403=无该分组/模型权限或未开通生图 `allow_image_generation`）视为「该候选无法服务此请求」，同样回退下一候选；
 - 鉴权 Key 无效（401）、无权限语义的 403、配额（429）、网络/超时错误**响亮失败不回退**，不掩盖配置错误；
 - 拿到任务 ID 之后的任何失败**不回退**，绝不重复生成、双重扣费；
 - 回退链写入结果 `notes` 透明告知。
@@ -75,9 +78,9 @@ dsh plugin --profile <profile> add github:ihero3/dsh-image-video
 ```yaml
 - id: image-video
   config:
-    provider: threerouter             # threerouter（默认，聚合器） | wanx | minimax | seedance
-    threerouter:
-      apiKey: !!js process.env.THREEROUTER_API_KEY
+    provider: threevideo             # threevideo（默认，聚合器） | wanx | minimax | seedance
+    threevideo:
+      apiKey: !!js process.env.THREEVIDEO_API_KEY
       baseURL: ''
     wanx:
       apiKey: !!js process.env.DASHSCOPE_API_KEY
@@ -92,14 +95,14 @@ dsh plugin --profile <profile> add github:ihero3/dsh-image-video
     defaultVideoDuration: 5
     timeoutMs: 60000
     pollIntervalMs: 5000
-    pollTimeoutMs: 300000
+    pollTimeoutMs: 600000
     retryTimes: 3
     outputsDir: './outputs'
     imageTransport: auto              # auto | async（强制） | sync（强制同步）
     imageUnknownStatePolicy: fail     # fail（默认）| resubmit-same-key
     watermark:
       enabled: true
-      text: 'Threerouter'
+      text: 'Threevideo'
       position: bottom-right
       opacity: 0.68
       fontSizeRatio: 0.032
@@ -112,6 +115,28 @@ dsh plugin --profile <profile> add github:ihero3/dsh-image-video
 
 凭证建议通过环境变量注入（`!!js process.env.XXX`），不要明文写入配置文件。DSH 凭证系统支持 `~/.dsh/.credentials.yaml` 和 `~/.dsh/.env` 两种来源。
 
+### ffmpeg（时间轴导出需本机安装）
+
+时间轴导出 MP4 依赖**本机 ffmpeg**。插件在导出前会探测 `DSH_FFMPEG_PATH` → `PATH` → 常见安装位置，并检测版本与 H.264/AAC 编码器；缺失 / 无权限 / 缺编码器都会在界面给出可操作提示，而不是抛栈。
+
+按你的系统安装：
+
+- **macOS**：`brew install ffmpeg`
+- **Windows**：`winget install ffmpeg`（或 `choco install ffmpeg`）；也可从 [gyan.dev](https://www.gyan.dev/ffmpeg/builds/) 下载 essentials 静态包解压后使用
+- **Linux**：`apt install ffmpeg`（Debian/Ubuntu）或 `brew install ffmpeg`（Homebrew on Linux）
+
+若装在非标准路径，设环境变量指向可执行文件后**重启宿主**生效：
+
+```sh
+# macOS / Linux
+export DSH_FFMPEG_PATH=/path/to/ffmpeg
+
+# Windows（用户级，持久化，在 PowerShell 中执行）
+# [Environment]::SetEnvironmentVariable('DSH_FFMPEG_PATH', 'C:\path\to\ffmpeg\bin\ffmpeg.exe', 'User')
+```
+
+> Windows 上 `installHint()` 不会提示 `brew install`（那是 macOS 命令）；装好后在 `C:/ProgramData/chocolatey/bin`、`C:/ffmpeg/bin`、`C:/tools/ffmpeg/bin` 或 `~/scoop/shims` 下的 `ffmpeg.exe` 会被自动探测到。
+
 ### 3. 运行
 
 ```sh
@@ -165,9 +190,36 @@ dsh --profile <profile>
 → 完成后视频首帧即该图片
 ```
 
-`resolution` 为可选分辨率档位，取值由服务商与模型决定（如 MiniMax-H3：`480P/768P/2K`；wan 图生视频：`480P/1080P`），留空使用服务商默认（MiniMax 系要求显式携带，未指定时插件自动注入 `768P`），不支持的值由上游响亮报错。图生视频的字段映射：threerouter `image`、wanx `input.img_url`、Seedance content 数组 `image_url` 块、MiniMax 官方 `first_frame_image`（MiniMax/Seedance 分支按官方协议实现，未在真实账号验证）。
+`resolution` 为可选分辨率档位，取值由服务商与模型决定（如 MiniMax-H3：`480P/768P/2K`；wan 图生视频：`480P/1080P`），留空使用服务商默认（MiniMax 系要求显式携带，未指定时插件自动注入 `768P`），不支持的值由上游响亮报错。图生视频的字段映射：threevideo `image`、wanx `input.img_url`、Seedance content 数组 `image_url` 块、MiniMax 官方 `first_frame_image`（MiniMax/Seedance 分支按官方协议实现，未在真实账号验证）。
+
+**视频编辑（参考视频换主体 / 改元素）：**
+
+```
+用户：把这段视频里的人物换成图片里的人  /path/source.mp4  /path/person.png
+
+模型（调用 generate_video）：
+  prompt: "编辑视频1：把视频1里的人物替换成图片1中的人物，保持镜头运动与人物动作不变"
+  media: [
+    { video: "/path/source.mp4", type: "reference_video" },
+    { image: "/path/person.png", type: "reference_image" }
+  ]
+
+→ 存在参考视频时缺省 model=wan3.0-video、aspectRatio=adaptive、duration=-1（保持原片时长）
+→ 本地素材在客户端预处理：图片按需压到长边 1600 的 JPEG，视频压到 ≤15 秒 / 720p / CRF 32
+→ 完成后视频保存到 outputs/，并缺省额外产出一条「原片 / 复刻」对比片
+```
 
-**图生图（参考图）语义差异**：`image` 入参各家模型行为不同——threerouter `/images/edits`（gpt-image-2 等）按提示词自由编辑；方舟 Seedream 4.0+ 按参考图编辑/组图（默认模型自动切换为 Seedream 4.0，3.0 不支持参考图）；MiniMax `subject_reference` 是**主体一致性**（保留人物/主体特征换场景换动作），且每次仅支持 1 张参考图、官方示例仅网络 URL（本地图转 data URL 传入待实测）。尺寸默认 **3:4**（`config.defaultImageSize`，接受比例写法 `3:4`/`16:9`/`1:1`）：qwen/wan 系自动换算为上游要求的 `宽*高`（长边 1536、32 对齐，如 3:4→1152*1536，实测 `3:4` 原样透传会被千问 400）；threerouter（OpenAI 系）/ 方舟系换算为 `宽x高`；MiniMax 比例写法原样透传。**实测约束**：百炼 `wanx2.1-imageedit` 参考图宽度须 512–4096px（过小先放大再调用）；其文字渲染弱（拼写易错），需要精准文字时建议生成后本地合成（如 ffmpeg drawtext）；千问图像默认开启 prompt_extend+思考模式，出图约 1–5 分钟，超时已按官方建议抬到 600s。
+**原片 / 复刻对比片（缺省自动生成）**：存在参考视频时，`generate_video` 缺省（`compare: true`）额外产出一条对比片，把原片与复刻结果并进同一画布直接对照，路径同时出现在结果文本与 `output.comparePath`。
+
+**拼接方向按原片画幅自动选择**：竖屏（3:4、9:16，即 `height ≥ width`）**左右并排**，横屏（4:3、16:9，即 `width > height`）**上下堆叠**——竖屏再上下堆叠会得到极端细长的画面、横屏再左右并排会得到极端宽扁的画面，两者都难以观看。判据见 `src/compare.ts` 的 `resolveCompareLayout`。
+
+对比片两侧等比缩放放进同一格（单格高度取 720 与原片高度的较小值）、统一 30fps、按较短者截断；命中常见系统字体时叠加 `ORIGINAL` / `AI RECREATED` 角标（字体全部未命中则不加，合成照常完成）。合成失败**只写进 `notes`**，不影响已经下载完成的复刻结果。
+
+**视频编辑的能力与边界**：`wan3.0-video` 是 All-in-One 视频模型，按 `input.media[].type` 与提示词意图自动路由任务类型——`reference_video` + 含编辑意图的提示词（"替换""改成""去掉"等）即「保留原片构图与动作、只改写指定元素」，**不需要额外的控制参数**（该模型没有 depth/pose 控制入参，深度等信息由服务端自原片自行提取）。上游文档声明：参考视频单段 ≤15 秒、最多 5 段、总时长 ≤15 秒、单文件 ≤100MB；**插件本地只强制**「单段 ≤15 秒」与「压缩后 ≤6MB」（`REFERENCE_VIDEO_MAX_BYTES`），其余不做事前拦截；参考图最多 10 张、单张 ≤20MB；`reference_*` 与 `first_frame`/`last_frame` 不可混用。
+
+**本地素材为何要压缩**：threevideo **没有文件上传端点**（2026-09-22 探测 `/v1/files`、`/v1/uploads`、`/v1/assets` 全 404），本地视频/图片只能以 data URL 提交，而过大的请求体会被网关拒绝（生图端点实测 2.4MB 载荷连续 502、≤1MB 稳定通过）。因此插件在客户端完成压缩，并对压缩后仍超过 6MB 的参考视频**响亮报错**（提示改用公网 URL 或裁短），而不是提交一个必然失败的巨型请求体。
+
+**图生图（参考图）语义差异**：`image` 入参各家模型行为不同——threevideo `/images/edits`（gpt-image-2 等）按提示词自由编辑；方舟 Seedream 4.0+ 按参考图编辑/组图（默认模型自动切换为 Seedream 4.0，3.0 不支持参考图）；MiniMax `subject_reference` 是**主体一致性**（保留人物/主体特征换场景换动作），且每次仅支持 1 张参考图、官方示例仅网络 URL（本地图转 data URL 传入待实测）。尺寸默认 **3:4**（`config.defaultImageSize`，接受比例写法 `3:4`/`16:9`/`1:1`）：qwen/wan 系自动换算为上游要求的 `宽*高`（长边 1536、32 对齐，如 3:4→1152*1536，实测 `3:4` 原样透传会被千问 400）；threevideo（OpenAI 系）/ 方舟系换算为 `宽x高`；MiniMax 比例写法原样透传。**实测约束**：百炼 `wanx2.1-imageedit` 参考图宽度须 512–4096px（过小先放大再调用）；其文字渲染弱（拼写易错），需要精准文字时建议生成后本地合成（如 ffmpeg drawtext）；千问图像默认开启 prompt_extend+思考模式，出图约 1–5 分钟，超时已按官方建议抬到 600s。
 
 **时长与模型能力**：wan 系模型（`wan2.2-t2v-plus`、`wan2.7-t2v`）不支持自定义时长——调用时传入 `duration` 会被插件丢弃（不发给上游，避免 `duration customization is not supported` 报错），并在结果 `notes` 中透明注明，实际时长由上游模型默认决定；MiniMax 系（`minimax-h3`）支持 4–15 秒。能力表见 `src/runtime-defaults.ts` 的 `VIDEO_DURATION_UNSUPPORTED`，按上游实测维护。
 
@@ -189,7 +241,7 @@ dsh-image-video/
     ├── media.ts              # 媒体下载 / 落地 / 摘要文本 / presentationMeta
     ├── providers/
     │   ├── types.ts          # ProviderAdapter 接口 + 通用类型
-    │   ├── threerouter.ts    # Threerouter API 适配器（默认服务商，聚合器：图片+视频）
+    │   ├── threevideo.ts    # Threevideo API 适配器（默认服务商，聚合器：图片+视频）
     │   ├── wanx.ts           # 万象（wanx）API 适配器
     │   ├── minimax.ts        # MiniMax 官方平台适配器（video-generation v2 + image_generation）
     │   └── seedance.ts       # Seedance2.5 API 适配器
@@ -204,32 +256,51 @@ dsh-image-video/
 
 | 字段 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
-| `provider` | `'threerouter' \| 'wanx' \| 'minimax' \| 'seedance'` | `threerouter` | 激活的服务商，切换后立即生效（HMR） |
-| `threerouter.apiKey` | `string` | `''` | Threerouter API Key；`provider=threerouter` 时必填 |
-| `threerouter.baseURL` | `string` | `''` | Threerouter 自定义接口地址，留空用默认端点 |
+| `provider` | `'threevideo' \| 'wanx' \| 'minimax' \| 'seedance'` | `threevideo` | 激活的服务商，切换后立即生效（HMR） |
+| `threevideo.apiKey` | `string` | `''` | Threevideo API Key；`provider=threevideo` 时必填（也可只填 `apiKeyEnv`） |
+| `threevideo.apiKeyEnv` | `string` | `''` | 凭证引用名；`apiKey` 留空时经 `ctx.credentials` 解析（如桌面端登录写入的 `THREEVIDEO_API_KEY`），留空表示不使用引用 |
+| `threevideo.baseURL` | `string` | `''` | Threevideo 自定义接口地址，留空用默认端点 |
 | `wanx.apiKey` | `string` | `''` | 万象 API Key；`provider=wanx` 时必填 |
 | `minimax.apiKey` | `string` | `''` | MiniMax 官方平台 API Key；`provider=minimax` 或模型家族路由命中时使用，留空自动跳过该候选 |
 | `wanx.baseURL` | `string` | `''` | 万象自定义接口地址，留空用默认端点 |
 | `seedance.apiKey` | `string` | `''` | Seedance2.5 API Key；`provider=seedance` 时必填 |
 | `seedance.baseURL` | `string` | `''` | Seedance2.5 自定义接口地址，留空用默认端点 |
-| `defaultImageProvider` | `'' \| 'threerouter' \| 'wanx' \| 'seedance'` | `''` | 默认图片服务商，留空跟随激活服务商，adapter 用其内置默认模型 |
-| `defaultVideoProvider` | `'' \| 'threerouter' \| 'wanx' \| 'seedance'` | `''` | 默认视频服务商，留空跟随激活服务商，adapter 用其内置默认模型 |
+| `defaultImageProvider` | `'' \| 'threevideo' \| 'wanx' \| 'seedance'` | `''` | 默认图片服务商，留空跟随激活服务商，adapter 用其内置默认模型 |
+| `defaultVideoProvider` | `'' \| 'threevideo' \| 'wanx' \| 'seedance'` | `''` | 默认视频服务商，留空跟随激活服务商，adapter 用其内置默认模型 |
 | `defaultImageModel` | `string` | `''` | 默认图片模型，留空用服务商内置默认（模型取值链：调用参数 > 此配置 > 内置默认） |
-| `defaultVideoModel` | `string` | `''` | 默认视频模型，留空用服务商内置默认（threerouter 内置 `minimax-h3`） |
+| `defaultVideoModel` | `string` | `''` | 默认视频模型，留空用服务商内置默认（threevideo 内置 `minimax-h3`） |
 | `defaultImageSize` | `string` | `'1024*1024'` | 默认图片尺寸，形如 `宽*高`（百炼接口要求 `*` 分隔） |
-| `defaultVideoDuration` | `number` | `5` | 默认视频时长（秒），范围 1-10 |
+| `defaultVideoDuration` | `number` | `5` | 默认视频时长（秒），范围 1–30（上限由上游模型校验） |
 | `timeoutMs` | `number` | `60000` | 单次 HTTP 请求超时（毫秒） |
 | `pollIntervalMs` | `number` | `5000` | 视频任务轮询间隔（毫秒） |
-| `pollTimeoutMs` | `number` | `300000` | 视频任务整体超时（毫秒），超时中止轮询 |
+| `pollTimeoutMs` | `number` | `600000` | 视频任务整体超时（毫秒），超时中止轮询 |
 | `retryTimes` | `number` | `3` | 可重试错误的最大重试次数（鉴权/配额错误不重试） |
 | `outputsDir` | `string` | `'./outputs'` | 生成媒体落地目录（相对路径基于进程 cwd） |
 | `imageTransport` | `'auto' \| 'async' \| 'sync'` | `'auto'` | 图片传输；auto 优先异步，异步端点未启用时降级同步 |
 | `imageUnknownStatePolicy` | `'fail' \| 'resubmit-same-key'` | `'fail'` | 提交超时/5xx 状态未知时的策略；默认只反查、不重提 |
 | `watermark.enabled` | `boolean` | `true` | 是否在落盘/附件前叠加品牌水印 |
-| `watermark.text` | `string` | `'Threerouter'` | 水印文字；空文本跳过后处理并保留原图 |
+| `watermark.text` | `string` | `'Threevideo'` | 水印文字；空文本跳过后处理并保留原图 |
 | `watermark.position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-right'` | 水印锚点 |
 | `watermark.opacity` | `number` | `0.68` | 水印透明度，0–1 |
 | `watermark.fontSizeRatio` | `number` | `0.032` | 字号相对图片宽度比例 |
+
+### 凭证缝引用（`apiKeyEnv`）
+
+每个服务商的凭证块都支持 `apiKeyEnv`：`apiKey` 留空时按该引用经宿主的 `credentials` 服务解析（`ctx.credentials.resolve(credentialRef(ref))`）。取值优先级为「明文 `apiKey` > 引用解析值」，两者都取不到时按未配置响亮报错。用途是让部署只在配置里声明引用名，把明文留给宿主凭证存储——桌面端登录 Threevideo 后写入的 `THREEVIDEO_API_KEY` 因此可直接复用：
+
+```yaml
+- id: image-video
+  config:
+    provider: threevideo
+    threevideo:
+      apiKeyEnv: THREEVIDEO_API_KEY   # 不内联明文
+```
+
+候选服务商过滤按「明文或引用任一非空」判定，只声明引用的服务商不会被跳过。
+
+### 媒体模式注入（`mediaMode`）
+
+桌面 composer 的媒体 tab 通过回环路由 `POST /image-video/defaults` 写入 `mediaMode`（`text` / `image` / `video`）。当它为 `image` / `video` 时，插件在 `agent/pre-step` 监听里向本步追加一条插件来源的指令消息（`source.kind = 'image-video.media-mode'`），要求模型直接调用对应生成工具、并告知当前生效的尺寸/风格/比例/时长；`text` 与未设置不注入。门控：只在 `next()` 成功且本步确实带来新的用户输入时注入（工具循环的后续步不重复），子代理（`origin === 'subagent'`）不继承主会话的媒体模式。
 | `watermark.marginXRatio` / `marginYRatio` | `number` | `0.028` / `0.012` | 水平/垂直边距比例 |
 | `watermark.glowEnabled` | `boolean` | `true` | 是否启用柔光描边 |
 | `watermark.glowColor` / `glowBlurRatio` | `string` / `number` | `'#ffffff'` / `0.18` | 描边颜色与模糊半径比例 |
@@ -254,6 +325,9 @@ dsh-image-video/
 |---|---|---|---|
 | `tools` | `inject = ['tools']` 顶部声明 | 插件必需，缺失则不加载 | dsh-base |
 | `attachments` | `ctx.inject(['attachments'], cb)` | `generate_image` 必需，`generate_video` 不依赖 | dsh-base 的 `attachment-local` |
+| `credentials` | `ctx.get('credentials')`（可选） | 可选：缺失时 `apiKeyEnv` 引用解析为未配置，显式 `apiKey` 仍可用 | dsh 的 credentials 服务 |
+| `agents` | `ctx.inject(['agents'], cb)`（可选） | 可选：缺失时不做媒体模式注入，工具本身照常注册 | dsh-base 的 agent 循环 |
+| `webServer` | `ctx.inject(['webServer'], cb)`（可选） | 可选：缺失时跳过 outputs 只读路由与 defaults 热更新路由 | 桌面宿主 |
 
 `generate_image` 通过 `ctx.inject` 显式声明 attachment 服务依赖：服务挂载时注册工具，服务撤销时 fiber dispose 自动注销。`generate_video` 始终注册。`cordis.patch.yml` 用 `- insert` 新增 `image-video` 行，不覆盖任何现有插件行，升级保持组合兼容。
 
@@ -323,7 +397,7 @@ dsh --profile <profile> --dump-config | grep -A3 "dsh-image-video"
 
 ## 服务商 API 参考
 
-- **Threerouter**：[统一媒体生成 API](https://threerouter.com/)（`/v1/media/generations` 创建 → `/v1/media/{id}` 轮询 → `/v1/media/{id}/content` 下载）
+- **Threevideo**：[统一媒体生成 API](https://threevideo.com/)（`/v1/media/generations` 创建 → `/v1/media/{id}` 轮询 → `/v1/media/{id}/content` 下载）
 - **万象 wanx（阿里云百炼 DashScope）**：[文生图](https://help.aliyun.com/zh/model-studio/text-to-image-guide) / [文生视频](https://help.aliyun.com/zh/model-studio/video-generation)
 - **Seedance2.5（火山引擎 Ark）**：[文生图](https://docs.volcengine.com/docs/85621/1616429) / [文生视频](https://docs.volcengine.com/docs/82379/1520757)
 

package/cordis.patch.yml

@@ -16,10 +16,10 @@
     - id: image-video
       name: 'dsh-image-video'
       config:
-        # 激活的生成服务商，threerouter（默认，图片+视频） | wanx | seedance
-        provider: threerouter
-        # Threerouter 凭证；provider=threerouter 时使用（图片+视频统一入口）
-        threerouter:
+        # 激活的生成服务商，threevideo（默认，图片+视频） | wanx | seedance
+        provider: threevideo
+        # Threevideo 凭证；provider=threevideo 时使用（图片+视频统一入口）
+        threevideo:
           apiKey: ''
           baseURL: ''
         # 万象（阿里云百炼）凭证；provider=wanx 时使用
@@ -34,9 +34,9 @@
         seedance:
           apiKey: ''
           baseURL: ''
-        # 默认图片服务商；留空跟随激活服务商（threerouter | wanx | seedance）
+        # 默认图片服务商；留空跟随激活服务商（threevideo | wanx | seedance）
         defaultImageProvider: ''
-        # 默认视频服务商；留空跟随激活服务商（threerouter | wanx | seedance）
+        # 默认视频服务商；留空跟随激活服务商（threevideo | wanx | seedance）
         defaultVideoProvider: ''
         # 默认图片尺寸（百炼接口要求 * 分隔，如 1024*1024）
         defaultImageSize: '1024*1024'
@@ -59,7 +59,7 @@
         # 最终图片水印：与模型结果使用同一 outputsDir 和 attachment 流程
         watermark:
           enabled: true
-          text: 'Threerouter'
+          text: 'Threevideo'
           opacity: 0.68
           position: bottom-right
           fontSizeRatio: 0.032