ops 参考
ops 是一个有序数组 ，每条形如 { "op": "setLayerProps", "index": 3, … }。两类 op 可以任意混排：
core op （core/psd-edit*.js）—— 纯格式知识：图层属性 / 文字 / 像素 / 蒙版 / 矢量 / 图层样式 / 调整与填充图层 / 智能对象 / 画板 / 锁定 / 图像资源。定位用 index（/api/doc/inspect 的 flat[].index，底 = 0）。服务端 op （server/server-ops.js + server/edit-ops.js）—— 需要渲染内核或重采样的：滤镜、调整、内容识别、画布 / 裁剪 / 图像大小 / 旋转 / 翻转、移动 / 复制图层、新建变形 / 画板、智能滤镜；以及换智能对象源图、变形写回。新扩展的这批用 index（或 target 写图层名）定位；老的 replaceSmartObject / deform / setSmartObjectDescriptor 用 target。
混排时的 index 口径： 每条 op 都作用在「前面所有 op 执行完之后」的文件上。会改图层表的 op（
deleteLayer /
reorderLayers /
createLayer /
duplicateLayer /
groupLayers /
createArtboard / 普通层上的
createDeform…，下表标「改图层表」的）之后，后续 op 的
index 以新的图层表为准。拿不准就先跑一次
/api/doc/edit/plan：含服务端扩展 op 时它会在内存里真跑一遍，判定与真实执行完全一致。
扩展 op 里 number 型 target 指图层下标： 新扩展的服务端 op（applyFilter、moveLayer 等）的 target: 3 与 index: 3 同义；只有老三条（replaceSmartObject / deform / setSmartObjectDescriptor）和 setSmartFilters 的数字 target 仍按「第几个智能对象」算，与 /api/render 保持一致。
全部 op 一览
共 78 条（core 58 · server 20）。机器可读版：GET /api/catalog
选区写法（selection）
像素类扩展 op（applyFilter / applyAdjustment / contentAwareFill / fillPixels / clearPixels）都接受同一种选区描述，坐标一律是文档像素 ：
写法 含义 {"type":"rect","x":10,"y":10,"width":200,"height":100}矩形；可加 feather（羽化半径，像素）与 antiAlias:false {"type":"ellipse","x":0,"y":0,"width":300,"height":300,"feather":8}椭圆 {"type":"polygon","points":[[0,0],[100,20],[40,90]]}多边形（套索） {"type":"all"}全选 [ 形状1, { …形状2, "mode":"subtract" } ]多个形状组合，第二个起按各自 mode（add 默认 / subtract / intersect / xor） {"shapes":[…],"invert":true}组合后反选
省略 selection = 作用于整层。结果按选区覆盖率混回（羽化边缘是渐变的），与编辑器里「先做选区再执行」同一口径。
示例：只把画面下三分之一做动感模糊，再在右上角去掉一块水印 复制
[
{ "op": "applyFilter", "index": 0, "filter": "motionBlur", "params": { "angle": 0, "distance": 30 },
"selection": { "type": "rect", "x": 0, "y": 800, "width": 1200, "height": 400, "feather": 20 } },
{ "op": "contentAwareFill", "index": 0,
"selection": { "type": "rect", "x": 1020, "y": 30, "width": 150, "height": 60 } }
]
op 来自 定位 做什么 setLayerPropscore index改图层名 / 可见 / 不透明度 / 剪贴 / 混合模式 renameLayercore indexsetLayerProps 的别名，只带 namesetVisiblecore index别名，只带 visible setOpacitycore index别名，只带 opacity setBlendModecore index别名，只带 blendKey setClippingcore index别名，只带 clipping setTextcore index改文字层内容（可换字体） deleteLayercore index删图层 / 删分组 reorderLayerscore order重排，顺带批量删除 replaceLayerPixelscore index换整层像素 setImageResourcecore id写入 / 替换图像资源块 removeImageResourcecore id删除图像资源块 replaceSmartObjectserver target换智能对象源图（别名 replaceSmartObjectImage） deformserver target网格 / 变形写回（别名 setMesh）
服务端 op 的 target 怎么写
写法 含义 省略 / null 第 0 个智能对象。文件里没有智能对象时 400 0 或 "0"智能对象序号 （与 /api/render 的 target 一致）"img"图层名（unicodeName 优先）。必须唯一 ，重名会 400 并告诉你重在第几层；图层树里找不到时，会再在智能对象名单里按放置块里的名字找一次 {"layerIndex":1}文档图层下标（/api/doc/inspect 口径） {"smartObjectIndex":0}智能对象序号（别名 smartObject / soIndex） {"name":"img"}同字符串写法
解析结果里两个下标同时给出（layerIndex + smartObjectIndex），互相打通用的是「名字 + 包围盒」打分；名字对不上就不认，避免张冠李戴。
core op 逐个说明
setLayerProps（及五个别名）
字段 类型 约束 indexinteger 必填，越界 400 namestring 非空、≤255 字符。同时写 luni 与 Pascal 名 unicodeNamestring 非空。只写 luni（PS 显示的就是它） visibleboolean — opacityinteger 0…255（255 = 不透明） clippingboolean | 0 | 1 — blendKeystring 恰好 4 个字符且在白名单里
至少给一个可改字段，否则 400。附加区被降级成原样字节（extraRaw）的图层不允许改名 —— 改了会被静默丢掉，所以直接拒绝。用 name 写非 ASCII 名字时，Pascal 名那份会按 ? 落地并给一条 warning，这是正常的（PS 读 luni）。
混合模式键（白名单）
键 模式 键 模式 键 模式 键 模式 pass穿透（仅图层组） norm正常 diss溶解 dark变暗 mul 正片叠底 idiv颜色加深 lbrn线性加深 dkCl深色 lite变亮 scrn滤色 div 颜色减淡 lddg线性减淡 lgCl浅色 over叠加 sLit柔光 hLit强光 vLit亮光 lLit线性光 pLit点光 hMix实色混合 diff差值 smud排除 fsub减去 fdiv划分 hue 色相 sat 饱和度 colr颜色 lum 明度
不足 4 字符的键要补空格 ："mul "、"div "、"hue "、"sat "、"lum "。写进白名单以外的键，Photoshop 会当文件损坏，所以这里直接 400。
示例 复制
[
{ "op": "setLayerProps", "index": 1, "name": "新图案", "opacity": 200, "blendKey": "mul " },
{ "op": "renameLayer", "index": 2, "name": "新标题" },
{ "op": "setVisible", "index": 0, "visible": false },
{ "op": "setClipping", "index": 2, "clipping": true }
]
setText
字段 类型 说明 indexinteger 必须是文字图层（有 TySh 块），否则 400 textstring 必填 opts.fontstring 换字体。走 setEngineFont，会同时改 EngineData 里的两份 FontSet 副本 （ResourceDict 与 DocumentResources）—— 只改一份 PS 双击内嵌文档会崩 opts.keepTxt2boolean 保留全局 Txt2。默认删掉 它
为什么要删 Txt2： PS CC 2015+ 优先读全局 Txt2（里面是旧文字与旧字形），留着它 PS 就会继续显示旧文字。删掉之后 PS 打开会提示「某些文本图层可能需要更新…」，点「更新」即可 —— 这是预期行为 。若显式 keepTxt2:true 且 Txt2 仍在，服务端会给一条 warning；非 keepTxt2 的情况下 Txt2 没删掉，会直接报错、不出文件。
结果里额外带 textChanged、txt2Removed、textBefore、textAfter。两份 FontSet 对不上时会给 warning（条目数或字体名不同）。
示例 复制
[ { "op": "setText", "index": 2, "text": "限时 8 折",
"opts": { "font": "SourceHanSansSC-Bold" } } ]
deleteLayer
字段 类型 说明 indexinteger 必填 keepChildrenboolean 删分组时只拆外壳、保留子图层
删分组默认连内容一起删（分组头 + 内容 + 分隔层整段）。会删光全部图层时直接 400。16/32 位文档的图层记录在 Lr16/Lr32 全局块里，暂不支持结构性增删改（改名 / 属性 / 文字仍可用）。
reorderLayers
字段 类型 说明 orderinteger[] 原始图层 index 的新顺序（底 = 0）。省略某个 index 就等于删除它
校验：不能越界、不能重复、不能为空、分组边界必须自洽。删掉文字图层但全局 Txt2 还在时会给 warning（建议同一批里再跑一次 setText）。
示例：把第 2 层挪到底，并删掉第 0 层 复制
[ { "op": "reorderLayers", "order": [2, 1] } ]
replaceLayerPixels
字段 类型 说明 indexinteger 必填 image引用 上传的图片（见图片引用写法 ）。服务端用 sharp 解成 RGBA rgbaobject 直接给 { data, width, height }，data 长度必须等于 width*height*4 boundsobject 可选。四个整数，尺寸必须与图片一致。省略时以原图层左上角为锚点 mergedobject 可选。整幅新合成图 RGBA（长度必须等于画布 W*H*4）。不传就保留原合成图 ，只改这一层
只支持 8 位 / 16 位文档。解出来不是 4 通道、或像素数超过 FULLPSD_DOC_MAX_PIXELS 会 400 / 413。结果里带 compositeUpdated 说明合成图有没有跟着重建。
示例 复制
[ { "op": "replaceLayerPixels", "index": 0,
"image": { "file": "image", "index": 0 } } ]
setImageResource / removeImageResource
字段 类型 说明 idinteger 0…65535。常见：1005 分辨率、1036 缩略图、1060 XMP datastring | number[] 仅 setImageResource：base64 字符串（接受 data: 前缀）或字节数组
资源已存在就替换、不存在就新增。删除不存在的资源不算错误，changed 为 false。
服务端 op 逐个说明
replaceSmartObject（别名 replaceSmartObjectImage）
字段 类型 说明 target见上 必须解析到智能对象，否则 400 image引用 必填 ，见图片引用写法fitobject 覆盖模式，默认 {"mode":"cover"}。字段同 /api/render meshobject 顺带改网格：{points,xn,yn,sliceX,sliceY} 或 {splits:{u,v}}。变形滤镜层不接受 sourceName / filenamestring 写进 PSD 的内嵌源图文件名；不给就用上传文件名
与 /api/render 逐字节相同： 这个 op 复用的是 pipeline.js 抽出来的同一段 preparePsdRender + writePsdOutput，所以同参数下产物与 /api/render（output.format=psd）逐字节一致 —— 这是结构性保证，不是巧合，server/test-edit-api.js 里有逐字节断言。
结果 meta：target、warpWritten、sourceReplaced、filterCacheUpdated、deformKind、bytes。三个「是否成功」字段可能是 true / null（不适用）/ 失败说明字符串 —— 服务端如实上报 而不是假装成功。
deform（别名 setMesh）
字段 类型 说明 target见上 必须解析到智能对象 points + xn/yn + sliceX/sliceY— Bezier 网格写回 deformobject 变形滤镜写回，见变形能力
内部先把文件切成 fragment，走与 /api/so/writeback 完全相同 的那段代码，再 replacePlacedBlocks 拼回 —— 与「片段模式 + 客户端拼回」的产物逐字节相同。结果 meta：target、mode、blocks[].bytes、bytesDelta。
示例：换图 + 拆一条经线 复制
[
{ "op": "replaceSmartObject", "target": { "smartObjectIndex": 0 },
"image": { "file": "image", "index": 0 },
"fit": { "mode": "contain", "alignY": 0, "scale": 0.9 },
"mesh": { "splits": { "u": [0.5] } },
"sourceName": "design-v2.png" }
]
服务端扩展 op 逐个说明
下面这批与编辑器的菜单命令一一对应，算法用的是编辑器同一份内核（滤镜注册表、调整、内容识别、选区、合成、变形），所以同参数下服务端结果与编辑器画布一致。产物同样过守门；改了像素 / 几何的，收尾时默认按图层重建合成图快照（见 output.recomposite）。
applyFilter 像素 对普通像素图层应用滤镜（75 种：模糊 / 锐化 / 杂色 / 扭曲 / 风格化 / 像素化 / 渲染 / 其它 / 自动调整…）
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } filterstring 是 滤镜名（GET /api/catalog 的 filters[].kind，如 gaussianBlur / unsharpMask / motionBlur / mosaic） paramsobject — 滤镜参数；缺省项用默认值；不认识的键会 400 selectionobject|array — 选区（文档坐标）：{ type:"rect"|"ellipse", x, y, width, height, feather? } | { type:"polygon", points:[[x,y],…] } | { type:"all" }；数组 = 多个形状按各自 mode（add/subtract/intersect/xor）组合；{ shapes:[…], invert:true } = 反选。省略 = 整层 fadenumber — 渐隐 0…100（PS 的「编辑 › 渐隐」不透明度），默认 100 foregroundstring|array — 前景色（云彩 / 纤维等用到前景背景色的滤镜） backgroundstring|array — 背景色 expandboolean|integer — 空间类滤镜自动往外补边（默认按半径 ×3）；false = 不补，整数 = 指定像素
只作用于 raster 图层；文字 / 智能对象 / 形状先 rasterizeLayer。智能滤镜（非破坏）暂未开放。
示例 复制
[
{
"op": "applyFilter",
"index": 1,
"filter": "gaussianBlur",
"params": {
"radius": 4
}
}
]
applyAdjustment 像素 破坏性图像调整（直接改像素）：曲线 / 色阶 / 色相饱和度 / 亮度对比度 / 黑白 / 色彩平衡 / 渐变映射…
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } adjustmentobject 是 { type, …参数 }；type 见 GET /api/catalog 的 adjustments（curves / levels / hueSaturation / brightnessContrast / …） selectionobject|array — 选区（文档坐标）：{ type:"rect"|"ellipse", x, y, width, height, feather? } | { type:"polygon", points:[[x,y],…] } | { type:"all" }；数组 = 多个形状按各自 mode（add/subtract/intersect/xor）组合；{ shapes:[…], invert:true } = 反选。省略 = 整层 fadenumber — 渐隐 0…100
要非破坏的调整图层请用 core op addAdjustmentLayer。
示例 复制
[
{
"op": "applyAdjustment",
"index": 1,
"adjustment": {
"type": "brightnessContrast",
"brightness": 20,
"contrast": 10
}
}
]
contentAwareFill 像素 内容识别填充：用图层其余像素补掉选区（去水印 / 去杂物）
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } selectionobject|array 是 要填掉的区域（必填） patchinteger — 补丁半径 1…6，默认 3 samplesinteger — 每像素候选样本数，默认 120 seedinteger — 随机种子（同种子结果可复现），默认 1
示例 复制
[
{
"op": "contentAwareFill",
"index": 0,
"selection": {
"type": "rect",
"x": 100,
"y": 100,
"width": 60,
"height": 40
}
}
]
fillPixels 像素 用纯色填充选区（PS 的「编辑 › 填充」）；空图层也能填（按选区长出像素）
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } colorstring|array 是 "#rrggbb" 或 [r,g,b] selectionobject|array — 选区（文档坐标）：{ type:"rect"|"ellipse", x, y, width, height, feather? } | { type:"polygon", points:[[x,y],…] } | { type:"all" }；数组 = 多个形状按各自 mode（add/subtract/intersect/xor）组合；{ shapes:[…], invert:true } = 反选。省略 = 整层 opacitynumber — 0…100，默认 100 preserveTransparencyboolean — 保留透明区域（只染已有像素）
示例 复制
[
{
"op": "fillPixels",
"index": 1,
"color": "#ff3366",
"selection": {
"type": "ellipse",
"x": 50,
"y": 50,
"width": 200,
"height": 120
}
}
]
clearPixels 像素 清除选区里的像素（PS 的 Delete）
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } selectionobject|array 是 要清除的区域（必填）
示例 复制
[
{
"op": "clearPixels",
"index": 1,
"selection": {
"type": "rect",
"x": 0,
"y": 0,
"width": 100,
"height": 100
}
}
]
moveLayer 几何 平移图层（组 = 带上整组）；文字仍可编辑、智能对象仍是智能对象、矢量路径与蒙版跟着走
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } indicesinteger[] — 一次平移多个图层 / 组 dxinteger 是 水平位移（像素，右为正） dyinteger 是 垂直位移（像素，下为正）
示例 复制
[
{
"op": "moveLayer",
"index": 1,
"dx": 40,
"dy": -20
}
]
duplicateLayer 结构 改图层表 复制图层 / 组 / 画板（字节级克隆，放在源正上方；智能对象为浅拷贝，与 PS 默认一致）
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } namestring — 副本名，默认「原名 拷贝」 dxinteger — 副本平移（像素） dyinteger — 副本平移
给组头 index = 连同全部成员整段复制。复制画板且没给 dx/dy 时，副本放到原画板右侧 100 像素处，画布不够自动撑大。副本整段插在源（组）正上方，其上所有图层下标相应后移。
示例 复制
[
{
"op": "duplicateLayer",
"index": 1,
"dx": 30,
"dy": 30
}
]
resizeCanvas 文档 画布大小（只挪位置、不重采样）；背景图层扩出来的部分用 extColor 填
字段 类型 必填 说明 widthinteger 是 新宽（像素，1…30000） heightinteger 是 新高 anchorstring|integer — 定位：top-left / top / top-right / left / center / right / bottom-left / bottom / bottom-right（或 0…8），默认 center extColorstring|array — 画布扩展颜色（背景图层用），默认白
示例 复制
[
{
"op": "resizeCanvas",
"width": 1600,
"height": 1200,
"anchor": "center"
}
]
crop 文档 裁剪到矩形（画布 = 该矩形，图层整体平移）
字段 类型 必填 说明 xinteger 是 裁剪框左 yinteger 是 裁剪框上 widthinteger 是 宽 heightinteger 是 高 deleteCroppedboolean — true = 普通像素层裁掉画布外的像素（PS 的「删除裁剪的像素」）；默认 false 保留
示例 复制
[
{
"op": "crop",
"x": 100,
"y": 80,
"width": 800,
"height": 600
}
]
resizeImage 文档 图像大小：整份文档重采样（像素层 lanczos3；文字改变换矩阵仍可编辑；智能对象改放置四点）
字段 类型 必填 说明 widthinteger — 新宽；只给一边 = 等比 heightinteger — 新高 scalenumber — 整体倍率（与 width/height 二选一） resolutionnumber — 新分辨率（像素/英寸），写入资源 1005 resamplestring — 重采样：lanczos3（默认）/ bicubic / bilinear / nearest可选：lanczos3 bicubic bilinear nearest scaleStylesboolean — PS 的「缩放样式」：图层样式里的像素尺寸、图案缩放、矢量描边宽度按比例缩放（默认 true）默认 true
非等比缩放时样式按面积比例的平方根缩放（与 PS 同口径）；实时形状的尺寸与圆角、切片矩形同步更新。
示例 复制
[
{
"op": "resizeImage",
"width": 800
}
]
rotateCanvas 文档 旋转画布（任意角度，顺时针；新画布 = 外接矩形，90° 倍数无损）
字段 类型 必填 说明 anglenumber 是 角度（度，顺时针） extColorstring|array — 背景图层露出部分的颜色，默认白
示例 复制
[
{
"op": "rotateCanvas",
"angle": 90
}
]
flipCanvas 文档 水平 / 垂直翻转画布
字段 类型 必填 说明 axisstring 是 horizontal / vertical可选：horizontal vertical
示例 复制
[
{
"op": "flipCanvas",
"axis": "horizontal"
}
]
新建透视变形 / 操控变形（PS 的「编辑 › 透视变形 / 操控变形」）；普通图层自动转智能对象，已有变形 = 再叠一条
档位： 需 deform.perspective / deform.puppet（按 kind：perspectiveWarp → deform.perspective，puppetWarp → deform.puppet），见 档位与权限 。
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } kindstring 是 perspectiveWarp（透视）/ puppetWarp（操控）可选：perspectiveWarp puppetWarp gridobject — 透视：{ cols, rows } 面的行列数 1…16，默认 1×1 cornersarray — 透视：把放置四角拉到这 4 点 [[x,y]×4]（左上 / 右上 / 右下 / 左下，文档坐标） pinsarray — 操控：[{ from:[x,y], to?:[x,y], rotate?:度 }]，from 吸附到最近的网格顶点 modestring — 操控：rigid（刚性，默认）/ similarity（正常）/ affine（扭曲）可选：rigid similarity affine cellinteger — 操控：网格间距（源图像素，越小越密） expandinteger — 操控：网格外扩格数 0…8，默认 1
写完放置块后会按新变形重渲染缓存栅格；之后可用 deform op（target 同一层）继续改顶点。
示例 复制
[
{
"op": "createDeform",
"index": 1,
"kind": "perspectiveWarp",
"corners": [
[
100,
100
],
[
500,
130
],
[
480,
420
],
[
120,
400
]
]
}
]
addSmartFilter 智能对象 改图层表 新增一条智能滤镜（非破坏，PS 里可双击改参数 / 关眼睛）；普通层自动转智能对象，已有智能滤镜 = 追加
字段 类型 必填 说明 indexinteger — 图层下标（/api/doc/inspect 的 flat[].index，底 = 0）；与 target 二选一 targetinteger|string|object — 图层名（须唯一）/ 下标 / { layerIndex } / { name } filterstring 是 滤镜名可选：gaussianBlur boxBlur blur blurMore motionBlur radialBlur unsharpMask sharpen sharpenMore sharpenEdges addNoise median despeckle dustScratches highPass mosaic findEdges solarize emboss maximum minimum twirl pinch spherize cameraRaw lensCorrection paramsobject — 参数，与 applyFilter 同名同范围（见 get_catalog section=filters） opacitynumber — 滤镜混合选项的不透明度 0…100，默认 100 modestring — 滤镜混合模式，默认 normal（预览只精确支持 normal） enabledboolean — false = 挂上但先关着
写完描述符后按「变形栈 → 全部智能滤镜」重渲染缓存栅格；栈里有服务端不认识的滤镜时只在现有缓存上叠加这一条。cameraRaw / lensCorrection 是 FullPsd 私有条目（PS 里只显示缓存像素、不能在 PS 里再调）；液化智能滤镜只能在编辑器里画。
示例 复制
[
{
"op": "addSmartFilter",
"index": 1,
"filter": "gaussianBlur",
"params": {
"radius": 6
},
"opacity": 80
}
]
setSmartFilters 智能对象 改智能对象上已有的智能滤镜（开关 / 参数 / 混合选项 / 删除 / 换序）；变形滤镜请用 deform
字段 类型 必填 说明 targetinteger|string|object — 智能对象序号 / 图层名 / { layerIndex }（number = 智能对象序号，与老 op 一致） indexinteger — 图层下标（与 target 二选一） editsobject 是 { style?:{ enabled?, filterMaskEnable?, … }, filters?:[{ index, enabled?, blendOptions?:{ opacity?, mode? }, values?:{ "参数路径": 值 }, remove? }], order?:[原下标…] }；可先用 POST /api/so/filters 或 MCP 的 get_smart_filters 看现有列表
改完按新描述符重渲染缓存栅格（栈里全是服务端认识的滤镜时）；新增请用 addSmartFilter。
示例 复制
[
{
"op": "setSmartFilters",
"target": 0,
"edits": {
"filters": [
{
"index": 0,
"enabled": false
}
]
}
}
]
renderText 文字 按服务端字体重排重绘文字层栅格（setText / 改样式后会自动重绘，这条用于强制重绘，如新装了字体）
字段 类型 必填 说明 indicesinteger[] — 要重绘的文字层；省略 = 全部文字层 indexinteger — 单个文字层
字体按 PostScript 名在服务端字体目录里找（server/fonts/、FULLPSD_FONT_DIRS、系统字体目录），缺字体用替代字体并给 warning；PS 打开时仍按它自己的字体重排。
示例 复制
[
{
"op": "renderText",
"indices": [
2
]
}
]
createArtboard 画板 改图层表 新建画板：给 indices 就把这些图层装进去（来自图层的画板），否则新建空画板放最上面
字段 类型 必填 说明 namestring — 画板名，默认「画板 N」 rectobject — { x, y, width, height } 或 { left, top, right, bottom }；给了 indices 时可省略（= 图层外接框） indicesinteger[] — 要装进画板的图层 / 组 backgroundTypeinteger|string — 1 白 / 2 黑 / 3 透明 / 4 自定（white / black / transparent / custom）默认 1 colorstring|array — backgroundType=4 时的底色 presetNamestring — 画板预设名 autoSizeCanvasboolean — 画板超出画布时撑大画布（默认 true）
示例 复制
[
{
"op": "createArtboard",
"name": "手机",
"rect": {
"x": 0,
"y": 0,
"width": 1125,
"height": 2436
},
"backgroundType": "white"
}
]
全部 op 参数表（自动生成）
由 tools/gen-api-docs.js 从运行时注册表生成（与 GET /api/catalog 同源），示例都在真实文件上跑通过。上面手写的几条讲了背景与坑，这里是字段级的全集。
addFrameLayer — 新建 Photoshop 原生画框组（矩形或椭圆）
字段 类型 必填 说明 atinteger — 插入位置，默认图层栈顶部；创建分隔记录和组头两条记录 namestring — 图框名称，默认自动编号 rectobject 是 {x,y,w,h} 文档像素；坐标可负，宽高必须为正有限数 shapestring — 矩形或椭圆，默认rect可选：rect ellipse
仅验证RGB/8新建。返回index/headerIndex和dividerIndex。内容需作为组内子图层，clipping=0。
示例 复制
[
{
"op": "addFrameLayer",
"name": "原生图框",
"rect": {
"x": 20,
"y": 30,
"w": 200,
"h": 150
},
"shape": "rect"
}
]
setFrameRect — 修改已有原生画框边界并同步矢量路径
字段 类型 必填 说明 indexinteger 是 具有frgb的画框组头下标 rectobject 是 {x,y,w,h} 文档像素；同步frgb/vsms/vogk并移除过期派生蒙版缓存
只调整图框边界，不缩放或移动组内内容。自定路径按当前矩形比例变换。
示例前置（让示例能跑通的准备步骤）：[{"op":"addFrameLayer","at":6,"name":"原生图框","rect":{"x":20,"y":30,"w":200,"h":150}}]
示例 复制
[
{
"op": "setFrameRect",
"index": 7,
"rect": {
"x": 25,
"y": 35,
"w": 240,
"h": 180
}
}
]
setLayerProps — 改图层名 / 可见性 / 不透明度 / 剪贴 / 混合模式（可一次改多项）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） namestring — 新图层名，非空、≤255 字符；同时写 luni（真名）与 Pascal 名（非 ASCII 落地为 ?） unicodeNamestring — 只改 luni 里的 Unicode 名（非空），不动 Pascal 名 visibleboolean — 是否可见 opacityinteger — 不透明度 0…255（255 = 不透明） clippingboolean|integer — 剪贴蒙版：布尔值或 0/1 blendKeystring — 图层混合模式 4 字符键（不足补空格，如 'mul '）可选：pass norm diss dark mul idiv lbrn dkCl lite scrn div lddg lgCl over sLit hLit vLit lLit pLit hMix diff smud fsub fdiv hue sat colr lum
name/unicodeName/visible/opacity/clipping/blendKey 至少给一个；附加区解析已降级（extraRaw）的图层拒绝改名。
示例 复制
[
{
"op": "setLayerProps",
"index": 1,
"name": "标题",
"opacity": 200,
"blendKey": "mul "
}
]
renameLayer — setLayerProps 的别名
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） namestring 是 新图层名，非空、≤255 字符
示例 复制
[
{
"op": "renameLayer",
"index": 1,
"name": "主标题"
}
]
setVisible — setLayerProps 的别名
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） visibleboolean 是 是否可见
示例 复制
[
{
"op": "setVisible",
"index": 1,
"visible": false
}
]
setOpacity — setLayerProps 的别名
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） opacityinteger 是 不透明度 0…255（255 = 不透明）
示例 复制
[
{
"op": "setOpacity",
"index": 1,
"opacity": 128
}
]
setBlendMode — setLayerProps 的别名
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） blendKeystring 是 图层混合模式 4 字符键（不足补空格，如 'mul '）可选：pass norm diss dark mul idiv lbrn dkCl lite scrn div lddg lgCl over sLit hLit vLit lLit pLit hMix diff smud fsub fdiv hue sat colr lum
示例 复制
[
{
"op": "setBlendMode",
"index": 1,
"blendKey": "scrn"
}
]
setClipping — setLayerProps 的别名
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） clippingboolean|integer 是 剪贴蒙版：布尔值或 0/1
示例 复制
[
{
"op": "setClipping",
"index": 1,
"clipping": true
}
]
setText — 改文字图层的文字内容（可顺带换字体），并删除全局 Txt2
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1），必须是文字图层（带 TySh 块） textstring 是 新文字内容（可为空串） optsobject — 可选：{ font?:PostScript 字体名（同步改两份 FontSet）, keepTxt2?:boolean（保留全局 Txt2，PS 可能仍显示旧字）, orientation?:'horizontal'|'vertical', antiAlias?, bounds? }
默认删全局 Txt2（否则 PS 优先读 Txt2 显示旧文字）；只改内容与 run 长度，不改字号 / 颜色。
示例 复制
[
{
"op": "setText",
"index": 1,
"text": "新的标题文字"
}
]
addTextLayer — 新建一个文字图层（以内置模板 TySh 为骨架，可设字号 / 颜色 / 字体 / 段落框）
字段 类型 必填 说明 textstring 是 文字内容，非空、≤30000 字符 atinteger — 新图层在「底=0」序里的插入下标，0…图层数；默认 = 图层数（最上面） namestring — 图层名，非空、≤255 字符默认 "文字首行（前 60 字）" xnumber — 文字基线原点的文档 x 坐标（段落文字为框左上角）默认 0 ynumber — 文字基线原点的文档 y 坐标默认 0 orientationstring — 排版方向可选：horizontal vertical fontSizenumber — 字号，0 < 值 ≤ 5000 colorstring|array — 文字颜色：'#rrggbb' / '#rgb' / [r,g,b]（0…255） boxarray — 段落文字框 [宽, 高]，正数；给了就是段落文字 fontstring — PostScript 字体名（如 ArialMT），非空 opacityinteger — 不透明度 0…255（255 = 不透明） visibleboolean — 是否可见
新层继承模板的字体与排版默认值；新建时无像素（bounds 全 0），由 PS 按 EngineData 排版；会删除全局 Txt2。传 at2 会被拒绝（位置用 x/y）。
示例 复制
[
{
"op": "addTextLayer",
"text": "你好世界",
"x": 200,
"y": 300,
"fontSize": 48,
"color": "#222222"
}
]
deleteLayer — 删除图层；指向组头或分隔记录时整组删除（或只拆外壳）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） keepChildrenboolean — index 是组头 / 分隔记录时：true = 只删组头+分隔两条记录、成员升一级；false = 整组连根删默认 false
不能删光全部图层；16/32 位文档（Lr16/Lr32）不支持；删掉文字层但保留全局 Txt2 时给 warning。
示例 复制
[
{
"op": "deleteLayer",
"index": 4
}
]
reorderLayers — 按原始 index 数组重排图层；数组里省略的 index 即被删除
字段 类型 必填 说明 orderarray 是 原始图层 index 组成的新顺序（底→顶），元素唯一、在 0…图层数-1 内；非空；省略的 index 表示删除
不能拆散分组：组头与其分隔记录必须同去同留、配对关系不变；16/32 位文档不支持。
示例 复制
[
{
"op": "reorderLayers",
"order": [
3,
4,
5,
0,
1,
2
]
}
]
groupLayers — 把若干图层包进一个新建的组（PS 的 ⌘G，支持不连续多选与组中组）
字段 类型 必填 说明 indicesarray — 要包进组的图层 index 数组（底=0）；选中组头（groupType 1）= 带上整个组；不能选分隔记录 indexinteger — 单个图层（旧口径）；与 indices 二选一 namestring — 图层名，非空、≤255 字符默认 "组"
indices / index 必须给一个；新组插在最顶层成员原来的位置，组头混合模式 pass。只识别 groupType=1（展开）的组头会带整组 —— 折叠组头（groupType=2）会被当成单条记录处理。
示例 复制
[
{
"op": "groupLayers",
"indices": [
1
],
"name": "新组"
}
]
newGroup — 新建一个空组（分隔记录 + 组头两条空记录）
字段 类型 必填 说明 atinteger — 插入下标，0…图层数；默认最上层；分隔落在 at、组头在 at+1 namestring — 图层名，非空、≤255 字符默认 "组 N（N = 现有组头数 + 1）"
示例 复制
[
{
"op": "newGroup",
"at": 6,
"name": "空组"
}
]
createLayer — 新建一个空像素图层（bounds 全 0，像素之后用 replaceLayerPixels 落地）
字段 类型 必填 说明 atinteger — 新图层在「底=0」序里的插入下标，0…图层数；默认 = 图层数（最上面） namestring — 图层名，非空、≤255 字符默认 "图层 N（N = 图层数 + 1）" visibleboolean — 是否可见
示例 复制
[
{
"op": "createLayer",
"name": "新图层"
}
]
replaceLayerPixels — 替换一个图层的像素（RGBA），可选同时更新整幅合成图
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） rgbaobject 是 { data:字节(长度 = width×height×4，非预乘 RGBA), width, height }；HTTP 可省略 rgba、改传 image（上传文件引用 { file:'image', index } / 文件名 / data URL / 裸 base64），服务端用 sharp 解码成 RGBA boundsobject — { top, left, bottom, right } 整数；尺寸必须等于 rgba 的宽高；默认 = 图层原左上角 + rgba 尺寸 mergedobject — { data:字节 } 整幅合成图 RGBA（长度 = 画布宽×高×4）；不给则原样保留旧合成图 optsobject — 透传给 rebuildPsdReplacingLayerPixels 的选项（premultiplied / sourcePatch / filterEffectsPatch / maskOriginDelta 等，一般不用）
只支持 8/16 位文档；不给 merged 时缩略图 / 合成图仍是旧的。
示例 复制
[
{
"op": "replaceLayerPixels",
"index": 1,
"rgba": {
"data": [
255,
0,
0,
255,
0,
255,
0,
255,
0,
0,
255,
255,
255,
255,
255,
128
],
"width": 2,
"height": 2
}
}
]
rasterizeLayer — 栅格化：摘掉决定图层类型的附加块（文字 / 矢量 / 填充 / 智能对象），变成普通像素层
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） keysarray — 只摘这些块（非空数组）；默认全摘可选：TySh vmsk vsms vogk vstk vscg SoCo GdFl PtFl SoLd PlLd
只摘块、不渲染像素 —— 渲染结果要另用 replaceLayerPixels 写；样式 / 锁定 / 名字等块保留；全局 Txt2 不在这里删。
示例 复制
[
{
"op": "rasterizeLayer",
"index": 1
}
]
setImageResource — 新增或替换一条图像资源（8BIM 资源块）
字段 类型 必填 说明 idinteger 是 资源 id，0…65535 dataarray 是 资源数据字节（Uint8Array / number[]）；HTTP 也接受 base64 字符串
示例 复制
[
{
"op": "setImageResource",
"id": 1034,
"data": [
0
]
}
]
removeImageResource — 删除一条图像资源（不存在则不改动）
字段 类型 必填 说明 idinteger 是 资源 id，0…65535
示例 复制
[
{
"op": "removeImageResource",
"id": 1054
}
]
setLayerFlags — 改图层锁定（lspf：锁透明像素 / 锁图像像素 / 锁位置 / 画板嵌套 / 全部锁定）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录 lockTransparencyboolean — 锁定透明像素 lockCompositeboolean — 锁定图像像素 lockPositionboolean — 锁定位置 lockAllboolean — 全部锁定 lockNestingboolean — 防止在画板和画框内外自动嵌套（lspf bit3）
五个字段至少给一个；从不删块（原本没有 lspf 且目标全 0 时不新建）。
示例 复制
[
{
"op": "setLayerFlags",
"index": 1,
"lockPosition": true
}
]
setLayerColorLabel — 改图层面板的颜色标签（lclr）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录 colorinteger|string 是 0…7（0 无 1 红 2 橙 3 黄 4 绿 5 蓝 6 紫 7 灰）或颜色名（另认 grey / 无）可选：none red orange yellow green blue violet gray
示例 复制
[
{
"op": "setLayerColorLabel",
"index": 1,
"color": "red"
}
]
setFillOpacity — 改填充不透明度（iOpa，面板上的「填充」）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录 fillOpacityinteger 是 0…255（255 = 填充 100%）
示例 复制
[
{
"op": "setFillOpacity",
"index": 1,
"fillOpacity": 128
}
]
setLayerKnockout — 改混合选项里的「挖空」（knko）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录 knockoutinteger 是 0 无 / 1 浅 / 2 深可选：0 1 2
示例 复制
[
{
"op": "setLayerKnockout",
"index": 2,
"knockout": 1
}
]
setBlendOptions — 改混合选项的高级混合 / 通道 / 混合颜色带（infx · clbl · tsly · lmgm · vmgm · brst · Blend If）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录 blendInteriorboolean — 将内部效果混合成组（infx，默认 false） blendClippedboolean — 将剪贴图层混合成组（clbl，默认 true） transparencyShapesboolean — 透明形状图层（tsly，默认 true） layerMaskHidesEffectsboolean — 图层蒙版隐藏效果（lmgm，默认 false） vectorMaskHidesEffectsboolean — 矢量蒙版隐藏效果（vmgm，默认 false） channelsobject — { r?, g?, b? } 布尔：false = 该通道不参与混合（brst） blendIfobject — { gray|red|green|blue: { this?: [黑低,黑高,白低,白高], under?: […] } }，0…255 且递增；只做等长覆写，记录里没有该通道的混合范围段会报错
示例 复制
[
{
"op": "setBlendOptions",
"index": 2,
"blendIf": {
"gray": {
"under": [
0,
0,
180,
230
]
}
},
"channels": {
"b": false
}
}
]
setMaskProps — 改图层蒙版的开关位与浓度 / 羽化（像素蒙版与矢量蒙版各一份）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录；改像素蒙版字段时图层必须已有蒙版，改矢量蒙版字段时必须已有矢量蒙版 disabledboolean — 停用蒙版 invertboolean — 混合时反相（PS 已废弃，仍原样读写） relativeboolean — 蒙版位置相对于图层数据 densityinteger — 像素蒙版浓度 0…255（255 = 100%） feathernumber — 像素蒙版羽化 0…1000 像素 vectorDensityinteger — 矢量蒙版浓度 0…255（255 = 100%） vectorFeathernumber — 矢量蒙版羽化 0…1000 像素
七个字段至少给一个。参数段里已有对应项时等长覆写；没有时补写参数段（蒙版段变长，只有矢量蒙版的图层会新建一个空矩形的蒙版段）。没有蒙版 / 没有矢量蒙版在 apply 阶段才报错（planEdits 查不出）。
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerMask","index":1}]
示例 复制
[
{
"op": "setMaskProps",
"index": 1,
"disabled": true
}
]
addLayerMask — 给图层新建用户蒙版（通道 -2），纯色填充或给灰度位图
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录；图层不能已有蒙版 fillstring|integer — 'reveal'（全白 255，默认）/ 'hide'（全黑 0）/ 0…255；与 gray 互斥 grayarray|object — 8 位灰度字节（长度 = bounds 宽×高）或 { data, width, height }；与 fill 互斥；JSON 请传 number[]（不解 base64） boundsobject — { top, left, bottom, right } 整数，宽高 > 0；默认 = 图层包围盒（空图层必须显式给） defaultColorinteger — 蒙版矩形之外的取值 0…255；默认 = fill 值（给 gray 时默认 0） disabledboolean — 新建即停用 invertboolean — 反相位
示例 复制
[
{
"op": "addLayerMask",
"index": 1,
"fill": "reveal"
}
]
deleteLayerMask — 删除图层蒙版（蒙版段 + 通道同删）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录 whichstring — user = 用户蒙版 -2 / real = real 用户蒙版 -3 / all = 两个都删可选：user real all 默认 "user"
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerMask","index":1}]
示例 复制
[
{
"op": "deleteLayerMask",
"index": 1
}
]
applyLayerMask — 应用蒙版：灰度乘进 alpha 后删除蒙版（停用的蒙版直接删、像素不变）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录 whichstring — 用哪个蒙版；不给则优先 -2、没有再用 -3可选：user real
只支持 8/16 位；蒙版带非默认浓度 / 羽化时拒绝；不重编合成图（给 warning）。
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerMask","index":1,"fill":128}]
示例 复制
[
{
"op": "applyLayerMask",
"index": 1
}
]
setLayerMaskPixels — 改现有蒙版的像素（整张 / 局部矩形 / 连同 bounds），画笔的落地出口
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录；图层必须已有对应蒙版 grayarray|object 是 灰度样本（Uint8Array / Uint16Array / number[]）或 { data, width, height }；长度 = 目标区域面积；JSON 请传 number[] whichstring — user（-2）/ real（-3）可选：user real 默认 "user" xinteger — 局部矩形左上角 x（相对蒙版左上角，≥0，默认 0） yinteger — 局部矩形左上角 y（相对蒙版左上角，≥0，默认 0） winteger — 局部矩形宽（给了 x/y/w/h 任一就必须给 w 与 h） hinteger — 局部矩形高 boundsobject — 同时改蒙版 bounds { top, left, bottom, right }（此时 gray 要覆盖整张新蒙版）；与 x/y/w/h 互斥
不给 x/y/w/h/bounds 时 gray 必须覆盖整张蒙版；保持原压缩方式；非 structural。
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerMask","index":1}]
示例 复制
[
{
"op": "setLayerMaskPixels",
"index": 1,
"x": 0,
"y": 0,
"w": 2,
"h": 2,
"gray": [
0,
64,
128,
255
]
}
]
replaceLayerMask — 整张换掉用户蒙版（-2）的像素与范围，保留其余蒙版属性（随图层变换用）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录；图层必须已有用户蒙版 boundsobject 是 新蒙版范围 { top, left, bottom, right }，整数，宽高 > 0 grayarray 是 8 位灰度（长度 = bounds 宽×高）；JSON 请传 number[] —— 传字符串会被逐字符当字节，长度凑巧相等时不报错 defaultColorinteger — 只能是 0 或 255可选：0 255
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerMask","index":1}]
示例 复制
[
{
"op": "replaceLayerMask",
"index": 1,
"bounds": {
"top": 748,
"left": 266,
"bottom": 750,
"right": 268
},
"gray": [
255,
0,
0,
255
]
}
]
addShapeLayer — 新建形状图层（SoCo 纯色填充 + vmsk 路径，可选 vstk 描边）
字段 类型 必填 说明 subpathsarray 是 子路径数组 [{ closed?:boolean(默认 true), operation?:'exclude'|'combine'|'subtract'|'intersect'|0…3|null, knots:[{ anchor:[x,y]|{x,y}, in?:[x,y], out?:[x,y], linked?:boolean }] }]；in/out 缺省 = 与 anchor 相同（角点）；至少一条子路径 unitsstring — 坐标单位：pixel（绝对像素）/ normalized（0…1）/ fixed（8.24 定点整数）可选：pixel normalized fixed 默认 "pixel" colorstring|array — 填充色：'#rrggbb' / '#rgb' / [r,g,b]（0…255），默认黑默认 "#000000" fillobject — { type:'solid', color }（color 的另一种写法；目前只支持 solid） strokeobject — { color, width(0.01…1000,默认1), opacity(0…100), dashOffset, cap:butt|round|square, join:miter|round|bevel, align:inside|center|outside, dash:[正数…], enabled:false=不描边 } originobject — 实时形状属性（vogk）：{ type:'rect'|'roundRect'|'ellipse', left, top, right, bottom, radii?:[左上,右上,右下,左下] }（像素）；PS 属性面板据此显示可调的 W/H 与四角圆角 atinteger — 新图层在「底=0」序里的插入下标，0…图层数；默认 = 图层数（最上面） namestring — 图层名，非空、≤255 字符默认 "形状 1" opacityinteger — 不透明度 0…255（255 = 不透明） visibleboolean — 是否可见 clippingboolean|integer — 剪贴蒙版：布尔值或 0/1 blendKeystring — 图层混合模式 4 字符键（不足补空格，如 'mul '）可选：pass norm diss dark mul idiv lbrn dkCl lite scrn div lddg lgCl over sLit hLit vLit lLit pLit hMix diff smud fsub fdiv hue sat colr lum
只支持 RGB 文档；像素坐标需落在画布附近（超 int32 定点范围拒绝）。
示例 复制
[
{
"op": "addShapeLayer",
"name": "矩形",
"color": "#ff6600",
"subpaths": [
{
"closed": true,
"knots": [
{
"anchor": [
100,
100
]
},
{
"anchor": [
400,
100
]
},
{
"anchor": [
400,
300
]
},
{
"anchor": [
100,
300
]
}
]
}
]
}
]
setShapeContent — 改形状 / 填充图层的填充类型与描边类型（属性面板「外观」两个下拉）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；须是形状或填充图层 fillobject — { type:'none'|'solid'|'gradient'|'pattern', color?, gradient?, pattern? }（gradient/pattern 结构同 addFillLayer） strokeobject — { type:'none'|'solid'|'gradient'|'pattern', color?, gradient?, pattern?, width?(0…1000) }
fill / stroke 至少给一个；只支持 RGB；「无填充」与描边需要图层有 vmsk 路径。
示例前置（让示例能跑通的准备步骤）：[{"op":"addShapeLayer","color":"#ff6600","subpaths":[{"closed":true,"knots":[{"anchor":[100,100]},{"anchor":[400,100]},{"anchor":[400,300]},{"anchor":[100,300]}]}]}]
示例 复制
[
{
"op": "setShapeContent",
"index": 6,
"stroke": {
"type": "solid",
"color": "#000000",
"width": 3
}
}
]
setShapeOrigin — 写 / 删形状层的实时形状属性（vogk：矩形 / 圆角矩形 / 椭圆的外框与四角半径）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；须是形状图层 originobject 是 { type:'rect'|'roundRect'|'ellipse', left, top, right, bottom, radii?:[左上,右上,右下,左下] }；传 null = 删掉 vogk（形状在 PS 里变成普通路径）
只改 vogk，不改路径：改圆角 / 尺寸时与 setVectorMaskPath 一起下发，两者要描述同一个形状。
示例前置（让示例能跑通的准备步骤）：[{"op":"addShapeLayer","color":"#ff6600","subpaths":[{"closed":true,"knots":[{"anchor":[100,100]},{"anchor":[400,100]},{"anchor":[400,300]},{"anchor":[100,300]}]}]}]
示例 复制
[
{
"op": "setShapeOrigin",
"index": 6,
"origin": {
"type": "roundRect",
"left": 10,
"top": 10,
"right": 110,
"bottom": 60,
"radii": [
8,
8,
8,
8
]
}
}
]
addVectorMask — 给没有矢量蒙版的图层新建矢量蒙版（vmsk）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是分组结束分隔记录；不能已有 vmsk/vsms subpathsarray 是 子路径数组 [{ closed?:boolean(默认 true), operation?:'exclude'|'combine'|'subtract'|'intersect'|0…3|null, knots:[{ anchor:[x,y]|{x,y}, in?:[x,y], out?:[x,y], linked?:boolean }] }]；in/out 缺省 = 与 anchor 相同（角点）；实际不能为空 unitsstring — 坐标单位：pixel（绝对像素）/ normalized（0…1）/ fixed（8.24 定点整数）可选：pixel normalized fixed 默认 "pixel"
代码注释说「subpaths 为空 = 隐藏全部」，但 freshPathRecords 会拒绝空数组 —— 目前必须至少一条子路径。
示例 复制
[
{
"op": "addVectorMask",
"index": 1,
"subpaths": [
{
"closed": true,
"knots": [
{
"anchor": [
100,
100
]
},
{
"anchor": [
400,
100
]
},
{
"anchor": [
400,
300
]
},
{
"anchor": [
100,
300
]
}
]
}
]
}
]
setVectorMaskPath — 整份替换已有矢量蒙版（vmsk/vsms）的路径
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；图层必须已有矢量蒙版 subpathsarray 是 子路径数组 [{ closed?:boolean(默认 true), operation?:'exclude'|'combine'|'subtract'|'intersect'|0…3|null, knots:[{ anchor:[x,y]|{x,y}, in?:[x,y], out?:[x,y], linked?:boolean }] }]；in/out 缺省 = 与 anchor 相同（角点）；空数组 = 清空路径（给 warning） unitsstring — 坐标单位：pixel（绝对像素）/ normalized（0…1）/ fixed（8.24 定点整数）可选：pixel normalized fixed 默认 "pixel"
operation / closed 缺省时沿用原子路径的值；没有矢量蒙版在 apply 阶段报错。
示例前置（让示例能跑通的准备步骤）：[{"op":"addVectorMask","index":1,"subpaths":[{"closed":true,"knots":[{"anchor":[100,100]},{"anchor":[400,100]},{"anchor":[400,300]},{"anchor":[100,300]}]}]}]
示例 复制
[
{
"op": "setVectorMaskPath",
"index": 1,
"subpaths": [
{
"closed": true,
"knots": [
{
"anchor": [
120,
120
]
},
{
"anchor": [
360,
120
]
},
{
"anchor": [
240,
320
]
}
]
}
]
}
]
setVectorStroke — 改矢量描边参数（vstk 描述符里的宽度 / 颜色 / 端点 / 虚线等）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；图层必须已有 vstk 块 valuesobject 是 非空对象 { 字段: 新值 }；width/dashOffset/opacity(0…100) 数字，cap:butt|round|square，join:miter|round|bevel，align:inside|center|outside，dashes:[≥0…]，color:'#rrggbb'|[r,g,b]|{r,g,b}（仅纯色描边），blendMode 友好名，enabled/fillEnabled/scaleLock/strokeAdjust 布尔可选：enabled fillEnabled width dashOffset miterLimit cap join align dashes opacity blendMode resolution scaleLock strokeAdjust color
values 的键也接受描述符字段名（strokeStyleLineWidth）与 lineWidth / size / dash 等同义写法。
示例前置（让示例能跑通的准备步骤）：[{"op":"addShapeLayer","color":"#ff6600","subpaths":[{"closed":true,"knots":[{"anchor":[100,100]},{"anchor":[400,100]},{"anchor":[400,300]},{"anchor":[100,300]}]}],"stroke":{"color":"#000000","width":2}}]
示例 复制
[
{
"op": "setVectorStroke",
"index": 6,
"values": {
"width": 4,
"color": "#ff0000"
}
}
]
setVectorMaskFlags — 改矢量蒙版标志位（反相 / 不链接 / 停用）与初始填充规则
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；图层必须已有矢量蒙版 invertboolean — 反相 notLinkboolean — 不与图层链接 disableboolean — 停用 fillStartsWithAllPixelsboolean — 初始填充规则记录（selector 8）
四个字段至少给一个。
示例前置（让示例能跑通的准备步骤）：[{"op":"addVectorMask","index":1,"subpaths":[{"closed":true,"knots":[{"anchor":[100,100]},{"anchor":[400,100]},{"anchor":[400,300]},{"anchor":[100,300]}]}]}]
示例 复制
[
{
"op": "setVectorMaskFlags",
"index": 1,
"disable": true
}
]
setLayerStyle — 整份替换一个图层的图层样式（样式面板「点样式 = 应用」；effects:null = 清除样式）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） effectsobject — lfx2 口径的效果描述符（class null：Scl / masterFXSwitch / DrSh / FrFX …）；null = 清除全部样式 effectsBytesstring — 或直接给序列化后的描述符字节（.asl 里 Styl.Lefx 那一段）
写 lfx2，并摘掉 lmfx / lrFX；样式里引用的图案需先用 addPatterns 写进文档。
示例 复制
[
{
"op": "setLayerStyle",
"index": 1,
"effects": null
}
]
addPatterns — 把图案写进文档全局图案资源（Patt / Pat2 / Pat3），供图案填充层 / 图案叠加按 Idnt 引用
字段 类型 必填 说明 patternsarray 是 [{ id(ASCII uuid), name, width, height, rgba(base64 或字节，width×height×4) }]；已有同 id 的跳过
示例 复制
[
{
"op": "addPatterns",
"patterns": [
{
"id": "00000000-0000-4000-8000-000000000001",
"name": "1×1",
"width": 1,
"height": 1,
"rgba": "/wAA/w=="
}
]
}
]
addLayerEffect — 给图层新增一条图层样式效果（没有样式块时新建 lfx2）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） effectstring 是 效果名（规范名或 4 字符 PS key，大小写不敏感；另认 drop-shadow / bevel / stroke 等同义写法）可选：dropShadow innerShadow outerGlow innerGlow bevelEmboss satin colorOverlay gradientOverlay patternOverlay stroke DrSh IrSh OrGl IrGl ebbl ChFX SoFi GrFl patternFill FrFX valuesobject — 覆盖默认模板的字段 { 路径: 值 }（如 Opct / Dstn / 'Clr ':'#000000'）；各效果可用路径见 core/psd-edit-create.js listCreatableEffects().fields；百分比 -100…100、角度 -360…360、像素 0…30000
新条目插在最前（at=0）；只允许一条的效果重复添加会被拒绝；patternOverlay 必须用 values 指定 Ptrn.Nm / Ptrn.Idnt；lfx2 上加第二条可多重效果会整块升级为 lmfx（不可逆）。
示例 复制
[
{
"op": "addLayerEffect",
"index": 1,
"effect": "dropShadow",
"values": {
"Opct": 60,
"Dstn": 8,
"Clr ": "#000000"
}
}
]
removeLayerEffect — 删除一条图层样式效果（删到一条不剩时删掉整个样式块）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） effectstring 是 效果名（规范名或 4 字符 PS key，大小写不敏感；另认 drop-shadow / bevel / stroke 等同义写法）可选：dropShadow innerShadow outerGlow innerGlow bevelEmboss satin colorOverlay gradientOverlay patternOverlay stroke DrSh IrSh OrGl IrGl ebbl ChFX SoFi GrFl patternFill FrFX atinteger — 多重效果里删第几条（≥0）默认 0
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerEffect","index":1,"effect":"dropShadow"}]
示例 复制
[
{
"op": "removeLayerEffect",
"index": 1,
"effect": "dropShadow"
}
]
setLayerEffect — 启用 / 停用一条已有的图层样式效果（enab）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） effectstring 是 效果名（规范名或 4 字符 PS key，大小写不敏感；另认 drop-shadow / bevel / stroke 等同义写法）可选：dropShadow innerShadow outerGlow innerGlow bevelEmboss satin colorOverlay gradientOverlay patternOverlay stroke DrSh IrSh OrGl IrGl ebbl ChFX SoFi GrFl patternFill FrFX enabledboolean 是 启用或停用 atinteger — 多重效果里改第几条（≥0）默认 0
图层没有描述符型样式块 / 没有该效果时在 apply 阶段才报错（planEdits 查不出）；老式 lrFX 不改。
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerEffect","index":1,"effect":"dropShadow"}]
示例 复制
[
{
"op": "setLayerEffect",
"index": 1,
"effect": "dropShadow",
"enabled": false
}
]
setLayerEffectsEnabled — 图层样式整体开关（masterFXSwitch）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） enabledboolean 是 启用或停用全部图层样式
图层没有样式块时在 apply 阶段才报错。
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerEffect","index":1,"effect":"dropShadow"}]
示例 复制
[
{
"op": "setLayerEffectsEnabled",
"index": 1,
"enabled": false
}
]
clearLayerEffects — 整块摘掉图层样式（lfx2 / lmfx / lrFX），用于样式已烘进像素之后
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）
没有样式块时不改动（changed=false）。
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerEffect","index":1,"effect":"dropShadow"}]
示例 复制
[
{
"op": "clearLayerEffects",
"index": 1
}
]
setLayerParams — 按路径改已有图层样式 / 调整图层 / 填充图层块里的参数（可增删渐变色标）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1） targetstring 是 'effects'（样式顶层）/ 'effect:<效果名或 key>'（也可裸写效果名）/ 'adjustment'（主调整块）/ 'adjustment:<块 key>'；块 key 见 enum可选：effects effect:DrSh effect:IrSh effect:OrGl effect:IrGl effect:ebbl effect:ChFX effect:SoFi effect:GrFl effect:patternFill effect:FrFX adjustment adjustment:SoCo adjustment:GdFl adjustment:PtFl adjustment:CgEd adjustment:blwh adjustment:vibA adjustment:clrL adjustment:brit adjustment:levl adjustment:curv adjustment:hue adjustment:hue2 adjustment:blnc adjustment:phfl adjustment:mixr adjustment:selc adjustment:expA adjustment:post adjustment:thrs adjustment:nvrt adjustment:grdm valuesobject — { 字段路径: 新值 }（'.' 分段，如 'Clr .Rd '、'records.3.midtoneInput'；颜色对象可整体赋 '#rrggbb'）；≤256 个；无 arrayOps 时必填且非空 atinteger — 多重效果里改第几条（≥0）默认 0 arrayOpsarray — 数组增删（≤64 条）：{ path, insertAt|removeAt|sortBy（三选一）, copyFrom?, value? }；仅白名单数组（渐变 Clrs/Trns、grdm 色标）；先于 values 执行
只改已有块里已存在的字段；字段是否存在、块能否原样重建在 apply 阶段校验（planEdits 只查参数形状）。可用字段见 core/psd-edit-params.js getLayerParams()。
示例前置（让示例能跑通的准备步骤）：[{"op":"addLayerEffect","index":1,"effect":"dropShadow"}]
示例 复制
[
{
"op": "setLayerParams",
"index": 1,
"target": "effect:DrSh",
"values": {
"Opct": 40
}
}
]
addAdjustmentLayer — 新建一个调整图层（无像素记录 + 对应调整块）
字段 类型 必填 说明 kindstring 是 调整类型（也认块 key 与 brightness / hue / bw / curve / level / mixer / selective 等别名，忽略大小写与连字符）可选：brightnessContrast levels curves hueSaturation invert posterize threshold blackWhite colorBalance exposure channelMixer selectiveColor vibrance photoFilter colorLookup gradientMap valuesobject — 按 kind 不同的参数，未知键报错；见 valuesByKind atinteger — 新图层在「底=0」序里的插入下标，0…图层数；默认 = 图层数（最上面） namestring — 图层名，非空、≤255 字符默认 "该 kind 的中文名" opacityinteger — 不透明度 0…255（255 = 不透明） visibleboolean — 是否可见 clippingboolean|integer — 剪贴蒙版：布尔值或 0/1 blendKeystring — 图层混合模式 4 字符键（不足补空格，如 'mul '）可选：pass norm diss dark mul idiv lbrn dkCl lite scrn div lddg lgCl over sLit hLit vLit lLit pLit hMix diff smud fsub fdiv hue sat colr lum
文档必须已有图层；支持位图/灰度/索引/RGB/CMYK/多通道/双色调/Lab 模式；16/32 位文档不支持。
示例 复制
[
{
"op": "addAdjustmentLayer",
"kind": "hueSaturation",
"values": {
"saturation": -30
}
}
]
addFillLayer — 新建填充图层：纯色（SoCo）/ 渐变（GdFl）/ 图案（PtFl），铺满画布
字段 类型 必填 说明 kindstring — 填充类型可选：solid gradient pattern 默认 "solid" colorstring|array — kind=solid 的颜色：'#rrggbb' / '#rgb' / [r,g,b]默认 "#000000" gradientobject — kind=gradient：{ type:linear|radial|angle|reflected|diamond, angle(-360…360,默认90), scale(1…1000), stops:[{color,location 0…1,midpoint 1…99}]≥2 个≤64 个, opacityStops:[{opacity 0…100,location,midpoint}], name, dither, reverse, align } patternobject — kind=pattern 时必填：{ name, id（文档 Patt 资源里的图案 uuid）, scale(1…1000), linked, angle } atinteger — 新图层在「底=0」序里的插入下标，0…图层数；默认 = 图层数（最上面） namestring — 图层名，非空、≤255 字符默认 "纯色填充 / 渐变填充 / 图案填充" opacityinteger — 不透明度 0…255（255 = 不透明） visibleboolean — 是否可见 clippingboolean|integer — 剪贴蒙版：布尔值或 0/1 blendKeystring — 图层混合模式 4 字符键（不足补空格，如 'mul '）可选：pass norm diss dark mul idiv lbrn dkCl lite scrn div lddg lgCl over sLit hLit vLit lLit pLit hMix diff smud fsub fdiv hue sat colr lum
只支持 RGB 文档；没有 vmsk（要限定范围请再加蒙版）。
示例 复制
[
{
"op": "addFillLayer",
"kind": "solid",
"color": "#3366ff",
"opacity": 128
}
]
convertToSmartObject — 把图层转换为内嵌智能对象（写内嵌 PSD + PlLd/SoLd + 全局 lnk2）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；不能是组，不能已是智能对象 sourceobject 是 { data:RGBA 字节(≥ width×height×4，非预乘), width, height } 内嵌文档像素（通常就是该层像素）；JSON 可传 number[] boundsobject — 智能对象在画布上的位置 { left, top, right, bottom }；默认 = 图层 bounds namestring — 内嵌文件名；默认「图层名.psd」 embeddedobject — 现成的内嵌 PSD 字节（Uint8Array，8BPS 开头）；只能在进程内调用时传，JSON 无法表达 idstring — 内嵌文件 uuid（测试用；默认随机） placedIdstring — 放置实例 uuid（默认随机） resolutionnumber — 内嵌文档分辨率 dpi默认 72
图层原有像素 / 蒙版 / 样式不动。
示例 复制
[
{
"op": "convertToSmartObject",
"index": 1,
"source": {
"data": [
200,
200,
200,
255,
200,
200,
200,
255,
200,
200,
200,
255,
200,
200,
200,
255
],
"width": 2,
"height": 2
}
}
]
detachSmartObject — 把共享内嵌文件的智能对象拆成独立副本（复制内嵌文件、换新 id）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；必须是智能对象
外部链接的智能对象（没有内嵌文件）拒绝。
示例 复制
[
{
"op": "detachSmartObject",
"index": 1
}
]
addGallerySmartFilter — 给智能对象追加一条「滤镜库」智能滤镜（SoLd.filterFX.filterFXList 末尾 = 最后应用，面板里显示在最上面）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；必须是智能对象且带 SoLd 放置描述符 entryobject 是 filterFXList 的一条描述符（__classID 'filterFX'，含 Fltr:{ classID 'GEfc', GEfs:[…] }）；由 core/filter-gallery-spec.js 的 galleryFilterFXEntry(layers, { fg, bg }) 生成
只写描述符，不重算缓存像素：图层像素请在同一批里用 replaceLayerPixels 一起写（一步撤销）。没有 filterFX 时新建（键紧跟 Rslt）。写完自检读回，末条不是刚写的滤镜就放弃。HTTP 走服务端 op addSmartFilter(kind:'filterGallery') 更方便（它会顺带算像素）。
setSmartFilterEntry — 改智能对象上的一条智能滤镜（SoLd.filterFX.filterFXList[at]）：参数（Fltr）/ 混合选项 / 前景背景色 / 启用位
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；必须是智能对象且带 SoLd 放置描述符 atinteger 是 filterFXList 下标（0 = 最先应用 = PS 图层面板上最下面那条） Fltrobject — 整份新的滤镜描述符（__classID 必须与原条目相同；换滤镜种类请删掉重加）。core/smart-filter-spec.js 的 fltrWithParams(原 Fltr, kind, 参数) / 滤镜库用 galleryDescriptor(layers) 生成 blendOptionsobject — { opacity?: 0…100, mode?: 图层混合键（norm / mul / scrn …）}，写成 PS 的 blendOptions（Opct #Prc + Md BlnM） fgarray — [r,g,b] 执行时的前景色（素描类滤镜库效果用；只在条目本来有 FrgC 时改） bgarray — [r,g,b] 执行时的背景色（BckC） enabledboolean — 这条滤镜的启用位（enab）
只改描述符，不重算缓存像素：图层像素请在同一批里用 replaceLayerPixels 一起写（一步撤销）。编辑器「双击智能滤镜重开对话框 / 混合选项」走的就是它。
setStackMode — 智能对象 › 堆栈模式：写进放置描述符（SoLd Type = 3「图像堆栈」+ imageStackPlugin 类；PlLd 的 placedLayerType 同步）
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；必须是智能对象且带 SoLd modestring 是 none / entropy / kurtosis / max / mean / median / min / range / skewness / stdDev / sum / variance（对应 PS 插件类 entr kurt maxx avrg medn minn rang skew stdv summ vari）可选：none entropy kurtosis max mean median min range skewness stdDev sum variance
只写描述符（none = 去掉 imageStackPlugin、Type 回 2）；统计后的缓存像素由调用方用 replaceLayerPixels 写（core/stack-modes.js 的 stackCombine）。imageStackPlugin 的存放位置按 Action Manager 口径（applyImageStackPluginRenderer 事件的 imageStackPlugin 类）推定，未拿 PS 样本逐字节核对。
示例 复制
[
{
"op": "setStackMode",
"index": 1,
"mode": "median"
}
]
copyLayerBlocks — 把一层的若干附加信息块原样拷到另一层（已有同名块则替换）
字段 类型 必填 说明 frominteger 是 源图层下标（底=0） tointeger 是 目标图层下标 keysarray 是 四字符块名数组，如 ['lfx2', 'vmsk']；源层没有的键跳过。不允许 lsct / lsdk / luni / lyid / SoLd / PlLd / TySh（会破坏图层身份）
「智能对象 › 转换为图层」用它把智能对象的图层样式 / 矢量蒙版带到外包组上。矢量蒙版坐标是相对画布归一化的，同一文档内拷贝不用换算。
示例 复制
[
{
"op": "copyLayerBlocks",
"from": 1,
"to": 4,
"keys": [
"lfx2"
]
}
]
ensureLayerIds — 给没有 lyid 的图层补一个唯一图层 id（链接组 / 图层复合 / 变量都按 lyid 对齐） 无参数。
已有 id 的不动；新 id = 当前最大 id + 1 起递增。全部都有时 changed:false。
示例 复制
[
{
"op": "ensureLayerIds"
}
]
setLinkGroups — 链接 / 取消链接图层，或停用 / 启用链接（图像资源 1026 / 1072，按 lyid 对齐）
字段 类型 必填 说明 indicesarray 是 图层下标数组（底=0）；非空 linkboolean — true = 链成一组（已在组里的并进最小组号，PS 同）；false = 从各自链接组里拿出（剩一层的组自动解散）；link:true 时至少两个图层（给了 disable 时除外） disableboolean — 给了就只改「在组里是否停用」（PS ⇧ 点链条图标出现红叉），忽略 link
会先自动补齐缺失的 lyid。
示例 复制
[
{
"op": "setLinkGroups",
"indices": [
1,
4
],
"link": true
}
]
setLayerCompsMeta — 写各图层的图层复合记录（shmd 块里的 cmls 子块）
字段 类型 必填 说明 entriesarray 是 [{ index, cmls: 描述符|null }]；cmls = 该层在各图层复合里的可见 / 位置 / 外观记录（PS 的 layerSettings 列表），null = 去掉该子块
没有 shmd 就新建；shmd 里其它子块原样保留。复合本身的列表在图像资源 1065（用 setImageResource 写），与这里按 compID 对应。
示例 复制
[
{
"op": "setLayerCompsMeta",
"entries": [
{
"index": 1,
"cmls": null
}
]
}
]
setLayerAnimMeta — 写各图层的帧动画记录（shmd 块里的 mlst / mdyn 子块）
字段 类型 必填 说明 entriesarray 是 [{ index, mlst: 描述符|null, mdyn: 整数|null }]；mlst = 该层在各帧里的可见性 / 位置偏移 / 不透明度（PS 的 LaSt 列表，按帧 id 分组），mdyn = 统一位置 / 样式 / 可见性与「传播帧 1」标志；两者都 null = 去掉这两个子块
没有 shmd 就新建；shmd 里其它子块原样保留。帧列表本身在图像资源 4000（'mani' / 'AnDs'），与这里按帧 id 对应。
示例 复制
[
{
"op": "setLayerAnimMeta",
"entries": [
{
"index": 1,
"mlst": null,
"mdyn": null
}
]
}
]
setArtboard — 把组头设为画板 / 改画板矩形与背景，或取消画板身份
字段 类型 必填 说明 indexinteger 是 图层下标（底=0，0…图层数-1）；设画板时必须是组头（groupType 1/2） rectobject — 画板矩形 { top, left, bottom, right }（数字，宽高 > 0）；remove 为假时必填 presetNamestring — 画板预设名；默认 = 图层名 colorstring|array — 背景色（backgroundType=4 时生效）默认 "#ffffff" backgroundTypeinteger|string — 1 白 / 2 黑 / 3 透明 / 4 其它（用 color）；也认 white / black / transparent / custom / other可选：1 2 3 4 white black transparent custom other 默认 1 removeboolean — true = 删掉 artb/artd/abdd，取消画板（此时其余字段忽略；本来不是画板则报错）
写 artb + abdd，原有 artd 一并更新；保留原 guideIDs。
示例 复制
[
{
"op": "setArtboard",
"index": 2,
"rect": {
"top": 0,
"left": 0,
"bottom": 1080,
"right": 1920
},
"backgroundType": "white"
}
]
replaceSmartObject — 换智能对象源图（按覆盖模式渲染进网格 / 变形，写回内嵌源图、缓存栅格、FEid 与缩略图）
字段 类型 必填 说明 targetinteger|string|object — 智能对象序号 / 图层名 / { layerIndex } / { smartObjectIndex }；省略 = 第 0 个智能对象 imageobject|integer|string 是 图片引用：{ file:"image", index:n } / 上传文件名 / data:URL / 裸 base64 fitobject — { mode:"cover"|"contain"|"tile"|"stretch", alignX?, alignY?, scale? }，默认 cover meshobject — 顺带改网格：{ points, xn, yn, sliceX, sliceY } 或 { splits:{ u, v } } sourceNamestring — 写进 PSD 的内嵌源图文件名
与 /api/render（output.format=psd）逐字节相同。注意：number 型 target 在这三条老 op 里指「智能对象序号」。
示例 复制
[
{
"op": "replaceSmartObject",
"target": 0,
"image": {
"file": "image",
"index": 0
},
"fit": {
"mode": "cover"
}
}
]
deform — 智能对象网格 / 变形滤镜写回（warp、quiltWarp、透视变形、操控变形）
字段 类型 必填 说明 targetinteger|string|object — 同 replaceSmartObject pointsarray — Bezier 网格控制点 [{x,y}]（配 xn / yn / sliceX / sliceY） deformobject — 变形滤镜 JSON（/api/so/resolve 的 deform 结构）；create:true = 新挂一条 deformsarray — 多条变形：[{ deform, at?, create? }]
示例 复制
[
{
"op": "deform",
"target": 0,
"deform": "<来自 POST /api/so/resolve 的 layerInfo.deform，改过 warped 顶点>"
}
]
setSmartObjectDescriptor — 改智能对象放置描述符（Idnt / placed / 原始尺寸 Sz）
字段 类型 必填 说明 targetinteger|string|object — 同 replaceSmartObject linkIdstring — 改 Idnt（指向哪份内嵌文件） placedIdstring — 改 placed（实例 id） originalSizeobject — { width, height }
示例 复制
[
{
"op": "setSmartObjectDescriptor",
"target": 0,
"originalSize": {
"width": 800,
"height": 800
}
}
]
滤镜 / 调整清单
滤镜清单 （75 种，applyFilter 的 filter / params）
filter 名称 分组 params gaussianBlur高斯模糊 模糊 radius 半径（0…250 像素） 默认 2boxBlur方框模糊 模糊 radius 半径（0…250 像素） 默认 4blur模糊 模糊 — blurMore进一步模糊 模糊 — motionBlur动感模糊 模糊 angle 角度（-180…180 度） 默认 0；distance 距离（0…2000 像素） 默认 20radialBlur径向模糊 模糊 amount 数量（0…100） 默认 20；method 方法（spin/zoom） 默认 "spin"average平均 模糊 — surfaceBlur表面模糊 模糊 radius 半径（1…100 像素） 默认 5；threshold 阈值（2…255 色阶） 默认 15lensBlur镜头模糊 模糊 iris 光圈形状（disc/hexagon/square/triangle） 默认 "hexagon"；radius 半径（0…100） 默认 15；brightness 镜面高光 亮度（0…100） 默认 0；threshold 镜面高光 阈值（0…255） 默认 255；noise 杂色 数量（0…100） 默认 0smartBlur特殊模糊 模糊 radius 半径（0.1…100） 默认 3；threshold 阈值（0.1…100） 默认 25；quality 品质（low/medium/high） 默认 "medium"；mode 模式（normal/edgeOnly/overlayEdge） 默认 "normal"shapeBlur形状模糊 模糊 radius 半径（4…1000 像素） 默认 10；shape 形状（disc/ring/square/triangle/hexagon/star/heart） 默认 "disc"unsharpMaskUSM 锐化 锐化 amount 数量（0…500 %） 默认 100；radius 半径（0.1…250 像素） 默认 1；threshold 阈值（0…255 色阶） 默认 0sharpen锐化 锐化 — sharpenMore进一步锐化 锐化 — smartSharpen智能锐化 锐化 amount 数量（0…500 %） 默认 200；radius 半径（0.1…64 像素） 默认 1；reduceNoise 减少杂色（0…100 %） 默认 10；remove 移去（gaussian/lens/motion） 默认 "gaussian"；angle 角度（动感）（-180…180 度） 默认 0sharpenEdges锐化边缘 锐化 — shake防抖 锐化 length 模糊描摹边界（1…199 像素） 默认 10；angle 模糊方向（-180…180 度） 默认 0；smoothing 平滑（0…100 %） 默认 20；iterations 迭代次数（1…40） 默认 10addNoise添加杂色 杂色 amount 数量（0…400 %） 默认 12；distribution 分布（uniform/gaussian） 默认 "gaussian"；monochromatic 单色（bool） 默认 false；seed 随机种子（0…999999） 默认 12345median中间值 杂色 radius 半径（0…16 像素） 默认 1despeckle去斑 杂色 — reduceNoise减少杂色 杂色 strength 强度（0…10） 默认 6；preserveDetails 保留细节（0…100 %） 默认 60；colorNoise 减少杂色（0…100 %） 默认 45；sharpen 锐化细节（0…100 %） 默认 25dustScratches蒙尘与划痕 杂色 radius 半径（1…100 像素） 默认 1；threshold 阈值（0…255 色阶） 默认 0mosaic马赛克 像素化 cell 单元格大小（1…200 方形） 默认 10facet彩块化 像素化 — colorHalftone彩色半调 像素化 maxRadius 最大半径（4…127 像素） 默认 8；angle1 通道 1（-360…360 度） 默认 108；angle2 通道 2（-360…360 度） 默认 162；angle3 通道 3（-360…360 度） 默认 90pointillize点状化 像素化 cell 单元格大小（3…300） 默认 5；seed 随机种子（0…999999） 默认 2crystallize晶格化 像素化 cell 单元格大小（3…300） 默认 10；seed 随机种子（0…999999） 默认 1fragment碎片 像素化 — mezzotint铜版雕刻 像素化 type 类型（fineDots/mediumDots/grainyDots/coarseDots/shortLines/mediumLines/longLines/shortStrokes/mediumStrokes/longStrokes） 默认 "fineDots"；seed 随机种子（0…999999） 默认 4findEdges查找边缘 风格化 — emboss浮雕效果 风格化 angle 角度（-180…180 度） 默认 135；height 高度（1…100 像素） 默认 3；amount 数量（1…500 %） 默认 100solarize曝光过度 风格化 — traceContour等高线 风格化 level 色阶（0…255） 默认 128；edge 边缘（lower/upper） 默认 "lower"wind风 风格化 method 方法（wind/blast/stagger） 默认 "wind"；direction 方向（fromRight/fromLeft） 默认 "fromRight"；seed 随机种子（0…999999） 默认 7diffuse扩散 风格化 mode 模式（normal/darkenOnly/lightenOnly/anisotropic） 默认 "normal"；seed 随机种子（0…999999） 默认 3tiles拼贴 风格化 number 拼贴数（1…99） 默认 10；maxOffset 最大位移（1…99 %） 默认 10；fill 填充空白区域用（background/foreground/inverse/unaltered） 默认 "background"；seed 随机种子（0…999999） 默认 5extrude凸出 风格化 type 类型（blocks/pyramids） 默认 "blocks"；size 大小（2…255 像素） 默认 30；depth 深度（1…255） 默认 30；depthMode 深度依据（random/level） 默认 "random"；solidFront 立方体正面（bool） 默认 true；seed 随机种子（0…999999） 默认 9oilPaint油画 风格化 stylization 描边样式（0.1…10） 默认 3；cleanliness 描边清洁度（0…10） 默认 5；scale 缩放（0.1…10） 默认 1；bristle 硬毛刷细节（0…10） 默认 5；lighting 光照（bool） 默认 true；angle 角度（-180…180 度） 默认 -60；shine 闪亮（0…10） 默认 1highPass高反差保留 其它 radius 半径（0.1…250 像素） 默认 3offset位移 其它 dx 水平（-4000…4000 像素） 默认 10；dy 垂直（-4000…4000 像素） 默认 10；wrap 折回（bool） 默认 truemaximum最大值 其它 radius 半径（0…100 像素） 默认 1minimum最小值 其它 radius 半径（0…100 像素） 默认 1hsbHslHSB/HSL 其它 mode 行序（hsb/hsl） 默认 "hsb"custom自定 其它 matrix 卷积核 默认 [0,0,0,0,0,0,0,-1,0,0,0,-1,5,-1,0,0,0,-1,0,0,0,0,0,0,0]；scale 缩放（1…9999） 默认 1；offset 位移（-9999…9999） 默认 0clouds云彩 渲染 octaves 细节层数（1…9） 默认 6；seed 随机种子（0…999999） 默认 1differenceClouds分层云彩 渲染 seed 随机种子（0…999999） 默认 1fibers纤维 渲染 variance 差异（1…64） 默认 16；strength 强度（1…64） 默认 4；seed 随机种子（0…999999） 默认 1lensFlare镜头光晕 渲染 brightness 亮度（10…300 %） 默认 100；centerX 中心 X（0…100 %） 默认 30；centerY 中心 Y（0…100 %） 默认 30；lens 镜头类型（zoom/prime35/prime105/movie） 默认 "zoom"lighting光照效果 渲染 type 光源（spot/point/infinite） 默认 "spot"；intensity 强度（-100…100） 默认 35；centerX 中心 X（0…100 %） 默认 50；centerY 中心 Y（0…100 %） 默认 50；radius 范围（1…200 %） 默认 50；angle 方向（-180…180 度） 默认 -45；ambience 环境（-100…100） 默认 8；gloss 光泽（-100…100） 默认 0；bump 纹理高度（亮度）（0…100） 默认 0；useFg 光色用前景色（bool） 默认 falsewave波浪 扭曲 generators 生成器数（1…99） 默认 5；wavelengthMin 波长 最小（1…998） 默认 10；wavelengthMax 波长 最大（2…999） 默认 120；amplitudeMin 波幅 最小（0…998） 默认 5；amplitudeMax 波幅 最大（1…999） 默认 35；scaleH 比例 水平（0…100 %） 默认 100；scaleV 比例 垂直（0…100 %） 默认 100；type 类型（sine/triangle/square） 默认 "sine"；edge 未定义区域（wrap/repeat） 默认 "wrap"；seed 随机种子（0…999999） 默认 1ripple波纹 扭曲 amount 数量（-999…999 %） 默认 100；size 大小（small/medium/large） 默认 "medium"polar极坐标 扭曲 mode 方式（rectToPolar/polarToRect） 默认 "rectToPolar"pinch挤压 扭曲 amount 数量（-100…100 %） 默认 50shear切变 扭曲 amount 弯曲（-100…100 %） 默认 30；shape 曲线形状（bow/s） 默认 "bow"；edge 未定义区域（wrap/repeat） 默认 "wrap"spherize球面化 扭曲 amount 数量（-100…100 %） 默认 100；mode 模式（normal/horizontal/vertical） 默认 "normal"zigzag水波 扭曲 amount 数量（-100…100） 默认 10；ridges 起伏（1…20） 默认 5；style 样式（aroundCenter/outFromCenter/pondRipples） 默认 "pondRipples"displace置换 扭曲 scaleH 水平比例（-999…999 %） 默认 10；scaleV 垂直比例（-999…999 %） 默认 10；mode 置换图（stretch/tile） 默认 "stretch"；edge 未定义区域（wrap/repeat） 默认 "repeat"twirl旋转扭曲 扭曲 angle 角度（-999…999 度） 默认 50fieldBlur场景模糊 模糊画廊 blur 模糊（0…500 像素） 默认 15irisBlur光圈模糊 模糊画廊 blur 模糊（0…500 像素） 默认 15；centerX 中心 X（0…100 %） 默认 50；centerY 中心 Y（0…100 %） 默认 50；radiusX 半径 X（1…200 %） 默认 30；radiusY 半径 Y（1…200 %） 默认 30；feather 过渡（0…100 %） 默认 60tiltShift移轴模糊 模糊画廊 blur 模糊（0…500 像素） 默认 15；centerY 中心 Y（0…100 %） 默认 50；angle 角度（-90…90 度） 默认 0；focus 清晰带（半高）（0…100 %） 默认 10；transition 过渡（0…100 %） 默认 20spinBlur旋转模糊 模糊画廊 angle 模糊角度（0…360 度） 默认 15；centerX 中心 X（0…100 %） 默认 50；centerY 中心 Y（0…100 %） 默认 50；radius 半径（1…200 %） 默认 40ntscNTSC 颜色 视频 — deinterlace逐行 视频 eliminate 消除（odd/even） 默认 "odd"；create 创建新场方式（duplication/interpolation） 默认 "interpolation"bumpMap生成凹凸图 3D blur 模糊（0…50 像素） 默认 1；contrast 对比度（-100…100） 默认 0；invert 反相高度（bool） 默认 falsenormalMap生成法线图 3D blur 模糊（0…50 像素） 默认 1；strength 细节缩放（0.1…20） 默认 2；contrast 对比度（-100…100） 默认 0；invert 反相高度（bool） 默认 falseautoTone自动色调 调整 — autoContrast自动对比度 调整 — autoColor自动颜色 调整 — shadowsHighlights阴影/高光 调整 shadowAmount 阴影 数量（0…100 %） 默认 35；shadowTone 阴影 色调（0…100 %） 默认 50；highlightAmount 高光 数量（0…100 %） 默认 0；highlightTone 高光 色调（0…100 %） 默认 50；radius 半径（0…2500 像素） 默认 30；colorCorrection 颜色（-100…100） 默认 20；midtoneContrast 中间调（-100…100） 默认 0hdrToningHDR 色调 调整 radius 半径（1…500 像素） 默认 50；strength 强度（0.1…4） 默认 0.5；gamma 灰度系数（0.1…2） 默认 1；exposure 曝光度（-5…5） 默认 0；detail 细节（-100…300 %） 默认 30；vibrance 自然饱和度（-100…100 %） 默认 0；saturation 饱和度（-100…100 %） 默认 20matchColor匹配颜色 调整 luminance 明亮度（1…200） 默认 100；intensity 颜色强度（1…200） 默认 100；fade 渐隐（0…100） 默认 0；neutralize 中和（bool） 默认 truereplaceColor替换颜色 调整 color 取样颜色 默认 [255,0,0]；fuzziness 颜色容差（0…200） 默认 40；hue 色相（-180…180） 默认 0；saturation 饱和度（-100…100） 默认 0；lightness 明度（-100…100） 默认 0cameraRawCamera Raw 滤镜 校正 temperature 色温（-100…100） 默认 0；tint 色调（-100…100） 默认 0；exposure 曝光（-5…5） 默认 0；contrast 对比度（-100…100） 默认 0；highlights 高光（-100…100） 默认 0；shadows 阴影（-100…100） 默认 0；whites 白色（-100…100） 默认 0；blacks 黑色（-100…100） 默认 0；texture 纹理（-100…100） 默认 0；clarity 清晰度（-100…100） 默认 0；dehaze 去除薄雾（-100…100） 默认 0；vibrance 自然饱和度（-100…100） 默认 0；saturation 饱和度（-100…100） 默认 0lensCorrection镜头校正 校正 distortion 移去扭曲（-100…100） 默认 0；caRed 修复红/青边（-100…100） 默认 0；caBlue 修复蓝/黄边（-100…100） 默认 0；vignette 晕影 数量（-100…100） 默认 0；midpoint 晕影 中点（0…100） 默认 50；vertical 垂直透视（-100…100） 默认 0；horizontal 水平透视（-100…100） 默认 0；angle 角度（-180…180 度） 默认 0；scale 比例（50…150 %） 默认 100；edge 边缘（clear/repeat） 默认 "clear"
破坏性调整清单 （16 种，applyAdjustment 的 adjustment.type）
type 名称 参数 exposure曝光度 exposure(-20…20) offset(-0.5…0.5) gamma(0.01…9.99) workingGamma(1…3 或 "srgb"，默认 2.2) levels色阶 inputBlack(0…254) inputWhite(1…255) gamma(0.01…9.99) outputBlack(0…255) outputWhite(0…255) channel(rgb|r|g|b) channels({rgb,r,g,b}) curves曲线 points([[输入,输出],…] 2…19 个点，输入严格递增，0…255) channel(rgb|r|g|b) channels({rgb,r,g,b}) interpolation(spline|monotone|linear，默认 spline = PS 的自然三次样条) hueSaturation色相/饱和度 hue(-180…180) saturation(-100…100) lightness(-100…100) colorize colorizeHue(0…360) colorizeSaturation(0…100) reds/yellows/greens/cyans/blues/magentas（各 { hue, saturation, lightness }，可带 range:[外低,内低,内高,外高]） vibrance自然饱和度（近似） vibrance(-100…100) saturation(-100…100) photoFilter照片滤镜（近似） color([r,g,b]，每项 0…255) density(0…100) preserveLuminosity(boolean) selectiveColor可选颜色 plates(10×4 个 -100…100 整数，plates[0] 为 PSD 占位) method(0 相对 / 1 绝对) brightnessContrast亮度/对比度（旧式） brightness(-150…150) contrast(-100…100，PS 面板只给 -50…100) useLegacy(必须 true) meanValue(0…255，默认 127) invert反相 （无参数） posterize色调分离 levels(2…255 整数) threshold阈值 level(1…255 整数) desaturate去色 （无参数） blackWhite黑白 red yellow green cyan blue magenta（均 -200…300，默认 40/60/40/60/20/80）useTint(boolean) tintColor([r,g,b]，useTint 时必填) channelMixer通道混合器 monochrome red/green/blue/gray 各 { red, green, blue, constant }（-200…200） colorBalance色彩平衡（近似） shadows/midtones/highlights（各 3 个 -100…100：[青-红, 洋红-绿, 黄-蓝]）preserveLuminosity gradientMap渐变映射 stops([{ position:0…1, color:[r,g,b], midpoint?:0…1 }, …] 至少 2 个) reverse
MCP 服务（给 AI agent 用）
标准 Model Context Protocol 服务端，挂在同一个服务的 /mcp 上。Claude、Cursor、VS Code 或任何 MCP 客户端配好地址与 key，agent 就能打开 PSD、看图层、批量编辑、看预览、导出 —— 背后走的是与 /api/doc/edit 完全相同的编辑管线与守门，产物照样是 PS 可编辑的 PSD。
端点 POST https://your-host/mcp（Streamable HTTP；响应一律 application/json，不开 SSE 流）鉴权 Authorization: Bearer <API key> 或 X-Api-Key（与 REST 同一套 key、同一套限流与并发闸）协议版本 2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05，按客户端请求协商能力 tools（19 个，含字体库 upload_font / list_fonts / delete_font 与档位查询 get_account；只列当前档位能用的）· resources（能力目录 + 每份打开文档的大纲 / 预览）· prompts（2 个）
接入
Claude Code 复制
claude mcp add --transport http fullpsd https://your-host/mcp \
--header "Authorization: Bearer $FULLPSD_KEY"
Cursor（~/.cursor/mcp.json） 复制
{
"mcpServers": {
"fullpsd": {
"url": "https://your-host/mcp",
"headers": { "Authorization": "Bearer YOUR_FULLPSD_KEY" }
}
}
}
VS Code（.vscode/mcp.json） 复制
{
"servers": {
"fullpsd": {
"type": "http",
"url": "https://your-host/mcp",
"headers": { "Authorization": "Bearer ${input:fullpsdKey}" }
}
},
"inputs": [{ "id": "fullpsdKey", "type": "promptString", "description": "FullPsd API key", "password": true }]
}
只支持 stdio 的客户端（经 mcp-remote 桥接） 复制
{
"mcpServers": {
"fullpsd": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://your-host/mcp", "--header", "Authorization:${FULLPSD_AUTH}"],
"env": { "FULLPSD_AUTH": "Bearer YOUR_FULLPSD_KEY" }
}
}
}
只支持 stdio 的客户端（仓库自带的本地代理：还能直接读 / 存本机文件） 复制
{
"mcpServers": {
"fullpsd": {
"command": "node",
"args": ["/path/to/fullpsd/server/mcp-stdio.js"],
"env": { "FULLPSD_MCP_URL": "https://your-host/mcp", "FULLPSD_API_KEY": "YOUR_FULLPSD_KEY" }
}
}
}
server/mcp-stdio.js 只用 Node 自带模块（不用 npm install），把 JSON-RPC 原样转给远程 /mcp，另外多给工具三个本地参数：path（代替 base64，如 open_document(path="~/a.psd")、upload_font(path=…)）、image_path（代替 image_base64）、导出类工具的 save_to（导出后存到本机目录 / 文件）。读本机文件上限 FULLPSD_MCP_STDIO_MAX_MB（默认 200）。
只能填一个 URL、没法配请求头的客户端：部署方设 FULLPSD_MCP_URL_KEY=1 后可以用 https://your-host/mcp/k/<API key>。代价是 key 会出现在 URL 与访问日志里，只建议给专用的低权限 key 用。
用 curl 验证（应返回 serverInfo 与 instructions） 复制
curl -s -X POST https://your-host/mcp \
-H "Authorization: Bearer $FULLPSD_KEY" -H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
调试台 /console#mcp 有一个现成的 MCP 调试面板：initialize → 选工具 → 填 arguments → 直接看 agent 会拿到的结果（含预览图）。
工具
工具 做什么 参数（* 必填） 性质 get_catalog能力目录 查询本服务支持的全部编辑 op（含参数 schema 与示例）、滤镜、破坏性调整、调整图层、图层样式、混合模式、新建文档预设。先用它弄清 ops 怎么写。 section op category只读 new_document新建文档 新建空白 PSD（同编辑器「文件 › 新建」）。可给 preset（如「默认 Photoshop 大小」「电商主图」，见 get_catalog section=newDocument）或 width/height。 width height preset resolution mode depth background backgroundColor name写 open_document打开文档 把一份 PSD/PSB 放进服务端工作区，返回 doc_id 与图层大纲。来源：url（http/https 公网地址）或 base64。大文件也可以先 POST /mcp/upload。 url base64 name写 · 访问外网 list_documents工作区文档 列出当前凭证在工作区里打开着的文档（doc_id、版本、可撤销步数、剩余存活时间）。 — 只读 inspect_document查看图层 文档尺寸、画板、图层大纲（缩进 = 层级，[n] 就是 ops 里用的 index；底 = 0）。detail=true 附带每层的结构化字段。 doc_id* detail只读 render_preview渲染预览 按图层重新合成并返回预览图（可只出一块画板或一个区域）。用来确认编辑效果。 doc_id* artboard max_size region format hide只读 render_layer单层预览 只渲染一个图层的像素（不含其它层），看某层到底长什么样。 doc_id* index* max_size只读 edit_document编辑文档 按顺序执行一组 ops（与 REST 的 /api/doc/edit 完全相同：改属性 / 文字 / 像素 / 滤镜 / 调整 / 画布 / 图像大小 / 旋转 / 移动 / 复制 / 蒙版 / 矢量 / 样式 / 智能对象 / 变形 / 画板…）。成功后生成新版本（可 undo），失败则文档不变。ops 写法：[{ "op":"setLayerProps", "index":3, "opacity":128 }, { "op":"applyFilter", "index":1, "filter":"gaussianBlur", "params":{"radius":4} }]；图片参数（replaceSmartObject / replaceLayerPixels 的 image）可写 { "url": "https://…" } 或 data URL。完整参数见 get_catalog。 doc_id* ops* dry_run label recomposite font_map写 · 访问外网 replace_smart_object换智能对象图片 样机最常用的一步：把某个智能对象的内容换成一张图（按网格 / 透视 / 操控变形渲染，PS 里双击进去也是新图）。等价于 edit_document 的 replaceSmartObject op。 doc_id* target image_url image_base64 fit写 · 访问外网 undo撤销 回到上一个版本（可一次撤销多步）。 doc_id* steps写 · 破坏性 export_document导出 导出 PSD 或位图（png / jpg / webp / tiff；可只导出一块画板），返回限时下载链接。 doc_id* format artboard max_size quality filename只读 export_artboards按画板导出 每块画板导出一张图（PS 的「画板至文件」），打包成 zip 返回下载链接。 doc_id* format artboards max_size quality只读 validate_document体检 结构体检：lintPsd + 可解析 + 字节往返自检（与编辑出口的守门同一套）。 doc_id*只读 get_smart_filters智能滤镜 查看某个智能对象上的智能滤镜列表（改它们用 edit_document 的 setSmartFilters op）。 doc_id* target只读 get_account我的档位 当前凭证的档位（基础 / 高级…）、能用哪些功能、rpm / 并发 / 上传上限，以及按功能频率限制的剩余次数。某个工具或 op 报「不在档位」时用它确认。 — 只读 list_fonts字体库 需 fonts.library 列出这把 API key 上传过的字体（服务端文字重绘时按 PostScript 名优先匹配）。PSD 里缺的字体可以用 upload_font 补上。 — 只读 upload_font上传字体 需 fonts.library 把字体文件（TTF / OTF / TTC / OTC / WOFF）存进这把 key 的字体库，之后 edit_document 改文字时服务端用它重绘，不再用替代字体。TTC 会拆成多个字体。同 PostScript 名的旧字体会被替换。字体授权由上传方负责。 url base64 filename faces写 · 访问外网 delete_font删除字体 需 fonts.library 从字体库删掉一款字体（按 list_fonts 给的 id 或 PostScript 名）。 id*写 · 破坏性 close_document关闭文档 从工作区移除文档（释放空间）。没导出的改动会丢失。 doc_id*写 · 破坏性
一次典型的会话
agent 视角 结构示意 复制
open_document { "url": "https://cdn.example.com/mockup/tshirt.psd" }
→ { "doc_id": "doc_pIWK1YrqGGKf", "width": 1200, "height": 1200,
"outline": "[2] 无法无天 (text · 248×172 @431,200 · 文字「无法无天」)\n[1] img (smartObject · 285×437 @461,370 · 混合 mul)\n[0] 背景 (raster · 1200×1200 @0,0)" }
replace_smart_object { "doc_id": "doc_pIWK1YrqGGKf", "target": "img", "image_url": "https://cdn.example.com/art/v2.png", "fit": "contain" }
edit_document { "doc_id": "doc_pIWK1YrqGGKf", "ops": [
{ "op": "setText", "index": 2, "text": "限时 8 折" },
{ "op": "applyAdjustment", "index": 0, "adjustment": { "type": "hueSaturation", "hue": 20 } },
{ "op": "moveLayer", "index": 2, "dx": 0, "dy": -60 } ] }
render_preview { "doc_id": "doc_pIWK1YrqGGKf", "max_size": 800 } → 一张 PNG（agent 直接看图确认）
export_document { "doc_id": "doc_pIWK1YrqGGKf", "format": "psd" } → { "url": "https://your-host/mcp/files/…/tshirt.psd", "expiresAt": "…" }
临时工作区
doc_id 归属凭证： 文档挂在打开它的 API key 名下（按 key 本身区分，不按名字），别的 key 拿到 doc_id 也读不到。Mcp-Session-Id 会签发但不强制回带 —— 断线重连、负载均衡都不会丢文档；客户端发 DELETE /mcp 结束会话时，只关掉这个会话 里打开的文档。版本与撤销： 每次成功的 edit_document 生成新版本；默认保留最近 5 个历史版本（FULLPSD_MCP_HISTORY），undo 回退。失败的编辑不会产生版本（守门不过的产物进不了工作区）。上限： 每个 key 同时最多 8 份（FULLPSD_MCP_MAX_DOCS）；全进程 1 GB（FULLPSD_MCP_MAX_MB，含历史版本，满了先丢最老的历史）；闲置 60 分钟清理（FULLPSD_MCP_TTL_MIN）。进程重启即清空。进出文件： 进 —— open_document 的 url（服务端去取）或 base64；大文件用 POST /mcp/upload（multipart 字段 file，返回 doc_id，比 base64 省 1/3 流量）。出 —— export_document / export_artboards 返回 /mcp/files/<token>/文件名 的限时下载链接（默认 30 分钟，token 本身就是凭证），协议 ≥ 2025-06-18 时同时附一个 resource_link。ops 里的图片： replaceSmartObject / replaceLayerPixels 的 image 可写 { "url": "https://…" }（服务端去取）或 data URL / base64。
安全
按 URL 取文件防 SSRF： 只允许 http/https；解析到内网 / 回环 / 链路本地 / 保留地址的主机一律拒绝，每一跳重定向都复查；有大小与超时上限。可用 FULLPSD_MCP_FETCH_HOSTS 收紧到白名单，FULLPSD_MCP_FETCH=off 整体关闭。Origin 校验： 带 Origin 头的请求只放行同源或 FULLPSD_MCP_ORIGINS 白名单（MCP 规范要求的 DNS 重绑定防护）。并发与限流： 渲染 / 编辑 / 导出类工具占用与 REST 同一套重接口并发闸（撞闸时工具返回 isError 并提示稍后重试；按 URL 下载图片发生在占闸之前，慢链接不会占着名额）；每次 HTTP 请求计一次 rpm，批量请求里每个额外的 tools/call 再各计一次。api-keys.json 里按 key 配的 maxUploadMB 对 MCP 的上传 / base64 / URL 取文件同样生效。
资源与提示
URI / 名字 内容 fullpsd://catalog能力目录（同 GET /api/catalog） fullpsd://documents/{doc_id}/summary文档尺寸、画板与图层大纲（JSON） fullpsd://documents/{doc_id}/preview按图层合成的预览 PNG（长边 ≤1024） prompt mockup-replace 样机换图并导出（参数 psd_url、image_url） prompt batch-resize 改尺寸出图（参数 psd_url、width、height?）
错误
请求头 MCP-Protocol-Version 给了但不在支持列表里时回 400 （规范要求）；不给则按 2025-03-26 处理。
工具执行层面的失败（参数不对、op 校验失败、守门不过、文档过期…）按 MCP 规范放在工具结果里：{ "isError": true, "content": [{ "type": "text", "text": "一句话原因\n{定位 JSON}" }] }，agent 能读到并自行修正；定位 JSON 与 REST 同口径（opIndex / op / stage / code）。协议层面的错误走 JSON-RPC error：-32601 方法不存在 · -32602 工具名 / 参数形状不对 · -32002 资源不存在 · -32700 JSON 解析失败。HTTP 层：401 缺 key 或 key 无效 · 403 Origin 不允许 · 405 GET（本服务不开 SSE 流）· 429 超出 rpm。