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