kevin-terminal-manager 0.0.2

An advanced terminal management platform powered by Tmux, MCP, and Tauri/React for LLM Agents.

Kevin-Terminal-Manager (KTM)

Kevin-Terminal-Manager (KTM) 是一个基于 Tmux 底层、通过 MCP (Model Context Protocol) 暴露给 Agent、并配有跨平台桌面状态栏与本地 Web Dashboard 的高级终端管理平台。

它的核心目标是解决大语言模型 (LLM) Agent 在执行长流程、强交互的终端任务时容易发生的状态丢失、交互死锁等问题，实现 “Agent 自动驾驶 + 状态精准感知 + 人类随时接管” 的深度人机协同 (Human-in-the-Loop) 工作流。

---

🏗️ 系统架构

KTM 采用前后端分离与底层终端解耦的架构设计，确保了 Agent 自动执行与人类干预的安全协同。

graph TD
    subgraph Agent["Agent 侧 (LLM)"]
        A[大语言模型 / Cursor] -->|调用 MCP Tools| B[MCP Server]
    end

    subgraph Backend["后端服务 (Python/FastAPI)"]
        B -->|操作指令| C[Tmux 控制模块]
        B -->|读写状态| D[(SQLite 数据库)]
        E[WebSocket Server] -->|流式读取| C
    end

    subgraph Underlying["底层设施"]
        C -->|PTY/会话管理| F[Tmux Sessions]
    end

    subgraph Frontend["前端 UI (Tauri + React)"]
        G[System Tray] -->|呼出| H[Web Dashboard]
        H -->|WebSocket| E
        H -->|接管控制| F
    end

    %% 状态与防冲突机制
    C -.->|状态检查| D
    C -.->|防冲突检测| F

核心组件说明：

• Agent 侧 (MCP Server)：基于 Python mcp SDK 构建，向 LLM 暴露 create_terminal、send_command、request_human 等标准化工具。这是由 Cursor/Claude Desktop 唤起的无头 (Headless) 进程。
• Web 后端服务 (FastAPI)：维护 SQLite 数据库（默认在用户目录 ~/.ktm/ 下生成 ktm.db，记录终端元数据、状态），并提供 WebSocket 服务用于向前端推送终端输出流。同时，它也负责静态托管打包后的 React 前端页面。这是一个独立的进程，专为前端 Dashboard 提供数据。
• 底层设施 (Tmux)：利用原生 tmux 的会话持久化和读写锁能力，确保终端进程在后台稳定运行，并提供严格的人机防冲突检测。
• 前端 UI (Tauri + React)：提供跨平台状态栏与可视化 Dashboard，集成 Xterm.js 实时渲染终端画面，支持人类随时点击“接管”打断 Agent。

💡 架构解耦特别说明 (双后端设计) 初次接触 KTM 的开发者容易混淆，KTM 实际上有两个独立的“后端”进程，它们共享同一个 SQLite 数据库和 Tmux 底层：

1. MCP Server (mcp_server.py)：由 Cursor/Claude Desktop 通过 stdio 自动拉起，不占用任何网络端口，专门负责接收大模型的工具调用指令。
2. Web Server (web_server.py)：由用户手动启动（通过 start_web_backend.sh），占用 8000 端口，专门负责给网页前端 Dashboard 提供 API 和 WebSocket 画面流。

这种解耦设计允许 Agent 在完全无头（Headless）的环境下极速运行，而人类只需在需要“监工”时启动 Web 服务即可实时查看状态。

---

🚀 快速开始与使用说明

本项目分为后端 (Python/FastAPI + MCP) 和前端 (Tauri/React) 两部分。

0. 环境准备 (Prerequisites)

在运行 KTM 之前，请确保你的机器上已安装以下基础环境：

