starforge-cli 0.1.6__tar.gz → 0.1.7__tar.gz

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: starforge-cli
-Version: 0.1.6
+Version: 0.1.7
 Summary: StarForge（星锻）命令行客户端：pip 安装后用 sf init 创建微调项目，再提交训练。
 Project-URL: Homepage, https://github.com/wccdev/starforge
 Project-URL: Documentation, https://github.com/wccdev/starforge
@@ -18,7 +18,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10
 Requires-Dist: datasets>=2.18
 Requires-Dist: pyyaml>=6
-Requires-Dist: starforge-core==0.1.6
+Requires-Dist: starforge-core==0.2.0
 Requires-Dist: typer>=0.12
 Provides-Extra: dev
 Requires-Dist: fastapi>=0.110; extra == 'dev'

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "starforge-cli"
-version = "0.1.6"
+version = "0.1.7"
 description = "StarForge（星锻）命令行客户端：pip 安装后用 sf init 创建微调项目，再提交训练。"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,7 +17,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
-    "starforge-core==0.1.6",
+    "starforge-core==0.2.0",
     "typer>=0.12",
     "datasets>=2.18",
     "pyyaml>=6",

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/__init__.py

@@ -1,3 +1,3 @@
 """starforge-cli：统一 CLI 包。命令入口见 starforge_cli.cli:app（安装后提供 `sf`）。"""
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/cli.py

@@ -36,12 +36,12 @@ app = typer.Typer(
 # ----------------------------- 项目与身份 -----------------------------
 from starforge_cli.commands import init as init_cmd  # noqa: E402
 
-app.command(help="创建 StarForge 微调项目（experiments/ + 官方基底 + common 骨架）")(init_cmd.init)
+app.command(help="创建 StarForge 仓库（experiments/ + 官方基底 + common 骨架）")(init_cmd.init)
 app.command(help="登录 StarForge")(login.login)
 app.command(help="登出")(login.logout)
 
 # ----------------------------- 实验资产（纯本地）-----------------------------
-app.command(help="列出实验 / 项目")(exp.ls)
+app.command(help="列出仓库里的实验目录")(exp.ls)
 app.command(help="新建实验（--from fork 现成实验；--method 来自 SDK recipe catalog）")(exp.new)
 app.command(name="methods", help="列出可用的后训练方法与它们的超参")(exp.methods)
 app.command(help="校验实验 config（提交前本地检查）")(exp.validate)

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/commands/common.py

@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 import os
-from enum import Enum
 from pathlib import Path
 from typing import Optional
 
@@ -12,24 +11,24 @@ from starforge_cli import cli_ui
 
 #: StarForge 项目标记文件：`sf init` 生成，项目发现的唯一依据。
 #: CLI 已 pip 化分发（starforge-cli），不再假设自己被 clone 在项目仓库里。
-PROJECT_MARKER = "starforge.yaml"
+REPO_MARKER = "starforge.yaml"
 
 
 def project_root() -> Path:
     """从 cwd 向上定位含 starforge.yaml 的项目根（类比 git 的仓库发现）。
 
     找不到即失败并给出可执行指引——所有需要项目上下文的命令都经此收口；
-    login / status 等全局命令不触碰它。SF_PROJECT_ROOT 环境变量可显式覆盖
+    login / status 等全局命令不触碰它。SF_REPO_ROOT 环境变量可显式覆盖
     （CI / 脚本场景免 cd）。
     """
-    if env := os.environ.get("SF_PROJECT_ROOT"):
+    if env := os.environ.get("SF_REPO_ROOT"):
         p = Path(env).resolve()
-        if (p / PROJECT_MARKER).is_file():
+        if (p / REPO_MARKER).is_file():
             return p
-        cli_ui.fail(f"SF_PROJECT_ROOT={env} 不是 StarForge 项目（缺 {PROJECT_MARKER}）")
+        cli_ui.fail(f"SF_REPO_ROOT={env} 不是 StarForge 仓库（缺 {REPO_MARKER}）")
     cur = Path.cwd().resolve()
     for cand in (cur, *cur.parents):
-        if (cand / PROJECT_MARKER).is_file():
+        if (cand / REPO_MARKER).is_file():
             return cand
     cli_ui.fail(
         "当前目录不在 StarForge 项目内",
@@ -56,22 +55,21 @@ def _root() -> Path:
 
 def project_name() -> str:
     """当前项目的 starforge.yaml name。提交到 console 的 project 只走这里。"""
-    from starforge_cli.project import ProjectError, load_project_name
+    from starforge_cli.repo import RepoError, load_project_name
 
     try:
         return load_project_name(_root())
-    except ProjectError as exc:
+    except RepoError as exc:
         cli_ui.fail(str(exc))
 
 
-class Kind(str, Enum):
-    experiments = "experiments"
-    projects = "projects"
+#: 实验目录的唯一存放位置（历史上还支持 projects/，已与 experiments/ 合并）。
+EXPERIMENTS_DIR = "experiments"
 
 
 def resolve_exp(name: str) -> str:
-    """把实验名解析为相对仓库根的路径，接受 'experiments/x' / 'projects/x' / 'x'。"""
-    cands = [name] if "/" in name else [f"experiments/{name}", f"projects/{name}"]
+    """把实验名解析为相对仓库根的路径，接受 'experiments/x' / 'x'。"""
+    cands = [name] if "/" in name else [f"{EXPERIMENTS_DIR}/{name}"]
     for c in cands:
         if (_root() / c).is_dir():
             return c
@@ -79,12 +77,10 @@ def resolve_exp(name: str) -> str:
 
 
 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))
