starforge-cli 0.1.6__py3-none-any.whl

starforge_cli/data_prep.py

@@ -0,0 +1,60 @@
+"""数据预处理脚本注册表：按约定发现，不再维护硬编码名单。
+
+加数据集 = 往 common/data/ 放一个 prepare_<name>.py —— 与「加方法 = 往
+catalog 加 recipe 目录」同一哲学。CLI（补全、错误提示、执行）都从这里取，
+后续插件系统（kind=data-prep）把已安装插件的脚本目录并入扫描即可，命令层
+零改动。
+
+脚本首行 docstring 会作为该数据集的一句话说明展示在 CLI 里，用 ast 读取而
+不 import —— 数据脚本普遍拉重依赖（datasets/pandas），列个清单不该付这个价。
+"""
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+_PREFIX = "prepare_"
+
+
+@dataclass(frozen=True)
+class DataPrep:
+    name: str
+    script: Path
+    summary: str
+
+
+def _summary(script: Path) -> str:
+    try:
+        doc = ast.get_docstring(ast.parse(script.read_text(encoding="utf-8")))
+    except (OSError, SyntaxError):
+        return ""
+    return doc.strip().splitlines()[0].strip() if doc else ""
+
+
+def default_dirs() -> list[Path]:
+    """扫描目录：仓库内置的 common/data + 已安装插件（forge_plugins/<name>/）。
+
+    内置目录在前：同名脚本内置优先，插件不能悄悄替换内置数据集的语义。
+    """
+    from starforge_cli.commands.common import ROOT
+
+    dirs = [ROOT / "common" / "data"]
+    plugins_root = ROOT / "forge_plugins"
+    if plugins_root.is_dir():
+        dirs += sorted(p for p in plugins_root.iterdir() if p.is_dir())
+    return dirs
+
+
+def discover(dirs: Iterable[Path] | None = None) -> dict[str, DataPrep]:
+    """扫描目录下的 prepare_<name>.py，返回 name → DataPrep（同名先到先得）。"""
+    found: dict[str, DataPrep] = {}
+    for d in dirs if dirs is not None else default_dirs():
+        if not d.is_dir():
+            continue
+        for script in sorted(d.glob(f"{_PREFIX}*.py")):
+            name = script.stem[len(_PREFIX):]
+            if name and name not in found:
+                found[name] = DataPrep(name=name, script=script, summary=_summary(script))
+    return found

starforge_cli/new_experiment.py

