dsh-agnes-media

dsh-agnes-media

English | 中文

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

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

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

安装

dsh plugin --profile <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

产物落在哪里

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

<工作区>/agnes-media/image-<UTC时间戳>.png
<工作区>/agnes-media/video-<UTC时间戳>.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