软件介绍

每个软件做什么，适合什么现场

1. 它是什么

FoxAgent 是一个面向终端的远程控制代理。它常驻在终端电脑的后台，接收来自第三方系统下发的指令，并在本机执行系统级操作：关机、重启、调节音量、开关屏幕、模拟键鼠、读写剪贴板、应答设备发现，以及查询设备信息、进程、磁盘与日志、抓取屏幕截图等。

架构上它采用「薄内核 + 全外置插件」。内核只负责五件事——协议收发、进程托管、指令路由、参数校验、事件分发，本身不包含任何业务性的平台能力；所有具体能力都以独立插件的形式外挂，每个插件可以单独安装、启用、停止、卸载。因此「这台机器能做什么」不是写死的，而是由当前装了哪些插件决定，程序会通过能力清单接口如实汇报。

指令入口有三个，且完全等价：HTTP（默认 42101）、TCP（默认 42102，每行一条 JSON）、UDP（默认 42103，单包一条 JSON）。同一条命令走任何一个入口，参数校验、MAC 守卫与响应结构完全一致。

它自 V3.0.1 起以 Windows 系统服务的方式托管（服务名 FoxAgent，启动类型「自动」，带崩溃自动重启），不需要任何人登录即可随开机常驻；音量、屏幕、键鼠、剪贴板这类天然依赖用户桌面的能力，由内核跨会话创建到当前登录用户的会话中运行，因此服务方式与交互能力可以兼得。同时它自带一个本机 Web 控制台（http://127.0.0.1:42101/console/），无需安装任何客户端：打开即看内核状态、插件列表与能力清单，并可在「功能测试」里按插件声明的参数直接试跑任意一条命令。

2. 能力边界

能做什么

• 电源：立即关机、立即重启、取消待执行关机、查询开机时长、休眠 / 睡眠
• 音量：查询音量与静音状态、设置音量（0–100）、切换静音、按步长增减
• 屏幕：关闭显示器（DPMS 待机）、打开显示器、锁定工作站
• 键鼠：模拟单键与组合键、输入文本、长按、移动与相对移动鼠标、单击与连击、滚动与横向滚动、拖拽，以及查询光标位置与屏幕分辨率
• 剪贴板：写入文本、读取文本、清空、查询可用格式
• 设备发现：应答 UDP 发现请求，返回本机真实物理网卡 MAC
• 设备信息：查询主机名、操作系统与 CPU、内存、磁盘布局、网卡 IP
• 进程：列出进程（可按名称过滤、排序、取前 N 条）、结束指定进程
• 校时：读取本机时间、设置系统时间（支持 dry_run 预演）
• 桌面提示：弹出系统通知（标题 / 正文 / 级别 / 时长可配）
• 磁盘：查询各分区容量与用量告警
• 截图：多屏抓图，返回 blob_id，经 GET /blob/{id} 下载
• 文件：列目录、查元信息、读文件内容（只读，受路径白名单限定）
• 日志：列出日志文件、查看尾部内容、导出下载（只读，受路径白名单限定）
• 可被第三方授权调用：少量终端时第三方可直接控制单台；大量终端时命令交由上层（Agent Server）统一路由
• 以系统服务托管：Windows 版注册为服务 FoxAgent 随开机自启，异常退出自动重启，无需用户登录
• 自带本机 Web 控制台：查状态、管插件（启停 / 持久启停 / 探测 / 卸载 / 上传安装）、看能力清单、按 schema 试跑任意一条命令

明确不做什么

• 不播放音视频、不展示内容页（那是 FoxPlayer / FoxDisplay 的事）
• 不管理授权与计费，不自带账号体系（授权由令牌 / 证书 / 签名承担）
• 不在无人登录时硬撑桌面类命令：没有登录用户会话时，交互类能力如实上报不可用并给出原因，不会静默失败
• 不提供常驻窗口与托盘图标；它的可视界面只有那个「用到才打开」的 Web 控制台

3. 与其他 Fox 软件的关系

需要「让屏幕播一段视频」用 Player，需要「让机器自己重启」用 Agent。它们可以装在同一台机器上，各司其职、互不越界。

4. 适用与不适用

适合

• 展厅、展馆、会议室、查询终端等设备分散、需要远程统管的现场
• 有中控系统或业务平台，需要把「开 / 关 / 切 / 调」等动作落到终端的场景
• 需要自动发现并识别网内终端的场景
• 内网、离线环境（全程不依赖公网）
• 终端长期无人操作、且需要「登录后即在、不登录也在」的服务化托管场景

不适合

• 需要播放内容或展示页面的场景（应叠加 Player / Display）
• 终端长期无人登录、且必须远程操作键鼠 / 剪贴板 / 屏幕 / 音量 / 桌面提示 / 截图的场景：这些能力依附用户会话，无人登录时确实不可用
• 需要账号权限体系、按人分配权限的场景

5. 常见误解澄清

1. 「MAC 是授权凭据」 —— 不是。MAC 只是寻址标识，用来判断这条命令是不是发给本机的；真正的授权由访问令牌、客户端证书或 HMAC 签名承担。
2. 「装了就能用键鼠 / 音量」 —— 不一定。键盘、鼠标、剪贴板、屏幕、音量属于用户交互桌面能力，必须有登录用户的桌面会话才能真正生效。以 Windows 服务方式运行时（内核处于 Session 0，看不到用户桌面），它会把这类插件跨会话创建到当前登录用户的会话中，因此大多数服务态部署下这些能力照常可用；只有在无人登录时才不可用——这属于预期行为（没有可依附的桌面），不是故障。
3. 「能力清单是固定的几项」 —— 不是。能力清单完全由已注册插件派生（当前官方插件 14 个），停用或卸载某个插件，对应能力随即从清单中消失，避免上层误以为能调用。
4. 「端口和旧版冲突」 —— 不冲突。旧版 ifu Agent 占用 42000–42002，FoxAgent 使用 42101–42103，同机可并行部署与灰度切换。
5. 「没有界面就不好排查」 —— 现在有了。内核自带 Web 控制台 http://127.0.0.1:42101/console/，登录令牌后可在页面上直接看插件状态、能力可用性，并用「功能测试」按参数声明试跑任意命令，不必手写 curl。注意：管理接口不接受「本机来源免认证」，因为任意网页都能借浏览器发出跨站请求，所以控制台必须填一次令牌。

分享