Jinni: добавьте контекст в свой проект

Jinni — это инструмент для эффективного предоставления Large Language Models контекста ваших проектов. Он дает консолидированное представление соответствующих файлов проекта, преодолевая ограничения и неэффективность чтения файлов по одному. Содержимому каждого файла предшествует простой заголовок, указывающий его путь:

```path=src/app.py
print("hello")

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

Имеется сервер MCP (Model Context Protocol) для интеграции с инструментами искусственного интеллекта и утилита командной строки (CLI) для ручного использования, которая копирует контекст проекта в буфер обмена, готовый к вставке в нужное место.

Эти инструменты имеют собственное мнение о том, что считается соответствующим контекстом проекта, чтобы наилучшим образом работать сразу после установки в большинстве случаев использования, автоматически исключая:

* Binary files
* Dotfiles and hidden directories
* Common naming conventions for logs, build directories, tempfiles, etc

При необходимости включения/исключения можно настраивать с полной детализацией с помощью .contextfiles — это работает так же, как .gitignore, за исключением определения включений.

Сервер MCP может предоставить столько проекта, сколько необходимо. По умолчанию областью действия является весь проект, но модель может запросить определенные модули / шаблоны соответствия / и т. д.

MCP Быстрый старт

Файл конфигурации сервера MCP для Cursor / Roo / Claude Desktop / клиента по выбору:

{
    "mcpServers": {
        "jinni": {
            "command": "uvx",
            "args": ["jinni-server"]
        }
    }
}

При желании вы можете ограничить сервер чтением только из дерева в целях безопасности на случай, если ваш LLM выйдет из-под контроля: добавьте "--root", "/absolute/path/" в список args .

Установите uv, если его нет в вашей системе: https://docs.astral.sh/uv/getting-started/installation/

Перезагрузите IDE, и теперь вы можете попросить агента прочитать контекст.

Если вы хотите ограничить это определенными модулями/путями, просто укажите, например, «Читать контекст для тестов».

В действии с курсором:

Примечание для пользователей курсора

Курсор может молча сбрасывать контекст, который больше допустимого максимума, поэтому, если у вас большой проект и агент ведет себя так, как будто вызов инструмента никогда не происходил, попробуйте уменьшить то, что вы вносите («прочитать контекст для xyz»).

Компоненты

Сервер jinni MCP:
- Интегрируется с клиентами MCP, такими как Cursor, Cline, Roo, Claude Desktop и т. д.
- Предоставляет инструмент read_context , который возвращает объединенную строку соответствующего содержимого файла из указанного каталога проекта.
jinni CLI:
- Инструмент командной строки для ручного создания дампа контекста проекта.
- Полезно для передачи контекста LLM через копирование-вставку или входной файл. Или перенаправьте вывод туда, где он вам нужен.

Функции

Эффективный сбор контекста: считывает и объединяет соответствующие файлы проекта за одну операцию.
Интеллектуальная фильтрация (включение в стиле Gitignore):
- Использует систему, основанную на синтаксисе .gitignore ( gitwildmatch библиотеки pathspec ).
- Поддерживает иерархическую конфигурацию с использованием .contextfiles , размещенных в каталогах вашего проекта. Правила применяются динамически на основе обрабатываемого файла/каталога.
- Поведение сопоставления: Шаблоны сопоставляются с путем относительно обрабатываемого целевого каталога (или корня проекта, если не указана конкретная цель). Например, если нацелен на src/ , правило !app.py в src/.contextfiles будет соответствовать app.py . Выходные пути остаются относительно исходного корня проекта.
- Переопределения: Поддерживает --overrides (CLI) или rules (MCP) для использования определенного набора правил исключительно. Когда переопределения активны, как встроенные правила по умолчанию, так и любые .contextfiles игнорируются. Сопоставление путей для переопределений по-прежнему относительно целевого каталога.
- Явное включение цели: Файлы, явно указанные в качестве целей, всегда включаются (обходя проверки правил, но не проверки двоичности/размера). Каталоги, явно указанные в качестве целей, всегда вводятся, и затем обнаружение/сопоставление правил выполняется относительно этого целевого каталога.
Настраиваемая конфигурация ( .contextfiles / Overrides):
- Точно определите, какие файлы/каталоги следует включить или исключить, используя шаблоны в стиле .gitignore применяемые к относительному пути .
- Шаблоны, начинающиеся с ! , отрицают совпадение (шаблон исключения). (См. раздел «Конфигурация» ниже).
Обработка большого контекста: прерывается с DetailedContextSizeError , если общий размер включенных файлов превышает настраиваемый предел (по умолчанию: 100 МБ). Сообщение об ошибке включает список из 10 самых больших файлов, влияющих на размер, что помогает вам определить кандидатов на исключение. См. раздел «Устранение неполадок» для получения рекомендаций по управлению размером контекста.
Заголовки метаданных: вывод включает заголовок пути для каждого включенного файла (например, ````path=src/app.py ). This can be disabled with list_only`.
Обработка кодировок: пытается использовать несколько распространенных кодировок текста (UTF-8, Latin-1 и т. д.).
Режим «Только список»: возможность перечислить только относительные пути файлов, которые будут включены, без их содержимого.

