---
name: mastergo-template-fill
description: 在研发云本地部署版或 MasterGo 私有版中，原生复制既有母版画板，按本地素材目录批量替换文字和二维码，保护固化层与样式，检查 MCP 连接并记录断点。用于展签、标牌等模板填充，不用于重新设计或 HTML 重绘。
---

# 研发云母版填充

交付原生母版的副本，只改绑定的文字与图片。**禁止以 HTML/SVG 生成、design_page、agent_sync_design、submit_page_to_canvas、整根 agent_replace_node 或逐层重建代替复制。** 不因 MCP 无复制能力而降低此要求。

先读 [连接与当前工具边界](references/connection.md)。用户本次只要求固化工具时，完成工具与只读验证即可；不要自行批量生成画板。用户要求执行填充时，已有授权足以创建副本和修改指定内容，不逐张征求确认。

## 文件名是内容来源

输入命名规则为 `<编号><中文标题>-中文.png` / `<编号><中文标题>-藏语.png`。例如 `1015白脉-中文.png`：

- 新画板名称：`1015白脉`（只去掉语言后缀及扩展名）。
- 编号文字：`1015`（保留前导零）。
- 中文标题：`白脉`（保留原文件名的标点、括号、续集编号，不擅自改写）。
- 下方藏文：对该中文标题的藏语翻译；不从母版沿用、不从二维码图像识别，也不把藏语目录中的中文文件名当作译文。
- 中文码/藏语码：使用同一编号的两张原始文件；两边标题冲突时停止该项，不猜测配对。

一组中藏码对应一张双语画板。`manifest.json` 的 board_name、id、title_zh、translation_source 必须由脚本解析；Agent 只生成 title_bo。最终画板名不得附加“流程验证”、日期或 run_id；运行标识保存在日志中。为断线找回使用临时唯一名称时，验收前必须改成 board_name，并记录真实 rootId。检查已有画板应结合 ID/运行记录，不能凭同名覆盖。

## 执行顺序

1. **准备素材**：运行 `scripts/prepare.py --zh <中文目录> --bo <藏语目录> --out <运行目录>/manifest.json`。按编号配对，不按排序位置或标题模糊匹配。保存原文件 SHA256、尺寸、标题。其他命名规则只改素材解析适配，不能放宽重复编号/缺失配对检查。目录名“藏语”仅表示二维码语言，文件名仍可能是中文。
2. **连接与定位**：确认官方 daemon 状态 → MCP initialize/tools/list → get_selection_node 指定母版。浏览器登录、daemon 存活、tools/list 成功均不能单独代表目标可读。核对 documentId/pageId/rootId。默认选区只用于发现，不能自动视为用户指定母版。目标缺失时先准备本地材料，再请求链接或选择目标。
3. **绑定一次**：读取完整母版树、预览、字体及尺寸。记录固化节点、内容槽位（编号/中文标题/译文/中文码/藏语码）。内容层中的固化子节点依然受保护；未绑定节点全部只读。保存模板快照、版本/哈希、槽位 ID 与结构路径、素材清单哈希到运行目录。仅名称不能作为唯一定位依据。
4. **先处理内容**：以文件名解析出的中文标题为翻译原文；若提供了对应译文则复用，否则直接翻译，保存原文、译文、语言和术语表。不要把藏语二维码文件名当作藏文标题，不擅自纠正原始专业名词或删减长标题。翻译不改变字体或字号；缺字、容纳不下时标记该项异常，交付准确原因。不要默默改固化版式。
5. **原生复制**：当前工具确有 native clone/duplicate 时按其 schema 执行；否则通过官方 UI 的“复制/粘贴/重复”原生操作。可使用经验证的官方插件原生 clone API，但先取得该版本 API 证据，禁止发明 API。每次创建后立即记录副本 rootId，并读取副本完整树建立**新 ID**映射。副本只允许根画板位置/名称按计划改变，内部坐标和样式不变。母版 ID 永不进入写入队列。若不具备原生复制路径，停止写入并报告，不换成重绘。
6. **样例先行**：先做一张样例，并包含最长标题/译文的布局检查。拿到**副本最新 HTML**后，使用 `scripts/guard.py` 生成叶子节点 payload。文字走 agent_update_node；图片 src 走 agent_replace_node。只针对单个叶子，保留原始全部属性/style/class。写入前比较当前文字，完全相同则跳过，避免无效更新。图片使用原图、本地确定路径；禁止生成、重编码、裁切二维码。对有富文本混排的节点，本脚本拒绝操作，需明确字符范围映射并保护各段样式，不能扁平化。
7. **验收再批量**：样例通过后串行处理每张画板；可批量读取，不能同时抢同一设计文件的连接。每张立即读回并核验，再处理下一张。不每张重新发现工具或启动客户端。优先复用单个 MCP 会话。
8. **最终报告**：输出成功/异常/未知数量、画板 ID 或链接、运行清单和检查结果。不得把“payload 已生成”“请求已接受”当作画板已完成。

