改图无痕 指哪改哪 多图嫁接（Zero-Trace Image Edit v4.7.1）

> 一句话能力：给一张图（或两张）+ 一句话，它只精准改动你指定的区域，其余像素零改动，出图经自动质检、改不好明说不合格。出图与交付均无需手动签名（v4.7.0 起），双签确认表降级为可选留痕；绝不输出假图，也绝不去除第三方版权水印这一条永远不变。

> 适用任何"动图"的行业：以服装改款为演示起点，但电商换配色/去瑕疵、家居换软装、房产去杂物、汽车改色换轮毂、摄影去路人、装修出效果图……凡是"图里某个东西想拿掉 / 换掉 / 加上"的场景都归它管。

> 合规红线：不移除第三方版权水印；不处理你无合法授权的素材；涉密/商业机密图请用 --no-public + 本地通道，图绝不出网。

> 搜索触发词（用户常搜的叫法，便于检索）：无痕改图、零痕改图、局部改图、图片局部编辑、指哪改哪、三图同改、指定区域改图、无痕去水印、无痕抠图、局部抠图、白底图局部改图、商品图局部改色、商品图零痕修图。

一、核心能力

1.1 四类改法，覆盖所有"动图"需求

1.2 核心差异：只改你指的地方，其余零改动

一般改图工具是"整张重画"——改完背景、光线、旁边的东西全变了，没法交付。本技能走 生成式造形 + 像素法校色 的组合拳：生成式负责"把形状做出来"，像素法负责"把颜色校回原样"。

客户看不出你改过哪里 —— 这才是能交付的东西。

1.3 零痕分（Zero-Trace Score，对外信任资产）

每次出图附一张保真度评分卡，把"零痕"从内部指标变成客户可验证的信任资产：

别的工具改坏了不告诉你，我们改不动就明说（FAIL / NOT_RUN）——在改坏要赔钱的场景，这是硬通货。

二、出图通道自适应（代码硬编码，不卡死人）

run_pipeline 自动执行 env_check 真实探测
（nvidia-smi → torch.cuda → PowerShell CIM 三级兜底，可识别 VDI/Citrix 下 nvidia-smi 失效）

🟢 LOCAL_FOOOCUS      本机 GPU + 后端就绪 → 本地出图（图不出厂、零按次付费，首选）
🔵 PUBLIC_OPENSOURCE  本地不可用（没装/没条件装 GPU）→ 自动改走公开开源渠道
                      出真图，明确告知「图会出网」；同时提示如何装回本地
🔴 BLOCKED            仅当使用者选 --no-public（隐私模式）且本地不可用 → 禁止出图

• 不卡死：没 GPU 的使用者也能拿到真图——技能自主走开源渠道完成任务，不把人挡在半路。
• 必告知：走公开渠道时输出 📢 告知（图会出网），涉密客户图请用 --no-public + 本地环境。
• 绝不假图：任何通道、任何失败场景，都严禁模拟图/占位图/示意图冒充交付。这是红线。

三、怎么用（极简模式优先）

3.1 🚀 极简模式（v4.7.0 默认推荐，无需签名）

不用填 9 项确认表，也不用签名。给图 + 一句话，加 --no-sign 即可直接出图——意图解析 → 蒙版预览 → 出图 → 闸门②自动质检 → 交付，全程不弹签名。

# 1) 用模板快速生成确认书（只填关键几项意图即可；nlp.mode 设 llm 可让 AI 从一句话转译）
python gate/confirm.py --init > confirm.json

# 2) 直接出图 —— 加 --no-sign 跳过签名①，闸门②自动质检照常强制跑
python gate/run_pipeline.py --confirm confirm.json --a 图A.jpg --b 图B.jpg --execute --no-sign

# 3) 拿图（out.png）+ 闸门②点检报告（checks.json）即完成交付；无需 --sign2
#    需要正式留痕表时再补：python gate/confirm.py --sign1 confirm.json --user 你 --out 表.docx