@@ -0,0 +1,195 @@
+"""跨平台新建 / fork 实验（唯一入口：sf new，macOS / Linux / Windows 共用）。"""
+from __future__ import annotations
+
+import re
+import shutil
+import tempfile
+from pathlib import Path
+
+
+class NewExperimentError(Exception):
+    pass
+
+
+def _resolve_src_dir(repo_root: Path, src: str) -> Path:
+    for c in (src, f"experiments/{src}", f"projects/{src}"):
+        p = repo_root / c
+        if p.is_dir():
+            return p
+    raise NewExperimentError(
+        f"找不到来源实验: {src}（试过 {src} / experiments/{src} / projects/{src}）"
+    )
+
+
+def _patch_fork_metadata(dest: Path, name: str) -> None:
+    """fork 后改 swanlab project/name 与 README 标题（保留注释）。"""
+    cfg = dest / "config.yaml"
+    if cfg.is_file():
+        lines = cfg.read_text(encoding="utf-8").splitlines()
+        in_sw, sw_indent = False, 0
+        for i, ln in enumerate(lines):
+            s, indent = ln.strip(), len(ln) - len(ln.lstrip())
+            if s == "swanlab:":
+                in_sw, sw_indent = True, indent
+                continue
+            if in_sw:
+                if s and indent <= sw_indent:
+                    in_sw = False
+                else:
+                    m = re.match(r"^(\s*)(project|name):\s*.*$", ln)
+                    if m:
+                        lines[i] = f'{m.group(1)}{m.group(2)}: "{name}"'
+        cfg.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    readme = dest / "README.md"
+    if readme.is_file():
+        rl = readme.read_text(encoding="utf-8").splitlines()
+        for i, ln in enumerate(rl):
+            if ln.startswith("# "):
+                rl[i] = f"# {name}"
+                break
+        readme.write_text("\n".join(rl) + "\n", encoding="utf-8")
+
+
+def _validate_recipe_template(dest: Path, recipe) -> None:
+    """只校验 recipe 声明的结构，不跨框架执行别的 validator。"""
+    if recipe.framework in {"nemo-rl", "verl"} and not (dest / "config.yaml").is_file():
+        raise NewExperimentError(f"recipe {recipe.id} 模板缺少 config.yaml")
+    if recipe.entrypoint.kind == "experiment":
+        entry = (dest / recipe.entrypoint.value).resolve()
+        root = dest.resolve()
+        if not entry.is_relative_to(root) or not entry.is_file():
+            raise NewExperimentError(
+                f"recipe {recipe.id} 模板缺少实验入口 {recipe.entrypoint.value}"
+            )
+
+
+def _copy_recipe_template(dest: Path, recipe) -> None:
+    from starforge_core.recipes import recipe_directory
+
+    template = recipe_directory(recipe.id) / recipe.template
+    if not template.is_dir():
+        raise NewExperimentError(f"recipe {recipe.id} 缺少模板目录: {template}")
+    shutil.copytree(template, dest, dirs_exist_ok=True)
+
+
+def _fork_experiment(repo_root: Path, kind: str, name: str, src: str) -> None:
+    dest = repo_root / kind / name
+    if dest.exists():
+        raise NewExperimentError(f"已存在: {dest}")
+
+    src_dir = _resolve_src_dir(repo_root, src)
+    from starforge_cli.commands.exp import validate_exp_config
+    from starforge_cli.recipe_lock import RecipeLockError, RecipeLockManager
+    from starforge_cli.spec_builder import infer_recipe
+
+    recipe_name = infer_recipe(src_dir)
+    if not recipe_name:
+        raise NewExperimentError(f"来源实验缺少 recipe.lock.json（recipe 声明）: {src_dir}")
+    shutil.copytree(src_dir, dest)
+    outputs = dest / "outputs"
+    if outputs.exists():
+        shutil.rmtree(outputs)
+
+    _patch_fork_metadata(dest, name)
+    try:
+        RecipeLockManager().upgrade(
+            dest,
+            recipe_name=recipe_name,
+            validate_config=lambda path, recipe: validate_exp_config(
+                path, recipe, repo_root=repo_root
+            ),
+        )
+    except RecipeLockError as exc:
+        shutil.rmtree(dest, ignore_errors=True)
+        raise NewExperimentError(
+            f"fork 后无法升级到当前 recipe：{exc}。"
+            f"先对来源执行 `sf recipe upgrade {src_dir.name}`"
+        ) from exc
+
+    print(f"已 fork 实验: {dest}（来源: {src}）")
+    print(f"  · config.yaml 的 swanlab project/name 与 README 标题已改为: {name}")
+    print(f"下一步: 改 {dest}/config.yaml 顶部【① 调参区】试你的超参，"
+          f"然后 sf submit {name} --profile <目标集群>")
+
+
+def _create_from_template(
+    repo_root: Path,
+    kind: str,
+    name: str,
+    method: str,
+    framework_version: str = "",
+) -> None:
+    dest = repo_root / kind / name
+    if dest.exists():
+        raise NewExperimentError(f"已存在: {dest}")
+
+    from starforge_core.contract import SpecError
+    from starforge_core.recipes import get_recipe
+
+    try:
+        recipe = get_recipe(method)
+        selected_framework_version = framework_version.strip() or recipe.runtime.default_version
+        recipe.runtime.resolve(selected_framework_version)
+    except SpecError as exc:
+        # get_recipe 的报错已列出可用值，并对无前缀裸名给出两段式提示。
+        raise NewExperimentError(f"--method 非法: {exc}") from exc
+    # 实验模板随 CLI 包分发（starforge_cli/scaffold/），不依赖项目内容。
+    from starforge_cli.project import experiment_template
+
+    template = experiment_template()
+    if not template.is_dir():
+        raise NewExperimentError(f"缺少模板目录: {template}")
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix=f".{name}.staging-", dir=dest.parent))
+    try:
+        shutil.copytree(template, staging, dirs_exist_ok=True)
+        _copy_recipe_template(staging, recipe)
+        gitkeep = staging / ".gitkeep"
+        if gitkeep.is_file():
+            gitkeep.unlink()
+        # recipe 声明只存在于 recipe.lock.json（infer_recipe 从锁读），不再写 method 标注文件；
+        # 硬件 profile 在提交时用 --profile 指定（env/overrides/拓扑均由服务端注册表下发）。
+        from starforge_cli.recipe_lock import write_recipe_lock
+
+        write_recipe_lock(staging, recipe.id, selected_framework_version)
+        _validate_recipe_template(staging, recipe)
+        staging.replace(dest)
+    except Exception:
+        shutil.rmtree(staging, ignore_errors=True)
+        raise
+
+    print(
+        f"已创建实验: {dest}（method={recipe.id}, "
+        f"framework={recipe.framework}@{selected_framework_version}）"
+    )
+    print("下一步:")
+    print(f"  1. 编辑 {dest}/README.md（目标 / 模型 / 数据 / 监控）")
+    print(f"  2. 按 {recipe.id} recipe 编辑模板文件")
+    print(f"  3. 用 sf submit {name} --profile <目标集群>[:总卡数] 提交（如 h200 / h200:4）")
+
+
+def create_experiment(
+    repo_root: Path,
+    kind: str,
+    name: str,
+    *,
+    src: str = "",
+    method: str = "nemo-rl/grpo",
+    framework_version: str = "",
+) -> None:
+    """新建或 fork 实验；失败时抛 NewExperimentError。"""
+    if kind not in ("experiments", "projects"):
+        raise NewExperimentError("第一个参数必须是 experiments 或 projects")
+
+    if src:
+        _fork_experiment(repo_root, kind, name, src)
+    else:
+        _create_from_template(
+            repo_root,
+            kind,
+            name,
+            method,
+            framework_version=framework_version,
+        )

