starforge-cli 0.1.6__py3-none-any.whl

starforge_cli/commands/admin.py

@@ -0,0 +1,140 @@
+"""管理员命令：用户 / 配额 / 维护模式（需 admin 权限）。"""
+from __future__ import annotations
+
+import json
+import urllib.parse
+from typing import Optional
+
+import typer
+
+from starforge_cli import api_client
+
+admin_app = typer.Typer(
+    no_args_is_help=True,
+    help="管理员：用户与配额管理（需 admin 权限）。",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+@admin_app.command("users", help="列出所有用户")
+def admin_users() -> None:
+    data = api_client._admin_call("GET", "/api/admin/users")
+    for u in data.get("users", []):
+        flag = " [disabled]" if u.get("disabled") else ""
+        typer.echo(f"{u['id']:>3}  {u['username']:<20} {u['role']:<10} {u.get('auth_source','')}{flag}")
+
+
+@admin_app.command("user-add", help="新建本地账号")
+def admin_user_add(
+    username: str = typer.Argument(...),
+    password: str = typer.Option(..., "--password", "-p", prompt=True, hide_input=True),
+    role: str = typer.Option("operator", "--role", help="admin | operator | viewer"),
+    email: Optional[str] = typer.Option(None, "--email"),
+) -> None:
+    u = api_client._admin_call(
+        "POST", "/api/admin/users",
+        body={"username": username, "password": password, "role": role, "email": email},
+    )
+    typer.secho(f"✓ 已创建 {u['username']}（{u['role']}）", fg=typer.colors.GREEN)
+
+
+@admin_app.command("set-role", help="修改用户角色")
+def admin_set_role(username: str = typer.Argument(...), role: str = typer.Argument(...)) -> None:
+    u = api_client._admin_call("PATCH", f"/api/admin/users/{username}/role?role={urllib.parse.quote(role)}")
+    typer.secho(f"✓ {u['username']} → {u['role']}", fg=typer.colors.GREEN)
+
+
+@admin_app.command("disable", help="停用/启用用户（--on 停用，--off 启用）")
+def admin_disable(
+    username: str = typer.Argument(...),
+    disabled: bool = typer.Option(True, "--on/--off", help="--on 停用，--off 启用"),
+) -> None:
+    u = api_client._admin_call("PATCH", f"/api/admin/users/{username}/disabled?disabled={str(disabled).lower()}")
+    typer.secho(f"✓ {u['username']} disabled={u['disabled']}", fg=typer.colors.GREEN)
+
+
+@admin_app.command("set-quota", help="设置用户算力配额")
+def admin_set_quota(
+    username: str = typer.Argument(...),
+    gpus: int = typer.Option(8, "--gpus", help="并发 GPU 上限"),
+    jobs: int = typer.Option(4, "--jobs", help="并发作业上限"),
+    daily_gpu_hours: int = typer.Option(0, "--daily-gpu-hours", help="每日 GPU-时（0=不限）"),
+    profiles: Optional[str] = typer.Option(None, "--profiles", help="允许的 profile（逗号分隔，空=全部）"),
+    priority: int = typer.Option(0, "--priority", help="排队优先级"),
+) -> None:
+    allowed = [p.strip() for p in profiles.split(",") if p.strip()] if profiles else []
+    q = api_client._admin_call("POST", "/api/admin/quotas", body={
+        "username": username, "max_concurrent_gpus": gpus, "max_concurrent_jobs": jobs,
+        "daily_gpu_hours": daily_gpu_hours, "allowed_profiles": allowed, "priority": priority,
+    })
+    typer.secho(f"✓ 已设置 {username} 配额：{json.dumps(q, ensure_ascii=False)}", fg=typer.colors.GREEN)
+
+
+# ----------------------------- 维护模式（滚动升级集群镜像）-----------------------------
+# 完整流程见 console 仓库 deploy/ray-cluster/README.md「升级」一节：
+#   sf admin maintenance drain --note "升级镜像至 0.7.0-20260805"
+#   sf admin maintenance status            # 等到「可以重启」
+#   （各节点 docker compose pull && up -d）
+#   sf admin maintenance resume            # 作业自动从 checkpoint 续训
+maintenance_app = typer.Typer(
+    no_args_is_help=True,
+    help="维护模式：排空集群 → 升级 → 恢复（作业从 checkpoint 续训，不丢进度）",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+admin_app.add_typer(maintenance_app, name="maintenance")
+
+
+def _print_maintenance(data: dict) -> None:
+    on = data.get("maintenance_mode")
+    typer.secho(
+        f"维护模式：{'开启' if on else '关闭'}" + (f"（{data['note']}）" if data.get("note") else ""),
+        fg=typer.colors.YELLOW if on else typer.colors.GREEN,
+    )
+    if paused := data.get("paused"):
+        typer.echo(f"本次暂停 {len(paused)} 个训练作业：")
+        for rid in paused:
+            typer.echo(f"  · {rid}")
+    if pending := data.get("paused_awaiting_resume"):
+        typer.echo(f"待自动续训：{pending} 个")
+
+    # blockers / failed 是决定「能不能动集群」的关键，务必显眼
+    for key, label, color in (
+        ("blockers", "仍占卡（不支持 checkpoint 续跑，需等它跑完或手动停）", typer.colors.YELLOW),
+        ("failed", "停止失败（重跑 drain 或手动处理）", typer.colors.RED),
+    ):
+        for item in data.get(key) or []:
+            typer.secho(
+                f"  ⚠ [{label}] {item.get('lab_run_id')} ({item.get('username')})"
+                + (f" — {item['reason']}" if item.get("reason") else ""),
+                fg=color,
+            )
+
+    if "safe_to_restart" in data:
+        if data["safe_to_restart"]:
+            typer.secho("\n✓ 集群已排空，可以重启节点了", fg=typer.colors.GREEN, bold=True)
+            typer.echo("  各节点：docker compose --profile <head|worker> pull && up -d")
+            typer.echo("  升级完成后：sf admin maintenance resume")
+        else:
+            n = data.get("remaining_active", data.get("active_jobs", "?"))
+            typer.secho(f"\n✗ 还有 {n} 个作业占着卡，现在重启会打断它们", fg=typer.colors.RED, bold=True)
+
+
+@maintenance_app.command("status", help="查看维护状态与是否可以安全重启集群")
+def maintenance_status() -> None:
+    _print_maintenance(api_client._admin_call("GET", "/api/admin/maintenance"))
+
+
+@maintenance_app.command("drain", help="进入维护模式并排空集群（幂等，没排干净就再跑一次）")
+def maintenance_drain(
+    note: str = typer.Option("", "--note", help="维护说明，会回显给被拦下的提交者"),
+) -> None:
+    _print_maintenance(api_client._admin_call("POST", "/api/admin/maintenance/drain", body={"note": note}))
+
+
+@maintenance_app.command("resume", help="退出维护模式，被暂停的作业自动从 checkpoint 续训")
+def maintenance_resume() -> None:
+    data = api_client._admin_call("POST", "/api/admin/maintenance/resume")
+    typer.secho(
+        f"✓ 已退出维护模式，{data.get('resuming', 0)} 个作业将由队列按原优先级自动续训",
+        fg=typer.colors.GREEN,
+    )

starforge_cli/commands/bench.py

@@ -0,0 +1,94 @@
+"""标准基准评测提交：`sf bench <exp> --model … --suites …`。
+
+评测作业就是一次普通提交（evalkit/benchmark recipe，同一条配额/排队/产物链路）；
+本命令只做三件事：解析模型引用（`run:<run_id>` → 该 run 的 hf_export 产物路径）、
+把评测参数翻成超参、走标准提交。分数自动入库平台 benchmark 看板。
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+from typing import Optional
+
+import typer
+
+from starforge_cli import api_client, cli_ui, packing
+from starforge_cli.auth import gate
+from starforge_cli.commands import common
+from starforge_cli.commands.submit import (
+    _build_spec_or_exit,
+    _echo_submit_result,
+    _materialize_profile_or_exit,
+    _require_clean_tree,
+)
+
+
+def _resolve_model_ref(model: str) -> str:
+    """`run:<run_id>` → 该 run 已登记的 hf_export 产物路径；其余原样返回。"""
+    ref = (model or "").strip()
+    if not ref.startswith("run:"):
+        return ref
+    run_id = ref[len("run:"):].strip()
+    if not run_id:
+        cli_ui.fail("run: 引用缺少 run_id（形如 run:grpo-alice-20260101-120000）")
+    try:
+        with api_client._bearer_request(
+            api_client.current_server(None), "GET",
+            f"/api/jobs/{run_id}/artifacts",
+        ) as r:
+            data = json.loads(r.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        cli_ui.fail_http(e, fallback=f"查询 run {run_id} 产物失败")
+    exports = [a for a in data.get("artifacts") or [] if a.get("kind") == "hf_export"]
+    if not exports:
+        cli_ui.fail(
+            f"run {run_id} 没有 hf_export 产物",
+            hint=f"先导出：sf export {run_id}",
+        )
+    return str(exports[-1]["path"])
+
+
+def bench(
+    exp: str = typer.Argument(..., autocompletion=common.complete_exp,
+                              help="评测实验（sf new <名字> --method evalkit/benchmark 创建）"),
+    model: str = typer.Option(..., "--model", "-m",
+                              help="HF 模型 id / 共享盘绝对路径 / run:<run_id>（取该 run 的 hf_export）"),
+    suites: str = typer.Option(..., "--suites",
+                               help="逗号分隔的基准名（如 gsm8k,mmlu / ceval）"),
+    runner: str = typer.Option("lm-eval", "--runner", help="评测后端：lm-eval | evalscope"),
+    limit: Optional[int] = typer.Option(None, "--limit", help="每基准样本上限（冒烟用）"),
+    extra_args: str = typer.Option("", "--extra-args", help="透传给 runner 的附加参数"),
+    profile: list[str] = common.PROFILE_EXPR_OPT,
+    allow_dirty: bool = typer.Option(False, "--allow-dirty", help="允许工作区有未提交改动"),
+) -> None:
+    """提交基准评测作业（lm-eval / evalscope），分数自动入库平台看板。"""
+    gate()
+    exp_path = common.resolve_exp(exp)
+    resolved_model = _resolve_model_ref(model)
+
+    exprs = [e for e in (profile or []) if e.strip()]
+    if not exprs:
+        exprs = [common.resolve_profile(exp_path, None)]
+    resolved_profile, pools, roles = _materialize_profile_or_exit(exprs)
+    prov = packing.git_provenance(common.ROOT, exp_path)
+    _require_clean_tree(allow_dirty, prov)
+
+    sets = [f"runner={runner}", f"suites={suites}"]
+    if limit:
+        sets.append(f"limit={limit}")
+    if extra_args:
+        sets.append(f"extra_args={extra_args}")
+    # evalkit 实验没有 config 树，跳过 config 校验；超参仍由 recipe schema 严格校验。
+    project = common.project_name()
+    spec = _build_spec_or_exit(
+        exp_path, method="evalkit/benchmark", project=project, sets=sets,
+        pools=pools, roles=roles, init_from=None, then=[],
+        model=resolved_model, provenance=prov, validate=False,
+    )
+    with cli_ui.submit_progress() as reporter:
+        res = api_client.submit_via_server(
+            exp_path, resolved_profile, common.ROOT,
+            project=project, reporter=reporter, spec=spec,
+        )
+    _echo_submit_result(res, label="（基准评测）")
+    typer.echo("  评完看分数：web「Benchmarks」页，或 GET /api/benchmarks")

starforge_cli/commands/common.py

@@ -0,0 +1,178 @@
+"""命令层共享：项目根定位、实验/profile 解析、Tab 补全回调。"""
+from __future__ import annotations
+
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from starforge_cli import cli_ui
+
+#: StarForge 项目标记文件：`sf init` 生成，项目发现的唯一依据。
+#: CLI 已 pip 化分发（starforge-cli），不再假设自己被 clone 在项目仓库里。
+PROJECT_MARKER = "starforge.yaml"
+
+
+def project_root() -> Path:
+    """从 cwd 向上定位含 starforge.yaml 的项目根（类比 git 的仓库发现）。
+
+    找不到即失败并给出可执行指引——所有需要项目上下文的命令都经此收口；
+    login / status 等全局命令不触碰它。SF_PROJECT_ROOT 环境变量可显式覆盖
+    （CI / 脚本场景免 cd）。
+    """
+    if env := os.environ.get("SF_PROJECT_ROOT"):
+        p = Path(env).resolve()
+        if (p / PROJECT_MARKER).is_file():
+            return p
+        cli_ui.fail(f"SF_PROJECT_ROOT={env} 不是 StarForge 项目（缺 {PROJECT_MARKER}）")
+    cur = Path.cwd().resolve()
+    for cand in (cur, *cur.parents):
+        if (cand / PROJECT_MARKER).is_file():
+            return cand
+    cli_ui.fail(
+        "当前目录不在 StarForge 项目内",
+        hint="sf init <项目名> 创建新项目，或 cd 进已有项目目录（含 starforge.yaml）",
+    )
+
+
+def __getattr__(name: str):
+    """PEP 562：`common.ROOT` 惰性解析为当前项目根。
+
+    保持属性形态是刻意的——测试用 monkeypatch.setattr(common, "ROOT", tmp)
+    注入后，真实属性优先于 __getattr__，注入语义不变。
+    """
+    if name == "ROOT":
+        return project_root()
+    raise AttributeError(name)
+
+
+def _root() -> Path:
+    """模块内部取项目根：优先被注入的 ROOT 属性（测试），否则实时发现。"""
+    injected = globals().get("ROOT")
+    return injected if isinstance(injected, Path) else project_root()
+
+
+def project_name() -> str:
+    """当前项目的 starforge.yaml name。提交到 console 的 project 只走这里。"""
+    from starforge_cli.project import ProjectError, load_project_name
+
+    try:
+        return load_project_name(_root())
+    except ProjectError as exc:
+        cli_ui.fail(str(exc))
+
+
+class Kind(str, Enum):
+    experiments = "experiments"
+    projects = "projects"
+
+
+def resolve_exp(name: str) -> str:
+    """把实验名解析为相对仓库根的路径，接受 'experiments/x' / 'projects/x' / 'x'。"""
+    cands = [name] if "/" in name else [f"experiments/{name}", f"projects/{name}"]
+    for c in cands:
+        if (_root() / c).is_dir():
+            return c
+    cli_ui.fail(f"找不到实验「{name}」", hint="运行 sf ls 查看可用实验")
+
+
+def list_exps() -> list[str]:
+    out: list[str] = []
+    for kind in ("experiments", "projects"):
+        base = _root() / kind
+        if base.is_dir():
+            out += [p.name for p in base.iterdir() if p.is_dir()]
+    return sorted(set(out))
+
+
+def list_profiles() -> list[str]:
+    """可用硬件 profile 名，来自服务端注册表（本仓库已无 cluster/ 目录）。
+
+    仅用于补全与提示：拿不到（未登录/服务不可达）就静默返回空，不阻断主流程。
+    """
+    try:
+        from starforge_cli import api_client
+
+        data = api_client.cluster_status_via_server()
+        return sorted(
+            str(p.get("name")) for p in (data.get("profiles") or []) if p.get("name")
+        )
+    except Exception:  # 网络/鉴权失败只影响补全，不阻断主流程
+        return []
+
+
+def profile_registry() -> dict[str, dict]:
+    """服务端 profile 注册表：{名称: {series, num_nodes, gpus_per_node, ...}}。
+
+    提交时把 `--profile 名称[:总卡数]` 物化成 JobSpec 资源池要用（series 与
+    默认形状的唯一来源）。拿不到就显式失败——提交本来就离不开服务端。
+    """
+    from starforge_cli import api_client
+
+    try:
+        data = api_client.cluster_status_via_server()
+    except Exception as e:  # noqa: BLE001
+        cli_ui.fail(
+            "无法从服务端获取 profile 注册表",
+            hint=f"提交需要在线解析 --profile 的卡型与默认形状；请先 sf login 或检查服务可达性（{e}）",
+        )
+    return {
+        str(p.get("name")): p
+        for p in (data.get("profiles") or [])
+        if p.get("name")
+    }
+
+
+def resolve_profile(exp_path: str, profile: Optional[str]) -> str:
+    """确定作业的硬件 profile：--profile 优先，否则读实验目录遗留的 cluster 标注（兼容旧实验）。
+
+    profile 的 env/overrides/拓扑都在服务端注册表，名字的合法性也由服务端裁决；
+    客户端只负责把选择传上去。
+    """
+    p = (profile or "").strip()
+    if not p:
+        legacy = _root() / exp_path / "cluster"
+        if legacy.is_file():
+            p = legacy.read_text(encoding="utf-8").strip()
+    if not p:
+        opts = " ".join(list_profiles())
+        cli_ui.fail(
+            "无法确定硬件 profile",
+            hint=f"加 --profile <名称>{f'（可选: {opts}）' if opts else ''}",
+        )
+    return p
+
+
+# ----------------------------- 动态补全回调 -----------------------------
+def complete_exp(incomplete: str) -> list[str]:
+    return [e for e in list_exps() if e.startswith(incomplete)]
+
+
+def complete_profile(incomplete: str) -> list[str]:
+    return [p for p in list_profiles() if p.startswith(incomplete)]
+
+
+def complete_method(incomplete: str) -> list[str]:
+    """补全两段式方法标识；也按叶子名前缀匹配（输入 gr 可补出 nemo-rl/grpo）。"""
+    from starforge_core.recipes import recipe_names
+
+    return [
+        name for name in recipe_names()
+        if name.startswith(incomplete) or name.split("/", 1)[1].startswith(incomplete)
+    ]
+
+
+# 共享的 profile 选项（export/eval 用：资源形状由 recipe 固定，只选卡型/环境）。
+PROF_OPT = typer.Option(
+    None, "--profile", autocompletion=complete_profile,
+    help="硬件 profile（服务端注册表管理；`sf status` 可查看可用值）",
+)
+
+# submit 用的统一资源参数：profile 即资源入口，形状用 :总卡数 修饰。
+PROFILE_EXPR_OPT = typer.Option(
+    [], "--profile", metavar="[ROLE=]名称[:总卡数]", autocompletion=complete_profile,
+    help="目标硬件与资源，一个参数说清：h200（注册表默认形状）、h200:4（4 张卡）、"
+         "h200:16（2 满节点）。可重复以按角色分池（异构扩展位）：--profile train=h200:8 --profile rollout=h100:2",
+)

starforge_cli/commands/dataset.py

@@ -0,0 +1,150 @@
+"""数据集生命周期：prepare（本地预处理）→ push（上传对象存储）→ ls（查看版本）。"""
+from __future__ import annotations
+
+import sys
+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
+
+dataset_app = typer.Typer(
+    no_args_is_help=True,
+    help="数据集：本地预处理、上传到对象存储、按版本分发给作业",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+def _complete_dataset(incomplete: str) -> list[str]:
+    from starforge_cli.data_prep import discover
+
+    return [d for d in sorted(discover()) if d.startswith(incomplete)]
+
+
+@dataset_app.command(
+    "prepare",
+    help="本地预处理数据集（按约定发现 common/data/prepare_*.py，`sf dataset prepare` 不带参数列出可选）",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def dataset_prepare(
+    ctx: typer.Context,
+    dataset: str = typer.Argument(
+        "", autocompletion=_complete_dataset, help="数据集名；留空列出全部可选"
+    ),
+) -> None:
+    import os
+    import subprocess
+
+    from starforge_cli.data_prep import discover
+
+    preps = discover()
+    if not dataset:
+        if not preps:
+            cli_ui.fail("没有可用的数据预处理脚本", hint="往 common/data/ 放 prepare_<name>.py")
+        for p in preps.values():
+            typer.echo(f"{p.name:16s} {p.summary}")
+        return
+    prep = preps.get(dataset)
+    if not prep:
+        cli_ui.fail(f"未知数据集「{dataset}」", hint=f"可选：{', '.join(sorted(preps))}")
+    cmd = [sys.executable, str(prep.script), *ctx.args]
+    typer.echo("› " + " ".join(cmd))
+    # 用当前解释器（项目 uv 环境，含 datasets）跑数据脚本。
+    raise typer.Exit(
+        subprocess.run(cmd, env=os.environ.copy(), cwd=str(common.ROOT)).returncode
+    )
+
+
+@dataset_app.command("ls", help="列出可见的数据集（公开的 + 自己的）")
+def dataset_ls(
+    dataset: Optional[str] = typer.Argument(
+        None, help="数据集 ID（<owner>/<name>）；不传则列全部可见的"
+    ),
+    version: str = typer.Option("", "--version", "-v", help="看某个版本的文件清单；默认最新"),
+) -> None:
+    gate()
+    if dataset:
+        if "/" not in dataset:
+            cli_ui.fail(
+                f"数据集 ID 必须是 <owner>/<name>，得到 {dataset!r}",
+                hint="用 `sf dataset ls` 查看完整 ID",
+            )
+        owner, _, name = dataset.partition("/")
+        q = f"?version={version}" if version else ""
+        d = api_client.api_get(f"/api/datasets/{owner}/{name}{q}")
+        vis = "公开" if d["visibility"] == "public" else "私有"
+        typer.echo(
+            f"{d['id']}@{d['version']}  [{vis}]  "
+            f"{d['total_bytes'] / 1e6:.1f} MB  {len(d['files'])} 个文件"
+        )
+        for f in d["files"]:
+            typer.echo(f"  {f['name']:40s} {f['size'] / 1e6:8.2f} MB  {(f.get('sha256') or '')[:12]}")
+        return
+    rows = api_client.api_get("/api/datasets")["datasets"]
+    if not rows:
+        typer.echo("（还没有可见的数据集；`sf dataset push` 上传一个）")
+        return
+    for d in rows:
+        vis = "公开" if d["visibility"] == "public" else "私有"
+        typer.echo(f"{d['id']:32s} [{vis}] {', '.join(d['versions']) or '（无版本）'}")
+
+
+@dataset_app.command("push", help="上传一个数据集版本（默认私有，--public 公开）")
+def dataset_push(
+    dataset: str = typer.Argument(
+        ..., help="数据集名（归到自己命名空间），或完整 <owner>/<name>（admin 可跨命名空间）"
+    ),
+    version: str = typer.Argument(..., help="版本，如 v1 / 20260812"),
+    path: str = typer.Argument(..., help="本地目录"),
+    public: bool = typer.Option(
+        False, "--public", help="首次创建时设为公开（所有人可在训练中引用）"
+    ),
+) -> None:
+    """上传目录下的全部文件，并生成带 sha256 的 index.json。
+
+    校验和不是可选项：作业侧靠它判断下载是否被截断。静默接受一个截断的
+    train.jsonl，就是拿脏数据训练几小时后才发现结果不对。
+
+    版本不可变：已完整上传的版本不能覆写，要更新请换新版本号。
+    """
+    gate()
+    root = Path(path)
+    if not root.is_dir():
+        cli_ui.fail(f"不是目录: {path}")
+    files = sorted(p for p in root.rglob("*") if p.is_file())
+    if not files:
+        cli_ui.fail(f"目录为空: {path}")
+    ds_id = api_client.dataset_push(
+        dataset, version, root, files, visibility="public" if public else None,
+    )
+    short = ds_id.rpartition("/")[2]
+    env_var = f"{short.upper().replace('-', '_').replace('.', '_')}_DATA_DIR"
+    typer.echo(f"已上传 {ds_id}@{version}（{len(files)} 个文件）")
+    # 数据集是实验的属性：推荐声明在 config（submit 自动拾取），CLI 参数仅作临时覆盖。
+    typer.echo(
+        f"训练里引用它：实验 config 里声明 data.train.dataset: {ds_id}@{version}"
+        f"，数据文件用 ${{oc.env:{env_var}}}/train.jsonl 指到"
+        f"（提交时自动拉到共享缓存并注入 {env_var}；--train-dataset 可临时覆盖版本）"
+    )
+
+
+@dataset_app.command("visibility", help="改数据集可见性（owner 或 admin）")
+def dataset_visibility(
+    dataset: str = typer.Argument(..., help="数据集 ID（<owner>/<name>）"),
+    public: bool = typer.Option(False, "--public", help="设为公开"),
+    private: bool = typer.Option(False, "--private", help="设为私有"),
+) -> None:
+    gate()
+    if public == private:
+        cli_ui.fail("必须且只能指定 --public 或 --private 之一")
+    if "/" not in dataset:
+        cli_ui.fail(
+            f"数据集 ID 必须是 <owner>/<name>，得到 {dataset!r}",
+            hint="用 `sf dataset ls` 查看完整 ID",
+        )
+    owner, _, name = dataset.partition("/")
+    vis = "public" if public else "private"
+    r = api_client.api_patch(f"/api/datasets/{owner}/{name}", {"visibility": vis})
+    typer.echo(f"{r['id']} 现在是{'公开' if r['visibility'] == 'public' else '私有'}数据集")