dsh-plugin-photoshop
让 DeepSeek Harness 里的 AI 直接驱动你本机的 Adobe Photoshop：批量抠图、批量处理、跑任意 PS 脚本，不用你手动一张张点。装上之后，说一句话就能让 Photoshop 自己干活。
简体中文 · 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
- Select and Mask / Refine Edge — a modal workspace, so use feather, contract and refine_mask instead
兼容性与要求
| 项目 | 要求 |
|---|---|
| 操作系统 | 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，文件名默认沿用原文件名。
每一张输出都会校验 PNG 头里的 alpha 通道——如果一个文件其实没有变透明，报告会直接写 NO ALPHA 并提示改用 remove-background，不会让一个假成功的文件混过去。
而且会测量边缘质量。 插件会真正解码 PNG、统计 alpha 通道的分布：完全透明、完全不透明、以及部分透明各有多少像素。部分透明的像素数就是轮廓上那条软过渡带的宽度——于是"边缘变好了"从一句主观判断变成了一个数字。同一张图，加上 feather_px: 2, contract_px: 1, mask_blur_px: 1 之后：
| 抠图 | 部分透明像素 | 过渡带占比 |
|---|---|---|
| 未优化 | 1,271 | 0.75% |
| 优化后 | 12,637 | 7.36% |
过渡带宽了约十倍，而这个数字是测试跑出来的，不是我说的。
示例：
> 把 D:\frames 和 D:\more\a.jpg 一起抠图，输出到 D:\cutouts，先试 5 张，边缘羽化 1 像素，最长边限制 1200
photoshop_batch —— 批量生产
把同一套操作跑在一批文件上，整批在一个 Photoshop 会话内完成。
| 参数 | 说明 |
|---|---|
paths |
必填。图片文件或文件夹 |
ops |
必填。对每个文件执行的操作列表（与 photoshop_apply 同一套词汇） |
output_dir |
必填。结果输出目录 |
output_format |
png（默认，唯一保留透明度）、jpeg、psd、tiff |
suffix |
输出文件名后缀 |
overwrite |
是否覆盖已存在的输出，默认否 |
recursive |
是否递归子文件夹 |
limit |
本次最多处理几个文件 |
每个文件都是打开 → 执行计划 → 存到输出目录 → 不保存关闭，所以原图永远不会被改写。单张失败会被记录下来，批次继续往下跑——一个坏帧就中断整批，对生产毫无用处。
计划里不允许出现 open、new_document、close、save_as——打开、保存、关闭由批次自己负责。带了会被明确拦下并说明原因（save_as 尤其危险：它会让每个输入都写到同一个路径）。
photoshop_apply —— 通用操作
把一串具名操作按顺序作用于已打开的文档。这是插件的通用手：文档设置与缩放、图层的新建/命名/排序/编组、蒙版、不透明度、混合模式、图层样式、色调与色彩调整、滤镜、文字、填充、选区、历史、元数据。
当前共 93 个操作，分九组：
| 组 | 数量 | 覆盖 |
|---|---|---|
document |
16 | 打开/新建/关闭/另存、缩放、画布、裁剪、旋转、翻转、裁边、拼合、合并、复制、色彩模式、配置文件、导出图层 |
layer |
23 | 新建/删除/复制/重命名/移动/编组/解组、不透明度、填充不透明度、混合模式、可见性、锁定、解锁背景、栅格化、智能对象、向下合并、蒙版增删应用反相与边缘柔化、剪贴蒙版、图层样式 |
adjust |
12 | 色阶、亮度对比度、色相饱和度、自然饱和度、黑白、去色、反相、阈值、色调分离、色调均化、自动色阶、自动对比度 |
filter |
20 | 高斯/动感/径向/特殊模糊、USM 锐化、锐化×3、添加杂色、蒙尘划痕、中间值、去斑、高反差保留、最大值、最小值、位移、自定义滤镜、挤压、球面化、旋转扭曲 |
select |
14 | 全选/取消/反选/清除、选择主体、选择天空、移除背景、扩展、收缩、羽化、平滑、边界、存储/载入选区 |
paint |
4 | 新建文字、修改文字、填充、添加纯色图层 |
action |
1 | 列出动作面板（播放被刻意移除，原因见路线图） |
history |
2 | 后退一步、前进一步 |
metadata |
1 | 写入文档元数据 |
两个让它可靠的设计：
- 整组计划是一个 undo 步。 在已有文档打开时，整串操作用
suspendHistory包起来，用户按一次 Ctrl+Z 就撤销 AI 做的所有事。计划本身要和历史打交道时（step_backward）可以关掉这个包装。 - 执行前先在本地校验计划。 拼错的操作名不会白跑一趟 Photoshop，而是当场返回
Unknown operation "gausian_blur". Did you mean gaussian_blur, …。 - 可以干跑（dry-run）。 加
dry_run: true时，它会解析计划里每一个图层引用并告诉你"会碰到什么"，但一个像素都不改——测试里用"history 状态数前后完全相同"来证明这一点。当计划里写了图层名时，这是把猜测变成事实的一次调用。
失败的汇报也是有用的：它告诉你第几个操作、操作名、错误原因、已经成功应用了哪些，以及撤销一次能不能全退回去。
photoshop_reference
按需返回操作词汇表（可只取一组）。不启动 Photoshop，也不需要文档。常驻提示词里只保留一句"需要时去查它"，模型照样能学到全部能力。
photoshop_run_jsx
逃生舱：在 Photoshop 里执行任意 ExtendScript 并返回结果。
批量改尺寸、应用录制好的动作（.atn）、合成图层、读取文档信息……任何 Photoshop 能脚本化的事都能做，不必等插件内置对应功能。
photoshop_run_jsx(script: "app.activeDocument.resizeImage(UnitValue(800,'px'))\n'resized'")
附带一个技能
插件还会注册一个名为 photoshop 的技能，装着"怎么把 PS 用对"的整套工作方法：调用顺序、图层寻址、不伤用户文件的红线、以及这个版本上那些反直觉的坑（新图层是全透明的、背景层要先解锁、图层组不能填充、选择并遮住无法无头运行，等等）。
它是按需加载的，所以常驻提示词里只有一句"做非平凡的 PS 工作前先加载它"，模型需要时再读全文。
安全性
这个插件会操作你真实的 Photoshop，所以设计上刻意保守：
- 只操作它自己打开的文档。你手动打开的文件永远不会被关闭。
- 永远不保存回原图。所有文档都以「不保存」关闭，输出只写到你指定的输出目录。
- 不改你的 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"
许可
本项目为独立社区项目，与 DeepSeek AI / DeepSeek Harness 官方无隶属关系，也未被官方背书。插件名 dsh-plugin-photoshop 不含官方包前缀，走的是 DSH 的公开插件规范（导出 apply(ctx) + cordis.patch.yml）。
许可与文档：MIT · CHANGELOG · 路线图与能力清单依据