starforge_cli/packing.py

@@ -0,0 +1,179 @@
+"""作业负载打包：清单式文件列表 + tar.gz + git 溯源。
+
+打包是白名单（清单式）而非黑名单：一次提交只上传用户拥有的三类路径——
+实验目录本身、共享代码 common/、配置继承根 configs/。平台 runner 与入口
+由服务端在准入后注入，客户端不能覆盖。
+"""
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import io
+import subprocess
+from pathlib import Path
+
+from starforge_cli import cli_ui
+
+
+def _git_out(args: list[str], cwd: Path) -> str:
+    """git 命令输出；失败直接报错——提交/打包必须在完好的 git 仓库内进行。"""
+    try:
+        return subprocess.run(
+            ["git", "-C", str(cwd), *args], capture_output=True, text=True, check=True
+        ).stdout
+    except FileNotFoundError:
+        cli_ui.fail("找不到 git 命令", hint="安装 git 后重试")
+    except subprocess.CalledProcessError as e:
+        cli_ui.fail(
+            f"git {' '.join(args)} 失败: {e.stderr.strip() or e}",
+            hint="请在 git 仓库目录内运行",
+        )
+
+
+def git_provenance(repo_root: Path, exp_rel: str) -> dict:
+    """提交可追溯：git commit / dirty / config 指纹。git 不可用时直接报错。"""
+    commit = _git_out(["rev-parse", "--short", "HEAD"], repo_root).strip()
+    if not commit:
+        cli_ui.fail("无法确定 git commit", hint="请在有提交历史的 git 仓库内运行")
+    dirty = bool(_git_out(["status", "--porcelain"], repo_root).strip())
+    cfg = repo_root / exp_rel / "config.yaml"
+    if cfg.is_file():
+        config_sha = hashlib.sha256(cfg.read_bytes()).hexdigest()[:12]
+    else:
+        config_sha = "none"
+    return {"git_commit": commit, "git_dirty": dirty, "config_sha": config_sha}
+
+
+# 清单内仍要剔除的非运行时产物（实验目录里偶尔混入的文档/报告）。
+_UPLOAD_EXCLUDE_SUFFIXES = (".pdf",)
+
+
+def _is_upload_excluded(rel: str) -> bool:
+    """该相对路径是否属于「不随作业上传」的非运行时产物。"""
+    return rel.replace("\\", "/").lower().endswith(_UPLOAD_EXCLUDE_SUFFIXES)
+
+
+# 疑似密钥/凭据文件：命中即拒绝打包（fail-closed）。
+# 清单用 `git ls-files --others` 收集未跟踪文件，.gitignore 覆盖不到的命名
+# （hf_token.txt / credentials.json / *.pem …）会随 --allow-dirty 静默出网。
+# 注意别用过宽的 "token*"：会误伤 tokenizer_config.json 这类训练必需文件。
+_SENSITIVE_EXACT = frozenset({
+    ".env", ".envrc", ".netrc",
+    "credentials.json", "token.txt", "api_key.txt",
+})
+_SENSITIVE_GLOBS = (
+    ".env.*", "*.pem", "*.key", "*.p12", "*.pfx",
+    "id_rsa*", "id_ed25519*", "id_ecdsa*", "id_dsa*",
+    "secrets.*", "*.secret", "hf_token*", "*_credentials.json",
+)
+
+
+def _is_sensitive(rel: str) -> bool:
+    base = rel.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    if base in _SENSITIVE_EXACT:
+        return True
+    return any(fnmatch.fnmatch(base, pat) for pat in _SENSITIVE_GLOBS)
+
+
+# 集群 Linux 侧会 source/读取；Windows 工作区可能是 CRLF，上传前须规范为 LF。
+_UNIX_LF_SUFFIXES = (".sh", ".conf")
+_UNIX_LF_BASENAMES = frozenset({"sf", "lab"})
+
+
+def _needs_unix_lf(rel: str) -> bool:
+    r = rel.replace("\\", "/")
+    base = r.rsplit("/", 1)[-1]
+    return base in _UNIX_LF_BASENAMES or r.endswith(_UNIX_LF_SUFFIXES)
+
+
+def _normalize_unix_lf(data: bytes) -> bytes:
+    return data.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+
+
+def upload_manifest(exp_rel: str, profile: str) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """作业包白名单：(目录前缀, 精确文件)。
+
+    集群侧运行时的全部依赖：
+      experiments/<exp>/   实验本体（config / recipe.lock / run.py …）
+      common/              实验 run.py 通过 REPO_ROOT sys.path 引用的共享代码
+      configs/             实验 config.yaml 用 ../../configs/ 相对路径继承的基底
+    profile 的 env/overrides 已服务端化（Console 硬件注册表经环境变量注入），
+    不再随包上传 cluster/ 目录；profile 参数保留用于入参完整性校验。
+    """
+    if not exp_rel or not profile:
+        raise ValueError("打包清单需要显式的实验路径与硬件 profile")
+    prefixes = (
+        exp_rel.rstrip("/") + "/",
+        "common/",
+        "configs/",
+    )
+    exact: tuple[str, ...] = ()
+    return prefixes, exact
+
+
+def list_working_files(repo_root: Path, *, exp_rel: str, profile: str,
+                       with_stats: bool = False):
+    """作业负载文件清单：git 跟踪 + 未忽略（遵循 .gitignore），再按白名单收窄。
+
+    with_stats=True 时返回 (files, skipped_count)，skipped 为 git 工作树中
+    不属于本次作业负载而被略过的文件数。
+    """
+    prefixes, exact = upload_manifest(exp_rel, profile)
+    listing = _git_out(["ls-files", "--cached", "--others", "--exclude-standard"], repo_root)
+    raw = [f.strip() for f in listing.splitlines() if f.strip()]
+    files = [
+        f for f in raw
+        if (f.startswith(prefixes) or f in exact) and not _is_upload_excluded(f)
+    ]
+    if sensitive := [f for f in files if _is_sensitive(f)]:
+        cli_ui.fail(
+            "作业包中发现疑似密钥/凭据文件，拒绝打包上传",
+            title="作业包中发现疑似密钥/凭据文件，拒绝打包上传",
+            items=sensitive,
+            hint="移出上传目录或加入 .gitignore；确属训练必需请改名并确认其中不含密钥",
+        )
+    if not files:
+        cli_ui.fail(
+            "作业包为空：清单内没有可上传的文件。",
+            hint=f"确认实验目录 {exp_rel}/ 存在且已入 git",
+        )
+    # 未跟踪文件只会在 --allow-dirty 时走到这里（clean-tree 检查把 dirty 拦在前面）。
+    # 它们不受 commit 溯源约束，必须让用户看见都上传了什么。
+    tracked = {f.strip() for f in _git_out(["ls-files"], repo_root).splitlines() if f.strip()}
+    if untracked := [f for f in files if f not in tracked]:
+        cli_ui.emit_warning(
+            f"{len(untracked)} 个未跟踪文件将随作业上传（不受 commit 溯源约束）",
+            body="\n".join(untracked[:20]) + ("\n…" if len(untracked) > 20 else ""),
+        )
+    return (files, len(raw) - len(files)) if with_stats else files
+
+
+def pack_working_dir(repo_root: Path, files: list[str], on_add=None) -> bytes:
+    """把清单文件打成 tar.gz；清单里的文件缺失直接报错，不静默跳过。
+
+    on_add(n)：每加入一个文件回调一次，用于驱动进度条。
+    """
+    import tarfile
+
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        for rel in files:
+            p = repo_root / rel
+            if not p.is_file():
+                cli_ui.fail(
+                    f"打包失败：清单文件不存在或不是普通文件: {rel}",
+                    hint="文件可能已删除但仍在 git 索引里；git add -A 后重试",
+                )
+            arcname = rel.replace("\\", "/")
+            if _needs_unix_lf(rel):
+                data = _normalize_unix_lf(p.read_bytes())
+                info = tarfile.TarInfo(name=arcname)
+                info.size = len(data)
+                info.mtime = int(p.stat().st_mtime)
+                info.mode = p.stat().st_mode
+                tar.addfile(info, io.BytesIO(data))
+            else:
+                tar.add(p, arcname=arcname)
+            if on_add:
+                on_add(1)
+    return buf.getvalue()

