mta-mcp 2.14.0 → 2.16.0

package/agents/_TEMPLATE.md

@@ -0,0 +1,153 @@
+# Agent 开发模板
+
+> 所有 Agent 必须采用"规范获取指引"模式
+> 版本: v1.0.0 | 创建日期: 2026-01-16
+
+---
+
+## 🎯 设计原则
+
+**Agent 的职责是引导 AI 获取规范，而不是嵌入完整规范。**
+
+| 应该包含 | 不应该包含 |
+|----------|------------|
+| MCP 工具调用示例 | 完整的代码示例 |
+| 规范 ID 列表 | 详细的规则说明 |
+| 简要提示（10-20行） | 大段代码块 |
+| 问题诊断指引 | 常用模式的完整实现 |
+
+---
+
+## 📋 标准结构
+
+```markdown
+# [框架/技术] 开发代理
+
+> 此 Agent 引导 AI 通过 MCP 工具获取 npm 包中的详细规范
+> 版本: vX.X.X | 最后更新: YYYY-MM-DD
+
+---
+
+## 🔴 问题诊断优先（最高优先级）
+
+**当用户描述任何问题时，必须首先调用：**
+
+\`\`\`
+troubleshoot({ problem: "用户描述的问题" })
+\`\`\`
+
+---
+
+## 📚 规范获取指引
+
+**⚠️ 核心原则：写代码前，必须先通过 MCP 工具获取规范！**
+
+### 按文件类型获取
+
+| 场景 | MCP 调用 |
+|------|----------|
+| xxx 文件 | \`get_standard_by_id({ id: 'xxx-standard' })\` |
+
+### 按使用的库获取
+
+| 库 | MCP 调用 |
+|----|----------|
+| xxx-lib | \`get_standard_by_id({ id: 'xxx-lib' })\` |
+
+### 智能获取（推荐）
+
+\`\`\`
+get_compact_standards({ currentFile: "当前文件路径" })
+\`\`\`
+
+---
+
+## 🎯 快速提示
+
+> 以下是简要提示，**详细规范请通过上述 MCP 工具获取**
+
+### 必须遵守（3-5条）
+
+- ✅ 规则1
+- ✅ 规则2
+
+### 禁止（3-5条）
+
+- ❌ 禁止1
+- ❌ 禁止2
+
+---
+
+## 📋 可用规范列表
+
+通过 \`get_standard_by_id({ id: 'xxx' })\` 获取：
+
+- \`standard-id-1\` - 描述
+- \`standard-id-2\` - 描述
+
+---
+
+**维护团队**: MTA工作室  
+**设计理念**: Agent 只提供获取指引，详细规范由 MCP 工具从 npm 包动态获取
+```
+
+---
+
+## ✅ 检查清单
+
+新建 Agent 时，确保：
+
+- [ ] 第一节是"问题诊断优先"
+- [ ] 第二节是"规范获取指引"（包含 MCP 调用表格）
+- [ ] "快速提示"不超过 20 行
+- [ ] 没有大段代码示例（超过 10 行的代码块）
+- [ ] 列出了所有可用的规范 ID
+- [ ] 文件总行数不超过 150 行
+
+---
+
+## 🚫 反面示例
+
+```markdown
+# ❌ 错误：嵌入完整规范
+
+## Vue 3 规范
+
+### Composition API
+
+\`\`\`vue
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue'
+
+// 30 行完整代码示例...
+</script>
+\`\`\`
+
+### 表单处理
+
+\`\`\`typescript
+// 又是 20 行完整代码...
+\`\`\`
+```
+
+```markdown
+# ✅ 正确：指引获取
+
+## 📚 规范获取指引
+
+| 场景 | MCP 调用 |
+|------|----------|
+| Vue 组件 | \`get_standard_by_id({ id: 'vue3-composition' })\` |
+
+## 🎯 快速提示
+
+- ✅ 使用 Composition API
+- ✅ Props 必须定义类型
+- ❌ 禁止 Options API
+
+> 详细规范请通过 MCP 工具获取
+```
+
+---
+
+**此模板适用于所有 Agent，包括现有的和未来添加的。**

package/agents/flutter.agent.md

@@ -1,210 +1,173 @@
-# Flutter 开发 Agent
+# Flutter 开发代理
 
-> Flutter 和 Dart 应用开发专家配置
+> 此 Agent 引导 AI 通过 MCP 工具获取 npm 包中的详细规范
+> 版本: v3.1.0 | 最后更新: 2026-01-19
+
+---
 
 ## 🔴 问题诊断优先（最高优先级）
 
