sdd-full 4.6.2 → 4.8.1

package/bin.js

@@ -6,7 +6,7 @@ const fs = require('fs');
 const path = require('path');
 
 const SDD = {
-  version: '4.6.2',
+  version: '4.8.1',
   name: 'sdd-full',
   description: '完整的软件设计开发技能包'
 };

package/index.js

@@ -17,22 +17,28 @@ const SDD = {
     const skillsDir = path.join(__dirname, 'skills');
     const skills = [];
     
-    if (fs.existsSync(skillsDir)) {
-      const items = fs.readdirSync(skillsDir);
-      
-      items.forEach(item => {
-        const itemPath = path.join(skillsDir, item);
-        const stat = fs.statSync(itemPath);
+    function searchSkills(dir, parentPath = '') {
+      if (fs.existsSync(dir)) {
+        const items = fs.readdirSync(dir);
         
-        if (stat.isDirectory() && !item.endsWith('.md')) {
-          const skillPath = path.join(itemPath, 'SKILL.md');
-          if (fs.existsSync(skillPath)) {
-            skills.push(item);
+        items.forEach(item => {
+          const itemPath = path.join(dir, item);
+          const stat = fs.statSync(itemPath);
+          
+          if (stat.isDirectory() && !item.startsWith('.')) {
+            const skillPath = path.join(itemPath, 'SKILL.md');
+            const skillRelativePath = parentPath ? path.join(parentPath, item) : item;
+            if (fs.existsSync(skillPath)) {
+              skills.push(skillRelativePath);
+            }
+            // 继续递归搜索子目录
+            searchSkills(itemPath, skillRelativePath);
           }
-        }
-      });
+        });
+      }
     }
     
+    searchSkills(skillsDir);
     return skills;
   },
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-full",
-  "version": "4.6.2",
+  "version": "4.8.1",
   "description": "SDD Full - 完整的软件设计开发技能包",
   "main": "index.js",
   "bin": "./bin.js",

package/skills/VERSION.md

@@ -1,8 +1,8 @@
 # SDD Full 技能包版本
 
-**版本**: 4.6.2  
-**发布日期**: 2026-05-06  
-**更新时间**: 2026-05-06 21:05:00  
+**版本**: 4.8.1  
+**发布日期**: 2026-05-08  
+**更新时间**: 2026-05-08 22:36:00  
 
 ---
 

package/skills/design-planning/global-overlay-stack-standard/SKILL.md

@@ -0,0 +1,83 @@
+name: global-overlay-stack-standard
+description: 全局浮层栈与层级规范 - 跨技术栈通用浮层管理规则
+author:
+version: 1.0.0
+trigger:
+  - 浮层栈
+  - 浮层规范
+  - 弹窗管理
+  - 层级管理
+tags:
+  - 浮层管理
+  - 工程规范
+  - UI规范
+  - 跨端通用
+
+【claude code调用标识：global-overlay-stack-standard】【trae调用标识：global-overlay-stack-standard+浮层管理】【流程场景：1.完整3阶段SDD流程、2.从零开始新项目、3.小型功能迭代】
+
+## 功能说明
+
+跨技术栈通用浮层栈与层级规范，不绑定 Flutter / iOS / Android / H5 / 小程序。只管控浮层栈、层级、弹出流程、防重叠、关闭逻辑、交互规则，不涉及UI动画、不限制具体实现语法。
+
+## 核心定位
+
+跨技术栈通用，不绑定任何平台/框架；只管控浮层栈、层级、弹出流程、防重叠、关闭逻辑、交互规则，不涉及UI动画、不限制具体实现语法。
+
+## 强制规范规则
+
+### 1. 浮层栈统一管理
+所有浮层类型：全局悬浮窗、强拦截弹窗、普通对话框、底部弹层、居中弹窗、Toast 弱提示，全部强制纳入全局统一栈管理，禁止业务私自独立创建、私自挂载根节点。
+
+### 2. 全局固定层级优先级
+全局固定层级优先级（永久不可随意篡改）：
+全局悬浮窗 ＞ 强拦截权限弹窗 ＞ 普通业务对话框 ＞ 底部弹层 ＞ Toast 轻量提示
+
+### 3. 栈机制严格遵循
+浮层严格遵循后进先出栈机制，任何操作只允许作用于当前栈顶浮层，禁止跨层操作、跨层关闭。
+
+### 4. 防重叠强制流程
+- 同优先级浮层禁止并行同时弹出，必须串行排队，上一个关闭后才允许弹出下一个；
+- 新浮层弹出前必须校验栈顶同等级浮层，存在则拦截重复弹出或进入等待队列；
+- 限制全局最大浮层嵌套层数，超出层数直接拦截创建，杜绝无限堆叠重叠；
+- 页面路由跳转、退出登录、流程终止时，自动清空当前页面附属所有浮层，避免残留遮挡。
+
+### 5. 遮罩行为统一规范
+- 全局默认固定遮罩可关闭/不可关闭基线规则；
+- 业务页面不准单独改写遮罩点击逻辑、不准私自穿透遮罩事件。
+
+### 6. 系统返回逻辑统一
+- 优先关闭栈顶浮层；
+- 无任何浮层时，才允许执行原生页面回退。
+
+### 7. 标准调用能力
+全局仅开放三个标准调用能力：展示浮层、关闭栈顶、关闭全部；
+业务禁止私自销毁浮层、私自移除遮罩、私自修改层级权重。
+
+### 8. 需求变更流程
+所有浮层相关需求变更、流程改动，必须先更新 SDD 对应规则，再进行开发；
+代码实现必须对齐本规范与 SDD 定义，不得私自偏离。
+
+## 使用指南
+
+### 调用方式
+- **Claude Code**: 调用 global-overlay-stack-standard
+- **Trae**: trae调用 global-overlay-stack-standard
+
+### 适用场景
+- 新项目浮层架构设计
+- 现有项目浮层问题治理
+- 跨端统一浮层规范制定
+- 浮层重叠、层级混乱问题修复
+
+## AI协作规范
+
+| 阶段 | AI职责 | 人工校验要求 |
+|------|--------|-------------|
+| 浮层需求分析 | 梳理浮层类型、优先级、交互规则 | 确认浮层分类合理性 |
+| 规范落地 | 协助生成浮层管理代码框架 | 必须人工二次确认层级优先级 |
+| Bug修复 | 分析浮层重叠、层级混乱原因 | 验证修复方案符合规范 |
+
+---
+
+**规范版本**: v1.0.0  
+**适用场景**: 跨技术栈通用浮层管理

package/skills/design-planning/ui-motion-interaction-standard/SKILL.md

@@ -0,0 +1,79 @@
+name: ui-motion-interaction-standard
+description: 全局UI动效与交互反馈规范 - 跨端通用交互动效管理
+author:
+version: 1.0.0
+trigger:
+  - 动效规范
+  - 交互动效
+  - 动画规范
+  - 交互反馈
+tags:
+  - UI动效
+  - 交互动画
+  - 工程规范
+  - 跨端通用
+
+【claude code调用标识：ui-motion-interaction-standard】【trae调用标识：ui-motion-interaction-standard+UI动效】【流程场景：1.完整3阶段SDD流程、2.从零开始新项目、3.小型功能迭代】
+
+## 功能说明
+
+跨端通用UI动效与交互反馈规范，管控所有交互动效、弹窗动画、点击反馈、过渡动效。和浮层栈逻辑解耦，单独归一管理，不侵入层级与栈流程。
+
+## 核心定位
+
+跨端通用，管控所有交互动效、弹窗动画、点击反馈、过渡动效。和浮层栈逻辑解耦，单独归一管理，不侵入层级与栈流程。
+
+## 强制规范规则
+
+### 1. 弹窗标准入场/退场动效统一约束
+
+- 居中弹窗：默认淡入淡出 + 轻微缩放；
+- 底部弹层：默认从底部滑入滑出；
+- 强拦截弹窗：淡入遮罩+居中缓慢浮现；
+- Toast：淡入淡出+轻微上浮位移。
+
+### 2. 全局动画统一固化标准
+
+固定动画时长、插值曲线、渐变节奏，业务不得随意改快慢、乱加非主流动效曲线，保持全站体验一致。
+
+### 3. 按钮与可点击控件交互反馈
+
+- 全局统一点击涟漪效果、按压缩放、透明度反馈；
+- 禁止各页面各自写一套点击动效，风格碎片化。
+
+### 4. 页面路由与模块过渡
+
+页面路由转场、模块显隐过渡，遵循全局统一动效规范，禁止私自写突兀无过渡、非主流转场方式。
+
+### 5. 动效职责分离
+
+动效只负责视觉表现，不参与浮层层级、栈顺序、关闭逻辑；不准通过动画层级、动画延时来 hack 规避浮层重叠规则。
+
+### 6. 动效变更流程
+
+所有新增动效类型、修改现有动效风格，必须先在 SDD 定义规范，再落地实现，保持全站动效统一口径。
+
+## 使用指南
+
+### 调用方式
+- **Claude Code**: 调用 ui-motion-interaction-standard
+- **Trae**: trae调用 ui-motion-interaction-standard
+
+### 适用场景
+- 新项目动效体系设计
+- 现有项目动效统一规范
+- 跨端动效体验一致性治理
+- 交互动效风格碎片化问题修复
+
+## AI协作规范
+
+| 阶段 | AI职责 | 人工校验要求 |
+|------|--------|-------------|
+| 动效需求分析 | 梳理动效类型、时长、曲线标准 | 确认动效风格一致性 |
+| 规范落地 | 协助生成动效实现代码框架 | 必须人工二次确认动效参数 |
+| 体验优化 | 分析动效流畅度、交互反馈合理性 | 验证体验符合规范 |
+
+---
+
+**规范版本**: v1.0.0  
+**适用场景**: 跨端通用UI动效与交互反馈

package/skills/flutter/skills/flutter-add-integration-test/SKILL.md

@@ -0,0 +1,165 @@
+【claude code调用标识：flutter-add-integration-test】【trae调用标识：flutter-add-integration-test+Flutter开发】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代】
+
+---
+name: flutter-add-integration-test
+description: Configures Flutter Driver for app interaction and converts MCP actions into permanent integration tests. Use when adding integration testing to a project, exploring UI components via MCP, or automating user flows with the integration_test package.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Tue, 21 Apr 2026 18:29:20 GMT
+---
+# Implementing Flutter Integration Tests
+
+## Contents
+- [Project Setup and Dependencies](#project-setup-and-dependencies)
+- [Interactive Exploration via MCP](#interactive-exploration-via-mcp)
+- [Test Authoring Guidelines](#test-authoring-guidelines)
+- [Execution and Profiling](#execution-and-profiling)
+- [Workflow: End-to-End Integration Testing](#workflow-end-to-end-integration-testing)
+- [Examples](#examples)
+
+## Project Setup and Dependencies
+
+Configure the project to support integration testing and Flutter Driver extensions.
+
+1. Add required development dependencies to `pubspec.yaml`:
+   ```bash
+   flutter pub add 'dev:integration_test:{"sdk":"flutter"}'
+   flutter pub add 'dev:flutter_test:{"sdk":"flutter"}'
+   ```
+2. Enable the Flutter Driver extension in your application entry point (typically `lib/main.dart` or a dedicated `lib/main_test.dart`):
+   - Import `package:flutter_driver/driver_extension.dart`.
+   - Call `enableFlutterDriverExtension();` before `runApp()`.
+3. Add `Key` parameters (e.g., `ValueKey('login_button')`) to critical widgets in the application code to ensure reliable targeting during tests.
+
+## Interactive Exploration via MCP
+
+Use the Dart/Flutter MCP server tools to interactively explore and manipulate the application state before writing static tests.
+
+- **Launch**: Execute `launch_app` with `target: "lib/main_test.dart"` to start the application and acquire the DTD URI.
+- **Inspect**: Execute `get_widget_tree` to discover available `Key`s, `Text` nodes, and widget `Type`s.
+- **Interact**: Execute `tap`, `enter_text`, and `scroll` to simulate user flows.
+- **Wait**: Always execute `waitFor` or verify state with `get_health` when navigating or triggering animations.
+- **Troubleshoot Unmounted Widgets**: If a widget is not found in the tree, it may be lazily loaded in a `SliverList` or `ListView`. Execute `scroll` or `scrollIntoView` to force the widget to mount before interacting with it.
+
+## Test Authoring Guidelines
+
+Structure integration tests using the `flutter_test` API paradigm. 
+
+- Create a dedicated `integration_test/` directory at the project root.
+- Name all test files using the `<name>_test.dart` convention.
+- Initialize the binding by calling `IntegrationTestWidgetsFlutterBinding.ensureInitialized();` at the start of `main()`.
+- Load the application UI using `await tester.pumpWidget(MyApp());`.
+- Trigger frames and wait for animations to complete using `await tester.pumpAndSettle();` after interactions like `tester.tap()`.
+- Assert widget visibility using `expect(find.byKey(ValueKey('foo')), findsOneWidget);` or `findsNothing`.
+- Scroll to specific off-screen widgets using `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder);`.
+
+**Conditional Logic for Legacy `flutter_driver`:**
+- If maintaining or migrating legacy `flutter_driver` tests, use `driver.waitFor()`, `driver.waitForAbsent()`, `driver.tap()`, and `driver.scroll()` instead of the `WidgetTester` APIs.
+
+## Execution and Profiling
+
+Execute tests using the `flutter drive` command. Require a host driver script located in `test_driver/integration_test.dart` that calls `integrationDriver()`.
+
+**Conditional Execution Targets:**
+- **If testing on Chrome:** Launch `chromedriver --port=4444` in a separate terminal, then run:
+  `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart -d chrome`
+- **If testing headless web:** Run with `-d web-server`.
+- **If testing on Android (Local):** Run `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`.
+- **If testing on Firebase Test Lab (Android):** 
+  1. Build debug APK: `flutter build apk --debug`
+  2. Build test APK: `./gradlew app:assembleAndroidTest`
+  3. Upload both APKs to the Firebase Test Lab console.
+
+## Workflow: End-to-End Integration Testing
+
+Copy and follow this checklist to implement and verify integration tests.
+
+- [ ] **Task Progress: Setup**
+  - [ ] Add `integration_test` and `flutter_test` to `pubspec.yaml`.
+  - [ ] Inject `enableFlutterDriverExtension()` into the app entry point.
+  - [ ] Assign `ValueKey`s to target widgets.
+- [ ] **Task Progress: Exploration**
+  - [ ] Run `launch_app` via MCP.
+  - [ ] Map the widget tree using `get_widget_tree`.
+  - [ ] Validate interaction paths using MCP tools (`tap`, `enter_text`).
+- [ ] **Task Progress: Authoring**
+  - [ ] Create `integration_test/app_test.dart`.
+  - [ ] Write test cases using `WidgetTester` APIs.
+  - [ ] Create `test_driver/integration_test.dart` with `integrationDriver()`.
+- [ ] **Task Progress: Execution & Feedback Loop**
+  - [ ] Run `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`.
+  - [ ] **Feedback Loop**: Review test output -> If `PumpAndSettleTimedOutException` occurs, check for infinite animations -> If widget not found, add `scrollUntilVisible` -> Re-run test until passing.
+
+## Examples
+
+### Standard Integration Test (`integration_test/app_test.dart`)
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:integration_test/integration_test.dart';
+import 'package:my_app/main.dart';
+
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  group('End-to-end test', () {
+    testWidgets('tap on the floating action button, verify counter', (tester) async {
+      // Load app widget.
+      await tester.pumpWidget(const MyApp());
+
+      // Verify the counter starts at 0.
+      expect(find.text('0'), findsOneWidget);
+
+      // Find the floating action button to tap on.
+      final fab = find.byKey(const ValueKey('increment'));
+
+      // Emulate a tap on the floating action button.
+      await tester.tap(fab);
+
+      // Trigger a frame and wait for animations.
+      await tester.pumpAndSettle();
+
+      // Verify the counter increments by 1.
+      expect(find.text('1'), findsOneWidget);
+    });
+  });
+}
+```
+
+### Host Driver Script (`test_driver/integration_test.dart`)
+
+```dart
+import 'package:integration_test/integration_test_driver.dart';
+
+Future<void> main() => integrationDriver();
+```
+
+### Performance Profiling Driver Script (`test_driver/perf_driver.dart`)
+
+Use this driver script if you wrap your test actions in `binding.traceAction()` to capture performance metrics.
+
+```dart
+import 'package:flutter_driver/flutter_driver.dart' as driver;
+import 'package:integration_test/integration_test_driver.dart';
+
+Future<void> main() {
+  return integrationDriver(
+    responseDataCallback: (data) async {
+      if (data != null) {
+        final timeline = driver.Timeline.fromJson(
+          data['scrolling_timeline'] as Map<String, dynamic>,
+        );
+
+        final summary = driver.TimelineSummary.summarize(timeline);
+
+        await summary.writeTimelineToFile(
+          'scrolling_timeline',
+          pretty: true,
+          includeSummary: true,
+        );
+      }
+    },
+  );
+}
+```

package/skills/flutter/skills/flutter-add-widget-preview/SKILL.md

@@ -0,0 +1,147 @@
+【claude code调用标识：flutter-add-widget-preview】【trae调用标识：flutter-add-widget-preview+Flutter开发】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代】
+
+---
+name: flutter-add-widget-preview
+description: Adds interactive widget previews to the project using the previews.dart system. Use when creating new UI components or updating existing screens to ensure consistent design and interactive testing.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Tue, 21 Apr 2026 20:05:23 GMT
+---
+# Previewing Flutter Widgets
+
+## Contents
+- [Preview Guidelines](#preview-guidelines)
+- [Handling Limitations](#handling-limitations)
+- [Workflows](#workflows)
+- [Examples](#examples)
+
+## Preview Guidelines
+
+Use the Flutter Widget Previewer to render widgets in real-time, isolated from the full application context. 
+
+- **Target Elements:** Apply the `@Preview` annotation to top-level functions, static methods within a class, or public widget constructors/factories that have no required arguments and return a `Widget` or `WidgetBuilder`.
+- **Imports:** Always import `package:flutter/widget_previews.dart` to access the preview annotations.
+- **Custom Annotations:** Extend the `Preview` class to create custom annotations that inject common properties (e.g., themes, wrappers) across multiple widgets.
+- **Multiple Configurations:** Apply multiple `@Preview` annotations to a single target to generate multiple preview instances. Alternatively, extend `MultiPreview` to encapsulate common multi-preview configurations.
+- **Runtime Transformations:** Override the `transform()` method in custom `Preview` or `MultiPreview` classes to modify preview configurations dynamically at runtime (e.g., generating names based on dynamic values, which is impossible in a `const` context).
+
+## Handling Limitations
+
+Adhere to the following constraints when authoring previewable widgets, as the Widget Previewer runs in a web environment:
+
+- **No Native APIs:** Do not use native plugins or APIs from `dart:io` or `dart:ffi`. Widgets with transitive dependencies on `dart:io` or `dart:ffi` will throw exceptions upon invocation. Use conditional imports to mock or bypass these in preview mode.
+- **Asset Paths:** Use package-based paths for assets loaded via `dart:ui` `fromAsset` APIs (e.g., `packages/my_package_name/assets/my_image.png` instead of `assets/my_image.png`).
+- **Public Callbacks:** Ensure all callback arguments provided to preview annotations are public and constant to satisfy code generation requirements.
+- **Constraints:** Apply explicit constraints using the `size` parameter in the `@Preview` annotation if your widget is unconstrained, as the previewer defaults to constraining them to approximately half the viewport.
+
+## Workflows
+
+### Creating a Widget Preview
+Copy and track this checklist when implementing a new widget preview:
+
+- [ ] Import `package:flutter/widget_previews.dart`.
+- [ ] Identify a valid target (top-level function, static method, or parameter-less public constructor).
+- [ ] Apply the `@Preview` annotation to the target.
+- [ ] Configure preview parameters (`name`, `group`, `size`, `theme`, `brightness`, etc.) as needed.
+- [ ] If applying the same configuration to multiple widgets, extract the configuration into a custom class extending `Preview`.
+
+### Interacting with Previews
+Follow the appropriate conditional workflow to launch and interact with the Widget Previewer:
+
+**If using a supported IDE (Android Studio, IntelliJ, VS Code with Flutter 3.38+):**
+1. Launch the IDE. The Widget Previewer starts automatically.
+2. Open the "Flutter Widget Preview" tab in the sidebar.
+3. Toggle "Filter previews by selected file" at the bottom left if you want to view previews outside the currently active file.
+
+**If using the Command Line:**
+1. Navigate to the Flutter project's root directory.
+2. Run `flutter widget-preview start`.
+3. View the automatically opened Chrome environment.
+
+**Feedback Loop: Preview Iteration**
+1. Modify the widget code or preview configuration.
+2. Observe the automatic update in the Widget Previewer.
+3. If global state (e.g., static initializers) was modified: Click the global hot restart button at the bottom right.
+4. If only the local widget state needs resetting: Click the individual hot restart button on the specific preview card.
+5. Review errors in the IDE/CLI console -> fix -> repeat.
+
+## Examples
+
+### Basic Preview
+```dart
+import 'package:flutter/widget_previews.dart';
+import 'package:flutter/material.dart';
+
+@Preview(name: 'My Sample Text', group: 'Typography')
+Widget mySampleText() {
+  return const Text('Hello, World!');
+}
+```
+
+### Custom Preview with Runtime Transformation
+```dart
+import 'package:flutter/widget_previews.dart';
+import 'package:flutter/material.dart';
+
+final class TransformativePreview extends Preview {
+  const TransformativePreview({
+    super.name,
+    super.group,
+  });
+
+  PreviewThemeData _themeBuilder() {
+    return PreviewThemeData(
+      materialLight: ThemeData.light(),
+      materialDark: ThemeData.dark(),
+    );
+  }
+
+  @override
+  Preview transform() {
+    final originalPreview = super.transform();
+    final builder = originalPreview.toBuilder();
+    
+    builder
+      ..name = 'Transformed - ${originalPreview.name}'
+      ..theme = _themeBuilder;
+
+    return builder.toPreview();
+  }
+}
+
+@TransformativePreview(name: 'Custom Themed Button')
+Widget myButton() => const ElevatedButton(onPressed: null, child: Text('Click'));
+```
+
+### MultiPreview Implementation
+```dart
+import 'package:flutter/widget_previews.dart';
+import 'package:flutter/material.dart';
+
+/// Creates light and dark mode previews automatically.
+final class MultiBrightnessPreview extends MultiPreview {
+  const MultiBrightnessPreview({required this.name});
+
+  final String name;
+
+  @override
+  List<Preview> get previews => const [
+        Preview(brightness: Brightness.light),
+        Preview(brightness: Brightness.dark),
+      ];
+
+  @override
+  List<Preview> transform() {
+    final previews = super.transform();
+    return previews.map((preview) {
+      final builder = preview.toBuilder()
+        ..group = 'Brightness'
+        ..name = '$name - ${preview.brightness!.name}';
+      return builder.toPreview();
+    }).toList();
+  }
+}
+
+@MultiBrightnessPreview(name: 'Primary Card')
+Widget cardPreview() => const Card(child: Padding(padding: EdgeInsets.all(8.0), child: Text('Content')));
+```