From d7543548d52e2a35040175e7dbc759eadb084f8f Mon Sep 17 00:00:00 2001 From: thzxx Date: Mon, 6 Apr 2026 03:24:52 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README.md=20?= =?UTF-8?q?=E9=80=82=E9=85=8D=20v2.0.0=20TypeScript=20+=20Electron=20?= =?UTF-8?q?=E6=9E=B6=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 194 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 115 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 1108256..b6af8a9 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # 🦙 Metona Ollama -基于原生 JavaScript 的 [Ollama](https://ollama.com) AI 聊天客户端。Web 版零依赖开箱即用，桌面版基于 Electron 封装，支持 Windows。 +基于 TypeScript + Electron 的 [Ollama](https://ollama.com) 桌面 AI 聊天客户端，专为 Windows 打造。 -![版本](https://img.shields.io/badge/version-1.1.0--desktop-brightgreen) -![平台](https://img.shields.io/badge/platform-Windows%20%7C%20Web-blue) +![版本](https://img.shields.io/badge/version-2.0.0--desktop-brightgreen) +![平台](https://img.shields.io/badge/platform-Windows%20x64-blue) +![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6) ![Electron](https://img.shields.io/badge/Electron-33-47848f) +![Vite](https://img.shields.io/badge/Vite-5-646cff) ![协议](https://img.shields.io/badge/license-MIT-green) --- @@ -33,12 +35,7 @@ - 导出格式：Markdown / HTML / TXT / JSON / .metona 加密备份 - .metona 格式支持 AES-256-GCM 加密（HTTPS）或 XOR 混淆（HTTP） ---- - -## 🖥️ 桌面版 - -基于 Electron 封装，Windows 专用，在 Web 版全部功能基础上增加原生特性。 - +### 🖥️ 桌面原生 | 特性 | 说明 | |------|------| | Fluent Design 主题 | Windows 11 暗色风格，Mica 毛玻璃材质 | @@ -50,58 +47,126 @@ | 单实例锁 | 防止重复启动 | | 无 CORS 限制 | 直连本地 Ollama，无需配置 OLLAMA_ORIGINS | -### 下载 +--- + +## 📥 下载 从 [Releases](https://gitee.com/thzxx/metona-ollama/releases) 页面下载： | 文件 | 类型 | |------|------| -| `Metona Ollama Setup 1.1.0.exe` | NSIS 安装包（可选目录、创建快捷方式） | -| `MetonaOllama-Portable-1.1.0.exe` | 绿色便携版（免安装，双击即用） | +| `Metona Ollama Setup 2.0.0.exe` | NSIS 安装包（可选目录、创建快捷方式） | +| `MetonaOllama-Portable-2.0.0.exe` | 绿色便携版（免安装，双击即用） | > ⚠️ 未签名版本，首次运行 Windows 可能弹出安全警告，点击「仍要运行」即可。 -### 从源码构建桌面版 +--- + +## 🔨 从源码构建 + +### 环境要求 + +- Node.js v22+ +- Windows 或 Linux（交叉编译需 Wine 9.0+） + +### 构建步骤 ```bash git clone https://gitee.com/thzxx/metona-ollama.git cd metona-ollama -git checkout metona-ollama-desktop-v1.1 +git checkout metona-ollama-desktop-v2 + +# 安装依赖（国内使用 npmmirror 加速） npm config set registry https://registry.npmmirror.com npm install -npm start # 开发运行 -ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist # 构建 Windows 安装包 + +# 构建 TypeScript +npm run build + +# 开发运行 +npm start + +# 构建 Windows 安装包 +ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist ``` -> 💡 国内环境需使用 npmmirror 加速，详见 [BUILD.md](BUILD.md)。 +> 💡 Linux 交叉编译 Windows 安装包需安装 Wine：`apt install wine` + +### 常用命令 + +```bash +npm run build:renderer # 仅构建渲染进程（Vite） +npm run build:main # 仅构建主进程（tsc） +npm run build # 构建全部 +npm start # 构建并运行 +npm run dist # 构建 Windows 安装包（NSIS + Portable） +npm run dist:nsis # 仅 NSIS 安装包 +npm run dist:portable # 仅便携版 +``` + +### 构建产物 + +| 文件 | 说明 | +|------|------| +| `release/Metona Ollama Setup 2.0.0.exe` | NSIS 安装包 | +| `release/MetonaOllama-Portable-2.0.0.exe` | 绿色便携版 | +| `dist/main/` | 主进程编译输出 | +| `dist/renderer/` | 渲染进程构建输出 | --- -## 🌐 Web 版 +## 📁 项目结构 -零构建步骤，纯 HTML + ES Modules，任何 HTTP 服务器即可托管。 - -```bash -git clone https://gitee.com/thzxx/metona-ollama.git -cd metona-ollama - -# 方式一：直接浏览器打开 -open index.html - -# 方式二：HTTP 服务器 -python3 -m http.server 8080 -# 访问 http://localhost:8080 ``` - -**跨域配置**（Web 版需要）： -```bash -OLLAMA_ORIGINS="*" ollama serve +metona-ollama/ +├── src/ +│ ├── main/ # Electron 主进程（TypeScript） +│ │ ├── main.ts # 应用入口、窗口管理、生命周期 +│ │ ├── preload.ts # contextBridge 安全暴露 +│ │ ├── menu.ts # 原生菜单系统 +│ │ ├── tray.ts # 系统托盘 +│ │ ├── ipc.ts # IPC 处理器 +│ │ └── utils.ts # 主进程工具函数 +│ └── renderer/ # 渲染进程（TypeScript） +│ ├── index.html # 渲染进程入口 HTML +│ ├── main.ts # 渲染进程入口 +│ ├── types.d.ts # 完整类型定义 +│ ├── api/ +│ │ └── ollama.ts # Ollama REST API 封装 +│ ├── db/ +│ │ └── chat-db.ts # IndexedDB 持久化 +│ ├── state/ +│ │ └── state.ts # 响应式状态管理 +│ ├── components/ # UI 组件 +│ │ ├── chat-area.ts # 消息渲染、流式更新 +│ │ ├── input-area.ts # 输入、文件上传 +│ │ ├── header.ts # 顶部导航 +│ │ ├── model-bar.ts # 模型选择栏 +│ │ ├── settings-modal.ts +│ │ ├── history-modal.ts +│ │ ├── kb-modal.ts # 知识库管理 +│ │ ├── preset-bar.ts # Agent 预设栏 +│ │ ├── toast.ts # 通知组件 +│ │ └── lightbox.ts # 图片预览 +│ ├── services/ +│ │ ├── rag.ts # RAG 检索增强生成 +│ │ ├── vector-store.ts # 向量存储 + 相似度搜索 +│ │ ├── document-processor.ts +│ │ ├── preset-manager.ts +│ │ └── crypto.ts # AES-256-GCM / XOR 加密 +│ ├── utils/ +│ │ ├── utils.ts # 工具函数 +│ │ ├── sanitizer.ts # HTML 净化器 +│ │ └── marked-config.ts # Markdown 配置 +│ └── styles/ +│ └── style.css # Windows 11 Fluent Design 样式 +├── assets/icons/ # 图标资源 +├── vite.config.ts # Vite 构建配置 +├── tsconfig.json # 渲染进程 TypeScript 配置 +├── tsconfig.main.json # 主进程 TypeScript 配置 +└── package.json # 项目配置 + electron-builder 打包 ``` -### PWA 离线使用 - -Web 版内置 Service Worker，可安装到桌面离线使用（桌面版无需此功能）。 - --- ## 🔌 Ollama API 接口 @@ -117,42 +182,6 @@ Web 版内置 Service Worker，可安装到桌面离线使用（桌面版无需 --- -## 📁 项目结构 - -``` -metona-ollama/ -├── index.html # 入口页面 -├── electron/ # 桌面版（Electron） -│ ├── main.js # 主进程：窗口、托盘、菜单、IPC -│ ├── preload.js # Preload：contextBridge 安全暴露 -│ ├── desktop-bridge.js # 渲染进程桥接 + Web 降级 -│ └── desktop-integration.js # 菜单响应、原生文件对话框 -├── js/ -│ ├── app.js # 主入口 -│ ├── ollama-api.js # Ollama REST API 封装 -│ ├── chat-db.js # IndexedDB 持久化 -│ ├── state.js # 响应式状态管理 -│ ├── rag.js # RAG 检索增强生成 -│ ├── vector-store.js # 向量存储 + 相似度搜索 -│ ├── document-processor.js # 文档分块 -│ ├── preset-manager.js # Agent 预设管理 -│ ├── crypto.js # 会话加密（AES-256-GCM / XOR） -│ └── components/ # UI 组件 -│ ├── chat-area.js # 消息渲染、流式更新 -│ ├── input-area.js # 输入、文件上传 -│ ├── settings-modal.js # 设置面板 -│ ├── history-modal.js # 历史记录 -│ ├── kb-modal.js # 知识库管理 -│ └── ... -├── css/style.css # 全局样式（暗色主题） -├── assets/icons/ # 图标资源 -├── package.json # Electron + electron-builder 配置 -├── sw.js # Service Worker（PWA） -└── manifest.json # PWA 清单 -``` - ---- - ## ⚙️ 设置 | 设置 | 默认值 | API 参数 | @@ -167,8 +196,9 @@ metona-ollama/ ## 🛠️ 技术栈 -- **纯原生 JavaScript** (ES Modules) — 零构建步骤 -- **Electron 33** — 桌面封装（Windows） +- **TypeScript 5.7** — 严格类型，完整接口定义 +- **Electron 33** — 桌面封装（Windows x64） +- **Vite 5** — 渲染进程构建、HMR 热更新 - **IndexedDB** — 异步持久化 - **Fetch + ReadableStream** — 流式 NDJSON 解析 - **CSS Variables** — 暗色主题，毛玻璃效果 @@ -181,17 +211,23 @@ metona-ollama/ - 内置 HTML 净化器（白名单标签 + 属性过滤 + URI 协议检查） - Markdown 链接仅允许 `http:` / `https:` / `mailto:` / `tel:` - 阻止 `javascript:` / `vbscript:` / `data:` 协议注入 -- 桌面版：contextIsolation + IPC 白名单 + 单实例锁 +- contextIsolation + IPC 白名单 + 单实例锁 --- ## 📋 更新日志 +### v2.0.0 +- ⚡ **TypeScript 全面重写** — 所有代码从 JavaScript 迁移至 TypeScript，严格类型定义 +- 🏗️ **Vite 构建系统** — 替代零构建，支持模块化打包 +- 🖥️ **纯桌面版** — 放弃 Web/PWA 支持，全面专注 Electron 桌面体验 +- 🧩 **主进程模块化** — 按职责拆分为独立模块（menu/tray/ipc/preload/utils） +- 🗑️ 移除 sw.js、manifest.json、desktop-bridge.js 等 Web 相关代码 + ### v1.1.0 - 🎨 UI 重构为 Windows 11 Fluent Design 暗色主题（Mica 材质、Segoe UI Variable） - 📐 知识库/历史记录弹框加宽 -- ✨ Think 按钮开启后添加蓝色光效，hover 时增强 -- 🖱️ 图片上传禁用态添加 hover 标识（微红背景 + 禁止光标） +- ✨ Think 按钮开启后添加蓝色光效 - 🚫 彻底隐藏窗口菜单栏 ### v1.0.0