sdd-full 4.2.0 → 4.3.1

package/skills/design-planning/ui-sdd/SKILL.md

@@ -0,0 +1,291 @@
+【claude code调用标识：ui-sdd】【trae调用标识：ui-sdd+UI交互SDD】【流程场景：1.完整3阶段SDD流程、2.从零开始新项目】
+
+# UI-SDD 完整整合版：App全域全景骨架 + 标准模板
+
+---
+
+## 第一部分：App全域全景骨架（项目启动第一步）
+
+### 核心定义
+**App全域全景骨架**：在写任何SDD、写任何代码前，先把整个App所有页面、弹窗、公共组件、全局隐性规则，梳理成一棵完整结构树。作用：定结构、定拆分、防遗漏。
+
+---
+
+### 具体5步流程（照着做！）
+
+#### 第1步：模拟用户完整走一遍App全流程
+从头到尾模拟真实用户操作，不思考设计、不写细节，只记录出现了哪些页面、哪些弹窗。
+
+**示例（地图导航App）**：
+```
+打开App → 启动页 → 首页（Tab）→ 搜索页 → 详情页 → 设置 → 退出
+            ↓
+         真实地图页
+            ↓
+         语音测试页
+```
+
+#### 第2步：逐一把看到的「页面、弹窗」全部罗列出来
+边走边记，看到什么写什么，不脑补、不省略。
+
+**示例（地图导航App）**：
+| 类型 | 名称 |
+|------|------|
+| 独立页面 | 启动页、首页、真实地图页、搜索页、语音测试页 |
+| 弹窗 | 确认弹窗、权限申请弹窗、语音识别中浮层 |
+| 反复出现组件 | 顶部导航栏、语音按钮、加载指示器、错误提示 |
+
+#### 第3步：分类归为三大类（固定分类）
+把罗列好的内容，强制分成3类：
+
+| 分类 | 说明 | 示例 |
+|------|------|------|
+| **业务页面（pages）** | 全屏独立页面，一页一个入口 | 启动页、首页、搜索页 |
+| **弹窗/浮层（dialog）** | 非全屏、弹出覆盖式 | 确认弹窗、权限弹窗 |
+| **全局公共组件（common）** | 多个页面复用的UI控件 | 导航栏、按钮、输入框 |
+
+#### 第4步：梳理「全局隐性规则」（最容易漏！）
+单独拉出一类，不属于页面也不属于组件，但是整个App都要遵守：
+
+| 规则分类 | 说明 | 示例 |
+|----------|------|------|
+| 全局配色/圆角/字体规范 | UI样式统一 | 主色调深海蓝、圆角统一8dp |
+| 平台适配 | iOS/Android差异 | iOS刘海安全区、Android物理返回 |
+| 页面路由/栈/返回逻辑 | 导航行为 | 返回保留页面栈、某些页面替换路由 |
+| 未登录拦截/登录态管理 | 用户状态 | 首次使用请求权限 |
+| 全局弱网/报错兜底 | 异常处理 | 网络不可用提示、加载失败重试 |
+| 全局键盘适配/防抖/权限流程 | 交互细节 | 键盘弹出布局调整、点击防抖 |
+
+#### 第5步：整理成「树形全景骨架结构」
+把上面三类，整理成树状层级：
+
+```
+App全域全景骨架
+├─ 启动流程页面
+│  ├─ 启动页（闪屏）
+│  └─ 隐私协议页（可选）
+├─ 主业务页面
+│  ├─ 首页
+│  ├─ 真实地图页
+│  ├─ 搜索页
+│  └─ 语音测试页
+├─ 全局弹窗/浮层
+│  ├─ 通用确认弹窗
+│  ├─ 权限申请弹窗
+│  └─ 语音识别浮层
+├─ 全局公共组件
+│  ├─ 顶部导航栏
+│  ├─ 语音按钮
+│  ├─ 加载指示器
+│  ├─ 错误提示
+│  └─ 确认弹窗
+└─ 全局隐性规则
+   ├─ 样式规范（颜色/字体/间距）
+   ├─ 平台适配（iOS/Android）
+   ├─ 路由逻辑（栈/返回）
+   ├─ 权限流程（定位/麦克风）
+   └─ 网络/键盘/防抖
+```
+
+---
+
+### 极简口诀（记住就会！）
+1. **模拟用户走全程**
+2. **所见全部罗列**
+3. **分成页面/弹窗/组件三类**
+4. **补上全局隐性规则**
+5. **整理成树形骨架**
+
+---
+
+### 画完骨架后马上能做什么？
+1. 直接按这个树，**建立SDD目录文件夹**
+2. 每个页面/弹窗/组件，对应新建SDD文档
+3. 对照骨架做「UI交互盘点清单」逐项打勾
+4. 保证后面所有SDD **100%全覆盖无遗漏**
+
+---
+
+## 第二部分：UI交互专用SDD标准模板
+
+### 何时使用
+- 需要为新页面、弹窗、复杂组件编写设计文档
+- 需要确保UI布局、交互、状态能1:1还原
+- 适用于Web、原生iOS、原生Android、Flutter项目
+- 需要替代原型设计，直接通过文档驱动开发
+
+---
+
+### 模板结构（完整11部分）
+
+#### 1. 基础信息
+| 字段 | 说明 |
+|------|------|
+| **归属平台** | Web / 原生iOS / 原生Android / Flutter |
+| **页面名称** | 页面的正式名称 |
+| **页面路由** | 路由地址（Web/Flutter）或页面标识 |
+| **关联用户故事** | 对应的用户故事ID或描述 |
+| **依赖接口/本地缓存** | 所需的数据接口或本地存储 |
+| **适配机型/系统版本** | 适配范围 |
+
+#### 2. 整体页面结构布局
+- 整体布局方式：固定布局 / 流式 / 弹性 / 卡片式
+- 页面整体分区（从上到下/从左到右）
+- 全局样式基准（统一约束）
+
+#### 3. 页面所有状态定义（必写！）
+必须逐条定义，不能只写正常状态：
+1. 默认初始态
+2. 加载中态（全局/局部）
+3. 空数据态
+4. 网络异常/接口报错态
+5. 表单禁用/按钮置灰态
+6. 操作成功反馈态
+7. 键盘弹出适配态（移动端必写）
+
+#### 4. 组件清单 & 静态UI描述
+逐个列出页面所有控件，每项写清楚：
+- 位置
+- 文案/占位符
+- 默认样式
+- 显隐条件
+
+#### 5. 逐组件交互逻辑（核心！）
+| 组件类型 | 需定义内容 |
+|----------|------------|
+| 输入类 | 输入规则、实时校验、清空按钮、键盘类型 |
+| 点击类 | 触发动作、防抖间隔、禁用条件、重复点击、点击反馈 |
+| 手势类 | 滑动、下拉刷新、长按、iOS右滑返回、Android物理返回 |
+
+#### 6. 弹窗、浮层、Toast交互规则
+- 触发条件
+- 弹出动画
+- 遮罩是否可点击关闭
+- 按钮确认/取消行为
+- 自动消失时长
+- 弹窗关闭后页面状态保留规则
+
+#### 7. 页面跳转 & 返回逻辑
+| 场景 | 路由 | 返回逻辑 | 保留页面栈 | 替换路由 |
+|------|------|----------|------------|----------|
+| 正向跳转 | | | | |
+| 返回上一页 | | | | |
+
+#### 8. 动画 & 过渡效果
+- 页面进入/退出过渡动画
+- 加载动画样式
+- 按钮点击动效
+- 列表加载骨架屏动效
+
+#### 9. 边界&异常场景处理
+1. 弱网/无网络时表现
+2. 接口报错文案展示
+3. 输入超限、特殊字符拦截
+4. 无权限访问处理
+5. 首次进入/非首次进入差异化
+
+#### 10. 平台差异化专属规则
+分别说明iOS、Android、Flutter、Web的差异。
+
+#### 11. 验收标准（UI视觉 + 交互行为逐条可测！）
+- 视觉验收
+- 状态验收
+- 交互验收
+- 异常验收
+- 平台适配验收
+
+---
+
+## 第三部分：完整工作流程
+
+### 项目从零启动（需求→UI→实现）
+```
+1. 用 sdd 技能：拆 Epic→Feature→Story，写验收标准，做估算
+2. 用 ui-sdd 的「App全域全景骨架」：梳理完整结构，建目录
+3. 用 ui-sdd 的「标准模板」：逐个页面写SDD
+4. 交付开发（或用 sdd-add 做快速实现）
+```
+
+### 正常迭代开发（日常新功能）
+```
+1. 用 sdd：把新功能拆成 Story，写验收标准
+2. 用 ui-sdd：回「全景骨架」补勾，补建/更新SDD
+3. 用 sdd-add：做快速实现，需求文档必须引用 sdd 的 Story 和 ui-sdd 的 SDD
+```
+
+### 临时需求/紧急修复
+```
+1. 直接用 sdd-add：快速澄清、优先级、实现
+2. 如果涉及UI/新增页面：必须同步回 ui-sdd 补勾、补建SDD
+3. 如果涉及Story拆分：必须同步回 sdd 补Story
+```
+
+---
+
+## 第四部分：文档关联引用规范
+
+### sdd Story 中引用 ui-sdd
+在 sdd 产出的 Story 文档中加入：
+```markdown
+## 关联文档
+- 对应UI交互SDD：spec/ui/pages/xxx-page.sdd.md
+- 复用组件SDD：spec/ui/common/ui-yyy.sdd.md
+- 相关弹窗SDD：spec/ui/dialog/zzz-dialog.sdd.md
+```
+
+### ui-sdd SDD 中引用 sdd Story
+在 ui-sdd 产出的页面/组件SDD中加入：
+```markdown
+## 关联用户故事
+- 主故事：US-001（在 docs/stories/user_stories.md）
+- 相关故事：US-002、US-003
+```
+
+### sdd-add 临时需求中引用前两者
+在 sdd-add 产出的临时需求文档中加入：
+```markdown
+## 关联文档
+- 关联Story：docs/stories/user_stories.md 中的 US-xxx
+- 关联UI-SDD：spec/ui/pages/yyy-page.sdd.md
+```
+
+---
+
+## 第五部分：一句话原则
+
+**「sdd 定方向（做什么），ui-sdd 定样子（怎么做），sdd-add 填细节（快速补）；从上往下拆，从下往上补，互相引用不遗漏」**
+
+---
+
+## 附录：快速检查表
+
+### 「App全域全景骨架」完成检查
+- [ ] 第1步：模拟用户走完全程
+- [ ] 第2步：所见全部罗列（页面/弹窗/组件）
+- [ ] 第3步：分成三大类（pages/dialog/common）
+- [ ] 第4步：补上全局隐性规则
+- [ ] 第5步：整理成树形结构
+
+### 单个UI-SDD文档完成检查
+- [ ] 基础信息完整
+- [ ] 页面结构清晰
+- [ ] 所有状态定义（至少7种）
+- [ ] 组件清单及静态UI
+- [ ] 交互逻辑详细（包括防抖、点击反馈）
+- [ ] 平台适配规则
+- [ ] 验收标准明确（逐条可测）
+
+---
+
+## 最佳实践总结
+
+1. **骨架先行**：先画App全域全景骨架，再写单个SDD
+2. **状态优先**：定义所有状态，再写组件和交互
+3. **交互细化**：每个交互都要考虑边缘情况（防抖、反馈等）
+4. **平台适配**：明确列出各平台的差异
+5. **验收标准**：每条标准都要可测试
+6. **互相引用**：sdd、ui-sdd、sdd-add 三者文档互相关联
+
+---
+
+*文档版本：v1.0 | 最后更新：2026-05-04*

