前言¶
在 DeepSeek Harness（DSH）桌面端里做智能体，常见需求是让模型根据对话生成配图或短视频，而不是只输出文字。若自行对接各家生成 API，往往要处理鉴权、下载临时 URL、异步轮询和落盘路径，还要控制返回给模型的上下文体积。社区插件 dsh-plugin-agnes-image（维护者 neil-ji，GitHub 分类为模型推理）把 Agnes Image / Video 2.5 Flash 封装成 Agent 可调用的工具，并把 API Key 放进 DSH 内置凭据库。下面介绍它是什么、能做什么，以及如何安装与配置。
这是什么¶
dsh-plugin-agnes-image 是非官方社区插件：对 Agnes 生成接口做调用封装，与 Agnes 官方无隶属关系。当前 package 版本为 0.3.1，许可证 MIT。
它解决的主要问题是：在带 tools 服务、read_image 工具和凭据服务的 DSH 桌面端上，为 Agent 提供文生图、图生图、文生视频能力；生成结果落到会话工作目录，模型侧主要拿到文件路径、尺寸或时长、字节数，看图用内置 read_image，交付用 present，避免把整图塞进上下文。
核心功能¶
插件向 Agent 注册四个工具，后端为 Agnes Image 2.5 Flash（图片）与 agnes-video-2.5-flash（视频）。
| 工具 | 用途 |
|---|---|
agnes_text2img |
文生图：一句提示词生成 PNG，保存到工作目录 |
agnes_img2img |
图生图 / 多参考图合成：1–6 张参考图（本地路径、公共 HTTPS URL、data: URI） |
agnes_video |
文生视频 / 首尾帧 / 参考素材：4–12 秒、720P，默认轮询并下载 MP4 |
agnes_video_status |
视频任务未完成时继续等待或查询，完成后下载 MP4 |
图片¶
- 调用
POST /v1/images/generations，将结果下载保存为 PNG（返回 URL 为临时直链，不落盘会过期）。 - 从 PNG/JPEG/WebP 文件头读取真实宽高。
- 同名文件不覆盖（例如已有
art.png则写入art-2.png）。 - 尺寸档位
1K/2K/3K/4K，比例含1:1、3:4、4:3、16:9、9:16、2:3、3:2、21:9（README 注明 16:9 的 2K 为 2624×1472，而非 1920×1080）。 - 引擎不支持的参数（seed、negative_prompt、steps、
n>1）不会出现在工具 schema 中。
视频¶
Agnes 视频为异步任务：先创建，再按 video_id 轮询，完成后从 url 下载。
- 分辨率固定 720P，时长
"4"–"12"秒，n固定为 1。 - 模式：
text（仅提示词）、keyframe（first_frame/last_frame至少一个）、reference（最多 5 张参考图 + 3 段参考音频，提示词中用<Picture 1>、<Audio 1>指代）。 - 视频参考素材须为公共 HTTPS URL；本地文件与
data:URI 不可用；Flash 不支持参考视频。 - 工具默认最多等待 3 分钟；未完成则返回
pending与videoId，可再调agnes_video_status；也可设wait: false立即拿到videoId。 - 下载 MP4 后在文件头校验（
ftyp），非视频不落盘；同名不覆盖。
默认输出目录为相对会话工作目录的 agnes-output（可通过配置 outputDir 修改）。
安装与启用¶
桌面端插件页（推荐）¶
打开 设置 → 插件 → 添加插件，粘贴仓库地址：
https://github.com/neil-ji/dsh-plugin-agnes-image
本地目录（开发时）¶
plugin_manager install_bundle "F:\path\to\dsh-plugin-agnes-image"
将路径替换为本机插件目录；README 示例为 Windows 路径格式。
配置 API Key¶
图片与视频共用同一个 Key，在 设置 → Agnes 生图 中配置：
- 打开 设置 → Agnes 生图。
- 粘贴 API Key，点击保存（密码框，可临时「显示」核对）。
- 状态指示变绿后，下一次生图或生视频即生效，无需重启 DSH。
Key 写入本机 DSH 凭据库（~/.dsh/.credentials.yaml 中 AGNES_API_KEY 引用）。界面只写不读，已存 Key 不会回显到浏览器。解析优先级为：apiKey 配置（仅 CI）→ 凭据库 → 同名环境变量。
常用配置字段（完整列表见仓库 README）包括：credentialRef（默认 AGNES_API_KEY）、model（默认 agnes-image-2.5-flash）、defaultSize / defaultRatio（默认 2K / 1:1）、videoModel（默认 agnes-video-2.5-flash）、videoWaitMs（默认 180000）等。
典型用法¶
在 Agent 对话中用自然语言触发即可，README 给出如下示例方向：
# 文生图
生成一张 2K、16:9 的赛博朋克街景，霓虹灯、雨后反光
# 图生图
把 C:\work\hero.png 里的角色改成挥剑动作，保持角色和构图，2K 16:9
# 文生视频
生成 6 秒、16:9 的视频：雨后的未来城市街道，霓虹倒映，银色跑车缓慢驶过，低机位跟拍，自然环境声
# 首尾帧视频（图片需公共 URL）
用这两张图做首尾帧，5 秒、16:9，人物自然转身走向窗边
适用场景与注意¶
适合谁：需要在 DSH 桌面 Agent 里直接出图、改图或出短视频，且愿意使用 Agnes 2.5 Flash 能力链路的开发者。
引擎限制（摘要）：
- 图片：无 seed，同提示词结果不可复现；一次一张；无 negative prompt / steps；输出无 alpha。
- 视频：仅 720P；参考图、音频须公网 URL；队列满时可能返回
503 video queue is full，README 建议约一分钟后重试。
安全与权限：插件以当前 DSH 进程权限运行，会读写会话工作目录并访问网络调用 Agnes。安装前请阅读仓库源码与 MIT 许可证；README 说明代码与文档中不含示例密钥，Bearer 令牌在日志中会打码。
DSH 生态强调「一切皆插件」；插件目录页 skillhub.cn 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-plugin-agnes-image 把 Agnes 文生图、图生图与 720P 短视频封装成四个 Agent 工具，并把 Key 纳入 DSH 凭据库与设置页，减少自建 HTTP 与落盘逻辑。进一步了解与提 Issue 见：
- 目录页：https://www.skillhub.cn/plugins/neil-ji/dsh-plugin-agnes-image
- GitHub：https://github.com/neil-ji/dsh-plugin-agnes-image
