compshare-cli 0.3.1__tar.gz → 0.3.2__tar.gz

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compshare-cli
-Version: 0.3.1
+Version: 0.3.2
 Summary: Command-line client for CompShare GPU compute
 Author: CompShare
 License-Expression: Apache-2.0
@@ -116,6 +116,11 @@ compshare instance ssh INSTANCE_ID --no-auto-password
 # 自动登录后执行远程命令；远程参数用 -- 与 CLI 选项分隔
 compshare instance ssh INSTANCE_ID -- nvidia-smi --query-gpu=name
 compshare instance ssh INSTANCE_ID -- 'cd /workspace && python train.py'
+# Agent/脚本：执行并返回 ok、phase、exit_code、stdout、stderr、error
+compshare --json instance ssh INSTANCE_ID -- nvidia-smi
+# 强制刷新或禁用本地 SSH 连接缓存
+compshare instance ssh INSTANCE_ID --refresh
+compshare instance ssh INSTANCE_ID --no-cache
 # 上传本地文件或目录，目录会自动递归复制
 compshare instance scp INSTANCE_ID ./model.bin /workspace/model.bin
 compshare instance scp INSTANCE_ID ./dataset /workspace/dataset
@@ -230,6 +235,10 @@ compshare lang       # 查看当前语言
 - `instance ssh` 在支持的交互式终端中通过伪终端自动填写登录密码，不会打印密码或将其放入进程参数。
 - 自动登录会接受首次出现的 SSH 主机密钥；已记录主机的密钥发生变化时仍会拒绝连接。
 - `instance ssh INSTANCE_ID -- COMMAND` 可非交互执行远程命令，透传命令输出和退出码。
+- `--json instance ssh INSTANCE_ID -- COMMAND` 会真实执行命令，并结构化返回退出码、标准输出、标准错误及连接/认证错误阶段。
+- `--json` 始终以 UTF-8 字节输出，不依赖 Windows 活动代码页或终端编码。
+- `instance ssh` 默认将 API 返回的 SSH 命令和密码按 profile/实例缓存 1 小时；Windows 使用当前用户的 DPAPI 加密密码，其他平台将缓存文件权限限制为当前用户。可用 `--refresh` 强制更新、`--no-cache` 禁用；重置密码和重装实例会清除对应缓存。
+- 实例创建是异步操作；`instance create` 默认等待到 `Running`，显式使用 `--no-wait` 才会在创建接口返回后立即退出。`instance ssh` 也会默认等待实例运行后再连接。
 - `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 可自动认证并上传本地文件或目录。
 - `--show-sensitive` 会恢复这些字段的原始值；请勿在共享终端、CI 日志或 Agent 会话中使用。
 - 删除、关机、重启、重装和改配等操作默认要求确认。

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/README.md

@@ -91,6 +91,11 @@ compshare instance ssh INSTANCE_ID --no-auto-password
 # 自动登录后执行远程命令；远程参数用 -- 与 CLI 选项分隔
 compshare instance ssh INSTANCE_ID -- nvidia-smi --query-gpu=name
 compshare instance ssh INSTANCE_ID -- 'cd /workspace && python train.py'
+# Agent/脚本：执行并返回 ok、phase、exit_code、stdout、stderr、error
+compshare --json instance ssh INSTANCE_ID -- nvidia-smi
+# 强制刷新或禁用本地 SSH 连接缓存
+compshare instance ssh INSTANCE_ID --refresh
+compshare instance ssh INSTANCE_ID --no-cache
 # 上传本地文件或目录，目录会自动递归复制
 compshare instance scp INSTANCE_ID ./model.bin /workspace/model.bin
 compshare instance scp INSTANCE_ID ./dataset /workspace/dataset
@@ -205,6 +210,10 @@ compshare lang       # 查看当前语言
 - `instance ssh` 在支持的交互式终端中通过伪终端自动填写登录密码，不会打印密码或将其放入进程参数。
 - 自动登录会接受首次出现的 SSH 主机密钥；已记录主机的密钥发生变化时仍会拒绝连接。
 - `instance ssh INSTANCE_ID -- COMMAND` 可非交互执行远程命令，透传命令输出和退出码。
+- `--json instance ssh INSTANCE_ID -- COMMAND` 会真实执行命令，并结构化返回退出码、标准输出、标准错误及连接/认证错误阶段。
+- `--json` 始终以 UTF-8 字节输出，不依赖 Windows 活动代码页或终端编码。
+- `instance ssh` 默认将 API 返回的 SSH 命令和密码按 profile/实例缓存 1 小时；Windows 使用当前用户的 DPAPI 加密密码，其他平台将缓存文件权限限制为当前用户。可用 `--refresh` 强制更新、`--no-cache` 禁用；重置密码和重装实例会清除对应缓存。
+- 实例创建是异步操作；`instance create` 默认等待到 `Running`，显式使用 `--no-wait` 才会在创建接口返回后立即退出。`instance ssh` 也会默认等待实例运行后再连接。
 - `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 可自动认证并上传本地文件或目录。
 - `--show-sensitive` 会恢复这些字段的原始值；请勿在共享终端、CI 日志或 Agent 会话中使用。
 - 删除、关机、重启、重装和改配等操作默认要求确认。

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "compshare-cli"
-version = "0.3.1"
+version = "0.3.2"
 description = "Command-line client for CompShare GPU compute"
 readme = "README.md"
 requires-python = ">=3.9"

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/src/compshare_cli/__init__.py

