feat: 消息会话支持 ws_scheme 参数以选择 ws/wss 协议

GitOrigin-RevId: efff209be34477a31b51980dc5bf82d805248003

Author: yangsijia-celina

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Message sessions accept an explicit `ws_scheme` (`"ws"` or `"wss"`, default
+  `"wss"`) so callers can dial `ws://` when the ArkClaw endpoint returned by
+  `GetClawInstanceChatToken` has no protocol prefix and the environment only
+  exposes plain WebSocket. The new `arkclaw message send|shell --ws-scheme`
+  CLI flag mirrors the SDK option. Endpoints already carrying an explicit
+  `http(s)://` / `ws(s)://` prefix keep their scheme.
+
 ## [0.2.0] - 2026-07-31
 
 ### Added

README.md

@@ -383,6 +383,7 @@ with client.create_message_session(
     instance_id="ci-xxx",
     wait=True,
     receive_timeout=120,
+    ws_scheme="wss",  # optional; when set, use the declared protocol
 ) as session:
     result = session.send_message("你好")
     print(result)
@@ -396,7 +397,8 @@ arkclaw message send \
   --instance-id ci-xxx \
   --message "你好" \
   --stream \
-  --text-only
+  --text-only \
+  --ws-scheme wss   # optional; when set, use the declared protocol
 
 arkclaw message shell \
   --space-id csi-xxx \

arkclaw/cli/messages.py

@@ -62,6 +62,12 @@ def _add_common_session_args(parser: argparse.ArgumentParser) -> None:
         default="agent:main:main",
         help="Logical ArkClaw chat session key to reuse across reconnects",
     )
+    parser.add_argument(
+        "--ws-scheme",
+        choices=["ws", "wss"],
+        default="wss",
+        help="WebSocket scheme to use when the token endpoint has no protocol prefix (default: wss)",
+    )
 
 
 def _build_session(args: argparse.Namespace) -> ArkClawMessageSession:
@@ -76,6 +82,7 @@ def _build_session(args: argparse.Namespace) -> ArkClawMessageSession:
         receive_timeout=args.receive_timeout,
         connect_retries=args.connect_retries,
         session_key=args.session_key,
+        ws_scheme=args.ws_scheme,
     )
 
 

arkclaw/message.py

@@ -153,7 +153,15 @@ def _render_stream_message(data: str, *, pretty: bool, text_only: bool) -> list[
     return []
 
 
-def _build_websocket_url(*, endpoint: str, chat_token: str, claw_instance_id: str) -> str:
+def _build_websocket_url(
+    *,
+    endpoint: str,
+    chat_token: str,
+    claw_instance_id: str,
+    default_scheme: str = "wss",
+) -> str:
+    if default_scheme not in ("ws", "wss"):
+        raise ValidationError(f"ws_scheme must be 'ws' or 'wss', got {default_scheme!r}")
     normalized = endpoint.strip()
     if normalized.startswith("wss://") or normalized.startswith("ws://"):
         base = normalized
@@ -162,7 +170,7 @@ def _build_websocket_url(*, endpoint: str, chat_token: str, claw_instance_id: st
     elif normalized.startswith("http://"):
         base = "ws://" + normalized[len("http://") :]
     else:
-        base = f"wss://{normalized}"
+        base = f"{default_scheme}://{normalized}"
 
     if "?" not in base:
         scheme_split = base.split("://", 1)
@@ -235,9 +243,12 @@ def __init__(
         connect_retries: int = 2,
         session_key: str = "agent:main:main",
         protocol_version: int = 4,
+        ws_scheme: str = "wss",
     ) -> None:
         if connect_retries < 0:
             raise ValidationError("connect_retries must be >= 0")
+        if ws_scheme not in ("ws", "wss"):
+            raise ValidationError(f"ws_scheme must be 'ws' or 'wss', got {ws_scheme!r}")
         self.client = client
         self.space_id = space_id
         self.instance_id = instance_id
@@ -251,6 +262,7 @@ def __init__(
         if protocol_version not in (3, 4):
             raise ValidationError(f"protocol_version must be 3 or 4, got {protocol_version}")
         self.protocol_version = protocol_version
+        self.ws_scheme = ws_scheme
 
         self._websocket_module: Any | None = None
         self._timeout_exc: type[BaseException] = TimeoutError
@@ -438,6 +450,7 @@ def _refresh_chat_access(self) -> None:
             endpoint=endpoint,
             chat_token=chat_token,
             claw_instance_id=claw_instance_id,
+            default_scheme=self.ws_scheme,
         )
 
     def _get_websocket_module(self) -> Any: