metona-ollama-desktop/README.md

<p align="center">
  <img src="assets/icons/llama.png" alt="Metona Ollama Desktop" width="128">
</p>

<h1 align="center">Metona Ollama Desktop</h1>

<p align="center">
  <strong>🤖 本地 AI 桌�客户�· Local AI Desktop Client</strong>
</p>

<p align="center">
  <a href="#-中文"><img src="https://img.shields.io/badge/🇨🇳-中文-E8734A?style=flat-square" alt="中文"></a>
  <a href="#-english"><img src="https://img.shields.io/badge/🇬🇧-English-47848F?style=flat-square" alt="English"></a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-v0.16.18-E8734A?style=flat-square" alt="version">
  <img src="https://img.shields.io/badge/electron-33+-47848F?style=flat-square&logo=electron" alt="electron">
  <img src="https://img.shields.io/badge/typescript-5.7+-3178C6?style=flat-square&logo=typescript" alt="typescript">
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license">
  <img src="https://img.shields.io/badge/platform-Windows%20x64-blue?style=flat-square" alt="platform">
</p>

<p align="center">
  <em>所�AI 推�在本地完�，数��离开本机�/em><br>
  <em>All AI inference runs locally �data never leaves your machine.</em>
</p>

---

# 🇨🇳 中文

## �特�

| | 功能 | 说明 |
|:---:|:---|:---|
| 🤖 | **ReAct Agent Loop** | 始终开�的唯一对�模�� 状�机（INIT→THINKING→PARSING→EXECUTING→OBSERVING→REFLECTING→COMPRESSING→TERMINATED），最�85 轮（��置），智能�试（永久错误立�返回�瞬�错误指数退�），工具去�，智能路径�赖串行化，看门狗超时��|
| 🛡�| **�示�加�* | �考数�标记（<<<REFERENCE_DATA_START>>>� 工具结果仅为数��指令的安全规则注入 |
| 📋 | **Plan Mode** | 开关切�，AI 首先生�执行计划（Markdown 渲染确认弹窗），批准�按步骤追踪执行，plan_track 工具标记完�状�，**支�断点续传**（中止����未完�计划�|
| 🔧 | **32 个内置工�* | 文件系统�3个） · 命令执行 · �网�索 · �览器控制（9个） · Git · 记忆 · 会� · �代�· 系统工具 · Plan Mode 追踪 |
| 🧠 | **智能记忆系统** | 三类记忆（fact / preference / rule），存储于工作空�MEMORY.md 文件，�路径�护�memory 工具�访问，写入�安全扫�，容� 500 �，对�结�自动��，严格格�校�|
| 📋 | **自定义文�* | SOUL.md（人格，��压缩� AGENT.md（行为准则，内置 fallback� USER.md（用户画�，仅工作空间读�，�存在则�注入） |
| � | **MCP �议扩展** | JSON-RPC 2.0 over stdio，动�工具�现，Shadowing 防护 |
| � | **�网�索（�模��* | SearXNG 元�索引�JSON API�0+引擎��� 四引�HTML 解�（Bing+百度+�狗+360），�模��切�；web_fetch 支��爬+UA切�+�览器回退 |
| � | **�览器控�* | 打开网页 · 截图 · 执行 JS · ��内容 · 点击 · 输入 · 滚动 · 关闭 |
| 🖥�| **工作空间��** | 终端（增���输出）+ 文件�览器，命令安全检�|
| 🔢 | **上下文长度手动控�* | 设置��下拉选择�28K / 256K / 512K / 1M），默认 128K，模型�显示当��置值，下拉框中显示�个模型自身的上下文长度 |
| 🗜�| **智能上下文管�* | 滑动窗� + Token 自动校准 + 消���性评�+ LLM 结构�JSON 压缩，智能触�（120 �增�压�+ 300 �硬上��|
| �� | **智能超时�护** | Agent Loop 看门狗（��，默�30min� ��总超时（��，默�300s� 工具 HTTP/MCP 超时�� |
| � | **Hook 系统** | 4 阶段生命周期钩�（pre_tool / post_tool / post_iteration / pre_completion），内置安全检查�文件去��自动计划追踪��更审计�结果校�|
| 👥 | **�代�委�* | spawn_task 工具，独立上下文 + 超时�护 |
| 📈 | **Token 仪表�* | 全局 + 会�统计，消耗趋势柱状图� 秒刷新，输入/输出分色 |
| 📋 | **系统�示���* | �� AI 回�顶部折��片，点击查看实际��给模型的完整上下文 |
| 🎨 | **暖色�UI** | 奶白 `#FAF7F2` + �瑚�`#E8734A`，长时间使用�疲劳，��渲染优化 |
| 🔔 | **系统托盘** | 原生托盘集� |
| � | **AES-256-GCM** | 数�加密支� |
| 🧪 | **�观测�* | 执行轨迹缓冲批�写入 SQLite + Agent Metrics JSON/Prometheus �格�导�|

