68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
# Конструктор команд (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)
|
||
|
||
1. В `schema.py`: добавить dataclass с полем `type` и методом `to_dict()`. Включить в Union `Action`. Расширить `action_from_dict()`.
|
||
2. В `tests/test_schema.py`: добавить roundtrip + negative-case тесты.
|
||
3. В `web/app.js`:
|
||
- карточка в `#action-grid` (`index.html`);
|
||
- ветка в `renderActionForm()`;
|
||
- ветка в `updateAction()`;
|
||
- ветка в `renderInlineEditor()` для использования внутри multi.steps.
|
||
4. В `main.py` → `run_action()`: обработчик нового `type`.
|
||
5. В `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/
|
||
```
|