SoftAgent 使用手册

确认运行环境满足要求，做好安装准备。

1. 确认被控 PC 为 Windows 10/11 x64 系统。
2. 确认有管理员账户权限（安装包会触发 UAC 提权）。
3. 确认防火墙允许 UDP 6500 端口入站（SoftAgent 监听端口）。
4. 安装包为自包含格式，目标机无需预装 .NET 运行时。

• 能以管理员身份运行程序（UAC 提权通过）。
• UDP 6500 端口未被其他程序占用。

• 多台被控 PC 可以使用同一个安装包，每台独立配置端口和上报地址。
• 展厅项目建议所有被控 PC 统一使用管理员账户自动登录，确保开机自启正常触发。

完成安装并确认 SoftAgent 在系统托盘正常运行。

1. 双击 SoftAgent-Setup-版本号.exe，在 UAC 弹窗中点击「是」允许管理员权限。
2. 按安装向导完成安装，默认安装到 C:\Program Files\SoftAgent\。
3. 安装完成页可勾选「立即运行 SoftAgent」，或完成后手动启动。
4. SoftAgent 启动后在系统托盘出现图标（不会打开主窗口）。
5. 右键托盘图标选择「打开配置」，确认主窗出现并显示 4 个标签（基础属性 / 程序管理 / 程序守护 / 设置）。

• 系统托盘出现 SoftAgent 图标。
• 任务管理器中可见 SoftAgent.App 和 SoftAgent.Watchdog 两个进程。
• 右键托盘可看到：打开配置 / 状态 / 暂停守护 / 打开日志目录 / 关于 / 退出。

SoftAgent 采用双进程架构：App 主进程负责功能执行，Watchdog 看门狗负责监控和自动重启 App 进程，互相保活。

完成基础配置并通过 UDP ping 确认代理工作正常。

1. 双击托盘图标打开主窗，切换到「设置」标签。
2. 确认监听端口为 6500（或按需修改），勾选「开机自启」注册计划任务。
3. 如需 SoftControl 集成，在「上报地址」字段填写 SoftControl 所在机器的 IP:端口。
4. 点击「保存并应用」保存配置。
5. 打开 PowerShell 发送 ping 验证：
6. $u = New-Object System.Net.Sockets.UdpClient
7. $b = [Text.Encoding]::UTF8.GetBytes('ping')
8. $u.Send($b, $b.Length, '127.0.0.1', 6500)
9. $r = $u.Receive([ref](New-Object System.Net.IPEndPoint([Net.IPAddress]::Any, 0)))
10. [Text.Encoding]::UTF8.GetString($r)
11. 收到 ok:pong 响应说明代理正常工作。

• 发送 ping 后收到 ok:pong 响应。
• 「设置」标签中开机自启勾选状态已保存。
• 用 schtasks /Query /TN SoftAgent 可查到注册的计划任务。

• 修改端口后忘记点「保存并应用」，导致配置未生效。
• 端口号填写了 HTTP 管理台端口而不是 UDP 监听端口。

掌握命令格式和风险等级，安全使用 SoftAgent。

1. 命令格式：verb 或 verb:arg（首个冒号后为参数），例如 volume:80 或 ping。
2. 成功响应：ok:<code>，例如 ok:pong 或 ok:volume。
3. 失败响应：err:<code>，例如 err:wol.invalidMac。
4. 风险等级分三类：Safe（安全，可反复执行）/ Disruptive（中断会话/进程但不丢数据）/ Destructive（破坏性，关机/重启/注销等）。
5. Destructive 类命令在界面上会弹出确认弹窗（或倒计时可取消弹窗），远程发命令时需自行负责确认。

• 发送 ping 收到 ok:pong，说明连接和命令格式均正常。
• 发送 describe 收到 JSON 能力清单，列出所有支持的命令及其风险等级。

发送 describe 命令可获取该 SoftAgent 实例的完整能力清单，包含每条命令的名称、描述、风险等级和是否需要确认，适合与 SoftControl 或 AI 系统集成时做能力发现。

掌握安全类命令的用法，用于日常音量控制和状态检测。

