# 游戏素材大师 · 详细工程文档

> 本文档由 README 的完整版迁来，保留算法细节、自检契约与历史踩坑记录。
> 简洁的入门文档见 [../README.md](../README.md)。

---

# 游戏素材大师 · DSH 插件

从一张设定图出发，批量产出游戏要用的角色素材。**火山方舟 Seedream** 负责生图，
**MiniMax** 负责图生视频，抠绿幕与合成全部在本地用 ffmpeg + 内置 JS 完成——
不需要任何系统图像库，也不需要把素材传到第三方服务。

插件包含四个功能模块，共用同一套 API 配置与抠像默认值：

| 模块 | 做什么 |
|---|---|
| **八方向图生成** | 一张人物设定图 → 8 方位 × 8 帧精灵图（含行走动画验收与 WASD 操控预览） |
| **图片生成** | 按提示词出图，可带参考图 → 可一键抠绿幕导出透明 PNG |
| **序列帧生成** | 首帧图 **或** 参考图+参考视频 → 生成视频 → 抽帧 → 抠像 → 横向合成，并可循环播放预览 |
| **骨骼动画生成**（实验性） | 角色整图 → 自动拆件 → 装配定位 → 推骨骼与动画（待机/行走/奔跑/挥手/跳跃/攻击）→ 打包 Spine 图集 |

