sdd-full 5.0.4 → 5.0.6

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

package/.claude/skills/code-review-standard/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: code-review-standard
+description: 代码审查标准技能 - 具体的代码审查检查清单和审查流程规范
+---
+
+# code-review-standard - 代码审查标准技能
+
+## 概述
+
+提供具体的代码审查检查清单和审查流程规范，确保代码质量。
+
+**核心原则：客观、具体、建设性**
+
+---
+
+## 1. 代码审查流程
+
+### 1.1 审查前准备
+
+```
+1. 变更范围：PR 不超过 400 行（建议）
+2. 描述清晰：说明变更目的、影响范围
+3. 自测通过：提交前已验证功能
+4. 检查清单：作者先自查
+```
+
+### 1.2 审查中
+
+```
+1. 理解意图：先理解代码做什么
+2. 逐项检查：对照清单检查
+3. 具体反馈：指明问题位置和原因
+4. 建议优先：用建议代替命令
+```
+
+### 1.3 审查后
+
+```
+1. 讨论分歧：有不同意见时及时沟通
+2. 确认修复：确保所有问题都处理
+3. 记录学习：记录有价值的审查点
+```
+
+---
+
+## 2. 代码审查检查清单
+
+### 2.1 功能性检查
+
+- [ ] 功能实现正确，符合需求
+- [ ] 边界条件处理（空值、最大值等）
+- [ ] 错误处理完整
+- [ ] 没有明显的 bug
+
+### 2.2 代码质量检查
+
+- [ ] 命名清晰、有意义
+- [ ] 函数/类单一职责
+- [ ] 没有重复代码
+- [ ] 注释适量，不冗余
+- [ ] 遵循项目代码规范
+
+### 2.3 架构/设计检查
+
+- [ ] 模块划分合理
+- [ ] 依赖关系清晰
+- [ ] 没有引入不必要的依赖
+- [ ] 考虑可扩展性
+
+### 2.4 性能检查
+
+- [ ] 没有明显的性能问题
+- [ ] 避免不必要的计算
+- [ ] 合理使用缓存
+
+### 2.5 安全检查
+
+- [ ] 输入验证/ sanitization
+- [ ] 没有安全漏洞（SQL注入、XSS等）
+- [ ] 敏感数据处理得当
+
+### 2.6 测试检查
+
+- [ ] 有对应的单元测试
+- [ ] 测试覆盖核心场景
+- [ ] 测试清晰、可维护
+
+---
+
+## 3. 审查反馈的写法
+
+### 3.1 好的反馈 vs 坏的反馈
+
+```
+坏的反馈：
+  "这代码写得不好"
+  "你应该用另一种方法"
+
+好的反馈：
+  "这里可以考虑用 xxx 方法，原因是..."
+  "这个变量命名可以更清晰一点，建议叫 xxx"
+  "这部分逻辑有点复杂，能否加个注释？"
+```
+
+### 3.2 反馈分类
+
+- **必须修改**：功能问题、安全问题
+- **建议修改**：可改进点
+- **可选**：风格问题
+
+---
+
+## 4. 常见问题处理
+
+### 4.1 意见分歧
+
+```
+1. 理解对方观点
+2. 提供客观理由
+3. 必要时寻求第三方意见
+4. 以目标为导向，而非个人
+```
+
+### 4.2 大 PR 处理
+
+```
+建议拆分：
+  1. 按功能模块拆分
+  2. 按重构 vs 新功能拆分
+  3. 分阶段提交审查
+```
+
+---
+
+## 5. Flutter/前端/后端 专项检查
+
+### 5.1 Flutter 专项
+
+- [ ] Widget 拆分合理
+- [ ] 状态管理恰当
+- [ ] 性能优化考虑（const、key等）
+
+### 5.2 前端专项
+
+- [ ] 组件复用合理
+- [ ] 状态管理恰当
+- [ ] 响应式/适配考虑
+
+### 5.3 后端专项
+
+- [ ] API 设计合理
+- [ ] 数据库查询优化
+- [ ] 事务处理正确
+
+---
+
+## 6. 审查文化
+
+```
+- 对事不对人
+- 互相学习
+- 感谢审查者的时间
+- 快速响应反馈
+```
+
+## 与其他技能的衔接
+
+- **配合**：code-split-spec、test-driven-development
+- **参考**：sdd-code、quality-gate