# Octocode 0.20.0: Markdown становится частью графа знаний

> Octocode 0.20.0 добавляет Markdown в граф знаний GraphRAG: документы становятся узлами, а ссылки между ними — типизированными связями references. В релиз также вошло исправление незаметно пропадавших связей в крупных проектах и двукратное снижение расхода памяти при их загрузке. Открытый исходный код, Apache-2.0.

README описывает архитектуру вашего проекта. Папка docs — принятые решения. И до сегодняшнего дня ничего из этого не существовало в графе знаний Octocode.

**0.20.0 закрывает этот пробел: файлы Markdown теперь становятся узлами графа знаний GraphRAG, а ссылки между документами — типизированными связями `references`, по которым AI-ассистент действительно может пройти.**

Меня это беспокоило уже давно. Octocode всегда умел _находить_ документацию — семантический поиск индексировал Markdown с самого начала. Но найти документ по ключевому слову и _обнаружить_ его, следуя структуре проекта, — разные вещи. Ассистент мог без труда пройти по графу кода в поисках ответа на вопрос «что зависит от платёжного модуля?» и при этом не заметить архитектурную заметку тремя каталогами дальше, где объясняется, _почему_ модуль устроен именно так.

Код рассказывал половину истории. Теперь граф знает и вторую.

---

## Что изменилось на самом деле

Если коротко, то при индексации документы Markdown теперь проходят через тот же конвейер GraphRAG, что и исходный код. Запросы к графу, раскрытие связей и MCP-инструмент `graphrag` могут находить документацию вместе с кодом — не отдельным поиском, а в рамках одного обхода.

Вот за счёт чего это приносит пользу, а не лишний шум:

**Ссылки между документами становятся связями `references`.** Когда один файл Markdown ссылается на другой — `[see the guide](guide.md)` — Octocode записывает между ними типизированное ребро. Относительные ссылки разрешаются от расположения исходного файла, якоря (`#section`) отбрасываются, а внешние URL с `http://` и `https://` игнорируются. Структура ссылок в вашей документации всегда была картой. Теперь граф умеет её читать.

**Веса подобраны осознанно.** При обходе графа `references` получает вес **0.6** — меньше, чем структурные связи кода imports и calls (0.7), но больше, чем организационные связи вроде нахождения в одном каталоге (0.3). Поэтому ссылки между документами заметно влияют на раскрытие графа, не заглушая структуру кода. Ссылка между двумя документами — это человек, который говорит: «Эти вещи связаны». Это важный сигнал, но не то же самое, что реальное ребро вызова, и веса отражают эту разницу.

**Файлы `.markdown` поддерживаются везде, где поддерживаются `.md`.** И в семантическом поиске, и в новой интеграции с графом. Мелочь, но раньше эта непоследовательность создавала проблемы в старых репозиториях.

И самое приятное в обновлении: **переиндексировать всё с нуля не нужно.** Содержимое Markdown уже хранится в блоках документов вашего индекса, поэтому при перестроении граф забирает его из существующей базы данных. Запустите `octocode index` или перестройте граф — и документация появится в нём.

---

## Ошибка, которая незаметно скрывала связи

Для некоторых из вас это исправление важнее самой новой возможности.

При чтении связей из LanceDB возвращалась лишь часть сохранённой выборки: последующие пакеты отбрасывались вместо объединения. На маленьких проектах это было незаметно. На больших запросы к графу могли **без предупреждения пропускать связи, которые должны были существовать.**

«Без предупреждения» — ключевые слова. Ни ошибки, ни уведомления — только неполный граф, который выглядел полным. Если при запросе к графу крупного репозитория вы когда-нибудь думали «здесь должно быть больше рёбер», скорее всего, причина была именно в этом. Теперь после перестроения или повторной загрузки граф содержит полный набор связей.

Вместе с этим вошли ещё два связанных исправления:

- **Заголовки Markdown больше не засоряют индекс символов кода.** Раньше заголовки документов индексировались как символы, а механизм разрешения imports находил совпадения с ними, создавая ложных кандидатов на связи. Теперь узлы Markdown исключены из индекса символов, но по-прежнему участвуют в графе через ссылки, разрешаемые по путям.
- **Узлы Markdown разрешаются по пути, а не по символу.** В оптимизированном проходе поиска связей документы теперь обрабатываются механизмом разрешения по пути — именно так работают ссылки между документами — вместо сопоставления символов, предназначенного для кода. Поэтому рёбра между документами теперь точны, а не случайны.

---

## Вдвое меньше памяти при загрузке связей

При промежуточной записи результатов инкрементальной индексации одна и та же связь могла попасть в несколько пакетов. В одном реальном крупном проекте загрузчик читал **575 тысяч строк для представления 288 тысяч уникальных связей** — почти половину набора составляли дубликаты.

Теперь при загрузке графа связи дедуплицируются по тройке `(source, target, type)`. Это примерно вдвое снижает расход памяти и ускоряет все операции графа, которые перебирают полный набор. При удалении дубликатов загрузчик сообщает их количество, поэтому результат можно проверить.

Менять конфигурацию не нужно. Граф просто загружается с меньшим расходом памяти.

---

## Остальные изменения

**MCP-сервер обновлён до rmcp 3.0.0.** Базовый SDK Model Context Protocol перешёл на новую основную версию, поэтому Octocode остаётся совместимым с актуальной экосистемой MCP и её потоковым HTTP-транспортом. Серверные режимы stdin и HTTP работают как прежде — менять конфигурацию не требуется.

**Управление конфигурацией перенесено в octolib.** Общая логика управления конфигурационными файлами и последовательной миграции между версиями — обход версий, проверки и объединение таблиц — теперь находится в общей библиотеке `octolib`. В Octocode остались только его собственные шаги миграции с v1 на v2. Для пользователя всё прозрачно: существующие конфигурации мигрируют точно так же, как раньше. Теперь достаточно один раз исправить обработку конфигурации в octolib, чтобы исправление получили все построенные на ней инструменты, вместо переноса изменений из репозитория в репозиторий.

**Документацию тоже обновили.** README теперь описывает весь набор MCP-инструментов, включая инструменты на базе LSP (`lsp_goto_definition`, `lsp_find_references`, `lsp_hover`, `lsp_document_symbols`, `lsp_workspace_symbols`, `lsp_completion`), а также их включение с помощью `--with-lsp`. Появились и новые независимые от поставщика руководства по подключению Octocode к любому совместимому с OpenAI API для LLM или эмбеддингов — как к локальным серверам моделей, так и к альтернативным облачным провайдерам.

---

## Обновление

```bash
# Homebrew
brew upgrade muvon/tap/octocode

# Универсальный установщик
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# Cargo
cargo install octocode --version 0.20.0
```

Обновление устанавливается без дополнительных изменений: конфигурацию менять не нужно, а существующие конфигурационные файлы мигрируют автоматически. После обновления остаётся сделать одно:

**Перестройте граф** (или просто запустите `octocode index`) в проекте с настоящей документацией. Затем задайте ассистенту вопрос, для ответа на который раньше человеку пришлось бы сопоставлять код с документацией: «Где обрабатывается аутентификация и что об этом сказано в руководстве по безопасности?» — и посмотрите, как ассистент пройдёт по тому и другому.

---

Octocode — проект с открытым исходным кодом под лицензией Apache-2.0, доступный на [github.com/Muvon/octocode](https://github.com/Muvon/octocode), и поисковый движок по коду, лежащий в основе [Octomind](https://octomind.run). Граф уже знал, как связан ваш код. Теперь он знает и то, что вы о нём написали.