| name | pencil-design-updater |
| description | 根据用户口述需求对 Pencil `.pen` 设计稿做增量更新，包含需求归一化、目标节点定位、最小化结构修改、组件复用保护、移动端布局约束校验和截图回归。用于用户要求改文案、调布局、增删模块、替换卡片、调整头部/背景、按描述修改当前 Pencil 设计稿，尤其适合“我说一句，你直接改稿”的场景。 |
Pencil Design Updater
Overview
把用户的口述需求转成对 Pencil 设计稿的精确修改，并在修改后完成结构校验与截图回归。优先做局部、可验证、可回滚的增量更新，不把“小改稿”做成整页重画。
需要具体操作样式、移动端全屏背景结构或组件复用判断时，读取 references/update-patterns.md。
Workflow
-
先归一化口述需求
- 提取目标页面、目标区域、动作类型、视觉约束、是否允许结构调整。
- 把模糊描述转成最小可执行指令，例如：
- “顶部更高级一点” -> 头部区域需要重排，可能涉及背景、标题层级、卡片位置。
- “这块往上提一点” -> 先定位具体节点，再判断是
M 还是 U(..., {margin/padding/...})。
- 能安全推断时直接执行；若缺少关键信息且错误成本高，再提出一个简短问题。
-
先读当前设计，再决定改法
- 先用编辑器状态确认当前
.pen 文件、当前选区、schema 是否已加载。
- 先读取目标 screen 或目标容器，不要一上来全量扫描整份文档。
- 用户只给“这一块”“上面那个卡片”之类口述时，优先结合：
-
先选最小修改路径
- 改文本、颜色、圆角、间距、显隐，优先
U(...)。
- 改层级顺序或移入其他容器，优先
M(...)。
- 新增区块或补充节点，使用
I(...)。
- 需要替换节点类型、替换组件槽位或整块内容，使用
R(...)。
- 非必要不要删除后重建；先保留可复用结构和已有组件关系。
-
对较大区域改动先加占位保护
- 修改整个 screen、长列表、复杂头部、组合卡片区域前，先给工作区域加
placeholder:true。
- 完成后移除占位状态，避免后续节点插入位置异常。
-
保护现有组件复用关系
- 遇到
type:"ref" 的真实组件实例时，优先覆写实例可覆写字段，不要随手打散成普通节点。
- 用户要求“统一修改所有同类卡片”或“改成公共样式”时，先判断当前是否真组件复用。
- 不能把“看起来一样”当作复用证据；需要以
type:"ref" 和 ref 为准。
-
修改后必须验证
- 重新读取被修改节点，确认结构、属性和组件关系符合预期。
- 对布局改动再做一次问题扫描，重点看裁切、重叠、越界。
- 用截图检查视觉结果，不只看结构树。
-
交付时明确说明
- 改了哪些区域
- 是否用了组件实例覆写、替换或移动
- 是否完成结构校验和截图回归
- 若存在仍未落地的模糊需求，明确指出
Hard Rules
- 默认做增量修改，不随意扩大设计范围。
- 没有用户授权时，不擅自重做整屏视觉风格。
- 修改前先确认父容器和目标节点，避免把“相邻但无关”的模块一起改坏。
- 处理移动端全屏背景、头部渐变、内容居中结构时，遵循
references/update-patterns.md 中的层级规则。
- 改动重复模块时，先判断是否已有真实复用；不要把真实组件实例改回普通
frame。
- 大改完成后必须读结构和看截图，截图只用于视觉验证，不用于证明组件复用。
Decision Rules
Text Or Style Change
- 文案、字号、颜色、圆角、边框、padding、gap、显隐等属性变化，优先
U(...)。
- 如果只是单个实例文案不同，优先改实例覆写，不要改组件源。
Structural Move
- 模块上下换位、移入新容器、从头部挪到内容区，优先
M(...)。
- 移动前先确认目标父容器是否具备正确 layout、gap、padding。
Section Insert
- 口述需求包含“加一个模块”“补一行提示”“底部插入卡片”时，先创建容器，再插内容。
- 需要与现有视觉体系一致时，优先复用已有组件或同层级结构。
Replace Instead Of Patch
- 当节点类型需要变化，或组件实例中的某个槽位要整个换掉时，使用
R(...)。
- 不要用
U(...) 去硬改 type、ref 或 children。
Mobile Layout Constraint
- 移动端页面默认优先保持 402px 屏宽与 362px 内容宽度体系。
- 涉及全屏背景时，主容器不要带左右 padding；内容另包一层固定宽度容器。
Delivery Rule
最终结果中始终给出：
- 目标页面或目标节点
- 采用的主要操作类型
- 是否影响组件复用关系
- 是否通过结构校验
- 是否完成截图回归
