# MetonaAI-Desktop 架构与交互设计

基于「生产级通用 AI Agent 桌面应用构建指南」+「Metona 内部 IR 标准」，定义完整的系统架构、27 个内置工具、4 个用户级磁盘文件、工作空间机制、数据库配置规范及全链路可追踪日志体系。

版本: v1.1.0 技术栈: React + Material UI (MUI) + Electron + SQLite 日期: 2026-07-15
📋 文档层级：本文档是 工作空间、27 个内置工具、4 个磁盘文件、数据库配置的权威定义，与《构建指南》第三、五、六章对应。冲突时以本文档为准。

## 📋 设计总览

MetonaAI-Desktop 是一个运行在用户本地桌面上的通用 AI Agent 应用。它以工作空间（Workspace）为基本组织单元， 通过 4 个 Markdown 磁盘文件 定义 Agent 的灵魂、行为、记忆和用户画像， 提供 27 个内置工具 赋予 Agent 操作文件系统、网络、记忆和命令行的能力。 全链路操作透明可追踪，所有决策过程、工具调用、LLM 推理记录在本地 SQLite 日志中。

    ┌──────────────────────────────────────────────────────────┐
    │                   MetonaAI-Desktop                        │
    │                                                          │
    │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
    │  │ SOUL.md  │  │ AGENTS.md│  │ MEMORY.md│  │ USERS.md│ │  ← 用户磁盘文件
    │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
    │       │             │             │             │       │
    │  ┌────▼─────────────▼─────────────▼─────────────▼────┐  │
    │  │              Agent Engine (ReAct Loop)             │  │
    │  │    INIT → THINKING → PARSING → EXECUTING → OBSERVING → REFLECTING → COMPRESSING → TERMINATED  │  │
    │  └────┬──────────────────────────────────────────────┘  │
    │       │                                                 │
    │  ┌────▼──────────────────────────────────────────────┐  │
    │  │         27 Base Tools (统一 IR)                     │  │
    │  │  filesystem(5) | editor | code_search | diff       │  │
    │  │  web_search | web_fetch | web_browser | http       │  │
    │  │  memory(2) | run_command | delegate_task          │  │
    │  │  git(4) | dev_tools(3) | task_mgr | todo | think   │  │
    │  └────┬──────────────────────────────────────────────┘  │
    │       │                                                 │
    │  ┌────▼──────────────────────────────────────────────┐  │
    │  │  Trace & Audit Logger (全链路 SQLite)               │  │
    │  └───────────────────────────────────────────────────┘  │
    └──────────────────────────────────────────────────────────┘

## 🏗️ 系统架构

### 进程架构

进程 | 运行时 | 职责
--- | --- | ---
Main Process | Node.js | Agent 引擎、工具调度、数据库、MCP 管理、配置加载
Preload Script | 沙箱 Node | 通过 contextBridge 安全暴露 API 给渲染进程
Renderer | Chromium | React + Material UI (MUI) 界面：聊天、Agent 监控、设置面板、Trace Viewer。所有 UI 组件强制使用 MUI，禁止自写。

### 四层 Harness 架构

层级 | 名称 | 核心模块 | 使用的 IR 类型
--- | --- | --- | ---
L1 | 推理与编排层 | ReAct Loop 状态机、Plan Mode 执行器、SubAgent 编排器 | MetonaRequest / MetonaResponse / MetonaStreamEvent
L2 | 上下文与记忆层 | Context Builder、MemorySystem（SQLite） | MetonaContext / MetonaMemoryItem
L3 | 工具与安全执行层 | Tool Registry、Sandbox Manager、Policy Engine、MCP Adapter | MetonaToolDef / MetonaToolCall / MetonaToolResult
L4 | 支撑与基础架构层 | Config Manager、Logging System、OTel Tracing、Error Boundary | MetonaError / 内置类型

## 📁 工作空间（Workspace）

工作空间是 Metona 的组织核心。每个工作空间是一个本地磁盘目录，包含该上下文的全部文件。 Agent 启动时加载工作空间下的配置/状态文件，所有工具操作默认限制在工作空间内。

### 默认工作空间

📍 默认路径：`~/MetonaWorkspaces/default/`
首次启动时自动创建。用户可在设置界面修改默认路径或为不同项目创建独立工作空间。

### 自定义工作空间

用户可通过以下方式选择自定义工作空间目录：

