> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Photoshop Bridge

> photoshop-bridge — 通过 MCP 把 Profy 接到本机 Photoshop：图层操作、智能对象、批处理

# Photoshop Bridge

把 Profy 接到你本机的 Adobe Photoshop，让专家能操作图层、用智能对象做可逆变换、跑批处理配方。

与 Profy 的 AI 生图能力（`profy-creative`）是两件事：生图是**从无到有造像素**，Photoshop Bridge 是**在你已有的 PSD 上做精确编辑**——图层结构、蒙版、调整图层这些生图模型给不了的东西。

<Warning>
  **当前实现状态（核对于 2026-08-11）**：本插件的 `mcpServers` 声明（`uvx photoshop-mcp`）在代码库中**没有任何消费方**——agent-runtime 的 `PluginManifest.mcp_servers` 被解析但从未读取，Core 侧只装配社区插件的 MCP，不覆盖内置 manifest。

  勾选后你会得到它的**技能与提示词**（非破坏性编辑纪律、批处理方法会真实影响模型行为），但**拿不到可调用的 Photoshop 工具**。
</Warning>

## 声明与激活

```json theme={null}
{
  "id": "photoshop-bridge",
  "name": "Photoshop Bridge",
  "version": "1.0.0",
  "mcpServers": [{ "name": "photoshop", "command": "uvx", "args": ["photoshop-mcp"] }],
  "activation": { "requires": { "desktop_connected": true }, "user_selectable": true }
}
```

两道门同时通过才激活：勾选（`user_selectable`）+ Desktop 已连接（`desktop_connected`，即 `PROFY_DESKTOP == "true"`）。云端网页对话里它不存在。

## 环境前置

| 要求                       | 说明                         |
| ------------------------ | -------------------------- |
| Adobe Photoshop 2024 或更高 | 需开启 UXP 开发者模式              |
| Python `uv` 已安装          | `uvx` 用于拉起 `photoshop-mcp` |
| Profy Desktop            | 云端不可用                      |

## 非破坏性编辑纪律（技能层，当前即生效）

整个技能围绕一条主线：**每一步都要留得住退路**。

```
1. 打开或新建文档
2. 在独立图层上作业（非破坏性）
3. 需要可逆变换时用智能对象
4. 每个重要操作后截图
5. 勤存版本（PSD 保图层，PNG/JPG 用于导出）
```

### 为什么强调非破坏

AI 编辑与人工编辑的关键差异在于**试错次数**。人改一版会想清楚再动手，模型会连着试五版。如果每一版都是破坏性的（直接在背景层上抹、直接应用滤镜），第三版发现方向错了就回不去了。

所以技能把这条写成硬约束：

* 在复制出的图层上作业，**绝不直接改背景层**
* 用调整图层做色彩校正（非破坏），而不是直接 Apply
* 拼合之前先存 PSD
* 绝不覆盖原始文件

## 能力清单（MCP 接线补齐后可用）

| 类别    | 内容                                |
| ----- | --------------------------------- |
| 文档    | 创建与管理                             |
| 图层    | 创建、复制、合并、混合模式、不透明度                |
| 选区    | 选框、魔棒、主体选择、快速蒙版                   |
| 调整    | 色阶、曲线、色相/饱和度（均以调整图层形式）            |
| 滤镜    | 模糊、锐化、噪点、扭曲                       |
| 文字与形状 | 文字图层（字体、字号、颜色）、形状图层               |
| 蒙版    | 图层蒙版、剪贴蒙版                         |
| 导出    | PNG（透明）、JPG（照片）、WebP（网页）、PSD（带图层） |
| 批处理   | 配方式批量应用                           |

## 批处理配方

重复性任务的推荐做法是三步，**中间那步是关键**：

1. 定义配方——把操作序列固定下来
2. 应用到整个图片文件夹
3. **先验证样本输出，再跑全量**

第 3 步顺序不能颠倒。批处理的破坏是规模化的：配方错了跑 500 张，和跑 1 张的代价差 500 倍，而验证 1 张的成本几乎为零。

## 色彩空间

提示词层要求按用途选色彩空间：网页用 sRGB，印刷用 CMYK。这不是可选项——在错误的色彩空间里调完色，转换时颜色会整体偏移，前面的工作全部作废。

## 边界与失败态

* **没有 Desktop 就没有这个插件**，云端对话里不出现。
* **Photoshop 没开 = 前置检查失败**。技能要求先取一次文档信息确认连通（尺寸、色彩模式、位深），拿不到就应停下报错。
* **MCP 声明当前未接线**（见页头），模型会给方法而不会实际执行。
* **UXP 开发者模式必须手动开**。这是 Adobe 侧的设置，装插件不会自动打开它。
* **智能对象不是万能的**。像素级的绘制、部分滤镜仍然是破坏性的，技能的建议是这类操作前先复制图层。

### 排错

| 症状                        | 原因                         | 处理                                |
| ------------------------- | -------------------------- | --------------------------------- |
| 插件面板里找不到 Photoshop Bridge | 不在 Desktop 中，或 Desktop 未连接 | 用 Profy Desktop 打开并确认连接           |
| 勾选了但模型说没有 Photoshop 工具    | `mcpServers` 未接线（见页头）      | 当前预期行为；技能层仍生效                     |
| 连接建立不起来                   | UXP 开发者模式未开启               | 在 Photoshop 首选项里开启后重启应用           |
| `uvx` 找不到                 | Python `uv` 未安装            | 先装 `uv` 并手动验证 `uvx photoshop-mcp` |
| 导出的 PNG 没有透明              | 底部有不透明背景层，或导出前拼合了          | 隐藏背景层，用带 alpha 的格式导出              |
| 批处理结果整体偏色                 | 在错误色彩空间里调的色                | 先转到目标色彩空间再调整，然后重跑                 |

## 验证你的配置

1. 在 Profy Desktop 新对话的插件面板中应能看到 Photoshop Bridge。看不到 = Desktop 未连接。
2. 勾选后问「当前打开的文档是什么尺寸和色彩模式」。返回方法建议而非实际数据，说明命中页头描述的未接线状态。
3. 让它「给一批产品图统一加水印」。正确回答必须包含：先定义配方、**先验证样本**、在复制图层上作业这三点——这验证技能层已加载。

## 相关页面

<CardGroup cols={2}>
  <Card title="图像生成" href="/zh/documentation/capabilities/image-generation">
    云端 AI 生图：从无到有造像素
  </Card>

  <Card title="Blender Bridge" href="/zh/documentation/plugins/blender-bridge">
    同族桥接：本机 Blender 建模与 GLB 导出
  </Card>
</CardGroup>

<Note>
  核对日期 2026-08-11。来源：`services/agent-runtime/src/plugins/builtin/photoshop-bridge/plugin.json`、`skills/photoshop-workflow/SKILL.md`、`prompts/PHOTOSHOP.md`、`services/agent-runtime/src/plugins/registry.py`（`_check_activation`）。
</Note>