metona-ai-desktop/standard/开发规范.md

# Metona 开发规范

> **版本**：v1.1.0  
> **生效日期**：2026-06-26  
> **适用范围**：Metona 项目所有代码（electron/、src/、scripts/）

---

## 第一铁律：优先使用第三方成熟库

### 核心原则

**禁止重复造轮子，禁止自写实现，除非第三方库确实没有。**

这是 Metona 项目的第一铁律，无例外。

### 规范细则

#### 1. 优先级顺序

```
第一选择：成熟的第三方库（npm 下载量 > 1000/周，维护活跃）
第二选择：轻量级第三方库（功能单一但稳定）
第三选择：自写实现（仅在确认无可用库时）
```

#### 2. 判断标准

在引入自写实现前，必须完成以下检查：

| 检查项 | 要求 |
|--------|------|
| npm 搜索 | 搜索关键词，确认无合适库 |
| GitHub 搜索 | 搜索相关实现，评估质量 |
| 下载量 | 周下载量 > 1000（活跃使用） |
| 维护状态 | 最近 6 个月内有更新 |
| Issue 处理 | 维护者活跃响应 |
| 文档质量 | 有完整的 README 和 API 文档 |
| TypeScript 支持 | 优先选择有 @types 包或自带类型 |

#### 3. 禁止自写的场景

以下场景**绝对禁止**自写实现：

| 场景 | 推荐库 | 禁止自写原因 |
|------|--------|--------------|
| HTTP 请求 | axios、ky、ofetch | 网络层复杂度高，需处理重试、超时、拦截器 |
| 数据库 | better-sqlite3、sql.js | 存储层需要事务、并发、性能优化 |
| 日志 | electron-log、winston | 需要文件轮转、级别控制、格式化 |
| 加密 | bcrypt、argon2、crypto-js | 安全性要求高，算法实现复杂 |
| UUID 生成 | nanoid、uuid | 需要保证唯一性和性能 |
| 日期处理 | date-fns、dayjs | 时区、格式化、计算逻辑复杂 |
| 参数校验 | zod、yup、joi | 需要类型推断、错误信息、嵌套校验 |
| Markdown 渲染 | react-markdown、marked | 渲染逻辑复杂，需支持扩展 |
| 代码高亮 | prismjs、highlight.js | 语言支持、主题、性能 |
| 动画 | framer-motion、react-spring | 性能优化、硬件加速、复杂动画 |
| 状态管理 | zustand、jotai | 需要订阅、更新、中间件 |
| 路由 | react-router | 需要历史管理、嵌套路由、守卫 |
| 表单 | react-hook-form | 需要校验、性能优化、受控/非受控 |
| 虚拟列表 | react-window、react-virtuoso | 性能优化、动态高度、滚动恢复 |
| 图表 | recharts、chart.js | 渲染复杂度高，需支持多种图表类型 |
| 国际化 | react-i18next、formatjs | 需要复数、格式化、懒加载 |
| 拖拽 | react-beautiful-dnd、dnd-kit | 需要无障碍、性能、复杂交互 |
| WebSocket | ws、socket.io | 需要重连、心跳、二进制支持 |
| 任务队列 | bull、bee-queue | 需要持久化、重试、优先级 |
| 配置管理 | dotenv、convict | 需要类型安全、环境变量、默认值 |
| UI 组件 | Material UI (MUI) @mui/material | 按钮、输入框、弹窗、选择器、表单、表格等所有 UI 组件 |

#### 3.1 UI 组件铁律

**所有前端 UI 组件必须使用 Material UI (MUI)**，禁止自写任何 UI 交互组件。

| 组件类型 | MUI 组件 | 禁止自写 |
|---------|----------|----------|
| 按钮 | Button、IconButton | 自写 `<button>` 样式 |
| 输入框 | TextField、InputBase | 自写 `<input>` 样式 |
| 选择器 | Select、MenuItem | 自写下拉框 |
| 弹窗 | Dialog、Drawer | 自写遮罩层 |
| 表单控件 | Checkbox、Switch、Slider | 自写表单控件 |
| 标签页 | Tabs、Tab | 自写 Tab 切换 |
| 提示 | Tooltip、Chip、Badge | 自写气泡提示 |
| 布局 | Box、Stack、Grid | 自写 Flex/Grid 布局 |
| 排版 | Typography | 自写 `<p>` `<span>` 样式 |
| 进度 | LinearProgress、CircularProgress | 自写进度条/加载动画 |
| 卡片 | Card、Paper | 自写卡片容器 |
| 头像 | Avatar | 自写头像圆形容器 |
| 列表 | List、ListItemButton | 自写列表项 |

#### 3.2 Toast 通知铁律

**所有 Toast 通知必须使用项目封装的 `MeToast` 组件**，禁止自写 Toast 组件、禁止直接使用第三方 Toast 库（如 notistack、react-hot-toast、react-toastify 等）。

| 场景 | 规范 |
|------|------|
| 前端主动显示 Toast | 使用 `MeToast` 组件（通过 `showToast()` 或对应 hook 调用） |
| 后端通过 IPC 触发 Toast | 主进程发送 `toast:show` IPC 事件，参数 `{ type: 'success' \| 'info' \| 'warning' \| 'error', message: string }`，前端 MeToast 监听并统一渲染 |
| 类型枚举 | `success` / `info` / `warning` / `error` 四种，不得自定义 |
| 并行事件防风暴 | 同一来源的并行事件（如多工具超时）需在后端节流，不得依赖前端去重 |

