runwhere 0.1.0__py3-none-any.whl

runw/__init__.py

@@ -0,0 +1,3 @@
+"""RunWhere.ai CLI — GPU job management tool."""
+
+__version__ = "0.1.0"

runw/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m runw`."""
+
+from runw.cli.main import main
+
+main()

runw/cli/auth.py

@@ -0,0 +1,64 @@
+"""Auth commands: login, whoami."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from runw.client.base import BaseClient
+from runw.config.store import ConfigStore
+from runw.output import console
+
+
+@click.command()
+@click.option("--endpoint", required=True, help="API 服务地址")
+@click.pass_context
+def login(ctx: click.Context, endpoint: str) -> None:
+    """登录 RunWhere.ai"""
+    json_mode: bool = ctx.obj["json_mode"]
+
+    # 交互式：隐藏输入提示粘贴 API Token。
+    # 非交互（管道/CI，如 `echo $TOKEN | runw login`）：从 stdin 读，
+    # 避免 hide_input 走 getpass 读 TTY，在无终端时永久挂起。
+    if sys.stdin.isatty():
+        token = click.prompt("Token", hide_input=True)
+    else:
+        token = sys.stdin.read().strip()
+        if not token:
+            console.fatal(
+                "未提供 API Token（stdin 为空）",
+                suggestion="交互式直接运行 runw login，或 `echo <token> | runw login --endpoint <url>`",
+            )
+
+    store = ConfigStore()
+    store.save(endpoint=endpoint, token=token)
+
+    console.success(f"登录成功（endpoint: {endpoint}）", json_mode=json_mode)
+
+
+@click.command()
+@click.pass_context
+def whoami(ctx: click.Context) -> None:
+    """查看当前登录用户"""
+    json_mode: bool = ctx.obj["json_mode"]
+
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录", suggestion="请先执行 runw login --endpoint <URL>")
+
+    client = BaseClient(store)
+    data = client.get("/api/v1/auth/me")
+
+    # /auth/me 返回 UserInfo：username 可能为空，身份回退到 phone；
+    # org 字段实际叫 current_org_id（旧代码取 "org" 永远空）。
+    user = data.get("username") or data.get("phone") or f"user#{data.get('id', '')}"
+    # PRD §1：whoami 输出「当前用户 + workspace 地址」。workspace = 登录 endpoint。
+    console.output(
+        {
+            "user": user,
+            "org_id": data.get("current_org_id", ""),
+            "workspace": store.endpoint or "",
+        },
+        json_mode=json_mode,
+    )

runw/cli/explain.py

@@ -0,0 +1,159 @@
+"""--explain 实现：列出平台自动填充的默认值与来源（spec 027 FR-011 / SC-005）。
+
+设计：CLI 端预演平台填充规则（与 backend job_orchestrator.fill_defaults 对齐），
+给用户在提交前完整透明的可解释视图。
+
+输出条目格式：
+- name: 字段路径（如 environment.command）
+- value: 填充后的值
+- source: "user_yaml" / "platform_default" / "auto_pricing" / "computed"
+- reason: 为什么填这个值（人类可读）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class FillEntry:
+    name: str
+    value: Any
+    source: str  # user_yaml / platform_default / auto_pricing / computed
+    reason: str
+
+
+# 平台默认填充规则——与 backend manifest_builder.build_platform_env_vars 对齐
+# 当用户 YAML 未指定时填充
+DEFAULT_RULES: list[dict[str, Any]] = [
+    {
+        "name": "kind",
+        "default": "Training",
+        "reason": "未指定 kind 时默认 Training（spec PRD-runw §6）",
+    },
+    {
+        "name": "resources.gpuNum",
+        "default": 1,
+        "reason": "未指定 gpuNum 时默认 1 卡",
+    },
+    {
+        "name": "environment.command",
+        "default": "python main.py",
+        "reason": "未指定 command 时默认 `python main.py`（用户应在 YAML 显式指定）",
+    },
+]
+
+
+# 平台自动注入的 env（spec PRD-workload §6 + spec 031 Wandb）
+PLATFORM_INJECTED_ENVS: list[dict[str, str]] = [
+    {
+        "name": "RUNW_JOB_ID",
+        "reason": "由 backend 生成，注入到 Pod 用于关联日志/指标",
+    },
+    {
+        "name": "RUNW_JOB_NAME",
+        "reason": "用户 YAML 中 job.name",
+    },
+    {
+        "name": "RUNW_ORG_ID",
+        "reason": "当前 token 的 org",
+    },
+    {
+        "name": "RUNW_USER_ID",
+        "reason": "当前用户",
+    },
+    {
+        "name": "RUNW_NPROC_PER_NODE",
+        "reason": "Training 任务自动设为 gpuNum（torch.distributed 用）",
+    },
+    {
+        "name": "NCCL_TIMEOUT=1800",
+        "reason": "防止 NCCL 通信超时崩溃（30 分钟）",
+    },
+    {
+        "name": "TORCH_NCCL_ASYNC_ERROR_HANDLING=1",
+        "reason": "PyTorch NCCL 异常异步处理",
+    },
+    {
+        "name": "NCCL_DEBUG=WARN",
+        "reason": "NCCL 调试输出限制为 WARN 级别",
+    },
+    {
+        "name": "WANDB_BASE_URL / WANDB_API_KEY / WANDB_ENTITY / WANDB_PROJECT",
+        "reason": "spec 031 — Org 注册时自动建 Wandb 账号，submit 时注入；YAML 设 environment.wandb_external=true 可禁用",
+    },
+]
+
+
+def compute_fill_entries(spec_dict: dict[str, Any]) -> list[FillEntry]:
+    """对照 DEFAULT_RULES 计算用户 YAML 哪些字段是平台填充的。"""
+    entries: list[FillEntry] = []
+
+    for rule in DEFAULT_RULES:
+        name = rule["name"]
+        path = name.split(".")
+        cur: Any = spec_dict
+        present = True
+        for p in path:
+            if not isinstance(cur, dict) or p not in cur or cur[p] is None:
+                present = False
+                break
+            cur = cur[p]
+
+        if present:
+            entries.append(
+                FillEntry(
+                    name=name, value=cur, source="user_yaml",
+                    reason="用户 YAML 显式指定",
+                )
+            )
+        else:
+            entries.append(
+                FillEntry(
+                    name=name, value=rule["default"],
+                    source="platform_default", reason=rule["reason"],
+                )
+            )
+    return entries
+
+
+def render_explain(
+    spec_dict: dict[str, Any],
+    *,
+    json_mode: bool = False,
+) -> dict[str, Any] | None:
+    """渲染 --explain 输出。json_mode=True 返回 dict 供 console.output；
+    否则直接打印到 stderr 并返回 None。
+    """
+    entries = compute_fill_entries(spec_dict)
+
+    payload: dict[str, Any] = {
+        "explain": {
+            "fields": [
+                {
+                    "name": e.name,
+                    "value": e.value,
+                    "source": e.source,
+                    "reason": e.reason,
+                }
+                for e in entries
+            ],
+            "platform_envs": PLATFORM_INJECTED_ENVS,
+        }
+    }
+
+    if json_mode:
+        return payload
+
+    from runw.output import console
+
+    console.info("─── 平台默认值填充过程（--explain）───")
+    for e in entries:
+        marker = "·" if e.source == "user_yaml" else "+"
+        console.info(f"  {marker} {e.name} = {e.value}  [{e.source}] — {e.reason}")
+    console.info("─── 自动注入的环境变量 ───")
+    for env in PLATFORM_INJECTED_ENVS:
+        console.info(f"  + {env['name']}  — {env['reason']}")
+    console.info("───────────────────────────────")
+    return None

runw/cli/jobs.py

@@ -0,0 +1,279 @@
+"""作业管理命令（PRD 对齐：动词在前）。
+
+PRD §7/§8/§11 命令形：
+  runw get jobs [--kind] [--status]   列出作业
+  runw get usage [--from] [--to]      用量与费用
+  runw describe job <name>            作业详情
+  runw stop job <name>               停止作业（保留 checkpoint，释放 GPU）
+  runw delete job <name> [--force]   删除作业记录
+"""
+
+from __future__ import annotations
+
+import click
+
+from runw.client.api_client import ApiClient
+from runw.config.store import ConfigStore
+from runw.output import console
+
+
+def _format_duration(seconds: int | float) -> str:
+    if not seconds:
+        return "-"
+    s = int(seconds)
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        return f"{s // 60}m {s % 60}s"
+    h = s // 3600
+    m = (s % 3600) // 60
+    return f"{h}h {m}m"
+
+
+def _fnum(value: object, prec: int = 1) -> str:
+    """数值格式化（容错）。后端 JSON 把 Decimal 序列化成**字符串**（如 "0.0000"），
+    直接 `:.1f` 会 ValueError 崩 → `runw get jobs`/`get usage` 整条命令挂。先 float 兜底。"""
+    try:
+        return f"{float(value):,.{prec}f}"  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return str(value)
+
+
+# 配额资源类型 → 展示名（与后端 quota_service.PLAN_QUOTAS 的 key 对齐）
+_QUOTA_LABELS = {
+    "inference": "推理服务",
+    "notebook": "Notebook",
+    "training": "训练作业",
+}
+
+_CLOUD_BILL_NOTE_FALLBACK = "GPU、存储等云资源费用由您的云账户直接结算，请前往云厂商费用中心查看"
+
+
+# ══════════════════ get 组（get jobs / get usage）══════════════════
+
+
+@click.group()
+@click.pass_context
+def get(ctx: click.Context) -> None:
+    """查询资源（jobs / usage）"""
+    pass
+
+
+@get.command("jobs")
+@click.option("--status", default=None, help="按状态筛选（running/stopped/failed）")
+@click.option("--kind", default=None, help="按类型筛选（Training/Inference/Notebook）")
+@click.pass_context
+def get_jobs(ctx: click.Context, status: str | None, kind: str | None) -> None:
+    """列出所有作业"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录", suggestion="请先执行 runw login")
+        return
+
+    client = ApiClient(store)
+    data = client.get_jobs(status=status, kind=kind)
+    job_list = data.get("data", []) if isinstance(data, dict) else data
+
+    if json_mode:
+        console.output(data if isinstance(data, dict) else {"data": job_list}, json_mode=True)
+        return
+
+    if not job_list:
+        console.info("暂无作业")
+        return
+
+    # 边界（2026-07-10，PRD §8）：不展示云账单估算列——平台不替云厂商报钱
+    columns = ["名称", "类型", "状态", "GPU", "运行时长", "URL"]
+    rows = []
+    for j in job_list:
+        gpu_info = f"{j.get('gpu_count', 1)}×{j.get('gpu_type', '?')}"
+        elapsed = _format_duration(j.get("elapsed_seconds", 0))
+        rows.append([
+            j.get("name", j.get("gpuctl_job_id", "")),
+            j.get("job_type", j.get("kind", "")),
+            j.get("status", ""),
+            gpu_info,
+            elapsed,
+            j.get("url") or "-",  # 推理/Notebook 访问地址；训练无
+        ])
+    console.table(columns, rows)
+
+
+@get.command("usage")
+@click.option("--from", "from_date", default=None, help="起始日期 YYYY-MM-DD")
+@click.option("--to", "to_date", default=None, help="结束日期 YYYY-MM-DD")
+@click.pass_context
+def get_usage(ctx: click.Context, from_date: str | None, to_date: str | None) -> None:
+    """查看用量与平台账单（配额占用 + GPU 时长 + 订阅/超额）"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录", suggestion="请先执行 runw login")
+        return
+
+    client = ApiClient(store)
+    data = client.get_usage(from_date=from_date, to_date=to_date)
+
+    if json_mode:
+        console.output(data, json_mode=True)
+        return
+
+    # 边界（2026-07-10，PRD §8）：只报事实（配额/时长/平台账单），
+    # 云侧金额不估算不展示——指路云厂商费用中心。
+    period = data.get("period", {})
+    summary = data.get("summary", {})
+
+    console.success(f"{period.get('from_date', '')} ~ {period.get('to_date', '')} 用量\n")
+
+    # 配额使用（并发数量制：在用 X / 上限 Y）
+    quota = data.get("quota", [])
+    if quota:
+        plan = data.get("plan", "free")
+        console.info(f"配额使用（{plan} 套餐）")
+        for q in quota:
+            label = _QUOTA_LABELS.get(q.get("resource_type", ""), q.get("resource_type", ""))
+            current = q.get("current", 0)
+            limit = q.get("limit")
+            usage = f"{current}（不限）" if limit is None else f"{current} / {limit}"
+            console.info(f"  {label}: {usage}")
+        console.info("")
+
+    # 资源用量（分型号 GPU 时长——超额计费的事实依据）
+    total_hours = summary.get("total_gpu_hours", 0)
+    if total_hours:
+        console.info(f"资源用量：GPU·小时 {_fnum(total_hours, 1)} hr")
+        for g in data.get("gpu_usage", []):
+            console.info(f"  {g.get('gpu_type', '')}: {_fnum(g.get('gpu_hours', 0), 1)} h")
+        console.info("")
+    else:
+        console.info("本期暂无 GPU 用量\n")
+
+    # 平台账单（RunWhere 实际出账：订阅 + 超额）——本命令的核心
+    platform_bill = data.get("platform_bill", {})
+    if platform_bill:
+        console.info("平台账单（RunWhere 出账）")
+        console.info(f"  订阅已摊销:   ¥{_fnum(platform_bill.get('subscription', 0), 2)}")
+        console.info(f"  超额预估:     ¥{_fnum(platform_bill.get('overage', 0), 2)}")
+        console.info(f"  本期平台账单: ¥{_fnum(platform_bill.get('total', 0), 2)}\n")
+
+    console.info(data.get("cloud_bill_note") or _CLOUD_BILL_NOTE_FALLBACK)
+
+
+# ══════════════════ describe 组（describe job）══════════════════
+
+
+@click.group()
+@click.pass_context
+def describe(ctx: click.Context) -> None:
+    """查看资源详情（job）"""
+    pass
+
+
+@describe.command("job")
+@click.argument("job_name")
+@click.pass_context
+def describe_job(ctx: click.Context, job_name: str) -> None:
+    """查看作业详情"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录")
+        return
+
+    client = ApiClient(store)
+    data = client.describe_job(job_name)
+
+    if json_mode:
+        console.output(data, json_mode=True)
+        return
+
+    console.success(f"作业: {data.get('name', job_name)}")
+    console.info(f"  ID: {data.get('job_id', data.get('gpuctl_job_id', ''))}")
+    console.info(f"  类型: {data.get('job_type', data.get('kind', ''))}")
+    console.info(f"  状态: {data.get('status', '')}")
+    if data.get("url"):  # 推理/Notebook 访问地址
+        console.info(f"  URL: {data['url']}")
+
+    metrics = data.get("gpu_metrics")
+    if metrics:
+        console.info("\n  GPU 指标（运行期滚动统计）:")
+        console.info(
+            f"    利用率: 平均 {metrics.get('gpu_util_avg', 0):.1f}% / 峰值 "
+            f"{metrics.get('gpu_util_max', 0):.1f}%"
+        )
+        console.info(
+            f"    显存峰值: {metrics.get('gpu_mem_used_max_gb', 0):.1f} GB"
+        )
+        console.info(f"    温度峰值: {metrics.get('gpu_temp_max', 0):.0f} °C")
+        console.info(f"    采样数: {metrics.get('samples_count', 0)}")
+
+    if data.get("platform_defaults"):
+        console.info("\n  平台自动行为:")
+        for key, val in data["platform_defaults"].items():
+            if isinstance(val, dict):
+                console.info(f"    {key}: {val.get('value', '')}（{val.get('reason', '')}）")
+            else:
+                console.info(f"    {key}: {val}")
+
+
+# ══════════════════ stop 组（stop job）══════════════════
+
+
+@click.group()
+@click.pass_context
+def stop(ctx: click.Context) -> None:
+    """停止资源（job）"""
+    pass
+
+
+@stop.command("job")
+@click.argument("job_name")
+@click.pass_context
+def stop_job(ctx: click.Context, job_name: str) -> None:
+    """停止运行中的作业（保留 checkpoint，释放 GPU）"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录")
+        return
+
+    client = ApiClient(store)
+    data = client.stop_job(job_name)
+
+    if json_mode:
+        console.output(data, json_mode=True)
+    else:
+        # 边界（2026-07-10，PRD §8）：不展示云侧金额（final_cost 是内部审计口径）
+        console.success(f"作业 {job_name} 已停止，GPU 已释放，计费停止")
+
+
+# ══════════════════ delete 组（delete job）══════════════════
+
+
+@click.group()
+@click.pass_context
+def delete(ctx: click.Context) -> None:
+    """删除资源（job）"""
+    pass
+
+
+@delete.command("job")
+@click.argument("job_name")
+@click.option("--force", is_flag=True, help="强制删除运行中的作业")
+@click.pass_context
+def delete_job(ctx: click.Context, job_name: str, force: bool) -> None:
+    """删除作业记录（不删 checkpoint / workspace 数据）"""
+    json_mode: bool = ctx.obj["json_mode"]
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录")
+        return
+
+    client = ApiClient(store)
+    data = client.delete_job(job_name, force=force)
+
+    if json_mode:
+        console.output(data, json_mode=True)
+    else:
+        console.success(f"作业 {job_name} 已删除")

runw/cli/logs.py

@@ -0,0 +1,103 @@
+"""Logs command — view job logs (historical or real-time via WebSocket)."""
+
+from __future__ import annotations
+
+import asyncio
+
+import click
+
+from runw.client.api_client import ApiClient
+from runw.client.ws_client import WSClient
+from runw.config.store import ConfigStore
+from runw.output import console
+
+
+@click.command()
+@click.argument("job_name")
+@click.option("-f", "--follow", is_flag=True, help="实时跟踪日志")
+@click.option("-n", "--tail", default=200, show_default=True, help="取尾部 N 行")
+@click.pass_context
+def logs(ctx: click.Context, job_name: str, follow: bool, tail: int) -> None:
+    """查看任务日志"""
+    json_mode: bool = ctx.obj["json_mode"]
+
+    store = ConfigStore()
+    if not store.token:
+        console.fatal_server("未登录", suggestion="请先执行 runw login --endpoint <URL>")
+        return
+
+    if follow:
+        _follow_logs(store, job_name, json_mode)
+    else:
+        _get_historical_logs(store, job_name, json_mode, tail)
+
+
+def _follow_logs(store: ConfigStore, job_name: str, json_mode: bool) -> None:
+    """Connect to WebSocket and stream logs in real-time."""
+    endpoint = store.endpoint
+    token = store.token
+    if not endpoint or not token:
+        console.fatal_user_input("未配置 endpoint")
+        return
+
+    ws = WSClient(endpoint, job_name, token)
+    console.info(f"[runw] 连接实时日志流: {job_name}")
+
+    try:
+        asyncio.run(_ws_log_loop(ws, json_mode))
+    except KeyboardInterrupt:
+        console.info("[runw] 已断开")
+
+
+async def _ws_log_loop(ws: WSClient, json_mode: bool) -> None:
+    async for event in ws.listen():
+        event_type = event.get("type", "")
+        payload = event.get("payload", {})
+
+        if event_type == "log":
+            line = payload.get("line", "")
+            if json_mode:
+                console.output(payload, json_mode=True)
+            else:
+                click.echo(line)
+        elif event_type == "status_changed":
+            msg = payload.get("message", payload.get("status", ""))
+            if not json_mode:
+                console.info(f"[runw] {msg}")
+        elif event_type == "url_ready":
+            # 推理/Notebook 就绪 → 显示访问地址（手册 §9.6：notebook URL 从 runw logs 看）
+            if json_mode:
+                console.output(payload, json_mode=True)
+            else:
+                console.success(f"[runw] 服务地址 → {payload.get('url', '')}")
+        elif event_type in ("completed", "failed"):
+            if not json_mode:
+                if event_type == "completed":
+                    console.success("[runw] 任务完成")
+                else:
+                    console.error(f"[runw] 任务失败: {payload.get('error', '')}")
+            return
+        elif event_type == "_reconnecting":
+            if not json_mode:
+                console.warn("[runw] 连接断开，正在重连...")
+
+
+def _get_historical_logs(
+    store: ConfigStore, job_name: str, json_mode: bool, tail: int
+) -> None:
+    """Get historical logs from API (P1-4: 返回日志行，不再只给 URL)。"""
+    client = ApiClient(store)
+    try:
+        data = client.get_logs(job_name, tail=tail)
+    except SystemExit:
+        return  # API error already displayed by BaseClient
+
+    lines = data.get("lines", [])
+    if json_mode:
+        console.output(data, json_mode=True)
+        return
+    if lines:
+        for line in lines:
+            click.echo(line)
+    else:
+        console.info("暂无日志（任务尚未产生输出，或日志已过期）")

runw/cli/main.py

@@ -0,0 +1,45 @@
+"""Root CLI group with global options."""
+
+from __future__ import annotations
+
+import click
+
+from runw import __version__
+
+
+@click.group()
+@click.option("--json", "json_mode", is_flag=True, envvar="RUNW_JSON", help="输出结构化 JSON")
+@click.option("--explain", is_flag=True, help="显示平台默认值填充过程")
+@click.version_option(version=__version__, prog_name="runw")
+@click.pass_context
+def main(ctx: click.Context, json_mode: bool, explain: bool) -> None:
+    """RunWhere.ai CLI — GPU 任务管理工具"""
+    ctx.ensure_object(dict)
+    ctx.obj["json_mode"] = json_mode
+    ctx.obj["explain"] = explain
+
+
+# Register sub-commands
+# PRD 对齐（手册）：统一模型——submit 创建（按 kind 分发训练/推理/notebook），
+# get/describe/logs/stop job/resume/delete job 管理（按 name 寻址、行为按 kind）。
+# 已删 deploy/notebook 命令组（创建收口到 submit；推理/notebook 的 stop/resume/list
+# 走通用 job 命令，resume 按 kind 兼管训练 checkpoint 与 notebook 挂起恢复）。
+from runw.cli.auth import login, whoami  # noqa: E402
+from runw.cli.sync import sync  # noqa: E402
+from runw.cli.submit import submit  # noqa: E402
+from runw.cli.logs import logs  # noqa: E402
+from runw.cli.price import price  # noqa: E402
+from runw.cli.jobs import delete, describe, get, stop  # noqa: E402
+from runw.cli.resume import resume  # noqa: E402
+
+main.add_command(login)
+main.add_command(whoami)
+main.add_command(sync)
+main.add_command(submit)
+main.add_command(logs)
+main.add_command(price)
+main.add_command(get)       # runw get jobs / runw get usage
+main.add_command(describe)  # runw describe job <name>
+main.add_command(stop)      # runw stop job <name>（notebook=挂起）
+main.add_command(delete)    # runw delete job <name>
+main.add_command(resume)    # runw resume <name>（训练 checkpoint / notebook 挂起恢复）