前言¶

在 Cursor、Claude Code 等环境里，Agent 擅长读写代码和跑终端命令，但一旦任务落到「切窗口、调音量、点界面、读串口、拉 Home Assistant」这类本机操作，往往只能给你一串建议，真正动手还要你自己来。下面介绍的 System Controller，是 SkillHub 上由 @user_e02e04b8 发布的 Linux 系统控制 Skill（列表页名称为 Linux System Controller，包内 Metadata 名称为 system-controller）。它用一组可独立调用的 Python CLI，把窗口、进程、硬件、串口、IoT 和 GUI 自动化串成统一入口，让 Agent 按 SKILL.md 里的规则直接执行脚本，而不是停留在口头指导。

任务线索中的官方地址 https://api.skillhub.cn/user_e02e04b8/system-controller 当前以 HTTP 405 响应，无法直接拉取正文；下文功能、命令与依赖以 SkillHub 安装说明，以及 360 安全技能中心同步的同名 Skill 文档为准。人类可读的 SkillHub 列表页为：https://skillhub.cn/skills/user_e02e04b8/linux-system-controller。

这是什么¶

System Controller 的定位是 Linux 系统统一控制接口：支持桌面应用、系统硬件、串口设备和 IoT 平台的综合控制。发布方为 SkillHub 用户 user_e02e04b8；在 SkillHub 分类为 it-ops-security（IT 运维与安全）。平台侧展示约 470 次下载（以你提供的 SkillHub 统计为准）。

整体链路可以概括为：用户自然语言请求 → Agent 理解意图 → 调用 scripts/ 下对应 Python 脚本 → 在本机完成系统操作。

核心功能¶

Skill 将能力拆成 六个模块，每个模块对应一个独立 CLI 脚本，脚本之间无相互依赖。

Window Manager：基于 xdotool、wmctrl，支持 list、activate、close、minimize、maximize、resize、move 等；文档要求先 list 再关闭或聚焦窗口。

Process Manager：list、kill、start、info、system；结束进程前应先按名称查询并确认。

Hardware Controller：音量（get/set/mute/unmute）、屏幕亮度、电源（lock/sleep/hibernate/shutdown/restart）、网络与 WiFi、USB 列表等；关机、重启、睡眠等破坏性操作需用户确认。

Serial Communication：列出端口、发送/接收、chat、监听；操作前应先 list 确认端口。

IoT Controller：Home Assistant REST（需 URL 与 token）、通用 HTTP GET/POST/PUT；智能家居场景由用户提供端点与凭证。

GUI Controller：鼠标移动/点击/拖拽/滚动、键盘输入与组合键、全屏/区域/活动窗口截图、OCR（依赖 tesseract-ocr）、按模板或颜色查找并点击等；启用 pyautogui 故障保护（鼠标移到屏幕角落可中止）。

当请求的设备或软件不在上述模块内时，SKILL.md 建议依次尝试：进程启动 → 窗口列表 → 全屏截图 → OCR → 图像点击 → 鼠标键盘直连 → HTTP API → USB/串口列表，再说明限制。

安装与启用¶

环境要求¶

• 操作系统：Linux（支持 X11 / Wayland）
• Python：3.6+
• 系统工具（文档列出的必需项）：xdotool、wmctrl、tesseract-ocr、alsa-utils

Metadata 中的依赖声明如下（安装 Skill 后按说明在本机满足即可）：

{
  "python": [
    "pyserial>=3.5",
    "requests>=2.28.0",
    "pyautogui>=0.9.54",
    "pillow>=9.0.0",
    "pytesseract>=0.3.10"
  ],
  "system": [
    "apt-get update && apt-get install -y xdotool wmctrl tesseract-ocr alsa-utils"
  ]
}

通过 SkillHub 安装¶

先按 SkillHub 安装与优先源配置 检查或安装 skillhub CLI。安装 Skill 时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 且可能不被识别。

官方给 Agent 的安装提示词为：

请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_e02e04b8/linux-system-controller`。

等价的手动 CLI 示例（将 <skills 目录> 换成你当前客户端的路径）：

command -v skillhub && skillhub --version
skillhub install @user_e02e04b8/linux-system-controller --dir <skills 目录>

常见客户端 skills 目录（摘自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

安装完成后，在对话中让 Agent 在涉及本机控制的任务里读取该 Skill 的 SKILL.md，并按其中的安全规则调用脚本。

其他渠道（可选）¶

360 安全技能中心提供同名 linux-system-controller 条目，并给出另一条安装话术：npx secure-skills-cli add linux-system-controller。若你以 SkillHub 包 @user_e02e04b8/linux-system-controller 为主源，建议优先使用上一节的 skillhub install，避免混用不同发布源时的版本差异。

典型用法¶

所有脚本统一采用「子命令 + 参数」模式，从 Skill 根目录执行：

python3 scripts/<script_name>.py <action> [flags]

下面几组示例均来自官方 SKILL 文档，可直接在装好依赖的机器上复现。

窗口与进程

python3 scripts/process_manager.py start "gedit"
python3 scripts/window_manager.py list
python3 scripts/window_manager.py activate --title "WeChat"
python3 scripts/process_manager.py kill --name gedit

硬件

python3 scripts/hardware_controller.py volume set --level 50
python3 scripts/hardware_controller.py volume mute
python3 scripts/hardware_controller.py screen brightness --level 30
python3 scripts/hardware_controller.py power lock

串口

python3 scripts/serial_comm.py list
python3 scripts/serial_comm.py send --port /dev/ttyUSB0 --data "LED_ON"

Home Assistant（需替换 URL 与 token）

python3 scripts/iot_controller.py homeassistant --url <HA_URL> --token <TOKEN> list
python3 scripts/iot_controller.py homeassistant --url <HA_URL> --token <TOKEN> on --entity-id light.living_room

GUI 与 OCR

python3 scripts/gui_controller.py screenshot full
python3 scripts/gui_controller.py mouse click --x 500 --y 300
python3 scripts/gui_controller.py keyboard type --text "Hello World"
python3 scripts/gui_controller.py visual ocr

更完整的子命令说明在 Skill 包内的 references/command_reference.md。

适用场景与注意¶

适合谁

• 在 Linux 工作站上用 Agent 做运维、自动化测试、桌面辅助操作的用户
• 需要把窗口/进程/硬件/串口/智能家居/GUI 合成一条对话工作流，而不是手写零散 shell 的团队

限制与风险

1. 平台：面向 Linux 图形桌面；Wayland 下部分 xdotool 能力可能受限，需在目标环境实测。
2. 安全：Skill 明确要求对关机、重启、杀进程、关窗口、禁用网卡等操作先确认；GUI 脚本会影响当前屏幕任意区域，不确定时先截图。
3. 权限：音量、网络、电源、串口设备通常需要相应用户权限或 udev 规则。
4. IoT：Home Assistant 与 HTTP 调用会把请求发到用户提供的地址，token 与内网地址不要写进公开仓库。
5. 依赖：OCR 质量取决于 tesseract-ocr 与屏幕分辨率；图像匹配需自备模板文件路径。

结尾¶

System Controller 把 Linux 上常见的「桌面 + 硬件 + 串口 + IoT + GUI」控制拆成六个独立 CLI，并配上 Agent 侧的执行与安全规则，适合作为 it-ops-security 类 Skill 挂在 Cursor 等客户端上，用自然语言驱动本机操作。官方 API 入口：https://api.skillhub.cn/user_e02e04b8/system-controller；列表与安装说明亦可从 https://skillhub.cn/skills/user_e02e04b8/linux-system-controller 与 https://skillhub.cn/install/skillhub.md 进入。