Photoshop 自动化Better-Rain/dsh-plugin-photoshop

dsh-plugin-photoshop

让 DeepSeek Harness 里的 AI 直接驱动你本机的 Adobe Photoshop：批量抠图、批量处理、跑任意 PS 脚本，不用你手动一张张点。装上之后，说一句话就能让 Photoshop 自己干活。

Topic
Listed on dsh-plugin.org

简体中文 · English

30 秒看懂

| | |
| --- | --- |
| 它是什么 | 一个常驻的 DSH 插件，给 AI 装上 7 个工具，用来驱动你本机的 Adobe Photoshop |
| 装完会怎样 | 你可以说「把这批图抠出人物」「把每个图层导出成单独文件」，AI 直接在 Photoshop 里做完，不是给你一段代码 |
| 和别的方案比 | 用的是 Photoshop 自己的「选择主体」——在人物、产品、插画上明显强于开源抠图模型 |
| 代价 | 需要 Windows + 本机装好的 Photoshop。不联网，不上传，零第三方依赖 |

它解决什么问题

想从一段视频里抽帧、再把画面里的人物抠出来当素材时，Photoshop 的「选择主体」比开源抠图模型准得多，但 AI 助手够不到你电脑上的 Photoshop，只能你自己一张张手动做。

装上这个插件之后，你只要说一句：

把 D:\frames 里所有图抠出人物，输出到 D:\cutouts

AI 就会调用本机 Photoshop 把整批做完，产出带透明通道的 PNG，并逐张报告结果。

实际输出

下面都是真实运行结果，不是示意。

批量抠图 —— 40 帧，单次调用（每张还报出边缘质量：部分透明像素的数量，也就是轮廓上软过渡带的宽度）

Photoshop cutout — mode select-subject, 40 image(s) queued
succeeded 40, failed 0, skipped 0
output: D:\cutouts
[ok]   male_station_000.png -> male_station_000.png  670x874 -> 670x874 (alpha, soft edge (4869 partial pixels, 0.83%))
[ok]   male_station_001.png -> male_station_001.png  671x874 -> 671x874 (alpha, soft edge (4739 partial pixels, 0.81%))
[ok]   male_station_002.png -> male_station_002.png  672x874 -> 672x874 (alpha, soft edge (4797 partial pixels, 0.82%))

一个计划 = 一个 undo 步 —— 46 个操作，用户按一次 Ctrl+Z 全部撤销

Applied 46 operations in a single undo step:
1. select_all          7. fill              13. black_white      19. posterize
2. contract            8. save_selection    14. auto_levels      20. equalize
3. feather             9. deselect          15. auto_contrast    21. gaussian_blur
4. fill               10. load_selection    16. desaturate       22. motion_blur
5. save_selection     11. deselect          17. invert           23. radial_blur
6. deselect           12. levels            18. threshold        24. smart_blur
...

动手之前先干跑，抓出写错的图层名（一个像素都不改，测试用 history 状态数前后一致来证明）

Dry run — 3 operations, nothing applied
1. select_all           ok    target = the active layer, "Green"
2. gaussian_blur        ok    target "Canvas" -> "Canvas"
3. gaussian_blur        FAIL  target "NoSuchLayer": no layer named "NoSuchLayer" — run photoshop_inspect to see the layer tree

1 operation(s) name something that does not exist. Fix those before running the plan for real.

环境自检会说清"这台机器做不到什么"，而不是让你撞上去才发现

Adobe Photoshop 27.0.0 (build 27.0 (20251015.r.25 d1c1320))
select subject available: yes
remove background available: yes

Not available on this installation, established by running them:
- Neural Filters and Generative Fill — the commands are not available here
- The Layer > Matting menu: Defringe, Remove White Matte, Remove Black Matte
- 选择并遮住 / 调整边缘 — 这是一个模态工作区，因此请改用 feather、contract 和 refine_mask

兼容性与要求

