Manual Pengguna SoftAgent

Konfirmasi lingkungan memenuhi persyaratan dan persiapkan untuk instalasi.

1. Konfirmasi PC target menjalankan Windows 10/11 x64.
2. Konfirmasi Anda memiliki hak akun administrator (penginstal akan memicu prompt elevasi UAC).
3. Konfirmasi firewall mengizinkan lalu lintas UDP masuk pada port 6500 (port listening SoftAgent).
4. Paket penginstal sudah lengkap sendiri — tidak perlu menginstal runtime .NET terlebih dahulu di mesin target.

• Dapat menjalankan program sebagai administrator (elevasi UAC diterima).
• Port UDP 6500 tidak digunakan oleh program lain.

• Beberapa PC yang dikontrol dapat menggunakan penginstal yang sama — konfigurasikan port dan alamat pelaporan secara independen pada masing-masing.
• Untuk proyek pameran, direkomendasikan mengatur semua PC yang dikontrol ke auto-login dengan akun administrator sehingga scheduled task auto-start terpicu dengan andal.

Selesaikan instalasi dan konfirmasi SoftAgent berjalan normal di system tray.

1. Klik dua kali SoftAgent-Setup-versi.exe dan klik Ya dalam prompt UAC untuk mengizinkan hak administrator.
2. Ikuti wizard penginstal untuk menyelesaikan instalasi (default: C:\Program Files\SoftAgent\).
3. Di halaman penyelesaian, opsional centang 'Luncurkan SoftAgent sekarang', atau mulai secara manual setelahnya.
4. Setelah startup, SoftAgent muncul di system tray (tidak ada jendela utama yang terbuka).
5. Klik kanan ikon tray dan pilih 'Buka Konfigurasi' — konfirmasi jendela utama muncul dengan 4 tab (Properties / Programs / Watchdog / Settings).

• Ikon SoftAgent muncul di system tray.
• Task Manager menampilkan proses SoftAgent.App dan SoftAgent.Watchdog yang berjalan.
• Klik kanan tray menampilkan: Buka Konfigurasi / Status / Jeda Watchdog / Buka Direktori Log / Tentang / Keluar.

SoftAgent menggunakan arsitektur proses ganda: proses App menangani fungsionalitas, dan Watchdog memantau dan me-restart otomatis App jika crash — saling menjaga satu sama lain.

Selesaikan konfigurasi dasar dan konfirmasi agen berfungsi melalui ping UDP.

1. Klik dua kali ikon tray untuk membuka jendela utama, beralih ke tab Settings.
2. Konfirmasi port listening adalah 6500 (atau ubah sesuai kebutuhan), dan centang 'Auto-start' untuk mendaftarkan scheduled task.
3. Untuk integrasi SoftControl, masukkan IP:port mesin SoftControl di bidang 'Alamat Pelaporan'.
4. Klik 'Simpan dan Terapkan' untuk menyimpan konfigurasi.
5. Buka PowerShell dan kirim ping untuk verifikasi:
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. Menerima ok:pong mengonfirmasi agen berfungsi normal.

• Mengirim ping menerima respons ok:pong.
• Centang auto-start di tab Settings tersimpan.
• Menjalankan schtasks /Query /TN SoftAgent menampilkan scheduled task yang terdaftar.

• Mengubah port tetapi lupa mengklik 'Simpan dan Terapkan', sehingga perubahan tidak berlaku.
• Memasukkan port konsol manajemen HTTP bukan port listening UDP.

Kuasai format perintah dan tingkat risiko untuk penggunaan SoftAgent yang aman.

1. Format perintah: kata kerja atau kata kerja:arg (argumen mengikuti titik dua pertama), misalnya volume:80 atau ping.
2. Respons berhasil: ok:<kode>, misalnya ok:pong atau ok:volume.
3. Respons gagal: err:<kode>, misalnya err:wol.invalidMac.
4. Tiga tingkat risiko: Aman (tidak mengganggu, dapat diulang) / Menggangu (mengganggu sesi/proses tetapi tidak ada kehilangan data) / Destruktif (shutdown/restart/logoff dll.).
5. Perintah Destruktif menampilkan dialog konfirmasi di UI. Saat dipicu dari jarak jauh, pemanggil bertanggung jawab untuk mengonfirmasi niat.

