mta-mcp 1.0.0

package/common/i18n.md

@@ -0,0 +1,385 @@
+# 国际化 (i18n) 最佳实践
+
+适用于需要多语言支持的前端项目
+
+## 🎯 核心原则
+
+1. **零硬编码**: 所有用户可见文本必须使用翻译函数
+2. **键名规范**: 使用点分层级结构 (`common.save`, `user.profile.title`)
+3. **参数化**: 动态内容使用参数插值，不拼接字符串
+4. **回退机制**: 提供默认语言作为回退
+
+## 🔧 标准配置 (Vue I18n)
+
+### 目录结构
+```
+src/locales/
+├── index.ts           # i18n 初始化
+├── zh-CN.ts          # 简体中文
+├── en-US.ts          # 英文
+└── ja-JP.ts          # 日文
+```
+
+### 翻译文件示例
+```typescript
+// zh-CN.ts
+export default {
+  common: {
+    save: '保存',
+    cancel: '取消',
+    confirm: '确认',
+    delete: '删除',
+    edit: '编辑',
+    search: '搜索'
+  },
+  user: {
+    profile: {
+      title: '用户资料',
+      name: '姓名',
+      email: '邮箱'
+    }
+  },
+  message: {
+    saveSuccess: '保存成功',
+    deleteConfirm: '确认删除 {name} 吗？',
+    itemsSelected: '已选择 {count} 项'
+  }
+}
+```
+
+## 🎨 单文件 i18n 配置（轻量方案）
+
+**适用于不想引入 vue-i18n 插件的项目，使用自定义实现：**
+
+### 1. 配置位置
+- **翻译文件**: `src/locales/messages.ts` (键值对数组格式)
+- **语言状态**: `src/stores/state/locale.ts` (Pinia Store)
+- **全局注册**: `src/main.ts` (自定义 $t 方法)
+
+### 2. 翻译文件格式
+```typescript
+// src/locales/messages.ts
+// 索引 0 为英文，索引 1 为中文
+
+const messages: Record<string, [string, string]> = {
+  // ========== 通用 ==========
+  是: ['Yes', '是'],
+  否: ['No', '否'],
+  确定: ['OK', '确定'],
+  取消: ['Cancel', '取消'],
+  确认: ['Confirm', '确认'],
+  保存: ['Save', '保存'],
+  提交: ['Submit', '提交'],
+  搜索: ['Search', '搜索'],
+  查询: ['Query', '查询'],
+  重置: ['Reset', '重置'],
+  导出: ['Export', '导出'],
+  新增: ['Add', '新增'],
+  编辑: ['Edit', '编辑'],
+  删除: ['Delete', '删除'],
+  详情: ['Detail', '详情'],
+  操作: ['Operation', '操作'],
+  状态: ['Status', '状态'],
+  备注: ['Remark', '备注'],
+  
+  // ========== 业务模块 ==========
+  订单号: ['Order No', '订单号'],
+  金额: ['Amount', '金额'],
+  // ... 按模块分组
+}
+
+export default messages
+```
+
+### 3. 语言状态管理
+```typescript
+// src/stores/state/locale.ts
+import { ref } from 'vue'
+import { defineStore } from 'pinia'
+
+export const useLocaleStore = defineStore('locale', () => {
+  // 默认中文，可从 localStorage 读取
+  const locale = ref<'zh-cn' | 'en'>(
+    (localStorage.getItem('locale') as 'zh-cn' | 'en') || 'zh-cn'
+  )
+
+  const setLocale = (lang: 'zh-cn' | 'en') => {
+    locale.value = lang
+    localStorage.setItem('locale', lang)
+  }
+
+  const toggleLocale = () => {
+    setLocale(locale.value === 'zh-cn' ? 'en' : 'zh-cn')
+  }
+
+  return { locale, setLocale, toggleLocale }
+})
+```
+
+### 4. main.ts 全局注册
+```typescript
+// src/main.ts
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import App from './App.vue'
+import messages from '@/locales/messages'
+import { useLocaleStore } from '@/stores'
+
+const app = createApp(App)
+const pinia = createPinia()
+
+// ⚠️ 必须先注册 pinia，再使用 store
+app.use(pinia)
+
+// 获取语言状态
+const localeStore = useLocaleStore()
+
+// 注册全局 $t 方法
+app.config.globalProperties.$t = (key: string): string => {
+  const translation = messages[key]
+  if (!translation) {
+    console.warn(`[i18n] Missing translation: ${key}`)
+    return key
+  }
+  // 索引 0 为英文，索引 1 为中文
+  return translation[localeStore.locale === 'zh-cn' ? 1 : 0] || key
+}
+
+app.mount('#app')
+```
+
+### 5. 使用方式
+
+**在模板中（直接使用）：**
+```vue
+<template>
+  <el-button>{{ $t('保存') }}</el-button>
+  <el-table-column :label="$t('订单号')" prop="orderNo" />
+  <el-tag>{{ $t(row.status === 'success' ? '成功' : '失败') }}</el-tag>
+</template>
+```
+
+**在 script 中（需要获取实例）：**
+```typescript
+<script setup lang="ts">
+import { getCurrentInstance } from 'vue'
+
+// ⚠️ 必须通过 getCurrentInstance 获取
+const { appContext } = getCurrentInstance()!
+const $t = appContext.config.globalProperties.$t
+
+// 使用
+ElMessage.success($t('保存成功'))
+ElMessageBox.confirm($t('确认删除吗？'), $t('提示'))
+
+// 表单验证
+const rules = {
+  name: [{ required: true, message: $t('请输入名称'), trigger: 'blur' }]
+}
+</script>
+```
+
+### 6. 添加新翻译键
+
+在 `src/locales/messages.ts` 中按分类添加：
+
+```typescript
+const messages: Record<string, [string, string]> = {
+  // ========== 已有内容 ==========
+  
+  // ========== 新增：交易模块 ==========
+  汇款订单: ['Remittance Order', '汇款订单'],
+  收款订单: ['Collection Order', '收款订单'],
+  交易流水: ['Transaction Record', '交易流水'],
+  
+  // ========== 新增：客户模块 ==========
+  客户名称: ['Customer Name', '客户名称'],
+  联系方式: ['Contact', '联系方式'],
+}
+```
+
+### ❌ 禁止事项
+
+```typescript
+// ❌ 不要引入 useI18n（项目未使用 vue-i18n）
+import { useI18n } from 'vue-i18n'
+
+// ❌ 不要硬编码文本
+<el-button>保存</el-button>
+
+// ❌ 不要字符串拼接
+const msg = '删除' + name + '成功'
+
+// ❌ 不要在翻译值中使用变量（当前实现不支持）
+$t('已选择 {count} 项', { count: 5 })  // 不支持！
+// ✅ 替代方案
+`${$t('已选择')} ${count} ${$t('项')}`
+```
+
+## ✅ 最佳实践
+
+### Vue 组件中使用
+```vue
+<script setup lang="ts">
+import { getCurrentInstance } from 'vue'
+
+// 获取 $t 函数
+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>
+  
+  <!-- 复数处理 -->
+  <span>{{ $t('message.itemsSelected', { count: selectedCount }) }}</span>
+  
+  <!-- ❌ 坏 -->
+  <el-button>保存</el-button>
+  <p>确认删除 {{ userName }} 吗？</p>
+</template>
+```
+
+### TypeScript 中使用
+```typescript
+import { ElMessage } from 'element-plus'
+
+// ✅ 好
+ElMessage.success($t('message.saveSuccess'))
+
+// 带参数
+ElMessage.warning($t('message.deleteConfirm', { name: user.name }))
+
+// ❌ 坏
+ElMessage.success('保存成功')
+```
+
+### 动态文本映射
+```typescript
+// ✅ 好 - 使用映射对象
+const statusMap = {
+  pending: $t('status.pending'),
+  success: $t('status.success'),
+  error: $t('status.error')
+}
+
+const statusText = statusMap[status]
+
+// 或在模板中
+{{ { 0: $t('type.input'), 1: $t('type.output') }[row.type] }}
+
+// ❌ 坏 - 硬编码
+const statusMap = {
+  pending: '待处理',
+  success: '成功',
+  error: '失败'
+}
+```
+
+## ⚠️ 禁止模式
+
+- ❌ 硬编码中文/英文文本
+- ❌ 字符串拼接: `'删除' + name + '吗？'`
+- ❌ 在代码中切换语言逻辑: `if (lang === 'zh') { ... }`
+- ❌ 重复的翻译键
+
+## 📋 代码审查清单
+
+- [ ] 所有用户可见文本使用 `$t()`
+- [ ] 翻译键使用点分层级结构
+- [ ] 动态内容使用参数插值
+- [ ] 所有语言文件有相同的键结构
+- [ ] ElMessage/ElMessageBox 的文本已翻译
+- [ ] 表单验证消息已翻译
+
+## 🔧 常见场景
+
+### 表单验证
+```typescript
+const rules = {
+  name: [
+    { 
+      required: true, 
+      message: $t('validation.required', { field: $t('user.profile.name') }), 
+      trigger: 'blur' 
+    },
+    { 
+      min: 2, 
+      max: 20, 
+      message: $t('validation.length', { min: 2, max: 20 }), 
+      trigger: 'blur' 
+    }
+  ]
+}
+```
+
+### 确认对话框
+```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) {
+    // 用户取消
+  }
+}
+```
+
+### 时间格式化
+```typescript
+// 使用 i18n 的日期格式化
+const formatDate = (date: Date) => {
+  return new Intl.DateTimeFormat(locale.value, {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric'
+  }).format(date)
+}
+```
+
+## 🌍 语言切换
+
+```typescript
+import { useI18n } from 'vue-i18n'
+
+const { locale } = useI18n()
+
+// 切换语言
+const changeLanguage = (lang: 'zh-CN' | 'en-US') => {
+  locale.value = lang
+  localStorage.setItem('language', lang)
+}
+```
+
+---
+
+## ⚠️ 重要：配置文件管理
+
+### Copilot 配置 .gitignore
+
+**推荐做法：**将自动生成的 `.github/copilot-instructions.md` 添加到 `.gitignore`
+
+```gitignore
+# Copilot 配置(自动生成)
+.github/copilot-instructions.md
+```
+
+**适用项目：**
+- 需要国际化的 Web 应用
+- Vue.js、React、Angular 项目
+- 多语言支持的前端项目
+
+**详细指南**: 参考 [Copilot .gitignore 通用指南](../docs/guides/COPILOT_GITIGNORE_GUIDE.md)