- 启动时选择：应用启动界面的"选择工作空间"按钮
- 菜单切换：菜单栏 → 文件 → 打开/创建工作空间
- 拖拽导入：将文件夹拖入应用窗口
- 命令行参数：`metona --workspace /path/to/dir`

### 工作空间目录结构

    # ~/MetonaWorkspaces/my-project/
    ├── SOUL.md          # [必需] AI 灵魂定义 — 角色、性格、核心价值观（用户自定义）
    ├── AGENTS.md        # [必需] AI 行为定义 — 规则、边界、工作流（用户自定义）
    ├── MEMORY.md        # [必需] AI 持久记忆 — 跨会话保留的知识（Agent 维护 + 用户编辑）
    ├── USERS.md         # [必需] 用户画像 — 背景、技能、偏好（用户自定义）
    ├── logs/              # [自动创建] 会话日志（每次对话一个 .jsonl）
    ├── traces/            # [自动创建] 执行追踪（每次 ReAct 迭代一条 trace）
    ├── .metona/           # [自动创建] Metona 内部目录
    │   └── agent.db       # SQLite 数据库（配置、记忆、审计日志、会话记录）
    └── src/               # [可选] 用户项目文件（Agent 可读写）

### 必需文件说明

文件 | 状态 | 缺失时处理 | 说明
--- | --- | --- | ---
SOUL.md | 必需 | 自动创建空文件，Agent 以通用模式运行 | 定义 Agent 身份和价值观
AGENTS.md | 必需 | 自动创建空文件，使用内置最小安全规则 | 定义 Agent 行为规则
MEMORY.md | 必需 | 自动创建带元数据头的规范文件 | 跨会话记忆（有严格格式要求）
USERS.md | 必需 | 自动创建空文件，Agent 以通用模式运行 | 用户画像信息

✅ 自动创建策略：打开工作空间时，Metona 会校验 4 个必需文件是否存在。
任何文件缺失都会自动创建，不会阻止启动。创建后提示用户编辑自定义内容。
`MEMORY.md` 创建时会自动包含符合格式规范的元数据头。

### 工作空间生命周期

1 用户选择/创建工作空间目录（或使用默认路径 `~/MetonaWorkspaces/default/`）
2 校验必需文件，缺失则自动创建（`MEMORY.md` 带元数据头）
3 加载 4 个磁盘文件，构建 System Prompt（空文件不影响启动）
4 连接 `.metona/agent.db`，加载配置、恢复历史会话
5 Agent 就绪，开始对话。所有工具操作默认以工作空间为根
6 会话结束后，`MEMORY.md`（更新时间戳）和 `.metona/agent.db` 自动更新

## 💾 数据库配置：.metona/agent.db

所有运行时配置存储在工作空间的 SQLite 数据库中（`.metona/agent.db`），而非外部配置文件。 这确保了配置与工作空间的强绑定，支持事务性更新和版本迁移。

💡 设计决策：采用数据库存储配置而非 YAML/JSON 文件，原因：
1. 配置与工作空间数据原子性一致
2. 支持并发访问和事务保护
3. 统一备份和迁移策略
4. 避免文件格式解析错误

### 配置表结构

    -- .metona/agent.db > app_config
    CREATE TABLE app_config (
        key         TEXT PRIMARY KEY,
        value       TEXT NOT NULL,        -- JSON 格式值
        category    TEXT NOT NULL,        -- llm | agent | tools | security | logging | mcp
        updated_at  TEXT DEFAULT (datetime('now'))
    );

    -- 配置分类索引
    CREATE INDEX idx_config_category ON app_config(category);

### 配置项一览

分类 | 键 | 类型 | 默认值 | 说明
--- | --- | --- | --- | ---
llm | provider | string | "deepseek" | LLM 提供商
model | string | "deepseek-v4-pro" | 模型名称
apiKey | string | "" | API 密钥（加密存储）
baseURL | string | "" | API 基础 URL
params | JSON | {temperature:0, maxTokens:8192} | 生成参数
fallbackProvider | string | "" | 备选 LLM 提供商（故障转移）
fallbackModel | string | "" | 备选模型名称
agent | maxIterations | number | 20 | 最大迭代次数
totalTimeoutMs | number | 600000 | 总超时（毫秒）
enableThinking | boolean | true | 启用思考模式
thinkingEffort | string | "high" | 思考强度: low/medium/high/max
tools | filesystem.enabled | boolean | true | 文件系统工具开关
web.enabled | boolean | true | 网络工具开关
command.enabled | boolean | true | 命令工具开关
security | requireWriteConfirmation | boolean | true | 写操作需确认
maxFileWriteSizeKB | number | 1024 | 最大写入文件大小
promptInjectionDefense | boolean | true | 注入防护开关
logging | level | string | "info" | 日志级别
auditEnabled | boolean | true | 审计日志开关
traceEnabled | boolean | true | 追踪日志开关

