photoshop-psjslisted
Install: claude install-skill younglark/photoshop-skills
# 用 UXP 脚本 (.psjs) 驱动 Photoshop
面向 agent 的可执行配方:在 Photoshop 里创建、修改、导出文档。事实分两类:
- **官方**:来自 Adobe UXP 文档,文末有链接。
- **实测**:在 Windows 和 macOS、Adobe Photoshop 2026 上用 `.psjs` 跑通的经验。未核实的标为 **未核实**,不要当成官方 API。
**成功标准:** 脚本写完结果 JSON(含 `done` / `ok` / `fatal` / `errs`);只改动任务指定的目标文档,其他打开的文档不受影响;需要像素对齐时,导出 PNG 并与金图做 ΔE / 像素差后迭代。
**先停下来:** 任务没说清要改哪个文档,或者要覆盖保存一个有用户未保��改动的文档,而任务没明确允许。
---
## 1. 何时用 / 何时不用
**用 `.psjs` 当:**
- 需要 Photoshop 才能做的事:渲染带图层样式的像素、按图层导出切片、用 batchPlay 建形状/文字/效果、把结果存成 PSD/PNG。
- 从 PSD/PSB 推断切图清单、审核后导出 1x PNG 和引擎无关的布局 JSON:见第 9 节。
- agent 要一次性跑完任务(写脚本 → 启动 → 轮询日志 → 拷回产物),不需要常驻面板。
**不要启动 Photoshop 当:**
- 只读图层树、名称、id、文本、大致 bounds:用 `psd-tools` 或 `ag-psd` 离线解析即可。实测:`psd-tools` 的 `layer_id` 与 UXP `layer.id` 一致,可用离线结构定位,只把渲染/导出交给 PS。注意 psd-tools 的 bbox **不含**图层效果,最终视觉 bounds 仍要在 PS 里算。
**改用 UXP 插件当:**
- 需要长驻、双向通道(例如 MCP 桥、面板、WebSocket)。官方:脚本 **没有** manifest / 面板;**Network、LaunchProcess、WebView、IPC 均不可用**。这些能力要做插件并在 manifest 里声明权限。
- 官方:不能从插件里调用另一个 `.psjs`;但脚本里的 UXP 代码一般可以搬进插件运行。
**改用 ExtendScript / JSX 当:**
- 目标是 Photoshop 23.5 以下,或只能走 Windows COM `DoJavaScript` / macOS AppleScript `do javascript` / CEP `evalScript`。JSX 是 ES3、同步 API,维护模式。不要把 `psx.jsx`(xbytor 的 ExtendScript 助手库)当成一种运行时。
---
## 2. 官方要点(先记住这些)
- 独立 UXP 脚本从 **Photoshop 23.5** 起可用,扩展名 `.psjs`。调试可用 UXP Developer Tool ≥ 1.6,但运行脚本不要求 UDT。
- 官方启动方式:`File > Scripts > Browse...`;把 `.psjs` 拖到 Dock 图标(Mac)或 Photoshop 窗口里非打开文档的区域(Mac / Win);用 Action 播放脚本。双击打开曾标注为 “Coming soon”。
- 脚本是现代 JS,支持 **顶层 `await`*