Использование

MCP-сервер (инструмент `read_context` )

Настройка: Настройте клиент MCP (например, claude_desktop_config.json от Claude Desktop) для запуска сервера jinni через uvx .
Вызов: при взаимодействии с вашим LLM через клиент MCP модель может вызвать инструмент read_context .
- project_root (string, required): Абсолютный путь к корневому каталогу проекта. Пути обнаружения и вывода правил относительны этого корня.
- targets (JSON-массив строк, обязательно): указывает обязательный список файлов/каталогов в project_root для обработки. Должен быть JSON-массивом строковых путей (например, ["path/to/file1", "path/to/dir2"] ). Пути могут быть абсолютными или относительными к CWD. Все целевые пути должны разрешаться в местоположения внутри project_root . Если указан пустой список [] , обрабатывается весь project_root .
- rules (JSON-массив строк, обязательно): обязательный список встроенных правил фильтрации (используя синтаксис в стиле .gitignore , например, ["src/**/*.py", "!*.tmp"] ). Укажите пустой список [] если не требуется никаких конкретных правил (будут использоваться встроенные значения по умолчанию). Если он непустой, эти правила используются исключительно, игнорируя встроенные значения по умолчанию и .contextfiles .
- list_only (логическое значение, необязательное): если true, возвращает только список относительных путей к файлам вместо содержимого.
- size_limit_mb (целое число, необязательно): переопределить ограничение размера контекста в МБ.
- debug_explain (логическое значение, необязательно): включить ведение журнала отладки на сервере.
1. Вывод: Инструмент возвращает одну строку, содержащую объединенный контент (с заголовками) или список файлов. Пути в заголовках/списках указываются относительно предоставленного project_root . В случае ошибки размера контекста он возвращает DetailedContextSizeError с подробностями о самых больших файлах.

MCP Server (инструмент `usage` )

Вызов: модель может вызывать инструмент usage (аргументы не требуются).
Вывод: Возвращает содержимое файла README.md в виде строки.

(Подробные инструкции по настройке сервера будут различаться в зависимости от вашего клиента MCP. Как правило, вам необходимо настроить клиент для запуска сервера Jinni.)

Запуск сервера:

Рекомендуемый метод: используйте uvx для непосредственного запуска точки входа на сервер (необходимо, чтобы пакет jinni был опубликован в PyPI или мог быть найден uvx ):
uvx jinni-server [OPTIONS]
Пример конфигурации клиента MCP (например, claude_desktop_config.json ):
{ "mcpServers": { "jinni": { "command": "uvx", "args": ["jinni-server"] } } }

Точные шаги настройки см. в документации вашего клиента MCP. Убедитесь, что uv установлен

Утилита командной строки ( `jinni` CLI)

jinni [OPTIONS] [<PATH...>]

<PATH...> (необязательно): Один или несколько путей к каталогам проекта или файлам для анализа. По умолчанию используется текущий каталог ( . ), если ничего не указано.
-r <DIR> / --root <DIR> (необязательно): Укажите корневой каталог проекта. Если указан, обнаружение правил начинается здесь, а выходные пути относительны этого каталога. Если пропущен, корень выводится из общего предка аргументов <PATH...> (или CWD, если обрабатывается только '.').
--output <FILE> / -o <FILE> (необязательно): Записать вывод в <FILE> вместо вывода на стандартный вывод.
--list-only / -l (необязательно): вывести только относительные пути файлов, которые будут включены.
--overrides <FILE> (необязательно): использовать правила из <FILE> вместо обнаружения .contextfiles .
--size-limit-mb <MB> / -s <MB> (необязательно): Переопределить максимальный размер контекста в МБ.
--debug-explain (необязательно): вывести подробные причины включения/исключения в stderr и jinni_debug.log .
--root <DIR> / -r <DIR> (необязательно): см. выше.
--no-copy (необязательно): предотвратить автоматическое копирование выходного содержимого в системный буфер обмена при печати на стандартный вывод (по умолчанию копирование).

