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

docs: 重构 README.md & 更新 docs 文件适配 v4.0.0

Browse Source 
- README.md: 全面重写，反映实际项目状态（25工具、SQLite、ReAct、暖色主题）
- DEVELOPMENT.md: 更新技术栈（SQLite替代IndexedDB）、架构（ReAct）、工具数、UI规范
- CHANGELOG.md: v4.0.0条目补充UI主题改版说明
- BUILD.md: 新增v4.0.0构建日志
This commit is contained in:
thzxx
2026-04-17 13:59:44 +08:00
parent 5ea958e5c1
commit 24a5475a7f
4 changed files with 189 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+73 -98
View File
@@ -2,7 +2,7 @@
基于 TypeScript + Electron 的 [Ollama](https://ollama.com) 桌面 AI Agent 客户端，专为 Windows 打造。 基于 TypeScript + Electron 的 [Ollama](https://ollama.com) 桌面 AI Agent 客户端，专为 Windows 打造。
> 💻 桌面版仓库 | 🌐 [Web 版历史存档](https://gitee.com/thzxx/metona-ollama-web) > 💡 全离线运行，数据本地存储，零外部依赖
![版本](https://img.shields.io/badge/version-4.0.0--desktop-brightgreen) ![版本](https://img.shields.io/badge/version-4.0.0--desktop-brightgreen)
![平台](https://img.shields.io/badge/platform-Windows%20x64-blue) ![平台](https://img.shields.io/badge/platform-Windows%20x64-blue)
@@ -22,8 +22,9 @@
- **多模态** — 图片上传，自动检测 Vision 模型能力 - **多模态** — 图片上传，自动检测 Vision 模型能力
- **文件分析** — 支持 50+ 种文本/代码格式，单文件 ≤500KB - **文件分析** — 支持 50+ 种文本/代码格式，单文件 ≤500KB
### 🔧 Tool Calling — AI 自主工具调用（v3.0 新增，21 个工具） ### 🔧 Tool Calling — 25 个工具（AI 自主工具调用）
AI 可以在对话中主动调用本地工具来完成任务，所有操作在用户可视化监督下执行：
AI 在对话中主动调用本地工具完成任务，所有操作在用户可视化监督下执行：
| 工具 | 说明 | 安全级别 | | 工具 | 说明 | 安全级别 |
|------|------|----------| |------|------|----------|
@@ -33,14 +34,14 @@ AI 可以在对话中主动调用本地工具来完成任务，所有操作在
| 🔍 `search_files` | 按文件名/内容搜索（支持扩展名过滤） | 自动 | | 🔍 `search_files` | 按文件名/内容搜索（支持扩展名过滤） | 自动 |
| 📂 `create_directory` | 创建目录（递归创建） | 自动 | | 📂 `create_directory` | 创建目录（递归创建） | 自动 |
| 🗑️ `delete_file` | 删除文件/目录 | 自动 | | 🗑️ `delete_file` | 删除文件/目录 | 自动 |
| 💻 `run_command` | 执行 Shell 命令（无超时，通过工作空间终端执行） | 自动/需确认/禁用 | | 💻 `run_command` | 执行 Shell 命令（无超时，工作空间终端执行） | 自动/需确认/禁用 |
| 📦 `move_file` | 移动/重命名文件或目录 | 自动 | | 📦 `move_file` | 移动/重命名文件或目录 | 自动 |
| 📋 `copy_file` | 复制文件或目录 | 自动 | | 📋 `copy_file` | 复制文件或目录 | 自动 |
| 🌐 `web_fetch` | 抓取网页内容（HTTP/HTTPS，自动提取文本，默认返回完整内容） | 自动 | | 🌐 `web_fetch` | 抓取网页内容（HTTP/HTTPS，默认返回完整内容） | 自动 |
| 🔍 `web_search` | 联网搜索（DuckDuckGo/Bing，返回标题+链接+摘要） | 自动 | | 🔍 `web_search` | 联网搜索（DuckDuckGo/Bing，返回标题+链接+摘要） | 自动 |
| ➕ `append_file` | 追加内容到文件末尾 | 自动 | | ➕ `append_file` | 追加内容到文件末尾 | 自动 |
| ✂️ `edit_file` | 查找替换文件中的文本（比重写整个文件高效） | 自动 | | ✂️ `edit_file` | 查找替换文件中的文本 | 自动 |
| ℹ️ `get_file_info` | 获取文件/目录详细信息（大小、日期、权限） | 自动 | | ℹ️ `get_file_info` | 获取文件/目录详细信息 | 自动 |
| 🌳 `tree` | 以树形结构展示目录 | 自动 | | 🌳 `tree` | 以树形结构展示目录 | 自动 |
| ⬇️ `download_file` | 从 URL 下载文件到本地 | 自动 | | ⬇️ `download_file` | 从 URL 下载文件到本地 | 自动 |
| 🔀 `diff_files` | 对比两个文件差异（unified diff） | 自动 | | 🔀 `diff_files` | 对比两个文件差异（unified diff） | 自动 |
@@ -48,90 +49,61 @@ AI 可以在对话中主动调用本地工具来完成任务，所有操作在
| 📚 `read_multiple_files` | 批量读取多个文件内容 | 自动 | | 📚 `read_multiple_files` | 批量读取多个文件内容 | 自动 |
| 🔖 `git` | Git 操作（status/log/diff/add/commit/push/pull/branch/checkout/merge/stash 等 16 个子操作） | 自动 | | 🔖 `git` | Git 操作（status/log/diff/add/commit/push/pull/branch/checkout/merge/stash 等 16 个子操作） | 自动 |
| 🗜️ `compress` | 创建/解压归档（zip/tar.gz） | 自动 | | 🗜️ `compress` | 创建/解压归档（zip/tar.gz） | 自动 |
| 🧠 `memory_search` | 搜索 Agent 记忆（语义/关键词） | 自动 |
| 💾 `memory_add` | 添加新记忆条目 | 自动 |
| 📋 `session_list` | 列出历史会话 | 自动 |
| 📖 `session_read` | 读取历史会话内容 | 自动 |
**Agent Loop**：用户请求 → 模型返回 tool_calls → 客户端执行 → 回传结果 → 循环直到无工具调用，支持流式 + 并行调用 + 最大 10 轮保护。自动检测并跳过重复工具调用（相同工具+参数），连续两轮完全相同则终止循环。 **Agent Loop（ReAct 模式）**：用户请求 → Thought → Action → Observation → Reflection → 循环直到 Final Answer。支持流式 + 并行调用 + 最大 15 轮保护 + 10 分钟总超时。自动检测并跳过重复工具调用。
> ⚠️ 需要模型支持 Tool Calling（推荐 Qwen3、Llama 3.1+、Mistral） > ⚠️ 需要模型支持 Tool Calling（推荐 Qwen3、Llama 3.1+、Mistral）
### 🖥️ 工作空间 — 终端 & 文件浏览器（v3.2 新增） ### 🖥️ 工作空间 — 终端 & 文件浏览器
右侧可折叠面板，提供终端命令行和文件浏览器： 右侧常驻面板（480px），提供终端命令行和文件浏览器：
**终端**： **终端**：
- 终端界面，实时流式显示命令输出（支持 ANSI 颜色） - 实时流式显示命令输出（支持 ANSI 颜色）
- 支持长时间运行命令（如 `ollama pull`），**无超时限制** - 支持长时间运行命令（如 `ollama pull`），**无超时限制**
- 单一终端进程，可随时停止 - 单一终端进程，可随时停止
- `ollama pull` 等进度条实时展示（`\r` 覆盖处理）
**文件浏览器**： **文件浏览器**：
- 浏览工作空间目录，目录树展示 - 浏览工作空间目录，目录树展示
- 点击文件预览内容（带行号） - 点击文件预览内容（带行号）
- 支持上级目录导航、刷新
**工作原理**： > ⚠️ Tool Calling 走 Agent Loop（有超时），工作空间走独立进程（无超时），由用户主动触发。
```
用户/AI 建议命令 → 工作空间执行按钮 → 主进程 spawn 子进程
│
┌─────────────────────┘
▼
IPC 双向通信（on/send 模式，无超时）
│
stdout/stderr 实时推送 → 渲染进程终端面板
│
进程退出 → 通知渲染进程显示退出状态
```
> ⚠️ 与 Tool Calling 的区别：Tool Calling 走 Agent Loop（有超时），工作空间走独立进程（无超时），由用户主动触发。 ### 🧠 Agent 记忆系统
AI 自动从对话中学习并记住关键信息，跨会话持续积累：
### 🧠 Agent 记忆系统（v3.0 新增） | 类型 | 说明 | 检索方式 |
AI 会自动从对话中学习并记住关键信息，跨会话持续积累，无需手动配置： |------|------|----------|
| 📌 事实 | 关于用户的事实 | 关键词 + 向量语义 |
**记忆类型**： | ⚙️ 偏好 | 用户的偏好习惯 | 始终注入 |
| 类型 | 说明 | 检索方式 | 示例 | | 📏 规则 | 应遵守的规则 | 始终注入 |
|------|------|----------|------|
| 📌 事实 | 关于用户的事实 | 关键词匹配 | "用户正在开发一个 Electron 应用" |
| ⚙️ 偏好 | 用户的偏好习惯 | 始终注入 | "喜欢用中文回答，代码风格简洁" |
| 📏 规则 | 应遵守的规则 | 始终注入 | "项目中使用 TypeScript 严格模式" |
**工作流程**：
```
会话结束 → LLM 自动提取关键信息 → 去重检测 → 存入 IndexedDB
↓
新消息发送 → 规则/偏好始终注入 + 事实关键词检索 → 注入 system prompt
↓
AI 基于记忆提供个性化回答
```
**特性**： **特性**：
- **自动提取** — 对话 ≥6 条消息后自动触发，LLM 智能识别值得记住的信息 - 对话 ≥6 条消息后自动触发 LLM 提取
- **智能检索** — 关键词 + 标签 + 重要性加权 + 使用频率 + 时间衰减 - FTS5 全文搜索 + 向量语义搜索（需选择嵌入模型）
- **持久化** — IndexedDB 独立存储，跨会话、跨浏览器重启保留 - SQLite 持久化，跨会话保留
- **可视化管理** — 记忆面板支持搜索、筛选、编辑、删除 - 可视化管理面板（搜索、筛选、编辑、删除）
- **完全可控** — 设置中一键开关，不影响其他功能 - 设置中一键开关
### 📚 向量记忆（记忆系统的语义检索层）
- 选择嵌入模型（如 `nomic-embed-text`）后，记忆系统启用向量语义搜索
- 记忆条目自动向量化 → IndexedDB 持久化
- IVF 索引优化（K-Means 聚类 + 倒排索引），支持大规模记忆高效检索
- 未选择嵌入模型时退化为关键词匹配检索
### 📦 数据 ### 📦 数据
- 历史记录 IndexedDB 持久化，支持搜索、分页 - SQLite (better-sqlite3) 持久化，WAL 模式高性能
- 导出格式：Markdown / HTML / TXT / .metona 加密备份 - 6 张表：sessions、messages、tool_calls、memories、settings、traces
- .metona 格式支持 AES-256-GCM 加密（HTTPS）或 XOR 混淆（HTTP） - 导出格式：Markdown / HTML / TXT / JSON（全量备份/恢复）
- 所有导入/导出均使用 Electron 原生文件对话框（不再依赖浏览器下载） - 所有导入/导出均使用 Electron 原生文件对话框
### 🖥️ 桌面原生 ### 🖥️ 桌面原生
| 特性 | 说明 | | 特性 | 说明 |
|------|------| |------|------|
| Fluent Design 主题 | Windows 11 暗色风格，Mica 毛玻璃材质 | | 暖色调亮色主题 | 奶白背景 + 珊瑚橙主色，圆润柔和 |
| 执行日志面板 | 左侧面板实时显示应用运行日志（初始化、连接、模型加载、工具调用等），纯运行时不持久化，常驻显示不可关闭 | | 执行日志面板 | 左侧面板实时显示应用运行日志 |
| 工作空间面板 | 右侧面板（常驻显示）：终端命令行（实时流式输出，单一终端进程）+ 文件浏览器，固定宽度 480px | | 工作空间面板 | 右侧面板：终端 + 文件浏览器，固定 480px |
| Token 消耗统计 | Header 实时显示当前会话总 token 消耗 | | Token 消耗统计 | Header 实时显示当前会话总 token 消耗 |
| 系统托盘 | 最小化到托盘，双击恢复，右键菜单 | | 系统托盘 | 最小化到托盘，双击恢复 |
| 原生菜单 | 文件 / 编辑 / 视图 / 窗口 / 帮助完整菜单 | | 原生菜单 | 文件 / 编辑 / 视图 / 窗口 / 帮助完整菜单 |
| 原生文件对话框 | 文件选择/保存全部使用 Electron 原生对话框，支持文件类型过滤 | | 原生文件对话框 | 文件选择/保存全部使用 Electron 原生对话框 |
| 系统通知 | Windows 原生通知中心推送 |
| 窗口管理 | 记忆窗口大小位置，支持置顶 |
| 单实例锁 | 防止重复启动 | | 单实例锁 | 防止重复启动 |
| 无 CORS 限制 | 直连本地 Ollama，无需配置 OLLAMA_ORIGINS | | 无 CORS 限制 | 直连本地 Ollama，无需配置 OLLAMA_ORIGINS |
@@ -139,13 +111,13 @@ AI 会自动从对话中学习并记住关键信息，跨会话持续积累，
## 🏗️ 架构 ## 🏗️ 架构
v3.3 四大子系统协调运作： v4.0 四大子系统协调运作：
``` ```
用户输入消息 用户输入消息
│ │
├─→ ① Agent 记忆检索（关键词 + 向量语义） → 注入 system prompt ├─→ ① Agent 记忆检索（关键词 + 向量语义） → 注入 system prompt
├─→ ② Tool Calling 检查 → Agent Loop 或普通流式 ├─→ ② ReAct Agent Loop → Thought → Action → Observation → Reflection
│ │
▼ ▼
Ollama API（携带组合后的 system prompt + tools） Ollama API（携带组合后的 system prompt + tools）
@@ -154,10 +126,13 @@ v3.3 四大子系统协调运作：
流式响应 → 渲染到聊天区域（含工具调用卡片） 流式响应 → 渲染到聊天区域（含工具调用卡片）
│ │
▼ ▼
保存会话 → 自动提取记忆（≥6 条消息时触发） 保存会话 → SQLite → 自动提取记忆（≥6 条消息时触发）
③ 工作空间（独立通道） ③ 工作空间（独立通道）
AI 建议命令 → 用户确认 → spawn 子进程 → IPC 流式推送 → 终端面板实时展示 AI 建议命令 → 用户确认 → spawn 子进程 → IPC 流式推送 → 终端面板实时展示
④ 数据层（SQLite）
sessions · messages · tool_calls · memories(FTS5) · settings · traces
``` ```
``` ```
@@ -175,19 +150,20 @@ v3.3 四大子系统协调运作：
│ │ ┌──────┴───────────────┴─────────────────────┴──────────┐ │ │ │ │ ┌──────┴───────────────┴─────────────────────┴──────────┐ │ │
│ │ │ 核心服务层 │ │ │ │ │ │ 核心服务层 │ │ │
│ │ │ agent-engine memory-manager vector-memory │ │ │ │ │ │ agent-engine memory-manager vector-memory │ │ │
│ │ │ tool-registry vector-store workspace-panel │ │ │ │ │ │ tool-registry vector-store context-manager │ │ │
│ │ └──────────────────────────┬────────────────────────────┘ │ │ │ │ └──────────────────────────┬────────────────────────────┘ │ │
│ │ │ │ │ │ │ │ │ │
│ │ ┌──────────────────────────┴────────────────────────────┐ │ │ │ │ ┌──────────────────────────┴────────────────────────────┐ │ │
│ │ │ ollama.ts (API) chat-db.ts (存储) │ │ │ │ │ │ ollama.ts (API) (SQLite via IPC) │ │ │
│ │ └──────────────────────────┬────────────────────────────┘ │ │ │ │ └──────────────────────────┬────────────────────────────┘ │ │
│ └─────────────────────────────┼──────────────────────────────┘ │ │ └─────────────────────────────┼──────────────────────────────┘ │
│ │ IPC │ │ │ IPC │
│ ┌─────────────────────────────┴──────────────────────────────┐ │ │ ┌─────────────────────────────┴──────────────────────────────┐ │
│ │ 主进程 (Main) │ │ │ │ 主进程 (Main) │ │
│ │ main.ts menu.ts tray.ts ipc.ts preload.ts │ │ │ │ main.ts menu.ts tray.ts ipc.ts preload.ts │ │
│ │ tool-handlers.ts (21 个工具) tool-security.ts workspace.ts│ │ │ │ tool-handlers.ts (25 工具) tool-security.ts workspace.ts│ │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ db/sqlite.ts: better-sqlite3 · WAL · FTS5 │ │ │
│ │ │ workspace.ts: spawn 进程管理 · 流式输出 · 安全检查 │ │ │ │ │ │ workspace.ts: spawn 进程管理 · 流式输出 · 安全检查 │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │ │ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │ │ └────────────────────────────────────────────────────────────┘ │
@@ -265,44 +241,43 @@ metona-ollama-desktop/
├── src/ ├── src/
│ ├── main/ # Electron 主进程 │ ├── main/ # Electron 主进程
│ │ ├── main.ts # 应用入口、窗口管理、workspace 初始化 │ │ ├── main.ts # 应用入口、窗口管理、workspace 初始化
│ │ ├── preload.ts # contextBridge 安全暴露（含 workspace API） │ │ ├── preload.ts # contextBridge 安全暴露（含 workspace/DB API）
│ │ ├── menu.ts # 原生菜单 │ │ ├── menu.ts # 原生菜单
│ │ ├── tray.ts # 系统托盘 │ │ ├── tray.ts # 系统托盘
│ │ ├── ipc.ts # IPC（Tool Calling + Workspace 流式通信） │ │ ├── ipc.ts # IPC（Tool Calling + Workspace + SQLite）
│ │ ├── utils.ts # 工具函数 │ │ ├── utils.ts # 工具函数
│ │ ├── tool-handlers.ts # 🔧 21 个工具实现 │ │ ├── tool-handlers.ts # 🔧 25 个工具实现
│ │ ├── tool-security.ts # 🔧 路径/命令安全检查 │ │ ├── tool-security.ts # 🔧 路径/命令安全检查
│ │ └── workspace.ts # 🖥️ spawn 进程管理、流式输出 │ │ ├── workspace.ts # 🖥️ spawn 进程管理、流式输出
│ │ └── db/
│ │ └── sqlite.ts # 📦 SQLite 数据库（better-sqlite3, WAL, FTS5）
│ └── renderer/ # 渲染进程 │ └── renderer/ # 渲染进程
│ ├── index.html # 入口 HTML（含工作空间面板） │ ├── index.html # 入口 HTML
│ ├── main.ts # 入口（全系统初始化） │ ├── main.ts # 入口（全系统初始化）
│ ├── types.d.ts # 完整类型定义（含 Workspace 类型） │ ├── types.d.ts # 完整类型定义
│ ├── api/ │ ├── api/
│ │ └── ollama.ts # Ollama REST API │ │ └── ollama.ts # Ollama REST API 客户端
│ ├── db/
│ │ └── chat-db.ts # IndexedDB v2（会话+记忆+向量）
│ ├── state/
│ │ └── state.ts # 响应式状态管理
│ ├── components/ │ ├── components/
│ │ ├── chat-area.ts # 消息渲染、工具调用卡片 │ │ ├── chat-area.ts # 消息渲染、工具调用卡片、导出
│ │ ├── input-area.ts # 消息发送、记忆检索、自动提取 │ │ ├── input-area.ts # 消息发送、记忆检索、自动提取
│ │ ├── memory-modal.ts # 🧠 记忆管理面板
│ │ ├── workspace-panel.ts # 🖥️ 工作空间面板（终端+文件） │ │ ├── workspace-panel.ts # 🖥️ 工作空间面板（终端+文件）
│ │ ├── memory-modal.ts # 🧠 记忆管理面板
│ │ ├── tool-confirm-modal.ts # 🔧 工具确认对话框 │ │ ├── tool-confirm-modal.ts # 🔧 工具确认对话框
│ │ ├── tools-modal.ts # 🔧 工具列表面板 │ │ ├── tools-modal.ts # 🔧 工具列表面板
│ │ ├── settings-modal.ts # 设置面板（含工作空间目录） │ │ ├── settings-modal.ts # 设置面板
│ │ ├── history-modal.ts # 历史记录 │ │ ├── history-modal.ts # 历史记录
│ │ ├── prompt-modal.ts # 自定义弹窗（替代原生 prompt/confirm） │ │ ├── prompt-modal.ts # 自定义弹窗
│ │ ├── header.ts # 顶部导航 │ │ ├── header.ts # 顶部导航
│ │ ├── model-bar.ts # 模型选择栏 │ │ ├── model-bar.ts # 模型选择栏
│ │ ├── toast.ts # 通知 │ │ ├── toast.ts # 通知
│ │ └── lightbox.ts # 图片预览 │ │ └── lightbox.ts # 图片预览
│ ├── services/ │ ├── services/
│ │ ├── agent-engine.ts # 🔧 ReAct Agent Loop 引擎
│ │ ├── tool-registry.ts # 🔧 工具注册调度（25 个工具）
│ │ ├── memory-manager.ts # 🧠 记忆管理核心 │ │ ├── memory-manager.ts # 🧠 记忆管理核心
│ │ ├── vector-memory.ts # 🧠 记忆向量索引（IVF 索引） │ │ ├── vector-memory.ts # 🧠 记忆向量索引（IVF）
│ │ ├── agent-engine.ts # 🔧 Agent Loop 引擎
│ │ ├── tool-registry.ts # 🔧 工具注册调度（21 个工具定义）
│ │ ├── vector-store.ts # 向量存储 + IVF 索引 │ │ ├── vector-store.ts # 向量存储 + IVF 索引
│ │ ├── context-manager.ts # 上下文窗口管理
│ │ ├── document-processor.ts # 文档分块 │ │ ├── document-processor.ts # 文档分块
│ │ ├── log-service.ts # 结构化执行日志 │ │ ├── log-service.ts # 结构化执行日志
│ │ └── crypto.ts # AES-256-GCM 加密 │ │ └── crypto.ts # AES-256-GCM 加密
@@ -310,8 +285,10 @@ metona-ollama-desktop/
│ │ ├── utils.ts # 工具函数 │ │ ├── utils.ts # 工具函数
│ │ ├── sanitizer.ts # HTML 净化器 │ │ ├── sanitizer.ts # HTML 净化器
│ │ └── marked-config.ts # Markdown 渲染 │ │ └── marked-config.ts # Markdown 渲染
│ ├── state/
│ │ └── state.ts # 响应式状态管理
│ └── styles/ │ └── styles/
│ └── style.css # Fluent Design 样式（含工作空间面板） │ └── style.css # 暖色调亮色主题样式
├── assets/icons/ # 图标资源 ├── assets/icons/ # 图标资源
├── docs/ ├── docs/
│ ├── BUILD.md # 构建指南 │ ├── BUILD.md # 构建指南
@@ -358,9 +335,9 @@ metona-ollama-desktop/
- **TypeScript 5.7** — 严格类型，完整接口定义 - **TypeScript 5.7** — 严格类型，完整接口定义
- **Electron 33** — 桌面封装（Windows x64） - **Electron 33** — 桌面封装（Windows x64）
- **Vite 5** — 渲染进程构建、HMR 热更新 - **Vite 5** — 渲染进程构建、HMR 热更新
- **IndexedDB** — 异步持久化（会话 + 向量 + 记忆） - **better-sqlite3 12.9** — SQLite 数据库（主进程，WAL 模式）
- **Fetch + ReadableStream** — 流式 NDJSON 解析 - **Fetch + ReadableStream** — 流式 NDJSON 解析
- **CSS Variables** — 暗色主题，毛玻璃效果 - **CSS Variables** — 暖色调亮色主题
- **electron-builder** — NSIS 安装包 - **electron-builder** — NSIS 安装包
- **零外部依赖** — Markdown 解析器、SHA-256、HTML 净化器全部内联实现 - **零外部依赖** — Markdown 解析器、SHA-256、HTML 净化器全部内联实现
@@ -385,14 +362,12 @@ metona-ollama-desktop/
- **IPC 双向通信**：`on/send` 模式，不走 `invoke/handle`，无超时但有独立进程管理 - **IPC 双向通信**：`on/send` 模式，不走 `invoke/handle`，无超时但有独立进程管理
- **命令安全检查**：复用 Tool Calling 的命令黑名单和路径检查 - **命令安全检查**：复用 Tool Calling 的命令黑名单和路径检查
- **目录限制**：文件浏览器仅允许在工作空间目录内浏览 - **目录限制**：文件浏览器仅允许在工作空间目录内浏览
- **进程生命周期**：窗口关闭时自动 `SIGTERM` 所有子进程，防止进程泄漏 - **进程生命周期**：窗口关闭时自动 `SIGTERM` 所有子进程
- **用户控制**：命令由用户手动执行或确认，AI 仅建议不直接执行
### 记忆系统安全 ### 数据安全
- SQLite 本地存储，不上传任何服务器
- 记忆提取仅基于对话内容，不读取文件系统 - 记忆提取仅基于对话内容，不读取文件系统
- 记忆存储在本地 IndexedDB，不上传到任何服务器
- 用户可随时查看、编辑、删除任意记忆条目 - 用户可随时查看、编辑、删除任意记忆条目
- 支持一键关闭自动记忆功能
--- ---
docs/BUILD.md
+9
View File
@@ -176,6 +176,15 @@ electron-builder 会自动处理所有依赖下载（Electron、NSIS、winCodeSi
## 构建日志 ## 构建日志
### v4.0.0（2026-04-17） — metona-ollama-desktop 仓库
- 📦 SQLite (better-sqlite3) 替代 IndexedDB，6 张表 + FTS5 全文搜索
- 🔧 Agent Loop 升级为 ReAct 模式（15 轮，10 分钟超时，执行轨迹记录）
- 🧠 新增 4 个记忆/会话管理工具（memory_search, memory_add, session_list, session_read）
- 🎨 UI 主题改版：暗色 Fluent → 暖色调亮色（奶白 + 珊瑚橙）
- ✨ 新增 context-manager.ts 上下文管理服务
- 📝 版本号更新至 4.0.0（package.json / package-lock.json / index.html / README.md / CHANGELOG.md / BUILD.md / DEVELOPMENT.md）
### v3.3.4（2026-04-17） — metona-ollama-desktop 仓库 ### v3.3.4（2026-04-17） — metona-ollama-desktop 仓库
- 🔧 修复 Agent Loop 工具调用重复问题（缓存 + 同轮/跨轮去重 + 自动终止） - 🔧 修复 Agent Loop 工具调用重复问题（缓存 + 同轮/跨轮去重 + 自动终止）
docs/CHANGELOG.md
+9 -1
View File
@@ -11,7 +11,7 @@
## 桌面版（Desktop） ## 桌面版（Desktop）
### Desktop v4.0.0 — SQLite 数据库 & ReAct Agent 升级 ### Desktop v4.0.0 — SQLite & ReAct Agent & 全新主题
- 📦 **数据库迁移：IndexedDB → SQLite (better-sqlite3)** - 📦 **数据库迁移：IndexedDB → SQLite (better-sqlite3)**
- 新增 `src/main/db/sqlite.ts`，使用 better-sqlite3 替代 IndexedDB - 新增 `src/main/db/sqlite.ts`，使用 better-sqlite3 替代 IndexedDB
@@ -27,6 +27,14 @@
- 新增 `memory_search`、`memory_add` 工具（AI 可主动管理记忆） - 新增 `memory_search`、`memory_add` 工具（AI 可主动管理记忆）
- 新增 `session_list`、`session_read` 工具（AI 可查阅历史会话） - 新增 `session_list`、`session_read` 工具（AI 可查阅历史会话）
- 记忆支持 FTS5 全文搜索 + 向量语义搜索 - 记忆支持 FTS5 全文搜索 + 向量语义搜索
- 上下文管理服务（`context-manager.ts`）
- 🎨 **UI 主题改版：暗色 → 暖色调亮色**
- 奶白背景 `#FAF7F2` + 珊瑚橙主色 `#E8734A`
- 圆润柔和设计：圆角 8-20px，柔和阴影
- 紫色辅助色（Think/推理），金色标签（Token 统计）
- 终端区域保留暖棕深色 `#2D2016` 保证代码可读性
- 字体升级：Inter + JetBrains Mono
- 窗口背景色、导出 HTML、theme-color 同步更新
- 🖥️ **工作空间改进** - 🖥️ **工作空间改进**
- IPC 通信优化，workspace 命令通过独立进程管理 - IPC 通信优化，workspace 命令通过独立进程管理
- AI 工具命令实时输出推送到工作空间终端 - AI 工具命令实时输出推送到工作空间终端
docs/DEVELOPMENT.md
+85 -106
View File
@@ -6,7 +6,7 @@
## 一、项目概述 ## 一、项目概述
Metona Ollama Desktop 是基于 TypeScript + Electron 的本地 Ollama AI 桌面客户端，面向 Windows 平台。项目采用零外部依赖策略，所有核心功能（Markdown 解析、SHA-256、HTML 净化器等）均内联实现。 Metona Ollama Desktop 是基于 TypeScript + Electron 的本地 Ollama AI 桌面客户端，面向 Windows 平台。项目采用零外部依赖策略（仅 better-sqlite3 为运行时依赖），所有核心功能（Markdown 解析、SHA-256、HTML 净化器等）均内联实现。
--- ---
@@ -17,7 +17,7 @@ Metona Ollama Desktop 是基于 TypeScript + Electron 的本地 Ollama AI 桌面
| 语言 | TypeScript | ≥5.7，严格模式 (`strict: true`) | | 语言 | TypeScript | ≥5.7，严格模式 (`strict: true`) |
| 桌面框架 | Electron | ≥33 | | 桌面框架 | Electron | ≥33 |
| 构建工具 | Vite (渲染进程) + tsc (主进程) | Vite ≥5 | | 构建工具 | Vite (渲染进程) + tsc (主进程) | Vite ≥5 |
| 数据存储 | IndexedDB | 原生 API，无 ORM | | 数据存储 | better-sqlite3 | ≥12.9，WAL 模式，FTS5 全文搜索 |
| 打包 | electron-builder | NSIS 格式 | | 打包 | electron-builder | NSIS 格式 |
--- ---
@@ -31,22 +31,38 @@ src/
│ ├── preload.ts # contextBridge API 暴露 │ ├── preload.ts # contextBridge API 暴露
│ ├── ipc.ts # IPC 处理器（invoke/handle + on/send） │ ├── ipc.ts # IPC 处理器（invoke/handle + on/send）
│ ├── workspace.ts # 子进程管理、流式输出 │ ├── workspace.ts # 子进程管理、流式输出
│ ├── tool-handlers.ts # Tool Calling 工具实现 │ ├── tool-handlers.ts # Tool Calling 25 个工具实现
│ ├── tool-security.ts # 路径/命令安全检查 │ ├── tool-security.ts # 路径/命令安全检查
│ ├── menu.ts # 原生菜单 │ ├── menu.ts # 原生菜单
│ ├── tray.ts # 系统托盘 │ ├── tray.ts # 系统托盘
│ └── utils.ts # 工具函数 │ ├── utils.ts # 工具函数
│ └── db/
│ └── sqlite.ts # SQLite 数据库层（6 张表 + FTS5）
├── renderer/ # 渲染进程 ├── renderer/ # 渲染进程
│ ├── main.ts # 入口、全局初始化 │ ├── main.ts # 入口、全局初始化
│ ├── types.d.ts # 完整类型定义 │ ├── types.d.ts # 完整类型定义
│ ├── index.html # 入口 HTML │ ├── index.html # 入口 HTML
│ ├── api/ # API 封装 │ ├── api/
│ ├── components/ # UI 组件 │ │ └── ollama.ts # Ollama REST API 客户端
│ ├── services/ # 核心服务 │ ├── components/ # 13 个 UI 组件
│ ├── utils/ # 工具函数 │ ├── services/
│ ├── db/ # IndexedDB 封装 │ │ ├── agent-engine.ts # ReAct Agent Loop 引擎
│ ├── state/ # 状态管理 │ │ ├── tool-registry.ts # 工具注册与调度（25 个工具定义）
│ └── styles/ # 样式 │ │ ├── memory-manager.ts # 记忆管理核心
│ │ ├── vector-memory.ts # 记忆向量索引（IVF）
│ │ ├── vector-store.ts # 向量存储 + IVF 索引
│ │ ├── context-manager.ts # 上下文窗口管理
│ │ ├── document-processor.ts # 文档分块
│ │ ├── log-service.ts # 结构化日志
│ │ └── crypto.ts # AES-256-GCM 加密
│ ├── utils/
│ │ ├── utils.ts # 工具函数
│ │ ├── sanitizer.ts # HTML 净化器
│ │ └── marked-config.ts # Markdown 渲染
│ ├── state/
│ │ └── state.ts # 响应式状态管理
│ └── styles/
│ └── style.css # 暖色调亮色主题
└── ... └── ...
``` ```
@@ -85,66 +101,38 @@ logDebug('调试信息', '可选详情');
```typescript ```typescript
import { import {
logInit, // 初始化日志 logInit, logSetting, logToolStart, logToolResult,
logSetting, // 设置变更日志 logStream, logAgentLoop, logModelResponse,
logToolStart, // 工具开始执行 logSession, logThink, logMemory, logRAG
logToolResult, // 工具执行结果
logStream, // 流式输出日志
logAgentLoop, // Agent Loop 进度
logModelResponse,// 模型响应日志
logSession, // 会话操作日志
logThink, // 思考过程日志
logMemory, // 记忆系统日志
logRAG // 向量存储日志
} from './services/log-service.js'; } from './services/log-service.js';
``` ```
**日志详细度要求：**
- 每个 IPC 调用必须记录发起方、参数摘要、结果
- 文件操作记录路径（脱敏）、大小、操作类型
- 工具调用记录工具名、参数摘要、执行时长、结果状态
- 错误日志必须包含错误消息和上下文信息
- 进程管理记录进程 ID、命令摘要、退出码
**主进程日志**：通过 `mainWindow?.webContents.send('main:log', ...)` 发送到渲染进程日志面板。 **主进程日志**：通过 `mainWindow?.webContents.send('main:log', ...)` 发送到渲染进程日志面板。
### 4.3 IPC 规范 ### 4.3 IPC 规范
项目使用两种 IPC 模式：
| 模式 | 用途 | 超时 | | 模式 | 用途 | 超时 |
|------|------|------| |------|------|------|
| `invoke/handle` | 请求-响应，同步等待结果 | 有（默认） | | `invoke/handle` | 请求-响应，同步等待结果 | 有（默认） |
| `on/send` | 单向推送，流式通信 | 无 | | `on/send` | 单向推送，流式通信 | 无 |
**选择原则：** **选择原则**：需要返回值 → `invoke/handle`；流式输出/实时推送 → `on/send`；长时间运行命令 → `on/send`。
- 需要返回值 → `invoke/handle`
- 流式输出/实时推送 → `on/send`
- 长时间运行的命令 → `on/send`（避免超时问题）
- Tool Calling 工具执行 → `invoke/handle`（通过 workspace IPC 实现无超时）
### 4.4 安全规范 ### 4.4 安全规范
#### 文件系统安全 #### 文件系统安全
- 所有文件路径通过 `tool-security.ts` 的 `checkPathAllowed()` 验证 - 所有文件路径通过 `tool-security.ts` 的 `checkPathAllowed()` 验证
- 写操作仅允许在用户目录下进行 - 写操作仅允许在用户目录下进行
- 路径黑名单：`/etc`, `/sys`, `/proc`, `~/.ssh`, `~/.gnupg` 等 - 路径黑名单：`/etc`, `/sys`, `/proc`, `~/.ssh`, `~/.gnupg` 等
#### 命令执行安全 #### 命令执行安全
- 所有命令通过 `tool-security.ts` 的 `checkCommandAllowed()` 验证 - 所有命令通过 `tool-security.ts` 的 `checkCommandAllowed()` 验证
- 命令黑名单：`rm -rf /`, `mkfs`, `dd`, `shutdown`, 反弹 shell 检测等 - 命令黑名单：`rm -rf /`, `mkfs`, `dd`, `shutdown`, 反弹 shell 检测等
- `run_command` 支持三种模式（自动/需确认/禁用），用户可随时切换 - `run_command` 支持三种模式（自动/需确认/禁用），用户可随时切换
- 其余 20 个工具均为自动执行，无需用户确认 - 其余 24 个工具均为自动执行，无需用户确认
#### 前端安全 #### 前端安全
- 内置 HTML 净化器（白名单标签 + 属性过滤 + URI 协议检查） - 内置 HTML 净化器（白名单标签 + 属性过滤 + URI 协议检查）
- Markdown 链接仅允许 `http:` / `https:` / `mailto:` / `tel:`
- 阻止 `javascript:` / `vbscript:` / `data:` 协议注入
- `contextIsolation: true` + IPC 白名单 - `contextIsolation: true` + IPC 白名单
--- ---
@@ -154,42 +142,50 @@ import {
### 5.1 四大子系统 ### 5.1 四大子系统
``` ```
① Agent 系统 → agent-engine.ts + tool-registry.ts ① Agent 系统 → agent-engine.ts + tool-registry.ts（25 工具）
② 记忆系统 → memory-manager.ts + vector-memory.ts ② 记忆系统 → memory-manager.ts + vector-memory.ts
③ 向量存储 → vector-store.ts ③ 向量存储 → vector-store.ts（IVF 索引）
④ 工作空间 → workspace.ts (主进程) + workspace-panel.ts (渲染进程) ④ 工作空间 → workspace.ts (主进程) + workspace-panel.ts (渲染进程)
⑤ 数据层 → db/sqlite.ts（SQLite, 6 张表, FTS5）
``` ```
### 5.2 Tool Calling 流程 ### 5.2 ReAct Agent Loop
``` ```
用户消息 → Agent Loop → 模型 tool_calls → 工具执行（run_command 需确认） → 结果回传 → 循环 用户消息 → Thought → Action(tool_calls) → Observation(result) → Reflection → 循环 → Final Answer
``` ```
- 最大循环次数：10 - 最大循环次数：15
- 全局超时：5 分钟 - 全局超时：10 分钟
- 除 run_command 外所有 20 个工具自动执行无需确认 - 工具执行超时：30 秒（run_command 除外，走 workspace 无超时）
- run_command 支持三模式：自动执行 / 需确认 / 禁用（通过工具面板下拉框切换） - 流式调用超时：2 分钟
- run_command：无超时（通过 workspace IPC 执行） - 自动重试：最多 2 次
- 其他工具：30 秒超时 - **去重机制**：工具调用缓存 + 同轮内重复检测 + 跨轮次重复检测
- **去重机制**：工具调用缓存（`toolResultCache`）+ 同轮内重复检测 + 跨轮次重复检测（连续两轮相同则终止）
### 5.3 联网搜索与网页抓取联动 ### 5.3 SQLite 数据库
6 张表，WAL 模式 + NORMAL 同步：
| 表 | 用途 | 关键特性 |
|---|---|---|
| `sessions` | 会话 | parent_id 父子关系 |
| `messages` | 消息 | 外键级联删除，thinking/tool_calls |
| `tool_calls` | 工具调用记录 | 按会话+工具名索引 |
| `memories` | Agent 记忆 | FTS5 全文搜索，向量嵌入 |
| `settings` | 设置 | JSON 序列化 |
| `traces` | ReAct 执行轨迹 | Agent 可观测性 |
### 5.4 联网搜索联动
- web_search 返回搜索结果（标题、URL、摘要），默认 15 条 - web_search 返回搜索结果（标题、URL、摘要），默认 15 条
- TOOL_USAGE_GUIDE 要求模型在 web_search 后必须选择相关 URL 调用 web_fetch 抓取详情 - TOOL_USAGE_GUIDE 要求模型在 web_search 后必须选择相关 URL 调用 web_fetch 抓取详情
- 模型被引导主动使用工具：不确定答案、信息过时、需实时数据时应调用工具而非猜测 - web_fetch 默认返回完整内容（`max_chars=0`），不截断
- web_fetch 默认返回完整内容（`max_chars=0`），不截断；仅用户显式指定 `max_chars` 时才截断
### 5.4 工作空间与 AI 集成 ### 5.5 工作空间与 AI 集成
- AI 通过 `run_command` 工具执行命令，命令在工作空间终端实时显示 - AI 通过 `run_command` 工具执行命令，命令在工作空间终端实时显示
- 执行路径：`tool-registry.ts` → `bridge.workspace.execTool()` → IPC `tool:execute` → `handleRunCommand()` → `spawn` 子进程 - 执行路径：tool-registry.ts → bridge.workspace.execTool() → IPC → handleRunCommand() → spawn
- 主进程 `handleRunCommand` 执行命令，stdout/stderr 通过 `cmd:output` 实时推送到渲染进程终端面板 - stdout/stderr 通过 `cmd:output` 实时推送到渲染进程终端面板
- 进程结束后通过 `cmd:done` 通知渲染进程，结果回传 AI
- 用户可通过工作空间面板停止按钮终止命令（`cmd:kill`）
- 命令执行前经过 `checkCommandAllowed()` 安全检查
- `run_command` 需确认模式下由用户确认后才执行；自动模式下直接执行
--- ---
@@ -197,10 +193,13 @@ import {
### 6.1 设计语言 ### 6.1 设计语言
- **风格**：Windows 11 Fluent Design 暗色主题 - **风格**：暖色调亮色主题
- **材质**：Mica 毛玻璃 + Acrylic 亚克力 - **背景**：奶白 `#FAF7F2`，卡片白 `#FFFFFF`
- **字体**：Segoe UI Variable (正文) + Cascadia Mono (代码) - **主色调**：珊瑚橙 `#E8734A`
- **圆角**：控件 4px，卡片 8px，弹框 12-16px - **辅助色**：紫色 `#9B7ED8`（Think），金色 `#D4A03C`（Token）
- **字体**：Inter (正文) + JetBrains Mono (代码)
- **圆角**：控件 8px，卡片 12px，弹框 16-20px
- **终端区域**：暖棕深色 `#2D2016`，保证代码可读性
### 6.2 Z-Index 层级规范 ### 6.2 Z-Index 层级规范
@@ -214,12 +213,9 @@ import {
| 低层 | 工作空间面板 | 10 | | 低层 | 工作空间面板 | 10 |
| 基础 | 日志面板 | 5 | | 基础 | 日志面板 | 5 |
**规则**：新增固定定位元素必须指定 z-index 并在此表中记录。
### 6.3 响应式规则 ### 6.3 响应式规则
- 工作空间面板宽度：固定 480px（v3.2.5 起不可拖拽调整，v3.2.6 起改为 flex 子元素） - 工作空间面板宽度：固定 480px（flex 子元素）
- 主内容区始终带 `with-workspace` class，面板常驻显示
- 模态框宽度：基础 480px，大号 860px - 模态框宽度：基础 480px，大号 860px
--- ---
@@ -243,26 +239,25 @@ npm run dist # 构建 Windows 安装包
| 文件 | 内容 | | 文件 | 内容 |
|------|------| |------|------|
| `package.json` | `"version": "X.Y.Z"` | | `package.json` | `"version": "X.Y.Z"` |
| `package-lock.json` | 顶层 version 字段（2 处） |
| `src/renderer/index.html` | `<span class="app-version">vX.Y.Z</span>` | | `src/renderer/index.html` | `<span class="app-version">vX.Y.Z</span>` |
| `README.md` | 版本徽章、下载文件名、构建分支引用 | | `README.md` | 版本徽章、下载文件名、构建分支引用 |
| `docs/BUILD.md` | 构建分支引用、新增构建日志条目 | | `docs/BUILD.md` | 构建分支引用、新增构建日志条目 |
| `docs/CHANGELOG.md` | 版本分支结构链、新增版本说明条目 | | `docs/CHANGELOG.md` | 版本分支结构链、新增版本说明条目 |
| `docs/DEVELOPMENT.md` | 文件头部版本号 |
### 更新日志 ### 更新日志
- **所有更新日志只写在 `docs/CHANGELOG.md`** - **所有更新日志只写在 `docs/CHANGELOG.md`**
- `README.md` 不写历史版本记录，只保留一行链接指向 `docs/CHANGELOG.md` - `README.md` 不写历史版本记录，只保留一行链接指向 `docs/CHANGELOG.md`
- 版本分支结构链在 `docs/CHANGELOG.md` 顶部维护
### 7.2 发布流程 ### 7.2 发布流程
1. 更新 `package.json` 版本号 1. 更新版本号（同步上述文件）
2. 更新 `docs/CHANGELOG.md` 2. 更新 `docs/CHANGELOG.md`
3. 更新 `README.md`（如需） 3. 构建并测试：`npm start`
4. 构建并测试：`npm start` 4. 构建安装包：`npm run dist`
5. 构建安装包：`npm run dist` 5. 推送到 develop → 合并到 master → 创建版本分支
6. 推送到 Gitee：`git add -A && git commit && git push origin develop`
7. 创建 Release Tag
--- ---
@@ -272,46 +267,30 @@ npm run dist # 构建 Windows 安装包
- `master` — 稳定发布版本 - `master` — 稳定发布版本
- `develop` — 开发主分支 - `develop` — 开发主分支
- `metona-ollama-desktop-vX.Y.Z` — 每个版本对应的发布分支 - `metona-ollama-desktop-vX.Y.Z` — 版本发布分支
- `feature/*` — 功能开发 - `feature/*` — 功能开发
- `fix/*` — Bug 修复 - `fix/*` — Bug 修复
### 提交规则
- **默认只推送到当前所在分支**
- 需要同步到其他分支时，用户会明确指定
- 不要自作主张往多个分支推送
### Commit 规范 ### Commit 规范
``` ```
<type>: <简要描述> <type>: <简要描述>
类型 (type): feat: 新功能
- feat: 新功能 fix: Bug 修复
- fix: Bug 修复 refactor: 重构
- refactor: 重构 style: 样式调整
- style: 样式调整 docs: 文档更新
- docs: 文档更新 chore: 构建/工具变更
- chore: 构建/工具变更 perf: 性能优化
- perf: 性能优化
```
示例：
```
feat: 工作空间与 AI Tool Calling 集成
fix: 工作空间面板遮挡 Header 的 z-index 问题
refactor: run_command 改用 workspace IPC 无超时执行
docs: 新增开发规范文档
``` ```
--- ---
## 九、注意事项 ## 九、注意事项
1. **零外部依赖**：新增功能优先使用内联实现，避免引入 npm 包 1. **零外部依赖**：新增功能优先使用内联实现，避免引入 npm 包（better-sqlite3 除外）
2. **安全优先**：所有文件/命令操作必须经过安全检查层 2. **安全优先**：所有文件/命令操作必须经过安全检查层
3. **日志完整**：关键操作必须记录到执行日志面板 3. **日志完整**：关键操作必须记录到执行日志面板
4. **无超时设计**：工作空间相关操作不设超时，由用户控制生命周期 4. **无超时设计**：工作空间相关操作不设超时，由用户控制生命周期
5. **命令安全**：`run_command` 支持三模式切换（自动/需确认/禁用），其余工具自动执行 5. **桌面优先**：API 调用必须检查 `bridge.isDesktop`，非桌面环境优雅降级
6. **桌面优先**：API 调用必须检查 `bridge.isDesktop`，非桌面环境优雅降级