242 lines
16 KiB
Markdown
242 lines
16 KiB
Markdown
# AGENTS.md
|
||
|
||
## Назначение
|
||
|
||
ProxyWarden — standalone Windows desktop-приложение для удобного per-app proxy routing. Стек: Tauri 2, Rust backend, React/TypeScript frontend и Vite. Production install/service/UAC runtime реализован в Rust; PowerShell остаётся только build/release/QA tooling. Приложение управляет выбранными Windows-приложениями через ProxiFyre и, опционально, через локальный sing-box runtime.
|
||
|
||
Этот файл — главный контракт для кодового агента. Любой агент, который меняет репозиторий, обязан соблюдать эти правила. Да, даже если ему очень хочется «быстренько поправить одну кнопочку» и случайно переписать половину сетевого стека. Особенно тогда.
|
||
|
||
## Продуктовая рамка
|
||
|
||
Проект не должен превращаться в коммерческий SaaS, Node gateway, VPN-провайдер, proxy server или облачный control plane. Это локальная Windows-утилита для себя и друзей.
|
||
|
||
Цель: надежно и понятно конфигурировать маршрутизацию выбранных приложений через внешний SOCKS5 proxy или через локальный sing-box, не ломая системную сеть и не пряча опасные действия за безобидными кнопками.
|
||
|
||
## Архитектурные инварианты
|
||
|
||
- Control App, ProxiFyre и Local sing-box — разные компоненты. Не смешивать их ответственность.
|
||
- ProxiFyre — обязательный слой для per-app routing.
|
||
- Local sing-box — optional runtime. Внешний SOCKS5 flow обязан работать без sing-box.
|
||
- React UI не пишет generated config напрямую. UI вызывает typed Tauri commands.
|
||
- `src/api/tauriCommands.ts` — единственная TypeScript-обертка над `invoke(...)`.
|
||
- Rust backend отвечает за storage, validation, config generation, component detection, service/install orchestration и structured errors.
|
||
- `C:\ProgramData\ProxyWarden\config` и `C:\ProgramData\ProxyWarden\state` — source of truth.
|
||
- `C:\Program Files\ProxyWarden\components\ProxiFyre` и `C:\Program Files\ProxyWarden\components\sing-box` — единственные current managed component roots.
|
||
- `config\components.json` — только legacy migration input. Реальный component status принадлежит native Windows inventory и проверенным receipts.
|
||
- Packaged component catalog — immutable offline baseline; проверенный download cache лежит отдельно в `C:\ProgramData\ProxyWarden\packages`.
|
||
- `C:\ProgramData\ProxyWarden\generated\proxifyre-app-config.json` и `sing-box-config.json` — derived artifacts. Их можно пересоздавать.
|
||
- Install/start/stop/uninstall — только явные действия пользователя. `apply` не должен скрыто устанавливать, удалять или «чинить» компоненты.
|
||
- Subscription URL, credentials, proxy passwords и userinfo нельзя выводить полностью в UI, logs, diagnostics, crash text или activity.
|
||
- Summary panel должен оставаться read-only: без install/start/stop/apply/delete/input/subscription mutations.
|
||
- Любые elevated операции должны быть максимально явными и проверяемыми.
|
||
|
||
## Основная структура
|
||
|
||
```text
|
||
src/
|
||
api/tauriCommands.ts # typed invoke facade
|
||
app/App.tsx # текущая UI orchestration зона, слишком крупная
|
||
app/readiness.ts # apply gating logic
|
||
app/viewModel.ts # display/view helpers
|
||
domain/types.ts # TypeScript DTO mirror
|
||
ui/* # reusable presentational components
|
||
styles/app.css # основной CSS
|
||
|
||
src-tauri/
|
||
tauri.conf.json # Tauri config, security, window config
|
||
capabilities/default.json # Tauri permissions/capabilities
|
||
src/models.rs # Rust domain models/defaults
|
||
src/validation.rs # normalization/validation
|
||
src/storage.rs # JSON storage, tmp/bak writes
|
||
src/activity.rs # activity log
|
||
src/subscription.rs # subscription fetch/parse
|
||
src/component_catalog.rs # pinned offline component catalog
|
||
src/component_inventory.rs # exact native SCM/process/registry inventory
|
||
src/component_packages.rs # verified bundled/cache package plans
|
||
src/component_cutover.rs # durable legacy cutover/rollback/cleanup
|
||
src/migration.rs # versioned storage migration/adoption
|
||
src/privileged_jobs.rs # sealed one-shot elevated job records
|
||
src/privileged_runtime.rs # fixed native elevated action dispatcher
|
||
src/proxifyre_runtime.rs # native ProxiFyre lifecycle
|
||
src/singbox_runtime.rs # native sing-box lifecycle
|
||
src/singbox_service.rs # WinSW service spec/status logic
|
||
src/safe_fs.rs # safe path/ACL/reparse helpers
|
||
src/adapters/* # ProxiFyre/sing-box/proxy-router adapters
|
||
src/commands.rs # Tauri command handlers; currently too large
|
||
tests/* # Rust integration/domain tests
|
||
|
||
scripts/
|
||
check-runtime-powershell-boundary.ps1
|
||
update-component-bundle.ps1
|
||
audit-windows-smoke.ps1
|
||
prepare-release.ps1
|
||
```
|
||
|
||
## Агентские skill-модули
|
||
|
||
Подробные инструкции лежат в `.agent/skills`:
|
||
|
||
- `.agent/skills/repository-orientation/SKILL.md` — как быстро понять репозиторий.
|
||
- `.agent/skills/rust-tauri-backend/SKILL.md` — Rust/Tauri backend changes.
|
||
- `.agent/skills/react-typescript-ui/SKILL.md` — frontend/UI changes.
|
||
- `.agent/skills/security-hardening/SKILL.md` — CSP, секреты, temp files, storage, SSRF, elevated boundary.
|
||
- `.agent/skills/windows-services-powershell/SKILL.md` — Windows service/install/PowerShell изменения.
|
||
- `.agent/skills/subscriptions-routing/SKILL.md` — subscription, sing-box, ProxiFyre routing.
|
||
- `.agent/skills/testing-ci-release/SKILL.md` — проверки, CI, release hygiene.
|
||
- `.agent/skills/communication-reporting/SKILL.md` — короткие понятные планы, ревью и отчеты с таблицами файлов.
|
||
|
||
Перед сложным изменением прочитать релевантный skill. Перед любым нетривиальным ответом владельцу проекта — прочитать `communication-reporting`. Да, инструкция про то, как не писать кашу, теперь тоже инструкция. Так мы и живем.
|
||
|
||
## Стиль общения агента
|
||
|
||
Пользователь — разработчик, но ему не нужен роман о каждом `match`, `useState` и переименованном импорте. Писать надо как для человека, которому нужно быстро принять решение: что изменилось, где изменилось, зачем и что проверить.
|
||
|
||
Перед любым нетривиальным ответом прочитать `.agent/skills/communication-reporting/SKILL.md` и перед финальным сообщением пройти `.agent/checklists/communication.md`.
|
||
|
||
### Обязательные правила
|
||
|
||
- Сначала результат, потом детали.
|
||
- Короткие абзацы, списки и таблицы вместо полотна текста.
|
||
- Для нетривиальных изменений использовать таблицу `Файл / Что изменилось / Зачем`.
|
||
- Не объяснять каждую строку. Объяснять важные места, решения, риски и поведение.
|
||
- Технические термины использовать только когда они помогают. Сложный термин объяснять одной простой фразой.
|
||
- Проверки делить на выполненные, не выполненные и требующие Windows/manual check.
|
||
- Для ревью группировать находки по приоритетам: `Критично`, `Важно`, `Можно потом`, `Косметика`.
|
||
- Не писать корпоративный туман вроде «улучшена архитектура» без указания, что именно стало проще, безопаснее или понятнее.
|
||
- Не заявлять “всё проверено”, если Rust tests, Windows service flow, Tauri build или UAC сценарии не запускались.
|
||
|
||
### Минимальный формат финального ответа
|
||
|
||
```md
|
||
## Коротко
|
||
|
||
- 1-3 главных результата.
|
||
|
||
## Файлы
|
||
|
||
| Файл | Что изменилось | Зачем |
|
||
|---|---|---|
|
||
| `path/file` | простое описание | практическая причина |
|
||
|
||
## Проверки
|
||
|
||
| Проверка | Статус | Комментарий |
|
||
|---|---|---|
|
||
| `command` | выполнено / не выполнено | почему |
|
||
|
||
## Риски
|
||
|
||
- Что осталось проверить или почему риска нет.
|
||
```
|
||
|
||
Если задача маленькая, формат можно сжать до нескольких строк. Если задача security/service/storage/routing-sensitive, детали обязательны, потому что «ну вроде работает» — это не инженерный метод, а жанр народного фольклора.
|
||
|
||
|
||
|
||
## Правила изменений
|
||
|
||
### Backend
|
||
|
||
- Не добавлять новую Tauri command без typed wrapper в `src/api/tauriCommands.ts` и соответствующего TypeScript DTO в `src/domain/types.ts`, если command используется UI.
|
||
- Не возвращать raw strings для сложных ошибок. Использовать structured error DTO: `code`, `message`, `details`.
|
||
- Тяжелые или блокирующие операции должны быть `async` command + `tauri::async_runtime::spawn_blocking`.
|
||
- Не вызывать network/process/service/file-heavy logic прямо из async runtime thread.
|
||
- Не использовать `unwrap()`/`expect()` в production path, кроме очевидно невозможных bootstrap cases с комментарием.
|
||
- Не писать generated configs неатомарно. Использовать temp + backup + rename where practical.
|
||
- Не расширять `commands.rs` без необходимости. Для новой логики предпочитать отдельные модули и thin command wrapper.
|
||
|
||
### Frontend
|
||
|
||
- Не увеличивать `App.tsx`, если можно вынести hook/helper/component.
|
||
- Не вызывать `invoke(...)` напрямую вне `src/api/tauriCommands.ts`.
|
||
- Не дублировать apply-readiness проверки в JSX. Расширять `src/app/readiness.ts`.
|
||
- Для UI использовать существующие компоненты из `src/ui`.
|
||
- Apply/start/install/delete buttons должны иметь disabled state и понятную причину.
|
||
- Не показывать secrets. Для subscription/proxy URL использовать redacted display values.
|
||
- UI должен оставаться compact Windows utility, а не SaaS dashboard с иллюзией корпоративной важности.
|
||
|
||
### Security
|
||
|
||
- Не отключать CSP. Если CSP мешает, исправлять source policy, а не ставить `csp: null`.
|
||
- Не добавлять Tauri shell permissions без жесткого scope и отдельного обоснования.
|
||
- Не запускать произвольные команды из UI input.
|
||
- Runtime-generated elevated scripts запрещены. Elevation использует current exe, fixed early modes и sealed typed job records без arbitrary command/path arguments.
|
||
- Удаление директорий допускается только после safe-path/marker/service-path checks.
|
||
- Subscription fetch должен иметь timeout и защиту от очевидно опасных/local metadata адресов либо explicit allow-mode.
|
||
|
||
### Windows/service boundary
|
||
|
||
- PowerShell разрешён только в build/release/QA allowlist: `check-runtime-powershell-boundary.ps1`, `update-component-bundle.ps1`, `audit-windows-smoke.ps1`, `prepare-release.ps1`.
|
||
- `PlanOnly`/`CheckOnly` у этих scripts должны быть side-effect-free, возвращать structured JSON и иметь `changed: false`.
|
||
- Production Rust, Tauri resources и NSIS hooks не должны запускать `powershell.exe`, `pwsh`, `.ps1` или generated script text.
|
||
- После изменения этой границы запускать `scripts/check-runtime-powershell-boundary.ps1 -CheckOnly`.
|
||
- Install/start/stop/uninstall должны быть явными user actions.
|
||
- Fuzzy-detected service не считать managed service без проверки `PathName`/metadata.
|
||
- В Linux/macOS CI не пытаться «проверить» Windows service operations как реальные. Тестировать pure logic/mocks.
|
||
|
||
## Известный технический долг
|
||
|
||
- `src-tauri/src/commands.rs` слишком большой. Главная цель рефакторинга: разрезать на модули по use-case.
|
||
- `src/app/App.tsx` слишком большой. Главная цель frontend-рефакторинга: hooks/components/view-model helpers.
|
||
|
||
## Минимальная проверка перед ответом
|
||
|
||
Для docs-only изменений достаточно проверить структуру файлов и отсутствие очевидных Markdown/JSON ошибок.
|
||
|
||
Для frontend изменений:
|
||
|
||
```powershell
|
||
npm ci
|
||
npm run build
|
||
```
|
||
|
||
Для Rust/backend изменений:
|
||
|
||
```powershell
|
||
cd src-tauri
|
||
cargo fmt --all -- --check
|
||
cargo clippy --all-targets --all-features -- -D warnings
|
||
cargo test --all-targets
|
||
```
|
||
|
||
Для Tauri/toolchain:
|
||
|
||
```powershell
|
||
npm run tauri -- info
|
||
npm run tauri -- dev
|
||
npm run tauri -- build
|
||
```
|
||
|
||
Для offline bundle/release boundaries:
|
||
|
||
```powershell
|
||
& .\scripts\check-runtime-powershell-boundary.ps1 -CheckOnly
|
||
& .\scripts\update-component-bundle.ps1 -PlanOnly
|
||
& .\scripts\update-component-bundle.ps1 -CheckOnly
|
||
& .\scripts\audit-windows-smoke.ps1 -Mode PlanOnly
|
||
& .\scripts\prepare-release.ps1 -PlanOnly -SkipBuild
|
||
```
|
||
|
||
Не оставлять dev/preview/Tauri dev servers запущенными после проверки.
|
||
|
||
## Формат отчета агента
|
||
|
||
Использовать один из шаблонов:
|
||
|
||
- `.agent/templates/work-plan.md` — короткий план перед работой.
|
||
- `.agent/templates/change-report.md` — отчет после изменения кода.
|
||
- `.agent/templates/investigation-report.md` — аудит, расследование, разбор проблемы.
|
||
- `.agent/templates/user-facing-summary.md` — краткая сводка для владельца проекта.
|
||
- `.agent/templates/pr-description.md` — описание PR.
|
||
|
||
Каждый нетривиальный ответ должен отвечать на вопросы:
|
||
|
||
1. Что поменялось или найдено?
|
||
2. В каких файлах?
|
||
3. Зачем это нужно?
|
||
4. Что проверено?
|
||
5. Что не проверено?
|
||
6. Где остался риск?
|
||
|
||
Не писать «всё готово», если Windows/elevated/service flow не проверялся на Windows. Эта фраза и так слишком много навредила миру.
|