Metadata-Version: 2.4
Name: kevin-terminal-manager
Version: 0.0.2
Summary: An advanced terminal management platform powered by Tmux, MCP, and Tauri/React for LLM Agents.
Author-email: Kevin <xukaiming1996@163.com>
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: fastapi>=0.136.1
Requires-Dist: mcp>=1.27.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: sqlalchemy>=2.0.49
Requires-Dist: uvicorn>=0.30.1
Requires-Dist: websockets>=16.0
Description-Content-Type: text/markdown

# 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 自动执行与人类干预的安全协同。

```mermaid
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 官方安装文档](https://github.com/astral-sh/uv)。
3. **Node.js & npm**: 用于运行前端 React 项目。
4. **Tauri 前置依赖** (仅打包桌面端需要): 如果你计划将前端打包为原生桌面应用，需要安装 Rust 和相关系统依赖，详情请见 [Tauri Prerequisites](https://tauri.app/v1/guides/getting-started/prerequisites)。

### 1. 启动服务

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

#### 选项 A：使用一键脚本启动 (推荐)
在项目根目录下执行：
```bash
# 一键同时启动前后端服务
./scripts/start_all.sh
```
*(你也可以单独运行 `./scripts/start_web_backend.sh`)*

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

**启动 Web 后端服务：**
Web 后端负责提供 WebSocket 流、REST API 以及**静态前端页面**。
```bash
# 在项目根目录下执行
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` 运行，无需下载源码：
```bash
# 启动 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` 中配置：

```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，配置将变得非常简单：

```json
{
  "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 接口详细文档](./notes/MCP_Tools_Reference.md)。

| 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 接口详细文档](./notes/MCP_Tools_Reference.md)
- [❓ 常见问题解答 (Q&A)](./notes/Q&A.md)
- [👨‍💻 开发者指南 (Developer Guide)](./notes/Developer_Guide.md) - 面向高级用户与后续开发者，包含项目结构解析与二次开发指南。

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

### 💡 对 KTM 后续开发的启示

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