1. 连通性探测：ping（响应 ok:pong，确认代理在线）。
2. 获取能力清单：describe（返回 JSON，列出所有命令的描述和风险等级）。
3. 设备发现：discover（返回包含机器名、IP、MAC、音量、守护状态的心跳快照 JSON）。
4. 调高音量一档：volup（默认每次 +5%）。
5. 调低音量一档：voldown（默认每次 -5%）。
6. 切换静音：mute（在静音和有声之间切换）。
7. 获取主网卡 MAC 地址：getmac（返回大写连字符格式，例如 AA-BB-CC-DD-EE-FF）。
8. 发送网络唤醒魔术包：wol:AA-BB-CC-DD-EE-FF（唤醒指定 MAC 对应的机器）。
9. 键盘模拟：key:^s（Ctrl+S），key:{F5}（F5），key:Hello（逐字符输入）。

• ping 命令返回 ok:pong。
• volup/voldown 执行后被控机音量发生变化。
• wol 命令执行后目标机器被唤醒（需目标机开启 WoL）。

• 用 discover 命令可以快速获取被控机的当前状态（IP、音量、守护状态），适合 SoftControl 批量巡检。
• key: 命令使用 Microsoft SendKeys 语法：^ 是 Ctrl，% 是 Alt，+ 是 Shift，特殊键用花括号如 {ENTER}。

掌握锁屏、进程启停和取消关机的命令。

1. 锁屏：lock（锁定当前工作站，重新登录即可恢复）。
2. 取消待执行的延时关机/重启：cancelshutdown（在关机倒计时期间使用）。
3. 按守护 ID 启动守护项：run:id（例如 run:db-player 启动名为 db-player 的守护进程）。
4. 按守护 ID 停止守护项：stop:id（停止并暂停其守护，进程不会被自动重启）。
5. 按序号启动受管程序：startpro:0（启动程序管理列表中序号为 0 的程序）。
6. 按序号停止受管程序：killpro:0。
7. 停止所有受管程序：killall。

• lock 执行后被控机进入锁屏界面。
• run:id 执行后对应守护进程启动，在程序守护标签的状态从「已停止」变为「运行中」。
• cancelshutdown 在关机倒计时期间执行后，关机取消。

• 推荐用 run/stop 加守护 ID（稳定标识符）控制进程，而不用 startpro/killpro 的序号（序号在删除/重排后会变化）。
• 守护 ID 在 SoftAgent 主窗「程序守护」标签中配置，重命名后需同步更新 SoftControl 中的指令。

安全地执行关机/重启/注销等破坏性操作。

1. 延时关机（推荐）：shutdown:60（60 秒后关机，期间可用 cancelshutdown 取消）。
2. 立即关机（谨慎）：shutdown（无延时，无法取消）。
3. 延时重启（推荐）：reboot:60（60 秒后重启）。
4. 重启进入 BIOS/UEFI：reboot:firmware（需 UEFI 固件支持）。
5. 注销当前用户：logoff（确认无未保存数据再执行）。
6. 关闭/开启 UAC：uac:off / uac:on（改注册表，需重启生效，需管理员）。
7. 关闭/开启触摸屏边缘手势：edgeswipe:off / edgeswipe:on。
8. 关闭/开启 Windows 启动自动修复：autorepair:off / autorepair:on。

• shutdown:60 执行后系统显示「将在 60 秒后关机」的倒计时提示。
• 在倒计时期间发送 cancelshutdown，关机取消。

• 直接发 shutdown 而不用延时，导致无法取消，被控机立即关机。
• uac:off 执行后没有重启，误以为 UAC 已关闭（需重启才生效）。

关机类命令需管理员权限；缺权限时返回 err:power.denied 等明确错误码，不会静默失败。

完成基础配置，使 SoftAgent 能被 SoftControl 正确发现和控制。

1. 打开 SoftAgent 主窗，切换到「设置」标签。
2. 监听端口（默认 6500）：SoftControl 等控制端发 UDP 命令到此端口。
3. 上报地址（格式 IP:端口）：SoftAgent 向该地址发送周期心跳 JSON；填写 SoftControl 的 IP 和监听端口。
4. 心跳间隔（秒）：默认 10 秒，心跳包含机器名、IP、MAC、音量、守护状态等信息。
5. 自启延时（秒）：开机自启时在登录后延迟多少秒再启动 SoftAgent（适合等待网络就绪）。
6. 修改后点击「保存并应用」——端口变更会出现持久提示「需重启」，其余配置热生效。