### MCP Server 配置表

    -- .metona/agent.db > mcp_servers
    CREATE TABLE mcp_servers (
        id          TEXT PRIMARY KEY,
        name        TEXT NOT NULL UNIQUE,
        transport   TEXT CHECK(transport IN ('stdio', 'sse')),
        command     TEXT,                    -- stdio 模式的命令
        args        TEXT,                    -- JSON 数组格式的参数
        url         TEXT,                    -- SSE 模式的 URL
        enabled     BOOLEAN DEFAULT TRUE,
        created_at  TEXT DEFAULT (datetime('now')),
        updated_at  TEXT DEFAULT (datetime('now'))
    );

🔧 配置管理：用户通过设置界面修改配置，变更即时生效并持久化到数据库。 首次创建工作空间时，系统自动插入所有配置项的默认值。

## 📊 27 个内置工具 — 总表

所有工具使用 Metona IR 的 MetonaToolDef / MetonaToolCall / MetonaToolResult 结构。内置在 Tool Registry 中，Adaper 为 LLM 生成 JSON Schema 格式的描述。

# | 工具名 | 分类 | 风险 | 需确认 | 核心功能
--- | --- | --- | --- | --- | ---
1 | read_file | filesystem | SAFE | 否 | 读取文件内容，支持分页
2 | write_file | filesystem | MEDIUM | 是(可配) | 写入/覆盖/追加文件内容
3 | list_directory | filesystem | SAFE | 否 | 列出目录内容
4 | search_files | filesystem | SAFE | 否 | 按模式搜索文件（名称/内容）
5 | web_search | network | LOW | 否 | 网络搜索，返回结果列表
6 | web_fetch | network | LOW | 否 | 抓取网页内容转 Markdown
7 | memory_store | database | MEDIUM | 否 | 存储一条记忆到 SQLite
8 | memory_search | database | SAFE | 否 | 检索记忆（关键词匹配）
9 | run_command | code_execution | HIGH | 是 | 执行 Shell 命令，沙箱限制
完整 27 个工具列表详见 README.md「内置工具」章节。新增工具涵盖：file_editor、code_search、diff_viewer、web_browser、http_request、git_status/git_diff/git_log/git_commit、lint_code、run_tests、project_info、delegate_task、task_manager、todo_write、think、view_image。

## 📄 类别一：文件系统工具（5个）

### 1. read_file

读取文件完整内容。支持行偏移和行数限制，自动检测二进制文件。文件超过 100K 字符时返回截断提示。

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
file_path | string | 必填 | 文件路径（相对于工作空间）
offset | number | 可选 | 起始行号（1-indexed，默认 1）
limit | number | 可选 | 最大行数（默认 500，最大 2000）

💡 返回格式：`{ content, total_lines, truncated, file_size }`。truncated=true 时须提示用户指定 offset 继续读取。

### 2. write_file

写入内容到文件。默认覆盖模式，支持追加。写操作前校验路径白名单，默认需用户确认。

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
file_path | string | 必填 | 目标文件路径
content | string | 必填 | 写入内容
mode | string | 可选 | "overwrite"（默认）/ "append"

### 3. list_directory

列出目录内容，支持递归深度控制和 glob 过滤。

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
dir_path | string | 可选 | 目录路径（默认工作空间根）
depth | number | 可选 | 递归深度（默认 1，最大 5）
glob | string | 可选 | 文件名过滤 (如 "*.ts")

### 4. search_files

在目录中按正则/glob 搜索文件内容或文件名。底层使用 ripgrep。

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
pattern | string | 必填 | 搜索正则或 glob 模式
target | string | 可选 | "content"（默认）/ "files"
path | string | 可选 | 搜索目录（默认工作空间根）
file_glob | string | 可选 | 限定文件名（如 "*.py"）
limit | number | 可选 | 最大结果数（默认 50）

## 🌐 类别二：网络搜索与抓取（2个）（另有 18 个工具见 README.md）

### 5. web_search

执行网络搜索，返回标题、摘要和 URL。支持搜索运算符（site:、filetype: 等）。

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
query | string | 必填 | 搜索关键词（支持 site:domain filetype:pdf 等）
limit | number | 可选 | 结果数（默认 5，最大 100）

