Интеграции и расширениеIntegrations and extension points

Screph расширяется через данные, adapters, profiles и внутренние registries, но сегодня не является платформой с установкой произвольных сторонних плагинов. Ниже разделены поддерживаемые пользовательские точки интеграции и механизмы, которые пока требуют изменения исходного кода.Screph is extended through data, adapters, profiles and internal registries, but it is not currently a platform for installing arbitrary third-party plugins. This page separates supported user-facing integration points from mechanisms that still require source changes.

Что можно использовать сейчасWhat you can use now

ПоверхностьSurface	СтатусStatus	КонтрактContract
Canonical project / derived JSON	Implemented	Версионированные JSON-схемы для проекта, `for_ai_agent`, tree module и CV manifests. Внешний consumer читает файл, не внутренний Qt state.Versioned JSON schemas for projects, `for_ai_agent`, tree modules and CV manifests. External consumers read files, not internal Qt state.
Automation Python API	Implemented	`automation_runtime` загружает проект, ищет изображения/текст и выполняет явные input actions.`automation_runtime` loads a project, finds images or text and performs explicit input actions.
LLM / speech connections	Implemented	Настраиваемые profiles для поддержанных providers, local runtimes и custom OpenAI-compatible endpoint. Это configuration surface, не Python plugin loader.Configurable profiles for supported providers, local runtimes and a custom OpenAI-compatible endpoint. This is a configuration surface, not a Python plugin loader.
Каталог semantic rulesSemantic rules catalog	Implemented	Вкладка «Семантика» принимает путь к внешнему JSON catalog. Файл валидируется; ошибка `selection_semantics.rule_catalog_load_failed` блокирует semantic command path и не вызывает тихий fallback.The Semantics tab accepts an external JSON catalog path. The file is validated; `selection_semantics.rule_catalog_load_failed` blocks the semantic command path instead of silently falling back.
Custom YOLO weights	Implemented	Можно импортировать собственный `.pt`. Файл остаётся на диске, но созданная custom registry entry пока существует только в текущем процессе.A custom `.pt` file can be imported. The file remains on disk, but its custom registry entry currently exists only for the running process.

Что называется plugin внутри кодаWhat “plugin” means inside the codebase

В коде есть InspectionPluginRegistry и TimelinePluginHost, а также registries CV methods, Assistant actions, settings providers и semantic handlers. Они дают typed composition boundary между внутренними компонентами и покрыты тестами, но собираются самим приложением.The codebase contains an InspectionPluginRegistry and TimelinePluginHost, plus registries for CV methods, Assistant actions, settings providers and semantic handlers. They provide typed composition boundaries between internal components and are covered by tests, but they are assembled by the application itself.

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

Сейчас нет discovery через Python entry points, plugin manifest/package format, install/uninstall UI, compatibility negotiation для стороннего пакета или sandbox. Название класса *PluginRegistry само по себе не означает, что пользователь может установить внешний модуль.There is currently no Python-entry-point discovery, plugin manifest or package format, install/uninstall UI, compatibility negotiation for third-party packages or sandbox. A class named *PluginRegistry does not by itself mean that users can install an external module.

Добавление нового CV method, timeline track, evidence inspector, settings provider или Assistant action сегодня является задачей разработки: код подключается в composition root, получает typed contract и тесты, затем входит в сборку.Adding a CV method, timeline track, evidence inspector, settings provider or Assistant action is currently a development task: code is wired into a composition root, given a typed contract and tests, and then included in a build.

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

ide_interaction.extensions при первом обращении сканирует только subpackages внутри установленного package и импортирует каждый entry.py, затем кэширует список до завершения процесса. Это internal composition loader: он не сканирует пользовательский каталог, Python entry points или скачанные packages и не проверяет manifest/signature/compatibility.On first use, ide_interaction.extensions scans only subpackages inside the installed package, imports each entry.py, and caches the list for the life of the process. This is an internal composition loader: it does not scan a user directory, Python entry points or downloaded packages, and it does not validate a manifest, signature or compatibility.

