前言¶
在 DeepSeek Harness（DSH）里做智能体时，对话模型能写方案、改代码，但「出一张可用的图」或「生成几秒演示视频」往往还要切到别的 Web 界面或自己接 HTTP API。密钥写进仓库、进度条假跑、生成结果散落在临时目录，也会拖慢迭代。
下面介绍社区插件 dsh-agnes-image（维护者 SZTMBABY，GitHub 仓库 SZTMBABY/dsh-agnes-image）。它在 DSH 侧注册两个 Agent 工具，并提供带 Images / Videos / Library / Settings 四个标签页的侧边栏面板；图像与视频走 Agnes 官方接口，提示词可在面板里一键优化，密钥只在 Settings 里填写并落在本机 DSH 数据目录，不进代码仓库。
这是什么¶
dsh-agnes-image 是 DSH 的客户端类 bundle 插件：宿主侧 index.js 负责配置、调用 Agnes、落盘与工具注册；浏览器侧 client.js 负责侧边栏与面板 UI。仓库按 DSH bundle 格式手写，无构建步骤，README 未声明额外运行时依赖。
能力概览（与 README 一致）：
- 静图：模型
agnes-image-2.5-flash，最高 4K，可选比例与 1–4 张批量。 - 视频：默认模型
agnes-video-2.5-flash，720P，时长 4–12 秒；任务在 Agnes 免费队列上执行，队列繁忙时插件会退避重试而非直接失败。 - 提示词优化：
agnes-3.0-flash（或可选复用 DSH 当前对话模型）。 - 面板与 Agent 工具共用同一条宿主代码路径，行为一致。
插件目录页：skillhub.cn/plugins/SZTMBABY/dsh-agnes-image。社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；安装前请自行查看源码与 MIT 许可证。当前 npm 包版本为 1.4.2，要求 Node.js >= 20。
核心功能¶
Agent 工具¶
对话中可直接调用以下工具（名称来自 README）：
| 工具 | 作用 |
|---|---|
agnes_generate_image |
文生图 / 参考图生图，返回磁盘绝对路径 |
agnes_generate_video |
创建视频任务、轮询、下载；默认最长阻塞约 15 分钟 |
agnes_generate_image 主要参数：prompt（必填）、size（1K/2K/3K/4K）、ratio（如 1:1、16:9 等）、count（1–4）、reference_images（公网 HTTPS URL 或 data:image/...;base64）。
agnes_generate_video 主要参数：prompt（必填）、mode（text / keyframe / reference）、seconds（"4"–"12"，默认 "5"）、size（默认流程为 720P）、aspect_ratio、首尾帧或参考图/音频等；各 mode 的媒资规则插件会在本地校验后再请求上游。
侧边栏面板¶
左到右四个标签：Images、Videos、Library、Settings。
- Images：提示词、尺寸、比例、数量、可选参考图；提交后尽快出缩略图。
- Videos：模式、时长、画幅、分辨率；提交后展示队列与渲染进度并自动轮询；完成后以海报形式展示，通过「用默认应用打开」交给系统播放器，不在面板内 inline 播放。
- Library：分段切换图片库与视频库，卡片网格展示；视频仅海报。
- Settings：粘贴并保存 Agnes API Key；未配置时生成按钮禁用并说明原因。
进度展示原则：图片任务为单次调用，使用不确定进度条加已用秒数，不伪造百分比；视频任务展示上游真实进度（如 0/10/70/100），长时间停在同一百分比时会切换为条纹样式并注明来源，避免假进度。
AI 提示词优化¶
图片与视频输入框均提供 AI Optimize：先展示改写卡片（仅改写内容，原标题留在输入框），可 Adopt / Discard / Retry。默认后端为 Agnes（agnes-3.0-flash，与生成共用 Key）；也可在设置中选择 dsh，复用 Harness 当前对话模型（无可用 LLM 时该选项不可用）。
调用的 Agnes 接口¶
| 用途 | 模型 | 端点 |
|---|---|---|
| 图像生成 | agnes-image-2.5-flash |
POST https://api.agnes-ai.cn/v1/images/generations |
| 视频生成 | agnes-video-2.5-flash（默认；720P） |
POST https://api.agnes-ai.cn/v1/videos，轮询 GET https://api.agnes-ai.cn/agnesapi?video_id=&model_name= |
| 提示词优化 | agnes-3.0-flash |
POST https://api.agnes-ai.cn/v1/chat/completions |
更细的 API 说明见 Agnes 文档（README 链接）：图像、视频、文本。
安装与启用¶
在已安装 DSH CLI 的环境中，README 给出的安装方式为：
npm install dsh-agnes-image
或使用 profile 向 Harness 添加插件：
dsh plugin --profile <your profile> add dsh-agnes-image
安装后打开面板 Settings，粘贴 Agnes API Key 并保存。凭证保存在本机 %DSH_HOME% 数据目录（settings 命名空间 agnes-image），仓库内不携带密钥。配置完成前，生成相关控件保持禁用。
典型用法¶
在对话里出图¶
向 Agent 说明需求，让其调用 agnes_generate_image。工具返回示例形态如下（路径因环境而异）：
Agnes generated 1 image (agnes-image-2.5-flash, 2K 1:1).
Saved to disk — absolute paths:
C:\...\default-workspace\agnes-images\2026-10-16\190212-测试：一只戴宇航头盔的柴犬.png (836.9 KB)
可在后续步骤中让 Agent 读取这些绝对路径，或到面板 Library 中查看并打开文件。
在面板里生成视频¶
- 打开侧边栏 Videos，填写
prompt，选择mode、秒数、画幅与分辨率。 - 若为
keyframe，补充首帧/尾帧；若为reference，添加参考图或音频（本地路径在符合大小与边长限制时会被内联为data:URL）。 - 提交后观察进度文案与百分比；完成后在面板查看海报，用系统默认应用打开成片；历史条目集中在 Library。
优化提示词再生成¶
在 Images 或 Videos 输入框写好意图后点 AI Optimize，确认改写再 Adopt 回输入框，然后照常生成。视频侧改写会额外考虑运动、镜头与节奏。
适用场景与注意¶
适合谁
- 已在 DSH 里做智能体，希望对话内直接出 4K 静图或数秒 720P 视频，并能把文件路径交回工作区。
- 希望用同一套 Agnes Key 在面板与工具间复用，且不愿把密钥写进项目代码。
- 需要诚实进度反馈与本地库管理，而不是在聊天里贴临时外链。
使用前请知悉
- 插件以当前 DSH 进程权限运行，会向
api.agnes-ai.cn发起请求并向本地磁盘写入生成物；安装前请阅读index.js/client.js与许可证。 - 视频依赖 Agnes 队列与账号配额；README 说明免费队列在繁忙时会退避重试，耗时会随上游变化。
reference模式下本地媒资有体积与像素边长限制（如单文件 15 MB、边长 256–5760 px），超出会报错。- 社区目录与 GitHub 星标（当前约 3）仅作发现与参考，不代表官方背书。
结尾¶
dsh-agnes-image 把 Agnes 的静图、短视频与提示词优化收进 DSH：两个 Agent 工具负责自动化，侧边栏负责交互与密钥管理，生成结果落盘并可在 Library 中交接给桌面应用。若你在 Harness 生态里做「能画图、能出片」的智能体，可从目录页或仓库 README 的安装命令起步，再在 Settings 中配置 Key。
