前言¶
在 DeepSeek Harness（DSH）里做智能体时，常见需求是让模型根据文字出图、出视频，或把本地/网络图片转成文字描述再参与对话。若自行对接 HTTP API、处理二进制回传与会话上下文，工具层和网关细节会占不少时间。社区插件 @lingxinsuixing/dsh-agnes 把 Agnes AI 的图像生成、视频生成和可选的图像识别封装成 DSH 工具：工具返回值始终是文本（路径、URL、摘要），生成文件落在本地目录，不把图片或视频字节塞进对话。
这是什么¶
@lingxinsuixing/dsh-agnes 由维护者 lingxinsuixing 发布，在 SkillHub 等社区目录中归类为「模型推理」。它面向已安装 DSH、并持有 Agnes API Key 的开发者，在 Harness 内注册可调用的生成与识别工具，与 DSH「一切皆插件」的扩展方式一致。社区目录站点与 DeepSeek / 幻方无官方从属关系，安装前仍应自行查看仓库源码与 MIT 许可证；插件以当前 dsh 进程权限运行。
核心功能¶
插件提供三个工具（识别可关闭），均只返回文本：
| 工具 | 作用 | 主要参数 |
|---|---|---|
agnes_image_generate（主能力） |
按文本提示生成或编辑图像 | prompt、size、ratio、references、saveTo |
agnes_video_generate（主能力） |
按文本提示生成视频 | prompt、mode、seconds、size、aspectRatio、images、saveTo |
agnes_image_recognize（可选） |
描述图像或按问题回答 | image（本地路径或 http(s) URL）、prompt |
默认模型方面：识别使用 agnes-3.0-flash；图像生成为 agnes-image-2.5-flash（文档称整条图像模型线目前免费）；视频默认为 agnes-video-2.5，若要用免费档可改为 agnes-video-2.5-flash（仅 720P，且不能带参考视频）。可在插件页「Models」中修改。模型列表与价格见 Agnes 文档概览。
关于 size：API 会把如 1920x1080 的请求映射到最近档位，结果里的 size 是磁盘上文件的实际像素尺寸，不一定与请求完全一致。
生成媒体默认写入 DSH 主目录下的 media/（$DSH_HOME/media，未设置 $DSH_HOME 时为 ~/.dsh/media），可在插件页「Output folder and read scope」调整 outputDir。每次调用返回所写文件的绝对路径。saveTo 必须指向已存在的目录，插件不会随意创建目录，文件名由插件生成，不会覆盖你已有文件。
安装与配置¶
下面介绍安装与密钥配置，顺序与 README 一致。
安装¶
包无构建步骤，安装后无需额外审批：
dsh plugin add github:lingxinsuixing/dsh-agnes
配置 API Key¶
在 Web UI 打开 Plugins → @lingxinsuixing/dsh-agnes 粘贴 Agnes API Key，或使用 DSH 凭据存储：
# ~/.dsh/credentials.yaml（或 Web UI 中的凭据存储）
AGNES_API_KEY: your-key
查找顺序为：插件配置 config.apiKey → 凭据项 AGNES_API_KEY → 环境变量 AGNES_API_KEY。设置在页面输入的 Key 会以明文写入你的个人配置中的 config.apiKey，不会写入插件包；包本身不带任何凭据。
可选：关闭图像识别¶
若不需要识别，在插件配置中设置 enableRecognition: false，则不会注册 agnes_image_recognize，仅保留图像与视频生成。工具在插件加载时注册，修改后需重启 DSH 一次生效。
识别还可通过 allowedReadRoots 限制可读本地图像的根目录列表（绝对路径）；为空表示不限制可读图像文件。
典型用法与集成注意¶
智能体在对话中调用上述工具即可：例如用 agnes_image_generate 传入 prompt 与可选的 size、ratio、references，从返回文本中取本地路径与 URL；视频同理使用 agnes_video_generate。需要理解图片内容时，应使用 agnes_image_recognize，而不是依赖 DSH 内置的 read_image。
README 明确说明：一旦模型被标记为支持图像，内置 read_image 会把图像内容块放进会话；Agnes 网关的 /v1/responses 不理解 input_image，下一次请求可能返回 400 且不会重试，整段会话历史重建后仍失败，需新开对话。因此在与 Agnes 通过 openai-responses 对接时，不要用 read_image 处理主对话里的图片，改用 agnes_image_recognize，由 Agnes 视觉模型处理图像，仅文本回到对话。
若 provider 使用 api: openai-completions 对接 Agnes，还应在模型条目中声明 reasoningEfforts，否则 DSH 不会发送 reasoning_effort，网关无 reasoning_content 时，模型可能把推理过程写进消息正文。
环境要求：@deepseek-ai/schemastery >=3.18.1（package.json 中对 peer 版本有更细区间）、有效的 Agnes API Key；视频按 Agnes 计费（-flash 档目前限制 720P）。
适用场景¶
适合已在 DSH 中编排工具、希望统一用 Agnes 做文生图、文生视频，或可选地做图像问答的开发者。不适合期望工具直接在对话里嵌入二进制媒体的场景——本插件设计就是文本结果 + 本地文件。
安装前请阅读 GitHub 仓库 源码与 MIT 许可证，确认权限与输出目录策略符合你的环境。
结尾¶
@lingxinsuixing/dsh-agnes 把 Agnes 的图像、视频生成和可选识别收成 DSH 原生工具，会话保持纯文本，产物落在可配置的本地目录。目录页：https://www.skillhub.cn/plugins/lingxinsuixing/dsh-agnes；源码与说明：https://github.com/lingxinsuixing/dsh-agnes。
