dsh-agnes-tools

Agnes AI image & video generation as native DeepSeek Harness tools.

agnes_image · agnes_edit_image · agnes_video · agnes_video_status · agnes_models

English · 中文

English

A small, tool-only plugin: it adds five tools to the agent and nothing else — no UI panel, no settings page, no runtime dependencies beyond the Schemastery peer DSH already ships.

Why this one

Five Agnes plugins already exist, so here is the honest difference:

• Video jobs are resumable. agnes_video submits, polls, and downloads — but when the in-call wait runs out it returns the video_id instead of losing the job. agnes_video_status picks it up later and downloads the mp4. On a queue that is regularly full (503 video_queue_full), that is the difference between a lost render and a finished one.
• agnes_models lists the models your key can actually reach, so you can tell a bad key from a bad model name in one call.
• Free-tier aware. Retries with backoff on 503/429, 6 s polling to stay under 20 RPM, and tolerance for the ~20 s window after submission where a status query wrongly reports 404.
• Tool-only, zero runtime deps. If you work in the chat and do not want a floating panel.

Install

From the DSH plugin market, once listed — then restart dsh web.

// $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

Configure

cordis.patch.yml holds the defaults; override any key in your profile's cordis.patch.yml or plugin settings.

The key is resolved in this order: apiKey → the DSH credential named by apiKeyRef → process.env[apiKeyRef].

Tools

Files land in outputDir as 20261018-015926-jvic-agnes-video.mp4. Generated images are also attached to the reply when the host supports attachments.

API quirks the code already handles

1. size is a tier, not a pixel size. Agnes takes 1K/2K/3K/4K plus ratio — not 1024x768.
2. Images must come back as base64. On the international endpoint the returned image URL lives on storage.googleapis.com, which is unreachable from mainland China. The plugin always asks for base64 instead.
3. The video queue is often full — 503 video_queue_full. Retried with backoff (up to 6 attempts, 8 s → 30 s).
4. A status query within ~20 s of submission reports 404 "task not found". The poll loop tolerates it.
5. The free tier allows 20 requests/minute; exceeding it returns 429. Hence the 6 s interval.
6. Video size is always "720P"; the real pixel size follows aspect_ratio (16:9 → 1280x704).

Development

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

Add node_modules to your profile and point dsh-agnes-tools at your checkout to iterate.

License

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。

// $DSH_HOME/profiles/web/package.json
{
  "dependencies": {
    "dsh-agnes-tools": "file:/你的路径/dsh-agnes-tools"   // 或 "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

配置

cordis.patch.yml 里写的是默认值，可在 profile 的 cordis.patch.yml 或插件设置里覆盖。

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

工具

产物落在 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）。

开发

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

许可证

MIT