dsy-xueai/image2editable/image-to-psd

Image to PSD

把图片重建为分层 PSD。文字只由可编辑文字图层贡献一次；视觉组件和背景不得残留文字像素。质量检查未通过时继续针对性修复并复检，不把整页图片伪装成分层结果。

全部文字包括艺术字均须可编辑，保留原有曲线、描边及多色；不得用文字截图、转曲轮廓或透明文字覆盖冒充。复用有效识别和组件资产，避免重复推理；只有实际渲染和编辑验收通过才能作为成品交付。

局部 OCR 找回文字后，先验证源图、manifest、资产哈希和文字增量依赖。可证明安全时只更新受影响像素及背景，保留其余有效组件；并行路径也必须使用新增文字清理后的图像。重建范围覆盖实际文字清理边缘，不能仅依据原 OCR 框。

输入与授权

识别阶段复用 text-context-cache 中匹配像素、语言和 OCR 实现的整行复核结果，避免重复处理相同冲突；不同栏位的文字不得因宽检测结果而丢失独立位置与样式。共享 OCR 的 words/runs 元数据不代表 PSD 已具备对应的艺术字渲染能力，必须核验实际文字图层效果。

• 仅支持 PNG、JPEG、BMP、TIFF 和 WebP。
• 单图输出一个 .psd；多图输出到目录，同名文件使用稳定序号区分。
• 每个 PSD 包含修复背景、按 z-order 排列的透明视觉组件和可编辑文字图层。
• PSD 写入依赖已授权的 Aspose.PSD。模型推理前必须设置 ASPOSE_PSD_LICENSE；授权缺失或无效时立即停止。

Windows PowerShell：

$env:ASPOSE_PSD_LICENSE="C:\path\to\Aspose.PSD.lic"

Linux/macOS：

export ASPOSE_PSD_LICENSE=/path/to/Aspose.PSD.lic

授权文件、模型权重、OCR 缓存和运行产物都不存放在此 skill 中。

环境准备与图片兼容入口

转换前必须阅读并执行 自动环境准备。完整仓库和仅安装 Skill 在 Windows、macOS、Linux 都自动准备缺少的 Python、Git、项目 Runtime、依赖、OCR 和模型。不得为依赖或模型安装向用户询问确认；遵循宿主实际审批与权限限制。Windows 新安装优先 D 盘，再选其他非 C 本地磁盘，仅在不存在其他本地磁盘时使用 C 盘；macOS/Linux 优先其他已挂载的本地磁盘，否则使用用户目录。使用 scripts/skill_environment.py 统一环境、模型、下载缓存与临时目录。已有可用环境和模型继续复用。

准备后默认使用下文产品 Runtime 的 Agent 流程；下面的 standalone CLI 是图片兼容入口。两者都使用自动安装的模型，不要求使用者手动配置 SAM2_MODEL、LAMA_MODEL 或 GROUNDING_DINO_MODEL。推理不会下载模型或回退 Hugging Face cache；准备阶段先校验 runtime receipt，已有显式模型路径须满足固定身份约束。LaMa 缺失或初始化失败时停止该无效路径并修复环境，不降低修复质量。

检查当前设备后再运行：

python -c "import sys, torch; print({'platform': sys.platform, 'cuda': torch.cuda.is_available(), 'rocm': torch.version.hip})"

CPU 仍使用完整模型和相同质量门，速度会明显慢于 GPU。macOS 在真实 Apple Silicon 回归完成前不自动把 MPS 设为默认。

从 skill 根目录运行 module，不要直接执行脚本文件：

cd skills/image-to-psd
python -m scripts.image_to_psd input.png
python -m scripts.image_to_psd input.png -o output.psd
python -m scripts.image_to_psd img1.png img2.png -o psd-output
python -m scripts.image_to_psd images/ -o psd-output --lang en

standalone CLI 只负责图片重建，不接受 --agent-provider。它先完成全部页面的严格准备，再发布 PSD；任一页面失败时不会留下部分输出。

