pencil-design-updater

name	pencil-design-updater
description	根据用户口述需求对 Pencil `.pen` 设计稿做增量更新，包含需求归一化、目标节点定位、最小化结构修改、组件复用保护、移动端布局约束校验和截图回归。用于用户要求改文案、调布局、增删模块、替换卡片、调整头部/背景、按描述修改当前 Pencil 设计稿，尤其适合“我说一句，你直接改稿”的场景。

Pencil Design Updater

Overview

把用户的口述需求转成对 Pencil 设计稿的精确修改，并在修改后完成结构校验与截图回归。优先做局部、可验证、可回滚的增量更新，不把“小改稿”做成整页重画。

需要具体操作样式、移动端全屏背景结构或组件复用判断时，读取 references/update-patterns.md。

Workflow

1. 先归一化口述需求

   • 提取目标页面、目标区域、动作类型、视觉约束、是否允许结构调整。
   • 把模糊描述转成最小可执行指令，例如：
     • “顶部更高级一点” -> 头部区域需要重排，可能涉及背景、标题层级、卡片位置。
     • “这块往上提一点” -> 先定位具体节点，再判断是 M 还是 U(..., {margin/padding/...})。
   • 能安全推断时直接执行；若缺少关键信息且错误成本高，再提出一个简短问题。

2. 先读当前设计，再决定改法

   • 先用编辑器状态确认当前 .pen 文件、当前选区、schema 是否已加载。
   • 先读取目标 screen 或目标容器，不要一上来全量扫描整份文档。
   • 用户只给“这一块”“上面那个卡片”之类口述时，优先结合：
     • 当前选区
     • 节点名称
     • 直接子节点结构
     • 必要时的截图

3. 先选最小修改路径

   • 改文本、颜色、圆角、间距、显隐，优先 U(...)。
   • 改层级顺序或移入其他容器，优先 M(...)。
   • 新增区块或补充节点，使用 I(...)。
   • 需要替换节点类型、替换组件槽位或整块内容，使用 R(...)。
   • 非必要不要删除后重建；先保留可复用结构和已有组件关系。

4. 对较大区域改动先加占位保护

   • 修改整个 screen、长列表、复杂头部、组合卡片区域前，先给工作区域加 placeholder:true。
   • 完成后移除占位状态，避免后续节点插入位置异常。

5. 保护现有组件复用关系

   • 遇到 type:"ref" 的真实组件实例时，优先覆写实例可覆写字段，不要随手打散成普通节点。
   • 用户要求“统一修改所有同类卡片”或“改成公共样式”时，先判断当前是否真组件复用。
   • 不能把“看起来一样”当作复用证据；需要以 type:"ref" 和 ref 为准。

6. 修改后必须验证

   • 重新读取被修改节点，确认结构、属性和组件关系符合预期。
   • 对布局改动再做一次问题扫描，重点看裁切、重叠、越界。
   • 用截图检查视觉结果，不只看结构树。

7. 交付时明确说明

   • 改了哪些区域
   • 是否用了组件实例覆写、替换或移动
   • 是否完成结构校验和截图回归
   • 若存在仍未落地的模糊需求，明确指出

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

最终结果中始终给出：

• 目标页面或目标节点
• 采用的主要操作类型
• 是否影响组件复用关系
• 是否通过结构校验
• 是否完成截图回归