> 老专业模式（--sign1/--sign2 完整双签）依然可用，无感兼容。签名仅影响"正式留痕 Word 表"，不签也能拿图、能交付。

3.2 纯色改色走传统像素法（推荐，框外保真 99.89%）

# 撞色缝线/纽扣改同色 —— 框外保真 99.89%，大身零改动
python gate/pixel_recolor.py --src A.jpg --out B.png --auto-thread --json report.json

3.3 外接引擎绑定与管理

python gate/engine_registry.py                       # 看有哪些引擎可选 + 就绪状态
python gate/ark_engine.py --guide                    # 小白版绑定向导
python gate/ark_engine.py --save --api-key <KEY> --account <ID> --model <模型名>
python gate/ark_engine.py --check                    # 凭据是否就绪
python gate/ark_engine.py --ping                     # 真实连通性测试
python gate/ark_engine.py --audit                    # ★ 发布前自检：技能包内是否残留凭据

环境探测与通道决策（不出图，只看结论）：

python gate/env_check.py                # 人话环境报告
python gate/backend_router.py           # 自适应通道决策

四、质量闭环（闸门②，强制）与签名（可选）

核心不变：出图后的自动质检（闸门②）永远强制跑——机测 ΔE<3、角度≤3°，任一 FAIL 即禁止交付。这是「改不好明说不合格」的质量铁律，也是 SkillHub TRACE 评测 Trust 4.9 的根。

v4.7.0 改动：原「两步强制签名」对新手偏重，改为可选留痕：

4.1 闸门② 量化点检（默认容差，强制）

铁律：缺数据 = NOT_RUN = 不能交付（不是跳过、更不是假 PASS）。机测项由 --ingest 自动回填；人工项出图后目检回填，然后才走签②（若需要）。

五、出图引擎可插拔架构

v2 只有三条通道（LOCAL/PUBLIC/BLOCKED），v3 升级为6 引擎注册表 + 分级路由 + 自动降级。

5.1 引擎登记表（gate/engine_registry.py）

三条设计原则：① 默认零配置可跑（不填 Key 不报错，上架版护城河）；② 引擎可插拔可降级（主力挂了自动切备用，绝不卡死）；③ 数据分级路由（涉密客户图禁出网，public / client / secret 三档）。

5.2 引擎选择铁律：按任务类型选，不按引擎强弱选

> 这是最有价值的结论，来自三轮真实 API 实测。

实测对照（同一张 A_front.jpg，同一任务"撞色缝线改同色"）：

差距 750 倍。

5.3 火山方舟三层关卡（报错码对照表）

方舟的门禁是三层独立关卡，报错码必须逐层对照：

> ⚠ Seedream ≠ Seedance：前者=图像生成/编辑（我们要的），后者=视频生成。两者在控制台「开通管理」里名字相邻、只差三个字母，是最常见的开通踩坑点。

5.4 传统像素法（gate/pixel_recolor.py）

python gate/pixel_recolor.py --src A.jpg --out B.png --auto-thread --json report.json
python gate/pixel_recolor.py --src A.jpg --out B.png --from-color 192,180,163 --to-color 122,124,134 --tol 40

实现要点（踩坑换来）：
- 检出阈值用实测色值校准：撞色缝线 R-B>25 & R>90（最初用 Lab a/b 阈值误判 28.3%）。
- ⚠ 必须做连通域背景剔除：木地板本身 R-B 也可能 >25，会被误判成缝线。实测某次 2451 个候选像素中 98% 都在木地板上，必须用「邻域主体占比 ≥0.45」剔除，否则会改到地板。
- 替换时保留原有明暗起伏（亮度比例映射），避免改出"死色块"。

5.5 组合拳流水线（gate/hybrid_pipeline.py）—— 解决生成式色偏

问题：Seedream 能生成新结构（口袋/部件），但会给整图带来均匀/非线性色偏（实测大身亮度 −20 ~ −30），交付时颜色对不上原款。

解决：让两个引擎分工——Seedream 负责"造形状"，传统像素法负责"校颜色"。