### 6. web_fetch

抓取网页内容，三阶段回退（HTTP + 反爬 + 浏览器渲染），10MB 限制

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
urls | string[] | 必填 | 待抓取的 URL 列表（最多 5 个）

## 🧠 类别三：记忆工具（2个）（另有 18 个工具见 README.md）

### 7. memory_store

将一条内容存入持久记忆。写入 SQLite，支持关键词检索。Agent 可在对话中保存重要信息。

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
content | string | 必填 | 记忆内容
type | string | 必填 | "episodic"（情节）/ "semantic"（语义）/ "working"（工作）
importance | number | 可选 | 重要程度 0-1（默认 0.5）
source | string | 可选 | 来源标识（默认 "agent"）
tags | string[] | 可选 | 标签列表

### 8. memory_search

检索记忆库：关键词精确匹配，返回相关性排序结果。

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
query | string | 必填 | 搜索关键词或语义查询
type | string | 可选 | 过滤记忆类型
topK | number | 可选 | 返回结果数（默认 5）
threshold | number | 可选 | 相似度阈值（默认 0.7）

## ⚒️ 类别四：命令工具（1个）（另有 18 个工具见 README.md）

### 9. run_command

在沙箱环境中执行 Shell 命令。命令在工作空间目录下运行，有超时限制和输出截断。高危命令需用户确认。

参数 | 类型 | 必填 | 说明
--- | --- | --- | ---
command | string | 必填 | Shell 命令
workdir | string | 可选 | 执行目录（默认工作空间根）
timeout | number | 可选 | 超时毫秒（默认 120000）

⚠ 安全规则（命令解析 + 模式匹配）：使用 `shell-quote` 库解析命令为 token 数组，再对每个 token 做模式匹配。不使用简单字符串匹配（易被绕过）。
硬阻止列表（绝对禁止执行）：

- `rm` + 包含 `/` 的路径参数（阻止删除根/系统目录）
- `sudo` / `su` / `doas`（提权命令）
- `shutdown` / `reboot` / `halt` / `poweroff`
- `curl ... | sh` / `curl ... | bash` / `wget ... | sh`（远程执行）
- `dd` + `of=/dev/`（写设备文件）
- `mkfs` / `fdisk`（格式化磁盘）
- `chmod 777` / `chown` 到非当前用户

需确认列表（用户显式确认后执行）：

- `eval` / `exec`（动态执行）
- 修改系统配置文件的命令
- 安装/卸载软件的命令（`apt` / `brew` / `npm install -g`）
- 网络请求类命令（`curl` / `wget` 不含管道）

🔧 实现要求：在 `SandboxManager` 中实现 `validateCommand(command: string): {allowed: boolean; reason?: string}` 方法。使用 `shell-quote`（npm 包）解析命令，检查每个 token。安全规则配置存储在 `app_config` 表中（`security.commandBlocklist` / `security.commandConfirmList`），用户可在设置界面自定义。

## 💾 4 个用户级磁盘文件

4 个 `.md` 文件位于工作空间根目录，是工作空间的必需文件。 其中 `SOUL.md`、`AGENTS.md`、`USERS.md` 完全由用户自定义，`MEMORY.md` 由 Agent 维护但用户可编辑。

文件 | 必需 | 注入阶段 | 作用 | 内容来源 | 缺失时处理
--- | --- | --- | --- | --- | ---
SOUL.md | 是 | 静态区（优先） | 定义 Agent 身份、性格、核心价值观 | 用户自定义 | 自动创建空文件
AGENTS.md | 是 | 静态区 | 定义行为规则、边界、工作流 | 用户自定义 | 自动创建空文件
MEMORY.md | 是 | 动态区 | 跨会话持久记忆 | Agent 维护 + 用户可编辑 | 自动创建带元数据头的规范文件
USERS.md | 是 | 静态区 | 用户画像：背景、技能、偏好 | 用户自定义 | 自动创建空文件

✅ 自动创建策略：所有必需文件缺失时都会自动创建，不会阻止启动。
• `SOUL.md`、`AGENTS.md`、`USERS.md`：创建空文件，提示用户编辑
• `MEMORY.md`：创建带完整元数据头的规范文件（格式版本、创建时间、工作空间路径）

## ✨ SOUL.md — AI 灵魂定义

定义 Agent 的身份、性格和核心价值观。加载后注入 System Prompt 的最高优先级静态区。此文件完全由用户自定义，Metona 不提供默认内容。

