Sổ tay người dùng SoftAgent

Xác nhận môi trường đáp ứng yêu cầu và chuẩn bị cài đặt.

1. Xác nhận PC mục tiêu đang chạy Windows 10/11 x64.
2. Xác nhận bạn có quyền tài khoản quản trị viên (trình cài đặt sẽ kích hoạt lời nhắc nâng quyền UAC).
3. Xác nhận tường lửa cho phép lưu lượng UDP vào trên cổng 6500 (cổng nghe của SoftAgent).
4. Gói cài đặt tự chứa — không cần cài .NET runtime trước trên máy mục tiêu.

• Có thể chạy chương trình với tư cách quản trị viên (chấp nhận nâng quyền UAC).
• Cổng UDP 6500 không bị chiếm dụng bởi chương trình khác.

• Nhiều PC được điều khiển có thể dùng cùng trình cài đặt — cấu hình cổng và địa chỉ báo cáo độc lập trên mỗi máy.
• Đối với dự án triển lãm, khuyến nghị đặt tất cả PC được điều khiển tự động đăng nhập bằng tài khoản quản trị viên để scheduled task tự khởi động hoạt động đáng tin cậy.

Hoàn thành cài đặt và xác nhận SoftAgent đang chạy bình thường trong system tray.

1. Nhấp đúp vào SoftAgent-Setup-phiên-bản.exe và nhấp Có trong lời nhắc UAC để cho phép quyền quản trị viên.
2. Làm theo trình hướng dẫn cài đặt để hoàn thành cài đặt (mặc định: C:\Program Files\SoftAgent\).
3. Trên trang hoàn thành, tùy chọn đánh dấu 'Khởi chạy SoftAgent ngay bây giờ', hoặc khởi động thủ công sau.
4. Sau khi khởi động, SoftAgent xuất hiện trong system tray (không có cửa sổ chính mở).
5. Nhấp chuột phải vào biểu tượng tray và chọn 'Mở Cấu hình' — xác nhận cửa sổ chính xuất hiện với 4 tab (Properties / Programs / Watchdog / Settings).

• Biểu tượng SoftAgent xuất hiện trong system tray.
• Task Manager hiển thị cả hai tiến trình SoftAgent.App và SoftAgent.Watchdog đang chạy.
• Nhấp chuột phải vào tray hiển thị: Mở Cấu hình / Trạng thái / Tạm dừng Watchdog / Mở Thư mục Log / Giới thiệu / Thoát.

SoftAgent sử dụng kiến trúc hai tiến trình: tiến trình App xử lý chức năng và Watchdog giám sát và tự khởi động lại App nếu bị crash — chúng lẫn nhau bảo vệ.

Hoàn thành cấu hình cơ bản và xác nhận đại lý hoạt động qua ping UDP.

1. Nhấp đúp vào biểu tượng tray để mở cửa sổ chính, chuyển sang tab Settings.
2. Xác nhận cổng nghe là 6500 (hoặc thay đổi nếu cần), và đánh dấu 'Tự khởi động' để đăng ký scheduled task.
3. Để tích hợp SoftControl, nhập IP:port của máy SoftControl vào trường 'Địa chỉ Báo cáo'.
4. Nhấp 'Lưu và Áp dụng' để lưu cấu hình.
5. Mở PowerShell và gửi ping để xác minh:
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. Nhận ok:pong xác nhận đại lý hoạt động bình thường.

• Gửi ping nhận được phản hồi ok:pong.
• Ô đánh dấu tự khởi động trong tab Settings được lưu.
• Chạy schtasks /Query /TN SoftAgent hiển thị scheduled task đã đăng ký.

• Thay đổi cổng nhưng quên nhấp 'Lưu và Áp dụng', vì vậy thay đổi không có hiệu lực.
• Nhập cổng bảng quản lý HTTP thay vì cổng nghe UDP.

Nắm vững định dạng lệnh và cấp độ rủi ro để sử dụng SoftAgent an toàn.

