thzxx
7e8b4882a0
P0 安全与工程基线（止血）: - .npmrc 移除硬编码 Gitea npm 凭据，改为 GITEA_NPM_AUTH 环境变量注入（已验证未设变量时 401） - 修复 typecheck 空操作缺陷：solution-style 根 tsconfig 改为双工程真检查（node + web）， pre-commit 与 CI 门禁恢复拦截能力 - 修复 4 处 v0.4.1 遗留类型错误：confirmation-hook.test 枚举名 FILE_SYSTEM→FILESYSTEM、 agent.ts VALIDATION 事件 severity 类型谓词收窄、ContextMenu.tsx 导出 attachments 类型 - 补装 v0.4.1 声明但未安装的 node-html-parser 依赖 P1 逻辑缺陷修复（跨模块边界）: - ConfirmationHook 会话隔离：rememberedDecisions 与 pendingConfirmations 按 sessionId 隔离， abortSession 只清本会话 pending（修复 A 会话中断误杀 B 会话确认、拒绝记忆跨会话污染） - SubAgent 可观测性：orchestrator 六个事件此前全项目零消费者，现接入 ① subagent:event 生命周期广播（AgentMonitor 新增 SubAgent 状态区） ② SubEngine 流事件独立 TRACE 录制（sessionId=taskId 的 JSONL 文件） - main.ts 启动链路异常兜底：初始化失败时记录日志 + 系统错误对话框 + 退出（原为白屏挂起） P2 工程强化: - CI：typecheck 双工程真检查；electron-test 从 experimental（continue-on-error）转正为阻塞门禁； GITEA_NPM_AUTH secret 注入说明 - 渲染 bundle 代码分割：单 2630KB chunk 拆为 main 557KB + vendor-react/mui/markdown/icons （业务代码变更不再使 vendor 缓存失效） - database 建表 mcp_servers CHECK 直接含 streamable-http（新库不再依赖迁移 6 立即重建） P3 功能补全: - DeepSeek 余额显示：新增 llm:getBalance IPC + LLMSettings 余额卡片（复用适配器原死代码 getBalance） - FTS5 会话内容搜索：messages_fts 虚表 + INSERT/UPDATE/DELETE 触发器实时同步 + 存量库 rebuild 迁移 + sessions:searchContent IPC + Sidebar 搜索框标题∪内容联合搜索 （短语转义防 FTS 运算符注入，按会话聚合展示 snippet） - 审计日志导出：audit:export IPC（JSONL / CSV RFC 4180 转义）+ LogsSettings 导出按钮 文档一致性大扫除: - README：工具数统一为 28（原 26/27/30 三口径）、handlers.ts→ipc/、录制事件名更正、 删除虚构的审计导出/归档宣称与 Schema 虚构字段、MCP 三种传输、配置 key 更正、 项目结构树对齐实际（settings 10 文件/lib 6 文件/react-virtuoso）、clone 地址改为 Gitea、 新增 GITEA_NPM_AUTH 配置说明、测试数 207 - 架构/构建指南/UI UX/IR 标准 4 份 HTML 设计文档同步修正（工具数、表数 10、 磁盘文件 2 个现状注记、ipc/*.ts 路径） - eslint.config.js 与开发规范.md 注释对齐零容忍基线与 better-sqlite3 选型 测试: 199→207 用例（新增 ConfirmationHook 跨会话隔离 5 用例 + FTS5 搜索/审计导出 8 用例） 验证: lint 0 problems / typecheck 双工程 0 errors / test:electron 207 全过 / build 成功
235 lines
8.8 KiB
Markdown
235 lines
8.8 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 | 需要类型安全、环境变量、默认值 |
|
||
| 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 | better-sqlite3（主进程同步 API，当前项目选型） | sql.js |
|
||
| 键值存储 | 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 (内存计算) | - |
|
||
|
||
---
|
||
|
||
> **记住**：代码是负债，库是资产。能用库解决的问题，绝不自己写。
|