Octofs: файловый сервер, который не даст ИИ сломать ваш код

Ваш ИИ-ассистент только что отредактировал три файла. Два в порядке. В третьем функция продублирована, отсутствует закрывающая скобка, а отступы совершенно неправильные. Он выглядел уверенно. Он не был прав.

Это случается чаще, чем кто-либо хочет признать. ИИ-агенты — мощные редакторы кода, пока не нагаллюцинируют номер строки, не запомнят неправильно отступ или не включат окружающий контекст в замену, которой там быть не должно. Редактирование технически проходит. Файл теперь сломан. Вы заметили это только тогда, когда упала сборка.

Octofs — это MCP-сервер файловой системы, построенный именно для того, чтобы это предотвратить. Он даёт вашему ИИ-агенту глаза, руки и страховочную сетку — возможность читать, редактировать, создавать и искать файлы, с несколькими уровнями защиты от ошибок, которые модели ИИ совершают при работе с кодом.

Сегодня мы представляем Octofs 0.4.0 — текущее состояние проекта, который начался как простой файловый сервер и эволюционировал во что-то, что, как мы считаем, нужно каждому ИИ-агенту.

Почему мы вообще построили файловый сервер

Мы начали не с этого. Мы начали с Octomind — рантайма для специализированных ИИ-агентов. Вы запускаете octomind run developer:general и за пять секунд получаете полностью оснащённого senior-разработчика. Агенту нужно читать код, редактировать файлы, выполнять команды, искать по вашему проекту. Ему нужен доступ к файловой системе.

В экосистеме MCP уже был эталонный сервер файловой системы. Мы попробовали его. Он работал — пока не переставал. ИИ ссылался на номера строк, которые сдвигались после предыдущего редактирования. Передавал слегка некорректные пробелы в строковую замену и получал тихое несовпадение. Дублировал строки на границах диапазона замены. Пытался запустить grep через shell, когда существовал специализированный инструмент поиска.

Каждый сбой был маленьким. Каждый требовал вмешательства человека. На масштабе агента — сотни редактирований в десятках файлов — мелкие сбои складываются во что-то, что перестаёт быть полезным.

Поэтому мы написали свой. Не потому, что доступ к файловой системе — это интересно. А потому что режимы отказов редактирования файлов, управляемого ИИ, предсказуемы, и хороший сервер может поймать большинство из них до того, как они станут вашей проблемой.

Проблема галлюцинаций ИИ при редактировании файлов

Вот что на самом деле ломается:

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

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

Дублирование контекста. Агент включает одну лишнюю строку окружающего контекста в свой текст замены. Теперь эта строка появляется в файле дважды. Если это закрывающая скобка, код всё ещё может парситься. Если это значимая строка, у вас тонкий баг.

Неоднозначные совпадения. Агент передаёт трёхстрочную строку, которая появляется в файле в четырёх местах. Какую из них следует заменить? Без устранения неоднозначности правка либо не срабатывает, либо попадает не туда.

Это не граничные случаи. Это стандартный опыт запуска ИИ-агентов в масштабе. И всё это решаемо — не делая ИИ умнее, а делая файловый сервер умнее в отношении ошибок, которые он знает, что ИИ совершит.

Как Octofs ловит ошибки

Трёхэтапное прогрессивное сопоставление

Когда ИИ вызывает str_replace с old_text, который должен совпасть с чем-то в файле, Octofs не просто пытается один раз и сдаётся. Он выполняет три этапа:

Этап 1: Точное совпадение. Строка old_text совпадает ровно один раз в файле. Замените её. Готово. Это счастливый путь — он корректно обрабатывает большинство правок.

Этап 2: Нечёткое сопоставление с нормализацией пробелов. Точное совпадение не сработало, поэтому Octofs нормализует пробелы как в предоставленном тексте, так и в содержимом файла — сворачивает последовательности пробелов, обрезает строки — и пытается снова. Если есть ровно одно нормализованное совпадение, он автоматически подстраивает отступы текста замены под фактический файл, применяет правку и сообщает ИИ, что произошло, через подсказку. ИИ учится. Правка проходит.

