Aile：Pencil 设计（aile-pencil-design）

概述

当 Story 涉及 UI/交互变更时，本技能用于阶段 2 产出可审查、可执行、可回溯的设计产物：

• docs/plans/{Story-Key}/design.pen（推荐）
• 在 docs/plans/{Story-Key}/analysis.md 回填 UI 设计章节与证据
• 若不产出 .pen，必须明确写出“本 Story 无 UI 设计”及原因

本技能采用 MCP-first 方式，核心目标是把“设计描述”升级为“设计执行规范 + 证据化门禁”。

来源原 Skill

• 来源：superpowers 原始需求分析与计划能力（已迁移为 aile-only）
• 策略：保留原 Skill 作为基线与回退路径，本 Skill 复制改写并强化 Pencil MCP 执行规范。

何时使用 / 何时跳过

使用场景

• Story 新增页面、弹窗、关键交互流程
• 现有页面布局、状态展示、交互反馈发生变化
• 需求明确要求提供设计稿/画布/原型

跳过场景

• 纯后端、数据处理、脚本、配置调整且无可见 UI 变化

跳过时必须在 analysis.md 写明：本 Story 无 UI 设计，并给出理由。

输入契约（先定义再作图）

在开始 MCP 操作前，先固化以下输入：

1. 页面/模块边界：本次改动影响哪些页面或弹层
2. 状态矩阵：正常 / 空 / 加载 / 异常（必要时加权限态）
3. 交互路径：入口、主流程、失败回路、返回路径
4. 复用策略：优先复用现有组件，缺失时再新增

输出契约（必须遵守）

• 产物目录：docs/plans/{Story-Key}/
• 设计文件：design.pen（有 UI 变更时必需）
• analysis.md 的 UI 章节必须包含：
  • 页面结构
  • 核心交互流程
  • 状态设计（正常/空/加载/异常）
  • 与 PM UI 示意对照说明
  • 关键截图与布局检查结论

执行流程（MCP-first）

Step 0：Pencil MCP 可执行性预检

执行前必须确认：

1. Pencil 已启动（桌面端或编辑器扩展）
2. MCP 已连接且工具可用
3. 目标文件位于项目工作区
4. 已约定保存策略（关键批次后手动保存）

若预检失败：

• 在 analysis.md 标记 UI 设计阻塞
• 记录阻塞原因、影响范围、恢复条件
• 输出最小线框说明和状态清单，待 MCP 恢复后补齐 design.pen

Step 1：初始化设计上下文

按顺序调用最小工具链：

1. open_document
2. get_editor_state
3. get_guidelines（按场景选择）
4. batch_get（一次性检索可复用组件）
5. get_variables（缺失时再 set_variables 补齐最小 token）

Step 2：分批构图（结构优先）

• 每次 batch_design 控制在 <=25 操作
• 先骨架后细节：布局框架 → 组件实例 → 文案与状态 → 视觉微调
• 推荐批次：
  • 批次 A：发现与复用
  • 批次 B：骨架搭建
  • 批次 C：核心状态（正常/空/加载/异常）
  • 批次 D：失败回路与返回路径

Step 3：每批质量门禁（硬性）

每一批都必须完成以下检查后再进入下一批：

1. snapshot_layout（problemsOnly=true）检查重叠/裁剪/越界
2. snapshot_layout（常规）复核结构
3. get_screenshot 抽样关键节点截图（至少主流程 + 异常态）

未通过则立即修正，不允许带问题进入下一批。

Step 4：回填计划文档

在 analysis.md 的 UI 小节回填：

• .pen 文件路径
• 状态覆盖清单（正常/空/加载/异常）
• 交互路径覆盖（入口、主流程、失败回路、返回路径）
• 遗留风险与后续动作

Step 5：准备 G2 审查材料

PR 中至少包含：

• analysis.md
• design.pen（如有 UI 变更）
• docs-templates/g2-design-review-checklist.md 对应自检结果

失败兜底与恢复策略

1. MCP 不可用：标记阻塞并降级为线框说明，不得跳过 UI 章节
2. 权限/连接异常：先检查 Pencil 是否运行、MCP 是否可见、工作区权限是否正确
3. 保存风险：关键批次后立刻手动保存并落 Git 版本

UI Definition of Done（DoD）

满足以下条件才允许进入开发阶段：

• 已产出并保存 design.pen，或明确“本 Story 无 UI 设计”
• 状态矩阵至少覆盖正常/空/加载/异常四态
• 主流程与失败回路均有可见反馈
• snapshot_layout 与 get_screenshot 验收通过
• analysis.md 的 UI 章节已完整回填