Code Structure

中文 | English

代码结构 (Code Structure)

面向贡献者与二次开发者的仓库结构说明。约定细节见仓库根目录的 AGENTS.md。FlowWeaver 源自 SniShaper，共享部分技术思路（sing-tun 数据面、uTLS/ECH 处理），但代码库独立演进。

技术栈

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

目录结构

FlowWeaver/
├── main.go                 # 入口：Wails 应用装配 + 托盘初始化
├── app/                    # Go 后端应用层
│   ├── app_api.go          #   App 结构体与全部前端绑定 API
│   ├── app_subscription.go #   订阅管理 API（导入/切换/节点选择）
│   ├── app_system.go       #   系统代理开关（注册表写入）
│   ├── autostart_*.go      #   开机自启（Windows: 任务计划程序）
│   ├── app_tray*.go        #   托盘：构建、会话监听、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/                  # 代理服务器核心逻辑
│   ├── proxy.go            #   HTTP + SOCKS5 混合端口服务
│   ├── mitm.go             #   MITM：本地终止 TLS、SNI 伪装/ECH 出站重放
│   ├── dialer.go           #   多协议出站拨号（ss/vmess/vless/trojan/tuic/hy2/wireguard/socks5/http）
│   ├── subscription_dialer.go  # 订阅节点拨号与 UDP 中继
│   ├── rules_merge.go      #   订阅规则与内置规则合并
│   ├── tun_flow.go         #   TUN 流量接入代理服务器
│   └── auto_routing.go     #   自动路由
├── pkg/                    # 独立功能包
│   ├── subscription/       #   Clash 订阅解析（节点/代理组/规则）
│   ├── singtun/            #   TUN 网卡管理（sing-tun 集成，gVisor 栈，UDP relay）
│   ├── netiface/           #   物理网卡探测与出站绑定
│   ├── certmanager/        #   CA 证书生成与安装
│   ├── cfpool/             #   Cloudflare IP 优选池
│   ├── dohresolver/        #   DoH 解析器（多节点故障转移）
│   ├── rules/gfwlist.go    #   GFWList 后缀匹配（仅本地缓存）
│   └── tlsfrag/            #   TLS-RF 分片实现
├── evolution/              # 规则进化测试：tester、规则生成器、结果分析
├── cli/                    # headless CLI（构建标签 headless）
│   ├── main.go             #   入口 + 命令分发
│   ├── catalog.go          #   命令目录（help 与 TUI 的单一事实来源）
│   └── tui.go              #   交互面板
├── frontend/src/           # React SPA，11 个页面
│                           #   Dashboard、Subscription、Proxies、Rules、Routing、
│                           #   DNS、Evolution、Logs、Settings、About、Welcome
├── common/                 # 跨平台工具（打开文件/URL、路径、崩溃日志）
├── rules/config.json       # 站点组规则
├── config/settings.json    # 应用设置：端口、TUN、主题、Cloudflare IP 等
└── Platform.md / build.md  # 平台支持与构建矩阵文档

数据流

前端 (React HashRouter)
   │  Wails 绑定：EventsOn 订阅 + 异步 Go 方法调用
   ▼
App API (app/app_api.go)
   │
   ├──► pkg/subscription  Clash 订阅解析 → 节点/代理组/规则
   ├──► proxy/            代理服务器（模式分发、多协议拨号、订阅 UDP 中继）
   ├──► core/             核心进程（TUN、gVisor 栈、自动路由、DNS 劫持）
   └──► pkg/              证书 / DoH / CF 优选池 / GFWList

• 前端状态同步：后端通过 emitFrontendState() 发出 app:state / app:state_changed 事件，前端订阅后刷新 UI。
• 订阅生效链路：sub use → 订阅规则经 rules_merge.go 合并加载并隐藏内置规则 → 节点选择写入订阅存储 → subscription_dialer.go 按选中节点拨号（TCP/UDP）。
• WireGuard 隧道以用户态 IP 栈运行：不创建内核网卡、不改系统路由表；TUN 的 UDP 流量经 singtun 的 UDP relay 走当前订阅节点。
• TUN 数据面只做域名嗅探重建（fake-ip 反查失败时读首包嗅探 SNI），绝不改写 ClientHello —— TLS 转录哈希覆盖整个握手包，中途改字节会导致 bad record MAC；SNI 伪装只在 TLS 端点侧（MITM 出站重放）进行。
• 核心进程 RPC 隔离：核心与客户端之间用一次性 token 鉴权（Ping/Shutdown 均需校验），避免重叠实例误杀新核心。

构建与测试

• 全量构建：.\build_windows.ps1 -Build all -Silent（Linux/macOS 用 ./build.sh；12 目标矩阵见 build.md）
• 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，占位符保持一致。
• 更改文件性质或新增文件时，同一变更内必须更新本 Wiki（zh + EN 页面）。
• 安全敏感区（证书、TUN、系统代理、核心 RPC token）改动需维护者审查。