Agnes 生成工具 zuihouye/dsh-agnes-tools

dsh-agnes-tools

把 Agnes AI 的图像与视频生成做成原生 DeepSeek Harness 工具。

agnes_image · agnes_edit_image · agnes_video · agnes_video_status · agnes_models

English · 中文

一个只做工具的小插件：它给智能体加五个工具，别的什么都不加——没有 UI 面板，没有设置页，除 DSH 自带的 Schemastery 之外没有运行时依赖。

为什么选这个

市面上已经有五个 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 配置档，并注册为 bundle：

// $DSH_HOME/profiles/web/package.json
{
"dependencies": {
"dsh-agnes-tools": "file:/path/to/dsh-agnes-tools" // or: "github:zuihouye/dsh-agnes-tools"
},
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-agnes-tools"]
}
}
}

cd "$DSH_HOME/profiles/web" && pnpm install

然后重启 dsh web。宿主侧插件在启动时加载——没有热重载。

两个坑值得知道：dsh plugin --profile web install 可能回一句 "Already up to date"，其实什么都没装，所以你自己在配置档里跑 pnpm install。另外 hoisted 链接器会复制 file: 依赖，改完源码要重新跑 pnpm install。

配置

cordis.patch.yml 里放着默认值；在配置档的 cordis.patch.yml 或插件设置里覆盖任意键。

| 键 | 默认值 | 说明 |
| apiKeyRef | AGNES_API_KEY | 存放你 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 进程工作目录。 |
| pollTimeoutMs | 300000 | agnes_video 在单次工具调用内等待多久。 |
| pollIntervalMs | 6000 | 不要调低：免费额度只允许 20 请求/分钟。 |

Key 按以下顺序解析：apiKey → apiKeyRef 指定的 DSH 凭据 →
process.env[apiKeyRef]。

工具

| 工具 | 必填 | 可选 |
| 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 | — | — |

文件落在 outputDir，形如 20261018-015926-jvic-agnes-video.mp4。
宿主支持附件时，生成的图片也会一并附在回复里。

代码已处理的 API 怪癖

1. size 是档位，不是像素尺寸。 Agnes 接受 1K/2K/3K/4K 加 ratio —— 不是 1024x768。
2. 图片必须以 base64 返回。 国际端点返回的图片 URL 落在 storage.googleapis.com 上，中国大陆访问不到。插件一律改为索取 base64。
3. 视频队列经常满 —— 503 video_queue_full。按退避重试（最多 6 次，8 s → 30 s）。
4. 提交后约 20 s 内查状态会报 404「task not found」。 轮询循环容忍这种情况。
5. 免费额度只允许 20 请求/分钟；超出返回 429。所以轮询间隔是 6 s。
6. 视频尺寸固定为 "720P"；真实像素尺寸随 aspect_ratio 变化（16:9 → 1280x704）。

开发

npm install && npm test # loads the plugin with a mock context and checks every tool

把 node_modules 加进你的配置档，再让 dsh-agnes-tools 指向你的检出目录，就能边改边调。

许可证

MIT

把 Agnes AI 的生图 / 生视频接成 DeepSeek Harness 的原生工具，一共 5 个，纯工具型：没有悬浮面板、没有设置页，除 DSH 自带的 Schemastery 外没有运行时依赖。

和已有的 Agnes 插件有什么不一样

Agnes 生图生视频的插件市面上已经有 5 个，所以这里只说真实差异：

- 长视频任务可以续查。 agnes_video 会一次调用内提交 + 轮询 + 下载；但等待超时后它返回 video_id 而不是把任务丢掉，之后用 agnes_video_status 接着查、完成后自动下载 mp4。
视频队列经常满（503 video_queue_full），这条差异决定了你是白等一场还是拿到成片。
- agnes_models 列出当前 Key 真能访问的模型，一次调用区分「Key 不对」还是「模型名不对」。
- 为免费额度调过参。 503/429 退避重试、6 秒轮询卡在 20 RPM 以内、容忍提交后约 20 秒内状态查询误报 404。
- 纯工具、零运行时依赖。 如果你就在对话里干活、不需要悬浮面板，这个更干净。

安装

插件市场上架后可直接安装，装完重启 dsh web。

手动安装（Windows 上已实测）

在 web 配置档里登记依赖和 bundle：

// $DSH_HOME/profiles/web/package.json
{
"dependencies": {
"dsh-agnes-tools": "file:/你的路径/dsh-agnes-tools" // 或 "github:zuihouye/dsh-agnes-tools" },
"dsh": {
"profile": {json
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-agnes-tools"]
}
}
}
bash
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]。

工具

| 工具 | 必填 | 选填 |
| 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 | — | — |

产物落在 outputDir，文件名形如 20261018-015926-jvic-agnes-video.mp4；生成的图片在宿主支持时会一并作为附件回复。

代码里已经处理掉的 API 怪癖

1. size 是档位不是像素：Agnes 收 1K/2K/3K/4K + ratio，不是 1024x768。
2. 图片必须按 base64 取回：国际站返回的图片 URL 在 storage.googleapis.com（国内不通），插件一律请求 base64，不依赖那个域名。
3. 视频队列经常满（503 video_queue_full）：内置退避重试，最多 6 次，8 秒 → 30 秒递增。
4. 提交后约 20 秒内查询会误报 404「任务不存在」：轮询循环里已容忍。
5. 免费 Key 20 RPM，超了报 429，所以轮询间隔设成 6 秒。
6. 视频尺寸固定 "720P"，实际像素由 aspect_ratio 决定（16:9 → 1280x704）。

开发 bash
npm install && npm test # 用 mock context 加载插件，逐个校验注册出来的工具

许可证

MIT