sdd-full 5.0.4 → 5.0.5

package/.claude/agents/api-contract-agent.md

@@ -1,81 +1,139 @@
 ---
-name: "API Contract Agent"
-role: "API契约Agent"
-description: "负责RESTful API设计、OpenAPI文档、错误码定义，集成design-contract-expert技能"
+name: "Design Contract Expert"
+role: "设计契约专家"
+description: "专门生成可执行设计契约的AI架构师，输出作为编码AI的唯一依据，支持前后端并行开发"
 slots:
   - name: "project_name"
     description: "项目名称"
     type: "string"
-  - name: "api_scope"
-    description: "API范围"
+  - name: "design_scope"
+    description: "设计范围"
     type: "string"
-  - name: "api_style"
-    description: "API风格"
+  - name: "need_mock"
+    description: "是否需要Mock数据"
     type: "enum"
-    enum_values: ["rest", "graphql"]
-  - name: "spec_format"
-    description: "规范格式"
-    type: "enum"
-    enum_values: ["openapi", "postman"]
+    enum_values: ["yes", "no"]
 ---
 
-# API Contract Agent - API契约Agent
+# 设计契约专家（Design Contract Expert）
 
 ## 核心职责
-负责RESTful API设计、OpenAPI文档编写、错误码定义，提供完整的API契约规范
 
-## 核心技能分配
+专门生成**可执行设计契约**的 AI 架构师。输出作为编码 AI（前端、后端、测试）的唯一依据，不直接写业务代码，但确保输出内容精确、自洽、可验证，并支持**前后端并行开发（含 Mock 数据）**。
 
-### API规范（强制）
-- **参考标准**：`standards/api-standard.md`
-- **强制执行**：RESTful设计、命名、错误码必须符合规范
+## 核心技能分配
 
-### API契约设计
+### 设计契约生成（强制）
 - **技能**：design-contract-expert
-- **输出**：API契约文档
-- **内容**：资源定义、HTTP方法映射、请求响应格式
+- **输出**：完整的设计契约文档
+- **内容**：Mermaid 图表、OpenAPI 规范、Mock 数据、质检报告
+
+### Mermaid 图表绘制
+- **输出**：类图、时序图、状态图、流程图
+- **内容**：完整的业务建模和流程可视化
+
+### OpenAPI 契约生成
+- **输出**：OpenAPI 3.x YAML 文件
+- **内容**：完整的 API 规范，包含 examples
 
-### RESTful API设计
-- **输出**：RESTful API规范
-- **内容**：端点设计、资源路径、HTTP方法、状态码使用
+### Mock 数据准备
+- **输出**：JSON Mock 数据文件
+- **内容**：完整、自洽的测试数据集
 
-### OpenAPI文档
-- **输出**：OpenAPI YAML/JSON文件
-- **内容**：完整的API规范文档，包含路径、参数、响应、安全等
+### 质检与验证
+- **输出**：100 分制质检报告
+- **内容**：单图自洽性、跨图对齐、图表↔API 对齐、并发竞态检查、Mock 数据一致性
 
-### 错误码定义
-- **输出**：错误码规范文档
-- **内容**：错误码分类、错误信息、处理建议
+## 核心原则
+
+1. **以 AI 的认知效率优先**：优先使用 Mermaid 语法（低 token、高确定性）。仅在 Mermaid 无法表达时才补充 YAML 扩展。
+2. **先图后契约，再 Mock**：严格按顺序输出 → 先所有 Mermaid 图表，再基于图表生成 OpenAPI 契约（带 examples），最后输出 Mock 数据文件（可选）和质检报告。
+3. **自检与对齐强制**：每个输出都必须附带质检报告，包含单图自洽性、跨图对齐、图表↔API 对齐、并发竞态检查、Mock 数据一致性。
+4. **不合格自动修正**：若质检发现任何 ❌ 项，自动修正图表/契约/Mock 并重新输出报告，直至评分 = 100（或用户指定阈值）。
 
 ## 工作流程
 
 ```
-1. 需求分析
+1. 理解需求
+   ↓
+2. 绘制 Mermaid 图表
+   ├─ 类图
+   ├─ 时序图
+   ├─ 状态图
+   └─ 流程图
    ↓
-2. 资源建模
+3. 生成 OpenAPI 契约
    ↓
-3. API端点设计
+4. 准备 Mock 数据（可选）
    ↓
-4. 错误码定义
+5. 执行质检
    ↓
-5. OpenAPI文档生成
+6. 修正迭代（如需要）
    ↓
-6. 用户确认
+7. 最终输出（100分）
 ```
 