-**遇到任何问题时，必须首先调用 `troubleshoot` 工具！**
+**当用户描述任何问题时，必须首先调用：**
 
 ```
-⚠️ AI 请注意：当用户描述了问题（错误、样式不对、效果不符预期等），
-在尝试任何解决方案前，必须先调用：
-
-mcp_mta_troubleshoot({ problem: "用户描述的问题" })
-
-案例库包含经过验证的解决方案，可避免 6-10 轮无效尝试。
+troubleshoot({ problem: "用户描述的问题" })
 ```
 
 ### 已收录的问题类型
 
-| 问题类型 | 案例ID | 关键词 |
-|----------|--------|--------|
-| 阴影透出/容器变暗 | shadow-透出问题 | shadow, transparency, neumorphism |
-| 布局尺寸不匹配 | layout-尺寸不匹配 | layout, size, spacing |
-| 阴影被裁剪 | clip-阴影裁剪 | clip, shadow, clipBehavior |
-| TabBar动画不同步 | tabbar-动画同步 | animation, tabbar, color |
-| SVG颜色异常 | svg-颜色异常 | svg, color, colorfilter |
-| SVG未居中 | svg-未居中 | svg, viewbox, center |
-| 图标尺寸提取错误 | sketch-图标尺寸 | sketch, icon, group, shape |
-| 属性定义但未使用 | sketch-属性未使用 | property, unused |
-| 输入框边框异常 | input-边框问题 | input, border, focus |
-| withOpacity弃用 | withopacity-弃用 | opacity, deprecated |
+| 问题类型 | 关键词 |
+|----------|--------|
+| 阴影透出/容器变暗 | shadow, transparency, neumorphism |
+| 布局尺寸不匹配 | layout, size, spacing |
+| 阴影被裁剪 | clip, shadow, clipBehavior |
+| SVG 颜色/居中问题 | svg, color, viewbox |
+| 输入框边框异常 | input, border, focus |
+| **TextField 垂直居中** | textfield, placeholder, 居中, 光标, 输入框 |
 
 ---
 
-## 📝 角色定义
-
-你是一位 Flutter 和 Dart 开发专家，精通:
-- **Dart 语言** - 空安全、异步编程、模式匹配
-- **Flutter 框架** - Widget 系统、状态管理、导航
-- **Material Design 3** - 现代 UI/UX 设计
-- **跨平台开发** - iOS、Android、Web、Desktop
-
----
-
-## ⚠️ 强制工作流
-
-### Step 0: 问题诊断（遇到问题时）
+## ⚠️ TextField 垂直居中（高频问题）
 
-```
-# 用户描述了问题？立即调用：
-troubleshoot({ problem: "阴影透出来了，容器比设计稿暗" })
-
-# 返回匹配的案例后，获取完整方案：
-get_troubleshooting_case({ framework: "flutter", caseId: "shadow-透出问题" })
-```
+> 此问题曾导致 15+ 轮对话才修复，必须一步到位
 
-### Step 1: 加载规范（编写代码时）
-
-**按文件类型加载**：
-```
-# Dart 代码
-get_relevant_standards({ fileType: "dart" })
-→ 加载: standards/core/dart-base.md
+### 问题特征
+- placeholder 和输入内容位置不一致
+- 光标位置偏上/偏下
+- 修改一个问题引发另一个问题
 
-# Flutter Widget
-get_relevant_standards({ fileType: "dart", imports: ["flutter"] })
-→ 加载: standards/frameworks/flutter.md
+### 正确方案（直接使用）
 
-# UI 开发（Token 系统）
-get_relevant_standards({ scenario: "Flutter UI 系统" })
-→ 加载: standards/frameworks/flutter-ui-system.md
-```
-
-**按场景加载**：
+```dart
+Container(
+  height: 36, // 设计稿容器高度
+  alignment: Alignment.center, // 关键1
+  child: TextField(
+    style: TextStyle(fontSize: 14, height: 1.43), // 关键2: 行高 = 文本高度÷字号
+    decoration: InputDecoration(
+      hintStyle: TextStyle(fontSize: 14, height: 1.43), // 关键3: 必须与style一致
+      contentPadding: EdgeInsets.zero, // 关键4
+      isDense: true, // 关键5
+    ),
+  ),
+)
 ```
-# 状态管理
-get_relevant_standards({ imports: ["riverpod"], scenario: "状态管理" })
-
-# API 调用
-get_relevant_standards({ scenario: "API 调用" })
-→ 加载: standards/patterns/api-layer.md
 
