starforge-cli 0.1.6__py3-none-any.whl

starforge_cli/commands/exp.py

@@ -0,0 +1,213 @@
+"""实验资产命令：ls / new / validate / methods（纯本地 + SDK catalog，不联网）。"""
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from starforge_cli import cli_ui
+from starforge_cli.commands import common
+from starforge_cli.new_experiment import NewExperimentError, create_experiment
+
+
+def ls() -> None:
+    """列出实验 / 项目。"""
+    for kind in ("experiments", "projects"):
+        base = common.ROOT / kind
+        if not base.is_dir():
+            continue
+        exps = sorted(p.name for p in base.iterdir() if p.is_dir())
+        typer.echo(f"\n[{kind}] ({len(exps)})")
+        for e in exps:
+            typer.echo(f"  - {e}")
+
+
+def new(
+    name: str = typer.Argument(..., help="实验名"),
+    from_exp: Optional[str] = typer.Option(
+        None, "--from", autocompletion=common.complete_exp,
+        help="从已有实验 fork",
+    ),
+    method: str = typer.Option(
+        "nemo-rl/grpo", "--method", "-m", autocompletion=common.complete_method,
+        help="方法标识 <framework>/<method>；默认 nemo-rl/grpo，`sf methods` 查看全部",
+    ),
+    framework_version: Optional[str] = typer.Option(
+        None,
+        "--framework-version",
+        help="精确框架版本；必须是 recipe catalog 已发布版本",
+    ),
+    kind: common.Kind = typer.Option(
+        common.Kind.experiments, "--kind", help="experiments 或 projects"
+    ),
+) -> None:
+    """新建实验（--from fork 现成实验；--method 来自 SDK recipe catalog）。"""
+    if from_exp and method != "nemo-rl/grpo":
+        typer.secho("fork 会继承来源实验配置，--method 已忽略。", fg=typer.colors.YELLOW)
+    src = ""
+    if from_exp:
+        from pathlib import Path
+
+        src = Path(common.resolve_exp(from_exp)).name
+    try:
+        create_experiment(
+            common.ROOT,
+            kind.value,
+            name,
+            src=src,
+            method=method,
+            framework_version=framework_version or "",
+        )
+    except NewExperimentError as e:
+        cli_ui.fail(str(e))
+
+
+def validate_exp_config(exp_dir, recipe, *, repo_root=None) -> list[str]:
+    """只校验实验内容与当前 recipe，不要求锁已经是最新。"""
+    errors, _ = _validate_exp_contents(exp_dir, recipe, repo_root=repo_root)
+    return errors
+
+
+def _validate_exp_contents(exp_dir, recipe, *, repo_root=None) -> tuple[list[str], list[str]]:
+    import yaml
+
+    from starforge_cli.config_resolve import resolve, validate_framework_config
+
+    root = repo_root or common.ROOT
+    if recipe.entrypoint.kind == "experiment":
+        entry = (exp_dir / recipe.entrypoint.value).resolve()
+        if not entry.is_relative_to(exp_dir.resolve()) or not entry.is_file():
+            return [f"{recipe.framework} 实验缺少入口: {recipe.entrypoint.value}"], []
+    if recipe.framework == "custom":
+        return [], []
+
+    entry_warns: list[str] = []
+    if recipe.entrypoint.kind != "experiment" and not recipe.entrypoint.experiment_override:
+        for candidate in ("run.py", "main.py"):
+            if (exp_dir / candidate).is_file():
+                entry_warns.append(
+                    f"实验目录有 {candidate}，但 recipe {recipe.id} 未声明 entrypoint.experiment_override，"
+                    f"提交后将执行默认入口 {recipe.entrypoint.value}，{candidate} 不会被执行。"
+                )
+
+    cfg_file = exp_dir / "config.yaml"
+    if not cfg_file.is_file():
+        return [f"{recipe.framework} 实验缺少 config.yaml: {exp_dir.name}"], []
+    try:
+        if recipe.framework == "nemo-rl":
+            cfg = resolve(cfg_file)
+        else:
+            cfg = yaml.safe_load(cfg_file.read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        return [f"解析 {recipe.framework} config 失败: {exc}"], []
+    if not isinstance(cfg, dict):
+        return [f"{recipe.framework} config 根节点必须是对象"], []
+
+    try:
+        issues = validate_framework_config(
+            recipe.framework, cfg, repo_root=root, recipe=recipe
+        )
+    except ValueError as exc:
+        return [str(exc)], entry_warns
+    return (
+        [message for level, message in issues if level == "error"],
+        entry_warns + [message for level, message in issues if level == "warn"],
+    )
+
+
+def _validate_exp(exp_path: str, recipe_override: str = "") -> tuple[list[str], list[str]]:
+    """锁必须是当前 bundle，再跑 recipe 所属框架的 validator。"""
+    from starforge_core.contract import SpecError
+    from starforge_core.recipes import get_recipe
+
+    from starforge_cli.recipe_lock import validate_recipe_lock
+    from starforge_cli.spec_builder import infer_recipe
+
+    exp_dir = common.ROOT / exp_path
+    recipe_name = recipe_override.strip() or infer_recipe(exp_dir)
+    if not recipe_name:
+        return [f"实验缺少 recipe 声明（recipe.lock.json）: {exp_path}"], []
+    try:
+        recipe = get_recipe(recipe_name)
+        validate_recipe_lock(exp_dir, recipe_name)
+    except (SpecError, ValueError) as exc:
+        return [str(exc)], []
+    return _validate_exp_contents(exp_dir, recipe)
+
+
+def validate(
+    exp: str = typer.Argument(..., autocompletion=common.complete_exp, help="实验名或路径"),
+) -> None:
+    """校验实验 config（提交前本地检查）。"""
+    exp_path = common.resolve_exp(exp)
+    errors, warns = _validate_exp(exp_path)
+    if errors:
+        cli_ui.emit_error(
+            f"{exp_path}：{len(errors)} 处错误" + (f"，{len(warns)} 处告警" if warns else ""),
+            items=errors,
+        )
+        raise typer.Exit(1)
+    if warns:
+        cli_ui.emit_warning(f"{exp_path}：{len(warns)} 处告警", body="\n".join(f"• {w}" for w in warns))
+    suffix = f"（{len(warns)} 个告警）" if warns else ""
+    typer.secho(f"✓ {exp_path}：通过{suffix}", fg=typer.colors.GREEN)
+
+
+def methods(
+    name: Optional[str] = typer.Argument(None, help="方法名；不传则列出全部"),
+) -> None:
+    """列出可用的后训练方法与它们的超参。
+
+    方法目录来自 starforge-core，与服务端是同一份 —— 这里看到的就是提交时会被校验的。
+    """
+    from starforge_core.contract import SpecError
+    from starforge_core.recipes import get_recipe, recipe_names
+
+    if not name:
+        for n in recipe_names():
+            r = get_recipe(n)
+            typer.echo(f"{n:22s} {r.title}")
+            typer.echo(
+                f"{'':22s} 默认 {r.framework}@{r.runtime.default_version}"
+                f" · 支持 {', '.join(r.runtime.supported_versions)}"
+            )
+            typer.echo(f"{'':22s} {r.summary.strip()}")
+        typer.echo("\n用 `sf methods <方法名>` 看它的可调超参。")
+        return
+
+    try:
+        r = get_recipe(name)
+    except SpecError as e:
+        cli_ui.emit_error(str(e))
+        raise typer.Exit(1) from e
+
+    typer.echo(f"{r.id} v{r.version} —— {r.title}")
+    typer.echo(f"  {r.summary.strip()}\n")
+    typer.echo(f"  框架      : {r.framework}@{r.runtime.default_version}（默认）")
+    typer.echo(f"  支持版本  : {', '.join(r.runtime.supported_versions)}")
+    typer.echo(f"  角色      : {', '.join(r.roles)}")
+    typer.echo(f"  训练后动作: {', '.join(r.lifecycle) or '（无）'}")
+    if r.plugins:
+        typer.echo(f"  算法插件  : {', '.join(r.plugins)}")
+    if r.runtime.requires:
+        typer.echo(f"  默认依赖  : {', '.join(r.runtime.requires)}")
+    typer.echo(f"  核心指标  : {', '.join(r.primary_metrics)}\n")
+    typer.echo("  可调超参（--set KEY=VALUE）:")
+    current_group = None
+    for p in r.params.values():
+        group = p.group or "其他"
+        if group != current_group:
+            typer.secho(f"    ── {group} ──", fg=typer.colors.CYAN)
+            current_group = group
+        rng = []
+        if p.minimum is not None:
+            rng.append(f"≥{p.minimum}" if not p.exclusive_minimum else f">{p.minimum}")
+        if p.maximum is not None:
+            rng.append(f"≤{p.maximum}")
+        if p.choices:
+            rng.append("|".join(str(c) for c in p.choices))
+        meta = f"{p.type}{' ' + ','.join(rng) if rng else ''}"
+        default = f" (默认 {p.default})" if p.default is not None else ""
+        typer.echo(f"    {p.name:32s} {meta}{default}")
+        if p.doc:
+            typer.echo(f"    {'':32s} {p.doc.strip()}")

starforge_cli/commands/init.py

@@ -0,0 +1,52 @@
+"""`sf init`：交互式创建 StarForge 微调项目。"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from starforge_cli import cli_ui
+from starforge_cli.project import InitError, init_project
+
+
+def init(
+    directory: Optional[str] = typer.Argument(
+        None, help="项目目录（省略则交互询问；. 表示当前目录）"
+    ),
+    name: Optional[str] = typer.Option(None, "--name", help="项目名（默认目录名）"),
+    no_git: bool = typer.Option(False, "--no-git", help="不初始化 git 仓库"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="非交互：全部取默认值"),
+) -> None:
+    """创建 StarForge 项目：experiments/ + configs/（官方基底）+ common/ 骨架。
+
+    项目是独立的 git 仓库——实验配置与共享代码归你和团队所有，
+    与 CLI 工具的版本解耦（升级 CLI 只需 pip install -U starforge-cli）。
+    """
+    target = (directory or "").strip()
+    if not target and not yes:
+        target = typer.prompt("项目目录", default="my-starforge-lab")
+    if not target:
+        target = "my-starforge-lab"
+    dest = Path(target).expanduser()
+
+    project_name = (name or "").strip() or (dest.resolve().name if target != "." else Path.cwd().name)
+    if not yes and not name:
+        project_name = typer.prompt("项目名", default=project_name)
+
+    use_git = not no_git
+    if not yes and not no_git:
+        use_git = typer.confirm("初始化 git 仓库？", default=True)
+
+    try:
+        root = init_project(dest if target != "." else Path.cwd(), name=project_name, git=use_git)
+    except InitError as e:
+        cli_ui.fail(str(e))
+
+    typer.secho(f"✓ StarForge 项目已创建：{root}", fg=typer.colors.GREEN)
+    typer.echo("下一步：")
+    if target not in (".",):
+        typer.echo(f"  cd {target}")
+    typer.echo("  sf login --server https://<你的 StarForge 域名>   # 首次")
+    typer.echo("  sf new my-exp --method nemo-rl/grpo")
+    typer.echo("  sf submit my-exp --profile <卡型:卡数>")

starforge_cli/commands/jobs.py

@@ -0,0 +1,223 @@
+"""作业观测与控制：status + job 子命令组（全部经 Console）。"""
+from __future__ import annotations
+
+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
+
+job_app = typer.Typer(
+    no_args_is_help=True,
+    help="作业管理",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _format_user_label(user: dict) -> str:
+    """把 /api/whoami 的 user 格式化为单行展示。"""
+    username = user.get("username") or "?"
+    role = user.get("role") or "?"
+    parts = [f"用户：{username}", f"角色：{role}"]
+    if user.get("email"):
+        parts.append(f"邮箱：{user['email']}")
+    return "  ".join(parts)
+
+
+def status() -> None:
+    """账号、配额、用量与活跃作业。"""
+    gate()
+    who = api_client.whoami_via_server()
+    user = who.get("user") or {}
+    typer.echo(_format_user_label(user))
+    typer.echo("")
+
+    data = api_client.usage_via_server()
+    q, u = data.get("quota") or {}, data.get("usage") or {}
+    cap = q.get("max_concurrent_gpus")
+    typer.echo("我的用量")
+    typer.echo(f"  并发 GPU : {u.get('active_gpus', 0)} / {'不限' if cap is None else cap}")
+    typer.echo(f"  并发作业 : {u.get('active_jobs', 0)} / {q.get('max_concurrent_jobs') or '不限'}")
+    typer.echo(f"  今日/累计 GPU-hours : {u.get('gpu_hours_today', 0):.1f} / {u.get('gpu_hours_total', 0):.1f}")
+    running = u.get("running") or []
+    typer.echo("\n我的活跃作业")
+    if not running:
+        typer.echo("  （无）")
+    else:
+        for r in running:
+            jid = (r.get("job_ref") or r.get("lab_run_id") or "-")[:26]
+            typer.echo(f"  {jid:<26} {r.get('status','-'):<10} GPU={r.get('gpus') or '-'}  {r.get('exp','-')}")
+
+    cluster = api_client.cluster_status_via_server()
+    gpu = (cluster or {}).get("gpu") or {}
+    if gpu:
+        accel = "/".join(gpu.get("accel") or []) or "GPU"
+        typer.echo("\n集群 GPU")
+        typer.echo(
+            f"  {accel} : 空闲 {gpu.get('gpu_free', 0):g} / 共 {gpu.get('gpu_total', 0):g}"
+            f"（占用 {gpu.get('gpu_used', 0):g}）"
+        )
+        typer.echo(f"  活跃作业 : {cluster.get('active_count', 0)}")
+    typer.echo("\n查看日志：sf job logs [作业 ID]")
+
+
+def _server_jobs_table(jobs: list[dict]) -> None:
+    if not jobs:
+        typer.echo("（无作业）")
+        return
+    typer.echo(f"{'TIME':<20} {'JOB ID':<26} {'状态':<10} {'GPU':>4}  实验")
+    for j in jobs:
+        jid = (j.get("job_ref") or j.get("lab_run_id") or "-")[:26]
+        typer.echo(
+            f"{str(j.get('submitted_at', '-'))[:19]:<20} {jid:<26} "
+            f"{str(j.get('status','-')):<10} {str(j.get('requested_gpus') or '-'):>4}  "
+            f"{j.get('exp','-')}"
+        )
+
+
+@job_app.command("ls", help="作业列表（含提交历史）")
+def job_ls(
+    all_jobs: bool = typer.Option(False, "--all", help="显示全部（默认最近 15 条）"),
+    exp: Optional[str] = typer.Option(
+        None, "--exp", autocompletion=common.complete_exp, help="只看某实验（接受全名或末段名）"
+    ),
+    limit: int = typer.Option(15, "-n", "--limit", help="显示条数（--all 时忽略）"),
+) -> None:
+    gate()
+    jobs = api_client.list_my_jobs(limit=200 if all_jobs else limit)
+    if exp:
+        jobs = [j for j in jobs if exp in (j.get("exp") or "")]
+    _server_jobs_table(jobs)
+
+
+@job_app.command("logs", help="跟随作业日志（省略作业 ID 则跟最近一个）")
+def job_logs(
+    job_id: Optional[str] = typer.Argument(None, help="作业 ID（见 sf job ls）；省略=最近一个"),
+    tail: Optional[int] = typer.Option(
+        2000, "-n", "--tail", help="只回放最后 N 行历史日志再跟随（默认 2000；-n 0 看全量）"
+    ),
+) -> None:
+    gate()
+    jid = job_id or api_client.latest_job_via_server()
+    if not jid:
+        cli_ui.emit_warning("还没有作业", hint="运行 sf submit 提交训练")
+        raise typer.Exit(1)
+    api_client.stream_logs_via_server(jid, tail=tail)
+
+
+@job_app.command("status", help="查看作业状态")
+def job_status(
+    job_id: str = typer.Argument(..., help="作业 ID"),
+) -> None:
+    gate()
+    match = [j for j in api_client.list_my_jobs(limit=200)
+             if job_id in (j.get("job_ref") or "", j.get("lab_run_id") or "")]
+    if not match:
+        cli_ui.fail(f"未找到作业 {job_id}")
+    _server_jobs_table(match)
+
+
+@job_app.command("samples", help="查看某次验证的多轮对话轨迹（默认最近一次验证）")
+def job_samples(
+    job_id: str = typer.Argument(..., help="作业 ID（见 sf job ls）"),
+    vidx: int = typer.Option(-1, "--vidx", help="验证轮次下标（默认 -1=最近一次）"),
+    n: int = typer.Option(6, "-n", "--limit", help="显示样本条数"),
+) -> None:
+    gate()
+    overview = api_client.job_overview_via_server(job_id)
+    vals = overview.get("validations") or []
+    if not vals:
+        typer.secho("该作业暂无验证样本。", fg=typer.colors.YELLOW)
+        raise typer.Exit(1)
+    idx = vidx if vidx >= 0 else len(vals) + vidx
+    if idx < 0 or idx >= len(vals):
+        typer.secho(f"验证下标越界：vidx={vidx}，共 {len(vals)} 轮。", fg=typer.colors.RED)
+        raise typer.Exit(1)
+    page = api_client.samples_via_server(job_id, idx, 0, n)
+    samples = page.get("samples") or []
+    typer.echo(
+        f"验证 step={page.get('step', '?')}（第 {idx + 1}/{len(vals)} 轮）  "
+        f"样本 {len(samples)}/{page.get('total', len(samples))}"
+    )
+    for s in samples:
+        typer.echo("")
+        typer.secho(f"── Sample {s.get('idx', '?')} | reward={s.get('reward', '?')} ──", fg=typer.colors.CYAN)
+        if s.get("user"):
+            typer.secho("USER:", fg=typer.colors.GREEN)
+            typer.echo(s["user"])
+        if s.get("assistant"):
+            typer.secho("ASSISTANT:", fg=typer.colors.BLUE)
+            typer.echo(s["assistant"])
+        if s.get("env"):
+            typer.secho("ENVIRONMENT:", fg=typer.colors.MAGENTA)
+            typer.echo(s["env"])
+
+
+@job_app.command("stop", help="停止作业（运行中 → 终止）")
+def job_stop(
+    job_id: str = typer.Argument(..., help="作业 ID"),
+) -> None:
+    gate()
+    api_client.job_control_via_server("stop", job_id)
+    typer.secho("✓ 已停止作业", fg=typer.colors.GREEN)
+
+
+@job_app.command("pause", help="暂停作业（保留 checkpoint，可继续）")
+def job_pause(
+    job_id: str = typer.Argument(..., help="作业 ID"),
+) -> None:
+    gate()
+    api_client.job_control_via_server("pause", job_id)
+    typer.secho("✓ 已暂停作业（恢复后从最近 checkpoint 继续，最多丢最近 save_period 步）", fg=typer.colors.GREEN)
+
+
+@job_app.command("resume", help="继续已暂停的作业（自动从最近 checkpoint 续训）")
+def job_resume(
+    job_id: str = typer.Argument(..., help="作业 ID"),
+) -> None:
+    gate()
+    res = api_client.job_control_via_server("resume", job_id)
+    typer.secho(f"✓ {res.get('message') or '已加入恢复队列'}", fg=typer.colors.GREEN)
+
+
+@job_app.command("delete", help="删除某个已结束的作业记录（运行中需先 stop）")
+def job_delete(
+    job_id: str = typer.Argument(..., help="作业 ID"),
+) -> None:
+    gate()
+    api_client.job_control_via_server("delete", job_id)
+    typer.secho("✓ 已删除记录", fg=typer.colors.GREEN)
+
+
+@job_app.command("cancel-all", help="停止我所有运行中 / 排队中的作业")
+def job_cancel_all(
+    yes: bool = typer.Option(False, "-y", "--yes", help="跳过确认"),
+) -> None:
+    gate()
+    if not yes:
+        typer.confirm("将停止你【全部】运行中/排队中的作业，确认？", abort=True)
+    res = api_client.batch_via_server("cancel-all")
+    typer.secho(f"✓ 已停止 {res.get('stopped', 0)} 个作业", fg=typer.colors.GREEN)
+
+
+@job_app.command("clean", help="清理已结束作业的显示记录")
+def job_clean() -> None:
+    gate()
+    res = api_client.batch_via_server("clean")
+    typer.secho(f"✓ 已清理 {res.get('deleted', 0)} 个终态作业记录", fg=typer.colors.GREEN)
+
+
+@job_app.command("stop-sweep", help="一键停止一个超参 sweep 的全部活跃作业")
+def job_stop_sweep(
+    sweep_id: str = typer.Argument(..., help="sweep 标识（sf sweep 提交时打印）"),
+    yes: bool = typer.Option(False, "-y", "--yes", help="跳过确认"),
+) -> None:
+    gate()
+    if not yes:
+        typer.confirm(f"将停止 sweep {sweep_id} 的全部活跃作业，确认？", abort=True)
+    res = api_client.stop_sweep_via_server(sweep_id)
+    typer.secho(f"✓ 已停止 {res.get('stopped', 0)} 个作业", fg=typer.colors.GREEN)
+    for item in res.get("failed") or []:
+        cli_ui.emit_warning(f"停止失败：{item.get('id')}（{item.get('error')}）")

starforge_cli/commands/login.py

@@ -0,0 +1,54 @@
+"""身份命令：login / logout（凭据管理核心见 starforge_cli.auth）。"""
+from __future__ import annotations
+
+import urllib.error
+from typing import Optional
+
+import typer
+
+from starforge_cli import auth, cli_ui
+
+
+def login(
+    server: Optional[str] = typer.Option(
+        None, "--server", "-s",
+        help=f"Lab 服务地址（默认 {auth.DEFAULT_FORGE_SERVER}）",
+    ),
+    token: Optional[str] = typer.Option(None, "--token", help="非交互登录：直接用服务令牌（CI 用）"),
+    device_flow: bool = typer.Option(False, "--device-flow", help="强制使用设备码登录（SSH / 无浏览器）"),
+    no_browser: bool = typer.Option(False, "--no-browser", help="不打开浏览器（等同 --device-flow）"),
+) -> None:
+    """登录 Lab（本机默认浏览器；SSH 环境走验证码）。"""
+    srv = auth.current_server(server)
+    auth._save_server(srv)
+    if token:
+        creds = {"access_token": token, "refresh_token": None, "expires_at": None, "user": None}
+        try:
+            who = auth._api(srv, "GET", "/api/whoami", token=token)
+            creds["user"] = who.get("user")
+        except urllib.error.HTTPError:
+            cli_ui.fail("登录令牌无效，请重新登录。", hint="运行 sf login 重新登录")
+        auth._save_creds(srv, creds)
+    else:
+        creds = auth._interactive_login(srv, device_flow=device_flow, no_browser=no_browser)
+        auth._save_creds(srv, creds)
+    u = (creds.get("user") or {}).get("username", "?")
+    typer.secho(f"✓ 已登录：{u}", fg=typer.colors.GREEN)
+
+
+def logout(
+    server: Optional[str] = typer.Option(None, "--server", "-s", help="指定 Lab 地址（默认当前）"),
+) -> None:
+    """登出当前账号。"""
+    srv = auth.current_server(server)
+    creds = auth._load_creds(srv)
+    if not creds:
+        typer.echo("当前未登录。")
+        return
+    if creds.get("refresh_token"):
+        try:
+            auth._api(srv, "POST", "/api/auth/logout", body={"refresh_token": creds["refresh_token"]})
+        except urllib.error.URLError:
+            pass
+    auth._clear_creds(srv)
+    typer.secho("✓ 已登出", fg=typer.colors.GREEN)