前言¶
在 DeepSeek Harness（DSH）里做智能体，常见需求是让模型直接出图、出短视频，而不是只返回文字说明。若自行封装 Agnes API，还要处理密钥分站、RPM 撞 429、多会话并发计数，以及视频转 GIF 等细节，工作量不小。
下面介绍社区插件 dsh-agnes-gen（维护者 Ylhow06，分类：模型推理）。它把 Agnes 的图像与视频能力注册为 DSH 可见工具 agnes_image、agnes_video，并内置跨进程 RPM 限流、429 退避和本机 ffmpeg 转 GIF，适合已在用 DSH、且持有 Agnes API Key 的开发者。
这是什么¶
dsh-agnes-gen 是 DSH 的 bundle 插件（当前版本 0.1.3，MIT 许可证），不是独立脚本。安装到某个 profile 后，该 profile 下的每个 session、每个 workspace 均可调用两个工具。
插件依赖宿主 DSH 自带的 @deepseek-ai/dsh-tools 与 @deepseek-ai/schemastery（在 peerDependencies 中声明），无需手动再装。Node 引擎要求：^22.19.0 || >=24.0.0。
- 目录页：https://www.skillhub.cn/plugins/Ylhow06/dsh-agnes-gen
- 源码与文档：https://github.com/Ylhow06/dsh-agnes-gen
SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
两个模型工具¶
| 工具 | 能力概要 |
|---|---|
agnes_image |
文生图、图生图、多图合成 |
agnes_video |
文生视频、首尾帧动画、图生视频 |
请求与本地处理¶
- 跨进程 RPM 限流：本地滑动窗口配额池，多会话、多进程并发时合计计数，降低触发 Agnes 429 的概率。
- 429 退避：按服务端
Retry-After等待（上限 120 秒），避免无效重试。 - GIF 转换：视频转 GIF 走本机 ffmpeg，不额外计费；未安装 ffmpeg 时降级为仅返回 mp4。
- 密钥分站：中国站（
cn）与国际站（intl）两套 Key 分开保存，互不通用。 - 图形配置：在 DSH Web GUI「插件」页配置站点、API Key、RPM 预设、模型白名单、ffmpeg 路径等（DSH
0.1.6为插件自带配置卡，0.1.7起为 DSH 原生表单，字段含义一致）。 - 内置技能：附带
agnes-image、agnes-video技能，引导 AI 正确调用工具。
DSH 版本适配¶
| DSH 版本 | 状态 | 需要做什么 |
|---|---|---|
0.1.6-alpha.2 起的 0.1.x（含其后 alpha / rc / 正式版） |
支持 | 无 |
0.2.0-rc.1 起的 0.2.x（含其后 rc / 正式版） |
支持（需插件 0.1.2+） |
将插件升到 0.1.2 或更高 |
早于 0.1.6-alpha.2 |
不支持 | 向仓库提 issue |
同一条 0.x 线内升级 DSH（例如 0.1.7-rc.1 → 0.1.8-alpha.1）一般无需改插件。配置修改后立即生效，受支持版本均无需重启。
安装与启用¶
插件可在 Web、Desktop、TUI 三种 DSH 界面下运行。
图形界面（推荐）¶
打开 DSH Web GUI → 侧栏「插件」→ 右上角「添加插件」，输入框填 dsh-agnes-gen，点「安装」，再点「立即启用」。
输入框也接受 GitHub 仓库地址或本地源码目录绝对路径；本插件用包名即可。
命令行¶
按 profile 选择：
dsh plugin --profile web add dsh-agnes-gen
dsh plugin --profile desktop add dsh-agnes-gen
dsh plugin --profile dsh-tui add dsh-agnes-gen
装完后：Web 用 dsh web 启动，其余用 dsh --profile <profile>。
也可从 GitHub 源码安装：
dsh plugin --profile web add github:Ylhow06/dsh-agnes-gen
卸载示例：
dsh plugin --profile <profile> remove dsh-agnes-gen
申请 API Key 与配置¶
插件不会代你申请 Key。到 Agnes 平台创建 Key 后，在插件页选择站点并填写对应 Key：
| 站点 | site |
申请地址 |
|---|---|---|
| 中国站（默认） | cn |
https://platform.agnes-ai.cn/settings/apiKeys |
| 国际站 | intl |
https://platform.agnes-ai.com/settings/apiKeys |
两站 Key 不通用；site 与 Key 必须匹配，否则会报未找到对应站的 Key。
DSH 0.1.6.x 可在 settings.yaml 中写 agnes-gen: 分节，例如：
agnes-gen:
site: cn
apiKeyCn: sk-...
plan: free
rateLimit: true
outDir: ''
DSH 0.1.7.x 及更新（含 0.2.x） 配置落在当前 profile 的 cordis.patch.yml 插件条目 config: 下，字段名相同。常用项包括 site、apiKeyCn / apiKeyIntl、plan（free / enterprise / token-plan）、rateLimit、ffmpegPath、outDir、各站图像/视频模型与白名单等；完整说明见仓库 README「配置」一节。
典型用法¶
配置完成后，对话中 AI 可自动选用工具；也可在对话里显式写出调用，例如：
agnes_image(prompt="日出薄雾峡谷上方的发光浮空城市，电影级写实，广角，高视觉密度")
agnes_video(prompt="夜晚森林中三只猫组成微型铜管乐队向前行进", seconds=5, gif=true)
输出位置¶
- 图片默认：会话工作目录下
out/agnes-images（可用outDir改根目录）。 - 视频默认：
out/agnes-videos。 - 传
output_name时使用纯文件名（无时间戳）；不传则用「时间戳 + 提示词前 16 字符」命名。同一目录重复纯名会覆盖，多次生成建议给不同output_name。
agnes_video 的 gif=true 时在本地转 GIF，可通过 gif_width、gif_fps 等参数调整；keep_mp4 控制转 GIF 后是否保留 mp4。
适用场景与注意¶
适合：已在 DSH 中开发智能体、需要 Agnes 图像/视频生成且希望限流与 GIF 本地化处理一并就绪的团队或个人。
安装前建议：插件以当前 DSH 进程的权限运行，安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的安全与合规要求。API Key 为机密字段，勿提交到版本库。
若安装时出现 peer 不匹配或插件不在界面列表中，多半是当前 DSH 版本不在 README 适配表范围内，可向仓库 issues 反馈。
结尾¶
dsh-agnes-gen 把 Agnes 的 agnes_image、agnes_video 以 DSH 工具形式暴露，并处理分站密钥、RPM 限流、429 退避与 ffmpeg GIF 等工程细节。需要试用或查参数表时，可看 SkillHub 目录页 与 GitHub README。