#### ✨ SOUL.md

~/MetonaWorkspaces/my-project/SOUL.md

用户自定义文件，定义 Agent 的灵魂

📝 用户自定义：SOUL.md 的内容完全由用户决定。Metona 不会预设任何角色、性格或价值观。
用户可以定义任何类型的 Agent：编程助手、写作伙伴、学习导师、虚拟角色等。

#### 推荐结构（仅供参考）

    # SOUL.md — 用户自定义 Agent 灵魂

    ## 身份
    # 定义 Agent 是谁：名称、角色、核心特征

    ## 性格与语气
    # 定义 Agent 如何与用户交流：风格、语气、态度

    ## 核心价值观
    # 定义 Agent 的行为准则和底线

#### SOUL.md 作用域

对象 | 影响
--- | ---
LLM 推理 | 全部轮次注入，决定回复语气、风格和价值观
工具调用 | 影响安全决策和行为边界
记忆存储 | 影响哪些信息被认为值得记忆
错误处理 | 决定错误回复的风格和态度

## 📋 AGENTS.md — AI 行为定义

定义 Agent 的行为规则、边界、工作流程和工具使用权限。此文件完全由用户自定义，Metona 仅提供内置最小安全规则作为兜底。

#### 📋 AGENTS.md

~/MetonaWorkspaces/my-project/AGENTS.md

用户自定义文件，定义 Agent 行为边界

📝 用户自定义：AGENTS.md 的内容完全由用户决定。Metona 不预设行为规则。
用户可以定义任意复杂度的规则体系，从简单的行为准则到详细的多层规则架构。

#### 推荐结构（仅供参考）

    # AGENTS.md — 用户自定义行为规则

    ## 行为准则
    # 定义 Agent 必须遵守的规则

    ## 工具使用规范
    # 定义哪些工具可用、何时需要确认

    ## 安全边界
    # 定义 Agent 的行为底线

    ## 工作流程
    # 定义 Agent 的推理和执行流程

#### 内置最小安全规则（兜底）

🛡 无论 AGENTS.md 如何定义，以下规则始终生效：

- 不执行明确违法的操作
- 不泄露用户隐私数据
- 不可逆操作前必须确认
- 工具调用失败必须如实报告

#### AGENTS.md 作用域

对象 | 影响
--- | ---
Agent 决策 | 所有行为受用户定义的规则约束
工具权限 | 定义哪些工具可用、需要确认、被禁用
输出验证 | 根据用户规则验证输出合规性
工作流 | 引导 Agent 的推理和执行流程

## 🧩 MEMORY.md — AI 记忆文件

跨会话持久记忆。Agent 启动时读取注入上下文，会话结束后自动追加新记忆。此文件有严格的格式规范，Agent 写入时必须遵循，用户编辑时也应遵守。

#### 🧩 MEMORY.md

~/MetonaWorkspaces/my-project/MEMORY.md

Agent 维护 + 用户可编辑的记忆文件

#### 格式规范

📋 强制格式：MEMORY.md 必须遵循以下结构，否则 Agent 写入时会自动修正格式。

#### 创建时的初始模板（自动填充）

当 MEMORY.md 不存在时，Agent 自动创建以下带元数据头的规范文件：

    # MEMORY.md — AI 持久记忆
    #
    # 格式版本: 1.0
    # 创建时间: 2026-06-25T12:00:00Z
    # 最后更新: 2026-06-25T12:00:00Z
    # 工作空间: /home/user/MetonaWorkspaces/my-project
    #
    # 此文件由 Metona Agent 自动维护，用户可手动编辑。
    # 格式规范详见文档，Agent 写入时会自动校验格式。

    ## 用户偏好
    # 格式: - [类别] 内容描述
    # 示例: - [沟通风格] 用户喜欢简洁的回答

    ## 项目上下文
    # 格式: - [项目名] 关键信息
    # 示例: - [MyApp] 技术栈: React + TypeScript

    ## 重要决策
    # 格式: - YYYY-MM-DD: 决策内容
    # 示例: - 2026-06-25: 选择 sql.js 作为数据库方案

    ## 待办事项
    # 格式: - [状态] 任务描述 (状态: pending/done/cancelled)
    # 示例: - [pending] 实现用户登录功能

    ## 已知问题
    # 格式: - 问题描述 | 影响范围 | 解决方案
    # 示例: - 首次加载慢 | 启动 | 预加载优化

