media-studio-agent-sdk 0.1.0b1__tar.gz

media_studio_agent_sdk-0.1.0b1/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets / local overrides（仓库不放任何默认 key）
+.env
+.env.*
+!.env.example
+.claude/settings.local.json
+*.pem
+*.key
+
+# Project specific
+*.log
+.dsh-test-tmp/
+.assets-test-tmp/
+.build-stage/
+.dev-install-test-tmp/
+.cli-test-tmp/
+.local/
+.tmp-wheel/

media_studio_agent_sdk-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI302
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

media_studio_agent_sdk-0.1.0b1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: media-studio-agent-sdk
+Version: 0.1.0b1
+Summary: AI302 Media Studio agent runtime SDK — FastAPI / WebSocket / replayable runs
+Project-URL: Homepage, https://github.com/ai302/claude-sandbox-sdk
+Project-URL: Repository, https://github.com/ai302/claude-sandbox-sdk
+Project-URL: Issues, https://github.com/ai302/claude-sandbox-sdk/issues
+Author: AI302
+License: MIT
+License-File: LICENSE
+Keywords: agent,fastapi,media,runtime,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: deepseek-harness-runtime-bin==0.2.1rc2
+Requires-Dist: deepseek-harness-sdk==0.2.1rc2
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]>=0.23.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hatchling>=1.21; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# media-studio-agent-sdk
+
+AI302 Media Studio 的 agent 运行时 SDK：FastAPI + WebSocket，逐 step 下发原始
+agent 通知，并提供可复查的 run 帧回放。
+
+## 安装
+
+```bash
+pip install media-studio-agent-sdk
+```
+
+## 启动
+
+```bash
+media-studio-agent --host 0.0.0.0 --port 8300
+```
+
+## 接口速览
+
+- `WS /ws/chat`：`init` → `message` → 原始运行时通知 + `run_started` /
+  `run_finished` 控制帧；每帧带 `run_id` / `seq`。
+- `GET /runs`、`GET /runs/{run_id}/frames?since_seq=`：与 WSS 一致的帧回放。
+- `GET /runs/{run_id}/trace`、`/trace.txt`：根 + 子 agent 的 step 级轨迹。
+- `GET /health`：服务状态 + 活动运行时数。
+
+部署配置、完整 WS 协议与已知限制见仓库 `docs/`。
+
+## 发版
+
+推送 `agent-v*` tag 触发 `.github/workflows/publish-agent.yml`；版本与流程见仓库
+`docs/release.md`。

media_studio_agent_sdk-0.1.0b1/README.md

@@ -0,0 +1,31 @@
+# media-studio-agent-sdk
+
+AI302 Media Studio 的 agent 运行时 SDK：FastAPI + WebSocket，逐 step 下发原始
+agent 通知，并提供可复查的 run 帧回放。
+
+## 安装
+
+```bash
+pip install media-studio-agent-sdk
+```
+
+## 启动
+
+```bash
+media-studio-agent --host 0.0.0.0 --port 8300
+```
+
+## 接口速览
+
+- `WS /ws/chat`：`init` → `message` → 原始运行时通知 + `run_started` /
+  `run_finished` 控制帧；每帧带 `run_id` / `seq`。
+- `GET /runs`、`GET /runs/{run_id}/frames?since_seq=`：与 WSS 一致的帧回放。
+- `GET /runs/{run_id}/trace`、`/trace.txt`：根 + 子 agent 的 step 级轨迹。
+- `GET /health`：服务状态 + 活动运行时数。
+
+部署配置、完整 WS 协议与已知限制见仓库 `docs/`。
+
+## 发版
+
+推送 `agent-v*` tag 触发 `.github/workflows/publish-agent.yml`；版本与流程见仓库
+`docs/release.md`。

media_studio_agent_sdk-0.1.0b1/dsh_sandbox/__init__.py

@@ -0,0 +1,5 @@
+"""DSH 沙盒服务（``/ws/chat`` + 可复查回放）。"""
+
+__version__ = "0.1.0b1"
+
+__all__ = ["__version__"]

media_studio_agent_sdk-0.1.0b1/dsh_sandbox/__main__.py