package/skills/design-planning/ui-sdd-specialized/SKILL.md

@@ -1,50 +1,56 @@
-# ui-sdd-specialized - UI专用SDD模板
+name: UI-SDD专用模板
+description: UI设计稿结构化SDD固定格式、字段、交付标准
+author: 
+version: 1.0.0
+trigger:
+  - UI-SDD专用模板
+  - UI设计稿模板
+  - UI交付标准
+tags:
+  - UI设计
+  - SDD模板
+  - 设计规范
+  - 交付标准
 
-## 功能说明
+【claude code调用标识：UI-SDD专用模板】【trae调用标识：UI-SDD专用模板+UI设计规范】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代】
 
-UI设计稿对应结构化SDD固定格式、字段、交付标准的专用模板。
+## 功能描述
 
-## 触发词
+本技能提供UI设计稿结构化SDD模板，包含固定格式、必填字段和交付标准，帮助团队规范UI设计流程。
 
-`UI-SDD`、`UI设计`、`界面设计`、`设计转代码`
+## 调用方式
 
-## 参数说明
-
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| page_name | string | 是 | 页面名称 |
-| design_source | string | 否 | 设计稿来源（Figma/Sketch/其他） |
-| platform | string | 否 | 目标平台：web/mobile/desktop |
-
-## 输出结构
-
-### 1. 页面概览
-- 页面定位
-- 功能概述
-- 用户场景
-
-### 2. 布局结构
-- 页面框架
-- 组件分布
-- 响应式适配
-
-### 3. 组件规格
-- 组件清单
-- 样式规范
-- 交互说明
-
-### 4. 交付标准
-- 设计稿规范
-- 切图标注
-- 动效要求
-
-## 使用示例
+### Claude Code调用
+```
+调用 UI-SDD专用模板 页面名称=首页 设计稿版本=v1.0
+```
 