#### 完整示例（有内容时）

    # MEMORY.md — AI 持久记忆
    #
    # 格式版本: 1.0
    # 创建时间: 2026-06-25T12:00:00Z
    # 最后更新: 2026-06-25T15:30:00Z
    # 工作空间: /home/user/MetonaWorkspaces/my-project

    ## 用户偏好
    - [沟通风格] 用户喜欢简洁的回答，不需要过度解释
    - [代码风格] 代码块使用 TypeScript 语法高亮
    - [工具偏好] 项目使用 pnpm 而非 npm

    ## 项目上下文
    - [MetonaAI-Desktop] 技术栈: React 18 + Electron 28 + TypeScript 5.x
    - [MetonaAI-Desktop] 构建工具: Vite + electron-builder

    ## 重要决策
    - 2026-06-20: 选择 sql.js 作为 SQLite 实现
    - 2026-06-22: 决定采用四层 Harness 架构

    ## 待办事项
    - [pending] 实现 MCP Server 动态加载
    - [done] 完成 Agent Loop 状态机

    ## 已知问题
    - Windows 下 electron-builder 签名需要证书 | 部署 | 使用代码签名证书

#### 格式校验规则

规则 | 说明 | 违反处理
--- | --- | ---
元数据头 | 必须包含 `# 格式版本`、`# 创建时间`、`# 最后更新`、`# 工作空间` | 自动补充缺失的元数据
分区结构 | 必须包含 `## 用户偏好`、`## 项目上下文`、`## 重要决策` 三个分区 | 自动创建缺失分区
条目前缀 | 每个条目必须以 `-` 开头，后跟 `[类别/标签]` | 自动添加默认标签
日期格式 | 决策条目必须使用 `YYYY-MM-DD` 格式 | 自动格式化为 ISO 日期
状态标记 | 待办事项必须包含 `[pending/done/cancelled]` 状态 | 默认标记为 `[pending]`
时间戳更新 | 每次写入时自动更新 `# 最后更新` 时间戳 | 自动更新

#### MEMORY.md 生命周期

1 首次创建：文件不存在时自动创建，包含完整元数据头（格式版本、创建时间、工作空间路径）
2 启动读取：Agent 初始化时解析 MEMORY.md，校验格式，注入 System Prompt 动态区
3 会话中使用：Agent 可通过 `memory_search` 检索 MEMORY.md 内容
4 会话结束后：Agent 自动分析本次会话，按格式规范追加新记忆条目，更新时间戳
5 格式校验：每次写入前校验格式，不合规内容自动修正
6 用户编辑：用户可随时编辑，Agent 下次启动时重新校验格式
💡 格式保护：Agent 写入 MEMORY.md 时会严格遵循格式规范。 如果用户手动编辑导致格式不合规，Agent 会在下次启动时提示并尝试自动修正，不会丢失已有内容。

#### MEMORY.md 与 SQLite 记忆系统的关系

MEMORY.md 磁盘文件与 SQLite 数据库中的记忆表是互补关系，各有明确职责：

维度 | MEMORY.md（磁盘文件） | SQLite memories（数据库）
--- | --- | ---
定位 | 用户可读可编辑的跨会话记忆摘要 | 结构化记忆存储，支持检索/评分/过期
格式 | Markdown，有严格格式规范 | 结构化表（episodic_memories / semantic_memories / working_memories）
谁写入 | Agent 会话结束后追加 + 用户手动编辑 | Agent 运行时通过 memory_store 工具写入
谁读取 | Agent 启动时解析，注入 System Prompt | Agent 运行时通过 memory_search 检索
检索方式 | 全量注入上下文（不检索） | 关键词/语义检索，按相关性排序

🔄 同步策略：
Agent 启动时：读取 MEMORY.md → 解析 → 注入 System Prompt 动态区（不写入 SQLite）
Agent 运行时：memory_store / memory_search 操作 SQLite（不读写 MEMORY.md）
会话结束后：Agent 从 SQLite 提取本次会话的重要记忆 → 追加到 MEMORY.md（按格式规范）
用户编辑后：下次启动时 Agent 重新解析 MEMORY.md，不回写 SQLite
Source of Truth：MEMORY.md 是用户可见的“记忆摘要”，SQLite 是 Agent 运行时的“记忆工作区”。两者不强制实时同步，通过启动读取 + 会话结束追加实现单向流动。

## 👤 USERS.md — 用户信息画像

