插件包

tp plugin publish ./my-plugin

插件包包含严格校验的 plugin.yaml，以及实现或声明文件。Python 提供方可以使用标准 wheel 和按能力划分的 PyPA entry points。平台保存不可变制品，不会在运行中的作业里安装依赖。

目录结构

my-plugin/
├── plugin.yaml       # manifest，必需
├── README.md         # 长描述，可选，展示在详情页
└── <你的文件>         # 代码类插件放代码，声明类插件放声明

plugin.yaml

schema: tuneplane/plugin/v1
name: opsd-patch
version: 1.2.0
capability: algorithm
entrypoint: patch:install
load: eager
summary: OPSD teacher-sampling correction

requires:
  core: ">=0.3,<1"

# 货架元数据 —— 只影响展示与检索，不影响装载与安全
icon: 🧩
author: Alice
license: Apache-2.0
homepage: https://github.com/alice/opsd-patch
keywords: [opsd, distillation]

必填字段

string

必填

永远是 tuneplane/plugin/v1。写别的会被拒，并告诉你这个版本支持哪个 schema。

string

必填

叶子名。平台在发布时把你的账号盖上去，所以对外 id 是 <owner>/<name>——owner 不用你自己写。

string

必填

首字符是字母或数字，之后允许字母、数字、.、_、-。一旦发布就不可变。

string

必填

你唯一需要声明的分类：包实现的能力协议，取值为 algorithm、environment、data-prep、 framework-integration、recipe、benchmark、playbook 或 prompt。代码在哪里运行、属于货架上哪一组，都由它推出。管理配置仅管理员可发布，控制面不加载插件代码。

local | job

只用于 data-prep——唯一有两个执行位置的能力：你自己的机器（local）或作业内（job）。其他能力的执行位置只有一个，写了这个字段会被拒。

schema 为其他值的清单一律拒绝。包类型（runtime、asset 或 policy）由能力推出，不在清单中声明。

代码类插件必填

module.path:callable

源码目录形式的 algorithm、environment，以及 execution: job 的 data-prep 必填；wheel 形式改用 wheel 与 provider。源码模块路径相对于包根目录，且发布时必须真实存在。其他能力及执行位置一律不接受。execution: local 的 data-prep 插件按 prepare_*.py 约定发现；声明包什么都不执行，因此根本没有入口。

eager | deferred

默认值:"eager"

训练入口进程何时调用或登记你的算法入口。见 algorithm 插件。

可选字段

PEP 440 specifier

你的插件适用于哪些 tuneplane 版本，例如 ">=0.3,<1"。启动时校验；不满足会以 plugin x@1.2.0 requires SDK >=0.3,<1, this one is 0.2.9 停下，而不是在更靠后、更古怪的地方失败。

string

一句话，列表里展示。

string

预设图标名称、emoji（最多 8 个字符）或包内相对 PNG 路径。 PNG 不超过 64 KiB，宽高均不超过 512 像素。留空则按能力取默认图标。

string

谁写的。与 owner 不同——后者是发布它的平台账号。

string, url, string[]

只用于展示与检索。homepage 必须是 http(s)。keywords 最多 12 个，会小写并去重。

README.md

包根的 README.md 会成为详情页的长描述。上限 64 KB，超出部分截断——详情页要的是介绍，不是手册。它有意不做成 manifest 字段：长文本塞进 YAML 会逼作者转义，也失去 Markdown 工具链。它在包摘要的覆盖范围内，所以改它同样要换版本号。

能力

你只声明能力；执行位置与货架分组都由它推出。data-prep 是唯一有两个执行位置的能力，所以只有它的清单还要写 execution。

能力 capability	执行位置 execution	货架分组	实现形式	谁能发布
`algorithm`	`job`	运行扩展	源码入口或 wheel 提供方	任何人
`environment`	`job`	运行扩展	源码入口或 wheel 提供方	任何人
`data-prep`	`local`（需声明）	运行扩展	`prepare_*.py` 约定	任何人
`data-prep`	`job`（需声明）	运行扩展	源码入口或 wheel 提供方	任何人
`framework-integration`	`job`	运行扩展	`integration.json` 配置与隔离编译器	任何人
`recipe`	`none`	模板与评测	配方声明与模板	任何人
`benchmark`	`none`	模板与评测	评测声明	任何人
`playbook`	`none`	管理配置	部署配置	仅管理员
`prompt`	`none`	管理配置	部署配置	仅管理员

内置框架集成随 SDK 一起发布，版本跟随 SDK。新增框架通过现有编译器契约发布集成包与配方，无需新增能力或修改核心的框架分支。新的协议行为需要契约版本变更，任意执行位置不会被接受。工程方案不以插件形式发布。

playbook 和 prompt 是部署级单例：只有一份生效，而且会改变所有人在诊断页上看到的东西。它们只允许管理员发布，因为后果落在别人头上。也没有按用户区分的版本—— 「这是谁的诊断结论」是一个不该存在的问题。

