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 是設計行為，防止短時間內無限重啟對系統資源造成影響。根本解決方案是修復被守護程式的崩潰原因，而不是手動反覆觸發守護。