前言¶

DeepSeek Harness（DSH）的插件化架构让扩展能力得以沉淀。在本地 ComfyUI 工作流里，dsh-comfyui-image 会把生成结果与 prompt、参数、工作流一并写入磁盘。频繁出图之后，这些文件散落在各处，查看、复用、管理都变得麻烦。相册插件就是围绕这些文件提供统一的入口，在侧边栏直接浏览、操作。

插件定位与解决什么问题¶

dsh-comfyui-album 是一个 DSH 客户端插件，由 YuChenLiao 维护。它不负责出图，只把 dsh-comfyui-image 已经落盘的图片整理成相册。核心价值在于：

• 侧边栏集中入口，避免在文件系统里翻找
• 鼠标悬浮即可复制图片、复制提示词、导出工作流、加入当前对话、删除
• 自动合并同一张图的多个副本，避免重复展示
• 支持目录筛选、搜索、分页加载

核心功能¶

侧边栏入口¶

左侧栏的「相册」是主入口，点击后中央面板显示相册内容。如果安装了 dsh-better-sidebar，相册会注册成一个侧栏页签，可在其「+」菜单或原生右栏里打开。中央面板顶部有「在侧边栏打开」按钮，用于就地跳转到侧栏页签。

相册面板¶

顶部工具栏包含：

• 相册计数
• 按提示词或文件名搜索
• 目录下拉选择
• 「仅生成图 / 含全部图片」切换
• 重新扫描按钮

下方是缩略图网格，每张卡片底部显示提示词开头与「尺寸 · seed · 模型」。滚动到底部会自动续页，拉完即停。

悬浮操作¶

鼠标移到任意一张图上，右上角浮出五个按钮：

• 复制图片：写入系统剪贴板（非 PNG 会先转 PNG）
• 复制提示词：复制 sidecar 里的正向提示词，没有 sidecar 时用 PNG 内嵌的那份
• 导出工作流：下载 <文件名>.workflow.json（ComfyUI API 格式）
• 添加到当前对话：先切回对话，再以「粘贴图片」的方式把图放进输入框草稿
• 删除：彻底删除图片、同名 sidecar、同组副本与缩略图缓存

删除会先弹确认框，不会误点就抹掉文件。

图片详情¶

点开任意一张图显示大图预览，右侧列出全部可复现参数与提示词全文（含负向提示词）。同样具备五个悬浮操作。

大图预览支持：

• 滚轮或 + / - 缩放（0.2×–8×），0 回到适应窗口
• 放大后按住拖动平移，双击在「适应窗口」与 2× 之间切换
• ← / → 切换上一张 / 下一张（首尾循环）
• 翻页只在「已加载」的列表内循环

它怎么找图¶

相册直接扫磁盘上的产物，不建数据库。元数据有两个来源：

1. 同名 sidecar <图片>.json：dsh-comfyui-image 生成时写下的完整记录（默认开启），带 prompt、负向提示词、seed、尺寸、步数、CFG、模型、采样器和完整 workflow。
2. PNG 内嵌工作流：ComfyUI 自己 SaveImage 出来的图没有 sidecar，但 PNG 的 tEXt 里就有 prompt 工作流。宿主只读文件头 64KB 把它解析成同样的字段。

支持的图片扩展名：.png .jpg .jpeg .webp .gif .avif .bmp（内嵌解析只对 PNG 生效）。

默认只列能读到元数据的图（sidecar 或内嵌其一），面板上的「仅生成图 / 含全部图片」可以切换成目录里的所有图片。

扫描根目录按以下顺序查找：

1. 显式配置（roots）
2. 当前工作目录
3. 全部 workspace
4. dsh-comfyui-image 配置里的 outputDir
5. 进程 cwd

一轮扫描按目录缓存 4 秒，面板上的刷新按钮会强制重扫。

列表里的缩略图由宿主按需生成（sharp，360px WebP，落盘缓存）。sharp 不可用时静默回退原图。

