MetonaAI Desktop

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

---

Metona 是一款基于 Electron 的本地优先 AI Agent 桌面应用，内置 ReAct 状态机驱动的智能体循环引擎、28 个内置工具、三层记忆系统、四层纵深安全防线与完整可观测性链路。支持六种 LLM Provider（DeepSeek / Agnes / MiMo / Ollama / OpenAI / Anthropic），兼容 MCP 协议扩展（stdio / SSE / Streamable HTTP），为开发者提供开箱即用的 AI 编程伙伴。

---

📑 目录

• ✨ 核心亮点
• 🛠 技术栈
• 🚀 快速开始
• 🧠 智能体引擎
• 🔧 工具系统
• 🔌 LLM 适配器
• 🧩 记忆系统
• 🛡 安全机制
• 🏗 项目架构
• 📊 可观测性
• 🎨 桌面体验
• ⚙️ 配置说明
• 📁 项目结构
• 📝 开发命令
• 📄 许可证

---

✨ 核心亮点

🧠 生产级 Agent 引擎 ReAct 八状态闭环、流式对话 (SSE/NDJSON)、Thinking 推理模式、死循环检测、上下文自动压缩、指数退避重试	🔧 28 个内置工具 文件系统 · 代码搜索 · 网络搜索 · 浏览器自动化 · Git · Shell 命令 · HTTP 请求 · 记忆存储 · 任务管理
🔌 多 Provider 支持 + 故障转移 DeepSeek V4 · Agnes AI 2.0 · Xiaomi MiMo 2.5 · Ollama · OpenAI · Anthropic — 一键切换，热重载适配器，主 Provider 失败自动切换备用	🧩 三层记忆架构 情节记忆 (Episodic) + 语义记忆 (Semantic) + 工作记忆 (Working)，TF-IDF 语义检索 + 时间衰减
🛡 四层纵深防御 路径边界校验 + Shell 沙箱 + 三级权限策略 + Prompt 注入检测 + 幻觉校验 — 层层设防	📡 MCP 协议兼容 支持 stdio / SSE / Streamable HTTP 三种传输方式的 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	富文本渲染
🌐 HTML 解析	node-html-parser	6	搜索引擎结果结构化解析
🔢 UUID	nanoid	5	唯一 ID 生成
💾 缓存	lru-cache	11	内存缓存
📋 日志	electron-log	5	分级结构化日志
⌨️ 命令解析	shell-quote	1	Shell 命令 token 化（防注入）

---

🚀 快速开始

环境要求

• Node.js ≥ 18
• npm ≥ 9
• Windows / macOS / Linux

安装与运行

# 1. 克隆仓库
git clone https://git.metona.cn/MetonaTeam/metona-ai-desktop.git
cd metona-ai-desktop

# 2. 配置私有 npm 仓库凭据（@metona-team/metona-toast 需要）
#    值为 base64("用户名:密码")，向仓库管理员申请
$env:GITEA_NPM_AUTH = "<你的 base64 凭据>"   # PowerShell
# export GITEA_NPM_AUTH="<你的 base64 凭据>"  # bash

# 3. 安装依赖
npm install

# 4. 配置 API Key（可选——推荐启动后在应用内「设置 → LLM 配置」可视化配置）
cp .env.example .env
# 编辑 .env 预置密钥（应用内未配置时自动回退读取，见下方「环境变量」说明）

# 5. 启动开发模式
npm run dev

# 6. 构建生产包
npm run build

配置 LLM Provider

在应用内通过 设置 → LLM 配置 可视化配置（推荐，密钥经操作系统密钥链加密存储）；或在 .env 中预置密钥（应用内未配置对应字段时自动回退读取）：

# 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

# OpenAI (https://platform.openai.com)
OPENAI_API_KEY=sk-your-key-here
OPENAI_BASE_URL=https://api.openai.com/v1

# Anthropic (https://console.anthropic.com)
ANTHROPIC_API_KEY=sk-ant-your-key-here
ANTHROPIC_BASE_URL=https://api.anthropic.com

# 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 摘要压缩，按 token 预算动态保留近期消息（超长 tool_result 二次截断）
🖼️ 多轮图片记忆	历史轮次的图片随上下文回传 LLM（最近 10 张，从最新向前收集）；多模态总开关 llm.multimodalEnabled 控制上传入口
🔄 错误重试	指数退避 (1s/2s/4s) + ±20% jitter，上限 30s
⏱️ 可配置迭代	最大迭代次数 (默认 20)、总超时 (默认 600s)、工具执行超时 (默认 120s)
🧵 子任务委派	TaskOrchestrator 支持最大 3 层深度的 SubAgent 编排

