thzxx
8973ea6d47
针对 AI 流式输出长内容时应用卡死问题，实施 12 项性能优化： 渲染层优化（F1/F3/F7）： - F1: React.memo 包裹 MessageItem/AssistantMessage，跳过历史消息重渲染 - F3: 流式时用纯文本渲染，避免 ReactMarkdown 全量重解析 O(n²) - F7: useMemo 缓存 ReactMarkdown 元素，非流式时复用实例 滚动与布局（F2/F4/F10/F12）： - F2: 滚动节流 rAF + 100ms throttle + trailing 兜底，避免高频布局 - F4: CSS content-visibility 准虚拟滚动，跳过不可见区域布局 - F10: CSS contain 隔离 markdown 布局计算 - F12: 滚动容器 transform: translateZ(0) GPU 加速 状态与 IPC 批处理（F5/F8/F9）： - F5: 渲染进程 text_delta rAF 批处理，合并多次 store 写入 - F8: 主进程 text_delta 32ms 节流合并，降低 IPC 频率 - F9: reasoning_delta traceSteps thought 走 rAF 批处理 代码清理（F11）： - F11: 移除 rehypeRaw，节省 raw HTML 解析开销 + 防 AI 输出注入 验证：tsc --noEmit 通过，flush 逻辑在 done/error/cleanup 三处正确执行。
583 lines
24 KiB
Markdown
583 lines
24 KiB
Markdown
# MetonaAI Desktop
|
||
|
||
> 生产级通用 AI Agent 智能体桌面应用
|
||
|
||
[](./package.json)
|
||
[](./LICENSE)
|
||
[](https://www.electronjs.org/)
|
||
[](https://react.dev/)
|
||
[](https://www.typescriptlang.org/)
|
||
|
||
Metona 是一款基于 Electron 的生产级 AI Agent 桌面应用，内置 ReAct 状态机驱动的智能体循环、27 个内置工具、三层记忆系统、四层安全防线与完整的可观测性链路。支持 DeepSeek、Agnes AI、MiMo（小米）、Ollama 四种 LLM Provider，兼容 MCP 协议扩展。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [技术栈](#技术栈)
|
||
- [快速开始](#快速开始)
|
||
- [核心特性](#核心特性)
|
||
- [项目架构](#项目架构)
|
||
- [内置工具](#内置工具)
|
||
- [LLM 适配器](#llm-适配器)
|
||
- [记忆系统](#记忆系统)
|
||
- [安全机制](#安全机制)
|
||
- [配置说明](#配置说明)
|
||
- [项目结构](#项目结构)
|
||
- [开发命令](#开发命令)
|
||
- [许可证](#许可证)
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| 运行时 | 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 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js >= 18
|
||
- npm >= 9
|
||
- Windows / macOS / Linux
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发模式（启动 Electron + Vite 热重载）
|
||
npm run dev
|
||
|
||
# 类型检查
|
||
npm run typecheck
|
||
|
||
# 构建生产包（Windows 输出 NSIS 安装包 + 便携版）
|
||
npm run build
|
||
```
|
||
|
||
### 配置 LLM Provider
|
||
|
||
1. 复制 `.env.example` 为 `.env`，填入 API Key：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
```env
|
||
# DeepSeek API
|
||
DEEPSEEK_API_KEY=your_key
|
||
DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||
|
||
# Agnes AI API
|
||
AGNES_API_KEY=your_key
|
||
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
|
||
|
||
# Ollama（本地运行，无需 Key）
|
||
OLLAMA_BASE_URL=http://localhost:11434
|
||
```
|
||
|
||
2. 或在应用启动后，通过 **设置 → LLM 配置** 界面可视化配置 Provider、API Key、模型、上下文窗口等参数。
|
||
|
||
---
|
||
|
||
## 核心特性
|
||
|
||
### 智能体引擎
|
||
|
||
- **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）
|
||
|
||
### 工具与执行
|
||
|
||
- **27 个内置工具**：覆盖文件系统、代码搜索、网络搜索、浏览器自动化、Git、开发工具、记忆、任务管理等
|
||
- **MCP 协议支持**：动态加载外部 MCP Server 工具
|
||
- **子任务委派**：TaskOrchestrator 支持最大 3 层深度的 SubAgent 编排
|
||
- **策略引擎**：三级权限（READ/WRITE/EXTERNAL_ACTION）+ 滑动窗口频率限制
|
||
- **确认机制**：HIGH/CRITICAL 风险工具需用户确认，支持会话内同类免确认与持久化自动执行
|
||
|
||
### 记忆与上下文
|
||
|
||
- **三层记忆系统**：情节记忆（episodic）、语义记忆（semantic）、工作记忆（working）
|
||
- **TF-IDF 语义检索**：中英文分词 + 时间衰减（30 天半衰期）+ IDF 缓存
|
||
- **自动记忆固化**：会话结束时 LLM 提取重要信息写入 MEMORY.md
|
||
- **System Prompt 分区构建**：SOUL.md + AGENTS.md + USERS.md + MEMORY.md + 安全准则
|
||
|
||
### 安全防线（四层纵深防御）
|
||
|
||
1. **路径安全**：工作空间边界校验 + realpathSync 符号链接逃逸检测 + 根目录 MEMORY.md 保护
|
||
2. **命令安全**：SandboxManager 28 模式扫描 + shell-quote 双层防御 + 受保护文件检查
|
||
3. **权限控制**：PolicyEngine 三级权限 + 频率限制（20 次/分钟）+ 用户确认钩子
|
||
4. **内容安全**：PromptInjectionDefender（30+ 正则 + 语义检测）+ OutputValidator（幻觉检测）
|
||
|
||
### 可观测性
|
||
|
||
- **全链路追踪**：TraceViewer 可视化 ReAct 每轮迭代
|
||
- **会话录制**：9 种事件录制到 JSONL 文件
|
||
- **审计日志**：SQLite 链式哈希防篡改（INSERT-ONLY 触发器）
|
||
- **Token 统计**：输入/输出/推理 Token 用量追踪
|
||
|
||
### 桌面体验
|
||
|
||
- **三栏布局**：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）
|
||
|
||
---
|
||
|
||
## 项目架构
|
||
|
||
### 四层 Harness 架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 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 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 进程模型
|
||
|
||
| 进程 | 运行时 | 职责 |
|
||
|------|--------|------|
|
||
| Main Process | Node.js | Agent 引擎、工具调度、数据库、MCP 管理、配置 |
|
||
| Preload Script | 沙箱 | contextBridge 安全暴露 14 个 API 命名空间 |
|
||
| Renderer | Chromium | React 19 + MUI 9 界面渲染 |
|
||
|
||
### 数据流
|
||
|
||
```
|
||
用户输入 → ChatInput → agent-store.sendMessage
|
||
→ IPC: agent:sendMessage → handlers.ts
|
||
→ reloadAdapter (热重载，配置签名比对)
|
||
→ 保存用户消息到 SQLite
|
||
→ 加载历史消息 + 注入相关记忆
|
||
→ ContextBuilder.buildSystemPrompt (SOUL+AGENTS+USERS+MEMORY+安全准则)
|
||
→ PromptInjectionDefender.detect (riskScore>=7 阻断)
|
||
→ AgentLoopEngine.runStream
|
||
→ Adapter.sendStream (SSE/NDJSON 流式)
|
||
→ 流式事件 → webContents.send('agent:streamEvent')
|
||
→ 工具调用 → PreToolHooks (权限+频率+确认)
|
||
→ ToolRegistry.execute → PostToolHooks (审计+记忆触发)
|
||
→ 80% 阈值触发上下文压缩
|
||
→ 死循环检测 (3 轮相同签名)
|
||
→ OutputValidator.validate (幻觉检测)
|
||
→ 保存 assistant 消息 + tool 结果消息
|
||
→ MemoryConsolidator.consolidate (异步提取记忆)
|
||
→ AuditService.logSessionEnd
|
||
← useAgentStream Hook 监听事件 → Zustand Store → React 重渲染
|
||
```
|
||
|
||
---
|
||
|
||
## 内置工具
|
||
|
||
Metona 内置 27 个工具，按功能分类如下：
|
||
|
||
### 文件系统（5 个）
|
||
|
||
| 工具 | 风险 | 需确认 | 功能 |
|
||
|------|------|--------|------|
|
||
| `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 个）
|
||
|
||
| 工具 | 风险 | 需确认 | 功能 |
|
||
|------|------|--------|------|
|
||
| `file_editor` | MEDIUM | 是 | 精准编辑，replace/insert/delete/regex + dry_run |
|
||
| `code_search` | SAFE | 否 | 基于 ripgrep 高速搜索，回退 JS |
|
||
| `diff_viewer` | SAFE | 否 | unified diff 格式，LCS 算法 |
|
||
|
||
### 网络与浏览器（4 个）
|
||
|
||
| 工具 | 风险 | 需确认 | 功能 |
|
||
|------|------|--------|------|
|
||
| `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 |
|
||
|
||
### 记忆（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，支持父子关系 |
|
||
| `todo_write` | SAFE | 否 | 会话级 TODO，LRU 淘汰（max 50 sessions） |
|
||
| `think` | SAFE | 否 | 结构化思考空间，无副作用 |
|
||
| `view_image` | SAFE | 否 | 读取图片返回 base64，5MB 限制，7 种格式 |
|
||
|
||
---
|
||
|
||
## 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） |
|
||
|
||
### 上下文窗口配置
|
||
|
||
- **DeepSeek / Agnes / MiMo**：`contextWindow` 配置项影响本地压缩判断和 UI 显示（最小 4096）
|
||
- **Ollama**：`num_ctx` 配置项直接影响 API 请求参数
|
||
- 切换 Provider 时自动清空 API Key，防止使用不兼容的密钥
|
||
- Engine 上下文窗口与 Adapter 配置值自动同步
|
||
|
||
---
|
||
|
||
## 记忆系统
|
||
|
||
### 三层记忆架构
|
||
|
||
| 层级 | 类型 | 存储表 | 用途 | 检索方式 |
|
||
|------|------|--------|------|----------|
|
||
| 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 角色定义（灵魂） | 是 |
|
||
| AGENTS.md | AI 行为规则 | 是 |
|
||
| MEMORY.md | 动态记忆存储 | 是（仅根目录受保护） |
|
||
| USERS.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
|
||
# DeepSeek API
|
||
DEEPSEEK_API_KEY=your_deepseek_api_key_here
|
||
DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||
|
||
# Agnes AI API
|
||
AGNES_API_KEY=your_agnes_api_key_here
|
||
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
|
||
|
||
# Xiaomi MiMo API
|
||
MIMO_API_KEY=your_mimo_api_key_here
|
||
MIMO_BASE_URL=https://api.xiaomimimo.com/v1
|
||
|
||
# Ollama API (local)
|
||
OLLAMA_BASE_URL=http://localhost:11434
|
||
|
||
# App
|
||
VITE_APP_TITLE=MetonaAI Desktop
|
||
```
|
||
|
||
### 应用配置（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 上下文窗口 |
|
||
|
||
### SearXNG 配置（可选）
|
||
|
||
启用 SearXNG 元搜索引擎替代内置四引擎搜索，支持 12 项配置（URL、引擎列表、认证方式等），详见设置界面。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
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 许可证
|
||
```
|
||
|
||
---
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
# 开发
|
||
npm run dev # 启动开发模式
|
||
npm run typecheck # 全量类型检查
|
||
npm run typecheck:node # Node 端类型检查
|
||
npm run lint # ESLint 检查
|
||
npm run lint:fix # ESLint 自动修复
|
||
npm run format # Prettier 格式化
|
||
|
||
# 测试
|
||
npm test # 运行单元测试 (Vitest)
|
||
npm run test:watch # 测试监听模式
|
||
npm run test:e2e # E2E 测试 (Playwright)
|
||
|
||
# 构建
|
||
npm run build # 构建生产包
|
||
npm run build:renderer # 仅构建渲染进程
|
||
npm run build:electron # 仅构建主进程
|
||
npm run preview # 预览构建产物
|
||
```
|
||
|
||
### 数据库 Schema（9 张表）
|
||
|
||
| 表名 | 用途 |
|
||
|------|------|
|
||
| sessions | 会话管理 |
|
||
| messages | 消息持久化 |
|
||
| app_config | 应用配置（键值对） |
|
||
| audit_logs | 审计日志（链式哈希防篡改） |
|
||
| mcp_servers | MCP Server 配置 |
|
||
| episodic_memories | 情节记忆 |
|
||
| semantic_memories | 语义记忆 |
|
||
| working_memories | 工作记忆 |
|
||
| tasks | 持久化任务 |
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
[MIT](./LICENSE)
|