> ⚠️ 骨骼动画生成是**实验性模块**：界面上页签带角标、每次进入弹窗说明、模块内常驻提示条
> （`RigExperimentalDialog` / `RigExperimentalBar` / `MODULES[].experimental`）。功能不完善，
> 共建入口见 [GitHub 仓库](https://github.com/universe-st/dsh-game-material-master)。

每个阶段都有独立的验收界面：看图、改提示词、单独重跑、打「通过」。任何一步不满意都可以只重做那一步。

四个模块的**全部功能都可以通过对话调用**：agent 用工具驱动同一条流水线，
多步流程（八方向图这种）能自己推进、等待、审查，也可以在每一步停下来让你验收——
详见下面的[对话调用](#对话调用agent-也能驱动整条流水线)。

---

## 一些绕不开的坑（先说，省得踩）

- **不要用「剪影」这个词写提示词。** 实测生图模型会按字面把角色画成纯黑轮廓。
- **提示词里要区分「转身」和「视线」。** 只写「朝画面左上方」时模型会理解成抬头仰视，
  必须补一句「只绕竖轴转身，禁止抬头低头，视线始终水平」。
- **图生视频不保证守住纯色背景。** 同一段素材里有的帧背景保持绿色，有的会逐渐打光成橙黄渐变。
  所以抠像不能只认绿色——见下面的「抠像」。
- **重复提交会白花钱。** 三个模块都做了重复提交拦截：同一张图 / 同一段视频在跑时再点一次会被拒绝。
  agent 走对话调用时同样受这条约束（工具层不重复拦一次，报错信息才清楚）。

---

## 对话调用：agent 也能驱动整条流水线

插件挂载时会把自己的控制面注册成一组模型工具，并追加一段系统提示词，
约定**固定流程**与验收协议。所以「帮我做个八方向的角色」这句话本身就能跑完整条链路。

### 工具

| 工具 | 作用 |
|---|---|
| `game_material_intake` | **固定流程第 0 步**：按真实状态算出「还缺哪些关键参数」与「必须先解决的阻塞」，并把「自动审核 / 每步人工审核」这个必问项一起交出来 |
| `game_material_call` | 万能通道：插件界面上有的功能都能调（63 个方法，含配置、提示词、抠像参数、删除等），描述里逐个列了入参与用途 |
| `game_material_upload` | 按**本机路径**上传素材（源图 / 参考图 / 首尾帧 / 参考视频），宿主自己读盘，不用把 base64 贴进对话 |
| `game_material_reviewMode` | 记录用户选的审核模式，存在项目 / 任务上；界面与对话读写同一份 |
| `game_material_status` | 读进度：项目 / 任务清单，或某个目标的阶段进度与产物 URL |
| `game_material_wait` | 阻塞等待「没有任务在跑」或超时（默认 120s，上限 900s），回来就是可审查状态 |
| `game_material_review` | 出**验收包**：每个产物的绝对 URL、状态、通过标记、报错与建议的下一步 |
| `game_material_approve` | 打「通过 / 取消通过」（八方向图按阶段+方位，图片按张，序列帧按步骤，骨骼动画按阶段+部件） |

底层没有第二套实现：工具直接复用界面用的那个 Typert 远程服务，所以
「界面上做到的事」与「对话里做到的事」永远是同一件事、同一份数据。

### 固定流程

```
第 0 步  先问，再动手
         agent 必须先用 game_material_intake 把缺的参数问清楚，
         并且必须问「自动审核 还是 每一步人工审核」——合并成一次提问。
         两个问题都拿到答复之前，不允许调用任何生成 / 删除类方法。
第 1 步  逐阶段推进（八方向图：images → videos → frames → sheet；
         骨骼动画：parts → layout → rig → atlas，其中只有 parts 花钱）
         每次提交类调用之后立刻 game_material_wait。
第 2 步  每步都审：game_material_review 看逐项 status / error / URL。
第 3 步  按审核模式分岔
         auto   → agent 自己判断没问题就 approve 并进入下一步
         manual → 贴出验收链接并停下等用户回复，用户说「通过」才继续
```

审核模式也可以在界面上直接改（四个模块都有下拉），因为它就是同一份数据。
没设置时界面显示「未设置（对话里会先问）」。

### 点链接切界面

工具返回里的 `openUrl` 是给用户点的深链接，形如：

```
http://127.0.0.1:43120/?dsh-gmm=1&module=sprite&project=p…&stage=videos
```

agent 会把它原样写成 Markdown 链接贴出来。用户点一下：

- 浏览器半区装了**捕获阶段的点击拦截器**，命中就 `preventDefault` 原地切到
  「游戏素材大师」面板，并落到对应模块 / 项目 / 阶段——不跳转、不新开标签；
- 若用户用中键 / Ctrl+点击强制新开标签页，链接会真的被打开，应用在
  `/?dsh-gmm=…` 上正常启动，插件读到参数后完成同样的切换（两条路径共用同一份意图）。

为什么链接必须是 `http(s)`：会话正文的 Markdown 渲染器对链接做了协议白名单
（只放行 http/https/mailto），自定义 scheme 会被丢掉、连 `<a>` 都不生成。
又因为宿主不知道对外 origin（可能被反代改写），浏览器半区会在挂载时把自己真实的
`location.origin` 上报给宿主（`reportClientOrigin`）。没收到上报时退化成
`http://localhost` —— 拦截是按参数匹配的，origin 不对也不影响点击。

拦截器只认 `dsh-gmm` 参数，其余链接（含站外的）一律放行。

---

## 安装

```bash
dsh plugin --profile web add /path/to/dsh-game-material-master
```

装完**重启 DSH**（新增 bundle 只在启动时读取）。

> **改了代码之后**：浏览器半区是按磁盘上的 `lib/client.js` 现取的，**刷新浏览器**就能用上；
> 宿主半区（工具注册、系统提示词、远程方法）是启动时装入的，**必须重启 DSH**。
> `node scripts/verify-live-bundle.mjs` 可以确认运行中的宿主到底在提供哪一版浏览器束。

- 需要宿主提供 `webServer` 与 `typert`，二者由 `@deepseek-ai/dsh-base` / `dsh-web-app` 提供，无需额外依赖。
- 需要 **ffmpeg / ffprobe** 在 `PATH` 上（macOS：`brew install ffmpeg`），
  也可用 `FFMPEG_PATH` / `FFPROBE_PATH` 指定绝对路径。设置页会显示探测结果。
- 本包**没有任何运行时 npm 依赖**：`zod`、`@deepseek-ai/dsh-typert-protocol`、`@deepseek-ai/cordis`
  都从 DSH 自身的安装树解析，避免出现两份不同版本的实例。

> 从旧版本（`dsh-8dir-sprites`）升级时，首次启动会把数据目录 `8dir-sprites/`
> 整体迁移到 `game-material-master/`，已有项目和配置无缝接上。

## 配置

**设置 → 游戏素材大师**：

| 项 | 说明 |
|---|---|
| 火山方舟 API Key | 「测试连接」会**真实生成一张 1K 小图**（产生少量费用），同时验证 Key 与模型 / 接入点 |
| 生图模型 | 默认 `doubao-seedream-4-0-250828`；也可选 4.5 / 5.0 Lite / Pro，或填自定义接入点 ID |
| MiniMax API Key | 「测试连接」只查一个不存在的任务，**免费**，能区分 Key 无效与其它错误 |
| 视频模型 | 默认 `MiniMax-H3`。选 H3/H3-Max 自动走 v2 协议，选 Hailuo/I2V 走 v1；**优云智算版 H3** 在同一个下拉里显式选择 |
| Base URL | **主机根**，不含 `/v1`、`/v2`。国内站 `https://api.minimax.cn`，国际站 `https://api.minimaxi.com`。选中「优云智算版 H3」时该字段固定为 `https://cp.compshare.cn`、不可编辑 |
| 默认参数 | 单格宽高、抽帧张数与工作尺寸、像素块边长、抠像阈值等 |

Key 只写入本机 `<DSH_HOME>/game-material-master/config.json`，回传界面时始终脱敏（只给尾号）。

> **模型是插件级设置，三个模块共用。** 「生图模型」「视频模型」只在设置页里改，
> 图片任务 / 序列帧任务内部**不允许**再存一份自己的模型副本——模块里那两个字段是
> 只读展示。原因：网关地址与 API Key 都是全局的，任务里若留一份旧模型快照，
> 切换模型后就会把请求打到错误网关（实测：任务存官方 H3 + 全局切优云智算 →
> `cp.compshare.cn/v2/…` 404）。任务在保存与提交时会自动对齐当前模型，
> 时长 / 分辨率档位也一并按当前模型收敛。

### 视频参数与模型的对应关系

| 视频模型（下拉选项） | 协议 | 分辨率 | 时长 |
|---|---|---|---|
| `MiniMax-H3` | v2 | `2K` / `768P` | 4~15 秒 |
| `MiniMax-H3 优云智算` | v2 | `2K` / `1080P` / `768P` | 4~30 秒 |
| `MiniMax-H3-Max` | v2 | `768P` / `480P`（不支持 2K） | 5~15 秒 |
| `MiniMax-Hailuo-02` | v1 | `768P` / `1080P` | 6 / 10 秒 |
| `I2V-01` / `I2V-01-Director` | v1 | `720P` | 6 秒 |

> **优云智算版 H3** 是 MiniMax H3 的第三方网关版：与官方 H3 是同一个模型，但走
> `https://cp.compshare.cn`，请求路径多一层 `/minimax`（`/minimax/v2/video_generation`），
> 分辨率支持 1080P 后置超分，时长放宽到 4~30 秒。
>
> 它是一个**显式选项**：在「视频模型」下拉里选择 `MiniMax-H3 优云智算` 即启用，
> 插件**不会**根据 Base URL 或 Key 前缀自动判断。选中后 Base URL、路径前缀、
> 分辨率/时长档位全部自动跟着它走；切回官方模型时 Base URL 自动还原。

切换模型时非法值会被自动收敛（例如从 Hailuo 换到 H3 时 `1080P` → `2K`）。
**参考图 / 参考视频模式是 v2 才有的能力**，选 v1 模型时会明确报错而不是静默失败。

---

## 模块一：八方向图生成

### 方位约定

这是 **RPG 地图上的八方向行走**，不是「抬头 / 低头」。约定画面上方为北：

| 方位 | 屏幕朝向 | 能看到什么 |
|---|---|---|
| **北 N** | 朝画面**上**方走 | 后脑勺，**完全看不到脸** |
| **东北 NE** | 朝画面右上走 | 斜背面，**完全看不到脸** |
| **东 E** | 朝画面**右**走 | **右侧脸**（纯侧面） |
| **东南 SE** | 朝画面右下走 | 正脸，转向右侧约 45° |
| **南 S** | 朝画面**下**方走 | **完整正脸** |
| **西南 SW** | 朝画面左下走 | 正脸，转向左侧约 45° |
| **西 W** | 朝画面**左**走 | **左侧脸**（纯侧面） |
| **西北 NW** | 朝画面左上走 | 斜背面，**完全看不到脸** |

提示词把**转身**（`{facing}`）和**可见部位**（`{visibility}`）分成两段写，
这是为了避开上面说的「抬头」坑。

### 生成顺序

依赖是**有向的**，所以生成也一层层来；同层内并发（并发数可配）：

| 顺序 | 方位 | 参考图 |
|---|---|---|
| 1 | 南（正对镜头） | 源图 |
| 2 | 北（背对镜头） | 南 |
| 3 | 西南 / 东南 | 南 |
| 4 | 西北 / 东北 | 北 |
| 5 | 西 / 东 | 南 **+** 北 |

重新生成某个方向时，依赖它的下游会自动标成 **「需重做」**。

### 阶段①的两种生成方式：转圈截帧（默认）与逐方向生图

`Project.imageMode` 决定阶段①怎么产出那八张 `images/<方向>.png`；**两条路的产物形态完全相同**，
所以阶段②（行走视频）、③（抽帧）、④（整图）完全不必知道用的是哪一种。

| | `turn` 转圈截帧（默认） | `direct` 逐方向生图（备选） |
|---|---|---|
| 怎么来 | 一段「原地匀速转一整圈」的绿幕视频，按时间轴截出八个方向 | 八个方向各自一次 Seedream 生图，按依赖顺序 |
| 花费 | 一次视频调用（几分钟） | 八次生图调用 |
| 一致性 | **好**：八个方向同源（同一个角色、同一段光线、同一套画风） | 一般：模型每次都要「重新理解」角色，脸型/发色/服装容易漂移 |
| 清晰度 | 受视频分辨率限制（默认 768P/2K） | 受生图分辨率限制（默认 2K，更高） |
| 可调 | 时间轴上八个圆圈，随时重切（本机、免费） | 每个方向单独重跑 |

新项目默认 `turn`；**老项目**（还没有 `imageMode` 字段时建的）自动沿用 `direct`——
它们已经有八张图了，直接跳到空白的转圈页只会让人以为产物丢了。切换用
`setImageMode({projectId, mode})`，切换**不删任何产物**。

转圈模式的三步：

1. `runTurnVideo({projectId})`：一次 MiniMax 调用，整圈只有这一段视频。首帧优先用
   已经存在的 `images/front.png`（正面绿幕图），没有就退回源图——源图不一定是绿幕，
   所以提示词里明确要求「纯色绿幕 #00FF00」，由模型把背景重画成绿幕。实际用的是哪张
   记在 `turn.video.firstFrame` 里，排查「第一帧就不是正面」时全靠它。
2. 视频落地后宿主**自动**抽候选帧（本机 ffmpeg，免费）：默认 32 张，按
   `fps = 张数 / 时长` 均匀取样，第 i 张对应 `i × 时长 / 张数` 秒；同时把整圈缩略条带
   写进 `turn/strip.png`——界面上那八个圆圈就是对着这条条带拖的。
3. 按 `turn.frames.picks`（八个方向各自选中第几帧）把八张方向图切出来，覆盖
   `images/<方向>.png`。这一步只读 `turn/raw.bin` 缓存，所以拖动圆圈是**本地、免费**的。

**为什么位置必须可拖**：默认位置假设「视频从正面开始、匀速转满一圈、方向是顺时针」，
而模型经常不遵守——起步有一两秒静止、转速前快后慢、或者干脆往反方向转。任何一种都
会让八个默认位置整体偏掉，所以轴上给了八个圆圈（`setTurnPick({projectId,key,index})`）
和「换个转圈方向重排」（`resetTurnPicks({projectId,direction})`）。拖动只重切那一张，
但会**作废该方向的行走视频与序列帧**（它们拍的是另一个朝向），整图同样作废。

改候选帧数（`saveSettings({turnFrameCount})`，8~64）会**自动重抽**，并把用户拖过的位置
按比例换算（32 帧里的第 12 帧 → 8 帧里的第 6 帧）；直接保留下标会把八个位置整体打乱。
另外，八个位置在**第一次**抽帧时按这次的张数重新等分——否则「新建项目默认 32、第一次
却抽 16 张」时，四个方向会一起被夹到最后一帧。

### 统一附加提示词

「八方向绿幕图」这一步有一个**统一附加提示词**输入框：非空时会被追加到**每一张**生图
提示词末尾，用来写跨方向的共同注意事项（例如「必须穿同一双靴子」「不要出现文字」）。
改一次全部生效，不必逐个方向去改。每个方向仍然可以单独覆盖自己的提示词。

### 行走视频

提示词要求**固定机位 / 固定背景 / 原地走三步**。八个任务并发提交，宿主后台每 15 秒轮询一次；
**提交完可以离开页面**，插件重启后还会把没跑完的任务接上。

某个方向不满意可以点**「重新生成」**：宿主会先作废这一段旧视频**和它抽出来的序列帧**
（整图同样作废，需要重新抽帧再合成），然后重新提交——帧是从视频里抽的，不重抽就会
把上一版动作混进整图。**其它方向不受影响**。工具栏的「生成全部视频」只提交还没完成的
方向，已经成片的不会重跑；要是八个方向都已完成，它会直接告诉你该点哪个按钮而不是
转一圈了事。

### 抽帧与合成

`ffmpeg` 用 `fps = 帧数 / 视频时长` 按时长平均取样。抽帧抽到的是**工作尺寸**
（长边上限，默认 768），不是最终格子尺寸——自动裁剪、统一缩放和像素量化都在 JS 里做，
这样八个方向才能共享同一个裁剪框、脚底对齐同一条基线。

### 行走预览

用 **WASD 或方向键**操控角色，验证八方向接起来顺不顺：

- 角色以**脚底中心**为锚点，帧推进按**走过的距离**而不是时间——步频和移动速度才对得上
- 「播放速度」只改步频快慢，「移动速度」只改走得多快，两者互不影响
- 切图用的是**整图自己记录的**行序与格子参数，所以改完行序即使还没重新合成，预览也不会取错方向
- 需要**点击画面取得键盘焦点**后才响应按键，避免和输入框抢键

---

## 模块二：图片生成

按提示词出图，可选带参考图（最多 10 张；多张时可在提示词里写「图一」「图二」）。
每张生成完，若开着抠像会自动抠一遍；也可以**把已有图片直接传进来只做抠像**——
这样它同时也是一个通用的绿幕抠像工具。

- 生成张数 1~8，按 Seedream 刊例约 0.2 元/张
- 每张可单独重新生成、删除、下载透明 PNG
- 每张会记录**背景占比**，用来判断抠像是否可信（占比异常说明绿幕没生成好）
- 每张可单独打「通过」，也可以一键全部通过；对话里的 `game_material_approve` 改的是同一份标记

---

## 模块三：序列帧生成

两种输入模式，**平台规定互斥**：

- **首尾帧模式**：上传首帧图（必填）+ 尾帧图（选填）
- **多模态参考模式**：上传参考图（≤9 张）+ 参考视频（≤3 段，每段 2~15 秒）

> 参考视频要转成 base64 内联在请求里，平台请求体上限 64 MB，所以本地文件卡在 40 MB；
> 更大的文件平台要求改用公网 URL。

流程：**生成视频 → 抽帧（张数可配）→ 抠像 → 横向合成**，其中抽帧完成后会自动接着抠像与合成。
界面里可以：

- 播放生成出来的视频（`<video>`，支持拖动进度条）
- **循环播放抠像后的序列帧**（可调 fps 与缩放），直接判断动作连贯性与抠像边缘稳定性
- 导出横向条图与逐帧 PNG
- 对「视频 / 抽帧 / 条图」三步各自打「通过」；对话里的 `game_material_approve` 改的是同一份标记

---

## 模块四：骨骼动画生成

把一张角色整图变成**可用的 Spine 骨骼动画**：拆件 → 装配定位 → 推骨骼与动画 → 打包图集。
整条流程参考并移植了 [spine-animation-ai](https://github.com/GenielabsOpenSource/spine-animation-ai)
（Genielabs 的 Claude skill），但做了两件它没有的事：

1. **每一步都可视化、可单独重跑**。参考项目是一条 Python 脚本跑到底，任何一步出问题都
   只能从头再来；这里四个阶段各有自己的状态、验收打标与重跑入口。
2. **不依赖 OpenCV / Python**。定位改用「多尺度掩码模板匹配 + 金字塔由粗到细搜索」，
   分割用纯 JS 连通域，全部跑在插件进程里。

| 阶段 | 做什么 | 花钱吗 | 重跑粒度 |
|---|---|---|---|
| ① 拆件 | 生图模型把角色拆成 16 个部件（4×4 网格），再自动分割成逐件透明 PNG | **一次 Seedream 生图**（约 0.2 元） | 整张重生成 / 用现有图重新分割（免费）/ 逐件上传替换 |
| ①.5 质检 | 自动查「同一部位被画了多遍」「装配相似度整体偏低」「部件数明显多出来」，并给出建议 | 免费（本地算） | 随时重跑 |
| ② 装配定位 | 把部件摆回参考姿态，出「参考图 \| 合成图」对比图 | 免费（本地算） | 整体、或只重跑指定部件 |
| ③ 骨骼与动画 | 按部件语义推骨骼层级 + 六个动画预设，出 `skeleton.json`（Spine 4.2）与 `skeleton_ske.json`（DragonBones 5.5），并给可播放预览 | 免费 | 整体、或逐台动画编辑关键帧 |
| ④ 图集 | 打包纹理图集，同时出 `.atlas`（Spine）与 `_tex.json`（DragonBones） | 免费 | 整体 |

- **每一格画什么由格子的名字决定**，提示词里逐格写成 `hip = hip / pelvis (…)` 这样的
  「名字 = 部位描述」。网格位置决定部件名，而骨架是拿「名字 → 语义」推的——
  实测标着 `hip` 的格子画出裙子、标着 `neck` 的格子画出大腿，**骨架从第一根骨头起就是错的**。
- **每个部位只画一次**。模型会为了填满网格把同一部位画进多个格子（实测 4 段大腿、
  4 只鞋、3 条袖子），多出来的会被硬塞进不相干的骨骼位。
- **左右成对的部件是镜像，不是复制**（实测两条「左右袖」同向重合 0.901）。
- **是「切图」不是「重画」**：格子名只决定切哪块，外观一律照参考图。
  写成「按解剖结构补全被遮住的部位」时，模型把 `hip` 画成了**短裤**（参考图里是裙子），
  外观与参考图不符、模板匹配全废；改成「照参考图切」之后 `hip` 恢复成裙子 + 围裙 + 鲸鱼尾。

> **拆件质量 ≠ 自动装配质量。** 即使拆件完全正确（16 块、命名对、左右镜像、画风一致），
> 模板匹配对**服装裁片**仍然失手——裁片只覆盖参考图里的一小块，而匹配要求整块相似。
> 拆件图里匹配得好的全是「封闭、独特、无遮挡」的件（领子 0.66、上衣 0.67、袖子 0.63~0.72、
> 鞋 0.60），头和腿这些「与身体连成一片」的件只有 0.10~0.28。所以下面那句
> 「自动摆位只是起点」是字面意思，不是客套。

### 拆件质检：拆件"看起来成功了"其实不可用

这是**被真实数据逼出来**的一步。用一张真实立绘跑完 ①，界面显示「部件（18）——逐件验收」一切正常，
装配却把「头」摆到了「大腿」下面。逐块看图之后发现三件事同时成立：

1. **同一个部位被画进了多个网格格子**：4 段「大腿→膝盖」、4 只「鞋袜脚」、3 条「整袖」，
   实际只有 12 块是真实部位。
2. **网格位置决定部件名，模型却按自己的理解画**：第 2 格叫「胯部」画的是裙子、
   第 9 格叫「脖子」画的是大腿。骨架是拿「名字 → 语义」推的，**名字错了骨架从第一根骨头起就是错的**。
3. **部件是重新绘制的**，与参考图像素不像，模板匹配只能挑一个「不那么错」的位置——
   相似度 0.08~0.50，而界面照样显示「已定位 17/18」。

三种都不是报错，而是"看起来成功了"。所以自动质检把它们变成明确结论：

| 检查 | 怎么做 | 判定 |
|---|---|---|
| 重复件 | 裁到内容包围盒 → 归一化 64×64 alpha 轮廓 → 两两 IoU | 同向 IoU ≥ 0.86 并组报错 |
| **左右件 vs 重复件** | 把 B 水平翻转后再比一次 | 镜像明显高于同向 = 左右各一，**不算重复** |
| 对称形状 | 同向与镜像都很高 | 分不出，降级为提示让人确认 |
| 装配质量 | 平均/最低相似度、低于 0.5 / 0.3 的个数 | 均值 < 0.5 报错 + 给出「先给先验再重跑」的命令 |
| 部件数超标 | 与「参考图目测约几个部位」比 | 超出报错（这项只能靠视觉，所以留成手填，给不出就不判断） |

实测判别力（真实部件量出来的）：同向重画的配对同向 0.90~0.98 / 镜像只有 0.15~0.75；
真·左右件正好相反（同向 0.66~0.76 / 镜像 0.93~0.96）。**镜像判别是关键**——
少了它会把「左右两条手臂」误报成重复，用户照做就缺一只手。

> 顺带修掉一个数据一致性问题：手工摆过位置的部件仍带着**旧的匹配分数**，
> 质检会拿这个陈旧数字当「这次装配准不准」的证据（手工摆对之后仍报「相似度 0.326，不可信」）。
> 现在摆位时会清掉 `score`/`coverage`，质检也跳过 `manual` 的项。

### 语义层：角色 / 父级 / 锚点

拆件之后、装配之前，每个部件会拿到一份**显式语义**：

| 字段 | 作用 | 默认从哪来 |
|---|---|---|
| `role` | 语义角色（头/脖子/躯干/胯/上臂/小臂/手/大腿/小腿/脚/头发/衣料/配饰/武器） | 按部件名关键词推断（支持中文名） |
| `parent` | 父部件名，决定骨骼挂在谁身上 | 由「角色 → 父角色」链推导 |
| `proximal` / `distal` | 近端 / 远端锚点（归一化到部件包围盒） | 角色默认值（四肢取上端为近端） |
| `tags` | 自由标签，供按组批量操作 | 角色名 + 左右侧 |

**为什么要有它**：以前骨架层级完全由「部件叫什么名字」隐式决定（按名字查固定表）。
这让名字承担了它承担不起的责任——模型没按网格摆、或角色不是标准人形时，用户只能
靠改名间接影响骨架，而改名又会连带动画。现在语义是数据：界面上改一次角色/父级/锚点，
骨架立刻跟着变。

两条设计约束：

1. **不填表也能跑**。所有字段都有推断兜底，所以历史任务与「直接上传部件 PNG」都不需要
   先填一张表；AI 或人之后只改**不对的那几条**。
2. **改语义不动装配**。语义只影响骨骼推导，所以改它会作废③骨骼与④图集，但**不会**
   作废②里已经摆好的位置——否则用户每试一次角色就要重摆一遍。

校验会给 error 与 warning 两级诊断（重名 / 未知角色 / 父级不存在 / 成环 / 锚点退化 /
**头的祖先链经过肢体** / 左右镜像缺失），并且**永远返回可用的语义表**，
让界面能显示「哪一条、为什么不对」，而不是一个保存失败的红点。

### 骨骼的手工偏移：三通道

骨骼的局部姿势被拆成两层（照搬 DragonBones `Bone.offsetMode = Additive` 的思路）：

```
local = origin ⊕ offset        （⊕ 对位移/旋转是加法）
```

- **`origin`** 由②的装配位置 + 语义层的锚点**算出来**，每次重跑都会被重算；
- **`offset`** 是**人**给出的偏置，**任何自动重跑都不碰它**。

所以「重新推骨骼」不会丢掉你调过的偏置，而「清除偏移」就是回到几何推出来的姿势。
这一条是本模块最关键的承诺，`scripts/verify-rig-module.mjs` 与 Playwright 端到端
各有一条断言盯着（重跑后 `0° → 8°` 仍在）。

实现上有一处必须注意：子骨骼的局部坐标要相对父骨骼的**绑定姿势**（不含 offset）去算，
这样父骨骼一旦带上 offset，子骨骼会跟着一起动（转躯干时头/手臂跟着转）；
若把 offset 并进父骨骼的世界变换，子骨骼会被抵消、不跟随。

目前只支持**平移与旋转**：Spine 的 bone setup 可以带 scale，但预览播放器的骨骼世界
变换还没传播缩放，加上去会变成「导出有效、预览看不到」的假象。

### 贴图变体：换色 / 替换 / AI 重绘 / 一键回退

真实立绘上总有几块画得不好。v1 只能「重新生成整张拆件图」——代价高，还会把别的部件
一起换掉。现在每个部件有一条**版本链**：

```
parts/left-hand.png        ← v1（拆件出来的原版）
parts/left-hand.v2.png     ← 换色 / 手工上传
parts/left-hand.v3.png     ← AI 重绘
```

- **每一次操作都新增一版，永不覆盖原图**。「这张 AI 头发不行，换回原版」＝ 点一下 `v1`。
- `activeTexture` 是当前生效的版本；`part.file` / `width` / `height` 始终是它的**镜像**，
  所以装配、骨骼、图集、预览都不需要知道版本的存在。
- 每一版都带来源与说明（「色相+140°」「深蓝色布料手套…」），回退时看得懂哪版是什么。

四种产生新版本的方式：

| 方式 | 花钱 | 说明 |
|---|---|---|
| **换色** | 免费 | 色相 / 饱和 / 明度 / 亮度 / 对比五条滑杆；拖动时缩略图用 CSS filter **即时预览**，点「应用」才落成新版本 |
| **手工上传替换** | 免费 | 同名上传即新增一版（不是替换） |
| **AI 重绘** | 一次 Seedream 调用 | 给一句提示词，重绘这一块 |
| **（批量）** | — | 换色支持按语义 `tag` 批量，例如所有 `cloth` 一起换色调 |

**AI 重绘为什么不会把摆好的位置弄乱**：① 先把部件补成正方形再送出去（模型会按自己的
画幅习惯重排画面）；② 把结果**缩放到正方形尺寸**再裁回来、缩回原尺寸；③ 用原图的
**alpha 当掩码**——轮廓保持原样，模型画出来的背景被切掉。轮廓不变是硬要求：
装配框与骨骼锚点都绑在原来的轮廓上。

落盘前还有一道**健全性检查**：如果结果几乎是纯色（说明模型没画出内容），这一步
明确失败并**拒绝新增版本**——否则用户会拿到一版白块贴图，而且从版本列表上看不出它坏了。

> 排查用的 `scripts/probe-redraw.mjs` 与插件**共用同一个提示词构造器**，
> 直接看模型原始输出比在插件里反复重试便宜得多。这个「共用」不是洁癖：
> 第一版探针自己拼了一份提示词，于是「探针能通、插件不通」的差异让我去猜模型行为，
> 而真正的原因是**我自己的裁剪坐标用错了尺寸**（模型返回 2048×2048，裁剪却按 216×216
> 的补边图算，读到的只是大图左上角一块平坦区域）。教训写在
> `src/rigpose.ts` 的 `maskAndFit` 注释里，并有一条反向验证过的回归测试钉着它。

### 拆件为什么用固定网格

生图模型只负责「把部件画出来」，它不会告诉你哪一块是头。所以提示词要求模型按
**4 列 × 4 行**摆放 16 个标准人形部件——**格子位置就是部件身份**：

```
row 1: head          | neck           | torso            | hip
row 2: left-upper-arm| left-lower-arm | right-upper-arm  | right-lower-arm
row 3: left-hand     | right-hand     | left-upper-leg   | right-upper-leg
row 4: left-lower-leg| right-lower-leg| left-foot        | right-foot
```

名字确定之后，骨骼层级（谁挂在谁下面）与六个动画预设才能自动套上去，而不必让用户
手工给十几个文件命名。模型不按网格摆时（实测会发生）会明确告警，并可以：
重新生成拆件图，或者用「部件 PNG」上传框自己传（**文件名即部件名**），或者在部件卡片上
点「改名」。

### 自动摆位不准时：让 agent 给「视觉先验」

纯几何匹配有一个结构性弱点：**模型重画过的部件**（裙摆、袖子这类服装裁片）与参考图
局部外观只大致对应，错误位置也可能拿到不低的分数——实测一张真实立绘，16 个部件里
只有 3 个落在正确区域，头甚至被摆到了脚下面。

所以插件把「看懂素材」这一步交回给多模态模型（这一步参考项目本来就是这么做的，
我一开始为了可复现把它换成了固定网格，事实证明那个取舍是错的）：

1. agent 用 `read_image` 看 `getRigJob` 返回的 `sourcePath`（参考图）与
   `partsMontagePath`（**部件蒙太奇图**：所有部件按 `partsOrder` 顺序从左上到右下
   摆在一张图上，带格线可以直接数格子）；
2. 逐个判断「这块在参考图的哪个位置」，给出**大致**的像素框；
3. `setRigLayoutHints({jobId, hints:{部件名:{x,y,width,height}}})` → `runRigLayout`。

先验框会被向外放宽 35%，只约束模板**中心**——给粗一点没关系，给错区域才是问题。
界面上会用虚线画出先验框，和实际摆放对比着一看就知道该不该信它。

**实测效果**（同一张真实立绘 + Seedream 5.0 Pro 的拆件图）：

| | 落在指定区域的部件 | 结构检查 |
|---|---|---|
| 无先验 | 3 / 16 | ✗ 头被摆到脚下面 |
| 有先验 | **13 / 16** | ✓ 正确 |

### 拆件是怎么切的

生图模型不会老老实实「一格一件」。实测两个坑：

- 一件东西被画成**互不相连的几块**（围裙的白布片、鲸鱼刺绣、裙摆高光都是独立连通域）。
  按「同一格合并所有」会把它们和同格的**别的**部件揉在一起——实测出现过「一只手 + 两段
  袖子」并成一个部件。现在改成按**真实像素邻近距离**合并（只扫连通域的边界像素向外找，
  代价 O(周长×gap²)），阈值约为格子的 1.5%。
- 部件**溢出格子**多半是往下的（裙摆、头发、尾巴）。按面积最大归属会把整条裙子判给下面
  那格，于是它被命名成 `right-lower-arm`。现在在覆盖率不低于最大值一半的候选里取**最靠上**
  的那格——同一张图里裙子因此正确落到 `hip`。

#### 软 alpha 不能拿「离底色多远」当透明度

切出轮廓之后还要给每个像素定 alpha。原来这一步是 `alpha = (离底色距离 − 容差) / 羽化`，
本意是让抗锯齿边缘不留底色描边。**这个映射对「浅色角色 + 白底」是灾难性的**：

实测一张真实立绘里白色长袜的填充色是 `rgb(247,227,221)`，与白底 `rgb(252,252,254)` 只差 42，
而容差 30 / 羽化 26 正好把 30～56 这一段全判成半透明——于是**整条腿、不只是边缘**拿到了
约 45% 的 alpha。同一张图里：

| 部件 | 内部（离轮廓 ≥2px）半透明像素占比 |
|---|---|
| 头 | 4.5% |
| 手 | 33.0% |
| 右小腿 | **64.3%** |

规律是「填充越浅越透明」，只有深色描边（距离 440+）才拿得到不透明。用户看到的就是
「不该半透明的地方全是半透明」，而且调容差也救不回来（调小会把浅色填充整个吃掉）。

现在把两件事拆开：

- **形状**由硬掩码决定（颜色距离 > 容差），并且把**完全封闭**的孔洞补上——浅色高光一旦
  落进容差内，会在部件中间咬出一个**透明的洞**，那比白斑更糟（能透过角色看到背景）；
- **过渡**只发生在轮廓最外圈 2～3 个像素里（3-4 chamfer 算到「外部」的像素距离，比棋盘
  距离圆），内部一律不透明，**与颜色无关**。设置里的「边缘羽化」现在只决定这一圈有多软。

同一张拆件图重切，内部半透明像素从「手 33% / 小腿 64%」降到 **0 / 1,129,745 = 0.00%**。

### 装配定位是怎么算的

1. **几何先验**：拆件图相对参考图的缩放 `hint ≈ √(1.3 × 角色轮廓面积 / Σ部件像素面积)`。
   有了它，搜索阶梯只需要覆盖 `hint` 的 ±25%，不必从 0.06 盲扫到 1.9。
2. **由粗到细**：在最粗的一档（长边 96）搜「尺度 × 旋转 × 位置」，之后逐级放大、只在
   上一级最优点附近的窗口里精修位置；最后一档再做 ±10% 的尺度与 ±6° 的旋转微调。
3. **打分**：零均值归一化互相关（ZNCC），只在**参考图前景**上统计。排序分是
   `ZNCC × (0.3 + 0.7×覆盖率) + 证据项`：
   - 覆盖率那一项压住「放大」——模板越出角色轮廓，覆盖率直接掉；
   - 证据项（模板掩码占前景面积的比例）压住「缩小」——小块色斑贴在角色内部任何位置
     都能拿到高相关系数，而它其实什么都没解释。
4. **遮挡感知再匹配**：按人形默认层级，把挡在前面的部件先从参考图里「忽略」掉再匹配一次。
   不做这一步，被头挡住顶部的躯干会整体下移十几像素——而且这是**系统性**误差。
5. **镜像消解**：左右对称的部件在 ZNCC 眼里几乎可以互换（相关系数本来就减掉了均值），
   所以用一条与命名约定无关的几何约束兜底：同一组镜像部件必须分居角色中线两侧。

### 手动装配：自动摆位只是起点

不管自动摆位做得多好，**总有几件对不上**（实测这张立绘稳定剩 2～3 件），而「裙子该压住腿、
头发该盖住肩」这类层级关系更是自动流程永远猜不准的。所以 ② 装配定位 整页就是一个装配台，
自动结果只是它的**初始值**：

- **拖进画布**：左侧「未放置」部件栏，按住拖到画布上松手即落地；落地尺寸按全局尺度算好，
  不用再缩一遍。
- **拖动 / 缩放**：拖部件本体移动，选中后八个方向手柄缩放，`锁等比` 按住对面角、关掉则自由
  拉伸；拖动时实时显示与其它部件的中线/边缘**对齐参考线**（`吸附` 开关控制，默认开）。
- **键盘**：方向键微调 1px，`Shift` 10px；`Delete` 把部件收回部件栏（不是删除，随时能再拖回来）。
- **撤销 / 重做**：`Ctrl/Cmd+Z` / `Ctrl/Cmd+Shift+Z`，50 步，整批操作算一步。
- **视图缩放 / 平移**：滚轮以**光标为锚**缩放（25%～600%），`Ctrl/Cmd+0` 适应窗口；
  按住空格或中键拖动平移。
- **图层**：右侧图层列表从下到上排列，点选、批量「置顶 / 置底」，也可以直接改 z 值——
  这就是上面说的遮挡关系。
- **精确数值**：选中后出现 x / y / 宽 / 高 / 旋转 / z 六个输入框，外加「宽高互换」。
  数值一律是**参考图像素**，和自动摆位共用同一套坐标系。
- **单件重定位**：每件都有一个「重新定位」按钮，只对这件重跑模板匹配（免费）。
- **参考图底图**：画布可以垫上原参考图，半透明叠着对位。

画布本身是**客户端自己叠的一摞 `<img>`**，拖动时只改 CSS，不等宿主回图；松手才提交一次，
宿主重算合成图并写回 `layout.json`。所以拖起来是跟手的，而磁盘上的产物始终是完整的一份。

> 两个踩过的坑，都很能说明「客户端不完全信宿主」这件事的代价：
>
> 1. **两份 `mouseup`**。拖动/缩放和「从部件栏拖进画布」各有一份。移动/缩放那份**注册更早**，
>    它的 `mouseup` 先把 `drag` 置空，React 随即同步重渲染，把后面那份监听器当清理函数摘掉了——
>    表现是拖进去毫无反应、撤销也不亮。现在两份监听器各自判断 `drag.kind`，互不越界。
> 2. **两个键**。客户端本地草稿写的是 `placed`（「我要收回它」这个**意图**），而决定图层显隐
>    与「已放置 N/16」计数的是 `matched`（宿主也是读 `placed`、写回 `matched`）。合并草稿时
>    不把两者折算一下，Delete 收回、部件栏拖入这类**纯本地**改动就要等宿主回包才看得见；
>    一旦通信失败（比如宿主半区还没重启），界面会一动不动，看起来就像整个手动装配是坏的。
> 3. **撤销栈被自己的提交清空**（M7 收尾时撞出来的）。`setHistory([])` 原先挂在
>    `[job.id, job.updatedAt]` 上，而 `commit()` 写盘后 `updatedAt` 必然变化——于是每提交一次
>    就清空撤销栈，「撤销」按钮**永远是灰的**。拆成两个 effect：历史栈只跟 `job.id`，
>    草稿跟 `updatedAt`。
> 4. **重做是空操作**。`undo()` 把从历史栈弹出的**改动前**快照也塞进了重做栈，重做时还原的
>    还是那一份，等于又撤一次。改成先把「当前状态」抓进重做栈。

这 4 条 `scripts/verify-client.mjs` 里各有一条契约盯着。

### 骨骼是怎么推出来的

- **骨骼原点**取部件的近端锚点（上臂取上端＝肩，大腿取上端＝胯），**朝向**取近端 → 远端。
- 骨骼的 `x`/`y` 换算到**父骨骼的局部坐标系**（spine-core 会先用父骨骼的旋转去转它）。
- 挂点用「图片中心 − 骨骼原点」再逆旋转到骨骼局部系，并用 `rotation` 抵消骨骼朝向——
  于是**初始姿态与装配结果逐像素一致**（`scripts/verify-rig.mjs` 断言偏差 < 0.02px），
  而动画一开始，部件就绕着正确的那节骨头转。
- 动画是 Spine **4.2 wire format**：旋转值写在 `value` 下（不是 3.8 时代的 `angle`），
  bezier 控制点是**绝对量**、且**每个被动画属性一份**（`rotate` 4 个数、`translate` 8 个）。
  这三点写错的表现分别是「骨骼不动」「骨架渲染一帧后整体消失」「运动突跳而不是缓动」。

**父级只解析一次**。语义层给了父级就用它，没给才按名字关键词往上找。解析结果存进一张
`resolvedParent` 表，**拓扑排序与写进产物的父子关系共用同一份**——这两处一旦各算一次，
「排序用的父级」和「产物里的父级」就可能分叉。

> 这里踩过一个**自 v1 起一直存在、却一条告警都没有**的坑：旧代码把「按名字找父级」和
> 「按祖先栈断环」揉在一个函数里，然后调用两次（排序传祖先栈、写骨骼传空集）；
> 更糟的是断环之后的兜底「挂到 torso」把刚断开的边**又接了回来**且不再复检。
> 默认网格里 `hip` 的语义父级是 `undefined`（身体根），而 `torso` 的父级正是 `hip`——
> 于是**每一份导出都带着 `hip ← torso` + `torso ← hip` 的互环**。
> 这个 bug 是被 DragonBones 的拓扑序校验揪出来的（Spine 那边一路绿灯），
> 所以现在两条导出路径都做拓扑序断言。回归测试在 `verify-rig.mjs` 第 12/13 节。

#### 骨骼方向指向「子部件的近端」

原先每根骨的方向都是「自己部件的上中 → 下中」。对竖直摆放的部件没问题，但**斜着摆的
部件会解出两条互相错开的骨骼**：实测举起的右臂，上臂骨原点到前臂骨原点只差 41.5px，
而上臂骨长 85px——拼图看着对，动画时部件绕的旋转中心却不在关节上。

现在方向改为指向**子部件的近端锚点**，叶子骨才退回自己部件的远端。**只改朝向与长度、
不改位置**，所以「初始姿态逐像素还原」依然成立。实测 11 根有子级的骨里 9 根末端误差
`0.000px`；`hip` / `torso` 非零是固有的（它们有多个子级，一根骨只能指向其中一个）。

> **连带影响（已知，未修）**：`length` 的含义从「部件长度」变成「到子骨原点的距离」，
> 于是**锚点质量开始直接影响骨骼长度**。实测前臂骨只剩 **14.3px**——因为 `left-hand`
> 的近端锚点是「部件顶端中点」，而手掌是**手指朝上张开**的，于是「手腕」被算在了指尖
> 那一侧、和肘挤在一起。改之前这个问题被「长度恒等于部件高度」**掩盖**了。
> 根因在锚点层（`RIG_SLOTS` 的 `P_TOP/P_BOTTOM` 假设肢体一律从上往下长），
> 而手/脚这类部件的正确锚点取决于**姿态**，通用规则覆盖不了——应当做成
> 「按部件主轴自动估计锚点」，或逐件设（`setRigSemantics` 的 `proximal`/`distal` 已支持）。

### 动画：从「两个旋钮」到「可编辑关键帧」

六个动画预设一开始只有两个旋钮——`amplitude`（统一缩放旋转与位移）和 `duration`（循环时长）。
这覆盖了「动作太大了」「这是慢节奏 NPC」这类诉求，但一旦有人想真的**改某一帧**，参数化就不够了。

所以「编辑」这个动作的定义是：**把参数化的预设固化成一份显式的关键帧数据**，从此以数据为准。

- 数据存在 `job.animations[id]`，结构就是简写时间轴
  `{duration, loop, bones: {骨骼名: {rotate|translate|scale: [{time, angle|x|y, curve}]}}}`。
  简写同时是 Spine 与 DragonBones 两条导出路径的**共同输入**，所以编辑器不需要任何格式转换。
- **一旦实例化，参数旋钮就不再影响这台动画**。刻意的：否则手调过的帧会被下一次调参悄悄改掉。
  「还原到预设」是唯一的回头路。
- 写盘前过一遍校验：时间非负、逐轨道时间严格递增、重合帧去重、每条轨道首帧必须是 0、
  **末帧 curve 强制清空**（Spine 的 curve 描述的是「以本帧为起点」的下一段，末帧没有下一段）、
  curve 只接受 4 个数或 `"stepped"`。丢掉的东西一定伴随一条 warning，不做静默修正。
- 界面上的时间轴可以：切换动画（标「已改」）、改时长/循环、点选关键帧、**拖动改时间**、
  双击空白处加帧、改数值、六个缓动预设、加/删轨道（含 scale）、删除关键帧。
  首帧（0 秒）不能删——它是每条轨道的锚；删掉它，0 → 首帧之间就是一段未定义的静默区。
- **拖动只改本地草稿、松手才提交**，与装配台一致（跟手，但提交少而完整）。
- 预览 iframe 的 `src` 带 `?v=${rig.updatedAt}`：少了它 React 认为 src 没变、不重新挂载，
  改完关键帧预览会一直是旧的。

> 顺手修掉两个真 bug：
>
> 1. `kf()` 给每帧都挂了默认缓动，**末帧也带了一个永远不会被读到的 curve**——导出不受影响，
>    但编辑器里用户会看到一个永远改不动的字段。
> 2. `invalidateFrom` 写成「让某个阶段**之后**的产物失效」，于是 `setRigBoneOffsets` /
>    `saveRigAnimation` 这类传 `"rig"` 的入口只清掉了「通过」标记，`rig.status` 仍是 `ready`
>    ——界面继续显示「已完成」，用户以为改动已经生效了。现在按阶段分开处理：
>    **`layout` 保留 `items`**（那是用户手工摆的劳动成果，不能因为改了一个先验就被抹掉），
>    **`rig`/`atlas` 置空**（纯派生物，重跑就有）。

### 导出两套格式：Spine 4.2 与 DragonBones 5.5

同一个骨架同时落两份产物，给不同的引擎用：

| 文件 | 给谁 |
|---|---|
| `rig/skeleton.json` | Spine 运行时 / Spine 编辑器 |
| `export/dragonbones/skeleton_ske.json` | DragonBones（Cocos / Egret / Laya 自带） |
| `atlas/skeleton.atlas` | Spine 的图集描述 |
| `atlas/skeleton_tex.json` | DragonBones 的图集描述（逐页一份） |
| `rig/preview.html` | 自带 Canvas 渲染器，零外部依赖，双击即播 |

两份是同**一次**推导、同**一次**装箱出来的——分开各算一次，坐标迟早对不上，而运行时的
表现只是「画错位」，不会有任何报错。

三处必须分开编码的差异（都对着 DragonBonesJS 的解析器逐行核过）：

1. **`tweenEasing` 缺省是 `-2`（阶跃）**，不是线性。所以每个补间帧都要显式写 `tweenEasing: 0`
   或真实缓动，否则动画一跳一跳。
2. **`curve` 是 0~1 归一化**的（紧凑式要求长度 `% 3 == 1`），而 Spine 4.2 是**绝对量**。
   所以简写动画被拆成 `buildAnimationShorthands`，两条路径各自编码一次。
3. **`duration` 是帧数**（`seconds × frameRate`，固定 30），Spine 那边是秒。

另外两处决定「画出来对不对」：图片落点靠 `pivot` + `frame*`（`_pivotX = pivot.x * frameWidth
+ frameX`），裁剪过的部件少给 `frame*` 会整体偏掉；坐标是 **y 向下**（`DragonBones.yDown`
默认 `true`），与我们的图像坐标一致，旋转角不取反。

### 预览为什么不用官方 Spine Web Player

官方播放器要从 CDN 拉 `spine-player.js`，而验收页可能在没有外网的环境里打开。所以
`preview.html` 把部件图片与骨架 JSON 全部 base64 内联、自带一个 Canvas 渲染器（含贝塞尔
插值、骨骼叠加显示、时间轴），双击就能看，零外部依赖。

### 验收与重试

- **① 拆件**：部件卡片逐件「通过 / 改名 / 隐藏 / 删除 / 重新定位」；
- **② 装配**：整页是手动装配台（拖入 / 拖动 / 缩放 / 对齐吸附 / 撤销 / 图层 / 精确数值，
  见上一节）；自动没匹配上的部件会明确标出来，同时给出「只重试未命中的 N 个」按钮；
- **③ 骨骼**：六个动画按钮直接切换播放，可开骨骼叠加与网格；页面上同时给
  `skeleton.json` 与 DragonBones `skeleton_ske.json` 两个入口；
- **④ 图集**：图集整图预览 + `.atlas` 文本 + DragonBones `_tex.json`，区域尺寸与
  `skeleton.json` 里的挂点尺寸一致。

对话里也能全程驱动：`game_material_call({method:'runRigLayout', payload:{jobId, names:['head']}})`
只重跑一个部件，不花钱。

---

## 抠像是怎么做的（含「角色贴边被整片误抠」的坑）

主判据是**边界洪水填充**：从四边出发，只沿着「颜色像背景」且「与相邻背景像素接近」的方向生长，
所以绿幕、黄幕、被重新打光成渐变的背景都能整片吃掉。

**坑**：调色板是拿边框像素建的——角色一旦贴到画面边缘（尾巴 / 头发 / 裙摆被裁到边上），
它自己的颜色就混进了「背景色」。填充于是顺着同色的身体部位一路吃进去。
实测一张 438×768 的转圈帧：尾巴贴住左边缘，1.6% 的边框采样点是藏青，
默认容差下 **7.7% 的掩码变成了角色的裙子与头发**，半条裙子直接没了。

**修法**：边框采样点先按颜色**单链聚类**（格心距离 ≤ 2 格算连通），只让**背景主色簇**
（占比 ≥ 15%，或最大的那一簇）进调色板。平缓渐变因为一路相连会被完整保留（暖色渐变用例
仍然 92% 透明），而那一小撮角色色自成小簇、被挡在门外。同一张帧修好后掩码里
「不像绿色」的像素从 7.7% 降到 **0.00%**，角色的不透明像素数回到关掉填充时的基线。

诊断字段（`KeyResult`，会写进合成日志与 `game_material_status` 的整图 cell）：
`backgroundFraction`（背景占比）、`borderSamples` / `borderSamplesDropped`（边框采样里被排除的点数，
> 0 通常意味着角色贴边）。`verify-pipeline.mjs` 第 12 节钉住了这一条：
贴边素材里角色的深蓝必须保住、干净素材一个采样点都不许排除、双色背景两块都要算背景。

## 抠像参数怎么调

| 旋钮 | 作用 | 什么时候动 |
|---|---|---|
| 背景分割容差 `bgTolerance` | 主判据：洪水填充的颜色容差 | 误抠成片 → 往小调；干净绿幕可以直接 0（= 只按绿色判据） |
| 抠像下限 / 上限 `keyLow` / `keyHigh` | 辅助判据 `绿色优势 = G − max(R,B)` | 角色身上偏绿的颜色被抠掉 → 两个值一起往下调（如 8 / 60） |
| 去绿溢出 `despill` | 只压绿色分量，不改透明度 | 抠完边缘发绿时才调大 |
| 边缘收缩 `edgeShrink` | 前景 alpha 向内腐蚀 n 像素 | 只剩一圈绿边时用 1~2；调大啃掉发丝 |

**为什么第 ③ 步抠过一次、第 ④ 步还要再抠**：③ 抠的是**每个方向的预览带**（顺手也合出了整图），
④ 在**同一份帧缓存**（`raw.bin`）上用**同一套参数**重抠一遍——目的是让 ④ 那十个参数
改完立刻生效，而不用重新解码视频重抽帧。两步结果必然一致，不是重复劳动。


三个模块共用同一套实现，判据分两条，**先空间、后颜色**：

1. **边界洪水填充**（主判据）。从画面四边出发，只沿着「与相邻已判定背景像素颜色接近」
   的方向生长。它跟随的是**局部连续性**而不是某个固定颜色，所以绿幕、黄幕、
   甚至被视频模型打光成整片渐变的背景都能整片吃掉。
2. **绿色优势值** `g - max(r, b)`（辅助判据）。只作用在未被判定为背景的像素上，
   清理轮廓残留的绿色，并按 `(1 - alpha)` 加权去绿溢出（不会改坏角色身上真正的绿色衣物）。

两个实测调出来的关键参数：

- **局部容差必须收得很紧（12）**。放宽到 16 就会顺着抗锯齿的软边缘渗进角色体内，
  把整个身体判成背景（白色围裙尤其容易中招）。背景的大范围变化由全局调色板负责，
  不需要局部判据承担。
- **全局调色板按球体标记**，不能只按格坐标扫一圈——那会标出一个立方体，
  角落到中心的距离可达容差的 √3 倍，于是离背景很远的角色颜色也会被误判成背景色。

### 像素量化

像素风来自**确定性的后处理**，不来自提示词。实测 Seedream 会忽略「像素画」这类风格指令
照旧输出平滑插画，所以量化放在了抽帧合成阶段：每个输出像素块单独做盒式平均
（按 alpha 预乘，背景色不会渗进边缘），再填满整块。生图和视频模型磨平了细节也不影响最终像素风。

默认 4px 方块在 256 格上是「能看出方块但仍保留细节」的平衡点；6px 以上开始丢细节。

---

## 产物位置

```
<DSH_HOME>/game-material-master/
├── config.json
├── projects/<项目 id>/          模块一：八方向图
│   ├── source/  images/  videos/  frames/  keyed/  preview/  out/
│   ├── turn/                    转圈截帧（阶段①的默认生成方式）
│   │   ├── raw.bin              候选帧的 RGBA 缓存（拖圆圈重切时只读它，不重新解码视频）
│   │   ├── frames/fNN.png       候选帧（整圈均匀取样）
│   │   └── strip.png            整圈缩略条带（界面上那八个圆圈对着它拖）
├── image-jobs/<任务 id>/        模块二：图片生成
│   ├── refs/  out/  keyed/
├── sequence-jobs/<任务 id>/     模块三：序列帧生成
│   ├── refs/  video-refs/  videos/  frames/  keyed/  out/
└── rig-jobs/<任务 id>/          模块四：骨骼动画生成
    ├── source/                  角色参考图（整图）
    ├── sheet/                   拆件摊平图（生图模型产出）
    ├── parts/                   分割后的部件透明 PNG（文件名即部件名）
    ├── layout/                  layout.json + composite.png + comparison.png
    ├── rig/                     skeleton.json + preview.html
    └── atlas/                   skeleton.png + skeleton.atlas
```

素材通过 `ctx.webServer` 注册的路由直接发给浏览器（支持 `Range`，视频能拖进度条）：

```
/dsh-game-material-master/assets/<项目 id>/<相对路径>
/dsh-game-material-master/image-assets/<任务 id>/<相对路径>
/dsh-game-material-master/sequence-assets/<任务 id>/<相对路径>
/dsh-game-material-master/rig-assets/<任务 id>/<相对路径>
```

四个模块的 id 前缀不同（项目 `p…`、图片任务 `i…`、序列帧任务 `s…`、骨骼动画任务 `r…`），
路由会校验前缀并挡住目录穿越。

---

## 开发

### 改了代码之后怎么生效

| 改了哪里 | 怎么生效 |
|---|---|
| `src/client.ts`（浏览器半区） | 刷新页面即可——客户端 bundle 由宿主按请求从磁盘读，带上 `rev` 指纹 |
| `src/*.ts` 的宿主半区（网关、路由、工具、流水线） | **正式环境必须重启 Harness**（菜单 `Harness → 重启 Harness`）。宿主半区是进程启动时冻结的模块图，改 YAML / 碰文件都不会让它重新 import |

#### 开发时的宿主半区热重载（不必重启）

重启 Harness 会掐断正在跑的 agent 会话，做插件开发时很难受。profile 声明了
`patchReload: live`，但**默认不生效**：启动时创建 `cordis-plugin-hmr` 用的是
`{ root: [] }`——也就是「不监听任何目录」，而且 `base` 会被
`new URL(base, ctx.baseUrl)` 解析，写成 `D:/...` 会被当成 `d:` scheme 抛
`ERR_INVALID_URL_SCHEME`（必须写 `file://` URL）。

起一个**独立端口的测试宿主**、并注入 `scripts/dev-overlay.yml`，就能拿到
「改完 `lib/*.js` 立即生效」的开发循环：

```bash
# 注意 --patch 是启动器的选项，要写在子命令前面
node "<DSH>/resources/app/node_modules/@deepseek-ai/dsh/lib/bin.js" \
  --profile web --patch scripts/dev-overlay.yml --port 43121 --no-open
```

判断「运行中的宿主到底吃到了哪一版代码」不用猜——有现成的探针：

```bash
curl http://127.0.0.1:43121/dsh-game-material-master/_health
# {"ok":true,"pid":29156,"bootedAt":...,"mtimeMs":...}
```

`mtimeMs` 是 `lib/index.js` **被 import 时**捕获的。重新 build 之后如果不手动刷新页面，
它就该跟着变；没变说明代码没生效，而不是功能坏了。

用 Playwright 驱动这个测试宿主时，需要先过 Web 认证（每个 Host RPC 都要求同一个
浏览器会话）：启动令牌只在进程内存里拿不到，但 cookie 的签名密钥是持久化的，
可以从本机凭据派生一份合法 cookie：

```bash
node scripts/dsh-web-cookie.mjs 127.0.0.1:43121 --json
```

这一点会真实地咬人：宿主半区是旧版而客户端是新版时，界面会以各种「读不到字段」的形式
坏掉（按钮一直是灰的、图片 404），而不是报一个明确的错。所以：

- 客户端在 `RigModule` 里对形状做了显式检查，版本对不上会直接提示「请重启 DSH Desktop」；
- `scripts/verify-rig-module.mjs` 有一条契约扫描 `RigModule` 读了哪些 `job.*` / `part.*`
  字段，逐条对着真实视图核对；
- `scripts/verify-client.mjs` 有一条契约核对 `REMOTE_METHODS` 里的**每个**方法都在
  `api` 对象上有实现——`REMOTE_METHODS` 只负责向宿主声明方法名，忘了挂实现时
  编译期完全看不出来（`api` 是隐式 any），一点就报 `api.xxx is not a function`。

### 自检脚本

| 脚本 | 覆盖 |
|---|---|
| `node scripts/verify-rigsemantics.mjs` | 模块四语义层：角色推断（含中文名与关键词优先级）、默认语义与 v1 的 `RIG_SLOTS` **逐条一致**、父级沿角色链回退、成环/悬空父级/锚点退化的校验与自动修复、确定性 |
| `node scripts/verify-rig.mjs` | 模块四算法层：拆件分割、装配定位精度、遮挡排序、骨骼初始姿态逐像素还原、Spine 4.2 wire format、**DragonBones 5.5 双格式导出（每个地雷都配了反例）**、语义成环时的无环保证、**拆件质检（重复件 / 镜像判别 / 装配质量）**、图集装箱、预览 HTML（合成图像素级断言） |
| `node scripts/verify-rig-module.mjs` | 模块四端到端：建任务 → 上传 → **语义** → 装配 → **手工骨骼偏移（含「重跑骨骼后仍在」）** → **关键帧编辑（含「改动作废骨骼」「导出 JSON 里是改后的值」）** → 骨骼 → 图集 → 打标 → 删除级联（走真实模块代码，数据落在临时 DSH_HOME） |
| `node scripts/montage-parts.mjs <部件目录> <输出.png> <部件名…>` | 把若干部件拼成一张带分隔的对比图，用来人工核对「哪几块其实是同一个部位」。肉眼看蒙太奇小图分不清，放大并排才看得出来 |
| `node scripts/make-rig-fixtures.mjs <目录>` | 生成**免费**的合成部件 PNG（`--full` 出完整 16 件），让除拆件以外的整条链可以零成本测试 |
| `node scripts/probe-redraw.mjs <部件PNG> "<提示词>"` | **花钱**：直接调生图模型重绘一个部件并打印统计（与插件共用提示词构造器）。用于排查「是模型不行还是管线不行」 |
| `node scripts/e2e-rig-live.mjs <角色整图>` | 模块四真实链路：**真的调一次生图模型**拆件，再跑完装配/骨骼/图集（约 0.2 元） |
| `node scripts/verify-host.mjs` | 宿主半区全链路（**285 项**）：四个模块的本地链路、**阶段①的转圈截帧（合成一段「转动」视频跑真实 ffmpeg，覆盖截帧位置、按比例换算、下游作废、切换生成方式）**、资源路由（含 `turn/` 白名单）、预览页的 `text/html`、目录穿越与 id 前缀校验 |
| `node scripts/verify-tools.mjs` / `verify-client.mjs` / `verify-pipeline.mjs` | 对话调用面（含四个模块 status/review 的文字渲染）、浏览器半区契约（含「每个远程方法都有 api 实现」与手动装配的四条回归）、抠像回归 |



```bash
npm run build          # tsc → lib/，并剥掉浏览器束结尾的 export {}

# 纯本地测试（不联网、不花钱）
node scripts/verify-minimax.mjs    # MiniMax 协议层（85 项，含请求体逐字段断言）
node scripts/verify-pipeline.mjs   # 抽帧/抠像/合成链路（40 项，含回归用例）
node scripts/verify-host.mjs       # 宿主冒烟（285 项，真实 cordis + 真实 HTTP）
node scripts/verify-client.mjs     # 浏览器半区契约（299 项：阶段 ctx 键必须被转发、每个生成类调用点都带 loading 反馈、转圈时间轴与八圆圈、手动装配的四个坑、拆件质检 / IK 约束组件）
node scripts/verify-feedback.mjs   # 浏览器半区渲染（119 项：真加载 lib/client.js，断言遮罩真的出现 / 空闲时真的不出现 / 转圈模式两种生成方式与八圆圈都在 / 深链接点击真的切面板）
node scripts/verify-tools.mjs      # 对话调用面（109 项：工具 schema、方法覆盖、固定流程（含阶段①生成方式必问）、审核模式、深链接契约、转圈模式的 status/review 渲染）
node scripts/verify-live-bundle.mjs # 运行中的宿主是否已在提供新束（走 /plugins/events 拿真实 graph，再按图里的 URL 取回）

# 真实 API 端到端（会花钱）
node scripts/e2e-modules.mjs                                  # 图片 + 序列帧两个新模块（约 2.9 元）
node scripts/e2e-8dir.mjs --source hero.jpg --until images    # 八方向：先只出图，便宜
node scripts/e2e-8dir.mjs --source hero.jpg --mode turn --from turn   # 走默认的转圈截帧：一次视频调用 + 本机截帧
node scripts/e2e-8dir.mjs --project <id> --from videos        # 再续跑视频
node scripts/rerun-videos.mjs <项目 id> <方向,方向>            # 只重跑指定方向的视频
node scripts/retry-video.mjs <项目 id> <方向> [--soft]         # 单方向重试（审核拦截时用）
```

`verify-pipeline.mjs` 里有三个针对实测踩过的坑的回归用例：
**角色贴边**（边框采样混进角色的颜色 → 洪水填充把同色的身体部位整片吃掉，见「抠像是怎么做的」）、
**暖色渐变背景**（只认绿色的抠像会整片失效）与**软边缘渗漏**（局部容差放宽就会穿透）。

`verify-host.mjs` 除了走一遍四阶段，还钉住了「单方向重新生成视频」这条路：宿主的
`runVideos` 默认跳过已经 ready 的方向（防止重复提交把任务覆盖成无人认领的孤儿），
所以「重新生成」必须显式带 `regenerate` 让宿主先作废旧视频与它的帧——少一个都不行，
否则这次点击会被当成「已完成」过滤掉，界面转一圈就结束，失败原因只留在日志里
（实测报错：「没有可提交的方向：请先生成绿幕图，或先清掉已完成的视频」）。
这一段用**本地假网关**顶替 MiniMax：提交必然失败，但「有没有真的提交出去」一目了然，
且不联网、不花钱。

`verify-host.mjs` 里 `9c` 一段专门跑**转圈截帧**：本地 ffmpeg 合成一段「竖条扫过画面」
的视频当转圈素材（不同时刻画面不同，所以「不同方向切到不同的帧」可以按字节断言），
再真实走一遍 `runTurnFrames` → 抽候选帧 → 切八张方向图，逐条钉住：任务覆盖面（八个
方向，切完一个摘一个）、时间戳按 `i × 时长 / 张数` 分布、八个位置按**这次**张数等分、
拖动圆圈后**只有那一张**变、这一方向的行走视频与序列帧被作废、改候选帧数后位置按比例
换算。`turn/` 也在这条链路上顺带进资源路由的白名单——漏了它界面只表现为「轴上的条带
图裂了」，不报任何错。

`verify-client.mjs` 盯的是浏览器半区的另一类坑：阶段渲染函数从 `ctx` 里解构哪些键，
调用点就必须原样转发哪些键。漏传一个键**渲染完全看不出来**，只有点到那个按钮才会炸
（实测：第 2 步漏传 `api` → 点「生成视频」报 `Cannot read properties of undefined
(reading 'runVideos')`；第 3、4 步的 `runFrames` / `compose` 同样中招）。

后半段还钉住了「每个生成类调用点都必须带 loading 反馈」：文本层面确认
`start` / `run` / `kickAndWatch` 的实参里有 `{ key, label }`。

`verify-feedback.mjs` 再往前一步——它把 `lib/client.js` **真的加载起来**（假
`__ModuleLoader__` + 假 React + 假 document），用桩项目数据渲染出元素树，断言遮罩真的长出来了：
某个方向在跑时它的预览必须被 `SPR_ovl` 盖住、批量时还没轮到的方向也要盖住、
空闲时**一个遮罩都不能有**。这类问题肉眼极难发现：不盖遮罩时界面看着完全正常，
只是「点了没反应」，用户会以为按钮失效而反复点击——每次点击都是真实计费。

它还顺带钉住了两件事：**验收控件真的渲染出来**（三个模块都能看到审核模式下拉与「通过」按钮），
以及**深链接点击真的会切面板**——装上真的捕获阶段监听器，派发一次合成点击，
断言 `preventDefault` 被调用、`layout.selectPanel("gameStudio")` 被调用、意图被广播出来；
同时断言普通外链与 Ctrl+点击 / 中键**不被抢走**。

`verify-tools.mjs` 盯的是对话调用面这一类坑：工具 schema 必须落在 DSH 支持的关键字子集里、
`game_material_call` 的 method 枚举必须**覆盖插件的每一个远程方法**（少一个就是「某个功能对话里调不了」）、
固定流程第 0 步必须按真实状态算出要问什么（缺源图就问、已有源图就不问）、
审核模式必须只有 auto/manual 两个选项。它还把四个模块的 `status` / `review` 文字渲染
**真的跑一遍**——这几个渲染器按同一套字段写，而骨骼动画的阶段形状跟其它三个模块不一样
（没有 `cells`，只有 `status`），一律按 `cells` 迭代会让 `game_material_review` 以
`stage.cells is not iterable` 整次失败，而按 `ready/total` 渲染 `status` 会印出一串
`undefined`；两种坏法都只在骨骼动画上出现，别的模块一条测试都不会红。
最后用**文本契约**把宿主 `links.ts` 与浏览器半区
`client.ts` 的深链接常量钉成一致——两边是两份实现（经典脚本不能 `import`），
参数名或模块名改单边会静默失效。

`verify-live-bundle.mjs` 回答的是另一个问题：「我改完了，运行中的宿主到底有没有换新束？」
自己拼 `/plugins/<id>/client.js` 一定 404（浏览器束是按模块图里带 rev 的 URL 提供的），
所以它先连 `/plugins/events` 拿真实 graph，再按图里的 URL 取回束并检查新标记。

### 调用接口时的反馈（loading）

三个模块里每一次「会出素材」的调用（生图 / 生视频 / 抽帧 / 抠像 / 合成 / 上传）
都必须让人一眼看见「正在跑」——否则按钮像是没生效，用户会反复点，而每次点击都是
真金白银。反馈分两层：

| 层 | 组件 | 用在哪 |
|---|---|---|
| 预览遮罩 | `LoadingOverlay` / `MediaBox` | 盖住缩略图、视频、序列条、整图、行走预览 |
| 按钮与徽章 | `BusyBtn` / `BusyBadge` | 按钮变转圈并置灰防重复提交；工具栏显示当前在跑什么 |

关键实现是 `usePendingTasks()` 这张按 key 记账的 pending 表，原因是**宿主把任务标成
running 落在下一次 `getProject` 里**：

- 点下去当场就把遮罩盖上（不等轮询回来），调用返回后还多留 700ms（`TASK_HOLD_MS`），
  避免「图已经变旧了但还没盖上」的闪一下；
- 判断条件是 `宿主状态 === "running" || tasks.has(key)`，两条路都能点亮遮罩；
- 批量操作有专属 key（`image:*all` 等），这样**还没轮到的方向**也能一并盖住，
  而不是只有正在跑的那一个变灰；
- 卸载后不再 `setState`（长任务可能几分钟才回来）。

### 批量任务跑多久，遮罩就得盖多久（`job.targets`）

上面那张 pending 表只活到**远程调用返回**为止，而批量任务是 kick 型调用：一提交就返回
`{started: true}`，真正的活在宿主后台一个方向一个方向地做（抽帧并发只有 2）。所以「还没
轮到」的判定不能只看本地 pending——实测的 bug 就出在这里：点「提取全部序列帧」后八个方向
先一起转圈，紧接着还没轮到的那几个变回「尚未抽帧」，过一阵才陆续出结果，看着像点击没生效。

因此宿主的运行表会公布**这次任务要负责哪些方向**（`project.jobs[].targets`，
见 `pipeline.ts` 的 `JobInfo`），界面按它决定盖不盖：

| 谁 | 什么时候 | 由谁负责 |
|---|---|---|
| `frames:extract` | 从任务登记（第一个 `await` 之前）到该方向的预览带写出来 | 抽帧节点自己的 running 状态；覆盖面负责「还没轮到」与「抽好了但预览带还没出」 |
| `videos:submit` | 逐方向提交的整段时间 | 提交成功后交给节点自己的 running 状态（覆盖面同时从该方向摘掉） |
| `images:all` | 整批生成期间 | 出图落地（成功或失败）后立刻摘掉，已通过验收、这次不重做的方向一开始就不在覆盖面里 |

两条硬约束（`verify-host.mjs` 钉住）：**覆盖面只包含真的有素材、这次真会做的方向**
（否则那个格子会一直转圈），**单方向操作只覆盖那一个方向**（否则其余方向被白白盖住）。
`verify-client.mjs` 用文本契约核对两边的任务 key：写错一个字不会有任何报错，
只是这条路静默失效。宿主半区是启动时装入的，**改完 `pipeline.ts` 要重启 DSH**；
浏览器半区刷新即可（旧宿主不带 `targets` 时这条路自动不生效，不会报错）。

`verify-client.mjs` 的文本契约与 `verify-feedback.mjs` 的真渲染断言一起保证：
新增调用点时忘了传反馈，或者遮罩在空闲时误开，都会在本地测试里直接失败。

### 工程结构

| 文件 | 作用 |
|---|---|
| `src/directions.ts` | 八方向定义、依赖关系、默认提示词 |
| `src/rigpose.ts` 的 `solveLayout` | 模块四的装配求解总入口（先验 → 匹配 → 冲突/遮挡/镜像消解） |
| `src/config.ts` | 全局配置、数据目录迁移 |
| `src/ark.ts` | 火山方舟生图客户端 |
| `src/minimax.ts` | MiniMax 视频客户端（v1/v2 双协议、首尾帧与多模态参考、优云智算版 `/minimax` 网关） |
| `src/media.ts` | ffmpeg / ffprobe 封装 |
| `src/chroma.ts` | 背景分割、绿色抠像、裁剪、像素量化、合成 |
| `src/png.ts` | 极简 PNG 编码器（RGBA8，基于 node:zlib） |
| `src/jsonio.ts` | 新模块共用的 JSON 原子写与日志 |
| `src/store.ts` / `src/pipeline.ts` | 模块一：项目持久化与四阶段编排 |
| `src/imagegen.ts` | 模块二：图片生成任务 |
| `src/seqgen.ts` | 模块三：序列帧任务 |
| `src/spine.ts` | 模块四：骨骼层级推导、Spine 4.2 JSON、六个动画预设、图集文本 |
| `src/rigpose.ts` | 模块四：连通域分割、多尺度模板匹配、遮挡/镜像消解、合成与装箱 |
| `src/rigpreview.ts` | 模块四：自包含 Canvas 骨骼动画预览（零外部依赖） |
| `src/riggen.ts` | 模块四：任务持久化与四阶段流水线 |
| `src/wire.ts` | Typert 远程协议清单（**唯一真源**） |
| `src/links.ts` | 深链接：意图编解码、origin 记录、面板 key（与浏览器半区共用同一套约定） |
| `src/tools.ts` | 对话调用面：`game_material_*` 工具、固定流程第 0 步、系统提示词段 |
| `src/index.ts` | 宿主半区：远程服务 + 资源路由 + 工具注册 |
| `src/client.ts` | 浏览器半区：四个模块的界面 |

`src/client.ts` 由宿主直接以 `/plugins/dsh-game-material-master/client.js` 提供给浏览器，
因此**必须是经典脚本**（无 `import` / `export`），所有 React 元素用 `React.createElement` 构造。

---

## 已知取舍

- **像素风来自后处理，不来自提示词**（原因见上）。
- **视频提示词按任务共用，同时保留按方向覆盖位**（模块一的 `prompts.videoPerDirection`），
  目前界面只暴露共用那一份。
- **内容审核**：MiniMax 偶尔会以 `1026 content blocked by moderation` 拒绝（实测约 10% 概率）。
  换一版更中性的提示词重试通常就过——用 `scripts/retry-video.mjs <项目> <方向> --soft`。
- **整图行序与外部素材未必逐行一致**——各家行序不同，所以做成了可调项。
- **骨骼动画的自动装配依赖美术细节**。模板匹配在**平涂、低细节**的角色上会明显吃力：
  同色的一大片区域内部没有任何区分度，左右肢、同色衣料之间几乎不可分辨。实测一张
  256×256 的纯色矢量小人和一张有明暗细节的立绘，自动命中率差一倍以上。
  这种情况下插件不会硬猜：低相似度的部件会被标出来，没匹配上的先放在「待摆放」区，
  用户在合成图上直接拖、或者用数值输入微调即可——每一步都不花钱。
- **拆件质量由生图模型决定，而且这是目前最大的瓶颈**。提示词已经明确要求
  「方形画布、等分网格、一格一件、四肢必须断开、与原图完全同款」，实测
  Seedream 4.0 有时会**把角色换成另一个**：拿一张「戴发箍、深蓝连衣裙、白围裙、
  鲸鱼尾巴的女仆」去拆件，它交回来的是同一张脸配白短裤和光腿的一具裸身——
  服装、发型、体型全换了。这种拆件图**不可能**匹配回原图，再调匹配参数也没有意义。
  **换 Seedream 5.0 Pro 后角色设定守住了**（同一张立绘：4.0 交回来的是换掉
  服装 / 发型 / 体型的另一个角色，5.0 Pro 交回来的是同一个女仆，连围裙上的鲸鱼
  和尾巴都在），但它把角色拆成了**服装裁片**（裙摆、袖子、领子、袜腿、鞋），
  而不是整段肢体——这些裁片的外观只覆盖参考图的一小块，模板匹配依然摆不准。
  插件不会假装自己摆对了，两道检查会明确拦住：
  - **结构合理性**：头被摆到脚下面 / 大腿下面时直接判定「自动定位结果明显不合理」；
  - **平均相似度**：低于 0.32 时告警「拆件图与参考图很可能不是同一个角色」。
  两条都会给出同样的三条出路——① 用「部件 PNG」上传框传自己的部件
  （**文件名即部件名**，完全绕开生图，也是目前**唯一可靠**的路径）；
  ② 换生图模型重新拆件；③ 在合成图上手工拖到正确位置。
- **自动装配目前只对「部件是整段肢体、且与参考图外观一致」的素材可靠**。
  实测结论：合成素材（部件就是参考图上切下来的整块）能到 16/16 命中、包围盒重合；
  真实立绘走生图拆件时还不能指望——因为拆件图是**重画的**，裁片与参考图的
  局部外观差异足以让匹配摆错位置，而且相关系数依然不低（实测有 0.48），
  纯靠分数发现不了。所以两道结构检查（头在下、均分过低）是必要的兜底。
  想要立即可用，走「上传自己的部件 PNG」这条路径。
- 模块一的默认行序是**罗盘顺时针**（北→东北→东→东南→南→西南→西→西北）；
  早期版本的生成依赖顺序会被自动迁移一次，之后你手动设成任何顺序都会被尊重。
- 模块四的动画预设（`src/spine.ts` 的 `RIG_ANIMATIONS`）只对**标准人形骨骼名**生效：
  部件名对不上就没有对应的时间轴。表外名字的部件仍然会进骨架，只是不会动。

## 许可

[MIT](LICENSE)