## 🔧 工具清�

<details>
<summary><strong>� 文件系统�3 个）</strong></summary>

| 工具 | 功能 |
|------|------|
| `read_file` | 读�文件（文�binary�000行默认） |
| `write_file` | 写入/追加文件（支�base64二进制） |
| `list_directory` | 列出目录内容 |
| `search_files` | �索文件（正�通�符） |
| `create_directory` | 创建目录 |
| `delete_file` | 删除文件/目录（返回大�） |
| `move_file` | 移动/�命�文�|
| `copy_file` | �制文件 |
| `edit_file` | 编辑文件（支�正则替�） |
| `tree` | 目录树结构（默认5层深度） |
| `download_file` | 下载文件 |
| `read_multiple_files` | 批�读��0文件/10KB�|
| `compress` | 压缩文件/目录 |

</details>

<details>
<summary><strong>�命令执行� 个）</strong></summary>

| 工具 | 功能 |
|------|------|
| `run_command` | 执行 shell 命令，实时��输出，支�自动/需确认/�用三�模� |

</details>

<details>
<summary><strong>� �网�索� 个）</strong></summary>

| 工具 | 功能 |
|------|------|
| `web_search` | SearXNG JSON API / 四引擎并行，默认 30 �结�|
| `web_fetch` | 网页内容抓�，自动�试（指数退�），移动端UA切�，SPA页�自动�级到�览器渲染 |

</details>

<details>
<summary><strong>� �览器控制（9 个）</strong></summary>

| 工具 | 功能 |
|------|------|
| `browser_open` | 打开网页 |
| `browser_screenshot` | 页�截图 |
| `browser_evaluate` | 执行 JavaScript |
| `browser_extract` | ��页�内容 |
| `browser_click` | 点击元素 |
| `browser_type` | 输入文本 |
| `browser_scroll` | 页�滚动 |
| `browser_wait` | 等待元素/延时 |
| `browser_close` | 关闭�览�|

</details>

<details>
<summary><strong>📦 Git� 个，17 个�命令�/strong></summary>

| �命�| 功能 |
|--------|------|
| `init` `clone` `add` `commit` `push` `pull` | 基础�作 |
| `diff` `log` `status` `branch` `checkout` | 查看与切�|
| `merge` `stash` `reset` `tag` `remote` | 高级�作 |

</details>

<details>
<summary><strong>🧠 记忆管�� 个）</strong></summary>

| 工具 | 功能 |
|------|------|
| `memory` | 统一记忆管�� �action：search �索 / add 添加 / replace 替� / remove 删除 / read_all 读�全部）。工作空�MEMORY.md �路径�护，仅此工具�访�|

</details>

<details>
<summary><strong>📊 会� / �代�（3 个）</strong></summary>

| 工具 | 功能 |
|------|------|
| `session_list` | 列出历�会� |
| `session_read` | 读�会�内容 |
| `spawn_task` | 委派�代�（独立上下�+ 超时�护�|

</details>

<details>
<summary><strong>� 系统工具� 个）</strong></summary>

| 工具 | 功能 |
|------|------|
| `calculator` | 安全数学计算� - * / ** % ()，递归下�解�器） |

</details>

<details>
<summary><strong>📋 Plan Mode� 个，�Plan 模�激活）</strong></summary>

| 工具 | 功能 |
|------|------|
| `plan_track` | Plan 模�执行进度追踪，标记步骤完�，自动统计剩余 |

</details>

## ��架构

```
用户消� �扫�工作空间 SOUL.md（��压缩层）→ AGENT.md �USER.md（工作空间，�存在则跳过�
              �
         记忆检�(MEMORY.md 关键��� �上下文注�
              �
         Agent Engine (8 状�机 ReAct Loop, �5 � 智能�试, 路径�赖串行� 看门�分级超时)
              �
         �示�加固（�考数�标�+ 工具结果安全规则�
              �
         Ollama API (���应，num_ctx 用户�� 128K/256K/512K/1M)
              �
         Tool Registry (32 内置 + MCP 动�+ Plan Mode plan_track)
              �
         Hook 系统 (pre/post tool/iteration/completion) �观察结果 ����循环 / 最终回�
```