定义用户的背景、技能、偏好和当前目标。Agent 据此调整回答深度、技术栈偏向和交互风格。此文件完全由用户自定义。

#### 👤 USERS.md

~/MetonaWorkspaces/my-project/USERS.md

用户自定义文件，描述用户画像

📝 用户自定义：USERS.md 的内容完全由用户决定。Metona 不预设任何用户信息。
用户可以描述自己的背景、技能、偏好、目标等，帮助 Agent 更好地理解和服务用户。

#### 推荐结构（仅供参考）

    # USERS.md — 用户自定义画像

    ## 基本信息
    # 称呼、角色、经验等

    ## 技术栈
    # 熟悉的技术、工具、框架

    ## 偏好
    # 工具偏好、沟通风格、工作习惯

    ## 当前目标
    # 正在做什么、想要达成什么

#### USERS.md 作用域

对象 | 影响
--- | ---
技术回答 | 根据用户技术栈调整回答深度和示例
工具选择 | 根据用户偏好选择工具和命令
安全策略 | 根据用户角色调整权限级别
语气风格 | 匹配用户的沟通习惯和偏好

## 🔍 全链路透明可追踪

用户可在任意时刻完整回溯 Agent 的每一步决策过程。所有数据分为三个可见层级：

### 三层可见性

层级 | 名称 | 存储位置 | 可见内容 | 用户访问方式
--- | --- | --- | --- | ---
L0 | UI 实时展示 | 内存 | Thought 过程、ToolCall 参数/结果、最终答案 | 聊天界面 / TraceViewer 面板
L1 | 会话日志 | logs/session_{id}.jsonl | 每轮 ReAct 迭代的完整状态、LLM 原始输入/输出、工具调用详情 | 直接打开 .jsonl 或内置日志查看器
L2 | 审计数据库 | .metona/agent.db | 结构化审计记录：谁（actor）、做了什么（target）、结果（outcome）、耗时 | SQLite 浏览器 / 内置控制台

### 会话日志格式 (.jsonl)

    # logs/session_s_abc_20260625T120000Z.jsonl
    {"seq":0,"ts":"2026-06-25T12:00:00.000Z","event":"session_start","sessionId":"s_abc","workspace":"/home/user/my-project"}
    {"seq":1,"ts":"2026-06-25T12:00:01.000Z","event":"context_built","sessionId":"s_abc","tokens":1240,"ratio":0.01}
    {"seq":2,"ts":"2026-06-25T12:00:01.500Z","event":"iteration_start","sessionId":"s_abc","iteration":1}
    {"seq":3,"ts":"2026-06-25T12:00:02.100Z","event":"llm_request","sessionId":"s_abc","iteration":1,"provider":"deepseek","model":"deepseek-v4-pro","messages":[...]}
    {"seq":4,"ts":"2026-06-25T12:00:03.800Z","event":"llm_response","sessionId":"s_abc","iteration":1,"content":"Thought: 需要读取文件...","finishReason":"tool_calls","usage":{"inputTokens":1240,"outputTokens":85,"totalTokens":1325}}
    {"seq":5,"ts":"2026-06-25T12:00:03.810Z","event":"tool_call","sessionId":"s_abc","iteration":1,"tool":"read_file","args":{"file_path":"data.csv"}}
    {"seq":6,"ts":"2026-06-25T12:00:03.820Z","event":"tool_result","sessionId":"s_abc","iteration":1,"tool":"read_file","success":true,"durationMs":5,"result":"..."}
    {"seq":7,"ts":"2026-06-25T12:00:04.500Z","event":"iteration_end","sessionId":"s_abc","iteration":1,"durationMs":3000}
    {"seq":8,"ts":"2026-06-25T12:00:10.000Z","event":"session_end","sessionId":"s_abc","totalIterations":3,"totalTokens":5430,"totalDurationMs":10000}

## 📝 日志设计

四层日志体系，覆盖从系统级到业务级的全部可观测需求。

### 日志分层

层级 | 日志类型 | 存储 | 内容
--- | --- | --- | ---
SYS | 系统日志 | electron-log 文件 | 进程启动/退出、崩溃堆栈、内存/CPU 异常、更新事件
AGENT | Agent 引擎日志 | logs/agent.log | 状态转换、迭代计数、超时、压缩触发、错误恢复
TOOL | 工具执行日志 | .metona/agent.db (audit_logs) | 每次工具调用的参数、结果、耗时、权限校验
TRACE | 全链路追踪 | logs/session_*.jsonl | 完整会话记录（见上文），可导出分析

