MetonaAI Desktop
生产级通用 AI Agent 智能体桌面应用
Metona 是一款基于 Electron 的本地优先 AI Agent 桌面应用，内置 ReAct 状态机驱动的智能体循环引擎、30+ 内置工具、三层记忆系统、四层纵深安全防线与完整可观测性链路。支持四种 LLM Provider，兼容 MCP 协议扩展，为开发者提供开箱即用的 AI 编程伙伴。
📑 目录
- ✨ 核心亮点
- 🛠 技术栈
- 🚀 快速开始
- 🧠 智能体引擎
- 🔧 工具系统
- 🔌 LLM 适配器
- 🧩 记忆系统
- 🛡 安全机制
- 🏗 项目架构
- 📊 可观测性
- 🎨 桌面体验
- ⚙️ 配置说明
- 📁 项目结构
- 📝 开发命令
- 📄 许可证
✨ 核心亮点
🧠 生产级 Agent 引擎ReAct 八状态闭环、流式对话 (SSE/NDJSON)、Thinking 推理模式、死循环检测、上下文自动压缩、指数退避重试 |
🔧 30+ 内置工具文件系统 · 代码搜索 · 网络搜索 · 浏览器自动化 · Git · Shell 命令 · HTTP 请求 · 记忆存储 · 任务管理 |
🔌 多 Provider 支持DeepSeek V4 · Agnes AI 2.0 · Xiaomi MiMo 2.5 · Ollama 本地模型 — 一键切换，热重载适配器 |
🧩 三层记忆架构情节记忆 (Episodic) + 语义记忆 (Semantic) + 工作记忆 (Working)，TF-IDF 语义检索 + 时间衰减 |
🛡 四层纵深防御路径边界校验 + Shell 沙箱 + 三级权限策略 + Prompt 注入检测 + 幻觉校验 — 层层设防 |
📡 MCP 协议兼容支持 stdio / SSE 两种传输方式的 MCP Server，动态发现工具，无需重启应用 |
📊 全链路可观测ReAct 迭代追踪 · JSONL 会话录制 · 链式哈希审计 · Token 用量统计 · SLO 健康监控 |
🎨 精致桌面体验三栏 IDE 布局 · 系统托盘 · 全局快捷键 · 暗色/亮色主题 · 5 步引导向导 · 命令面板 |
🛠 技术栈
| 层级 | 技术 | 版本 | 用途 |
|---|---|---|---|
| 🖥 运行时 | Electron | 35 | 跨平台桌面框架 |
| ⚛️ 前端 | React | 19 | UI 渲染引擎 |
| 🎨 组件库 | Material UI (MUI) | 9 | 统一 UI 组件体系 |
| 📘 类型 | TypeScript | 5.8 | 全量类型安全 |
| 🗄 数据库 | better-sqlite3 | 11 | 本地 SQLite 持久化 (WAL 模式) |
| 📦 状态管理 | Zustand | 5 | 轻量级响应式状态 |
| 🔧 构建 | electron-vite + Vite | 3 / 6 | 双端构建 (Main + Renderer) |
| 🛰 MCP | @modelcontextprotocol/sdk | 1.12 | 外部工具协议集成 |
| 🎨 样式 | Tailwind CSS | 4 | 辅助原子化样式 |
| 📝 Markdown | react-markdown + remark-gfm | 10 / 4 | 富文本渲染 |
| 🔢 UUID | nanoid | 5 | 唯一 ID 生成 |
| ✅ 校验 | Zod | 3 | 运行时类型校验 |
| 💾 缓存 | lru-cache | 11 | 内存缓存 |
| 📋 日志 | electron-log | 5 | 分级结构化日志 |
| ⚙️ 配置 | electron-store | 10 | 键值对持久化配置 |
🚀 快速开始
环境要求
- Node.js ≥ 18
- npm ≥ 9
- Windows / macOS / Linux
安装与运行
# 1. 克隆仓库
git clone https://github.com/your-org/metona-ai-desktop.git
cd metona-ai-desktop
# 2. 安装依赖
npm install
# 3. 配置 API Key
cp .env.example .env
# 编辑 .env，填入你的 LLM API Key
# 4. 启动开发模式
npm run dev
# 5. 构建生产包
npm run build
配置 LLM Provider
在 .env 中填入密钥，或在应用内通过 设置 → LLM 配置 可视化配置：
# DeepSeek API (https://platform.deepseek.com)
DEEPSEEK_API_KEY=sk-your-key-here
DEEPSEEK_BASE_URL=https://api.deepseek.com
# Agnes AI API (https://apihub.agnes-ai.com)
AGNES_API_KEY=your-key-here
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
# Xiaomi MiMo API (https://api.xiaomimimo.com)
MIMO_API_KEY=your-key-here
MIMO_BASE_URL=https://api.xiaomimimo.com/v1
# Ollama (本地运行, 无需 API Key)
OLLAMA_BASE_URL=http://localhost:11434
🧠 智能体引擎
ReAct 八状态闭环
Metona 的核心是一个 ReAct (Reasoning + Acting) 状态机驱动引擎，通过 8 个状态完成完整的推理-执行-观测-反思循环：
┌──────────────────────────────────────────────────────────┐
│ 用户消息输入 │
└────────────────────────┬─────────────────────────────────┘
▼
┌───────────────────────────────┐
│ INIT（初始化） │
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ THINKING（思考推理） │ ←──────────┐
└───────────────┬───────────────┘ │
▼ │
┌───────────────────────────────┐ │
│ PARSING（解析输出） │ │
└───────────────┬───────────────┘ │
▼ │
┌───────────────────────────────┐ │
│ EXECUTING（执行工具调用） │ │
└───────────────┬───────────────┘ │
▼ │
┌───────────────────────────────┐ │
│ OBSERVING（观测工具结果） │ │
└───────────────┬───────────────┘ │
▼ │
┌───────────────────────────────┐ │
│ REFLECTING（反思与决策） │──────────────┘
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ COMPRESSING（上下文压缩 - 可选） │
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ TERMINATED（任务完成） │
└───────────────────────────────┘
引擎关键特性
| 特性 | 说明 |
|---|---|
| 🔄 流式对话 | SSE (DeepSeek/Agnes/MiMo) + NDJSON (Ollama) 双协议流式响应 |
| 💭 Thinking 模式 | 支持 deepseek-v4-pro / agnes-2.0-flash / qwen3 等推理模型的思维链展示 |
| 🔁 死循环检测 | 连续 3 轮相同工具调用签名自动终止 |
| 📦 上下文压缩 | 80% 阈值触发 LLM 摘要压缩，保留最近 10 条消息 |
| 🔄 错误重试 | 指数退避 (1s/2s/4s) + ±20% jitter，上限 30s |
| ⏱️ 可配置迭代 | 最大迭代次数 (默认 20)、总超时 (默认 600s)、工具执行超时 (默认 120s) |
| 🧵 子任务委派 | TaskOrchestrator 支持最大 3 层深度的 SubAgent 编排 |
🔧 工具系统
工具分类总览
Metona 内置 30+ 工具，按安全风险分为五个等级：
SAFE (无需确认) LOW (无需确认) MEDIUM (可配自动) HIGH (强制确认) CRITICAL (双人复核)
│ │ │ │ │
├─ read_file ├─ web_search ├─ write_file ├─ delete_file ├─ (预留)
├─ list_directory ├─ web_fetch ├─ file_editor ├─ run_command
├─ search_files ├─ http_request ├─ memory_store ├─ web_browser
├─ code_search ├─ run_tests ├─ delegate_task ├─ git_commit
├─ diff_viewer ├─ task_manager ├─ file_move └─ browser actions
├─ git_status └─ think (open/navigate)
├─ git_diff
├─ git_log
├─ lint_code
├─ project_info
├─ memory_search
├─ view_image
└─ file_info
详细工具列表
📂 文件系统 (7 tools)
| 工具 | 风险 | 需确认 | 功能描述 |
|---|---|---|---|
read_file |
SAFE | 否 | 读取文本文件，二进制检测，offset/limit 分页 |
write_file |
MEDIUM | 是 | 原子写入 (tmp+rename)，支持 overwrite/append 模式 |
list_directory |
SAFE | 否 | 列出目录，depth (max 5)、glob 模式、include_hidden |
search_files |
SAFE | 否 | 按名称/内容模式搜索，支持 context_lines |
delete_file |
HIGH | 是 | 删除文件，禁止删除工作空间根目录和 MEMORY.md |
file_move |
MEDIUM | 是 | 移动/重命名文件，跨工作空间拒绝 |
file_info |
SAFE | 否 | 获取文件元信息 (大小、修改时间、MIME 类型) |
✏️ 编辑与搜索 (3 tools)
| 工具 | 风险 | 需确认 | 功能描述 |
|---|---|---|---|
file_editor |
MEDIUM | 是 | 精准编辑：replace / insert / delete / regex / find_replace，支持 dry_run |
code_search |
SAFE | 否 | 基于 ripgrep 高速代码搜索，自动回退 JS fallback |
diff_viewer |
SAFE | 否 | LCS 算法生成 unified diff 格式差异 |
🌐 网络与浏览器 (4 tools)
| 工具 | 风险 | 需确认 | 功能描述 |
|---|---|---|---|
web_search |
LOW | 否 | 双模式搜索 (SearXNG 元搜索 / 四引擎内置降级) |
web_fetch |
LOW | 否 | 三阶段回退获取 (HTTP → SPA 升级 → 浏览器渲染)，10MB 限制 |
web_browser |
HIGH | 是 | 统一浏览器工具：open / screenshot / evaluate / extract / click / type / scroll / wait / close |
http_request |
LOW | 否 | HTTP 请求，6 种 method，SSRF 防护 (DNS IP 校验) |
🧠 记忆 (2 tools)
| 工具 | 风险 | 需确认 | 功能描述 |
|---|---|---|---|
memory_store |
MEDIUM | 否 | 存储记忆到三层 (Episodic / Semantic / Working) |
memory_search |
SAFE | 否 | TF-IDF 语义检索记忆，时间衰减加权 |
💻 命令与开发 (5 tools)
| 工具 | 风险 | 需确认 | 功能描述 |
|---|---|---|---|
run_command |
HIGH | 是 | Shell 命令执行，shell-quote 解析 + SandboxManager 28+ 模式扫描 |
lint_code |
SAFE | 否 | TypeScript tsc 或 ESLint 检查 |
run_tests |
LOW | 否 | 运行测试套件 (jest/vitest/mocha)，filter 白名单防注入 |
project_info |
SAFE | 否 | 项目结构分析，4 种 detail 级别 |
delegate_task |
MEDIUM | 否 | 子任务委派给独立 SubAgent，最大深度 3 层 |
🔀 Git (4 tools)
| 工具 | 风险 | 需确认 | 功能描述 |
|---|---|---|---|
git_status |
SAFE | 否 | 工作树状态，porcelain v1 格式解析 |
git_diff |
SAFE | 否 | 差异输出，50KB 截断，5MB maxBuffer |
git_log |
SAFE | 否 | 提交历史，支持 --oneline / --stat 等格式 |
git_commit |
MEDIUM | 是 | 暂存 + 提交，校验文件在工作空间内 |
📋 任务与辅助 (4 tools)
| 工具 | 风险 | 需确认 | 功能描述 |
|---|---|---|---|
task_manager |
LOW | 否 | 持久化任务 CRUD，支持父子关系，写入后通知 UI 实时刷新 |
think |
SAFE | 否 | 结构化思考空间，零副作用，纯推理 |
view_image |
SAFE | 否 | 读取图片返回 base64，5MB 限制，支持 7 种格式 |
mcp:* |
可变 | 可变 | MCP 协议扩展工具，运行时动态发现加载 |
🔌 LLM 适配器
Metona 通过统一的 IMetonaProviderAdapter 接口抽象了所有 LLM Provider，支持热重载切换：
| 适配器 | Provider | 模型 | 上下文 | 流式格式 | Thinking | 多模态 |
|---|---|---|---|---|---|---|
| DeepSeekAdapter | deepseek |
deepseek-v4-pro / deepseek-v4-flash | 1M tokens | SSE | thinking.type + reasoning_effort |
否 |
| AgnesAdapter | agnes |
agnes-2.0-flash | 1M tokens | SSE | chat_template_kwargs / Anthropic 兼容 |
是 (URL + Base64) |
| MimoAdapter | mimo |
mimo-v2.5-pro / mimo-v2.5 | 1M tokens | SSE | thinking.type: enabled |
是 (URL + Base64) |
| OllamaAdapter | ollama |
qwen3 / gemma3 / deepseek-r1 等 | 可配 (num_ctx) | NDJSON | think 参数 |
是 (Base64) |
适配器核心能力
- 统一 IR 格式：所有 Provider 均转换为
MetonaRequest/MetonaResponse/MetonaStreamEvent内部指令，上层代码零感知差异 - 热重载切换：切换 Provider 时自动清空 API Key，配置签名比对，无需重启
- 流式解析：共享 SSE 流解析器 (
sse-stream.ts) + OpenAI 兼容格式构建器 (openai-format.ts) - API 健康检查：
healthCheck()方法在各适配器中独立实现，支持状态监控
🧩 记忆系统
三层记忆架构
┌──────────────────────────────────────────────────────┐
│ L1: 工作记忆 (Working Memory) │
│ 当前任务临时状态，精确键值查找，会话级别生命周期 │
├──────────────────────────────────────────────────────┤
│ L2: 情节记忆 (Episodic Memory) │
│ 会话事件流、工具调用历史、用户交互记录 │
│ 检索方式: TF-IDF 语义检索 + 时间衰减 (30 天半衰期) │
├──────────────────────────────────────────────────────┤
│ L3: 语义记忆 (Semantic Memory) │
│ 知识事实、用户偏好、项目经验累积 │
│ 检索方式: 精确匹配 + 模糊匹配 + 重要性评分 │
└──────────────────────────────────────────────────────┘
记忆生命周期
新记忆写入 → 重要性评分 (0~1)
├── 高 (>0.8) → 永久保存，核心知识
├── 中 (0.4~0.8) → 定期回顾，逐渐衰减
└── 低 (<0.4) → 短期保留，自然遗忘
会话结束 → MemoryConsolidator (LLM 驱动提取)
→ 写入 MEMORY.md (5 个允许的 section)
→ 同步写入 semantic_memories 表 (双轨同步)
磁盘文件 (工作空间内)
| 文件 | 用途 | 是否必需 | 保护机制 |
|---|---|---|---|
SOUL.md |
AI 角色定义 (灵魂)，定义 Agent 的行为准则与个性 | 是 (自动创建) | 不可通过工具删除 |
MEMORY.md |
动态记忆存储，LLM 会话结束后自动追加 | 是 (仅根目录受保护) | 仅根目录版本受保护 |
🛡 安全机制
四层纵深防御
┌─────────────────────────────────────────────────────────────────┐
│ 第 1 层：路径安全 │
│ isPathWithinWorkspace() + realpathSync (符号链接逃逸检测) │
│ + 根目录 MEMORY.md 保护 + 工作空间边界校验 │
├─────────────────────────────────────────────────────────────────┤
│ 第 2 层：命令安全 │
│ SandboxManager (28+ 正则模式扫描: child_process/eval/路径遍历/ │
│ 反弹Shell/fork炸弹/编码执行/动态导入) │
│ + shell-quote 双层防御 + 受保护文件白名单检查 │
├─────────────────────────────────────────────────────────────────┤
│ 第 3 层：权限控制 │
│ PolicyEngine (35+ 默认策略) │
│ READ / WRITE / EXTERNAL_ACTION 三级权限 │
│ 滑动窗口频率限制 (20 次/分钟) │
│ ConfirmationHook: HIGH/CRITICAL 工具需用户确认 │
│ 会话内同类免确认 + 持久化自动执行 (Auto-Execute) │
├─────────────────────────────────────────────────────────────────┤
│ 第 4 层：内容安全 │
│ PromptInjectionDefender: │
│ 40+ 正则模式 (指令覆写/分隔符注入/Base64编码/角色扮演攻击) │
│ + 语义检测 (命令式动词密度/角色边界异常/嵌套分隔符) │
│ + Unicode 归一化 (NFKC + 零宽字符移除 + 混合脚本检测) │
│ OutputValidator: │
│ 格式校验 + PII/API Key 泄漏检测 + 事实一致性校验 + 幻觉检测 │
└─────────────────────────────────────────────────────────────────┘
风险分级
| 风险等级 | 示例工具 | 确认要求 | 自动执行 |
|---|---|---|---|
| 🟢 SAFE | read_file, list_directory, code_search, git_status | 无需确认 | 默认允许 |
| 🔵 LOW | web_search, web_fetch, http_request, task_manager | 无需确认 | 默认允许 |
| 🟡 MEDIUM | write_file, file_editor, memory_store, delegate_task | 可配置自动 | 用户可选 |
| 🟠 HIGH | delete_file, run_command, web_browser, git_commit | 强制确认 | 不支持 |
| 🔴 CRITICAL | (预留) | 双人复核 | 不支持 |
🏗 项目架构
四层 Harness 架构
Metona 的 Agent 引擎采用分层架构，每层职责清晰：
┌──────────────────────────────────────────────────────────────────┐
│ L1 推理与编排层 (Reasoning & Orchestration) │
│ ┌─────────────────────┐ ┌──────────────────────────────────┐ │
│ │ AgentLoopEngine │ │ TaskOrchestrator │ │
│ │ ReAct 八状态机 │ │ 子任务分解 · 并行执行 · 结果聚合 │ │
│ │ 流式解析 · 死循环检测 │ │ SubAgent 最大深度 3 层 │ │
│ └─────────────────────┘ └──────────────────────────────────┘ │
│ 类型: MetonaRequest / MetonaResponse / MetonaStreamEvent │
├──────────────────────────────────────────────────────────────────┤
│ L2 上下文与记忆层 (Context & Memory) │
│ ┌─────────────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ ContextBuilder │ │ MemoryManager│ │ Consolidator │ │
│ │ System Prompt 组装 │ │ TF-IDF 检索 │ │ LLM 记忆提取 │ │
│ │ SOUL + MEMORY + 安全 │ │ 三层记忆 CRUD │ │ MEMORY.md 写入 │ │
│ └─────────────────────┘ └──────────────┘ └───────────────┘ │
│ 类型: MetonaContext / MetonaMemoryItem │
├──────────────────────────────────────────────────────────────────┤
│ L3 工具与安全执行层 (Tools & Security) │
│ ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │
│ │ ToolRegistry│ │ Sandbox │ │PolicyEng │ │ InjectionDefender│ │
│ │ 30+ 工具注册│ │ 28+ 扫描 │ │ 35+ 策略 │ │ 40+ 正则 + 语义 │ │
│ │ MCP 适配 │ │ 路径校验 │ │ 频率限制 │ │ 输出校验 │ │
│ └────────────┘ └──────────┘ └──────────┘ └─────────────────┘ │
│ 类型: MetonaToolDef / MetonaToolCall / MetonaToolResult │
├──────────────────────────────────────────────────────────────────┤
│ L4 支撑与基础架构层 (Infrastructure) │
│ ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │
│ │ Config │ │ Database │ │ Audit │ │ Session Services │ │
│ │ 全局+工作空间│ │ SQLite │ │ 链式哈希 │ │ 会话 · 录制 · MCP │ │
│ │ 分层配置 │ │ WAL 9 表 │ │ INSERT │ │ 托盘 · 更新 · 窗口│ │
│ └────────────┘ └──────────┘ └──────────┘ └─────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
进程模型
| 进程 | 运行时 | 职责 |
|---|---|---|
| Main Process | Node.js | Agent 引擎、工具调度、SQLite 数据库、MCP 管理、配置服务 |
| Preload Script | 沙箱 | contextBridge 安全暴露 window.metona (15 个 API 命名空间) |
| Renderer | Chromium | React 19 + MUI 9 界面渲染，Zustand 状态管理 |
核心数据流
用户输入 → ChatInput → agent-store.sendMessage
→ IPC: agent:sendMessage → handlers.ts
→ reloadAdapter (配置签名比对，热重载)
→ 保存用户消息到 SQLite messages 表
→ 加载历史消息 + 注入相关记忆 (MemoryManager.search)
→ ContextBuilder.buildSystemPrompt (SOUL.md + MEMORY.md + 安全准则)
→ PromptInjectionDefender.detect (riskScore ≥ 7 阻断)
→ AgentLoopEngine.runStream
→ Adapter.sendStream (SSE / NDJSON 流式调用)
→ 流式事件 → webContents.send('agent:streamEvent')
→ 工具调用 → PreToolHooks (权限验证 + 频率限制 + 用户确认)
→ ToolRegistry.execute → PostToolHooks (审计记录 + 记忆触发)
→ 80% 阈值触发 Compressing (LLM 摘要压缩)
→ 死循环检测 (3 轮相同签名)
→ OutputValidator.validate (幻觉检测 + PII 检查)
→ 保存 assistant 消息 + tool 结果消息到 SQLite
→ MemoryConsolidator.consolidate (异步 LLM 提取记忆 → MEMORY.md)
→ AuditService.logSessionEnd (链式哈希审计)
← useAgentStream Hook 监听事件 → Zustand Store → React 重渲染
📊 可观测性
全链路追踪
- TraceViewer：按
runId分组可视化展示每轮 ReAct 迭代，包括思考过程、工具调用参数/结果/耗时、状态转换链 - Token 用量面板：输入/输出 Token、当前上下文占用百分比 (按 60%/80% 阈值变色)、压缩节省的 Token
会话录制
- 9 种事件类型：session_start, user_message, assistant_message, tool_call, tool_result, state_change, context_compressed, error, session_end
- 录制到 JSONL 文件，支持回放重放
- 录制格式：每行一条结构化 JSON 事件
审计日志
- 链式哈希防篡改：每条记录哈希 = SHA-256(prev_hash + 记录内容)，INSERT-ONLY 触发器
- 完整性校验：
verifyChain()逐条验证哈希链 - 导出：支持只读 JSONL (chmod 0o444)、CSV、归档 (90 天保留)
SLO 监控
| 指标 | 目标 |
|---|---|
| Agent Loop 成功率 | 95% |
| P99 延迟 | < 60s (95%) |
| 工具调用成功率 | 98% |
| 死循环发生率 | < 0.1% (99.9%) |
| MCP Server 可用性 | 99% |
| 应用崩溃率 | < 0.1% (99.9%) |
🎨 桌面体验
三栏 IDE 布局
┌──────────┬──────────────────────────────┬──────────────┐
│ │ Header 顶部栏 │ │
│ Sidebar │ Provider · Model · 面板切换 │ DetailPanel │
│ 260px ├──────────────────────────────┤ 360px │
│ │ │ │
│ 会话列表 │ ChatPanel 聊天区域 │ Trace View │
│ 搜索 │ │ Memory │
│ 工具管理 │ MessageList + ChatInput │ Tasks │
│ │ │ Workspace │
│ │ │ │
├──────────┴──────────────────────────────┴──────────────┤
│ StatusBar · 状态 · Token · 版本 │
└────────────────────────────────────────────────────────┘
交互特性
| 特性 | 描述 |
|---|---|
| 🔔 系统托盘 | 4 状态指示 (idle / thinking / executing / error)，最小化到托盘 |
| ⌨️ 全局快捷键 | Cmd/Ctrl+Shift+M 唤起应用 |
| 🎹 应用内快捷键 (16 个) | 会话管理 / 布局切换 / 主题切换 / 命令面板 / 详情面板 |
| 🌓 暗色/亮色主题 | 跟随系统自动切换 + 手动切换 (Ctrl+D 循环) |
| 🧭 5 步引导向导 | 欢迎 → 配置 LLM → 自定义 Agent → 工作空间 → 开始使用 |
| 🔍 命令面板 | Cmd/Ctrl+K 快速搜索会话与命令 |
| 🖼️ 附件支持 | 拖拽/粘贴图片与文件，自动压缩与注入上下文 |
| 📝 消息编辑 | 双击用户消息原地编辑 (Ctrl+Enter 重发) |
多平台构建
| 平台 | 构建格式 |
|---|---|
| 🪟 Windows | NSIS 安装包 (x64) + 便携版 (Portable, x64) |
| 🍎 macOS | DMG (x64 + arm64) + ZIP (Universal) |
| 🐧 Linux | AppImage (x64) + DEB (x64) |
⚙️ 配置说明
环境变量 (.env)
# ===========================================
# LLM API 密钥
# ===========================================
# DeepSeek (https://platform.deepseek.com)
DEEPSEEK_API_KEY=sk-your-key
DEEPSEEK_BASE_URL=https://api.deepseek.com
# Agnes AI (https://apihub.agnes-ai.com)
AGNES_API_KEY=your-key
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
# Xiaomi MiMo (https://api.xiaomimimo.com)
MIMO_API_KEY=your-key
MIMO_BASE_URL=https://api.xiaomimimo.com/v1
# Ollama (本地运行)
OLLAMA_BASE_URL=http://localhost:11434
# 应用标题
VITE_APP_TITLE=MetonaAI Desktop
应用配置 (app_config 表)
| 配置项 | 默认值 | 说明 |
|---|---|---|
llm.provider |
deepseek |
LLM Provider ID |
llm.model |
deepseek-v4-pro |
模型标识符 |
agent.maxIterations |
20 |
ReAct 最大迭代轮次 |
agent.totalTimeoutMs |
600000 |
Agent 总超时 (ms) |
agent.toolTimeoutMs |
120000 |
单个工具执行超时 (ms) |
agent.thinkingEnabled |
true |
启用 Thinking 推理模式 |
agent.thinkingEffort |
high |
推理强度 (high / max) |
agent.confirmationTimeoutMs |
120000 |
确认弹窗超时 (30s ~ 600s) |
deepseek.contextWindow |
1000000 |
DeepSeek 上下文窗口 |
agnes.contextWindow |
1000000 |
Agnes 上下文窗口 |
mimo.contextWindow |
1000000 |
MiMo 上下文窗口 |
ollama.numCtx |
4096 |
Ollama num_ctx 参数 |
SearXNG 元搜索引擎 (可选)
启用 SearXNG 替代内置四引擎搜索，支持 12 项细粒度配置：
- 基础配置：enabled / base_url / timeout / max_results
- 搜索范围：categories (general/news/scihub 等)、engines filter
- 安全与隐私：safe_search、language、认证方式 (Basic Auth / Token)
- 连接测试：内置测试功能，点击即可验证
📁 项目结构
MetonaAI-Desktop/
├── 📂 electron/ # Electron 主进程 (~60+ 文件)
│ ├── 📄 main.ts # 应用入口
│ ├── 📄 preload.ts # contextBridge 安全桥接 (15 个 API)
│ ├── 📂 ipc/
│ │ └── 📄 handlers.ts # IPC 通道处理 (50+ 通道)
│ ├── 📂 services/ # 业务服务层 (9 个 Service)
│ │ ├── 📄 audit.service.ts # 审计日志 (链式哈希防篡改)
│ │ ├── 📄 config.service.ts # 配置管理 (全局+工作空间分层)
│ │ ├── 📄 database.service.ts # SQLite 数据库 (WAL 模式, 9 张表)
│ │ ├── 📄 global-config.service.ts # 机器级全局配置 (JSON 文件)
│ │ ├── 📄 mcp-manager.service.ts # MCP Server 生命周期管理
│ │ ├── 📄 session-recorder.service.ts# 会话 JSONL 录制
│ │ ├── 📄 session.service.ts # 会话 CRUD
│ │ ├── 📄 tray-manager.service.ts # 系统托盘 (4 状态)
│ │ ├── 📄 update.service.ts # 自动更新
│ │ ├── 📄 window-manager.service.ts # 窗口管理 + 全局快捷键
│ │ └── 📄 workspace.service.ts # 工作空间 (SOUL.md + MEMORY.md)
│ ├── 📂 harness/ # Agent 智能体核心引擎
│ │ ├── 📂 agent-loop/ # ReAct 状态机
│ │ │ ├── 📄 engine.ts # 循环引擎 (8 状态, 1293 行)
│ │ │ └── 📄 types.ts # 状态枚举 · 终止原因 · 配置类型
│ │ ├── 📂 adapters/ # LLM Provider 适配器
│ │ │ ├── 📄 base-adapter.ts # 抽象基类 (fetchWithTimeout)
│ │ │ ├── 📄 deepseek.adapter.ts # DeepSeek v4 (SSE, 1M ctx)
│ │ │ ├── 📄 agnes-ai.adapter.ts # Agnes AI 2.0 (SSE, 多模态)
│ │ │ ├── 📄 mimo.adapter.ts # MiMo 2.5 (SSE, 1M ctx)
│ │ │ ├── 📄 ollama.adapter.ts # Ollama (NDJSON, 600 行)
│ │ │ └── 📂 shared/ # 共享: OpenAI 格式 · SSE 解析
│ │ ├── 📂 tools/ # 工具系统
│ │ │ ├── 📄 registry.ts # 工具注册 · PolicyEngine · 超时管理
│ │ │ └── 📂 built-in/ # 30+ 内置工具实现
│ │ │ ├── 📄 filesystem.ts # 文件系统 (7 tools)
│ │ │ ├── 📄 file-editor.ts # 精准编辑
│ │ │ ├── 📄 file-guard.ts # 路径安全共享工具
│ │ │ ├── 📄 code-search.ts # 代码搜索 (ripgrep + JS fallback)
│ │ │ ├── 📄 diff-viewer.ts # 差异查看 (LCS 算法)
│ │ │ ├── 📄 web-search.ts # 网络搜索 (SearXNG + 四引擎)
│ │ │ ├── 📄 web-fetch.ts # 网页抓取 (3 阶段回退)
│ │ │ ├── 📄 browser.ts # 浏览器自动化 (9 actions)
│ │ │ ├── 📄 http-request.ts # HTTP 请求 (SSRF 防护)
│ │ │ ├── 📄 memory.ts # 记忆存储/搜索
│ │ │ ├── 📄 command.ts # Shell 命令执行
│ │ │ ├── 📄 git.ts # Git 工具集 (4 tools)
│ │ │ ├── 📄 dev-tools.ts # 开发工具 (3 tools)
│ │ │ ├── 📄 task-manager.ts # 任务管理
│ │ │ ├── 📄 delegate-task.ts # 子任务委派
│ │ │ ├── 📄 think.ts # 思考工具
│ │ │ ├── 📄 view-image.ts # 图片查看
│ │ │ └── 📄 network-utils.ts # 网络共享工具
│ │ ├── 📂 types/ # Metona IR 类型定义
│ │ │ ├── 📄 metona-request.ts # 请求类型
│ │ │ ├── 📄 metona-response.ts # 响应/流事件类型 (19 错误码)
│ │ │ ├── 📄 metona-tool.ts # 工具定义/执行上下文类型
│ │ │ ├── 📄 metona-context.ts # 上下文/记忆类型
│ │ │ └── 📄 metona-adapter.ts # 适配器接口
│ │ ├── 📂 sandbox/ # 沙箱安全
│ │ │ ├── 📄 sandbox.ts # SandboxManager (28+ 模式)
│ │ │ └── 📄 permissions.ts # PolicyEngine (35+ 策略)
│ │ ├── 📂 security/ # 安全防御
│ │ │ └── 📄 prompt-injection-defense.ts # 三层注入检测 (40+ 正则)
│ │ ├── 📂 memory/ # 记忆系统
│ │ │ ├── 📄 manager.ts # MemoryManager (TF-IDF, CJK 分词)
│ │ │ └── 📄 consolidator.ts # MemoryConsolidator (LLM 提取)
│ │ ├── 📂 orchestration/ # 编排
│ │ │ └── 📄 orchestrator.ts # TaskOrchestrator (深度限制 3)
│ │ ├── 📂 prompts/ # 提示词构建
│ │ │ └── 📄 context-builder.ts # ContextBuilder (SOUL + MEMORY)
│ │ ├── 📂 hooks/ # 钩子
│ │ │ ├── 📄 pre-tool.ts # 前钩 (权限 + 频率)
│ │ │ ├── 📄 post-tool.ts # 后钩 (审计 + 记忆)
│ │ │ └── 📄 confirmation-hook.ts # 确认钩 (IPC 弹窗)
│ │ ├── 📂 verification/ # 验证
│ │ │ └── 📄 output-validator.ts # OutputValidator (幻觉检测)
│ │ └── 📂 utils/ # 工具函数
│ │ └── 📄 token-estimator.ts # Token 估算 (CJK/ASCII)
│ └── 📂 utils/
│ └── 📄 slo.ts # 健康检查 · SLO 监控
├── 📂 src/ # React 渲染进程 (~42 文件)
│ ├── 📄 main.tsx # 渲染进程入口
│ ├── 📄 App.tsx # 根组件 (三栏布局 + Store 连接)
│ ├── 📂 components/
│ │ ├── 📂 chat/ # 聊天组件 (11 个)
│ │ │ ├── 📄 ChatPanel.tsx # 聊天主面板
│ │ │ ├── 📄 MessageList.tsx # 消息列表 (content-visibility 虚拟滚动)
│ │ │ ├── 📄 MessageItem.tsx # 消息路由 (memo)
│ │ │ ├── 📄 AssistantMessage.tsx # Agent 回复 (Markdown + 代码高亮)
│ │ │ ├── 📄 UserMessage.tsx # 用户消息 (附件 + 双击编辑)
│ │ │ ├── 📄 SystemMessage.tsx # 系统通知
│ │ │ ├── 📄 ChatInput.tsx # 输入框 (附件 + / 命令)
│ │ │ ├── 📄 ThoughtBlock.tsx # 思考过程 (可折叠)
│ │ │ ├── 📄 ToolCallCard.tsx # 工具调用卡片 (5 状态)
│ │ │ ├── 📄 ToolResultBlock.tsx # 工具结果块
│ │ │ └── 📄 StreamingIndicator.tsx # 流式加载指示器
│ │ ├── 📂 layout/ # 布局组件 (5 个)
│ │ │ ├── 📄 Header.tsx # 顶部栏 (Provider · 面板切换)
│ │ │ ├── 📄 Sidebar.tsx # 侧边栏 (会话列表 · 工具管理)
│ │ │ ├── 📄 DetailPanel.tsx # 详情面板 (4 Tab)
│ │ │ ├── 📄 AgentMonitor.tsx # Agent 状态指示器
│ │ │ └── 📄 StatusBar.tsx # 底部状态栏
│ │ ├── 📂 settings/
│ │ │ └── 📄 SettingsModal.tsx # 设置弹窗 (8 标签页)
│ │ ├── 📂 memory/
│ │ │ └── 📄 MemoryViewer.tsx # 记忆浏览器 (3 类型)
│ │ ├── 📂 tasks/
│ │ │ └── 📄 TaskList.tsx # 任务列表
│ │ ├── 📂 trace/ # 追踪组件 (3 个)
│ │ │ ├── 📄 TraceViewer.tsx # ReAct 迭代时间轴
│ │ │ ├── 📄 TraceStep.tsx # 单步详情 (Thought + ToolCalls)
│ │ │ └── 📄 TokenUsage.tsx # Token 统计面板
│ │ ├── 📂 workspace/
│ │ │ └── 📄 WorkspaceViewer.tsx # 工作空间浏览器
│ │ ├── 📂 onboarding/
│ │ │ └── 📄 OnboardingWizard.tsx # 5 步引导向导
│ │ ├── 📂 common/
│ │ │ └── 📄 ErrorBoundary.tsx # 错误边界
│ │ ├── 📄 CommandPalette.tsx # Cmd+K 命令面板
│ │ ├── 📄 ConfirmationDialog.tsx # 工具确认弹窗 (批量审批)
│ │ ├── 📄 ContextMenu.tsx # 右键菜单
│ │ └── 📄 ToastContainer.tsx # Toast 通知 (metona-toast v2)
│ ├── 📂 hooks/
│ │ ├── 📄 useAgentStream.ts # 流式事件监听 (rAF 批处理)
│ │ ├── 📄 useKeyboardShortcuts.ts # 键盘快捷键 (16 个)
│ │ └── 📄 useTheme.ts # 主题管理
│ ├── 📂 stores/
│ │ ├── 📄 agent-store.ts # Agent 状态 (消息·流·Trace·Token)
│ │ ├── 📄 session-store.ts # 会话列表 (搜索·置顶·归档)
│ │ └── 📄 ui-store.ts # UI 状态 (主题·面板·专注模式)
│ ├── 📂 lib/
│ │ ├── 📄 constants.ts # 常量 (布局·颜色·快捷键)
│ │ ├── 📄 formatters.ts # 格式化 (时间·Token·文件大小)
│ │ ├── 📄 theme.ts # MUI 暗色/亮色主题
│ │ └── 📄 cn.ts # className 合并
│ ├── 📂 styles/
│ │ └── 📄 globals.css # 全局样式 (Tailwind + 动画 + Markdown)
│ └── 📂 types/
│ └── 📄 global.d.ts # window.metona API 类型声明
├── 📂 docs/ # 设计文档 (~10K 行)
│ ├── 📄 Agentic-Loop详解.md # Agent Loop 理论 (637 行)
│ ├── 📄 Agent网络工具通用设计-v2.md # 网络工具链设计 (953 行)
│ ├── 📄 MetonaAI-Desktop UI UX 设计集成方案.html # UI/UX 设计 (741 行)
│ ├── 📄 MetonaAI-Desktop 内部API请求与响应标准.html # Metona IR 标准 (1262 行)
│ ├── 📄 MetonaAI-Desktop 架构与交互设计.html # 系统架构 (999 行)
│ └── 📄 生产级通用AI Agent智能体桌面应用：完整设计与构建指南.html # 完整指南 (6616 行)
├── 📂 standard/ # 开发规范
│ └── 📄 开发规范.md # 第一铁律 + 常用库清单
├── 📂 apis/ # LLM API 文档
│ ├── 📄 deepseek-api-docs-20260518.html # DeepSeek API (Chat + FIM + Balance)
│ ├── 📄 agnes-ai-api-docs-20260625.html # Agnes AI API (1M ctx, 多模态)
│ ├── 📄 mimo-api-docs-20260715.html # MiMo API (Chat + TTS + Web Search)
│ └── 📄 ollama-api-docs-20260518.html # Ollama API (12 endpoints)
├── 📂 assets/ # 应用图标 (构建资源)
│ ├── 🖼️ logo.ico # Windows 图标 (264KB)
│ └── 🖼️ logo.png # macOS/Linux 图标 (2MB)
├── 📂 public/
│ └── 🖼️ logo.png # 渲染进程 Logo
├── 📄 .env.example # 环境变量模板
├── 📄 electron-builder.yml # 多平台构建配置
├── 📄 electron.vite.config.ts # electron-vite 配置
├── 📄 vite.config.ts # Vite + Vitest 配置
├── 📄 tsconfig.json # TypeScript 根配置
├── 📄 tsconfig.node.json # Node 端 TS 配置
├── 📄 tsconfig.web.json # Web 端 TS 配置
├── 📄 package.json # 依赖与脚本
├── 📄 index.html # HTML 入口
└── 📄 LICENSE # MIT 许可证
📝 开发命令
# ─── 开发 ─────────────────────────────────
npm run dev # 启动开发模式 (Electron + Vite 热重载)
npm run typecheck # 全量 TypeScript 类型检查
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 # 构建生产包 (Windows NSIS + 便携版)
npm run build:renderer # 仅构建渲染进程
npm run build:electron # 仅编译主进程 TypeScript
npm run preview # 预览构建产物
数据库 Schema
| 表名 | 用途 | 关键特性 |
|---|---|---|
sessions |
会话管理 | title, created_at, updated_at, pinned, archived |
messages |
消息持久化 | role, content, reasoning_content, tool_calls (JSON), token_usage |
app_config |
应用配置 | 键值对，5 大分类 (llm/agent/tools/security/logging) |
audit_logs |
审计日志 | chain_hash (SHA-256), INSERT-ONLY 触发器 |
mcp_servers |
MCP Server 配置 | name, transport (stdio/sse), command, args, env, url |
episodic_memories |
情节记忆 | content, importance, access_count, last_accessed, created_at |
semantic_memories |
语义记忆 | content, embedding (JSON), importance, decay_factor |
working_memories |
工作记忆 | key-value, session_id, expires_at |
tasks |
持久化任务 | title, description, status, priority, parent_id, session_id |
📄 许可证
本项目基于 MIT License 开源。
Made with ❤️ by the Metona Team · 2026