dsh-photoshop-genfill：Photoshop 修图代理插件

前言¶

DeepSeek Harness（DSH）的插件模型允许在对话中直接调用外部服务。对于图像处理场景，常见的做法是让 Agent 生成图片 URL，再由人工或脚本手动导入 Photoshop。这种方式在「选区填充」「局部重绘」等连续操作中会打断工作流，且无法利用 Photoshop 原生非破坏性工具（蒙版、调整图层、智能对象）。

dsh-photoshop-genfill 是一个 DeepSeek Harness 的 profile 插件包，把 Photoshop 操作与图片生成 / 编辑 API 接在一起，提供一套「抓选区 → 调用 API → 写回蒙版图层」的闭环工具。插件基于 @alisaitteke/photoshop-mcp（MCP stdio 连接），将 128 个 Photoshop 工具注册为 mcp__photoshop__*，同时暴露若干 Host 工具和斜杠命令，供 Agent 或用户直接使用。

核心能力¶

插件提供以下能力：

生成式填充（选区 → 编辑 → 回填蒙版图层）：ps_generative_fill、/psfill <提示词>
文生图并放入当前文档（适配画布）：ps_generate_layer、/psgen <描述>
图生图 / 局部重绘：ps_image_edit、/psedit <要求>
只出图不入 Photoshop（先预览再选用）：ps_generate_images
把本地图片放入当前文档：ps_place_image
查看当前合成画布的图像预览（返回图片内容）：ps_preview
查看当前 Photoshop / 文档 / 选区 / 图层 / API 配置：ps_state、/psstatus
撤销历史步骤：ps_undo、/psundo [n]

MCP 连接会注册 128 个 Photoshop 工具（如 mcp__photoshop__photoshop_select_subject、mcp__photoshop__photoshop_recipe_remove_background 等），用于建选区、调图层、导出、批处理等精细操作。插件只负责「图片生成 API + 图层回填」这一段串接。

修图 Agent 工作流示例¶

在 Photoshop 中打开一张图，用选框工具圈出区域（或让 Agent 调用 mcp__photoshop__photoshop_select_subject 选中主体）。
在 Harness 中执行 /psfill 赛博朋克夜景，霓虹灯，电影感。
- 插件抓取选区 → 调用图片编辑 API → 以「AI Fill …」新图层回填，并按选区加蒙版。
如需回退，执行 /psundo 1；或用 /psstatus 查看文档 / 选区 / 图层状态。

对 Agent 的自然语言示例：
- 「用生成式填充把选区改成赛博朋克夜景，保留构图」
- 「选中这个人物，把他换成穿宇航服的样子」
- 「生成一张极简产品海报放到当前文档，做成新图层」
- 「把整个画布调成暖色电影感，先给我三张图看看」→ 会先调用 ps_generate_images，再 ps_place_image。

安装与启用¶

前置要求¶

macOS 或 Windows
Adobe Photoshop 2024+，且可以被本机自动化控制
Node.js 22+
兼容 OpenAI Images API 的服务地址和 API Key（本插件默认使用 https://chatgpt2api.343426.xyz/v1，模型 gpt-image-2）

从本地目录安装¶

在 Harness 中执行：

plugin_manager install_bundle → target: /path/to/dsh-photoshop-genfill

提示：install_bundle 的 registry 参数是给 npm 包用的，安装本地目录时不要传空字符串，否则会报 a registry must be an http(s) URL。省略该参数即可。

从 GitHub 安装（需先克隆）¶

克隆仓库：

git clone https://github.com/<你的账号>/dsh-photoshop-genfill.git
cd dsh-photoshop-genfill

在 Harness 中执行 plugin_manager install_bundle，将 target 指向克隆下来的仓库目录。
在 Harness Settings → Plugins 中启用 Photoshop Retouch Agent，填写 API 地址、Key 和模型。
重启或重新加载 Harness；首次启动 MCP 时允许 Harness 控制 Photoshop。

安装会同时启用 photoshop-mcp 和本插件的 Host 工具、命令与 Web 面板。

配置¶

配置写在 bundle 的 cordis.patch.yml 里作为初始值；安装后可在 Harness Settings → Plugins → Photoshop Retouch Agent 中修改。改完重载插件或重启 Harness 生效。

- id: photoshop-genfill
  name: '@local/dsh-photoshop-genfill'
  config:
    apiBaseUrl: 'https://your-image-api.example/v1'
    apiKey: ''                         # 建议在 Settings 填写，或使用 PS_GENFILL_API_KEY
    model: 'gpt-image-2'               # 旧配置兼容回退值
    generationModel: 'gpt-image-2'     # ps_generate_layer / ps_generate_images
    editModel: 'gpt-image-2'            # ps_generative_fill / ps_image_edit
    photoshopApp: 'Adobe Photoshop 2026'
    outputDir: '~/.dsh/photoshop-genfill'
    requestTimeoutMs: 180000
    defaultFit: 'cover'

说明：

apiBaseUrl 支持带或不带 /v1；接口路径固定为 POST /v1/images/generations、POST /v1/images/edits。
apiKey 不要提交到 GitHub；可以在插件 Settings 填写，也可以设置环境变量 PS_GENFILL_API_KEY。
图片接口返回 {"error":{"message":…}} 时会转成可读错误。
所有生成物落在 outputDir：capture-*.png、gen-*.png、edit-*.png。

generationModel 和 editModel 可以填写不同模型。例如文生图使用 gpt-image-2，图像编辑使用服务商提供的 gpt-image-2-edit。如果只填写旧字段 model，两个端点都会回退到它。

