Инструкции для агентов

Контекст проекта

ProxyWarden - standalone Windows desktop client в корне репозитория. Это Tauri 2 + React/TypeScript UI + Rust backend для маршрутизации выбранных Windows-приложений через внешний SOCKS5-прокси или опциональный Local sing-box.

Не возвращать старую идею APP_MODE=windows и не подключать Windows-клиент к отдельному Node gateway/server. Текущий рабочий путь - src, src-tauri, scripts в корне репозитория.

Основные инварианты

Три компонента должны оставаться разделенными: Control App, ProxiFyre, Local sing-box.
ProxiFyre - обязательный слой для per-app routing; Local sing-box - необязательный runtime.
Внешний SOCKS5 flow должен работать без установленного Local sing-box.
Profile apply не должен скрыто устанавливать, удалять, запускать или чинить компоненты. Install/start/stop/uninstall - только явные действия пользователя.
Source of truth - JSON под C:\ProgramData\ProxyWarden\config и state.
C:\ProgramData\ProxyWarden\generated\proxifyre-app-config.json и sing-box-config.json - derived artifacts, их можно пересоздать.
Subscription URL и другие секреты нельзя показывать полностью в UI, diagnostics или логах.
Summary panel должен оставаться read-only: без apply/install/start/stop/delete/input/subscription mutations.

Структура

src/app/App.tsx - основная React-оркестрация, вкладки Сводка, ProxiFyre, VPN / Прокси, вызовы Tauri-команд и transient UI state.
src/app/readiness.ts - gating применимости маршрута. Не обходить его локальными проверками в JSX.
src/app/viewModel.ts - маленькие display/view-model helpers.
src/ui/* - общие presentational-компоненты. Для новых кнопок, вкладок, service rows, pills, полей и лог-дока сначала расширять эти компоненты.
src/api/tauriCommands.ts - единственная TypeScript-обертка над invoke(...); держать DTO в синхронизации с Rust.
src/domain/types.ts - TypeScript-зеркало доменных DTO.
src-tauri/src/models.rs - Rust-модели и default values.
src-tauri/src/validation.rs - нормализация входов.
src-tauri/src/storage.rs и activity.rs - JSON storage, backup/tmp writes, activity cap/sort.
src-tauri/src/adapters/proxy_router.rs - adapter boundary для proxy-router.
src-tauri/src/adapters/proxifyre.rs - первый adapter, генерирует ProxiFyre app-config.json.
src-tauri/src/adapters/singbox.rs - генерация локального sing-box конфига из subscription cache и выбранного сервера.
src-tauri/src/component_detection.rs - detection ProxiFyre/Proxifier/Local sing-box.
src-tauri/src/commands.rs - Tauri command handlers, installer/service orchestration, structured errors.
src-tauri/src/main.rs - реальная Tauri entrypoint-регистрация команд.
src-tauri/src/lib.rs сейчас scaffold/stale; не считать его источником регистрации команд без отдельной cleanup-задачи.
scripts/*.ps1 - явные installer entrypoints. -PlanOnly должен возвращать structured JSON без side effects.

Правила изменений

Не создавать второй источник правды для профилей, targets, components, subscription или activity.
Не писать generated config напрямую из React.
Не парсить raw PowerShell/stdout в UI. Backend/helper boundary должен возвращать structured JSON/error DTO.
Не привязывать UI напрямую к деталям ProxiFyre, если изменение относится к общему proxy-router поведению.
Не делать Local sing-box обязательным для external target.
Для service/install операций сохранять UAC/admin boundary и человекочитаемые ошибки.
При удалении install folders сохранять safe-path checks; не ослаблять рекурсивное удаление.
В UI держать стиль компактной Windows-утилиты, а не landing/dashboard. Использовать existing Button, Tabs, ServiceControlRow, StatusPill, Field, ActionMenu, LogDock.
Всплывающие подсказки при наведении делать быстрыми, кастомными и читаемыми: темная compact-плашка с мягкой рамкой/тенью, появление ~120ms, без нативного browser title как основного UI. Для иконок расширять общий IconButton/tooltip-паттерн, а не дублировать JSX/CSS локально.
Apply actions должны быть disabled с объяснением, когда нет приложений, ProxiFyre отсутствует, proxy input неверный или local route не готов.
Не оставлять dev-серверы (npm run dev, npm run tauri -- dev, preview-серверы) запущенными после проверки. Если сервер был поднят агентом, остановить его перед финальным ответом.

Проверка

Минимум для frontend/UI:

npm run build

Rust/backend:

cd D:\repos\ProxyWarden\src-tauri
cargo test

Tauri/toolchain:

npm run tauri -- info
npm run tauri -- dev
npm run tauri -- build

Installer boundaries:

& .\scripts\install-control-app.ps1 -PlanOnly
& .\scripts\install-proxyfier.ps1 -PlanOnly
& .\scripts\install-singbox.ps1 -PlanOnly

Для UI-изменений проверять browser-preview на desktop и narrow viewport. Browser-preview не доказывает native Tauri commands или elevated service lane.

Известные риски

Реальные elevated install/start/stop/uninstall операции для ProxiFyre и Local sing-box считаются implemented but unproven, пока они не проверены на Windows с UAC/admin confirmation.
Исторические planning/evidence файлы лежат в ignored docs-папках и не должны попадать в коммиты.
Старые документы могут ссылаться на apps/windows-client; текущая структура репозитория - standalone client в корне.

7.2 KiB Raw Blame History Unescape Escape