SoftAgent 사용 설명서

환경이 요구 사항을 충족하는지 확인하고 설치를 준비합니다.

1. 대상 PC가 Windows 10/11 x64를 실행하는지 확인합니다.
2. 관리자 계정 권한이 있는지 확인합니다(설치 프로그램이 UAC 권한 상승 프롬프트를 표시함).
3. 방화벽이 포트 6500의 UDP 인바운드 트래픽을 허용하는지 확인합니다(SoftAgent의 수신 포트).
4. 설치 프로그램 패키지는 자체 완결형이므로 대상 시스템에 .NET 런타임을 미리 설치할 필요가 없습니다.

• 관리자로 프로그램을 실행할 수 있습니다(UAC 권한 상승 수락).
• UDP 포트 6500이 다른 프로그램에 점유되어 있지 않습니다.

• 여러 제어 PC에 동일한 설치 프로그램을 사용할 수 있습니다 — 각 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 실행 시 등록된 예약 작업이 표시됩니다.

• 포트를 변경했지만 '저장 및 적용'을 클릭하지 않아 변경이 적용되지 않는 경우.
• UDP 수신 포트 대신 HTTP 관리 콘솔 포트를 입력하는 경우.

명령 형식과 위험 수준을 마스터하여 SoftAgent를 안전하게 사용합니다.

1. 명령 형식: verb 또는 verb:arg (인수는 첫 번째 콜론 뒤에 옴), 예: volume:80 또는 ping.
2. 성공 응답: ok:<코드>, 예: ok:pong 또는 ok:volume.
3. 실패 응답: err:<코드>, 예: err:wol.invalidMac.
4. 세 가지 위험 수준: 안전(방해 없음, 반복 가능) / 방해(세션/프로세스를 중단하지만 데이터 손실 없음) / 파괴적(종료/재시작/로그오프 등).
5. 파괴적인 명령은 UI에 확인 대화 상자를 표시합니다. 원격으로 트리거할 때는 호출자가 의도를 확인해야 합니다.

• 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. 기본 NIC MAC 주소 가져오기: getmac (대문자 하이픈 구분 형식 반환, 예: AA-BB-CC-DD-EE-FF).
8. Wake-on-LAN 매직 패킷 전송: 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을 보내면 종료가 취소됩니다.

• 인덱스(항목 삭제 또는 재정렬 시 변경)가 아닌 감시 ID(안정적인 식별자)와 함께 run/stop을 사용하세요.
• 감시 ID는 SoftAgent의 감시 탭에서 구성합니다. ID를 변경하면 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의 경우 SoftControl에서 일괄 명령 입력을 단순화하기 위해 모든 PC에서 동일한 포트(6500)를 사용하는 것을 권장합니다.
• 보고 주소를 비워두면 SoftAgent가 능동적으로 하트비트를 보내지 않지만 UDP 명령에는 여전히 응답합니다.

RDP 없이 SoftAgent의 인터페이스를 통해 제어 시스템 IP 구성을 수정합니다.

1. 메인 창을 열고 속성 탭으로 전환하여 네트워크 패널 드롭다운에서 대상 네트워크 카드를 선택합니다.
2. NIC를 선택하면 현재 IP, 서브넷 마스크, 게이트웨이, DNS 및 MAC 주소가 자동으로 채워집니다.
3. '고정 IP / DHCP' 모드를 전환합니다: 고정 모드에서는 필드 편집 가능, DHCP 모드에서는 읽기 전용.
4. 대상 IP, 서브넷 마스크, 게이트웨이, DNS를 입력합니다(고정 모드).
5. 'IP 설정 변경'을 클릭하고 확인 대화 상자에서 확인합니다.
6. IP 변경은 파괴적 작업입니다 — 변경 후 현재 연결이 끊어집니다. 새 IP로 재연결하세요.

• 변경 후 제어 시스템을 새 IP 주소로 핑할 수 있습니다.
• SoftAgent 하트비트 JSON에 업데이트된 IP 주소가 표시됩니다.

IP 변경은 파괴적입니다. 진행하기 전에 새 IP가 LAN에서 접근 가능한지 확인하여 제어 시스템에 대한 원격 접근을 잃지 않도록 하세요.

제어 PC가 재시작된 후 SoftAgent가 자동으로 재개되도록 자동 시작을 구성합니다.

1. 메인 창 설정 탭에서 '자동 시작'을 체크합니다.
2. '저장 및 적용'을 클릭합니다.
3. PowerShell에서 schtasks /Query /TN SoftAgent로 확인합니다 — 예약 작업이 등록되어 있는지 확인합니다.
4. 작업 트리거: ONLOGON(사용자 로그인 후 트리거), 최고 권한 수준.
5. 시작 지연을 설정하려면(네트워크나 종속 서비스 대기), '자동 시작 지연' 필드에 초를 입력합니다.
6. 자동 시작을 비활성화하려면 '자동 시작'을 체크 해제하고 저장합니다.

• schtasks /Query /TN SoftAgent에 작업이 존재하고 활성화되어 있는 것이 표시됩니다.
• 제어 PC를 재시작한 후 로그인 시 시스템 트레이에 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 응답)이 표시됩니다.