### 🧩 UI 组件（原�DOM�

```
main.ts (入�)
  ├── header.ts              # 顶部导航�
  ├── model-bar.ts           # 模型选择�
  ├── chat-area.ts           # �天消�区域
  ├── input-area.ts          # 输入�+ 文件上传 + Plan Mode 开�
  ├── workspace-panel.ts     # 终端 + 文件�览�+ 工具�片
  ├── settings-modal.ts      # 设置��（�看门狗超时�置）
  ├── history-modal.ts       # 会�历�
  ├── memory-modal.ts        # 记忆管�
  ├── tools-modal.ts         # 工具列表
  ├── token-dashboard.ts     # Token 消耗仪表盘
  ├── tool-confirm-modal.ts  # 工具执行确认
  ├── prompt-modal.ts        # 系统�示�查�+ Plan 确认弹窗
  ├── toast.ts               # Toast 通知
  └── lightbox.ts            # 图片�箱
```

### 🗄�数��

SQLite (sql.js WASM)� 张表，WAL 模��

| �| 用�|
|---|---|
| `sessions` | 会�（parent_id 父�关系�|
| `messages` | 消�（外键级�删除） |
| `tool_calls` | 工具调用记录 |
| `settings` | 设置（JSON �列化） |
| `traces` | ReAct 执行轨迹 |

## 🔒 安全机制

| 层级 | 措施 |
|------|------|
| � 文件系统 | `checkPathAllowed()` �路径黑��（33 个系��感目录，� Linux + Windows�|
| �命令执行 | `checkCommandAllowed()` �命令黑��（30 ��险命令，�POSIX + Windows� 三�模� |
| 🖥��端渲染 | HTML 净化器（白��标签 + URI �议检查） |
| 🔒 Electron | `contextIsolation: true` + IPC 白��+ IPC fs 路径验� |
| � 数�加密 | AES-256-GCM |
| 🧠 记忆安全 | 写入�Prompt Injection / �感信�检测，多层级去�过�|
| � MCP 安全 | Shadowing 防护 + �下划线分隔防歧�|
| � 网络安全 | `web_fetch` ��体积�制�0MB� �content-length 时防 OOM |
| �进程安全 | Windows `taskkill` 强制终止 + 工作空间路径大�写��感校验 |

## 🚀 快速开�

```bash
git clone https://gitee.com/thzxx/metona-ollama-desktop.git
cd metona-ollama-desktop
npm config set registry https://registry.npmmirror.com
npm install
npm start
```

## 📦 构建 Windows 安装�

```bash
# 环境：Ubuntu 24.04 + Node.js v22 + Wine 9.0+
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist
```

产出：`release/Metona Ollama Setup v0.16.18.exe`

## 🛠�常用命令

```bash
npm start              # 构建并��
npm run dev:renderer   # Vite watch（渲染进程）
npm run dev:main       # tsc watch（主进程�
npm run build          # 完整构建
npm run dist           # 构建 Windows 安装�
```

## 💻 系统�求

- 🖥�Windows 10/11�4 �）
- 🤖 Ollama 本地�行中（默认 `http://localhost:11434`�
- 💾 建议 8GB+ 内存

## 📄 许��

[MIT](LICENSE)

---

# 🇬🇧 English

## �Features