面板与命令¶

安装后，Web GUI 输入框下方会出现一个紧凑面板：

● PS 生成式填充   [模式 ▾]  [提示词…]                    [生成]  [状态] [撤销]

模式：填充（选区）/ 生成（新图层）/ 编辑（图生图）。
提交后通过 Harness 的 Client Remote 执行对应全局命令，结果同时出现在对话里的命令记录行。
面板只做触发与状态展示，真正的流水线在 Host 端执行（不占模型 token）。

命令输出示例：

✅ 生成式填充
已生成并写入图层「AI Fill 16:21:03 cyberpunk」（选区 620×480px，已按选区加蒙版）。
图层: AI Fill 16:21:03 cyberpunk
文档: poster.psd (1920×1080px)
区域: selection 620×480px @ (100,50)，已加选区蒙版
图片 API: gpt-image-2 / 27.3s
输出: edit-<timestamp>.png

实现结构¶

目录结构如下：

.
├── package.json          # bundle 清单：dsh.bundle.patch + dsh.client
├── cordis.patch.yml      # MCP 连接行 + Host 插件行（含配置）
├── index.js              # Host：Config schema、工具注册、斜杠命令注册
├── lib/
│   ├── ps-bridge.js      # macOS：AppleScript → Photoshop ExtendScript，串行队列/超时/错误
│   ├── ps-scripts.js     # ExtendScript 片段：读状态/抓选区/放置图层/加蒙版/撤销
│   ├── image-api.js      # 兼容 OpenAI 的 images/generations + images/edits 客户端
│   └── pipeline.js       # 抓取 → 调 API → 回填 + 蒙版 + 结果/错误整理
├── client.js             # Web 面板（composer.dock）
├── locale/en.json|zh.json# 插件清单显示名/描述
└── icon.svg              # 插件图标

数据流：

用户/Agent
  │  /psfill 或 ps_generative_fill
  ▼
pipeline.fill
  ├─ ps-bridge  → AppleScript → Photoshop ExtendScript：读文档/选区，duplicate+crop 导出 PNG
  ├─ image-api  → POST /v1/images/edits (multipart: model, prompt, image)
  └─ ps-bridge  → Photoshop：Place 为智能对象 → 缩放到选区 → 按选区建图层蒙版 → 重命名

细节：

结果以智能对象放置，可再用 Photoshop 的「替换内容」非破坏地迭代。
fit：cover（默认，保持比例铺满区域）、stretch（拉伸铺满）、contain（完整放入）。
无选区时 region: auto 会退化为当前图层范围、再退化为整幅画布。
结果图层名形如 AI Fill 16:21:03 cyberpunk，便于撤销与识别。
MCP 的 128 个工具与插件命令使用同一个 Photoshop 实例，互不冲突。

排障¶

现象	处理
`Photoshop 操作失败：Photoshop 未运行` / AppleScript 报错	先手动启动 Photoshop 2026；确认系统设置 → 隐私与安全性 → 自动化里 Harness 允许控制 Photoshop。
`图片 API 鉴权失败（401）`	检查 `apiKey`（或 `PS_GENFILL_API_KEY`）；本机 curl 验证：`curl -H "Authorization: Bearer $KEY" https://chatgpt2api.343426.xyz/v1/models`。
`图片 API 超时`	生成/编辑通常 25–60s，接口偶发更慢；适当调大 `requestTimeoutMs`，或重试。
`当前没有像素选区`	用选框/套索/主体选择建选区，或让 Agent 调 `mcp__photoshop__photoshop_select_subject`。
区域太小 / 过大	扩大/缩小选区；上限 8192px 边长。
新图层位置不对	用 `fit: cover` + 重试；或先确认选区/图层 bounds（`/psstatus`）。
MCP 工具不出现	npx 首次下载失败或 npm 源不可用：检查 `~/.npm` 缓存与网络；MCP 行配置了 `npm_config_registry=https://registry.npmjs.org/` 规避镜像限制。
想彻底撤掉	Settings → Plugins 里禁用/卸载 bundle；或 `plugin_manager remove_bundle`。

安全说明¶

公开补丁不包含 API Key，也不包含开发者机器的绝对路径；使用者必须在 Settings 或环境变量中自行配置。
如果历史版本曾经提交过真实 Key，请立即在服务商后台撤销并重新生成；仅从文件中删除并不能让旧提交安全。
插件只写入 outputDir 与 Photoshop 文档；不修改系统设置。
图像编辑接口会将捕获的画布区域发送到你配置的第三方 API，请确认其隐私政策后再处理敏感图片。
MCP 服务由本机 npx 启动，仅通过 stdio 与 Harness 连接。

适用场景与注意¶

适合需要「选区生成式填充」「局部重绘」「文生图并适配画布」等连续操作的图像处理场景。插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证。

小结¶

dsh-photoshop-genfill 把 Photoshop 操作与图片生成 / 编辑 API 接在一起，提供一套「抓选区 → 调用 API → 写回蒙版图层」的闭环工具。对于需要精细修图且希望保持工作流连续性的用户，可以在 Harness 中直接调用 /psfill、/psgen、/psedit 等命令或 Agent 工具，实现从选区填充到图层生成、图生图的一体化操作。

插件目录：https://www.skillhub.cn/plugins/Aliax-LI/dsh-photoshop-genfill
源码仓库：https://github.com/Aliax-LI/dsh-photoshop-genfill