基于 MCP 协议的 AI 驱动 Photoshop 自动化工具
PSForge 是一个 MCP 服务器，让 AI 助手直接控制 Adobe Photoshop。不再为每个 PS 操作单独封装工具，而是暴露少量高杠杆工具 —— AI 直接生成 ExtendScript，PSForge 通过 COM 执行。
快速开始： 查看 QUICKSTART.md 了解安装指南
上一版把每个 PS 操作（创建图层、设透明度、加模糊……）都封装成独立的 MCP 工具，共 61 个。实际使用中，AI 几乎只用 execute_script 发送原始 ExtendScript，因为：
- 一段脚本能做 10 个工具调用的事，只需一次 COM 往返
- ExtendScript 比任何固定参数集都灵活
- AI 完全有能力生成正确的 ExtendScript
所以 v0.3.0 去掉了所有包壳工具，只保留真正有用的。v0.4.x 继续保留极简核心，同时新增面向图片复刻 PSD 的高层工作流工具。
| 工具 | 用途 |
|---|---|
execute_script |
在 Photoshop 中执行任意 ExtendScript。主力工具。 |
execute_batch |
单次 COM 调用执行多段脚本，各自收集结果。 |
get_session_info |
查询 PS 连接状态、版本、当前文档概况。 |
get_layers |
获取所有图层信息（名称、类型、透明度、混合模式、边界）。 |
capture_canvas |
截图画布返回 base64 PNG，供 AI 视觉反馈。 |
recreate_image_as_layered_psd |
将参考图复刻为分层 PSD，并导出 PNG 预览。支持 fast / balanced / source 模式。 |
除了基础工具，PSForge 还提供内置的 Prompt 模板，帮助大模型以特定的工作流处理任务。
| 提示词 | 用途 |
|---|---|
ps-image-analyzer |
指引 AI 客户端（利用客户端自身的 Vision 视觉能力）分析参考图，并生成一套可被 PSForge 完美执行的 Photoshop 结构化重建规格书（JSON）。 |
Prompts 由 FastMCP 自动注册，可在支持 MCP Prompt 协议的客户端中使用：
- Claude Desktop：点击输入框左侧的 Prompts 列表，选择
ps-image-analyzer，将规则载入上下文。 - Cursor / Agent 助手：用自然语言命令 AI（如 “使用 ps-image-analyzer 提示词分析此图片并重建”），Agent 会自动在后台读取并应用该模板。
| 组件 | 版本 | 说明 |
|---|---|---|
| Python | 3.10 - 3.14 | 必需 |
| 操作系统 | Windows | 使用 COM 接口 |
| Photoshop | CC 2019+ | 需要运行中 |
| MCP 客户端 | 任意 | Claude Desktop、Cursor 等 |
pip install psforge从源码安装：
git clone https://github.com/deermiya/PSForge.git
cd PSForge
pip install -e .编辑 %APPDATA%\Claude\claude_desktop_config.json：
{
"mcpServers": {
"psforge": {
"command": "psforge"
}
}
}如果你是从源码运行，使用项目自带的启动脚本，并把路径替换为你的实际克隆目录：
{
"mcpServers": {
"psforge": {
"command": "C:\\path\\to\\PSForge\\start_psforge.bat"
}
}
}重启 Claude Desktop，测试：获取 Photoshop 会话信息
参考示例文件：codex_config.example.toml
编辑 Codex 配置文件：
%USERPROFILE%\.codex\config.toml
如果你已通过 pip install psforge 安装：
[mcp_servers.psforge]
command = 'psforge'
startup_timeout_sec = 120如果你是从源码运行，推荐使用项目自带的启动脚本，并把路径替换为你的实际克隆目录：
[mcp_servers.psforge]
command = 'C:\path\to\PSForge\start_psforge.bat'
startup_timeout_sec = 120保存后重启 Codex，测试：使用 PSForge 获取 Photoshop 会话信息。
配置 MCP 并重启客户端后，直接在对话中明确要求使用 PSForge：
使用 PSForge 获取 Photoshop 会话信息用 PSForge 把这张图片复刻成分层 PSD调用 PSForge 的 recreate_image_as_layered_psd，把这张海报生成 PSD 和预览图调用 PSForge execute_script 创建一个 Photoshop 文档使用 PSForge 批量处理 D:\photos 下的 PNG 图片
PSForge 会向 AI Agent 暴露 execute_script、execute_batch、get_session_info、get_layers、capture_canvas、recreate_image_as_layered_psd 等 MCP 工具。Agent 可以直接调用这些工具控制 Photoshop，不需要屏幕识别、鼠标模拟或 Computer Use。
如果 Agent 没有自动选择 PSForge，可以在提示词里加一句：
请使用 PSForge MCP，不要使用屏幕识别或 Computer Use。
相比基于屏幕的自动化，PSForge 通过 ExtendScript/COM 直接控制 Photoshop，几乎不消耗视觉识别 token，更快、更稳定，也更适合生成可编辑 PSD 和批量自动化。
AI 客户端 (Claude / Cursor)
│ MCP 协议 (stdio)
▼
MCP Server (FastMCP) ← server.py + registry.py
│ 工具 & 提示词调用
▼
核心工具 & 提示词 ← tools/ 和 prompts/
│ PS 操作
▼
PS 适配层 ← ps_adapter/（单例、重试、上下文）
│ Windows COM / ExtendScript
▼
Adobe Photoshop
你：创建一张 1080x1350 的 synthwave 风格海报，渐变背景、
条纹太阳、透视网格、标题 "RETROWAVE"
Claude 生成一段 ExtendScript：
1. 创建文档
2. 绘制多色标渐变背景
3. 用选区循环创建条纹太阳
4. 用数学绘制透视网格
5. 添加带外发光的标题文字
→ 一次 execute_script 调用完成
你：打开这张照片，调成电影感
Claude：
1. execute_script → 打开文件，应用曲线 + 调色
2. capture_canvas → 截图回传给 AI
3. AI 判断："暗部太深，高光需要暖色"
4. execute_script → 调整曲线，加暖色滤镜
5. capture_canvas → 确认最终效果
你：给 D:\photos 下所有 PNG 加水印
Claude：
1. execute_batch → [打开文件1 + 加水印 + 保存, 打开文件2 + ...]
单次 COM 往返完成
在 psforge/tools/ 目录下新建 Python 文件，启动时自动注册：
from psforge.decorators import debug_tool, log_tool_call
from psforge.ps_adapter import PhotoshopApp
from psforge.registry import register_tool
def register(mcp):
registered_tools = []
@debug_tool
@log_tool_call
def my_tool(param: str) -> dict:
"""工具描述。"""
ps_app = PhotoshopApp()
result = ps_app.execute_javascript(f'/* 你的脚本 */')
return {"success": True, "result": str(result)}
registered_tools.append(register_tool(mcp, my_tool, "my_tool"))
return registered_tools
## 添加自定义提示词 (Prompts)
在 `psforge/prompts/` 目录下新建 Python 文件，启动时自动注册：
```python
from psforge.registry import register_prompt
def register(mcp):
def my_prompt() -> str:
"""提示词描述。"""
return "在此处填写你的提示词模板内容。"
register_prompt(mcp, my_prompt, name="my-custom-prompt")
return ["my-custom-prompt"]
## 常见问题
**"无法连接 Photoshop"** — 确保 PS 正在运行。检查 首选项 → 常规 → 启用远程连接。查看 `psforge_debug.log` 了解详情。
**"操作超时"** — 检查 PS 是否有弹窗。PSForge 会自动禁用对话框，但某些操作仍可能阻塞。
**Claude 中看不到工具** — 检查 `claude_desktop_config.json` 路径是否正确。重启 Claude Desktop。查看日志：`%APPDATA%\Claude\logs\`
## 版本历史
### v0.4.0
新增 MCP Prompts（提示词模板）机制。引入 `ps-image-analyzer` 提示词模板，供 AI 客户端自动进行设计图像分析与 Photoshop 重建。支持在 `psforge/prompts/` 目录下动态扫描与自动注册自定义 Prompt。
### v0.4.x
新增 `recreate_image_as_layered_psd`，用于低 token 的图片到分层 PSD 工作流。工具会创建隐藏参考层、分离的构建图层、可编辑文字层，并导出 PNG 预览。
### v0.3.0
从 61 个工具精简为 5 个核心工具。新增 `capture_canvas` 支持 AI 视觉反馈。AI 直接生成 ExtendScript，不再需要包壳工具。
### v0.2.0
性能优化：移除自动上下文查询，修复重试嵌套。新增 `execute_batch` 和 `select_layer_by_name`。61 个工具 / 15 个模块。
### v0.1.0
首次发布。59 个工具，四层架构。
## 许可证
MIT License - 详见 [LICENSE](LICENSE)
**基于 [photoshop-python-api](https://github.com/loonghao/photoshop-python-api) 和 [MCP](https://modelcontextprotocol.io/) 构建**