Установка

Вы можете установить Jinni с помощью pip или uv :

Используя pip:

pip install jinni

Использование УФ:

uv pip install jinni

Это сделает команду jinni CLI доступной в вашей среде. См. раздел «Запуск сервера» выше, чтобы узнать, как запустить сервер MCP в зависимости от вашего метода установки.

Заметки, специфичные для платформы

Окна + WSL

Jinni v0.1.7+ автоматически преобразует пути WSL.

Укажите любой из них в качестве project_root (аргумент CLI --root или MCP):

/home/user/project
vscode-remote://wsl+Ubuntu-22.04/home/user/project

Никаких оболочек, монтирований или дополнительных флагов не требуется — Jinni автоматически разрешает путь UNC ( \\wsl$\... ) в Windows.

Формат пути UNC: Jinni всегда использует \\wsl$\<distro>\... для максимальной совместимости со всеми версиями Windows, поддерживающими WSL. Обработка имени дистрибутива: в имени дистрибутива разрешены пробелы и большинство специальных символов. Только действительно недопустимые символы UNC заменяются на _ . Кэширование: поиск и преобразование пути WSL кэшируются для повышения производительности. Если вы устанавливаете WSL во время работы Jinni, перезапустите Jinni, чтобы использовать новый wslpath . Отказ: установите переменную среды JINNI_NO_WSL_TRANSLATE=1 чтобы отключить всю логику преобразования пути WSL.

Транслируются только URI wsl+<distro> и абсолютные пути POSIX (начинающиеся с / ); для удаленных SSH или контейнеров запустите Jinni внутри этой среды.

ОС времени выполнения	Что вы передаете	Что возвращает `_translate_wsl_path()`
Окна	`vscode-remote://wsl+Ubuntu/home/a/b`	`\\wsl$\\Ubuntu\home\a\b`
Окна	`/home/a/b`	`\\wsl$\\Ubuntu\home\a\b` (через wslpath)
Linux/WSL	`vscode-remote://wsl+Ubuntu/home/a/b`	`/home/a/b`
Linux/WSL	`/home/a/b`	`/home/a/b` (без изменений)

Примеры

Вывести контекст my_project/ на консоль:
jinni ./my_project/ # Process a single directory jinni ./src ./docs/README.md # Process multiple targets jinni # Process current directory (.)
Список файлов, которые будут включены в my_project/ без содержимого:
jinni -l ./my_project/ jinni --list-only ./src ./docs/README.md
Сохраните контекст my_project/ в файл с именем context_dump.txt :
jinni -o context_dump.txt ./my_project/
Используйте правила переопределения из custom.rules вместо .contextfiles :
jinni --overrides custom.rules ./my_project/
Показать отладочную информацию:
jinni --debug-explain ./src
Контекст дампа (по умолчанию вывод автоматически копируется в буфер обмена):
jinni ./my_project/
Сделать дамп контекста, но не копировать в буфер обмена:
jinni --no-copy ./my_project/

Конфигурация ( `.contextfiles` и переопределения)

Jinni использует .contextfiles (или файл переопределения) для определения того, какие файлы и каталоги следует включить или исключить, на основе шаблонов в стиле .gitignore .

