TUUI：一个开源的本地 AI 工具箱，让大模型真正「动」起来

TUUI Logo 图1：TUUI 应用图标

场景切入：为什么你需要 TUUI？

想象这样一个日常：你同时在用 Claude 处理文档、在本地跑 Qwen 做代码补全、还用 DeepSeek 做知识库检索。三个模型，三套界面，三组 API Key 管理——光是来回切换就让人疲惫。更别说想给某个模型挂载本地文件系统的上下文，或者让不同厂商的模型互相调用彼此的工具。

TUUI 正是为解决这个痛点而生。 它是一个桌面级 MCP（Model Context Protocol）客户端，将多个大语言模型和它们的工具生态聚合到一个窗口里，让 AI 不再是割裂的「问答机器」，而是真正能操控本地资源、协同工作的智能代理。

背景故事：一个人用 AI 逆向构建的实验

TUUI 的开发故事本身就颇具戏剧性。项目 README 开篇明言：这是一个**「大胆的实验」**——尝试完全用 AI 来创建整个项目。大部分代码组件直接从原型项目通过 AI 转换或生成。

这种开发方式带来了独特的代码规范要求：为了保证 AI 生成内容的质量与安全，TUUI 采用了严格的语法检查和命名约定体系。开发者在仓库中配置了完整的 ESLint + Prettier + TypeScript 检查链，任何 PR 都必须经过 lint 工具的自动修复验证才能合入。

项目由 AI-QL 团队维护，仓库地址 github.com/AI-QL/tuui，官方文档站 tuui.com，采用 Apache-2.0 开源协议。目前已在 GitHub 收获 1,148 个 stars，话题标签涵盖 agent、agentic-ai、anthropic、claude、deepseek 等多个 AI 生态关键词。

类比解释：给 AI 用的「多窗口管理器」

如果把普通 AI 对话工具比作只能显示一张网页的浏览器，TUUI 就是一个自带开发者工具、可以同时打开几十个标签页、支持页面间互相通信的多标签浏览器。它解决的核心问题是：打破 AI 工具之间的壁垒，让工具可以被复用、被组合、被统一调度。

具体来说，TUUI 扮演三个角色：

MCP 客户端：作为 MCP 协议的标准客户端，连接并管理各类 MCP Server
多 LLM 编排器：通过 JSON 配置，同时连接 OpenAI、Claude、Qwen、DeepSeek 等多个后端
桌面工具集成层：内置截图、剪贴板、文件系统等本地工具，让 AI 的能力延伸到屏幕之外

核心功能：技术细节与实用场景

MCP 协议全面支持

TUUI 是 Model Context Protocol 的深度实践者，完整实现了 MCP 规范中的核心能力：

能力	类型	说明
Tools	Server	调用 MCP Server 注册的工具函数
Prompts	Server	访问预定义提示模板
Resources	Server	读写 MCP 资源（文件、数据库等）
Sampling	Client	让 LLM 自主请求采样（LLM-In-The-Loop）
Elicitation	Client	AI 向用户主动请求额外信息
Discovery	Registry	实时发现 MCP Registry 上的服务端
MCPB	Extension	支持 MCP Bundles（.mcpb）打包格式

跨厂商 LLM API 编排

TUUI 的 LLM 配置基于 JSON 文件，支持 OpenAI-Compatible API 格式，可以同时配置多个模型：

{
  "name": "Qwen",
  "apiKey": "",
  "url": "https://dashscope.aliyuncs.com/compatible-mode",
  "path": "/v1/chat/completions",
  "model": "qwen-turbo",
  "modelList": ["qwen-turbo", "qwen-plus", "qwen-max"],
  "mcp": true
}

支持 OpenRouter、DeepInfra 等聚合 API 网关，一个 TUUI 实例中可以同时对话来自不同厂商的多个模型。maxTokens、temperature 等参数均可按需配置。

远程 MCP Server 支持

