Расширения¶

Расширение — это каталог, который добавляет в Koda CLI MCP-серверы, файлы контекста, пользовательские слеш-команды, навыки и ограничения инструментов.

Где CLI ищет расширения¶

Если расширение с одинаковым name есть в обеих областях, версия из рабочей области имеет приоритет.

Команды управления¶

koda extensions install <git-url>
koda extensions install --path ./local-extension
koda extensions uninstall <name>
koda extensions list
koda extensions update <name>
koda extensions enable <name> --scope User
koda extensions disable <name> --scope Workspace

Команда install принимает ссылку на git-репозиторий или локальный путь. Локальный каталог должен содержать kodacli-extension.json.

Манифест kodacli-extension.json¶

Каждое расширение должно содержать kodacli-extension.json:

{
  "name": "example-extension",
  "version": "1.0.0",
  "contextFileName": ["KODA.md", "AGENTS.md"],
  "mcpServers": {
    "example": {
      "command": "node",
      "args": ["${extensionPath}${/}server.js"]
    }
  },
  "excludeTools": ["run_shell_command"]
}

Обязательные поля:

Опциональные поля:

Если contextFileName не задан, но файл KODA.md присутствует в каталоге расширения, он будет загружен.

MCP-серверы из настроек¶

MCP-серверы из settings.json имеют приоритет над серверами расширений. Если сервер с тем же ключом определён и в настройках, и в расширении, используется версия из настроек, а конфигурация расширения пропускается.

Принцип наименьших привилегий¶

Разрешайте MCP-серверу только те возможности, которые нужны для работы. Если расширение использует мощные инструменты вроде run_shell_command, ограничьте их через excludeTools — тогда CLI заблокирует опасные команды, даже если модель попытается их выполнить.

MCP-сервер работает на машине пользователя, поэтому проверяйте входные данные инструментов: валидируйте пути, запрещайте произвольное выполнение кода и несанкционированный доступ к файловой системе.

Имя расширения¶

Поле name — это уникальный идентификатор расширения. Он используется для разрешения конфликтов, когда команды расширения совпадают с пользовательскими или проектными командами.

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

Переменные в конфигурации¶

В kodacli-extension.json поддерживаются подстановки:

Подстановка выполняется во всех строках конфигурации, включая command, args и cwd. Разделяйте исполняемый файл и его аргументы через command и args, а не вкладывайте их в одну строку command.

Пример:

{
  "command": "node",
  "args": ["${extensionPath}${/}dist${/}server.js"]
}

Слеш-команды расширения¶

Расширение может добавить TOML-команды в commands/:

.kodacli/extensions/foo/
├── kodacli-extension.json
└── commands/
    ├── deploy.toml
    └── gcs/
        └── sync.toml

Команды будут доступны как /deploy и /gcs:sync, если имена не конфликтуют с пользовательскими или проектными командами. При конфликте команда расширения получает префикс имени расширения, например /foo.deploy.

Формат TOML описан в командах CLI.

Разрешение конфликтов¶

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

Если команда не отвечает, проверьте, не перекрыта ли она командой более высокого приоритета, и вызовите её по префиксному имени (например, /foo.deploy).

Навыки в расширениях¶

Если расширение содержит каталог skills/ или .agents/skills/, Koda CLI загрузит найденные SKILL.md так же, как пользовательские навыки. Это удобный способ распространять вместе команды, MCP-сервер и инструкции агента. Подробнее о навыках — на странице навыки агента.

Исключение инструментов¶

Расширение может скрыть от модели отдельные инструменты через поле excludeTools. Значения из всех активных расширений объединяются с глобальным excludeTools из настроек, поэтому скрытие работает на уровне всей сессии.

{
  "name": "example-extension",
  "version": "1.0.0",
  "excludeTools": ["run_shell_command"]
}

В поле excludeTools можно указывать как имя инструмента целиком, так и элементы с уточнением, например run_shell_command(rm).

MCP-промпты в расширениях¶

Из MCP-серверов, подключённых расширением, Koda CLI использует не только инструменты, но и промпты (prompts/list). Они попадают в реестр промптов и могут быть вызваны моделью, если сервер их объявляет.

Метаданные установки¶

При установке CLI создаёт служебный файл .kodacli-extension-install.json с полями source и type:

{
  "source": "https://github.com/example/foo.git",
  "type": "git"
}

Файл нужен командам update и uninstall, поэтому редактировать его вручную не стоит.

Создание собственного расширения¶

Расширение создаётся вручную: каталог с корректным манифестом размещается в одной из директорий поиска или устанавливается командой koda extensions install.