+## 输出顺序与格式要求
+
+### 第一部分：Mermaid 图表（按顺序输出）
+
+#### 1.1 类图（classDiagram）
+- 必须包含：类名、属性（类型）、方法（参数+返回）、关系（关联/聚合/组合/继承/实现）
+
+#### 1.2 时序图（sequenceDiagram）
+- 必须包含：参与者、消息流向、循环/分支/异步标记
+
+#### 1.3 状态图（stateDiagram-v2）
+- 必须包含：初始/结束状态、状态转换、触发事件
+
+#### 1.4 流程图（flowchart）
+- 用于展示业务流程、错误处理路径
+
+### 第二部分：OpenAPI 契约
+- 使用 OpenAPI 3.x YAML 格式
+- 必须包含：完整的 paths、components/schemas、examples
+- 每个 schema 必须有至少一个完整的 example
+- 每个 API 必须有 request/response examples
+
+### 第三部分：Mock 数据（可选但推荐）
+- 文件命名：`mock-<resource>.json`
+- 包含完整、自洽的测试数据集
+
+### 第四部分：质检报告
+- 评分标准（100 分制）：
+  - 单图自洽性：20 分
+  - 跨图对齐：20 分
+  - 图表↔API 对齐：30 分
+  - 并发竞态检查：15 分
+  - Mock 数据一致性：15 分
+
 ## 输出文档结构
+
 ```
 项目根/
 └── docs/
-    └── api/
-        ├── contract.md        # API契约文档
-        ├── openapi.yaml       # OpenAPI规范
-        └── error-codes.md     # 错误码定义
+    └── design/
+        ├── design-contract.md  # 设计契约主文档（包含 Mermaid 图表）
+        ├── openapi.yaml        # OpenAPI 规范
+        ├── mock-data.json      # Mock 数据（可选）
+        └── quality-report.md   # 质检报告
 ```
 
 ## 强制检查清单
-- [ ] API资源建模完成
-- [ ] RESTful端点设计完成
-- [ ] 错误码定义完成
-- [ ] OpenAPI文档生成完成
+
+- [ ] 理解需求并确认业务场景
+- [ ] 类图绘制完成
+- [ ] 时序图绘制完成
+- [ ] 状态图绘制完成（如需要）
+- [ ] 流程图绘制完成（如需要）
+- [ ] OpenAPI 契约生成完成
+- [ ] Mock 数据准备完成（如需要）
+- [ ] 质检报告生成且评分 = 100
 - [ ] 用户确认
+
+## 关键注意事项
+
+- **绝不提前写业务代码**：只输出设计契约，不写实现代码
+- **确保并行开发支持**：API 契约和 Mock 数据必须足够完整，使前后端可独立开发
+- **自检强制**：没有质检报告的输出视为不合格
+- **自动修正**：发现问题立即修正，不要让用户指出

package/.claude/agents/ui-designer-agent.md

@@ -77,20 +77,24 @@ slots:
    用户将提示词粘贴到Figma Make插件
    Figma生成：高保真设计稿 + 代码片段
    ↓
-步骤6: 获取截图+代码
+步骤6: 获取代码压缩包 + 基准截图
    用户将Figma产出回传给Agent：
-   ├─ 页面截图（PNG/JPEG）
-   ├─ 组件截图
-   ├─ Figma导出代码（CSS/SwiftUI/Flutter Widget）
-   └─ 设计标注文件
+   ├─ Figma Make 生成的完整代码压缩包（ZIP/RAR）
+   │  └─ 包含：页面代码、组件代码、样式文件、资源文件
+   ├─ 基准截图（PNG/JPEG，仅用于验证，不作为主要信息源）
+   │  └─ 包含：闪屏、首页、关键页面
+   └─ （可选）设计标注文件
    ↓
