前言¶

在 DeepSeek Harness（dsh）里做智能体时，模型往往需要「生成一张图并拿到本地路径或可读摘要」，而不是只在对话里描述画面。若把 API Key、默认模型、输出目录、历史记录都塞进每次工具调用的参数里，调用面会变重，也不利于人在界面里改配置。

下面介绍社区插件 dsh-plugin-agnes-image（维护者 zhp282515-wq）：向模型注册 agnes_image 工具，并在 dsh 设置页嵌入 Agnes Image 控制台，把模型切换、密钥、预设与历史图库从工具参数里拆出去。上游图像 API 为 POST https://apihub.agnes-ai.com/v1/images/generations；README 写明撰写时各档位与参考图均为免费，实际计费以 Agnes 官方为准。

这是什么¶

dsh-plugin-agnes-image 属于 DSH 社区目录中的「模型推理」类插件（SkillHub 目录页）。一个包分成两半协同工作：

• Host 半：注册 agnes_image 工具，并在本机 loopback 上提供小型 HTTP API（设置、密钥、历史、生成）。
• Browser 半：在 Settings → Agnes Image（shell 为中文时显示 Agnes 生图）增加一节，嵌入 Host 提供的控制台页面。

运行时无额外 npm 依赖，仅 Node 内置模块与全局 fetch；要求 Node ≥ 22。当前 package 版本 1.1.0，许可证 MIT（见 GitHub 仓库）。

核心功能¶

模型与能力¶

agnes_image 工具¶

模型调用 agnes_image 后，会在磁盘上得到真实 PNG，并返回可继续处理的 JSON；摘要中含 Markdown 图片引用。

返回字段包括：ok、path、url、bytes、model、size、ratio、nativePixels、prompt、revisedPrompt、keySource。

设置页控制台¶

控制台支持 English / 中文（顶栏切换；默认 Auto 跟随 shell 与浏览器）。各区块作用如下：

配置在下一次生成时生效，无需重启 dsh。生效顺序（高到低）：操作者在 patch 行里的配置、控制台保存的设置、内置默认值。

安装与启用¶

该包不在 npm 发布。按 README，需克隆仓库后以 local link 挂入实际使用的 dsh profile，并在 dsh.profile.bundles 中注册 bundle 名称。

1、克隆仓库到任意路径

git clone https://github.com/zhp282515-wq/dsh-plugin-agnes-image.git /path/to/dsh-plugin-agnes-image

2、用 pnpm 链入 profile

link: 须使用绝对路径。示例 profile 为 desktop，请换成你实际使用的 profile：

cd ~/.dsh/profiles/desktop
pnpm add "link:/path/to/dsh-plugin-agnes-image"

Windows 跨盘符时 README 建议形如 link:D:/dsh-plugin/dsh-plugin-agnes-image。若不用 pnpm，可用目录 junction（PowerShell 示例见仓库 README）。

3、在 profile 的 package.json 注册 bundle

仅 pnpm add link: 不够；须把包名写入 dsh.profile.bundles，否则插件不会加载且 dsh 不会提示原因：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-plugin-agnes-image"
      ]
    }
  }
}

4、重启 dsh 一次

Host 半之后可热重载；Browser 半在启动时编入 boot graph。

卸载：从 bundles 移除条目、删除依赖与 link；Windows 删除 junction 用 cmd /c rmdir <link>，勿用 Remove-Item -Recurse（会删到源目录）。

API Key 配置¶

lib/agnes.js 按以下顺序解析密钥：

1. 插件配置中的显式 apiKey
2. 环境变量 AGNES_AI_API_KEY，其次 AGNES_API_KEY
3. 配置指定的密钥文件
4. 默认密钥文件（取第一个存在的）：~/.dsh/agnes_key.txt、~/.agnes/api_key.txt

密钥文件为纯文本，首尾空白会被 trim。启动时日志会输出 [agnes-image] API key source: …（仅来源，不打印密钥）。控制台可写入密钥（模式 0600），页面通过 GET /agnes-image/state 只得到掩码指纹（如 sk-Wsd********J8FR）与来源说明。也可设置环境变量 AGNES_AI_API_KEY 后重启 dsh，勿把密钥提交到仓库或截图。

典型用法¶

脚本调用 loopback HTTP API¶

控制台能做的事均可脚本化。README 示例（端口以你本机 dsh 为准，文档示例为 19387）：

curl -s http://127.0.0.1:19387/agnes-image/state

curl -s -X POST http://127.0.0.1:19387/agnes-image/generate \
  -H 'content-type: application/json' \
  -d '{"prompt":"a red paper lantern over still black water","size":"1K","ratio":"16:9"}'

常用路由包括：GET /agnes-image/state、POST /agnes-image/settings、POST /agnes-image/key、POST /agnes-image/test（mode:"auth" 或 mode:"generate"）、POST /agnes-image/generate、GET /agnes-image/history 等。插件自行校验 Host 为 loopback，并限制 GET /agnes-image/image 的路径范围，避免任意文件读取。

在对话中由模型调用工具¶

智能体在 dsh 中启用该 bundle 后，模型可按任务调用 agnes_image，传入 prompt 及可选的 size、ratio、model、images、out；返回的 path 与 Markdown 摘要可用于后续步骤（例如写入文档或再作图生图参考）。

适用场景与注意¶

适合谁：已在用 dsh、希望把 Agnes 文生图 / 图生图 / 多图合成接到 Agent 工具链，并希望在设置页统一管理模型、密钥与历史的开发者。

权限与安全：插件以当前 dsh 进程权限运行，可读写配置的输出目录与密钥文件；安装前请自行审阅 源码与 MIT 许可证，仅从可信来源安装。

生态说明：DSH 社区插件目录（如 SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系；本文事实均来自上述仓库 README 与 package 元数据。

链接¶

• 目录页：https://www.skillhub.cn/plugins/zhp282515-wq/dsh-plugin-agnes-image
• GitHub：https://github.com/zhp282515-wq/dsh-plugin-agnes-image