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 или эмбеддингов — как к локальным серверам моделей, так и к альтернативным облачным провайдерам.

Обновление

# 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, и поисковый движок по коду, лежащий в основе Octomind. Граф уже знал, как связан ваш код. Теперь он знает и то, что вы о нём написали.