> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# sf init 生成了什么

> sf init 生成什么、CLI 上传什么、什么永远不离开笔记本

StarForge 的 **lab** 是本机上一个普通 git 仓库。控制台不会去 clone。`sf submit` 打一个文件子集的包，上传后由服务端再注入 Job Capsule。

## `sf init my-lab --yes` 之后

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
my-lab/
├── starforge.yaml      # 仓库标记 + 项目名（sf 找根目录的唯一信号）
├── experiments/        # sf new 在这里建目录
├── configs/            # 官方基底 + 模型片段，你可以改、可以 pin
├── common/             # 共享代码：数据脚本、环境、奖励
├── .gitignore
└── README.md
```

`starforge.yaml` 需要一个 `name`，字符限制 `[A-Za-z0-9._-]`。这就是控制台项目名。提交时不要传 `--project`。

```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
name: my-lab
```

需要项目的命令（`sf new`、`submit`、`ls`、`validate`）从当前目录往上找这个文件。CI 可以设 `SF_REPO_ROOT`，不必 `cd`。`sf login` / `logout` / `status` 是全局的，不依赖项目。

## 一个实验目录

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf new my-grpo --method nemo-rl/grpo
```

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
experiments/my-grpo/
├── config.yaml           # 你的差异；靠 defaults 继承
├── README.md             # 脚手架说明，不执行
└── recipe.lock.json      # 方法 + 框架钉死
```

`custom/custom` 还会有 `train.sh`（唯一入口）。旁边可以再放 `train.py`。`sf plugin install … --exp` 之后会多 `plugins.lock.json`。

不要在实验目录里放一个 `framework` 文件指望平台去读。方法以锁文件为准。

## 什么会被上传

CLI 打包实验、`common/`、`configs/`。排除列表和服务器共用（`starforge.contract.env` 里的 `PACKAGE_EXCLUDES`）：

| 模式                                         | 为什么丢掉                                             |
| ------------------------------------------ | ------------------------------------------------- |
| `.forge/**`                                | 本机凭据。进了包就等于把 token 送到集群。                          |
| `.git/**`                                  | 历史用 provenance 里的 commit SHA 记录，不是整库克隆。           |
| `**/outputs/**`                            | 本机残留产物。集群产物在 `$FORGE_OUT_DIR`。                    |
| `datasets/**/raw/**`、`datasets/**/data/**` | 原始数据体积。用[平台数据集](/zh-Hans/guides/datasets)或 HF id。 |
| `**/__pycache__/**`                        | 字节码。                                              |
| `**/*.key`、`**/secrets.env`                | 密钥放服务端，不进作业包。                                     |

JobSpec 写在包内 `.starforge/jobspec.json`。注意是 `.starforge/`，不是 `.forge/`。`.forge` 会被排除，写进去集群侧读不到。

## 仓库里不会有的东西

* 集群 kubeconfig、Slurm JWT、对象存储密钥
* Job Capsule（`runner.pex`）。准入后由服务端注入。
* 硬件并行度。来自 `--profile` 和注册表。

## Git

提交会记录 `NRL_GIT_COMMIT` 和 `NRL_GIT_DIRTY`。工作区不干净默认拒绝，除非 `--allow-dirty`。未跟踪文件两种情况下都会当警告列出来。`sf init` 默认就初始化 git，第一次提交不要拖到交作业那一刻。

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
git add -A && git commit -m "first grpo config"
sf submit my-grpo --profile h200:8
```