1. Tmux: 系统的核心底层依赖。Linux 下可通过 sudo apt install tmux 安装，macOS 通过 brew install tmux。
2. uv: 极速的 Python 包和环境管理器。参考 uv 官方安装文档。
3. Node.js & npm: 用于运行前端 React 项目。
4. Tauri 前置依赖 (仅打包桌面端需要): 如果你计划将前端打包为原生桌面应用，需要安装 Rust 和相关系统依赖，详情请见 Tauri Prerequisites。

1. 启动服务

我们提供了便捷的一键启动脚本，同时也保留了手动启动的详细步骤供开发者参考。

选项 A：使用一键脚本启动 (推荐)

在项目根目录下执行：

# 一键同时启动前后端服务
./scripts/start_all.sh

(你也可以单独运行 ./scripts/start_web_backend.sh)

选项 B：手动分步启动

如果你想深入了解启动细节或进行开发调试，可以手动启动：

启动 Web 后端服务： Web 后端负责提供 WebSocket 流、REST API 以及静态前端页面。

# 在项目根目录下执行
uv run uvicorn ktm.backend.web_server:app --reload --host 127.0.0.1 --port 8000

服务启动后，打开浏览器访问 http://localhost:8000 即可看到控制台。

选项 C：通过 PyPI 全局安装 (v0.0.2 新增)

如果项目已经发布到 PyPI，你可以直接使用 uvx 运行，无需下载源码：

# 启动 Web Dashboard
uvx kevin-terminal-manager ktm-web

然后访问 http://localhost:8000。

2. 在 Cursor / Claude Desktop 中配置 MCP

要让你的 AI Agent 能够使用 KTM，需要在你的 MCP 客户端（如 Cursor 或 Claude Desktop）中添加该 Server。

方式一：如果使用本地源码 (开发模式)

在 Cursor 的 mcp.json 中配置：

{
  "mcpServers": {
    "KTM": {
      "command": "/home/user/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/home/user/path/to/kevin_terminal_manager_mcp",
        "python",
        "-m",
        "ktm.backend.mcp_server"
      ]
    }
  }
}

方式二：如果通过 PyPI 全局安装 (推荐)

如果项目已经发布到 PyPI，配置将变得非常简单：

{
  "mcpServers": {
    "KTM": {
      "command": "uvx",
      "args": [
        "kevin-terminal-manager",
        "ktm-mcp"
      ]
    }
  }
}

⚠️ 重要提示： Cursor 在后台启动 MCP Server 时，不会加载你终端的完整环境变量 (如 $PATH)。因此，必须将 uv 替换为其绝对路径（可以通过在终端执行 which uv 获取）。

配置完成后，Agent 即可调用 KTM 提供的强大终端控制工具。

---

🛠️ MCP Tools 接口概览

KTM 向 Agent 暴露了以下核心工具，用于实现对终端的精细化控制。详细的参数说明与功能介绍请参阅 👉 MCP Tools 接口详细文档。

Tool 名称	核心功能	简述
create_terminal	创建终端	创建一个新的 Tmux 后台终端会话，并等待其 Shell 完全初始化就绪，支持环境变量和工作目录注入。
query_terminals	查询终端	根据名称、标签、状态等条件检索当前管理的终端列表，并动态返回人类实时连接状态（窥屏/接管）。
update_remark	更新备注	更新指定终端的业务总结备注，帮助 Agent 维持长线记忆。
send_command	发送命令	向终端发送命令，并挂起等待特定正则输出（内置防冲突拦截）。
read_screen	读取屏幕	抓取指定终端最近的 N 行纯文本输出。
get_command_rules	获取安全规则	获取当前系统配置的危险命令过滤与拦截规则。
request_human	请求人类接管	主动挂起 Agent 运行，触发通知并等待人类干涉和恢复。
close_terminal	关闭终端	安全终止 Tmux 会话并清理相关数据库记录。

---

📚 更多参考文档

• 👉 MCP Tools 接口详细文档
• ❓ 常见问题解答 (Q&A)
• 👨‍💻 开发者指南 (Developer Guide) - 面向高级用户与后续开发者，包含项目结构解析与二次开发指南。

📊 同类 MCP 终端项目对比