Шаг 1. Структура каталога¶

├── kodacli-extension.json
├── KODA.md                  # context-файл (необязательно)
├── server.js                # источник MCP-сервера (необязательно)
├── commands/
│   └── greeting.toml        # слеш-команда (необязательно)
└── skills/
    └── my-skill/
        └── SKILL.md         # навык агента (необязательно)

Расширение может состоять только из манифеста и любого сочетания остальных частей. Как минимум нужен kodacli-extension.json с name и version.

Шаг 2. Манифест¶

Создайте kodacli-extension.json в корне каталога. Обязательные поля — name и version.

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "contextFileName": "KODA.md",
  "mcpServers": {
    "example": {
      "command": "node",
      "cwd": "${extensionPath}",
      "args": ["${extensionPath}${/}server.js"]
    }
  }
}

Для MCP-сервера доступны параметры command, args, cwd, env, timeout, trust, а также сетевые url, httpUrl, headers и OAuth-конфигурация. Имя сервера (example) задаёт префикс его инструментов и промптов.

Для переносимости между операционными системами всегда используйте ${extensionPath} для ссылок на файлы внутри расширения.

Шаг 3. Context-файл и слеш-команды¶

Поместите инструкции агента в файл из contextFileName (по умолчанию KODA.md, если он есть). Команды из commands/ описываются в TOML, как описано в Слеш-командах расширения.

description = "Поприветствовать пользователя"
prompt = """
Ответь на приветствие, после чего спроси, чем помочь в этом проекте.
"""

Шаг 4. Установка и проверка¶

Локальное расширение устанавливается через --path, git-репозиторий — через URL:

koda extensions install --path ./my-first-extension
koda extensions install https://github.com/example/my-first-extension.git

Установка копирует каталог в ~/.kodacli/extensions/<name>, создаёт метаданные и включает расширение. Для локальной разработки достаточно переустановить расширение после изменений либо разместить его вручную в директории поиска — изменения подхватятся после перезапуска сессии.

Убедитесь, что расширение видно и активно:

koda extensions list

Распространение расширения¶

Готовое расширение удобно распространять как git-репозиторий, чтобы его можно было установить по URL — так же, как каталог расширений Gemini. В репозитории в корне должен лежать kodacli-extension.json, а сам каталог расширения может иметь любое имя — при установке он сохраняется под именем из манифеста.

Структура сложного расширения¶

Для больших проектов поддерживайте разделение исходников и сборки:

├── package.json
├── tsconfig.json
├── kodacli-extension.json
├── src/
│   ├── index.ts
│   └── tools/
└── dist/

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

• Используйте TypeScript для проверки типов и лучшего опыта разработки;
• держите исходники в src/, а артефакты сборки — в dist/;
• при большом количестве зависимостей собирайте их в один бандл (например, esbuild), чтобы быстрее устанавливать расширение и избегать конфликтов.

Тестирование расширения¶

Перед выпуском проверьте расширение в реальной сессии:

• установите расширение и перезапустите CLI;
• убедитесь, что инструменты появились у модели, а слеш-команды резолвятся;
• если расширение включает MCP-сервер, напишите unit-тесты для логики инструментов (например, Vitest или Jest), изолировав транспорт MCP моком.

Диагностика проблем¶

Расширение не загружается¶

• Проверьте, что kodacli-extension.json лежит в корне каталога и содержит валидный JSON;
• проверьте в логах CLI предупреждение о причине пропуска расширения (неверный манифест, отсутствие name или version);
• не переименовывайте вручную каталог установленного расширения — при установке он сохраняется под именем из name, и по нему работают update и uninstall;
• перезапустите CLI — расширения загружаются при старте сессии.

MCP-сервер не запускается¶

• Посмотрите логи CLI — там будет причина падения сервера;
• запустите command и args сервера вручную в терминале, чтобы убедиться, что он стартует вне CLI.

Команда не отвечает¶

• Помните про приоритет: пользовательские и проектные команды перекрывают команды расширений;
• вызовите команду по префиксному имени (например, /foo.deploy);
• просмотрите список доступных команд через /help.

Версионирование¶

Следуйте Semantic Versioning:

• Major — ломающие изменения (переименование инструментов, изменение аргументов);
• Minor — новые возможности (новые инструменты или команды);
• Patch — исправления ошибок и улучшения производительности.

Используйте ветки для каналов релизов, чтобы пользователь мог выбирать между стабильной версией и новыми возможностями. Команда koda extensions update <name> обновляет установленное расширение до версии из source его метаданных.