package/common/typescript-strict.md

@@ -0,0 +1,186 @@
+# TypeScript 严格模式指南
+
+适用于所有需要高质量类型安全的 TypeScript 项目
+
+## 🎯 核心原则
+
+1. **零 any**: 绝不使用 `any` 类型，使用 `unknown` 或具体类型
+2. **严格空检查**: 启用 `strictNullChecks`，明确处理 `null`/`undefined`
+3. **完整类型定义**: 所有函数参数、返回值、变量都有明确类型
+4. **类型推断优先**: 让 TypeScript 推断简单类型，复杂类型显式声明
+
+## 📝 tsconfig.json 配置
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}
+```
+
+## ✅ 最佳实践
+
+### 类型定义
+```typescript
+// ✅ 好
+interface User {
+  id: number
+  name: string
+  email?: string  // 可选属性
+}
+
+function getUser(id: number): Promise<User | null> {
+  // ...
+}
+
+// ❌ 坏
+function getUser(id: any): any {
+  // ...
+}
+```
+
+### 空值处理
+```typescript
+// ✅ 好
+const user: User | null = await getUser(1)
+if (user) {
+  console.log(user.name)
+}
+
+// 或使用可选链
+console.log(user?.name)
+
+// ❌ 坏
+const user = await getUser(1)
+console.log(user.name)  // 可能报错
+```
+
+### 联合类型
+```typescript
+// ✅ 好
+type Status = 'pending' | 'success' | 'error'
+
+function handleStatus(status: Status) {
+  switch (status) {
+    case 'pending': return 'Loading...'
+    case 'success': return 'Done!'
+    case 'error': return 'Failed!'
+  }
+}
+
+// ❌ 坏
+function handleStatus(status: string) {
+  // 失去类型约束
+}
+```
+
+### 泛型使用
+```typescript
+// ✅ 好
+function fetchData<T>(url: string): Promise<T> {
+  return fetch(url).then(res => res.json())
+}
+
+interface Product {
+  id: number
+  name: string
+}
+
+const products = await fetchData<Product[]>('/api/products')
+
+// ❌ 坏
+function fetchData(url: string): Promise<any> {
+  return fetch(url).then(res => res.json())
+}
+```
+
+## ⚠️ 禁止模式
+
+- ❌ `any` 类型
+- ❌ 类型断言 `as any`
+- ❌ `@ts-ignore` / `@ts-nocheck`
+- ❌ 隐式 any (`noImplicitAny: false`)
+- ❌ 非空断言 `!` (除非确定安全)
+
+## 📋 代码审查清单
+
+- [ ] 所有函数有明确的参数类型和返回值类型
+- [ ] 没有使用 `any` 类型
+- [ ] 正确处理可能为 `null`/`undefined` 的值
+- [ ] 使用联合类型而非宽泛的 `string`/`number`
+- [ ] 复杂对象有接口定义
+- [ ] 泛型使用恰当
+
+## 🔧 常见场景
+
+### API 响应处理
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+}
+
+async function callApi<T>(endpoint: string): Promise<ApiResponse<T>> {
+  try {
+    const response = await fetch(endpoint)
+    const data = await response.json()
+    return { success: true, data }
+  } catch (error) {
+    return { 
+      success: false, 
+      error: error instanceof Error ? error.message : 'Unknown error' 
+    }
+  }
+}
+```
+
+### 类型守卫
+```typescript
+function isUser(obj: unknown): obj is User {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'id' in obj &&
+    'name' in obj
+  )
+}
+
+const data: unknown = await fetchData()
+if (isUser(data)) {
+  console.log(data.name)  // TypeScript 知道 data 是 User
+}
+```
+
+---
+
+## ⚠️ 重要：配置文件管理
+
+### Copilot 配置 .gitignore
+
+**推荐做法：**将自动生成的 `.github/copilot-instructions.md` 添加到 `.gitignore`
+
+```gitignore
+# Copilot 配置(自动生成)
+.github/copilot-instructions.md
+```
+
+**适用项目：**
+- TypeScript 应用（React、Vue、Angular）
+- Node.js 后端服务
+- TypeScript 工具库
+- 所有使用 TypeScript 的项目
+
+**详细指南**: 参考 [Copilot .gitignore 通用指南](../docs/guides/COPILOT_GITIGNORE_GUIDE.md)

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * 故障排除案例元数据
+ */
+interface TroubleshootingCase {
+    id: string;
+    framework: string;
+    title: string;
+    problemType: string;
+    tags: string[];
+    severity: string;
+    timeSaved: string;
+    filePath: string;
+}
+/**
+ * 查询结果
+ */
+interface TroubleshootingQueryResult {
+    cases: Array<{
+        id: string;
+        title: string;
+        framework: string;
+        problemType: string;
+        tags: string[];
+        matchScore: number;
+        timeSaved: string;
+        preview: string;
+    }>;
+    totalFound: number;
+    queryInfo: {
+        framework?: string;
+        keywords: string[];
+        errorMessage?: string;
+    };
+}
+/**
+ * 查询故障排除案例
+ */
+declare function queryTroubleshootingCases(params: {
+    framework?: string;
+    keywords?: string[];
+    errorMessage?: string;
+    codePattern?: string;
+    limit?: number;
+}): Promise<TroubleshootingQueryResult>;
+/**
+ * 获取案例完整内容
+ */
+declare function getTroubleshootingCaseContent(params: {
+    framework: string;
+    caseId: string;
+}): Promise<{
+    content: string;
+    metadata: any;
+}>;
+/**
+ * 列出所有可用案例
+ */
+declare function listTroubleshootingCases(framework?: string): Promise<{
+    cases: TroubleshootingCase[];
+    frameworks: string[];
+}>;
+
+export { getTroubleshootingCaseContent, listTroubleshootingCases, queryTroubleshootingCases };