Встроенный packageBuilt-in package	Фактический статусActual status	ConsumerConsumer
Clickermann	Implemented	Определяет `main.cms` target, добавляет guide/context, готовит проект и предоставляет отдельный runner/history. Для выполнения нужен установленный внешний Clickermann.Resolves the `main.cms` target, adds guide/context, prepares the project and supplies a dedicated runner/history. Execution requires an external Clickermann installation.
AutoHotkey, Robot Framework Visual, SikuliX, TagUI, UiPath CV	Internal scaffold	Их текущие `entry.py` одинаково возвращают `None`, пустые lists и пустой context. Они не добавляют mode, backend, target profile или runner и не должны считаться доступными интеграциями.Their current `entry.py` files return `None`, empty lists and empty context. They add no mode, backend, target profile or runner and must not be treated as available integrations.

Failure boundary. Если импорт entry падает с любым ModuleNotFoundError, loader сейчас молча пропускает package; прочие exceptions пишутся в log. Поэтому исчезнувший built-in adapter может означать missing module, а UI не является полным diagnostic report.Failure boundary. If importing an entry raises any ModuleNotFoundError, the loader currently skips the package silently; other exceptions are logged. A missing built-in adapter may therefore indicate a missing module, and the UI is not a complete diagnostic report.

Launcher CLI и граница headlessLauncher CLI and the headless boundary

pyproject.toml публикует один Python console entry point: Screph = main:main. Установщик вместо этого создаёт ярлыки на <выбранный TargetDir>\screph.exe --mode prod; default target — %LOCALAPPDATA%\Screph. Он не добавляет команду Screph в PATH. Обе точки входа запускают полную программу или одну из её process surfaces; это не headless CLI для редактирования проектов или произвольного запуска автоматизации.pyproject.toml publishes one Python console entry point, Screph = main:main. The installer instead creates shortcuts to <selected TargetDir>\screph.exe --mode prod; the default target is %LOCALAPPDATA%\Screph. It does not add a Screph command to PATH. Both entry points launch the complete program or one of its process surfaces; this is not a headless CLI for editing projects or running arbitrary automation.

& "$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

АргументArgument	Фактическое действиеActual behavior	ГраницаBoundary
`--mode dev\|prod`	Выставляет целый набор runtime environment values. Packaged default — `prod`, source default — `dev`.Sets a complete group of runtime environment values. The packaged default is `prod`; the source default is `dev`.	`dev` требует source/development checkout с `WebSite/local_dev`, сертификатом и website Python environment; это не встроенный production web host.`dev` requires a source/development checkout with `WebSite/local_dev`, its certificate and website Python environment; it is not an embedded production web host.
`--verbose`, `--log-file`	Меняют logging текущего процесса; явный файл не становится сохранённым пользовательским default.Change logging for the current process; an explicit file does not become the persisted user default.	Для предсказуемого места используйте абсолютный путь.Use an absolute path for a predictable destination.
`--config-dir`	Устанавливает `SCREPH_CONFIG_DIR` до создания settings runtime.Sets `SCREPH_CONFIG_DIR` before the settings runtime is created.	Несмотря на имя, перенаправляет весь root, который используют `get_runtime_file(...)`: settings, logs, caches, models и другие runtime data. Projects по явно выбранным путям и secrets в Windows Credential Manager туда не переносятся.Despite its name, it redirects the entire root used by `get_runtime_file(...)`: settings, logs, caches, models and other runtime data. Projects at explicitly selected paths and secrets in Windows Credential Manager do not move there.
`--server-only`	Только с `--mode dev`: проверяет health, при необходимости запускает local HTTPS через PowerShell, ждёт до 15 секунд и завершает launcher.Only with `--mode dev`: checks health, starts local HTTPS through PowerShell if necessary, waits up to 15 seconds and exits the launcher.	Launcher не остаётся владельцем foreground server loop; lifecycle ведут `start_https.ps1`, `restart_https.ps1` и PID file.The launcher does not remain as the foreground owner of the server loop; lifecycle belongs to `start_https.ps1`, `restart_https.ps1` and the PID file.
`--codegen-gui`	Запускает standalone окно Screph Code вместо основного desktop window.Launches the standalone Screph Code window instead of the main desktop window.	Требуются соответствующий component/runtime и LLM configuration.The corresponding component, runtime and LLM configuration are required.
`--profile-startup`	Включает `cProfile` до создания Application, но отключает его только после выхода из `app.run()`, затем печатает 50 cumulative entries.Enables `cProfile` before Application construction but disables it only after `app.run()` exits, then prints 50 cumulative entries.	Имя сильнее фактической границы: профилируется вся GUI-сессия до закрытия, а не только startup.The name is narrower than the actual boundary: it profiles the complete GUI session until exit, not startup alone.
`--oauth-callback`, `--pro-agent`	Специализированный custom-URI completion path и внутренний JSON-RPC по stdin/stdout.A specialized custom-URI completion path and internal JSON-RPC over stdin/stdout.	Это integration/process contracts, не интерактивные пользовательские команды. Обычный account device login запускается из UI; Pro Agent должен запускать его consumer.These are integration and process contracts, not interactive user commands. Normal account device login starts in the UI, and a Pro Agent consumer should launch its process.

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