Основной принцип: правила применяются динамически во время обхода относительно текущего обрабатываемого целевого каталога.
Расположение ( .contextfiles ): Поместите .contextfiles в любой каталог. При обработке каталога (либо исходного целевого, либо подкаталога) Jinni ищет .contextfiles , начиная с этого каталога и далее вниз. Правила из родительских каталогов за пределами текущего целевого каталога игнорируются при обработке внутри этого целевого каталога.
Формат: простой текст в кодировке UTF-8, один шаблон на строку.
Синтаксис: использует стандартный синтаксис шаблона .gitignore (в частности, реализацию gitwildmatch``pathspec ).
- Комментарии: Строки, начинающиеся с # игнорируются.
- Шаблоны включения: укажите файлы/каталоги для включения (например, src/**/*.py , *.md , /config.yaml ).
- Шаблоны исключения: строки, начинающиеся с ! указывают, что соответствующий файл следует исключить (отменяет шаблон).
- Привязка: начальный символ / привязывает шаблон к каталогу, содержащему .contextfiles .
- Соответствие каталогам: завершающий символ / соответствует только каталогам.
- Подстановочные знаки: * , ** , ? работают как в .gitignore .
Логика применения правила:
1. Определение цели: Jinni определяет целевой каталог (либо явно указанный, либо корневой каталог проекта).
2. Проверка переопределения: Если указаны --overrides (CLI) или rules (MCP), то используются исключительно эти правила. Все .contextfiles и встроенные значения по умолчанию игнорируются. Сопоставление путей выполняется относительно целевого каталога.
3. Правила динамического контекста (без переопределений): При обработке файла или подкаталога в целевом каталоге:
  - Jinni находит все .contextfiles , начиная с целевого каталога и заканчивая каталогом текущего элемента.
  - Он объединяет правила из обнаруженных .contextfiles файлов со встроенными правилами по умолчанию.
  - Он компилирует эти объединенные правила в спецификацию ( PathSpec ).
  - Он сопоставляет текущий путь к файлу/подкаталогу, рассчитанный относительно целевого каталога , с этой спецификацией.
4. Сопоставление: последний шаблон в объединенном наборе правил, который соответствует относительному пути элемента, определяет его судьбу. ! отменяет соответствие. Если ни один определенный пользователем шаблон не соответствует, элемент включается, если только он не соответствует встроенному исключению по умолчанию (например !.* ).
5. Обработка целей: явно целевые файлы обходят проверки правил. Явно целевые каталоги становятся корнем для обнаружения правил и сопоставления их содержимого. Выходные пути всегда остаются относительно исходного project_root .

Примеры ( `.contextfiles` )

Пример 1: включение исходного кода Python и корневой конфигурации

Расположено в my_project/.contextfiles :

# Include all Python files in the src directory and subdirectories
src/**/*.py

# Include the main config file at the root of the project
/config.json

# Include all markdown files anywhere
*.md

# Exclude any test data directories found anywhere
!**/test_data/

Пример 2: Переопределение в подкаталоге

Расположено по адресу my_project/src/.contextfiles :

# In addition to rules inherited from parent .contextfiles...

# Include specific utility scripts in this directory
utils/*.sh

# Exclude a specific generated file within src, even if *.py is included elsewhere
!generated_parser.py

Разработка

Подробности дизайна: DESIGN.md
Запуск сервера локально: во время разработки (после установки с помощью uv pip install -e . или аналогичной команды) вы можете запустить модуль сервера напрямую:
python -m jinni.server [OPTIONS]
Пример конфигурации клиента MCP для локальной разработки:
{ "mcpServers": { "jinni": { // Adjust python path if needed, or ensure the correct environment is active "command": "python -m jinni.server" // Optionally constrain the server to only read within a tree (recommended for security): // "command": "python -m jinni.server --root /absolute/path/to/repo" } } }

Поиск неисправностей

Ошибки размера контекста ( `DetailedContextSizeError` )

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

Чтобы решить эту проблему:

Просмотрите самые большие файлы: проверьте список, предоставленный в сообщении об ошибке. Есть ли большие файлы (например, файлы данных, журналы, артефакты сборки, медиа), которые не должны быть частью контекста LLM?
Настройте исключения: используйте .contextfiles или параметры --overrides / rules , чтобы исключить ненужные файлы или каталоги.
- Пример ( .contextfiles ): Чтобы исключить все файлы .log и определенный большой каталог данных:
  # Exclude all log files !*.log # Exclude a large data directory !large_data_files/
- Подробную информацию о синтаксисе и использовании см. в разделе «Конфигурация» выше.
Увеличьте лимит (используйте с осторожностью): Если все включенные файлы действительно необходимы, вы можете увеличить лимит размера с помощью --size-limit-mb (CLI) или size_limit_mb (MCP). Помните об ограничениях окна контекста LLM и затратах на обработку.
Используйте jinni usage / usage : если вам необходимо вернуться к этим инструкциям или сведениям о конфигурации при устранении неполадок, используйте команду jinni usage или инструмент MCP usage .

Jinni: Bring Your Project Into Context