SoftAgent ユーザーマニュアル

環境が要件を満たしていることを確認し、インストールの準備をする。

1. ターゲットPCがWindows 10/11 x64で動作していることを確認します。
2. 管理者アカウント権限があることを確認します（インストーラーはUAC昇格プロンプトを表示します）。
3. ファイアウォールがSoftAgentのリッスンポートであるUDPポート6500への着信通信を許可していることを確認します。
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:portを入力します。
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. 3つのリスクレベル：安全（中断なし、繰り返し可能） / 破壊的（セッション/プロセスを中断するがデータ損失なし） / 危険（シャットダウン/再起動/ログオフなど）。
5. 危険コマンドはUIで確認ダイアログを表示します。リモートでトリガーする場合は、呼び出し側が意図を確認する責任があります。

• pingを送信するとok:pongが返り、接続とコマンド形式が正しいことを確認。
• describeを送信すると、サポートされているすべてのコマンドとそのリスクレベルを含むJSON機能リストが返る。

describeコマンドはこのSoftAgentインスタンスの完全な機能リストを返します。各コマンドの名前、説明、リスクレベル、確認が必要かどうかが含まれており、SoftControlやAIシステムと統合する際の機能検出に役立ちます。

日常的な音量制御と状態監視のための安全コマンドを習得する。

1. 接続プローブ：ping（ok:pongで応答、エージェントがオンラインであることを確認）。
2. 機能リストを取得：describe（すべてのコマンドの説明とリスクレベルを含むJSONを返す）。
3. デバイス検出：discover（ホスト名、IP、MAC、音量、監視状態を含むハートビートスナップショットJSONを返す）。
4. 音量を1ステップ上げる：volup（デフォルトで呼び出しごとに+5%）。
5. 音量を1ステップ下げる：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:port）：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アドレスでpingが成功する。
• SoftAgentのハートビートJSONに更新されたIPアドレスが表示される。

IPの変更は危険な操作です。実行前に、新しいIPがLAN上で到達可能であることを確認して、管理対象マシンへのリモートアクセスを失わないようにしてください。

管理対象PCの再起動後にSoftAgentが自動的に再起動するよう自動起動を設定する。

1. メインウィンドウの「設定」タブで「自動起動」にチェックを入れます。
2. 「保存して適用」をクリックします。
3. PowerShellで確認します：schtasks /Query /TN SoftAgent — スケジュールタスクが登録されていることを確認します。
4. タスクのトリガー：ONLOGON（ユーザーログイン後にトリガー）、権限レベル：HIGHEST。
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応答）が表示される。

• 各管理対象マシンのコマンドセットを作成する際、デバイス名をプレフィックスとして使用します（例：「ホール-PC-01_シャットダウン」）。これにより保守が容易になります。
• 展示の終了などの一括操作には、SoftControlのコマンドグループを使用します — 複数のマシンのシャットダウンコマンドを1つのグループに追加して1回でトリガーします。

ハートビート報告を設定して、SoftControlから管理対象マシンのオンライン状態を監視する。

1. SoftAgentの設定で、報告アドレスをSoftControlのIP:port（SoftControlの外部UDPインターフェース、デフォルト8818）に設定します。
2. SoftAgentは起動時に1回ハートビートを即時送信し、その後設定された間隔（デフォルト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秒、毎回2倍；時間ウィンドウ内の制限を超えると放棄）。

• 監視されているプログラムが監視リストに「実行中」の状態で表示される。
• 監視対象プロセスを手動で終了すると、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コマンドで管理対象マシンの画面がロックされる（破壊的レベル — 権限が正しいことを確認）。

自動起動の失敗を診断して修正する。

1. PowerShellでschtasks /Query /TN SoftAgentを実行して、スケジュールタスクが存在することを確認します。
2. タスクが存在しない場合、SoftAgentの「設定」タブを開いて「自動起動」に再度チェックを入れ、保存します。
3. PCが手動ログインを待っているのではなく（展示では一般的）、自動ログインを使用していることを確認します — タスクのトリガーはONLOGONで、ユーザーのログインが必要です。
4. 自動ログインが設定されている場合、自動ログインアカウントがタスクを実行する権限を持っていることを確認します（管理者アカウントが必要）。
5. %ProgramData%\SoftAgent\logs\の最近のログで起動失敗の理由を確認します。

• schtasks /Query /TN SoftAgentの出力にONLOGONトリガーとHIGHEST権限が含まれている。
• 管理対象PCを再起動してログインすると、SoftAgentが自動的にシステムトレイに表示される。

なぜ監視が放棄されたかを理解し、ターゲットアプリケーションの監視を復旧する。

1. SoftAgentのメインウィンドウの「監視」タブで状態バッジを確認します — 「放棄」状態を確認。
2. %ProgramData%\SoftAgent\logs\のログファイルで具体的なクラッシュ理由（各クラッシュ前のエラー）を確認します。
3. 監視対象アプリケーションのクラッシュの根本原因を修正します（設定エラー、依存関係の欠如、ポートの競合など）。
4. 修正後、「監視」タブで監視アイテムの個別スイッチをオフにしてから再度オンにするか（またはSoftControlからrun:idを送信）、監視を再トリガーします。
5. 監視アイテムの状態が「実行中」に変わり、時間の経過とともに安定していることを確認します。

• 監視対象アプリケーションを修正した後、監視の状態が「放棄」から「実行中」に変わる。
• ハートビートJSONに対応する監視アイテムの状態が実行中に更新されて表示される。

放棄は無限再起動ストームがシステムリソースに影響するのを防ぐための意図的な動作です。本当の解決策はクラッシュの根本原因を修正することであり、監視を手動で繰り返しトリガーすることではありません。