通过 Cloudflare 的 mcp-remote 项目，TUUI 还支持连接远程 MCP Server，实现云端工具服务的调用。只需在 mcp.json 中添加配置即可：

{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOURDOMAIN.com/sse"]
    }
  }
}

前端界面与技术栈

TUUI 的 UI 层采用 Electron + Vue3 + Vuetify 构建，这是一个在桌面应用中成熟可靠的组合。状态管理使用 Pinia，路由使用 Vue Router，界面支持多语言国际化（locales 目录下有中文等翻译文件）。

渲染进程目录 src/renderer/ 包含完整的组件体系：screens 目录下有 Chat（聊天）、Agent、MCP、Setting 等主要页面；components 目录包含各类可复用 UI 组件；composables 目录封装了组合式函数逻辑。

主进程目录 src/main/ 是 Electron 的核心所在：IPC 通信层（IPCs.ts）负责主进程与渲染进程的消息传递；MCP 模块（mcp/）实现了 MCP 协议的客户端逻辑，包含 StdioClientTransport 连接、Sampling 请求处理、Elicitation 响应处理；aid/ 目录提供辅助工具（如快捷键注册、命令执行器）。

MCP 客户端核心使用了 @modelcontextprotocol/sdk 官方 SDK，通过 Node.js 标准 I/O（stdio）与 MCP Server 进程通信。连接超时默认 90 秒，超时后自动终止。

上手门槛：需要什么配置？

安装前提：

Node.js >= 18：执行 NPX 类型的 MCP Server
Python + UV：执行 UVX 类型的 MCP Server
Docker：运行 Docker 类型 MCP Server（仅 macOS/Linux）
LLM 后端：需要一个支持 tool/function calling 的 API（OpenAI、Claude、Qwen 等均可）

运行方式：

下载预编译 Release 包（Windows/macOS/Linux）→ 双击即用
从源码构建 → npm install && npm run dev（开发模式）或打包（生产模式）

已知问题：

macOS 上使用 NPX 启动 MCP Server 可能遇到 spawn 错误（ENOENT），官方建议使用绝对路径或等待上游修复
首次启动需在设置中配置 LLM API Key（TUUI 本身不提供 API Key）

技术架构：模块化设计一览

TUUI 采用经典的 Electron 多进程架构：

src/
├── main/           # Electron 主进程
│   ├── index.ts    # 入口，管理窗口生命周期
│   ├── MainRunner.ts  # 窗口创建（主窗口/闪屏/错误窗口）
│   ├── mcp/        # MCP 客户端实现
│   │   ├── client.ts  # StdioClientTransport 初始化
│   │   ├── config.ts  # MCP Server 配置解析
│   │   ├── connection.ts  # 连接管理
│   │   └── dxt.ts      # Desktop Extensions / MCPB 扩展
│   ├── aid/        # 辅助工具
│   ├── tray.ts     # 系统托盘
│   └── assets/config/  # 默认配置文件（llm.json, mcp.json）
├── preload/        # 预加载脚本，安全暴露 IPC
│   └── index.ts
└── renderer/       # Vue3 渲染进程
    ├── screens/    # 页面（chat, agent, mcp, setting...）
    ├── components/ # UI 组件
    ├── store/      # Pinia 状态（agent, chatbot, dxt, mcp, message...）
    ├── locales/    # 多语言
    └── composables/ # 组合式函数

关键依赖：

@modelcontextprotocol/sdk ^1.29.0：MCP 协议核心库
@anthropic-ai/mcpb ^2.1.2：MCP Bundles 处理
electron ^42.0.1：跨平台桌面框架
vue ^3.x + vuetify：前端 UI
pinia ^3.0.4：状态管理
@nut-tree-fork/nut-js ^4.2.6：本地自动化（截图等）
md-editor-v3 ^6.5.0：Markdown 编辑
mermaid ^11.15.0：图表渲染

