kvm-pilot

<!-- mcp-name: io.github.DustinTrap/kvm-pilot --> <p align="center"> <img src="https://raw.githubusercontent.com/DustinTrap/kvm-pilot/main/docs/assets/logo.svg" alt="kvm-pilot" width="460"> </p> <p align="center"> <a href="https://pypi.org/project/kvm-pilot/"><img src="https://img.shields.io/pypi/v/kvm-pilot?color=534ab7" alt="PyPI 版本"></a> <a href="https://pypi.org/project/kvm-pilot/"><img src="https://img.shields.io/pypi/pyversions/kvm-pilot" alt="Python 版本"></a> <a href="https://github.com/DustinTrap/kvm-pilot/actions/workflows/ci.yml"><img src="https://github.com/DustinTrap/kvm-pilot/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/DustinTrap/kvm-pilot/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="许可证：Apache-2.0"></a> <a href="https://registry.modelcontextprotocol.io/v0/servers?search=kvm-pilot"><img src="https://img.shields.io/badge/MCP_registry-io.github.DustinTrap%2Fkvm--pilot-534ab7" alt="MCP 注册表"></a> </p> # kvm-pilot **您的人工智能代理的智能助手。** 一个可写入、多平面的（KVM + BMC + SSH）MCP服务器，用于控制物理机器 —— **有权限验证，审计记录。** `kvm-pilot`允许代理通过IP-KVM（PiKVM，GL.iNet GLKVM fork GL-RM1 / GL-RM1PE，BliKVM）在像素级别控制无头设备，通过BMC（Redfish on iDRAC / iLO / OpenBMC，IPMI on旧BMC）获取结构化状态，通过Intel AMT / vPro（BIOS / POST / GRUB截图 + 电源 + SOL）在固件级别，以及通过SSH在操作系统级别进行控制。插件式视觉子系统读取KVM截图并告诉您机器的引导阶段 —— `bios_menu`、`grub_menu`、`installer_progress`、`login_prompt`、`crash_screen`等。安全层通过操作员确认和每次调用的批准来控制每个破坏性操作。 视觉处理运行在Claude **或** 任何本地OpenAI兼容的VLM（LM Studio，Ollama，vLLM，llama.cpp）上。指向您自己的GPU上的模型，截图永远不会离开您的网络，并且每帧无需花费。 ## 它是如何工作的 `kvm-pilot`运行一个**查看 → 决定 → 执行**的循环，屏幕是其唯一的传感器：它从KVM拉取截图，视觉模型分类引导阶段，`kvm-pilot`通过KVM的键盘和电源执行操作。因为它在像素级别工作，所以**目标上没有代理** —— 同样的循环驱动POST、固件、引导加载程序和操作系统安装。  实际的、未经编辑的运行测试在一个家用机群上的GLKVM：一个诚实的预检，一个无头的快照（观看它唤醒按需编码器），一个**有权限**的干燥运行电源循环，以及代理实际看到的启动控制台：  ## 快速开始 一次安装提供整个产品 —— **`kvm-pilot` CLI**， **`kvm-pilot-mcp` MCP服务器**，以及捆绑的**Claude技能** —— 无需克隆。目前的发布线是**预发布**，因此需要 `--pre`（普通的 `pip install kvm-pilot` 故意不获取预发布版本；`0.1.0a1` 已被删除，比此README更旧 - 不要使用它）。 ```bash pip install --pre kvm-pilot # CLI + 技能 + MCP服务器 + WebSocket事件 pip install --pre "kvm-pilot[totp]" # + 2FA / TOTP支持（pyotp） kvm-pilot install-skill # 可选：将捆绑的技能放在Claude Code加载的位置 ``` ### 从AI代理（MCP）驱动KVM ```bash claude mcp add kvm-pilot -s user \ -e KVM_PILOT_PROFILE=<profile> -e KVM_PILOT_MCP_READ_ONLY=1 -- \ kvm-pilot-mcp ``` `KVM_PILOT_MCP_READ_ONLY=1` 是推荐的信任梯度的第一步 —— 代理可以查看所有内容，但不能触摸任何内容，直到您的硬件经过验证。[入门指南](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/getting-started.md)涵盖了凭证、Claude Desktop JSON配置、样本提示和攀登信任梯度。服务器发布到官方 [MCP注册表](https://registry.modelcontextprotocol.io/v0/servers?search=kvm-pilot) 为 **`io.github.DustinTrap/kvm-pilot`**，因此注册表感知的宿主可以发现并安装它。代理：存储库根目录包含一个 [`llms.txt`](https://github.com/DustinTrap/kvm-pilot/blob/main/llms.txt) 文档映射。 ### 从Python脚本 ```python from kvm_pilot import KVMClient from kvm_pilot.vision import ScreenAnalyzer, make_backend kvm = KVMClient("192.168.8.1", "admin", "secret") # 使用Claude分类当前屏幕（运行时自动解析模型） analyzer = ScreenAnalyzer(kvm, make_backend("anthropic")) print(analyzer.classify().phase) # 或完全在本地VLM上运行 - 没有数据离开您的网络 local = make_backend("local", base_url="http://127.0.0.1:1234/v1", model="qwen2.5-vl-7b") analyzer = ScreenAnalyzer(kvm, local) # 等待机器达到GRUB菜单，然后选择第一个条目 analyzer.wait_for_state("grub_menu", timeout=120) kvm.press_key("Enter") ``` 对于最新的未发布代码树： ```bash pip install "kvm-pilot[totp,ws] @ git+https://github.com/DustinTrap/kvm-pilot" ``` ### CLI ```bash kvm-pilot info --host 192.168.8.1 --user admin --ask-passwd # 提示（无回显） kvm-pilot capabilities --profile homelab # 此驱动器支持什么 kvm-pilot snapshot screen.jpg --profile homelab kvm-pilot --timeout 60 power-cycle --profile homelab --dry-run # 记录，不要发送 kvm-pilot eject --profile homelab # 断开虚拟媒体 kvm-pilot events --profile homelab --count 5 # 流事件（'ws'额外） kvm-pilot watch grub_menu --profile homelab \ --backend local --vision-url http://127.0.0.1:1234/v1 --vision-model qwen2.5-vl-7b ``` CLI在任何破坏性操作之前提示确认。使用 `--yes` 跳过自动化中的提示，或使用 `--dry-run` 记录预期操作而不发送它们 - 干燥运行在提示之前短路，因此它永远不会阻塞等待输入。 `--timeout` （HTTP每个请求的超时时间）是一个全局标志，放在子命令之前； `watch` 保留自己的 `--timeout` 用于视觉等待截止日期。 配置文件如 `homelab` 存放在 `~/.config/kvm-pilot/config.toml` 中。有关完整的命令表（每个子命令、所需功能及其门控），请参见 [docs/cli.md](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/cli.md)；有关配置文件格式、每个 `KVM_PILOT_*` 环境变量和优先级的信息，请参见 [docs/configuration.md](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/configuration.md)。 > **GLKVM设置说明：** 在GL.iNet固件上，PiKVM REST API **默认禁用** （每个 `/api/*` 调用404，表现为明显的 `ApiDisabledError`），固件升级可以重新禁用它。在 `/etc/kvmd/nginx-kvmd.conf` 中启用它并使用 `--driver glkvm` / `driver = "glkvm"` 固定驱动程序 - 完整的步骤在 [troubleshooting guide](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/troubleshooting.md#every-api-call-returns-404-glkvm). ## 工具表面，按平面划分 相同的功能协议跨越三个执行平面，因此一个代理工作流可以混合像素、结构化BMC状态和shell访问 - 每个破坏性效果都按类别划分： | 平面 | 读取 | 执行（操作员门控） | |---|---|---| | **KVM - 像素和HID** （PiKVM · GLKVM · BliKVM） | `snapshot` · `classify_screen` · `wait_for_state` · `power_state` · `logs` · `list_virtual_media` | `power` · `type_text` / `press_key` / `send_shortcut` / `mouse` · `calibrate_mouse` · `mount_iso` / `eject` | | **BMC - 结构化状态** （Redfish · IPMI） | `info` · `boot_options` · `logs`（SEL）· 传感器（CLI） | `power` · `set_boot_device` · SOL控制台（CLI `console`） | | **固件 - Intel AMT/vPro** （跨越两个平面） | `info` · `snapshot`（固件BIOS/POST/GRUB）· `boot_options` · `power_state` | `power` · `set_boot_device` · `type`/`mouse` · SOL（`console`）· `amt_enable`（打开SOL/KVM监听器） | | **SSH - 带内和设备** | `ssh_reachable` · `appliance_status` · `access_paths` | `ssh_exec` · `wake`（WoL）· `appliance_reboot` | | **元 - 证据和摄入** | `capabilities` · `support_matrix` · `healthcheck` | `file_firmware_report` | 规范的每个工具参考 - 注释、效果门控、审批生命周期 - 是 [MCP服务器README](https://github.com/DustinTrap/kvm-pilot/blob/main/src/kvm_pilot/mcp/README.md)；CLI涵盖了完整的表面在 [docs/cli.md](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/cli.md)。 ## 状态和成熟度 > **状态：测试版 - 准备好进行更广泛的测试。** （确切的版本位于 [CHANGELOG](https://github.com/DustinTrap/kvm-pilot/blob/main/CHANGELOG.md) 中；使用 `pip install --pre kvm-pilot` 安装。）核心路径已从仅模拟到实时验证：一个GL-RM1PE单元的机群已在两个固件版本上运行 `snapshot`/`healthcheck`/`logs`/`power_state`/`virtual_media`/`info` - 这些功能在发布的轮子中达到 **beta** 成熟度，源自实际运行，从未手动编辑 - 并且Dell iDRAC6已在端到端运行IPMI驱动程序（电源、引导设备、传感器、事件日志、SOL串行控制台）。可以造成伤害的路径已加强：传输永远不会重新发送破坏性请求，MCP审批是有审计跟踪的单次使用收据，每个破坏性效果都有自己的操作员确认门控。最近的测试版添加了远程引导设备控制（Redfish、IPMI和带内 `efibootmgr`）、Wake-on-LAN、一个预Redfish的IPMI驱动程序用于早期的BMC、串行（SOL）控制台、鼠标自动校准和无头原生分辨率GLKVM快照； `kvm-pilot test-report` 将贡献的证据变成一个命令，而固件注册表自我填充（`firmware-check` 自动归档注册表更新）。 > **现在我们需要您的硬件。** PiKVM、其他GLKVM型号和Redfish BMC（iDRAC / iLO / OpenBMC）是矩阵最需要的组合 - 成功 *或* 失败， [硬件报告](https://github.com/DustinTrap/kvm-pilot/issues/new?template=hardware-report.yml) 需要两分钟，而每小时的摄入会完成其余部分。 [Hardware-Compatibility list](https://github.com/DustinTrap/kvm-pilot/wiki/Hardware-Compatibility) 中没有显示为已演练的内容仍然未经验证：期待一些API移动到1.0之前，请注意GL-RM1PE上的远程固件闪存静音 ([#94](https://github.com/DustinTrap/kvm-pilot/issues/94)/[#95](https://github.com/DustinTrap/kvm-pilot/issues/95))，不要将破坏性操作指向您无法承受意外断电的机器。参见 [Compatibility](#compatibility)。  ## 引导阶段检测 视觉分类器将每个截图映射到一个 **阶段** - `bios_menu`、`grub_menu`、`installer_progress`、`login_prompt`、`crash_screen`等。 `wait_for_state()` 轮询屏幕并阻塞，直到请求的阶段出现（或超时触发），因此无人值守的安装成为几个等待操作：  ## 感知模型 视觉是最昂贵的方式来读取屏幕 - 每个帧一个模型调用 - 而大多数它推断的内容（电源状态、引导阶段、实时性、崩溃）也是作为 **字段、事件或文本行** 可用的。 `kvm-pilot`的方向是按层次结构分类：从设备暴露的最便宜信号开始，并通过OCR和视觉模型仅在没有更便宜的信号时进行。  PiKVM/GLKVM客户端已经公开了便宜的一端 - ATX和HID LED、视频信号和分辨率、设备OCR（`?ocr=true`）、日志、Prometheus指标和WebSocket事件流。[功能协议](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/architecture.md)添加 `Logs`、 `BootProgress`、 `Sensors`、 `SerialConsole` 和 `Watchdog` 作为BMC驱动器（Redfish/IPMI）的缝隙，其中引导阶段是结构化枚举（`BootProgress.LastState`）而控制台是串行文本流而不是像素。设备类别几乎是互补的：捕获设备在像素上很强，而BMC在结构化状态和串行文本上很强。 ## 安全模型 电源关闭、硬重置、虚拟媒体连接/断开和图像上传、键盘/鼠标注入（`type_text`、`press_key`、快捷键、点击）、GPIO、引导配置更改和Redfish/IPMI重置被分类为 **破坏性`并通过安全层： - **dry-run** 首先短路 *第一步：* 它记录预期的调用并跳过它 - 确认回调永远不会被调用，因此dry run永远不会阻塞等待输入的意图并跳过它 - 确认回调永远不会被调用，因此干燥运行永远不会阻塞。 - **确认** - 能够否决任何破坏性调用的操作。库的默认设置允许所有操作（因此纯脚本有效）；CLI安装了一个交互式`y/N`提示，除非你传递 `--yes`。  破坏性操作集在`kvm_pilot.safety.DESTRUCTIVE_OPS`中明确定义，因此它是可审计的而不是被猜测的。视觉分类永远不会独立触发破坏性操作 - 您自己连接它们，安全层仍然适用。在MCP方面，每个破坏性 **效果类别** 都需要操作员确认环境门控和每次调用的批准，支持签名单次使用收据的 **信任梯度** (`READ_ONLY` → `DRY_RUN` → 触发器`ALLOW_*`) 在 [MCP服务器README](https://github.com/DustinTrap/kvm-pilot/blob/main/src/kvm_pilot/mcp/README.md) 中绘制。 该软件控制真实硬件，可以关闭或中断正在运行的机器的电源。在将KVM暴露在互联网上之前，请阅读 [SECURITY.md](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/SECURITY.md)。 ## 没有硬编码的模型版本 代码中没有模型版本号。Anthropic后端通过Models API解析最新的视觉支持模型并缓存它；设置`KVM_PILOT_VISION_MODEL`或传递`model=`以固定一个。本地后端使用您在服务器上加载的模型。您可以自定义后端、端点和模型。 ## 与其他客户端的区别 [`pikvm-lib`](https://github.com/guanana/pikvm-lib) 是一个通用的 PiKVM 客户端。`kvm-pilot` 旨在完成不同的任务： - **基于视觉的启动阶段检测** — 根据截图分类 BIOS/GRUB/安装程序/崩溃状态，并带有阻塞式 `wait_for_state` 环路。这是核心功能，`pikvm-lib` 没有等效功能。 - **可插拔的本地或云 VLM** — 在您自己的 GPU 上以零每帧成本运行推理，或在 Claude 上运行。 - **破坏性操作的安全层** （干运行 + 确认）。 - **GLKVM-fork 意识** — 记录 API 启用前提条件和 GL 硬件特殊性，这些特殊性会影响 GL-RM1PE 用户。 - **仅限标准库的客户端核心** — 驱动程序/视觉代码仅导入标准库（捆绑的 MCP 服务器拉取 `mcp` SDK；功能扩展是可选的）。 如果您只想针对库存 PiKVM 编写电源和 HID 脚本，而不需要视觉层，`pikvm-lib` 可能是一个更简单的选择。 在 BMC 方面，[sushy](https://opendev.org/openstack/sushy)、DMTF 的 [python-redfish-library](https://github.com/DMTF/python-redfish-library) 和 [pyghmi](https://opendev.org/x/pyghmi) （IPMI）是成熟的、更完整的 BMC 管理 SDK — 如果您需要帐户/固件/网络配置、EventService 订阅或硬件验证的成熟度，请使用它们。`kvm-pilot` 放弃了这种完整性，以换取跨设备类别（IP-KVM 和 BMC，后面是相同的协议）的统一功能表面、每个破坏性调用的安全层以及在具有像素的设备上的视觉环路。 ## 兼容性 | 设备 | 状态 | |--------|--------| | GL-RM1PE (Comet PoE) | 主要目标 — **实际测试**：在固件 V1.5.1 release2 和 V1.9.1 release1 上验证了读取/健康检查/日志；在 V1.9.1 上验证了快照（在 V1.5.1 上失败，出现明确的错误 — 不可解码的 H.264 帧，[#107](https://github.com/DustinTrap/kvm-pilot/issues/107)/[#151](https://github.com/DustinTrap/kvm-pilot/issues/151)）；远程闪存无效 ([#94](https://github.com/DustinTrap/kvm-pilot/issues/94)/[#95](https://github.com/DustinTrap/kvm-pilot/issues/95))；编码器卡顿 > 1080p ([#107](https://github.com/DustinTrap/kvm-pilot/issues/107)) | | Dell iDRAC6 — IPMI (PowerEdge R710) | **实际测试**：通过 `ipmitool` lanplus（固件 1.95）验证了电源/引导设备/传感器/事件日志（SEL）/SOL 串行控制台 | | Dell Latitude 5411 — Intel AMT/vPro | **实际测试** （AMT 14.1.67）：WS-Man 电源/信息/一次性引导，远程 SOL + KVM 启用，以及 **1920×1080 BIOS/POST 快照通过 KVM 重定向** — 固件屏幕是 HDMI 捕获 KVM 在笔记本电脑上看不到的 | | GL-RM1 (Comet) | 预计适用（相同的固件系列）；未测试 | | PiKVM v3 / v4 | 预计适用（上游 API）；未测试 | | BliKVM | 预计适用（兼容 PiKVM 的 API）；未测试 | | Redfish BMCs (iDRAC7+, iLO, OpenBMC) | 模拟器验证（存储库模拟器 + DMTF sushy-tools 在 CI 中）；正在进行实时 BMC 验证 ([#29](https://github.com/DustinTrap/kvm-pilot/issues/29)) | GL-RM1PE（读取/快照路径）、通过 IPMI 的 Dell iDRAC6 和通过 Intel AMT 的 Dell Latitude 5411 是目前为止运行良好的组合 — 其他所有组合都预计适用，待验证。[硬件兼容性列表](https://github.com/DustinTrap/kvm-pilot/wiki/Hardware-Compatibility) 是按功能记录的权威记录。ATX 电源控制需要将 ATX 适配器连接到目标的前面板接头：在 GL Comet 系列（GL-RM1 / GL-RM1PE）上，这是 GL.iNet 单独销售的 ATX 板（GL-ATXPC），而 PiKVM v3/v4 套件包含 ATX 适配器，BliKVM 套件因型号而异 — 请检查您的型号。没有 ATX 接线，ATX 调用会从设备返回错误。任何硬件上的成功或失败报告对于这个测试版本来说都是需要的 — 请打开一个[硬件报告](https://github.com/DustinTrap/kvm-pilot/issues/new?template=hardware-report.yml)。 ## 架构 `kvm-pilot` 建立在模块化的 **驱动程序插件** 架构上，因此支持可以扩展到许多 KVM/BMC 设备（PiKVM 家族、Redfish BMCs、IPMI BMCs、JetKVM、...）。每个设备仅实现其硬件支持的功能协议；CLI、安全层和视觉子系统保持设备无关性。`make_driver(kind)` 注册表（镜像 `make_backend`）按名称构建驱动程序，并且无硬件的 `FakeDriver` 允许您在没有设备的情况下执行整个环路 — 功能、安全门控、分析器 — 使用 `kvm-pilot capabilities --driver fake`。有关设计和图表，请参见 [docs/architecture.md](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/architecture.md)。 **`RedfishDriver`** (`make_driver("redfish")`) 通过 DMTF Redfish API 与服务器 BMCs 对话 — Dell iDRAC、HPE iLO、Supermicro、Lenovo XCC、OpenBMC — 在一个仅限标准库的客户端中。它展示了为什么功能被分段：BMC 的一套功能与 PiKVM 的功能 **互补** （强于结构化状态 — 电源、引导阶段、传感器、日志、虚拟媒体 — 无键盘/鼠标/截图），并且驱动程序通过遵循 Redfish 超媒体而不是硬编码供应商 ID 来保持可移植： ```python from kvm_pilot.drivers import make_driver bmc = make_driver("redfish", host="idrac.lan", user="root", passwd="…") bmc.get_boot_progress() # 'os_running' — 结构化，无截图 bmc.read_sensors()["temperatures"] bmc.power_off(wait=True) # 映射到目标的实际 ResetType， gated ``` **`IpmiDriver`** (`make_driver("ipmi")`) 通过系统 `ipmitool` 覆盖早于 Redfish 的 BMC（例如 Dell iDRAC6）：电源、引导设备控制、传感器、SEL 事件日志和 SOL 串行控制台（`kvm-pilot console`）。两者都在 CLI 上 — `kvm-pilot info --driver redfish --host idrac.lan …`。BMC 无法提供的功能特定子命令（`type`、`snapshot`、`events`）会干净地失败，而不是崩溃。添加 `--redfish-auth basic` 以获取没有 SessionService 的端点（模拟器或禁用会话身份验证的 BMC）。 **`AmtDriver`** (`make_driver("amt")`) 通过 AMT 的三个原生协议管理 Intel AMT/vPro 笔记本电脑和台式机 — WS-Man（电源/信息/一次性引导）、SOL（`kvm-pilot console`）和 **KVM 重定向** — 全部纯标准库。它是 **第一个具有 `Video` + `HID` 的非 PiKVM 驱动程序**：`snapshot` 在 HDMI 捕获 KVM 看不到启动的笔记本电脑上返回真正的固件级 **BIOS/POST/GRUB 快照**。SOL 和 KVM 监听器通过 WS-Man 远程打开（`kvm-pilot amt enable-sol` / `enable-kvm`），无需 MEBx trip。 ## 文档 完整的用户和开发者文档位于 [`docs/`](https://github.com/DustinTrap/kvm-pilot/tree/main/docs/) （架构、设计决策、Redfish 参考、[故障排除和 FAQ](https://github.com/DustinTrap/kvm-pilot/blob/main/docs/troubleshooting.md)、贡献和安全策略）。[项目维基](https://github.com/DustinTrap/kvm-pilot/wiki) 是自动生成、格式良好的该文件夹的镜像，存储库根目录中包含 [`llms.txt`](https://github.com/DustinTrap/kvm-pilot/blob/main/llms.txt) 文档地图，供 AI 代理使用。 ## 许可证 Apache License 2.0 — 参见 [LICENSE](https://github.com/DustinTrap/kvm-pilot/blob/main/LICENSE) 和 [NOTICE](https://github.com/DustinTrap/kvm-pilot/blob/main/NOTICE)。`kvm-pilot` 是独立的，与 PiKVM 项目、GL.iNet 或 Anthropic 无关；这些名称仅用于兼容性描述。