1. Định dạng lệnh: động_từ hoặc động_từ:đối_số (đối số theo sau dấu hai chấm đầu tiên), ví dụ volume:80 hoặc ping.
2. Phản hồi thành công: ok:<mã>, ví dụ ok:pong hoặc ok:volume.
3. Phản hồi thất bại: err:<mã>, ví dụ err:wol.invalidMac.
4. Ba cấp độ rủi ro: An toàn (không gián đoạn, có thể lặp lại) / Gián đoạn (làm gián đoạn phiên/tiến trình nhưng không mất dữ liệu) / Phá hủy (tắt máy/khởi động lại/đăng xuất v.v.).
5. Lệnh Phá hủy hiển thị hộp thoại xác nhận trong giao diện. Khi được kích hoạt từ xa, người gọi chịu trách nhiệm xác nhận ý định.

• Gửi ping nhận ok:pong, xác nhận kết nối và định dạng lệnh chính xác.
• Gửi describe nhận danh sách khả năng JSON với tất cả lệnh được hỗ trợ và cấp độ rủi ro của chúng.

Lệnh describe trả về danh sách khả năng đầy đủ của phiên bản SoftAgent này, bao gồm tên, mô tả, cấp độ rủi ro và có yêu cầu xác nhận hay không của mỗi lệnh — hữu ích để khám phá khả năng khi tích hợp với SoftControl hoặc hệ thống AI.

Nắm vững lệnh An toàn để điều khiển âm lượng và giám sát trạng thái hàng ngày.

1. Thăm dò kết nối: ping (phản hồi ok:pong, xác nhận đại lý trực tuyến).
2. Lấy danh sách khả năng: describe (trả về JSON liệt kê tất cả lệnh với mô tả và cấp độ rủi ro).
3. Khám phá thiết bị: discover (trả về JSON snapshot heartbeat với hostname, IP, MAC, âm lượng, trạng thái guard).
4. Tăng âm lượng một bước: volup (mặc định +5% mỗi lần gọi).
5. Giảm âm lượng một bước: voldown (mặc định -5% mỗi lần gọi).
6. Chuyển đổi tắt tiếng: mute (chuyển đổi giữa tắt tiếng và bật tiếng).
7. Lấy địa chỉ MAC NIC chính: getmac (trả về định dạng viết hoa phân cách bằng gạch nối, ví dụ AA-BB-CC-DD-EE-FF).
8. Gửi gói magic Wake-on-LAN: wol:AA-BB-CC-DD-EE-FF (đánh thức máy có MAC được chỉ định).
9. Mô phỏng bàn phím: key:^s (Ctrl+S), key:{F5} (phím F5), key:Hello (gõ ký tự).

• Lệnh ping trả về ok:pong.
• volup/voldown thay đổi âm lượng của máy được điều khiển.
• Lệnh wol đánh thức máy mục tiêu (yêu cầu WoL được bật trên máy mục tiêu).

• Dùng discover để nhanh chóng lấy trạng thái hiện tại của máy được điều khiển (IP, âm lượng, trạng thái guard) — hữu ích cho kiểm tra sức khỏe hàng loạt của SoftControl.
• key: sử dụng cú pháp SendKeys của Microsoft: ^ là Ctrl, % là Alt, + là Shift, phím đặc biệt trong dấu ngoặc nhọn như {ENTER}.

Nắm vững lệnh khóa màn hình, khởi động/dừng tiến trình và hủy tắt máy.

1. Khóa màn hình: lock (khóa workstation hiện tại — đăng nhập lại để khôi phục).
2. Hủy tắt máy/khởi động lại đang chờ: cancelshutdown (dùng trong khi đếm ngược tắt máy).
3. Khởi động item watchdog theo ID: run:id (ví dụ run:db-player khởi động item có tên db-player).
4. Dừng item watchdog theo ID: stop:id (dừng và tạm dừng watchdog — tiến trình sẽ không được tự khởi động lại).
5. Khởi động chương trình được quản lý theo chỉ mục: startpro:0 (khởi động chương trình tại chỉ mục 0 trong danh sách chương trình được quản lý).
6. Dừng chương trình được quản lý theo chỉ mục: killpro:0.
7. Dừng tất cả chương trình được quản lý: killall.

