Файлы и скрипты шаблона

Стартовый шаблон рабочего пространства доставляет файлы из files/ в рабочую директорию /workspace/code. Скрипты из scripts/ выполняют настройку после доставки файлов. Примеры ниже изменяют существующий стартовый шаблон.

Добавление файла в рабочую директорию

Например, чтобы каждое пространство получало настройки редактора:

1. Откройте шаблон, вкладку «Файлы», и его черновик.

2. Нажмите «Добавить файл» и укажите путь files/.vscode/settings.json. Можно также использовать «Загрузить файлы» для текстовых файлов в UTF-8; проверьте путь каждого загруженного файла.

3. Заполните файл:

   {
     "editor.formatOnSave": true,
     "files.insertFinalNewline": true,
     "files.trimTrailingWhitespace": true
   }

4. Нажмите «Сохранить», опубликуйте и активируйте новую версию.

5. Создайте рабочее пространство из этой версии и откройте IDE.

В рабочей директории появится /workspace/code/.vscode/settings.json. Префикс files/ в целевой путь не входит. Вложенные директории создаются автоматически.

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

Файл с сохранением пользовательских изменений

Чтобы выдать исходные инструкции агенту и разрешить владельцу менять их, создайте files/AGENTS.md или измените уже существующий файл:

# Project instructions

Read README.md before changing the project.
Run the tests related to changed files.
Show the test results and changed files in the final response.

В существующем блоке locals файла main.tf задайте политику по пути относительно files/:

file_policies = {
  "AGENTS.md"             = "create_if_missing"
  ".vscode/settings.json" = "create_if_missing"
}

Политика create_if_missing создаёт файл, только если его ещё нет в рабочей директории. Существующий файл, в том числе полученный из Git, сохраняется. Изменение файла в новой версии шаблона не заменяет пользовательскую копию.

Политики действуют следующим образом:

В штатном шаблоне AGENTS.md уже имеет политику create_if_missing. Для остальных файлов без явной политики используется managed.

Первоначальная настройка нового тома

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

1. Добавьте файл files/config/application.example.json:

   {
     "listen": "0.0.0.0:8080",
     "logLevel": "info"
   }

2. Добавьте файл scripts/create.sh:

   #!/usr/bin/env bash
   set -euo pipefail
   
   mkdir -p .local/results
   if [ ! -e config/application.json ]; then
     cp config/application.example.json config/application.json
   fi

3. Сохраните файлы, опубликуйте и активируйте версию.

4. Создайте рабочее пространство и проверьте директорию .local/results и файл config/application.json.

Скрипт выполняется из рабочей директории после клонирования репозитория, доставки файлов и подготовки навыков. После успешного выполнения на томе сохраняется отметка; повторный запуск на том же томе пропускает create.sh. Если скрипт завершится ошибкой, следующая попытка повторит его, поэтому проверяйте существование уже созданных файлов.

Добавление create.sh в новую версию шаблона не повторяет уже успешно выполненную первоначальную настройку существующего тома. Для настройки при каждом запуске используйте start.sh.

Настройка при каждом запуске

Чтобы проверять конфигурацию и создавать временные директории после каждого запуска пода, добавьте scripts/start.sh:

#!/usr/bin/env bash
set -euo pipefail

mkdir -p .local/cache
test -s config/application.json
printf 'Workspace configuration is ready\n'

В этом примере сначала добавьте create.sh и начальный файл из предыдущего примера. При успешном запуске контейнер bootstrap выведет Workspace configuration is ready.

Скрипт выполняется до старта агента и IDE. Команды должны завершаться; не запускайте в нём сервер, который занимает процесс навсегда. Ошибка скрипта препятствует готовности пода и отображается в логе bootstrap на вкладке «Диагностика».

Штатный под работает с UID/GID 10000, без повышения привилегий и с корневой файловой системой только для чтения. Размещайте рабочие данные и устанавливаемые инструменты на постоянном томе. Пример установки Go и настройки окружения агента и IDE — в руководстве по инструментам разработки.

Применение изменений к существующему пространству

Чтобы существующее пространство получило новые файлы:

1. Опубликуйте новую версию шаблона.
2. Остановите рабочее пространство.
3. Обновите его до новой версии и дождитесь успешной операции.
4. Запустите рабочее пространство.
5. Проверьте файлы в IDE и лог контейнера bootstrap.

Для managed применится новое содержимое. Для create_if_missing сохранится существующий файл. Активация версии шаблона сама по себе не меняет файлы уже созданных пространств.