metona-ai-desktop/README.md

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)
MimoAdapter	mimo	mimo-v2.5-pro / mimo-v2.5	131K 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	131072	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, 131K 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}