zlforward/dsh-agnes-media

dsh-agnes-media

为 DeepSeek Harness 接入 Agnes AI 的图像与视频生成，提供两个模型可调用的工具：

| 工具 | 端点 | 说明 |
|---|---|---|
| agnes_image | POST /v1/images/generations | 文生图、图生图、多图合成 |
| agnes_video | POST /v1/videos + GET /agnesapi | 异步视频任务：文生视频、首尾帧、多模态参考 |

为什么是一个插件而不是一条 LLM 路由

Harness 的 LLM 接缝只说 chat 协议（completions / responses / messages）。Agnes 的文本模型可以照常做成 llm-pi-ai 路由，但图像和视频是生成端点——它们不返回对话，所以做成工具而不是模型。两者可以并存：文本走路由，图像/视频走本插件。

安装

dsh plugin --profile  add dsh-agnes-media

或以 bundle 形式声明在 profile 的 package.json：

{
"dsh": { "profile": { "bundles": ["dsh-agnes-media"] } }
}

安装后重启 Harness。

凭据

插件不保存密钥。它在每次调用时通过 harness 凭据接缝解析 apiKeyEnv（默认 AGNES_API_KEY）：

$DSH_HOME/.credentials.yaml
refs:
AGNES_API_KEY: sk-...

未配置时调用会以点名该引用的错误失败，而不是发出一个注定 401 的请求。

配置

在 profile 的 patch 层里按 id 覆盖：

- id: agnes-media
config:
baseURL: https://apihub.agnes-ai.com/v1
apiKeyEnv: AGNES_API_KEY
imageModel: agnes-image-2.5-flash
videoModel: agnes-video-2.5-flash
outputDir: agnes-media
requestTimeoutMs: 300000
imageTimeoutMs: 360000
videoTimeoutMs: 1800000
videoPollIntervalMs: 3000

| 字段 | 默认值 | 含义 |
|---|---|---|
| baseURL | https://apihub.agnes-ai.com/v1 | 国际站。中国站为 https://api.agnes-ai.cn/v1，国际备用为 https://apihub.agnes-ai.cn/v1 |
| apiKeyEnv | AGNES_API_KEY | 每次调用解析的凭据引用 |
| imageModel | agnes-image-2.5-flash | 调用未点名模型时使用 |
| videoModel | agnes-video-2.5-flash | 默认选免费档，未配置的调用不会静默花钱 |
| outputDir | agnes-media | 相对调用方工作区；绝对 outputPath 可绕过 |

产物落在哪里

默认写入发起调用的 agent 会话工作区下的 outputDir：

/agnes-media/image-.png
/agnes-media/video-.mp4

扩展名按下载回来的字节头嗅探决定，不是写死的。调用时传 outputPath 可覆盖（相对路径按工作区解析，绝对路径原样使用）。

Agnes 还会返回一份自己托管的 URL（结果里的 sourceUrl），那份可能过期——所以插件把字节下载到本地，本地文件才是准的。

免费额度

按 Agnes 定价页：三个图像模型的所有分辨率档当前免费；agnes-video-v2.0 与 agnes-video-2.5-flash 当前 $0/秒；agnes-video-2.5 按秒计费。免费档有账号级限流。

实现细节：与文档不一致的地方

这些是实测得出的，都影响正确性，所以写在这里而不是埋在代码里注释中：

- 视频结果 URL 在响应顶层 url，文档写的 metadata.url 在实测响应里根本不存在。插件优先读顶层、保留文档形态作为回退。
- 任务状态会出现文档没列的拼写：实测返回 pending，文档写 queued。因此按终态判断（completed / failed），不枚举在途状态。
- 轮询会撞 429，即使按文档建议的 1–2 秒间隔。插件退避重试，不把限流当成生成失败。
- 创建会撞 503 video_queue_full。同样退避重试。通用 500 故意不重试——无法与"任务已创建后才失败"区分，重试会导致重复计费。
- 产物 URL 不接受 Bearer 头，带上会得到 401。下载时不带鉴权。
- 图像接受 data URI，所以本地图片可以直接内联，不需要先上传。
- 视频媒体必须是公网 URL——Agnes 服务端自行抓取，够不到本机文件。

限制

- 图像的 input 模态依赖 Agnes 对 data URI 的支持（已实测），不是所有兼容网关都如此。
- 视频工具是长任务：默认最多轮询 30 分钟，工具声明了对应的 timeoutMs，并全程观测 exec.signal 以支持协作式取消。
- 未接入 Agnes 的图像/视频模型目录发现——模型名是配置，不是从端点查询得来。

许可

MIT