## 必须保持的属性

固化层全子树、层级/顺序、组件引用、约束/自动布局规则、局部坐标、固定宽高、圆角、描边、填充、透明度、字体/字号/字重/字距/行高、文本样式范围不变。内容槽位只允许文字值或图片资源改变。画板根的位置和名称是单独允许项，不能全局忽略所有位置/名称差异。

已证明为“适应内容”的容器，其计算宽高可随新文本自然变化；逐节点记录例外与原生 UI/API 证据，不能忽略其他尺寸差异。文本图层由产品自动将名称同步为新文字时，记录为该槽位的预期名称变化，不放宽其他名称检查。

图层被替换导致 ID 改变时重新绑定，保留旧新 ID 对照。比较前后语义结构及属性；图片临时 URL 改变不能当作视觉变化或直接忽略，解析到素材哈希后比较。HTML 快照未暴露的设计属性属于**未验证**，不能声称全属性无损。用原生复制 + 叶子修改缩小影响范围，再检查原生预览。二维码如果是小程序太阳码，普通 QR 解码失败不能判坏，需对应扫码器或人工扫描；不得声称已扫码通过。

## 超时和续跑

运行目录放持久路径，不依赖 /tmp。每个编号使用唯一 run_id/item_id；操作前写 `intent`（源/目标 ID、内容哈希、操作），返回后写 `applied`，读回核验后写 `verified`。复制超时记 `unknown`，先找本次唯一标记和读取目标，**禁止直接再复制**。图片工具即使返回“已完成”，也可能短暂读到旧图缓存；等待后重新读取并按实际图片内容比对，不能只检查 src 路径。工具返回 accepted 时，记录 accepted_pending，等待后只读核对实际目标内容（最多 5 次、间隔 2 秒），未出现预期内容就停止，不继续写下一项。任何写入超时都不自动重放；查到已完成则续验，无法确定则停该项。读取失败可重新握手后重试一次。不要杀其他任务进程、修改登录凭据或重启公共 daemon。源稿变动、素材哈希变化、文件/页面切换时停止旧计划，重新绑定。

## 工具与格式

- [脚本接口与验收](references/workflow.md)：执行脚本、payload 输入、运行记录及恢复规则。
- [本机博物馆案例](references/aba-museum.md)：已读到的候选母版与素材信息；这些 ID 是案例，其他项目不得复用。
- `runtime/package-lock.json` 固定官方客户端依赖，迁移时在 runtime 中运行 `npm ci --no-audit --no-fund`。

这些脚本提供连接探测、素材准备、叶子修改防漂移；另有已绑定副本的串行修改执行器 apply_sample.py；原生复制仍通过 UI 完成，因此它们不是全自动原生复制执行器，也不能保证没有相应工具权限的 Agent 完成设计写入。

## 安装

```bash
git clone git@git.internal:design/mastergo-template-fill.git ~/.dsh/skills/mastergo-template-fill
```

重启 DSH 后生效；更新执行 `git pull`。
