WebSocket API v1

エンドポイント：

ws://127.0.0.1:25548/api/v1/ws
wss://<リモートアクセスURL>/api/v1/ws

プロトコルバージョンは v=1 です。すべてのメッセージは JSON テキストフレームとして送受信されます。

メッセージエンベロープ

リクエスト

{
  "v": 1,
  "type": "request",
  "id": "req-001",
  "method": "instances.list",
  "params": {}
}

フィールド	制約事項
v	1 固定
type	request
id	1〜100文字。同一セッション内で一意であること
method	登録済みのメソッド名
params	厳格なスキーマ。未定義フィールドの混入は禁止

成功レスポンス

{ "v": 1, "type": "response", "id": "req-001", "ok": true, "result": [] }

失敗レスポンス

{
  "v": 1,
  "type": "response",
  "id": "req-001",
  "ok": false,
  "error": { "code": "INVALID_PARAMS", "message": "リクエスト形式またはパラメータが不正です", "details": [] }
}

イベント通知

{ "v": 1, "type": "event", "topic": "overview", "data": {} }

セッション管理

接続確立後、サーバーから初期イベントがプッシュされます：

{
  "v": 1,
  "type": "event",
  "topic": "session",
  "data": { "authRequired": true, "protocolVersion": 1 }
}

• authRequired: false の場合、ループバック接続かつパスワード未設定であるため、そのままメソッドを呼び出し可能です。
• 未認証状態の読み取りタイムアウトは30秒、認証後は60秒です。

ログイン

{
  "v": 1, "type": "request", "id": "a1", "method": "auth.login",
  "params": { "password": "<WebUI パスワード>" }
}

リモートペアリングクライアントはマスターパスワードではなくペアリング認証情報を送信します。ペアリングが取り消された場合、次回のリクエスト（15秒ごとのハートビートを含む）で UNAUTHORIZED が返却されます。

イベント購読

{
  "v": 1, "type": "request", "id": "s1", "method": "events.subscribe",
  "params": { "instance": "ap", "topics": ["overview", "logs", "statistics"] }
}

トピック	配信データ内容	サンプリング周期
instances	インスタンス一覧と実行ステータス	2秒
overview	現在実行中のタスク、保有資材	1秒
logs	増分ログ	変更時即時プッシュ
preview	スクリーンショットプレビュー	変更時即時プッシュ
statistics	統計レポート	1秒
notifications	通知ストリーム	イベント発生時
stock	取引所・交換情報	イベント発生時

購読は全体上書き方式です

再度購読を実行すると以前の購読トピックはすべて解除されます。Android ホストはこの仕様上、グローバルな購読者を1つのみ保持します。外部ツールとフロントエンドが同一インスタンスを同時に購読して競合させないようご注意ください。

制限事項とエラーコード

項目	上限値
単一メッセージサイズ	≤ 8 MiB
通常リクエストサイズ	≤ 1 MiB
大容量リクエストの例外	mind.import、mind.recognize、mind.save、mind.calculate
レート制限	30 リクエスト / 秒

エラーコード	意味
INVALID_REQUEST	メッセージエンベロープまたはサイズが不正
INVALID_PARAMS	パラメータのバリデーションに失敗
UNAUTHORIZED	未認証、またはペアリング失効
TLS_REQUIRED	リモート経由のアカウント操作で WSS が未使用
RATE_LIMITED	リクエストレート超過
DUPLICATE_REQUEST	リクエスト ID の重複
INTERNAL_ERROR	サーバー内部エラー（詳細は秘匿）

パラメータエラー時はフィールドのパスと期待される型のみが返却され、入力値はエコーバックされません。

代表的なリクエストフロー

インスタンス一覧の取得と概要の確認

{"v":1,"type":"request","id":"1","method":"instances.list","params":{}}
{"v":1,"type":"request","id":"2","method":"overview.get","params":{"instance":"ap"}}

スケジューラーの開始と停止

{"v":1,"type":"request","id":"3","method":"scheduler.start","params":{"instance":"ap"}}
{"v":1,"type":"request","id":"4","method":"scheduler.stop","params":{"instance":"ap"}}

設定の変更

{
  "v": 1, "type": "request", "id": "5", "method": "config.patch",
  "params": {
    "instance": "ap",
    "revision": "<前回取得した revision>",
    "changes": [{ "path": "Research.Scheduler.Enable", "value": true }]
  }
}

revision による楽観的排他制御が行われます。現在のバージョンと一致しない場合はコンフリクトエラーが返るため、再度 config.get で取得し直して送信する必要があります。

タスクの即時実行

{"v":1,"type":"request","id":"6","method":"tasks.run","params":{"instance":"ap","task":"Research"}}

これは「スケジュールをバイパスして即座に実行する」処理であり、NextRun の値は更新されません。

ログの増分取得

{"v":1,"type":"request","id":"7","method":"logs.get","params":{"instance":"ap","after":128}}

after にカーソル番号を指定することで、それ以降の増分ログエントリを取得できます。

メソッド一覧

以下のテーブルは frontend/src/api/contract.json から自動生成されています。各行を展開するとパラメータの型定義と制約を確認できます。

72 / 72 个方法 · 契约版本 1 · 7de6bb9

クライアント実装のベストプラクティス

1. 接続後は直ちにリクエストを送信せず、まず session イベントを受信してからログイン要否を判定してください。
2. リクエスト id は単調増加番号または UUID を使用し、絶対に再利用しないでください。
3. 切断時は指数バックオフにより再接続を試み、トピックを再購読してください。
4. 購読開始時はまず overview.get で全量を一度取得し、以後はイベントによる増分同期を行ってください。
5. 書き込み操作後は成功を前提とせず、状態を再読込して確認してください。
6. パスワードを URL に含めないでください（カスタムヘッダーを設定できないクライアント向けの MCP ?key= は例外です）。

セキュリティ上の推奨事項

• リモートアクセス時は必ず WSS を使用してください。ローカル外からのアカウント操作時は TLS が強制されます。
• WebSocket アドレスとパスワードが写り込んだスクリーンショットを公開・共有しないでください。
• 独自開発のモニタリングダッシュボード等では読み取り専用メソッドのみを利用し、scheduler.stop などの破壊的操作の誤実行を防いでください。