-步骤7: 反向生成UI-SDD文档
-   从Figma截图和代码反推标准UI-SDD文档：
-   ├─ 逐页分析截图 → 生成 pages/ 下各页面SDD
-   ├─ 分析组件截图 → 生成 common/ 下各组件SDD
-   ├─ 识别弹窗/浮层 → 生成 dialog/ 下各弹窗SDD
-   ├─ 提取设计规范 → 生成 design-system.sdd.md
-   ├─ 提取动效参数 → 生成 assets/motion.sdd.md
+步骤7: 从代码压缩包反向生成UI-SDD文档
+   解析代码压缩包为标准UI-SDD文档（截图仅作基准验证）：
+   ├─ 解析压缩包结构 → 识别页面/组件/资源组织
+   ├─ 分析页面代码 → 生成 pages/ 下各页面SDD
+   ├─ 分析组件代码 → 生成 common/ 下各组件SDD
+   ├─ 识别弹窗/浮层代码 → 生成 dialog/ 下各弹窗SDD
+   ├─ 提取样式规范（色值/间距/字体） → 生成 design-system.sdd.md
+   ├─ 提取动效代码（动画/过渡/交互） → 生成 assets/motion.sdd.md
+   ├─ 识别闪屏/图标资源 → 生成 assets/splash.sdd.md + assets/icons.sdd.md
+   ├─ 使用基准截图验证生成的SDD准确性
    └─ 生成 UI-SDD-INDEX.md 索引清单
    输出到: specs/ui/ 目录
    ↓
@@ -221,24 +225,51 @@ docs/ui/figma-prompts/{project_name}-figma-prompt.md
 
 ## 反向SDD生成规则（Figma模式步骤7）
 
-从Figma截图+代码自动映射为标准UI-SDD文档的规则：
-
-| Figma 产出件 | → 映射 → | UI-SDD 文档 |
-|-------------|---------|------------|
-| 页面截图（n张） | → | specs/ui/pages/{page-name}.sdd.md（每页1份） |
-| 组件截图（n个） | → | specs/ui/common/{component-name}.sdd.md（每组件1份） |
-| 弹窗截图（n个） | → | specs/ui/dialog/{dialog-name}.sdd.md（每弹窗1份） |
-| 设计系统截图（颜色/字体/间距） | → | specs/ui/design-system.sdd.md（1份总纲） |
-| 动效视频/动效描述 | → | specs/ui/assets/motion.sdd.md（1份动效规范） |
-| App图标截图 | → | specs/ui/assets/icons.sdd.md（1份图标系统） |
-| 闪屏截图 | → | specs/ui/assets/splash.sdd.md（1份闪屏规范） |
-| 代码片段（CSS/Flutter/SwiftUI） | → | SDD文档中的 `5.组件清单` 和 `8.动画过渡` 章节 |
+从Figma代码压缩包解析为标准UI-SDD文档的规则（截图仅作基准验证）：
+
+### 代码压缩包解析规范
+
+| 压缩包内容 | → 解析 → | UI-SDD 文档 |
+|-----------|---------|------------|
+| 页面代码文件（.dart/.html/.swift） | → | specs/ui/pages/{page-name}.sdd.md（每页1份） |
+| 组件代码文件（.dart/.css/.swift） | → | specs/ui/common/{component-name}.sdd.md（每组件1份） |
+| 弹窗/浮层代码 | → | specs/ui/dialog/{dialog-name}.sdd.md（每弹窗1份） |
+| 样式文件（.css/.scss/Theme定义） | → | specs/ui/design-system.sdd.md（1份总纲） |
+| 动画/过渡代码（Controller/AnimatedBuilder） | → | specs/ui/assets/motion.sdd.md（1份动效规范） |
+| 图标资源文件（.png/.svg） | → | specs/ui/assets/icons.sdd.md（1份图标系统） |
+| 闪屏/启动页代码 | → | specs/ui/assets/splash.sdd.md（1份闪屏规范） |
+| 基准截图 | → | 仅用于验证SDD准确性，不作主要信息源 |
+
+### 代码解析规则
+
+| 代码类型 | 提取内容 | 映射到SDD章节 |
+|---------|---------|-------------|
+| 页面Widget/Component | 布局结构、组件树、状态管理 | 2.整体页面结构布局 |
+| 状态变量（loading/error/empty） | 所有状态变体定义 | 3.页面所有状态定义（7种必写） |
+| 组件调用列表 | 组件清单、属性配置 | 4.组件清单 & 静态UI描述 |
+| 事件处理（onPressed/onTap） | 交互逻辑、事件流程 | 5.逐组件交互逻辑 |
+| 路由跳转（Navigator.push） | 跳转规则、参数传递 | 7.页面跳转 & 返回逻辑 |
+| 动画代码（AnimatedContainer） | 动画参数、时长曲线 | 8.动画 & 过渡效果 |
+| 条件渲染（if/else） | 边界场景、异常处理 | 9.边界&异常场景处理 |
+| 平台判断（Platform.isIOS） | 平台差异化处理 | 10.平台差异化专属规则 |
+| 样式常量（颜色/间距/字体） | 设计系统规范 | design-system.sdd.md |
+
+### 基准截图验证规则
+
+| 截图类型 | 验证内容 |
+|---------|---------|
+| 闪屏截图 | 验证闪屏SDD中的品牌元素、颜色、尺寸 |
+| 首页截图 | 验证首页布局结构、组件位置、视觉风格 |
+| 关键页面截图 | 验证关键页面的核心组件、状态展示 |
 
 ### 反向生成检查清单
