fix(docs): инструкция MCP — побочные эффекты прав владельца и остановки контроллера
«Обновить мои права» аннулирует планы и выключает профили Route AI; контроллер останавливается и при изменении политики, отзыве токена и ошибке проверки. Бюджет списывается при применении по календарному часу. Уточнены кнопка «Разрешения», применение из интерфейса, «Новый токен», отказ APPROVAL_REQUIRED и формулировка о проверке на стенде. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
1 parent
c85f1a49a0
commit
2568b59afa
3 files changed
+32
-18
No files matched your search
@@ -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
@@ -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 плана завершения).
|
||||
@@ -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 |
|
||||
|
||||
## История отказов (не перекрашивается)
|
||||
|
||||
|
||||
Reference in new issue
Block a user