MetonaTeam/metona-ai-desktop
2
0
Fork 0
Code Issues 51 Pull Requests Actions Packages Projects Releases 8 Wiki Activity
Files
8f687f77a6c5a650dfa7d2367d91421362742180
metona-ai-desktop/standard/开发规范.md
T
thzxx 1d185db6b3 feat: MetonaAI Desktop 初始项目 
- 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 导入导致黑屏
2026-06-27 21:33:27 +08:00

6.5 KiB
Raw Blame History

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
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 (内存计算) -

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

Reference in New Issue View Git Blame Copy Permalink