---

🔧 工具系统

工具分类总览

Metona 内置 28 个工具，按安全风险分为五个等级：

SAFE (14 个)               LOW (5 个)             MEDIUM (6 个)        HIGH (3 个)          CRITICAL (预留)
    │                       │                      │                    │                    │
    ├─ read_file            ├─ web_search          ├─ write_file*       ├─ delete_file       ├─ (预留)
    ├─ list_directory       ├─ web_fetch           ├─ file_editor*      ├─ run_command
    ├─ search_files         ├─ http_request        ├─ file_move*        └─ web_browser
    ├─ code_search          ├─ run_tests           ├─ git_commit*
    ├─ diff_viewer          └─ task_manager        ├─ memory_store
    ├─ git_status                                  └─ delegate_task
    ├─ git_diff
    ├─ git_log
    ├─ lint_code
    ├─ project_info
    ├─ memory_search
    ├─ view_image
    ├─ file_info
    └─ think

* 标记的 MEDIUM 工具设置了 requiresPermission: true（执行前需用户确认）；未标记的 MEDIUM 工具（memory_store / delegate_task）无需确认。

详细工具列表

📂 文件系统 (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 紧凑格式或 NULL 分隔的完整字段格式
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 / deepseek-v4-flash-vision-exp	1M (vision 128K)	SSE	thinking.type + reasoning_effort	是（仅 vision 系列）
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)
OpenAIAdapter	openai	gpt-4o / gpt-4.1 / o3-mini	128K~1M tokens	SSE	reasoning_effort（o 系列）	是（o 系列除外）
AnthropicAdapter	anthropic	claude-sonnet-4-5 / claude-opus-4-1 / claude-haiku-4-5	200K tokens	SSE（原生事件）	thinking.budget_tokens	是 (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│   │
│  │ 28 工具注册 │ │ 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 命名空间，v0.5.0 新增 llm)
Renderer	Chromium	React 19 + MUI 9 界面渲染，Zustand 状态管理

核心数据流

用户输入 → ChatInput → agent-store.sendMessage
  → IPC: agent:sendMessage → ipc/agent.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
• SubAgent 状态区（v0.5.0）：AgentMonitor 实时展示 delegate_task 委派的子任务生命周期（委派/运行/完成/失败、层级深度、耗时、迭代轮数）

会话录制

• 9 种事件类型：session_start, context_built, iteration_start, llm_request, llm_response, tool_call, tool_result, iteration_end, session_end
• 录制到 JSONL 文件（{workspace}/logs/session_*.jsonl），支持事后回放分析
• v0.5.0: SubAgent（delegate_task）的执行轨迹录制到独立 JSONL 文件（taskId 作为会话标识）

审计日志

• 链式哈希防篡改：每条记录哈希 = SHA-256(prev_hash + 记录内容)，INSERT-ONLY 触发器
• 完整性校验：verifyChain() 逐条验证哈希链
• 导出：支持 JSONL / CSV 两种格式导出（设置 → 日志与数据）

SLO 监控

SLOMonitor 在 5 分钟滑动窗口内实时统计 Agent 请求质量，燃烧速率超预算时记录告警日志：

监控项	说明
请求成功率	按 complete 事件的 terminationReason 统计错误率
延迟分布	P50 / P95 / P99 分位数 + 平均延迟
吞吐量	每秒请求数
燃烧速率	实际错误率 / 错误预算（目标 99.9%），>1 时告警
健康检查	每 60s 检查数据库连通性、系统可用内存、主进程堆内存

---

🎨 桌面体验

三栏 IDE 布局

┌──────────┬──────────────────────────────┬──────────────┐
│          │        Header 顶部栏          │              │
│ Sidebar  │  Provider · Model · 面板切换   │  DetailPanel │
│ 300px    ├──────────────────────────────┤   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)

主进程启动时通过 dotenv 自动加载。应用内配置优先：.env 中的值仅在应用内对应字段为空时作为回退默认值（适合预置团队默认 Provider，个人密钥仍建议在应用内配置以获得密钥链加密）。

# ===========================================
#           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

# OpenAI (https://platform.openai.com)
OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://api.openai.com/v1

# Anthropic (https://console.anthropic.com)
ANTHROPIC_API_KEY=sk-ant-your-key
ANTHROPIC_BASE_URL=https://api.anthropic.com

# Ollama (本地运行)
OLLAMA_BASE_URL=http://localhost:11434

应用配置 (app_config 表)