产品 Runtime

完整仓库或已安装的 image2editable 只支持 host Provider，使用统一的组件动作、最多 5 批修复和相同质量门。

完整仓库中缺少 PSD 依赖时，在仓库根目录安装对应 extra：

python -m pip install -e ".[psd]"

仅已安装 image2editable distribution、没有仓库源码时，直接安装同一 PSD writer 依赖，不对调用者的当前项目执行 editable install：

python -m pip install "aspose-psd>=26.5.0"

随后以非交互方式安装并校验固定的 SAM、LaMa 和 DINO runtime：

image2editable models install runtime --yes
image2editable doctor

host 直接使用当前支持视觉、本地文件读取、工具调用和结构化 JSON 的宿主，不探测、下载或要求配置其他组件决策模型。处理敏感文件前，确认宿主服务的数据策略符合要求。

Host 模式先准备 Run，再推进到 awaiting_agent：

image2editable prepare input.png -o output.psd \
  --run-dir runs/psd-job --format psd --agent-provider host
image2editable run execute runs/psd-job
image2editable agent next runs/psd-job
image2editable agent record runs/psd-job --plan response.json
image2editable run execute runs/psd-job

第一次 agent next 返回视觉能力 challenge。必须实际查看 image_path，记录观察到的 shape、color 和 count，不能从文件名或 metadata 猜测。之后每轮只查看 request 中按顺序列出的 review_evidence，同时核验完整 request、hash、组件图、候选和冻结状态；quality-report.json 作为质量证据读取，不能当图片发送。

计划必须绑定当前 request_sha256。每个 action 只使用请求组件图中的 ID，并限定为现有十四类动作：accept、discard、merge、split、expand、shrink、retry_with_box、retry_with_points、attach_text、suppress_text、collapse_to_parent、rebuild_background、absorb_residual、absorb_into_parent。Agent confidence 不能放宽硬失败。

若绑定的 unexplained-mask.png 中有经验证的结构碎片，可用 absorb_residual 并入相关候选；请求图中的 inactive visual 有对应来源证据时，该动作仅恢复绑定残差，不恢复整个已停用复合对象，也不调用 SAM。随后按需 rebuild_background 并重新验证。只有残差证据不足以确定结构时才重新分割，不得将残差归为背景来消除违规。

质量与失败

卡片底色连接多个独立纯色图形时，split 可复用原图色块边界拆分，保留全部像素，不调用 SAM。parts 对应实际完整单元并包含底色，不能按期望数量任意切块。文字框外的标点应修复 OCR 字形范围，不能作为图形残差吸收。

• 每张图片独立判断，不能跨图片套用拆分结果。
• 每个视觉组件应是可独立移动的最小完整单元，不得残缺、重叠、吸收相邻对象或只保留阴影碎片。
• 已通过组件立即冻结并复用；检测无进展和重复产物，停止无效策略并切换针对性修复，不为耗尽轮数重复执行。有实际进展的任务不因总耗时较长而放弃。
• rebuild_background.margin_ratio 使用能覆盖残影且不触及相邻结构的最小值，不固定写死。
• unexplained_visual_residual 必须由 active visual owner 覆盖；不能用 accept、discard 或归为背景来消除违规。
• 可靠 OCR 文字必须全部写为可编辑文字图层，并且只能出现一次。
• preserved_with_warning 是内部未完成状态，不是分层交付。当前运行时仍有修复周期耗尽后无法继续的路径；须解决该交付能力缺口并补通用回归，不能将低质量结果标为成功或宣称已具备发布条件。
• standalone 质量异常包含指标和诊断路径，由宿主检查 source.png、ownership.png、reconstructed.png 和 report.json 并修复。诊断不能代替最终文件，不把修复责任交给使用者；不得放宽门禁、删内容、伪造通过或回退为整页图片。用户主动取消时停止处理并保留恢复依据。