发布

tp plugin publish ./my-plugin
tp plugin publish ./my-plugin --owner platform-team   # 仅管理员

客户端先在本地校验 manifest 和目录结构、算出目录摘要，然后上传。服务端重算摘要，不一致就拒绝。

失败	含义
`409`	这个版本已存在。版本不可变——请升号
`400`	manifest 或结构有问题；`detail` 会点名字段
`403`	往不属于你的命名空间发布

安装与引用

tp plugin ls                                      # 这套部署有哪些插件
tp plugin info alice/opsd-patch                   # manifest、版本历史、digest
tp plugin install alice/opsd-patch                # 下载到本地 ./tuneplane_plugins/
tp plugin install alice/opsd-patch --exp my-grpo  # 并锁进某个实验

--exp 会往实验里写 plugins.lock.json：引用加它的 digest。提交时平台读这个锁文件，把正好那个版本注入作业包的 tuneplane_plugins/<name>/，并把三元组记进 JobSpec。

plugins.lock.json

{
  "plugins": [
    { "id": "alice/opsd-patch", "version": "1.2.0", "digest": "sha256:9f2c…" }
  ]
}

两个会解包到同名叶子目录的插件不能在同一个作业里组合使用。改名其中一个。

确认成功

tp plugin info alice/opsd-patch

会显示你刚发布的版本和它的 digest。提交引用了它的作业之后，作业日志里每个装载的插件有一行：

plugin  : alice/opsd-patch@1.2.0 applied in entrypoint process

如果注入之后内容被改动过，作业会拒绝启动：

plugin alice/opsd-patch@1.2.0 content digest mismatch: spec=sha256:9f2c…, actual=sha256:41ab…

下一步

Algorithm 插件讲你的入口函数收到什么 · Recipe 包 · Benchmark 包

标准 Python 提供方

Python 提供方使用三个独立入口组：算法为 tuneplane.algorithms，环境为 tuneplane.environments，数据转换为 tuneplane.transforms。在 pyproject.toml 注册 callable 后，用通常的 Python 构建工具生成 wheel。plugin.yaml 使用 wheel、provider 和 api: "1"，替代源码目录的 entrypoint。

[project.entry-points."tuneplane.transforms"]
clean = "my_company_cleaner:transform"

目前支持无需安装时文件重定位的纯 Python wheel。原生库和依赖须预先放入作业镜像；实际作业进程检查 wheel 的 Requires-Python 和 Requires-Dist。发现范围仅限作业选中的制品，不会自动加载环境中全部已安装插件。

schema: tuneplane/plugin/v1
name: cleaner
version: 1.0.0
capability: data-prep
execution: job
api: "1"
wheel: my_company_cleaner-1.0.0-py3-none-any.whl
provider: clean
requires:
  core: ">=0.3.56,<1"
  python: ">=3.12"
  frameworks: {custom: ""}
  methods: [custom/custom]

requires.frameworks 声明框架名与版本范围，空范围表示只限制框架名；methods 是方法 ID 列表；backends 是执行后端列表。未知字段直接报错。未声明的条件不额外限制，但也不会绕过能力本身支持的执行路径和平台资源限制。框架、方法、后端在提交时检查；Python 和实际安装的依赖在作业内检查。

tp plugin validate ./cleaner
tp plugin publish ./cleaner
tp plugin install alice/cleaner@1.0.0 --exp <experiment>

本地制品保存在 tuneplane_plugins/<owner>/<name>/，下载校验成功后才替换原安装。作业使用插件必须通过 --exp 写入实验锁文件。当前同一作业仍拒绝同名叶节点，以及重叠的 Python 导入命名空间。

两个可运行的内置实例

插件页面包含 tuneplane/jsonl-filter 和 tuneplane/text-records，有独立图标、适用条件、版本管理和 README。它们是真实插件包；管理员可以禁用，重启不会重新启用。

JSONL 筛选：结构校验、长度筛选、基于磁盘的精确去重，保留原记录，输出各类剔除数量。错误记录默认使作业失败，可以显式选择跳过。它不做语义质量判断或个人信息识别。
文本转记录：将 UTF-8 文本和 Markdown 按字符分块，支持重叠，保留稳定 ID、来源路径、文档摘要和位置。它不生成 SFT 指令，也不解析 PDF。

两者要求 Python >= 3.12、SDK >= 0.3.56、custom 框架和 custom/custom 方法，不需要 GPU 或训练库。单机纯 CPU 作业支持 Local、Node、Kubernetes 和 Slurm Fleet。声明一个资源池，设置 nodes: 1、gpus_per_node: 0、正数 cpus 和 memory_gb，不填写 GPU 系列。Local/Node 需要 Docker 或 Podman 并配置主机可分配额度；Kubernetes 使用原生 Pod 和对象存储分发 Capsule；Slurm 使用已注册的 SIF/SQSH 运行时与共享存储，无需 Ray。产出数据用于下游训练时，仍须符合训练框架和方法的数据格式。转换接口是 TransformRequest → TransformResult，定义位于 tuneplane.contract.transforms。输入为命名路径与 JSON 配置，输出目录由运行器提供。返回值必须列出全部产出文件；符号链接和越界路径会被拒绝。

