starforge-cli 0.1.6__py3-none-any.whl

starforge_cli/commands/plugin.py

@@ -0,0 +1,243 @@
+"""插件命令：ls / info / publish / install / remove。
+
+插件是平台托管、digest 锁定的扩展包（algorithm 算法补丁 / data-prep 数据脚本）。
+代码只在用户自己的作业容器（或本机）执行，控制平面只存储与分发。
+
+    sf plugin publish ./my-plugin          # 发布（名字版本以 plugin.yaml 为准）
+    sf plugin install alice/myalgo --exp x # 下载到本地 + 写实验锁文件
+    sf submit x ...                        # 锁文件里的引用随 JobSpec 提交
+"""
+from __future__ import annotations
+
+import io
+import json
+import shutil
+import tarfile
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from starforge_cli import api_client, cli_ui
+from starforge_cli.auth import gate
+from starforge_cli.commands import common
+
+plugin_app = typer.Typer(
+    no_args_is_help=True,
+    help="插件中心：发布 / 安装 / 管理平台托管的扩展包（算法补丁、数据脚本）",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+#: 本地安装目录（仓库根下）。data-prep 插件的 prepare_*.py 从这里被发现。
+LOCAL_PLUGINS_DIR = "forge_plugins"
+
+
+def _split_ref(ref: str) -> tuple[str, str, str]:
+    """解析 <owner>/<name>[@version] → (owner, name, version)。"""
+    base, _, version = ref.strip().partition("@")
+    owner, _, name = base.partition("/")
+    if not owner or not name or "/" in name:
+        cli_ui.fail(
+            f"插件 ID 必须是 <owner>/<name>[@version]，收到 {ref!r}",
+            hint="用 `sf plugin ls` 查看完整 ID",
+        )
+    return owner, name, version
+
+
+@plugin_app.command("ls", help="列出平台上的插件")
+def plugin_ls() -> None:
+    gate()
+    rows = api_client.api_get("/api/plugins")["plugins"]
+    if not rows:
+        typer.echo("（还没有插件；`sf plugin publish <目录>` 发布一个）")
+        return
+    for p in rows:
+        state = "" if p["enabled"] else "  [已禁用]"
+        typer.echo(
+            f"{p['id']:32s} {p['kind']:10s} @{p['latest_version']:<10s}{state} {p['summary']}"
+        )
+
+
+@plugin_app.command("info", help="查看插件详情（manifest、版本历史、digest）")
+def plugin_info(
+    ref: str = typer.Argument(..., help="插件 ID：<owner>/<name>[@version]"),
+) -> None:
+    gate()
+    owner, name, version = _split_ref(ref)
+    q = f"?version={version}" if version else ""
+    p = api_client.api_get(f"/api/plugins/{owner}/{name}{q}")
+    typer.echo(f"{p['id']}@{p['version']}  [{p['kind']}]  {'可用' if p['enabled'] else '已禁用'}")
+    if p.get("summary"):
+        typer.echo(f"  {p['summary']}")
+    typer.echo(f"  digest : {p['digest']}")
+    typer.echo(f"  发布者 : {p['created_by']}  {p['created_at']}")
+    manifest = p.get("manifest") or {}
+    if manifest.get("entrypoint"):
+        typer.echo(f"  入口   : {manifest['entrypoint']}  ({manifest.get('load') or 'eager'})")
+    if (manifest.get("requires") or {}).get("core"):
+        typer.echo(f"  要求   : core {manifest['requires']['core']}")
+    typer.echo("  版本   :")
+    for v in p.get("versions") or []:
+        state = "" if v["enabled"] else "  [已禁用]"
+        typer.echo(f"    {v['version']:12s} {v['digest'][:19]}…  {v['created_at']}{state}")
+
+
+@plugin_app.command("publish", help="发布一个插件版本（目录内须有 plugin.yaml；版本不可变）")
+def plugin_publish(
+    path: str = typer.Argument(..., help="插件目录"),
+    owner: Optional[str] = typer.Option(
+        None, "--owner", help="目标命名空间（仅 admin 可跨；默认自己）"
+    ),
+) -> None:
+    gate()
+    from starforge_core.plugins import (
+        PluginError,
+        digest_files,
+        directory_digest,
+        load_manifest,
+        validate_package_layout,
+    )
+
+    src = Path(path)
+    if not src.is_dir():
+        cli_ui.fail(f"不是目录: {path}")
+    try:
+        manifest = load_manifest(src)
+        # 与服务端同一份结构校验：拼错的 entrypoint / 遮蔽保留模块名的顶层文件
+        # 在上传前就报出来，不必等服务端往返。
+        validate_package_layout(src, manifest)
+    except PluginError as e:
+        cli_ui.fail(f"插件包非法：{e}", hint="检查 plugin.yaml（schema: lab-plugin/v1）")
+    digest = directory_digest(src)
+
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        for f in digest_files(src):
+            tar.add(f, arcname=f.relative_to(src).as_posix())
+    blob = buf.getvalue()
+
+    q = f"?owner={owner}" if owner else ""
+    row = api_client.api_post_bytes(f"/api/plugins/publish{q}", blob)
+    if row["digest"] != digest:
+        # 理论上不可能：两侧跑的是 SDK 同一份 directory_digest。真出现说明打包/解包链路有毛病。
+        cli_ui.fail(
+            f"服务端摘要 {row['digest']} 与本地 {digest} 不一致，发布结果不可信",
+            hint="检查 CLI 与服务端 SDK 版本是否一致",
+        )
+    typer.secho(
+        f"✓ 已发布 {row['id']}@{row['version']}  [{row['kind']}]  "
+        f"{cli_ui.human_bytes(row['size_bytes'])}",
+        fg=typer.colors.GREEN,
+    )
+    typer.echo(f"  digest: {row['digest']}")
+    typer.echo(f"  实验里使用：sf plugin install {row['id']}@{row['version']} --exp <实验>")
+
+
+@plugin_app.command(
+    "install",
+    help="安装插件：下载到本地 forge_plugins/，并（可选）锁定到实验的 plugins.lock.json",
+)
+def plugin_install(
+    ref: str = typer.Argument(..., help="插件 ID：<owner>/<name>[@version]，缺省最新版"),
+    exp: Optional[str] = typer.Option(
+        None, "--exp", "-e", autocompletion=common.complete_exp,
+        help="锁定到该实验：提交时随 JobSpec 引用，由平台注入作业包",
+    ),
+) -> None:
+    gate()
+    from starforge_core.plugins import directory_digest
+
+    owner, name, version = _split_ref(ref)
+    q = f"?version={version}" if version else ""
+    meta = api_client.api_get(f"/api/plugins/{owner}/{name}{q}")
+    if not meta["enabled"]:
+        cli_ui.fail(f"插件 {meta['id']}@{meta['version']} 已被管理员禁用")
+    blob, _headers = api_client.api_get_bytes(f"/api/plugins/{owner}/{name}/package{q}")
+
+    dest = common.ROOT / LOCAL_PLUGINS_DIR / name
+    if dest.exists():
+        shutil.rmtree(dest)
+    dest.mkdir(parents=True)
+    with tarfile.open(fileobj=io.BytesIO(blob), mode="r:gz") as tar:
+        dest_root = dest.resolve()
+        for m in tar.getmembers():
+            target = (dest / m.name).resolve()
+            # is_relative_to 而非字符串前缀：startswith 有 /a/b 匹配 /a/bc 的绕过。
+            if not target.is_relative_to(dest_root):
+                cli_ui.fail(f"插件包含非法归档成员路径: {m.name}")
+        tar.extractall(dest, filter="data")
+    local_digest = directory_digest(dest)
+    if local_digest != meta["digest"]:
+        shutil.rmtree(dest, ignore_errors=True)
+        cli_ui.fail(
+            f"下载内容摘要 {local_digest} 与平台记录 {meta['digest']} 不一致，已删除",
+            hint="重试；若持续失败请联系管理员",
+        )
+    typer.secho(
+        f"✓ 已安装 {meta['id']}@{meta['version']} → {LOCAL_PLUGINS_DIR}/{name}/",
+        fg=typer.colors.GREEN,
+    )
+
+    if meta["kind"] == "data-prep":
+        typer.echo("  数据脚本已可用：sf dataset prepare 会自动发现其中的 prepare_*.py")
+    if not exp:
+        if meta["kind"] == "algorithm":
+            typer.echo(f"  提交训练时使用：sf plugin install {meta['id']}@{meta['version']} --exp <实验>")
+        return
+
+    from starforge_cli.plugins_lock import LOCK_FILE, upsert_plugin_lock
+
+    exp_path = common.resolve_exp(exp)
+    try:
+        plugins = upsert_plugin_lock(
+            common.ROOT / exp_path,
+            {"id": meta["id"], "version": meta["version"], "digest": meta["digest"]},
+        )
+    except ValueError as e:
+        cli_ui.fail(str(e))
+    typer.echo(f"  已锁定到 {exp_path}/{LOCK_FILE}（{len(plugins)} 个插件），提交时自动生效")
+
+
+@plugin_app.command("remove", help="从实验的 plugins.lock.json 移除一个插件引用")
+def plugin_remove(
+    ref: str = typer.Argument(..., help="插件 ID：<owner>/<name>"),
+    exp: str = typer.Option(
+        ..., "--exp", "-e", autocompletion=common.complete_exp, help="实验名或路径"
+    ),
+) -> None:
+    from starforge_cli.plugins_lock import remove_plugin_lock
+
+    owner, name, _ = _split_ref(ref)
+    exp_path = common.resolve_exp(exp)
+    try:
+        removed = remove_plugin_lock(common.ROOT / exp_path, f"{owner}/{name}")
+    except ValueError as e:
+        cli_ui.fail(str(e))
+    if not removed:
+        cli_ui.fail(f"实验 {exp_path} 未引用插件 {owner}/{name}")
+    typer.secho(f"✓ 已从 {exp_path} 移除 {owner}/{name}", fg=typer.colors.GREEN)
+
+
+@plugin_app.command("enable", help="启用插件（admin）")
+def plugin_enable(
+    ref: str = typer.Argument(..., help="插件 ID：<owner>/<name>[@version]"),
+) -> None:
+    _set_enabled(ref, True)
+
+
+@plugin_app.command("disable", help="禁用插件：新作业不可再引用，历史记录保留（admin）")
+def plugin_disable(
+    ref: str = typer.Argument(..., help="插件 ID：<owner>/<name>[@version]"),
+) -> None:
+    _set_enabled(ref, False)
+
+
+def _set_enabled(ref: str, enabled: bool) -> None:
+    gate()
+    owner, name, version = _split_ref(ref)
+    body: dict = {"enabled": enabled}
+    if version:
+        body["version"] = version
+    r = api_client.api_patch(f"/api/plugins/{owner}/{name}", body)
+    verb = "启用" if enabled else "禁用"
+    typer.secho(f"✓ 已{verb} {r['id']}（{r['versions_affected']} 个版本）", fg=typer.colors.GREEN)

starforge_cli/commands/recipe.py

@@ -0,0 +1,163 @@
+"""recipe 锁状态与显式升级。"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from starforge_cli import cli_ui
+from starforge_cli.commands import common
+from starforge_cli.recipe_lock import (
+    LOCK_FILE,
+    LockInspection,
+    RecipeLockBatchError,
+    RecipeLockError,
+    RecipeLockManager,
+    iter_lock_dirs,
+)
+
+recipe_app = typer.Typer(
+    no_args_is_help=True,
+    help="recipe 锁管理",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _rel(path: Path) -> str:
+    try:
+        return str(path.parent.relative_to(common.ROOT))
+    except ValueError:
+        return str(path.parent)
+
+
+def _print_inspection(item: LockInspection) -> None:
+    typer.echo(f"{_rel(item.path)}")
+    typer.echo(f"  state: {item.state.value}")
+    if item.recipe_name:
+        fw = f"  framework: {item.framework_version}" if item.framework_version else ""
+        typer.echo(f"  recipe: {item.recipe_name}{fw}")
+    for diff in item.diffs:
+        typer.echo(f"  - {diff.field}: {diff.locked or '∅'} → {diff.current or '∅'}")
+    if not item.is_current:
+        typer.echo(f"  hint: sf recipe upgrade {_rel(item.path)}")
+
+
+def _config_errors(exp_dir: Path, recipe) -> list[str]:
+    from starforge_cli.commands.exp import validate_exp_config
+
+    return validate_exp_config(exp_dir, recipe, repo_root=common.ROOT)
+
+
+@recipe_app.command("status", help="查看实验 recipe 锁与当前 catalog 的差异")
+def recipe_status(
+    exp: Optional[str] = typer.Argument(
+        None, autocompletion=common.complete_exp, help="实验名或路径；省略则需 --all"
+    ),
+    all_exps: bool = typer.Option(False, "--all", help="扫描 experiments/projects/smoke"),
+    server: bool = typer.Option(False, "--server", help="再与 Console catalog 握手对照"),
+) -> None:
+    manager = RecipeLockManager()
+    if all_exps:
+        items = [manager.inspect(path) for path in iter_lock_dirs(common.ROOT)]
+    elif exp:
+        items = [manager.inspect(common.ROOT / common.resolve_exp(exp))]
+    else:
+        cli_ui.fail("指定实验名，或加 --all")
+
+    stale = 0
+    for item in items:
+        _print_inspection(item)
+        if not item.is_current:
+            stale += 1
+        if server and item.expected is not None:
+            _echo_server_drift(item)
+    if stale:
+        raise typer.Exit(1)
+
+
+def _echo_server_drift(item: LockInspection) -> None:
+    from starforge_cli import api_client
+
+    if item.expected is None:
+        return
+    try:
+        payload = api_client.api_get("/api/recipes")
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(f"  server: {exc}")
+        return
+    selected = next(
+        (
+            recipe
+            for recipe in (payload.get("recipes") or [])
+            if recipe.get("name") == item.recipe_name
+        ),
+        None,
+    )
+    if selected is None:
+        typer.echo(f"  server: Console 未启用 {item.recipe_name}")
+        return
+    wanted = item.expected["recipe"]
+    drift = [
+        f"{field} server={selected.get(field)!r} local={wanted.get(field)!r}"
+        for field in ("version", "digest")
+        if selected.get(field) != wanted.get(field)
+    ]
+    if drift:
+        typer.echo("  server: " + "; ".join(drift))
+        return
+    typer.echo("  server: current")
+
+
+@recipe_app.command("upgrade", help="把实验锁升级到当前 catalog（默认不改 framework version）")
+def recipe_upgrade(
+    exp: Optional[str] = typer.Argument(
+        None, autocompletion=common.complete_exp, help="实验名或路径；与 --all 互斥"
+    ),
+    all_exps: bool = typer.Option(False, "--all", help="先全量校验，再统一写入"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="只显示 diff，不写文件"),
+    framework_version: Optional[str] = typer.Option(
+        None, "--framework-version", help="升级时改到指定精确框架版本"
+    ),
+    accept_runtime_change: bool = typer.Option(
+        False,
+        "--accept-runtime-change",
+        help="锁定的框架版本已从 catalog 移除时，改用当前默认版本",
+    ),
+) -> None:
+    manager = RecipeLockManager()
+    selected = (framework_version or "").strip()
+    try:
+        if all_exps:
+            items = manager.upgrade_all(
+                common.ROOT,
+                framework_version=selected,
+                accept_runtime_change=accept_runtime_change,
+                dry_run=dry_run,
+                validate_config=_config_errors,
+            )
+        elif exp:
+            items = [
+                manager.upgrade(
+                    common.ROOT / common.resolve_exp(exp),
+                    framework_version=selected,
+                    accept_runtime_change=accept_runtime_change,
+                    dry_run=dry_run,
+                    validate_config=_config_errors,
+                )
+            ]
+        else:
+            cli_ui.fail("指定实验名，或加 --all")
+    except RecipeLockBatchError as exc:
+        cli_ui.emit_error(str(exc), items=[item.message for item in exc.failures])
+        raise typer.Exit(1) from exc
+    except RecipeLockError as exc:
+        cli_ui.emit_error(exc.inspection.message)
+        raise typer.Exit(1) from exc
+
+    for item in items:
+        _print_inspection(item)
+    typer.secho(
+        f"{'将' if dry_run else '已'}处理 {len(items)} 个 {LOCK_FILE}",
+        fg=typer.colors.GREEN,
+    )

starforge_cli/commands/serve.py

@@ -0,0 +1,79 @@
+"""Playground 推理服务：训练产物一键起 vLLM 服务并试用。
+
+服务生命周期完全由 console 管理（GPU 台账 + 闲置 TTL 自动回收）；
+CLI 只是端点的瘦封装。对话试用建议用 web「Playground」页（流式 UI）。
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+from typing import Optional
+
+import typer
+
+from starforge_cli import api_client, cli_ui
+from starforge_cli.auth import gate
+
+serve_app = typer.Typer(no_args_is_help=True, help="推理服务（Playground）")
+
+
+def _call(method: str, path: str, body: dict | None = None) -> dict:
+    srv = api_client.current_server(None)
+    data = json.dumps(body).encode() if body is not None else None
+    headers = {"Content-Type": "application/json"} if data is not None else None
+    try:
+        with api_client._bearer_request(srv, method, path, data=data, headers=headers) as r:
+            return json.loads(r.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        cli_ui.fail_http(e, fallback="Playground 操作失败")
+
+
+@serve_app.command("start", help="启动推理服务（模型：HF id / 绝对路径 / run:<run_id>）")
+def serve_start(
+    model: str = typer.Argument(..., help="HF id / 共享盘绝对路径 / run:<run_id>"),
+    gpus: int = typer.Option(1, "--gpus", "-g", help="张数（张量并行度）"),
+    ttl_hours: Optional[float] = typer.Option(None, "--ttl-hours", help="闲置 TTL（小时），默认服务端配置"),
+) -> None:
+    gate()
+    body: dict = {"model": model, "gpus": gpus}
+    if ttl_hours:
+        body["ttl_s"] = ttl_hours * 3600
+    res = _call("POST", "/api/playground/start", body)
+    typer.secho(f"✓ 推理服务已启动  {res.get('lab_run_id')}", fg=typer.colors.GREEN, bold=True)
+    typer.echo(f"  模型: {res.get('model')}  端口: {res.get('port')}  到期: {res.get('expires_at')}")
+    typer.echo("  对话试用：web「Playground」页；一键停止：sf serve stop <run_id>")
+
+
+@serve_app.command("ls", help="列出我的推理服务")
+def serve_ls() -> None:
+    gate()
+    res = _call("GET", "/api/playground")
+    rows = res.get("servings") or []
+    if not rows:
+        typer.echo("没有推理服务。启动：sf serve start <模型>")
+        return
+    for r in rows:
+        flag = "●" if r.get("active") else "○"
+        typer.echo(
+            f"{flag} {r.get('lab_run_id')}  {r.get('status'):<9} "
+            f"{r.get('model') or '-'}  {r.get('gpus')}GPU  到期 {r.get('expires_at') or '-'}"
+        )
+
+
+@serve_app.command("stop", help="停止推理服务")
+def serve_stop(run_id: str = typer.Argument(...)) -> None:
+    gate()
+    _call("POST", f"/api/playground/{urllib.parse.quote(run_id, safe='')}/stop")
+    typer.secho("✓ 已停止", fg=typer.colors.GREEN)
+
+
+@serve_app.command("extend", help="续期推理服务 TTL")
+def serve_extend(
+    run_id: str = typer.Argument(...),
+    hours: float = typer.Option(1.0, "--hours", help="续期时长（小时）"),
+) -> None:
+    gate()
+    res = _call("POST", f"/api/playground/{urllib.parse.quote(run_id, safe='')}/extend",
+                {"extra_s": hours * 3600})
+    typer.secho(f"✓ 已续期，到期 {res.get('expires_at')}", fg=typer.colors.GREEN)