Memory Import Processor

Memory Import Processor — это функция, которая позволяет модуляризовать ваши контекстные файлы (например, QWEN.md), импортируя содержимое из других файлов с помощью синтаксиса @file.md.

Обзор

Эта функция позволяет разбивать большие контекстные файлы (например, QWEN.md) на более мелкие и удобные для управления компоненты, которые можно повторно использовать в разных контекстах. Import processor поддерживает как относительные, так и абсолютные пути, а также имеет встроенные механизмы безопасности, предотвращающие циклические импорты и обеспечивающие безопасность доступа к файлам.

Синтаксис

Используйте символ @, за которым следует путь к файлу, который вы хотите импортировать:

 
# Основной файл QWEN.md
 
Это основное содержимое.
 
@./components/instructions.md
 
Здесь еще больше контента.
 
@./shared/configuration.md

Поддерживаемые форматы путей

Относительные пути

• @./file.md — Импорт из той же директории
• @../file.md — Импорт из родительской директории
• @./components/file.md — Импорт из поддиректории

Абсолютные пути

• @/absolute/path/to/file.md — Импорт с использованием абсолютного пути

Примеры

Базовый импорт

 
# My QWEN.md
 
Добро пожаловать в мой проект!
 
@./getting-started.md
 
## Возможности
 
@./features/overview.md

Вложенные импорты

Импортируемые файлы могут сами содержать импорты, создавая вложенную структуру:

 
# main.md
 
@./header.md
@./content.md
@./footer.md

 
# header.md
 
# Заголовок проекта
 
@./shared/title.md

Функции безопасности

Обнаружение циклических импортов

Процессор автоматически обнаруживает и предотвращает циклические импорты:

 
# file-a.md
 
@./file-b.md
 
# file-b.md
 
@./file-a.md <!-- Это будет обнаружено и заблокировано -->

Безопасность доступа к файлам

Функция validateImportPath гарантирует, что импорт разрешен только из указанных директорий, предотвращая доступ к чувствительным файлам вне разрешенной области.

Максимальная глубина импорта

Чтобы предотвратить бесконечную рекурсию, можно настроить максимальную глубину импорта (по умолчанию: 5 уровней).

Обработка ошибок

Отсутствующие файлы

Если указанный файл не существует, импорт завершится с ошибкой, и в выводе появится комментарий с описанием ошибки.

Ошибки доступа к файлам

Проблемы с правами доступа или другие ошибки файловой системы обрабатываются корректно с выводом соответствующих сообщений об ошибках.

Определение областей кода

Процессор импорта использует библиотеку marked для определения блоков кода и встроенных фрагментов кода, благодаря чему @ импорты внутри этих областей корректно игнорируются. Это обеспечивает надежную обработку вложенных блоков кода и сложных структур Markdown.

Структура дерева импорта

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

Пример структуры дерева:

 Memory Files
 L project: QWEN.md
            L a.md
              L b.md
                L c.md
              L d.md
                L e.md
                  L f.md
            L included.md

Дерево сохраняет порядок, в котором файлы были импортированы, и показывает полную цепочку импорта для целей отладки.

Сравнение с подходом Claude Code /memory (claude.md)

Функция /memory в Claude Code (как показано в claude.md) создает плоский, линейный документ путем объединения всех включенных файлов, всегда помечая границы файлов清晰ыми комментариями и именами путей. Она не представляет явно иерархию импортов, но LLM получает все содержимое файлов и пути, что достаточно для восстановления иерархии при необходимости.

Примечание: Импортное дерево主要用于开发过程中的清晰度，对LLM消费的相关性有限。

Справочник API

processImports(content, basePath, debugMode?, importState?)

Обрабатывает import statements в содержимом файла контекста.

Параметры:

• content (string): Содержимое для обработки импортов
• basePath (string): Путь к директории, где находится текущий файл
• debugMode (boolean, опционально): Включить ли debug logging (по умолчанию: false)
• importState (ImportState, опционально): Отслеживание состояния для предотвращения циклических импортов

Возвращает: Promise<ProcessImportsResult> - Объект с обработанным содержимым и деревом импортов

ProcessImportsResult

interface ProcessImportsResult {
  content: string; // Обработанное содержимое с разрешенными импортами
  importTree: MemoryFile; // Древовидная структура, показывающая иерархию импортов
}

MemoryFile

interface MemoryFile {
  path: string; // Путь к файлу
  imports?: MemoryFile[]; // Прямые импорты в порядке их подключения
}

validateImportPath(importPath, basePath, allowedDirectories)

Проверяет пути импорта, чтобы убедиться, что они безопасны и находятся в разрешенных директориях.

Параметры:

• importPath (string): Путь импорта для проверки
• basePath (string): Базовая директория для разрешения относительных путей
• allowedDirectories (string[]): Массив разрешенных путей директорий

Возвращает: boolean - Является ли путь импорта допустимым

findProjectRoot(startDir)

Находит корень проекта, выполняя поиск директории .git вверх по дереву, начиная с указанной стартовой директории. Реализована как async функция с использованием неблокирующих API файловой системы, чтобы избежать блокировки event loop в Node.js.

Параметры:

• startDir (string): Директория, с которой начинается поиск

Возвращает: Promise<string> - Директория корня проекта (или стартовая директория, если .git не найдена)

Рекомендации

1. Используйте понятные имена файлов для импортируемых компонентов
2. Держите импорты поверхностными — избегайте глубоко вложенных цепочек импортов
3. Документируйте структуру — поддерживайте четкую иерархию импортируемых файлов
4. Тестируйте импорты — убедитесь, что все указанные файлы существуют и доступны
5. Используйте относительные пути когда это возможно, для лучшей переносимости

Устранение неполадок

Частые проблемы

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

Режим отладки

Включите режим отладки, чтобы видеть подробный лог процесса импорта:

const result = await processImports(content, basePath, true);