### 数据库审计表结构

    -- .metona/agent.db > audit_logs
    CREATE TABLE audit_logs (
        id          INTEGER PRIMARY KEY AUTOINCREMENT,
        session_id  TEXT NOT NULL,         -- 会话 ID
        iteration   INTEGER,                 -- ReAct 迭代轮次
        event_type  TEXT NOT NULL,         -- tool_call | permission_check | error | llm_request | llm_response
        actor       TEXT NOT NULL,         -- 'agent' | 'user' | 'system'
        target      TEXT NOT NULL,         -- 操作对象 (工具名 / 模块名)
        details     TEXT,                    -- JSON 格式详细信息
        outcome     TEXT,                    -- 'success' | 'denied' | 'error'
        duration_ms INTEGER,                 -- 耗时
        created_at  TEXT DEFAULT (datetime('now'))
    );

### 日志级别

级别 | 含义 | 示例
--- | --- | ---
DEBUG | 开发调试细节 | State transition: THINKING → PARSING
INFO | 正常业务流程 | MCP server 'filesystem' connected with 8 tools
WARN | 非预期但可恢复 | Context compression triggered at iteration 15
ERROR | 需要关注的错误 | Tool 'web_search' failed: network timeout

## 🔄 完整交互流程

从用户启动应用到一次完整对话结束的端到端流程。

### 启动流程

1 Electron Main Process 启动 → 初始化日志系统
2 选择/创建工作空间 → 校验必需文件（缺失则自动创建）
3 连接 SQLite（.metona/agent.db）→ 执行 schema 迁移 → 加载配置
4 初始化 Provider Adapter（根据数据库配置选择）
5 加载 4 个磁盘文件，构建 System Prompt（空文件不影响启动）
6 连接启用的 MCP Servers → 动态加载 MCP 工具
7 启动 React UI（Chromium Renderer），Agent 就绪
8（可选）提示用户编辑 SOUL.md / AGENTS.md / USERS.md 以自定义 Agent

### 对话流程（一次 ReAct 迭代）

1 用户在 ChatInput 输入消息 → IPC `agent:sendMessage` 发送 MetonaRequest
2 Context Builder 组装 MetonaContext：System Prompt + 历史 + 记忆 + 工具列表
3 Provider Adapter 将 MetonaContext → 外部 API 格式 → 发送 LLM 请求
4 流式接收响应 → 转换为 MetonaStreamEvent → 实时推送 UI
5 Parser 解析 LLM 输出 → 提取 Thought / ToolCall 或 FinalAnswer
6（如有 ToolCall）Policy Engine 校验权限 → 执行工具 → 收集 MetonaToolResult
7 Observation 注入上下文 → 写入审计日志 → 进入下一轮迭代或输出最终答案
8 会话结束 → 更新 MEMORY.md + SQLite → 生成 Session Report

### IPC 通道总览

以下为核心 Agent 交互通道。完整 IPC 通道列表（含会话管理、MCP 管理、应用工具等）见《构建指南》第八章 IPC 架构，以构建指南为权威定义。

通道 | 方向 | 数据类型 | 用途
--- | --- | --- | ---
agent:sendMessage | Renderer → Main | MetonaRequest | 发送用户消息
agent:streamEvent | Main → Renderer | MetonaStreamEvent | 流式推送 LLM 输出
agent:stateChange | Main → Renderer | AgentLoopState | 状态机状态变化
agent:abortSession | Renderer → Main | {sessionId} | 用户中断会话
agent:providerSwitched | Main → Renderer | {from, to, reason} | 故障转移通知
db:searchMemories | Renderer → Main | MemorySearchOptions | UI 查询记忆
config:get / config:set | 双向 | {key, value} | 读写配置

💡 完整 IPC 通道分组：构建指南第八章定义了 4 组 IPC 通道：
• Agent 交互（6 个）：上表所列
• 会话管理（6 个）：`sessions:list / create / rename / delete / getMessages / pin`
• MCP 管理（4 个）：`mcp:listServers / addServer / removeServer / toggleServer`
• 应用工具（4 个）：`app:getVersion / getAppDataPath / openExternal / showItemInFolder`
所有 IPC 通道均通过 Preload `contextBridge` 安全暴露，渲染进程无 Node.js 访问权限。

🏗️ MetonaAI-Desktop 架构与交互设计文档

基于: 生产级通用 AI Agent 构建指南 + Metona 内部 IR 标准

版本 v1.1.0 · 2026-07-15