+### Trae调用
 ```
-trae调用 UI-SDD专用模板 页面名称=首页
-trae调用 UI-SDD专用模板 页面名称=商品详情页 平台=mobile
+trae调用 UI-SDD专用模板 页面名称=首页 设计稿版本=v1.0 流程场景=完整3阶段SDD流程
 ```
 
-## 版本
+## 参数说明
 
-v4.1.0
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| 页面名称 | string | 是 | UI页面或组件名称 |
+| 设计稿版本 | string | 否 | 设计稿版本号 |
+| 设计师 | string | 否 | 设计师姓名 |
+| 设计日期 | string | 否 | 设计日期 |
+
+## 输出内容
+
+1. 设计稿信息（Figma链接、备份文件、版本）
+2. 页面结构（层级、组件清单、布局规范）
+3. 交互设计（页面跳转、状态切换、动效说明）
+4. 视觉规范（颜色、字体、间距）
+5. 交付标准（完整性检查、切图规范）
+6. 验收标准（视觉还原度、交互正确性）
+
+## 适用场景
+
+- UI设计阶段
+- 设计稿评审
+- 设计规范制定
+- 前端开发参考

package/skills/design-planning/writing-plans/SKILL.md

@@ -0,0 +1,144 @@
+【claude code调用标识：writing-plans】【trae调用标识：writing-plans+编写实现计划】【流程场景：1.完整3阶段SDD流程、2.从零开始新项目、3.小型功能迭代】
+
+---
+name: writing-plans
+description: 当你有规范或多步骤任务的需求时，在接触代码前使用
+---
+
+# 编写计划
+
+## 概述
+
+编写全面的实现计划，假设工程师对我们的代码库没有任何上下文，并且品味可疑。记录他们需要知道的一切：每个任务需要修改哪些文件、代码、测试、他们可能需要检查的文档、如何测试。将整个计划分解为 bite-sized 任务。DRY（不要重复自己）、YAGNI（你不会需要它）、TDD（测试驱动开发）、频繁提交。
+
+假设他们是熟练的开发人员，但对我们的工具集或问题域几乎一无所知。假设他们不太了解良好的测试设计。
+
+**开始时宣布：** "我正在使用 writing-plans 技能创建实现计划。"
+
+**上下文：** 这应该在专用的工作树中运行（由 brainstorming 技能创建）。
+
+**保存计划到：** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+- （用户对计划位置的偏好覆盖此默认值）
+
+## 范围检查
+
+如果规范涵盖多个独立子系统，在头脑风暴期间应该已经分解为子项目规范。如果没有，建议将其分解为单独的计划 - 每个子系统一个。每个计划都应该独立产生可工作、可测试的软件。
+
+## 文件结构
+
+在定义任务之前，映射出将创建或修改哪些文件以及每个文件的职责。这是分解决策被锁定的地方。
+
+- 设计具有明确边界和定义良好接口的单元。每个文件应该有一个明确的职责。
+- 你对能一次保持在上下文中的代码推理得最好，当文件集中时，你的编辑更可靠。优先选择较小、集中的文件，而不是做太多事情的大文件。
+- 一起更改的文件应该放在一起。按职责划分，而不是按技术层划分。
+- 在现有代码库中，遵循已建立的模式。如果代码库使用大文件，不要单方面重构 - 但如果你正在修改的文件变得难以管理，在计划中包含拆分是合理的。
+
+这种结构为任务分解提供信息。每个任务应该产生独立有意义的自包含更改。
+
+## Bite-Sized 任务粒度
+
+**每个步骤是一个动作（2-5分钟）：**
+- "编写失败的测试" - 步骤
+- "运行它以确保它失败" - 步骤
+- "实现最小代码以使测试通过" - 步骤
+- "运行测试并确保它们通过" - 步骤
+- "提交" - 步骤
+
+## 计划文档标题
+
+**每个计划必须以以下标题开始：**
+
+```markdown
+# [功能名称] 实现计划
+
+> **对于代理工作者：** 必需：使用 superpowers:subagent-driven-development（如果子代理可用）或 superpowers:executing-plans 来实现此计划。步骤使用复选框（`- [ ]`）语法进行跟踪。
+
+**目标：** [一句话描述此构建内容]
+
+**架构：** [关于方法的2-3句话]
+
+**技术栈：** [关键技术/库]
+
+---
+```
+
+## 任务结构
+
+````markdown
+### 任务 N：[组件名称]
+
+**文件：**
+- 创建：`exact/path/to/file.py`
+- 修改：`exact/path/to/existing.py:123-145`
+- 测试：`tests/exact/path/to/test.py`
+
+- [ ] **步骤 1：编写失败的测试**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **步骤 2：运行测试以验证它失败**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：失败，提示 "function not defined"
+
+- [ ] **步骤 3：编写最小实现**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **步骤 4：运行测试以验证它通过**
+
+运行：`pytest tests/path/test.py::test_name -v`
+预期：通过
+
+- [ ] **步骤 5：提交**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## 记住
+- 始终使用精确的文件路径
+- 计划中包含完整的代码（不是 "添加验证"）
+- 带有预期输出的精确命令
+- 使用 @ 语法引用相关技能
+- DRY、YAGNI、TDD、频繁提交
+
+## 计划审查循环
+
+编写完整计划后：
+
+1. 调度单个 plan-document-reviewer 子代理（参见 plan-document-reviewer-prompt.md），使用精心设计的审查上下文 - 绝不是你的会话历史。这使审查者专注于计划，而不是你的思考过程。
+   - 提供：计划文档路径，规范文档路径
+2. 如果 ❌ 发现问题：修复问题，重新调度审查者审查整个计划
+3. 如果 ✅ 批准：继续执行交接
+
+**审查循环指导：**
+- 编写计划的同一代理修复它（保留上下文）
+- 如果循环超过3次迭代，提交给人类指导
+- 审查者是顾问 - 如果你认为反馈不正确，解释分歧
+
+## 执行交接
+
+保存计划后：
+
+**"计划完成并保存到 `docs/superpowers/plans/<filename>.md`。准备执行？"**
+
+**执行路径取决于 harness 能力：**
+
+**如果 harness 有子代理（Claude Code 等）：**
+- **必需：** 使用 superpowers:subagent-driven-development
+- 不要提供选择 - 子代理驱动是标准方法
+- 每个任务使用新的子代理 + 两阶段审查
+
+**如果 harness 没有子代理：**
+- 在当前会话中使用 superpowers:executing-plans 执行计划
+- 批处理执行，带有审查检查点

