Правка apps.json: где он находится, как его обновить и восстановить

Каждое приложение, которым управляет Moonpool, - это одна запись в apps.json. Править её можно в редакторе приложения (диалог «Добавить приложение» и «Изменить приложение») или вручную. Оба способа пишут в один и тот же файл. В некоторых результатах инструментов и сообщениях этот файл называется манифестом.

Где находится конфигурация

Режим	Папка конфигурации
Установленный (Windows)	%USERPROFILE%\.moonpool\moonpool-config\
Портативный	moonpool-config\ рядом с moonpool.exe (внутри папки .moonpool\)
Linux	$XDG_CONFIG_HOME/Moonpool/, иначе ~/.config/Moonpool/

apps.json лежит в этой папке рядом со следующими элементами:

Элемент	Назначение
apps.json.history\	Кольцо отката из последних 10 корректных файлов apps.json.
settings.json	Настройки приложения. См. settings.json.
cli-output\<id>\	Журналы сеансов каждого приложения. См. Журналы.
moonpool.log	Журнал отладки, пока включён параметр Записывать отладочные данные в файл.
icons\	Необязательные переопределения значков <id>.png (также .ico, .svg, .jpg, .jpeg, .webp).
state.json	Снимок текущего состояния, обновляется раз в пару секунд.
dumps\	Файлы, которые записывают команды dump, read-config и restore-config.
mcp_seen.json	Для каких приложений уже использовался MCP-помощник.
window-state.json	Размер и положение окна-хаба.
AI-README.md	Руководство для ИИ-агентов, перезаписывается при каждом запуске.

Что из этого включать в резервную копию, описано в разделе Резервное копирование и восстановление.

При первом запуске Moonpool заполняет apps.json примерами записей. Уже существующий файл никогда не перезаписывается.

Правка

• Диалог. Используйте Добавить приложение в меню … вверху боковой панели. Чтобы изменить приложение, нажмите на карандаш в его строке или щёлкните по нему правой кнопкой и выберите Изменить. Диалог проверяет и сохраняет сразу.
• Вручную. Изменить apps.json в том же меню открывает файл в вашем редакторе по умолчанию. Сохраните его, затем выберите Обновить в меню (или нажмите F5 либо Ctrl+R).

Правки вручную не подхватываются, пока вы не обновите список. Обновление только читает файл и не переписывает его.

Сохранение из диалога переписывает весь файл в нормализованном виде с отступами. Неизвестные Moonpool ключи отбрасываются, а в JSON нет комментариев, поэтому заметки храните в поле note.

Структура

Файл - это массив объектов JSON. В каждой записи обязательны четыре ключа: id, name, group, type. Всё остальное необязательно. См. Поля приложения.

apps.json

[
  { "id": "site", "name": "Site", "group": "Web apps", "type": "web",
    "cwd": "C:\\code\\site", "command": "npm run dev", "port": 5173,
    "url": "http://localhost:5173", "openBrowser": true }
]

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

Что делает обновление

Обновление заменяет список Moonpool в памяти содержимым файла. Запуск, остановка и перезапуск читают запись в момент нажатия, поэтому изменённые command, cwd, env или параметры завершения применяются при следующем запуске или перезапуске этого приложения. Обновление никогда ничего не перезапускает: уже работающее приложение продолжает работать с теми настройками, с которыми запустилось.

Проверка

Moonpool проверяет весь файл при загрузке, при каждом сохранении и при каждой записи агентом. Одна неверная запись приводит к отклонению всего файла.

Правило	Ошибка содержит
Недопустимый JSON, отсутствует обязательный ключ или у значения неверный тип	сообщение разборщика JSON
id пуст, начинается с - или содержит символы, кроме букв, цифр, ., _, -	invalid id
У двух записей одинаковый id	duplicate app id
name пусто	has an empty name
group пуста	has an empty group
type не равен desktop, web, static или cli	unknown type
port равен 0 (port больше 65535 не разбирается)	invalid port 0
Запись static без url	requires a url
Любой другой тип без command	requires a command

Ошибки указывают запись по номеру, например:

apps.json entry 2 (site) requires a command

Идентификатор id

id - это постоянный ключ записи. По нему называются папка журналов и файл значка, и именно его вы передаёте в moonpool.exe launch <id> и агентам. Диалог выводит его из названия при добавлении приложения. Он приводит название к нижнему регистру, превращает каждую последовательность символов, кроме a-z и 0-9, в один - и обрезает - с обоих концов. Пустой результат становится app. Если такой id занят, добавляются -2, -3 и так далее. Потом id никогда не меняется, поэтому переименование приложения сохраняет его id. Название Habit Tracker даёт id habit-tracker.

Если файл повреждён

• При обновлении файл, не прошедший проверку, остаётся нетронутым, а Moonpool сохраняет последний загруженный список. Баннер над боковой панелью показывает ошибку и кнопку открытия файла; список остаётся рабочим, но затемнённым. См. Когда в apps.json ошибка.
• При запуске повреждённый файл означает, что сохранять нечего, поэтому Moonpool запускается без приложений, о чём сообщает баннер. Исправьте файл и выберите Обновить либо восстановите снимок (ниже или инструментом moonpool_restore_config).
• В обоих случаях сохранения из диалога (а также переименование, удаление, выбор значка) отклоняются, пока файл снова не загрузится, поэтому повреждённый файл никогда не будет перезаписан. Исправьте файл и выберите Обновить.
• Из диалога, от агента или при восстановлении недопустимое изменение отклоняется, а файл на диске остаётся прежним.

Moonpool хранит последние 10 рабочих версий apps.json в apps.json.history\. Как выполнить откат, описано в разделе Резервное копирование и восстановление. Симптомы и решения приведены в разделе Устранение неполадок.

Агенты

ИИ-агент должен менять apps.json через MCP-инструменты Moonpool, а не через файл, чтобы устаревшая или недопустимая запись отклонялась, а агент в песочнице не правил частную копию. См. Инструменты MCP.