• 保存后配置立即生效（端口变更需重启）。
• 如果配置了上报地址，SoftControl 端会开始收到来自该 SoftAgent 的心跳 JSON。

• 多台被控 PC 建议统一使用相同端口（6500），方便在 SoftControl 批量录入指令。
• 上报地址留空时 SoftAgent 不会主动上报心跳，但仍可被动响应 UDP 命令。

通过 SoftAgent 界面修改被控机 IP 配置，避免 RDP 到每台机器单独操作。

1. 打开主窗，切换到「基础属性」标签，在网络面板下拉选择目标网卡。
2. 选中网卡后会自动回填当前 IP、子网掩码、网关、DNS 和 MAC 地址。
3. 切换「静态 IP / DHCP」模式：静态时字段可编辑；DHCP 时字段只读。
4. 填写目标 IP、子网掩码、网关和 DNS（静态模式）。
5. 点击「更改 IP 设置」，在确认弹窗中点击确认。
6. IP 修改为破坏性操作——修改后当前连接断开，需用新 IP 重新连接。

• 修改后用新 IP 地址能成功 ping 通被控机。
• SoftAgent 心跳包中的 IP 字段更新为新地址。

改 IP 是破坏性操作，操作前确认新 IP 在局域网内可达，避免改错后无法远程访问被控机。

配置开机自启，确保被控机重启后 SoftAgent 自动恢复运行。

1. 在主窗「设置」标签中勾选「开机自启」。
2. 点击「保存并应用」。
3. 用命令验证：在 PowerShell 运行 schtasks /Query /TN SoftAgent，确认计划任务已注册。
4. 计划任务触发条件：ONLOGON（用户登录后触发）/ 最高权限（HIGHEST）。
5. 如需设置启动延时（等待网络或依赖服务就绪），在「自启延时」字段设置秒数。
6. 如需取消自启，取消勾选「开机自启」并保存。

• schtasks /Query /TN SoftAgent 显示计划任务存在且为启用状态。
• 重启被控机后，登录系统时 SoftAgent 自动出现在系统托盘。

在 SoftControl 中完成 SoftAgent 指令录入，实现按钮控制被控机。

1. 进入 SoftControl 后台管理，打开「指令管理」。
2. 新建指令，协议选择「UDP」。
3. 目标地址填写被控 PC 的 IP 地址（例如 192.168.1.101）。
4. 端口填写 SoftAgent 的监听端口（默认 6500）。
5. 指令文本填写具体命令，例如：volup（音量加）、mute（静音）、lock（锁屏）、shutdown:60（60秒后关机）。
6. 保存后单独测试该指令，确认被控机产生对应反应。
7. 把验证通过的指令绑定到 SoftControl 前台界面的按钮上。

• SoftControl 发送 UDP 指令后，被控机 SoftAgent 执行对应动作。
• SoftControl 日志显示指令发送成功（OK 响应）。

• 为每台被控机创建一套指令，以设备名作为指令名前缀（例如「展厅PC-01_关机」），便于后期维护。
• 一键关馆等批量操作建议用 SoftControl 的指令组，把多台被控机的关机指令加入同一指令组，一次触发。

配置心跳上报，在 SoftControl 中感知被控机在线状态。

1. 在 SoftAgent 设置中配置上报地址为 SoftControl 的 IP:端口（SoftControl 的外部 UDP 接口，默认 8818）。
2. SoftAgent 上线后立即发送一帧心跳，此后按配置间隔（默认 10 秒）持续上报。
3. 心跳 JSON 包含：agentId（设备唯一标识）、hostname（机器名）、ip/mac（网络信息）、volume/muted（音量状态）、guards（守护进程状态）、uptimeSeconds（运行时长）。
4. 如需主动查询某台被控机当前状态，从 SoftControl 发送 discover 命令，SoftAgent 返回心跳快照。
5. 通过心跳中的 guards 字段可以判断守护进程是否正常运行，发现崩溃或放弃守护的情况。

• SoftControl 侧能收到来自 SoftAgent 的周期心跳 JSON。
• 发送 discover 命令后收到包含机器名、IP、音量等信息的 JSON 响应。

为展厅应用程序配置崩溃自动重启守护。