配置项	默认值	说明
llm.provider	（空）	LLM Provider ID（未配置时回退 .env）
llm.model	（空）	模型标识符
llm.temperature	0	生成温度（注入引擎请求参数）
llm.maxTokens	63488	单次生成最大 token（各 Provider 按模型上限自动钳制）
llm.multimodalEnabled	false	多模态总开关 — 未开启时即使模型支持也不能上传图片
security.promptInjectionDefense	true	提示注入检测总开关（用户消息 + 工具结果扫描）
logging.auditEnabled	true	工具调用审计日志开关
logging.traceEnabled	true	会话 TRACE 录制开关（JSONL 文件）
agent.maxIterations	20	ReAct 最大迭代轮次
agent.totalTimeoutMs	600000	Agent 总超时 (ms)
agent.toolExecutionTimeoutMs	120000	单个工具执行超时 (ms)
agent.thinkingEnabled	true	启用 Thinking 推理模式
agent.thinkingEffort	high	推理强度 (low / medium / high / max)
agent.confirmationTimeoutMs	120000	确认弹窗超时 (30s ~ 600s)
deepseek.contextWindow	1000000	DeepSeek 上下文窗口
agnes.contextWindow	1000000	Agnes 上下文窗口
mimo.contextWindow	1000000	MiMo 上下文窗口
openai.contextWindow	128000	OpenAI 上下文窗口
anthropic.contextWindow	200000	Anthropic 上下文窗口
ollama.numCtx	（空）	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/                           # IPC 域模块 (P2 拆分, 50+ 通道)
│   │   ├── 📄 index.ts                   #   统一注册入口（防重入）
│   │   ├── 📄 context.ts                 #   共享上下文 + broadcast 多窗口广播
│   │   ├── 📄 shared.ts                 #   配置写入共享副作用
│   │   ├── 📄 agent.ts                   #   Agent 消息/中断/常驻事件管道/SubAgent 广播与录制
│   │   ├── 📄 sessions.ts               #   会话 CRUD/消息截断/Trace 持久化
│   │   ├── 📄 config.ts                 #   配置读写 (get/set/setBatch)
│   │   ├── 📄 tools.ts                  #   工具列表/确认/自动执行
│   │   └── 📄 ... (mcp/memory/tasks/data/workspace/app)
│   ├── 📂 services/                      # 业务服务层 (12 个 Service)
│   │   ├── 📄 agent-engine-manager.service.ts #   每会话独立引擎管理 (P2)
│   │   ├── 📄 audit.service.ts           #   审计日志 (链式哈希防篡改)
│   │   ├── 📄 config.service.ts          #   配置管理 (全局+工作空间分层)
│   │   ├── 📄 database.service.ts        #   SQLite 数据库 (WAL 模式, 10 张表)
│   │   ├── 📄 global-config.service.ts   #   机器级全局配置 (JSON, 敏感项加密)
│   │   ├── 📄 mcp-manager.service.ts     #   MCP Server 生命周期管理
│   │   ├── 📄 session-recorder.service.ts#   会话 JSONL 录制 (9 种事件, 多会话)
│   │   ├── 📄 session-summary.service.ts #   会话滚动摘要 (分层上下文, P2)
│   │   ├── 📄 session.service.ts         #   会话 CRUD
│   │   ├── 📄 tray-manager.service.ts    #   系统托盘 (4 状态)
│   │   ├── 📄 window-manager.service.ts  #   窗口管理 + 全局快捷键
│   │   └── 📄 workspace.service.ts       #   工作空间 (SOUL.md + MEMORY.md)
│   ├── 📂 harness/                       # Agent 智能体核心引擎
│   │   ├── 📂 agent-loop/                #   ReAct 状态机
│   │   │   ├── 📄 engine.ts              #     循环引擎 (8 状态, 重试+故障转移)
│   │   │   └── 📄 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 行)
│   │   │   ├── 📄 openai.adapter.ts      #     OpenAI (o 系列推理模型, P3)
│   │   │   ├── 📄 anthropic.adapter.ts   #     Anthropic Messages API (P3)
│   │   │   └── 📂 shared/               #     共享: OpenAI 格式 · SSE 解析
│   │   ├── 📂 tools/                     #   工具系统
│   │   │   ├── 📄 registry.ts            #     工具注册 · PolicyEngine · 超时管理
│   │   │   └── 📂 built-in/              #     28 个内置工具实现
│   │   │       ├── 📄 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 渲染进程 (~50 文件)
│   ├── 📄 main.tsx                       #   渲染进程入口
│   ├── 📄 App.tsx                        #   根组件 (三栏布局 + Store 连接)
│   ├── 📂 components/
│   │   ├── 📂 chat/                      #   聊天组件 (11 个)
│   │   │   ├── 📄 ChatPanel.tsx          #     聊天主面板
│   │   │   ├── 📄 MessageList.tsx        #     消息列表 (react-virtuoso 真虚拟滚动)
│   │   │   ├── 📄 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 状态指示器 + SubAgent 状态区
│   │   │   └── 📄 StatusBar.tsx          #     底部状态栏
│   │   ├── 📂 settings/                  #   设置弹窗 (v0.4.1 拆分, 10 文件)
│   │   │   ├── 📄 SettingsModal.tsx      #     主框架 + 垂直 Tab 导航
│   │   │   ├── 📄 useConfig.ts           #     共享配置读写 Hook
│   │   │   └── 📄 ... (LLM/Agent/Tools/MCP/SearXNG/Appearance/Logs/Workspace 8 个 Tab)
│   │   ├── 📂 memory/
│   │   │   └── 📄 MemoryViewer.tsx       #   记忆浏览器 (3 类型)
│   │   ├── 📂 tasks/
│   │   │   └── 📄 TaskList.tsx           #   任务列表
│   │   ├── 📂 trace/                     #   追踪组件 (3 个)
│   │   │   ├── 📄 TraceViewer.tsx        #     ReAct 迭代时间轴 (按 runId 分组)
│   │   │   ├── 📄 TraceStep.tsx          #     单步详情 (Thought + ToolCalls)
│   │   │   └── 📄 TokenUsage.tsx         #     Token 统计面板
│   │   ├── 📂 workspace/
│   │   │   └── 📄 WorkspaceViewer.tsx    #   工作空间浏览器
│   │   ├── 📂 onboarding/
│   │   │   └── 📄 OnboardingWizard.tsx   #   5 步引导向导
│   │   ├── 📂 common/
│   │   │   └── 📄 ErrorBoundary.tsx      #   错误边界 (上报 error:report)
│   │   ├── 📄 CommandPalette.tsx         #   Cmd+K 命令面板
│   │   ├── 📄 ConfirmationDialog.tsx     #   工具确认弹窗 (批量审批 + 拒绝记忆恢复)
│   │   ├── 📄 ContextMenu.tsx            #   右键菜单 (5 类对象)
│   │   └── 📄 ToastContainer.tsx         #   Toast 通知 (metona-toast v2)
│   ├── 📂 hooks/
│   │   ├── 📄 useAgentStream.ts          #   流式事件监听 (rAF 批处理 + runId 过滤)
│   │   ├── 📄 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 暗色/亮色主题
│   │   ├── 📄 export-markdown.ts        #   会话 Markdown 导出
│   │   ├── 📄 tool-result-display.ts    #   工具结果显示层裁剪 (剥离 base64)
│   │   └── 📄 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, 系统 Node — audit 套件因 better-sqlite3 ABI 自动跳过)
npm run test:electron      # 运行全量单元测试 (Electron Node ABI, 252 用例全执行, 含 SQLite 审计链哈希 + 引擎工具链集成)
npm run test:watch         # 测试监听模式