package/skills/development-execution/flutter-errors/SKILL.md

@@ -1,44 +1,54 @@
-# flutter-errors - Flutter常见异常专项
-
-## 功能说明
-
-SocketException、Framebuffer渲染异常排查与修复标准化流程。
-
-## 触发词
+name: Flutter常见异常专项SDD
+description: SocketException、Framebuffer渲染异常排查与修复标准化流程
+author: 
+version: 1.0.0
+trigger:
+  - Flutter异常处理
+  - SocketException
+  - Framebuffer异常
+  - Bug排查
+tags:
+  - Flutter
+  - 异常处理
+  - Bug修复
+  - 调试
+
+【claude code调用标识：Flutter常见异常专项SDD】【trae调用标识：Flutter常见异常专项SDD+异常处理】【流程场景：4.Bug处理】
+
+## 功能描述
+
+本技能提供Flutter常见异常专项SDD模板，包含SocketException、Framebuffer渲染异常等常见问题的排查与修复标准化流程。
+
+## 调用方式
+
+### Claude Code调用
+```
+调用 Flutter常见异常专项SDD 项目名称=个人备忘录APP
+```
 
-`Flutter异常`、`异常处理`、`SocketException`、`渲染错误`
+### Trae调用
+```
+trae调用 Flutter常见异常专项SDD 项目名称=个人备忘录APP 异常类型=SocketException 流程场景=Bug处理
+```
 
 ## 参数说明
 
 | 参数名 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