• Sau lock, máy được điều khiển hiển thị màn hình khóa.
• Sau run:id, item watchdog tương ứng khởi động — trạng thái thay đổi từ Stopped sang Running trong tab Watchdog.
• cancelshutdown gửi trong khi đếm ngược tắt máy sẽ hủy tắt máy.

• Dùng run/stop với ID watchdog (định danh ổn định) thay vì startpro/killpro với chỉ mục (chỉ mục thay đổi khi item bị xóa hoặc sắp xếp lại).
• ID watchdog được cấu hình trong tab Watchdog của SoftAgent. Cập nhật lệnh SoftControl nếu bạn đổi tên ID.

Thực hiện an toàn các thao tác phá hủy như tắt máy, khởi động lại và đăng xuất.

1. Tắt máy có trễ (khuyến nghị): shutdown:60 (tắt máy sau 60 giây, cancelshutdown có thể hủy trong khi đếm ngược).
2. Tắt máy ngay lập tức (dùng thận trọng): shutdown (không có trễ, không thể hủy).
3. Khởi động lại có trễ (khuyến nghị): reboot:60 (khởi động lại sau 60 giây).
4. Khởi động lại vào BIOS/UEFI: reboot:firmware (yêu cầu hỗ trợ firmware UEFI).
5. Đăng xuất người dùng hiện tại: logoff (xác nhận không có dữ liệu chưa lưu trước khi thực thi).
6. Bật/Tắt UAC: uac:off / uac:on (thay đổi registry, yêu cầu khởi động lại để có hiệu lực, yêu cầu admin).
7. Bật/Tắt cử chỉ cạnh màn hình cảm ứng: edgeswipe:off / edgeswipe:on.
8. Bật/Tắt tự sửa khởi động Windows: autorepair:off / autorepair:on.

• Sau shutdown:60, hệ thống hiển thị thông báo đếm ngược 'tắt máy sau 60 giây'.
• cancelshutdown gửi trong khi đếm ngược sẽ hủy tắt máy.

• Gửi shutdown mà không có trễ, khiến không thể hủy — máy được điều khiển tắt ngay lập tức.
• Sau uac:off, không khởi động lại và cho rằng UAC đã bị tắt (yêu cầu khởi động lại để có hiệu lực).

Lệnh tắt máy yêu cầu quyền quản trị viên. Nếu không đủ quyền, mã lỗi rõ ràng như err:power.denied được trả về — không có lỗi im lặng.

Hoàn thành cấu hình cơ bản để SoftAgent có thể được SoftControl khám phá và điều khiển chính xác.

1. Mở cửa sổ chính SoftAgent và chuyển sang tab Settings.
2. Cổng nghe (mặc định 6500): SoftControl và các bộ điều khiển khác gửi lệnh UDP đến cổng này.
3. Địa chỉ báo cáo (định dạng IP:cổng): SoftAgent gửi heartbeat JSON định kỳ đến địa chỉ này; nhập IP và cổng nghe của SoftControl.
4. Khoảng thời gian Heartbeat (giây): mặc định 10 giây; heartbeat chứa hostname, IP, MAC, âm lượng, trạng thái guard v.v.
5. Trễ tự khởi động (giây): trễ sau đăng nhập trước khi SoftAgent khởi động (hữu ích để chờ sẵn sàng mạng).
6. Nhấp 'Lưu và Áp dụng' sau thay đổi — thay đổi cổng hiển thị thông báo 'Yêu cầu Khởi động lại' liên tục; các thay đổi khác có hiệu lực ngay lập tức.

• Cấu hình có hiệu lực ngay sau khi lưu (thay đổi cổng cần khởi động lại).
• Nếu địa chỉ báo cáo được cấu hình, SoftControl sẽ bắt đầu nhận heartbeat JSON định kỳ từ SoftAgent này.