@@ -1,3 +1,3 @@
 """CompShare command-line client."""
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/src/compshare_cli/commands/instance.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+import os
 import shlex
 import subprocess
 import sys
 import time
 from decimal import Decimal, InvalidOperation
+from hashlib import sha256
 from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple, TypeVar
 
@@ -12,6 +14,7 @@ import typer
 
 from compshare_cli.api import call, call_captured, collect_pages, invoke
 from compshare_cli.commands.common import confirm, confirm_details, request, runtime
+from compshare_cli.config import ConfigStore
 from compshare_cli.errors import UsageError
 from compshare_cli.i18n import tr
 from compshare_cli.location import instance_location, locate_instance, supported_locations
@@ -30,9 +33,12 @@ from compshare_cli.ssh import (
     PasswordAutomationUnavailable,
     connect_with_password,
     copy_with_password,
+    execute_captured,
+    execute_captured_with_password,
     execute_with_password,
     scp_upload_command,
 )
+from compshare_cli.ssh_cache import DEFAULT_TTL, SSHCredentialCache
 
 app = typer.Typer(help="Manage GPU instances.", no_args_is_help=True)
 ports_app = typer.Typer(help="Manage container port mappings.", no_args_is_help=True)
@@ -203,6 +209,41 @@ def _wait_enabled(state: Runtime, value: Optional[bool]) -> bool:
     return not state.json_output and sys.stdout.isatty()
 
 
