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
commit 1d185db6b3
109 changed files with 39155 additions and 0 deletions
@@ -0,0 +1,194 @@
+# 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 (内存计算) | - |
+
+---
+
+> **记住**：代码是负债，库是资产。能用库解决的问题，绝不自己写。