Files

T

thzxx f3f81b135d Reapply "docs: 添加推荐记忆规则到 README"

This reverts commit 5e5145cb17.

2026-04-24 15:42:05 +08:00

8.6 KiB

Raw Blame History

Metona Ollama Desktop

本地 Ollama AI 桌面客户端 — TypeScript + Electron

简介

Metona Ollama Desktop 是一个基于 Ollama 的本地 AI 桌面客户端，支持 Tool Calling、记忆系统、浏览器控制、MCP 协议等能力。数据不离开本机，零配置启动。

特性

🤖 ReAct Agent Loop — Thought → Action → Observation → Reflection 循环，默认最大 85 轮
🔧 38 个内置工具 — 文件系统/命令执行/联网搜索/浏览器/Git/记忆/技能/会话/子代理
🧠 智能记忆系统 — 三类记忆（fact/preference/rule）+ FTS5 全文搜索 + 向量语义搜索 + 安全扫描
🌐 MCP 协议 — JSON-RPC 2.0 over stdio，动态工具发现与执行，Shadowing 防护
🔍 三引擎联网搜索 — Bing + 百度 + Google
🖥️ 工作空间面板 — 终端（实时流式输出）+ 文件浏览器一体化
🎨 暖色调 UI — 奶白 #FAF7F2 + 珊瑚橙 #E8734A，长时间使用不疲劳

工具列表

分类	数量	工具
文件系统	17	read_file, write_file, list_directory, search_files, create_directory, delete_file, move_file, copy_file, append_file, edit_file, get_file_info, tree, download_file, diff_files, replace_in_files, read_multiple_files, compress
命令执行	1	run_command（实时流式输出，工作空间终端集成）
联网搜索	2	web_search（Bing + 百度 + Google 三引擎）, web_fetch
浏览器控制	8	browser_open, browser_screenshot, browser_evaluate, browser_extract, browser_click, browser_type, browser_scroll, browser_close
Git	1	git（init/clone/add/commit/push/pull/diff/log/status/branch/checkout/merge/stash/reset/tag/remote）
记忆管理	4	memory_search, memory_add, memory_replace, memory_remove
技能系统	2	skill_list, skill_view（渐进式加载）
会话管理	2	session_list, session_read
子代理	1	spawn_task（独立上下文 + 超时保护）

架构

用户消息 → Agent Loop（ReAct）
              ↓
         记忆检索（FTS5 + 向量搜索）→ 上下文注入
              ↓
         Ollama API（流式响应）
              ↓
         工具调用（38 内置 + MCP 动态）
              ↓
         观察结果 → 反思 → 循环/最终回答

数据层

SQLite (sql.js WASM)：7 张表（sessions, messages, tool_calls, memories, settings, traces, skills）
FTS5 全文搜索：memories 表支持全文检索
WAL 模式 + NORMAL 同步：零原生依赖，无需 electron-rebuild

记忆系统

三类记忆：fact（事实）、preference（偏好）、rule（规则，始终注入）
安全扫描：写入前检测 prompt injection、敏感信息泄露、不可见 Unicode 字符
容量管理：上限 500 条，超限自动清理低价值条目（rule 类型受保护）
过期衰减：90 天未使用的记忆自动降低 importance

技术栈

层级	技术
语言	TypeScript (strict mode)
桌面框架	Electron 33+
构建	Vite（渲染进程）+ tsc（主进程）
数据库	sql.js (WASM) + FTS5
第三方库	marked（Markdown）, DOMPurify（HTML 净化）
打包	electron-builder (NSIS)

快速开始

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 安装包

# 环境：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（82MB）

项目结构