代码质量方面，项目使用 TypeScript 严格模式、完整 ESLint 配置、Prettier 格式化，测试框架使用 Playwright，代码规范程度较高。测试目录 tests/ 和 Playwright 配置 playwright.config.ts 表明项目有自动化测试覆盖。

争议与局限

macOS MCP Server 兼容性问题：NPX 启动 MCP Server 在 macOS 上存在已知的 spawn ENOENT 错误，虽然 Windows 有 workaround，但 macOS 尚未完全解决。
纯桌面端限制：TUUI 本质是 Electron 桌面应用，不支持 Docker 部署，也不提供 Web 版本。对于服务器端场景或远程访问需求，当前无法满足。
LLM 后端需自备：TUUI 不内置任何 LLM 能力，必须自行准备 OpenAI/Claude/Qwen 等 API Key，对普通用户存在一定门槛。
文档质量参差不齐：README 文档较为详尽，但部分子文档（如安装指南）需要参考 wiki 页面，对离线用户不够友好。
一个人主导的 AI 生成项目：虽然 README 坦承「用 AI 构建整个项目」的实验性质，但外界对代码可维护性、可审计性存在一定顾虑。

行业意义与增长趋势

TUUI 代表着 MCP 生态从概念走向实用化的一条路径。随着 MCP 协议被越来越多的 AI 工具采纳（Anthropic、OpenAI、GitHub 等厂商均已支持），类似 TUUI 这样的客户端工具将成为连接本地工具与云端模型的枢纽。

从数据看，项目在 2026-05-14 仍有活跃提交，保持着稳定迭代。它选择拥抱 MCP 而非自建协议，体现了对开放标准的坚持——这一点在 AI 工具碎片化的当下尤为重要。

对于希望本地化部署 AI 能力、聚合多模型工具、深度定制 AI 工作流的开发者，TUUI 是一个值得关注的选择。

TUUI：一个开源的本地 AI 工具箱，让大模型真正「动」起来

TUUI Logo 图1：TUUI 应用图标

场景切入：为什么你需要 TUUI？

背景故事：一个人用 AI 逆向构建的实验

类比解释：给 AI 用的「多窗口管理器」

具体来说，TUUI 扮演三个角色：

MCP 客户端：作为 MCP 协议的标准客户端，连接并管理各类 MCP Server
多 LLM 编排器：通过 JSON 配置，同时连接 OpenAI、Claude、Qwen、DeepSeek 等多个后端
桌面工具集成层：内置截图、剪贴板、文件系统等本地工具，让 AI 的能力延伸到屏幕之外

核心功能：技术细节与实用场景

MCP 协议全面支持

TUUI 是 Model Context Protocol 的深度实践者，完整实现了 MCP 规范中的核心能力：

能力	类型	说明
Tools	Server	调用 MCP Server 注册的工具函数
Prompts	Server	访问预定义提示模板
Resources	Server	读写 MCP 资源（文件、数据库等）
Sampling	Client	让 LLM 自主请求采样（LLM-In-The-Loop）
Elicitation	Client	AI 向用户主动请求额外信息
Discovery	Registry	实时发现 MCP Registry 上的服务端
MCPB	Extension	支持 MCP Bundles（.mcpb）打包格式

跨厂商 LLM API 编排

TUUI 的 LLM 配置基于 JSON 文件，支持 OpenAI-Compatible API 格式，可以同时配置多个模型：

{
  "name": "Qwen",
  "apiKey": "",
  "url": "https://dashscope.aliyuncs.com/compatible-mode",
  "path": "/v1/chat/completions",
  "model": "qwen-turbo",
  "modelList": ["qwen-turbo", "qwen-plus", "qwen-max"],
  "mcp": true
}

支持 OpenRouter、DeepInfra 等聚合 API 网关，一个 TUUI 实例中可以同时对话来自不同厂商的多个模型。maxTokens、temperature 等参数均可按需配置。

远程 MCP Server 支持

通过 Cloudflare 的 mcp-remote 项目，TUUI 还支持连接远程 MCP Server，实现云端工具服务的调用。只需在 mcp.json 中添加配置即可：