-# 组件设计
-get_relevant_standards({ scenario: "组件设计" })
-→ 加载: standards/patterns/component-design.md
-```
+### 禁止事项
+- ❌ `style.height` ≠ `hintStyle.height`
+- ❌ 同时用 `textAlignVertical` 和 `height`
+- ❌ 用 `strutStyle + forceStrutHeight`
+- ❌ 反复调整 `contentPadding` 试错
 
 ---
 
-## 🎯 核心原则
-
-### Widget 开发
-- 使用组合优于继承
-- 区分 StatelessWidget 和 StatefulWidget
-- 使用 const 构造函数优化性能
-- 避免 build 方法中创建对象
+## 📚 规范获取指引
 
-### 状态管理
-- 区分瞬时状态和应用状态
-- 使用现代方案（Provider、Riverpod、Bloc）
-- 避免状态重复
+**⚠️ 核心原则：写代码前，必须先通过 MCP 工具获取规范！**
 
-### 最小修改原则
+### 按文件类型获取
 
-| 判断项 | 是 | 否 |
-|--------|---|---|
-| 元素只在当前页面使用？ | 可写在页面内 | **抽象为公共组件** |
-| 修改会影响其他页面？ | **停止，重新评估** | 继续修改 |
-| 样式全局通用？ | 添加到 Token | 使用局部样式 |
+| 场景 | MCP 调用 |
+|------|----------|
+| Dart 代码 | `get_standard_by_id({ id: 'dart-base' })` |
+| Flutter Widget | `get_standard_by_id({ id: 'flutter' })` |
+| UI Token 系统 | `get_standard_by_id({ id: 'flutter-ui-system' })` |
 
----
+### 按场景获取
 
-## 🎨 UI 开发要点
+| 场景 | MCP 调用 |
+|------|----------|
+| 状态管理 | `get_standard_by_id({ id: 'riverpod' })` |
+| API 调用 | `get_standard_by_id({ id: 'api-layer' })` |
+| 组件设计 | `get_standard_by_id({ id: 'component-design' })` |
 
-### Token 系统（禁止硬编码）
-
-```dart
-// ❌ 禁止
-Container(color: Color(0xFF3B82F6), padding: EdgeInsets.all(16))
+### 智能获取（推荐）
 
-// ✅ 正确
-Container(color: $c.primary, padding: EdgeInsets.all($s.md))
 ```
+// 根据当前文件自动匹配
+get_compact_standards({ currentFile: "xxx.dart" })
 
-### 全局快捷方式
-- `$c` - 颜色 (AppColors)
-- `$t` - 文字样式 (AppTypography)
-- `$s` - 间距 (AppSpacing)
-- `$r` - 圆角 (AppRadius)
-- `$shadow` - 阴影 (AppShadows)
+// 获取多个规范
+get_standard_by_id({ ids: ['flutter', 'flutter-ui-system'] })
+```
 
 ---
 
-## 🎨 Sketch 设计稿还原
-
-### 核心原则
-
-1. **一次性提取所有属性** - 使用完整样式提取脚本，不要分散查询
-2. **精确坐标** - 从 Sketch 读取精确的 x, y, width, height
-3. **图标用 SVG** - 禁止使用近似的 Material Icons
-4. **检查内部尺寸** - 图标取 Shape 尺寸，不是 Group 尺寸
-
-### 遇到问题时
+## 🎯 快速提示
 
-**不要猜测！调用 `troubleshoot` 获取经验：**
+> 以下是简要提示，**详细规范请通过上述 MCP 工具获取**
 
-```
-# 阴影效果不对
-troubleshoot({ problem: "新拟态阴影透出来了" })
+### 必须遵守
 
-# 布局偏移
-troubleshoot({ problem: "元素位置与设计稿不符" })
+- ✅ 使用 Token 系统（`$c`, `$t`, `$s`, `$r`）
+- ✅ 使用 const 构造函数优化性能
+- ✅ 区分 StatelessWidget 和 StatefulWidget
+- ✅ 组合优于继承
 
-# 动画不同步
-troubleshoot({ problem: "TabBar切换时颜色变化太快" })
-```
+### 禁止
 
----
+- ❌ 硬编码颜色/尺寸（如 `Color(0xFF3B82F6)`）
+- ❌ 在 build 方法中创建对象
+- ❌ 直接使用 setState 管理复杂状态
 
-## 📐 架构模式
+### Token 快捷方式
 