src/
├── main/                         # Electron 主进程
│   ├── main.ts                   # 入口、窗口管理
│   ├── preload.ts                # contextBridge API（53 个 invoke + 2 个 send）
│   ├── ipc.ts                    # IPC 处理器
│   ├── browser.ts                # 浏览器控制（8 个工具）
│   ├── mcp-manager.ts            # MCP 协议管理（JSON-RPC 2.0 over stdio）
│   ├── tool-handlers-fs.ts       # 文件系统工具（15 个）
│   ├── tool-handlers-system.ts   # 系统网络工具（6 个）
│   ├── tool-handlers-git.ts      # Git 工具
│   ├── tool-handlers-shared.ts   # 共享工具函数
│   ├── tool-security.ts          # 路径/命令安全检查
│   └── db/sqlite.ts              # SQLite 数据库层（7 张表 + FTS5）
├── renderer/                     # 渲染进程
│   ├── main.ts                   # 入口、全局初始化
│   ├── services/
│   │   ├── agent-engine.ts       # ReAct Agent Loop 引擎
│   │   ├── tool-registry.ts      # 工具注册与调度（38 个内置 + MCP 动态）
│   │   ├── memory-manager.ts     # 记忆管理核心
│   │   ├── vector-memory.ts      # 记忆向量索引（IVF）
│   │   ├── vector-store.ts       # 向量存储
│   │   ├── context-manager.ts    # 上下文窗口管理
│   │   ├── skill-manager.ts      # 技能自动生成
│   │   ├── sub-agent.ts          # 子代理委派
│   │   ├── mcp-client.ts         # MCP 渲染端客户端
│   │   ├── log-service.ts        # 结构化日志
│   │   └── crypto.ts             # AES-256-GCM 加密
│   ├── components/               # UI 组件（14 个）
│   ├── utils/
│   │   ├── utils.ts              # 工具函数
│   │   ├── sanitizer.ts          # HTML 净化器
│   │   └── marked-config.ts      # Markdown 渲染
│   ├── state/state.ts            # 响应式状态管理
│   ├── db/chat-db.ts             # SQLite 渲染端接口
│   ├── styles/style.css          # 暖色调亮色主题
│   └── index.html                # 入口 HTML
└── vendor/                       # 第三方库（marked, DOMPurify）

推荐记忆规则

以下是使用 Metona Ollama Desktop 时推荐预先写入记忆系统的规则（rule 类型），可帮助 Agent 更高效、更安全地工作：

🔧 开发类规则

规则	说明
`所有日志必须通过 log-service.ts 输出，禁止使用 console.log/error/warn`	项目铁律，保持日志面板统一
`新增第三方依赖优先 vendor 到 src/vendor/，避免 npm 运行时依赖`	项目依赖管理策略，sql.js 除外
`所有文件写入和命令执行必须经过 tool-security.ts 安全检查`	安全底线，防止越权操作
`TypeScript 严格模式，禁止滥用 any，类型定义集中在 types.d.ts`	代码质量保障
`文件名 kebab-case，类型 PascalCase，变量 camelCase，常量 UPPER_SNAKE_CASE`	命名规范统一

🧠 效率类规则

规则	说明
`联网搜索后必须用 web_fetch 抓取相关 URL 详情，不要只看摘要`	搜索结果摘要信息有限，抓取原文才能给出准确回答
`执行多步任务时优先使用子代理 spawn_task 分担，避免主会话上下文膨胀`	保持主会话响应速度
`复杂文件操作前先 list_directory 确认路径结构，再执行具体操作`	防止路径错误导致意外
`长对话中主动使用 session_list/session_read 回顾历史，避免重复工作`	利用会话管理工具保持连贯性

🛡️ 安全类规则

规则	说明
`禁止执行 rm -rf /、mkfs、dd、shutdown 等破坏性命令`	硬性安全红线
`写操作仅允许在用户工作目录下进行，系统目录只读`	路径安全策略
`记忆写入前自动扫描 prompt injection 和敏感信息，发现异常立即拒绝`	记忆系统安全机制
`MCP 工具注册时自动检测与内置工具重名，防止 Shadowing 攻击`	MCP 安全防护

💡 使用技巧

规则	说明
`记忆系统上限 500 条，优先写入高价值信息，低价值内容会自动清理`	合理利用记忆容量
`rule 类型记忆始终注入上下文，适合放铁律和偏好；fact/preference 按需检索`	区分记忆类型，提高注入效率
`技能系统会从成功任务中自动学习，遇到重复任务时优先查看已有技能`	利用技能系统减少重复推理

💡 提示：以上规则可通过 memory_add 工具写入，类型设为 rule，即可在每次对话中自动注入上下文。

许可证

MIT

8.6 KiB Raw Blame History Unescape Escape