- Home
- Plugin
- Visione, voce e multimodale
- dsh-plugin-agnes-studio
dsh-plugin-agnes-studio
skillre/dsh-plugin-agnes-studio
Agnes AI 免费生图与生视频工作台:侧栏看板、可调参数的图片/视频生成,以及会话内可调用的 DSH 工具
Installazione
dsh plugin --profile web add github:skillre/dsh-plugin-agnes-studioREADME
@skillre/dsh-plugin-agnes-studio
状态:experimental · 实测 DSH
0.2.2-rc.2(2026-11-13)
用 Agnes 的免费模型生成图片和视频,有两个入口:
- 侧栏看板:在 DSH 左侧栏点「Agnes 工作室」。左侧是参数区(提示词、模型、分辨率、比例), 右侧是结果画廊,两边各自滚动,生成按钮固定在参数区底部,不用滚动就能点到。 分辨率、模式这类 2–4 选项用分段控件直接摊开,比例、时长这类大集合用带比例示意图的胶囊标签。 点结果卡上的「查看大图」(或直接点缩略图)会在面板内放大查看:滚轮缩放、拖动平移、 双击放大、Esc 或点背景关闭,多张图时用左右方向键连续翻看。看板不弹新窗口,也不跳出应用。
- 会话内工具:直接说「画一张…」「生成一段…视频」,模型调用
agnes_image/agnes_video, 图片作为真正的 DSH 图片块出现在对话里。
它能做什么
| 能力 | 模型 | 参数 |
|---|---|---|
| 文生图 / 图生图 / 多图合成 | agnes-image-2.5-flash(默认)、2.1-flash、2.0-flash | 分辨率档 1K/2K/3K/4K,比例 8 种,最多 8 张参考图 |
| 文生视频 / 首尾帧 / 参考素材 | agnes-video-2.5(默认)、agnes-video-2.5-flash | 720P–2K(Flash 固定 720P),比例 6 种,4–12 秒,可选 seed,首帧/尾帧/参考图/参考音频/参考视频 |
参数不是自由填写的:看板的下拉项由模型能力表生成,Host 在发请求前按同一张表校验。
选 agnes-video-2.5-flash 时分辨率只剩 720P,因为上游对该模型只接受 720P —— 这样 UI 永远不会
给出一个上游会以 HTTP 400 拒绝的值。
结果可以接着改,改出来的版本叠在同一张卡片里。 成功的结果卡片上有「继续编辑」:提示词、 模型、分辨率、比例和参考图会带回左侧表单,并且这张图会作为下一张的参考图(图生图)一起提交 —— 想改什么、要保留什么直接写进提示词即可。失败的卡片上有「调整后重试」:不必重打提示词, 原来的参数回到表单,改到满意再生成。
改出来的新版本不另开一张卡,而是叠在原条目上,做法跟微信「发送后合并展示」的多图一致:卡片 左上角显示「第 2 / 3 版」,最新的一版是正面那张,其余版本从左右两侧露出自己那张图的窄边—— 不是灰色装饰条,露的是真实的图,所以没动手就能看出「后面还有几张」。四种操作互不冲突:
- 左右滑动——触控板双指左右滑、或者按住图片横向拖,一次翻一版,就像翻一叠照片;键盘也可以用 ←/→。滑到头就停住,不会莫名其妙跳回另一端。
- 发牌式切换——翻页时新的一版从侧面带着轻微旋转和缩放压到正面,被换下的那一版往反方向缩回 并淡出,像从牌堆里发一张牌;不是原来那种「一闪就换图」。
- 卡片尺寸分毫不动——所有版本早就加载好、卡片高度取各版本里最高的那个,翻页只改变每张图的 位移与透明度,所以卡片不会闪、不会抖、不会变高变矮,鼠标下和手指下的东西不会跑走。
- 不会把整屏拖走——堆叠卡与普通卡同宽,任何内容都不越出卡片,画廊不会因为堆叠出现横向滚动条; 竖向滚轮仍然滚动画廊,横向手势只翻版本,不会被浏览器的横向平移抢走。
- 跳转——点卡片下方那一排版本数字,直接跳到某一版,它的查看 / 下载 / 继续编辑 / 删除也就都 指向这一版;点「1」回到跟随最新版,之后新生成的改动版仍会自动出现在正面。
- 展开——点「展开」把整条线拆成一张张独立卡片,每张都能单独操作,再点「收起」收回堆叠。
你改过几次,历史里看到的是一条「原图 → 修改版 → …」的线,而不是一堆看不出关系的卡片。
视频结果不在此列:上游没有在既有视频上编辑/续写的接口,「参考视频」要求公网可访问的 URL 且只有
付费的 agnes-video-2.5 支持,所以成功视频卡片只提供下载与删除;失败视频仍可「调整后重试」。
安装
由用户在 DSH Desktop Client 或 Web UI 的 Plugins / 插件管理 里选择来源并确认安装。
发布后输入 npm 包名(如 @skillre/dsh-plugin-agnes-studio@0.1.0);未发布时可用已构建
.tgz 的绝对路径,但需先确认目标客户端接受该来源。
安装后到 Plugins → 本插件 → 配置 里确认 enableTools 为开(默认开),左侧栏就会出现入口。
配置 API Key
插件不把密钥写进配置文件。按以下顺序解析,每次调用都重新读取,所以换 key 不需要重启:
- DSH 凭据服务里名为
AGNES_API_KEY的记录(推荐); - 环境变量
AGNES_API_KEY; - 都没有 → 看板显示「还没有配置 API Key」并禁用生成按钮,会话里的工具返回
not-configured。
在 https://platform.agnes-ai.com 创建免费 key(无需绑卡)。密钥只在 Host 侧使用, 不会发送到浏览器,也不会写进生成记录。
配置项
全部可选,在插件行的 config 里覆盖:
| 键 | 默认 | 说明 |
|---|---|---|
baseUrl | https://apihub.agnes-ai.com/v1 | Agnes API 根地址,不带结尾斜杠 |
credentialRef | AGNES_API_KEY | 凭据服务里的记录名 |
apiKeyEnv | AGNES_API_KEY | 凭据为空时回退的环境变量名 |
dataDir | '' → $DSH_HOME/agnes-studio | 生成记录索引与媒体文件目录(插件独占)。留空时跟随 DSH home,避免隔离 profile 写进用户真实目录 |
enableTools | true | 是否注册 agnes_image / agnes_video 工具 |
historyLimit | 200 | 保留多少条记录;超出时最旧的连同文件一起删除 |
imageTimeoutMs | 360000 | 生图超时(上游建议 60–360 秒) |
videoTimeoutMs | 900000 | 视频任务总超时,含排队 |
pollIntervalMs | 2000 | 视频任务轮询间隔 |
retryAttempts | 5 | 「持续重试」总尝试次数(含第一次);1 关闭该功能,回到单次重试 |
retryBaseDelayMs | 15000 | 第二次尝试前的等待,之后每次翻倍 |
retryMaxDelayMs | 180000 | 退避上限,避免几分钟都不动一次 |
权限与副作用
- 网络:只访问
baseUrl(默认apihub.agnes-ai.com)以及它返回的媒体地址。 第三方 CDN 的下载不带 API Key。 - 文件:只写
dataDir(默认$DSH_HOME/agnes-studio),一个index.json加media/下的媒体文件。 文件名是随机 UUID;读取时再校验一次 id 形状,路径穿越不可达。 - 密钥:只经凭据服务或环境变量读取;不写日志、不进生成记录、不发给浏览器。
- 浏览器:看板通过 DSH Connection 的
/api路由通信,走同一套 Host/Origin 与登录态校验; 生成的媒体也经同一道栅栏提供,不是公开可读。
数据与清理
生成记录在 $DSH_HOME/agnes-studio(通常是 ~/.dsh/agnes-studio):
# 删除全部生成记录与文件(等价于看板的「清空全部」)
rm -rf ~/.dsh/agnes-studio
看板里单条删除、清空全部都会同时删掉索引项和磁盘文件。
dataDir 留空(默认)时跟随 $DSH_HOME,只有在 DSH_HOME 未设置时才回退到 ~/.dsh ——
这样在隔离或自定义 home 的 profile 里,数据不会落进用户真实安装目录。
卸载与回滚
见 UNINSTALL。卸载插件不会自动删除 ~/.dsh/agnes-studio;
如不再需要,按上面的命令手动删除。
后台任务与提示词优化
- 任务在 Host 上跑,不占用看板。 生成请求提交后 Host 立刻返回,任务在 Host 里继续;
切换面板、切到别的页面、甚至刷新整个 Web 页面,任务都不会中断。回到看板时,正在跑的任务
从 Host 的
state.running读出来继续显示(含进度条与「取消」),跑完后自动变成结果卡片。 之前「任务没中断但回来什么都看不到」是因为在跑标记只存在客户端组件里,组件卸载就没了。 还没有记录的新任务在画廊里占一张占位卡,并在参数区上方显示后台提示条;重试不吃这一套, 见下一条。 - 重试按记录 id 走 Host。点击失败卡片的「重试」是把记录的 id 交给 Host,由 Host 用这条 记录自己保存的原始请求重新发起 —— 不依赖看板内存里「上次提交了什么」,所以离开再回来、 刷新页面之后重试同样有效(实测整页刷新后重试仍能发起任务)。重试会原地更新那一行, 不会每点一次就多一条失败记录;进度也显示在这张卡片自己里(转圈 +「正在重试,完成后会 更新这条记录」+「取消」),不会在旁边多出一张「新任务」卡片再等它合并,也不会重复出现在 后台提示条里。
- 持续重试:队列满时不用一直点。 免费版视频队列会连续几分钟返回「队列已满」,手动点一次重试
通常还是撞在同一堵墙上,用户最后只能反复点。失败卡片因此多了一个「持续重试」:Host 会按
15s → 30s → 60s → 120s → 180s(封顶)的退避自己重排,最多 5 次,期间卡片显示「第 2 / 5 次
尝试」和「N 秒后自动重试」倒计时;这一段等待发生在 Host,关掉看板或刷新页面都不会中断,
回来继续看到进度。只重试可能自愈的失败(队列满、限流、5xx、超时、下载中断);参数错、
余额不足、Key 无效这类确定性失败一次就报出来,不会白等。中途可以「取消」。重试次数与退避
间隔可配置(
retryAttempts/retryBaseDelayMs/retryMaxDelayMs),retryAttempts: 1即关闭该功能、回到单次重试。最终结果只写一条记录,并标出「共尝试 N 次」。 - 继续编辑与调整后重试。点成功图片卡片的「继续编辑」时,看板把这条记录的原始请求
(提示词、模型、分辨率、比例、参考图)回填到左侧表单,并在表单顶部显示来源缩略图;提交时
Host 从磁盘读出这张图的字节,内联成
data:URI 作为图生图的参考图发给上游 —— 生成的图片走 的是同源鉴权路由,上游取不到它,所以内联发生在 Host 侧,浏览器只传「用哪条记录」。 点失败卡片的「调整后重试」只回填提示词与参数(失败任务没有产物可当参考图),改完按新记录重跑。 两种操作都不复用原记录 id:原记录留着,新记录带derivedFrom与「承接 …」标记;如果源记录 在提交前被删掉,Host 会当场拒绝并说明原因,不会留下无法解释的失败卡。 - 提示词优化:提示词框里的「优化提示词」调用 Agnes 的文字模型(
agnes-3.0-flash)把草稿 写得更具体,按生图/生视频给不同建议(生图补构图、光比、镜头;生视频补运动、运镜、节奏), 并保持你原来的语言与主体。改写后可点「撤销」回到原文;继续手动编辑即视为接受。 - 取消:在跑的任务可以在看板上直接取消,取消不会留下失败记录。
已知限制
- 视频是异步任务:提交后 Host 轮询上游直到完成。队列满时上游返回 HTTP 503
video_queue_full,看板会明确说明这是上游并发容量限制(不是参数问题)并标为「可重试」。 实测该状态可连续持续数分钟,属于上游侧排队,不是插件故障。 - 账户余额不足时上游返回 403
insufficient_user_quota,插件会报成「余额不足」并说明 Key 本身 有效 —— 不会误报成「API Key 无效」。付费视频模型(agnes-video-2.5)会消耗额度,agnes-video-2.5-flash是免费的但共享队列。 - 参考素材必须是公网可访问的 HTTPS 地址或
data:URI。localhost、内网地址、明文 HTTP 在发请求前就被拒绝 —— 上游自己去取素材,这类地址只会延迟失败。 - 视频结果不支持「继续编辑」:上游视频接口只有文生视频、首尾帧和参考素材三种模式,没有在
既有视频上编辑、续写或重混的能力;唯一的「参考视频」输入要求公网可访问的 URL,且只有付费的
agnes-video-2.5接受。本插件把结果存在本地、用同源鉴权路由提供,没有把本地视频变成公网地址的 通道,所以成功视频卡片只有下载与删除;失败视频仍可「调整后重试」。 - 图片「继续编辑」把结果内联成
data:URI 作为参考图,不需要图片公网可访问;代价是请求体会随 原图尺寸增大(1K 约 2 MiB,4K 可达 20 MiB 以上)。上游对超大请求可能拒绝,表现为普通失败, 可换低分辨率档位后重试。 agnes-video-2.5-flash不支持参考视频,且最多 5 张参考图(2.5是 8 张)。- 生成记录是本地的,不跨设备同步;
historyLimit之外的最旧记录会被删除。 - 看板一次只跑一个任务(避免重复提交造成重复计费与排队加深)。任务在后台运行期间表单保持 禁用,点「取消」可以结束它。
- 图片查看器只在面板内放大,不会打开系统图片查看器或新窗口:生成图是本地存储、 靠会话鉴权访问的,交给外部程序既会 401 也会绕开 DSH 的窗口策略。视频仍在卡片里就地播放, 查看器只处理图片。
- 同一
dataDir只应由一个插件实例使用:索引写入在单个 handle 内串行化,两个实例指向同一目录 仍可能互相覆盖。 - 图片以 DSH 附件形式进入对话;视频以同源 URL 返回,在对话里给出可打开的位置, 不是视频块。
- Agnes 的免费额度、模型清单与参数上限由上游随时调整;本插件按 2026-11-11 的实测契约实现, 上游新增能力需要更新插件。
验证记录
- 离线测试 206 项:参数校验、响应解析、错误映射、存储并发与淘汰、路由栅栏、媒体路径形状、
Range 请求、schema 契约、工具参数映射、看板渲染(含重试就地进入进度态、不新增占位卡;
完成图回填表单并把来源作为 symbolic 参考图提交;失败记录回填后可调整;视频结果不提供继续编辑)、
版本堆叠(照片堆)(血缘归并成一张卡、单条不加堆叠外壳、横向滚轮滑一次翻一版并可在
两端夹住而不回绕、竖向滚轮不翻页、方向键与横向拖拽同样翻页、切换版本时不新增/移除/重排任何
节点(结构性防抖)、整叠内容不越出卡片(stage 没有负 margin / padding,条带是卡片的子节点,
不留出任何会撑宽网格的宽度)、发牌位移真的写在不同 offset 上(正面 identity、
邻居带 translate/rotate/scale,翻页后 offset 重新分配而节点数不变)、点数字跳到某一版并在
移开鼠标后停在那一版、卡片操作作用于正在看的那一版、扇形永远只画「别的」版本而不会重复当前版、
翻到旧版后扇形换到另一侧、展开成独立卡片后最新版与最旧版一定可达(步进函数在版本数 × 步长的
组合上穷举)、可收起、源记录被删的孤儿版本仍独立成条目)、持续重试(只重试可能自愈的失败、
达到上限只留一条记录并标出尝试次数、未开启时仍是单次重试、等待期间发布下一次时间、拒绝重试
栅栏接受
retryAll)、图片查看器交互、后台任务生命周期(state 报告在跑任务、后台失败落成记录、 取消不留记录、dispose 中止所有任务、优化提示词),以及打包后的 client bundle(走真实 loader 信封加载并渲染两个注册面)。 - 打包 tarball 装入一次性隔离 profile:
--dump-config合成、有界真实启动、经认证的/api路由调用、真实生图并下载字节、重启后记录与文件仍在、删除后文件消失。 - 真实 headless Chrome 驱动 DSH Web 应用,共 48 项(其中 2 项重试、3 项继续编辑、12 项版本堆叠
检查需要真实 API Key,无 Key 时跳过并显式报告):侧栏入口、看板渲染、双栏布局(实测两栏并排且参数区不占满宽度)、
模型派生控件及其控件形态(4 档分辨率是分段控件、8 种比例是胶囊标签)、Flash 收窄分辨率、
生成按钮在视口内可直接点到、画廊卡片与 4:3 缩略图裁切、分类筛选真的改变结果、明暗两套主题下
表面与文字颜色确实跟随、图片查看器(覆盖整个视口、缩放改变实际布局、Esc/背景关闭、点图不关闭、
方向键翻页并重置缩放、关闭后焦点回到触发控件)、提示词优化按钮就位、空闲时不会出现假的
「生成中」界面、重试就地渲染(点失败记录的「重试」后同一张卡片进入进度态,占位卡数量为 0、
后台提示条不重复出现、卡片数不变,跑完仍是同一条记录原地更新)、继续编辑(点完成图片的
「继续编辑」后提示词回填、来源缩略图出现、卡片数不变、提交按钮变成「生成修改版」;提交后经
真实
data:URI 图生图生成新记录,卡片数 +1、新卡片带「承接」血缘,存储里保留 symbolic 参考 与derivedFrom)。版本堆叠(照片堆):续图跑完后不新增卡片,而是并入原条目的堆叠 (卡片数不变、出现 1 个堆叠、露出 1 个真实画面窄边、版本数字排到 2 个、徽标显示 2 个版本、 最新版带「承接」血缘);横向不溢出——遍历面板内所有可滚动容器要求没有一个出现scrollWidth > clientWidth,网格自身也不许溢出,且 stage 与卡片实测同宽(这正是「整屏被拖走」 的机器化验收);条带真的画出来了——不是看elementFromPoint(它看不见pointer-events:none的装饰),而是只截条带那一列像素,要求与正面同高的照片像素不同; 发牌动画真的在动——先在旧版上发起一次真实滚轮翻页,再用requestAnimationFrame逐帧采样 计算样式的transform,要求抓到至少一个既非起点也非终点的中间值(纯淡入淡出会一帧都抓不到); 随后用真实触控板式横向滚轮滑一次,要求确实切到旧版、徽标与版本数字同步、且卡片与图片区的getBoundingClientRect逐个字段与前一次完全相等;再反方向滑回最新版,卡片尺寸仍不变;用 真实鼠标拖拽图片横向 130px,要求拖动过程中整叠图片确实跟手(deck 上读到非 0 的位移变量)、 松手后翻页、没有误开大图、松手后位移被清空、卡片尺寸不变;方向键左右各按一次同样只在两个 版本间移动且尺寸不变;竖向滚轮要求不翻页(并且若画廊可滚动则必须滚动);点版本数字「2」 固定旧版后,徽标、数字栏同步,鼠标移开仍停在那一版、卡片高度不变、露出条也换到左侧并在画它 自己那张图;整套堆叠切到暗色主题要求条带仍在画真实图片、宽度不为 0(前面对比主题的截图在 任何堆叠出现之前就拍了,暗色下的堆叠只有这里会被真正看一眼);再种入一条6 版本深链条并 整页刷新:版本数字必须 6 个都在、一个都不能被裁掉,扇形封顶 2 条,徽标报 6 个版本,数字栏能 到达最旧版,用横向滚轮连滑 8 次必须能走回最新版,且 6 版本的卡片包围盒始终不变;点「展开」 变成 2 张独立卡片、点「收起」收回。 证据见docs/evidence/。 - 带真实 key 的端到端实测(不进 CI):提交生图 → 切换离开看板 → 回到看板时任务仍在运行且 显示进度 → 跑完变成结果卡片;同样的任务在整页刷新后回到看板仍然显示为运行中,跑完落成 结果卡片;提交生视频失败 → 整页刷新 → 点失败记录的「重试」→ 真的发起任务,且卡片数不增加; 点失败记录的「重试」→ 进度只出现在那张卡片里(不新增「新任务」卡)→ 跑完后同一条记录在原位 变成生成结果(实测整页重载后仍成立);对成功图片点「继续编辑」→ 回填并显示来源 → 提交后上游 接受这张图作为参考图 → 新记录落成、原记录保留、新卡片带「承接」标记。
开发
npm install
npm run check # preview + typecheck + 206 项测试 + publint + pack
npm pack
隔离验证(只用自己拥有的、可丢弃的非 Desktop profile):
AGNES_API_KEY=... node scripts/verify-isolated.mjs ./skillre-dsh-plugin-agnes-studio-0.1.0.tgz
脚本自己创建临时 DSH home、装包、启动、验证,并在 finally 里停进程、删目录、核对清理完成。
Bundle
- npm:
@skillre/dsh-plugin-agnes-studio - GitHub:
skillre/dsh-plugin-agnes-studio - Cordis row / plugin name:
skillre-agnes-studio package.json#dsh.bundle.patch→cordis.patch.yml
显示元数据
locale/en.json、locale/zh.json 提供卡片标题与描述,icon.svg 是图标。
三者都随包发布(files 覆盖,exports 声明 "./locale/*.json")。
Plugin correlati
dsh-web-ui (dsh-tool-describe-image)
zhu1090093659/dsh-web-ui
modlens
liustack/modlens
ipollowork
devin-axis/ipollowork
dsh-image-gen
shanliuling/dsh-image-gen