| 项目 | 要求 |
| --- | --- |
| 操作系统 | Windows（走 COM 自动化接口，macOS / Linux 不支持） |
| Photoshop | 本插件在 Photoshop 2026 / 27.0 上完整验证；「选择主体」需要 Photoshop 2020 及以上 |
| DSH profile | web 已验证；插件在 host 平面且零依赖，任何注册了 tools 服务的 profile 都能用 |
| Node.js | 20 或更高（DSH 本体已要求） |
| 其他 | 无需 ffmpeg、无需 Python、无任何第三方依赖 |
| 许可证 | MIT |

安装

dsh plugin --profile web add github:better-rain/dsh-plugin-photoshop

一条命令，无需构建——仓库里已包含可直接加载的 lib/。

发布到 npm 之后也可以直接用包名（更短）：

dsh plugin --profile web add dsh-plugin-photoshop

包名版本需要该版本已在 npm 上发布。当前请用上面的 GitHub 源命令，它现在就能装。

装完重启 dsh web 即生效。插件是常驻的：之后每个新会话都能用。

换个 profile 就换名字（web 是已验证的）：

dsh plugin --profile tui add github:better-rain/dsh-plugin-photoshop

卸载：

dsh plugin --profile web remove dsh-plugin-photoshop

权限与外部服务

这个插件会驱动你真实的 Photoshop，所以边界在这里说清楚。

它需要什么

- 本机装好的 Adobe Photoshop（Windows）
- 对你指定的文件与目录的读写权限
- 如果 Photoshop 当时没开着，第一次调用会启动它（你屏幕上会看到窗口出现，冷启动可能要一分钟）

它不会做什么

- 不联网。 没有遥测、不需要账号、不上传任何数据——所有处理都在本机 Photoshop 里完成
- 不改你的输入文件。 每个文档都以「不保存」关闭，输出只写到你指定的目录
- 不关闭你自己打开的文档。 它只关闭自己打开的那些
- 不改你的 Photoshop 偏好。 脚本执行期间临时抑制弹窗（弹窗会卡死自动化），结束后立即恢复原值
- 不覆盖已有的输出文件，除非明确传 overwrite: true

动手前想确认安全，用这两个

- photoshop_apply 加 dry_run: true：先看它会碰什么，一个像素都不改
- 一个计划在已有文档打开时是单个 undo 步，一次 Ctrl+Z 全部撤销

已知限制（都是实测结论，不是推测）：整个「修边」菜单、Neural Filters、生成式填充、Camera Raw 滤镜、在低版本上缺失的命令，以及"播放录制动作"（会弹出无法从脚本端关闭的对话框）。photoshop_status 会把这些直接列出来。

七个工具

photoshop_status

环境自检。只读，不打开也不修改任何文件。

报告 Photoshop 版本与 build、是否已经在运行、当前打开了哪些文档、这个版本有没有「选择主体」和「移除背景」命令。当 Photoshop 相关操作莫名失败时，先跑它。

photoshop_inspect

读取当前屏幕上的真实状态。只读。

报告每个打开的文档，以及其中一个的：尺寸、分辨率、色彩模式、位深、色彩配置文件、磁盘路径、是否有未保存修改、当前活动图层、选区范围、历史记录位置、通道/路径/参考线数量。

然后是完整的图层树，每个图层都会带上：索引路径、名称路径、类型、可见性、不透明度、填充不透明度、混合模式、是否剪贴蒙版、是否有蒙版、是否有矢量蒙版、是否有图层样式、是否背景层、边界范围；文字图层还会读出内容、字号、字体和对齐方式。

图层用两种方式标识，方便后续操作引用：

- 索引路径 0.1 —— 第一个组里的第二个图层
- 名称路径 Header/Title —— 就是你平时嘴上说的那个名字