• Đối với nhiều PC được điều khiển, khuyến nghị dùng cùng cổng (6500) trên tất cả để đơn giản hóa nhập lệnh hàng loạt trong SoftControl.
• Để trống địa chỉ báo cáo có nghĩa là SoftAgent sẽ không chủ động gửi heartbeat nhưng vẫn phản hồi lệnh UDP.

Sửa đổi cấu hình IP máy được điều khiển qua giao diện SoftAgent mà không cần RDP.

1. Mở cửa sổ chính, chuyển sang tab Properties, và chọn card mạng mục tiêu trong dropdown bảng mạng.
2. Sau khi chọn NIC, IP hiện tại, subnet mask, gateway, DNS và địa chỉ MAC tự động điền.
3. Chuyển đổi chế độ 'IP tĩnh / DHCP': các trường có thể chỉnh sửa ở chế độ Tĩnh; chỉ đọc ở chế độ DHCP.
4. Điền IP mục tiêu, subnet mask, gateway và DNS (chế độ Tĩnh).
5. Nhấp 'Thay đổi Cài đặt IP' và xác nhận trong hộp thoại xác nhận.
6. Thay đổi IP là thao tác phá hủy — kết nối hiện tại bị ngắt sau khi thay đổi. Kết nối lại bằng IP mới.

• Sau khi thay đổi, có thể ping thành công máy được điều khiển tại địa chỉ IP mới.
• Heartbeat JSON của SoftAgent hiển thị địa chỉ IP đã cập nhật.

Thay đổi IP là phá hủy. Trước khi tiếp tục, xác nhận IP mới có thể tiếp cận trên LAN để tránh mất quyền truy cập từ xa vào máy được điều khiển.

Cấu hình tự khởi động để SoftAgent tự động tiếp tục chạy sau khi PC được điều khiển khởi động lại.

1. Trong tab Settings của cửa sổ chính, đánh dấu 'Tự khởi động'.
2. Nhấp 'Lưu và Áp dụng'.
3. Xác minh bằng: schtasks /Query /TN SoftAgent trong PowerShell — xác nhận scheduled task đã đăng ký.
4. Kích hoạt task: ONLOGON (kích hoạt sau khi người dùng đăng nhập) với cấp quyền HIGHEST.
5. Để đặt trễ khởi động (chờ mạng hoặc dịch vụ phụ thuộc), đặt số giây trong trường 'Trễ tự khởi động'.
6. Để tắt tự khởi động, bỏ đánh dấu 'Tự khởi động' và lưu.

• schtasks /Query /TN SoftAgent hiển thị task tồn tại và được bật.
• Sau khi khởi động lại PC được điều khiển, SoftAgent tự động xuất hiện trong system tray sau đăng nhập.

Hoàn thành cài đặt lệnh SoftAgent trong SoftControl để điều khiển máy được điều khiển bằng nút.

1. Vào bảng quản trị SoftControl và mở Quản lý Lệnh.
2. Tạo lệnh mới, chọn giao thức UDP.
3. Đặt địa chỉ mục tiêu thành IP của PC được điều khiển (ví dụ 192.168.1.101).
4. Đặt cổng thành cổng nghe SoftAgent (mặc định 6500).
5. Đặt văn bản lệnh thành lệnh cụ thể, ví dụ: volup (tăng âm lượng), mute (chuyển đổi tắt tiếng), lock (khóa màn hình), shutdown:60 (tắt máy trong 60 giây).
6. Lưu và kiểm tra lệnh riêng lẻ — xác nhận máy được điều khiển phản hồi chính xác.
7. Gắn lệnh đã xác minh vào nút trên giao diện phía trước SoftControl.

• Sau khi SoftControl gửi lệnh UDP, SoftAgent của máy được điều khiển thực thi hành động.
• Log SoftControl hiển thị lệnh đã gửi thành công (phản hồi OK).

