Эта страница написана так, чтобы хватало её одной, в том числе ИИ-агенту, которому дали только эту ссылку (сырая версия Markdown заканчивается на index.md). Здесь два вида плагинов, выбери один:
| Плагин-виджет (HTML) | Автономный плагин (WebAssembly) | |
|---|---|---|
| Что это | папка с plugin.json и веб-страницей | один файл .wasm, работает внутри программы |
| Язык | HTML, JS, CSS (любой веб-стек) | Go (есть SDK); Rust и другие через ABI |
| Где работает | в изолированном iframe оверлея | на сервере, без окна |
| Подходит для | того, что рисуется на стриме: чат, счётчики, алерты | логики, которая должна работать всегда: награды Twitch, очереди, таймеры, HTTP-запросы, сообщения бота, события |
| Свой интерфейс | он и есть интерфейс | да: виджеты и страница настроек упаковываются в тот же файл |
Их можно сочетать: автономный плагин может нести свои виджеты, а виджет общается со своим плагином через oc.plugin.
Часть 1. Плагин-виджет (HTML)
Папка
plugins/
my-widget/
plugin.json
index.html
app.js
Папка плагинов открывается из Add Source → Open plugins folder. Виджет раздаётся по адресу /plugins/<id>/.
plugin.json
{
"id": "my-widget",
"name": "My widget",
"version": "1.0.0",
"description": "What the widget does",
"entry": "index.html",
"defaultSize": { "width": 480, "height": 200 },
"permissions": ["chat.read", "storage"],
"settings": [
{ "key": "channel", "label": "Channel", "type": "string", "default": "" },
{ "key": "size", "label": "Font size", "type": "number", "default": 32, "min": 8, "max": 200 },
{ "key": "color", "label": "Color", "type": "color", "default": "#ffffff" },
{ "key": "mode", "label": "Mode", "type": "select", "default": "a",
"options": [ { "value": "a", "label": "Mode A" }, { "value": "b", "label": "Mode B" } ] }
]
}
id:a-z A-Z 0-9 _ -, до 64 символов, равен имени папки.version: semver, поднимай при каждом изменении (обновления предлагаются по версии).entry: страница, которая открывается по/plugins/<id>/(по умолчаниюindex.html).- Типы настроек:
string,text,number,range,bool,color(#rrggbb),font,select(нужныoptions).min,max,stepдляnumberиrange;group— заголовок секции;help— подпись. - Редактор сохраняет только изменённые пользователем значения, поэтому значения по умолчанию должен знать и сам виджет. Держи их равными значениям из манифеста.
- Настройки приходят виджету query-параметрами его адреса:
?size=32&color=%23ffffff. Число —32, bool —trueилиfalse.
index.html
<!doctype html>
<meta charset="utf-8">
<style>body { margin: 0; background: transparent; color: #fff; font: 32px sans-serif; }</style>
<div id="out"></div>
<script src="/plugin-sdk/oc.js"></script>
<script>
const size = oc.param("size", 32); // reads the query, cast to the type of the default
document.body.style.fontSize = size + "px";
oc.chat.on("message", (m) => {
document.getElementById("out").textContent = m.displayName + ": " + m.text;
});
oc.chat.subscribe(); // chat of the streamer's channel
</script>
Фон страницы должен быть прозрачным: она рисуется поверх стрима. oc.js создаёт глобальный oc. Полное описание типов — один файл oc.d.ts, его отдаёт запущенная программа по /plugin-sdk/oc.d.ts (и он лежит в репозитории как web/sdk/oc.d.ts); отдай его редактору или агенту.
API oc
| Вызов | Разрешение | Что делает |
|---|---|---|
oc.ready | нет | промис со сведениями {pluginId, sourceId, settings, permissions, preview} |
oc.param(key, default) | нет | настройка из query, приведённая к типу default |
oc.chat.subscribe({channel?}) | chat.read | начать читать чат; события через oc.chat.on("message" | "delete" | "clear" | "status", fn) |
oc.chat.say(text, {channel?, as?, replyTo?}) | chat.send | написать от имени бота (as: "bot", по умолчанию) или стримера |
oc.storage.get/set/delete/list(prefix) | storage | JSON-значения плагина на этом компьютере |
oc.storage.update(key, fn) | storage | безопасное «прочитал → изменил → записал» |
oc.storage.onChange(fn) | storage | другая копия виджета изменила данные |
oc.net.localGet(target, path) | net.local | GET к программе на этом компьютере (нужно правило netLocal в манифесте) |
oc.lifecycle.onStop(fn) | нет | до 3 секунд на сохранение данных при выходе из программы |
Заметки: ключ хранилища — до 128 символов A–Z a–z 0–9 _ . : / -, значение — любой JSON до 256 КБ, квота — 5000 ключей и 8 МБ. В предпросмотре редактора say отключён (ответы дублировались бы). Отправка ограничена примерно 18 сообщениями за 30 с на бота.
oc.chat.on("message", async (m) => {
if (m.text.startsWith("!task ")) {
await oc.storage.update("tasks", (list = []) => [...list, m.text.slice(6)]);
}
});
oc.storage.onChange((c) => { if (c.key === "tasks") render(c.value || []); });
Песочница
Виджет работает в iframe с sandbox="allow-scripts allow-forms allow-popups allow-modals" и без allow-same-origin. У него «непрозрачный» origin: нет localStorage, cookie и доступа к API программы. fetch и WebSocket к внешним адресам работают (другая сторона должна разрешать CORS). Собственные файлы плагина (/plugins/<id>/…) отдаются с CORS *.
Публикация
Положи плагин в репозиторий GitHub как plugins/<id>/ (с plugin.json и файлом входа) и поделись адресом репозитория: пользователи добавляют его в Add Source → Plugin store…. Примеры — compico/oc-plugins (osu-np, fps-meter). Файл changelog.json рядом с plugin.json показывается пользователям после обновления: [{ "version": "1.2.0", "date": "2026-10-27", "changes": ["что нового"], "migration": "что сделать после обновления" }].
Часть 2. Автономный плагин на Go
Автономный плагин пассивен: он объявляет маршруты и обработчики, а вызывает их хост. Сам он ничего не слушает и в фоне не работает. Долгоживущими ресурсами (таймерами, сетевыми запросами, соединением с Twitch) владеет хост.
Подготовка
Нужен Go 1.24 или новее (//go:wasmexport). У SDK нет зависимостей.
mkdir hello && cd hello
go mod init example.com/hello
go get github.com/compico/overlaycomposer/pkg/ocplugin
main.go:
package main
import "github.com/compico/overlaycomposer/pkg/ocplugin"
func init() {
p := ocplugin.New(ocplugin.Meta{
ID: "hello", // a-z 0-9 -, up to 64 characters; also the URL segment
Name: "Hello",
Version: "0.1.0", // semver
Permissions: []string{ocplugin.PermStorage},
})
p.GET("/greet", func(c *ocplugin.Ctx) error {
n, _, _ := ocplugin.Load[int]("count")
_ = ocplugin.Store("count", n+1)
return c.JSON(200, map[string]any{"hello": c.Query("name"), "count": n + 1})
})
}
func main() {} // required to build a reactor; stays empty
Сборка:
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o hello.wasm .
Установка: скопируй hello.wasm в папку плагинов (🧩 Plugins → Open folder), нажми Rescan, затем выдай запрошенные разрешения (🧩 Plugins, карточка плагина). Проверка: http://127.0.0.1:8000/plugins/hello/api/greet?name=oc вернёт {"count":1,"hello":"oc"}.
Правила, без которых не заработает:
Newвызывается один раз, изinit(); в одном.wasmодин плагин. Пути маршрутов начинаются с/.- id плагина не должен совпадать с id HTML-плагина.
- Плагин на Go весит около 3 МБ (рантайм Go); это нормально.
Что нужно учитывать в устройстве плагина
- Вызовы идут по одному, на вызов не больше 10 с. Паника, trap или таймаут пересоздают экземпляр; 5 сбоев за минуту переводят плагин в
failedдо ручного перезапуска. - Состояние храни в хранилище хоста (
Store/Load), а не в переменных: экземпляр пересоздаётся после сбоя, после смены разрешений и после смены настроек. OnInitвыполняется много раз. Пока пользователь не выдал разрешение, операции хоста возвращаютpermission denied. ВOnInitэто обычное состояние: не возвращай ошибку (ошибка изOnInitпереводит плагин вfailed).- Обработчик маршрута отвечает сразу. Долгая работа идёт через операции хоста, результат которых приходит позже событием (
Fetch→OnHTTPResponse,SetTimer→OnTimer). - В
wasip1нет потоков: горутины работают только внутри вызова хоста. time.Now()иcrypto/randработают как обычно (время в UTC).- Лог:
ocplugin.Info/Warn/Error/Debug(msg, "ключ", значение, …), а также stdout/stderr, попадают в лог программы какplugin=<id>.
Маршруты и запросы
p.POST("/add", func(c *ocplugin.Ctx) error {
var in struct{ Text string `json:"text"` }
if err := c.Bind(&in); err != nil {
return c.Error(400, "bad json")
}
if in.Text == "" {
return c.Error(422, "text is empty")
}
return c.JSON(201, map[string]any{"ok": true})
})
p.GET/POST/PUT/PATCH/DELETE(path, handler) становятся /plugins/<id>/api<path>. У Ctx есть Query(key), Bind(&v), JSON(status, v), NoContent(), Error(status, msg) и поля Method, Path. Возвращённая error превращается в голый 500 (подробности только в лог). Паника в обработчике превращается в 500, плагин продолжает работать. Ответ всегда application/json.
Безопасность маршрутов: запрос с чужого origin (в том числе из iframe виджета) программа отклоняет, другим устройствам нужен токен сопряжения, поэтому GET-обработчики не должны иметь побочных эффектов (их может вызвать любая страница). Любой ввод считай недоверенным.
Операции хоста (разрешения)
Разрешения перечисляются в Meta.Permissions, выдаёт их пользователь.
| Разрешение | SDK | Что делает |
|---|---|---|
storage (PermStorage) | Load[T](key), Store(key, v), Remove(key) | JSON-значения в базе программы (личные для плагина) |
timer (PermTimer) | SetTimer(id, d, repeat), ClearTimer(id), p.OnTimer(id, f) | от 50 мс до 24 ч, до 16 таймеров, тот же id заменяет |
net.http (PermNetHTTP) | Fetch(id, FetchRequest{Method, URL, Body}), p.OnHTTPResponse(id, f) | только http(s); тело запроса до 256 КБ, ответ до 1 МБ, 15 с, 8 одновременно, до 3 редиректов; адреса loopback, частных сетей, link-local и CGNAT запрещены |
twitch.redemption (PermRedeem) | p.OnRedemption(f), FulfillRedemption(rewardID, id), CancelRedemption(rewardID, id) | награды за баллы канала; отмена возвращает баллы |
events.publish (PermPublish) | Publish(topic, v), PublishRetained(topic, v) | события для виджетов, аддонов и Deck |
chat.send (PermChat) | Say(text) | сообщение в канале стримера от имени бота: до 300 символов, всплеск 3, затем одно в 3 с; канал и аккаунт выбирает хост |
Неудавшаяся операция возвращает error (например, permission denied).
Таймер
p.OnInit(func() error {
_ = ocplugin.SetTimer("tick", 30*time.Second, true) // denied before the grant: that is fine
return nil
})
p.OnTimer("tick", func() { ocplugin.Info("tick") })
HTTP-запрос
_ = ocplugin.Fetch("rates", ocplugin.FetchRequest{URL: "https://example.com/api/rates"})
p.OnHTTPResponse("rates", func(r ocplugin.HTTPResponse) {
if r.Error != "" || r.Status != 200 {
return
}
_ = ocplugin.Store("rates", r.Body) // r.Body is a string
})
Награда Twitch
p := ocplugin.New(ocplugin.Meta{
ID: "orders", Name: "Orders", Version: "0.1.0",
Permissions: []string{ocplugin.PermStorage, ocplugin.PermRedeem, ocplugin.PermChat},
ConfigSchema: map[string]any{
"rewardId": map[string]any{"type": "string", "format": "twitch.reward", "title": "Reward"},
},
})
p.OnRedemption(func(r ocplugin.Redemption) {
// r.Input is text typed by the viewer: untrusted
var cfg struct{ RewardID string `json:"rewardId"` }
_ = p.Config(&cfg)
if r.RewardID != cfg.RewardID {
return
}
// ... validate r.Input, save the order with Store ...
_ = ocplugin.FulfillRedemption(r.RewardID, r.ID) // or CancelRedemption: the points are returned
_ = ocplugin.Say("@" + r.UserName + " accepted")
})
У Redemption есть поля ID, RewardID, RewardTitle, UserID, UserLogin, UserName, Input, Status, RedeemedAt. Награда должна быть создана самой программой (в настройках плагина: New reward…), иначе Twitch не даст менять её статус. Программа сама подписывается на EventSub Twitch, пока у включённого плагина есть разрешение twitch.redemption; повторные доставки одного погашения отбрасываются по id.
Настройки (configSchema)
Meta.ConfigSchema описывает форму, которую показывает программа: поля типа string, integer/number, boolean с title и description. "format": "twitch.reward" даёт выбор награды. Значения читай через p.Config(&struct{...}) (доступно с OnInit); сохранение настроек перезапускает плагин.
Публикация событий
Объяви топики в Meta.Events и добавь разрешение events.publish:
Events: []ocplugin.EventDecl{{ID: "now", Name: "Now playing"}, {ID: "commands"}},
ocplugin.Publish("commands", v) публикует событие; PublishRetained("now", v) ещё и хранит последнее значение, чтобы новый подписчик получил его сразу (для состояния, не для команд). Топик: a-z0-9._-, до 64 символов, до 32 на плагин; данные — JSON до 64 КБ; в среднем около 20 событий/с на плагин.
Подписчики:
- виджет или страница настроек того же плагина:
oc.plugin.subscribe("now", (data, meta) => …), гдеmeta—{topic, seq, retained}; - внешняя программа: WebSocket
ws://127.0.0.1:8000/plugins/<id>/ws. Кадры — текстовый JSON: отправь{"t":"sub","topic":"now"}, получай{"t":"event","topic":"now","data":…,"seq":7,"retained":true}; время от времени шли{"t":"ping"}и переподключайся при потере связи (послеsubretained-значение приходит снова). Допустимые origin: пустой, тот же хост,music-application://desktop.
Интерфейс внутри .wasm: виджеты и страница настроек
Положи HTML, JS, CSS, картинки и шрифты в папку (например, ui/), объяви их в Meta и упакуй папку в тот же .wasm утилитой ocpack:
Widgets: []ocplugin.Widget{{ID: "queue", Name: "Queue", Entry: "queue.html", Width: 360, Height: 240}},
Settings: "settings.html", // a page shown under 🧩 Plugins → Settings
# in a clone of github.com/compico/overlaycomposer
go run ./cmd/ocpack pack hello.wasm ./ui # appends the oc.assets section; running again replaces it
go run ./cmd/ocpack list hello.wasm
В GitHub Actions используй uses: compico/overlaycomposer/actions/ocpack@<тег-или-коммит> с входами wasm: и ui:. Правила: относительные пути с / и символами A–Z a–z 0–9 . _ ~ @ -, без .., без скрытых файлов; расширения только html htm js mjs css json txt png jpg jpeg gif webp svg ico woff woff2 mp3 ogg wav; до 256 файлов, до 2 МБ на файл, 8 МБ всего. Если файла из Entry или Settings нет, плагин не загрузится.
Страницы раздаются по /plugins/<id>/ui/<путь> (относительные ссылки вроде app.js работают). Виджеты появляются в Add Source → Widgets с пометкой standalone. В странице подключи SDK и вызывай свой плагин:
<script src="/plugin-sdk/oc.js"></script>
<script>
oc.plugin.get("/queue").then(({ body }) => render(body)); // GET /plugins/<id>/api/queue
oc.plugin.post("/started", { id: "abc" });
oc.plugin.subscribe("now", (data) => show(data));
</script>
oc.plugin.call/get/post идут через страницу оверлея, а не через fetch из песочницы; они достают только маршруты, объявленные этим плагином (до 8 одновременных вызовов, 15 с). Предпросмотр редактора тоже вызывает плагин (oc.ready даёт info.preview === true): не отправляй из предпросмотра действия, меняющие состояние. На странице настроек доступны также oc.storage.* (с разрешением storage) и те же oc.plugin.*.
Каждая страница плагина отдаётся с Content-Security-Policy: sandbox allow-scripts; к API программы она обратиться не может.
Тесты
Слой SDK собирается только под wasip1, но обработчики — обычные функции. Подмени хост в обычном go test:
func TestGreet(t *testing.T) {
store := map[string]json.RawMessage{}
ocplugin.SetHost(func(op string, arg []byte) []byte {
switch op {
case "storage.get":
var a struct{ Key string }
_ = json.Unmarshal(arg, &a)
if v, ok := store[a.Key]; ok {
return []byte(`{"found":true,"value":` + string(v) + `}`)
}
return []byte(`{"found":false}`)
case "storage.set":
var a struct {
Key string
Value json.RawMessage
}
_ = json.Unmarshal(arg, &a)
store[a.Key] = a.Value
}
return []byte(`{}`)
})
// call your logic (kept in separate functions) and assert
}
Логику (очереди, разбор) держи в функциях, не трогающих SDK, и тестируй их напрямую; wasm/music в oc-plugins — полный пример.
Публикация автономного плагина
В compico/oc-plugins (или в своём репозитории, устроенном так же): плагин лежит в wasm/<id>/ со своим go.mod (имя папки равно id), необязательной ui/ и README.md.
node scripts/wasm.mjs build <id>выполняетgo vet,go test, собираетdist/<id>.wasm(упаковываяui/черезocpack) и печатает метаданные, прочитанные из файла.npm testпроверяет все манифесты.- Поднимай
Versionпри каждом изменении кода. После merge вmainCI создаёт релиз<id>-v<версия>с<id>.wasmи sha256; PR, который меняет код без повышения версии, не проходит проверку. - Пользователи ставят файл из релиза (см. Виджеты и плагины).
Часть 3. Другие языки (ABI)
Файл .wasm для цели wasip1 (reactor) с этими экспортами и одним импортом работает на любом языке. Всё, кроме сигнатур, — JSON, поэтому новые возможности не ломают готовые плагины. i64 — это (ptr << 32) | len буфера в памяти плагина, 0 — пусто.
| Экспорт | Назначение |
|---|---|
alloc(n: i32) -> i32 | выделить не менее n байт |
dealloc(ptr: i32) | освободить буфер |
oc_meta() -> i64 | чистая функция: JSON метаданных (вызывается на одноразовом экземпляре, host_call там недоступен) |
oc_init(ptr, len) -> i64 | {"apiVersion":1,"config":{…}}; результат игнорируется |
oc_call(name_ptr, name_len, arg_ptr, arg_len) -> i64 | обработчик маршрута (по имени из oc_meta) или on_event |
Импорт (модуль oc): host_call(op_ptr, op_len, arg_ptr, arg_len) -> i64 выполняет операцию хоста: на входе JSON-аргумент, на выходе JSON-результат ({"error":"…"} при ошибке). Если экспортирован _initialize, хост его вызывает. Go: -buildmode=c-shared с //go:wasmexport и //go:wasmimport; Rust: cdylib для wasm32-wasip1.
Результат oc_meta:
{
"id": "music", "name": "Music requests", "version": "0.1.0", "apiVersion": 1,
"permissions": ["storage", "timer", "net.http", "twitch.redemption", "events.publish", "chat.send"],
"subscriptions": ["twitch.redemption"],
"routes": [{"method": "GET", "path": "/next", "handler": "next"}],
"events": [{"id": "now", "name": "Now playing"}],
"widgets": [{"id": "queue", "name": "Queue", "entry": "queue.html", "width": 360, "height": 240}],
"settings": "settings.html",
"configSchema": {"rewardId": {"type": "string", "format": "twitch.reward", "title": "Reward"}}
}
Обработчик маршрута получает {"method","path","query":{…},"body":<json|null>} и возвращает {"status":200,"body":<json>}. События приходят в обработчик с именем on_event как {"type","data"}: twitch.redemption, timer ({"id"}), http.response ({"id","status","body","error"}).
Операции хоста (host_call): log, storage.get/set/delete, timer.set/clear, http.fetch, twitch.redemption.update, events.publish, chat.send. Аргументы — JSON-объекты, которые строят функции Go SDK выше (например, storage.set принимает {"key","value"}, timer.set — {"id","ms","repeat"}, chat.send — {"text"}).
SDK для Rust (как ocplugin для Go) запланирован; см. issue #136. Плагины на Rust на том же ABI весят около 100 КБ.
Чек-лист для агента
- Выбери вид плагина (часть 1 или 2). Если нужны награды Twitch, таймеры, сообщения бота или работа без открытого виджета, это автономный плагин.
- Напиши
Meta/plugin.jsonс минимумом разрешений. - Состояние держи в хранилище; не полагайся на переменные и фоновую работу; на маршруты отвечай сразу.
- Любой текст зрителя (
Redemption.Input, сообщения чата) считай недоверенным; не собирай из него HTML черезinnerHTML. - Поднимай версию при каждом изменении.
- Собери (
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o <id>.wasm .), установи, выдай разрешения в 🧩 Plugins, проверь лог (plugin=<id>).