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
docs/DEVELOPMENT.md
+97 -118
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`) |
| 桌面框架 | Electron | ≥33 |
| 构建工具 | Vite (渲染进程) + tsc (主进程) | Vite ≥5 |
| 数据存储 | IndexedDB | 原生 API，无 ORM |
| 数据存储 | better-sqlite3 | ≥12.9，WAL 模式，FTS5 全文搜索 |
| 打包 | electron-builder | NSIS 格式 |
---
@@ -26,27 +26,43 @@ Metona Ollama Desktop 是基于 TypeScript + Electron 的本地 Ollama AI 桌面
```
src/
├── main/ # Electron 主进程
│ ├── main.ts # 入口、窗口管理
│ ├── preload.ts # contextBridge API 暴露
│ ├── ipc.ts # IPC 处理器（invoke/handle + on/send）
│ ├── workspace.ts # 子进程管理、流式输出
│ ├── tool-handlers.ts # Tool Calling 工具实现
│ ├── tool-security.ts # 路径/命令安全检查
│ ├── menu.ts # 原生菜单
│ ├── tray.ts # 系统托盘
│ └── utils.ts # 工具函数
├── renderer/ # 渲染进程
│ ├── main.ts # 入口、全局初始化
│ ├── types.d.ts # 完整类型定义
│ ├── index.html # 入口 HTML
│ ├── api/ # API 封装
│ ├── components/ # UI 组件
│ ├── services/ # 核心服务
│ ├── utils/ # 工具函数
│ ├── db/ # IndexedDB 封装
│ ├── state/ # 状态管理
│ └── styles/ # 样式
├── main/ # Electron 主进程
│ ├── main.ts # 入口、窗口管理
│ ├── preload.ts # contextBridge API 暴露
│ ├── ipc.ts # IPC 处理器（invoke/handle + on/send）
│ ├── workspace.ts # 子进程管理、流式输出
│ ├── tool-handlers.ts # Tool Calling 25 个工具实现
│ ├── tool-security.ts # 路径/命令安全检查
│ ├── menu.ts # 原生菜单
│ ├── tray.ts # 系统托盘
│ ├── utils.ts # 工具函数
│ └── db/
│ └── sqlite.ts # SQLite 数据库层（6 张表 + FTS5）
├── renderer/ # 渲染进程
│ ├── main.ts # 入口、全局初始化
│ ├── types.d.ts # 完整类型定义
│ ├── index.html # 入口 HTML
│ ├── api/
│ │ └── ollama.ts # Ollama REST API 客户端
│ ├── components/ # 13 个 UI 组件
│ ├── services/
│ │ ├── agent-engine.ts # ReAct Agent Loop 引擎
│ │ ├── tool-registry.ts # 工具注册与调度（25 个工具定义）
│ │ ├── 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
import {
logInit, // 初始化日志
logSetting, // 设置变更日志
logToolStart, // 工具开始执行
logToolResult, // 工具执行结果
logStream, // 流式输出日志
logAgentLoop, // Agent Loop 进度
logModelResponse,// 模型响应日志
logSession, // 会话操作日志
logThink, // 思考过程日志
logMemory, // 记忆系统日志
logRAG // 向量存储日志
logInit, logSetting, logToolStart, logToolResult,
logStream, logAgentLoop, logModelResponse,
logSession, logThink, logMemory, logRAG
} from './services/log-service.js';
```
**日志详细度要求：**
- 每个 IPC 调用必须记录发起方、参数摘要、结果
- 文件操作记录路径（脱敏）、大小、操作类型
- 工具调用记录工具名、参数摘要、执行时长、结果状态
- 错误日志必须包含错误消息和上下文信息
- 进程管理记录进程 ID、命令摘要、退出码
**主进程日志**：通过 `mainWindow?.webContents.send('main:log', ...)` 发送到渲染进程日志面板。
### 4.3 IPC 规范
项目使用两种 IPC 模式：
| 模式 | 用途 | 超时 |
|------|------|------|
| `invoke/handle` | 请求-响应，同步等待结果 | 有（默认） |
| `on/send` | 单向推送，流式通信 | 无 |
**选择原则：**
- 需要返回值 → `invoke/handle`
- 流式输出/实时推送 → `on/send`
- 长时间运行的命令 → `on/send`（避免超时问题）
- Tool Calling 工具执行 → `invoke/handle`（通过 workspace IPC 实现无超时）
**选择原则**：需要返回值 → `invoke/handle`；流式输出/实时推送 → `on/send`；长时间运行命令 → `on/send`。
### 4.4 安全规范
#### 文件系统安全
- 所有文件路径通过 `tool-security.ts` 的 `checkPathAllowed()` 验证
- 写操作仅允许在用户目录下进行
- 路径黑名单：`/etc`, `/sys`, `/proc`, `~/.ssh`, `~/.gnupg` 等
#### 命令执行安全
- 所有命令通过 `tool-security.ts` 的 `checkCommandAllowed()` 验证
- 命令黑名单：`rm -rf /`, `mkfs`, `dd`, `shutdown`, 反弹 shell 检测等
- `run_command` 支持三种模式（自动/需确认/禁用），用户可随时切换
- 其余 20 个工具均为自动执行，无需用户确认
- 其余 24 个工具均为自动执行，无需用户确认
#### 前端安全
- 内置 HTML 净化器（白名单标签 + 属性过滤 + URI 协议检查）
- Markdown 链接仅允许 `http:` / `https:` / `mailto:` / `tel:`
- 阻止 `javascript:` / `vbscript:` / `data:` 协议注入
- `contextIsolation: true` + IPC 白名单
---
@@ -154,42 +142,50 @@ import {
### 5.1 四大子系统
```
① Agent 系统 → agent-engine.ts + tool-registry.ts
① Agent 系统 → agent-engine.ts + tool-registry.ts（25 工具）
② 记忆系统 → memory-manager.ts + vector-memory.ts
③ 向量存储 → vector-store.ts
③ 向量存储 → vector-store.ts（IVF 索引）
④ 工作空间 → 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
- 全局超时：5 分钟
- 除 run_command 外所有 20 个工具自动执行无需确认
- run_command 支持三模式：自动执行 / 需确认 / 禁用（通过工具面板下拉框切换）
- run_command：无超时（通过 workspace IPC 执行）
- 其他工具：30 秒超时
- **去重机制**：工具调用缓存（`toolResultCache`）+ 同轮内重复检测 + 跨轮次重复检测（连续两轮相同则终止）
- 最大循环次数：15
- 全局超时：10 分钟
- 工具执行超时：30 秒（run_command 除外，走 workspace 无超时）
- 流式调用超时：2 分钟
- 自动重试：最多 2 次
- **去重机制**：工具调用缓存 + 同轮内重复检测 + 跨轮次重复检测
### 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 条
- TOOL_USAGE_GUIDE 要求模型在 web_search 后必须选择相关 URL 调用 web_fetch 抓取详情
- 模型被引导主动使用工具：不确定答案、信息过时、需实时数据时应调用工具而非猜测
- web_fetch 默认返回完整内容（`max_chars=0`），不截断；仅用户显式指定 `max_chars` 时才截断
- web_fetch 默认返回完整内容（`max_chars=0`），不截断
### 5.4 工作空间与 AI 集成
### 5.5 工作空间与 AI 集成
- AI 通过 `run_command` 工具执行命令，命令在工作空间终端实时显示
- 执行路径：`tool-registry.ts` → `bridge.workspace.execTool()` → IPC `tool:execute` → `handleRunCommand()` → `spawn` 子进程
- 主进程 `handleRunCommand` 执行命令，stdout/stderr 通过 `cmd:output` 实时推送到渲染进程终端面板
- 进程结束后通过 `cmd:done` 通知渲染进程，结果回传 AI
- 用户可通过工作空间面板停止按钮终止命令（`cmd:kill`）
- 命令执行前经过 `checkCommandAllowed()` 安全检查
- `run_command` 需确认模式下由用户确认后才执行；自动模式下直接执行
- 执行路径：tool-registry.ts → bridge.workspace.execTool() → IPC → handleRunCommand() → spawn
- stdout/stderr 通过 `cmd:output` 实时推送到渲染进程终端面板
---
@@ -197,10 +193,13 @@ import {
### 6.1 设计语言
- **风格**：Windows 11 Fluent Design 暗色主题
- **材质**：Mica 毛玻璃 + Acrylic 亚克力
- **字体**：Segoe UI Variable (正文) + Cascadia Mono (代码)
- **圆角**：控件 4px，卡片 8px，弹框 12-16px
- **风格**：暖色调亮色主题
- **背景**：奶白 `#FAF7F2`，卡片白 `#FFFFFF`
- **主色调**：珊瑚橙 `#E8734A`
- **辅助色**：紫色 `#9B7ED8`（Think），金色 `#D4A03C`（Token）
- **字体**：Inter (正文) + JetBrains Mono (代码)
- **圆角**：控件 8px，卡片 12px，弹框 16-20px
- **终端区域**：暖棕深色 `#2D2016`，保证代码可读性
### 6.2 Z-Index 层级规范
@@ -214,12 +213,9 @@ import {
| 低层 | 工作空间面板 | 10 |
| 基础 | 日志面板 | 5 |
**规则**：新增固定定位元素必须指定 z-index 并在此表中记录。
### 6.3 响应式规则
- 工作空间面板宽度：固定 480px（v3.2.5 起不可拖拽调整，v3.2.6 起改为 flex 子元素）
- 主内容区始终带 `with-workspace` class，面板常驻显示
- 工作空间面板宽度：固定 480px（flex 子元素）
- 模态框宽度：基础 480px，大号 860px
---
@@ -243,26 +239,25 @@ npm run dist # 构建 Windows 安装包
| 文件 | 内容 |
|------|------|
| `package.json` | `"version": "X.Y.Z"` |
| `package-lock.json` | 顶层 version 字段（2 处） |
| `src/renderer/index.html` | `<span class="app-version">vX.Y.Z</span>` |
| `README.md` | 版本徽章、下载文件名、构建分支引用 |
| `docs/BUILD.md` | 构建分支引用、新增构建日志条目 |
| `docs/CHANGELOG.md` | 版本分支结构链、新增版本说明条目 |
| `docs/DEVELOPMENT.md` | 文件头部版本号 |
### 更新日志
- **所有更新日志只写在 `docs/CHANGELOG.md`**
- `README.md` 不写历史版本记录，只保留一行链接指向 `docs/CHANGELOG.md`
- 版本分支结构链在 `docs/CHANGELOG.md` 顶部维护
### 7.2 发布流程
1. 更新 `package.json` 版本号
1. 更新版本号（同步上述文件）
2. 更新 `docs/CHANGELOG.md`
3. 更新 `README.md`（如需）
4. 构建并测试：`npm start`
5. 构建安装包：`npm run dist`
6. 推送到 Gitee：`git add -A && git commit && git push origin develop`
7. 创建 Release Tag
3. 构建并测试：`npm start`
4. 构建安装包：`npm run dist`
5. 推送到 develop → 合并到 master → 创建版本分支
---
@@ -272,46 +267,30 @@ npm run dist # 构建 Windows 安装包
- `master` — 稳定发布版本
- `develop` — 开发主分支
- `metona-ollama-desktop-vX.Y.Z` — 每个版本对应的发布分支
- `metona-ollama-desktop-vX.Y.Z` — 版本发布分支
- `feature/*` — 功能开发
- `fix/*` — Bug 修复
### 提交规则
- **默认只推送到当前所在分支**
- 需要同步到其他分支时，用户会明确指定
- 不要自作主张往多个分支推送
### Commit 规范
```
<type>: <简要描述>
类型 (type):
- feat: 新功能
- fix: Bug 修复
- refactor: 重构
- style: 样式调整
- docs: 文档更新
- chore: 构建/工具变更
- perf: 性能优化
```
示例：
```
feat: 工作空间与 AI Tool Calling 集成
fix: 工作空间面板遮挡 Header 的 z-index 问题
refactor: run_command 改用 workspace IPC 无超时执行
docs: 新增开发规范文档
feat: 新功能
fix: Bug 修复
refactor: 重构
style: 样式调整
docs: 文档更新
chore: 构建/工具变更
perf: 性能优化
```
---
## 九、注意事项
1. **零外部依赖**：新增功能优先使用内联实现，避免引入 npm 包
1. **零外部依赖**：新增功能优先使用内联实现，避免引入 npm 包（better-sqlite3 除外）
2. **安全优先**：所有文件/命令操作必须经过安全检查层
3. **日志完整**：关键操作必须记录到执行日志面板
4. **无超时设计**：工作空间相关操作不设超时，由用户控制生命周期
5. **命令安全**：`run_command` 支持三模式切换（自动/需确认/禁用），其余工具自动执行
6. **桌面优先**：API 调用必须检查 `bridge.isDesktop`，非桌面环境优雅降级
5. **桌面优先**：API 调用必须检查 `bridge.isDesktop`，非桌面环境优雅降级