| 1 | # Runbook: доступ к KB через MCP (handshake, деградация, сбои) — v1 |
| 2 | |
| 3 | **Назначение:** согласовать поведение агента, когда канон живёт в репозитории **agent-notes** и доступен через **agent-notes MCP** (`read_knowledge_file`, `list_knowledge_files`, запись — отдельные инструменты). Среда-независимо: тот же смысл, если чтение идёт с диска по well-known пути без MCP. |
| 4 | |
| 5 | **Связь:** `SHOWCASE.md` § «Доступ к KB»; hub [`agent-memory-and-operating-principles-v1.md`](../../agent-memory-and-operating-principles-v1.md); §6–7 ниже; `playbook-multi-project-context-v1.md` §6 (PRIMARY). |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## 1. Явная деградация (контур чтения недоступен) |
| 10 | |
| 11 | Если агент **не может** вызвать `read_knowledge_file` / `list_knowledge_files` (или эквивалент чтения файлов из `knowledge/`) — в ответе **коротко указать**, что контур чтения канона сейчас недоступен, и **не** выдавать длинные «цитаты из KB» или точные формулировки как будто файл только что прочитан. |
| 12 | |
| 13 | Краткая самопроверка уместна: «могу ли я сейчас подтвердить путь из канона вызовом?» — если нет, одна честная фраза лучше ложного доверия. Объём — **одно предложение**, без морализаторства (практика в духе уже принятого поведения при «молчащем» MCP / после Reload — см. обсуждения в сессиях). |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## 2. Микро-handshake (опционально) |
| 18 | |
| 19 | **Зачем:** сигнал живости контура за мало токенов; пользователю видно, что KB не «в уме модели», а на проводе. |
| 20 | |
| 21 | **Как (любой один шаг):** |
| 22 | - `list_knowledge_files` с пустым `subdir`; или |
| 23 | - `read_knowledge_file` с `file_path: "SHOWCASE.md"`. |
| 24 | |
| 25 | Не превращать в обязательный тяжёлый ритуал на каждое сообщение — только по смыслу (новая сессия, сомнение в MCP, после Reload Window). |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## 3. Три типичных сбоя (чеклист) |
| 30 | |
| 31 | Таблица симптомов (канон): [`troubleshooting/playbook-knowledge-engineering-mcp-troubleshooting-v1.md`](troubleshooting/playbook-knowledge-engineering-mcp-troubleshooting-v1.md). |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## 4. PRIMARY и канон |
| 36 | |
| 37 | Маркер **`[PRIMARY:…]`** задаёт приоритет **карточки проекта** и путей из неё; он **не** заменяет проверку доступности MCP. Если PRIMARY — `agent-notes-kb`, а MCP молчит — сначала честно про деградацию (§1), потом действия. |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ## 5. Полный отказ MCP, «ключи в машине» и человек в контуре |
| 42 | |
| 43 | **Парадокс загрузки:** этот runbook лежит в `knowledge/`; если **чтение канона через MCP недоступно полностью**, агент **не прочитает** и этот файл тем же контуром — инструкция «открой runbook» бессильна (аналог «ключи оставили в салоне»). |
| 44 | |
| 45 | **Типичный реальный случай:** человек **не просит** править заметки/KB, пока не поднят MCP (или пока не работают с локальным клоном репо без агента). Тогда сценарий не раздувается. |
| 46 | |
| 47 | **Где текст всё же полезен агенту:** частичные сбои (неверный `canon_path`, один файл не открывается, «сервер в UI» vs «нет тулов в чате»), новая сессия, сомнение в живости контура — без обвинения пользователя. |
| 48 | |
| 49 | **Выход без размножения правил в конкретной IDE:** локальный клон **agent-notes**, открытие файла в редакторе, сообщение человека в чате, задачи вне канона. Канон задуман **vendor-aware** (см. `SHOWCASE.md`); не обязательно дублировать длинные блоки в настройках Cursor — достаточно внешнего якоря (клон, путь, починка MCP). |
| 50 | |
| 51 | --- |
| 52 | |
| 53 | ## Версия |
| 54 | |
| 55 | v1.3 · 2026-06-12. v1.0 — первый текст. v1.1: §1 без дублирования эпистемики L0. v1.2: §5 bootstrap-парадокс. **v1.3:** §6–7 запись/чтение KB через MCP (из hub agent-memory). |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ## 6. Запись в knowledge/ — только agent-notes MCP |
| 60 | |
| 61 | При изменении **`knowledge/`** канона — **только** инструменты agent-notes MCP, не Write IDE «мимо» (кроме явного согласования с оператором). |
| 62 | |
| 63 | | Действие | Инструмент | |
| 64 | |----------|------------| |
| 65 | | Чтение | `read_knowledge_file` | |
| 66 | | Полная замена | `write_knowledge_file` | |
| 67 | | Конец файла | `append_knowledge_file` | |
| 68 | | Секция по `section_id` | `upsert_knowledge_section`, `delete_knowledge_section` | |
| 69 | | Удалить файл | `delete_knowledge_file` | |
| 70 | | Список | `list_knowledge_files` | |
| 71 | |
| 72 | Канон: **`AGENT_NOTES_CANON_PATH`**. Provenance: [`META/provenance-contract-v1.md`](../../META/provenance-contract-v1.md), [`templates/template-knowledge-card-v1.md`](../../templates/template-knowledge-card-v1.md). |
| 73 | |
| 74 | ## 7. Чтение при недоступности MCP |
| 75 | |
| 76 | Если **чтение** недоступно — не цитировать KB из памяти как факт; одна фраза про недоступность контура. Когда MCP снова доступен — §6 в силе. Подробнее §1–5 выше. |
| 77 | |