• Mengirim ping menerima ok:pong, mengonfirmasi koneksi dan format perintah benar.
• Mengirim describe menerima daftar kemampuan JSON dengan semua perintah yang didukung dan tingkat risikonya.

Perintah describe mengembalikan daftar kemampuan lengkap instans SoftAgent ini, termasuk nama, deskripsi, tingkat risiko, dan apakah konfirmasi diperlukan untuk setiap perintah — berguna untuk penemuan kemampuan saat mengintegrasikan dengan SoftControl atau sistem AI.

Kuasai perintah Aman untuk kontrol volume dan pemantauan status sehari-hari.

1. Probe konektivitas: ping (merespons ok:pong, mengonfirmasi agen online).
2. Dapatkan daftar kemampuan: describe (mengembalikan JSON yang mencantumkan semua perintah dengan deskripsi dan tingkat risiko).
3. Penemuan perangkat: discover (mengembalikan JSON snapshot heartbeat dengan hostname, IP, MAC, volume, status guard).
4. Naikkan volume satu langkah: volup (default +5% per panggilan).
5. Turunkan volume satu langkah: voldown (default -5% per panggilan).
6. Toggle bisu: mute (beralih antara bisu dan tidak bisu).
7. Dapatkan alamat MAC NIC utama: getmac (mengembalikan format dipisah hubung huruf besar, misalnya AA-BB-CC-DD-EE-FF).
8. Kirim paket magic Wake-on-LAN: wol:AA-BB-CC-DD-EE-FF (bangunkan mesin dengan MAC yang ditentukan).
9. Simulasi keyboard: key:^s (Ctrl+S), key:{F5} (tombol F5), key:Hello (ketik karakter).

• Perintah ping mengembalikan ok:pong.
• volup/voldown mengubah volume mesin yang dikontrol.
• Perintah wol membangunkan mesin target (memerlukan WoL yang diaktifkan pada target).

• Gunakan discover untuk mendapatkan status terkini mesin yang dikontrol dengan cepat (IP, volume, status guard) — berguna untuk pemeriksaan kesehatan batch SoftControl.
• key: menggunakan sintaks SendKeys Microsoft: ^ adalah Ctrl, % adalah Alt, + adalah Shift, tombol khusus dalam kurung kurawal seperti {ENTER}.

Kuasai perintah kunci layar, start/stop proses, dan batal-shutdown.

1. Kunci layar: lock (mengunci workstation saat ini — login ulang untuk memulihkan).
2. Batalkan shutdown/restart tertunda yang tertunda: cancelshutdown (gunakan selama hitungan mundur shutdown).
3. Mulai item watchdog berdasarkan ID: run:id (misalnya run:db-player memulai item bernama db-player).
4. Hentikan item watchdog berdasarkan ID: stop:id (menghentikan dan menjeda watchdog — proses tidak akan di-restart otomatis).
5. Mulai program terkelola berdasarkan indeks: startpro:0 (memulai program pada indeks 0 dalam daftar program terkelola).
6. Hentikan program terkelola berdasarkan indeks: killpro:0.
7. Hentikan semua program terkelola: killall.

• Setelah lock, mesin yang dikontrol menampilkan layar kunci.
• Setelah run:id, item watchdog yang sesuai dimulai — status berubah dari Stopped ke Running di tab Watchdog.
• cancelshutdown yang dikirim selama hitungan mundur shutdown membatalkan shutdown.

• Gunakan run/stop dengan ID watchdog (pengenal yang stabil) daripada startpro/killpro dengan indeks (indeks berubah saat item dihapus atau diurutkan ulang).
• ID watchdog dikonfigurasi di tab Watchdog SoftAgent. Perbarui perintah SoftControl jika Anda mengganti nama ID.

Jalankan operasi destruktif seperti shutdown, restart, dan logoff dengan aman.

1. Shutdown tertunda (direkomendasikan): shutdown:60 (shutdown setelah 60 detik, cancelshutdown dapat membatalkan selama hitungan mundur).
2. Shutdown segera (gunakan dengan hati-hati): shutdown (tanpa penundaan, tidak dapat dibatalkan).
3. Restart tertunda (direkomendasikan): reboot:60 (restart setelah 60 detik).
4. Restart ke BIOS/UEFI: reboot:firmware (memerlukan dukungan firmware UEFI).
5. Logoff pengguna saat ini: logoff (konfirmasi tidak ada data yang belum disimpan sebelum mengeksekusi).
6. Aktifkan/Nonaktifkan UAC: uac:off / uac:on (perubahan registry, memerlukan restart untuk berlaku, memerlukan admin).
7. Aktifkan/Nonaktifkan gestur tepi layar sentuh: edgeswipe:off / edgeswipe:on.
8. Aktifkan/Nonaktifkan perbaikan startup otomatis Windows: autorepair:off / autorepair:on.