-### 推荐的项目结构
-
-```
-lib/
-├── core/               # 核心功能（constants, errors, network, utils）
-├── data/               # 数据层（models, repositories, services）
-├── domain/             # 业务逻辑层（entities, usecases）
-├── presentation/       # 表现层（screens, widgets, providers, theme）
-└── l10n/               # 国际化
-```
+| 快捷方式 | 用途 |
+|----------|------|
+| `$c` | 颜色 (AppColors) |
+| `$t` | 文字样式 (AppTypography) |
+| `$s` | 间距 (AppSpacing) |
+| `$r` | 圆角 (AppRadius) |
+| `$shadow` | 阴影 (AppShadows) |
 
 ---
 
-## 🚀 性能优化清单
-
-- [ ] 使用 `const` 构造函数
-- [ ] 提取不变的子 Widget
-- [ ] 使用 `ListView.builder` 处理长列表
-- [ ] 使用 `cached_network_image` 缓存图片
-- [ ] 在 `dispose` 中清理动画资源
-- [ ] 使用 `RepaintBoundary` 隔离重绘
+## 📋 可用规范列表
 
----
+通过 `get_standard_by_id({ id: 'xxx' })` 获取：
 
-## 📚 常用包推荐
+**核心规范**
+- `dart-base` - Dart 语言基础规范
+- `flutter` - Flutter 框架规范
+- `flutter-ui-system` - UI Token 系统
 
-| 类别 | 推荐 |
-|------|------|
-| 状态管理 | riverpod, flutter_bloc, provider |
-| 网络请求 | dio, retrofit |
-| 本地存储 | hive, isar, shared_preferences |
-| 导航 | go_router, auto_route |
-| UI | flutter_svg, cached_network_image, shimmer |
-| 工具 | freezed, json_serializable |
+**模式规范**
+- `api-layer` - API 层封装模式
+- `component-design` - 组件设计模式
 
 ---
 
-## ✅ 代码审查清单
+## 🎨 设计稿还原强制规范
+
+> ⚠️ 使用 Sketch/Figma MCP 时必须遵守
+
+### 强制要求：完整读取选中元素及其所有子集
+
+```javascript
+// 正确：一次性获取容器+所有子元素的完整信息
+function extractComplete(element) {
+  // 1. 容器信息
+  console.log(`容器: ${element.frame.width}x${element.frame.height}`);
+  
+  // 2. 所有子元素信息（关键！）
+  element.layers.forEach(child => {
+    console.log(`子元素: ${child.name}`);
+    console.log(`  位置: Y=${child.frame.y}px`);
+    console.log(`  尺寸: ${child.frame.width}x${child.frame.height}`);
+    if (child.type === 'Text') {
+      console.log(`  字号: ${child.style.fontSize}px`);
+      console.log(`  行高: ${child.frame.height / child.style.fontSize}`);
+    }
+  });
+}
+```
 
-- [ ] 所有公共 API 有文档注释
-- [ ] 通过 `dart analyze` 无警告
-- [ ] 通过 `dart format` 格式化
-- [ ] 无内存泄漏
-- [ ] 符合无障碍标准
+### 禁止事项
+- ❌ 只读容器属性，忽略内部元素位置
+- ❌ 每次只查一个属性，分散多轮获取
+- ❌ 假设"差不多"而不验证精确像素值
+- ❌ 用"试错法"调整参数
 
 ---
 
 **维护团队**: MTA工作室  
-**版本**: v2.0.0（精简版，详细方案请查询 troubleshooting）
+**设计理念**: Agent 只提供获取指引，详细规范由 MCP 工具从 npm 包动态获取

package/agents/i18n.agent.md

@@ -1,133 +1,78 @@
----
-description: '国际化 (i18n) 专用代理 - 零硬编码文本'
-tags: ['i18n', 'vue', 'react']
-tools: ['edit', 'search', 'usages', 'vscodeAPI', 'problems', 'runSubagent']
----
+# 国际化 (i18n) 开发代理
 
-# 国际化 (i18n) 代理
+> 此 Agent 引导 AI 通过 MCP 工具获取 npm 包中的详细规范
+> 版本: v3.0.0 | 最后更新: 2026-01-16
 
-**规范来源**: `prompts/common/i18n.md`
+---
 
-## ⚠️ 强制工作流
+## 🔴 问题诊断优先（最高优先级）
 
-**在添加任何用户可见文本前，必须先调用 MCP 工具：**
+**当用户描述任何问题时，必须首先调用：**
 
 ```
-get_relevant_standards({ imports: ["vue-i18n"] })
+troubleshoot({ problem: "用户描述的问题" })
 ```
 
-或者使用场景匹配：
-```
-get_relevant_standards({ scenario: "国际化" })
-```
+---
 
-## 核心原则
+## 📚 规范获取指引
 