Проверенный main.dist/screph.exe — AMD64 PE32+ с subsystem CUI; --help реально выводит перечисленные visible flags и default prod. Поэтому запуск current candidate из ярлыка может сопровождаться console window: это текущая Alpha packaging boundary, а не отдельный headless product.The inspected main.dist/screph.exe is an AMD64 PE32+ binary with the CUI subsystem; --help actually prints the listed visible flags and the prod default. Launching the current candidate from a shortcut may therefore include a console window: this is the current Alpha packaging boundary, not a separate headless product.

Позиционный project.json не является командой Open Project. Открывайте проект через GUI/Project Manager.A positional project.json is not an Open Project command. Open projects through the GUI and Project Manager.
Текущий source launcher теперь завершает неизвестные аргументы с exit code 2 до старта GUI; уже собранный candidate всё ещё использует прежний parse_known_args contract и может молча продолжить после typo.The current source launcher now exits with code 2 for unknown arguments before starting the GUI; the already-built candidate still uses the earlier parse_known_args contract and may continue silently after a typo.
Скрытые smoke/runtime-dependency flags обслуживают packaging, installer bridge и diagnostics. Они не являются стабильным публичным CLI.Hidden smoke and runtime-dependency flags serve packaging, the installer bridge and diagnostics. They are not a stable public CLI.
Для headless screen actions используйте отдельный automation_runtime script/API contract; launcher Screph не принимает произвольный automation script.For headless screen actions, use the separate automation_runtime script and API contract; the Screph launcher does not accept an arbitrary automation script.

HTTP API сайтаWebsite HTTP API

Текущий versioned API обслуживает health, профиль/баланс, usage, diagnostics upload и speech inference; отдельные user-management routes обслуживают login/device/support. Он не предоставляет общий удалённый CRUD для Screph projects, загрузку project package или запуск desktop automation.The current versioned API covers health, profile and balance, usage, diagnostics upload and speech inference; separate user-management routes cover login, device authorization and support. It does not expose generic remote CRUD for Screph projects, project-package upload or desktop automation execution.

Auth, server speech и data transfer →Auth, server speech and data transfer →

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

Для собственного анализа используйте canonical/derived JSON и проверяйте schema_version.For custom analysis, use canonical or derived JSON and check schema_version.
Для действий на экране используйте automation_runtime и его явный target/input contract.For screen actions, use automation_runtime and its explicit target/input contract.
Для модели используйте connection profile или supported custom endpoint, не импортируйте UI internals.For a model, use a connection profile or supported custom endpoint rather than importing UI internals.
Для новой встроенной возможности работайте через исходный код и соответствующий registry contract; не загружайте непроверенный Python как «плагин».For a new built-in capability, work through the source and its registry contract; do not load untrusted Python as a “plugin.”

Форматы и примеры: данные и экспорт. Участие в разработке: сообщество и contributing.For formats and examples, see data and exports. For source contributions, see community and contributing.

Unclear

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

Архитектурные документы требуют versioned IPC/plugin boundaries для отдельных компонентов, но репозиторий не подтверждает пользовательский marketplace, общий SDK или срок появления установки сторонних плагинов. Поэтому такую возможность нельзя обещать как Planned feature до отдельного публичного contract/roadmap.Architecture documents call for versioned IPC and plugin boundaries between selected components, but the repository does not confirm a user marketplace, general SDK or delivery date for third-party plugin installation. It therefore cannot be promised as a Planned feature until a public contract and roadmap exist.