• Setelah shutdown:60, sistem menampilkan notifikasi hitungan mundur 'mati dalam 60 detik'.
• cancelshutdown yang dikirim selama hitungan mundur membatalkan shutdown.

• Mengirim shutdown tanpa penundaan, membuatnya tidak mungkin dibatalkan — mesin yang dikontrol langsung mati.
• Setelah uac:off, tidak me-reboot dan berasumsi UAC sudah dinonaktifkan (memerlukan restart untuk berlaku).

Perintah shutdown memerlukan hak administrator. Jika izin tidak mencukupi, kode kesalahan yang jelas seperti err:power.denied dikembalikan — tidak ada kegagalan diam.

Selesaikan konfigurasi dasar agar SoftAgent dapat ditemukan dan dikontrol dengan benar oleh SoftControl.

1. Buka jendela utama SoftAgent dan beralih ke tab Settings.
2. Port Listening (default 6500): SoftControl dan kontroler lain mengirim perintah UDP ke port ini.
3. Alamat Pelaporan (format IP:port): SoftAgent mengirim heartbeat JSON berkala ke alamat ini; masukkan IP dan port listening SoftControl.
4. Interval Heartbeat (detik): default 10 detik; heartbeat mengandung hostname, IP, MAC, volume, status guard, dll.
5. Penundaan Auto-start (detik): penundaan setelah login sebelum SoftAgent dimulai (berguna untuk menunggu kesiapan jaringan).
6. Klik 'Simpan dan Terapkan' setelah perubahan — perubahan port menampilkan pemberitahuan 'Restart Diperlukan' yang persisten; perubahan lain berlaku segera.

• Konfigurasi berlaku segera setelah disimpan (perubahan port memerlukan restart).
• Jika alamat pelaporan dikonfigurasi, SoftControl harus mulai menerima heartbeat JSON berkala dari SoftAgent ini.

• Untuk beberapa PC yang dikontrol, rekomendasikan menggunakan port yang sama (6500) di semua untuk menyederhanakan entri perintah batch di SoftControl.
• Membiarkan alamat pelaporan kosong berarti SoftAgent tidak akan secara proaktif mengirim heartbeat tetapi masih akan merespons perintah UDP.

Modifikasi konfigurasi IP mesin yang dikontrol melalui antarmuka SoftAgent tanpa RDP.

1. Buka jendela utama, beralih ke tab Properties, dan pilih kartu jaringan target dalam dropdown panel jaringan.
2. Setelah memilih NIC, IP saat ini, subnet mask, gateway, DNS, dan alamat MAC terisi otomatis.
3. Toggle mode 'IP Statis / DHCP': bidang dapat diedit dalam mode Statis; hanya-baca dalam mode DHCP.
4. Isi IP target, subnet mask, gateway, dan DNS (mode Statis).
5. Klik 'Ubah Pengaturan IP' dan konfirmasi dalam dialog konfirmasi.
6. Perubahan IP adalah operasi destruktif — koneksi saat ini terputus setelah perubahan. Sambungkan kembali dengan IP baru.

• Setelah perubahan, mesin yang dikontrol dapat di-ping berhasil di alamat IP baru.
• Heartbeat JSON SoftAgent menampilkan alamat IP yang diperbarui.

Mengubah IP adalah destruktif. Sebelum melanjutkan, konfirmasi IP baru dapat dijangkau di LAN untuk menghindari kehilangan akses jarak jauh ke mesin yang dikontrol.

Konfigurasikan auto-start agar SoftAgent secara otomatis melanjutkan berjalan setelah PC yang dikontrol restart.

1. Di tab Settings jendela utama, centang 'Auto-start'.
2. Klik 'Simpan dan Terapkan'.
3. Verifikasi dengan: schtasks /Query /TN SoftAgent di PowerShell — konfirmasi scheduled task terdaftar.
4. Pemicu task: ONLOGON (dipicu setelah login pengguna) dengan tingkat hak HIGHEST.
5. Untuk mengatur penundaan startup (tunggu jaringan atau layanan dependen), atur detik di bidang 'Penundaan Auto-start'.
6. Untuk menonaktifkan auto-start, hapus centang 'Auto-start' dan simpan.