• Tạo bộ lệnh cho mỗi máy được điều khiển, dùng tên thiết bị làm tiền tố (ví dụ 'Hall-PC-01_Shutdown') để dễ bảo trì.
• Để các thao tác hàng loạt như đóng cửa triển lãm, dùng nhóm lệnh SoftControl — thêm lệnh tắt máy cho nhiều máy vào một nhóm và kích hoạt một lần.

Cấu hình báo cáo heartbeat để giám sát trạng thái trực tuyến của máy được điều khiển từ SoftControl.

1. Trong cài đặt SoftAgent, cấu hình địa chỉ báo cáo thành IP:cổng của SoftControl (giao diện UDP ngoài của SoftControl, mặc định 8818).
2. SoftAgent gửi ngay một heartbeat khi khởi động, sau đó tiếp tục theo khoảng thời gian đã cấu hình (mặc định 10 giây).
3. Heartbeat JSON bao gồm: agentId (định danh thiết bị duy nhất), hostname, ip/mac (thông tin mạng), volume/muted (trạng thái âm thanh), guards (trạng thái tiến trình watchdog), uptimeSeconds.
4. Để chủ động truy vấn trạng thái hiện tại của máy được điều khiển, gửi discover từ SoftControl — SoftAgent trả về snapshot heartbeat.
5. Trường guards trong heartbeat cho biết liệu các tiến trình watchdog có đang chạy bình thường không, để lộ các crash hoặc trạng thái bỏ cuộc.

• SoftControl nhận heartbeat JSON định kỳ từ SoftAgent.
• Gửi discover nhận phản hồi JSON với hostname, IP, âm lượng và thông tin khác.

Cấu hình watchdog tự khởi động lại crash cho các ứng dụng triển lãm.

1. Mở cửa sổ chính SoftAgent và chuyển sang tab Watchdog.
2. Nhấp 'Duyệt...' để chọn .exe cần bảo vệ, tùy chọn đặt tên và ID watchdog (định danh ổn định được dùng cho lệnh run/stop).
3. Nhấp 'Thêm' để đưa nó vào danh sách watchdog. Nút chuyển đổi riêng lẻ kiểm soát liệu watchdog của item này có được bật không.
4. Nút chuyển đổi watchdog chính ở đầu tab — tắt sẽ tạm dừng tất cả watchdog (đồng bộ với menu tray 'Tạm dừng Watchdog').
5. Huy hiệu trạng thái hiển thị trạng thái của mỗi item: Running / Stopped / Crashed / GaveUp (watchdog từ bỏ sau quá nhiều crash trong cửa sổ thời gian).
6. Sau crash, SoftAgent khởi động lại với exponential backoff (ban đầu 5 giây, gấp đôi mỗi lần; từ bỏ sau khi vượt giới hạn trong cửa sổ thời gian).

• Chương trình được bảo vệ hiển thị trạng thái 'Running' trong danh sách watchdog.
• Tắt cưỡng bức tiến trình được bảo vệ và SoftAgent tự động khởi động lại sau một khoảng trễ.
• Trường guards trong heartbeat JSON phản ánh trạng thái watchdog mới nhất.

Không thay đổi ID watchdog một cách tùy tiện — lệnh run/stop của SoftControl phụ thuộc vào nó. Nếu bạn đổi tên ID, hãy cập nhật các lệnh SoftControl tương ứng.

Khôi phục kênh điều khiển lệnh UDP.

1. Xác nhận SoftAgent hiển thị trong system tray (tiến trình đang chạy).
2. Xác nhận cổng gửi khớp với cổng nghe đã cấu hình của SoftAgent (mặc định 6500).
3. Kiểm tra Tường lửa Windows có cho phép lưu lượng UDP vào trên cổng 6500 không.
4. Thử ping từ localhost (127.0.0.1) trước để loại trừ vấn đề mạng, sau đó thử từ xa.
5. Kiểm tra tệp log trong %ProgramData%\SoftAgent\logs\ để tìm bản ghi nhận lệnh.

