thzxx
9b45c445bf
硬性契约：删除代码中一切写死的上下文窗口与最大输出上限（含六家模型元信息
钳制与全部兜底值）——唯一合法来源是设置面板「上下文长度」（llm.contextWindow）
与「最大输出上限」（llm.maxTokens），跨 Provider/模型原样透传。
P0 正确性收口：
- 迁移 11/12（SCHEMA_VERSION 5）：记忆表 embedding 列 + 分 Provider 窗口键清理
- 记忆生命周期接线：会话终态清理 working memory / episodic 90 天 TTL / access_count 回写
- 回放缓冲模块化 + 会话终态清理（杜绝 4MB/会话内存滞留）
- i18n 收口：主进程 main-locale（zh/en，ui.locale 热切换）+ 渲染层 17 处出层
P1 能力演进：
- 本地向量混合检索：0.6×向量余弦 + 0.4×TF-IDF，Ollama embeddings 首次投产，
存量记忆惰性回填，嵌入不可用自动回退 TF-IDF
- MEMORY.md 维护闭环：固化去重消除截断盲区；两阶段维护（AI 建议 → 用户确认 →
原子改写 + 语义记忆双轨同步 + 审计）；>50KB 告警
- 可观测闭环：cacheTokens 引擎→前端透传（Token 面板命中率/成本行）+ 输入框
上下文占用指示条
- MCP Prompts/Resources 对话可用：/mcp:{server}:{prompt} 与 @mcp:{server}:{uri}
P2 体验补全：
- 工具自定义策略（正则白/黑名单 + 频率 + 强制确认，热生效）
- 连续 ≥3 同类工具确认聚合为单弹框
- 会话消息游标分页（首屏 200 条向上翻页）
- 开机自启；Playwright + Electron E2E 冒烟（本地 mock LLM 零外联）
Review 回归修复：MCP 大小写失配 / 分页状态复位 / 清空=未配置语义（Number(null)=0
隐患）/ MEMORY.md 告警位置 / working_memories FK（迁移 13）/ 全局配置层废键清理；
附带根治权限加固启动时序、代理回环放行、safeStorage 降级、悬空 symlink 逃逸。
验证：typecheck/lint 0 问题；test:electron 2478/2478（0 跳过）；E2E 2/2；
docs/v0.8.1-迭代实施清单.md 全项留档。
951 lines
58 KiB
Markdown
951 lines
58 KiB
Markdown
|
||
<p align="center">
|
||
<img src="assets/logo.png" alt="MetonaAI Logo" width="120" height="120" />
|
||
</p>
|
||
|
||
<h1 align="center">MetonaAI Desktop</h1>
|
||
|
||
<p align="center">
|
||
<strong>生产级通用 AI Agent 智能体桌面应用</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/version-0.8.1-blue?style=flat-square" alt="Version" />
|
||
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" />
|
||
<img src="https://img.shields.io/badge/Electron-35-47848F?style=flat-square&logo=electron" alt="Electron" />
|
||
<img src="https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react" alt="React" />
|
||
<img src="https://img.shields.io/badge/TypeScript-5.8-3178C6?style=flat-square&logo=typescript" alt="TypeScript" />
|
||
<img src="https://img.shields.io/badge/MUI-9-007FFF?style=flat-square&logo=mui" alt="MUI" />
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square" alt="Platform" />
|
||
<img src="https://img.shields.io/badge/DeepSeek-Supported-4D6BFE?style=flat-square" alt="DeepSeek" />
|
||
<img src="https://img.shields.io/badge/Agnes%20AI-Supported-8B5CF6?style=flat-square" alt="Agnes AI" />
|
||
<img src="https://img.shields.io/badge/MiMo-Supported-FF6B35?style=flat-square" alt="MiMo" />
|
||
<img src="https://img.shields.io/badge/Ollama-Supported-000000?style=flat-square&logo=ollama" alt="Ollama" />
|
||
</p>
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
Metona 是一款<strong>基于 Electron 的本地优先 AI Agent 桌面应用</strong>，内置<strong> ReAct 状态机驱动</strong>的智能体循环引擎、<strong>28 个内置工具</strong>、<strong>三层记忆系统</strong>、<strong>四层纵深安全防线</strong>与<strong>完整可观测性链路</strong>。支持六种 LLM Provider（DeepSeek / Agnes / MiMo / Ollama / OpenAI / Anthropic），兼容 <strong>MCP 协议</strong>扩展（stdio / SSE / Streamable HTTP），为开发者提供开箱即用的 AI 编程伙伴。
|
||
</p>
|
||
|
||
---
|
||
|
||
## 📑 目录
|
||
|
||
- [✨ 核心亮点](#-核心亮点)
|
||
- [🛠 技术栈](#-技术栈)
|
||
- [🚀 快速开始](#-快速开始)
|
||
- [🧠 智能体引擎](#-智能体引擎)
|
||
- [🔧 工具系统](#-工具系统)
|
||
- [🔌 LLM 适配器](#-llm-适配器)
|
||
- [🧩 记忆系统](#-记忆系统)
|
||
- [🛡 安全机制](#-安全机制)
|
||
- [🏗 项目架构](#-项目架构)
|
||
- [📊 可观测性](#-可观测性)
|
||
- [🎨 桌面体验](#-桌面体验)
|
||
- [⚙️ 配置说明](#-配置说明)
|
||
- [📁 项目结构](#-项目结构)
|
||
- [📝 开发命令](#-开发命令)
|
||
- [📄 许可证](#-许可证)
|
||
|
||
---
|
||
|
||
## 🆕 v0.8.1 更新亮点
|
||
|
||
| 特性 | 说明 |
|
||
|:---|:---|
|
||
| ⚙️ **上下文/输出上限 全局单一配置** | 硬性契约：删除代码中一切写死的上下文窗口与最大输出上限（含六家模型元信息钳制）——唯一合法来源是设置面板「上下文长度」与「最大输出上限」，跨 Provider/模型原样透传 |
|
||
| 🧠 **本地向量混合检索** | 激活 Ollama embeddings：记忆检索升级为 0.6×向量余弦 + 0.4×TF-IDF 混合评分，同义改写可召回；存量记忆惰性回填，嵌入不可用自动回退 TF-IDF |
|
||
| 📝 **MEMORY.md 维护闭环** | 固化去重消除全文截断盲区；两阶段维护（AI 建议 → 用户勾选 → 原子改写 + 语义记忆双轨同步）；>50KB 体积告警 |
|
||
| 📊 **成本/缓存可观测闭环** | Prompt Cache 命中率与估算成本（可选单价配置）进 Token 面板；输入框新增上下文占用指示条（60%/80% 变色） |
|
||
| 🔌 **MCP Prompts/Resources 对话可用** | `/mcp:{server}:{prompt}` 斜杠菜单填充输入框；`@mcp:{server}:{uri}` 资源注入附件管线（512KB 上限、二进制拒绝） |
|
||
| 🛡 **工具自定义策略** | 每个工具可配置拒绝/允许参数正则、频率上限、强制确认（设置 → 工具管理 → 策略），保存即热生效 |
|
||
| ⏩ **批量确认 & 游标分页 & 自启** | 连续 ≥3 同类工具确认自动聚合为单弹框；会话消息游标分页（首屏 200 条向上翻页）；开机自启开关 |
|
||
| 💾 **记忆生命周期接线** | 会话终态联动清理工作记忆；情节记忆 90 天 TTL 真实写入；语义记忆 access_count 检索回写（LRU 激活） |
|
||
| 🧪 **E2E 冒烟** | Playwright + Electron 端到端链路（本地 mock LLM，零外联、数据隔离）；附带根治权限加固启动时序、回环代理放行、safeStorage 降级三处环境级缺陷 |
|
||
|
||
---
|
||
|
||
## 🆕 v0.8.0 更新亮点
|
||
|
||
| 特性 | 说明 |
|
||
|:---|:---|
|
||
| 🔒 **流结束契约（根治"思考中会话停止"）** | finish_reason 全链路贯通：`length` 截断不再被静默判定为完成；零产出流自动重试；思考耗尽输出预算时自动降级（关闭思考）重试一次，仍失败则给出 OUTPUT_LENGTH_EXCEEDED 结构化错误与修复建议 |
|
||
| 🧠 **思考用户意图优先 + 预算自愈** | 思考参数完全遵循用户配置（模型元信息仅告警不拦截）；若思考耗尽输出预算（`finish_reason=length` 空回复），自动关闭思考重试一次，仍失败给出 `OUTPUT_LENGTH_EXCEEDED` 明确报错；Ollama 保留服务端能力探测门控（向不支持思考的模型发 `think` 会被服务端 400 拒绝） |
|
||
| 🪟 **后台会话回放缓冲** | 切走会话后其运行内容不再丢失，切回时自动恢复；abort 失败自愈、收尾兜底、中断卡片清扫三重防线 |
|
||
| 🗑️ **会话回收站** | 删除改为软删除，30 天自动清理；支持恢复与彻底删除 |
|
||
| 🎬 **会话回放播放器** | TRACE JSONL 录制可视化回放（时间轴 / 步进 / 变速） |
|
||
| 🛡️ **浏览器通道 SSRF 根治** | Agent 浏览器分区流量经本地 Pinned CONNECT 代理（校验期 IP pinning），关闭 DNS rebinding 残余窗口；配置类 URL 增加域名解析深校验 |
|
||
| 📦 **electron-updater 自动更新** | 生产环境启动静默检查、可用即通知，一键下载安装 |
|
||
| ✏️ **@ 文件提及** | 输入 `@` 联想工作空间文件，发送时以附件管线注入文本片段（512KB 上限 + 二进制拒绝） |
|
||
| 🔍 **MCP Resources/Prompts 发现** | 连接后自动发现并列出 Server 的资源与提示词（可选能力，失败静默降级） |
|
||
| ⚡ **工具中断全覆盖** | web_search / web_fetch / http_request / code_search / git 系列 / delegate_task 全部接入引擎 abort 信号；web_search 自动抓取增加时间预算收敛 |
|
||
|
||
---
|
||
|
||
## ✨ 核心亮点
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%">
|
||
<h3>🧠 生产级 Agent 引擎</h3>
|
||
<p>ReAct 八状态闭环、流式对话 (SSE/NDJSON)、Thinking 推理模式、死循环检测、上下文自动压缩、指数退避重试</p>
|
||
</td>
|
||
<td width="50%">
|
||
<h3>🔧 28 个内置工具</h3>
|
||
<p>文件系统 · 代码搜索 · 网络搜索 · 浏览器自动化 · Git · Shell 命令 · HTTP 请求 · 记忆存储 · 任务管理</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<h3>🔌 多 Provider 支持 + 故障转移</h3>
|
||
<p>DeepSeek V4 · Agnes AI 2.0 · Xiaomi MiMo 2.5 · Ollama · OpenAI · Anthropic — 一键切换，热重载适配器，主 Provider 失败自动切换备用</p>
|
||
</td>
|
||
<td>
|
||
<h3>🧩 三层记忆架构</h3>
|
||
<p>情节记忆 (Episodic) + 语义记忆 (Semantic) + 工作记忆 (Working)，TF-IDF 语义检索 + 时间衰减</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<h3>🛡 四层纵深防御</h3>
|
||
<p>路径边界校验 + Shell 沙箱 + 三级权限策略 + Prompt 注入检测 + 幻觉校验 — 层层设防</p>
|
||
</td>
|
||
<td>
|
||
<h3>📡 MCP 协议兼容</h3>
|
||
<p>支持 stdio / SSE / Streamable HTTP 三种传输方式的 MCP Server，动态发现工具，无需重启应用</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<h3>📊 全链路可观测</h3>
|
||
<p>ReAct 迭代追踪 · JSONL 会话录制 · 链式哈希审计 · Token 用量统计 · SLO 健康监控</p>
|
||
</td>
|
||
<td>
|
||
<h3>🎨 精致桌面体验</h3>
|
||
<p>三栏 IDE 布局 · 系统托盘 · 全局快捷键 · 暗色/亮色主题 · 5 步引导向导 · 命令面板</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
---
|
||
|
||
## 🛠 技术栈
|
||
|
||
| 层级 | 技术 | 版本 | 用途 |
|
||
|:---|:---|:---|:---|
|
||
| 🖥 运行时 | **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 化（防注入） |
|
||
| 🌍 国际化 | **i18next + react-i18next** | latest | 集中文案字典与多语言运行时（扁平 key） |
|
||
| 📝 HTML→MD | **turndown** | 7 | web_fetch markdown 输出模式转换器 |
|
||
| 🔀 网络代理 | **undici** | latest | 主进程 fetch 的 ProxyAgent 全局调度器 |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- **Node.js** ≥ 18
|
||
- **npm** ≥ 9
|
||
- **Windows** / **macOS** / **Linux**
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
# 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` 中预置密钥（应用内未配置对应字段时自动回退读取）：
|
||
|
||
```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 (13 个) LOW (4 个) MEDIUM (8 个) HIGH (3 个) CRITICAL (预留)
|
||
│ │ │ │ │
|
||
├─ read_file ├─ web_search ├─ write_file* ├─ delete_file ├─ (预留)
|
||
├─ list_directory ├─ web_fetch ├─ file_editor* ├─ run_command
|
||
├─ search_files ├─ lint_code* ├─ file_move* └─ web_browser
|
||
├─ code_search └─ task_manager ├─ http_request*
|
||
├─ diff_viewer ├─ git_commit*
|
||
├─ git_status ├─ run_tests*
|
||
├─ git_diff ├─ memory_store
|
||
├─ git_log └─ delegate_task
|
||
├─ project_info
|
||
├─ memory_search
|
||
├─ view_image
|
||
├─ file_info
|
||
└─ think
|
||
```
|
||
|
||
> `*` 标记的工具设置了 `requiresPermission: true`（执行前需用户确认）；未标记的 MEDIUM 工具（memory_store / delegate_task）无需确认。v0.7.4：lint_code 升 LOW + 需确认、run_tests 升 MEDIUM + 需确认（二者经 npm/npx 执行工作区代码，与 run_command 执行边界对齐）。
|
||
|
||
### 详细工具列表
|
||
|
||
#### 📂 文件系统 (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 限制，SSRF 防护 + 重定向终态复检 |
|
||
| `web_browser` | HIGH | 是 | 统一浏览器工具：open / screenshot / evaluate / extract / click / type / scroll / wait / close，open 动作同样经过 SSRF 校验 |
|
||
| `http_request` | MEDIUM | 是 | 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` | LOW | 是 | TypeScript tsc 或 ESLint 检查（v0.7.4: 经 npx 执行工作区代码，升 LOW + 需确认 + --no-install 禁自动下载） |
|
||
| `run_tests` | MEDIUM | 是 | 运行测试套件 (jest/vitest/mocha)，filter 白名单防注入（v0.7.4: npm test 执行 scripts.test 任意命令，升 MEDIUM + 需确认） |
|
||
| `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，个人密钥仍建议在应用内配置以获得密钥链加密）。
|
||
|
||
```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
|
||
|
||
# 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) |
|
||
| `agent.enableReflection` | `false` | 反思阶段开关 — 开启后每轮工具执行经过 REFLECTING 状态（失败结果告警，不阻断） |
|
||
| `memory.consolidationEnabled` | `true` | 会话结束记忆固化总开关（v0.7.3 节流策略） |
|
||
| `memory.consolidationMinChars` | `200` | 固化内容门控：回答字符数阈值（或存在成功工具调用） |
|
||
| `memory.consolidationIntervalMs` | `600000` | 固化频率窗口（同会话两次固化的最小间隔） |
|
||
| `mcp.autoReconnect` | `true` | MCP 断连自动重连（指数退避 5s/15s/60s，最多 3 次） |
|
||
| `llm.contextWindow` | `131072` | **上下文长度（全局唯一合法配置，v0.8.1）** —— 驱动引擎压缩预算与占用指示，Ollama 场景同时作为 num_ctx 下发；分 Provider 的 contextWindow 键与 ollama.numCtx 已废除（迁移 12 清理） |
|
||
| `llm.maxTokens` | `63488` | **最大输出上限（全局唯一合法配置，v0.8.1）** —— 原样透传请求参数，代码中不存在任何按模型钳制 |
|
||
| `llm.priceInput` / `llm.priceOutput` | （空） | 成本估算单价（每百万 tokens，可选；留空隐藏成本行） |
|
||
| `memory.embeddingModel` | （空） | 本地向量记忆嵌入模型（Ollama embedding 模型名；留空 = 纯 TF-IDF 检索） |
|
||
|
||
### 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 许可证
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 开发命令
|
||
|
||
```bash
|
||
# ─── 开发 ─────────────────────────────────
|
||
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 — SQLite 依赖用例因 better-sqlite3 ABI 自动跳过)
|
||
npm run test:electron # 运行全量单元测试 (Electron Node ABI, 全部用例执行, 含 SQLite 审计链哈希 + 引擎工具链集成)
|
||
npm run test:watch # 测试监听模式
|
||
npm run test:e2e # E2E 冒烟（构建产物 + Playwright + Electron，本地 mock LLM 零外联）
|
||
|
||
# ─── 构建 ─────────────────────────────────
|
||
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](./LICENSE) 开源。
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<sub>Made with ❤️ by the Metona Team · 2026</sub>
|
||
</p>
|