Code Structure

中文 | English

代码结构 (Code Structure)

面向贡献者与二次开发者的仓库结构说明。约定细节（命名、错误处理、i18n 规则）见仓库根目录的 AGENTS.md 与 docs/CONTRIBUTING.md。

技术栈

层	技术
后端	Go 1.27+，Wails v3 绑定
前端	React 19 + TypeScript + MUI + Vite，@heroicons/react 图标
核心	Mihomo 衍生核心进程（with_gvisor 标签构建，TUN 依赖 gVisor）
打包	Windows MSIX（PFX 签名）、跨平台 CLI 12 目标矩阵

目录结构

SniShaper/
├── main.go              # 入口：Wails 应用装配 + 托盘初始化
├── app/                 # Go 后端应用层
│   ├── app_api.go       #   App 结构体与全部前端绑定 API
│   ├── app_system.go    #   系统代理开关（注册表写入）
│   ├── autostart_*.go   #   开机自启（Windows: 任务计划程序；Linux/macOS: 平台实现）
│   ├── app_tray*.go     #   托盘：构建、会话监听（解锁/Explorer 重启恢复）、reshow
│   └── app_update*.go   #   版本检查、下载与自更新安装
├── core/                # 核心进程管理
│   ├── core_client.go   #   核心进程拉起、RPC 客户端（带 token 鉴权）
│   ├── core_api.go      #   核心内 RPC 服务（Ping/Shutdown 需 token 校验）
│   ├── core_runtime.go  #   核心运行时装配（TUN、证书、规则）
│   └── core_admin_*.go  #   管理员提权
├── proxy/               # 代理服务器核心逻辑
│   ├── mitm.go          #   MITM：本地终止 TLS、SNI 伪装/ECH 出站重放
│   ├── tun_flow.go      #   TUN 流量接入代理服务器
│   └── rules_*.go       #   规则匹配与自动路由
├── pkg/                 # 独立功能包
│   ├── certmanager/     #   CA 证书生成与安装
│   ├── cfpool/          #   Cloudflare IP 优选池（测速/健康检查/刷新）
│   ├── dohresolver/     #   DoH 解析器（多节点故障转移）
│   ├── rules/gfwlist.go #   GFWList 后缀匹配（仅本地缓存文件，无网络更新）
│   ├── singtun/         #   TUN 网卡管理（sing-tun 集成，gVisor 栈）
│   └── tlsfrag/         #   TLS-RF 分片实现
├── evolution/           # 规则进化测试：tester、规则生成器、结果分析
├── cli/                 # headless CLI（构建标签 headless）
│   ├── main.go          #   入口 + 命令分发
│   ├── catalog.go       #   命令目录（help 与 TUI 的单一事实来源）
│   └── tui.go           #   交互面板
├── frontend/src/        # React SPA，10 个页面
│                        #   Dashboard、Proxies、Rules、Routing、DNS、
│                        #   Evolution、Logs、Settings、About、Welcome
├── common/              # 跨平台工具（打开文件/URL、路径、崩溃日志）
├── rules/config.json    # 站点组规则（~3800 行）：MITM/ECH/SNI 伪装配置
├── config/settings.json # 应用设置：端口、TUN、主题、Cloudflare IP 等
└── docs/                # build / Platform / 贡献指南 / 协作条款等文档

数据流

前端 (React HashRouter)
   │  Wails 绑定：EventsOn 订阅 + 异步 Go 方法调用
   ▼
App API (app/app_api.go)
   │
   ├──► proxy/  代理服务器（HTTP + SOCKS5 混合端口、模式分发、规则匹配）
   ├──► core/   核心进程（TUN、gVisor 栈、自动路由、DNS 劫持）
   └──► pkg/    证书 / DoH / CF 优选池 / GFWList

• 前端状态同步：后端通过 emitFrontendState() 发出 app:state / app:state_changed 事件，前端订阅后刷新 UI。
• TUN 数据面：TUN 只做域名嗅探重建（fake-ip 反查失败时读首包嗅探 SNI），绝不改写 ClientHello —— TLS 转录哈希覆盖整个握手包，中途改字节会导致 bad record MAC；SNI 伪装只在 TLS 端点侧（MITM 出站重放）进行。
• 核心进程 RPC 隔离：核心与客户端之间用一次性 token 鉴权（Ping/Shutdown 均需校验），避免重叠实例误杀新核心。

构建与测试

• 全量构建：.\build_windows.ps1 -Build all -Silent（加 -BuildMsix 出 MSIX 安装包）
• 仅后端 / 前端：-Build backend / -Build frontend
• Go 编译检查：go build -tags with_gvisor ./...
• 前端类型检查（权威）：cd frontend && ./node_modules/.bin/tsc --noEmit
• headless CLI：见 CLI 命令参考 的自建章节

贡献须知

• 提交信息使用英文 conventional-commit 风格（feat: / fix: / refactor: …）。
• 新增 UI 文案必须同步补齐 zh / en / ru 三份 i18n JSON，占位符保持一致。
• 安全敏感区（证书、TUN、系统代理、核心 RPC token）改动需维护者审查；成为 collaborator 的条款见 docs/COLLABORATOR_AGREEMENT.md。