From a742d3a5a58ae1605efcf4e0a1179769de7672ad Mon Sep 17 00:00:00 2001 From: thzxx Date: Sat, 25 Apr 2026 09:23:33 +0800 Subject: [PATCH] docs: rewrite README with bilingual CN/EN, icons, and verified features --- README.md | 684 ++++++++++++++++++++++++++---------------------------- 1 file changed, 329 insertions(+), 355 deletions(-) diff --git a/README.md b/README.md index f35e661..76439bb 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,12 @@

Metona Ollama Desktop

- 本地 AI 桌面客户端 — 基于 TypeScript + Electron，为 Ollama 而生 + 🤖 本地 AI 桌面客户端 · Local AI Desktop Client +

+ +

+ 中文 + English

@@ -17,67 +22,38 @@

- 所有 AI 推理均在本地完成，数据不离开本机。
- 零配置启动 · 全离线运行 · 暖色调 UI · 系统级集成 + 所有 AI 推理在本地完成，数据不离开本机。
+ All AI inference runs locally — data never leaves your machine.

--- -## ✨ 特性一览 +# 🇨🇳 中文 - - - - - -
+## ✨ 特性 -### 🤖 ReAct Agent Loop -Thought → Action → Observation → Reflection 完整循环，最大 85 轮迭代（可配置），支持自动重试、工具调用去重、并行/链式执行。 +| | 功能 | 说明 | +|:---:|:---|:---| +| 🤖 | **ReAct Agent Loop** | Thought → Action → Observation → Reflection 完整循环，最大 85 轮（可配置），自动重试 2 次，工具去重，并行/链式执行 | +| 🔧 | **38 个内置工具** | 文件系统 · 命令执行 · 联网搜索 · 浏览器控制 · Git · 记忆 · 技能 · 会话 · 子代理 | +| 🧠 | **智能记忆系统** | 三类记忆（fact / preference / rule），FTS5 全文搜索 + 向量语义搜索，写入前安全扫描，容量 500 条，90 天衰减 | +| 🌐 | **MCP 协议扩展** | JSON-RPC 2.0 over stdio，动态工具发现，Shadowing 防护 | +| 🔍 | **三引擎联网搜索** | Bing + 百度 + Google 聚合，web_search → web_fetch 链式抓取 | +| 🌏 | **浏览器控制** | 打开网页 · 截图 · 执行 JS · 提取内容 · 点击 · 输入 · 滚动 · 关闭 | +| 🖥️ | **工作空间面板** | 终端（实时流式输出）+ 文件浏览器，命令安全检查 | +| 📊 | **技能自动生成** | 从成功的工具调用链自动提取可复用技能（≥2 步），Level 0 摘要 | +| 🗜️ | **上下文管理** | 滑动窗口 + LLM 摘要压缩（50% 自动触发）+ /compress 手动触发 | +| 👥 | **子代理委派** | spawn_task 工具，独立上下文 + 超时保护 | +| ⏰ | **定时任务** | cron-manager，支持一次性/周期性调度 | +| 📈 | **Token 仪表盘** | 全局 + 会话统计，消耗趋势图，2 秒刷新 | +| 🎨 | **暖色调 UI** | 奶白 `#FAF7F2` + 珊瑚橙 `#E8734A`，长时间使用不疲劳 | +| 🔔 | **系统托盘** | 原生托盘集成 | +| 🔐 | **AES-256-GCM** | 数据加密支持 | -### 🔧 38 个内置工具 -文件系统 · 命令执行 · 联网搜索 · 浏览器控制 · Git · 记忆 · 技能 · 会话 · 子代理 - -### 🧠 智能记忆系统 -三类记忆（fact / preference / rule）+ FTS5 全文搜索 + 向量语义搜索，写入前自动安全扫描，容量管理 + 过期衰减。 - - - -### 🌐 MCP 协议扩展 -JSON-RPC 2.0 over stdio，动态工具发现与执行，Shadowing 防护，30 秒超时保护。 - -### 🔍 三引擎联网搜索 -Bing + 百度 + Google 聚合搜索，web_search → web_fetch 链式抓取，SPA 页面智能跳过。 - -### 🖥️ 工作空间面板 -终端（实时流式输出）+ 文件浏览器一体化，命令安全检查，三种执行模式。 - -
- ---- - -## 🎨 界面预览 - -

