Files
metona-ai-desktop/README.md
T
thzxx dde21f0b3f feat: 升级至 v0.3.8 — Trace Viewer 叠加修复 + LLM 配置校验改造 + toast 反馈统一
- Trace Viewer 叠加渲染修复
  - sendMessage 补 traceSteps/tokenUsage 重置(止血)
  - TraceStep 加 runId 字段,useAgentStream 按 runId 判定同迭代(稳健改造)

- LLM 配置校验中等改造(SettingsModal LLMSettings)
  - 取消 onChange 实时落库,改为本地 state + Save 按钮统一提交
  - 字段级 inline error:Base URL http(s):// 正则、Model 空格校验、contextWindow ≥ 4096
  - Provider 切换清空 Model(之前只清 apiKey)
  - 保存结果改用 metona-toast(不再用 Alert)

- toast 反馈机制全面统一(15 处问题修复)
  - ContextMenu: 原生 confirm/prompt 改 MUI Dialog(新增 useDialogStore + ContextMenuDialogHost)
  - ContextMenu: 抽 copyWithToast helper 替代散落 7 处静默失败
  - OnboardingWizard: 配置保存失败静默改 toast.error
  - useKeyboardShortcuts: Ctrl+N / Ctrl+Shift+C 失败补 toast
  - SettingsModal: inheritFiles 失败 toast.warning、handleApply 失败 toast.error
  - LogsSettings: resultAlert Alert 改 toast(保留 Dialog 确认)
  - MemoryViewer: 删除失败改 toast(加载/搜索保留 Alert)
  - TaskList: create/update/delete/无会话改 toast
  - agent-store: sendMessage/session 失败补 toast(保留 system message)

- 删除当前会话同步清空 ChatPanel/DetailPanel
  - Sidebar confirmDelete + ContextMenu delete 均补 agent-store 重置
  - 修复 useSessionStore.removeSession 不触发 agent-store 同步的遗漏
2026-07-20 21:22:20 +08:00

24 KiB
Raw Blame History

MetonaAI Desktop

生产级通用 AI Agent 智能体桌面应用

Version License Electron React TypeScript

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

  1. 复制 .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
  1. 或在应用启动后,通过 设置 → LLM 配置 界面可视化配置 Provider、API Key、模型、上下文窗口等参数。

核心特性

智能体引擎

  • ReAct 状态机8 状态闭环(INIT → THINKING → PARSING → EXECUTING → OBSERVING → REFLECTING → COMPRESSING → TERMINATED
  • 流式对话SSEDeepSeek/Agnes+ NDJSONOllama)双协议流式响应
  • 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 + AGENTS.md + USERS.md + MEMORY.md + 安全准则

安全防线(四层纵深防御)

  1. 路径安全:工作空间边界校验 + realpathSync 符号链接逃逸检测 + 根目录 MEMORY.md 保护
  2. 命令安全SandboxManager 28 模式扫描 + shell-quote 双层防御 + 受保护文件检查
  3. 权限控制PolicyEngine 三级权限 + 频率限制(20 次/分钟)+ 用户确认钩子
  4. 内容安全PromptInjectionDefender30+ 正则 + 语义检测)+ 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 快速搜索
  • 多平台构建WindowsNSIS + 便携版)、macOSDMG + ZIP)、LinuxAppImage + 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 列出目录,depthmax 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 个 actionopen/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

Git4 个)

工具 风险 需确认 功能
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,支持父子关系
todo_write SAFE 会话级 TODOLRU 淘汰(max 50 sessions
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 / MiMocontextWindow 配置项影响本地压缩判断和 UI 显示(最小 4096)
  • Ollamanum_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 角色定义(灵魂)
AGENTS.md AI 行为规则
MEMORY.md 动态记忆存储 是(仅根目录受保护)
USERS.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 # DeepSeekSSE
│       │   ├── agnes-ai.adapter.ts  # Agnes AISSE
│       │   ├── mimo.adapter.ts     # MiMo 小米(SSE
│       │   ├── ollama.adapter.ts   # OllamaNDJSON
│       │   └── 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            # 预览构建产物

数据库 Schema9 张表)

表名 用途
sessions 会话管理
messages 消息持久化
app_config 应用配置(键值对)
audit_logs 审计日志(链式哈希防篡改)
mcp_servers MCP Server 配置
episodic_memories 情节记忆
semantic_memories 语义记忆
working_memories 工作记忆
tasks 持久化任务

许可证

MIT