扩展点

不改平台代码就能加进 StarForge 的所有东西，以及怎么选对那一种。

sf plugin publish ./my-extension

平台有九个扩展点。先回答一个问题，它决定了其余的一切：平台会执行你的代码，还是只读你的声明？

​

全图

你想加的东西	用	平台执行你的代码吗	怎么发布
一种训练方法	recipe pack	否	sf plugin publish
一个评测集	benchmark pack	否	sf plugin publish
给裁判用的判分标准	rubric	否	控制台，或 PUT /api/rubrics
诊断阈值	playbook 包（管理员）	否	sf plugin publish
诊断 / 裁判的提示词	prompt 包（管理员）	否	sf plugin publish
训练循环的运行期补丁	algorithm 插件	在你自己的训练容器里	sf plugin publish
Agent RL 任务集	环境	—	sf env push
驱动模型走完环境的那段代码	environment 插件（harness）	在你自己的训练容器里	sf plugin publish
本地数据预处理步骤	data-prep 插件	在你自己的机器上	sf plugin publish

​

决定这一切形状的那条规则

控制平面永远不装载第三方代码。现在不会，将来加个开关也不会。

控制台进程持有数据库连接、JWT 签名密钥和对象存储凭据。在那里跑插件，等于把整个平台交给发布者。

所以代码类插件只会在已经属于你的地方执行：你的训练容器，或者你自己的笔记本。 要改控制平面的行为，请跨进程边界：通知通道用 webhook，agent 工具用外部 MCP server。

这也是为什么没有 runs_in: console 这一档插件，以及为什么将来也不会有。

​

声明包里不能有代码

平台只读不执行的那类包（recipe、benchmark、playbook、prompt）， 根层出现可执行文件就会在发布期被拒——.py、.sh、.so、.js 以及另外约二十种后缀。

my-grpo-variant/
├── plugin.yaml         # kind: recipe
├── recipe.yaml         # 平台要解析的那份声明
├── README.md
└── template/           # 唯一允许放可执行文件的地方
    ├── config.yaml
    └── run.sh

template/ 是例外，理由值得知道：那是 sf new 拷进你的仓库、由你在你的容器里跑的脚手架， 平台一行都不碰。

这把「平台永不执行声明包」从一句承诺变成了脚本能检查的事实。踩到时的报错：

recipe is a declarative pack -- the platform parses it and never runs it, so it must
contain no executable files: helper.py. Scaffolding meant to be handed to users belongs
under template/; if the platform really has to execute code, use one of the
algorithm/environment/data-prep kinds instead.

​

代码插件要过三道闸

只要代码会被执行，就要过同样的三道内容摘要校验。它们保证「集群上跑的」和「你发布的」是同一份东西。

1. 发布时

   服务端解包重算内容摘要，与客户端声明的比对，不一致就拒绝。

2. 提交时

   校验 JobSpec 里的 (id, version, digest) 三元组与库内记录一致，且插件未被管理员禁用。

3. 启动时

   launcher 对真正注入到作业里的目录再算一次摘要。与 JobSpec 锁定值不同，作业直接拒绝启动—— 宁可不跑，也不产出一个没人能复现的结果。

摘要是对目录内容算的（排序后的相对路径 + 文件字节），不是对 tar 包算的。 tar 的 hash 会把 mtime 和 uid 吃进去，同一份代码打两次包会得到两个 digest，锁定也就没意义了。

__pycache__、.git、.venv、*.pyc 和 .DS_Store 不参与摘要。它们是环境副产物，不是插件内容。

​

代码包还要多过两道检查

发布期的结构校验，让错误在你的笔记本上就暴露，而不是在集群跑了四十分钟之后：

entrypoint 模块必须真实存在

entrypoint: patch:install 要求包里有 patch.py 或 patch/__init__.py。拼错在发布期就被拒：

entrypoint module 'pathc' does not exist in the package (expected pathc.py or
pathc/__init__.py). A misspelled entry point would otherwise fail only when training
starts, so it is refused here.

顶层名不得遮蔽真实依赖

插件根目录会加入 sys.path，所以根层一个叫 torch.py 的文件会让训练进程之后所有的 import torch 都拿到你的文件。症状离病因极远，因此这些名字是保留字，直接拒绝：

starforge  nemo_rl  common  ray  torch  transformers  vllm
trl  verl  numpy  yaml  json  os  sys

​

版本不可变

同一个 1.2.0 发两次会得到 409。修 bug 请发 1.2.1。

这是 digest 锁定成立的前提：版本能被覆盖，锁文件指向的东西就可能已经不存在了。 README.md 也一样在摘要覆盖范围内，所以改长描述同样要换版本号。 「文档说的和代码做的不一致」是插件市场最常见的坑，这是防住它最便宜的办法。

​

命名与命名空间

对象	引用形式	说明
插件	<owner>/<name>	owner 由平台在发布时盖章，不是 manifest 里自己写的
已发布的方法	<framework>/<owner>.<name>	多出来的这一段让「和内置方法撞名」在结构上不可能发生
环境	<owner>/<name>@<version>
Rubric	<owner>/<name>

​

治理

sf plugin disable alice/opsd-patch   # 管理员：新作业不得再引用它
sf plugin enable alice/opsd-patch

三个动词，三个不同的作用域，别混为一谈：

动词	谁	作用域
启用 / 禁用	管理员	整套部署。下架一个东西，保留历史
引用	你	单个实验，写在 plugins.lock.json 里
同步	自动	你的本地方法库。无状态——删了再同步一次即可

禁用只挡新提交。已经在跑和已经排队的作业不受影响。

​

下一步

插件包

manifest、目录结构、发布与安装。

Algorithm 插件

入口函数签名，以及它什么时候被调用。

Recipe 包

不发平台版本就加一种训练方法。

Benchmark 包

声明跑什么、读哪些数。

环境

Agent RL 的任务集，以及四种协议。

Verifier

判定任务是否完成的三种方式。