前言¶
DeepSeek Harness（DSH）出厂时能读写文件、跑命令，但不自带画图能力。要在对话里「说一句话出一张图」，要么自己接第三方图像 API 并写工具封装，要么装社区插件。下面介绍维护者 Naskete 发布的 dsh-agnes-image：通过 Agnes AI（默认模型 agnes-image-2.5-flash）完成文生图、图生图和多图合成，零依赖、纯 JavaScript、无需构建。插件在 SkillHub 分类为「模型推理」；仓库为 MIT 许可的非官方社区插件，与 DeepSeek、Agnes AI 均无隶属关系。
这是什么¶
dsh-agnes-image 给 DSH 增加工具 agnes_generate_image。模型理解你的自然语言后调用该工具，插件把描述（及可选参考图）发给 Agnes，拿回图片后写入当前工作目录并在对话中展示。
典型流程：
你说话 → DSH 模型 → 调用 agnes_generate_image → Agnes 云端生图 → 本地保存 + 对话显示
能做：文生图、图生图（改风格/换背景等）、多图合成。
不做：视频、图库管理、批量队列、在线编辑器。
生成文件默认落在工作目录下的 generated-images/<日期>/，按日期分文件夹，文件名带时间戳，连续多次生成不会互相覆盖。
核心功能¶
三种用法¶
| 玩法 | 你需要提供 | 插件行为 |
|---|---|---|
| 文生图 | 文字描述 | 主要带 prompt 及尺寸、比例等 |
| 图生图 | 描述 + 一张参考图（本地路径、公网 URL 或 data:image/...） |
参考图放入 image |
| 多图合成 | 描述 + 多张参考图 | 多张按顺序放入 image |
本地参考图会被读取并转为 base64 再请求接口。支持 PNG / JPEG / WebP / GIF，单张最大 12 MB。
可调参数（可口语交给模型）¶
| 参数 | 说明 | 默认 |
|---|---|---|
prompt |
画面描述，必填 | — |
size |
1K / 2K / 3K / 4K，或如 1024x768 |
1K |
ratio |
1:1、3:4、4:3、16:9、9:16、2:3、3:2、21:9 |
1:1 |
model |
agnes-image-2.5-flash / 2.1-flash / 2.0-flash |
2.5 |
image |
参考图 | 无 |
outputName |
输出文件名（不含扩展名） | 由提示词自动生成 |
配置项 outputDir 可改输出目录（默认上述 generated-images 结构）。
实现特点¶
- 纯 JavaScript，无额外 npm 依赖，无构建步骤。
package.json要求 Node>=22.19.0（命令行版 Harness 需满足运行环境要求）。- 密钥通过 HTTP 头
Authorization: Bearer ...发往配置的baseUrl（默认 Agnes 官方地址）；插件声明不会把 Key 写入日志或对话回显。
安装与启用¶
准备¶
- 可用的 DSH（桌面版或命令行版；两个版本插件需各自安装一次）。
- Agnes AI 账号：在 agnes-ai.com 注册，于开发者控制台 API Key 管理 创建并复制
sk-开头的 Key 值（不是 Key 的名称）。
安装插件¶
--profile 与 Harness 版本对应：桌面版多为 desktop，命令行版多为 web。不确定时可执行 dsh plugin --profile web list 查看。
从 GitHub 安装（README 推荐方式之一）：
dsh plugin --profile web add github:Naskete/dsh-agnes-image
也可从本地目录或 Release 的 .tgz 安装：
dsh plugin --profile web add D:\path\to\dsh-agnes-image
dsh plugin --profile web add D:\path\to\dsh-agnes-image-0.1.0.tgz
图形界面：Harness 左侧 插件 → + 添加插件，可填 npm 包名 dsh-agnes-image 或本地绝对路径；github:... 形式在界面可能无法通过预检，宜改用命令行。
卸载：
dsh plugin --profile web remove dsh-agnes-image
配置 API Key（三选一）¶
方式 ① 密钥文件（推荐，改 Key 无需重启 Harness）
Windows：C:\Users\<用户名>\.dsh\agnes-image.config.json
macOS / Linux：~/.dsh/agnes-image.config.json
{ "apiKey": "sk-你的Key" }
方式 ② 环境变量（需重启 Harness 后生效）
setx AGNES_API_KEY "sk-你的Key"
export AGNES_API_KEY="sk-你的Key"
方式 ③ profile 配置（编辑 ~/.dsh/profiles/<profile>/cordis.patch.yml）
- id: agnes-image
name: dsh-agnes-image
config:
apiKey: sk-你的Key
除方式 ① 外，修改配置后建议完全退出 Harness 再打开（桌面版需从托盘退出，而非仅关窗口）。
验证¶
对 Harness 说例如：
画一张：一只戴耳机的小熊猫在画画，扁平插画风格
成功时应调用 agnes_generate_image、对话内显示图片，且工作目录出现 generated-images/<当天日期>/xxx.png。若报 Agnes API key is missing 检查密钥文件；401/403 多为 Key 填错；若无该工具则确认安装并完全重启。
典型用法¶
无需背诵命令，用自然语言即可，例如：
- 「画一张海边日落的壁纸，16:9」
- 「给 README 配个头图，扁平风」
- 「把
D:\shots\room.png改成雨夜赛博朋克，保留构图」 - 「用这两张图合成一张海报，第一张是主角，第二张是产品」
需要精确控制时，可直接说明比例与清晰度，例如「竖版 9:16、2K」对应 ratio 与 size。
图生图提示词可参考 README 结构：改动要求 + 新风格/场景 + 要加/要去的元素 + 必须保留的元素。
一次工具调用返回一张图；要多张可多次说明或让模型连续调用。
适用场景与注意¶
适合：在 DSH 工作流里快速出配图、改风格、多素材合成；依赖 Agnes 图像模型（README 称目前免费，以 Agnes 官方定价为准）。
权限与安全：插件以当前 DSH 进程权限运行，仅发 HTTP 请求并在工作区写图片；只有你（或模型）在 image 中明确给出路径时才会读取该本地文件，并对非图片路径、超大文件、data: 非图片类型做拒绝。提示词与参考图会经 Agnes 服务器处理。安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证；勿把含 Key 的会话目录提交到 git。
必须联网；不支持视频与批量队列管理。
结尾¶
dsh-agnes-image 把 Agnes AI 的生图能力接到 DSH 工具链上，用一句话完成文生图、图生图与多图合成，结果自动落盘并在对话展示。社区目录页：SkillHub - Naskete/dsh-agnes-image；源码与完整安装说明：github.com/Naskete/dsh-agnes-image。
