thzxx
1d185db6b3
- Electron + React + TypeScript 架构 - 三栏布局: Sidebar | ChatPanel | DetailPanel - 9 个内置工具 (文件系统/网络/记忆/命令) - SQLite 持久化 (better-sqlite3) - MUI 暗色/亮色主题系统 - Agent Loop ReAct 状态机引擎 - DeepSeek / Agnes AI / Ollama Provider 适配器 - MCP 协议集成 - 系统托盘 + 全局快捷键 - Tailwind CSS v4 + Tailwind Merge - 修复: Sidebar 缺失 TextField 导入导致黑屏
195 lines
6.5 KiB
Markdown
195 lines
6.5 KiB
Markdown
# 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 | 需要类型安全、环境变量、默认值 |
|
||
|
||
#### 4. 允许自写的场景
|
||
|
||
以下场景可以自写实现，但需满足条件：
|
||
|
||
| 场景 | 条件 |
|
||
|------|------|
|
||
| 简单工具函数 | < 20 行，无依赖，纯函数 |
|
||
| 业务逻辑封装 | 特定于项目的业务规则 |
|
||
| 类型定义 | 项目特有的接口和类型 |
|
||
| 适配器/桥接层 | 连接不同库的中间层 |
|
||
| 简单 UI 组件 | < 50 行，无复杂交互 |
|
||
| 配置常量 | 项目特有的配置值 |
|
||
| 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 | - |
|
||
| 状态管理 | Zustand | Jotai、Valtio |
|
||
| 路由 | React Router | TanStack Router |
|
||
| 表单 | React Hook Form | Formik |
|
||
| 样式 | Tailwind CSS | CSS Modules |
|
||
| 组件库 | shadcn/ui | Radix UI |
|
||
| 图标 | 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 (内存计算) | - |
|
||
|
||
---
|
||
|
||
> **记住**：代码是负债，库是资产。能用库解决的问题，绝不自己写。
|