@@ -0,0 +1,370 @@
+"""启动入口：``python -m dsh_sandbox``（开发时 ``PYTHONPATH=app``）。
+
+生产镜像里可以直接::
+
+    uvicorn --factory dsh_sandbox.server:create_app_from_env --host 0.0.0.0 --port 8300
+
+本地（Windows/macOS）常用::
+
+    python -m dsh_sandbox --port 8300 \
+        --workspace C:\\work\\agent-workspace \
+        --data-dir C:\\work\\.dsh-sandbox
+
+想先确认最终生效的路径/模型，加 ``--print-config``（不会创建目录、不启动服务）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import logging
+import os
+import socket
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import __version__
+from .config import DEFAULT_DATA_DIR, DEFAULT_WORKSPACE, Settings
+
+logger = logging.getLogger(__name__)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="media-studio-agent",
+        description="Media Studio agent 服务：WebSocket 逐 step 输出 + HTTP 复查",
+    )
+    parser.add_argument("--host", default=None, help="监听地址（默认 DSH_SANDBOX_HOST / 0.0.0.0）")
+    parser.add_argument("--port", type=int, default=None, help="监听端口（默认 DSH_SANDBOX_PORT / 8300）")
+    parser.add_argument("--log-level", default=None, help="DEBUG / INFO / WARNING / ERROR")
+    parser.add_argument(
+        "--workspace",
+        default=None,
+        help=f"agent 工作目录（默认按平台：Linux /home/user/workspace，其它 {DEFAULT_WORKSPACE}）",
+    )
+    parser.add_argument("--data-dir", default=None, help=f"run 落盘目录（默认 {DEFAULT_DATA_DIR}）")
+    parser.add_argument(
+        "--assets-dir",
+        default=None,
+        help="agent 资产版本仓（默认 <data-dir>/assets）；控制中台经 POST /assets 投放",
+    )
+    parser.add_argument("--runtime-home", default=None, help="运行时持久化 home（默认 <data-dir>/home）")
+    parser.add_argument("--provider", default=None, help="模型 provider id（默认 deepseek-official）")
+    parser.add_argument("--model", default=None, help="模型 id（默认 deepseek-v4-flash）")
+    parser.add_argument("--effort", default=None, help="reasoning effort（等价 EFFORT 环境变量）")
+    parser.add_argument("--max-tokens", type=int, default=None, help="单次输出上限（默认 49152）")
+    parser.add_argument(
+        "--context-window",
+        type=int,
+        default=None,
+        help="路由上下文容量（缺失时用于算 run_finished.context 百分比；0=不兜底）",
+    )
+    parser.add_argument(
+        "--patch",
+        action="append",
+        default=None,
+        metavar="FILE",
+        help="运行时 profile patch（可重复）；第三方网关的 compat 配置从这里投放",
+    )
+    parser.add_argument("--ssl-keyfile", default=None, help="TLS 私钥（服务自己终止 wss 时用）")
+    parser.add_argument("--ssl-certfile", default=None, help="TLS 证书（服务自己终止 wss 时用）")
+    parser.add_argument("--print-config", action="store_true", help="打印生效配置后退出（不建目录、不启动）")
+    parser.add_argument("--check-dirs", action="store_true", help="逐个检查/创建启动目录并报告可写性，然后退出")
+    parser.add_argument("--version", action="version", version=f"media-studio-agent-sdk {__version__}")
+    return parser
+
+
+def build_settings(args: argparse.Namespace) -> Settings:
+    settings = Settings()
+    if args.host is not None:
+        settings.host = args.host
+    if args.port is not None:
+        settings.port = args.port
+    if args.log_level is not None:
+        settings.log_level = args.log_level
+    if args.workspace is not None:
+        settings.workspace = Path(args.workspace).expanduser()
+    if args.data_dir is not None:
+        settings.data_dir = Path(args.data_dir).expanduser()
+    if args.assets_dir is not None:
+        settings.assets_dir = Path(args.assets_dir).expanduser()
+    if args.runtime_home is not None:
+        settings.dsh_home = Path(args.runtime_home).expanduser()
+    if args.provider is not None:
+        settings.provider = args.provider
+    if args.model is not None:
+        settings.model = args.model
+    if args.effort is not None:
+        settings.reasoning_effort = args.effort or None
+    if args.max_tokens is not None:
+        settings.max_tokens = args.max_tokens
+    if args.context_window is not None:
+        settings.context_window = args.context_window
+    if args.patch:
+        settings.provider_patches = tuple(args.patch)
+    if args.ssl_keyfile is not None:
+        settings.ssl_keyfile = args.ssl_keyfile
+    if args.ssl_certfile is not None:
+        settings.ssl_certfile = args.ssl_certfile
+    return settings
+
+
+def print_config(settings: Settings) -> None:
+    """打印最终生效值（供本地排查路径/模型用）。"""
+    rows = [
+        ("workspace", settings.workspace),
+        ("data_dir", settings.data_dir),
+        ("assets_dir", settings.resolved_assets_dir),
+        ("runtime_home", settings.resolved_dsh_home),
+        ("host", settings.host),
+        ("port", settings.port),
+        ("provider", settings.provider),
+        ("model", settings.model),
+        ("reasoning_effort", settings.reasoning_effort or ""),
+        ("max_tokens", settings.max_tokens),
+        ("context_window", settings.context_window or "auto"),
+        ("profile", settings.dsh_profile),
+        ("patches", list(settings.provider_patches)),
+        ("run_timeout_sec", settings.run_timeout_sec),
+        ("ssl_keyfile", settings.ssl_keyfile or ""),
+        ("ssl_certfile", settings.ssl_certfile or ""),
+    ]
+    width = max(len(name) for name, _ in rows)
+    for name, value in rows:
+        print(f"{name:<{width}} : {value}")
+
+
+def report_dirs(settings: Settings) -> bool:
+    """打印每个启动目录的可写性；全部 ok 返回 True。"""
+    results = settings.directory_checks()
+    width = max(len(label) for label, _, _ in results)
+    for label, path, status in results:
+        mark = "ok  " if status == "ok" else "FAIL"
+        print(f"[{mark}] {label:<{width}}  {path}")
+        if status != "ok":
+            print(f"         {status}")
+    return all(status == "ok" for _, _, status in results)
+
+
+# ---- 端口占用预检 ------------------------------------------------------
+#
+# 端口被占时 uvicorn 只打一行 ``error while attempting to bind on address``，
+# Windows 上还常被写成 ``WinError 10013``（"以一种访问权限不允许的方式做了一个
+# 访问套接字的尝试"），看着像权限问题，实际是 Docker Desktop 之类的进程先占了
+# 8300。这里先探一次，直接说清楚"谁占着、换哪个端口"。
+
+
+@dataclass(frozen=True, slots=True)
+class PortProblem:
+    """端口不可用的原因（``owner`` 仅在查得出来时有值）。"""
+
+    host: str
+    port: int
+    reason: str
+    owner: str | None = None
+    occupied: bool = False
+
+
+def probe_host(host: str) -> str:
+    """把监听地址换成可连接的探测地址。
+
+    监听在 ``0.0.0.0`` / ``::`` 时没法直接 connect，分别换成回环地址。
+    """
+    stripped = (host or "").strip().strip("[]")
+    if stripped in {"", "*", "0.0.0.0"}:
+        return "127.0.0.1"
+    if stripped in {":", "::"}:
+        return "::1"
+    return stripped
+
+
+def _is_listening(connect_host: str, port: int, timeout: float = 0.3) -> bool:
+    """能否连通该端口（能连通即有人监听）。"""
+    try:
+        with socket.create_connection((connect_host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def _bind_error(host: str, port: int) -> OSError | None:
+    """真实试绑一次，返回失败原因（``None`` 表示绑得上）。
+
+    socket 选项跟 uvicorn 对齐：Windows 上用独占绑定，POSIX 上用
+    ``SO_REUSEADDR``（否则 TIME_WAIT 会误报）。只 bind 不 listen，不影响后续启动。
+    """
+    family = socket.AF_INET6 if ":" in probe_host(host) else socket.AF_INET
+    sock = socket.socket(family, socket.SOCK_STREAM)
+    try:
+        exclusive = getattr(socket, "SO_EXCLUSIVEADDRUSE", None)
+        if os.name == "nt" and exclusive is not None:
+            sock.setsockopt(socket.SOL_SOCKET, exclusive, 1)
+        else:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind((host if host else "0.0.0.0", port))
+        return None
+    except OSError as exc:
+        return exc
+    finally:
+        sock.close()
+
+
+def _describe_bind_error(exc: OSError) -> str:
+    winerror = getattr(exc, "winerror", None)
+    if exc.errno == 13 or winerror == 10013:
+        return "系统拒绝监听（端口已被独占，或落在 Windows 保留/排除的端口段）"
+    if exc.errno == 98 or winerror in {10048, 10049}:
+        return "端口已被占用"
+    return f"{type(exc).__name__}: {exc}"
+
+
+def find_port_owner(port: int) -> str | None:
+    """尽力查出占用端口的进程（仅 Windows，纯标准库，查不到返回 ``None``）。"""
+    if os.name != "nt":
+        return None
+    try:
+        listing = subprocess.run(
+            ["netstat", "-ano", "-p", "tcp"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        ).stdout
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+    pids: list[str] = []
+    for line in listing.splitlines():
+        parts = line.split()
+        if len(parts) < 4 or parts[0].upper() != "TCP":
+            continue
+        if parts[1].rsplit(":", 1)[-1] == str(port) and parts[-1].isdigit():
+            if parts[-1] not in pids:
+                pids.append(parts[-1])
+
+    names: list[str] = []
+    for pid in pids:
+        try:
+            raw = subprocess.run(
+                ["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            ).stdout
+            row = next(csv.reader(io.StringIO(raw)), [])
+            name = row[0] if row else ""
+        except (OSError, subprocess.SubprocessError, StopIteration):
+            name = ""
+        names.append(f"{name} (PID {pid})" if name else f"PID {pid}")
+    return "、".join(names) if names else None
+
+
+def check_port(host: str, port: int) -> PortProblem | None:
+    """端口可用返回 ``None``，否则返回带原因（和占用者）的 :class:`PortProblem`。"""
+    if port <= 0:
+        return None
+    if port < 1024 and os.name != "nt" and hasattr(os, "geteuid") and os.geteuid() != 0:
+        return PortProblem(host, port, "监听 <1024 的端口需要 root")
+
+    connect_host = probe_host(host)
+    if _is_listening(connect_host, port):
+        return PortProblem(host, port, "端口已被占用", find_port_owner(port), occupied=True)
+
+    exc = _bind_error(host, port)
+    if exc is not None:
+        return PortProblem(host, port, _describe_bind_error(exc))
+    return None
+
+
+def suggest_free_port(host: str, port: int, *, limit: int = 20) -> int | None:
+    """在 ``port+1`` 之后找一个能用的端口（找不到返回 ``None``）。"""
+    for candidate in range(port + 1, port + 1 + limit):
+        if check_port(host, candidate) is None:
+            return candidate
+    return None
+
+
+def port_owner_hint(port: int) -> str:
+    if os.name == "nt":
+        return f"netstat -ano | findstr :{port}"
+    return f"ss -ltnp 'sport = :{port}'"
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    settings = build_settings(args)
+
+    if args.print_config:
+        print_config(settings)
+        return 0
+    if args.check_dirs:
+        return 0 if report_dirs(settings) else 1
+
+    logging.basicConfig(
+        level=getattr(logging, settings.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    try:
+        settings.ensure_dirs()
+    except OSError as exc:
+        logger.error("无法创建目录: %s", exc)
+        logger.error("目录检查：")
+        for label, path, status in settings.directory_checks():
+            logger.error("  %-12s %s : %s", label, path, status)
+        logger.error(
+            "提示：若只有 runtime_home 失败，用 --runtime-home 指到可写目录；"
+            "也可以把 --data-dir 换到 %LOCALAPPDATA% 下（避开 Desktop/OneDrive 的访问限制）。"
+        )
+        if os.environ.get("DSH_SHELL") == "1":
+            logger.error(
+                "检测到 DSH_SHELL=1：当前终端是 DSH 的沙箱 shell，只能写会话工作区；"
+                "请换普通 PowerShell，或把 --workspace/--data-dir 指到当前工作区内（如 .local\\data）。"
+            )
+        return 1
+
+    logger.info(
+        "workspace=%s data_dir=%s runtime_home=%s provider=%s model=%s",
+        settings.workspace,
+        settings.data_dir,
+        settings.resolved_dsh_home,
+        settings.provider,
+        settings.model,
+    )
+
+    problem = check_port(settings.host, settings.port)
+    if problem is not None:
+        logger.error("无法监听 %s:%s —— %s", problem.host, problem.port, problem.reason)
+        if problem.owner:
+            logger.error("当前占用者：%s", problem.owner)
+        elif problem.occupied:
+            logger.error("占用进程不在当前用户可见范围内（常见是 Docker Desktop 的 com.docker.backend）")
+        logger.error("查看占用：%s", port_owner_hint(problem.port))
+        alternative = suggest_free_port(settings.host, settings.port)
+        if alternative is not None:
+            logger.error("换一个端口即可：%s", f"--port {alternative}")
+        return 1
+
+    # 延迟导入：避免 --help / --print-config 时也拉起 FastAPI / SDK。
+    from .server import create_app
+
+    import uvicorn
+
+    app = create_app(settings)
+    uvicorn.run(
+        app,
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level.lower(),
+        ssl_keyfile=settings.ssl_keyfile,
+        ssl_certfile=settings.ssl_certfile,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())