+    base = _root() / EXPERIMENTS_DIR
+    if not base.is_dir():
+        return []
+    return sorted({p.name for p in base.iterdir() if p.is_dir()})
 
 
 def list_profiles() -> list[str]:

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/commands/exp.py

@@ -11,15 +11,15 @@ 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}")
+    """列出仓库里的实验目录。"""
+    base = common.ROOT / common.EXPERIMENTS_DIR
+    if not base.is_dir():
+        typer.echo(f"[{common.EXPERIMENTS_DIR}] (0)")
+        return
+    exps = sorted(p.name for p in base.iterdir() if p.is_dir())
+    typer.echo(f"\n[{common.EXPERIMENTS_DIR}] ({len(exps)})")
+    for e in exps:
+        typer.echo(f"  - {e}")
 
 
 def new(
@@ -37,9 +37,6 @@ def new(
         "--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":
@@ -52,7 +49,7 @@ def new(
     try:
         create_experiment(
             common.ROOT,
-            kind.value,
+            common.EXPERIMENTS_DIR,
             name,
             src=src,
             method=method,

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/commands/init.py

@@ -1,4 +1,4 @@
-"""`sf init`：交互式创建 StarForge 微调项目。"""
+"""`sf init`：交互式创建 StarForge 仓库。"""
 from __future__ import annotations
 
 from pathlib import Path
@@ -7,25 +7,25 @@ from typing import Optional
 import typer
 
 from starforge_cli import cli_ui
-from starforge_cli.project import InitError, init_project
+from starforge_cli.repo import InitError, init_repo
 
 
 def init(
     directory: Optional[str] = typer.Argument(
-        None, help="项目目录（省略则交互询问；. 表示当前目录）"
+        None, help="仓库目录（省略则交互询问；. 表示当前目录）"
     ),
-    name: Optional[str] = typer.Option(None, "--name", help="项目名（默认目录名）"),
+    name: Optional[str] = typer.Option(None, "--name", help="项目名，写入 starforge.yaml（默认目录名）"),
     no_git: bool = typer.Option(False, "--no-git", help="不初始化 git 仓库"),
     yes: bool = typer.Option(False, "--yes", "-y", help="非交互：全部取默认值"),
 ) -> None:
-    """创建 StarForge 项目：experiments/ + configs/（官方基底）+ common/ 骨架。
+    """创建 StarForge 仓库：experiments/ + configs/（官方基底）+ common/ 骨架。
 
-    项目是独立的 git 仓库——实验配置与共享代码归你和团队所有，
+    仓库是独立的 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")
+        target = typer.prompt("仓库目录", default="my-starforge-lab")
     if not target:
         target = "my-starforge-lab"
     dest = Path(target).expanduser()
@@ -39,11 +39,11 @@ def init(
         use_git = typer.confirm("初始化 git 仓库？", default=True)
 
     try:
-        root = init_project(dest if target != "." else Path.cwd(), name=project_name, git=use_git)
+        root = init_repo(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.secho(f"✓ StarForge 仓库已创建：{root}", fg=typer.colors.GREEN)
     typer.echo("下一步：")
     if target not in (".",):
         typer.echo(f"  cd {target}")

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/commands/jobs.py

@@ -160,8 +160,13 @@ 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)
+    res = api_client.job_control_via_server("stop", job_id)
+    # 服务端用 stopped 区分「真停了」与「本来就是终态」——一律打印「已停止」会让人
+    # 以为卡放出来了。老服务端不返回这个字段，缺失时按真停了处理。
+    if res.get("stopped", True):
+        typer.secho("✓ 已停止作业", fg=typer.colors.GREEN)
+    else:
+        typer.secho(f"· 作业已是终态（{res.get('status') or '未知'}），无需停止", fg=typer.colors.YELLOW)
 
 
 @job_app.command("pause", help="暂停作业（保留 checkpoint，可继续）")
@@ -187,8 +192,11 @@ 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)
+    res = api_client.job_control_via_server("delete", job_id)
+    if res.get("removed_db", True):
+        typer.secho("✓ 已删除记录", fg=typer.colors.GREEN)
+    else:
+        typer.secho("· 台账记录未变（可能已被删除）", fg=typer.colors.YELLOW)
 
 
 @job_app.command("cancel-all", help="停止我所有运行中 / 排队中的作业")

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/commands/plugin.py

@@ -10,7 +10,6 @@
 from __future__ import annotations
 
 import io
-import json
 import shutil
 import tarfile
 from pathlib import Path

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/commands/recipe.py

@@ -54,7 +54,7 @@ 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"),
+    all_exps: bool = typer.Option(False, "--all", help="扫描 experiments/ 与 smoke/"),
     server: bool = typer.Option(False, "--server", help="再与 Console catalog 握手对照"),
 ) -> None:
     manager = RecipeLockManager()

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/commands/sweep.py

@@ -4,7 +4,7 @@
   - **不造第二条提交路径**：每个变体就是一次普通 `sf submit`（同一份 spec 构建、
     校验、打包、配额准入、容量排队），服务端零特殊逻辑。sweep 只是「展开 + 循环 +
     分组标识」。
-  - 分组复用现成机制：project 来自 starforge.yaml（web 实验分组页按项目聚合）+
+  - 分组复用现成机制：project 来自 starforge.yaml（web 项目页按项目聚合）+
     client_meta.sweep_id / sweep_params（服务端落 jobs.sweep_id 索引列，
     一键停止 / 徽标展示用）。
   - 配额不足的变体自动入队（persist_and_enqueue），不会失败——批量提交天然

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/new_experiment.py

@@ -12,12 +12,12 @@ class NewExperimentError(Exception):
 
 
 def _resolve_src_dir(repo_root: Path, src: str) -> Path:
-    for c in (src, f"experiments/{src}", f"projects/{src}"):
+    for c in (src, f"experiments/{src}"):
         p = repo_root / c
         if p.is_dir():
             return p
     raise NewExperimentError(
-        f"找不到来源实验: {src}（试过 {src} / experiments/{src} / projects/{src}）"
+        f"找不到来源实验: {src}（试过 {src} / experiments/{src}）"
     )
 
 
@@ -135,7 +135,7 @@ def _create_from_template(
         # get_recipe 的报错已列出可用值，并对无前缀裸名给出两段式提示。
         raise NewExperimentError(f"--method 非法: {exc}") from exc
     # 实验模板随 CLI 包分发（starforge_cli/scaffold/），不依赖项目内容。
-    from starforge_cli.project import experiment_template
+    from starforge_cli.repo import experiment_template
 
     template = experiment_template()
     if not template.is_dir():
@@ -180,8 +180,8 @@ def create_experiment(
     framework_version: str = "",
 ) -> None:
     """新建或 fork 实验；失败时抛 NewExperimentError。"""
-    if kind not in ("experiments", "projects"):
-        raise NewExperimentError("第一个参数必须是 experiments 或 projects")
+    if kind != "experiments":
+        raise NewExperimentError("实验目录只能建在 experiments/ 下")
 
     if src:
         _fork_experiment(repo_root, kind, name, src)

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/recipe_lock.py

@@ -20,7 +20,7 @@ LOCK_FILE = "recipe.lock.json"
 LOCK_VERSION = "forge/recipe-lock/v3"
 _LEGACY_LOCK_VERSION = "forge/recipe-lock/v2"
 _SUPPORTED_LOCK_VERSIONS = (LOCK_VERSION, _LEGACY_LOCK_VERSION)
-_EXPERIMENT_KINDS = ("experiments", "projects", "smoke")
+_EXPERIMENT_KINDS = ("experiments", "smoke")
 
 
 class LockState(str, Enum):

starforge_cli-0.1.6/starforge_cli/project.py → starforge_cli-0.1.7/starforge_cli/repo.py

@@ -1,16 +1,20 @@
-"""StarForge 项目脚手架：`sf init` 的实现。
+"""StarForge 仓库脚手架：`sf init` 的实现。
 
 CLI 经 pip 分发（starforge-cli），用户不 clone 工具仓库；`sf init` 生成
-自包含的项目目录（自己的 git 仓库），布局与作业包白名单严格对应：
+自包含的仓库目录（自己的 git 仓库），布局与作业包白名单严格对应：
 
     my-lab/
-    ├── starforge.yaml     项目标记（项目发现的唯一依据）
-    ├── experiments/       实验目录（sf new 在此创建）
+    ├── starforge.yaml     仓库标记，并声明本仓库的项目名（项目发现的唯一依据）
+    ├── experiments/       实验目录（sf new 在此创建，一个目录 = 一次实验/作业）
     ├── configs/           官方基底 + 模型片段（脚手架落地，用户可调可 pin）
-    ├── common/            项目共享代码（数据脚本 / 环境 / 奖励）
+    ├── common/            仓库共享代码（数据脚本 / 环境 / 奖励）
     └── .gitignore
 
-平台 bootstrap/runner 不落地到项目，也不由 CLI 上传；console 在准入后注入
+仓库与项目的关系：仓库是磁盘上的容器，项目是 starforge.yaml 声明的名字，提交后
+在 console 侧按 @<用户名>/<项目名> 聚合出「项目」。项目名不要求全局唯一——用户名
+编入分组键，不同用户的同名项目互不干扰。
+
+平台 bootstrap/runner 不落地到仓库，也不由 CLI 上传；console 在准入后注入
 内容寻址 Job Capsule，用户代码不能覆盖平台入口。
 """
 from __future__ import annotations
@@ -24,31 +28,31 @@ from pathlib import Path
 
 import yaml
 
-PROJECT_MARKER = "starforge.yaml"
+REPO_MARKER = "starforge.yaml"
 # 与 console 分组键一致：会进 URL / 路径，只允许安全字符。
 _PROJECT_NAME_RE = re.compile(r"^[A-Za-z0-9._-]+$")
 
 
-class ProjectError(RuntimeError):
+class RepoError(RuntimeError):
     pass
 
 
 def load_project_name(root: Path) -> str:
-    """读 starforge.yaml 的 name。提交到 console 的 project 只来自这里。"""
-    path = root / PROJECT_MARKER
+    """读 starforge.yaml 的 name（本仓库的项目名）。提交到 console 的 project 只来自这里。"""
+    path = root / REPO_MARKER
     if not path.is_file():
-        raise ProjectError(f"{root} 不是 StarForge 项目（缺 {PROJECT_MARKER}）")
+        raise RepoError(f"{root} 不是 StarForge 仓库（缺 {REPO_MARKER}）")
     try:
         data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     except yaml.YAMLError as exc:
-        raise ProjectError(f"{path} 无法解析：{exc}") from exc
+        raise RepoError(f"{path} 无法解析：{exc}") from exc
     if not isinstance(data, dict):
-        raise ProjectError(f"{path} 根节点必须是对象")
+        raise RepoError(f"{path} 根节点必须是对象")
     name = str(data.get("name") or "").strip()
     if not name:
-        raise ProjectError(f"{path} 缺少 name")
+        raise RepoError(f"{path} 缺少 name")
     if name in (".", "..") or not _PROJECT_NAME_RE.match(name):
-        raise ProjectError(f"非法项目名 {name!r}（仅允许字母数字与 . _ -）")
+        raise RepoError(f"非法项目名 {name!r}（仅允许字母数字与 . _ -）")
     return name
 
 
@@ -66,14 +70,14 @@ class InitError(RuntimeError):
     pass
 
 
-def init_project(dest: Path, *, name: str = "", git: bool = True) -> Path:
-    """在 dest 生成 StarForge 项目；目录已是项目或非空冲突时报错。"""
+def init_repo(dest: Path, *, name: str = "", git: bool = True) -> Path:
+    """在 dest 生成 StarForge 仓库；目录已是仓库或非空冲突时报错。"""
     dest = dest.resolve()
-    if (dest / PROJECT_MARKER).is_file():
-        raise InitError(f"{dest} 已经是 StarForge 项目")
+    if (dest / REPO_MARKER).is_file():
+        raise InitError(f"{dest} 已经是 StarForge 仓库")
     if dest.exists() and any(dest.iterdir()):
         # 允许在非空目录初始化（如已有 README 的空仓库），但拒绝覆盖关键路径
-        for clash in ("experiments", "configs", "common", PROJECT_MARKER):
+        for clash in ("experiments", "configs", "common", REPO_MARKER):
             if (dest / clash).exists():
                 raise InitError(f"{dest} 下已存在 {clash}，拒绝覆盖；换个目录或清理后重试")
     dest.mkdir(parents=True, exist_ok=True)
@@ -93,8 +97,8 @@ def init_project(dest: Path, *, name: str = "", git: bool = True) -> Path:
         cli_version = _pkg_version("starforge-cli")
     except Exception:  # noqa: BLE001 — 源码运行（未安装分发元数据）
         cli_version = "dev"
-    (dest / PROJECT_MARKER).write_text(
-        "# StarForge 项目标记：`sf` 命令以此发现项目根，勿删除。\n"
+    (dest / REPO_MARKER).write_text(
+        "# StarForge 仓库标记：`sf` 命令以此发现仓库根，勿删除。\n"
         f'apiVersion: forge/project/v1\n'
         f'name: {project_name}\n'
         f'created_by: starforge-cli {cli_version}\n',
@@ -104,7 +108,7 @@ def init_project(dest: Path, *, name: str = "", git: bool = True) -> Path:
     if not readme.exists():
         readme.write_text(
             f"# {project_name}\n\n"
-            "StarForge（星锻）微调项目。常用命令：\n\n"
+            "StarForge（星锻）微调仓库。常用命令：\n\n"
             "```bash\n"
             "sf new my-exp --method nemo-rl/grpo   # 新建实验\n"
             "sf validate my-exp                    # 本地校验\n"
@@ -112,7 +116,7 @@ def init_project(dest: Path, *, name: str = "", git: bool = True) -> Path:
             "sf job logs                           # 跟随日志\n"
             "```\n\n"
             "目录说明：`experiments/` 实验本体；`configs/` 官方基底与模型片段；\n"
-            "`common/` 项目共享代码（数据脚本 / Agent 环境 / 奖励函数）。\n",
+            "`common/` 仓库共享代码（数据脚本 / Agent 环境 / 奖励函数）。\n",
             encoding="utf-8",
         )
 

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/scaffold/experiment-template/README.md

@@ -25,7 +25,7 @@
 ## 运行
 
 ```bash
-uv run sf submit <实验名> --profile h100
+sf submit <实验名> --profile h100
 ```
 
 产物（checkpoint / 日志）落到本目录 `outputs/`（已 .gitignore）。

{starforge_cli-0.1.6 → starforge_cli-0.1.7}/starforge_cli/spec_builder.py

@@ -157,7 +157,7 @@ def materialize_pools(
         roles = [f"{role}:{pool_name}"] if role else []
         return name, pools, roles
 
-    missing = [raw for raw, (role, _, _) in zip(exprs, parsed) if not role]
+    missing = [raw for raw, (role, _, _) in zip(exprs, parsed, strict=False) if not role]
     if missing:
         raise SpecError(
             f"多个 --profile 时每条都要 role= 前缀（角色到池的映射），缺前缀：{missing[0]!r}"
@@ -231,16 +231,13 @@ def build_spec(
         raise SpecError(f"方法 {r.id} 使用 platform observability，不允许 --observability-url")
     if r.framework == "custom" and not selected_image:
         raise SpecError("custom recipe 要求显式提供 --image")
-    if r.framework in {"verl", "trl"} and operation == "train":
-        missing = [
-            flag
-            for flag, value in (
-                ("--model", base_model),
-                ("--train-data", train_data),
-                ("--validation-data", validation_data),
-            )
-            if not value.strip()
-        ]
+    if r.framework in {"verl", "trl", "openrlhf"} and operation == "train":
+        required = [("--model", base_model), ("--train-data", train_data)]
+        # openrlhf：RL 的 eval.dataset 依赖 remote reward（上游硬约束），验证集是
+        # 可选项，约束由服务端 adapter 在编译期裁决；verl/trl 仍然三项必填。
+        if r.framework != "openrlhf":
+            required.append(("--validation-data", validation_data))
+        missing = [flag for flag, value in required if not value.strip()]
         if missing:
             raise SpecError(f"{r.framework} recipe 要求显式提供：{' '.join(missing)}")