Agent Skill + language-neutral protocol contract for controlling exhibition-hall Windows PCs. 让 AI agent 安全地控制展厅 Windows 主机的 Agent Skill 与语言中立协议契约。
This repository contains two things — and deliberately not the SoftAgent implementation source:
| Directory | What it is |
|---|---|
skills/softagent/ |
An Agent Skill following the agentskills.io open standard. Teaches an AI agent how to drive a SoftAgent host correctly and safely. |
spec/ |
The language-neutral protocol contract: command dictionary, message format, heartbeat & discovery, JSON Schemas. |
SoftAgent is a lightweight agent installed on managed Windows PCs in exhibition halls, museums, retail chains and unattended kiosks. It receives atomic text or JSON commands over UDP (default port 6500) and returns receipts.
- System control — shutdown / reboot / logoff / lock / volume / key simulation / Wake-on-LAN
- Process guarding — remote start-stop of managed programs, plus automatic restart after a crash (exponential backoff + rate limiting)
- Scheduling — cron, boot-delay and pre-shutdown triggers, executed locally so they fire even without network
- Device control — PJLink to projectors, raw TCP / UDP / HTTP to players and processors
- Status reporting — periodic heartbeat so the control side knows it is alive
SoftAgent is a pure actuator. It embeds no LLM and performs no on-device orchestration. The AI "brain" lives upstream — that's you, loading this Skill.
Product page and free download → https://softcontrol.io/en/product/softagent
Two practical reasons:
- The protocol contract is the single source of truth. Our .NET implementation is CI-enforced against
spec/— the command set, risk levels and parameter schemas must match exactly, or the build fails. Publishing it means you can write your own control client against it without worrying about stale docs. - AI-driven device control is becoming normal. Rather than have everyone start from packet captures, here is the procedural knowledge written down — including which commands are destructive, which need confirmation, and why shutdown should always be "delayed + cancellable".
# 1. Discover capabilities first — never assume the command set from memory
python skills/softagent/scripts/send_command.py 192.168.1.50 6500 describe
# 2. Connectivity check
python skills/softagent/scripts/send_command.py 192.168.1.50 6500 ping
# -> ok:pong
# 3. Safely test a shutdown (60s delay, cancellable at any time)
python skills/softagent/scripts/send_command.py 192.168.1.50 6500 shutdown:60
python skills/softagent/scripts/send_command.py 192.168.1.50 6500 cancelshutdownDrop skills/softagent/ into your agent's skills directory. The Skill instructs the agent to:
- Always start with
describeto fetch the live capability list rather than assuming; - Respect each command's
risk(Safe/Disruptive/Destructive) andrequiresConfirmflags; - Prefer delayed + cancellable for destructive actions;
- Address guarded programs by stable
id, not by list index; - Verify every receipt rather than assuming success.
Three ready-made workflows are included: opening (wake and verify), closing (safe shutdown), and recovery (restart a crashed guarded program, then re-verify).
| Shape | Meaning |
|---|---|
ok:<code> |
Success — e.g. ok:pong, ok:volup |
err:<code> |
Failure — <code> states the reason, e.g. dispatch.unknownVerb, power.invalidDelay |
| JSON | Data-bearing receipt — e.g. the describe capability list, the discover status snapshot |
Full command dictionary → spec/commands.md
Message, heartbeat and discovery format → spec/protocol.md
The v1 protocol is plaintext and unauthenticated. Use it on a trusted LAN only.
Never port-forward SoftAgent's listening port to the public internet — its capability set is equivalent to "can shut down and can execute programs". For remote operations use a VPN, or have the device dial out.
SoftAgent has a free tier that is permanent, not a time-limited trial. The first install automatically starts a 30-day trial with the full enterprise feature set; when it expires the software gracefully falls back to the free tier and keeps all your configuration.
The free tier includes basic system control, heartbeat reporting, device-control commands (PJLink / TCP / UDP / HTTP), 2 managed programs, 2 process guards (with complete crash recovery), and 2 scheduled tasks.
How we fund it: Standard/Enterprise licences and exhibition-hall integration projects. The free tier isn't bait — it does real work, and we run it in our own projects.
- Product & download — https://softcontrol.io/en/product/softagent
- SoftControl ecosystem — https://softcontrol.io/en
- Hands-on tutorials (Chinese) — https://qifujun.vip/guide/s7/s7-softagent-yuancheng-guankong-shizhan/
两样东西 —— 并且刻意不包含 SoftAgent 的实现源码：
| 目录 | 内容 |
|---|---|
skills/softagent/ |
符合 agentskills.io 开放标准的 Agent Skill，教 AI agent 怎么正确、安全地驱动一台 SoftAgent 主机 |
spec/ |
语言中立的协议契约：指令字典、报文格式、心跳与发现机制、JSON Schema |
SoftAgent 是装在展厅、展馆、连锁门店、无人值守终端等场所的被控 Windows 电脑上的轻量代理，通过 UDP（默认 6500）接收原子文本或 JSON 指令并回执。
- 系统控制 —— 关机 / 重启 / 注销 / 锁屏 / 音量 / 键盘模拟 / 网络唤醒
- 程序守护 —— 受管程序的远程启停，以及崩溃后自动拉起（带指数退避与时间窗限次）
- 定时任务 —— 定点、开机后延时、关机前三种触发，在本机执行，断网也照常触发
- 设备控制 —— 直接给 PJLink 投影机、TCP / UDP / HTTP 播放器发指令
- 状态上报 —— 周期心跳，让控制端知道它还活着
SoftAgent 是纯执行器，不内嵌 LLM、不在设备侧做编排。AI「大脑」住在上层——也就是加载了本 Skill 的你。
产品页与免费下载 → https://softcontrol.io/zh/product/softagent
两个很实际的原因：
- 协议契约是单一事实来源。 我们自己的 .NET 实现由 CI 强制校验与
spec/一致——指令集合、风险等级、参数 schema 必须完全对齐，否则构建失败。把它公开，意味着你可以放心照着它写自己的控制端，不用担心文档过期。 - AI 驱动的设备控制正在变成常态。 与其让每个人从抓包开始摸索，不如直接给出一份写好的程序性知识——包括哪些指令是破坏性的、哪些必须先确认、关机为什么要用「延时 + 可取消」。
# 1. 先探测能力（务必先做，不要凭记忆假设指令集）
python skills/softagent/scripts/send_command.py 192.168.1.50 6500 describe
# 2. 连通性测试
python skills/softagent/scripts/send_command.py 192.168.1.50 6500 ping
# -> ok:pong
# 3. 安全地试一次关机（60 秒后执行，随时可取消）
python skills/softagent/scripts/send_command.py 192.168.1.50 6500 shutdown:60
python skills/softagent/scripts/send_command.py 192.168.1.50 6500 cancelshutdown把 skills/softagent/ 放进你的 agent 的 skills 目录即可。Skill 会要求 agent：
- 第一步永远是
describe，获取实时能力清单，而不是凭记忆假设； - 遵守每条指令的
risk（Safe/Disruptive/Destructive）与requiresConfirm标注； - 破坏性动作优先用延时 + 可取消，给出反悔窗口；
- 守护项按稳定
id寻址，不要用列表序号（序号会随拖拽漂移）； - 逐条核对回执，不假设成功。
Skill 里还给了三个现成的工作流：开馆（唤醒并校验）、闭馆（安全关机）、异常恢复（守护程序崩溃后拉起并复验）。
| 形态 | 含义 |
|---|---|
ok:<code> |
成功，如 ok:pong、ok:volup |
err:<code> |
失败，<code> 指明原因，如 dispatch.unknownVerb、power.invalidDelay |
| JSON | 带数据的回执，如 describe 能力清单、discover 状态快照 |
完整指令字典 → spec/commands.md
报文、心跳与发现格式 → spec/protocol.md
v1 协议是明文、无鉴权的，仅可在可信内网使用。
绝不要把 SoftAgent 的监听端口映射到公网——它的能力等同于「能关机、能执行程序」，暴露出去就是敞开的后门。需要远程运维请走 VPN，或让设备主动往外连。
SoftAgent 提供免费版，长期可用，不是限时试用。首次安装自动开启 30 天试用（等同企业版全集），到期后自动回落免费版继续用，配置全部保留。
免费版包含：基础系统控制、心跳上报、设备控制指令（PJLink / TCP / UDP / HTTP）、2 个受管程序、2 项程序守护（含完整崩溃自愈）、2 个定时任务。
我们靠什么挣钱： 标准版 / 企业版授权，以及展厅集成项目本身。免费版不是引流噱头，它确实能独立干活——我们自己的项目里也在用。
- 产品页与下载 —— https://softcontrol.io/zh/product/softagent
- SoftControl 生态 —— https://softcontrol.io/zh
- 上手实战教程 —— https://qifujun.vip/guide/s7/s7-softagent-yuancheng-guankong-shizhan/
- 展厅运维系列教程 —— https://qifujun.vip/guide/
Issues and PRs are welcome, particularly for:
- Corrections or clarifications to the protocol documentation
- Client implementations in other languages (Rust, Go, Node.js …)
- Improvements to the Agent Skill's workflows and safety guidance
Note that skills/softagent/references/ mirrors spec/ by design — the Agent Skill standard expects references to be self-contained. If you change one, change both.