# ─── 构建 ─────────────────────────────────
npm run build              # 构建生产包 (Windows NSIS + 便携版)
npm run build:renderer     # 仅构建渲染进程
npm run build:electron     # 仅编译主进程 TypeScript
npm run preview            # 预览构建产物

数据库 Schema

共 10 张表（v0.4.0 新增 session_summaries 用于分层上下文）：

表名	用途	关键特性
sessions	会话管理	title, created_at, updated_at, pinned, archived
messages	消息持久化	role, content, reasoning_content, tool_calls (JSON), attachments (JSON), iteration
app_config	应用配置	键值对（llm / agent / tools / security / logging / searxng / ui）
audit_logs	审计日志	prev_hash + current_hash 链式哈希 (SHA-256), INSERT-ONLY 触发器
mcp_servers	MCP Server 配置	name, transport (stdio/sse/streamable-http), command, args, url
episodic_memories	情节记忆	content, summary, source, importance, tf_cache (分词缓存)
semantic_memories	语义记忆	key-value (UNIQUE key), category, confidence, access_count, tf_cache
working_memories	工作记忆	key-value, session_id + task_id + key 唯一约束
tasks	持久化任务	title, description, status, priority, parent_id (自引用), order_idx
session_summaries	会话滚动摘要	summary, summarized_until_rowid 游标（分层上下文加载）

---

📄 许可证

本项目基于 MIT License 开源。

---

_{Made with ❤️ by the Metona Team · 2026}