+def _create_wait_enabled(value: Optional[bool]) -> bool:
+    """Creation is asynchronous, so wait by default in both human and Agent modes."""
+    return True if value is None else value
+
+
+def _ssh_cache_profile(state: Runtime) -> str:
+    name = (
+        state.profile_name or os.environ.get("COMPSHARE_PROFILE") or ConfigStore().current_profile()
+    )
+    credential = sha256(state.profile.public_key.encode("utf-8")).hexdigest()[:16]
+    return f"{name}:{credential}"
+
+
+def _locate_ssh_instance(
+    state: Runtime,
+    instance: str,
+    *,
+    use_cache: bool,
+    refresh: bool,
+    cache_ttl: int,
+) -> Tuple[str, str, Dict[str, Any], str]:
+    cache = SSHCredentialCache()
+    profile = _ssh_cache_profile(state)
+    if use_cache and not refresh:
+        host = cache.get(profile, instance, ttl=cache_ttl)
+        if host is not None:
+            region, zone = instance_location(host, instance)
+            return region, zone, host, "cache"
+
+    region, zone, host = locate_instance(state, instance)
+    if use_cache:
+        cache.put(profile, instance, host)
+    return region, zone, host, "api"
+
+
 def _wait_for_instance(
     state: Runtime,
     instance: str,
@@ -937,9 +978,16 @@ def create(
     ids = created.get("UHostIds") or created.get("UHostId") or []
     if isinstance(ids, str):
         ids = [ids]
-    if _wait_enabled(state, wait):
+    if _create_wait_enabled(wait):
         result["final"] = [
-            _wait_for_instance(state, item, region=region, timeout=timeout) for item in ids
+            _wait_for_instance(
+                state,
+                item,
+                region=region,
+                desired={"Running"},
+                timeout=timeout,
+            )
+            for item in ids
         ]
     Renderer(state.json_output, state.show_sensitive).details(
         "Operation completed",
@@ -1286,6 +1334,7 @@ def password(
         yes=yes,
         extra={"Password": encode_password(secret)},
     )
+    SSHCredentialCache().delete(_ssh_cache_profile(runtime(ctx)), instance)
 
 
 @app.command("reinstall", help="Reinstall an instance from an image.")
@@ -1318,6 +1367,7 @@ def reinstall(
         wait=wait,
         timeout=timeout,
     )
+    SSHCredentialCache().delete(_ssh_cache_profile(runtime(ctx)), instance)
 
 
 @app.command("resize", help="Change instance CPU, memory, GPU or disk size.")
@@ -1758,16 +1808,65 @@ def ssh(
         "--auto-password/--no-auto-password",
         help="Automatically enter the password returned by the API.",
     ),
+    wait: bool = typer.Option(
+        True,
+        "--wait/--no-wait",
+        help="Wait for the instance to be running before connecting.",
+    ),
+    timeout: int = typer.Option(600, "--timeout", min=1, help="Maximum wait time in seconds."),
+    connect_timeout: int = typer.Option(
+        30,
+        "--connect-timeout",
+        min=1,
+        help="Maximum SSH connection time in seconds.",
+    ),
+    use_cache: bool = typer.Option(
+        True,
+        "--cache/--no-cache",
+        help="Cache SSH connection data to avoid repeated instance queries.",
+    ),
+    cache_ttl: int = typer.Option(
+        DEFAULT_TTL,
+        "--cache-ttl",
+        min=1,
+        help="SSH connection cache lifetime in seconds.",
+    ),
+    refresh: bool = typer.Option(
+        False,
+        "--refresh",
+        help="Refresh SSH connection data from the API before connecting.",
+    ),
 ) -> None:
     state = runtime(ctx)
-    region, zone, host = locate_instance(state, instance)
+    region, zone, host, credential_source = _locate_ssh_instance(
+        state,
+        instance,
+        use_cache=use_cache,
+        refresh=refresh,
+        cache_ttl=cache_ttl,
+    )
+    if wait and host.get("State") and str(host.get("State")) != "Running":
+        ready = _wait_for_instance(
+            state,
+            instance,
+            region=region,
+            desired={"Running"},
+            timeout=timeout,
+        )
+        hosts = ready.get("UHostSet") or []
+        if hosts:
+            host = hosts[0]
+            if use_cache:
+                SSHCredentialCache().put(_ssh_cache_profile(state), instance, host)
     command = host.get("SshLoginCommand")
     raw_password = host.get("Password")
     password = decode_password(str(raw_password)) if raw_password is not None else None
     if not command:
         raise UsageError(tr("Instance {instance} has no SSH login command.", instance=instance))
     argv = [*shlex.split(command), *(remote_command or [])]
-    if print_only or state.json_output:
+    if remote_command:
+        argv[1:1] = ["-o", f"ConnectTimeout={connect_timeout}"]
+    if print_only or (state.json_output and not remote_command):
         Renderer(state.json_output, state.show_sensitive).data(
             {
                 "instance": instance,
@@ -1775,9 +1874,43 @@ def ssh(
                 if not remote_command
                 else f"{command} {shlex.join(remote_command)}",
                 "password": password,
+                "credential_source": credential_source,
             }
         )
         return
+    if remote_command and state.json_output:
+        execution = (
+            execute_captured_with_password(argv, str(password))
+            if password and auto_password
+            else execute_captured(argv)
+        )
+        error = None
+        if not execution.ok:
+            message = execution.stderr.strip() or f"SSH exited with status {execution.exit_code}."
+            error = {
+                "phase": execution.phase,
+                "code": execution.error_code,
+                "message": message,
+            }
+            if credential_source == "cache" and execution.phase in {
+                "authentication",
+                "connection",
+                "ssh",
+            }:
+                SSHCredentialCache().delete(_ssh_cache_profile(state), instance)
+        Renderer(True, state.show_sensitive).data(
+            {
+                "instance": instance,
+                "ok": execution.ok,
+                "phase": execution.phase,
+                "exit_code": execution.exit_code,
+                "stdout": execution.stdout,
+                "stderr": execution.stderr,
+                "error": error,
+                "credential_source": credential_source,
+            }
+        )
+        raise typer.Exit(execution.exit_code)
     if password and state.show_sensitive:
         typer.echo(f"Password: {password}")
     if password and auto_password:
@@ -1795,6 +1928,8 @@ def ssh(
                 err=True,
             )
         else:
+            if exit_code == 255 and credential_source == "cache":
+                SSHCredentialCache().delete(_ssh_cache_profile(state), instance)
             raise typer.Exit(exit_code)
     if password and not state.show_sensitive:
         typer.echo(tr("Password hidden; rerun with --show-sensitive to display it."))
@@ -1806,7 +1941,10 @@ def ssh(
                 instance=instance,
             )
         )
-    raise typer.Exit(subprocess.call(argv))
+    exit_code = subprocess.call(argv)
+    if exit_code == 255 and credential_source == "cache":
+        SSHCredentialCache().delete(_ssh_cache_profile(state), instance)
+    raise typer.Exit(exit_code)
 
 
 @app.command("scp", help="Copy a local file or directory to an instance.")

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/src/compshare_cli/i18n.py

@@ -93,6 +93,15 @@ ZH_TRANSLATIONS: Dict[str, str] = {
     "Month, Day, Dynamic or Postpay.": "目标计费方式：Month、Day、Dynamic 或 Postpay。",
     "Print instead of executing SSH.": "只显示 SSH 命令，不执行连接。",
     "Automatically enter the password returned by the API.": "自动填写 API 返回的登录密码。",
+    "Wait for the instance to be running before connecting.": "连接前等待实例进入运行状态。",
+    "Maximum SSH connection time in seconds.": "SSH 建立连接的最长时间（秒）。",
+    "Cache SSH connection data to avoid repeated instance queries.": (
+        "缓存 SSH 连接信息，避免重复查询实例。"
+    ),
+    "SSH connection cache lifetime in seconds.": "SSH 连接缓存的有效期（秒）。",
+    "Refresh SSH connection data from the API before connecting.": (
+        "连接前从 API 强制刷新 SSH 连接信息。"
+    ),
     "Remote command and arguments; use -- before command options.": (
         "要在实例中执行的命令及参数；命令包含选项时请先使用 -- 分隔。"
     ),

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/src/compshare_cli/output.py

@@ -65,6 +65,22 @@ def sanitized(value: Any, *, show_sensitive: bool = False) -> Any:
     return value
 
 
+def _write_json(payload: Dict[str, Any]) -> None:
+    """Write one UTF-8 JSON document independently of the console code page."""
+    document = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+    stream = sys.stdout
+    binary = getattr(stream, "buffer", None)
+    if binary is not None:
+        stream.flush()
+        binary.write(document.encode("utf-8"))
+        binary.flush()
+        return
+    # String-only test/application streams have no byte encoding contract. Escaping
+    # non-ASCII keeps this fallback valid UTF-8 under every ASCII-compatible encoding.
+    stream.write(json.dumps(payload, ensure_ascii=True, separators=(",", ":")) + "\n")
+    stream.flush()
+
+
 class Renderer:
     def __init__(self, json_output: bool, show_sensitive: bool = False) -> None:
         self.json_output = json_output
@@ -80,7 +96,7 @@ class Renderer:
     ) -> None:
         safe = sanitized(response, show_sensitive=self.show_sensitive)
         if self.json_output:
-            sys.stdout.write(json.dumps(safe, ensure_ascii=False, separators=(",", ":")) + "\n")
+            _write_json(safe)
             return
         if rows is not None and columns:
             self.table(rows, columns)
@@ -139,7 +155,7 @@ class Renderer:
                     details,
                     show_sensitive=self.show_sensitive,
                 )
-            sys.stdout.write(json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n")
+            _write_json(payload)
         else:
             Console(stderr=True).print(f"[red]{tr('Error')}:[/red] {message}")
 

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/src/compshare_cli/ssh.py

@@ -7,6 +7,7 @@ import signal
 import subprocess
 import sys
 import tempfile
+from dataclasses import dataclass
 from typing import Any, List, Optional
 
 _ASKPASS_PASSWORD_FILE_ENV = "COMPSHARE_INTERNAL_SSH_PASSWORD_FILE"
@@ -40,6 +41,21 @@ class PasswordAutomationUnavailable(RuntimeError):
     """Raised when the current terminal cannot safely automate an SSH password."""
 
 
+@dataclass(frozen=True)
+class RemoteExecutionResult:
+    """Captured output and an Agent-friendly classification of an SSH execution."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+    phase: str
+    error_code: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
 def _is_windows() -> bool:
     return os.name == "nt"
 
@@ -171,13 +187,70 @@ def execute_with_password(argv: List[str], password: str) -> int:
     return _run_with_askpass(command, password)
 
 
+def execute_captured_with_password(argv: List[str], password: str) -> RemoteExecutionResult:
+    """Run and capture a non-interactive SSH command without exposing its password."""
+    command = _password_authentication(argv, command_mode=True)
+    completed = _run_with_askpass(command, password, capture=True)
+    assert isinstance(completed, subprocess.CompletedProcess)
+    return remote_execution_result(completed.returncode, completed.stdout, completed.stderr)
+
+
+def execute_captured(argv: List[str]) -> RemoteExecutionResult:
+    """Run and capture a non-interactive SSH command using normal OpenSSH auth."""
+    executable = os.path.basename(argv[0]).casefold()
+    if executable not in {"ssh", "ssh.exe"}:
+        raise PasswordAutomationUnavailable
+    command = [
+        argv[0],
+        "-o",
+        "StrictHostKeyChecking=accept-new",
+        "-n",
+        "-T",
+        *argv[1:],
+    ]
+    completed = subprocess.run(command, capture_output=True, text=True, check=False)
+    return remote_execution_result(completed.returncode, completed.stdout, completed.stderr)
+
+
+def remote_execution_result(exit_code: int, stdout: str, stderr: str) -> RemoteExecutionResult:
+    """Classify common OpenSSH failures while preserving the original diagnostics."""
+    if exit_code == 0:
+        return RemoteExecutionResult(exit_code, stdout, stderr, "completed")
+
+    diagnostic = stderr.casefold()
+    patterns = (
+        ("could not resolve hostname", "connection", "dns_resolution_failed"),
+        ("name or service not known", "connection", "dns_resolution_failed"),
+        ("connection timed out", "connection", "connection_timeout"),
+        ("operation timed out", "connection", "connection_timeout"),
+        ("no route to host", "connection", "network_unreachable"),
+        ("network is unreachable", "connection", "network_unreachable"),
+        ("connection refused", "connection", "connection_refused"),
+        ("host key verification failed", "connection", "host_key_verification_failed"),
+        ("permission denied", "authentication", "authentication_failed"),
+        ("authentication failed", "authentication", "authentication_failed"),
+        ("too many authentication failures", "authentication", "authentication_failed"),
+    )
+    for marker, phase, error_code in patterns:
+        if marker in diagnostic:
+            return RemoteExecutionResult(exit_code, stdout, stderr, phase, error_code)
+    if exit_code == 255:
+        return RemoteExecutionResult(exit_code, stdout, stderr, "ssh", "ssh_failed")
+    return RemoteExecutionResult(exit_code, stdout, stderr, "remote_command", "remote_exit_nonzero")
+
+
 def copy_with_password(argv: List[str], password: str) -> int:
     """Run an SCP upload using the API-provided password."""
     command = _scp_password_authentication(argv)
     return _run_with_askpass(command, password)
 
 
-def _run_with_askpass(command: List[str], password: str) -> int:
+def _run_with_askpass(
+    command: List[str],
+    password: str,
+    *,
+    capture: bool = False,
+) -> Any:
     with tempfile.TemporaryDirectory(prefix="compshare-ssh-") as temporary_directory:
         password_file = os.path.join(temporary_directory, "password")
         descriptor = os.open(password_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
@@ -192,6 +265,14 @@ def _run_with_askpass(command: List[str], password: str) -> int:
             }
         )
         environment.setdefault("DISPLAY", "compshare-ssh")
+        if capture:
+            return subprocess.run(
+                command,
+                env=environment,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
         return subprocess.call(command, env=environment)
 
 

compshare_cli-0.3.2/src/compshare_cli/ssh_cache.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+import time
+from base64 import b64decode, b64encode
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from compshare_cli.config import config_path
+
+CACHE_VERSION = 1
+DEFAULT_TTL = 3600
+_CACHED_HOST_FIELDS = {
+    "Password",
+    "Region",
+    "SshLoginCommand",
+    "State",
+    "UHostId",
+    "Zone",
+}
+_DPAPI_PREFIX = "dpapi:"
+
+
+def _protect_password(password: str) -> Optional[str]:
+    if os.name != "nt":
+        return password
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        class DataBlob(ctypes.Structure):
+            _fields_ = [("size", wintypes.DWORD), ("data", ctypes.POINTER(ctypes.c_byte))]
+
+        raw = password.encode("utf-8")
+        buffer = ctypes.create_string_buffer(raw)
+        source = DataBlob(len(raw), ctypes.cast(buffer, ctypes.POINTER(ctypes.c_byte)))
+        protected = DataBlob()
+        if not ctypes.windll.crypt32.CryptProtectData(
+            ctypes.byref(source),
+            "CompShare SSH cache",
+            None,
+            None,
+            None,
+            0x1,  # CRYPTPROTECT_UI_FORBIDDEN
+            ctypes.byref(protected),
+        ):
+            return None
+        try:
+            encrypted = ctypes.string_at(protected.data, protected.size)
+        finally:
+            ctypes.windll.kernel32.LocalFree(protected.data)
+        return _DPAPI_PREFIX + b64encode(encrypted).decode("ascii")
+    except (AttributeError, OSError, ValueError):
+        return None
+
+
+def _unprotect_password(password: str) -> Optional[str]:
+    if os.name != "nt":
+        return password
+    if not password.startswith(_DPAPI_PREFIX):
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        class DataBlob(ctypes.Structure):
+            _fields_ = [("size", wintypes.DWORD), ("data", ctypes.POINTER(ctypes.c_byte))]
+
+        raw = b64decode(password[len(_DPAPI_PREFIX) :], validate=True)
+        buffer = ctypes.create_string_buffer(raw)
+        source = DataBlob(len(raw), ctypes.cast(buffer, ctypes.POINTER(ctypes.c_byte)))
+        clear = DataBlob()
+        if not ctypes.windll.crypt32.CryptUnprotectData(
+            ctypes.byref(source),
+            None,
+            None,
+            None,
+            None,
+            0x1,  # CRYPTPROTECT_UI_FORBIDDEN
+            ctypes.byref(clear),
+        ):
+            return None
+        try:
+            decrypted = ctypes.string_at(clear.data, clear.size)
+        finally:
+            ctypes.windll.kernel32.LocalFree(clear.data)
+        return decrypted.decode("utf-8")
+    except (AttributeError, OSError, UnicodeDecodeError, ValueError):
+        return None
+
+
+def ssh_cache_path() -> Path:
+    override = os.environ.get("COMPSHARE_SSH_CACHE_FILE")
+    if override:
+        return Path(override).expanduser()
+    return config_path().with_name("ssh-cache.json")
+
+
+class SSHCredentialCache:
+    """Short-lived, profile-scoped cache for API-provided SSH connection data."""
+
+    def __init__(self, path: Optional[Path] = None) -> None:
+        self.path = path or ssh_cache_path()
+
+    @staticmethod
+    def _key(profile: str, instance: str) -> str:
+        return f"{profile}\0{instance}"
+
+    def get(
+        self,
+        profile: str,
+        instance: str,
+        *,
+        ttl: int = DEFAULT_TTL,
+        now: Optional[float] = None,
+    ) -> Optional[Dict[str, Any]]:
+        if ttl <= 0:
+            return None
+        data = self._read()
+        raw = data.get("entries", {}).get(self._key(profile, instance))
+        if not isinstance(raw, dict):
+            return None
+        cached_at = raw.get("cached_at")
+        host = raw.get("host")
+        current = time.time() if now is None else now
+        if not isinstance(cached_at, (int, float)) or current - cached_at > ttl:
+            return None
+        if not isinstance(host, dict):
+            return None
+        if not host.get("SshLoginCommand"):
+            return None
+        result = dict(host)
+        password = result.get("Password")
+        if isinstance(password, str):
+            clear = _unprotect_password(password)
+            if clear is None:
+                return None
+            result["Password"] = clear
+        return result
+
+    def put(
+        self,
+        profile: str,
+        instance: str,
+        host: Dict[str, Any],
+        *,
+        now: Optional[float] = None,
+    ) -> None:
+        cached_host = {key: host[key] for key in _CACHED_HOST_FIELDS if host.get(key) is not None}
+        if not cached_host.get("SshLoginCommand"):
+            return
+        password = cached_host.get("Password")
+        if isinstance(password, str):
+            protected = _protect_password(password)
+            if protected is None:
+                return
+            cached_host["Password"] = protected
+        data = self._read()
+        entries = data.setdefault("entries", {})
+        entries[self._key(profile, instance)] = {
+            "cached_at": time.time() if now is None else now,
+            "host": cached_host,
+        }
+        self._write(data)
+
+    def delete(self, profile: str, instance: str) -> None:
+        data = self._read()
+        entries = data.get("entries", {})
+        if not isinstance(entries, dict) or entries.pop(self._key(profile, instance), None) is None:
+            return
+        self._write(data)
+
+    def _read(self) -> Dict[str, Any]:
+        if not self.path.exists():
+            return {"version": CACHE_VERSION, "entries": {}}
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {"version": CACHE_VERSION, "entries": {}}
+        if (
+            not isinstance(data, dict)
+            or data.get("version") != CACHE_VERSION
+            or not isinstance(data.get("entries"), dict)
+        ):
+            return {"version": CACHE_VERSION, "entries": {}}
+        return data
+
+    def _write(self, data: Dict[str, Any]) -> None:
+        temporary: Optional[Path] = None
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            os.chmod(self.path.parent, stat.S_IRWXU)
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                dir=self.path.parent,
+                prefix=f".{self.path.name}.",
+                suffix=".tmp",
+                delete=False,
+            ) as handle:
+                temporary = Path(handle.name)
+                os.chmod(temporary, stat.S_IRUSR | stat.S_IWUSR)
+                handle.write(json.dumps(data, ensure_ascii=False, separators=(",", ":")) + "\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+            temporary.replace(self.path)
+            os.chmod(self.path, stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            if temporary is not None:
+                try:
+                    temporary.unlink(missing_ok=True)
+                except OSError:
+                    pass
+            # Caching is an optimization and must never prevent an SSH connection.
+            return

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/src/compshare_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compshare-cli
-Version: 0.3.1
+Version: 0.3.2
 Summary: Command-line client for CompShare GPU compute
 Author: CompShare
 License-Expression: Apache-2.0
@@ -116,6 +116,11 @@ compshare instance ssh INSTANCE_ID --no-auto-password
 # 自动登录后执行远程命令；远程参数用 -- 与 CLI 选项分隔
 compshare instance ssh INSTANCE_ID -- nvidia-smi --query-gpu=name
 compshare instance ssh INSTANCE_ID -- 'cd /workspace && python train.py'
+# Agent/脚本：执行并返回 ok、phase、exit_code、stdout、stderr、error
+compshare --json instance ssh INSTANCE_ID -- nvidia-smi
+# 强制刷新或禁用本地 SSH 连接缓存
+compshare instance ssh INSTANCE_ID --refresh
+compshare instance ssh INSTANCE_ID --no-cache
 # 上传本地文件或目录，目录会自动递归复制
 compshare instance scp INSTANCE_ID ./model.bin /workspace/model.bin
 compshare instance scp INSTANCE_ID ./dataset /workspace/dataset
@@ -230,6 +235,10 @@ compshare lang       # 查看当前语言
 - `instance ssh` 在支持的交互式终端中通过伪终端自动填写登录密码，不会打印密码或将其放入进程参数。
 - 自动登录会接受首次出现的 SSH 主机密钥；已记录主机的密钥发生变化时仍会拒绝连接。
 - `instance ssh INSTANCE_ID -- COMMAND` 可非交互执行远程命令，透传命令输出和退出码。
+- `--json instance ssh INSTANCE_ID -- COMMAND` 会真实执行命令，并结构化返回退出码、标准输出、标准错误及连接/认证错误阶段。
+- `--json` 始终以 UTF-8 字节输出，不依赖 Windows 活动代码页或终端编码。
+- `instance ssh` 默认将 API 返回的 SSH 命令和密码按 profile/实例缓存 1 小时；Windows 使用当前用户的 DPAPI 加密密码，其他平台将缓存文件权限限制为当前用户。可用 `--refresh` 强制更新、`--no-cache` 禁用；重置密码和重装实例会清除对应缓存。
+- 实例创建是异步操作；`instance create` 默认等待到 `Running`，显式使用 `--no-wait` 才会在创建接口返回后立即退出。`instance ssh` 也会默认等待实例运行后再连接。
 - `instance scp INSTANCE_ID LOCAL_PATH REMOTE_PATH` 可自动认证并上传本地文件或目录。
 - `--show-sensitive` 会恢复这些字段的原始值；请勿在共享终端、CI 日志或 Agent 会话中使用。
 - 删除、关机、重启、重装和改配等操作默认要求确认。

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/src/compshare_cli.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ src/compshare_cli/qa.py
 src/compshare_cli/runtime.py
 src/compshare_cli/sdk.py
 src/compshare_cli/ssh.py
+src/compshare_cli/ssh_cache.py
 src/compshare_cli.egg-info/PKG-INFO
 src/compshare_cli.egg-info/SOURCES.txt
 src/compshare_cli.egg-info/dependency_links.txt
@@ -42,4 +43,5 @@ tests/test_output.py
 tests/test_parsing.py
 tests/test_qa.py
 tests/test_sdk.py
-tests/test_ssh.py
+tests/test_ssh.py
+tests/test_ssh_cache.py

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/tests/test_cli.py

@@ -9,10 +9,18 @@ from compshare_cli.commands import doctor as doctor_module
 from compshare_cli.commands import image as image_module
 from compshare_cli.commands import instance, team
 from compshare_cli.i18n import localize_command
+from compshare_cli.ssh import RemoteExecutionResult
 
 runner = CliRunner()
 
 
+@pytest.fixture(autouse=True)
+def isolate_ssh_cache(monkeypatch, tmp_path) -> None:
+    monkeypatch.setenv("COMPSHARE_SSH_CACHE_FILE", str(tmp_path / "ssh-cache.json"))
+    monkeypatch.setenv("COMPSHARE_PUBLIC_KEY", "test-public")
+    monkeypatch.setenv("COMPSHARE_PRIVATE_KEY", "test-private")
+
+
 @pytest.mark.parametrize(
     "args",
     [
@@ -375,7 +383,7 @@ def test_create_interactive_wizard_resolves_all_required_parameters(monkeypatch)
     )
     result = runner.invoke(
         cli.app,
-        ["instance", "create", "--yes"],
+        ["instance", "create", "--yes", "--no-wait"],
         input="1\n1\n\n\n",
         env={
             "COMPSHARE_PUBLIC_KEY": "public",
@@ -467,6 +475,14 @@ def test_create_explicit_json_mode_skips_discovery(monkeypatch) -> None:
         return {"RetCode": 0, "UHostIds": ["uhost-test"]}
 
     monkeypatch.setattr(instance, "call", fake_call)
+    waits = []
+    monkeypatch.setattr(
+        instance,
+        "_wait_for_instance",
+        lambda state, value, **kwargs: (
+            waits.append((value, kwargs)) or {"UHostSet": [{"UHostId": value, "State": "Running"}]}
+        ),
+    )
     result = runner.invoke(
         cli.app,
         [
@@ -502,6 +518,7 @@ def test_create_explicit_json_mode_skips_discovery(monkeypatch) -> None:
         "CreateCompShareInstance",
     ]
     assert json.loads(result.stdout)["selection"]["ChargeType"] == "Postpay"
+    assert waits == [("uhost-test", {"region": "cn-wlcb", "desired": {"Running"}, "timeout": 600})]
 
 
 def test_create_dry_run_never_calls_create(monkeypatch) -> None:
@@ -776,6 +793,7 @@ def test_ssh_print_redacts_sensitive_values_by_default(monkeypatch) -> None:
         "instance": "uhost-1",
         "command": "***",
         "password": "***",
+        "credential_source": "api",
     }
 
 
@@ -804,9 +822,41 @@ def test_ssh_print_includes_sensitive_values_only_with_global_flag(monkeypatch)
         "instance": "uhost-1",
         "command": "ssh root@example.invalid",
         "password": "instance-secret",
+        "credential_source": "api",
     }
 
 
+def test_ssh_reuses_cached_connection_data_without_describing_again(monkeypatch) -> None:
+    descriptions = []
+
+    def locate(state, value):
+        descriptions.append(value)
+        return (
+            "cn-wlcb",
+            "cn-wlcb-01",
+            {
+                "UHostId": value,
+                "Region": "cn-wlcb",
+                "Zone": "cn-wlcb-01",
+                "State": "Running",
+                "SshLoginCommand": "ssh root@example.invalid",
+                "Password": "instance-secret",
+            },
+        )
+
+    monkeypatch.setattr(instance, "locate_instance", locate)
+    args = ["--json", "instance", "ssh", "uhost-1", "--print"]
+
+    first = runner.invoke(cli.app, args)
+    second = runner.invoke(cli.app, args)
+
+    assert first.exit_code == 0, first.output
+    assert second.exit_code == 0, second.output
+    assert json.loads(first.stdout)["credential_source"] == "api"
+    assert json.loads(second.stdout)["credential_source"] == "cache"
+    assert descriptions == ["uhost-1"]
+
+
 def test_ssh_automatically_enters_hidden_password_by_default(monkeypatch) -> None:
     monkeypatch.setattr(
         instance,
@@ -992,6 +1042,8 @@ def test_ssh_executes_remote_command_with_password_and_returns_its_status(monkey
         (
             [
                 "ssh",
+                "-o",
+                "ConnectTimeout=30",
                 "-p",
                 "2222",
                 "root@example.invalid",
@@ -1003,6 +1055,72 @@ def test_ssh_executes_remote_command_with_password_and_returns_its_status(monkey
     ]
 
 
+def test_ssh_json_executes_and_returns_structured_connection_error(monkeypatch) -> None:
+    monkeypatch.setattr(
+        instance,
+        "locate_instance",
+        lambda state, value: (
+            "cn-wlcb",
+            "cn-wlcb-01",
+            {
+                "UHostId": value,
+                "State": "Running",
+                "SshLoginCommand": "ssh root@example.invalid",
+                "Password": "instance-secret",
+            },
+        ),
+    )
+    executions = []
+    monkeypatch.setattr(
+        instance,
+        "execute_captured_with_password",
+        lambda argv, password: (
+            executions.append((argv, password))
+            or RemoteExecutionResult(
+                255,
+                "",
+                "ssh: connect to host example.invalid port 22: Connection timed out\n",
+                "connection",
+                "connection_timeout",
+            )
+        ),
+    )
+
+    result = runner.invoke(
+        cli.app,
+        ["--json", "instance", "ssh", "uhost-1", "--", "hostname"],
+    )
+
+    assert result.exit_code == 255, result.output
+    payload = json.loads(result.stdout)
+    assert payload == {
+        "instance": "uhost-1",
+        "ok": False,
+        "phase": "connection",
+        "exit_code": 255,
+        "stdout": "",
+        "stderr": "ssh: connect to host example.invalid port 22: Connection timed out\n",
+        "error": {
+            "phase": "connection",
+            "code": "connection_timeout",
+            "message": "ssh: connect to host example.invalid port 22: Connection timed out",
+        },
+        "credential_source": "api",
+    }
+    assert executions == [
+        (
+            [
+                "ssh",
+                "-o",
+                "ConnectTimeout=30",
+                "root@example.invalid",
+                "hostname",
+            ],
+            "instance-secret",
+        )
+    ]
+
+
 def test_ssh_print_includes_quoted_remote_command_when_sensitive(monkeypatch) -> None:
     monkeypatch.setattr(
         instance,
@@ -1038,6 +1156,7 @@ def test_ssh_print_includes_quoted_remote_command_when_sensitive(monkeypatch) ->
         "instance": "uhost-1",
         "command": "ssh root@example.invalid 'cd /workspace && python train.py'",
         "password": "instance-secret",
+        "credential_source": "api",
     }
 
 

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/tests/test_output.py

@@ -1,5 +1,7 @@
 import json
+from io import BytesIO, TextIOWrapper
 
+from compshare_cli import output
 from compshare_cli.output import Renderer, sanitized
 
 
@@ -31,6 +33,17 @@ def test_json_renderer_emits_one_compact_document(capsys) -> None:
     assert json.loads(output) == {"RetCode": 0, "value": "中文"}
 
 
+def test_json_renderer_writes_utf8_bytes_under_a_gbk_stdout(monkeypatch) -> None:
+    raw = BytesIO()
+    gbk_stdout = TextIOWrapper(raw, encoding="gbk")
+    monkeypatch.setattr(output.sys, "stdout", gbk_stdout)
+
+    Renderer(True).data({"ok": False, "error": "尚未配置 API 密钥。"})
+
+    document = raw.getvalue().decode("utf-8")
+    assert json.loads(document) == {"ok": False, "error": "尚未配置 API 密钥。"}
+
+
 def test_table_accepts_no_rows(capsys) -> None:
     Renderer(False).table(None, (("Id", "ID"),))
 

{compshare_cli-0.3.1 → compshare_cli-0.3.2}/tests/test_ssh.py

@@ -1,6 +1,8 @@
 from pathlib import Path
 from types import SimpleNamespace
 
+import pytest
+
 from compshare_cli import ssh
 
 
@@ -150,6 +152,29 @@ def test_execute_with_password_uses_askpass_without_password_in_argv(monkeypatch
     assert ssh._ASKPASS_PASSWORD_FILE_ENV not in ssh.os.environ
 
 
+@pytest.mark.parametrize(
+    ("stderr", "phase", "error_code"),
+    [
+        (
+            "ssh: connect to host x port 22: Connection timed out",
+            "connection",
+            "connection_timeout",
+        ),
+        (
+            "root@x: Permission denied (publickey,password).",
+            "authentication",
+            "authentication_failed",
+        ),
+        ("unclassified OpenSSH failure", "ssh", "ssh_failed"),
+    ],
+)
+def test_remote_execution_result_classifies_ssh_failures(stderr, phase, error_code) -> None:
+    result = ssh.remote_execution_result(255, "", stderr)
+
+    assert result.phase == phase
+    assert result.error_code == error_code
+
+
 def test_askpass_reads_and_removes_internal_password_file(monkeypatch, capsys, tmp_path) -> None:
     password_file = tmp_path / "password"
     password_file.write_text("instance-secret")

compshare_cli-0.3.2/tests/test_ssh_cache.py

@@ -0,0 +1,47 @@
+import json
+import stat
+
+from compshare_cli.ssh_cache import SSHCredentialCache
+
+
+def _host(password="secret"):
+    return {
+        "UHostId": "uhost-1",
+        "Region": "cn-wlcb",
+        "Zone": "cn-wlcb-01",
+        "State": "Running",
+        "SshLoginCommand": "ssh root@example.invalid",
+        "Password": password,
+        "Unrelated": "not-cached",
+    }
+
+
+def test_ssh_cache_round_trip_is_profile_scoped_and_permission_restricted(tmp_path) -> None:
+    path = tmp_path / "ssh-cache.json"
+    cache = SSHCredentialCache(path)
+    cache.put("alpha", "uhost-1", _host(), now=100)
+
+    assert cache.get("alpha", "uhost-1", ttl=60, now=150) == {
+        key: value for key, value in _host().items() if key != "Unrelated"
+    }
+    assert cache.get("beta", "uhost-1", ttl=60, now=150) is None
+    assert stat.S_IMODE(path.stat().st_mode) == 0o600
+    saved = json.loads(path.read_text(encoding="utf-8"))
+    assert "Unrelated" not in next(iter(saved["entries"].values()))["host"]
+
+
+def test_ssh_cache_expires_and_can_be_deleted(tmp_path) -> None:
+    cache = SSHCredentialCache(tmp_path / "ssh-cache.json")
+    cache.put("default", "uhost-1", _host(), now=100)
+
+    assert cache.get("default", "uhost-1", ttl=60, now=161) is None
+    assert cache.get("default", "uhost-1", ttl=60, now=160) is not None
+    cache.delete("default", "uhost-1")
+    assert cache.get("default", "uhost-1", ttl=60, now=150) is None
+
+
+def test_corrupt_ssh_cache_is_ignored(tmp_path) -> None:
+    path = tmp_path / "ssh-cache.json"
+    path.write_text("not json", encoding="utf-8")
+
+    assert SSHCredentialCache(path).get("default", "uhost-1") is None