• Gửi ping đến 127.0.0.1 nhận ok:pong, xác nhận SoftAgent và cổng UDP đang hoạt động.
• Gửi ping từ máy từ xa cũng nhận phản hồi, xác nhận đường dẫn mạng thông suốt.

Đảm bảo SoftAgent chạy với quyền quản trị viên để hỗ trợ tất cả lệnh cấp hệ thống.

1. Xác nhận SoftAgent chạy với quyền admin: tự khởi động dùng scheduled task quyền HIGHEST; để khởi động thủ công, nhấp chuột phải vào exe và 'Chạy với tư cách quản trị viên'.
2. Nếu lệnh được kích hoạt qua SoftControl, bản thân SoftControl không cần quyền admin — quyền được xác định bởi SoftAgent trên phía được điều khiển.
3. Kiểm tra cột 'Elevated' cho SoftAgent.App.exe trong tab Details của Task Manager — phải hiển thị 'Yes'.
4. Nếu không chạy với tư cách admin, thoát SoftAgent và khởi động lại với tư cách quản trị viên.

• Tab Details của Task Manager hiển thị 'Yes' trong cột Elevated cho SoftAgent.App.exe.
• Lệnh volup/voldown phản hồi bình thường (không cần admin — hữu ích để xác minh cơ bản).
• Lệnh lock khóa màn hình máy được điều khiển (cấp Gián đoạn — xác nhận quyền đã đúng).

Chẩn đoán và sửa lỗi tự khởi động.

1. Chạy schtasks /Query /TN SoftAgent trong PowerShell để xác nhận scheduled task tồn tại.
2. Nếu task không tồn tại, mở tab Settings của SoftAgent, đánh dấu lại 'Tự khởi động' và lưu.
3. Xác nhận PC dùng tự đăng nhập (phổ biến trong triển lãm) thay vì chờ đăng nhập thủ công — kích hoạt task là ONLOGON, yêu cầu người dùng đăng nhập.
4. Nếu được cài đặt tự đăng nhập, xác nhận tài khoản tự đăng nhập có quyền chạy task (yêu cầu tài khoản quản trị viên).
5. Kiểm tra log gần đây trong %ProgramData%\SoftAgent\logs\ để tìm lý do lỗi khởi động.

• Kết quả schtasks /Query /TN SoftAgent chứa kích hoạt ONLOGON và quyền HIGHEST.
• Sau khi khởi động lại PC được điều khiển và đăng nhập, SoftAgent tự động xuất hiện trong system tray.

Hiểu tại sao watchdog từ bỏ và khôi phục giám sát ứng dụng mục tiêu.

1. Trong tab Watchdog của cửa sổ chính SoftAgent, kiểm tra huy hiệu trạng thái — xác nhận trạng thái 'GaveUp'.
2. Kiểm tra tệp log trong %ProgramData%\SoftAgent\logs\ để tìm lý do crash cụ thể (lỗi trước mỗi lần crash).
3. Sửa nguyên nhân gốc rễ gây crash của ứng dụng được bảo vệ (lỗi cấu hình, thiếu phụ thuộc, xung đột cổng v.v.).
4. Sau khi sửa, chuyển đổi nút riêng lẻ của item watchdog tắt rồi bật lại trong tab Watchdog (hoặc gửi run:id từ SoftControl) để kích hoạt lại watchdog.
5. Xác nhận trạng thái item watchdog thay đổi sang 'Running' và duy trì ổn định theo thời gian.

• Sau khi sửa ứng dụng được bảo vệ, trạng thái watchdog thay đổi từ 'GaveUp' sang 'Running'.
• Heartbeat JSON hiển thị trạng thái item watchdog tương ứng được cập nhật sang running.

GaveUp là hành vi có chủ đích để ngăn vòng lặp khởi động lại vô tận ảnh hưởng đến tài nguyên hệ thống. Giải pháp thực sự là sửa nguyên nhân gốc rễ của crash — không phải kích hoạt lại watchdog thủ công lặp đi lặp lại.