# dsh-agnes-media

[English](README.md) | 中文

为 DeepSeek Harness 接入 [Agnes AI](https://platform.agnes-ai.com/) 的图像与视频生成，提供两个模型可调用的工具：

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

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

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

## 安装

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

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

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

安装后重启 Harness。

## 凭据

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

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

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

## 配置

在 profile 的 patch 层里按 id 覆盖：

```yaml
- 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-<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