日常怎么用、常见操作怎么做
1. 界面总览
FoxAgent 没有常驻窗口、没有托盘图标，它对外呈现为四个入口，理解这四处即理解了它的全貌：
| 区域 | 位置 | 用途 |
|---|---|---|
| 命令行 | fox-agent.exe |
运行内核、管理插件、管理服务、自检、查看版本 |
| Web 控制台 | http://127.0.0.1:42101/console/ |
看状态、管插件、看能力清单、按参数声明试跑任意命令 |
| 命令接口 | POST /（HTTP 42101）、TCP 42102、UDP 42103 |
下发控制命令 |
| 查询与管理接口 | GET /health、GET /capabilities、GET /admin/*、GET /blob/{id} |
查看状态、能力、插件清单、命令清单；下载插件上报的大对象（截图 / 文件 / 日志导出） |
配置文件位于数据目录（见第 5 节），核心配置项见第 3 节与《高级配置》。
1.1 Web 控制台
浏览器打开 http://127.0.0.1:42101/console/ 即可使用；页面由内核内嵌（go:embed），不额外起进程、不额外占端口，换台终端也无须部署前端。远端终端把地址换成 http://<终端IP>:42101/console/ 即可（对应端口需放通）。
页面分四块：
| 区块 | 内容 |
|---|---|
| 状态概览 | 内核版本、运行时长、插件「就绪 / 总数」、能力「可用 / 声明」、已注册命令数、三端口监听地址、当前认证方式 |
| 插件 | 插件表（ID / 版本 / 会话域 / 状态 / 启用 / PID / 命令数 / 能力数 / 目录），支持启动、停止、启用、禁用、探测、卸载、重新加载，以及上传或拖拽目录安装新插件 |
| 能力清单 | 可折叠的表格：能力名、所属插件、会话域、当前是否可用、不可用原因 |
| 功能测试 | 选一条命令 → 表单按该命令的参数声明自动生成 → 点「执行」看内核的原始返回 |
「功能测试」的价值在于不需要记参数名与取值范围：参数项、必填与否、数值上下限、枚举选项、说明文字全部来自插件自己上报的声明，插件改了参数，页面刷新后表单自动跟着变。响应区原样展示内核返回的 JSON（成功绿框、失败红框），便于直接对照协议定位问题。
关于令牌：控制台页面本身是静态资源、不含数据，所以能直接打开；但页内每个管理请求都要求令牌。管理接口不接受「本机来源免认证」——否则任意网页都能借浏览器发起跨站请求来操纵插件。首次进入时把
config.json里的auth.token粘进登录框即可，令牌会存在浏览器本地。
2. 逐功能操作
2.1 电源
| 命令 | 参数 | 说明 |
|---|---|---|
power.off |
mac, delay, message |
关机（可延迟，delay 秒 0–600，message 为关机前提示） |
power.reboot |
mac, delay, message |
重启（可延迟，参数同 power.off） |
power.abort |
mac |
取消已计划但尚未执行的关机 / 重启，返回 aborted |
power.uptime |
mac |
查询运行时长，返回 seconds、boot_time |
power.suspend |
mac, mode |
进入睡眠（sleep，默认）或休眠（hibernate） |
- 入口：命令接口，
{"cmd":"power.reboot","mac":"aa:bb:cc:dd:ee:ff"} - 结果：
power.off/power.reboot无data，status为success表示已下发关机 / 重启 - 注意：后台常驻即可完整工作，服务态同样可用
2.2 系统音量
| 命令 | 参数 | 响应 data |
|---|---|---|
volume.get |
mac |
{"volume":50,"muted":false} |
volume.set |
mac, value（0–100） |
- |
volume.mute |
mac, mode（on/off/toggle，默认 toggle） |
{"muted":true} |
volume.up |
mac, step（1–50，默认 5） |
{"volume":55} |
volume.down |
mac, step（1–50，默认 5） |
{"volume":45} |
越界（如 value=150）返回参数非法。
2.3 屏幕开关
| 命令 | 参数 | 说明 |
|---|---|---|
screen.off |
mac |
关闭显示器（DPMS 待机） |
screen.on |
mac |
打开显示器 |
screen.lock |
mac |
锁定当前会话（保持登录，需重新输入凭据解锁） |
2.4 键盘
| 命令 | 参数 | 说明 |
|---|---|---|
input.key.tap |
mac, key, mods |
模拟按键，支持组合键 |
input.key.type |
mac, text |
输入文本 |
input.key.hold |
mac, key, duration, mods |
按住按键一段时间后松开（duration 毫秒，默认 500） |
- 组合键示例：
{"cmd":"input.key.tap","mac":"all","key":"tab","mods":["ctrl","shift"]}表示 Ctrl+Shift+Tab - 支持的按键：
a–z、0–9、f1–f12、enter/space/tab/esc/backspace/delete/insert/home/end/pageup/pagedown/up/down/left/right/capslock/printscreen等；修饰键ctrl/shift/alt/win，均大小写不敏感。
2.5 鼠标
| 命令 | 参数 | 说明 |
|---|---|---|
input.mouse.move |
mac, x, y |
移动到绝对坐标 |
input.mouse.move_relative |
mac, dx, dy |
相对当前位置移动 |
input.mouse.click |
mac, button, count |
单击，left/right/middle（默认 left），count 1–3（默认 1） |
input.mouse.scroll |
mac, scroll, horizontal |
滚动滚轮，scroll 为垂直量（必填），horizontal 为可选水平量 |
input.mouse.drag |
mac, from_x, from_y, to_x, to_y, button, duration |
从起点拖拽到终点（duration 毫秒，默认 300） |
input.cursor |
mac |
查询光标位置，返回 x、y |
input.screen_size |
mac |
查询主显示器分辨率，返回 width、height |
2.6 剪贴板
| 命令 | 参数 | 响应 data |
|---|---|---|
clipboard.write |
mac, text |
- |
clipboard.read |
mac |
{"text":"剪贴板内容"} |
clipboard.clear |
mac |
- |
clipboard.format |
mac |
{"formats":["CF_UNICODETEXT"]} |
2.7 设备发现
无命令，仅应答 UDP 发现请求。请求 / 响应格式见《集成与 API》；探测到的 MAC 为本机真实物理网卡（自动排除虚拟网卡）。
2.8 磁盘用量
| 命令 | 参数 | 响应 data |
|---|---|---|
disk.list |
mac |
JSON 字符串：各分区的总量 / 已用 / 使用率，使用率超 90% 的分区附带告警标记 |
只读命令，无参数可调。用于巡检终端盘满情况，常与定时重启（power.reboot）配合排查「机器越用越慢」。
2.9 屏幕截图
| 命令 | 参数 | 响应 data |
|---|---|---|
screen.capture |
mac, display, format, quality, scale |
JSON 字符串：图像尺寸与 blob_id |
| 参数 | 取值 | 默认 |
|---|---|---|
display |
显示器序号（从 0 起）；-1 表示把所有屏幕拼接成一张 |
0 |
format |
png（无损、体积大）/ jpeg（有损、体积小） |
png |
quality |
JPEG 质量 1–100，仅 format=jpeg 时生效 |
85 |
scale |
缩放比例 0.1–1.0，弱网下可缩小传输量 | 1.0 |
画面本身不放在命令响应里：命令只返回 blob_id，需再经 GET /blob/{id} 下载（需认证），说明见 2.11 末尾。
2.10 文件读取（只读）
| 命令 | 参数 | 响应 data |
|---|---|---|
file.list |
mac, path, limit |
JSON 字符串：目录条目（目录优先、按名称排序）与统计 |
file.stat |
mac, path |
JSON 字符串：元信息；体积 ≤16MB 时附带 sha256 |
file.read |
mac, path, encoding, max_bytes |
JSON 字符串：文件内容，超限时改为大对象引用 |
| 参数 | 取值 | 默认 |
|---|---|---|
path |
绝对路径，必须落在白名单内 | 无（必填） |
limit |
file.list 返回条目数上限 1–2000 |
200 |
encoding |
text（按 UTF-8 文本返回）/ base64（取二进制用） |
text |
max_bytes |
file.read 读取字节上限 1–8388608 |
1048576（1MB） |
- 白名单由
plugins.config["fox.file"].roots配置，为空即拒绝一切访问（见《高级配置》第 3 节）。 - 内容超过 512KB 时不内联，改为返回
blob_id，经GET /blob/{id}下载。 - 本插件只读：没有写入、删除、改名命令。
2.11 日志查看（只读）
| 命令 | 参数 | 响应 data |
|---|---|---|
log.list |
mac |
JSON 字符串：日志文件清单（含体积与修改时间） |
log.tail |
mac, file, lines, filter |
JSON 字符串：尾部行与统计 |
log.export |
mac, file |
JSON 字符串：整份文件的 blob_id 与体积 |
| 参数 | 取值 | 默认 |
|---|---|---|
file |
日志文件绝对路径，必须落在白名单内（可先用 log.list 取） |
无（必填） |
lines |
log.tail 读取的尾部行数 1–2000 |
200 |
filter |
可选关键字，只在取到的尾部行中保留包含该串的行，最长 128 字符 | 无 |
- 白名单由
plugins.config["fox.log"].paths配置，默认指向内核自身日志目录<数据目录>/logs，装上即可用；为空即拒绝一切访问。 log.export单文件上限 60MB，超出直接拒绝。- 本插件只读：没有删除或改写日志的命令。
- 大对象通道说明：
screen.capture、file.read（超 512KB）、log.export的正文都不在命令响应里，只返回blob_id；需再请求GET /blob/{id}流式下载（需令牌或证书）。原因是内核读取插件输出有单行 1MB 上限，大内容必须走独立通道。
2.12 插件管理
命令行方式：
fox-agent plugin list 列出已发现插件
fox-agent plugin install <路径> 安装插件（需管理员 / root）
fox-agent plugin remove 卸载插件（需管理员 / root）
fox-agent plugin enable 启用插件（改写 plugin.json，持久）
fox-agent plugin disable 禁用插件（改写 plugin.json，持久）
fox-agent plugin start 启动插件（仅本次运行，需内核在线）
fox-agent plugin stop 停止插件（仅本次运行，需内核在线）
fox-agent plugin reload 通知内核重新加载插件
fox-agent plugin doctor 探测指定插件的能力可用性
fox-agent doctor 内核自检
enable/disable 是持久的（改配置文件），start/stop 只对本次运行生效。
Web 控制台方式（等价，但不用记插件 ID）：打开 http://127.0.0.1:42101/console/，插件表每行末尾就是「启动 / 停止 / 启用或禁用 / 探测 / 卸载」按钮；插件表上方的「安装插件…」按钮（或把插件目录直接拖到虚线框里）等价于 plugin install，「重新加载插件」等价于 plugin reload。
2.13 服务管理（Windows）
fox-agent service status 查看服务状态（无需管理员权限）
fox-agent service start 启动服务
fox-agent service stop 停止服务
fox-agent service install 注册服务并设为「自动」启动（需管理员）
fox-agent service uninstall 停止并删除服务（需管理员）
安装包已代做注册与首次启动，本节命令用于日常起停与排障。服务异常退出时由系统按恢复策略自动重启，无需人工介入。
3. 参数说明
| 参数 | 含义 | 取值范围 | 默认值 |
|---|---|---|---|
cmd |
命令名 | 见第 2 节命令表 | 无（必填） |
mac |
目标机器 MAC；all 表示广播 |
aa:bb:cc:dd:ee:ff / aa-bb-.. / aabb.. / all |
无（必填） |
token |
访问令牌 | 配置文件 auth.token |
无（非回环必填；高危命令即便来自回环也必填） |
value |
数值参数 | 音量 0–100 | 无 |
mode |
枚举参数 | sleep/hibernate；on/off/toggle |
依命令（多为默认值） |
text |
文本参数 | 键盘输入 / 剪贴板内容 | 无 |
key / mods |
按键与修饰键 | 见 2.4 | 无 |
x / y |
鼠标屏幕坐标 | 整数 | 无 |
button |
鼠标按键 | left/right/middle |
left |
scroll |
滚轮格数 | 整数，正=上滚 | 无 |
path / file |
文件或目录路径（file.* / log.*） |
绝对路径，须在插件白名单内 | 无（必填） |
limit |
目录条目数上限（file.list） |
1–2000 | 200 |
encoding |
文件内容编码（file.read） |
text / base64 |
text |
max_bytes |
读取字节上限（file.read） |
1–8388608 | 1048576 |
lines |
日志尾部行数（log.tail） |
1–2000 | 200 |
filter |
日志关键字过滤（log.tail） |
字符串，最长 128 字符 | 无 |
display |
显示器序号（screen.capture） |
-1（拼接全部屏幕）/ 0 起整数 |
0 |
format |
图像格式（screen.capture） |
png / jpeg |
png |
quality |
JPEG 质量（screen.capture） |
1–100 | 85 |
scale |
截图缩放比例（screen.capture） |
0.1–1.0 | 1.0 |
MAC 守卫语义：all 放行；与本机 MAC 匹配放行；不匹配返回 skipped（不执行）；本机 MAC 探测失败返回 error（不冒险执行）。
4. 日常维护动作
| 周期 | 动作 |
|---|---|
| 每日 | 无需人工干预，程序常驻自管；Windows 下服务异常退出会自动重启 |
| 每周 | fox-agent service status 确认服务在运行；抽查一台终端的 /health 与 /capabilities，确认在线与能力齐全 |
| 每周 | fox-agent plugin list 核对插件状态，确认无 Failed；或打开控制台直接看插件表 |
| 变更前 | 修改配置后 fox-agent doctor 自检，再 fox-agent service stop / start 重启服务 |
| 升级时 | 覆盖安装 → 访问 /capabilities 复核插件全部加载 |
5. 数据与文件位置
| 类别 | Windows | Linux |
|---|---|---|
| 安装目录（含官方插件） | C:Program FilesFoxAgent |
/opt/FoxAgent/ |
| 数据目录（配置 / 令牌 / 第三方插件） | %ProgramData%FoxAgent |
/var/lib/FoxAgent/ |
| 配置文件 | %ProgramData%FoxAgentconfig.json |
/var/lib/FoxAgent/config.json |
| 服务运行日志 | %ProgramData%FoxAgentlogskernel.log（超 8 MiB 轮转为 kernel.log.1） |
/var/lib/FoxAgent/logs/kernel.log（服务态运行时有） |
| TLS 证书 | %ProgramData%FoxAgent ls |
/var/lib/FoxAgent/tls/ |
| 第三方插件目录 | %ProgramData%FoxAgentplugins |
/var/lib/FoxAgent/plugins/ |
配置文件权限被收紧为仅所有者可读写；卸载安装包不会删除数据目录，避免升级后认证信息丢失。
扫码在手机上打开，再用微信右上角的「···」发送给朋友或分享到朋友圈。