python gate/hybrid_pipeline.py --orig A.jpg --gen seedream_out.jpg --out fixed.jpg \
    --exclude 0.30,0.62,0.10,0.48 --json report.json
#           ↑ 排除新增部件区（y0,y1,x0,x1 画面比例），避免把新口袋算进色偏基准

校色模式：--mode curve（默认，推荐）/ --mode shift（旧法）。Seedream 的色偏是非线性压暗（暗部压得多、亮部压得少），"整图加同一常数"必然只能对齐一头；曲线按像素亮度分箱查表，最大区域偏差 17.3 → 4.7，且空间均匀、无拼接块。关键：取样掩膜收紧到衣身主体（混入背景会拉偏曲线）+ 箱间平滑/插值（否则出色带）。

5.6 移除部件专用打法

加部件和拆部件，打法完全不同。 加部件看"改了多少"，拆部件看"平不平"。

• 提示词必须用正向句式：Seedream 把"no X"理解成"这里有个 X"。实测"Remove pockets / no seam"改动率 12.1%→ 改为"前片是一整块连续的平整材质"后 22.4% PASS（0.49~0.59×）。
• 验收判据用平整度（边缘强度比），不是"改动率"：口袋细线像素占比小，改动率低会假 FAIL。判据：出图边缘强度 / 干净裙面边缘强度 ≤ 2.5 → PASS。
• 必须排除衣物固有结构线（侧缝/公主线/腰省）：否则把结构线算成"残留"，误报 156%。

5.7 双动作与位置锚点

"拆一处 + 加一处"同时做，比单动作难一个量级：

• 位置必须用图上可见参照物做锚点（腰头缝/原部件轮廓/侧缝），禁用 upper / lower / middle front 等模糊空间词——模型对人类空间词理解不一致，实测会把口袋掉到大腿中部。
• 色偏全局向量只能对齐一头 → 优先保主体（客户看的是衣服），背景差异如实标注并给双版本。
• 同材质同色检测的基准区必须与目标区光照相当（跨明暗交界取样会误报色差 81）。

5.8 三图同改 / 级联嫁接（v4.1.0）

一次改图可分别指定「形状来自 B、材质来自 C、颜色来自 A」，也可把上一步输出作为下一步的 B 形成级联（猪嘴 → 马头 → 牛身实测驱动）。每一步独立走流程、独立质检。诚实记录：闸门② FAIL 不是 bug，是技能按契约真实反馈；公开渠道版本应标注为「概念效果图」，本地通道版本才是「可交付零痕改图」。

六、真实改图案例与前后对比

> 说明：以下案例均为真实实测数据（含机测 ΔE / 边缘强度比），非示意。前后对比图请放入技能目录 demos/cases/（命名：案例名_原图.jpg / 案例名_蒙版.jpg / 案例名_出图.jpg），发布包默认不含该目录（属作者落图模板），文档文字案例随 SKILL.md 一同发布，保证可读。

6.1 案例 A：纯色改色（缝线改同色）—— 框外保真 99.89%

• 任务：撞色缝线改为大身同色。
• 打法：pixel_recolor.py --auto-thread（自动识别撞色缝线）。
• 结果：改动像素 0.11%，框外保真 99.89%，大身区域变化 0.0000（完全未动）。

6.2 案例 B：移除部件（拆两侧口袋）—— 平整度 PASS

• 任务：白裙子移除两侧口袋。
• 打法：正向提示词（"前片是一整块连续的平整材质"）+ 平整度点检。
• 结果：左口袋边缘强度 2.56 → 1.37（0.59×），右口袋 2.98 → 1.13（0.49×），均 ≤ 2.5 PASS；组合拳校色后色偏 −4.3 → −0。

6.3 案例 C：结构改造（斜插袋嫁接）—— 结构+位置一轮全对