为什么先做这个：现实中几乎每个需求都是相对于已经打开的东西说的——"把背景层换成蓝色"、"把这个组里所有图层导出"。没有这一步，AI 只能猜图层名，而猜就是它不可靠的根源。

photoshop_cutout —— 主力工具

批量抠图。整批在同一个 Photoshop 会话内处理完，而不是每张图来回一次，几百张图的场景下速度差一个数量级。

| 参数 | 说明 |
| --- | --- |
| paths | 必填。图片文件或文件夹（可混用、可多个） |
| output_dir | 必填。输出目录，不存在会自动创建 |
| mode | select-subject（选择主体，默认）或 remove-background（移除背景） |
| recursive | 是否递归扫描子文件夹，默认否 |
| trim | 是否裁掉透明边距让人物贴边，默认是 |
| feather_px | 边缘羽化像素数，默认 0（保留「选择主体」自带的抗锯齿） |
| contract_px | 抠图前把选区收缩几像素，丢掉主体原来压着的那圈背景——这是消除彩色描边最有效的手段，也是 Photoshop「修边」菜单无法脚本化时的替代方案。默认 0 |
| mask_blur_px | 抠图后对图层蒙版做模糊，进一步柔化轮廓。默认 0。这是「选择并遮住」无法无头运行时的替代方案 |
| max_side | 最长边限制，超过则等比缩小，默认 0（保持原尺寸） |
| suffix | 输出文件名后缀，默认无 |
| overwrite | 是否覆盖已存在的输出，默认否（跳过并说明） |
| limit | 本次最多处理几张，用来先试几张看看效果 |
| timeout_ms | 整批的时间预算，几百张图时请调大 |

输出为 PNG-24 带 alpha，文件名默认沿用原文件名。
Every output is validated for the alpha channel in the PNG header—if a file hasn't actually become transparent, the report will directly write NO ALPHA and suggest switching to remove-background, rather than letting a falsely successful file slip through.

And it measures edge quality. The plugin actually decodes the PNG and tallies the distribution of the alpha channel: how many pixels are fully transparent, fully opaque, and partially transparent. The number of partially transparent pixels is the width of that soft transition band along the contour—so "the edges got better" goes from a subjective judgment to a number. For the same image, after adding feather_px: 2, contract_px: 1, mask_blur_px: 1:

| Cutout | Partially transparent pixels | Transition band ratio |
| --- | --- | --- |
| Unoptimized | 1,271 | 0.75% |
| Optimized | 12,637 | 7.36% |

The transition band is about ten times wider, and this number came out of a test run, not from me saying so.

Example:

Cut out D:\frames and D:\more\a.jpg together, output to D:\cutouts, try 5 first, feather edges by 1 pixel, limit the longest side to 1200

photoshop_batch — batch production

Run the same set of operations on a batch of files, with the whole batch completed within a single Photoshop session.

| Parameter | Description |
| --- | --- |
| paths | Required. Image files or folders |
| ops | Required. The list of operations to perform on each file (same vocabulary as photoshop_apply) |
| output_dir | Required. The output directory for results |
| output_format | png (default, the only one that preserves transparency), jpeg, psd, tiff |
| suffix | Suffix for output filenames |
| overwrite | Whether to overwrite existing outputs, default no |
| recursive | Whether to recurse into subfolders |
| limit | Maximum number of files to process this time |

Each file is opened → execute the plan → save to the output directory → close without saving, so the original image is never rewritten. A single failure is logged, and the batch keeps running—aborting the whole batch because of one bad frame is useless for production.

The plan is not allowed to contain open, new_document, close, or save_as—opening, saving, and closing are handled by the batch itself. If included, it will be explicitly blocked with an explanation (especially save_as: it would make every input write to the same path).

photoshop_apply — general operations

Apply a series of named operations in order to an already-open document. This is the plugin's general-purpose hand: document settings and scaling, layer creation/naming/ordering/grouping, masks, opacity, blend modes, layer styles, tonal and color adjustments, filters, text, fills, selections, history, metadata.