starforge_cli/plugins_lock.py

@@ -0,0 +1,73 @@
+"""实验插件锁文件（plugins.lock.json）。
+
+与 recipe.lock.json 同一哲学：实验用哪个插件的哪个精确版本、什么内容摘要，
+在 `sf plugin install --exp` 时固定下来；提交时原样写进 JobSpec，服务端与
+集群侧各自比对 —— 不一致就拒绝，绝不猜。
+
+锁定的是 (id, version, digest) 三元组，不含代码：插件包体由平台在提交时注入
+作业包，客户端不上传、也改不了。
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+LOCK_FILE = "plugins.lock.json"
+LOCK_VERSION = "forge/plugins-lock/v1"
+
+
+def read_plugin_lock(exp_dir: Path) -> list[dict]:
+    """读取实验的插件引用列表；没有锁文件返回空表。"""
+    path = Path(exp_dir) / LOCK_FILE
+    if not path.is_file():
+        return []
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{path} 非法: {exc}") from exc
+    if payload.get("apiVersion") != LOCK_VERSION:
+        raise ValueError(
+            f"{path} 的 apiVersion 不是 {LOCK_VERSION}；"
+            "重新执行 `sf plugin install <id> --exp <exp>` 重建锁文件"
+        )
+    plugins = payload.get("plugins") or []
+    for p in plugins:
+        if not all(str(p.get(k) or "").strip() for k in ("id", "version", "digest")):
+            raise ValueError(f"{path} 存在缺字段的插件引用: {p!r}")
+    return [
+        {"id": p["id"], "version": p["version"], "digest": p["digest"]}
+        for p in plugins
+    ]
+
+
+def upsert_plugin_lock(exp_dir: Path, entry: dict) -> list[dict]:
+    """写入/更新一条插件引用（同 id 覆盖），返回更新后的列表。"""
+    plugins = [p for p in read_plugin_lock(exp_dir) if p["id"] != entry["id"]]
+    plugins.append({"id": entry["id"], "version": entry["version"], "digest": entry["digest"]})
+    plugins.sort(key=lambda p: p["id"])
+    _write(exp_dir, plugins)
+    return plugins
+
+
+def remove_plugin_lock(exp_dir: Path, plugin_id: str) -> bool:
+    """移除一条插件引用；返回是否真的移除了。"""
+    plugins = read_plugin_lock(exp_dir)
+    kept = [p for p in plugins if p["id"] != plugin_id]
+    if len(kept) == len(plugins):
+        return False
+    _write(exp_dir, kept)
+    return True
+
+
+def _write(exp_dir: Path, plugins: list[dict]) -> None:
+    path = Path(exp_dir) / LOCK_FILE
+    if not plugins:
+        path.unlink(missing_ok=True)
+        return
+    path.write_text(
+        json.dumps(
+            {"apiVersion": LOCK_VERSION, "plugins": plugins},
+            ensure_ascii=False, indent=2, sort_keys=True,
+        ) + "\n",
+        encoding="utf-8",
+    )

starforge_cli/project.py

@@ -0,0 +1,130 @@
+"""StarForge 项目脚手架：`sf init` 的实现。
+
+CLI 经 pip 分发（starforge-cli），用户不 clone 工具仓库；`sf init` 生成
+自包含的项目目录（自己的 git 仓库），布局与作业包白名单严格对应：
+
+    my-lab/
+    ├── starforge.yaml     项目标记（项目发现的唯一依据）
+    ├── experiments/       实验目录（sf new 在此创建）
+    ├── configs/           官方基底 + 模型片段（脚手架落地，用户可调可 pin）
+    ├── common/            项目共享代码（数据脚本 / 环境 / 奖励）
+    └── .gitignore
+
+平台 bootstrap/runner 不落地到项目，也不由 CLI 上传；console 在准入后注入
+内容寻址 Job Capsule，用户代码不能覆盖平台入口。
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from importlib.metadata import version as _pkg_version
+from importlib.resources import files
+from pathlib import Path
+
+import yaml
+
+PROJECT_MARKER = "starforge.yaml"
+# 与 console 分组键一致：会进 URL / 路径，只允许安全字符。
+_PROJECT_NAME_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+class ProjectError(RuntimeError):
+    pass
+
+
+def load_project_name(root: Path) -> str:
+    """读 starforge.yaml 的 name。提交到 console 的 project 只来自这里。"""
+    path = root / PROJECT_MARKER
+    if not path.is_file():
+        raise ProjectError(f"{root} 不是 StarForge 项目（缺 {PROJECT_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
+    if not isinstance(data, dict):
+        raise ProjectError(f"{path} 根节点必须是对象")
+    name = str(data.get("name") or "").strip()
+    if not name:
+        raise ProjectError(f"{path} 缺少 name")
+    if name in (".", "..") or not _PROJECT_NAME_RE.match(name):
+        raise ProjectError(f"非法项目名 {name!r}（仅允许字母数字与 . _ -）")
+    return name
+
+
+def scaffold_root() -> Path:
+    """包内脚手架资源根（editable 与 wheel 安装均为真实目录）。"""
+    return Path(str(files("starforge_cli") / "scaffold"))
+
+
+def experiment_template() -> Path:
+    """实验脚手架模板（sf new 用）。"""
+    return scaffold_root() / "experiment-template"
+
+
+class InitError(RuntimeError):
+    pass
+
+
+def init_project(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.exists() and any(dest.iterdir()):
+        # 允许在非空目录初始化（如已有 README 的空仓库），但拒绝覆盖关键路径
+        for clash in ("experiments", "configs", "common", PROJECT_MARKER):
+            if (dest / clash).exists():
+                raise InitError(f"{dest} 下已存在 {clash}，拒绝覆盖；换个目录或清理后重试")
+    dest.mkdir(parents=True, exist_ok=True)
+
+    src = scaffold_root() / "project"
+    shutil.copytree(src / "configs", dest / "configs")
+    shutil.copytree(src / "common", dest / "common")
+    if not (dest / ".gitignore").exists():
+        shutil.copyfile(src / "gitignore", dest / ".gitignore")
+    (dest / "experiments").mkdir(exist_ok=True)
+    keep = dest / "experiments" / ".gitkeep"
+    if not keep.exists():
+        keep.write_text("")
+
+    project_name = (name or dest.name).strip()
+    try:
+        cli_version = _pkg_version("starforge-cli")
+    except Exception:  # noqa: BLE001 — 源码运行（未安装分发元数据）
+        cli_version = "dev"
+    (dest / PROJECT_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',
+        encoding="utf-8",
+    )
+    readme = dest / "README.md"
+    if not readme.exists():
+        readme.write_text(
+            f"# {project_name}\n\n"
+            "StarForge（星锻）微调项目。常用命令：\n\n"
+            "```bash\n"
+            "sf new my-exp --method nemo-rl/grpo   # 新建实验\n"
+            "sf validate my-exp                    # 本地校验\n"
+            "sf submit my-exp --profile h200:8     # 提交训练\n"
+            "sf job logs                           # 跟随日志\n"
+            "```\n\n"
+            "目录说明：`experiments/` 实验本体；`configs/` 官方基底与模型片段；\n"
+            "`common/` 项目共享代码（数据脚本 / Agent 环境 / 奖励函数）。\n",
+            encoding="utf-8",
+        )
+
+    if git and shutil.which("git") and not (dest / ".git").exists():
+        subprocess.run(["git", "init", "-q"], cwd=dest, check=False)
+        # 本地身份：CI / 干净机器没有 user.name 时也能完成首提交（submit 需要 git 溯源）
+        subprocess.run(["git", "config", "user.email", "starforge@localhost"], cwd=dest, check=False)
+        subprocess.run(["git", "config", "user.name", "sf init"], cwd=dest, check=False)
+        subprocess.run(["git", "config", "commit.gpgsign", "false"], cwd=dest, check=False)
+        subprocess.run(["git", "add", "-A"], cwd=dest, check=False)
+        subprocess.run(
+            ["git", "commit", "-q", "-m", "sf init: StarForge project scaffold"],
+            cwd=dest, check=False,
+        )
+    return dest