| | Feature | Description |
|:---:|:---|:---|
| 🤖 | **ReAct Agent Loop** | Always-on, only chat mode. 8-state machine, up to 85 iterations (configurable), smart retry (permanent errors return immediately, transient errors use exponential backoff), tool dedup, path-aware dependency serialization, watchdog + tiered timeout protection |
| 🛡�| **Prompt Hardening** | Reference data markers (<<<REFERENCE_DATA_START>>>) + tool results are data-not-instructions safety rules |
| 📋 | **Plan Mode** | Toggle switch. AI first generates an execution plan (Markdown-rendered confirmation dialog), then tracks step-by-step execution, **supports resume** (interrupted plans restore on next session) |
| 🔧 | **32 Built-in Tools** | File system · Command · Web search · Browser · Git · Memory · Sessions · Sub-agent · System · Plan Mode tracking |
| 🧠 | **Smart Memory System** | Three types (fact / preference / rule), stored in workspace MEMORY.md file, path-protected �only the memory tool can access it, pre-write security scan, 500 capacity, auto-extract on conversation end, strict format validation |
| 📋 | **Custom Files** | SOUL.md (persona, never compressed) + AGENT.md (behavior rules, built-in fallback) + USER.md (user profile, workspace only, skipped if absent) |
| � | **MCP Protocol Extension** | JSON-RPC 2.0 over stdio, dynamic tool discovery, Shadowing protection |
| � | **Web Search (dual-mode)** | SearXNG meta-search JSON API (70+ engines) / quad-engine HTML parsing (Bing+Baidu+Sogou+360), switchable; web_fetch with auto-retry+mobile UA+SPA browser fallback |
| � | **Browser Control** | Open pages · Screenshot · JS execution · Content extraction · Click · Type · Scroll · Close |
| 🖥�| **Workspace Panel** | Terminal (incremental streaming) + file browser, command security checks |
| 🔢 | **Manual Context Length** | Settings dropdown (128K / 256K / 512K / 1M), default 128K. Model bar shows configured value, dropdown shows per-model context length |
| 🗜�| **Smart Context Manager** | Sliding window + Token auto-calibration + message importance scoring + LLM structured JSON compression, smart triggers (120 msg incremental + 300 msg hard limit) |
| �� | **Smart Timeout Protection** | Agent Loop watchdog (configurable, default 30min) + stream total timeout (configurable, default 300s) + configurable HTTP/MCP timeouts |
| � | **Hook System** | 4-phase lifecycle hooks (pre_tool / post_tool / post_iteration / pre_completion), built-in security check, file dedup, auto plan tracking, change audit, result validation |
| 👥 | **Sub-agent Delegation** | spawn_task tool, isolated context + timeout protection |
| 📈 | **Token Dashboard** | Global + session stats, consumption trend bar chart, 2s refresh, input/output color-coded |
| 📋 | **System Prompt Card** | Collapsible card atop each AI reply �click to inspect the full context sent to the model |
| 🎨 | **Warm-tone UI** | Cream `#FAF7F2` + coral `#E8734A`, fatigue-free for extended use, streaming render optimized |
| 🔔 | **System Tray** | Native tray integration |
| � | **AES-256-GCM** | Data encryption support |
| 🧪 | **Observability** | Buffered trace persistence to SQLite + Agent Metrics JSON/Prometheus dual-format export |

## 🔧 Tool List

<details>
<summary><strong>� File System (13)</strong></summary>

| Tool | Function |
|------|------|
| `read_file` | Read file (text/binary, 2000 lines default) |
| `write_file` | Write/append file (base64 binary support) |
| `list_directory` | List directory contents |
| `search_files` | Search files (regex/wildcard) |
| `create_directory` | Create directory |
| `delete_file` | Delete file/dir (returns size) |
| `move_file` | Move/rename file |
| `copy_file` | Copy file |
| `edit_file` | Edit file (regex support) |
| `tree` | Directory tree (default 5 levels) |
| `download_file` | Download file |
| `read_multiple_files` | Batch read (50 files/10KB) |
| `compress` | Compress file/directory |

</details>

<details>
<summary><strong>âš?Command Execution (1)</strong></summary>

| Tool | Function |
|------|------|
| `run_command` | Execute shell command, real-time streaming, auto/confirm/disabled modes |

</details>

<details>
<summary><strong>� Web Search (2)</strong></summary>

| Tool | Function |
|------|------|
| `web_search` | SearXNG JSON API / quad-engine parallel, 30 results default |
| `web_fetch` | Fetch web page content, auto-retry with backoff, mobile UA toggle, SPA auto-upgrade to browser rendering |

</details>

<details>
<summary><strong>� Browser Control (9)</strong></summary>

| Tool | Function |
|------|------|
| `browser_open` | Open web page |
| `browser_screenshot` | Page screenshot |
| `browser_evaluate` | Execute JavaScript |
| `browser_extract` | Extract page content |
| `browser_click` | Click element |
| `browser_type` | Type text |
| `browser_scroll` | Scroll page |
| `browser_close` | Close browser |

</details>

<details>
<summary><strong>📦 Git (1 tool, 17 subcommands)</strong></summary>

| Subcommands | Function |
|--------|------|
| `init` `clone` `add` `commit` `push` `pull` | Basic operations |
| `diff` `log` `status` `branch` `checkout` | View & switch |
| `merge` `stash` `reset` `tag` `remote` | Advanced operations |

</details>

<details>
<summary><strong>🧠 Memory Management (1)</strong></summary>

| Tool | Function |
|------|------|
| `memory` | Unified memory management (5 actions: search / add / replace / remove / read_all). Workspace MEMORY.md is path-protected, only this tool can access it |

</details>

<details>
<summary><strong>📊 Sessions / Sub-agent (3)</strong></summary>

