fix(docs): инструкция MCP — побочные эффекты прав владельца и остановки контроллера

«Обновить мои права» аннулирует планы и выключает профили Route AI;
контроллер останавливается и при изменении политики, отзыве токена и
ошибке проверки. Бюджет списывается при применении по календарному часу.
Уточнены кнопка «Разрешения», применение из интерфейса, «Новый токен»,
отказ APPROVAL_REQUIRED и формулировка о проверке на стенде.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
DenozordecandClaude Opus 5.5 committed 2026-11-21 21:13:02 +07:00
1 parent c85f1a49a0
commit 2568b59afa
3 files changed
+32 -18

No files matched your search

+1 -1
View File
@@ -117,7 +117,7 @@
## Этап 5. Закрытие (FINAL-2 и FINAL-3)
- [x] Манифест: критерий плана → доказательство → статус, без перекраски `failed` и `unknown` — 2026-11-21, [mcp-final-manifest.md](mcp-final-manifest.md): исходные критерии реестра по направлениям POLL, DB, ROUTING, NATIVE, PATHS, EXTERNAL-UI, FINAL с доказательствами и статусами; отдельно история отказов (13 строк) и критерии вне плана завершения со статусом «не проверено». Решения по открытым строкам — за владельцем
- [x] Инструкция по включению: наблюдение → подтверждения → ограниченная автономность — 2026-11-21, [mcp-enable-guide.md](mcp-enable-guide.md): права портала, `MCP_PUBLIC_URL` и `MCP_STATE_DIR`, три шага с переходами и возвратом, срок прав владельца (до 24 часов), часовой бюджет в объектах, срок плана 5 и 15 минут, защиты, временный допуск, Route AI без автоматического восстановления, пауза, отзыв и аварийная остановка, частые отказы. Надписи сверены с `components/mcp/*.tsx`, числа и коды — с backend и контрактами. На стенде проверен только режим «С подтверждением»; «Наблюдатель» и «Автономный» покрыты `policy.test.ts`
- [x] Инструкция по включению: наблюдение → подтверждения → ограниченная автономность — 2026-11-21, [mcp-enable-guide.md](mcp-enable-guide.md): права портала, `MCP_PUBLIC_URL` и `MCP_STATE_DIR`, три шага с переходами и возвратом, срок прав владельца (до 24 часов), часовой бюджет в объектах, срок плана 5 и 15 минут, защиты, временный допуск, Route AI без автоматического восстановления, пауза, отзыв и аварийная остановка, частые отказы. Надписи сверены с `components/mcp/*.tsx`, числа и коды — с backend и контрактами. В документах стенда есть доказательства только для режима «С подтверждением»; «Наблюдатель» и «Автономный» покрыты `policy.test.ts`. По интерфейсу инструкцию целиком не проходили
- [x] Проверить, что MCP и контроллер выключены по умолчанию — 2026-11-21: `mcp_settings.enabled` и `mcp_routing_profiles.enabled` по умолчанию `false` (`0015_mcp.sql`), `autoRecovery` по умолчанию `false` (контракт), выключенный MCP отказывает токену `MCP_DISABLED`/503 (`store.ts`), воркер не вызывает контроллер при выключенном MCP (`workers.ts`). Проверки на свежей базе добавлены в `integration.test.ts` (первичный шард `test-mcp-postgres-sharded.mjs`)
- [ ] Сократить `docs/mcp.md` (417 КБ) до пользовательской документации
- [ ] PR в `main`
+30 -16
View File
@@ -9,10 +9,10 @@
**По умолчанию всё выключено.** После установки:
- MCP выключен;
- нет ни одного подключения;
- профили Route AI выключены, автоматическое восстановление маршрутов недоступно.
- профили Route AI выключены;
- автоматическое восстановление маршрутов выключено.
Это закреплено тестом на свежей базе (`integration.test.ts`).
Это закреплено тестом на свежей базе (`integration.test.ts`). Подключений нет, пока администратор их не создаст.
Названия в кавычках «…» — надписи в интерфейсе, раздел **MCP** в Manager.
@@ -83,7 +83,7 @@
1. Скопируйте токен в секреты AI-клиента.
2. Нажмите «Закрыть и скрыть токен».
Токен действует до срока подключения. «Новый токен» выпускает замену, старый токен сразу перестаёт работать.
Токен действует до срока подключения. «Новый токен» выпускает замену, старый токен сразу перестаёт работать. OAuth-токены и временные допуски при этом остаются: если токен утёк, используйте «Отозвать».
### Подключить клиента
@@ -105,10 +105,14 @@
Подключение действует, пока подтверждены права его владельца. Подтверждение длится до истечения токена портала, с которым владелец подтвердил права, но не дольше 24 часов. Обновление сессии в портале этот срок не продлевает. Права подтверждаются:
- при создании подключения;
- при сохранении «Изменить разрешения»;
- при сохранении окна «Изменить разрешения»;
- кнопкой «Обновить мои права».
Когда срок прошёл, любой вызов получает `UNAUTHORIZED` (401): «Подключение недействительно или требуется подтверждение прав владельца». Помогает только «Обновить мои права».
Оба срока видны в строке подключения: «Доступ до» и «Права владельца до».
Когда срок прошёл, любой вызов получает `UNAUTHORIZED` (401): «Подключение недействительно или требуется подтверждение прав владельца». Права подтверждает только сам владелец.
«Обновить мои права» аннулирует все неприменённые планы подключения и выключает его профили Route AI. Подтверждайте права до того, как агент начнёт готовить планы.
Если в портале отозвать сессии пользователя, Manager отзывает и его подключения MCP вместе с токенами и временными допусками.
@@ -136,15 +140,16 @@
### Перевести подключение
«Подключения» → подключение → «Изменить разрешения»:
«Подключения» → строка подключения → «Разрешения». Откроется окно «Изменить разрешения»:
- **«Режим управления»** — «С подтверждением».
- **Операции записи** — добавьте нужные `*_plan`.
- **Права** — добавьте права записи.
- **«Изменений в час».** Бюджет считает изменяемые объекты, а не вызовы.
- План, который не помещается в остаток бюджета, отклоняется до подтверждения с `BUDGET_EXCEEDED`.
- Бюджет расходуется при применении плана и обнуляется в начале каждого часа по часам сервера.
- Остаток проверяется дважды: при подготовке плана и при применении. Не хватает — `BUDGET_EXCEEDED`.
- Пример: удаление сервера IPsec на стенде меняет 11 объектов, при значении 10 оно не пройдёт никогда.
- Ставьте значение не меньше самого большого ожидаемого плана, умноженного на число таких планов в час.
- Ставьте значение не меньше суммы объектов всех планов, которые агент применяет за час.
Сохранение не меняет токен. Оно увеличивает версию политики и аннулирует все неприменённые планы подключения. Возврат на шаг 1 делается так же: сменить режим на «Наблюдатель».
@@ -153,12 +158,12 @@
1. Агент вызывает `*_plan`. Manager читает роутер, строит план и проверяет политику.
2. План получает состояние `awaiting-approval`. Он виден в «Планы и операции» → «Планы изменений», а на вкладке «Обзор» растёт счётчик «Ожидают подтверждения».
3. Человек с `mm:mcp:approve` открывает план, проверяет изменения и нажимает «Подтвердить план» или «Отклонить». Подтверждение относится ровно к показанному плану.
4. Агент вызывает `mm_change_apply` с ID плана. Применить план может и человек: «Применить план».
4. Агент вызывает `mm_change_apply` с ID плана. Без подтверждения применение отклоняется с `APPROVAL_REQUIRED`. Администратор (`mm:mcp:admin`) может применить подтверждённый план и сам: «Применить план».
5. Ход записи — в «Выполнение операций»: «Записано намерение», «Применена», «Результат проверен». Агент читает то же через `mm_operation_get`.
**У плана есть срок:**
- 5 минут для сетевых операций;
- 5 минут для операций раздела `network` в каталоге операций;
- 15 минут для остальных;
- для `servers.poll` и `routing.community.switch` — меньше, если раньше истекают данные, на которых построен план.
@@ -194,7 +199,7 @@
- Планы агента совпадают с тем, что вы ожидали.
- Отклонённых планов нет или почти нет.
- Операции доходят до «Результат проверен».
- «Расхождения конфигурации» пусты.
- «Планы и операции» → «Расхождения конфигурации» пусты.
- Защиты стоят на всём, что агент менять не должен.
## Шаг 3. Ограниченная автономность
@@ -235,6 +240,8 @@
Автономная работа ограничена правами владельца: до истечения токена портала, с которым он последний раз подтвердил права, и не дольше 24 часов после этого. Дольше агент без человека не работает. Это намеренно.
Продление — «Обновить мои права». Оно аннулирует неприменённые планы, поэтому делайте его между задачами агента, а не во время.
## Постоянный контроллер Route AI
Отдельная функция: контроллер сам переключает маршруты по профилю.
@@ -252,17 +259,22 @@
- «Допуск действует до (UTC, максимум 24 часа)»;
- срок не позже срока токена, подключения и прав владельца.
Порядок: сначала «Обновить мои права», потом выдавайте допуск профилю. Подтверждение прав после выдачи выключит контроллер.
**Профиль отдельной таблицы или VRF:**
- нужна явная BGP-привязка;
- у каждого пути — контрольная проба с исходным адресом.
**Автоматическое восстановление недоступно.** Профиль с ним отклоняется: `ROUTE_RECOVERY_EXECUTOR_UNAVAILABLE`. Нет источника событий RouterOS, который замечает пропуски.
**Автоматическое восстановление недоступно.** Включить профиль с ним нельзя: `UNSUPPORTED_CAPABILITY` с причиной `ROUTE_RECOVERY_EXECUTOR_UNAVAILABLE`. Если такой профиль всё же оказался включён, контроллер сразу останавливается. Причина: нет источника событий RouterOS, который замечает пропуски.
**Контроллер останавливается сам:**
- когда истёк допуск;
- при любом изменении политики подключения: сохранение «Разрешения», «Пауза», «Отозвать»;
- при «Обновить мои права» владельца подключения;
- при отзыве токена, с которым выдан допуск;
- при ошибке проверки состояния;
- при обнаружении расхождения конфигурации у операций этого подключения;
- при «Остановить автоматические изменения».
@@ -276,7 +288,7 @@
| --- | --- | --- | --- |
| «Пауза» | «Подключения» | Токены подключения не принимаются, неприменённые планы аннулируются | да, «Включить» |
| «Отозвать» | «Подключения» | Подключение и все его токены отозваны, неприменённые планы аннулируются | нет: `CONNECTION_REVOKED` |
| «Новый токен» | «Подключения» | Старый токен перестаёт работать | — |
| «Новый токен» | «Подключения» | Старый токен перестаёт работать. OAuth-токены и временные допуски остаются | — |
| «Отозвать допуск» | «Проверка подключения и временные допуски» | Временный допуск и его токен перестают действовать | нет |
| Снять «Разрешить обращения MCP» | «Настройки» | Все вызовы получают `MCP_DISABLED`, контроллер и проверка расхождений не работают. Токены не отзываются | да: после включения токены снова работают |
| «Остановить автоматические изменения» | «Обзор», право `mm:mcp:pause` | MCP выключается, все профили Route AI выключаются. Начатые записи завершаются или сверяются | частично: MCP включается флагом, профили Route AI включают заново вручную |
@@ -290,7 +302,7 @@
| --- | --- | --- |
| `MCP_DISABLED` | MCP выключен | «Разрешить обращения MCP» |
| `UNAUTHORIZED` | Токен неверный, отозван или истёк, подключение на паузе, права владельца не подтверждены или сменилось поколение доступа | проверить подключение, «Обновить мои права», при необходимости «Новый токен» |
| `OPERATION_DENIED` | Операция не выдана подключению | добавить операцию в «Изменить разрешения» |
| `OPERATION_DENIED` | Операция не выдана подключению | добавить операцию в окне «Изменить разрешения» |
| `OWNER_PERMISSION_MISSING`, `CONNECTION_PERMISSION_MISSING` | Нет права у владельца или у подключения | выдать право в портале или подключению |
| `SERVER_DENIED`, `GLOBAL_DENIED` | Сервер вне области, глобальные операции не разрешены | расширить область, если это нужно |
| `GRANT_INACTIVE`, `GRANT_SCOPE_DENIED` | Временный допуск истёк или запрос шире допуска | новый допуск |
@@ -300,6 +312,7 @@
| `PLAN_LIMIT_EXCEEDED` | Слишком много серверов или объектов в плане | разбить план или поднять лимит |
| `PROTECTED_OBJECT` | Объект под «Запрет изменений» | снять защиту, если изменение действительно нужно |
| `AUDIT_UNAVAILABLE` | Аудит недоступен | восстановить базу или аудит; изменения до этого не выполняются |
| `APPROVAL_REQUIRED` | Применение плана без подтверждения человеком | подтвердить план в «Планы и операции» |
| `PLAN_EXPIRED` | Истёк срок плана или исходных данных | подготовить новый план |
| `CONFIGURATION_BUSY` | Глобальная конфигурация занята другой операцией дольше 30 секунд | повторить позже |
@@ -311,6 +324,7 @@
- IPsec: пять прогонов подряд, в каждом 4 подтверждения в интерфейсе. Применение без подтверждения отклонено.
- Маршрутизация A3: 2 подтверждения.
- Выдача токена в интерфейсе, подтверждение плана и подписанный отзыв в настоящих Manager и Portal — EXT-1.
- **Режимы «Наблюдатель» и «Автономный», защиты, бюджет и лимиты** покрыты тестами политики (`policy.test.ts`). На стенде отдельно не проверялись.
- **Режимы «Наблюдатель» и «Автономный», защиты, бюджет и лимиты** покрыты тестами политики (`policy.test.ts`). В документах стенда доказательств их отдельной проверки нет.
- **Сама инструкция** сверена с кодом: надписи — с `components/mcp/*.tsx`, числа и коды — с backend и контрактами. По интерфейсу её целиком не проходили.
- **Раздел MCP в интерфейсе** проверен частично: выдача ограниченного доступа, отказы, фильтры и пагинация на стенде не проверялись (UI-1).
- **Автоматическое восстановление маршрутов** не реализовано и выключено (этап 4 плана завершения).
+1 -1
View File
@@ -91,7 +91,7 @@
| --- | --- | --- |
| Итоговый снимок исходников и регрессия | Этап 1 на прежнем HEAD; на коде `d02a019b`: шардированный `test-mcp-postgres-sharded.mjs` 6 из 6, `--module-completion`, набор A7 205/205 | принято частично: полный этап 1 (`lint`, `build`, `test:mcp:pg:all`, Playwright) на итоговом HEAD повторяется перед PR |
| Контракты, безопасность, покрытие, судьба нерешённой истории | `coverage.test.ts` (этап 1); этот манифест | принято частично: манифест составлен, решение по открытым строкам — за владельцем |
| Инструкции по эксплуатации и безопасное включение | Проверка «выключено по умолчанию» (выше); [mcp-enable-guide.md](mcp-enable-guide.md) — три шага включения, остановка и отзыв, частые отказы | принято частично: на стенде проверен только режим «С подтверждением»; «Наблюдатель» и «Автономный» — тестами политики. Сокращение `docs/mcp.md` до пользовательской документации — этап 5 |
| Инструкции по эксплуатации и безопасное включение | Проверка «выключено по умолчанию» (выше); [mcp-enable-guide.md](mcp-enable-guide.md) — три шага включения, остановка и отзыв, частые отказы | принято частично: в документах стенда есть доказательства только для режима «С подтверждением»; «Наблюдатель» и «Автономный» — тестами политики; инструкция сверена с кодом, по интерфейсу целиком не пройдена. Сокращение `docs/mcp.md` до пользовательской документации — этап 5 |
## История отказов (не перекрашивается)