| name | pencil-component-creator |
| description | 为 Pencil `.pen` 设计文件创建可复用组件、替换重复节点为真实 `ref` 实例、校验组件是否真的被复用。用于用户要求抽组件、沉淀公共组件、统一卡片/按钮/商品块、把重复结构替换成组件实例，或排查“看起来像组件但其实不是复用”的情况。 |
Pencil Component Creator
Overview
为 Pencil 中的重复 UI 结构建立真正可复用的组件源，并把页面上的重复节点替换成真实 ref 实例。重点处理 reusable、ref、descendants、placeholder、实例验证和回归截图。
需要精确操作示例、常见覆写写法和反例时，读取 references/patterns.md。
Workflow
- 先定位目标节点：读取当前
.pen 文件、目标区域、重复节点和候选组件源。
- 先判断现状：确认目标节点现在是普通
frame、已有 ref，还是“视觉相同但不是真组件”。
- 先确定组件源：
- 已有可靠组件源时，直接复用。
- 没有可靠组件源时，新建一个真正的
reusable 源。
- 对“公共组件”先做编辑器级验真：
- 组件源必须在当前编辑器里被识别为真正可复用组件，而不只是磁盘文件里写了
reusable:true。
- 必要时先插入一个临时
ref 实例做探针，确认编辑器返回的是 type:"ref"。
- 对目标屏幕先加
placeholder:true，整个替换过程保持占位，结束后再移除。
- 用真实组件源替换重复节点，实例差异只通过
descendants 覆写。
- 用
batch_get 验证实例节点必须是 type:"ref" 且 ref:"<sourceId>"。
- 对公共组件做一次联动验证：
- 改组件源的一个安全字段，例如图标尺寸、占位文本或颜色；
- 确认页面实例同步变化；
- 再恢复到目标值。
- 用
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 实例
- 是否存在仅视觉一致但不是复用的剩余节点
- 是否完成“改组件源即联动页面”的验证
- 是否完成截图校验