-1. **零硬编码** - 所有用户可见文本使用翻译函数
-2. **键名规范** - 点分层级 (`common.save`)
-3. **参数化** - 动态内容用插值，不拼接
-4. **回退机制** - 提供默认语言
+**⚠️ 核心原则：添加任何用户可见文本前，必须先获取规范！**
 
-## Vue 组件中使用
+### 按框架获取
 
-```vue
-<script setup lang="ts">
-import { getCurrentInstance } from 'vue'
-
-const { appContext } = getCurrentInstance()!
-const $t = appContext.config.globalProperties.$t
-</script>
-
-<template>
-  <!-- ✅ 好 -->
-  <el-button>{{ $t('common.save') }}</el-button>
-  <el-table-column :label="$t('user.profile.name')" />
-  
-  <!-- 参数插值 -->
-  <p>{{ $t('message.deleteConfirm', { name: userName }) }}</p>
-  
-  <!-- ❌ 坏 -->
-  <el-button>保存</el-button>
-</template>
+| 框架 | MCP 调用 |
+|------|----------|
+| Vue + vue-i18n | `get_standard_by_id({ id: 'i18n' })` |
+| Vue 3 组件 | `get_standard_by_id({ id: 'vue3-composition' })` |
+| React | `get_standard_by_id({ id: 'react-i18n' })` |
+
+### 智能获取（推荐）
+
+```
+// 根据当前文件自动匹配
+get_compact_standards({ currentFile: "xxx.vue", scenario: "国际化" })
 ```
 
-## TypeScript 中使用
+---
 
-```typescript
-import { ElMessage } from 'element-plus'
+## 🎯 快速提示
 
-// ✅ 好
-ElMessage.success($t('message.saveSuccess'))
+> 以下是简要提示，**详细规范请通过上述 MCP 工具获取**
 
-// 带参数
-ElMessage.warning($t('message.deleteConfirm', { name: user.name }))
+### 必须遵守
 
-// ❌ 坏
-ElMessage.success('保存成功')
-```
+- ✅ 零硬编码 - 所有用户可见文本使用 `$t()`
+- ✅ 键名规范 - 点分层级 (`common.save`)
+- ✅ 参数化 - 动态内容用插值，不拼接
 
-## 动态文本映射
+### 禁止
 
-```typescript
-// ✅ 好
-const statusMap = {
-  pending: $t('status.pending'),
-  success: $t('status.success'),
-  error: $t('status.error')
-}
+- ❌ 硬编码中文/英文
+- ❌ 字符串拼接: `'删除' + name + '吗？'`
+- ❌ 重复的翻译键
 
-// 模板中
-{{ { 0: $t('type.input'), 1: $t('type.output') }[row.type] }}
+### 快速示例
 
-// ❌ 坏
-const statusMap = {
-  pending: '待处理',
-  success: '成功'
-}
-```
+```vue
+<!-- ✅ 正确 -->
+<el-button>{{ $t('common.save') }}</el-button>
+<el-table-column :label="$t('user.name')" />
 
-## 表单验证
-
-```typescript
-const rules = {
-  name: [
-    { 
-      required: true, 
-      message: $t('validation.required', { 
-        field: $t('user.profile.name') 
-      }), 
-      trigger: 'blur' 
-    }
-  ]
-}
+<!-- ❌ 错误 -->
+<el-button>保存</el-button>
 ```
 
-## 确认对话框
-
-```typescript
-const handleDelete = async (row: User) => {
-  try {
-    await ElMessageBox.confirm(
-      $t('message.deleteConfirm', { name: row.name }),
-      $t('common.warning'),
-      {
-        confirmButtonText: $t('common.confirm'),
-        cancelButtonText: $t('common.cancel'),
-        type: 'warning'
-      }
-    )
-    // 执行删除
-  } catch (err) {
-    // 用户取消
-  }
-}
-```
+---
 
-## 禁止模式
+## 📋 可用规范列表
 
-- ❌ 硬编码中文/英文
-- ❌ 字符串拼接: `'删除' + name + '吗？'`
-- ❌ 代码中切换语言逻辑
-- ❌ 重复的翻译键
+通过 `get_standard_by_id({ id: 'xxx' })` 获取：
+
+- `i18n` - Vue 国际化完整规范
+- `vue3-composition` - Vue 3 规范（含 i18n 章节）
+
+---
 
-**完整规范**: `prompts/common/i18n.md`
+**维护团队**: MTA工作室  
+**设计理念**: Agent 只提供获取指引，详细规范由 MCP 工具从 npm 包动态获取