Интеграции и расширение

Screph расширяется через данные, adapters, profiles и внутренние registries, но сегодня не является платформой с установкой произвольных сторонних плагинов. Ниже разделены поддерживаемые пользовательские точки интеграции и механизмы, которые пока требуют изменения исходного кода.

Что можно использовать сейчас

Поверхность	Статус	Контракт
Canonical project / derived JSON	Implemented	Версионированные JSON-схемы для проекта, `for_ai_agent`, tree module и CV manifests. Внешний consumer читает файл, не внутренний Qt state.
Automation Python API	Implemented	`automation_runtime` загружает проект, ищет изображения/текст и выполняет явные input actions.
LLM / speech connections	Implemented	Настраиваемые profiles для поддержанных providers, local runtimes и custom OpenAI-compatible endpoint. Это configuration surface, не Python plugin loader.
Каталог semantic rules	Implemented	Вкладка «Семантика» принимает путь к внешнему JSON catalog. Файл валидируется; ошибка `selection_semantics.rule_catalog_load_failed` блокирует semantic command path и не вызывает тихий fallback.
Custom YOLO weights	Implemented	Можно импортировать собственный `.pt`. Файл остаётся на диске, но созданная custom registry entry пока существует только в текущем процессе.

Что называется plugin внутри кода

В коде есть InspectionPluginRegistry и TimelinePluginHost, а также registries CV methods, Assistant actions, settings providers и semantic handlers. Они дают typed composition boundary между внутренними компонентами и покрыты тестами, но собираются самим приложением.

Не публичная plugin-платформа

Сейчас нет discovery через Python entry points, plugin manifest/package format, install/uninstall UI, compatibility negotiation для стороннего пакета или sandbox. Название класса *PluginRegistry само по себе не означает, что пользователь может установить внешний модуль.

Добавление нового CV method, timeline track, evidence inspector, settings provider или Assistant action сегодня является задачей разработки: код подключается в composition root, получает typed contract и тесты, затем входит в сборку.

Встроенный IDE/codegen extension loader

ide_interaction.extensions при первом обращении сканирует только subpackages внутри установленного package и импортирует каждый entry.py, затем кэширует список до завершения процесса. Это internal composition loader: он не сканирует пользовательский каталог, Python entry points или скачанные packages и не проверяет manifest/signature/compatibility.

Встроенный package	Фактический статус	Consumer
AutoHotkey, Robot Framework Visual, SikuliX, TagUI, UiPath CV	Internal scaffold	Их текущие `entry.py` одинаково возвращают `None`, пустые lists и пустой context. Они не добавляют mode, backend, target profile или runner и не должны считаться доступными интеграциями.

Failure boundary. Если импорт entry падает с любым ModuleNotFoundError, loader сейчас молча пропускает package; прочие exceptions пишутся в log. Поэтому исчезнувший built-in adapter может означать missing module, а UI не является полным diagnostic report.

Launcher CLI и граница headless

pyproject.toml публикует один Python console entry point: Screph = main:main. Установщик вместо этого создаёт ярлыки на <выбранный TargetDir>\screph.exe --mode prod; default target — %LOCALAPPDATA%\Screph. Он не добавляет команду Screph в PATH. Обе точки входа запускают полную программу или одну из её process surfaces; это не headless CLI для редактирования проектов или произвольного запуска автоматизации.

& "$env:LOCALAPPDATA\Screph\screph.exe" --help
& "$env:LOCALAPPDATA\Screph\screph.exe" --mode prod --verbose
python main.py --mode dev
python main.py --mode prod --log-file C:\logs\screph.log

Аргумент	Фактическое действие	Граница
`--mode dev\|prod`	Выставляет целый набор runtime environment values. Packaged default — `prod`, source default — `dev`.	`dev` требует source/development checkout с `WebSite/local_dev`, сертификатом и website Python environment; это не встроенный production web host.
`--verbose`, `--log-file`	Меняют logging текущего процесса; явный файл не становится сохранённым пользовательским default.	Для предсказуемого места используйте абсолютный путь.
`--config-dir`	Устанавливает `SCREPH_CONFIG_DIR` до создания settings runtime.	Несмотря на имя, перенаправляет весь root, который используют `get_runtime_file(...)`: settings, logs, caches, models и другие runtime data. Projects по явно выбранным путям и secrets в Windows Credential Manager туда не переносятся.
`--server-only`	Только с `--mode dev`: проверяет health, при необходимости запускает local HTTPS через PowerShell, ждёт до 15 секунд и завершает launcher.	Launcher не остаётся владельцем foreground server loop; lifecycle ведут `start_https.ps1`, `restart_https.ps1` и PID file.
`--codegen-gui`	Запускает standalone окно Screph Code вместо основного desktop window.	Требуются соответствующий component/runtime и LLM configuration.
`--profile-startup`	Включает `cProfile` до создания Application, но отключает его только после выхода из `app.run()`, затем печатает 50 cumulative entries.	Имя сильнее фактической границы: профилируется вся GUI-сессия до закрытия, а не только startup.
`--oauth-callback`, `--pro-agent`	Специализированный custom-URI completion path и внутренний JSON-RPC по stdin/stdout.	Это integration/process contracts, не интерактивные пользовательские команды. Обычный account device login запускается из UI; Pro Agent должен запускать его consumer.

Что подтверждено на packaged candidate

Проверенный main.dist/screph.exe — AMD64 PE32+ с subsystem CUI; --help реально выводит перечисленные visible flags и default prod. Поэтому запуск current candidate из ярлыка может сопровождаться console window: это текущая Alpha packaging boundary, а не отдельный headless product.

Позиционный project.json не является командой Open Project. Открывайте проект через GUI/Project Manager.
Текущий source launcher теперь завершает неизвестные аргументы с exit code 2 до старта GUI; уже собранный candidate всё ещё использует прежний parse_known_args contract и может молча продолжить после typo.
Скрытые smoke/runtime-dependency flags обслуживают packaging, installer bridge и diagnostics. Они не являются стабильным публичным CLI.
Для headless screen actions используйте отдельный automation_runtime script/API contract; launcher Screph не принимает произвольный automation script.

HTTP API сайта

Текущий versioned API обслуживает health, профиль/баланс, usage, diagnostics upload и speech inference; отдельные user-management routes обслуживают login/device/support. Он не предоставляет общий удалённый CRUD для Screph projects, загрузку project package или запуск desktop automation.

Auth, server speech и data transfer →

Выберите устойчивую границу

Для собственного анализа используйте canonical/derived JSON и проверяйте schema_version.
Для действий на экране используйте automation_runtime и его явный target/input contract.
Для модели используйте connection profile или supported custom endpoint, не импортируйте UI internals.
Для новой встроенной возможности работайте через исходный код и соответствующий registry contract; не загружайте непроверенный Python как «плагин».

Форматы и примеры: данные и экспорт. Участие в разработке: сообщество и contributing.

Unclear

Будущая внешняя plugin-система

Архитектурные документы требуют versioned IPC/plugin boundaries для отдельных компонентов, но репозиторий не подтверждает пользовательский marketplace, общий SDK или срок появления установки сторонних плагинов. Поэтому такую возможность нельзя обещать как Planned feature до отдельного публичного contract/roadmap.