Currently 93 operations in total, divided into nine groups:

| Group | Count | Coverage |
| --- | --- | --- |
| document | 16 | Open/new/close/save as, scaling, canvas, crop, rotate, flip, trim, flatten, merge, duplicate, color mode, profile, export layers |
| layer | 23 | New/delete/duplicate/rename/move/group/ungroup, opacity, fill opacity, blend mode, visibility, lock, unlock background, rasterize, smart object, merge down, mask add/delete/apply/invert and edge feathering, clipping mask, layer styles |
| adjust | 12 | Levels, brightness/contrast, hue/saturation, vibrance, black & white, desaturate, invert, threshold, posterize, equalize, auto levels, auto contrast |
| filter | 20 | Gaussian/motion/radial/smart blur, USM sharpen, sharpen ×3, add noise, dust & scratches, median, despeckle, high pass, maximum, minimum, offset, custom filter, pinch, spherize, twirl |
| select | 14 | Select all/deselect/inverse/clear, select subject, select sky, remove background, expand, contract, feather, smooth, border, save/load selection |
| paint | 4 | New text, edit text, fill, add solid color layer |
| action | 1 | List the actions panel (playback was deliberately removed, see the roadmap for why) |
| history | 2 | Step backward, step forward |
| metadata | 1 | Write document metadata |

Two design choices that make it reliable:

- The entire group plan is one undo step. When an existing document is open, the whole sequence of operations is wrapped in suspendHistory, so the user presses Ctrl+Z once to undo everything the AI did. If the plan itself needs to interact with history (step_backward), this wrapper can be turned off.
- Validate the plan locally before execution. A misspelled operation name won't waste a trip to Photoshop; instead it returns on the spot Unknown operation "gausian_blur". Did you mean gaussian_blur, ….
- Dry-run is available. With dry_run: true, it resolves every layer reference in the plan and tells you "what will be touched," but doesn't change a single pixel—the tests prove this by "the history state count is exactly the same before and after." When the plan contains layer names, this is the call that turns guesswork into fact.

Failure reporting is also useful: it tells you which operation number, the operation name, the cause of the error, which ones were already successfully applied, and whether a single undo can roll everything back.

photoshop_reference

Returns the operation vocabulary on demand (optionally just one group). It doesn't launch Photoshop and doesn't need a document. The persistent prompt keeps only one line, "look it up when needed," and the model can still learn all the capabilities.

photoshop_run_jsx

Escape hatch: execute arbitrary ExtendScript in Photoshop and return the result.

Batch resizing, applying recorded actions (.atn), compositing layers, reading document info… anything Photoshop can script can be done, without waiting for the plugin to have a corresponding built-in feature.

photoshop_run_jsx(script: "app.activeDocument.resizeImage(UnitValue(800,'px'))\n'resized'")

Comes with a skill

The plugin also registers a skill named photoshop, containing the entire working methodology for "how to use PS correctly": call order, layer addressing, the red lines that keep user files safe, and the counterintuitive pitfalls in this version (new layers are fully transparent, the background layer must be unlocked first, layer groups can't be filled, Select and Mask can't run headless, etc.).

It is loaded on demand, so the persistent prompt contains only one line, "load it before doing non-trivial PS work," and the model reads the full text when needed.

Safety

This plugin operates your real Photoshop, so it is deliberately conservative by design:

- It only operates on documents it opened itself. Files you opened manually will never be closed.
- It never saves back to the original image. All documents are closed with "don't save," and output is written only to the output directory you specify.
- 不改你的 Photoshop 偏好。脚本执行期间会临时抑制弹窗（否则会卡死自动化），结束后立刻恢复原值。
- 覆盖需显式授权。输出文件已存在时默认跳过并提示，只有传 overwrite: true 才会覆盖。
- 可中断。批处理每张图之间会检查取消标记，被取消时已完成的部分仍会完整汇报。