Этап 3: Богатая диагностика. Не сработали ни точное, ни нечёткое сопоставление. Вместо общей ошибки «совпадения не найдено» Octofs запускает поиск по сходству скользящим окном по всему файлу, находит три ближайших совпадения и возвращает их с процентами сходства, номерами строк, диагнозом, почему они отличаются (несовпадение отступов, только пробелы или различается содержимое), и предпросмотром текста-кандидата. Затем ИИ может использовать batch_edit с точным диапазоном строк — или исправить свой old_text и попробовать снова.

Это то, что происходит каждый раз, когда правка не удаётся, и это самое большое единичное сокращение повторных попыток неудачных правок, которое мы видели.

Идентификация строк на основе хэша

Номера строк — ужасный идентификатор для правок, управляемых ИИ. Они сдвигаются. ИИ читает файл в 500 строк, планирует отредактировать строки 142-156, но предыдущая правка вставила четыре строки на строке 80. Теперь цель находится на 146-160. ИИ этого не знает, если только не перечитает файл — а он может этого и не сделать.

Octofs предлагает альтернативу: идентификаторы строк на основе хэша. Каждая строка получает 4-символьный шестнадцатеричный хэш, выведенный из её позиции и содержимого. В отличие от номеров строк, хэши стабильны при правках — хэш строки не меняется только потому, что выше была вставлена другая строка. ИИ может ссылаться на строки по хэшу, и даже после нескольких правок эти ссылки остаются валидными.

Алгоритм хэширования использует FNV-1a, свёрнутый до 16 бит, с ключом "<позиция>:<содержимое>". Позиция включена специально для обработки дублирующихся строк — две идентичные строки в разных позициях всегда получают разные хэши, без необходимости разрешения коллизий.

Включите его с --line-mode hash, и каждый ответ инструмента будет возвращать хэши вместо номеров. ИИ использует их для диапазонов batch_edit, диапазонов view и диагностики. Сдвиг номеров строк перестаёт быть проблемой.

Обнаружение дубликатов на границах замены

Вот тонкий момент. ИИ планирует замену для строк 100-105. Он включает строку 99 (строку перед диапазоном) в содержимое замены — не потому, что хочет её изменить, а потому, что «предоставляет контекст». Теперь строка 99 появляется дважды. Если это закрывающая скобка или пустая строка, возможно, вреда нет. Если это реальный код, у вас баг.

Octofs проверяет каждую замену на дублирование границ. Он сравнивает первую строку замены со строкой непосредственно перед целевым диапазоном, и последнюю строку со строкой после. Если какая-то совпадает, он отклоняет правку с конкретным сообщением: «Обнаружена дублирующаяся строка в операции 2: первая строка содержимого совпадает со строкой 99 (непосредственно перед диапазоном замены [100-105]). НЕ включайте окружающие неизменённые строки.»

Структурный шум — одиночные закрывающие скобки, пустые строки — освобождён от этой проверки. Они законно появляются на границах. Составные закрывающие конструкции вроде }); не освобождены. Они несут реальный семантический смысл.

Обнаружение конфликтов для пакетных операций

batch_edit позволяет ИИ выполнять несколько операций вставки и замены в одном файле атомарно. Но что если две замены пересекаются? Что если две вставки нацелены на одну и ту же якорную строку?

Octofs валидирует каждую операцию против всех остальных операций перед тем, как трогать файл. Диапазоны замена-против-замены, которые пересекаются, отклоняются. Вставка-против-вставки в одном якоре отклоняется (неоднозначный порядок). Вставка-против-замены никогда не конфликтуют — они работают в концептуально разных позициях (пробел после строки против содержимого строки).

Если есть конфликт, сообщение об ошибке включает индексы операций и конкретные затронутые диапазоны строк. ИИ может исправить свой план и повторить попытку. Никакого частичного повреждения.

Атомарные записи с историей отмен

Каждая правка проходит через atomic_write: запись во временный файл в том же каталоге, затем переименование поверх целевого. Файл никогда не находится в частичном состоянии. Если процесс падает посреди записи, оригинал остаётся целым. Переименование — единственный деструктивный шаг, и он атомарен на уровне файловой системы.

Перед каждой записью Octofs сохраняет предыдущую версию. До десяти уровней отмены на файл. Если правка идёт не так, ИИ может вызвать undo_edit, и файл откатывается. Никакого ручного git restore. Никакого «упс, мне нужно исправить то, что ИИ только что сделал».

Обнаружение неправильного использования shell

