Metadata-Version: 2.5
Name: s-pluginkit
Version: 0.1.0
Summary: Кит плагинов: один владелец группы точек входа skillery.plugins, общая часть механизма видов (<сервис>_<вид>, таблица вид→метод, однородность вызова), реестр объявленного, поиск и доставка пакетов-навыков, манифест состава на диске с автодоустановкой, команды CLI из точек входа, разбор кандидатов с причинами (волна 6, Atlas #2717).
Author: Dmitry
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: packaging>=23.0
Description-Content-Type: text/markdown

# pluginkit (`s-pluginkit`)

Кит ПЛАГИНОВ платформы китов: один владелец группы точек входа, общий механизм
видов, реестр объявленного, доставка навыков и манифест их состава.

Родился волной 6 (Atlas #2717) выделением из шлюза `gateway` и из двух
китов-контрактов (`socialkit`, `aichatkit`).

## Зачем

| До волны 6 | Что было не так |
|---|---|
| Имя группы `skillery.plugins` — ДВА независимых литерала (`socialkit.registry.PLUGIN_GROUP`, `adapterkit.registry.PLUGIN_ENTRY_POINT_GROUP`) | Совпадали только потому, что их правили руками синхронно. Расхождение молчаливое: навык доезжает туда, где его не ищут, — пустой перечень вместо ошибки |
| Механизм видов дублируется почти дословно у соцсетей и у чатов | Разбор, знающий про СОСТАВНОЙ вид (`deep_research`), и разбор, не знающий, отвечают разными сервисами на одно имя |
| Манифеста состава нет вовсе | Навыки живут ТОЛЬКО ссылками в окружении инструмента, а `uv tool install --force` сносит окружение целиком. Восстанавливать было не из чего |
| Механизма команд из точек входа нет | Навык приносил умение, но не приносил способа им воспользоваться |
| Совет печатает только тех, кого позвали | Исключённые кандидаты и причины не фигурируют в выводе вовсе — «навык молчит» и «навык не поставлен» неразличимы |

## Состав

- `pluginkit.groups` — `PLUGIN_GROUP`, `COMMAND_GROUP`.
- `pluginkit.kinds` — `capability_id`, `service_of`, `identity_methods`,
  `method_of`, `resolve_method`, `uniformity_problems`.
- `pluginkit.registry` — чтение реестра объявленного (метаданные, без импорта тел).
- `pluginkit.discovery` — поиск пакетов-навыков на диске по их `pyproject.toml`.
- `pluginkit.delivery` — доставка навыков в окружение, добор спутников.
- `pluginkit.manifest` — состав на диске + план автодоустановки.
- `pluginkit.commands` — команды CLI из точек входа.
- `pluginkit.roster` — разбор кандидатов с причинами исключения.

## Закон слоёв

`pluginkit` не импортирует НИ ОДИН другой кит экосистемы (включая `corekit`):
`socialkit`, `aichatkit` и `adapterkit` берут отсюда имя группы и механизм видов,
поэтому обратная зависимость завела бы цикл. Единственная внешняя зависимость —
`packaging` (канон имён дистрибутивов, PEP 503/508).

## Манифест состава

```python
from pluginkit import manifest
from pluginkit.discovery import discover_plugin_packages

manifest.record(discover_plugin_packages([Path("~/PROJECT/_storage").expanduser()]))
# ... переустановка продукта уносит окружение ...
пакеты, исчезли, беда = manifest.autoheal_plan()
```

Файл лежит ВНЕ окружения инструмента (`%LOCALAPPDATA%/skillery/plugins.json` или
`$XDG_DATA_HOME/skillery/plugins.json`); путь переопределяется переменной
`PLUGINKIT_MANIFEST`.