-| error_type | string | 是 | 异常类型 |
-| scenario | string | 否 | 发生场景 |
+| 项目名称 | string | 是 | 项目名称 |
+| 异常类型 | string | 否 | SocketException/Framebuffer/其他 |
 
-## 异常类型
+## 输出内容
 
-### 1. SocketException
-- 网络连接失败
-- 超时处理
-- 重试机制
-
-### 2. Framebuffer渲染异常
-- UI卡顿
-- 内存泄漏
-- 渲染优化
-
-### 3. 其他常见异常
-- 空指针异常
-- 类型转换错误
-- 状态管理问题
-
-## 使用示例
-
-```
-trae调用 Flutter常见异常专项SDD 异常类型=SocketException
-trae调用 Flutter常见异常专项SDD 异常类型=Framebuffer渲染异常 场景=列表滚动
-```
+1. SocketException异常（描述、排查流程、修复方案、预防措施）
+2. Framebuffer渲染异常（描述、排查流程、修复方案、预防措施）
+3. 其他常见异常（空指针、类型转换、内存泄漏）
+4. 异常处理框架（全局异常捕获、Zone捕获、Error Widget）
+5. 验收标准（异常处理验证、稳定性测试）
 
-## 版本
+## 适用场景
 
-v4.1.0
+- Bug排查
+- 异常处理
+- 稳定性保障
+- 代码调试