MetonaTeam/metona-ollama-desktop
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: 重写 README.md 适配 v2.0.0 TypeScript + Electron 架构

Browse Source
This commit is contained in:
thzxx
2026-04-06 03:24:52 +08:00
parent 0ec6e902de
commit d7543548d5
1 changed files with 115 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+115 -79
View File
@@ -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