dsh-tool-generate-image

dsh plugin --profile web add dsh-tool-generate-image

dsh-tool-generate-image

[English](./README.en.md) | 中文

给 DeepSeek Harness（DSH） 的纯文本模型一个 generate_image 工具：用自然语言描述想要的图片，模型调用工具，经 Antigravity CLI（agy） 让 Google Gemini 画出来，保存到输出目录并返回文件路径。

生成的图片会直接内联显示在对话里，同时持久化保存到磁盘——重启后文件仍在，不像纯内存方案那样重启就 404。

说明

这是模型侧工具——由模型在任务中按需调用（"给第 3 节画个示意图，存好，我引用路径"），而不是聊天侧的自动生图 + 展示。

• 底层走本机 agy 的 generate_image 工具 + gemini-3.1-flash-image 图像模型（免费 Google 账号，无需 API key）。
• 生成结果从 ~/.gemini/antigravity-cli 递归收割（agy 落盘位置不固定：scratch/、brain/<会话>/、.tempmediaStorage/ 都有可能出现；也可能产出 SVG 矢量图），复制到可配置的输出目录后返回绝对路径。
• 对话内联显示：图片字节存进程内存，经宿主 web server 上一个回环-only 路由（默认 /generate-image）以 markdown 引用形式返回，模型把这一行复制进回复即渲染；内存上限 200 张 / 128MB，重启即清（磁盘副本不受影响）。
• 零运行时依赖：node 内置模块，不改 dsh 源码。

安装

dsh plugin --profile web add dsh-tool-generate-image

安装后重启 web 应用，模型即可调用 generate_image 工具。

使用

装好后不用记任何命令。正常对话，直接让模型画图即可，例如：

画一只戴着工程师帽、坐在工作台前写代码的柴犬，卡通风格，16:9

模型会调用 generate_image，把图存到输出目录（默认 ~/.dsh/generated-images），并把文件路径 + 内联显示引用返回给你——模型把这行 markdown 复制进回复，图就直接显示在对话里：

双保险：对话内联显示是内存态（重启后旧引用 404，无所谓），而图已真实保存到磁盘，重启后文件路径依然有效、可以继续引用。

配置

插件 apply(ctx, config) 读取（web profile 的 cordis.patch.yml / 设置层注入）：

键 · 默认 · 含义

model · gemini-3.7-flash-medium · 驱动生成的对话模型（实际图像由后台 gemini-3.1-flash-image 渲染）

outputDir · ~/.dsh/generated-images · 生成图保存目录

timeoutMs · 300000 · 单次生成超时

toolName · generate_image · 注册的工具名（与宿主其他工具撞名时可改）

agy · agy · agy 可执行文件

effort · — · 可选 low / medium / high，传给 agy --effort

inlinePath · /generate-image · 内联显示路由前缀（挂在宿主 web server 上，回环-only）

displayHost · 自动用 http://127.0.0.1:<webServer.port> · 内联 markdown 里用的图片基址；仅当需要改时设置

工具参数：prompt（必填，自然语言描述）、fileName（可选，输出文件名，默认时间戳）。

返回：ok、images（磁盘绝对路径，持久）、markdown（内联显示引用，内存态，可能为空）、message。

工作原理

模型："画一只柴犬"
  └─ generate_image 工具 execute()
       └─ spawn agy -p "<prompt>" --dangerously-skip-permissions \
                 --model <model> --print-timeout <Ns>
            └─ agy 调用 generate_image 工具 → gemini-3.1-flash-image 渲染
       └─ 对 ~/.gemini/antigravity-cli 递归 mtime 快照，找出新图
       └─ 复制到 outputDir（持久）
       └─ 字节存入内存 store → markdown ![图](http://127.0.0.1:<port>/generate-image/raw/<id>)
  └─ 返回 { ok, images: [绝对路径], markdown, message }
       └─ 模型把 markdown 行复制进回复 → DSH 前端渲染 → 图显示在对话里

--dangerously-skip-permissions 是必需的：agy 的 print 模式不带它时工具调用会被静默跳过，图永远画不出来。

⚠️ 安全说明：该参数意味着一个完整的 agent CLI（agy）在关闭权限确认的状态下运行。提示词经 spawn 参数数组传递、不经过 shell，因此没有注入面；但使用前请知悉——agy 会以其已登录账号的权限直接执行工具调用。

注意事项

• 前置：需要安装并登录 Antigravity CLI（curl -fsSL https://antigravity.google/cli/install.sh | bash，然后 agy 登录一次）。
• 配额波动：免费档图像服务偶发 503 MODEL_CAPACITY_EXHAUSTED / 429 RESOURCE_EXHAUSTED，属瞬时错误，稍后重试即可。
• 仅 Web profile 测试过。
• 重启生效：装/卸插件需重启 web 应用。

开发 / 测试

node test/harvest.mjs                                  # 收割逻辑单元测试
node test/inline.mjs                                   # 内联路由单元测试（含真实 http 往返）
node test/standalone.mjs "一只柴犬" /tmp/out            # 端到端（真实调 agy 生图）

许可证

[Apache-2.0](./LICENSE)