Справочник по манифесту

Каждый модуль объявляет module-manifest.json в своём корне. tv-sdk validate проверяет его Zod-схемой из @tv/extension-sdk/manifest — это авторитетная проверка, та же самая, что выполняют CI и реестр.

Проверка

npx @tv/extension-sdk validate module-manifest.json
# выход 0 — валиден, 1 — невалиден, 2 — ошибка использования

manifest.schema.json для проверки в редакторе

В пакете также поставляется manifest.schema.json. Начиная с 1.1.0 он генерируется в режиме input — то есть описывает то, что вам разрешено писать, — согласуется с tv-sdk validate и его можно смело подключать в редакторе:

"$schema": "./node_modules/@tv/extension-sdk/manifest.schema.json"

В версиях 1.0.x он выпускался в режиме output и помечал обязательным каждое поле со значением по умолчанию; он отклонял 30 из 31 модуля, работавших тогда. Если вы закреплены ниже 1.1.0 — не указывайте $schema.

Завязывайте CI на tv-sdk validate, а не на JSON Schema: валидатор — это контракт, который проверяет реестр, а схема генерируется из него.

Поля верхнего уровня

Поле	Обязательно	Описание
id	да	@vendor/module-name — глобально уникальный. Используйте свою область, не @tv.
name	да	Человекочитаемое имя, отображаемое в консоли
version	да	Semver вашего модуля
minCoreVersion	да	Минимальная версия tv-api, напр. >=2.0.0
category	да	core / operations / engagement / infrastructure / analytics / ai
sdkVersion	да	Версия SDK, под которую написан манифест, напр. 1.1.0. Платформа отклоняет манифесты, нацеленные на более новый SDK, чем у неё.
buildingTypes	да	["all"] или конкретные типы, напр. ["mall","office"]
capabilities	да	provides + requires — именованные контракты возможностей между модулями
permissions	да	Домены данных, которые вы читаете/пишете (см. ниже)
events	да	Массивы publishes + subscribes
mcpTools	да	Инструменты Copilot/MCP, которые даёт ваш модуль. [], если их нет.
lifecycle	да	healthEndpoint, init, dependencies
description	нет	Однострочное описание для каталога
maxCoreVersion	нет	Верхняя граница, если вы знаете, что выше ломаетесь
mcpEndpoint	нет	Внутрикластерный URL, по которому платформа вызывает ваши MCP-инструменты
ui	если есть UI	маршруты + пункты навигации
author	нет	name, email, url

Для capabilities, events, mcpTools, lifecycle и buildingTypes есть значения по умолчанию, поэтому tv-sdk validate примет манифест без них — но объявляйте их явно. Это разница между «у меня нет событий» и «я забыл подумать про события», а ревьюер их не различит.

Разрешения

"permissions": [
  {
    "subject": "building.spaces",
    "actions": ["read"],
    "reason": "Выводит список помещений на главной странице модуля."
  }
]

Для валидатора reason необязателен, а на практике обязателен — он дословно показывается администратору, который одобряет установку.

Каталог

Субъекты и действия берутся из реестра разрешений tv-api и поставляются с SDK в файле permissions.snapshot.json. Полный список — каждый субъект, каждое действие и роли, которым оно выдано, — строится из этого же снимка на странице Каталог разрешений, поэтому он не может разойтись с тем, что платформа реально проверяет. Там же перечислены зарезервированные префиксы, доступные только модулям первой стороны.

Если не хотите покидать терминал — читайте прямо из пакета:

cat node_modules/@tv/extension-sdk/permissions.snapshot.json | jq '.subjects[].subject'

UI

"ui": {
  "remoteEntry": "./Shell",
  "routes": [{ "path": "/cafm", "requiresLicense": true }],
  "navigation": [
    { "label": "CAFM", "icon": "Wrench", "path": "/cafm", "section": "operations", "order": 100 }
  ]
}

routes — это места монтирования вашего федеративного Shell. navigation — то, что появляется на боковой панели Building OS; section — одно из operations, engagement, infrastructure, analytics, admin.

remoteEntry должен быть ./Shell — оболочка ищет ровно это имя. Проверяйте это в CI:

npx @tv/extension-sdk check-exposes module-manifest.json --config=./vite.config.ts

Жизненный цикл

"lifecycle": {
  "healthEndpoint": "/health",
  "init": "on_demand",
  "dependencies": []
}

init: "on_demand" загружает модуль лениво, при первом обращении к его маршруту; on_boot запускает его вместе с оболочкой. В dependencies перечисляются идентификаторы модулей, которые должны стать HEALTHY до вашего старта, — держите список пустым, если вы действительно не можете работать без другого модуля.

Полный пример

См. эталонный модуль — полный проверенный манифест с mcpTools, mcpEndpoint, heartbeat и федерацией, подписанной HMAC. В каталоге модулей перечислены все модули, работающие сегодня.

Стабильность схемы

Схема манифеста следует semver SDK. Несовместимые изменения (новые обязательные поля, удалённые поля) повышают мажорную версию SDK. Дополняющие поля повышают минорную. См. политику стабильности.