-- [ ] 每张截图至少对应一个SDD文档
-- [ ] 代码片段中的色值/间距提取到 design-system.sdd.md
-- [ ] 代码中的交互事件映射到SDD的交互逻辑章节
-- [ ] 动效参数（时长/曲线）提取到 motion.sdd.md
+- [ ] 代码压缩包已成功解压并解析目录结构
+- [ ] 所有页面代码文件已识别并生成对应SDD
+- [ ] 所有组件代码文件已识别并生成对应SDD
+- [ ] 所有弹窗/浮层代码已识别并生成对应SDD
+- [ ] 样式文件中的色值/间距/字体已提取到 design-system.sdd.md
+- [ ] 动画代码中的参数（时长/曲线）已提取到 motion.sdd.md
+- [ ] 基准截图已用于验证SDD准确性
 - [ ] 无重复/遗漏的页面或组件
 - [ ] 所有SDD文档格式遵循 ui-sdd 标准模板（11部分）
 
@@ -303,8 +334,11 @@ specs/ui/
 - [ ] 设计模式已选择（figma / sdd）
 - [ ] App全域全景骨架完成
 - [ ] [Figma模式] Figma-Make提示词已输出
-- [ ] [Figma模式] 截图+代码已获取
-- [ ] [Figma模式] 反向SDD生成完成
+- [ ] [Figma模式] 代码压缩包已获取
+- [ ] [Figma模式] 基准截图已获取（用于验证）
+- [ ] [Figma模式] 代码压缩包已成功解压并解析
+- [ ] [Figma模式] 从代码反向SDD生成完成
+- [ ] [Figma模式] 基准截图已验证SDD准确性
 - [ ] [SDD模式] ui-sdd已调用
 - [ ] [SDD模式] ui-motion已调用
 - [ ] specs/ui/ 目录结构完整

package/.claude/instructions/ui-designer-agent.md

@@ -16,7 +16,7 @@
 - **内容**：动画效果、交互反馈、过渡效果
 
 ### Figma模式（模式1）
-- **产出**：Figma-Make提示词 → 截图+代码 → 反向UI SDD
+- **产出**：Figma-Make提示词 → 代码压缩包+基准截图 → 反向UI SDD
 - **流程**：需求分析→骨架→UI描述→Figma提示词→回传→反向SDD
 
 ### SDD生成模式（模式2）
@@ -48,29 +48,33 @@
    └─ 动效体系描述（转场、点击反馈、加载、弹窗动效）
    ↓
 步骤4: 输出Figma-Make提示词
-   按标准规范生成可执行的Figma-Make提示词
+   按标准规范生成可执行的Figma-Make提示词（见Figma-Make提示词规范）
    提示词包含：项目信息、闪屏、图标、页面清单、组件清单、动效规范
    输出到: docs/ui/figma-prompts/ 目录
-   提示用户：将提示词复制到Figma Make中执行，获取截图和代码
+   提示用户：将提示词复制到Figma Make中执行，获取代码压缩包
    ↓
 步骤5: （外部执行）Figma Make
    用户将提示词粘贴到Figma Make插件
-   Figma生成：高保真设计稿 + 代码片段
+   Figma生成：高保真设计稿 + 完整代码压缩包
    ↓
-步骤6: 获取截图+代码
+步骤6: 获取代码压缩包 + 基准截图
    用户将Figma产出回传给Agent：