- Metona Logo -

- -| 设计元素 | 规范 | -|:---:|:---:| -| 背景色 | 奶白 `#FAF7F2` | -| 主色调 | 珊瑚橙 `#E8734A` | -| Think 标识 | 紫色 `#9B7ED8` | -| Token 标识 | 金色 `#D4A03C` | -| 终端区域 | 暖棕深色 `#2D2016` | -| 正文字体 | Inter | -| 代码字体 | JetBrains Mono | - ---- - -## 📦 工具清单 +## 🔧 工具清单
-文件系统（17 个） +📁 文件系统（17 个） | 工具 | 功能 | |------|------| @@ -102,16 +78,16 @@ Bing + 百度 + Google 聚合搜索，web_search → web_fetch 链式抓取，SP
-命令执行（1 个） +⚡ 命令执行（1 个） | 工具 | 功能 | |------|------| -| `run_command` | 执行 shell 命令，实时流式输出到工作空间终端，支持自动/需确认/禁用三种模式 | +| `run_command` | 执行 shell 命令，实时流式输出，支持自动/需确认/禁用三种模式 |
-联网搜索（2 个） +🔍 联网搜索（2 个） | 工具 | 功能 | |------|------| @@ -121,7 +97,7 @@ Bing + 百度 + Google 聚合搜索，web_search → web_fetch 链式抓取，SP
-浏览器控制（8 个） +🌐 浏览器控制（8 个） | 工具 | 功能 | |------|------| @@ -137,7 +113,7 @@ Bing + 百度 + Google 聚合搜索，web_search → web_fetch 链式抓取，SP
-Git（1 个，17 个子命令） +📦 Git（1 个，17 个子命令） | 子命令 | 功能 | |--------|------| @@ -148,7 +124,7 @@ Bing + 百度 + Google 聚合搜索，web_search → web_fetch 链式抓取，SP
-记忆管理（4 个） +🧠 记忆管理（4 个） | 工具 | 功能 | |------|------| @@ -160,337 +136,113 @@ Bing + 百度 + Google 聚合搜索，web_search → web_fetch 链式抓取，SP
-技能 / 会话 / 子代理（5 个） +📊 技能 / 会话 / 子代理（5 个） | 工具 | 功能 | |------|------| | `skill_list` | 列出已生成的技能 | -| `skill_view` | 查看技能详情（渐进式加载） | +| `skill_view` | 查看技能详情 | | `session_list` | 列出历史会话 | | `session_read` | 读取会话内容 | | `spawn_task` | 委派子代理（独立上下文 + 超时保护） |
---- - ## 🏗️ 架构 ``` -用户消息 - │ - ▼ -┌─────────────────────────────────────────────────────────┐ -│ Agent Engine (ReAct Loop) │ -│ Thought → Action → Observation → Reflection → 循环 │ -│ 最大 85 轮 · 自动重试 2 次 · 工具去重 · 并行执行 │ -└─────────────────┬───────────────────────────────────────┘ - │ - ┌─────────────┼─────────────────┐ - ▼ ▼ ▼ -┌────────┐ ┌──────────┐ ┌──────────────┐ -│ 记忆 │ │ 技能 │ │ 上下文管理 │ -│ FTS5 + │ │ 自动提取 │ │ 滑动窗口 + │ -│ 向量 │ │ Level 0 │ │ LLM 摘要压缩 │ -└────────┘ └──────────┘ └──────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────┐ -│ Ollama API（流式响应） │ -└─────────────────┬───────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────┐ -│ Tool Registry │ -│ 38 内置工具 + MCP 动态工具 │ -│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ -│ │ FS │ │ CMD │ │ Web │ │ Git │ │ Mem │ │ MCP │ ... │ -│ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ -└─────────────────┬───────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────┐ -│ SQLite (sql.js WASM) │ -│ sessions · messages · tool_calls · memories (FTS5) │ -│ settings · traces · skills │ -│ WAL 模式 · 零原生依赖 │ -└─────────────────────────────────────────────────────────┘ +用户消息 → Agent Engine (ReAct Loop, ≤85轮) + ↓ + 记忆检索 (FTS5 + 向量语义搜索) → 上下文注入 + ↓ + Ollama API (流式响应) + ↓ + Tool Registry (38 内置 + MCP 动态) + ↓ + 观察结果 → 反思 → 循环 / 最终回答 ``` ---- - -## 📂 项目结构 +### 🧩 UI 组件（原生 DOM） ``` -src/ -├── main/ # Electron 主进程 -│ ├── main.ts # 入口、窗口管理 -│ ├── preload.ts # contextBridge API（53 invoke + 2 send） -│ ├── ipc.ts # IPC 处理器（70+ 通道） -│ ├── workspace.ts # 子进程管理、流式输出 -│ ├── tool-handlers.ts # Tool Calling re-export -│ ├── tool-handlers-fs.ts # 17 个文件系统工具 -│ ├── tool-handlers-system.ts # 6 个系统网络工具 -│ ├── tool-handlers-git.ts # Git 工具 -│ ├── tool-handlers-shared.ts # 共享工具函数和类型 -│ ├── tool-security.ts # 路径/命令安全检查 -│ ├── browser.ts # 浏览器控制（8 个工具） -│ ├── mcp-manager.ts # MCP 协议管理（JSON-RPC 2.0 over stdio） -│ ├── menu.ts # 原生菜单 -│ ├── tray.ts # 系统托盘 -│ ├── utils.ts # 工具函数 -│ └── db/ -│ └── sqlite.ts # SQLite 数据库层（7 张表 + FTS5） -│ -├── renderer/ # 渲染进程 -│ ├── main.ts # 入口、全局初始化 -│ ├── index.html # 入口 HTML -│ ├── types.d.ts # 完整类型定义 -│ ├── api/ -│ │ └── ollama.ts # Ollama REST API 客户端 -│ ├── services/ -│ │ ├── agent-engine.ts # ReAct Agent Loop 引擎 -│ │ ├── tool-registry.ts # 工具注册与调度（38 + MCP 动态） -│ │ ├── memory-manager.ts # 记忆管理核心 -│ │ ├── vector-memory.ts # 记忆向量索引（IVF） -│ │ ├── vector-store.ts # 向量存储 + IVF 索引 -│ │ ├── context-manager.ts # 上下文窗口管理（自动/手动压缩） -│ │ ├── skill-manager.ts # 技能自动生成（Level 0） -│ │ ├── sub-agent.ts # 子代理委派 -│ │ ├── cron-manager.ts # 定时任务 -│ │ ├── mcp-client.ts # MCP 渲染端客户端 -│ │ ├── document-processor.ts # 文档分块 -│ │ ├── log-service.ts # 结构化日志 -│ │ └── crypto.ts # AES-256-GCM 加密 -│ ├── components/ # 14 个 UI 组件 -│ ├── utils/ -│ │ ├── utils.ts # 工具函数 -│ │ ├── sanitizer.ts # HTML 净化器 -│ │ └── marked-config.ts # Markdown 渲染配置 -│ ├── state/ -│ │ └── state.ts # 响应式状态管理 -│ ├── db/ -│ │ └── chat-db.ts # SQLite 渲染端接口 -│ └── styles/ -│ └── style.css # 暖色调亮色主题 -│ -├── vendor/ # 第三方库本地化 -│ ├── marked.js # Markdown 解析 -│ ├── marked.d.ts -│ ├── dompurify.js # HTML 净化 -│ └── dompurify.d.ts -│ -├── tsconfig.json # 渲染进程 TS 配置 -├── tsconfig.main.json # 主进程 TS 配置 -├── vite.config.ts # Vite 构建配置 -└── package.json +main.ts (入口) + ├── header.ts # 顶部导航栏 + ├── model-bar.ts # 模型选择栏 + ├── chat-area.ts # 聊天消息区域 + ├── input-area.ts # 输入框 + 文件上传 + ├── workspace-panel.ts # 终端 + 文件浏览器 + ├── log-panel.ts # 结构化日志面板 + ├── settings-modal.ts # 设置面板 + ├── history-modal.ts # 会话历史 + ├── memory-modal.ts # 记忆管理 + ├── tools-modal.ts # 工具列表 + ├── token-dashboard.ts # Token 消耗仪表盘 + ├── tool-confirm-modal.ts # 工具执行确认 + ├── toast.ts # Toast 通知 + └── lightbox.ts # 图片灯箱 ``` ---- +### 🗄️ 数据库 -## 🚀 快速开始 +SQLite (sql.js WASM)，7 张表，WAL 模式 + FTS5 全文搜索： -### 环境要求 - -| 依赖 | 版本 | -|------|------| -| Node.js | ≥ 22 | -| npm | ≥ 10 | -| Ollama | 本地运行中（默认 `http://localhost:11434`） | - -### 开发运行 - -```bash -# 克隆项目 -git clone https://gitee.com/thzxx/metona-ollama-desktop.git -cd metona-ollama-desktop -git checkout desktop-v1-stable-release - -# 设置 npm 镜像 -npm config set registry https://registry.npmmirror.com - -# 安装依赖 -npm install - -# 开发运行 -npm start -``` - -### 构建 Windows 安装包 - -```bash -# 环境：Ubuntu 24.04 + Wine 9.0+ -# 1. 恢复构建缓存（首次 ~145MB） -bash restore-build-cache.sh - -# 2. 构建 -ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist -``` - -产出文件：`release/Metona Ollama Setup v1-stable-release.exe` - ---- - -## 🗄️ 数据库设计 - -项目使用 **sql.js (WASM)** 实现零原生依赖的 SQLite 存储，WAL 模式 + NORMAL 同步。 - -### 表结构 - -| 表 | 用途 | 关键特性 | -|:---|:---|:---| -| `sessions` | 会话 | `parent_id` 父子关系 | -| `messages` | 消息 | 外键级联删除，`thinking` / `tool_calls` 字段 | -| `tool_calls` | 工具调用记录 | 按会话 + 工具名索引 | -| `memories` | Agent 记忆 | FTS5 全文搜索 + 向量嵌入，容量上限 500 | -| `settings` | 设置 | JSON 序列化 | -| `traces` | ReAct 执行轨迹 | Agent 可观测性 | -| `skills` | 自动生成的技能 | 成功/失败次数、平均时长、summary 字段 | - -### FTS5 全文搜索 - -```sql -CREATE VIRTUAL TABLE memories_fts USING fts5( - content, tags, source, - content='memories', - content_rowid='rowid' -); -``` - ---- - -## 🧠 记忆系统 - -### 三种记忆类型 - -| 类型 | 图标 | 注入策略 | 适用场景 | -|:---:|:---:|:---|:---| -| `fact` | 📌 | 按需检索 | 项目信息、个人背景、技术栈 | -| `preference` | ⚙️ | 按需检索 | 语言偏好、输出风格、格式习惯 | -| `rule` | 📏 | **始终注入** | 行为准则、安全红线、铁律 | - -### 记忆生命周期 - -``` -用户对话 → 自动提取 → 安全扫描 → 存储（FTS5 + 向量） - │ -用户提问 → 语义检索 → 相关记忆注入上下文 → Agent 使用 - │ - 90 天未使用 → 自动衰减 importance - 超过 500 条 → 自动清理低价值条目 -``` - -### 安全扫描 - -写入前自动检测： -- Prompt Injection 攻击模式 -- 敏感信息泄露（密钥、Token、密码） -- 不可见 Unicode 字符 - ---- - -## ⚡ 上下文管理 - -### 三层策略 - -``` -┌─────────────────────────────────────┐ -│ 滑动窗口 │ 保留首尾各 N 条消息 │ -├─────────────────────────────────────┤ -│ LLM 压缩 │ 中间轮次摘要为 1-2 条 │ -├─────────────────────────────────────┤ -│ 记忆注入 │ FTS5 + 向量检索注入 │ -└─────────────────────────────────────┘ -``` - -- **自动压缩阈值**：消息 token 占 context window 50% 时触发 -- **手动压缩**：`/compress` 命令 -- **Token 估算**：中文 1.5 字/token，英文 4 字符/token - ---- +| 表 | 用途 | +|---|---| +| `sessions` | 会话（parent_id 父子关系） | +| `messages` | 消息（外键级联删除） | +| `tool_calls` | 工具调用记录 | +| `memories` | Agent 记忆（FTS5 + 向量嵌入） | +| `settings` | 设置（JSON 序列化） | +| `traces` | ReAct 执行轨迹 | +| `skills` | 自动生成的技能 | ## 🔒 安全机制 | 层级 | 措施 | |------|------| -| 文件系统 | `checkPathAllowed()` — 路径黑名单（`/etc`, `/sys`, `/proc`, `~/.ssh` 等） | -| 命令执行 | `checkCommandAllowed()` — 命令黑名单 + 三种模式（自动/需确认/禁用） | -| 前端渲染 | HTML 净化器（白名单标签 + 属性过滤 + URI 协议检查） | -| Electron | `contextIsolation: true` + IPC 白名单 | -| 数据加密 | AES-256-GCM | -| 记忆安全 | 写入前 Prompt Injection / 敏感信息 / 不可见字符检测 | -| MCP 安全 | Shadowing 防护（MCP 工具不能覆盖内置工具名） | +| 📁 文件系统 | `checkPathAllowed()` — 路径黑名单 | +| ⚡ 命令执行 | `checkCommandAllowed()` — 命令黑名单 + 三种模式 | +| 🖥️ 前端渲染 | HTML 净化器（白名单标签 + URI 协议检查） | +| 🔒 Electron | `contextIsolation: true` + IPC 白名单 | +| 🔐 数据加密 | AES-256-GCM | +| 🧠 记忆安全 | 写入前 Prompt Injection / 敏感信息检测 | +| 🌐 MCP 安全 | Shadowing 防护 | ---- +## 🚀 快速开始 + +```bash +git clone https://gitee.com/thzxx/metona-ollama-desktop.git +cd metona-ollama-desktop +git checkout desktop-v1-stable-release +npm config set registry https://registry.npmmirror.com +npm install +npm start +``` + +## 📦 构建 Windows 安装包 + +```bash +# 环境：Ubuntu 24.04 + Node.js v22 + Wine 9.0+ +ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist +``` + +产出：`release/Metona Ollama Setup v1-stable-release.exe` ## 🛠️ 常用命令 ```bash -npm start # 构建并运行（开发） -npm run dev:renderer # Vite watch 模式（渲染进程） -npm run dev:main # tsc watch 模式（主进程） +npm start # 构建并运行 +npm run dev:renderer # Vite watch（渲染进程） +npm run dev:main # tsc watch（主进程） npm run build # 完整构建 -npm run build:renderer # 仅渲染进程 -npm run build:main # 仅主进程 -npm run pack # 构建目录（不打包） -npm run dist # 构建 Windows NSIS 安装包 -npm run dist:nsis # 同上 +npm run dist # 构建 Windows 安装包 ``` ---- +## 💻 系统要求 -## 📋 版本号更新清单 - -更新版本号时需同步修改以下 **7 个文件**： - -| 文件 | 修改内容 | -|------|----------| -| `package.json` | `"version": "X.Y.Z"` | -| `package-lock.json` | 顶层 version 字段（2 处） | -| `src/renderer/index.html` | `vX.Y.Z` | -| `README.md` | 版本徽章、下载文件名 | -| `docs/BUILD.md` | 构建分支引用 | -| `docs/CHANGELOG.md` | 新增版本条目 | -| `docs/DEVELOPMENT.md` | 文件头部版本号 | - ---- - -## 🌿 Git 规范 - -### 分支模型 - -``` -master ← 稳定发布 -develop ← 开发主分支 -metona-ollama-desktop-vX.Y.Z ← 版本发布分支 -feature/* ← 功能开发 -fix/* ← Bug 修复 -``` - -### Commit 规范 - -| 前缀 | 用途 | -|------|------| -| `feat:` | 新功能 | -| `fix:` | Bug 修复 | -| `refactor:` | 重构 | -| `style:` | 样式调整 | -| `docs:` | 文档更新 | -| `chore:` | 构建/工具变更 | -| `perf:` | 性能优化 | - ---- - -## 📖 技术文档 - -项目详细技术文档位于 `docs/` 目录： - -| 文档 | 内容 | -|------|------| -| [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | 开发规范、代码规范、架构设计 | -| [`docs/BUILD.md`](docs/BUILD.md) | Windows 安装包构建指南、故障排查 | - ---- +- 🖥️ Windows 10/11（64 位） +- 🤖 Ollama 本地运行中（默认 `http://localhost:11434`） +- 💾 建议 8GB+ 内存 ## 📄 许可证 @@ -498,6 +250,228 @@ fix/* ← Bug 修复 --- +# 🇬🇧 English + +## ✨ Features + +| | Feature | Description | +|:---:|:---|:---| +| 🤖 | **ReAct Agent Loop** | Full Thought → Action → Observation → Reflection cycle, up to 85 iterations (configurable), auto-retry 2 times, tool dedup, parallel/chain execution | +| 🔧 | **38 Built-in Tools** | File system · Command · Web search · Browser · Git · Memory · Skills · Sessions · Sub-agent | +| 🧠 | **Smart Memory System** | Three types (fact / preference / rule), FTS5 + vector semantic search, pre-write security scan, 500 capacity, 90-day decay | +| 🌐 | **MCP Protocol Extension** | JSON-RPC 2.0 over stdio, dynamic tool discovery, Shadowing protection | +| 🔍 | **Triple-engine Web Search** | Bing + Baidu + Google aggregation, web_search → web_fetch chain | +| 🌏 | **Browser Control** | Open pages · Screenshot · JS execution · Content extraction · Click · Type · Scroll · Close | +| 🖥️ | **Workspace Panel** | Terminal (real-time streaming) + file browser, command security checks | +| 📊 | **Auto Skill Generation** | Extracts reusable skills from successful tool call chains (≥2 steps), Level 0 summaries | +| 🗜️ | **Context Management** | Sliding window + LLM summary compression (auto at 50%) + /compress manual trigger | +| 👥 | **Sub-agent Delegation** | spawn_task tool, isolated context + timeout protection | +| ⏰ | **Cron Tasks** | cron-manager, one-time and periodic scheduling | +| 📈 | **Token Dashboard** | Global + session stats, consumption trend chart, 2s refresh | +| 🎨 | **Warm-tone UI** | Cream `#FAF7F2` + coral `#E8734A`, fatigue-free for extended use | +| 🔔 | **System Tray** | Native tray integration | +| 🔐 | **AES-256-GCM** | Data encryption support | + +## 🔧 Tool List + +
+📁 File System (17) + +| Tool | Function | +|------|------| +| `read_file` | Read file content | +| `write_file` | Write file | +| `list_directory` | List directory contents | +| `search_files` | Search files (regex/wildcard) | +| `create_directory` | Create directory | +| `delete_file` | Delete file | +| `move_file` | Move/rename file | +| `copy_file` | Copy file | +| `append_file` | Append content to file | +| `edit_file` | Edit file (find & replace) | +| `get_file_info` | Get file metadata | +| `tree` | Directory tree structure | +| `download_file` | Download file | +| `diff_files` | File diff comparison | +| `replace_in_files` | Batch replace | +| `read_multiple_files` | Batch read | +| `compress` | Compress file/directory | + +
+ +
+⚡ Command Execution (1) + +| Tool | Function | +|------|------| +| `run_command` | Execute shell command, real-time streaming, auto/confirm/disabled modes | + +
+ +
+🔍 Web Search (2) + +| Tool | Function | +|------|------| +| `web_search` | Triple-engine search (Bing + Baidu + Google), returns title, URL, snippet, 15 results | +| `web_fetch` | Fetch web page content, no truncation | + +
+ +
+🌐 Browser Control (8) + +| Tool | Function | +|------|------| +| `browser_open` | Open web page | +| `browser_screenshot` | Page screenshot | +| `browser_evaluate` | Execute JavaScript | +| `browser_extract` | Extract page content | +| `browser_click` | Click element | +| `browser_type` | Type text | +| `browser_scroll` | Scroll page | +| `browser_close` | Close browser | + +
+ +
+📦 Git (1 tool, 17 subcommands) + +| Subcommands | Function | +|--------|------| +| `init` `clone` `add` `commit` `push` `pull` | Basic operations | +| `diff` `log` `status` `branch` `checkout` | View & switch | +| `merge` `stash` `reset` `tag` `remote` | Advanced operations | + +
+ +
+🧠 Memory Management (4) + +| Tool | Function | +|------|------| +| `memory_search` | Search memories (FTS5 + vector semantic) | +| `memory_add` | Add memory (auto security scan) | +| `memory_replace` | Modify memory | +| `memory_remove` | Delete memory | + +
+ +
+📊 Skills / Sessions / Sub-agent (5) + +| Tool | Function | +|------|------| +| `skill_list` | List generated skills | +| `skill_view` | View skill details | +| `session_list` | List session history | +| `session_read` | Read session content | +| `spawn_task` | Delegate sub-agent (isolated context + timeout) | + +
+ +## 🏗️ Architecture + +``` +User message → Agent Engine (ReAct Loop, ≤85 rounds) + ↓ + Memory Retrieval (FTS5 + Vector Semantic Search) → Context Injection + ↓ + Ollama API (Streaming Response) + ↓ + Tool Registry (38 Built-in + MCP Dynamic) + ↓ + Observation → Reflection → Loop / Final Answer +``` + +### 🧩 UI Components (Native DOM) + +``` +main.ts (Entry) + ├── header.ts # Top navigation bar + ├── model-bar.ts # Model selector + ├── chat-area.ts # Chat message area + ├── input-area.ts # Input box + file upload + ├── workspace-panel.ts # Terminal + file browser + ├── log-panel.ts # Structured log panel + ├── settings-modal.ts # Settings panel + ├── history-modal.ts # Session history + ├── memory-modal.ts # Memory management + ├── tools-modal.ts # Tool list + ├── token-dashboard.ts # Token consumption dashboard + ├── tool-confirm-modal.ts # Tool execution confirmation + ├── toast.ts # Toast notifications + └── lightbox.ts # Image lightbox +``` + +### 🗄️ Database + +SQLite (sql.js WASM), 7 tables, WAL mode + FTS5 full-text search: + +| Table | Purpose | +|---|---| +| `sessions` | Sessions (parent_id hierarchy) | +| `messages` | Messages (cascade delete) | +| `tool_calls` | Tool call records | +| `memories` | Agent memories (FTS5 + vector embedding) | +| `settings` | Settings (JSON serialization) | +| `traces` | ReAct execution traces | +| `skills` | Auto-generated skills | + +## 🔒 Security + +| Layer | Measure | +|------|------| +| 📁 File System | `checkPathAllowed()` — path blacklist | +| ⚡ Command Execution | `checkCommandAllowed()` — command blacklist + three modes | +| 🖥️ Frontend Rendering | HTML sanitizer (whitelist tags + URI protocol check) | +| 🔒 Electron | `contextIsolation: true` + IPC whitelist | +| 🔐 Data Encryption | AES-256-GCM | +| 🧠 Memory Security | Pre-write prompt injection / sensitive info detection | +| 🌐 MCP Security | Shadowing protection | + +## 🚀 Quick Start + +```bash +git clone https://gitee.com/thzxx/metona-ollama-desktop.git +cd metona-ollama-desktop +git checkout desktop-v1-stable-release +npm config set registry https://registry.npmmirror.com +npm install +npm start +``` + +## 📦 Build Windows Installer + +```bash +# Environment: Ubuntu 24.04 + Node.js v22 + Wine 9.0+ +ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist +``` + +Output: `release/Metona Ollama Setup v1-stable-release.exe` + +## 🛠️ Common Commands + +```bash +npm start # Build and run +npm run dev:renderer # Vite watch (renderer) +npm run dev:main # tsc watch (main process) +npm run build # Full build +npm run dist # Build Windows installer +``` + +## 💻 System Requirements + +- 🖥️ Windows 10/11 (64-bit) +- 🤖 Ollama running locally (default `http://localhost:11434`) +- 💾 8GB+ RAM recommended + +## 📄 License + +[MIT](LICENSE) + +--- +

Made with ❤️ by thzxx