Расширения¶

Koda CLI поддерживает расширения, которые можно использовать для настройки и расширения его функциональности.

Как это работает¶

При запуске Koda CLI ищет расширения в двух местах:

1. <workspace>/.kodacli/extensions
2. <home>/.kodacli/extensions

Koda CLI загружает все расширения из обоих мест. Если расширение с одинаковым именем существует в обоих местах, приоритет отдается расширению в рабочем каталоге.

В каждом месте отдельные расширения существуют в виде каталога, который содержит файл kodacli-extension.json. Например:

<workspace>/.kodacli/extensions/my-extension/kodacli-extension.json

kodacli-extension.json¶

Файл kodacli-extension.json содержит конфигурацию расширения. Файл имеет следующую структуру:

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "KODA.md",
  "excludeTools": ["run_shell_command"]
}

• name: Имя расширения. Используется для уникальной идентификации расширения и для разрешения конфликтов, когда команды расширения имеют такое же имя, как команды пользователя или проекта.
• version: Версия расширения.
• mcpServers: Карта серверов MCP для настройки. Ключ - это имя сервера, а значение - конфигурация сервера. Эти серверы будут загружаться при запуске, так же как серверы MCP, настроенные в файле settings.json. Если и расширение, и файл settings.json настраивают сервер MCP с одинаковым именем, приоритет имеет сервер, определенный в файле settings.json.
• contextFileName: Имя файла, который содержит контекст для расширения. Это будет использоваться для загрузки контекста из рабочей области. Если это свойство не используется, но файл KODA.md присутствует в каталоге расширения, то этот файл будет загружен.
• excludeTools: Массив имен инструментов, которые нужно исключить из модели. Вы также можете указать ограничения, специфичные для команд, для инструментов, которые их поддерживают, например, инструмент run_shell_command. Например, "excludeTools": ["run_shell_command(rm -rf)"] заблокирует команду rm -rf.

Когда Koda CLI запускается, он загружает все расширения и объединяет их конфигурации. Если есть какие-либо конфликты, приоритет имеет конфигурация рабочей области.

Команды расширений¶

Расширения могут предоставлять пользовательские команды, поместив файлы TOML в подкаталог commands/ внутри каталога расширения. Эти команды следуют тому же формату, что и пользовательские и проектные команды, и используют стандартные соглашения об именовании.

Пример¶

Расширение с именем gcp со следующей структурой:

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

Предоставит следующие команды:

• /deploy - Отображается как [gcp] Пользовательская команда из deploy.toml в справке
• /gcs:sync - Отображается как [gcp] Пользовательская команда из sync.toml в справке

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

Команды расширений имеют самый низкий приоритет. Когда возникает конфликт с командами пользователя или проекта:

1. Нет конфликта: Команда расширения использует свое естественное имя (например, /deploy)
2. Есть конфликт: Команда расширения переименовывается с префиксом расширения (например, /gcp.deploy)

Например, если и пользователь, и расширение gcp определяют команду deploy:

• /deploy - Выполняет команду deploy пользователя
• /gcp.deploy - Выполняет команду deploy расширения (отмечена тегом [gcp])

Установка расширений¶

Вы можете установить расширения с помощью команды install. Эта команда позволяет устанавливать расширения из Git-репозитория или локального пути.

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

koda extensions install <source> | [options]

Параметры¶

• source <url> positional argument: URL Git-репозитория, из которого нужно установить расширение. Репозиторий должен содержать файл kodacli-extension.json в корне.
• --path <path>: Путь к локальному каталогу для установки расширения. Каталог должен содержать файл kodacli-extension.json.

Переменные¶

Расширения Koda CLI поддерживают подстановку переменных в kodacli-extension.json. Это полезно, например, если нужно использовать текущий путь расширения в "cwd": "${extensionPath}${/}run.ts".

Поддерживаемые переменные: