dsh-agnes-create 0.4.1 → 0.10.3

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,76 @@ 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
+
+> 关键帧只在视频模式出现；图片模式用的是上面的「参考图」。
+
+### 参考生视频（参考图，最多 5 张）
+
+视频模式还有一栏「参考图」，用来给上游参考**风格、主体或构图**，而不是指定起止画面。最多 5 张，来源同样是「＋ 本地」和「＋ 结果」。
+
+| 给了什么 | 实际行为 |
+| --- | --- |
+| 只有参考图 | 按参考图的风格 / 主体 / 构图生成新视频（`mode: reference`） |
+| 参考图 + 首帧或尾帧 | 按关键帧生成，**参考图本次不生效**（面板会提示） |
+| 什么都不给 | 纯文生视频 |
+
+同样以 data URI 直接发给上游，不需要图床。结果信息里会标注「参考生视频」，和「图生视频」「纯文生视频」区分开。
+
+> 三种模式的优先级：关键帧 > 参考图 > 纯文本。
+
+### 提示词随图保存
+
+出图时会把这次的提示词写进图片文件本身（PNG 用 iTXt 块、JPEG 用 COM 段），所以：
+
+- 在面板里把鼠标移到结果图上，底部会浮出当初的提示词，点「复制」就能拿到；
+- 用系统看图软件、Photoshop、exiftool 打开也能看到这段文字——不依赖本插件；
+- 只对新生成的图片生效；视频不写（mp4 元数据没有通用写法）。
+
+### 浏览输出目录
+
+结果卡片右上角的 **输出目录** 按钮会把输出目录里已经存在的文件列成缩略图：
+
+- 分「图片 / 视频」两页，各带数量；
+- 点任意一张就把它显示到上方结果区，图片会连带读回当初写在文件里的提示词；
+- 只读不写，不会改动或删除你的文件；「刷新」用于同步新生成的文件。
+
+### 顶部直接切换模型
+
+标题栏「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 账号结算，本插件不涉及任何计费。
@@ -104,9 +177,9 @@ Key 从 [Agnes AI 平台](https://platform.agnes-ai.com) 获取。端点默认
 
 - 视频为**异步任务**：提交后轮询，通常需要 1–4 分钟；队列繁忙时提交会返回 `503`，插件会自动重试
 - 查询接口有频率限制，触发 `429` 时面板会显示「限流重试中…」并退避，任务不会因此失败
-- 视频只支持**文生视频**：暂无首尾帧、参考音频与视频输入（Flash 版接口本身不支持这些）
+- 视频暂不支持参考音频与参考视频输入（Flash 版接口本身不支持）；图生视频目前只走首帧 / 尾帧关键帧
 - 参考图最多 8 张；单张在浏览器侧压到长边 1280，细节极多的小字参考图重绘后可能看不清
-- 生成结果只保留最近 8 条（本次会话内），刷新页面后历史清空；文件本身在输出目录里不会丢
+- 生成历史保留最近 24 条，落盘到 `~/.dsh/agnes-create/history.json`；点「清空」会同时清掉磁盘记录，但已生成的文件仍在输出目录里
 
 ## 开发