1. 打开 SoftAgent 主窗，切换到「程序守护」标签。
2. 点击「浏览…」选择需要守护的 .exe 文件，填写可选名称和守护 ID（稳定标识符，用于 run/stop 命令）。
3. 点击「添加」将其加入守护列表，单独开关可以控制该项守护是否启用。
4. 守护总开关位于标签顶部，关闭时所有守护暂停（与托盘「暂停守护」菜单同步）。
5. 状态徽标显示各守护项的状态：运行中 / 已停止 / 已崩溃 / 已放弃（崩溃次数超限后放弃守护）。
6. 崩溃后 SoftAgent 按指数退避重启（初始 5 秒，逐次翻倍，时间窗内超限则放弃）。

• 守护列表中的程序显示「运行中」状态。
• 手动结束守护进程后，SoftAgent 在延迟后自动将其重启。
• 心跳 JSON 中 guards 字段反映最新守护状态。

守护 ID 设置后不要随意更改，因为 SoftControl 中录入的 run/stop 指令依赖该 ID。修改 ID 需同步更新 SoftControl 指令。

恢复 UDP 命令控制链路。

1. 确认 SoftAgent 在系统托盘可见（进程正在运行）。
2. 确认发送端口与 SoftAgent 配置中的监听端口一致（默认 6500）。
3. 检查 Windows 防火墙是否放行 UDP 6500 端口入站规则。
4. 尝试本机 127.0.0.1 发 ping 排除网络问题，再从远程发。
5. 查看 %ProgramData%\SoftAgent\logs\ 中的日志文件，确认是否有命令接收记录。

• 本机 127.0.0.1 发 ping 收到 ok:pong，说明 SoftAgent 和 UDP 端口正常。
• 远程发 ping 也收到响应，说明网络链路通畅。

确保 SoftAgent 以管理员权限运行，支持全部系统级命令。

1. 确认 SoftAgent 以管理员权限运行：开机自启通过计划任务 HIGHEST 权限启动；手动启动时在 exe 上右键「以管理员身份运行」。
2. 如果是通过 SoftControl 触发的命令，SoftControl 本身无需管理员权限，权限由被控端 SoftAgent 决定。
3. 检查任务管理器「详细信息」中 SoftAgent.App.exe 的「提升」列是否显示「是」。
4. 如果不是管理员运行，退出 SoftAgent 并以管理员身份重新启动。

• 任务管理器中 SoftAgent.App.exe 的「提升」列显示「是」。
• 发送 volup/voldown 命令正常响应（这些不需要管理员权限，可用于基础验证）。
• 发送 lock 命令后被控机锁屏（Disruptive 级，需确认权限正常）。

排查并修复开机自启失败的问题。

1. 在 PowerShell 运行 schtasks /Query /TN SoftAgent，确认计划任务存在。
2. 如果计划任务不存在，打开 SoftAgent 设置标签重新勾选「开机自启」并保存。
3. 确认被控机使用的是自动登录（展厅常见配置），而不是等待手动登录——计划任务触发条件是 ONLOGON，需要用户登录后触发。
4. 如果机器设置了「无需登录直接进入桌面」（自动登录），确认自动登录账户有权执行计划任务（需管理员账户）。
5. 查看 %ProgramData%\SoftAgent\logs\ 中最近日志，确认启动失败原因。

• schtasks /Query /TN SoftAgent 输出包含 ONLOGON 触发器和 HIGHEST 权限。
• 重启被控机并登录后，SoftAgent 在系统托盘自动出现。

了解放弃守护的原因，并恢复对目标程序的守护。

1. 在 SoftAgent 主窗「程序守护」标签中查看该守护项状态徽标，确认显示「已放弃」。
2. 查看 %ProgramData%\SoftAgent\logs\ 中的日志，找到程序崩溃的具体原因（崩溃前的错误日志）。
3. 修复被守护程序本身的问题（配置错误、依赖缺失、端口冲突等）。
4. 修复后，在「程序守护」标签中关闭再开启该守护项的单项开关（或通过 SoftControl 发 run:id 命令），重新触发守护。
5. 确认守护项状态变为「运行中」，并在一段时间内保持稳定。

• 被守护程序修复后，守护状态从「已放弃」变为「运行中」。
• 心跳 JSON 中对应守护项状态更新为 running。

GaveUp 是设计行为，防止短时间内无限重启对系统资源造成影响。根本解决方案是修复被守护程序的崩溃原因，而不是手动反复触发守护。