У ИИ есть доступ к shell. Это необходимо — ему нужно запускать сборки, тесты, линтеры. Но он также иногда пытается использовать cat для чтения файла, или grep для поиска текста, или sed для редактирования строки. У всех этих есть выделенные, лучшие инструменты в Octofs.

Когда ИИ выполняет shell-команду, соответствующую известному шаблону неправильного использования, Octofs обнаруживает это и встраивает подсказку в следующий ответ инструмента: «Предпочтите view для чтения файлов (с нумерацией строк, поддерживает диапазоны).» ИИ видит подсказку, корректирует своё поведение и в следующий раз использует правильный инструмент.

Принудительное использование неинтерактивного shell

Shell-команды выполняются с stdin=null, выделенной группой процессов и переменными окружения вроде GIT_TERMINAL_PROMPT=0 и PAGER=cat. ИИ не может случайно породить интерактивный prompt, который повесит сессию. Git не будет запрашивать учётные данные. sudo не будет запрашивать пароль. less не будет вызван. Команда либо завершается успехом, либо неудачей — третьего состояния нет.

При завершении работы группа процессов каждого незавершённого shell-потомка убивается с помощью SIGKILL. Никаких процессов-сирот. Никаких zombie-шеллов, поедающих память.

Текущее состояние: 0.4.0

Octofs 0.4.0 — это не анонс релиза, а то, где находится проект прямо сейчас, и он достаточно стабилен, чтобы на него полагаться. Вот что предоставляет текущая версия:

Просмотр файлов с несколькими диапазонами. Читайте несмежные секции файла одним вызовом — [[1, 50], [200, 250], [400, 430]] — вместо трёх отдельных запросов. Меньше круговых обращений. Меньше потерь контекста.

Структурированные типы диапазонов строк. Диапазоны строк теперь являются типами первого класса с надлежащей валидацией — а не сырыми JSON-массивами, которые ИИ должен правильно форматировать. Сервер валидирует форму, границы и количество перед тем, как что-то делать.

Принудительное использование неинтерактивного shell. Shell-команды гарантированно неинтерактивны. Больше никаких зависших prompts, никаких диалогов учётных данных, никакого мусорного вывода, вызванного пейджером.

Усечение выхода за границы. Диапазоны строк, превышающие длину файла, усекаются, а не отклоняются. ИИ просит строки 1-1000 в файле из 200 строк? Он получает строки 1-200. Никаких ошибок. Никаких повторов.

Диапазоны строк для каждого файла в мультифайловых просмотрах. При просмотре нескольких файлов сразу каждый файл может иметь свой собственный диапазон строк. paths: ["a.rs", "b.rs", "c.rs"] с lines: [[1,50], null, [10,30]] — первый файл показывает 1-50, второй показывает всё, третий показывает 10-30.

Канонизированная блокировка файлов. Блокировки файлов используют канонизированные пути, поэтому ./src/main.rs, src/main.rs и /absolute/path/to/src/main.rs все разрешаются в одну и ту же блокировку. Никакого повреждения от одновременной записи из-за aliasing путей.

Чисто Rust-поиск. Поиск содержимого больше не вызывает ripgrep через shell. Это чисто Rust-реализация, которая достаточно быстра, имеет ноль внешних зависимостей и работает одинаково на каждой платформе.

Инструменты

Octofs предоставляет семь MCP-инструментов:

Инструмент Что делает
view Читает файлы, перечисляет каталоги, ищет содержимое. Поддерживает мультифайловость, мульти-диапазоны, идентификаторы строк на основе хэша, поиск содержимого со строками контекста
text_editor Создаёт файлы, заменяет текст с прогрессивным сопоставлением, отменяет правки
batch_edit Множественные атомарные операции вставки/замены в одном файле с обнаружением конфликтов
extract_lines Копирует диапазоны строк из одного файла в другой
shell Выполняет команды с поддержкой фоновых задач, обнаружением неправильного использования, принудительным неинтерактивным режимом
workdir Управляет контекстом рабочего каталога

Все инструменты поддерживают как STDIO, так и Streamable HTTP-транспорт. Все инструменты учитывают gitignore при обходе каталогов. Все инструменты отвечают выводом с нумерацией строк (или идентификацией по хэшу), чтобы у ИИ были стабильные ссылки для последующих операций.

