前言¶
DeepSeek Harness（DSH）的理念是「一切皆插件」。在智能体开发中，把外部 API 接成原生工具是常见需求。Agnes AI 提供了图像和视频生成能力，市面上已有 5 个 DSH 插件，但它们大多在长视频任务处理、免费额度适配、错误处理上存在不足。dsh-agnes-tools 是一个纯工具型插件，把 Agnes 的生图/生视频能力接成 DSH 原生工具，不依赖额外的 UI 面板或设置页。
插件定位与核心差异¶
这个插件只做一件事：把 Agnes AI 的图像与视频生成能力接成 DSH 的原生工具。维护者是 zuihouye，目前 Star 数为 0。
与已有的 Agnes 插件相比，这里只说真实差异：
-
长视频任务可以续查。
agnes_video在一次调用内提交任务、轮询状态并下载结果。如果等待超时，它会返回video_id而不是丢弃任务。之后用agnes_video_status接着查询，任务完成后自动下载 mp4。在视频队列经常满（503 video_queue_full）的情况下，这个差异决定了你是白等一场还是拿到成片。 -
agnes_models列出当前 Key 真正能访问的模型，一次调用就能区分「Key 不对」还是「模型名不对」。 -
为免费额度调过参。对
503/429错误进行退避重试，轮询间隔设为 6 秒以控制在 20 RPM 以内，并对提交后约 20 秒内状态查询误报 404 的情况进行容忍。 -
纯工具、零运行时依赖。如果你就在对话里干活，不需要悬浮面板，这个更干净。
安装与启用¶
插件上架到 DSH 插件市场后，可以直接安装，装完重启 dsh web。
如果需要手动安装（在 Windows 上已实测），在 web profile 里登记依赖和 bundle：
// $DSH_HOME/profiles/web/package.json
{
"dependencies": {
"dsh-agnes-tools": "file:/你的路径/dsh-agnes-tools" // 或 "github:zuihouye/dsh-agnes-tools"
},
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-agnes-tools"]
}
}
}
然后在 profile 目录下执行：
cd "$DSH_HOME/profiles/web" && pnpm install
重启 dsh web。host 侧插件在启动时装载，没有热加载。
两个坑：①
dsh plugin --profile web install可能回一句 “Already up to date” 却什么也没装，直接进 profile 目录跑pnpm install更可靠；② hoisted linker 下file:依赖是复制不是软链，改完源码要重跑pnpm install。
配置¶
配置保存在 cordis.patch.yml 里，默认值如下。可以在 profile 的 cordis.patch.yml 或插件设置里覆盖。
| 键 | 默认 | 说明 |
|---|---|---|
apiKeyRef |
AGNES_API_KEY |
DSH 凭据里的引用名，推荐 |
apiKey |
空 | 直接写 Key，优先级高于 apiKeyRef，不建议 |
baseURL |
https://api.agnes-ai.cn/v1 |
国内节点；国际站是 https://apihub.agnes-ai.com/v1 |
imageModel |
agnes-image-2.5-flash |
图像生成模型 |
videoModel |
agnes-video-2.5-flash |
视频生成模型 |
outputDir |
agnes-output |
绝对路径，或相对 dsh 进程的 cwd |
pollTimeoutMs |
300000 |
单次工具调用内最长等待 |
pollIntervalMs |
6000 |
别调小：免费 Key 只有 20 RPM |
Key 的解析顺序：apiKey → apiKeyRef 指向的 DSH 凭据 → process.env[apiKeyRef]。
工具¶
插件提供 5 个工具：
agnes_image：生图。必填prompt；可选ratio（1:1 / 4:3 / 3:4 / 16:9 / 9:16 / 3:2 / 2:3 / 21:9）、size（1K/2K/3K/4K）、save_path。agnes_edit_image：编辑图片。必填prompt、images；可选ratio、size、save_path。images支持本地绝对路径、公网 URL、data URI，可多张。agnes_video：生成视频。必填prompt；可选seconds（"4"–"12"，默认"5"）、aspect_ratio、mode（text/keyframe/reference）、first_frame、last_frame、images（≤5）、save_path。agnes_video_status：查询视频状态。必填video_id；可选save_path。agnes_models：列出当前 Key 可访问的模型。无参数。
产物落在 outputDir，文件名形如 20261018-015926-jvic-agnes-video.mp4；生成的图片在宿主支持时会一并作为附件回复。
代码里已经处理掉的 API 怪癖¶
size是档位不是像素。Agnes 收1K/2K/3K/4K+ratio，不是1024x768。- 图片必须按 base64 取回。国际站返回的图片 URL 在
storage.googleapis.com（国内不通），插件一律请求 base64，不依赖那个域名。 - 视频队列经常满（
503 video_queue_full）：内置退避重试，最多 6 次，8 秒 → 30 秒递增。 - 提交后约 20 秒内查询会误报 404「任务不存在」：轮询循环里已容忍。
- 免费 Key 20 RPM，超了报 429，所以轮询间隔设成 6 秒。
- 视频尺寸固定
"720P"，实际像素由aspect_ratio决定（16:9 → 1280x704）。
适用场景与注意¶
适合在 DSH 中需要直接调用 Agnes AI 进行图像与视频生成的场景，尤其是需要处理长视频任务、使用免费额度或对错误处理敏感的场景。
插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证（MIT）。
结尾¶
dsh-agnes-tools 把 Agnes AI 的生图与生视频能力接成 DSH 原生工具，提供长视频任务续查、可用模型查询、免费额度适配等能力。如果你在 DSH 中需要与 Agnes AI 交互，这个插件可以作为直接工具使用。
- 目录页：https://www.skillhub.cn/plugins/zuihouye/dsh-agnes-tools
- GitHub：https://github.com/zuihouye/dsh-agnes-tools
