图像工坊 naletko/dsh-image-studio

dsh-image-studio

给 DeepSeek Harness 用的 Images 工作区：一个页面就能用 fal.ai 生成图片、翻看你产出过的全部结果、对比候选图，再把胜出的那张交给 Kling，做成图生视频镜头。

Images
┌──────────────────────────────────────────────────────────────────────┐
│ Describe an image… │ │ Model: GPT Image 2 ▾ Aspect: 9:16 ▾ Variants: 4 ▾ [Generate] │ ├──────────────────────────────────────────────────────────────────────┤ │ Gallery | Templates All · Images · Videos · Favourites │ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ 🖼 │ │ 🖼 │ │ 🎬 5s │ │ 🖼 │ click → lightbox │ │ └────────┘ └────────┘ └────────┘ └────────┘ → Animate in Kling │ └──────────────────────────────────────────────────────────────────────┘

你能得到什么

- 一个真正的页面，不是聊天消息。 侧边栏多出 Images 入口；页面里有提示词输入栏、模型与画幅选择器、最多 8 张的变体数量，下面就是画廊。
- 底层是 fal.ai。 接入三个文生图系列，字段名按 fal 自家 OpenAPI 文档声明的来：fal-ai/flux-2/klein/9b（快速探索）、openai/gpt-image-2（质量档，擅长文字渲染）、fal-ai/nano-banana-2（Gemini，参考图编辑，0.5K–4K）。其他任何含 / 的 fal slug 都能当自定义端点用。
- 你生成过的东西都还在。 结果落到磁盘上的 studio 文件夹，旁边配一份索引，所以翻看零成本、重启不丢、服务商挂了也能用。收藏、搜索、按类型筛选都能缩小网格范围。
- 一个真正好用的灯箱。 按原始尺寸看图、下载原图、复制提示词、标为收藏，或者按 Animate in Kling 把这张静帧变成镜头——Kling v3 Pro 图生视频，运动提示词和时长都由你定。
- 一个混剪标签页。 把片段和静帧挑进时间线，选 9:16 / 4:5 / 1:1 / 16:9，宿主用 ffmpeg 把它们合成一个 h264 文件——先把每段统一到同样的尺寸、帧率、像素格式，再拼接，不重新编码。静帧按你选的停留时长循环成片段。
- 模板。 八个起步提示词（产品主图、生活方式、UGC 自拍、平铺摆拍、前后对比、节令、角色设定表、美食特写），俄语和英语都有。模板只填提示词框，你不按 Generate 就不花钱。
- 双语界面。 俄语和英语，跟着界面语言走。
- 密钥永远不离开凭据存储。 设置卡片通过 harness 凭据接缝写入 fal 密钥；宿主从不把值返回给页面，也从不把密钥写进配置。

安装

从插件页面安装（推荐）

1. 打开 Plugins → Add plugin。
2. 粘贴包名（发布后可用），或者这个文件夹的绝对路径：

dsh-image-studio
C:\Users\you\Documents\deepseek-harness\dsh-image-studio

3. 安装，然后按页面提示重启 harness。

从终端安装

dsh plugin --profile web add dsh-image-studio # web profile
dsh plugin --profile desktop add dsh-image-studio # only while DSH Desktop is fully quit

desktop 配置档属于 DSH Desktop 应用：应用运行时它拒绝终端管理，所以这里请用 Plugins → Add plugin。装好后侧边栏会显示 Images。

API key 存在哪里

key 是凭据引用，绝不是配置值。默认引用是 FAL_API_KEY，解析顺序沿用 harness 自己的规则：

1. 启动 harness 时的环境变量（FAL_API_KEY=… dsh）——应用只读；
2. 凭据存储 ~/.dsh/.credentials.yaml：

version: 1
refs:
FAL_API_KEY: <key_id>:<key_secret>

3. <workspace>/.env，然后是 ~/.dsh/.env。

最省事的做法是用 Settings → Plugins → Images (fal.ai) 里的卡片：粘贴 key_id:key_secret（fal.ai → Keys 里的整串内容），点 Save。卡片会显示 key 是否已配置、来自哪里——但从不显示值本身。存好之后，下一次 Generate 就会用它，不用重启。

引用名可以在该行的配置里改（falKeyRef）。如果某台机器把 key 存在别的名字下，这个就有用。

更新

插件会自己更新，不用卸载或重装：

- Settings → Plugins → Image Studio → Updates 会向 GitHub 查询分支版本，把已安装版本和 main 上的版本并排显示，列出改动内容，一键把锁定 commit 交给 harness 插件管理器。
- 分支上有新版本时，页面标题栏的计数器旁边也会出现 Update 按钮。
- 更新后重新加载页面。浏览器那一半的改动立即生效；宿主那一半的改动需要重启应用，如果运行中的版本没变，该区块会说明这一点。

检查读取的是插件自己的仓库（updateRepo，默认 naletko/dsh-image-studio），可以在该行配置里用 updateCheck: false 关掉。除此之外不拉取任何东西，安装 spec 由插件根据配置的仓库加一个校验过的 commit hash 拼出来——绝不来自请求。