Как это сочетается: Octomind + Octofs

Octofs работает с любым MCP-совместимым клиентом — Claude Desktop, Cursor, Windsurf, Zed. Но он спроектирован для Octomind.

Агенты Octomind читают вашу кодовую базу, планируют изменения и выполняют правки через Octofs. Octobrain — наш сервер памяти — хранит то, что агент узнаёт во время сессии. Octolib обрабатывает каждый вызов LLM. Вместе они представляют полный стек для разработки, управляемой ИИ:

  • Octolib общается с моделями ИИ
  • Octobrain запоминает между сессиями
  • Octofs безопасно работает с вашими файлами
  • Octomind оркестрирует всё

Каждая часть — open source. Каждая часть работает самостоятельно. Вместе они решают проблему предоставления ИИ-агенту надёжного, безопасного доступа к кодовой базе.

Open source, нативный Rust

Octofs на GitHub под Apache-2.0. Он построен на Rust — не потому, что мы фетишизируем производительность, а потому, что файловые операции выигрывают от корректности на этапе компиляции, zero-cost async и отсутствия пауз сборки мусора. Бинарник маленький, быстрый и имеет ноль runtime-зависимостей помимо ОС.

# Сборка из исходников (требует Rust 1.95+)
git clone https://github.com/muvon/octofs
cd octofs && cargo build --release

# Или загрузите предсобранный бинарник с GitHub Releases

Добавьте в конфиг Claude Desktop:

{
	"mcpServers": {
		"octofs": {
			"command": "/path/to/octofs",
			"args": ["--line-mode", "hash"]
		}
	}
}

Используйте hash-режим для любого агента, который делает многошаговые правки. Стабильные ссылки на строки устраняют целый класс сбоев.

FAQ

Что такое Octofs?

Octofs — это open-source MCP-сервер файловой системы на Rust. Он даёт ИИ-агентам безопасный, надёжный доступ для чтения, редактирования, поиска и создания файлов — со встроенной защитой от режимов отказов, которые модели ИИ демонстрируют при редактировании кода.

Какие ИИ-клиенты работают с Octofs?

Любой MCP-совместимый клиент: Claude Desktop, Cursor, Windsurf, Zed и open-source рантайм агентов Octomind.

Как Octofs предотвращает поломку файлов из-за галлюцинаций ИИ?

Пять слоёв: (1) трёхэтапное прогрессивное сопоставление для str_replace, (2) идентификаторы строк на основе хэша, которые переживают правки, (3) обнаружение дубликатов на границах замены, (4) обнаружение конфликтов для пакетных операций, (5) атомарные записи с до 10 уровнями отмены на файл.

Что такое идентификаторы строк на основе хэша?

Каждая строка получает 4-символьный шестнадцатеричный хэш, выведенный из её содержимого и позиции (FNV-1a, свёрнутый до 16 бит). В отличие от номеров строк, хэши стабильны при правках — хэш строки не сдвигается, когда выше вставляются другие строки. Включите с --line-mode hash.

Чем Octofs отличается от эталонного MCP-сервера файловой системы?

Эталонный сервер выполняет прямой файловый I/O. Octofs добавляет нечёткое сопоставление с автоматическими отступами, хэш-идентификаторы, обнаружение дубликатов на границах, проверки конфликтов в пакетных операциях, атомарные записи, историю отмен, обнаружение неправильного использования shell и принудительный неинтерактивный shell. Построен специально для режимов отказов, которые ИИ-агенты производят в масштабе.

Готов ли Octofs к продакшену?

Да. 0.4.0 стабилен и ежедневно используется внутри Octomind. Apache-2.0, единственный Rust-бинарник, ноль runtime-зависимостей помимо ОС. Атомарные записи гарантируют, что файлы никогда не остаются в частичном состоянии.

Поддерживает ли он и STDIO, и HTTP?

Да. STDIO-транспорт для настольных клиентов (Claude, Cursor и т.д.) и Streamable HTTP для удалённых агентов.

Что дальше

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

Файловый сервер — не самая захватывающая часть стека ИИ-агента. Это часть, которая должна работать безупречно, каждый раз, иначе всё остальное рушится. Это требование, вокруг которого построен Octofs — и он open source на GitHub под Apache-2.0, если хотите углубиться.