Softagent Control

SoftAgent 控制技能

SoftAgent 是运行在被控 Windows PC 上的轻量代理，通过 UDP（默认端口 6500）接收 原子文本/JSON 指令并回执。本技能教你（上层 AI agent）如何安全、正确地驱动它。

> SoftAgent 自身不含 LLM，也不加载本技能；本技能是给你（编排方）用的程序性知识。 > 编排逻辑在你这一侧——SoftAgent 只执行单条原子指令。

何时使用

需要远程控制展厅 / 被控 Windows PC 时：

• 电源：开机后唤醒（WoL）、关机、重启、注销、锁屏、取消延时关机。
• 音量：调高 / 调低 / 静音。
• 进程守护：立即拉起或停止某个被守护程序（按稳定 id）。
• 状态：查询设备在线情况、IP/MAC、音量、守护项状态。
• 键盘：向前台窗口模拟按键（如刷新 F5）。

第一步：发现能力（务必先做）

不要凭记忆假设指令集。先向目标发 describe，获取实时能力清单（JSON）：

python scripts/send_command.py  6500 describe

回执是 { "commands": [ { name, description, risk, requiresConfirm, parameterSchema } ] }。 据每条的 risk 与 requiresConfirm 决定是否需要确认 / 延时执行。完整能力面与字段含义见 [references/commands.md](./references/commands.md) 与 [references/protocol.md](./references/protocol.md)。

如何调用

• 文本指令：verb 或 verb:arg，例如 volup、wol:AA-BB-CC-DD-EE-FF、shutdown:30。
• JSON 指令：以 { 起始且含 cmd 字段，例如 {"cmd":"shutdown","delay":30}。
• 目标：:，端口默认 6500。
• 回执解读：
• ok: —— 成功（如 ok:pong、ok:volup）。
• err: —— 失败，` 指明原因（如 wol.invalidMac、power.invalidDelay、dispatch.unknownVerb`）。
• JSON 对象 —— 带数据的回执（describe 能力清单、discover 心跳快照）。

发送与收回执可直接用脚本：

python scripts/send_command.py 192.168.1.50 6500 "ping"
# -> ok:pong

安全实践（关键）

1. Destructive 指令必须确认：shutdown / reboot / logoff 的 risk=Destructive、

requiresConfirm=true。执行前取得人工/策略确认。

1. 关机/重启优先用"延时 + 可取消"：发 shutdown:60 而非 shutdown，给出反悔窗口；

误操作时立刻发 cancelshutdown 取消。

1. 优先用稳定 id 而非 index：run:db-player / stop:db-player，避免 GUI 列表序号漂移。
2. 多步操作逐条执行并核对每步回执：不要假设成功；每发一条都读回执，失败则停下分析（如

err:...、超时无回执可能是主机离线或网络未就绪）。

1. 明文无鉴权：v1 协议无加密/鉴权，仅在可信内网使用。

常见工作流（编排在你侧，设备侧只执行原子指令）

开馆（唤醒并校验）

1. wol: 唤醒主机（目标需开启 WoL）。
2. 轮询 discover 或 ping，直到回执表示主机上线（网络就绪可能需要数十秒，按周期重试）。
3. discover 读快照，确认 guards 中关键程序为 running；若某项非 running，发 run: 拉起后再次 discover 校验。
4. 按需 volup/voldown 调到合适音量。

闭馆（安全关机）

1. discover 确认无未保存的关键任务。
2. shutdown:60 排定 60 秒后关机（给反悔窗口）。
3. 如需取消：cancelshutdown。

异常恢复（某守护程序崩溃）

1. discover 发现某 guard 为 crashed 或 gaveup。
2. run: 重新拉起。
3. 再 discover 校验回到 running；若仍失败，记录并上报人工处理。

启动编排（浏览器/终端/任意程序）

• 打开浏览器到指定网址：openurl:https://example.com。
• 开终端进目录并预置命令、开 N 窗（JSON 报文）：

{"cmd":"launchterm","target":"powershell","workingDir":"D:\\proj","preCommand":"claude --dangerously-skip-permissions","count":3}

• 起任意程序：{"cmd":"launch","target":"C:\\app.exe","args":["--flag"],"asAdmin":true}。
• 触发界面里定义好的命名启动档：launchprofile:。
• 成功回 JSON {requested,started,pids,warnings}；started 导入；成功回 ok:license（重启 SoftAgent 后生效），失败回 err:license.（如 license.DeviceMismatch/license.Tampered/license.AlreadyExpired）。授权码与设备 ID 绑定（设备 ID 见 App「设置 → 授权与版本」或心跳）。

1. 过期优雅回落：授权过期后自动回落免费版，基础控制（音量/电源/锁屏/唤醒/键盘/手动 run·stop 等）始终可用。

> 典型分档：改 IP、UAC/边缘手势/启动修复、reboot:firmware、启动编排（launch/openurl/launchterm/launchprofile）、守护自愈、多受管程序 = 标准版及以上；基础控制 = 免费版。以 describe 实际返回为准。

参考资料

• [references/commands.md](./references/commands.md)：完整指令字典（verb / 参数 / risk / requiresConfirm / 错误码）。
• [references/protocol.md](./references/protocol.md)：报文格式、回执、限流、心跳、发现、guard 状态值域、agentId/主网卡规则。
• scripts/send_command.py：UDP 发送 + 收回执小工具。

> references/ 内容与仓库 spec/ 同名文件保持一致（由 CI 同步测试保障），是设备侧协议的权威镜像。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: softcontrol-io
• Source: softcontrol-io/softagent-skill
• License: Apache-2.0
• Homepage: https://softcontrol.io/en/product/softagent

Install and usage instructions live in the source repository linked above.