metona-ollama-desktop/README.md

Metona Ollama Desktop

🤖 本地 AI 桌�客户�· Local AI Desktop Client

所�AI 推�在本地完�，数��离开本机�/em>
All AI inference runs locally �data never leaves your machine.

---

🇨🇳 中文

�特�

	功能	说明
🤖	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 �格�导�

🔧 工具清�

� 文件系统�3 个）

工具	功能
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	压缩文件/目录

�命令执行� 个）

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

� �网�索� 个）

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

� �览器控制（9 个）

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

📦 Git� 个，17 个�命令�/strong>

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

🧠 记忆管�� 个）

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

📊 会� / �代�（3 个）

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

� 系统工具� 个）

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

📋 Plan Mode� 个，�Plan 模�激活）

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

��架构

用户消� �扫�工作空间 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 强制终止 + 工作空间路径大�写��感校验

🚀 快速开�

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 安装�

# 环境：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

🛠�常用命令

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

---

🇬🇧 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

� File System (13)

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

âš?Command Execution (1)

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

� Web Search (2)

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

� Browser Control (9)

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

📦 Git (1 tool, 17 subcommands)

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

🧠 Memory Management (1)

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

📊 Sessions / Sub-agent (3)

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

� System Tools (1)

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

📋 Plan Mode (1, only active in Plan Mode)

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

��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

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

# 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

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

---

_{Made with �� by thzxx}