| Tool | Function |
|------|------|
| `session_list` | List session history |
| `session_read` | Read session content |
| `spawn_task` | Delegate sub-agent (isolated context + timeout) |

</details>

<details>
<summary><strong>� System Tools (1)</strong></summary>

| Tool | Function |
|------|------|
| `calculator` | Safe math evaluation (+ - * / ** % (), recursive descent parser) |

</details>

<details>
<summary><strong>📋 Plan Mode (1, only active in Plan Mode)</strong></summary>

| Tool | Function |
|------|------|
| `plan_track` | Plan Mode execution progress tracking, mark steps complete, auto tally remaining |

</details>

## ��Architecture

```
User message �workspace SOUL.md (never compressed) �AGENT.md �USER.md (workspace, skipped if absent)
              �
         Memory Retrieval (MEMORY.md keyword search) �Context Injection
              �
         Agent Engine (8-state ReAct Loop, �5 iter, smart retry, path-aware serialization, watchdog+tiered timeout)
              �
         Prompt Hardening (reference data markers + tool result safety rules)
              �
         Ollama API (Streaming Response, num_ctx user-configurable 128K/256K/512K/1M)
              �
         Tool Registry (32 Built-in + MCP Dynamic + Plan Mode plan_track)
              �
         Hook System (pre/post tool/iteration/completion) �Observation �Reflection �Loop / Final Answer
```

### 🧩 UI Components (Native DOM)

```
main.ts (Entry)
  ├── header.ts              # Top navigation bar
  ├── model-bar.ts           # Model selector
  ├── chat-area.ts           # Chat message area
  ├── input-area.ts          # Input box + file upload + Plan Mode toggle
  ├── workspace-panel.ts     # Terminal + file browser + tool cards
  ├── settings-modal.ts      # Settings panel (with watchdog timeout config)
  ├── history-modal.ts       # Session history
  ├── memory-modal.ts        # Memory management
  ├── tools-modal.ts         # Tool list
  ├── token-dashboard.ts     # Token consumption dashboard
  ├── tool-confirm-modal.ts  # Tool execution confirmation
  ├── prompt-modal.ts        # System prompt viewer + Plan confirm dialog
  ├── toast.ts               # Toast notifications
  └── lightbox.ts            # Image lightbox
```

### 🗄�Database

SQLite (sql.js WASM), 5 tables, WAL mode:

| Table | Purpose |
|---|---|
| `sessions` | Sessions (parent_id hierarchy) |
| `messages` | Messages (cascade delete) |
| `tool_calls` | Tool call records |
| `settings` | Settings (JSON serialization) |
| `traces` | ReAct execution traces |

## 🔒 Security

| Layer | Measure |
|------|------|
| � File System | `checkPathAllowed()` �path blacklist (33 system/sensitive dirs, Linux + Windows) |
| �Command Execution | `checkCommandAllowed()` �command blacklist (30 dangerous commands, POSIX + Windows) + three modes |
| 🖥�Frontend Rendering | HTML sanitizer (whitelist tags + URI protocol check) |
| 🔒 Electron | `contextIsolation: true` + IPC whitelist + IPC fs path validation |
| � Data Encryption | AES-256-GCM |
| 🧠 Memory Security | Pre-write prompt injection / sensitive info detection, multi-layer dedup filtering |
| � MCP Security | Shadowing protection + double-underscore delimiter disambiguation |
| � Network Security | `web_fetch` streaming size limit (10MB) + OOM prevention without content-length |
| âš?Process Security | Windows `taskkill` forced termination + case-insensitive workspace path validation |

## 🚀 Quick Start

```bash
git clone https://gitee.com/thzxx/metona-ollama-desktop.git
cd metona-ollama-desktop
npm config set registry https://registry.npmmirror.com
npm install
npm start
```

## 📦 Build Windows Installer

```bash
# Environment: Ubuntu 24.04 + Node.js v22 + Wine 9.0+
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm run dist
```

Output: `release/Metona Ollama Setup v0.16.18.exe`

## 🛠�Common Commands

```bash
npm start              # Build and run
npm run dev:renderer   # Vite watch (renderer)
npm run dev:main       # tsc watch (main process)
npm run build          # Full build
npm run dist           # Build Windows installer
```

## 💻 System Requirements

- 🖥�Windows 10/11 (64-bit)
- 🤖 Ollama running locally (default `http://localhost:11434`)
- 💾 8GB+ RAM recommended

## 📄 License

[MIT](LICENSE)

---

<p align="center">
  <sub>Made with �� by <a href="https://gitee.com/thzxx">thzxx</a></sub>
</p>