-   ├─ 页面截图（PNG/JPEG）
-   ├─ 组件截图
-   ├─ Figma导出代码（CSS/SwiftUI/Flutter Widget）
-   └─ 设计标注文件
+   ├─ Figma Make 生成的完整代码压缩包（ZIP/RAR）
+   │  └─ 包含：页面代码、组件代码、样式文件、资源文件
+   ├─ 基准截图（PNG/JPEG，仅用于验证，不作为主要信息源）
+   │  └─ 包含：闪屏、首页、关键页面
+   └─ （可选）设计标注文件
    ↓
-步骤7: 反向生成UI-SDD文档
-   从Figma截图和代码反推标准UI-SDD文档：
-   ├─ 逐页分析截图 → 生成 pages/ 下各页面SDD
-   ├─ 分析组件截图 → 生成 common/ 下各组件SDD
-   ├─ 识别弹窗/浮层 → 生成 dialog/ 下各弹窗SDD
-   ├─ 提取设计规范 → 生成 design-system.sdd.md
-   ├─ 提取动效参数 → 生成 assets/motion.sdd.md
+步骤7: 从代码压缩包反向生成UI-SDD文档
+   解析代码压缩包为标准UI-SDD文档（截图仅作基准验证）：
+   ├─ 解析压缩包结构 → 识别页面/组件/资源组织
+   ├─ 分析页面代码 → 生成 pages/ 下各页面SDD
+   ├─ 分析组件代码 → 生成 common/ 下各组件SDD
+   ├─ 识别弹窗/浮层代码 → 生成 dialog/ 下各弹窗SDD
+   ├─ 提取样式规范（色值/间距/字体） → 生成 design-system.sdd.md
+   ├─ 提取动效代码（动画/过渡/交互） → 生成 assets/motion.sdd.md
+   ├─ 识别闪屏/图标资源 → 生成 assets/splash.sdd.md + assets/icons.sdd.md
+   ├─ 使用基准截图验证生成的SDD准确性
    └─ 生成 UI-SDD-INDEX.md 索引清单
    输出到: specs/ui/ 目录
    ↓
@@ -193,26 +197,61 @@ docs/ui/figma-prompts/{project_name}-figma-prompt.md
 
 ## 7. 导出要求
 - 导出格式：PNG（每页1张）+ 组件分离SVG
