dsh-agnes-media：Agnes AI 图像与视频生成插件

前言¶

DeepSeek Harness (DSH) 的 LLM 端点主要处理文本对话。然而，像 Agnes 这样的图像和视频生成服务返回的是媒体文件，而非聊天消息。dsh-agnes-media 插件通过提供 agnes_image 和 agnes_video 工具，填补了这一空白，将媒体生成能力集成到 DSH 的工具生态中。

插件简介¶

dsh-agnes-media 是一个面向 Agnes AI 图像和视频生成工具的插件，包含两个核心工具：agnes_image 和 agnes_video。该插件由 zlforward 维护。

核心功能¶

agnes_image：支持文本到图像、图像到图像、多图像组合。
agnes_video：支持文本到视频、关键帧、多模态参考（异步任务）。

安装与启用¶

使用官方命令安装插件：

dsh plugin --profile <profile> add dsh-agnes-media

或在 profile 的 package.json 中声明 bundle：

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

安装后需要重启 DSH 进程。

典型用法¶

在 credentials.yaml 中设置 API 密钥：

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

在 profile 的补丁层中覆盖配置：

- 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

输出路径：默认情况下，生成的文件保存在调用智能体会话的工作空间中：

<workspace>/agnes-media/image-<UTC timestamp>.png
<workspace>/agnes-media/video-<UTC timestamp>.mp4

适用场景与注意事项¶

该插件适合需要在智能体工作流中直接调用图像和视频生成能力的场景。

密钥管理：插件不存储秘密，通过环境变量 AGNES_API_KEY 解析凭证。未配置的引用会导致报错，而非静默失败。
结果权威性：Agnes 返回的托管 URL 可能会过期，插件会下载字节流并保存为本地文件，本地文件是权威来源。
视频任务特性：agnes_video 是长时间运行的任务（最长约 30 分钟），涉及轮询和异步处理，默认超时时间较长。
输入限制：视频媒体必须是公共 URL，无法直接访问本地文件系统；图片支持数据 URI，无需上传步骤。
错误处理：插件内置了对 429（速率限制）和 503（服务不可用）的重试机制，并会处理 video_queue_full 错误。
API 差异：视频结果 URL 结构位于顶层（url）而非文档中的 metadata.url；任务状态拼写（如 pending）与文档不一致，插件已做适配。
模型配置：模型名称（如 agnes-image-2.5-flash）需在配置中指定，无法从端点自动发现。

结语¶

dsh-agnes-media 解决了 DSH LLM 路由无法处理非对话类生成请求的问题。通过提供标准的工具接口和本地化文件处理能力，它为构建多模态智能体提供了可靠的底层支持。