CarlMarkswx / dsh-imagen

DeepSeek Imagen —— DeepSeek Harness 图像生成插件

Beta 版本 · 为 DeepSeek Harness 提供对话内图像生成能力：AI 自主调用、确定性派发、对话内缩略图预览、可点击存档路径、可视化提供商管理。

---

✨ 功能特性

• 🤖 Agent 自主调用 —— 用户说"画一张…"，模型自动调用 generate_image 工具
• 🎯 确定性派发 —— 工具只接收 prompt/尺寸/数量参数，直接派发到你在设置页启用的提供商，模型不参与（也不会猜错）provider/model
• 🖼️ 对话内预览 —— 生成的图片以缩略图内联显示在工具行中，点击可放大
• 📂 可点击存档 —— 每张图同时保存为本地 PNG，路径按钮点击即用系统默认程序打开
• 🛡️ 上游故障友好 —— 图像服务 5xx/超时等上游故障会明确转告用户，而不是盲目重试
• 🧩 完全插件化 —— 不修改 DeepSeek Harness 任何源文件，安装器 + Cordis patch 注入
• 🌍 中英文双语 设置界面

📋 环境要求

依赖	版本
DeepSeek Harness	源码检出（可 pnpm install 的工作区）
操作系统	Windows / macOS / Linux
Node.js	≥ 22.19
pnpm	≥ 11

🚀 安装

git clone https://github.com/CarlMarkswx/dsh-imagen.git
cd dsh-imagen

# 自动检测 DeepSeek Harness 路径（支持 Windows / macOS / Linux）；也可手动指定：
node install-to-harness.cjs "D:\Tools\DeepSeek Harness"    # Windows
node install-to-harness.cjs ~/code/deepseek-harness        # macOS / Linux

# 或通过环境变量声明（优先级最高）：
# Windows: set DEEPSEEK_HARNESS_PATH=D:\Tools\DeepSeek Harness
# macOS / Linux: export DEEPSEEK_HARNESS_PATH=~/code/deepseek-harness

安装器会自动完成（全程输出日志）：

1. 复制 4 个插件包到 <harness>/packages/imagen/
2. 在 <harness>/pnpm-workspace.yaml 登记 packages/imagen/*
3. 写入 Cordis patch：
   • <harness>/imagen.patch.yml（可用 dsh --profile web --patch imagen.patch.yml 显式加载）
   • ~/.dsh/cordis.patch.yml（用户层 patch，自动加载；已存在时做幂等迁移，不覆盖你的其他条目）
4. 在 ~/.dsh/profiles/node_modules/@deepseek-imagen/ 创建包解析 junction
5. 生成 .env.imagen.example（提供方凭据均在设置页配置，无需内置厂商 Key）
6. 在 Harness 工作区内构建全部插件包

然后启动 DeepSeek Harness（你平时的启动方式即可，例如 pnpm dsh web 或一键 bat）。

⚙️ 配置图像服务

打开浏览器 → 设置 → 图像生成：

1. 添加提供方：填写 Provider ID、API URL、API Key（或留空走环境变量），支持任意 OpenAI 兼容的 /images/generations 接口
2. 获取可用模型：一键探测端点的模型目录并勾选
3. 固定尺寸：若模型只支持单一尺寸（如 2048×2048），在提供方上声明，请求会自动吸附
4. 启用后即时生效（无需重启）

OpenAI 在这里只是一种兼容协议：任何兼容 /images/generations（及可选 /images/edits）的网关都可以作为提供方接入，模型与凭据完全由你在设置页配置。

💬 使用

在任意会话中直接说：

帮我生成一张日落海滩的照片，胶片质感

模型会调用 generate_image，对话中出现专属工具行：

• 生成中：显示 prompt 摘要与进度动画
• 成功后：图片缩略图（点击放大/还原）+ 存档路径按钮（点击用系统程序打开）
• 上游故障：明确提示"图像服务暂时不可用"及上游原话

生成的图片双份持久化：

• Harness 附件存储（内容寻址，供对话预览，回放历史会话依然可见）
• ~/DeepSeek-Imagen-Images/imagen-<时间戳>-N.png（可用 IMAGEN_OUTPUT_DIR 环境变量改目录）

🏗️ 架构

packages/imagen/
├── imagen-service/        能力 seam：ImagenService 注册表 + ImagenProvider 接口
├── tool-imagen/           模型工具：generate_image（确定性派发 + 双份持久化）
└── ui-imagen-settings/    浏览器端：设置页 + generate_image 专属工具行

关键设计：

• 预览不污染模型历史：附件引用走工具的 presentationMeta（随会话日志持久化的 UI-only 元数据），不进入模型请求，因此 DeepSeek 等纯文本路由不会被 image block 破坏
• 预览字节下发：插件自建同源路由 GET /imagen/attachment，携带完整附件引用（sha256 + 尺寸 + 字节数），由附件存储逐字段校验后返回图片，URL 天然自验证
• 附件上限：patch 将单图上限从默认 5MB 提升到 20MB（2K PNG 约 7MB）；聚合上限保持默认以兼容 Harness 的请求体校验不变量

🔄 更新插件

修改本仓库源码后，重新运行安装器即可（复制 → patch 迁移 → 重新构建一条龙），然后重启 DeepSeek Harness：

node install-to-harness.cjs "D:\Tools\DeepSeek Harness"

⚠️ Beta 已知限制

• 测试覆盖尚薄：目前仅 imagen-service 有单元测试（注册/派发/错误文案），工具与 UI 行为依赖端到端验证
• 单会话建议的图像数量受附件存储聚合上限（默认 100MB/消息）约束
• 预览路由面向本机回环部署（Harness 默认绑定 127.0.0.1）；若你将 Harness 暴露到局域网，请自行评估风险
• 提供商配置存储在 ~/.dsh/settings.yaml 的 imagen 命名空间，API Key 以明文保存于该文件（与 Harness 凭据管理现状一致）

📄 许可证

MIT