重复合并¶

同一次生成常常落两份：ComfyUI 自己 SaveImage 存一份，插件又另存一份（路径与文件名都不同）。相册按「seed + 像素尺寸 + 提示词前 160 字符」判断是不是同一张图，默认只显示一条：

• 卡片左上角的 ×2 角标表示还有 1 份副本，点开灯箱能看到副本的完整路径
• 主项优先取有 sidecar 的那份（元数据更完整），其次路径更短、修改时间更新
• 删除是连坐的：删掉一条就把这一组的全部副本一起从磁盘移除
• 工具栏的「合并重复」可以关掉，改看未合并的原始列表

没有 seed 的图不参与合并。

批量操作¶

工具栏的「选择」进入选择模式：

• 全选当前已加载的图片，或一键清除
• 导出工作流：把所有选中图的工作流打成一个 ZIP（comfyui-album-workflows-<时间戳>.zip）
• 删除：二次确认后从磁盘彻底删除所选图片、同名元数据、同组副本与缩略图缓存

单次批量上限 500 条，防止误选整库。退出选择模式即清空选择。

安装与启用¶

从 GitHub 安装：

# 从 GitHub 安装（<profile> 换成你的 profile 名，常见的是 desktop 或 web）
dsh plugin --profile <profile> add github:YuChenLiao/dsh-comfyui-album

本地开发可以直接把目录 link 进 profile：

dsh plugin --profile <profile> add link:/path/to/dsh-comfyui-album

装完刷新一下页面（Web GUI 要重新加载客户端 bundle）。插件已在 DSH 0.2.1-rc.2 上验证，前置是先装好 dsh-comfyui-image，否则相册里没有东西可看。

配置¶

在 profile 的 cordis.patch.yml 里给本插件那行加 config：

- id: dsh-comfyui-album
  name: dsh-comfyui-album
  config:
    roots: ['D:\Comfy-Desktop\output']  # 额外纳入相册的目录
    maxDepth: 3        # 扫描深度，0 = 只看根目录本身
    maxItems: 4000     # 单个根目录最多收集多少张图
    cacheMs: 4000      # 列表缓存毫秒数
    includeHidden: false

API¶

插件挂在 /comfyui-album/api 下：

• GET /roots — 允许读取的根目录
• GET /items?root=&q=&offset=&limit=&all=1&refresh=1&dedupe=0 — 相册列表（dedupe=0 关闭重复合并；默认合并）
• GET /meta?path= — 单张图片的完整元数据
• GET /workflow?path= — 工作流下载
• GET /file?path=&thumb=1 — 图片字节（thumb=1 取缩略图）
• POST /delete?path= — 删除图片与同名 sidecar，返回 { ok, removed }
• POST /delete-many — body { paths: [...] }（1–500 条），返回 { ok, removed, failed }
• POST /workflows — body { paths: [...] }，把所选图片的工作流打成 ZIP 返回

path 一律校验必须落在白名单根目录内，越界返回 403。写接口只接受 POST/DELETE，读取接口只接受 GET/HEAD。

生态背景¶

DSH 的理念是「一切皆插件」。社区目录 https://www.skillhub.cn/plugins/YuChenLiao/dsh-comfyui-album 是独立站点，与 DeepSeek / 幻方无官方从属关系。

适用场景与注意¶

本插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。它依赖 dsh-comfyui-image 提供元数据，没有它时相册会是空的。

致谢¶

• dsh-comfyui-image：把 prompt、seed、采样参数和完整 workflow 都写进了图片旁边的 sidecar，并坚持“文件名带时间戳、绝不覆盖”的落盘规则。
• dsh-better-sidebar：开放的 ctx.betterSidebar 注册接口和清楚的接入文档。
• DeepSeek Harness：webServer 路由、sidebar.panellist 与 main 面板这套插槽设计。

许可¶

MIT