89 lines
8.4 KiB
Markdown
89 lines
8.4 KiB
Markdown
# modules Specification
|
||
|
||
## Purpose
|
||
Устройство хаба из ядра и подключаемых модулей (первый — `jira`): что принадлежит ядру, как модуль подключается описанием, проверка пересечений при старте и единая схема базы.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Ядро и модули хаба
|
||
Хаб SHALL состоять из ядра и подключаемых модулей. Ядро SHALL владеть базой и миграциями, настройками хаба, проектами
|
||
(метка, название), хранилищем файлов, реле общей папки, релизом агента, очередью пакетов команд, HTTP-сервером с
|
||
авторизацией, раздачей веб-приложения и общим слоем MCP. Модуль SHALL подключаться к ядру описанием: таблицы, типы команд
|
||
и их обработчики в очереди, маршруты HTTP, ключи настроек, фоновые работы, инструменты MCP, подкоманды CLI. Первый модуль —
|
||
`jira` (зеркало задач, журнал изменений, вложения, команды Jira). Ядро MUST NOT импортировать модули, кроме списка
|
||
подключённых модулей и истории миграций схемы.
|
||
|
||
При старте хаб SHALL проверять, что типы команд, ключи настроек и маршруты (метод и шаблон адреса) ядра и модулей не
|
||
пересекаются; пересечение — ошибка старта с указанием конфликта.
|
||
|
||
Схема базы SHALL оставаться одной, с одной версией `setting.schema_version` на весь хаб; таблицы модуля входят в неё.
|
||
|
||
#### Scenario: Конфликт типов команд
|
||
- **WHEN** два подключённых модуля объявляют тип команды `refresh`
|
||
- **THEN** хаб не стартует, ошибка называет тип и оба модуля
|
||
|
||
#### Scenario: Поведение без изменений
|
||
- **WHEN** хаб после перестройки стартует на базе v6 с агентом v14
|
||
- **THEN** схема остаётся v6, копия базы не создаётся; адреса API, веба, ответы и инструменты MCP — прежние; агент берёт
|
||
команды и отчитывается как раньше
|
||
|
||
### Requirement: Агенты модулей
|
||
У каждого подключённого модуля, объявляющего типы команд, SHALL быть свой агент; имя агента — имя модуля (`jira` —
|
||
jira-agent, `wiki` — eva-agent). Агент SHALL определяться по токену: `setting.tokens = {client, agents: {<модуль>:
|
||
<токен>}}`, недостающий токен агента хаб создаёт при старте. Хаб SHALL для каждого агента отдельно:
|
||
- выдавать в `claim` только команды типов его модуля, с одной командой в полёте на агента (агенты работают
|
||
параллельно);
|
||
- хранить строку `agent_status` (ключ — имя агента);
|
||
- держать опубликованный релиз `release/<модуль>/` и состояние самообновления;
|
||
- отдавать в `GET /agent/settings` ключи ядра и ключи для агента только своего модуля;
|
||
- пускать на маршруты модуля со scope `agent` только агента этого модуля (токен другого агента — 401).
|
||
|
||
Миграция v7 SHALL сохранить прежний агентский токен как токен агента `jira`, перенести строку `agent_status` в агента
|
||
`jira` и прежнюю публикацию `release/agent.py` в `release/jira/`. jira-agent v14 SHALL работать без обновления.
|
||
|
||
#### Scenario: jira-agent после выкатки
|
||
- **WHEN** хаб v6 с агентским токеном T и публикацией v14 обновлён до v7, jira-agent v14 шлёт `claim` с токеном T
|
||
- **THEN** 200; ответ содержит `agent_release {version: 14, …}`; `GET /agent` показывает агента `jira` с версией 14
|
||
|
||
#### Scenario: Агенты не берут чужие команды
|
||
- **WHEN** в очереди пакет 1 с `ensure_issue` и пакет 2 с `wiki_sync`, оба `queued`; агент `wiki` шлёт `claim`
|
||
- **THEN** выдан `wiki_sync`; следующий `claim` агента `jira` получает `ensure_issue`, хотя `wiki_sync` ещё `claimed`
|
||
|
||
#### Scenario: Чужой маршрут агента
|
||
- **WHEN** токеном агента `wiki` вызван `POST /agent/state`
|
||
- **THEN** 401, зеркало не меняется
|
||
|
||
#### Scenario: Настройки только своего модуля
|
||
- **WHEN** токеном агента `wiki` вызван `GET /agent/settings`
|
||
- **THEN** в ответе есть `wiki_pacing` и `settings_version`, ключей jira (`project_key`, `transitions_map`) нет
|
||
|
||
### Requirement: Поля проекта от модулей
|
||
Проект ядра SHALL состоять из `label`, `name`, `created_at`; остальные поля проекта SHALL объявлять модули: имя, тип,
|
||
проверку, изменяемость после создания, подпись и подсказку. Модуль SHALL сам хранить свои поля и отдавать их значения
|
||
(включая вычисляемые) для списка проектов. При старте хаб SHALL отвергать два модуля с одним именем поля или поле
|
||
модуля с именем поля ядра — ошибка старта с именем поля и модулей. В ядре SHALL NOT оставаться знания о полях модулей
|
||
(доска, число задач, корень вики).
|
||
|
||
#### Scenario: Конфликт полей
|
||
- **WHEN** два модуля объявляют поле проекта `root`
|
||
- **THEN** хаб не стартует, ошибка называет поле и оба модуля
|
||
|
||
#### Scenario: Поля jira прежние
|
||
- **WHEN** после миграции v7 вызван `GET /projects`
|
||
- **THEN** у `AWPCA` `board_id = 4216`, `board_type = scrum`, `issues_count` — как до миграции
|
||
|
||
### Requirement: Подготовка отчёта команды модулем
|
||
Контракт `CommandHooks` SHALL содержать два необязательных хука. `before_result(conn, cmd, status, result, files_dir)`
|
||
SHALL вызываться ядром при отчёте по выданной команде до транзакции отчёта, чтобы модуль готовил тяжёлую работу (перевод,
|
||
запись файлов) вне блокировки базы; `ValueError` из него SHALL отдаваться как ошибка сервера, а не как неверный статус
|
||
отчёта. `abort_result(conn, cmd)` SHALL вызываться, когда отчёт не дошёл до `after_result` (ранний выход, исключение), и
|
||
снимать подготовку `before_result`. Модуль без этих хуков SHALL работать как прежде.
|
||
|
||
#### Scenario: Подготовка до транзакции
|
||
- **WHEN** агент шлёт отчёт `done` по команде типа модуля с `before_result`
|
||
- **THEN** `before_result` вызван до `BEGIN IMMEDIATE`, после фиксации транзакции — `after_result`
|
||
|
||
#### Scenario: Отчёт прерван
|
||
- **WHEN** `before_result` выполнен, а транзакция отчёта завершилась исключением
|
||
- **THEN** вызван `abort_result`, подготовка снята, команда остаётся выданной
|