pencil-component-creator

name	pencil-component-creator
description	为 Pencil `.pen` 设计文件创建可复用组件、替换重复节点为真实 `ref` 实例、校验组件是否真的被复用。用于用户要求抽组件、沉淀公共组件、统一卡片/按钮/商品块、把重复结构替换成组件实例，或排查“看起来像组件但其实不是复用”的情况。

Pencil Component Creator

Overview

为 Pencil 中的重复 UI 结构建立真正可复用的组件源，并把页面上的重复节点替换成真实 ref 实例。重点处理 reusable、ref、descendants、placeholder、实例验证和回归截图。

需要精确操作示例、常见覆写写法和反例时，读取 references/patterns.md。

Workflow

1. 先定位目标节点：读取当前 .pen 文件、目标区域、重复节点和候选组件源。
2. 先判断现状：确认目标节点现在是普通 frame、已有 ref，还是“视觉相同但不是真组件”。
3. 先确定组件源：
   • 已有可靠组件源时，直接复用。
   • 没有可靠组件源时，新建一个真正的 reusable 源。
4. 对“公共组件”先做编辑器级验真：
   • 组件源必须在当前编辑器里被识别为真正可复用组件，而不只是磁盘文件里写了 reusable:true。
   • 必要时先插入一个临时 ref 实例做探针，确认编辑器返回的是 type:"ref"。
5. 对目标屏幕先加 placeholder:true，整个替换过程保持占位，结束后再移除。
6. 用真实组件源替换重复节点，实例差异只通过 descendants 覆写。
7. 用 batch_get 验证实例节点必须是 type:"ref" 且 ref:"<sourceId>"。
8. 对公共组件做一次联动验证：
   • 改组件源的一个安全字段，例如图标尺寸、占位文本或颜色；
   • 确认页面实例同步变化；
   • 再恢复到目标值。
9. 用 get_screenshot 检查页面与组件源是否仍然符合预期。

Hard Rules

• 真正的复用，必须以实例节点读出来是 type:"ref" 为准。不要用“样式很像”或“节点名相同”当证据。
• 实例名不同、商品名称不同、价格不同，仍然可能是复用。判断依据始终是 type:"ref" 和 ref。
• 当用户明确要求“使用公共组件”时，不要接受“复制一份长得一样的 frame”这种结果。
• 当用户要求“公共组件”时，验收标准必须同时满足三件事：
  • 组件源在当前编辑器里是可复用组件；
  • 页面节点读出来是 type:"ref" 且 ref 指向该组件源；
  • 修改组件源后，页面实例会同步联动。
• 修改现有页面时，先给对应 screen 或工作区域加 placeholder:true，结束后及时去掉。
• 优先把组件源放在画布空白区，不要压在现有页面上。
• 实例差异只改 descendants 中必要字段；不要把圆角、字号、布局等基础视觉在每个实例里重写一遍，除非用户明确要变体。
• 若目标是“同一视觉体系下的变体”，先判断是继续覆写实例，还是应该拆成单独组件变体。不要在一个实例上积累过多局部样式差异。
• 如果改了组件源但页面没有跟着变，不要再宣称“已经复用成功”；这说明当前页面仍是展开节点、假实例，或者挂错了组件源。

Source Creation Rules

• 需要可靠组件源时，优先直接新建一个 reusable:true 的组件源，而不是先做普通节点再赌后续转换成功。
• 新组件源应包含最小必要结构：外层容器、核心内容节点、后续需要覆写的文本/图像槽位。
• 给组件内部关键节点起稳定名字并保留清晰 id 路径，方便后续 descendants 覆写。
• 若组件需要多个页面复用，优先使用中性命名，如 Component/Product/CompactCard/Shared，避免绑定单一页面语义。
• 如果旧组件源在磁盘文件里看似存在，但编辑器不把它识别为可复用组件，直接在编辑器里新建一个新的真实组件源，再让页面改挂这个新源。

Replacement Rules

• 替换前先读取目标区域结构，确认待删节点和要保留的父容器。
• 替换时优先插入新的 ref 实例，再做最小必要的 descendants 覆写。
• 商品卡、按钮、列表项这类重复结构，常见可覆写字段包括：
  • 名称文本
  • 价格/原价文本
  • 图像占位 fill 或显隐
  • 少量状态色
• 若分类页、首页、详情页对同一组件的尺寸差异很大，不要硬塞同一个实例样式。先判断是否拆 CategoryVariant、CompactVariant 等变体组件。

Verification Rules

• 替换完成后，必须重新读取实例节点本身，而不是只读父容器截图。
• 验证通过标准：
  • 节点是 type:"ref"
  • ref 指向正确组件源 id
  • 仅存在预期的 descendants 覆写
• 若用户要的是“公共组件联动”，还必须额外验证：
  • 改组件源一个安全字段；
  • 页面实例同步变化；
  • 恢复字段后页面也恢复。
• 若截图和结构读取冲突，先以 MCP 读取到的当前编辑器节点结构为准，再决定是否检查磁盘上的 .pen 文件。
• 截图只用于验证视觉结果，不用于证明“是否真正复用”。

Recovery Rules

• 如果发现页面上的“组件”其实是独立 frame，直接承认并修正，不要继续围绕错误前提打补丁。
• 若旧的候选组件源无法稳定作为真实复用源，直接新建新的 reusable 组件源，再批量替换实例。
• 若磁盘文件里已经写成 ref，但编辑器里页面仍不跟随组件源变化，按“未成功复用”处理：
  • 在编辑器里重建真实组件源；
  • 重新插入真实 ref 实例；
  • 删除失效的旧源、探针实例和展开节点。
• 替换过程中若插入了测试节点、探针实例或临时组件，结束前全部清理。

Delivery Rule

在最终结果中明确给出：

• 组件源 id
• 哪些节点已经替换为真实 ref 实例
• 是否存在仅视觉一致但不是复用的剩余节点
• 是否完成“改组件源即联动页面”的验证
• 是否完成截图校验