{"api":"tuneplane/transform/v1","inputs":{"documents":"input.jsonl"},"config":{"min_length":20}}

锁定插件后，在 custom 作业脚本中执行：

python -m tuneplane.transforms --plugin tuneplane/jsonl-filter \
  --request request.json --output "$TUNEPLANE_OUT_DIR/dataset" \
  --report "$TUNEPLANE_OUT_DIR/transform-result.json" --timeout 600

输出目录必须尚不存在。运行器使用独立进程、超时和取消清理，成功且校验通过后才发布完整目录；报告记录确切提供方版本和摘要。进程隔离是生命周期边界，安全执行边界仍由作业容器提供。使用已有的 output_dataset 配置发布数据集。

发布与部署激活分开

发布 playbook 或 prompt 仅保存可用版本。管理员须显式激活具体版本：

tp plugin activate alice/team-rules@1.2.0
tp plugin activate alice/team-rules@1.1.0
tp plugin deactivate playbook

绑定记录 ID、版本、摘要与 generation，并拒绝过期 generation 的并发更新。停用正在应用的插件或版本前，必须先恢复平台默认配置或明确应用其他版本；停用不会悄悄切换部署策略。多个服务实例最终一致；应用失败会保留本进程上次成功的状态并重试，响应说明处理请求的实例是否已应用，不表示全部实例同时完成。

插件图标

在 plugin.yaml 中将 icon 设置为预设名称（filter 或 files）、emoji，或相对 PNG 路径（例如 icons/logo.png）。图片必须包含在发布的插件包中，不超过 64 KiB，宽高均不超过 512 像素。不接受外部 URL 或包外路径。控制台从注册元数据读取图标；图片加载失败时回退到类型图标。

在控制台管理插件

插件页面展示本平台注册的包。卡片上的开关控制整个插件；发布新版本会保留这一设置。“版本”页签单独控制每个版本，并设置新安装使用的推荐版本，不会改动已有实验的版本锁定。没有推荐版本时，不指定版本的解析仍会使用最近发布的已启用版本；需要可复现时请指定版本。上传根目录包含 plugin.yaml 的 tar.gz 包，最大 32 MiB。预览会校验包并展示标识、兼容要求和摘要，不会执行插件代码。确认添加会携带短期有效的预览凭证再次发送相同文件，服务端重新核验。浏览器导入的版本默认停用，使用前需要启用插件及对应版本。原有 CLI 发布流程仍可使用。 “使用与记录”按插件能力提供操作说明，支持策略插件的应用与恢复默认，并展示已记录的作业引用。非管理员仅能看到自己的作业，未提交的本地实验不计入统计。策略应用结果只说明响应请求的服务进程，不代表全部副本已完成应用。

选择版本前检查内容

打开插件的文件与差异页签，可以检查当前精确版本，包括已禁用的版本。这里展示已记录的添加方式和添加者、存储压缩包的 SHA-256，以及解包内容摘要。旧包没有来源记录时显示“未记录”；摘要不能证明发布者可信。支持搜索包内路径，预览不超过 128 KiB、4,000 行的 UTF-8 文本。二进制文件仅显示大小和 SHA-256，不执行内容，也不展开嵌套压缩包。返回检查结果前，服务端会重新核对包的内容摘要。无效压缩包或摘要不一致会明确报错，不会显示成空文件列表。选择比较版本并指定基准版本，即可查看从基准到当前选中版本的新增、删除和修改文件。文本差异最多展示 2,000 行、256 KiB，超出时明确提示截断。比较不会添加、启用、推荐或应用版本。可以先上传一个新的不可变版本，检查内容后，再明确启用或设为推荐。

开始

核心概念

训练模型

评测与服务

Agent 环境

扩展平台

协作

集成

参考

帮助

目录结构

plugin.yaml

必填字段

代码类插件必填

可选字段

README.md

能力

发布

安装与引用

确认成功

下一步

标准 Python 提供方

两个可运行的内置实例

发布与部署激活分开

插件图标

在控制台管理插件

选择版本前检查内容

​目录结构

​plugin.yaml

​必填字段

​代码类插件必填

​可选字段

​README.md

​能力

​发布

​安装与引用

​确认成功

​下一步

​标准 Python 提供方

​两个可运行的内置实例

​发布与部署激活分开

​插件图标

​在控制台管理插件

​选择版本前检查内容

目录结构

plugin.yaml

必填字段

代码类插件必填

可选字段

README.md

能力

发布

安装与引用

确认成功

下一步

标准 Python 提供方

两个可运行的内置实例

发布与部署激活分开

插件图标

在控制台管理插件

选择版本前检查内容