为了更清晰地明确 KTM 的定位，我们在下表中客观比较了目前社区中主流的交互式终端 MCP 项目。这不仅展示了 KTM 的核心优势，也为我们后续的功能演进提供了参考。

1. 核心特性矩阵对比

功能特性	KTM (本项目)	WangYihang	mitsuhiko	phoityne	bnomei	nickgnd	ttommyth
底层引擎	Tmux	PTY	Pexpect	PTY	Tmux	Tmux	OS Native
状态持久化	✅	✅	✅	✅	✅	✅	❌
哨兵就绪检测 (Sentinel Wait)	✅	❌	❌	❌	❌	❌	❌
正则匹配等待	✅	✅	❌	❌	❌	❌	❌
防冲突锁 (防人机混输)	✅	❌	❌	❌	❌	❌	❌
可视化 Dashboard	✅	❌	❌	❌	❌	❌	❌
人类接管干涉	✅	❌	❌	❌	✅	❌	✅ (仅问答)
调试器深度优化	❌	❌	✅ (GDB/LLDB)	❌	❌	❌	❌
OS 原生通知	✅	❌	❌	❌	❌	❌	✅

2. 各项目优劣势详细分析

项目名称	核心语言	优势 (Pros)	劣势 (Cons)	KTM 对比分析
WangYihang/interactive-terminal-mcp	Python	轻量级；支持正则匹配 (wait_for)；状态持久化。	纯 Headless，无 GUI；无防冲突机制；目前存在输出截断 (Truncating) 的 Issue。	KTM 借鉴了其出色的 wait_for 正则等待理念，但在此基础上增加了 SQLite 持久化和防冲突锁。
mitsuhiko/pexpect-mcp	Python	调试场景极其强大；由知名开发者 (mitsuhiko) 维护；代码精简。	场景较垂直（偏向调试）；缺乏人类协同 UI。	KTM 更偏向通用终端管理。后续 KTM 可以参考其对 GDB/LLDB 的特殊处理优化底层 PTY 交互。
phoityne/pty-mcp-server	Haskell	底层 PTY 控制力强；工具分类细致 (pty-ssh, pty-bash 等)。	Haskell 编写导致二次开发和环境配置门槛极高；缺乏可视化界面。	KTM 使用 Python + Tmux 替代了纯 PTY，降低了开发门槛，同时获得了 Tmux 原生的多 Client Attach 能力。
bnomei/tmux-mcp	Rust	性能极高；支持人类手动 Attach 到同一 Session 观看；支持 Pane 切分。	纯 CLI 工具，无专属 Dashboard；没有实现严格的“读写防冲突锁”。	同样基于 Tmux，KTM 牺牲了部分极简性，换取了强大的 React Dashboard 和严格的人机防冲突状态机。
nickgnd/tmux-mcp	JS/TS	JS 生态集成方便；支持窗口和 Pane 管理。	功能相对基础；缺乏高级的正则等待和人机交接管逻辑。	KTM 的 Python 后端在处理复杂正则和异步超时方面比纯 JS 脚本调用更具鲁棒性。
ttommyth/interactive-mcp	TS	极佳的人机交互体验；支持 OS 原生通知；支持预设选项问答。	并非真正的后台终端管理器，更像是一个“对话框/通知”插件。	KTM 的 request_human 工具定位与其类似。KTM 后续可以借鉴其跨平台通知的实现方案，增强干涉请求的提醒效果。

💡 对 KTM 后续开发的启示

通过上述对比，我们可以得出 KTM 下一步的优化方向：

1. 调试器深度支持：参考 pexpect-mcp，后续可考虑为 GDB/LLDB/Pdb 等常见调试器增加专属的快速解析 Tool，而不仅仅是当作普通终端对待。
2. 前端系统托盘 (System Tray) 完善：目前前端已经实现了 Web 轮询通知，但 Tauri 的原生系统托盘菜单（如右键退出、快速切换终端）尚未完全实现，未来可以在 Rust 侧进一步丰富桌面端的交互体验。