{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOURDOMAIN.com/sse"]
    }
  }
}

前端界面与技术栈

MCP 客户端核心使用了 @modelcontextprotocol/sdk 官方 SDK，通过 Node.js 标准 I/O（stdio）与 MCP Server 进程通信。连接超时默认 90 秒，超时后自动终止。

上手门槛：需要什么配置？

安装前提：

Node.js >= 18：执行 NPX 类型的 MCP Server
Python + UV：执行 UVX 类型的 MCP Server
Docker：运行 Docker 类型 MCP Server（仅 macOS/Linux）
LLM 后端：需要一个支持 tool/function calling 的 API（OpenAI、Claude、Qwen 等均可）

运行方式：

下载预编译 Release 包（Windows/macOS/Linux）→ 双击即用
从源码构建 → npm install && npm run dev（开发模式）或打包（生产模式）

已知问题：

macOS 上使用 NPX 启动 MCP Server 可能遇到 spawn 错误（ENOENT），官方建议使用绝对路径或等待上游修复
首次启动需在设置中配置 LLM API Key（TUUI 本身不提供 API Key）

技术架构：模块化设计一览

TUUI 采用经典的 Electron 多进程架构：

src/
├── main/           # Electron 主进程
│   ├── index.ts    # 入口，管理窗口生命周期
│   ├── MainRunner.ts  # 窗口创建（主窗口/闪屏/错误窗口）
│   ├── mcp/        # MCP 客户端实现
│   │   ├── client.ts  # StdioClientTransport 初始化
│   │   ├── config.ts  # MCP Server 配置解析
│   │   ├── connection.ts  # 连接管理
│   │   └── dxt.ts      # Desktop Extensions / MCPB 扩展
│   ├── aid/        # 辅助工具
│   ├── tray.ts     # 系统托盘
│   └── assets/config/  # 默认配置文件（llm.json, mcp.json）
├── preload/        # 预加载脚本，安全暴露 IPC
│   └── index.ts
└── renderer/       # Vue3 渲染进程
    ├── screens/    # 页面（chat, agent, mcp, setting...）
    ├── components/ # UI 组件
    ├── store/      # Pinia 状态（agent, chatbot, dxt, mcp, message...）
    ├── locales/    # 多语言
    └── composables/ # 组合式函数

关键依赖：

@modelcontextprotocol/sdk ^1.29.0：MCP 协议核心库
@anthropic-ai/mcpb ^2.1.2：MCP Bundles 处理
electron ^42.0.1：跨平台桌面框架
vue ^3.x + vuetify：前端 UI
pinia ^3.0.4：状态管理
@nut-tree-fork/nut-js ^4.2.6：本地自动化（截图等）
md-editor-v3 ^6.5.0：Markdown 编辑
mermaid ^11.15.0：图表渲染

争议与局限

macOS MCP Server 兼容性问题：NPX 启动 MCP Server 在 macOS 上存在已知的 spawn ENOENT 错误，虽然 Windows 有 workaround，但 macOS 尚未完全解决。
纯桌面端限制：TUUI 本质是 Electron 桌面应用，不支持 Docker 部署，也不提供 Web 版本。对于服务器端场景或远程访问需求，当前无法满足。
LLM 后端需自备：TUUI 不内置任何 LLM 能力，必须自行准备 OpenAI/Claude/Qwen 等 API Key，对普通用户存在一定门槛。
文档质量参差不齐：README 文档较为详尽，但部分子文档（如安装指南）需要参考 wiki 页面，对离线用户不够友好。
一个人主导的 AI 生成项目：虽然 README 坦承「用 AI 构建整个项目」的实验性质，但外界对代码可维护性、可审计性存在一定顾虑。

行业意义与增长趋势

对于希望本地化部署 AI 能力、聚合多模型工具、深度定制 AI 工作流的开发者，TUUI 是一个值得关注的选择。