**原因**：
1. 统一视觉风格与动画效果
2. 集中管理 Toast 队列、堆叠顺序、自动消失时间
3. 避免 MUI Snackbar 与第三方库混用导致重复弹出或层级冲突

**例外**：无。任何 Toast 需求都必须走 MeToast 通道。

**例外**：仅当 MUI 确认不存在对应组件时，才可使用原生 HTML 元素 + Tailwind CSS 实现，且必须注释说明原因。

#### 4. 允许自写的场景

以下场景可以自写实现，但需满足条件：

| 场景 | 条件 |
|------|------|
| 简单工具函数 | < 20 行，无依赖，纯函数 |
| 业务逻辑封装 | 特定于项目的业务规则 |
| 类型定义 | 项目特有的接口和类型 |
| 适配器/桥接层 | 连接不同库的中间层 |
| 配置常量 | 项目特有的配置值 |
| Provider Adapter 流式解析 | 需精细控制 SSE/NDJSON 流式响应解析时，允许使用原生 fetch 替代 axios。条件：仅在 `electron/harness/adapters/` 目录内，且需封装为统一的流式处理工具函数 |

#### 5. 引入新库的流程

```
1. 搜索评估
   - npm search / GitHub search
   - 检查下载量、维护状态、文档质量
   
2. 技术评审
   - 包体积影响（bundlephobia.com）
   - 依赖树分析（是否有重复依赖）
   - 许可证检查（是否兼容 MIT）
   - 安全漏洞检查（npm audit）

3. 团队讨论
   - 在 PR 中说明选择理由
   - 列出备选方案和对比

4. 集成测试
   - 单元测试覆盖
   - 与现有代码集成测试
   - 性能基准测试

5. 文档更新
   - 更新 package.json
   - 更新 README 依赖说明
   - 添加使用示例
```

### 违规处理

| 违规类型 | 处理方式 |
|----------|----------|
| 有成熟库却自写 | PR 拒绝，要求使用第三方库 |
| 引入未评估的库 | PR 拒绝，要求完成评估流程 |
| 引入有安全漏洞的库 | 立即修复，回退到安全版本 |
| 引入已废弃的库 | PR 拒绝，选择替代方案 |

### 代码审查检查清单

在 Code Review 时，必须检查：

- [ ] 是否有可用的第三方库替代自写实现
- [ ] 引入的新库是否经过评估
- [ ] 新库的包体积是否可接受
- [ ] 新库是否有安全漏洞
- [ ] 新库的许可证是否兼容
- [ ] 新库的 TypeScript 类型是否完善

---

## 附录：常用库推荐清单

### 前端核心

| 功能 | 推荐库 | 备选 |
|------|--------|------|
| UI 框架 | React 18/19 | - |
| 组件库 | **Material UI (MUI)** — 强制使用，所有 UI 组件必须基于 MUI | shadcn/ui（仅概念参考） |
| 状态管理 | Zustand | Jotai、Valtio |
| 路由 | React Router | TanStack Router |
| 表单 | React Hook Form | Formik |
| 样式 | Tailwind CSS（仅辅助，禁止替代 MUI 组件） | CSS Modules |
| 图标 | Lucide React | React Icons |

### 数据处理

| 功能 | 推荐库 | 备选 |
|------|--------|------|
| 校验 | Zod | Yup、Joi |
| 日期 | date-fns | Day.js |
| UUID | nanoid | uuid |
| 深拷贝 | structuredClone | lodash.cloneDeep |
| 排序 | Array.sort + 自定义比较 | lodash.orderBy |

### 网络通信

| 功能 | 推荐库 | 备选 |
|------|--------|------|
| HTTP 客户端 | axios | ky、ofetch | Provider Adapter 层因需精细控制 SSE 流式解析，允许使用原生 fetch（见下方说明） |
| WebSocket | ws | socket.io-client |
| SSE | EventSource | fetch + ReadableStream |

### 存储持久化

| 功能 | 推荐库 | 备选 |
|------|--------|------|
| SQLite | sql.js | better-sqlite3 |
| 键值存储 | electron-store | conf |
| 缓存 | lru-cache | - |

### 开发工具

| 功能 | 推荐库 | 备选 |
|------|--------|------|
| 日志 | electron-log | winston |
| 测试 | Vitest | Jest |
| E2E 测试 | Playwright | Cypress |
| 代码检查 | ESLint | Biome |
| 格式化 | Prettier | Biome |
| 构建 | Vite | esbuild |

### AI/LLM 相关

| 功能 | 推荐库 | 备选 |
|------|--------|------|
| LLM SDK | Vercel AI SDK | LangChain.js |
| MCP 客户端 | @modelcontextprotocol/sdk | - |
| 嵌入模型 | @huggingface/transformers | - |
| 向量搜索 | sql.js (内存计算) | - |

---

> **记住**：代码是负债，库是资产。能用库解决的问题，绝不自己写。