Owner decision 2026-11-16: VLESS, VMess and Trojan run on the official Xray core; sing-box stays the gasket (TUN, routing, DNS, protected sockets) and only keeps Shadowsocks, SOCKS, HTTP and the rest. sing-box had no XHTTP transport for VMess and Trojan and only approximated the other transports, while Xray runs any of its protocols over any transport. - protocol_core: VMess/Trojan in Xray's JSON shape go to Xray; a raw sing-box JSON outbound pasted by the user (type key) stays with sing-box. - link_parser: xray_only for VMess/Trojan (allowInsecure without a pin is dropped like VLESS, Xray 26.x has none), TLS validation for all three, VMess alterId > 0 refused, vmess:// carries XHTTP mode and extra, WebSocket/HTTPUpgrade drop h2/h3 from alpn. - masking: VMess/Trojan are Xray servers (shape, presets); sing-box fragment keeps AnyTLS, HTTP, ShadowTLS. - config_builder: dead VMess/Trojan/transport conversion removed. - tests flipped to Shadowsocks where they need a sing-box server; new tests/test_xray_owns_vmess_trojan.py; docs updated. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
6 KiB
6 KiB
Project Rules
- Do not create new Git branches unless the user explicitly asks for one. By default, keep work on
mainand commit/push requested changes directly tomain. - Stable production releases use the one-command
python3 scripts/release_windows.py --change ...workflow defined by$zapret-kvn-releasein.agents/skills/zapret-kvn-release/SKILL.md. A release request authorizes the runner's local Windows dev/stable builds, immutable Forgejo publication, and stable-only Telegram delivery unless the user excludes it. Do not manually replay successful runner phases. Forgejo Actions validates portable source in the background; it does not own Windows release publication. - Release stable yourself, always, without asking (owner decision 2026-11-08, standing rule): after a fix or feature is verified, commit, push and run the release runner; do not ask "release now?". The runner's gates stay mandatory and a failed gate stops the release. Details: the workspace
../AGENTS.md. - Architecture basis (owner decision 2026-11-04): each protocol runs on its own complete native core (VLESS, VMess and Trojan go to Xray-core since owner decision 2026-11-16, Hysteria2 to official Hysteria, WG/AWG to Amnezia, the rest to sing-box), and sing-box is only the intermediary gasket that owns TUN, routing, DNS and protected sockets. Do not reimplement or approximate a protocol in sing-box or in app code when its native core exists; more native cores will be added. Details:
docs/RUNTIME_MODULES.mdand the workspace../AGENTS.md. - For sing-box and Xray proxy/native TUN modes, the active raw JSON config is the routing and DNS source of truth. Keep versioned defaults under
data/templates/sing-boxanddata/templates/xray, using only the original native core schemas. - Do not introduce a custom routing DSL, overlay,
${APP_ROUTE_RULES}-style compiler, or hidden Python injection of product routing policy. Runtime mutations must stay limited to app-owned transport and safety contracts. - The same active raw JSON owns routing for an engine's proxy and native TUN modes. The hybrid Xray sidecar owns only its
proxypath, while tun2socks remains a separate legacy path. - The updater preserves
data/, while remote builds carry current native templates inassets/template-update. On startup,template_sync.pyreplaces shipped templates and merges each same-path active config per top-level section: a section (dns,route,outbounds…) still equal to the previously installed template follows the new template, every section the user edited is kept verbatim. The app never rewrites user sections outside that update merge; returning to stock is a manual action (whole config or one section) in the routing GUI. - The «Маршрутизация» pages are a structured editor of the same active native sing-box JSON, driven by the pinned core's own schema (
assets/sing-box-schema/, regenerated byscripts/generate_singbox_schema.pyafter a sing-box pin change). They edit the parsed JSON in place and serialize it back; they must not introduce their own routing model. Wording and emphasis live inxray_fluent/singbox_config/catalog.py; field names, types and allowed values come only from the schema. - For JSON routing work, follow the project skill
$zapret-kvn-json-routingin.agents/skills/zapret-kvn-json-routing/SKILL.md. - Keep page-level surfaces transparent. Do not add local background fills or page/root/scroll-area style sheets that block Windows 11 Mica.
- Prefer built-in
qfluentwidgetsappearance over custom page styling. Add local UI styling only when the user explicitly asks for it or when the library cannot provide the needed result. - Do not force
WA_TranslucentBackgroundon full pages, scroll areas, or their viewports unless it is explicitly needed and visually verified; prefer the same built-in page behavior used by working screens. - Do not rebuild or smoke-start the app automatically after UI changes. The user will build it manually unless they explicitly ask for a build or startup verification.
- Do not change Xray proxy template/config
listenaddresses from0.0.0.0to localhost-only. In this project that is an intentional feature so the app can share the local proxy with other devices/apps when the user wants proxy distribution. - When a build is explicitly requested, use the project builder
python build.pyfrom the repo root instead of calling PyInstaller directly. - Before building, make sure
dist/ZapretKVN/ZapretKVN.exeis not running; if needed, stopZapretKVN.exefirst or the clean step can fail because the old binary is locked. - The builder is WSL-aware and converts paths for the Windows virtualenv automatically, so prefer it even when working from WSL.
User guides follow the app
- Zapret KVN for Windows is retold by the notes of the wiki vault
~/Privacy:Zapret/premium.md(the beginner guide, https://jvsymvhifd.fuckingspeedtest.com/Zapret/premium),premium/apps.md(the Windows section),premium/discord.md(the local proxy on port1390, discord-drover) andpremium/v2rayn.md(proxy and TUN mode). - If you change anything the user sees (adding a subscription, page and button names, the local proxy port, the proxy and TUN modes, routing templates, installation and update), update these notes and the affected screenshots in the same task. The task is not closed while the guide describes the old app (owner decision of 15.10.2026).
- Windows screenshots are taken on the machine
win10(VM 100); personal data and subscription links are painted over in the screenshots. - Edit the notes with the vault skill
~/Privacy/.claude/skills/vault-note/SKILL.md; publish with a commit andgit pushof the vault (the site rebuilds itself) and"$HOME/.local/bin/obsidian" vault="Privacy" publish:add path=<file>for the mirror. The detailed procedure and the site check are in the skillvpnbot-maintain-user-guidesin~/vpnbot/vpnbot_codex/.claude/skills/.
Response format
The response format rules are common to all projects: the "Response format" section in ~/AGENTS.md. Read it and follow it in every session; change the rules only there.