# mtl-loop-agent

**Repository Path**: mutongli/mtl-loop-agent

## Basic Information

- **Project Name**: mtl-loop-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MTL Loop Agent

> 基于 **Loop Engineering** 理论的桌面端 AI Agent 系统，让 AI 在本地环境中自主完成代码编写、文件操作、命令执行等任务。

[![Electron](https://img.shields.io/badge/Electron-43-blue)](https://www.electronjs.org/)
[![React](https://img.shields.io/badge/React-19-61dafb)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178c6)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

---

## 项目简介

**MTL Loop Agent** 是一个基于 Electron 的桌面端 AI Agent 系统，核心设计理念源于 **Loop Engineering** 理论。

系统通过「思考 -> 行动 -> 观察 -> 调整」的闭环迭代，让 AI 能够：

- 访问和操作本地文件系统
- 执行 Shell、Python、Node.js 等命令
- 调用和管理可复用的 Skill 技能模块
- 接入多种 LLM 模型（OpenAI、Anthropic、DeepSeek、本地模型等）
- 通过 MCP 协议集成外部工具服务

从而在本地环境中自主完成复杂任务，成为你的**智能开发助手**。

---

## 核心特性

### 本地文件系统访问
- 目录遍历、创建、重命名、删除（支持递归）
- 文件读写（文本/二进制）、复制、移动、重命名、搜索
- 文件内容搜索（支持正则表达式）
- 文件监控（chokidar 实时变更检测）
- 代码编辑器集成（Monaco Editor，支持 80+ 语言语法高亮）
- **多 Tab 编辑**：支持同时打开多个文件，Tab 栏管理（右键菜单、Ctrl+Tab 切换、滚轮滚动）
- **Markdown / HTML 预览**：编辑模式下支持分栏预览和纯预览模式
- 目录大小统计

### 命令行运行环境
- 支持 Shell（cmd/bash/powershell）命令执行（带超时控制）
- **交互式终端**（基于 xterm.js + node-pty，支持终端重设大小）
- 多进程管理（创建、监控、终止、列表查看）
- Python / Node.js 交互式 REPL 支持
- 进程资源使用监控（CPU/内存）
- 环境检测（Python 版本、Node.js 版本）

### Skill 管理系统
- 遵循 **Agent Skills Specification** 开放标准（SKILL.md 定义）
- 三种执行模式：`config`（步骤化模板执行）、`code`（VM 沙箱安全执行）、`mcp`（MCP 协议）
- 多级 Skill 目录扫描（项目级/用户级/工作区级），优先级覆盖机制
- **热更新**（chokidar 文件监听，自动重新加载）
- 启用/禁用、zip 导入导出、增删改查
- **意图匹配**（关键词评分算法，自动匹配用户需求）
- 完整 SKILL.md 解析（触发条件、执行步骤、输出格式、错误处理、示例）

### 模型管理服务
- 支持 **OpenAI**、**Anthropic**、**Custom**（OpenAI 兼容 API）、本地模型
- 模型配置管理（增删改查，多模型列表）
- 运行时模型切换（动态切换当前模型）
- **故障自动切换**（当前模型失败时按优先级尝试其他可用模型）
- API Key **加密存储**（AES-256-CBC 加密）
- Token 消耗统计与调用监控（调用次数、错误次数、延迟等）
- 连接测试、流式调用支持（SSE 实时推送）

### Agent 循环引擎（Loop Engine）
- **反应式循环**：思考 -> 工具调用 -> 观察 -> 决策的闭环迭代
- 完整的任务生命周期管理（运行/暂停/恢复/取消）
- 最大迭代次数和超时控制（可配置）
- 系统提示词动态构建（集成本地工具和 Skill 描述）
- 工具调用自动解析（`` ``` `` 格式）
- 步骤事件回调（实时转发到渲染进程 UI）
- **对话历史记忆压缩**：超过阈值时自动将早期对话压缩为摘要，保留上下文完整性
- 状态变化通知、任务完成/错误/超时系统通知
- Function Calling 集成，模型自主选择调用工具

### MCP 协议支持
- 标准 MCP Server 接入（支持 **stdio** 和 **SSE** 连接类型）
- 工具自动发现与注册（连接后自动列出可用工具）
- 服务器管理（注册、连接、断开、删除）
- 与内置工具统一调度
- 服务器状态监控（connected/disconnected/error）
- 服务器能力信息和版本信息获取

### 安全与权限控制
- **文件访问控制**：黑名单/白名单机制（支持 glob 模式匹配）
- **命令安全校验**：内置危险命令黑名单（rm -rf、format、shutdown 等）
- **自定义命令黑名单**：用户可添加自定义拦截规则
- **审计日志系统**：记录文件操作、命令执行、模型调用等审计信息
- **敏感配置加密**：AES-256-CBC 加密存储 API Key
- 安全管理器统一入口（集成文件访问、命令校验、审计日志）

### 通知服务
- 系统桌面通知（任务完成、错误、警告）
- **系统托盘图标**（最小化到托盘）
- 通知历史记录查看
- 通知窗口显示/隐藏
- 通知配置（启用/禁用各类通知）

### 用户界面
- **三栏可拖拽布局**：左侧文件浏览器（280px）、中间编辑器+终端、右侧对话面板（360px）
- **面板可折叠**：左右侧面板可折叠/展开，带手柄式按钮
- **面板宽度可拖拽**：分隔条拖拽调整面板宽度
- **终端高度可调**：编辑器/终端分隔条可拖拽，终端可最小化
- **状态栏**：显示当前目录、模型状态（在线/离线）、Python/Node.js 版本
- **布局持久化**：面板显隐状态、尺寸自动保存到 localStorage
- **深色主题**：统一的 Tokyo Night 配色方案
- **可配置快捷键**：支持自定义快捷键绑定

### 应用打包
- Windows: NSIS 安装包（可选安装目录、桌面快捷方式）
- macOS: DMG（Intel + Apple Silicon 双架构）
- Linux: AppImage
- ASAR 打包 + 原生模块自动解包（node-pty、sqlite3）
- 内置 Skill 和资源随应用分发（extraResources）

---

## 架构设计

```
+------------------------------------------------------------------+
|                    渲染进程 (React 19 UI)                          |
|  +----------+  +----------+  +----------+  +----------+          |
|  |文件浏览器 |  |代码编辑器 |  | 对话面板  |  | 终端组件  |          |
|  +----------+  +----------+  +----------+  +----------+          |
|  |设置面板   |  |状态栏    |  |模型选择   |  |Skill管理  |          |
|  +-----+----+  +-----+----+  +-----+----+  +-----+----+          |
+--------|------------|------------|------------|------------------+
         |          IPC 通信层 (contextBridge)                      |
+--------|------------|------------|------------|------------------+
|        v            v            v            v  主进程           |
|  +----------+  +----------+  +----------+  +----------+          |
|  |文件系统   |  |命令执行   |  | 模型管理  |  | Skill    |          |
|  |服务       |  |引擎      |  | 服务     |  | Manager  |          |
|  +----------+  +----------+  +----------+  +----------+          |
|  +----------+  +----------+  +----------+  +----------+          |
|  |循环引擎   |  | MCP      |  | 安全     |  | 配置     |          |
|  |LoopEngine |  | Manager  |  | Manager  |  | Manager  |          |
|  +-----+----+  +-----+----+  +-----+----+  +-----+----+          |
|        +------------+------------+------------+                  |
|                +------+-------+                                  |
|                | ToolExecutor |                                  |
|                | (5个内置工具) |                                  |
|                +--------------+                                  |
+------------------------------------------------------------------+
|  SQLite (sql.js)  |  electron-store  |  chokidar (文件监听)       |
|  node-pty (终端)  |  zod (校验)      |  crypto (加密)             |
+------------------------------------------------------------------+
```

---

## 技术栈

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| **开发语言** | TypeScript 5.8 | 全栈类型安全 |
| **桌面框架** | Electron 43 | 跨平台桌面应用 |
| **渲染框架** | React 19.2 + Vite 8.1 | 组件化 UI + 快速构建 |
| **状态管理** | Zustand 5 | 轻量级状态管理（6 个 Store） |
| **代码编辑器** | Monaco Editor 0.55 + @monaco-editor/react 4.7 | VS Code 同款编辑组件 |
| **终端模拟** | xterm.js 6.0 + node-pty 1.1 | 真终端交互（含自适应插件） |
| **数据库** | SQLite (sql.js 1.14) | 纯 JS 实现，免编译 |
| **参数校验** | Zod 4 | TypeScript 优先的 Schema 校验 |
| **MCP 协议** | @modelcontextprotocol/sdk 1.29 | 标准工具协议接入 |
| **文件监控** | chokidar 5.0 | 跨平台文件变更监听 |
| **图标** | lucide-react 1.24 | 开源图标组件 |
| **Markdown** | react-markdown 10 + remark-gfm 4 | Markdown 渲染 |
| **密钥加密** | crypto (AES-256-CBC) | 内置加密模块 |
| **打包** | electron-builder 26 | 应用打包分发 |

---

## 快速开始

### 前置要求

- **Node.js** >= 18.x
- **npm** >= 8.x
- **Windows 打包**（可选）：Visual Studio Build Tools（原生模块编译）

### 安装

```bash
git clone git@gitee.com:mutongli/mtl-loop-agent.git
cd mtl-loop-agent
npm install
```

> 项目已配置 `.npmrc` 国内镜像加速，安装时会自动使用 npmmirror 源和 Electron 镜像。
> `postinstall` 脚本会自动使用 `electron-builder install-app-deps` 编译原生模块。

### 开发模式

```bash
# 同时启动主进程和渲染进程（推荐）
npm run dev

# 或分别启动
npm run dev:main       # 编译主进程并启动 Electron
npm run dev:renderer   # 启动 Vite 开发服务器
```

### 构建

```bash
npm run build          # 构建全部（主进程 + 渲染进程）
npm run build:main     # 仅构建主进程
npm run build:renderer # 仅构建渲染进程
```

### 打包

```bash
npm run pack      # 打包到目录（不生成安装包）
npm run dist:win  # 打包 Windows NSIS 安装包
npm run dist:mac  # 打包 macOS DMG
npm run dist:linux # 打包 Linux AppImage
```

> 打包脚本已内置 `ELECTRON_BUILDER_BINARIES_MIRROR` 镜像加速和 `--publish never`，无需额外配置。

### 生产运行

```bash
npm start
```

---

## 设置面板

点击状态栏右侧的齿轮图标，打开设置面板，集中管理系统的核心配置：

| 设置页面 | 功能描述 |
|----------|----------|
| **模型管理** | 添加/编辑/删除模型，设置当前模型，配置 API Key 和参数，测试连接 |
| **MCP 管理** | 管理 MCP 服务器（添加/编辑/删除/连接/断开），查看服务器工具列表 |
| **Skill 管理** | 查看 Skill 列表，搜索过滤，启用/禁用，查看详情，导入 zip 包 |
| **安全设置** | 文件访问规则（黑白名单），危险命令控制，查看审计日志 |
| **通知设置** | 通知开关，通知类型筛选，免打扰模式，托盘图标管理，通知历史 |
| **快捷键** | 自定义快捷键绑定，恢复默认 |

---

## 项目结构

```
mtl-loop-agent/
+-- src/
|   +-- main/                        # Electron 主进程
|   |   +-- main.ts                  # 应用入口，IPC 注册（~200 个 handler）
|   |   +-- preload.ts               # Preload 脚本（contextBridge 安全桥接）
|   |   +-- common/                  # 公共类型和常量
|   |   |   +-- types.ts             # 全局类型定义（~50 个接口/类型）
|   |   |   +-- constants.ts         # IPC 通道常量（10 组通道分类）
|   |   +-- core/                    # 核心引擎
|   |   |   +-- loop-engine.ts       # 反应式循环引擎（思考-行动-观察闭环）
|   |   |   +-- model-manager.ts     # 模型管理（多 Provider + 故障自动切换 + 统计监控）
|   |   |   +-- tool-executor.ts     # 内置工具执行器（5 个 Function Calling 工具）
|   |   |   +-- skill-executor.ts    # Skill 执行引擎（config/code/mcp 三种模式）
|   |   +-- services/                # 服务层
|   |   |   +-- file-system.ts       # 文件系统服务（完整文件/目录操作）
|   |   |   +-- command-executor.ts  # 命令执行引擎（含交互式终端、进程管理、REPL）
|   |   |   +-- skill-manager.ts     # Skill 生命周期管理（扫描/注册/热更新/导入）
|   |   |   +-- skill-scanner.ts     # Skill 扫描与 SKILL.md 解析器
|   |   |   +-- mcp-manager.ts       # MCP 协议管理器（Server 注册/连接/工具发现）
|   |   |   +-- notifications.ts     # 通知服务（系统通知 + 系统托盘 + 历史记录）
|   |   |   +-- security.ts          # 安全管理器（FileAccess + CommandValidator + AuditLogger）
|   |   +-- config/
|   |   |   +-- config-manager.ts    # 配置管理（electron-store + 加密存储）
|   |   +-- ipc/
|   |   |   +-- ipc-api.ts           # IPC API 注册器（zod 校验 + 标准响应）
|   |   +-- providers/               # 模型提供者
|   |       +-- openai-provider.ts   # OpenAI Provider（含流式调用）
|   |       +-- anthropic-provider.ts# Anthropic Provider
|   |       +-- custom-provider.ts   # 自定义 Provider（兼容 OpenAI 协议）
|   +-- renderer/                    # Electron 渲染进程
|   |   +-- index.html               # HTML 入口
|   |   +-- index.tsx                # React 入口
|   |   +-- App.tsx                  # 主应用组件（三栏布局 + 可拖拽分隔线）
|   |   +-- components/              # UI 组件
|   |   |   +-- FileBrowser.tsx      # 文件浏览器（树形目录 + 文件列表 + 右键菜单）
|   |   |   +-- EditorPanel.tsx      # 代码编辑器（Monaco Editor，多 Tab，Markdown/HTML 预览）
|   |   |   +-- TabBar.tsx           # Tab 栏（多文件切换、右键菜单、滚轮滚动）
|   |   |   +-- ChatPanel.tsx        # 对话面板（消息列表 + 输入框 + 历史压缩）
|   |   |   +-- TerminalView.tsx     # 终端组件（xterm.js 集成）
|   |   |   +-- SettingsPanel.tsx    # 设置面板（统一设置入口，导航式布局）
|   |   |   +-- ModelSettings.tsx    # 模型配置（多模型管理 UI）
|   |   |   +-- SkillSettings.tsx    # Skill 管理（列表/启用/禁用/导入/测试）
|   |   |   +-- McpSettings.tsx      # MCP 配置（服务器管理 UI）
|   |   |   +-- SecuritySettings.tsx # 安全设置（文件规则/命令控制/审计日志）
|   |   |   +-- NotificationSettings.tsx # 通知设置（类型/托盘/历史）
|   |   |   +-- ShortcutSettings.tsx # 快捷键设置（自定义绑定/恢复默认）
|   |   |   +-- StatusBar.tsx        # 状态栏（模型状态/环境版本/设置入口）
|   |   +-- store/                   # Zustand 状态管理（6 个 Store）
|   |   |   +-- fileStore.ts         # 文件浏览状态
|   |   |   +-- chatStore.ts         # 对话消息状态（含历史压缩逻辑）
|   |   |   +-- editorStore.ts       # 编辑器状态（多 Tab 管理）
|   |   |   +-- terminalStore.ts     # 终端状态
|   |   |   +-- settingsStore.ts     # 设置面板状态
|   |   |   +-- layoutStore.ts       # 布局状态（侧边栏/面板/终端尺寸持久化）
|   |   +-- hooks/
|   |   |   +-- useHotkeys.ts        # 快捷键 Hook
|   |   +-- utils/
|   |   |   +-- ipc.ts               # 渲染进程 IPC 调用封装
|   |   +-- styles/
|   |       +-- index.css            # 全局样式（CSS 变量 + Tokyo Night 暗色主题）
+-- skills/                          # 内置 Skill
|   +-- code-analysis/SKILL.md       # 代码分析技能
|   +-- command-executor/SKILL.md    # 命令执行技能
|   +-- file-operations/SKILL.md     # 文件操作技能
+-- assets/                          # 应用图标和打包资源
|   +-- icon.png                     # 应用图标（PNG）
|   +-- icon.ico                     # 应用图标（ICO，多尺寸）
|   +-- entitlements.mac.plist       # macOS 签名权限
+-- .npmrc                           # npm 镜像加速配置
+-- package.json
+-- tsconfig.json                    # 渲染进程 TS 配置
+-- tsconfig.main.json               # 主进程 TS 配置
+-- vite.config.ts                   # Vite 构建配置
+-- electron-builder.json            # 打包配置
+-- USER_GUIDE.md                    # 用户使用文档
+-- design.md                        # 详细设计文档（13 章完整设计）
+-- requirements.md                  # 需求文档
+-- tasks.md                         # 任务管理（35 个任务进度追踪）
```

---

## 内置工具（Function Calling）

Agent 循环引擎通过 Function Calling 方式调用以下 5 个内置工具，实现与本地环境的交互：

| 工具名称 | 功能描述 | 主要参数 |
|----------|----------|----------|
| `file_read` | 读取指定文件内容 | filePath (必填) |
| `file_write` | 写入内容到文件（不存在则创建） | filePath, content (必填) |
| `file_list` | 列出目录下的文件和子目录 | dirPath (可选，默认当前目录) |
| `command_execute` | 执行 Shell 命令（含危险命令检查） | command (必填) |
| `skill_execute` | 执行已注册的 Skill | skillId (必填), inputs (可选) |

---

## Skill 开发

Skill 通过 `SKILL.md` 文件定义，遵循 Agent Skills Specification 开放标准：

```markdown
---
name: "my-skill"
description: "技能描述"
version: "1.0.0"
author: "作者"
category: "分类"
tags:
  - "标签1"
  - "标签2"
---

## 1. 触发条件
- 触发关键词或条件

## 2. 输入参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param1 | string | 必填 | 参数说明 |

## 3. 执行步骤
1. 步骤描述
2. 步骤描述

## 4. 输出格式
纯文本/表格/markdown/代码块

## 5. 错误处理
- 参数缺失：提示补充
- 执行失败：友好提示

## 6. 使用示例
用户输入：xxx
AI输出：xxx
```

### 三种执行模式

| 模式 | 说明 | 适用场景 |
|------|------|---------|
| `config` | 解析 SKILL.md 正文为步骤模板，按步骤调用文件/命令/模型 | 数据处理、文件操作、自动化流程 |
| `code` | 在 VM 沙箱中执行 JavaScript，注入安全的 fs/path/exec API | 复杂逻辑处理、数据转换 |
| `mcp` | 通过 MCP 协议调用外部工具服务 | 第三方 API 集成、远程服务调用 |

### Skill 目录优先级

系统按优先级从三个目录加载 Skill，高优先级覆盖低优先级：

| 优先级 | 目录 | 说明 |
|--------|------|------|
| 1 | `{工作目录}/.mtl/skills/` | 项目级（随项目分发，最高优先级） |
| 2 | `{用户数据}/.mtl/skills/` | 用户级（跨项目共享） |
| 3 | `{资源目录}/skills/` | 工作区级（随应用内置分发） |

### 导入 Skill

在应用内「设置 -> Skill 管理」页面，点击「导入」按钮选择 `.zip` 文件即可。zip 包内需包含 `SKILL.md` 文件及其相关资源文件。

---

## 对话历史记忆压缩

当对话超过预设轮数时，系统自动执行**记忆压缩**：

- **配置参数**：`maxRounds`（默认 12 轮）、`compressRounds`（默认 6 轮）
- **触发条件**：对话轮数超过 `maxRounds` 时，在发送新消息前自动执行压缩
- **压缩方式**：将最早的 `compressRounds` 轮对话提取关键内容，生成一条 `system` 类型的摘要消息
- **保留上下文**：保留最近的消息完整上下文，不影响当前对话质量

---

## 使用场景

### 代码开发助手

```
用户："帮我创建一个 Python Flask 项目，实现 REST API"
Agent：
  1. 分析需求，规划步骤
  2. 创建项目目录结构
  3. 编写 requirements.txt、app.py 和测试文件
  4. 安装依赖 (pip install)
  5. 运行测试，报告结果
```

### 数据处理分析

```
用户："帮我分析这个 CSV 文件，统计各列数据分布并生成图表"
Agent：
  1. 读取 CSV 文件
  2. 使用 Code Analysis Skill 分析数据结构
  3. 编写 Python 分析脚本
  4. 执行脚本生成图表
  5. 展示分析结果
```

### 自动化运维

```
用户："检查系统磁盘使用情况，清理超过 30 天的日志文件"
Agent：
  1. 执行系统命令检查磁盘使用情况
  2. 分析磁盘使用数据
  3. 查找 30 天前的日志文件
  4. 执行清理命令
  5. 报告清理结果
```

---

## 开发指南

### 代码规范

```bash
npm run lint     # ESLint 代码检查（TypeScript + React）
npm run format   # Prettier 代码格式化
```

### 添加模型 Provider

1. 在 `src/main/providers/` 下创建新的 Provider 文件
2. 实现 `Provider` 接口（`configure/call/streamCall/testConnection`）
3. 在 `src/main/core/model-manager.ts` 中注册新 Provider

### IPC 通道扩展

1. 在 `src/main/common/constants.ts` 中定义新的通道常量
2. 在 `src/main/main.ts` 中通过 `ipcApi.register()` 注册 handler
3. 在 `src/renderer/utils/ipc.ts` 中添加渲染进程调用封装
4. 在 `src/main/common/types.ts` 中定义相关类型

### 添加内置工具

1. 在 `src/main/core/tool-executor.ts` 的 `BUILT_IN_TOOLS` 数组中添加工具定义
2. 定义 `function.name`、`function.description`、`function.parameters`
3. 实现 `execute` 回调函数

---

## 配置存储

配置文件路径（electron-store 自动管理）：
- **Windows**: `%APPDATA%/mtl-loop-agent/config.json`
- **macOS**: `~/Library/Application Support/mtl-loop-agent/config.json`
- **Linux**: `~/.config/mtl-loop-agent/config.json`

配置内容包含：
- 模型列表及配置（API Key 加密存储）
- 当前模型 ID
- 安全配置（文件访问规则、命令黑名单）
- 通知配置（启用状态、托盘图标）
- MCP 服务器列表
- 禁用的 Skill 列表
- 快捷键配置

---

## 项目进度

查看 [`tasks.md`](./tasks.md) 获取完整的开发任务追踪（共 35 个任务，已完成 32 个，完成率 91.4%）：

| 阶段 | 任务数 | 已完成 | 已废弃 | 完成率 |
|------|--------|--------|--------|--------|
| 阶段一：基础功能 | 11 | 11 | 0 | 100% |
| 阶段二：核心能力 | 12 | 12 | 0 | 100% |
| 阶段三：完善优化 | 11 | 8 | 3 | 72.7% |
| 其他 | 1 | 1 | 0 | 100% |
| **合计** | **35** | **32** | **3** | **91.4%** |

详细设计文档请查看 [`design.md`](./design.md)（13 章，涵盖架构、文件系统、命令执行、Skill 管理、模型管理、循环引擎、交互设计、安全等）。

用户使用文档请查看 [`USER_GUIDE.md`](./USER_GUIDE.md)（安装指南、快速开始、功能详解、快捷键、FAQ）。

---

## 许可证

本项目基于 **MIT** 许可证开源。

---

> **MTL Loop Agent** -- 让 AI 成为你的本地智能开发助手，在 Loop 中持续进化。