• 각 제어 시스템에 대한 명령 세트를 생성하고 장치 이름을 접두사로 사용하세요(예: 'Hall-PC-01_Shutdown') — 유지 관리가 쉬워집니다.
• 전시장 마감과 같은 일괄 작업의 경우 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를 변경하면 해당 SoftControl 명령을 업데이트하세요.

UDP 명령 제어 채널을 복구합니다.

1. 시스템 트레이에 SoftAgent가 표시되는지 확인합니다(프로세스가 실행 중).
2. 발신 포트가 SoftAgent의 구성된 수신 포트(기본 6500)와 일치하는지 확인합니다.
3. Windows 방화벽이 포트 6500의 UDP 인바운드 트래픽을 허용하는지 확인합니다.
4. 먼저 로컬호스트(127.0.0.1)에서 ping을 시도하여 네트워크 문제를 배제한 다음 원격에서 시도합니다.
5. %ProgramData%\SoftAgent\logs\의 로그 파일에서 명령 수신 기록을 확인합니다.

• 127.0.0.1로 ping을 보내면 ok:pong 응답이 와서 SoftAgent와 UDP 포트가 작동하는 것을 확인합니다.
• 원격 시스템에서 ping을 보낼 때도 응답이 와서 네트워크 경로가 열려 있는 것을 확인합니다.

SoftAgent가 모든 시스템 수준 명령을 지원하는 관리자 권한으로 실행되도록 합니다.

1. SoftAgent가 관리자 권한으로 실행되는지 확인합니다: 자동 시작은 예약 작업 최고 권한을 사용하며, 수동 시작 시 exe를 우클릭하고 '관리자 권한으로 실행'을 선택하세요.
2. SoftControl을 통해 명령이 트리거되는 경우 SoftControl 자체는 관리자 권한이 필요하지 않습니다 — 권한은 제어 측의 SoftAgent에서 결정됩니다.
3. 작업 관리자 세부 정보 탭에서 SoftAgent.App.exe의 '상승' 열을 확인합니다 — '예'로 표시되어야 합니다.
4. 관리자로 실행되지 않는 경우 SoftAgent를 종료하고 관리자 권한으로 재시작합니다.

• 작업 관리자 세부 정보 탭에서 SoftAgent.App.exe의 상승 열이 '예'로 표시됩니다.
• volup/voldown 명령이 정상적으로 응답합니다(관리자 불필요 — 기본 확인에 유용).
• lock 명령이 제어 시스템 화면을 잠급니다(방해 수준 — 권한이 올바른 것을 확인).

자동 시작 실패를 진단하고 수정합니다.

1. PowerShell에서 schtasks /Query /TN SoftAgent를 실행하여 예약 작업이 존재하는지 확인합니다.
2. 작업이 없다면 SoftAgent의 설정 탭을 열고 '자동 시작'을 다시 체크하고 저장합니다.
3. PC가 자동 로그인(전시장에서 일반적)을 사용하는지 확인합니다. 작업 트리거가 ONLOGON이므로 사용자가 로그인해야 합니다.
4. 자동 로그인을 설정한 경우 자동 로그인 계정이 작업을 실행할 권한(관리자 계정 필요)이 있는지 확인합니다.
5. %ProgramData%\SoftAgent\logs\의 최근 로그에서 시작 실패 이유를 확인합니다.

• schtasks /Query /TN SoftAgent 출력에 ONLOGON 트리거와 최고 권한이 포함됩니다.
• 제어 PC를 재시작하고 로그인 후 시스템 트레이에 SoftAgent가 자동으로 나타납니다.

감시가 포기한 이유를 이해하고 대상 애플리케이션 모니터링을 복구합니다.

1. SoftAgent 메인 창 감시 탭에서 상태 배지를 확인합니다 — 'GaveUp' 상태를 확인합니다.
2. %ProgramData%\SoftAgent\logs\의 로그 파일에서 구체적인 충돌 이유를 확인합니다(각 충돌 전 오류).
3. 감시된 애플리케이션의 충돌 근본 원인을 수정합니다(설정 오류, 누락된 종속성, 포트 충돌 등).
4. 수정 후 감시 탭에서 해당 항목의 개별 스위치를 껐다가 켜거나(또는 SoftControl에서 run:id 전송) 감시를 다시 트리거합니다.
5. 감시 항목 상태가 '실행 중'으로 변경되고 시간이 지나도 안정적으로 유지되는지 확인합니다.

• 감시된 애플리케이션을 수정한 후 감시 상태가 'GaveUp'에서 '실행 중'으로 변경됩니다.
• 하트비트 JSON에 해당 감시 항목 상태가 실행으로 업데이트된 것이 표시됩니다.

GaveUp은 시스템 리소스에 영향을 주는 무한 재시작 폭풍을 방지하기 위한 의도된 동작입니다. 진정한 해결책은 충돌의 근본 원인을 수정하는 것입니다 — 감시를 수동으로 반복해서 다시 트리거하는 것이 아닙니다.