MetonaAI Desktop
生产级通用 AI Agent 智能体桌面应用
Metona 是一款基于 Electron 的生产级 AI Agent 桌面应用，内置 ReAct 状态机驱动的智能体循环、27 个内置工具、三层记忆系统、四层安全防线与完整的可观测性链路。支持 DeepSeek、Agnes AI、MiMo（小米）、Ollama 四种 LLM Provider，兼容 MCP 协议扩展。
目录
技术栈
| 层级 | 技术 | 版本 |
|---|---|---|
| 运行时 | Electron | 35 |
| 前端框架 | React | 19 |
| 类型系统 | TypeScript | 5.8 |
| UI 组件库 | Material UI (MUI) | 9 |
| 状态管理 | Zustand | 5 |
| 数据库 | better-sqlite3 | 11 |
| 构建工具 | electron-vite + Vite | 3 / 6 |
| LLM 协议 | MCP SDK | 1.12 |
| 样式辅助 | Tailwind CSS | 4 |
| Markdown | react-markdown + remark-gfm | 10 / 4 |
| UUID | nanoid | 5 |
| 校验 | Zod | 3 |
| 缓存 | lru-cache | 11 |
| 日志 | electron-log | 5 |
| 配置存储 | electron-store | 10 |
快速开始
环境要求
- Node.js >= 18
- npm >= 9
- Windows / macOS / Linux
安装与运行
# 安装依赖
npm install
# 开发模式（启动 Electron + Vite 热重载）
npm run dev
# 类型检查
npm run typecheck
# 构建生产包（Windows 输出 NSIS 安装包 + 便携版）
npm run build
配置 LLM Provider
- 复制
.env.example为.env，填入 API Key：
cp .env.example .env
# DeepSeek API
DEEPSEEK_API_KEY=your_key
DEEPSEEK_BASE_URL=https://api.deepseek.com
# Agnes AI API
AGNES_API_KEY=your_key
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
# Ollama（本地运行，无需 Key）
OLLAMA_BASE_URL=http://localhost:11434
- 或在应用启动后，通过 设置 → LLM 配置 界面可视化配置 Provider、API Key、模型、上下文窗口等参数。
核心特性
智能体引擎
- ReAct 状态机：8 状态闭环（INIT → THINKING → PARSING → EXECUTING → OBSERVING → REFLECTING → COMPRESSING → TERMINATED）
- 流式对话：SSE（DeepSeek/Agnes）+ NDJSON（Ollama）双协议流式响应
- Thinking 模式：支持 deepseek-v4-pro / agnes-2.0-flash / qwen3 等模型的推理模式
- 死循环检测：连续 3 轮相同工具调用签名自动终止
- 上下文压缩：80% 阈值触发 LLM 摘要压缩，保留最近 10 条消息
- 错误重试：指数退避（1s/2s/4s，上限 30s）+ ±20% jitter
- 可配置迭代：最大迭代次数（默认 20）、总超时（默认 600s）、工具执行超时（默认 120s）
工具与执行
- 27 个内置工具：覆盖文件系统、代码搜索、网络搜索、浏览器自动化、Git、开发工具、记忆、任务管理等
- MCP 协议支持：动态加载外部 MCP Server 工具
- 子任务委派：TaskOrchestrator 支持最大 3 层深度的 SubAgent 编排
- 策略引擎：三级权限（READ/WRITE/EXTERNAL_ACTION）+ 滑动窗口频率限制
- 确认机制：HIGH/CRITICAL 风险工具需用户确认，支持会话内同类免确认与持久化自动执行
记忆与上下文
- 三层记忆系统：情节记忆（episodic）、语义记忆（semantic）、工作记忆（working）
- TF-IDF 语义检索：中英文分词 + 时间衰减（30 天半衰期）+ IDF 缓存
- 自动记忆固化：会话结束时 LLM 提取重要信息写入 MEMORY.md
- System Prompt 分区构建：SOUL.md + MEMORY.md + 安全准则（v0.3.14 移除 AGENTS.md 和 USERS.md）
安全防线（四层纵深防御）
- 路径安全：工作空间边界校验 + realpathSync 符号链接逃逸检测 + 根目录 MEMORY.md 保护
- 命令安全：SandboxManager 28 模式扫描 + shell-quote 双层防御 + 受保护文件检查
- 权限控制：PolicyEngine 三级权限 + 频率限制（20 次/分钟）+ 用户确认钩子
- 内容安全：PromptInjectionDefender（30+ 正则 + 语义检测）+ OutputValidator（幻觉检测）
可观测性
- 全链路追踪：TraceViewer 可视化 ReAct 每轮迭代
- 会话录制：9 种事件录制到 JSONL 文件
- 审计日志：SQLite 链式哈希防篡改（INSERT-ONLY 触发器）
- Token 统计：输入/输出/推理 Token 用量追踪
桌面体验
- 三栏布局：Sidebar + Chat + DetailPanel，支持专注模式
- 系统托盘：4 状态指示（idle/thinking/executing/error）
- 全局快捷键：Cmd/Ctrl+Shift+M 唤起应用
- 14 个应用内快捷键：会话管理、布局切换、主题切换等
- 暗色/亮色主题：跟随系统 + 手动切换
- 首次使用引导：5 步 Onboarding 向导
- 命令面板：Cmd/Ctrl+K 快速搜索
- 多平台构建：Windows（NSIS + 便携版）、macOS（DMG + ZIP）、Linux（AppImage + DEB）
项目架构
四层 Harness 架构
┌─────────────────────────────────────────────────────────────┐
│ L1 推理与编排层 │
│ AgentLoopEngine (ReAct 状态机) · TaskOrchestrator (子任务) │
│ MetonaRequest / MetonaResponse / MetonaStreamEvent │
├─────────────────────────────────────────────────────────────┤
│ L2 上下文与记忆层 │
│ ContextBuilder · MemoryManager · MemoryConsolidator │
│ MetonaContext / MetonaMemoryItem │
├─────────────────────────────────────────────────────────────┤
│ L3 工具与安全执行层 │
│ ToolRegistry · SandboxManager · PolicyEngine · MCPAdapter │
│ PromptInjectionDefender · OutputValidator · ConfirmationHook │
│ MetonaToolDef / MetonaToolCall / MetonaToolResult │
├─────────────────────────────────────────────────────────────┤
│ L4 支撑与基础架构层 │
│ ConfigService · DatabaseService · AuditService │
│ SessionService · SessionRecorder · WindowManager │
│ TrayManager · MCPManager · WorkspaceService │
└─────────────────────────────────────────────────────────────┘
进程模型
| 进程 | 运行时 | 职责 |
|---|---|---|
| Main Process | Node.js | Agent 引擎、工具调度、数据库、MCP 管理、配置 |
| Preload Script | 沙箱 | contextBridge 安全暴露 14 个 API 命名空间 |
| Renderer | Chromium | React 19 + MUI 9 界面渲染 |
数据流
用户输入 → ChatInput → agent-store.sendMessage
→ IPC: agent:sendMessage → handlers.ts
→ reloadAdapter (热重载，配置签名比对)
→ 保存用户消息到 SQLite
→ 加载历史消息 + 注入相关记忆
→ ContextBuilder.buildSystemPrompt (SOUL+AGENTS+USERS+MEMORY+安全准则)
→ PromptInjectionDefender.detect (riskScore>=7 阻断)
→ AgentLoopEngine.runStream
→ Adapter.sendStream (SSE/NDJSON 流式)
→ 流式事件 → webContents.send('agent:streamEvent')
→ 工具调用 → PreToolHooks (权限+频率+确认)
→ ToolRegistry.execute → PostToolHooks (审计+记忆触发)
→ 80% 阈值触发上下文压缩
→ 死循环检测 (3 轮相同签名)
→ OutputValidator.validate (幻觉检测)
→ 保存 assistant 消息 + tool 结果消息
→ MemoryConsolidator.consolidate (异步提取记忆)
→ AuditService.logSessionEnd
← useAgentStream Hook 监听事件 → Zustand Store → React 重渲染
内置工具
Metona 内置 27 个工具，按功能分类如下：
文件系统（5 个）
| 工具 | 风险 | 需确认 | 功能 |
|---|---|---|---|
read_file |
SAFE | 否 | 读取文本文件，二进制检测，offset/limit 分页 |
write_file |
MEDIUM | 是 | 原子写入（tmp+rename），支持 overwrite/append |
list_directory |
SAFE | 否 | 列出目录，depth（max 5）/glob/include_hidden |
search_files |
SAFE | 否 | 按模式搜索，content/files 模式，context_lines |
delete_file |
HIGH | 是 | 删除文件，禁止删除工作空间根目录和 MEMORY.md |
编辑与搜索（3 个）
| 工具 | 风险 | 需确认 | 功能 |
|---|---|---|---|
file_editor |
MEDIUM | 是 | 精准编辑，replace/insert/delete/regex + dry_run |
code_search |
SAFE | 否 | 基于 ripgrep 高速搜索，回退 JS |
diff_viewer |
SAFE | 否 | unified diff 格式，LCS 算法 |
网络与浏览器（4 个）
| 工具 | 风险 | 需确认 | 功能 |
|---|---|---|---|
web_search |
LOW | 否 | 双模式（SearXNG / 内置四引擎），智能排序，自动抓取 |
web_fetch |
LOW | 否 | 三阶段回退（HTTP + 反爬 + 浏览器渲染），10MB 限制 |
web_browser |
HIGH | 是 | 浏览器自动化，9 个 action（open/screenshot/extract 等） |
http_request |
LOW | 否 | HTTP/REST API 请求，6 种 method |
记忆（2 个）
| 工具 | 风险 | 需确认 | 功能 |
|---|---|---|---|
memory_store |
MEDIUM | 否 | 存储记忆到三层（episodic/semantic/working） |
memory_search |
SAFE | 否 | TF-IDF 检索记忆，时间衰减 |
命令与开发（5 个）
| 工具 | 风险 | 需确认 | 功能 |
|---|---|---|---|
run_command |
HIGH | 是 | 沙箱执行 Shell 命令，双重校验 + shell-quote 防御 |
lint_code |
SAFE | 否 | TypeScript tsc 或 ESLint 检查 |
run_tests |
LOW | 否 | 运行测试套件，filter 字符白名单防注入 |
project_info |
SAFE | 否 | 项目结构分析，4 种 detail |
delegate_task |
MEDIUM | 否 | 子任务委派给独立 SubAgent |
Git（4 个）
| 工具 | 风险 | 需确认 | 功能 |
|---|---|---|---|
git_status |
SAFE | 否 | 工作树状态，porcelain v1 解析 |
git_diff |
SAFE | 否 | diff 输出，50KB 截断，5MB maxBuffer |
git_log |
SAFE | 否 | 提交历史，jest/vitest/mocha 格式解析 |
git_commit |
MEDIUM | 是 | 暂存+提交，校验 file 在 workspace 内 |
任务与辅助（4 个）
| 工具 | 风险 | 需确认 | 功能 |
|---|---|---|---|
task_manager |
LOW | 否 | 持久化任务 CRUD，支持父子关系，写入后通知 UI 刷新 |
think |
SAFE | 否 | 结构化思考空间，无副作用 |
view_image |
SAFE | 否 | 读取图片返回 base64，5MB 限制，7 种格式 |
LLM 适配器
| 适配器 | Provider ID | 模型 | 上下文窗口 | 流式格式 | Thinking | 多模态 |
|---|---|---|---|---|---|---|
| DeepSeekAdapter | deepseek | deepseek-v4-pro / deepseek-v4-flash | 1M（可配） | SSE | thinking + reasoning_effort | 否 |
| AgnesAdapter | agnes | agnes-2.0-flash | 1M（可配） | SSE | chat_template_kwargs | 是（URL） |
| MimoAdapter | mimo | mimo-v2.5-pro / mimo-v2.5 | 131072（可配） | SSE | thinking.type | 是（URL） |
| OllamaAdapter | ollama | qwen3 / gemma3 / deepseek-r1 | 4096（可配 num_ctx） | NDJSON | think 参数 | 是（Base64） |
上下文窗口配置
- DeepSeek / Agnes / MiMo：
contextWindow配置项影响本地压缩判断和 UI 显示（最小 4096） - Ollama：
num_ctx配置项直接影响 API 请求参数 - 切换 Provider 时自动清空 API Key，防止使用不兼容的密钥
- Engine 上下文窗口与 Adapter 配置值自动同步
记忆系统
三层记忆架构
| 层级 | 类型 | 存储表 | 用途 | 检索方式 |
|---|---|---|---|---|
| L2 | 情节记忆 (episodic) | episodic_memories | 会话事件、用户交互 | TF-IDF + 时间衰减 |
| L3 | 语义记忆 (semantic) | semantic_memories | 知识、偏好、事实 | 精确 + 模糊匹配 |
| L1 | 工作记忆 (working) | working_memories | 当前任务临时状态 | 精确键值查找 |
记忆生命周期
新记忆写入 → 重要性评分 (0-1)
├── 高 (>0.8) → 永久保存
├── 中 (0.4-0.8) → 定期回顾，逐渐衰减
└── 低 (<0.4) → 短期保留，自然遗忘
会话结束 → MemoryConsolidator 提取重要信息 → 写入 MEMORY.md
磁盘文件（工作空间）
| 文件 | 用途 | 是否必需 |
|---|---|---|
| SOUL.md | AI 角色定义（灵魂） | 是 |
| MEMORY.md | 动态记忆存储 | 是（仅根目录受保护） |
安全机制
四层纵深防御
第 1 层：路径安全
└─ isPathWithinWorkspace + realpathSync + MEMORY.md 保护
第 2 层：命令安全
└─ SandboxManager (28 模式扫描) + shell-quote 双层防御
第 3 层：权限控制
└─ PolicyEngine (三级权限) + 频率限制 (20/min) + ConfirmationHook
第 4 层：内容安全
└─ PromptInjectionDefender (30+ 正则 + 语义检测) + OutputValidator (幻觉检测)
风险分级
| 风险等级 | 示例工具 | 确认要求 |
|---|---|---|
| SAFE | read_file, list_directory, code_search | 无需确认 |
| LOW | web_search, web_fetch, http_request | 无需确认 |
| MEDIUM | write_file, file_editor, memory_store | 可配置自动执行 |
| HIGH | delete_file, run_command, web_browser, git_commit | 强制确认 |
| CRITICAL | （预留） | 强制确认 + 双人复核 |
配置说明
环境变量（.env）
# DeepSeek API
DEEPSEEK_API_KEY=your_deepseek_api_key_here
DEEPSEEK_BASE_URL=https://api.deepseek.com
# Agnes AI API
AGNES_API_KEY=your_agnes_api_key_here
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
# Xiaomi MiMo API
MIMO_API_KEY=your_mimo_api_key_here
MIMO_BASE_URL=https://api.xiaomimimo.com/v1
# Ollama API (local)
OLLAMA_BASE_URL=http://localhost:11434
# App
VITE_APP_TITLE=MetonaAI Desktop
应用配置（app_config 表）
关键配置项及默认值：
| 配置项 | 默认值 | 说明 |
|---|---|---|
llm.provider |
deepseek | LLM Provider |
llm.model |
deepseek-v4-pro | 模型名称 |
agent.maxIterations |
20 | 最大迭代次数 |
agent.totalTimeoutMs |
600000 | 总超时（ms） |
agent.thinkingEnabled |
true | Thinking 模式 |
agent.thinkingEffort |
high | 推理强度 |
agent.confirmationTimeoutMs |
120000 | 确认超时（30s~600s） |
deepseek.contextWindow |
1000000 | DeepSeek 上下文窗口 |
agnes.contextWindow |
1000000 | Agnes 上下文窗口 |
mimo.contextWindow |
131072 | MiMo 上下文窗口 |
ollama.numCtx |
4096 | Ollama 上下文窗口 |
SearXNG 配置（可选）
启用 SearXNG 元搜索引擎替代内置四引擎搜索，支持 12 项配置（URL、引擎列表、认证方式等），详见设置界面。
项目结构
MetonaAI-Desktop/
├── electron/ # Electron 主进程
│ ├── main.ts # 应用入口（538 行）
│ ├── preload.ts # 安全桥接（14 个 API 命名空间）
│ ├── ipc/
│ │ └── handlers.ts # IPC 通道处理（50+ 通道）
│ ├── services/ # 业务服务层
│ │ ├── audit.service.ts # 审计日志（链式哈希防篡改）
│ │ ├── config.service.ts # 配置管理
│ │ ├── database.service.ts # SQLite 数据库（9 张表）
│ │ ├── mcp-manager.service.ts # MCP Server 管理
│ │ ├── session-recorder.service.ts # 会话录制
│ │ ├── session.service.ts # 会话 CRUD
│ │ ├── tray-manager.service.ts # 系统托盘
│ │ ├── update.service.ts # 自动更新
│ │ ├── window-manager.service.ts # 窗口管理
│ │ └── workspace.service.ts # 工作空间管理
│ └── harness/ # Agent 核心引擎
│ ├── agent-loop/ # ReAct 状态机
│ │ ├── engine.ts # 循环引擎（8 状态）
│ │ └── types.ts # 状态枚举
│ ├── adapters/ # LLM Provider 适配器
│ │ ├── base-adapter.ts # 抽象基类
│ │ ├── deepseek.adapter.ts # DeepSeek（SSE）
│ │ ├── agnes-ai.adapter.ts # Agnes AI（SSE）
│ │ ├── mimo.adapter.ts # MiMo 小米（SSE）
│ │ ├── ollama.adapter.ts # Ollama（NDJSON）
│ │ └── shared/ # 共享模块
│ │ ├── openai-format.ts # OpenAI 兼容格式
│ │ └── sse-stream.ts # SSE 流解析
│ ├── tools/ # 工具系统
│ │ ├── registry.ts # 工具注册 + PolicyEngine
│ │ └── built-in/ # 27 个内置工具
│ │ ├── filesystem.ts # 文件系统（5 工具）
│ │ ├── file-editor.ts # 编辑器
│ │ ├── code-search.ts # 代码搜索
│ │ ├── diff-viewer.ts # 差异查看
│ │ ├── web-search.ts # 网络搜索
│ │ ├── web-fetch.ts # 网页抓取
│ │ ├── browser.ts # 浏览器工具
│ │ ├── browser-window-manager.ts # 浏览器窗口管理
│ │ ├── network.ts # 网络工具入口
│ │ ├── network-utils.ts # 网络工具函数
│ │ ├── http-request.ts # HTTP 请求
│ │ ├── memory.ts # 记忆工具
│ │ ├── command.ts # 命令执行
│ │ ├── git.ts # Git 工具（4 个）
│ │ ├── dev-tools.ts # 开发工具（3 个）
│ │ ├── task-manager.ts # 任务管理
│ │ ├── delegate-task.ts # 子任务委派
│ │ ├── todo.ts # TODO 工具
│ │ ├── think.ts # 思考工具
│ │ ├── view-image.ts # 图片查看
│ │ └── file-guard.ts # 文件保护
│ ├── types/ # Metona IR 类型定义
│ │ ├── metona-request.ts # 请求类型
│ │ ├── metona-response.ts # 响应类型
│ │ ├── metona-tool.ts # 工具类型
│ │ ├── metona-context.ts # 上下文类型
│ │ └── metona-adapter.ts # 适配器接口
│ ├── sandbox/ # 沙箱安全
│ │ ├── sandbox.ts # SandboxManager
│ │ └── permissions.ts # PolicyEngine
│ ├── security/ # 安全防御
│ │ └── prompt-injection-defense.ts
│ ├── memory/ # 记忆系统
│ │ ├── manager.ts # MemoryManager
│ │ └── consolidator.ts # MemoryConsolidator
│ ├── orchestration/ # 编排
│ │ └── orchestrator.ts # TaskOrchestrator
│ ├── prompts/ # 提示词构建
│ │ └── context-builder.ts # ContextBuilder
│ ├── hooks/ # 钩子
│ │ ├── pre-tool.ts # 工具前钩子
│ │ ├── post-tool.ts # 工具后钩子
│ │ └── confirmation-hook.ts # 确认钩子
│ ├── verification/ # 验证
│ │ └── output-validator.ts # OutputValidator
│ └── utils/ # 工具函数
│ └── token-estimator.ts # Token 估算
├── src/ # React 渲染进程
│ ├── main.tsx # React 入口
│ ├── App.tsx # 应用根组件
│ ├── components/ # UI 组件（25 个）
│ │ ├── chat/ # 聊天组件（11 个）
│ │ ├── layout/ # 布局组件（5 个）
│ │ ├── settings/ # 设置面板
│ │ ├── memory/ # 记忆查看器
│ │ ├── tasks/ # 任务列表
│ │ ├── trace/ # 追踪查看器（3 个）
│ │ ├── workspace/ # 工作空间查看器
│ │ ├── onboarding/ # 引导向导
│ │ └── common/ # 通用组件
│ ├── hooks/ # React Hooks
│ │ ├── useAgentStream.ts # Agent 流式事件
│ │ ├── useKeyboardShortcuts.ts # 键盘快捷键
│ │ └── useTheme.ts # 主题管理
│ ├── stores/ # Zustand 状态管理
│ │ ├── agent-store.ts # Agent 状态
│ │ ├── session-store.ts # 会话状态
│ │ └── ui-store.ts # UI 状态
│ ├── lib/ # 工具库
│ │ ├── constants.ts # 常量定义
│ │ ├── formatters.ts # 格式化函数
│ │ ├── theme.ts # MUI 主题
│ │ └── cn.ts # className 合并
│ ├── styles/
│ │ └── globals.css # 全局样式
│ └── types/
│ └── global.d.ts # window.metona 类型声明
├── docs/ # 设计文档
├── standard/ # 开发规范
├── apis/ # LLM API 文档
├── assets/ # 应用图标
├── .env.example # 环境变量示例
├── electron-builder.yml # 构建配置
├── electron.vite.config.ts # Vite 配置
├── package.json # 依赖与脚本
├── tsconfig.json # TypeScript 配置
├── tsconfig.node.json # Node 端配置
├── tsconfig.web.json # Web 端配置
└── LICENSE # MIT 许可证
开发命令
# 开发
npm run dev # 启动开发模式
npm run typecheck # 全量类型检查
npm run typecheck:node # Node 端类型检查
npm run lint # ESLint 检查
npm run lint:fix # ESLint 自动修复
npm run format # Prettier 格式化
# 测试
npm test # 运行单元测试 (Vitest)
npm run test:watch # 测试监听模式
npm run test:e2e # E2E 测试 (Playwright)
# 构建
npm run build # 构建生产包
npm run build:renderer # 仅构建渲染进程
npm run build:electron # 仅构建主进程
npm run preview # 预览构建产物
数据库 Schema（9 张表）
| 表名 | 用途 |
|---|---|
| sessions | 会话管理 |
| messages | 消息持久化 |
| app_config | 应用配置（键值对） |
| audit_logs | 审计日志（链式哈希防篡改） |
| mcp_servers | MCP Server 配置 |
| episodic_memories | 情节记忆 |
| semantic_memories | 语义记忆 |
| working_memories | 工作记忆 |
| tasks | 持久化任务 |