- Build all:
.\build_windows.ps1 -Build all -Silent - Build backend only:
.\build_windows.ps1 -Build all,gui,backend -Silent - Build frontend only:
.\build_windows.ps1 -Build all,gui,frontend -Silent - Build + MSIX:
.\build_windows.ps1 -Build all -Silent -BuildMsix(-Buildformat is<system>,<mode>,<scope>, e.g.windows,gui,backend; single token without comma is parsed as<system>only) - Headless CLI (linux/WSL TUN test):
$env:GOOS='linux'; $env:CGO_ENABLED='0'; go build -tags "headless with_gvisor" -o build/bin/snishaper-linux ./cli(must includewith_gvisor, otherwise TUN fails with "gVisor is not included in this build") then run in WSL2 as root:./snishaper start && ./snishaper tun on, test withcurl -k -m 15 <url>, cleanup./snishaper tun off && ./snishaper stop; note:stopis async, so wait for processes to fully exit (pgrep -x snishaper) before the nextstart— core RPC is token-isolated (a stale instance can no longer kill a newly started core), but a zero-gap restart can still race the TUN device teardown and leave the data plane degraded - Frontend dev:
cd frontend && npm run dev - Frontend install:
cd frontend && npm install - Go mod tidy:
go mod tidy - Go build check:
go build -tags with_gvisor ./... - Frontend type check:
cd frontend && ./node_modules/.bin/tsc --noEmit(authoritative;vite builddoes NOT run strict type checks, so it can miss TS errors) - No test framework exists (no test files in repo)
SniShaper is a Windows local proxy tool using ECH Injection, TLS-RF Fragmentation, QUIC Connection Rebuilding, and Lightweight Server Mode Relay. Frontend: React 19 + Wails v3 + MUI + Vite 8. Backend: Go 1.27+ with Wails v3 bindings.
/main.go— entry point, Wails app + tray setup/app/— Go backend: App struct, API bindings (app_api.go), system proxy (app_system.go), autostart/core/— Mihomo core process management (core_client.go), TUN, admin elevation/proxy— Proxy server (MITM, SOCKS5, TLS fragmentation, TUN flow, auto-routing, rules): no longer a local directory, imported from snishaper-core asproxy/pkg/— Local packages only: a thinsysproxyfacade; cert manager, CF IP pool, DoH resolver, netiface, singtun, subscription, TLS fragmentation and GFWList all live in snishaper-coreevolution— Rule evolution testing (tester, rule generator, result analysis) isgithub.com/SnishaperTeam/snishaper-core/evolution; there is no local/evolution/directory/frontend/src/— React SPA: 10 pages (Dashboard, Proxies, Rules, Routing, DNS, Evolution, Logs, Settings, About, Welcome)/rules/config.json— Site group rules (~3800 lines), MITM/ECH/SNI-fake configs/config/settings.json— App settings (port, TUN, theme, Cloudflare IPs)
Data flow: Frontend (React HashRouter) → Wails bindings (EventsOn + async Go calls) → App API → proxy/core subsystems. Frontend state sync via app:state_changed events from emitFrontendState().
Engine and shared feature packages come from github.com/SnishaperTeam/snishaper-core (pinned in go.mod, no replace directive). This repo imports: proxy, certmanager, cfpool, dohresolver, netiface, singtun, subscription, sysproxy, evolution, config and log.
pkg/sysproxyis only a thin facade over core'ssysproxy.Manager: one process-wide instance plus the original package-level helpers, so call sites are unchanged. Core'sManageris per-instance (no process-global proxy snapshot); the facade injectsSUDO_USERviasysproxy.WithRunAsUserevolution(rule evolution testing) has no local directory — it issnishaper-core/evolution- Core requires
^v0.4.0: v0.4.0 movedsysproxyandevolutioninto the library, each app previously carrying a byte-identical copy
- Go: standard layout,
snishapermodule path, no external DI framework - Frontend: React 19 + TypeScript 6,
@/path alias for./src/, MUI v9 + emotion for styling,@iconify/react+@iconify-icons/*for icons (seefrontend/src/lib/icons.tsx) - Error handling: log via
a.appendLog(), return errors to frontend; no panic except top-level recover inmain.go - Naming: Go
camelCasefor unexported,PascalCasefor exported; TScamelCasefor functions/vars,PascalCasefor components/types - Imports: Go stdlib → third-party → internal; TS: React → components → API → i18n
- i18n:
I18nContextprovider,useTranslation()hook, lazy page loading withSuspense - i18n
t(path, params)resolves dotted paths against zh/en/ru; a missing key returns the key itself (truthy) — sot(key) || 'fallback'is dead code and must NOT be written; fallback pattern islabel === key ? fallback : label - i18n dynamic keys (
t(\section.${x}`)`) MUST have a missing-key guard, otherwise unknown values render as the raw key - i18n placeholders: param names passed to
t('k', {...})must match{param}placeholders in all three locales (shorthand props like{ ms }count as params); keep the key tree structurally identical across zh/en/ru - i18n coverage: aria-label / placeholder / title / toast / button text must go through
t(); add new UI copy to ALL of zh/en/ru JSON in the same commit - Git: commit messages MUST be written in English (user requirement), conventional-commit style, e.g.
refactor: remove GFWList dynamic update and complete i18n - Wiki: any change that alters a file's purpose/nature, adds new files, or renames/removes files MUST update the GitHub Wiki in the same change (zh + EN pages; clone
https://github.com/SnishaperTeam/SniShaper.wiki.git, naming:Page.md= zh,EN-Page.md= en)
- MSIX signing: the release pipeline restores the pfx from the
MSIX_PFX_BASE64secret (passwordMSIX_PFX_PASSWORD); without it an ephemeral cert is generated per build. A local untrackeddevcert.pfxmay exist for dev signing. Release bundles ship only the publicdevcert.cer— never the pfx or its password - Cert manager lives in snishaper-core (
certmanager); it writes the CA under the per-user config dir (runtime, gitignored) - Admin rights required for system proxy registry writes and TUN
- Registry access via
golang.org/x/sys/windows/registry(notreg.exe)
- Changes to
app_system.go,app_api.go— verify proxy start/stop + system proxy toggling - Changes to
rules/config.json— verify correct site group, MITM/ECH modes - Changes to frontend event handling — verify
app:state/app:state_changedevents - Changes to core client — verify TUN ready + wintun.dll presence
- Changes to i18n keys/text — verify
tsc --noEmitpasses and zh/en/ru key trees stay consistent (no missing keys, no placeholder mismatches)