• 任务：深灰束脚裤圆角贴袋 → 移除；卡其工装裤斜插袋（welt）嫁接到同位置。
• 打法：锚点式位置描述（"top edge flush against the bottom edge of the waistband"）+ 曲线校色 --mode curve。
• 结果：结构 + 位置一轮全对；最大区域色偏 4.7（曲线模式），无拼接块。

6.4 案例 D：三图同改（猪嘴 → 马头 → 牛身）—— 诚实 FAIL 拦截

• Stage 1（猪嘴嫁马头）：PASS，耳朵/眼睛/鬃毛未动。
• Stage 2（带猪鼻马脸嫁牛身，shape=B, fabric/color=A）：颜色 ΔE=21.18 FAIL、纹理角度差 9.4° FAIL——公开渠道部分保留 B 的颜色/材质。
• 解药：混合来源提示词强化（"recolor to match image A"）+ 本地通道优先 + 后处理校色。诚实记录 FAIL，不假 PASS。

七、常见问题 FAQ（反模式与高频坑）

Q1：改出来颜色不对 / 整图色偏大怎么办？

• 原因：生成式引擎（seedream 等）出图带来整图均匀/非线性色偏（实测大身亮度 −20~−30）。
• 解药：① 走「组合拳」自动曲线校色（hybrid_pipeline.py --mode curve，默认开），最大区域偏差 17.3 → 4.7；② 纯色改色直接走传统像素法 pixel_recolor.py（框外保真 99.89%，大身零改动）。
• 仍偏：检查取样掩膜是否混入背景；同材质同色基准区必须与目标区光照相当（跨明暗交界会误报色差 81）。

Q2：蒙版位置怎么调？落点不准怎么办？

• 位置必须用图上可见参照物做锚点（腰头缝/原部件轮廓/侧缝），禁用 upper/lower/middle 等模糊空间词（模型理解与人类不一致，实测会把口袋掉到大腿中部）。
• 微调：确认表里位置项支持 1cm 网格 + 方向键微挪；系统自动做 wearer_frame 镜像归一化，确认回译只输出「着装者左右」坐标，结构上消灭镜像 bug。

Q3：改图失败（出图为空 / 通道报错 / 契约导出）常见原因与应对？

• 本地无 GPU：自动改走公开开源渠道出真图（图出网，会告知）；或装本地 Fooocus 后端（首次约 10–30 分钟含模型下载）。
• 云 API 401/404/429：见 5.3 三层关卡对照表（Key 格式 / 模型未开通 / 安全体验模式额度）。
• 隐私模式 --no-public 且本地不可用：主动 BLOCKED（exit 2），不出假图——这是设计内的安全拦截，不是 bug。
• 契约导出 exit 3：正常现象，平台按契约真实生成后 --ingest 回灌即可。

Q4：手机拍摄的图片能用吗？

• 能。只要满足素材受理：短边 ≥ 1024px、摆位底图是平铺图/线稿（非透视变形大图）。手机原图通常够清晰；夜景/模糊/强反光会拉低框外保真度，建议光线充足、对焦清晰。涉密/商业机密图走 --no-public + 本地通道，图绝不出网。

Q5：图片清晰度 / 尺寸有上限或下限吗？

• 下限：短边 ≥ 1024px（低于则素材受理拦截，框外保真度与蒙版精度不足）。
• 上限：无硬上限，但超大图（>4000px）本地推理更慢、显存更吃紧；公开渠道按画幅跟随处理。建议出图前合理裁剪到目标区域。
• 画幅：引擎支持画幅跟随（契约字段 render_size / aspect_error），尽量保持原图比例。

八、高频失败原因集中排查表

九、目录结构（符合 Open WorkBuddy 上架规范：≤2 级目录）