• schtasks /Query /TN SoftAgent menampilkan task ada dan diaktifkan.
• Setelah me-restart PC yang dikontrol, SoftAgent secara otomatis muncul di system tray setelah login.

Selesaikan pengaturan perintah SoftAgent di SoftControl untuk kontrol mesin yang dikontrol berbasis tombol.

1. Masuk panel admin SoftControl dan buka Manajemen Perintah.
2. Buat perintah baru, pilih protokol UDP.
3. Atur alamat target ke IP PC yang dikontrol (misalnya 192.168.1.101).
4. Atur port ke port listening SoftAgent (default 6500).
5. Atur teks perintah ke perintah spesifik, misalnya: volup (naikkan volume), mute (toggle bisu), lock (kunci layar), shutdown:60 (shutdown dalam 60 detik).
6. Simpan dan uji perintah secara individual — konfirmasi mesin yang dikontrol merespons dengan benar.
7. Ikat perintah yang terverifikasi ke tombol pada antarmuka depan SoftControl.

• Setelah SoftControl mengirim perintah UDP, SoftAgent mesin yang dikontrol mengeksekusi tindakan.
• Log SoftControl menampilkan perintah berhasil dikirim (respons OK).

• Buat set perintah untuk setiap mesin yang dikontrol, menggunakan nama perangkat sebagai awalan (misalnya 'Hall-PC-01_Shutdown') untuk kemudahan pemeliharaan.
• Untuk operasi batch seperti menutup pameran, gunakan grup perintah SoftControl — tambahkan perintah shutdown untuk beberapa mesin ke satu grup dan picu sekali.

Konfigurasikan pelaporan heartbeat untuk memantau status online mesin yang dikontrol dari SoftControl.

1. Di pengaturan SoftAgent, konfigurasikan alamat pelaporan ke IP:port SoftControl (antarmuka UDP eksternal SoftControl, default 8818).
2. SoftAgent segera mengirim satu heartbeat saat startup, kemudian berlanjut pada interval yang dikonfigurasi (default 10 detik).
3. Heartbeat JSON menyertakan: agentId (pengenal perangkat unik), hostname, ip/mac (info jaringan), volume/muted (status audio), guards (status proses watchdog), uptimeSeconds.
4. Untuk secara aktif mengkueri status terkini mesin yang dikontrol, kirim discover dari SoftControl — SoftAgent mengembalikan snapshot heartbeat.
5. Bidang guards dalam heartbeat menunjukkan apakah proses watchdog berjalan normal, mengungkapkan crash atau status menyerah.

• SoftControl menerima heartbeat JSON berkala dari SoftAgent.
• Mengirim discover menerima respons JSON dengan hostname, IP, volume, dan info lainnya.

Konfigurasikan watchdog auto-restart crash untuk aplikasi pameran.

1. Buka jendela utama SoftAgent dan beralih ke tab Watchdog.
2. Klik 'Telusuri...' untuk memilih .exe yang akan dijaga, opsional atur nama dan ID watchdog (pengenal stabil yang digunakan untuk perintah run/stop).
3. Klik 'Tambah' untuk memasukkannya ke dalam daftar watchdog. Toggle individual mengontrol apakah watchdog item ini diaktifkan.
4. Toggle watchdog utama ada di bagian atas tab — menonaktifkan menjeda semua watchdog (disinkronkan dengan menu tray 'Jeda Watchdog').
5. Lencana status menampilkan status setiap item: Running / Stopped / Crashed / GaveUp (watchdog ditinggalkan setelah terlalu banyak crash dalam jendela waktu).
6. Setelah crash, SoftAgent me-restart dengan exponential backoff (awal 5 detik, berlipat ganda setiap kali; ditinggalkan setelah batas terlampaui dalam jendela waktu).

• Program yang dijaga menampilkan status 'Running' dalam daftar watchdog.
• Mematikan paksa proses yang dijaga dan SoftAgent secara otomatis me-restart setelah penundaan.
• Bidang guards heartbeat JSON mencerminkan status watchdog terbaru.

