mta-mcp 1.0.0

package/standards/core/dart-base.md

@@ -0,0 +1,572 @@
+# Dart 基础规范
+
+> 基于 [Effective Dart](https://dart.dev/effective-dart) 和 Flutter 官方最佳实践
+
+## 核心原则
+
+1. **类型安全优先** - 充分利用 Dart 的类型系统和空安全特性
+2. **简洁清晰** - 代码应当简洁但不失可读性
+3. **函数式风格** - 优先使用函数式和声明式编程模式
+4. **不可变性** - 优先使用不可变数据结构
+5. **测试优先** - 编写可测试的代码
+
+## 类型系统
+
+### 空安全 (Null Safety)
+
+```dart
+// ✅ 好 - 充分利用空安全
+String? nullableString;
+String nonNullableString = 'Hello';
+
+// 使用 null 检查
+if (nullableString != null) {
+  print(nullableString.length);
+}
+
+// 使用 null-aware 操作符
+final length = nullableString?.length ?? 0;
+
+// ❌ 坏 - 避免使用 ! 除非确定非空
+final length = nullableString!.length; // 危险!
+```
+
+### 类型推断
+
+```dart
+// ✅ 好 - 让 Dart 推断明显的类型
+var name = 'John';
+var count = 42;
+final items = <String>[];
+
+// ✅ 好 - 显式声明不明显的类型
+String? getUserName() => null;
+final String? username = getUserName();
+
+// ❌ 坏 - 过度类型标注
+String name = 'John'; // 不必要
+```
+
+### 泛型
+
+```dart
+// ✅ 好 - 使用泛型保证类型安全
+class Box<T> {
+  final T value;
+  Box(this.value);
+}
+
+final stringBox = Box<String>('Hello');
+
+// 泛型方法
+T first<T>(List<T> items) => items.first;
+
+// ❌ 坏 - 避免使用 dynamic
+class Box {
+  final dynamic value; // 失去类型安全
+  Box(this.value);
+}
+```
+
+## 函数与方法
+
+### 函数定义
+
+```dart
+// ✅ 好 - 清晰的参数和返回类型
+int add(int a, int b) => a + b;
+
+// 命名参数
+String greet({
+  required String name,
+  String title = '',
+}) {
+  return title.isEmpty ? name : '$title $name';
+}
+
+// 可选位置参数
+String formatDate(DateTime date, [String format = 'yyyy-MM-dd']) {
+  // 实现
+}
+```
+
+### 异步编程
+
+```dart
+// ✅ 好 - 正确使用 async/await
+Future<User?> fetchUser(String id) async {
+  try {
+    final response = await http.get(Uri.parse('/api/users/$id'));
+    if (response.statusCode == 200) {
+      return User.fromJson(jsonDecode(response.body));
+    }
+    return null;
+  } catch (e) {
+    print('Error fetching user: $e');
+    return null;
+  }
+}
+
+// ✅ 好 - 使用 Stream 处理事件序列
+Stream<int> countStream(int max) async* {
+  for (var i = 0; i < max; i++) {
+    await Future.delayed(Duration(seconds: 1));
+    yield i;
+  }
+}
+
+// ❌ 坏 - 忘记 await
+Future<void> saveUser(User user) async {
+  database.save(user); // 忘记 await!
+}
+```
+
+### 箭头函数
+
+```dart
+// ✅ 好 - 单行函数使用箭头语法
+int square(int x) => x * x;
+bool get isValid => value > 0 && value < 100;
+
+// ✅ 好 - 复杂逻辑使用函数体
+String formatName(String first, String last) {
+  final firstName = first.trim();
+  final lastName = last.trim();
+  return '$lastName, $firstName';
+}
+
+// ❌ 坏 - 过度复杂的箭头函数
+String formatName(String first, String last) => 
+  '${last.trim()}, ${first.trim().toUpperCase()}'; // 难以阅读
+```
+
+## 类与对象
+
+### 类定义
+
+```dart
+// ✅ 好 - 清晰的类结构
+class User {
+  // 1. 构造函数首先
+  User({
+    required this.id,
+    required this.name,
+    this.email,
+  });
+  
+  // 2. 命名构造函数
+  User.guest() : id = 0, name = 'Guest', email = null;
+  
+  // 3. 字段
+  final int id;
+  final String name;
+  final String? email;
+  
+  // 4. Getters
+  bool get hasEmail => email != null;
+  
+  // 5. 方法
+  Map<String, dynamic> toJson() => {
+    'id': id,
+    'name': name,
+    'email': email,
+  };
+  
+  // 6. 重写方法
+  @override
+  String toString() => 'User($id: $name)';
+  
+  @override
+  bool operator ==(Object other) =>
+    identical(this, other) ||
+    other is User && 
+    runtimeType == other.runtimeType &&
+    id == other.id;
+  
+  @override
+  int get hashCode => id.hashCode;
+}
+```
+
+### 不可变类
+
+```dart
+// ✅ 好 - 使用不可变数据
+class Point {
+  const Point(this.x, this.y);
+  
+  final double x;
+  final double y;
+  
+  // 返回新实例而不是修改
+  Point translate(double dx, double dy) => 
+    Point(x + dx, y + dy);
+}
+
+// ❌ 坏 - 可变状态
+class Point {
+  Point(this.x, this.y);
+  
+  double x;
+  double y;
+  
+  void translate(double dx, double dy) {
+    x += dx;
+    y += dy;
+  }
+}
+```
+
+## 模式匹配
+
+### Switch 表达式和语句
+
+```dart
+// ✅ 好 - 使用 switch 表达式
+String getStatusMessage(Status status) => switch (status) {
+  Status.pending => '等待中',
+  Status.running => '运行中',
+  Status.completed => '已完成',
+  Status.failed => '失败',
+};
+
+// ✅ 好 - 模式匹配
+String describe(Object obj) => switch (obj) {
+  int() => '整数',
+  String() => '字符串',
+  List<int>() => '整数列表',
+  _ => '其他类型',
+};
+
+// ✅ 好 - 解构
+void processUser(User user) {
+  final User(:name, :email) = user;
+  print('$name: ${email ?? "无邮箱"}');
+}
+```
+
+### Records (记录类型)
+
+```dart
+// ✅ 好 - 使用 Record 返回多个值
+(int, String) getUserInfo() => (42, 'John');
+
+// 命名字段
+({int age, String name}) getDetailedUserInfo() => 
+  (age: 42, name: 'John');
+
+// 解构使用
+final (age, name) = getUserInfo();
+final (:age, :name) = getDetailedUserInfo();
+
+// ❌ 坏 - 为简单返回定义完整的类
+class UserInfo {
+  final int age;
+  final String name;
+  UserInfo(this.age, this.name);
+}
+```
+
+## 集合
+
+### 列表操作
+
+```dart
+// ✅ 好 - 使用函数式方法
+final numbers = [1, 2, 3, 4, 5];
+
+final doubled = numbers.map((n) => n * 2).toList();
+final evens = numbers.where((n) => n.isEven).toList();
+final sum = numbers.reduce((a, b) => a + b);
+
+// ✅ 好 - 集合字面量
+final names = <String>['Alice', 'Bob'];
+final scores = <String, int>{'Alice': 90, 'Bob': 85};
+final uniqueIds = <int>{1, 2, 3};
+
+// ✅ 好 - 集合 if 和 for
+final items = [
+  'Home',
+  if (isLoggedIn) 'Profile',
+  if (isAdmin) 'Admin Panel',
+  for (var category in categories) category.name,
+];
+```
+
+### Spread 操作符
+
+```dart
+// ✅ 好 - 使用 spread 操作符
+final first = [1, 2, 3];
+final second = [4, 5, 6];
+final combined = [...first, ...second];
+
+// null-aware spread
+final List<int>? optional = null;
+final result = [...first, ...?optional]; // [1, 2, 3]
+```
+
+## 错误处理
+
+### 异常处理
+
+```dart
+// ✅ 好 - 具体的异常类型
+class ValidationException implements Exception {
+  final String message;
+  ValidationException(this.message);
+  
+  @override
+  String toString() => 'ValidationException: $message';
+}
+
+// ✅ 好 - 适当的 try-catch
+Future<void> processData(String data) async {
+  try {
+    final parsed = jsonDecode(data);
+    await saveToDatabase(parsed);
+  } on FormatException catch (e) {
+    print('Invalid JSON format: $e');
+    rethrow;
+  } on DatabaseException catch (e, stackTrace) {
+    print('Database error: $e');
+    print(stackTrace);
+    throw ProcessingException('Failed to save data');
+  } finally {
+    cleanup();
+  }
+}
+
+// ❌ 坏 - 捕获所有异常却不处理
+try {
+  dangerousOperation();
+} catch (e) {
+  // 空的 catch 块 - 隐藏错误!
+}
+```
+
+## 命名规范
+
+### 标识符命名
+
+```dart
+// ✅ 好 - 清晰的命名
+class UserProfile {}           // UpperCamelCase 类名
+void fetchUserData() {}        // lowerCamelCase 函数/方法
+const maxRetryCount = 3;       // lowerCamelCase 常量
+enum NetworkStatus {}          // UpperCamelCase 枚举
+final _privateField = 0;       // 下划线开头表示私有
+
+// 文件名使用 snake_case
+// user_profile.dart
+// network_service.dart
+
+// ❌ 坏 - 不清晰的命名
+class UP {}                    // 缩写不清晰
+void fetchUD() {}              // 缩写不清晰
+const MAX_RETRY = 3;           // Dart 不使用 SCREAMING_CAPS
+```
+
+### 布尔值命名
+
+```dart
+// ✅ 好 - 使用 is/has/can 等前缀
+bool isValid;
+bool hasPermission;
+bool canEdit;
+bool shouldRetry;
+
+// ❌ 坏
+bool valid;       // 不够清晰
+bool permission;  // 听起来不像布尔值
+```
+
+## 断言和调试
+
+### 使用 assert
+
+```dart
+// ✅ 好 - 使用 assert 验证不变量
+class Rectangle {
+  Rectangle(this.width, this.height)
+    : assert(width > 0, 'Width must be positive'),
+      assert(height > 0, 'Height must be positive');
+  
+  final double width;
+  final double height;
+  
+  double get area {
+    assert(!width.isNaN && !height.isNaN);
+    return width * height;
+  }
+}
+
+// ✅ 好 - 调试时的断言
+void processItems(List<Item> items) {
+  assert(() {
+    // 复杂的验证逻辑,仅在 debug 模式运行
+    for (final item in items) {
+      if (!item.isValid) {
+        print('Invalid item found: $item');
+        return false;
+      }
+    }
+    return true;
+  }());
+  
+  // 处理逻辑...
+}
+```
+
+## 文档注释
+
+### DartDoc 风格
+
+```dart
+/// 计算两个数的和。
+///
+/// 接受两个整数参数 [a] 和 [b],返回它们的和。
+///
+/// 示例:
+/// ```dart
+/// final result = add(2, 3);
+/// print(result); // 输出: 5
+/// ```
+int add(int a, int b) => a + b;
+
+/// 表示应用程序中的用户。
+///
+/// [User] 是不可变的,包含用户的基本信息。
+/// 使用 [User.guest] 创建访客用户。
+///
+/// 另见:
+/// * [UserProfile] - 用户的详细资料
+/// * [UserRepository] - 用户数据访问
+class User {
+  /// 创建新用户实例。
+  ///
+  /// [id] 和 [name] 是必需的。
+  /// [email] 是可选的。
+  User({
+    required this.id,
+    required this.name,
+    this.email,
+  });
+  
+  /// 用户的唯一标识符。
+  final int id;
+  
+  /// 用户的显示名称。
+  final String name;
+  
+  /// 用户的电子邮件地址(可选)。
+  final String? email;
+}
+```
+
+## 避免的模式
+
+### ❌ 避免使用 dynamic
+
+```dart
+// ❌ 坏 - 失去类型安全
+dynamic data = fetchData();
+print(data.length); // 运行时才知道是否出错
+
+// ✅ 好 - 使用具体类型或泛型
+Object data = fetchData();
+if (data is String) {
+  print(data.length);
+}
+```
+
+### ❌ 避免过度使用 extension
+
+```dart
+// ❌ 坏 - 不必要的 extension
+extension StringExtension on String {
+  String capitalize() => this[0].toUpperCase() + substring(1);
+}
+
+// ✅ 好 - 使用普通函数
+String capitalize(String str) => 
+  str[0].toUpperCase() + str.substring(1);
+```
+
+### ❌ 避免 part/part of
+
+```dart
+// ❌ 坏 - 避免使用 part/part of
+// file1.dart
+part of 'main.dart';
+
+// ✅ 好 - 使用 import/export
+// file1.dart
+class MyClass {}
+
+// main.dart
+import 'file1.dart';
+```
+
+## 性能建议
+
+### 避免不必要的计算
+
+```dart
+// ✅ 好 - 缓存计算结果
+class Rectangle {
+  Rectangle(this.width, this.height);
+  
+  final double width;
+  final double height;
+  
+  late final double area = width * height; // 只计算一次
+}
+
+// ❌ 坏 - 重复计算
+class Rectangle {
+  Rectangle(this.width, this.height);
+  
+  final double width;
+  final double height;
+  
+  double get area => width * height; // 每次访问都计算
+}
+```
+
+### 使用 const 构造函数
+
+```dart
+// ✅ 好 - 使用 const 减少内存分配
+class Color {
+  const Color(this.r, this.g, this.b);
+  
+  final int r, g, b;
+  
+  static const red = Color(255, 0, 0);
+  static const blue = Color(0, 0, 255);
+}
+
+// 使用时
+const widget = Icon(icon: Icons.home, color: Color.red);
+```
+
+## 最佳实践总结
+
+1. **充分利用空安全** - 明确区分可空和非空类型
+2. **优先使用不可变数据** - 使用 `final` 和 `const`
+3. **编写简洁的代码** - 但不牺牲可读性
+4. **使用模式匹配** - switch 表达式和解构
+5. **适当的异常处理** - 使用具体的异常类型
+6. **编写文档注释** - 为公共 API 提供清晰的文档
+7. **使用断言验证** - 在开发时捕获错误
+8. **遵循命名规范** - 保持代码一致性
+9. **测试优先** - 编写可测试的代码
+10. **性能意识** - 使用 const、缓存等优化技巧
+
+---
+
+**参考资源:**
+- [Effective Dart](https://dart.dev/effective-dart)
+- [Dart Language Tour](https://dart.dev/language)
+- [Flutter Style Guide](https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md)

package/standards/core/mandatory-rules.md

@@ -0,0 +1,103 @@
+# 底层必须规则（Mandatory Rules）
+
+> 此规范由 MCP 底层自动注入，所有规范请求都会附加此内容。
+> 版本: v1.0.0 | 最后更新: 2026-01-16
+
+---
+
+## 🚨 零容忍规则
+
+**这些规则在任何情况下都不能违反，优先级最高：**
+
+### 1. 完整的标签配对
+
+```html
+✅ <div>...</div>
+✅ <el-table>...</el-table>
+❌ <div>...<div>  <!-- 缺少结束标签 -->
+❌ </div>         <!-- 孤立的结束标签 -->
+```
+
+### 2. 禁止 `any` 类型
+
+```typescript
+// ❌ 禁止
+const data: any = {}
+function process(input: any) {}
+
+// ✅ 正确
+const data: Record<string, unknown> = {}
+function process(input: UserData) {}
+```
+
+### 3. 国际化强制使用
+
+```vue
+<!-- ✅ 正确 -->
+<el-button>{{ $t('提交') }}</el-button>
+:label="$t('名称')"
+:placeholder="$t('请输入')"
+
+<!-- ❌ 硬编码 -->
+<el-button>提交</el-button>
+label="名称"
+```
+
+---
+
+## ⚠️ 强制工作流
+
+### 问题诊断优先
+
+当用户描述问题时（错误、样式不对、效果不符预期），必须先调用：
+
+```
+troubleshoot({ problem: "用户描述的问题" })
+```
+
+### 规范加载验证
+
+在生成代码前，必须确认已加载相关规范：
+
+1. **检查项目作用域** - 确认文件路径属于当前项目
+2. **声明已加载** - 在响应中说明：`✅ 已加载规范: [规范名称]`
+
+---
+
+## 🔍 代码审查清单
+
+**每次编辑后必检：**
+
+- [ ] 所有 HTML 标签正确闭合
+- [ ] Vue SFC 只有一个 `<style>` 标签
+- [ ] 所有用户可见文本已国际化
+- [ ] 无 `any` 类型
+- [ ] Props/Emits 有完整类型定义
+
+---
+
+## 🚫 全局禁止模式
+
+| 禁止 | 替代方案 |
+|------|----------|
+| `any` 类型 | 具体类型或 `unknown` |
+| Options API | Composition API (`<script setup>`) |
+| 直接修改 Props | emit 事件或 computed |
+| `<script>` 中使用 `this` | 使用响应式变量 |
+| 多个 `<style>` 标签 | 合并为一个 |
+| 硬编码文本 | `$t('...')` 国际化 |
+
+---
+
+## 📋 最小改动原则
+
+| 判断项 | 是 | 否 |
+|--------|---|---|
+| 修改只影响当前文件？ | 继续修改 | **停止，重新评估** |
+| 存在类似模式？ | **复用现有模式** | 可新建 |
+| 需要改组件类型？ | **先确认用户意图** | 继续 |
+| 需要删除现有代码？ | **先确认必要性** | 继续 |
+
+---
+
+**此规范自动注入，无需手动加载。**