MetonaTeam/metona-ai-desktop

Fork 0

Files

T

thzxx 7e8b4882a0

CI / 类型检查 + Lint + 单元测试 (push) Failing after 5m38s

Details

CI / 产物编译验证 (push) Successful in 10m15s

Details

CI / 全量测试 (Electron ABI) (push) Failing after 5m27s

Details

feat: v0.5.0 审计修复版 — 类型基线重建 + 会话隔离 + SubAgent 可观测性 + 三项功能补全

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 成功

2026-08-21 21:07:01 +08:00

8.8 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	需要类型安全、环境变量、默认值
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` 四种，不得自定义
并行事件防风暴	同一来源的并行事件（如多工具超时）需在后端节流，不得依赖前端去重

原因：

统一视觉风格与动画效果
集中管理 Toast 队列、堆叠顺序、自动消失时间
避免 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
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 (内存计算)	-

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

8.8 KiB Raw Blame History Unescape Escape

Metona 开发规范

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

核心原则

规范细则

1. 优先级顺序

2. 判断标准

3. 禁止自写的场景

3.1 UI 组件铁律

3.2 Toast 通知铁律

4. 允许自写的场景

5. 引入新库的流程

违规处理

代码审查检查清单

附录：常用库推荐清单

前端核心

数据处理

网络通信

存储持久化

开发工具

AI/LLM 相关

8.8 KiB

Raw Blame History