工作原理

Photoshop 在 Windows 上注册了一个版本无关的 COM 自动化服务 Photoshop.Application，它暴露了 DoJavaScript()，可以在这台正在运行的 Photoshop 里执行 ExtendScript 并取回结果。所以整条链路是：

Node（插件）
└─ powershell.exe -File runner.ps1
└─ New-Object -ComObject Photoshop.Application
└─ DoJavaScript(生成的 ExtendScript)
└─ 真正的 Photoshop

几点实现取舍：

- 参数用 JSON 字面量直接嵌进生成的脚本。JSON 是 JavaScript 字面量的子集，因此不需要任何转义层或 base64 中转。
- 结果走文件、不走控制台。Windows PowerShell 的控制台按代码页编码，非 ASCII 路径和报错信息会被搞乱；所有结果都由 ExtendScript 自己以 UTF-8 写文件。
- 整批一个脚本。一次 COM 往返处理完整批，而不是每张图一次。
- 零依赖。插件不 import 任何 @deepseek-ai/* 框架包，只用 Node 标准库，因此不会因为不同安装器 / 包管理器的依赖提升布局而加载失败。

抠图的正确姿势也是实测出来的：Photoshop 的「选择主体」命令是 autoCutout（selectSubject 这个 action ID 在本版本里会报「命令当前不可用」）；抠图需要先把背景层解锁（isBackgroundLayer = false）才能清除像素，否则反选后的删除会失败。

常见问题

报告 PHOTOSHOP_UNAVAILABLE
这台机器上找不到 Photoshop，或者 COM 服务没注册。确认 Photoshop 能正常启动。

报告 Photoshop did not answer within the time budget
批次太大，或者 Photoshop 本来没开、被这次调用冷启动（冷启动可能要一分钟以上）。调大 timeout_ms。

某张图报 Select Subject found no subject in this image
Photoshop 的 AI 在这张图里没找到主体。换 mode: "remove-background" 试试，或确认画面里确实有人/主体。

输出文件 NO ALPHA
抠图没有真正生效，画面内容仍然是不透明的。改用 remove-background 模式重跑这些图。

超过 --profile web 的其他 profile
把命令里的 web 换成你要装的那个 profile 名即可。

开发

git clone https://github.com/Better-Rain/dsh-plugin-photoshop.git
cd dsh-plugin-photoshop
node test/e2e.mjs                 # 会对真实 Photoshop 跑一次完整验证
node test/probe-capabilities.mjs  # 反射枚举本机 PS 的真实 API 表面
node test/probe-operations.mjs    # 逐项真实执行，产出能力矩阵

test/e2e.mjs 会构建工具定义、注册到替身注册表、然后像工具运行时那样调用它们的 execute——覆盖除 Cordis 本体以外的全链路，并用 PNG 头验证每张输出的 alpha 通道，以及用一个真实夹具文档（含图层组、嵌套文字图层、带蒙版的像素图层）验证 photoshop_inspect 报告的每一项事实。测试输入取自 ~/Pictures/1.jpg（也可以传一张自己的图作为参数），产物落在 _research/e2e/ 供肉眼检查；每次运行都会先清空输出目录，因此可以反复运行。

两个探针是能力清单的依据：反射给出本机真实存在的 API 表面，执行矩阵逐项验证"到底能不能跑"。新增能力时先让它在矩阵里变成 ok，再写进文档。

也可以直接把本目录装进 profile 做开发：

dsh plugin --profile web add "F:\路径\到\dsh-plugin-photoshop"

许可

MIT

本项目为独立社区项目，与 DeepSeek AI / DeepSeek Harness 官方无隶属关系，也未被官方背书。插件名 dsh-plugin-photoshop 不含官方包前缀，走的是 DSH 的公开插件规范（导出 apply(ctx) + cordis.patch.yml）。

许可与文档：MIT · CHANGELOG · 路线图与能力清单依据