如果部署环境没有插件管理器，同一个区块会打印出手动 spec，粘贴到 Plugins → Add plugin 即可：

github:naletko/dsh-image-studio

文件放在哪里

<DSH_HOME>/image-studio/
gallery.json the index: one entry per image or video
config.json non-secret defaults (model, aspect, variants)
files/<id>.png the media itself, named from a generated id
<DSH_HOME> 就是 $DSH_HOME 或 ~/.dsh。设置 DSH_IMAGE_STUDIO_HOME 可以把 studio 放到别处——当图库需要放在更大的磁盘上，或者要单独备份时很有用。这个文件夹里的内容永远不会提供给另一台机器：/api/image-studio/file 只响应 loopback 调用方，而且每条路径都由校验过的 id 拼出来。

配置

行配置来自配置档补丁（~/.dsh/profiles/<profile>/cordis.patch.yml）：

| 键 | 默认值 | 含义 |
| falKeyRef | FAL_API_KEY | 保存 fal 密钥的凭据引用。 |
| defaultModel | fal-ai/flux-2/klein/9b | 页面上预选的模型。 |
| defaultAspect | 1:1 | 页面上预选的宽高比。 |
| defaultCount | 1 | 页面上预选的变体数量。 |
| imageTimeoutMs | 240000 | 单个文生图任务的时限。 |
| videoTimeoutMs | 900000 | 单个视频任务的时限；Kling 渲染要花几分钟。 |
| ffmpegPath | 空 | 用于拼片的 ffmpeg 可执行文件；留空表示从 PATH 取 ffmpeg。 |

HTTP 接口

页面做的所有事情都走插件自己的 loopback 路由。这些路由的存在，是为了让浏览器那一半永远不碰服务商、密钥或文件路径。

| 路由 | 用途 |
| GET /state | 目录、默认值、凭据状态、计数器、studio 路径 |
| GET /gallery?kind=&q=&favorite= | 过滤后的索引 |
| GET /file?id= | 某一条目的媒体字节 |
| POST /credentials | 保存或清除 fal 密钥（只写） |
| POST /config | 非密钥类默认值 |
| POST /generate、POST /video、POST /montage | 把任务加入队列，返回 202 和该任务 |
| GET /job?id= | 任务状态、队列位置、产出的条目 |
| POST /favorite、POST /delete | 日常管理 |

所有路由都会拒绝任何不是来自 loopback 来源的 loopback 请求，请求体上限 256 KB，媒体只从由校验过的 id 重新拼出的路径读取。

兼容性

| 包 | 版本 |
| dsh-image-studio | 0.1.0 |
| DSH core | 0.2.0-rc.2、0.2.0-rc.1（compatibility.json） |
| Node | ^22.19.0 \|\| >=24.0.0 |

Windows 和 macOS 都支持：没有平台相关代码，不调用 shell，没有原生模块，没有构建步骤——浏览器那一半只是普通脚本，由 harness 自己加载。

测试

npm run check # syntax, every file
node test/catalog-check.mjs # request shaping for each model family
node test/fal-check.mjs # the fal queue client against a scripted queue
node test/gallery-check.mjs # index, path confinement, pruning
node test/montage-check.mjs # ffmpeg command planning, plus a real assembly when ffmpeg can run
node test/host-check.mjs # the HTTP surface end to end, fake credentials and a fake queue
node test/metadata-check.mjs # the browser half's module and slot registrations
node test/render-check.mjs # every component rendered with real data, effects inert
node test/manifest-check.mjs # the bundle contract the harness reads
node --test test/ 会为每个文件启动一个子进程，有些沙箱会拒绝这种做法；直接运行文件则始终可行。

已知限制

- 只支持 fal.ai。 服务商接缝只有一个客户端；想接入另一个网关，就得在 lib/fal.js 旁边再加一个模块。
- 还不支持参考图输入。 页面上没有暴露图生图和角色一致性功能，尽管 fal 上已经有对应的编辑端点。
- 任务存在内存里。 一次生成能挺过页面刷新，但挺不过 harness 重启；已经写入的媒体两种情况都会保留。
- 画廊是本机的。 它就是一个文件夹，不是同步服务。
- 拼接是硬切，不是剪辑。 片段按顺序拼接，尺寸和帧率一致；还没有交叉淡化，没有音轨，没有标题。它需要机器上装有 ffmpeg，缺失时标签页会说明这一点。
- 模型看不到视频。 harness 的内容词汇表里没有视频块，所以模型只能知道一个文件路径；图片是由生成它们的插件作为附件返回给对话的，不是由这个页面返回。

隐私

插件只与 fal.ai 通信，不碰其他任何东西。提示词、媒体和密钥都留在本机；密钥每次调用时从 harness 凭据存储读取，绝不记录日志、绝不回显、也绝不写进配置文件。

许可证

MIT © 2026 Alex Naletko。