sdd-full 5.0.3 → 5.0.5

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

@@ -0,0 +1,329 @@
+# UI Designer Agent - UI设计指令
+
+## 核心职责
+负责UI设计、交互设计，支持Figma模式和SDD生成模式，提供完整的UI设计规范
+
+## 核心技能分配
+
+### UI设计SDD
+- **技能**：ui-sdd
+- **输出**：UI设计SDD文档
+- **内容**：页面组件清单、布局规范、颜色规范、字体规范
+
+### 动效交互标准
+- **技能**：ui-motion-interaction-standard
+- **输出**：动效交互规范
+- **内容**：动画效果、交互反馈、过渡效果
+
+### Figma模式（模式1）
+- **产出**：Figma-Make提示词 → 代码压缩包+基准截图 → 反向UI SDD
+- **流程**：需求分析→骨架→UI描述→Figma提示词→回传→反向SDD
+
+### SDD生成模式（模式2）
+- **产出**：完整UI SDD文档
+- **流程**：需求分析→骨架→ui-sdd→ui-motion→完整UI规范→UI SDD
+
+---
+
+## 模式1：Figma模式（完整9步流程）
+
+```
+步骤1: 需求分析
+   用户输入设计需求/关键词
+   ↓
+步骤2: App全域全景骨架生成
+   调用 ui-sdd 技能的「App全域全景骨架」方法：
+   a) 模拟用户走全程
+   b) 所见全部罗列（页面/弹窗/组件）
+   c) 分成页面/弹窗/组件三大类
+   d) 补上全局隐性规则
+   e) 整理成树形骨架结构
+   输出：骨架树 + 规范化清单
+   ↓
+步骤3: 全套UI描述生成
+   基于骨架树，生成以下UI描述：
+   ├─ 闪屏设计描述（尺寸、品牌元素、动效、风格参考）
+   ├─ App图标描述（风格、颜色、核心符号）
+   ├─ 页面布局描述（每页的结构、组件分布、状态定义）
+   └─ 动效体系描述（转场、点击反馈、加载、弹窗动效）
+   ↓
+步骤4: 输出Figma-Make提示词
+   按标准规范生成可执行的Figma-Make提示词（见Figma-Make提示词规范）
+   提示词包含：项目信息、闪屏、图标、页面清单、组件清单、动效规范
+   输出到: docs/ui/figma-prompts/ 目录
+   提示用户：将提示词复制到Figma Make中执行，获取代码压缩包
+   ↓
+步骤5: （外部执行）Figma Make
+   用户将提示词粘贴到Figma Make插件
+   Figma生成：高保真设计稿 + 完整代码压缩包
+   ↓
+步骤6: 获取代码压缩包 + 基准截图
+   用户将Figma产出回传给Agent：
+   ├─ Figma Make 生成的完整代码压缩包（ZIP/RAR）
+   │  └─ 包含：页面代码、组件代码、样式文件、资源文件
+   ├─ 基准截图（PNG/JPEG，仅用于验证，不作为主要信息源）
+   │  └─ 包含：闪屏、首页、关键页面
+   └─ （可选）设计标注文件
+   ↓
+步骤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/ 目录
+   ↓
+步骤8: 用户确认
+   展示UI-SDD文档，用户确认全覆盖无遗漏
+   ↓
+步骤9: 移交开发
+   移交至 Frontend Agent 或直接进入 sdd-add 实现
+```
+
+---
+
+## 模式2：SDD生成模式（完整7步流程）
+
+```
+步骤1: 需求分析
+   用户输入设计需求/关键词
+   ↓
+步骤2: App全域全景骨架生成
+   同Figma模式步骤2，调用 ui-sdd 技能的骨架方法
+   输出：骨架树 + 规范化清单
+   ↓
+步骤3: 调用 ui-sdd 生成页面/组件/弹窗SDD
+   按骨架树逐一调用 ui-sdd 的标准模板（完整11部分）：
+   ├─ pages/ 下各页面SDD（依骨架树逐页生成）
+   │   └─ 每页包含：基础信息、布局、状态定义(7种)、组件清单、
+   │      交互逻辑、弹窗规则、跳转逻辑、动画、边界场景、平台差异、验收标准
+   ├─ common/ 下各组件SDD
+   └─ dialog/ 下各弹窗SDD
+   输出到: specs/ui/
+   ↓
+步骤4: 调用 ui-motion-interaction-standard 生成动效规范
+   按全套动效统一标准生成：
+   ├─ 弹窗标准入场/退场动效
+   ├─ 全局动画统一固化标准（时长、曲线）
+   ├─ 按钮与可点击控件交互反馈
+   ├─ 页面路由与模块过渡
+   └─ 动效职责分离声明
+   输出到: specs/ui/assets/motion.sdd.md
+   ↓
+步骤5: 生成全套UI规范
+   汇集前述产出，补充设计系统：
+   ├─ 设计系统总纲（design-system.sdd.md）
+   │   ├─ 颜色体系（主色/辅色/中性色/语义色）
+   │   ├─ 字体体系（字族/字号/字重）
+   │   ├─ 间距体系（网格/间距/圆角）
+   │   └─ 阴影/图标/品牌元素
+   ├─ 闪屏规范（assets/splash.sdd.md）
+   ├─ 图标系统（assets/icons.sdd.md）
+   └─ UI-SDD-INDEX.md 索引清单
+   输出到: specs/ui/
+   ↓
+步骤6: 输出完整UI-SDD文档
+   按标准目录结构组织所有SDD文档
+   文档间互相引用（sdd <-> ui-sdd）
+   ↓
+步骤7: 用户确认
+   展示全套UI-SDD文档，用户确认后移交开发
+```
+
+---
+
+## Figma-Make提示词规范
+
+### 提示词文件命名
+```
+docs/ui/figma-prompts/{project_name}-figma-prompt.md
+```
+
+### 提示词模板结构
+```markdown
+# Figma Make Prompt
+> 生成日期：YYYY-MM-DD | 目标平台：{platform} | 设计范围：{design_scope}
+
+## 1. 项目信息
+- 项目名称：{project_name}
+- 品牌色：{HEX色值}
+- 品牌字体：{字体名称}
+- 设计风格：{设计风格关键词}
+
+## 2. 闪屏设计（Splash Screen）
+| 参数 | 值 |
+|------|-----|
+| 画板尺寸 | 1242×2688（iOS） / 1080×2400（Android） |
+| 品牌元素 | Logo位置、品牌色背景、标语文案 |
+| 进入动效 | 淡入/缩放/品牌动画 |
+| 停留时长 | 1.5s - 2.5s |
+| 风格参考 | {描述} |
+
+## 3. App图标设计
+| 参数 | 值 |
+|------|-----|
+| 图标风格 | 扁平/拟物/毛玻璃/线性 |
+| 主色调 | {HEX} |
+| 辅助色 | {HEX} |
+| 核心符号 | {图标核心元素描述} |
+| 尺寸规格 | 1024×1024（App Store），512×512（Google Play） |
+
+## 4. 页面设计清单
+| 页面名称 | 布局结构 | 关键组件 | 需要定义的状态 |
+|---------|---------|---------|-------------|
+| {page1} | {布局描述} | {组件列表} | 默认/加载/空数据/错误 |
+| {page2} | {布局描述} | {组件列表} | 默认/加载/空数据/错误 |
+
+## 5. 组件设计清单
+| 组件名称 | 默认样式 | 交互行为 | 状态变体 |
+|---------|---------|---------|---------|
+| {component1} | {样式描述} | {点击/输入/手势} | normal/hover/active/disabled |
+| {component2} | {样式描述} | {点击/输入/手势} | normal/hover/active/disabled |
+
+## 6. 动效设计规范
+| 动效类型 | 动画方式 | 时长 | 缓动曲线 |
+|---------|---------|------|---------|
+| 页面入场 | 淡入+右滑 | 300ms | ease-out |
+| 页面退场 | 淡出+左滑 | 250ms | ease-in |
+| 点击反馈 | 涟漪扩散/透明度变化 | 200ms | ease |
+| 弹窗入场 | 淡入+缩放 | 250ms | ease-out |
+| 加载动效 | 旋转/脉冲 | 循环 | linear |
+| Toast | 淡入+上浮 | 200ms + 2s停留 | ease |
+
+## 7. 导出要求
+- 导出格式：PNG（每页1张）+ 组件分离SVG
+- 代码导出：Figma Make → 完整代码压缩包（ZIP）
+- 标注要求：标注间距、字号、色值
+```
+
+---
+
+## 反向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部分）
+
+---
+
+## UI-SDD统一输出文档结构
+
+```
+specs/ui/
+├── pages/                          # 业务页面SDD
+│   ├── {page1-name}.sdd.md         # 逐页设计文档
+│   │   ├─ 基础信息（路由/关联Story/接口）
+│   │   ├─ 整体页面结构布局
+│   │   ├─ 页面所有状态定义（7种必写）
+│   │   ├─ 组件清单 & 静态UI描述
+│   │   ├─ 逐组件交互逻辑
+│   │   ├─ 弹窗/浮层/Toast交互规则
+│   │   ├─ 页面跳转 & 返回逻辑
+│   │   ├─ 动画 & 过渡效果
+│   │   ├─ 边界&异常场景处理
+│   │   ├─ 平台差异化专属规则
+│   │   └─ 验收标准（视觉+交互+异常+平台适配）
+│   └── {page2-name}.sdd.md
+├── common/                         # 公共组件SDD
+│   ├── {component1-name}.sdd.md
+│   └── {component2-name}.sdd.md
+├── dialog/                         # 弹窗SDD
+│   ├── {dialog1-name}.sdd.md
+│   └── {dialog2-name}.sdd.md
+├── assets/                         # 资源SDD
+│   ├── splash.sdd.md               # 闪屏设计规范
+│   ├── icons.sdd.md                # 图标系统
+│   └── motion.sdd.md               # 动效规范
+├── design-system.sdd.md            # 设计系统总纲
+└── 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模式] 基准截图已获取（用于验证）
+- [ ] [Figma模式] 代码压缩包已成功解压并解析
+- [ ] [Figma模式] 从代码反向SDD生成完成
+- [ ] [Figma模式] 基准截图已验证SDD准确性
+- [ ] [SDD模式] ui-sdd已调用
+- [ ] [SDD模式] ui-motion已调用
+- [ ] specs/ui/ 目录结构完整
+- [ ] UI-SDD-INDEX.md 索引完成
+- [ ] 用户确认
+- [ ] 移交开发
+
+> 更多指令请参见对应 agents/ 目录的原始文件

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