Конструктор команд (developer notes)

GUI-надстройка для редактирования commands.yaml без ручной правки YAML. Запускается отдельным процессом, не зависит от рантайма Jarvis.

Запуск

python -m tools.command_builder

или из корня репо run_builder.bat.

Стек

pywebview (бэкенд EdgeWebView2 на Windows) — оборачивает локальный HTML.
Frontend — vanilla JS + CSS, без сборки. Vendored js-yaml только для предпросмотра YAML на стороне UI.
ruamel.yaml — чтение/запись commands.yaml с сохранением комментариев и форматирования.
pyautogui — рантайм для action-типа keys.

Структура

tools/command_builder/
  __main__.py        точка входа python -m
  app.py             pywebview bootstrap + Python bridge (js_api)
  schema.py          dataclass-схема action-блоков и валидация
  yaml_writer.py     atomic write + .bak бэкап перед каждой записью
  llm_suggest.py     Groq/OpenAI SDK 1.x, response_format=json_object
  web/               frontend
  tests/             pytest для schema + writer

Bridge API (методы класса `Bridge` в `app.py`)

Все методы возвращают сериализуемые структуры. Ошибки идут как {"ok": false, "error": "..."}.

метод	назначение
`list_existing_commands()`	список ключей верхнего уровня в `commands.yaml`
`list_exes()`	basename'ы `*.exe` из `custom-commands/`
`list_sound_names()`	разрешённые имена для `play_sound` (из `schema.VALID_SOUND_NAMES`)
`preview_sound(name)`	проигрывает звук в фоновом потоке через `simpleaudio`
`slugify(phrase)`	транслит для генерации `cmd_id`
`validate_draft(json_str)`	прогон через `command_from_dict`
`save_command(json_str)`	append/upsert + бэкап (`overwrite: true` чтобы перезаписать)
`llm_suggest(prompt)`	Groq → JSON → провалидированный action-блок

Расширение схемы (новый тип action)

В schema.py: добавить dataclass с полем type и методом to_dict(). Включить в Union Action. Расширить action_from_dict().
В tests/test_schema.py: добавить roundtrip + negative-case тесты.
В web/app.js:
- карточка в #action-grid (index.html);
- ветка в renderActionForm();
- ветка в updateAction();
- ветка в renderInlineEditor() для использования внутри multi.steps.
В main.py → run_action(): обработчик нового type.
В llm_suggest.py → _ACTION_SCHEMA_DOC: описание для LLM.

Бэкапы

yaml_writer.append_command / upsert_command перед записью копируют commands.yaml в commands.yaml.bak (через shutil.copy2). При запуске app.py вызывается _check_yaml_health() — если основной файл не парсится, в stderr печатается путь к .bak для ручного восстановления.

Тесты

.venv\Scripts\python.exe -m pytest tools/command_builder/tests/

3.6 KiB Raw Blame History Unescape Escape