dsh-generate-image

Readme

<p align="center">
  <h1 align="center">dsh-generate-image</h1>
</p>

<p align="center"><b>DeepSeek Harness 插件：通过本机 OpenAI Codex CLI 生成与编辑图片。</b></p>

<p align="center">
  <a href="https://github.com/zemul/dsh-generate-image"><img src="https://img.shields.io/github/stars/zemul/dsh-generate-image?style=flat-square" alt="GitHub stars"></a>
  <a href="https://github.com/zemul/dsh-generate-image/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js >= 18">
  <img src="https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square" alt="Zero dependencies">
  <img src="https://img.shields.io/badge/build-none-brightgreen?style=flat-square" alt="No build step">
</p>

向 Harness 的模型暴露一个 `generate_image` 工具，提供两种模式：

- **文生图**：`generate_image(prompt)` — 根据文字描述生成全新图片。
- **图生图（编辑）**：`generate_image(prompt, inputImage)` — 传入已有图片路径，按描述编辑（换背景、改颜色、去物体、重绘局部等），未指定部分保持不变。

纯 JS 实现、**零 npm 依赖、零构建步骤**——从 GitHub 安装后即可直接运行，不需要 `prepare` 构建脚本或 pnpm 构建授权。

与 [modlens](https://github.com/liustack/modlens) 的 `modlens_read_image` 是对偶设计：modlens 让纯文本模型「看」图，本插件让模型「画」图，两者底层都复用你本机的 Codex CLI。

## 特性

- 🖼️ **文生图 + 图生图**双模式，一次调用完成生成或编辑
- 🔑 **无需 API key**：走 Codex 内置 `image_gen` 工具，复用本机 Codex 登录（ChatGPT 账号额度）
- 📦 **零依赖零构建**：只用 Node 内置模块，git 安装即用
- 🔍 **可靠的结果获取**：通过目录快照 diff 定位新生成的图片，不依赖解析模型输出文本
- ⏱️ **超时与信号保护**：遵循工具调用的 abort 信号，超时强制终止

## 工作原理

```
模型调用 generate_image(prompt [, inputImage])
      │
      ▼  spawn codex exec --json [ -i <inputImage> ]
本地 Codex CLI（需已登录）
      │  模型读取预装的 imagegen skill → 调用内置 image_gen 工具
      ▼
图片落盘 $CODEX_HOME/generated_images/<session>/exec-<uuid>.png
      │
      ▼  插件对比快照找到新文件 → 拷回输出目录
返回 { path, source, edit, note }
```

## 安装

### 从 GitHub 安装

一条命令（无需本机安装 dsh CLI，npx 会自动拉官方 `dsh`）：

```sh
npx -y @deepseek-ai/dsh plugin --profile web add github:zemul/dsh-generate-image
```

- `--profile web` 是 Web GUI 使用的组合（`dsh web` 即 `--profile web`）；其他组合把 `web` 换成对应名字即可。
- 本机已装 `dsh` 命令时可直接 `dsh plugin --profile web add github:zemul/dsh-generate-image`。
- 刚发布 24 小时内 `@latest` 可能被 pnpm 扣住解析不到，建议点名版本：`dsh-generate-image@0.1.0`。

本包没有任何生命周期脚本，pnpm 不会要求构建授权；若仍提示，在该 profile 的 `pnpm-workspace.yaml` 中加入：

```yaml
allowBuilds:
  dsh-generate-image: true
```

重启 GUI 后生效。

### 本地开发（overlay）

```yaml
# cordis.patch.yml
- insert:
    - id: generate-image
      name: '/绝对路径/dsh-generate-image/index.js'
```

## 快速开始

模型在对话中直接调用即可：

```
生成一张赛博朋克风格的城市夜景图，霓虹灯紫蓝配色
```

```
把 ./assets/hero.png 的背景换成渐变星空，保留前景主体
```

工具返回生成图片的绝对路径，模型与用户可直接引用。

## 配置

通过插件行的 `config` 提供：

```yaml
- insert:
    - id: generate-image
      name: 'dsh-generate-image'
      config:
        codexBin: /opt/homebrew/bin/codex    # 默认自动探测 PATH
        model: gpt-5.6-sol                   # 可选，覆盖 codex 默认模型
        defaultOutputDir: /path/to/workspace # 默认 process.cwd()
        timeoutMs: 300000                    # 默认 300s
        sandbox: workspace-write             # codex exec 沙箱级别
        toolName: generate_image             # 工具名，默认 generate_image
```

## 测试

不依赖 GUI，直接验证引擎链路（会消耗少量 Codex 额度）：

```sh
# 文生图
node test/verify.mjs 'Generate ONE tiny simple test image: a small blue square on a yellow background'

# 图生图（第二个参数为输入图路径）
node test/verify.mjs 'Change the blue square into a green circle, keep the background' \
  ./test/test-output/input.png
```

插件形态验证（不消耗额度）：

```sh
node test/load.mjs
```

## 常见问题

**Q：需要 API key 吗？**
不需要。走 Codex 内置 `image_gen` 工具（官方默认路径），复用本机 `~/.codex/auth.json` 登录。

**Q：生成后图片存在哪？**
Codex 默认存 `$CODEX_HOME/generated_images/`（默认 `~/.codex`）；插件拷一份到输出目录（默认工作目录）并返回该路径。

**Q：额度怎么算？**
每次生图消耗你的 Codex/ChatGPT 账号额度（OAuth），生图比文本贵。

**Q：登录失效怎么办？**
工具会报错提示；在终端重跑一次 `codex` 重新登录即可。

**Q：为什么不需要构建？**
插件只用 Node 内置模块（`node:child_process`、`node:fs` 等）和原生 JSON-Schema 工具定义，源码即产物。

## License

[MIT](./LICENSE)