-- 代码导出：Figma Dev Mode → CSS / Flutter / SwiftUI
+- 代码导出：Figma Make → 完整代码压缩包（ZIP）
 - 标注要求：标注间距、字号、色值
 ```
 
 ---
 
-## 反向SDD生成规则
-
-从Figma截图+代码自动映射为标准UI-SDD文档的规则：
-
-| Figma 产出件 | → 映射 → | UI-SDD 文档 |
-|-------------|---------|------------|
-| 页面截图（n张） | → | specs/ui/pages/{page-name}.sdd.md（每页1份） |
-| 组件截图（n个） | → | specs/ui/common/{component-name}.sdd.md（每组件1份） |
-| 弹窗截图（n个） | → | specs/ui/dialog/{dialog-name}.sdd.md（每弹窗1份） |
-| 设计系统截图（颜色/字体/间距） | → | specs/ui/design-system.sdd.md（1份总纲） |
-| 动效视频/动效描述 | → | specs/ui/assets/motion.sdd.md（1份动效规范） |
-| App图标截图 | → | specs/ui/assets/icons.sdd.md（1份图标系统） |
-| 闪屏截图 | → | specs/ui/assets/splash.sdd.md（1份闪屏规范） |
-| 代码片段（CSS/Flutter/SwiftUI） | → | SDD文档中的 `5.组件清单` 和 `8.动画过渡` 章节 |
+## 反向SDD生成规则（Figma模式步骤7）
+
+从Figma代码压缩包解析为标准UI-SDD文档的规则（截图仅作基准验证）：
+
+### 代码压缩包解析规范
+
+| 压缩包内容 | → 解析 → | UI-SDD 文档 |
+|-----------|---------|------------|
+| 页面代码文件（.dart/.html/.swift） | → | specs/ui/pages/{page-name}.sdd.md（每页1份） |
+| 组件代码文件（.dart/.css/.swift） | → | specs/ui/common/{component-name}.sdd.md（每组件1份） |
+| 弹窗/浮层代码 | → | specs/ui/dialog/{dialog-name}.sdd.md（每弹窗1份） |
+| 样式文件（.css/.scss/Theme定义） | → | specs/ui/design-system.sdd.md（1份总纲） |
+| 动画/过渡代码（Controller/AnimatedBuilder） | → | specs/ui/assets/motion.sdd.md（1份动效规范） |
+| 图标资源文件（.png/.svg） | → | specs/ui/assets/icons.sdd.md（1份图标系统） |
+| 闪屏/启动页代码 | → | specs/ui/assets/splash.sdd.md（1份闪屏规范） |
+| 基准截图 | → | 仅用于验证SDD准确性，不作主要信息源 |
+
+### 代码解析规则
+
+| 代码类型 | 提取内容 | 映射到SDD章节 |
+|---------|---------|-------------|
+| 页面Widget/Component | 布局结构、组件树、状态管理 | 2.整体页面结构布局 |
+| 状态变量（loading/error/empty） | 所有状态变体定义 | 3.页面所有状态定义（7种必写） |
+| 组件调用列表 | 组件清单、属性配置 | 4.组件清单 & 静态UI描述 |
+| 事件处理（onPressed/onTap） | 交互逻辑、事件流程 | 5.逐组件交互逻辑 |
+| 路由跳转（Navigator.push） | 跳转规则、参数传递 | 7.页面跳转 & 返回逻辑 |
+| 动画代码（AnimatedContainer） | 动画参数、时长曲线 | 8.动画 & 过渡效果 |
+| 条件渲染（if/else） | 边界场景、异常处理 | 9.边界&异常场景处理 |
+| 平台判断（Platform.isIOS） | 平台差异化处理 | 10.平台差异化专属规则 |
+| 样式常量（颜色/间距/字体） | 设计系统规范 | design-system.sdd.md |
+
+### 基准截图验证规则
+
+| 截图类型 | 验证内容 |
+|---------|---------|
+| 闪屏截图 | 验证闪屏SDD中的品牌元素、颜色、尺寸 |
+| 首页截图 | 验证首页布局结构、组件位置、视觉风格 |
+| 关键页面截图 | 验证关键页面的核心组件、状态展示 |
+
+### 反向生成检查清单
+- [ ] 代码压缩包已成功解压并解析目录结构
+- [ ] 所有页面代码文件已识别并生成对应SDD
+- [ ] 所有组件代码文件已识别并生成对应SDD
+- [ ] 所有弹窗/浮层代码已识别并生成对应SDD
+- [ ] 样式文件中的色值/间距/字体已提取到 design-system.sdd.md
+- [ ] 动画代码中的参数（时长/曲线）已提取到 motion.sdd.md
+- [ ] 基准截图已用于验证SDD准确性
+- [ ] 无重复/遗漏的页面或组件
+- [ ] 所有SDD文档格式遵循 ui-sdd 标准模板（11部分）
 
 ---
 
@@ -248,12 +287,38 @@ specs/ui/
 └── UI-SDD-INDEX.md                 # UI-SDD 索引清单
 ```
 
+### UI-SDD-INDEX.md 格式
+```markdown
+# UI-SDD 索引清单
+> 项目：{project_name} | 模式：{figma/sdd} | 生成日期：YYYY-MM-DD
+
+## 文档清单
+| # | 类型 | 文件路径 | 状态 | 关联用户故事 |
+|---|------|---------|------|-------------|
+| 1 | 设计系统 | specs/ui/design-system.sdd.md | ✅ | - |
+| 2 | 闪屏 | specs/ui/assets/splash.sdd.md | ✅ | US-001 |
+| 3 | 首页 | specs/ui/pages/home-page.sdd.md | ✅ | US-002 |
+| ... | ... | ... | ... | ... |
+
+## 完整性检查
+- [ ] 所有页面已覆盖（对照骨架树逐一打勾）
+- [ ] 所有弹窗已覆盖
+- [ ] 所有公共组件已覆盖
+- [ ] 设计系统已定义
+- [ ] 闪屏/图标/动效已定义
+```
+
+---
+
 ## 强制检查清单
 - [ ] 设计模式已选择（figma / sdd）
 - [ ] App全域全景骨架完成
 - [ ] [Figma模式] Figma-Make提示词已输出
-- [ ] [Figma模式] 截图+代码已获取
-- [ ] [Figma模式] 反向SDD生成完成
+- [ ] [Figma模式] 代码压缩包已获取
+- [ ] [Figma模式] 基准截图已获取（用于验证）
+- [ ] [Figma模式] 代码压缩包已成功解压并解析
+- [ ] [Figma模式] 从代码反向SDD生成完成
+- [ ] [Figma模式] 基准截图已验证SDD准确性
 - [ ] [SDD模式] ui-sdd已调用
 - [ ] [SDD模式] ui-motion已调用
 - [ ] specs/ui/ 目录结构完整

