# Softagent Control

> 控制展厅/被控 Windows PC 的开关机、重启、注销、锁屏、音量、网络唤醒(WoL)、键盘模拟，以及拉起/守护程序与查询设备状态。当需要远程操作一台或多台运行 SoftAgent 的 Windows 主机（通过 UDP 发文本/JSON 指令）时使用。

- **Type:** Skill
- **Install:** `agentstack add skill-softcontrol-io-softagent-skill-softagent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [softcontrol-io](https://agentstack.voostack.com/s/softcontrol-io)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [softcontrol-io](https://github.com/softcontrol-io)
- **Source:** https://github.com/softcontrol-io/softagent-skill/tree/main/skills/softagent
- **Website:** https://softcontrol.io/en/product/softagent

## Install

```sh
agentstack add skill-softcontrol-io-softagent-skill-softagent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SoftAgent 控制技能

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

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

## 何时使用

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

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

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

```bash
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` 心跳快照）。

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

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

## 安全实践（关键）

1. **Destructive 指令必须确认**：`shutdown` / `reboot` / `logoff` 的 `risk=Destructive`、
   `requiresConfirm=true`。执行前取得人工/策略确认。
2. **关机/重启优先用"延时 + 可取消"**：发 `shutdown:60` 而非 `shutdown`，给出反悔窗口；
   误操作时立刻发 `cancelshutdown` 取消。
3. **优先用稳定 `id` 而非 index**：`run:db-player` / `stop:db-player`，避免 GUI 列表序号漂移。
4. **多步操作逐条执行并核对每步回执**：不要假设成功；每发一条都读回执，失败则停下分析（如
   `err:...`、超时无回执可能是主机离线或网络未就绪）。
5. **明文无鉴权**：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「设置 → 授权与版本」或心跳）。
4. **过期优雅回落**：授权过期后自动回落免费版，基础控制（音量/电源/锁屏/唤醒/键盘/手动 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](https://github.com/softcontrol-io)
- **Source:** [softcontrol-io/softagent-skill](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-softcontrol-io-softagent-skill-softagent
- Seller: https://agentstack.voostack.com/s/softcontrol-io
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.