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

docs: 重写 README.md 适配 Agent 记忆系统 + Tool Calling 双引擎架构

Browse Source
This commit is contained in:
thzxx
2026-04-06 13:48:22 +08:00
parent dc43db7d9c
commit eba5098728
1 changed files with 169 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+169 -97
View File
@@ -28,32 +28,48 @@ AI 可以在对话中主动调用本地工具来完成任务，所有操作在
| 📄 `read_file` | 读取文件内容（≤1MB，支持行范围） | 自动 | | 📄 `read_file` | 读取文件内容（≤1MB，支持行范围） | 自动 |
| ✏️ `write_file` | 写入文件（自动创建父目录） | 需确认 | | ✏️ `write_file` | 写入文件（自动创建父目录） | 需确认 |
| 📁 `list_directory` | 列出目录（支持递归、隐藏文件） | 自动 | | 📁 `list_directory` | 列出目录（支持递归、隐藏文件） | 自动 |
| 🔍 `search_files` | 按文件名/内容搜索（支持正则、扩展名过滤） | 自动 | | 🔍 `search_files` | 按文件名/内容搜索（支持扩展名过滤） | 自动 |
| 📂 `create_directory` | 创建目录（递归创建） | 需确认 | | 📂 `create_directory` | 创建目录（递归创建） | 需确认 |
| 🗑️ `delete_file` | 删除文件/目录 | 需确认 | | 🗑️ `delete_file` | 删除文件/目录 | 需确认 |
| 💻 `run_command` | 执行 Shell 命令（默认禁用） | 需确认 | | 💻 `run_command` | 执行 Shell 命令（默认禁用） | 需确认 |
**Agent Loop**：用户请求 → 模型返回 tool_calls → 客户端执行 → 回传结果 → 循环直到无工具调用，支持流式 + 并行调用 + 最大 10 轮保护。 **Agent Loop**：用户请求 → 模型返回 tool_calls → 客户端执行 → 回传结果 → 循环直到无工具调用，支持流式 + 并行调用 + 最大 10 轮保护。
**安全模型**：
- 路径白名单/黑名单（自动屏蔽 `/etc`, `/sys`, `.ssh` 等）
- 命令黑名单（`rm -rf /`, `mkfs`, 反弹 shell 检测等）
- 高风险操作弹出确认对话框（内容预览 + 一键取消）
- 系统提示词自动注入安全规则
> ⚠️ 需要模型支持 Tool Calling（推荐 Qwen3、Llama 3.1+、Mistral） > ⚠️ 需要模型支持 Tool Calling（推荐 Qwen3、Llama 3.1+、Mistral）
### 🧠 RAG 知识库 ### 🧠 Agent 记忆系统（v3.0 新增）
AI 会自动从对话中学习并记住关键信息，跨会话持续积累，无需手动配置：
**记忆类型**：
| 类型 | 说明 | 示例 |
|------|------|------|
| 📌 事实 | 关于用户的事实 | "用户正在开发一个 Electron 应用" |
| ⚙️ 偏好 | 用户的偏好习惯 | "喜欢用中文回答，代码风格简洁" |
| 📏 规则 | 应遵守的规则 | "项目中使用 TypeScript 严格模式" |
| 📝 事件 | 重要事件和结论 | "已成功构建 Windows 安装包" |
**工作流程**：
```
会话结束 → LLM 自动提取关键信息 → 去重检测 → 存入 IndexedDB
↓
新消息发送 → 关键词+标签+重要性检索 → 注入 system prompt
↓
AI 基于记忆提供个性化回答
```
**特性**：
- **自动提取** — 对话 ≥6 条消息后自动触发，LLM 智能识别值得记住的信息
- **智能检索** — 关键词 + 标签 + 重要性加权 + 使用频率 + 时间衰减
- **持久化** — IndexedDB 独立存储，跨会话、跨浏览器重启保留
- **可视化管理** — 记忆面板支持搜索、筛选、编辑、删除
- **完全可控** — 设置中一键开关，不影响其他功能
### 📚 RAG 知识库
- 文档上传 → 自动分块 → 向量化 → IndexedDB 持久化 - 文档上传 → 自动分块 → 向量化 → IndexedDB 持久化
- 语义检索增强问答，支持多集合管理 - 语义检索增强问答，支持多集合管理
- IVF 索引优化（K-Means 聚类 + 倒排索引） - IVF 索引优化（K-Means 聚类 + 倒排索引）
- 需嵌入模型（如 `nomic-embed-text`） - 需嵌入模型（如 `nomic-embed-text`）
### 🤖 Agent 预设
- 内置 6 个预设：💬 默认、🌐 翻译官、🔍 代码审查、✍️ 写作助手、📊 数据分析师、🎓 学习导师
- 一键切换系统提示词 + 温度 + 上下文长度 + Think 开关
- 支持自定义创建/编辑/删除
### 📦 数据 ### 📦 数据
- 历史记录 IndexedDB 持久化，支持搜索、分页 - 历史记录 IndexedDB 持久化，支持搜索、分页
- 导出格式：Markdown / HTML / TXT / .metona 加密备份 - 导出格式：Markdown / HTML / TXT / .metona 加密备份
@@ -73,6 +89,61 @@ AI 可以在对话中主动调用本地工具来完成任务，所有操作在
--- ---
## 🏗️ 架构
v3.0 三大子系统协调运作：
```
用户输入消息
│
├─→ ① Agent 记忆检索 → 注入 system prompt
├─→ ② RAG 知识库检索 → 追加到 system prompt
├─→ ③ Tool Calling 检查 → Agent Loop 或普通流式
│
▼
Ollama API（携带组合后的 system prompt + tools）
│
▼
流式响应 → 渲染到聊天区域（含工具调用卡片）
│
▼
保存会话 → 自动提取记忆（≥6 条消息时触发）
```
```
┌─────────────────────────────────────────────────────────┐
│ Electron 应用 │
│ ┌───────────────────────────────────────────────────┐ │
│ │ 渲染进程 (Renderer) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌──────────────┐ ┌─────────┐ │ │
│ │ │ chat-area │ │ input-area │ │ memory │ │ │
│ │ │ 消息渲染 │ │ 消息发送 │ │ panel │ │ │
│ │ │ 工具卡片 │ │ 记忆检索 │ │ 记忆管理 │ │ │
│ │ └──────┬──────┘ └──────┬───────┘ └────┬────┘ │ │
│ │ │ │ │ │ │
│ │ ┌──────┴───────────────┴───────────────┴──────┐ │ │
│ │ │ 核心服务层 │ │ │
│ │ │ agent-engine memory-manager rag │ │ │
│ │ │ 工具调用循环 记忆管理 知识检索 │ │ │
│ │ │ tool-registry vector-store doc-proc │ │ │
│ │ └──────────────────────┬──────────────────────┘ │ │
│ │ │ │ │
│ │ ┌──────────────────────┴──────────────────────┐ │ │
│ │ │ ollama.ts (API) chat-db.ts (存储) │ │ │
│ │ └──────────────────────┬──────────────────────┘ │ │
│ └─────────────────────────┼─────────────────────────┘ │
│ │ IPC │
│ ┌─────────────────────────┴─────────────────────────┐ │
│ │ 主进程 (Main) │ │
│ │ main.ts menu.ts tray.ts ipc.ts preload.ts │ │
│ │ tool-handlers.ts tool-security.ts │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
---
## 📥 下载 ## 📥 下载
从 [Releases](https://gitee.com/thzxx/metona-ollama/releases) 页面下载： 从 [Releases](https://gitee.com/thzxx/metona-ollama/releases) 页面下载：
@@ -114,7 +185,7 @@ npm start
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist
``` ```
> 💡 Linux 交叉编译 Windows 安装包需安装 Wine：`apt install wine`，详细构建指南见 [docs/BUILD.md](docs/BUILD.md) > 💡 Linux 交叉编译需安装 Wine：`apt install wine`，详细构建指南见 [docs/BUILD.md](docs/BUILD.md)
### 常用命令 ### 常用命令
@@ -128,15 +199,6 @@ npm run dist:nsis # 仅 NSIS 安装包
npm run dist:portable # 仅便携版 npm run dist:portable # 仅便携版
``` ```
### 构建产物
| 文件 | 说明 |
|------|------|
| `release/Metona Ollama Setup 3.0.0.exe` | NSIS 安装包 |
| `release/MetonaOllama-Portable-3.0.0.exe` | 绿色便携版 |
| `dist/main/` | 主进程编译输出 |
| `dist/renderer/` | 渲染进程构建输出 |
--- ---
## 📁 项目结构 ## 📁 项目结构
@@ -144,59 +206,61 @@ npm run dist:portable # 仅便携版
``` ```
metona-ollama/ metona-ollama/
├── src/ ├── src/
│ ├── main/ # Electron 主进程（TypeScript） │ ├── main/ # Electron 主进程
│ │ ├── main.ts # 应用入口、窗口管理、生命周期 │ │ ├── main.ts # 应用入口、窗口管理
│ │ ├── preload.ts # contextBridge 安全暴露 │ │ ├── preload.ts # contextBridge 安全暴露
│ │ ├── menu.ts # 原生菜单系统 │ │ ├── menu.ts # 原生菜单
│ │ ├── tray.ts # 系统托盘 │ │ ├── tray.ts # 系统托盘
│ │ ├── ipc.ts # IPC 处理器（含 Tool Calling） │ │ ├── ipc.ts # IPC（含 Tool Calling）
│ │ ├── utils.ts # 主进程工具函数 │ │ ├── utils.ts # 工具函数
│ │ ├── tool-handlers.ts # 🔧 工具执行器（7 个工具实现） │ │ ├── tool-handlers.ts # 🔧 7 个工具实现
│ │ └── tool-security.ts # 🔧 路径/命令安全检查 │ │ └── tool-security.ts # 🔧 路径/命令安全检查
│ └── renderer/ # 渲染进程（TypeScript） │ └── renderer/ # 渲染进程
│ ├── index.html # 渲染进程入口 HTML │ ├── index.html # 入口 HTML
│ ├── main.ts # 渲染进程入口 │ ├── main.ts # 入口（全系统初始化）
│ ├── types.d.ts # 完整类型定义（含 Tool Calling） │ ├── types.d.ts # 完整类型定义
│ ├── api/ │ ├── api/
│ │ └── ollama.ts # Ollama REST API 封装 │ │ └── ollama.ts # Ollama REST API
│ ├── db/ │ ├── db/
│ │ └── chat-db.ts # IndexedDB 持久化 │ │ └── chat-db.ts # IndexedDB v2（会话+记忆+向量）
│ ├── state/ │ ├── state/
│ │ └── state.ts # 响应式状态管理 │ │ └── state.ts # 响应式状态管理
│ ├── components/ # UI 组件 │ ├── components/
│ │ ├── chat-area.ts # 消息渲染、工具调用卡片 │ │ ├── chat-area.ts # 消息渲染、工具调用卡片
│ │ ├── input-area.ts # 输入、Agent Loop 触发 │ │ ├── input-area.ts # 消息发送、记忆检索、自动提取
│ │ ├── header.ts # 顶部导航 │ │ ├── memory-panel.ts # 🧠 记忆管理面板
│ │ ├── model-bar.ts # 模型选择栏 │ │ ├── tool-confirm-modal.ts # 🔧 工具确认对话框
│ │ ├── settings-modal.ts # 设置面板（含 Tool Calling 开关） │ │ ├── kb-modal.ts # RAG 知识库管理
│ │ ├── history-modal.ts # 历史记录 │ │ ├── settings-modal.ts # 设置面板
│ │ ├── kb-modal.ts # 知识库管理 │ │ ├── history-modal.ts # 历史记录
│ │ ├── preset-bar.ts # Agent 预设栏 │ │ ├── header.ts # 顶部导航
│ │ ├── tool-confirm-modal.ts # 🔧 工具调用确认对话框 │ │ ├── model-bar.ts # 模型选择栏
│ │ ├── toast.ts # 通知组件 │ │ ├── preset-bar.ts # Agent 预设栏（兼容）
│ │ └── lightbox.ts # 图片预览 │ │ ├── toast.ts # 通知
│ │ └── lightbox.ts # 图片预览
│ ├── services/ │ ├── services/
│ │ ├── rag.ts # RAG 检索增强生成 │ │ ├── memory-manager.ts # 🧠 记忆管理核心
│ │ ├── vector-store.ts # 向量存储 + IVF 索引 │ │ ├── agent-engine.ts # 🔧 Agent Loop 引擎
│ │ ├── document-processor.ts # 文档分块 │ │ ├── tool-registry.ts # 🔧 工具注册调度
│ │ ├── preset-manager.ts # Agent 预设管理 │ │ ├── rag.ts # RAG 检索管线
│ │ ├── crypto.ts # AES-256-GCM / XOR 加密 │ │ ├── vector-store.ts # 向量存储 + IVF 索引
│ │ ├── tool-registry.ts # 🔧 工具注册与调度中心 │ │ ├── document-processor.ts # 文档分块
│ │ └── agent-engine.ts # 🔧 Agent Loop 核心引擎 │ │ ├── preset-manager.ts # 预设管理（兼容层）
│ │ └── crypto.ts # AES-256-GCM 加密
│ ├── utils/ │ ├── utils/
│ │ ├── utils.ts # 工具函数 │ │ ├── utils.ts # 工具函数
│ │ ├── sanitizer.ts # HTML 净化器 │ │ ├── sanitizer.ts # HTML 净化器
│ │ └── marked-config.ts # Markdown 配置 │ │ └── marked-config.ts # Markdown 渲染
│ └── styles/ │ └── styles/
│ └── style.css # Windows 11 Fluent Design 样式 │ └── style.css # Fluent Design 样式
├── assets/icons/ # 图标资源 ├── assets/icons/ # 图标资源
├── docs/ ├── docs/
│ ├── BUILD.md # 构建指南（踩坑记录） │ ├── BUILD.md # 构建指南
│ └── V3-TOOL-CALLING.md # Tool Calling 技术设计文档 │ └── V3-TOOL-CALLING.md # Tool Calling 设计文档
├── vite.config.ts # Vite 构建配置 ├── vite.config.ts # Vite 配置
├── tsconfig.json # 渲染进程 TypeScript 配置 ├── tsconfig.json / tsconfig.main.json # TypeScript 配置
├── tsconfig.main.json # 主进程 TypeScript 配置 ├── package.json # 项目配置 + electron-builder
└── package.json # 项目配置 + electron-builder 打包 └── README.md
``` ```
--- ---
@@ -209,22 +273,23 @@ metona-ollama/
| `GET /api/ps` | 运行中模型 | 设置面板 | | `GET /api/ps` | 运行中模型 | 设置面板 |
| `GET /api/version` | Ollama 版本 | 连接检测 | | `GET /api/version` | Ollama 版本 | 连接检测 |
| `POST /api/show` | 模型详情（能力检测） | Think/Vision 检测 | | `POST /api/show` | 模型详情（能力检测） | Think/Vision 检测 |
| `POST /api/chat` | 流式聊天（核心，支持 tools） | 消息发送 / Agent Loop | | `POST /api/chat` | 流式聊天（支持 tools） | 对话 / Agent Loop |
| `POST /api/embed` | 生成嵌入向量 | RAG 知识库 | | `POST /api/embed` | 生成嵌入向量 | RAG 知识库 |
--- ---
## ⚙️ 设置 ## ⚙️ 设置
| 设置 | 默认值 | API 参数 | | 设置 | 默认值 | 说明 |
|------|--------|----------| |------|--------|------|
| Ollama 服务地址 | `http://127.0.0.1:11434` | — | | Ollama 服务地址 | `http://127.0.0.1:11434` | 本地 Ollama 地址 |
| 系统提示词 | 关闭 | `system` | | 系统提示词 | 关闭 | 自定义 AI 角色 |
| 上下文长度 | 24576 tokens | `options.num_ctx` | | 上下文长度 | 24576 tokens | `num_ctx`，越大记忆越长 |
| 温度 | 0.7 | `options.temperature` | | 温度 | 0.7 | 0=精确，2=创意 |
| Think 模式 | 关闭 | `think` | | Think 模式 | 关闭 | 深度推理（需模型支持） |
| 工具调用 | 关闭（v3.0 新增） | `tools` | | 工具调用 | 关闭 | AI 主动调用本地工具 |
| 命令执行 | 关闭（v3.0 新增） | — | | 命令执行 | 关闭 | Shell 命令执行（高风险） |
| Agent 记忆 | 开启 | 自动学习+跨会话记忆 |
--- ---
@@ -233,7 +298,7 @@ metona-ollama/
- **TypeScript 5.7** — 严格类型，完整接口定义 - **TypeScript 5.7** — 严格类型，完整接口定义
- **Electron 33** — 桌面封装（Windows x64） - **Electron 33** — 桌面封装（Windows x64）
- **Vite 5** — 渲染进程构建、HMR 热更新 - **Vite 5** — 渲染进程构建、HMR 热更新
- **IndexedDB** — 异步持久化（对话 + 向量） - **IndexedDB** — 异步持久化（会话 + 向量 + 记忆）
- **Fetch + ReadableStream** — 流式 NDJSON 解析 - **Fetch + ReadableStream** — 流式 NDJSON 解析
- **CSS Variables** — 暗色主题，毛玻璃效果 - **CSS Variables** — 暗色主题，毛玻璃效果
- **electron-builder** — NSIS + Portable 打包 - **electron-builder** — NSIS + Portable 打包
@@ -249,13 +314,19 @@ metona-ollama/
- 阻止 `javascript:` / `vbscript:` / `data:` 协议注入 - 阻止 `javascript:` / `vbscript:` / `data:` 协议注入
- contextIsolation + IPC 白名单 + 单实例锁 - contextIsolation + IPC 白名单 + 单实例锁
### Tool Calling 安全（v3.0） ### Tool Calling 安全
- **路径黑名单**：自动屏蔽 `/etc`, `/sys`, `/proc`, `/dev`, `~/.ssh`, `~/.gnupg` 等 - **路径黑名单**：自动屏蔽 `/etc`, `/sys`, `/proc`, `~/.ssh`, `~/.gnupg` 等
- **写操作白名单**：仅允许用户目录下的写入 - **写操作白名单**：仅允许用户目录下的写入
- **命令黑名单**：`rm -rf /`, `mkfs`, `dd`, `shutdown`, 反弹 shell 检测等 - **命令黑名单**：`rm -rf /`, `mkfs`, `dd`, `shutdown`, 反弹 shell 检测等
- **用户确认**：写入/删除/命令执行必须用户确认 - **用户确认**：写入/删除/命令执行必须用户确认
- **安全提示词注入**：自动向 system prompt 追加工具使用安全规则 - **安全提示词注入**：自动向 system prompt 追加工具使用安全规则
### 记忆系统安全
- 记忆提取仅基于对话内容，不读取文件系统
- 记忆存储在本地 IndexedDB，不上传到任何服务器
- 用户可随时查看、编辑、删除任意记忆条目
- 支持一键关闭自动记忆功能
--- ---
## 📋 更新日志 ## 📋 更新日志
@@ -265,29 +336,30 @@ metona-ollama/
- 7 个工具：`read_file` / `write_file` / `list_directory` / `search_files` / `create_directory` / `delete_file` / `run_command` - 7 个工具：`read_file` / `write_file` / `list_directory` / `search_files` / `create_directory` / `delete_file` / `run_command`
- Agent Loop 引擎：流式多轮工具调用循环，支持并行调用 - Agent Loop 引擎：流式多轮工具调用循环，支持并行调用
- 安全模型：路径白名单/黑名单、命令过滤、用户确认对话框 - 安全模型：路径白名单/黑名单、命令过滤、用户确认对话框
- 工具调用可视化卡片（参数、状态、结果预览） - 工具调用可视化卡片（5 种状态）
- 设置面板新增工具调用开关 - 🧠 **Agent 记忆系统**
- ⚡ Agent Loop 触发逻辑替代普通单轮对话（工具开启时自动生效） - 自动从对话中提取关键信息（事实/偏好/规则/事件）
- 🎨 工具调用卡片样式（5 种状态：等待确认/执行中/完成/失败/已取消） - 关键词+标签+重要性加权检索，自动注入上下文
- IndexedDB 持久化，跨会话积累
- 可视化记忆管理面板
- ⚡ **全功能协调运作**
- 记忆检索 → RAG 检索 → Tool Calling 三层协作
- 对话结束自动记忆提取
### v2.0.0 ### v2.0.0
- ⚡ **TypeScript 全面重写** — 所有代码从 JavaScript 迁移至 TypeScript，严格类型定义 - ⚡ TypeScript 全面重写，严格类型定义
- 🏗️ **Vite 构建系统** — 替代零构建，支持模块化打包 - 🏗️ Vite 构建系统，模块化打包
- 🖥️ **纯桌面版** — 放弃 Web/PWA 支持，全面专注 Electron 桌面体验 - 🖥️ 纯桌面版，专注 Electron 体验
- 🧩 **主进程模块化** — 按职责拆分为独立模块（menu/tray/ipc/preload/utils） - 🧩 主进程模块化拆分
- 🗑️ 移除 sw.js、manifest.json、desktop-bridge.js 等 Web 相关代码
### v1.1.0 ### v1.1.0
- 🎨 UI 重构为 Windows 11 Fluent Design 暗色主题（Mica 材质、Segoe UI Variable） - 🎨 Windows 11 Fluent Design 暗色主题
- 📐 知识库/历史记录弹框加宽 - 📐 知识库/历史弹框优化
- ✨ Think 按钮开启后添加蓝色光效 - ✨ Think 按钮光效
- 🚫 彻底隐藏窗口菜单栏
### v1.0.0 ### v1.0.0
- 🖥️ Electron Windows 桌面客户端首版 - 🖥️ Electron Windows 桌面客户端首版
- 📦 NSIS 安装包 + 绿色便携版 - 📦 NSIS 安装包 + 绿色便携版
- 📋 系统托盘、原生菜单、原生文件对话框
- 🔔 系统通知、窗口管理、单实例锁
--- ---