Jangan ubah ID watchdog secara sembarangan — perintah run/stop SoftControl bergantung padanya. Jika Anda mengganti nama ID, perbarui perintah SoftControl yang sesuai.

Pulihkan saluran kontrol perintah UDP.

1. Konfirmasi SoftAgent terlihat di system tray (proses berjalan).
2. Konfirmasi port pengiriman sesuai dengan port listening yang dikonfigurasi SoftAgent (default 6500).
3. Periksa apakah Windows Firewall mengizinkan lalu lintas UDP masuk pada port 6500.
4. Coba ping dari localhost (127.0.0.1) terlebih dahulu untuk mengesampingkan masalah jaringan, kemudian coba dari jarak jauh.
5. Periksa file log di %ProgramData%\SoftAgent\logs\ untuk catatan penerimaan perintah.

• Mengirim ping ke 127.0.0.1 menerima ok:pong, mengonfirmasi SoftAgent dan port UDP berfungsi.
• Mengirim ping dari mesin jarak jauh juga menerima respons, mengonfirmasi jalur jaringan bersih.

Pastikan SoftAgent berjalan dengan hak administrator untuk mendukung semua perintah tingkat sistem.

1. Konfirmasi SoftAgent berjalan dengan hak admin: auto-start menggunakan scheduled task hak HIGHEST; untuk start manual, klik kanan exe dan 'Jalankan sebagai administrator'.
2. Jika perintah dipicu melalui SoftControl, SoftControl itu sendiri tidak perlu hak admin — hak ditentukan oleh SoftAgent di sisi yang dikontrol.
3. Periksa kolom 'Elevated' untuk SoftAgent.App.exe di tab Details Task Manager — harus menampilkan 'Ya'.
4. Jika tidak berjalan sebagai admin, keluar dari SoftAgent dan restart sebagai administrator.

• Tab Details Task Manager menampilkan 'Ya' di kolom Elevated untuk SoftAgent.App.exe.
• Perintah volup/voldown merespons normal (tidak perlu admin — berguna untuk verifikasi dasar).
• Perintah lock mengunci layar mesin yang dikontrol (tingkat Menggangu — mengonfirmasi hak sudah benar).

Diagnosis dan perbaiki kegagalan auto-start.

1. Jalankan schtasks /Query /TN SoftAgent di PowerShell untuk mengonfirmasi scheduled task ada.
2. Jika task tidak ada, buka tab Settings SoftAgent, centang ulang 'Auto-start', dan simpan.
3. Konfirmasi PC menggunakan auto-login (umum di pameran) daripada menunggu login manual — pemicu task adalah ONLOGON, memerlukan pengguna untuk login.
4. Jika diatur untuk auto-login, konfirmasi akun auto-login memiliki izin untuk menjalankan task (memerlukan akun administrator).
5. Periksa log terbaru di %ProgramData%\SoftAgent\logs\ untuk alasan kegagalan startup.

• Output schtasks /Query /TN SoftAgent mengandung pemicu ONLOGON dan hak HIGHEST.
• Setelah me-restart PC yang dikontrol dan login, SoftAgent secara otomatis muncul di system tray.

Pahami mengapa watchdog menyerah dan pulihkan pemantauan aplikasi target.

1. Di tab Watchdog jendela utama SoftAgent, periksa lencana status — konfirmasi status 'GaveUp'.
2. Periksa file log di %ProgramData%\SoftAgent\logs\ untuk alasan crash spesifik (kesalahan sebelum setiap crash).
3. Perbaiki penyebab utama crash aplikasi yang dijaga (kesalahan konfigurasi, dependensi yang hilang, konflik port, dll.).
4. Setelah memperbaiki, toggle switch individual item watchdog mati lalu nyalakan di tab Watchdog (atau kirim run:id dari SoftControl) untuk memicu ulang watchdog.
5. Konfirmasi status item watchdog berubah ke 'Running' dan tetap stabil seiring waktu.

• Setelah memperbaiki aplikasi yang dijaga, status watchdog berubah dari 'GaveUp' ke 'Running'.
• Heartbeat JSON menampilkan status item watchdog yang sesuai diperbarui ke running.

GaveUp adalah perilaku yang disengaja untuk mencegah storm restart tak terbatas dari memengaruhi sumber daya sistem. Solusi nyata adalah memperbaiki penyebab utama crash — bukan memicu ulang watchdog secara manual berulang kali.