From 2568b59afad3f0078ae4c1f9d0b2b5c235381642 Mon Sep 17 00:00:00 2001 From: Denozordec Date: Sat, 21 Nov 2026 21:13:02 +0700 Subject: [PATCH] =?UTF-8?q?fix(docs):=20=D0=B8=D0=BD=D1=81=D1=82=D1=80?= =?UTF-8?q?=D1=83=D0=BA=D1=86=D0=B8=D1=8F=20MCP=20=E2=80=94=20=D0=BF=D0=BE?= =?UTF-8?q?=D0=B1=D0=BE=D1=87=D0=BD=D1=8B=D0=B5=20=D1=8D=D1=84=D1=84=D0=B5?= =?UTF-8?q?=D0=BA=D1=82=D1=8B=20=D0=BF=D1=80=D0=B0=D0=B2=20=D0=B2=D0=BB?= =?UTF-8?q?=D0=B0=D0=B4=D0=B5=D0=BB=D1=8C=D1=86=D0=B0=20=D0=B8=20=D0=BE?= =?UTF-8?q?=D1=81=D1=82=D0=B0=D0=BD=D0=BE=D0=B2=D0=BA=D0=B8=20=D0=BA=D0=BE?= =?UTF-8?q?=D0=BD=D1=82=D1=80=D0=BE=D0=BB=D0=BB=D0=B5=D1=80=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit «Обновить мои права» аннулирует планы и выключает профили Route AI; контроллер останавливается и при изменении политики, отзыве токена и ошибке проверки. Бюджет списывается при применении по календарному часу. Уточнены кнопка «Разрешения», применение из интерфейса, «Новый токен», отказ APPROVAL_REQUIRED и формулировка о проверке на стенде. Co-Authored-By: Claude Opus 5.5 --- docs/mcp-completion-plan.md | 2 +- docs/mcp-enable-guide.md | 46 ++++++++++++++++++++++++------------- docs/mcp-final-manifest.md | 2 +- 3 files changed, 32 insertions(+), 18 deletions(-) diff --git a/docs/mcp-completion-plan.md b/docs/mcp-completion-plan.md index d05b9ba3..cfa54271 100644 --- a/docs/mcp-completion-plan.md +++ b/docs/mcp-completion-plan.md @@ -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` diff --git a/docs/mcp-enable-guide.md b/docs/mcp-enable-guide.md index 51e12745..1af26cf2 100644 --- a/docs/mcp-enable-guide.md +++ b/docs/mcp-enable-guide.md @@ -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 плана завершения). diff --git a/docs/mcp-final-manifest.md b/docs/mcp-final-manifest.md index c8782c7c..6782d9aa 100644 --- a/docs/mcp-final-manifest.md +++ b/docs/mcp-final-manifest.md @@ -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 | ## История отказов (не перекрашивается)