zero-trace-image-edit/
├── SKILL.md                            # 本文件（九字段 frontmatter）
├── LICENSE.txt                         # MIT 许可（平台要求 .txt 后缀）
├── _icon.png                           # 技能图标
├── region_coords.json                  # 区域预设（通用场景可自行扩充坐标）
├── prompt_template.txt                 # 提示词英文模板
├── payload_demo.json                   # 演示载荷
├── auto_edit.py                        # 出图引擎（本地 Fooocus-API 调用契约）
├── demos/cases/                        # 真实前后对比落图模板（作者用，发布包默认不含）
└── gate/                               # ★ 质量闭环 + 引擎层
    ├── wearer_frame.py                 # 镜像归一化 + 坐标↔人话双向翻译
    ├── checks.py                       # 闸门② 量化点检（ΔE/角度/cm/%）
    ├── confirm.py                      # 闸门① 校验 + 双签驱动（可选）
    ├── gen_confirmation_table.py       # 确认表生成器
    ├── sample_confirmation.json        # 确认模板（9 项示例值）
    ├── env_check.py                    # 真实环境探测（GPU 三级兜底）
    ├── backend_router.py               # 通道自适应决策（LOCAL/PUBLIC/BLOCKED）
    ├── engine_registry.py              # 引擎登记表 + 分级路由 + 画幅跟随
    ├── ark_engine.py                   # 火山方舟适配器（凭据三级查找/向导/自检）
    ├── pixel_recolor.py                # 传统像素法（局部定向改色 + 连通域背景剔除）
    ├── hybrid_pipeline.py              # 组合拳（生成式出形 + 像素法校色；curve/shift 双模式）
    ├── tone_match.py                   # 亮度曲线校色（分箱查表+平滑插值）
    ├── check_removal.py                # 移除部件点检（平整度判据，防假FAIL/假残留）
    └── run_pipeline.py                 # S0–S8 端到端编排（含 --no-sign 极简模式）

十、版本历史（精简）

• v4.7.1（2026-10-10）：OWB 类目纠正——改回本技能实测通过 OWB 的类目「工具 > 图片处理」（局部图编辑不改背景/不生成新身份，个人账号可直接过审）；清除文档误用类目字样；author 兜底值对齐外部身份规范。其余同 v4.7.0。
• v4.7.0（2026-10-10）：按 SkillHub TRACE 评测（综合 4.6/优秀）短板定向优化。① 去掉两步强制签名，run_pipeline.py 新增 --no-sign 极简模式，出图/交付不再强制签名，双签确认表改可选留痕，闸门②自动质检强制保留；② 新增第七/八节 FAQ 与高频失败排查表（直击评测"反模式与 FAQ 3.8"）；③ 新增第六/九节真实案例与目录规范（直击"文档质量 4.0"）；④ 文档整体重写为干净专业版，砍掉冗余变更日志噪音。
• v4.6.4（2026-10-08）：按《三平台技能上架规则》对齐 OWB（category 用实测通过的「工具 > 图片处理」、author 外部身份、别名统一方案 B）。
• v4.6.2（2026-09-30）：文档诚实化——去掉"免费/零依赖/绝对本地"假词，如实披露本地优先 + 火山方舟云兜底（seedream/豆包，按调用计费，图出网告知）。
• v4.0.0–v4.1.0（2026-09-11~14）：从"服装专用"升级为通用图片局部编辑；新增三图同改/级联嫁接。
• v3.0.0–v3.4.0（2026-09-11）：引擎可插拔架构、传统像素法、组合拳曲线校色、移除/双动作打法（全部源于真实 API 实测）。

十一、Open WorkBuddy 上架合规自检

• ✅ frontmatter 九字段齐全（name/display_name/display_name_en/description/description_zh/description_en/category/version/author）+ agent_created
• ✅ 目录层级 ≤ 2 级（SKILL.md 在包根、gate/ 一级子目录）
• ✅ LICENSE.txt（.txt 后缀规避白名单拦截）；_icon.png 在位
• ✅ 包体 < 3MB；frontmatter 字段值 YAML 安全（英文描述加引号、无裸 ASCII 冒号）
• ✅ author 按外部开发者身份规范填写；包内不含个人邮箱/手机号/证件号/云凭据
• ✅ category 工具 > 图片处理（image-edit 局部图编辑实测通过 OWB 的类目，个人账号可直接过审）