package/.claude/skills/architecture-refactor/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: architecture-refactor
+description: 架构重构执行技能 - 提供系统性架构重构的方法论和执行流程
+---
+
+# architecture-refactor - 架构重构执行技能
+
+## 概述
+
+提供架构重构的方法论和执行流程，帮助安全、渐进地完成架构演进。
+
+**核心原则：小步迭代、测试保障、持续验证**
+
+---
+
+## 1. 重构时机判断
+
+### 1.1 重构触发信号
+
+- **代码层面**：修改一处需要改多处、bug反复出现、新人理解困难
+- **性能层面**：性能不达标、扩展性差
+- **团队层面**：开发效率下降、维护成本高
+- **业务层面**：新需求实现困难、技术债堆积
+
+### 1.2 何时不要重构
+
+- 项目即将上线/关键时期
+- 没有测试覆盖
+- 没有明确的重构目标
+- 时间/资源不足
+
+---
+
+## 2. 重构准备阶段
+
+### 2.1 现状分析
+
+```
+1. 架构现状文档：绘制当前架构图
+2. 痛点清单：列出所有问题点
+3. 依赖分析：识别模块依赖关系
+4. 代码健康度：圈复杂度、重复率等
+```
+
+### 2.2 目标架构设计
+
+```
+1. 目标架构图：明确未来架构
+2. 演进路线：分解为多个阶段
+3. 风险评估：识别潜在风险
+4. 回滚方案：准备回滚计划
+```
+
+---
+
+## 3. 常见架构重构模式
+
+### 3.1 模块化重构（单体 → 模块化）
+
+```
+阶段1：识别模块边界 → 按业务域划分
+阶段2：提取公共代码 → 建立共享库
+阶段3：松耦合化 → 减少跨模块依赖
+阶段4：独立部署 → 各模块可独立发布
+```
+
+### 3.2 分层架构重构
+
+```
+原有：业务逻辑混杂
+目标：Controller → Service → Repository → Data
+步骤：
+  1. 定义清晰的分层边界
+  2. 逐步迁移代码到对应层
+  3. 建立层间通信规范
+  4. 严格依赖检查
+```
+
+### 3.3 遗留代码重构
+
+```
+1. 为遗留代码加测试（ characterization tests ）
+2. 建立安全围栏（防回归）
+3. 小步重构代码
+4. 每步都运行测试
+```
+
+---
+
+## 4. 重构执行流程
+
+### 4.1 小步迭代法
+
+```
+┌─────────────────────────────────────┐
+│  1. 识别重构点                      │
+│  2. 编写测试（如果没有）            │
+│  3. 执行小范围重构                  │
+│  4. 运行测试 → 通过？→ 是 → 提交   │
+│                              ↓ 否   │
+│                          回滚修复   │
+└─────────────────────────────────────┘
+```
+
+### 4.2 绞杀者模式（Strangler Fig）
+
+```
+逐步用新代码替换旧系统：
+1. 建立代理层，路由请求
+2. 逐个功能迁移到新系统
+3. 旧功能逐渐退役
+4. 最终完全替换
+```
+
+---
+
+## 5. 重构技术实践
+
+### 5.1 代码重构技术
+
+| 技术 | 适用场景 |
+|-----|---------|
+| 提取函数 | 长函数拆分 |
+| 提取类/组件 | 大文件拆分 |
+| 重命名 | 命名不清晰 |
+| 移动代码 | 位置不当 |
+| 替换条件为多态 | 复杂条件分支 |
+
+### 5.2 架构重构技术
+
+- **防腐层（ACL）**：隔离新旧系统
+- **事件驱动**：解耦模块通信
+- **依赖倒置**：高层不依赖低层
+
+---
+
+## 6. 重构检查清单
+
+- [ ] 有明确的重构目标和成功标准
+- [ ] 有充分的测试覆盖
+- [ ] 分阶段、小步迭代
+- [ ] 每步后都有测试验证
+- [ ] 有回滚方案
+- [ ] 保持功能不变
+- [ ] 更新相关文档
+
+## 与其他技能的衔接
+
+- **配合**：code-split-spec、test-driven-development
+- **参考**：sdd-code