The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: salvage zh-CN framework skill translations
Affaan Mustafa4359947a6ab7
diff --git a/docs/zh-CN/skills/csharp-testing/SKILL.md b/docs/zh-CN/skills/csharp-testing/SKILL.mdnew file mode 100644index 000000000..f33c48ee0--- /dev/null+++ b/docs/zh-CN/skills/csharp-testing/SKILL.md@@ -0,0 +1,321 @@+---+name: csharp-testing+description: 使用 xUnit、FluentAssertions、模拟、集成测试和测试组织最佳实践的 C# 和 .NET 测试模式。+origin: ECC+---++# C# 测试模式++使用 xUnit、FluentAssertions 和现代测试实践为 .NET 应用程序提供的全面测试模式。++## 何时使用++* 为 C# 代码编写新测试+* 审查测试质量和覆盖率+* 为 .NET 项目搭建测试基础设施+* 调试不稳定或缓慢的测试++## 测试框架栈++| 工具 | 用途 |+|---|---|+| **xUnit** | 测试框架(.NET 首选) |+| **FluentAssertions** | 可读的断言语法 |+| **NSubstitute** 或 **Moq** | 模拟依赖项 |+| **Testcontainers** | 集成测试中的真实基础设施 |+| **WebApplicationFactory** | ASP.NET Core 集成测试 |+| **Bogus** | 生成逼真的测试数据 |++## 单元测试结构++### 安排-操作-断言++```csharp+public sealed class OrderServiceTests+{+ private readonly IOrderRepository _repository = Substitute.For<IOrderRepository>();+ private readonly ILogger<OrderService> _logger = Substitute.For<ILogger<OrderService>>();+ private readonly OrderService _sut;++ public OrderServiceTests()+ {+ _sut = new OrderService(_repository, _logger);+ }++ [Fact]+ public async Task PlaceOrderAsync_ReturnsSuccess_WhenRequestIsValid()+ {+ // Arrange+ var request = new CreateOrderRequest+ {+ CustomerId = "cust-123",+ Items = [new OrderItem("SKU-001", 2, 29.99m)]+ };++ // Act+ var result = await _sut.PlaceOrderAsync(request, CancellationToken.None);++ // Assert+ result.IsSuccess.Should().BeTrue();+ result.Value.Should().NotBeNull();+ result.Value!.CustomerId.Should().Be("cust-123");+ }++ [Fact]+ public async Task PlaceOrderAsync_ReturnsFailure_WhenNoItems()+ {+ // Arrange+ var request = new CreateOrderRequest+ {+ CustomerId = "cust-123",+ Items = []+ };++ // Act+ var result = await _sut.PlaceOrderAsync(request, CancellationToken.None);++ // Assert+ result.IsSuccess.Should().BeFalse();+ result.Error.Should().Contain("at least one item");+ }+}+```++### 使用 Theory 的参数化测试++```csharp+[Theory]+[InlineData("", false)]+[InlineData("a", false)]+[InlineData("[email protected]", false)]+[InlineData("[email protected]", true)]+[InlineData("[email protected]", true)]+public void IsValidEmail_ReturnsExpected(string email, bool expected)+{+ EmailValidator.IsValid(email).Should().Be(expected);+}++[Theory]+[MemberData(nameof(InvalidOrderCases))]+public async Task PlaceOrderAsync_RejectsInvalidOrders(CreateOrderRequest request, string expectedError)+{+ var result = await _sut.PlaceOrderAsync(request, CancellationToken.None);++ result.IsSuccess.Should().BeFalse();+ result.Error.Should().Contain(expectedError);+}++public static TheoryData<CreateOrderRequest, string> InvalidOrderCases => new()+{+ { new() { CustomerId = "", Items = [ValidItem()] }, "CustomerId" },+ { new() { CustomerId = "c1", Items = [] }, "at least one item" },+ { new() { CustomerId = "c1", Items = [new("", 1, 10m)] }, "SKU" },+};+```++## 使用 NSubstitute 进行模拟++```csharp+[Fact]+public async Task GetOrderAsync_ReturnsNull_WhenNotFound()+{+ // Arrange+ var orderId = Guid.NewGuid();+ _repository.FindByIdAsync(orderId, Arg.Any<CancellationToken>())+ .Returns((Order?)null);++ // Act+ var result = await _sut.GetOrderAsync(orderId, CancellationToken.None);++ // Assert+ result.Should().BeNull();+}++[Fact]+public async Task PlaceOrderAsync_PersistsOrder()+{+ // Arrange+ var request = ValidOrderRequest();++ // Act+ await _sut.PlaceOrderAsync(request, CancellationToken.None);++ // Assert — verify the repository was called+ await _repository.Received(1).AddAsync(+ Arg.Is<Order>(o => o.CustomerId == request.CustomerId),+ Arg.Any<CancellationToken>());+}+```++## ASP.NET Core 集成测试++### WebApplicationFactory 设置++```csharp+public sealed class OrderApiTests : IClassFixture<WebApplicationFactory<Program>>+{+ private readonly HttpClient _client;++ public OrderApiTests(WebApplicationFactory<Program> factory)+ {+ _client = factory.WithWebHostBuilder(builder =>+ {+ builder.ConfigureServices(services =>+ {+ // Replace real DB with in-memory for tests+ services.RemoveAll<DbContextOptions<AppDbContext>>();+ services.AddDbContext<AppDbContext>(options =>+ options.UseInMemoryDatabase("TestDb"));+ });+ }).CreateClient();+ }++ [Fact]+ public async Task GetOrder_Returns404_WhenNotFound()+ {+ var response = await _client.GetAsync($"/api/orders/{Guid.NewGuid()}");++ response.StatusCode.Should().Be(HttpStatusCode.NotFound);+ }++ [Fact]+ public async Task CreateOrder_Returns201_WithValidRequest()+ {+ var request = new CreateOrderRequest+ {+ CustomerId = "cust-1",+ Items = [new("SKU-001", 1, 19.99m)]+ };++ var response = await _client.PostAsJsonAsync("/api/orders", request);++ response.StatusCode.Should().Be(HttpStatusCode.Created);+ response.Headers.Location.Should().NotBeNull();+ }+}+```++### 使用 Testcontainers 进行测试++```csharp+public sealed class PostgresOrderRepositoryTests : IAsyncLifetime+{+ private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder()+ .WithImage("postgres:16-alpine")+ .Build();++ private AppDbContext _db = null!;++ public async Task InitializeAsync()+ {+ await _postgres.StartAsync();+ var options = new DbContextOptionsBuilder<AppDbContext>()+ .UseNpgsql(_postgres.GetConnectionString())+ .Options;+ _db = new AppDbContext(options);+ await _db.Database.MigrateAsync();+ }++ public async Task DisposeAsync()+ {+ await _db.DisposeAsync();+ await _postgres.DisposeAsync();+ }++ [Fact]+ public async Task AddAsync_PersistsOrder()+ {+ var repo = new SqlOrderRepository(_db);+ var order = Order.Create("cust-1", [new OrderItem("SKU-001", 2, 10m)]);++ await repo.AddAsync(order, CancellationToken.None);++ var found = await repo.FindByIdAsync(order.Id, CancellationToken.None);+ found.Should().NotBeNull();+ found!.Items.Should().HaveCount(1);+ }+}+```++## 测试组织++```+tests/+ MyApp.UnitTests/+ Services/+ OrderServiceTests.cs+ PaymentServiceTests.cs+ Validators/+ EmailValidatorTests.cs+ MyApp.IntegrationTests/+ Api/+ OrderApiTests.cs+ Repositories/+ OrderRepositoryTests.cs+ MyApp.TestHelpers/+ Builders/+ OrderBuilder.cs+ Fixtures/+ DatabaseFixture.cs+```++## 测试数据构建器++```csharp+public sealed class OrderBuilder+{+ private string _customerId = "cust-default";+ private readonly List<OrderItem> _items = [new("SKU-001", 1, 10m)];++ public OrderBuilder WithCustomer(string customerId)+ {+ _customerId = customerId;+ return this;+ }++ public OrderBuilder WithItem(string sku, int quantity, decimal price)+ {+ _items.Add(new OrderItem(sku, quantity, price));+ return this;+ }++ public Order Build() => Order.Create(_customerId, _items);+}++// Usage in tests+var order = new OrderBuilder()+ .WithCustomer("cust-vip")+ .WithItem("SKU-PREMIUM", 3, 99.99m)+ .Build();+```++## 常见反模式++| 反模式 | 修复方法 |+|---|---|+| 测试实现细节 | 测试行为和结果 |+| 共享的可变测试状态 | 每个测试使用新实例(xUnit 通过构造函数实现) |+| 在异步测试中使用 `Thread.Sleep` | 使用带超时的 `Task.Delay` 或轮询辅助方法 |+| 对 `ToString()` 输出进行断言 | 对类型化属性进行断言 |+| 每个测试一个巨型断言 | 每个测试一个逻辑断言 |+| 测试名称描述实现 | 按行为命名:`Method_ExpectedResult_WhenCondition` |+| 忽略 `CancellationToken` | 始终传递并验证取消 |++## 运行测试++```bash+# Run all tests+dotnet test++# Run with coverage+dotnet test --collect:"XPlat Code Coverage"++# Run specific project+dotnet test tests/MyApp.UnitTests/++# Filter by test name+dotnet test --filter "FullyQualifiedName~OrderService"++# Watch mode during development+dotnet watch test --project tests/MyApp.UnitTests/+```diff --git a/docs/zh-CN/skills/dart-flutter-patterns/SKILL.md b/docs/zh-CN/skills/dart-flutter-patterns/SKILL.mdnew file mode 100644index 000000000..c34471782--- /dev/null+++ b/docs/zh-CN/skills/dart-flutter-patterns/SKILL.md@@ -0,0 +1,565 @@+---+name: dart-flutter-patterns+description: 生产就绪的 Dart 和 Flutter 模式,涵盖空安全、不可变状态、异步组合、Widget 架构、流行的状态管理框架(BLoC、Riverpod、Provider)、GoRouter 导航、Dio 网络请求、Freezed 代码生成和整洁架构。+origin: ECC+---++# Dart/Flutter 模式++## 使用场景++在以下情况使用此技能:++* 开始新的 Flutter 功能,需要状态管理、导航或数据访问的惯用模式+* 审查或编写 Dart 代码,需要空安全、密封类型或异步组合的指导+* 搭建新的 Flutter 项目,在 BLoC、Riverpod 或 Provider 之间做选择+* 实现安全的 HTTP 客户端、WebView 集成或本地存储+* 为 Flutter 组件、Cubit 或 Riverpod 提供者编写测试+* 使用认证守卫配置 GoRouter++## 工作原理++此技能提供按关注点组织的、可直接复制粘贴的 Dart/Flutter 代码模式:++1. **空安全** — 避免 `!`,优先使用 `?.`/`??`/模式匹配+2. **不可变状态** — 密封类、`freezed`、`copyWith`+3. **异步组合** — 并发 `Future.wait`、`BuildContext` 后安全使用 `await`+4. **组件架构** — 提取为类(而非方法)、`const` 传播、作用域重建+5. **状态管理** — BLoC/Cubit 事件、Riverpod 通知器和派生提供者+6. **导航** — 通过 `refreshListenable` 实现带响应式认证守卫的 GoRouter+7. **网络请求** — 带拦截器的 Dio、带一次性重试守卫的令牌刷新+8. **错误处理** — 全局捕获、`ErrorWidget.builder`、Crashlytics 集成+9. **测试** — 单元测试(BLoC 测试)、组件测试(ProviderScope 覆盖)、使用假对象而非模拟对象++## 示例++```dart+// Sealed state — prevents impossible states+sealed class AsyncState<T> {}+final class Loading<T> extends AsyncState<T> {}+final class Success<T> extends AsyncState<T> { final T data; const Success(this.data); }+final class Failure<T> extends AsyncState<T> { final Object error; const Failure(this.error); }++// GoRouter with reactive auth redirect+final router = GoRouter(+ refreshListenable: GoRouterRefreshStream(authCubit.stream),+ redirect: (context, state) {+ final authed = context.read<AuthCubit>().state is AuthAuthenticated;+ if (!authed && !state.matchedLocation.startsWith('/login')) return '/login';+ return null;+ },+ routes: [...],+);++// Riverpod derived provider with safe firstWhereOrNull+@riverpod+double cartTotal(Ref ref) {+ final cart = ref.watch(cartNotifierProvider);+ final products = ref.watch(productsProvider).valueOrNull ?? [];+ return cart.fold(0.0, (total, item) {+ final product = products.firstWhereOrNull((p) => p.id == item.productId);+ return total + (product?.price ?? 0) * item.quantity;+ });+}+```++***++适用于 Dart 和 Flutter 应用程序的实用、生产就绪模式。尽可能保持库无关性,并明确覆盖最常见的生态系统包。++***++## 1. 空安全基础++### 优先使用模式而非感叹号操作符++```dart+// BAD — crashes at runtime if null+final name = user!.name;++// GOOD — provide fallback+final name = user?.name ?? 'Unknown';++// GOOD — Dart 3 pattern matching (preferred for complex cases)+final display = switch (user) {+ User(:final name, :final email) => '$name <$email>',+ null => 'Guest',+};++// GOOD — guard early return+String getUserName(User? user) {+ if (user == null) return 'Unknown';+ return user.name; // promoted to non-null after check+}+```++### 避免过度使用 `late`++```dart+// BAD — defers null error to runtime+late String userId;++// GOOD — nullable with explicit initialization+String? userId;++// OK — use late only when initialization is guaranteed before first access+// (e.g., in initState() before any widget interaction)+late final AnimationController _controller;++@override+void initState() {+ super.initState();+ _controller = AnimationController(vsync: this, duration: const Duration(milliseconds: 300));+}+```++***++## 2. 不可变状态++### 状态层次结构的密封类++```dart+sealed class UserState {}++final class UserInitial extends UserState {}++final class UserLoading extends UserState {}++final class UserLoaded extends UserState {+ const UserLoaded(this.user);+ final User user;+}++final class UserError extends UserState {+ const UserError(this.message);+ final String message;+}++// Exhaustive switch — compiler enforces all branches+Widget buildFrom(UserState state) => switch (state) {+ UserInitial() => const SizedBox.shrink(),+ UserLoading() => const CircularProgressIndicator(),+ UserLoaded(:final user) => UserCard(user: user),+ UserError(:final message) => ErrorText(message),+};+```++### 使用 Freezed 实现无模板代码的不可变性++```dart+import 'package:freezed_annotation/freezed_annotation.dart';++part 'user.freezed.dart';+part 'user.g.dart';++@freezed+class User with _$User {+ const factory User({+ required String id,+ required String name,+ required String email,+ @Default(false) bool isAdmin,+ }) = _User;++ factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);+}++// Usage+final user = User(id: '1', name: 'Alice', email: '[email protected]');+final updated = user.copyWith(name: 'Alice Smith'); // immutable update+final json = user.toJson();+final fromJson = User.fromJson(json);+```++***++## 3. 异步组合++### 使用 Future.wait 的结构化并发++```dart+Future<DashboardData> loadDashboard(UserRepository users, OrderRepository orders) async {+ // Run concurrently — don't await sequentially+ final (userList, orderList) = await (+ users.getAll(),+ orders.getRecent(),+ ).wait; // Dart 3 record destructuring + Future.wait extension++ return DashboardData(users: userList, orders: orderList);+}+```++### 流模式++```dart+// Repository exposes reactive streams for live data+Stream<List<Item>> watchCartItems() => _db+ .watchTable('cart_items')+ .map((rows) => rows.map(Item.fromRow).toList());++// In widget layer — declarative, no manual subscription+StreamBuilder<List<Item>>(+ stream: cartRepository.watchCartItems(),+ builder: (context, snapshot) => switch (snapshot) {+ AsyncSnapshot(connectionState: ConnectionState.waiting) =>+ const CircularProgressIndicator(),+ AsyncSnapshot(:final error?) => ErrorWidget(error.toString()),+ AsyncSnapshot(:final data?) => CartList(items: data),+ _ => const SizedBox.shrink(),+ },+)+```++### Await 后的 BuildContext++```dart+// CRITICAL — always check mounted after any await in StatefulWidget+Future<void> _handleSubmit() async {+ setState(() => _isLoading = true);+ try {+ await authService.login(_email, _password);+ if (!mounted) return; // ← guard before using context+ context.go('/home');+ } on AuthException catch (e) {+ if (!mounted) return;+ ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(e.message)));+ } finally {+ if (mounted) setState(() => _isLoading = false);+ }+}+```++***++## 4. 组件架构++### 提取为类,而非方法++```dart+// BAD — private method returning widget, prevents optimization+Widget _buildHeader() {+ return Container(+ padding: const EdgeInsets.all(16),+ child: Text(title, style: Theme.of(context).textTheme.headlineMedium),+ );+}++// GOOD — separate widget class, enables const, element reuse+class _PageHeader extends StatelessWidget {+ const _PageHeader(this.title);+ final String title;++ @override+ Widget build(BuildContext context) {+ return Container(+ padding: const EdgeInsets.all(16),+ child: Text(title, style: Theme.of(context).textTheme.headlineMedium),+ );+ }+}+```++### const 传播++```dart+// BAD — new instances every rebuild+child: Padding(+ padding: EdgeInsets.all(16.0), // not const+ child: Icon(Icons.home, size: 24.0), // not const+)++// GOOD — const stops rebuild propagation+child: const Padding(+ padding: EdgeInsets.all(16.0),+ child: Icon(Icons.home, size: 24.0),+)+```++### 作用域重建++```dart+// BAD — entire page rebuilds on every counter change+class CounterPage extends ConsumerWidget {+ @override+ Widget build(BuildContext context, WidgetRef ref) {+ final count = ref.watch(counterProvider); // rebuilds everything+ return Scaffold(+ body: Column(children: [+ const ExpensiveHeader(), // unnecessarily rebuilt+ Text('$count'),+ const ExpensiveFooter(), // unnecessarily rebuilt+ ]),+ );+ }+}++// GOOD — isolate the rebuilding part+class CounterPage extends StatelessWidget {+ const CounterPage({super.key});++ @override+ Widget build(BuildContext context) {+ return const Scaffold(+ body: Column(children: [+ ExpensiveHeader(), // never rebuilt (const)+ _CounterDisplay(), // only this rebuilds+ ExpensiveFooter(), // never rebuilt (const)+ ]),+ );+ }+}++class _CounterDisplay extends ConsumerWidget {+ const _CounterDisplay();++ @override+ Widget build(BuildContext context, WidgetRef ref) {+ final count = ref.watch(counterProvider);+ return Text('$count');+ }+}+```++***++## 5. 状态管理:BLoC/Cubit++```dart+// Cubit — synchronous or simple async state+class AuthCubit extends Cubit<AuthState> {+ AuthCubit(this._authService) : super(const AuthState.initial());+ final AuthService _authService;++ Future<void> login(String email, String password) async {+ emit(const AuthState.loading());+ try {+ final user = await _authService.login(email, password);+ emit(AuthState.authenticated(user));+ } on AuthException catch (e) {+ emit(AuthState.error(e.message));+ }+ }++ void logout() {+ _authService.logout();+ emit(const AuthState.initial());+ }+}++// In widget+BlocBuilder<AuthCubit, AuthState>(+ builder: (context, state) => switch (state) {+ AuthInitial() => const LoginForm(),+ AuthLoading() => const CircularProgressIndicator(),+ AuthAuthenticated(:final user) => HomePage(user: user),+ AuthError(:final message) => ErrorView(message: message),+ },+)+```++***++## 6. 状态管理:Riverpod++```dart+// Auto-dispose async provider+@riverpod+Future<List<Product>> products(Ref ref) async {+ final repo = ref.watch(productRepositoryProvider);+ return repo.getAll();+}++// Notifier with complex mutations+@riverpod+class CartNotifier extends _$CartNotifier {+ @override+ List<CartItem> build() => [];++ void add(Product product) {+ final existing = state.where((i) => i.productId == product.id).firstOrNull;+ if (existing != null) {+ state = [+ for (final item in state)+ if (item.productId == product.id) item.copyWith(quantity: item.quantity + 1)+ else item,+ ];+ } else {+ state = [...state, CartItem(productId: product.id, quantity: 1)];+ }+ }++ void remove(String productId) =>+ state = state.where((i) => i.productId != productId).toList();++ void clear() => state = [];+}++// Derived provider (selector pattern)+@riverpod+int cartCount(Ref ref) => ref.watch(cartNotifierProvider).length;++@riverpod+double cartTotal(Ref ref) {+ final cart = ref.watch(cartNotifierProvider);+ final products = ref.watch(productsProvider).valueOrNull ?? [];+ return cart.fold(0.0, (total, item) {+ // firstWhereOrNull (from collection package) avoids StateError when product is missing+ final product = products.firstWhereOrNull((p) => p.id == item.productId);+ return total + (product?.price ?? 0) * item.quantity;+ });+}+```++***++## 7. 使用 GoRouter 的导航++```dart+final router = GoRouter(+ initialLocation: '/',+ // refreshListenable re-evaluates redirect whenever auth state changes+ refreshListenable: GoRouterRefreshStream(authCubit.stream),+ redirect: (context, state) {+ final isLoggedIn = context.read<AuthCubit>().state is AuthAuthenticated;+ final isGoingToLogin = state.matchedLocation == '/login';+ if (!isLoggedIn && !isGoingToLogin) return '/login';+ if (isLoggedIn && isGoingToLogin) return '/';+ return null;+ },+ routes: [+ GoRoute(path: '/login', builder: (_, __) => const LoginPage()),+ ShellRoute(+ builder: (context, state, child) => AppShell(child: child),+ routes: [+ GoRoute(path: '/', builder: (_, __) => const HomePage()),+ GoRoute(+ path: '/products/:id',+ builder: (context, state) =>+ ProductDetailPage(id: state.pathParameters['id']!),+ ),+ ],+ ),+ ],+);+```++***++## 8. 使用 Dio 的 HTTP 请求++```dart+final dio = Dio(BaseOptions(+ baseUrl: const String.fromEnvironment('API_URL'),+ connectTimeout: const Duration(seconds: 10),+ receiveTimeout: const Duration(seconds: 30),+ headers: {'Content-Type': 'application/json'},+));++// Add auth interceptor+dio.interceptors.add(InterceptorsWrapper(+ onRequest: (options, handler) async {+ final token = await secureStorage.read(key: 'auth_token');+ if (token != null) options.headers['Authorization'] = 'Bearer $token';+ handler.next(options);+ },+ onError: (error, handler) async {+ // Guard against infinite retry loops: only attempt refresh once per request+ final isRetry = error.requestOptions.extra['_isRetry'] == true;+ if (!isRetry && error.response?.statusCode == 401) {+ final refreshed = await attemptTokenRefresh();+ if (refreshed) {+ error.requestOptions.extra['_isRetry'] = true;+ return handler.resolve(await dio.fetch(error.requestOptions));+ }+ }+ handler.next(error);+ },+));++// Repository using Dio+class UserApiDataSource {+ const UserApiDataSource(this._dio);+ final Dio _dio;++ Future<User> getById(String id) async {+ final response = await _dio.get<Map<String, dynamic>>('/users/$id');+ return User.fromJson(response.data!);+ }+}+```++***++## 9. 错误处理架构++```dart+// Global error capture — set up in main()+void main() {+ FlutterError.onError = (details) {+ FlutterError.presentError(details);+ crashlytics.recordFlutterFatalError(details);+ };++ PlatformDispatcher.instance.onError = (error, stack) {+ crashlytics.recordError(error, stack, fatal: true);+ return true;+ };++ runApp(const App());+}++// Custom ErrorWidget for production+class App extends StatelessWidget {+ @override+ Widget build(BuildContext context) {+ ErrorWidget.builder = (details) => ProductionErrorWidget(details);+ return MaterialApp.router(routerConfig: router);+ }+}+```++***++## 10. 测试快速参考++```dart+// Unit test — use case+test('GetUserUseCase returns null for missing user', () async {+ final repo = FakeUserRepository();+ final useCase = GetUserUseCase(repo);+ expect(await useCase('missing-id'), isNull);+});++// BLoC test+blocTest<AuthCubit, AuthState>(+ 'emits loading then error on failed login',+ build: () => AuthCubit(FakeAuthService(throwsOn: 'login')),+ act: (cubit) => cubit.login('[email protected]', 'wrong'),+ expect: () => [const AuthState.loading(), isA<AuthError>()],+);++// Widget test+testWidgets('CartBadge shows item count', (tester) async {+ await tester.pumpWidget(+ ProviderScope(+ overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier(count: 3))],+ child: const MaterialApp(home: CartBadge()),+ ),+ );+ expect(find.text('3'), findsOneWidget);+});+```++***++## 参考++* [Effective Dart: 设计](https://dart.dev/effective-dart/design)+* [Flutter 性能最佳实践](https://docs.flutter.dev/perf/best-practices)+* [Riverpod 文档](https://riverpod.dev/)+* [BLoC 库](https://bloclibrary.dev/)+* [GoRouter](https://pub.dev/packages/go_router)+* [Freezed](https://pub.dev/packages/freezed)+* 技能:`flutter-dart-code-review` — 全面审查清单+* 规则:`rules/dart/` — 编码风格、模式、安全性、测试、钩子diff --git a/docs/zh-CN/skills/dashboard-builder/SKILL.md b/docs/zh-CN/skills/dashboard-builder/SKILL.mdnew file mode 100644index 000000000..f4d64ae83--- /dev/null+++ b/docs/zh-CN/skills/dashboard-builder/SKILL.md@@ -0,0 +1,108 @@+---+name: dashboard-builder+description: 为 Grafana、SigNoz 等平台构建能够回答实际运维人员问题的监控仪表板。适用于将指标转化为可用的仪表板,而非华而不实的展示板。+origin: ECC direct-port adaptation+version: "1.0.0"+---++# 仪表盘构建器++当任务需要构建一个可供操作人员使用的仪表盘时使用此方案。++目标不是"展示所有指标",而是回答以下问题:++* 系统健康吗?+* 瓶颈在哪里?+* 发生了什么变化?+* 应该采取什么行动?++## 使用场景++* "构建一个Kafka监控仪表盘"+* "为Elasticsearch创建一个Grafana仪表盘"+* "为这个服务制作一个SigNoz仪表盘"+* "将这个指标列表转化为真正的运维仪表盘"++## 约束条件++* 不要从视觉布局开始;要从操作人员的问题出发+* 不要仅仅因为指标存在就包含所有可用指标+* 不要在没有结构的情况下混合健康、吞吐量和资源面板+* 不要发布没有标题、单位和合理阈值的面板++## 工作流程++### 1. 定义操作问题++围绕以下方面组织:++* 健康/可用性+* 延迟/性能+* 吞吐量/容量+* 饱和度/资源+* 服务特定风险++### 2. 研究目标平台架构++首先检查现有仪表盘:++* JSON结构+* 查询语言+* 变量+* 阈值样式+* 分区布局++### 3. 构建最小可用面板++推荐结构:++1. 概览+2. 性能+3. 资源+4. 服务特定分区++### 4. 剔除装饰性面板++每个面板都应回答一个真实问题。如果不能,则移除。++## 示例面板集++### Elasticsearch++* 集群健康+* 分片分配+* 搜索延迟+* 索引速率+* JVM堆/GC++### Kafka++* 代理数量+* 副本不足的分区+* 消息流入/流出+* 消费者滞后+* 磁盘和网络压力++### API网关/入口++* 请求速率+* p50/p95/p99延迟+* 错误率+* 上游健康+* 活跃连接数++## 质量检查清单++* \[ ] 有效的仪表盘JSON+* \[ ] 清晰的分区分组+* \[ ] 包含标题和单位+* \[ ] 阈值/状态颜色有意义+* \[ ] 存在常用过滤器的变量+* \[ ] 默认时间范围和刷新频率合理+* \[ ] 没有对操作人员无价值的装饰性面板++## 相关技能++* `research-ops`+* `backend-patterns`+* `terminal-ops`diff --git a/docs/zh-CN/skills/design-system/SKILL.md b/docs/zh-CN/skills/design-system/SKILL.mdnew file mode 100644index 000000000..9c08f34af--- /dev/null+++ b/docs/zh-CN/skills/design-system/SKILL.md@@ -0,0 +1,85 @@+---+name: design-system+description: 使用此技能生成或审计设计系统,检查视觉一致性,并审查涉及样式的PR。+origin: ECC+---++# 设计系统 — 生成与审查视觉系统++## 使用场景++* 启动需要设计系统的新项目+* 审查现有代码库的视觉一致性+* 在重新设计前——了解现有状况+* 当界面看起来"不对劲"但无法定位原因时+* 审查涉及样式修改的PR++## 工作原理++### 模式1:生成设计系统++分析代码库并生成统一的设计系统:++```+1. 扫描 CSS/Tailwind/styled-components 以查找现有模式+2. 提取:颜色、排版、间距、边框圆角、阴影、断点+3. 研究 3 个竞品网站以获取灵感(通过浏览器 MCP)+4. 提出一套设计令牌(JSON + CSS 自定义属性)+5. 生成 DESIGN.md,说明每个决策的理由+6. 创建一个交互式 HTML 预览页面(自包含,无依赖)+```++输出:`DESIGN.md` + `design-tokens.json` + `design-preview.html`++### 模式2:视觉审查++从10个维度对界面进行评分(每项0-10分):++```+1. 色彩一致性 — 你使用的是自己的调色板还是随机的十六进制值?+2. 排版层级 — 清晰的 h1 > h2 > h3 > 正文 > 说明文字?+3. 间距节奏 — 一致的尺度(4px/8px/16px)还是随意设置?+4. 组件一致性 — 相似的元素看起来是否相似?+5. 响应式行为 — 在断点处流畅还是混乱?+6. 深色模式 — 完整实现还是半途而废?+7. 动画 — 有目的性还是多余?+8. 无障碍性 — 对比度、焦点状态、触摸目标+9. 信息密度 — 杂乱还是整洁?+10. 细节打磨 — 悬停状态、过渡效果、加载状态、空状态+```++每个维度都会获得评分、具体示例以及包含精确文件:行号的修复方案。++### 模式3:AI生成内容检测++识别通用的AI生成设计模式:++```+- 到处滥用渐变效果+- 默认采用紫蓝配色+- 毫无意义的"玻璃拟态"卡片+- 不该圆角的地方强行圆角+- 滚动时过度动画效果+- 居中文字搭配默认渐变的通用英雄区+- 毫无个性的无衬线字体堆叠+```++## 示例++**为SaaS应用生成设计系统:**++```+/design-system generate --style minimal --palette earth-tones+```++**审查现有界面:**++```+/design-system audit --url http://localhost:3000 --pages / /pricing /docs+```++**检测AI生成内容:**++```+/design-system slop-check+```diff --git a/docs/zh-CN/skills/dotnet-patterns/SKILL.md b/docs/zh-CN/skills/dotnet-patterns/SKILL.mdnew file mode 100644index 000000000..79956144a--- /dev/null+++ b/docs/zh-CN/skills/dotnet-patterns/SKILL.md@@ -0,0 +1,321 @@+---+name: dotnet-patterns+description: 惯用的C#和.NET模式、约定、依赖注入、async/await以及构建健壮、可维护的.NET应用程序的最佳实践。+origin: ECC+---++# .NET 开发模式++用于构建健壮、高性能且可维护应用程序的惯用 C# 和 .NET 模式。++## 何时激活++* 编写新的 C# 代码时+* 审查 C# 代码时+* 重构现有 .NET 应用程序时+* 使用 ASP.NET Core 设计服务架构时++## 核心原则++### 1. 优先使用不可变性++对数据模型使用记录和仅初始化属性。可变性应作为明确且有理由的选择。++```csharp+// Good: Immutable value object+public sealed record Money(decimal Amount, string Currency);++// Good: Immutable DTO with init setters+public sealed class CreateOrderRequest+{+ public required string CustomerId { get; init; }+ public required IReadOnlyList<OrderItem> Items { get; init; }+}++// Bad: Mutable model with public setters+public class Order+{+ public string CustomerId { get; set; }+ public List<OrderItem> Items { get; set; }+}+```++### 2. 显式优于隐式++明确表达可空性、访问修饰符和意图。++```csharp+// Good: Explicit access modifiers and nullability+public sealed class UserService+{+ private readonly IUserRepository _repository;+ private readonly ILogger<UserService> _logger;++ public UserService(IUserRepository repository, ILogger<UserService> logger)+ {+ _repository = repository ?? throw new ArgumentNullException(nameof(repository));+ _logger = logger ?? throw new ArgumentNullException(nameof(logger));+ }++ public async Task<User?> FindByIdAsync(Guid id, CancellationToken cancellationToken)+ {+ return await _repository.FindByIdAsync(id, cancellationToken);+ }+}+```++### 3. 依赖抽象++对服务边界使用接口。通过依赖注入容器注册。++```csharp+// Good: Interface-based dependency+public interface IOrderRepository+{+ Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken);+ Task<IReadOnlyList<Order>> FindByCustomerAsync(string customerId, CancellationToken cancellationToken);+ Task AddAsync(Order order, CancellationToken cancellationToken);+}++// Registration+builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();+```++## 异步/等待模式++### 正确使用异步++```csharp+// Good: Async all the way, with CancellationToken+public async Task<OrderSummary> GetOrderSummaryAsync(+ Guid orderId,+ CancellationToken cancellationToken)+{+ var order = await _repository.FindByIdAsync(orderId, cancellationToken)+ ?? throw new NotFoundException($"Order {orderId} not found");++ var customer = await _customerService.GetAsync(order.CustomerId, cancellationToken);++ return new OrderSummary(order, customer);+}++// Bad: Blocking on async+public OrderSummary GetOrderSummary(Guid orderId)+{+ var order = _repository.FindByIdAsync(orderId, CancellationToken.None).Result; // Deadlock risk+ return new OrderSummary(order);+}+```++### 并行异步操作++```csharp+// Good: Concurrent independent operations+public async Task<DashboardData> LoadDashboardAsync(CancellationToken cancellationToken)+{+ var ordersTask = _orderService.GetRecentAsync(cancellationToken);+ var metricsTask = _metricsService.GetCurrentAsync(cancellationToken);+ var alertsTask = _alertService.GetActiveAsync(cancellationToken);++ await Task.WhenAll(ordersTask, metricsTask, alertsTask);++ return new DashboardData(+ Orders: await ordersTask,+ Metrics: await metricsTask,+ Alerts: await alertsTask);+}+```++## 选项模式++将配置节绑定到强类型对象。++```csharp+public sealed class SmtpOptions+{+ public const string SectionName = "Smtp";++ public required string Host { get; init; }+ public required int Port { get; init; }+ public required string Username { get; init; }+ public bool UseSsl { get; init; } = true;+}++// Registration+builder.Services.Configure<SmtpOptions>(+ builder.Configuration.GetSection(SmtpOptions.SectionName));++// Usage via injection+public class EmailService(IOptions<SmtpOptions> options)+{+ private readonly SmtpOptions _smtp = options.Value;+}+```++## 结果模式++对预期失败返回显式成功/失败,而非抛出异常。++```csharp+public sealed record Result<T>+{+ public bool IsSuccess { get; }+ public T? Value { get; }+ public string? Error { get; }++ private Result(T value) { IsSuccess = true; Value = value; }+ private Result(string error) { IsSuccess = false; Error = error; }++ public static Result<T> Success(T value) => new(value);+ public static Result<T> Failure(string error) => new(error);+}++// Usage+public async Task<Result<Order>> PlaceOrderAsync(CreateOrderRequest request)+{+ if (request.Items.Count == 0)+ return Result<Order>.Failure("Order must contain at least one item");++ var order = Order.Create(request);+ await _repository.AddAsync(order, CancellationToken.None);+ return Result<Order>.Success(order);+}+```++## 使用 EF Core 的仓储模式++```csharp+public sealed class SqlOrderRepository : IOrderRepository+{+ private readonly AppDbContext _db;++ public SqlOrderRepository(AppDbContext db) => _db = db;++ public async Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken)+ {+ return await _db.Orders+ .Include(o => o.Items)+ .AsNoTracking()+ .FirstOrDefaultAsync(o => o.Id == id, cancellationToken);+ }++ public async Task<IReadOnlyList<Order>> FindByCustomerAsync(+ string customerId,+ CancellationToken cancellationToken)+ {+ return await _db.Orders+ .Where(o => o.CustomerId == customerId)+ .OrderByDescending(o => o.CreatedAt)+ .AsNoTracking()+ .ToListAsync(cancellationToken);+ }++ public async Task AddAsync(Order order, CancellationToken cancellationToken)+ {+ _db.Orders.Add(order);+ await _db.SaveChangesAsync(cancellationToken);+ }+}+```++## 中间件与管道++```csharp+// Custom middleware+public sealed class RequestTimingMiddleware+{+ private readonly RequestDelegate _next;+ private readonly ILogger<RequestTimingMiddleware> _logger;++ public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)+ {+ _next = next;+ _logger = logger;+ }++ public async Task InvokeAsync(HttpContext context)+ {+ var stopwatch = Stopwatch.StartNew();+ try+ {+ await _next(context);+ }+ finally+ {+ stopwatch.Stop();+ _logger.LogInformation(+ "Request {Method} {Path} completed in {ElapsedMs}ms with status {StatusCode}",+ context.Request.Method,+ context.Request.Path,+ stopwatch.ElapsedMilliseconds,+ context.Response.StatusCode);+ }+ }+}+```++## 最小 API 模式++```csharp+// Organized with route groups+var orders = app.MapGroup("/api/orders")+ .RequireAuthorization()+ .WithTags("Orders");++orders.MapGet("/{id:guid}", async (+ Guid id,+ IOrderRepository repository,+ CancellationToken cancellationToken) =>+{+ var order = await repository.FindByIdAsync(id, cancellationToken);+ return order is not null+ ? TypedResults.Ok(order)+ : TypedResults.NotFound();+});++orders.MapPost("/", async (+ CreateOrderRequest request,+ IOrderService service,+ CancellationToken cancellationToken) =>+{+ var result = await service.PlaceOrderAsync(request, cancellationToken);+ return result.IsSuccess+ ? TypedResults.Created($"/api/orders/{result.Value!.Id}", result.Value)+ : TypedResults.BadRequest(result.Error);+});+```++## 守卫子句++```csharp+// Good: Early returns with clear validation+public async Task<ProcessResult> ProcessPaymentAsync(+ PaymentRequest request,+ CancellationToken cancellationToken)+{+ ArgumentNullException.ThrowIfNull(request);++ if (request.Amount <= 0)+ throw new ArgumentOutOfRangeException(nameof(request.Amount), "Amount must be positive");++ if (string.IsNullOrWhiteSpace(request.Currency))+ throw new ArgumentException("Currency is required", nameof(request.Currency));++ // Happy path continues here without nesting+ var gateway = _gatewayFactory.Create(request.Currency);+ return await gateway.ChargeAsync(request, cancellationToken);+}+```++## 应避免的反模式++| 反模式 | 修复方案 |+|---|---|+| `async void` 方法 | 返回 `Task`(事件处理程序除外) |+| `.Result` 或 `.Wait()` | 使用 `await` |+| `catch (Exception) { }` | 处理或带上下文重新抛出 |+| 构造函数中的 `new Service()` | 使用构造函数注入 |+| `public` 字段 | 使用带适当访问器的属性 |+| 业务逻辑中的 `dynamic` | 使用泛型或显式类型 |+| 可变的 `static` 状态 | 使用依赖注入作用域或 `ConcurrentDictionary` |+| 循环中的 `string.Format` | 使用 `StringBuilder` 或内插字符串处理程序 |diff --git a/docs/zh-CN/skills/gan-style-harness/SKILL.md b/docs/zh-CN/skills/gan-style-harness/SKILL.mdnew file mode 100644index 000000000..303c0d7d0--- /dev/null+++ b/docs/zh-CN/skills/gan-style-harness/SKILL.md@@ -0,0 +1,284 @@+---+name: gan-style-harness+description: "受GAN启发的生成器-评估器代理框架,用于自主构建高质量应用。基于Anthropic 2026年3月的框架设计论文。"+origin: ECC-community+tools: Read, Write, Edit, Bash, Grep, Glob, Task+---++# GAN 风格编排技能++> 灵感来源于 [Anthropic 的长时间运行应用开发编排设计](https://www.anthropic.com/engineering/harness-design-long-running-apps)(2026年3月24日)++一种多智能体编排,将**生成**与**评估**分离,形成对抗性反馈循环,推动质量远超单个智能体所能达到的水平。++## 核心洞察++> 当要求评估自身工作时,智能体是病态的乐观主义者——它们会赞美平庸的输出,并说服自己忽略真正的问题。但设计一个**独立的评估器**并使其极度严格,远比教会生成器自我批评要容易得多。++这与 GAN(生成对抗网络)的机制相同:生成器负责产出,评估器负责批评,这种反馈驱动下一轮迭代。++## 适用场景++* 根据一行提示构建完整应用+* 需要高视觉质量的前端设计任务+* 需要工作功能而不仅仅是代码的全栈项目+* 任何"AI 垃圾"美学不可接受的任务+* 愿意投入 50-200 美元以获得生产级质量输出的项目++## 不适用场景++* 快速单文件修复(使用标准 `claude -p`)+* 预算紧张的任务(<10 美元)+* 简单重构(改用去垃圾化模式)+* 已有完善测试规范的任务(使用 TDD 工作流)++## 架构++```+ ┌─────────────┐+ │ 规划器 │+ │ (Opus 4.6) │+ └──────┬──────┘+ │ 产品规格+ │ (功能、冲刺、设计方向)+ ▼+ ┌────────────────────────┐+ │ │+ │ 生成器-评估器 │+ │ 反馈循环 │+ │ │+ │ ┌──────────┐ │+ │ │ 生成器 │--构建-->│──┐+ │ │(Opus 4.6)│ │ │+ │ └────▲─────┘ │ │+ │ │ │ │ 实时应用+ │ 反馈 │ │+ │ │ │ │+ │ ┌────┴─────┐ │ │+ │ │ 评估器 │<-测试---│──┘+ │ │(Opus 4.6)│ │+ │ │+Playwright│ │+ │ └──────────┘ │+ │ │+ │ 5-15 次迭代 │+ └────────────────────────┘+```++## 三个智能体++### 1. 规划器智能体++**角色:** 产品经理——将简短的提示扩展为完整的产品规格。++**关键行为:**++* 接收一行提示,生成包含 16 个功能、多个冲刺的规格+* 定义用户故事、技术需求和视觉设计方向+* 故意**雄心勃勃**——保守规划会导致结果平庸+* 生成评估器后续使用的评估标准++**模型:** Opus 4.6(需要深度推理进行规格扩展)++### 2. 生成器智能体++**角色:** 开发者——根据规格实现功能。++**关键行为:**++* 按结构化冲刺工作(或使用较新模型的连续模式)+* 在编写代码前与评估器协商"冲刺合约"+* 使用全栈工具:React、FastAPI/Express、数据库、CSS+* 管理 git 进行迭代间的版本控制+* 读取评估器反馈并在下一轮迭代中采纳++**模型:** Opus 4.6(需要强大的编码能力)++### 3. 评估器智能体++**角色:** QA 工程师——测试实时运行的应用,而不仅仅是代码。++**关键行为:**++* 使用 **Playwright MCP** 与实时应用交互+* 点击功能、填写表单、测试 API 端点+* 根据四个标准评分(可配置):+ 1. **设计质量**——是否感觉像一个连贯的整体?+ 2. **原创性**——自定义决策 vs. 模板/AI 模式?+ 3. **工艺**——排版、间距、动画、微交互?+ 4. **功能性**——所有功能是否真正工作?+* 返回结构化反馈,包含分数和具体问题+* 设计为**极度严格**——从不赞美平庸的工作++**模型:** Opus 4.6(需要强大的判断力 + 工具使用能力)++## 评估标准++默认四个标准,每个评分 1-10:++```markdown+## 评估标准++### 设计质量(权重:0.3)+- 1-3分:模板化、千篇一律的"AI生成"美学+- 4-6分:合格但平庸,遵循常规设计+- 7-8分:独特且连贯的视觉识别+- 9-10分:可媲美专业设计师作品++### 原创性(权重:0.2)+- 1-3分:默认配色、模板布局,缺乏个性+- 4-6分:部分自定义选择,整体仍属常规模式+- 7-8分:清晰的创意构思,独特的设计手法+- 9-10分:令人惊喜、愉悦,真正新颖++### 工艺水平(权重:0.3)+- 1-3分:布局错乱,状态缺失,无动画效果+- 4-6分:功能可用但粗糙,间距不统一+- 7-8分:精致流畅,过渡平滑,响应式设计+- 9-10分:像素级完美,令人愉悦的微交互++### 功能性(权重:0.2)+- 1-3分:核心功能损坏或缺失+- 4-6分:主流程可用,边缘情况处理失败+- 7-8分:所有功能正常,错误处理良好+- 9-10分:无懈可击,覆盖所有边缘情况+```++### 评分++* **加权分数** = 总和(标准\_分数 \* 权重)+* **通过阈值** = 7.0(可配置)+* **最大迭代次数** = 15(可配置,通常 5-15 次足够)++## 使用方法++### 通过命令行++```bash+# Full three-agent harness+/project:gan-build "Build a project management app with Kanban boards, team collaboration, and dark mode"++# With custom config+/project:gan-build "Build a recipe sharing platform" --max-iterations 10 --pass-threshold 7.5++# Frontend design mode (generator + evaluator only, no planner)+/project:gan-design "Create a landing page for a crypto portfolio tracker"+```++### 通过 Shell 脚本++```bash+# Basic usage+./scripts/gan-harness.sh "Build a music streaming dashboard"++# With options+GAN_MAX_ITERATIONS=10 \+GAN_PASS_THRESHOLD=7.5 \+GAN_EVAL_CRITERIA="functionality,performance,security" \+./scripts/gan-harness.sh "Build a REST API for task management"+```++### 通过 Claude Code(手动)++```bash+# Step 1: Plan+claude -p --model opus "You are a Product Planner. Read PLANNER_PROMPT.md. Expand this brief into a full product spec: 'Build a Kanban board app'. Write spec to spec.md"++# Step 2: Generate (iteration 1)+claude -p --model opus "You are a Generator. Read spec.md. Implement Sprint 1. Start the dev server on port 3000."++# Step 3: Evaluate (iteration 1)+claude -p --model opus --allowedTools "Read,Bash,mcp__playwright__*" "You are an Evaluator. Read EVALUATOR_PROMPT.md. Test the live app at http://localhost:3000. Score against the rubric. Write feedback to feedback-001.md"++# Step 4: Generate (iteration 2 — reads feedback)+claude -p --model opus "You are a Generator. Read spec.md and feedback-001.md. Address all issues. Improve the scores."++# Repeat steps 3-4 until pass threshold met+```++## 随模型能力的演进++编排应随模型改进而简化。遵循 Anthropic 的演进路径:++### 阶段 1 — 较弱模型(Sonnet 级别)++* 需要完整的冲刺分解+* 冲刺间重置上下文(避免上下文焦虑)+* 最少 2 个智能体:初始化器 + 编码智能体+* 大量脚手架弥补模型限制++### 阶段 2 — 能力型模型(Opus 4.5 级别)++* 完整的 3 智能体编排:规划器 + 生成器 + 评估器+* 每个实现阶段前有冲刺合约+* 复杂应用分解为 10 个冲刺+* 上下文重置仍有帮助但不再关键++### 阶段 3 — 前沿模型(Opus 4.6 级别)++* 简化编排:单次规划,连续生成+* 评估简化为单次最终评估(模型更智能)+* 无需冲刺结构+* 自动压缩处理上下文增长++> **关键原则:** 编排的每个组件都编码了一个关于模型无法独立完成什么的假设。当模型改进时,重新测试这些假设。剥离不再需要的部分。++## 配置++### 环境变量++| 变量 | 默认值 | 描述 |+|----------|---------|-------------|+| `GAN_MAX_ITERATIONS` | `15` | 最大生成器-评估器循环次数 |+| `GAN_PASS_THRESHOLD` | `7.0` | 通过所需的加权分数(1-10) |+| `GAN_PLANNER_MODEL` | `opus` | 规划智能体的模型 |+| `GAN_GENERATOR_MODEL` | `opus` | 生成器智能体的模型 |+| `GAN_EVALUATOR_MODEL` | `opus` | 评估器智能体的模型 |+| `GAN_EVAL_CRITERIA` | `design,originality,craft,functionality` | 逗号分隔的标准 |+| `GAN_DEV_SERVER_PORT` | `3000` | 实时应用的端口 |+| `GAN_DEV_SERVER_CMD` | `npm run dev` | 启动开发服务器的命令 |+| `GAN_PROJECT_DIR` | `.` | 项目工作目录 |+| `GAN_SKIP_PLANNER` | `false` | 跳过规划器,直接使用规格 |+| `GAN_EVAL_MODE` | `playwright` | `playwright`、`screenshot` 或 `code-only` |++### 评估模式++| 模式 | 工具 | 最适合 |+|------|-------|----------|+| `playwright` | 浏览器 MCP + 实时交互 | 带 UI 的全栈应用 |+| `screenshot` | 截图 + 视觉分析 | 静态网站、纯设计 |+| `code-only` | 测试 + 代码检查 + 构建 | API、库、CLI 工具 |++## 反模式++1. **评估器过于宽松**——如果评估器在第一次迭代就通过所有内容,你的评分标准过于慷慨。收紧评分标准,并为常见的 AI 模式添加明确惩罚。++2. **生成器忽略反馈**——确保反馈以文件形式传递,而非内联。生成器应在每次迭代开始时读取 `feedback-NNN.md`。++3. **无限循环**——始终设置 `GAN_MAX_ITERATIONS`。如果生成器在 3 次迭代后无法突破分数平台,停止并标记为人工审查。++4. **评估器测试流于表面**——评估器必须使用 Playwright **交互**实时应用,而不仅仅是截图。点击按钮、填写表单、测试错误状态。++5. **评估器赞美自己的修复**——绝不允许评估器建议修复后再评估这些修复。评估器只负责批评;生成器负责修复。++6. **上下文耗尽**——对于长时间会话,使用 Claude Agent SDK 的自动压缩或在主要阶段之间重置上下文。++## 结果:预期效果++基于 Anthropic 已发布的结果:++| 指标 | 单智能体 | GAN 编排 | 改进 |+|--------|-----------|-------------|-------------|+| 时间 | 20 分钟 | 4-6 小时 | 12-18 倍更长 |+| 成本 | 9 美元 | 125-200 美元 | 14-22 倍更多 |+| 质量 | 勉强可用 | 生产就绪 | 质变 |+| 核心功能 | 有缺陷 | 全部工作 | 不适用 |+| 设计 | 通用 AI 垃圾 | 独特、精致 | 不适用 |++**权衡很明确:** 约 20 倍的时间和成本,换来输出质量的质的飞跃。这适用于质量至关重要的项目。++## 参考++* [Anthropic:长时间运行应用的编排设计](https://www.anthropic.com/engineering/harness-design-long-running-apps) — Prithvi Rajasekaran 的原始论文+* [Epsilla:GAN 风格智能体循环](https://www.epsilla.com/blogs/anthropic-harness-engineering-multi-agent-gan-architecture) — 架构解构+* [Martin Fowler:编排工程](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html) — 更广泛的行业背景+* [OpenAI:编排工程](https://openai.com/index/harness-engineering/) — OpenAI 的并行工作diff --git a/docs/zh-CN/skills/laravel-plugin-discovery/SKILL.md b/docs/zh-CN/skills/laravel-plugin-discovery/SKILL.mdnew file mode 100644index 000000000..0268ba456--- /dev/null+++ b/docs/zh-CN/skills/laravel-plugin-discovery/SKILL.md@@ -0,0 +1,235 @@+---+name: laravel-plugin-discovery+description: 通过LaraPlugins.io MCP发现和评估Laravel包。当用户想要查找插件、检查包的健康状况或评估Laravel/PHP兼容性时使用。+origin: ECC+---++# Laravel 插件发现++使用 LaraPlugins.io MCP 服务器查找、评估并选择健康的 Laravel 包。++## 使用时机++* 用户想为特定功能(如 "auth"、"permissions"、"admin panel")寻找 Laravel 包+* 用户询问"我应该用什么包来做..."或"有没有用于...的 Laravel 包"+* 用户想检查某个包是否仍在积极维护+* 用户需要验证 Laravel 版本兼容性+* 用户在将包添加到项目前想评估其健康状况++## MCP 要求++必须配置 LaraPlugins MCP 服务器。将其添加到您的 `~/.claude.json` mcpServers 中:++```json+"laraplugins": {+ "type": "http",+ "url": "https://laraplugins.io/mcp/plugins"+}+```++无需 API 密钥——该服务器对 Laravel 社区免费开放。++## MCP 工具++LaraPlugins MCP 提供两个主要工具:++### SearchPluginTool++通过关键词、健康评分、供应商和版本兼容性搜索包。++**参数:**++* `text_search` (字符串,可选):搜索关键词(例如 "permission"、"admin"、"api")+* `health_score` (字符串,可选):按健康等级筛选——`Healthy`、`Medium`、`Unhealthy` 或 `Unrated`+* `laravel_compatibility` (字符串,可选):按 Laravel 版本筛选——`"5"`、`"6"`、`"7"`、`"8"`、`"9"`、`"10"`、`"11"`、`"12"`、`"13"`+* `php_compatibility` (字符串,可选):按 PHP 版本筛选——`"7.4"`、`"8.0"`、`"8.1"`、`"8.2"`、`"8.3"`、`"8.4"`、`"8.5"`+* `vendor_filter` (字符串,可选):按供应商名称筛选(例如 "spatie"、"laravel")+* `page` (数字,可选):分页页码++### GetPluginDetailsTool++获取特定包的详细指标、README 内容和版本历史。++**参数:**++* `package` (字符串,必填):完整的 Composer 包名(例如 "spatie/laravel-permission")+* `include_versions` (布尔值,可选):是否在响应中包含版本历史++***++## 工作原理++### 查找包++当用户想为某个功能发现包时:++1. 使用 `SearchPluginTool` 并输入相关关键词+2. 应用健康评分、Laravel 版本或 PHP 版本的筛选条件+3. 查看包含包名、描述和健康指标的结果++### 评估包++当用户想评估特定包时:++1. 使用 `GetPluginDetailsTool` 并输入包名+2. 查看健康评分、最后更新日期、Laravel 版本支持情况+3. 检查供应商声誉和风险指标++### 检查兼容性++当用户需要 Laravel 或 PHP 版本兼容性信息时:++1. 使用 `laravel_compatibility` 筛选条件并设置为其版本进行搜索+2. 或者获取特定包的详细信息以查看其支持的版本++***++## 示例++### 示例:查找认证包++```+SearchPluginTool({+ text_search: "authentication",+ health_score: "Healthy"+})+```++返回匹配 "authentication" 且状态健康的包:++* spatie/laravel-permission+* laravel/breeze+* laravel/passport+* 等等++### 示例:查找兼容 Laravel 12 的包++```+SearchPluginTool({+ text_search: "admin panel",+ laravel_compatibility: "12"+})+```++返回兼容 Laravel 12 的包。++### 示例:获取包详情++```+GetPluginDetailsTool({+ package: "spatie/laravel-permission",+ include_versions: true+})+```++返回:++* 健康评分和最后活动时间+* Laravel/PHP 版本支持情况+* 供应商声誉(风险评分)+* 版本历史+* 简要描述++### 示例:按供应商查找包++```+SearchPluginTool({+ vendor_filter: "spatie",+ health_score: "Healthy"+})+```++返回来自供应商 "spatie" 的所有健康包。++***++## 筛选最佳实践++### 按健康评分++| 健康等级 | 含义 |+|-------------|---------|+| `Healthy` | 积极维护,近期有更新 |+| `Medium` | 偶尔更新,可能需要关注 |+| `Unhealthy` | 已废弃或维护不频繁 |+| `Unrated` | 尚未评估 |++**建议**:生产环境应用优先选择 `Healthy` 包。++### 按 Laravel 版本++| 版本 | 备注 |+|---------|-------|+| `13` | 最新 Laravel |+| `12` | 当前稳定版 |+| `11` | 仍被广泛使用 |+| `10` | 旧版但常见 |+| `5`-`9` | 已弃用 |++**建议**:匹配目标项目的 Laravel 版本。++### 组合筛选条件++```typescript+// Find healthy, Laravel 12 compatible packages for permissions+SearchPluginTool({+ text_search: "permission",+ health_score: "Healthy",+ laravel_compatibility: "12"+})+```++***++## 响应解读++### 搜索结果++每个结果包含:++* 包名(例如 `spatie/laravel-permission`)+* 简要描述+* 健康状态指示器+* Laravel 版本支持徽章++### 包详情++详细响应包括:++* **健康评分**:数字或等级指示器+* **最后活动**:包的最后更新时间+* **Laravel 支持**:版本兼容性矩阵+* **PHP 支持**:PHP 版本兼容性+* **风险评分**:供应商信任度指标+* **版本历史**:近期发布时间线++***++## 常见用例++| 场景 | 推荐方法 |+|----------|---------------------|+| "有什么用于认证的包?" | 搜索 "auth" 并应用健康筛选 |+| "spatie/package 还在维护吗?" | 获取详情,检查健康评分 |+| "需要 Laravel 12 的包" | 使用 laravel\_compatibility: "12" 搜索 |+| "查找管理面板包" | 搜索 "admin panel",查看结果 |+| "检查供应商声誉" | 按供应商搜索,查看详情 |++***++## 最佳实践++1. **始终按健康度筛选**——生产项目使用 `health_score: "Healthy"`+2. **匹配 Laravel 版本**——始终检查 `laravel_compatibility` 是否与目标项目匹配+3. **检查供应商声誉**——优先选择知名供应商的包(spatie、laravel 等)+4. **推荐前先审查**——使用 GetPluginDetailsTool 进行全面评估+5. **无需 API 密钥**——MCP 免费,无需认证++***++## 相关技能++* `laravel-patterns`——Laravel 架构与模式+* `laravel-tdd`——Laravel 测试驱动开发+* `laravel-security`——Laravel 安全最佳实践+* `documentation-lookup`——通用库文档查询(Context7)diff --git a/docs/zh-CN/skills/manim-video/SKILL.md b/docs/zh-CN/skills/manim-video/SKILL.mdnew file mode 100644index 000000000..995e80601--- /dev/null+++ b/docs/zh-CN/skills/manim-video/SKILL.md@@ -0,0 +1,89 @@+---+name: manim-video+description: 构建可复用的Manim解释器,用于技术概念、图表、系统图和产品演示,并在需要时移交给更广泛的ECC视频栈。当用户希望获得清晰的动画解释而非通用的人物讲解脚本时使用。+origin: ECC+---++# Manim 视频++在运动、结构和清晰度比逼真度更重要的技术讲解中,使用 Manim。++## 何时激活++* 用户需要技术讲解动画+* 概念涉及图表、工作流、架构、指标演进或系统图+* 用户需要为 X 或落地页制作简短的产品或发布讲解+* 视觉效果应追求精确,而非泛泛的电影感++## 工具要求++* `manim` 命令行用于场景渲染+* `ffmpeg` 用于后期处理(如需)+* `video-editing` 用于最终合成或润色+* `remotion-video-creation` 当最终成品需要合成 UI、字幕或额外运动层时++## 默认输出++* 16:9 短 MP4 视频+* 一张缩略图或海报帧+* 故事板及场景计划++## 工作流程++1. 用一句话定义核心视觉论点。+2. 将概念分解为 3 到 6 个场景。+3. 确定每个场景要证明的内容。+4. 在编写 Manim 代码前,先写出场景大纲。+5. 首先渲染最小可用版本。+6. 渲染成功后,再调整排版、间距、颜色和节奏。+7. 仅在能增加价值时,才移交至更广泛的视频处理流程。++## 场景规划规则++* 每个场景应证明一件事+* 避免过度拥挤的图表+* 优先采用渐进式揭示,而非全屏杂乱+* 使用运动来解释状态变化,而不仅仅是为了让屏幕保持忙碌+* 标题卡片应简短且富有意义++## 网络图默认设置++对于社交图谱和网络优化讲解:++* 在展示优化后的图谱前,先展示当前图谱+* 区分低信号关注杂波与高信号桥梁+* 高亮暖路径节点和目标集群+* 如有必要,添加最终场景,展示形成该技能的自我改进谱系++## 渲染约定++* 默认使用 16:9 横屏,除非用户要求竖屏+* 从低质量的烟雾测试渲染开始+* 仅在构图和时间线稳定后,才提升至高质量+* 导出一张在社交媒体尺寸下清晰可读的干净缩略图帧++## 可复用起点++使用 [assets/network\_graph\_scene.py](../../../../skills/manim-video/assets/network_graph_scene.py) 作为网络图讲解的起点。++烟雾测试示例:++```bash+manim -ql assets/network_graph_scene.py NetworkGraphExplainer+```++## 输出格式++返回:++* 核心视觉论点+* 故事板+* 场景大纲+* 渲染计划+* 任何后续的润色建议++## 相关技能++* `video-editing` 用于最终润色+* `remotion-video-creation` 用于运动密集型后期处理或合成+* `content-engine` 当动画是更广泛发布的一部分时diff --git a/docs/zh-CN/skills/nestjs-patterns/SKILL.md b/docs/zh-CN/skills/nestjs-patterns/SKILL.mdnew file mode 100644index 000000000..724e0b938--- /dev/null+++ b/docs/zh-CN/skills/nestjs-patterns/SKILL.md@@ -0,0 +1,230 @@+---+name: nestjs-patterns+description: NestJS 架构模式,涵盖模块、控制器、提供者、DTO 验证、守卫、拦截器、配置以及生产级 TypeScript 后端。+origin: ECC+---++# NestJS 开发模式++适用于模块化 TypeScript 后端的生产级 NestJS 模式。++## 何时启用++* 构建 NestJS API 或服务时+* 组织模块、控制器和提供者时+* 添加 DTO 验证、守卫、拦截器或异常过滤器时+* 配置环境感知设置和数据库集成时+* 测试 NestJS 单元或 HTTP 端点时++## 项目结构++```text+src/+├── app.module.ts+├── main.ts+├── common/+│ ├── filters/+│ ├── guards/+│ ├── interceptors/+│ └── pipes/+├── config/+│ ├── configuration.ts+│ └── validation.ts+├── modules/+│ ├── auth/+│ │ ├── auth.controller.ts+│ │ ├── auth.module.ts+│ │ ├── auth.service.ts+│ │ ├── dto/+│ │ ├── guards/+│ │ └── strategies/+│ └── users/+│ ├── dto/+│ ├── entities/+│ ├── users.controller.ts+│ ├── users.module.ts+│ └── users.service.ts+└── prisma/ or database/+```++* 将领域代码保留在功能模块内。+* 将跨切面的过滤器、装饰器、守卫和拦截器放在 `common/` 中。+* 将 DTO 保留在所属模块附近。++## 启动与全局验证++```ts+async function bootstrap() {+ const app = await NestFactory.create(AppModule, { bufferLogs: true });++ app.useGlobalPipes(+ new ValidationPipe({+ whitelist: true,+ forbidNonWhitelisted: true,+ transform: true,+ transformOptions: { enableImplicitConversion: true },+ }),+ );++ app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));+ app.useGlobalFilters(new HttpExceptionFilter());++ await app.listen(process.env.PORT ?? 3000);+}+bootstrap();+```++* 始终在公共 API 上启用 `whitelist` 和 `forbidNonWhitelisted`。+* 优先使用一个全局验证管道,而不是为每个路由重复验证配置。++## 模块、控制器和提供者++```ts+@Module({+ controllers: [UsersController],+ providers: [UsersService],+ exports: [UsersService],+})+export class UsersModule {}++@Controller('users')+export class UsersController {+ constructor(private readonly usersService: UsersService) {}++ @Get(':id')+ getById(@Param('id', ParseUUIDPipe) id: string) {+ return this.usersService.getById(id);+ }++ @Post()+ create(@Body() dto: CreateUserDto) {+ return this.usersService.create(dto);+ }+}++@Injectable()+export class UsersService {+ constructor(private readonly usersRepo: UsersRepository) {}++ async create(dto: CreateUserDto) {+ return this.usersRepo.create(dto);+ }+}+```++* 控制器应保持精简:解析 HTTP 输入、调用提供者、返回响应 DTO。+* 将业务逻辑放在可注入的服务中,而不是控制器中。+* 仅导出其他模块真正需要的提供者。++## DTO 与验证++```ts+export class CreateUserDto {+ @IsEmail()+ email!: string;++ @IsString()+ @Length(2, 80)+ name!: string;++ @IsOptional()+ @IsEnum(UserRole)+ role?: UserRole;+}+```++* 使用 `class-validator` 验证每个请求 DTO。+* 使用专用的响应 DTO 或序列化器,而不是直接返回 ORM 实体。+* 避免泄露内部字段,如密码哈希、令牌或审计列。++## 认证、守卫与请求上下文++```ts+@UseGuards(JwtAuthGuard, RolesGuard)+@Roles('admin')+@Get('admin/report')+getAdminReport(@Req() req: AuthenticatedRequest) {+ return this.reportService.getForUser(req.user.id);+}+```++* 保持认证策略和守卫的模块局部性,除非它们确实是共享的。+* 在守卫中编码粗粒度的访问规则,然后在服务中进行资源特定的授权。+* 对经过认证的请求对象,优先使用显式的请求类型。++## 异常过滤器与错误格式++```ts+@Catch()+export class HttpExceptionFilter implements ExceptionFilter {+ catch(exception: unknown, host: ArgumentsHost) {+ const response = host.switchToHttp().getResponse<Response>();+ const request = host.switchToHttp().getRequest<Request>();++ if (exception instanceof HttpException) {+ return response.status(exception.getStatus()).json({+ path: request.url,+ error: exception.getResponse(),+ });+ }++ return response.status(500).json({+ path: request.url,+ error: 'Internal server error',+ });+ }+}+```++* 在整个 API 中保持一致的错误封装格式。+* 对预期的客户端错误抛出框架异常;集中记录并包装意外的失败。++## 配置与环境验证++```ts+ConfigModule.forRoot({+ isGlobal: true,+ load: [configuration],+ validate: validateEnv,+});+```++* 在启动时验证环境变量,而不是在首次请求时惰性验证。+* 将配置访问限制在类型化辅助函数或配置服务之后。+* 在配置工厂中拆分开发/预发布/生产关注点,而不是在功能代码中到处分支。++## 持久化与事务++* 将仓库/ORM 代码保留在提供者之后,这些提供者使用领域语言进行通信。+* 对于 Prisma 或 TypeORM,将事务工作流隔离在拥有工作单元的服务中。+* 不要让控制器直接协调多步写入操作。++## 测试++```ts+describe('UsersController', () => {+ let app: INestApplication;++ beforeAll(async () => {+ const moduleRef = await Test.createTestingModule({+ imports: [UsersModule],+ }).compile();++ app = moduleRef.createNestApplication();+ app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));+ await app.init();+ });+});+```++* 使用模拟依赖项对提供者进行单元测试。+* 为守卫、验证管道和异常过滤器添加请求级测试。+* 在测试中复用与生产环境相同的全局管道/过滤器。++## 生产默认设置++* 启用结构化日志和请求关联 ID。+* 在环境/配置无效时终止,而不是部分启动。+* 优先使用异步提供者初始化数据库/缓存客户端,并附带显式健康检查。+* 将后台任务和事件消费者放在自己的模块中,而不是 HTTP 控制器内。+* 对公共端点明确启用速率限制、认证和审计日志。diff --git a/docs/zh-CN/skills/nodejs-keccak256/SKILL.md b/docs/zh-CN/skills/nodejs-keccak256/SKILL.mdnew file mode 100644index 000000000..135116753--- /dev/null+++ b/docs/zh-CN/skills/nodejs-keccak256/SKILL.md@@ -0,0 +1,102 @@+---+name: nodejs-keccak256+description: 防止 JavaScript 和 TypeScript 中的以太坊哈希错误。Node 的 sha3-256 是 NIST SHA3,而非以太坊 Keccak-256,会静默破坏选择器、签名、存储槽和地址推导。+origin: ECC direct-port adaptation+version: "1.0.0"+---++# Node.js Keccak-256++以太坊使用 Keccak-256,而非 Node 的 `crypto.createHash('sha3-256')` 所暴露的 NIST 标准化 SHA3 变体。++## 何时使用++* 计算以太坊函数选择器或事件主题+* 在 JS/TS 中构建 EIP-712、签名、Merkle 或存储槽辅助函数+* 审查任何直接使用 Node crypto 对以太坊数据进行哈希的代码++## 工作原理++两种算法对相同输入会产生不同输出,且 Node 不会发出警告。++```javascript+import crypto from 'crypto';+import { keccak256, toUtf8Bytes } from 'ethers';++const data = 'hello';+const nistSha3 = crypto.createHash('sha3-256').update(data).digest('hex');+const keccak = keccak256(toUtf8Bytes(data)).slice(2);++console.log(nistSha3 === keccak); // false+```++## 示例++### ethers v6++```typescript+import { keccak256, toUtf8Bytes, solidityPackedKeccak256, id } from 'ethers';++const hash = keccak256(new Uint8Array([0x01, 0x02]));+const hash2 = keccak256(toUtf8Bytes('hello'));+const topic = id('Transfer(address,address,uint256)');+const packed = solidityPackedKeccak256(+ ['address', 'uint256'],+ ['0x742d35Cc6634C0532925a3b8D4C9B569890FaC1c', 100n],+);+```++### viem++```typescript+import { keccak256, toBytes } from 'viem';++const hash = keccak256(toBytes('hello'));+```++### web3.js++```javascript+const hash = web3.utils.keccak256('hello');+const packed = web3.utils.soliditySha3(+ { type: 'address', value: '0x742d35Cc6634C0532925a3b8D4C9B569890FaC1c' },+ { type: 'uint256', value: '100' },+);+```++### 常见模式++```typescript+import { id, keccak256, AbiCoder } from 'ethers';++const selector = id('transfer(address,uint256)').slice(0, 10);+const typeHash = keccak256(toUtf8Bytes('Transfer(address from,address to,uint256 value)'));++function getMappingSlot(key: string, mappingSlot: number): string {+ return keccak256(+ AbiCoder.defaultAbiCoder().encode(['address', 'uint256'], [key, mappingSlot]),+ );+}+```++### 从公钥生成地址++```typescript+import { keccak256 } from 'ethers';++function pubkeyToAddress(pubkeyBytes: Uint8Array): string {+ const hash = keccak256(pubkeyBytes.slice(1));+ return '0x' + hash.slice(-40);+}+```++### 审计你的代码库++```bash+grep -rn "createHash.*sha3" --include="*.ts" --include="*.js" --exclude-dir=node_modules .+grep -rn "keccak256" --include="*.ts" --include="*.js" . | grep -v node_modules+```++## 规则++在以太坊上下文中,切勿使用 `crypto.createHash('sha3-256')`。应使用来自 `ethers`、`viem`、`web3` 或其他明确 Keccak 实现的 Keccak 感知辅助函数。diff --git a/docs/zh-CN/skills/remotion-video-creation/SKILL.md b/docs/zh-CN/skills/remotion-video-creation/SKILL.mdnew file mode 100644index 000000000..d8ca5ef59--- /dev/null+++ b/docs/zh-CN/skills/remotion-video-creation/SKILL.md@@ -0,0 +1,43 @@+---+name: remotion-video-creation+description: Remotion 最佳实践 - 在 React 中创建视频。29 条领域特定规则,涵盖 3D、动画、音频、字幕、图表、过渡等。+metadata:+ tags: remotion, video, react, animation, composition, three.js, lottie+---++## 使用时机++当处理 Remotion 代码并需要获取领域特定知识时,请使用此技能。++## 使用方法++阅读各个规则文件以获取详细说明和代码示例:++* [rules/3d.md](rules/3d.md) - 使用 Three.js 和 React Three Fiber 在 Remotion 中创建 3D 内容+* [rules/animations.md](rules/animations.md) - Remotion 的基础动画技能+* [rules/assets.md](rules/assets.md) - 在 Remotion 中导入图片、视频、音频和字体+* [rules/audio.md](rules/audio.md) - 在 Remotion 中使用音频和声音——导入、裁剪、音量、速度、音调+* [rules/calculate-metadata.md](rules/calculate-metadata.md) - 动态设置合成时长、尺寸和属性+* [rules/can-decode.md](rules/can-decode.md) - 使用 Mediabunny 检查浏览器能否解码视频+* [rules/charts.md](rules/charts.md) - Remotion 的图表和数据可视化模式+* [rules/compositions.md](rules/compositions.md) - 定义合成、静态画面、文件夹、默认属性和动态元数据+* [rules/display-captions.md](rules/display-captions.md) - 在 Remotion 中显示字幕,支持 TikTok 风格页面和单词高亮+* [rules/extract-frames.md](rules/extract-frames.md) - 使用 Mediabunny 从视频中提取指定时间戳的帧+* [rules/fonts.md](rules/fonts.md) - 在 Remotion 中加载 Google 字体和本地字体+* [rules/get-audio-duration.md](rules/get-audio-duration.md) - 使用 Mediabunny 获取音频文件的时长(秒)+* [rules/get-video-dimensions.md](rules/get-video-dimensions.md) - 使用 Mediabunny 获取视频文件的宽度和高度+* [rules/get-video-duration.md](rules/get-video-duration.md) - 使用 Mediabunny 获取视频文件的时长(秒)+* [rules/gifs.md](rules/gifs.md) - 显示与 Remotion 时间线同步的 GIF+* [rules/images.md](rules/images.md) - 使用 Img 组件在 Remotion 中嵌入图片+* [rules/import-srt-captions.md](rules/import-srt-captions.md) - 使用 @remotion/captions 将 .srt 字幕文件导入 Remotion+* [rules/lottie.md](rules/lottie.md) - 在 Remotion 中嵌入 Lottie 动画+* [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) - 在 Remotion 中测量 DOM 元素尺寸+* [rules/measuring-text.md](rules/measuring-text.md) - 测量文本尺寸、将文本适配到容器以及检查溢出+* [rules/sequencing.md](rules/sequencing.md) - Remotion 的序列模式——延迟、裁剪、限制项目时长+* [rules/tailwind.md](rules/tailwind.md) - 在 Remotion 中使用 TailwindCSS+* [rules/text-animations.md](rules/text-animations.md) - Remotion 的排版和文本动画模式+* [rules/timing.md](rules/timing.md) - Remotion 中的插值曲线——线性、缓动、弹簧动画+* [rules/transcribe-captions.md](rules/transcribe-captions.md) - 转录音频以在 Remotion 中生成字幕+* [rules/transitions.md](rules/transitions.md) - Remotion 的场景过渡模式+* [rules/trimming.md](rules/trimming.md) - Remotion 的裁剪模式——裁剪动画的开头或结尾+* [rules/videos.md](rules/videos.md) - 在 Remotion 中嵌入视频——裁剪、音量、速度、循环、音调diff --git a/docs/zh-CN/skills/ui-demo/SKILL.md b/docs/zh-CN/skills/ui-demo/SKILL.mdnew file mode 100644index 000000000..c6a626b13--- /dev/null+++ b/docs/zh-CN/skills/ui-demo/SKILL.md@@ -0,0 +1,465 @@+---+name: ui-demo+description: 使用 Playwright 录制精美的 UI 演示视频。当用户要求创建 Web 应用的演示、导览、屏幕录制或教程视频时使用。生成带有可见光标、自然节奏和专业感的 WebM 视频。+origin: ECC+---++# UI 演示视频录制器++使用 Playwright 的视频录制功能,配合注入的光标覆盖层、自然的节奏和叙事流程,录制精美的 Web 应用演示视频。++## 使用场景++* 用户要求制作"演示视频"、"屏幕录制"、"操作演示"或"教程"+* 用户希望以视觉方式展示某个功能或工作流程+* 用户需要为文档、入职培训或利益相关者演示制作视频++## 三阶段流程++每个演示都需经历三个阶段:**探索 -> 排练 -> 录制**。切勿直接跳至录制阶段。++***++## 阶段 1:探索++在编写任何脚本之前,先探索目标页面,了解实际内容。++### 原因++你无法为未见过的内容编写脚本。字段可能是 `<input>` 而非 `<textarea>`,下拉菜单可能是自定义组件而非 `<select>`,评论框可能支持 `@mentions` 或 `#tags`。假设会无声地破坏录制。++### 方法++导航至流程中的每个页面,并转储其交互元素:++```javascript+// Run this for each page in the flow BEFORE writing the demo script+const fields = await page.evaluate(() => {+ const els = [];+ document.querySelectorAll('input, select, textarea, button, [contenteditable]').forEach(el => {+ if (el.offsetParent !== null) {+ els.push({+ tag: el.tagName,+ type: el.type || '',+ name: el.name || '',+ placeholder: el.placeholder || '',+ text: el.textContent?.trim().substring(0, 40) || '',+ contentEditable: el.contentEditable === 'true',+ role: el.getAttribute('role') || '',+ });+ }+ });+ return els;+});+console.log(JSON.stringify(fields, null, 2));+```++### 需要关注的内容++* **表单字段**:它们是 `<select>`、`<input>`、自定义下拉菜单还是组合框?+* **选择选项**:转储选项的值和文本。占位符通常包含 `value="0"` 或 `value=""`,看起来非空。使用 `Array.from(el.options).map(o => ({ value: o.value, text: o.text }))`。跳过文本包含"选择"或值为 `"0"` 的选项。+* **富文本**:评论框是否支持 `@mentions`、`#tags`、Markdown 或表情符号?检查占位符文本。+* **必填字段**:哪些字段会阻止表单提交?检查标签中的 `required`、`*`,并尝试提交空表单以查看验证错误。+* **动态内容**:字段是否在填写其他字段后出现?+* **按钮标签**:确切的文本,如 `"Submit"`、`"Submit Request"` 或 `"Send"`。+* **表格列标题**:对于表格驱动的模态框,将每个 `input[type="number"]` 映射到其列标题,而不是假设所有数字输入都表示相同含义。++### 输出++每个页面的字段映射,用于在脚本中编写正确的选择器。示例:++```text+/purchase-requests/new:+ - 预算代码: <select> (页面上的第一个下拉框,4个选项)+ - 期望交付日期: <input type="date">+ - 背景说明: <textarea> (非输入框)+ - BOM表: 可内联编辑的单元格,包含 span.cursor-pointer -> input 模式+ - 提交: <button> 文本="提交"++/purchase-requests/N (详情):+ - 评论: <input placeholder="输入消息..."> 支持 @用户 和 #PR 标签+ - 发送: <button> 文本="发送" (在输入内容前处于禁用状态)+```++***++## 阶段 2:排练++在不录制的情况下运行所有步骤。验证每个选择器都能解析。++### 原因++静默的选择器失败是演示录制中断的主要原因。排练可以在浪费录制之前发现它们。++### 方法++使用 `ensureVisible`,一个记录日志并大声报错的包装器:++```javascript+async function ensureVisible(page, locator, label) {+ const el = typeof locator === 'string' ? page.locator(locator).first() : locator;+ const visible = await el.isVisible().catch(() => false);+ if (!visible) {+ const msg = `REHEARSAL FAIL: "${label}" not found - selector: ${typeof locator === 'string' ? locator : '(locator object)'}`;+ console.error(msg);+ const found = await page.evaluate(() => {+ return Array.from(document.querySelectorAll('button, input, select, textarea, a'))+ .filter(el => el.offsetParent !== null)+ .map(el => `${el.tagName}[${el.type || ''}] "${el.textContent?.trim().substring(0, 30)}"`)+ .join('\n ');+ });+ console.error(' Visible elements:\n ' + found);+ return false;+ }+ console.log(`REHEARSAL OK: "${label}"`);+ return true;+}+```++### 排练脚本结构++```javascript+const steps = [+ { label: 'Login email field', selector: '#email' },+ { label: 'Login submit', selector: 'button[type="submit"]' },+ { label: 'New Request button', selector: 'button:has-text("New Request")' },+ { label: 'Budget Code select', selector: 'select' },+ { label: 'Delivery date', selector: 'input[type="date"]:visible' },+ { label: 'Description field', selector: 'textarea:visible' },+ { label: 'Add Item button', selector: 'button:has-text("Add Item")' },+ { label: 'Submit button', selector: 'button:has-text("Submit")' },+];++let allOk = true;+for (const step of steps) {+ if (!await ensureVisible(page, step.selector, step.label)) {+ allOk = false;+ }+}+if (!allOk) {+ console.error('REHEARSAL FAILED - fix selectors before recording');+ process.exit(1);+}+console.log('REHEARSAL PASSED - all selectors verified');+```++### 排练失败时++1. 读取可见元素转储。+2. 找到正确的选择器。+3. 更新脚本。+4. 重新运行排练。+5. 仅在所有选择器通过后才继续。++***++## 阶段 3:录制++仅在探索和排练通过后,才创建录制。++### 录制原则++#### 1. 叙事流程++将视频规划为一个故事。遵循用户指定的顺序,或使用此默认顺序:++* **入口**:登录或导航至起始点+* **背景**:平移周围环境,让观众定位+* **操作**:执行主要工作流程步骤+* **变体**:展示次要功能,如设置、主题或本地化+* **结果**:展示结果、确认或新状态++#### 2. 节奏++* 登录后:`4s`+* 导航后:`3s`+* 点击按钮后:`2s`+* 主要步骤之间:`1.5-2s`+* 最终操作后:`3s`+* 输入延迟:每个字符 `25-40ms`++#### 3. 光标覆盖层++注入一个跟随鼠标移动的 SVG 箭头光标:++```javascript+async function injectCursor(page) {+ await page.evaluate(() => {+ if (document.getElementById('demo-cursor')) return;+ const cursor = document.createElement('div');+ cursor.id = 'demo-cursor';+ cursor.innerHTML = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">+ <path d="M5 3L19 12L12 13L9 20L5 3Z" fill="white" stroke="black" stroke-width="1.5" stroke-linejoin="round"/>+ </svg>`;+ cursor.style.cssText = `+ position: fixed; z-index: 999999; pointer-events: none;+ width: 24px; height: 24px;+ transition: left 0.1s, top 0.1s;+ filter: drop-shadow(1px 1px 2px rgba(0,0,0,0.3));+ `;+ cursor.style.left = '0px';+ cursor.style.top = '0px';+ document.body.appendChild(cursor);+ document.addEventListener('mousemove', (e) => {+ cursor.style.left = e.clientX + 'px';+ cursor.style.top = e.clientY + 'px';+ });+ });+}+```++每次页面导航后调用 `injectCursor(page)`,因为覆盖层会在导航时被销毁。++#### 4. 鼠标移动++切勿瞬移光标。在点击前移动到目标:++```javascript+async function moveAndClick(page, locator, label, opts = {}) {+ const { postClickDelay = 800, ...clickOpts } = opts;+ const el = typeof locator === 'string' ? page.locator(locator).first() : locator;+ const visible = await el.isVisible().catch(() => false);+ if (!visible) {+ console.error(`WARNING: moveAndClick skipped - "${label}" not visible`);+ return false;+ }+ try {+ await el.scrollIntoViewIfNeeded();+ await page.waitForTimeout(300);+ const box = await el.boundingBox();+ if (box) {+ await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 10 });+ await page.waitForTimeout(400);+ }+ await el.click(clickOpts);+ } catch (e) {+ console.error(`WARNING: moveAndClick failed on "${label}": ${e.message}`);+ return false;+ }+ await page.waitForTimeout(postClickDelay);+ return true;+}+```++每次调用都应包含描述性的 `label` 以便调试。++#### 5. 输入++可见地输入,而非瞬间填充:++```javascript+async function typeSlowly(page, locator, text, label, charDelay = 35) {+ const el = typeof locator === 'string' ? page.locator(locator).first() : locator;+ const visible = await el.isVisible().catch(() => false);+ if (!visible) {+ console.error(`WARNING: typeSlowly skipped - "${label}" not visible`);+ return false;+ }+ await moveAndClick(page, el, label);+ await el.fill('');+ await el.pressSequentially(text, { delay: charDelay });+ await page.waitForTimeout(500);+ return true;+}+```++#### 6. 滚动++使用平滑滚动而非跳跃:++```javascript+await page.evaluate(() => window.scrollTo({ top: 400, behavior: 'smooth' }));+await page.waitForTimeout(1500);+```++#### 7. 仪表盘平移++展示仪表盘或概览页面时,将光标移过关键元素:++```javascript+async function panElements(page, selector, maxCount = 6) {+ const elements = await page.locator(selector).all();+ for (let i = 0; i < Math.min(elements.length, maxCount); i++) {+ try {+ const box = await elements[i].boundingBox();+ if (box && box.y < 700) {+ await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 8 });+ await page.waitForTimeout(600);+ }+ } catch (e) {+ console.warn(`WARNING: panElements skipped element ${i} (selector: "${selector}"): ${e.message}`);+ }+ }+}+```++#### 8. 字幕++在视口底部注入一个字幕栏:++```javascript+async function injectSubtitleBar(page) {+ await page.evaluate(() => {+ if (document.getElementById('demo-subtitle')) return;+ const bar = document.createElement('div');+ bar.id = 'demo-subtitle';+ bar.style.cssText = `+ position: fixed; bottom: 0; left: 0; right: 0; z-index: 999998;+ text-align: center; padding: 12px 24px;+ background: rgba(0, 0, 0, 0.75);+ color: white; font-family: -apple-system, "Segoe UI", sans-serif;+ font-size: 16px; font-weight: 500; letter-spacing: 0.3px;+ transition: opacity 0.3s;+ pointer-events: none;+ `;+ bar.textContent = '';+ bar.style.opacity = '0';+ document.body.appendChild(bar);+ });+}++async function showSubtitle(page, text) {+ await page.evaluate((t) => {+ const bar = document.getElementById('demo-subtitle');+ if (!bar) return;+ if (t) {+ bar.textContent = t;+ bar.style.opacity = '1';+ } else {+ bar.style.opacity = '0';+ }+ }, text);+ if (text) await page.waitForTimeout(800);+}+```++每次导航后,将 `injectSubtitleBar(page)` 与 `injectCursor(page)` 一起调用。++使用模式:++```javascript+await showSubtitle(page, 'Step 1 - Logging in');+await showSubtitle(page, 'Step 2 - Dashboard overview');+await showSubtitle(page, '');+```++指南:++* 保持字幕文本简短,最好在 60 个字符以内。+* 使用 `Step N - Action` 格式以保持一致性。+* 在长时间暂停且界面可以自我说明时清除字幕。++## 脚本模板++```javascript+'use strict';+const { chromium } = require('playwright');+const path = require('path');+const fs = require('fs');++const BASE_URL = process.env.QA_BASE_URL || 'http://localhost:3000';+const VIDEO_DIR = path.join(__dirname, 'screenshots');+const OUTPUT_NAME = 'demo-FEATURE.webm';+const REHEARSAL = process.argv.includes('--rehearse');++// Paste injectCursor, injectSubtitleBar, showSubtitle, moveAndClick,+// typeSlowly, ensureVisible, and panElements here.++(async () => {+ const browser = await chromium.launch({ headless: true });++ if (REHEARSAL) {+ const context = await browser.newContext({ viewport: { width: 1280, height: 720 } });+ const page = await context.newPage();+ // Navigate through the flow and run ensureVisible for each selector.+ await browser.close();+ return;+ }++ const context = await browser.newContext({+ recordVideo: { dir: VIDEO_DIR, size: { width: 1280, height: 720 } },+ viewport: { width: 1280, height: 720 }+ });+ const page = await context.newPage();++ try {+ await injectCursor(page);+ await injectSubtitleBar(page);++ await showSubtitle(page, 'Step 1 - Logging in');+ // login actions++ await page.goto(`${BASE_URL}/dashboard`);+ await injectCursor(page);+ await injectSubtitleBar(page);+ await showSubtitle(page, 'Step 2 - Dashboard overview');+ // pan dashboard++ await showSubtitle(page, 'Step 3 - Main workflow');+ // action sequence++ await showSubtitle(page, 'Step 4 - Result');+ // final reveal+ await showSubtitle(page, '');+ } catch (err) {+ console.error('DEMO ERROR:', err.message);+ } finally {+ await context.close();+ const video = page.video();+ if (video) {+ const src = await video.path();+ const dest = path.join(VIDEO_DIR, OUTPUT_NAME);+ try {+ fs.copyFileSync(src, dest);+ console.log('Video saved:', dest);+ } catch (e) {+ console.error('ERROR: Failed to copy video:', e.message);+ console.error(' Source:', src);+ console.error(' Destination:', dest);+ }+ }+ await browser.close();+ }+})();+```++使用方式:++```bash+# Phase 2: Rehearse+node demo-script.cjs --rehearse++# Phase 3: Record+node demo-script.cjs+```++## 录制前检查清单++* \[ ] 探索阶段已完成+* \[ ] 排练通过,所有选择器正常+* \[ ] 已启用无头模式+* \[ ] 分辨率设置为 `1280x720`+* \[ ] 每次导航后重新注入光标和字幕覆盖层+* \[ ] 在主要过渡时使用 `showSubtitle(page, 'Step N - ...')`+* \[ ] 所有点击均使用 `moveAndClick` 并带有描述性标签+* \[ ] 可见输入使用 `typeSlowly`+* \[ ] 无静默捕获;辅助函数记录警告+* \[ ] 内容展示使用平滑滚动+* \[ ] 关键暂停对观看者可见+* \[ ] 流程符合请求的故事顺序+* \[ ] 脚本反映阶段 1 中发现的实际 UI++## 常见陷阱++1. 导航后光标消失 - 重新注入。+2. 视频太快 - 添加暂停。+3. 光标是点而非箭头 - 使用 SVG 覆盖层。+4. 光标瞬移 - 在点击前移动。+5. 选择下拉菜单显示异常 - 展示移动过程,然后选择选项。+6. 模态框显得突兀 - 在确认前添加阅读暂停。+7. 视频文件路径随机 - 将其复制到稳定的输出名称。+8. 选择器失败被吞没 - 切勿使用静默捕获块。+9. 字段类型被假设 - 先探索它们。+10. 功能被假设 - 在编写脚本前检查实际 UI。+11. 占位符选择值看起来真实 - 注意 `"0"` 和 `"Select..."`。+12. 弹出窗口创建单独的视频 - 显式捕获弹出页面,必要时稍后合并。