fluxor: Instructions file for Codex

Fluxor 项目 AI 代理指南 (AGENTS.md)

本文件为后续接手的 AI 编码助手或开发者提供项目的系统架构、核心逻辑、通信接口及开发规约，以便于快速理解项目并进行无缝维护与扩展。

---

1. 项目定位与架构概述

Fluxor 是一个轻量级、无冗余的 Mihomo 内核管理面板与订阅生成系统。它采用前后端不分离的架构设计：

• 后端 (Go)：位于 backend/ 目录，以 Go 标准库为主，仅引入两个外部依赖：gorilla/websocket（通信）与 gopkg.in/yaml.v3（订阅/配置文件字段级校验）。新增依赖需有明确理由。后端托管在 Unix Socket (/var/apps/Fluxor/target/app.sock) 上，对外通过前端反向代理暴露，内嵌了前端的所有静态资源。
• 前端 (Vue 3 TypeScript 版)：位于 frontend/ 目录，由 Vue 3 (Composition API / Setup) + Vite + TailwindCSS + Pinia + TypeScript 构成，是项目唯一且主维护的前端实现。
  • 前端构建与内嵌：frontend/ 使用 Vite 构建，产物输出到 frontend/dist/（含 index.html 模板与 assets/ 静态资源）。直接执行 make 会清理旧 dist、构建前端、同步到 backend/dist/，再由后端在 backend/main.go 中以 //go:embed dist 内嵌该产物。
  • 版本号：不在前端注入。编译时经 -ldflags -X fluxor/internal/buildinfo.Version=... 写入后端（make V=1.0.0），前端经 GET /app-version 读取。
  • 开发环境编译：任何新功能或漏洞修复请在 Vue 3 版本中维护，修改前端代码后在项目根目录执行 make 完成整体构建。

核心功能职责

1. 内核进程生命周期管理：负责本地 Mihomo 二进制文件的启动、停止、状态查询及配置热重载（不中断长连接）。
2. 配置文件订阅与生成：读取用户的订阅链接及自定义规则集，生成内核可运行的 config.yaml。
3. 通信中转代理 (Bridge)：由于 Mihomo 运行在本地 Unix Socket 上，Fluxor 后端作为前端与本地内核之间的“双向桥梁”，代理所有的 HTTP API 请求与 WebSocket 数据流（流量、内存、连接、日志等）。该链路不携带任何认证头——内核对 Unix Socket 来源默认信任（见 3.10）；panel_secret 只对内核的 TCP 外部控制端口生效。

---

2. 目录结构与索引

fluxor/
├── Makefile               # 统一构建入口：make（清 dist → 前端 → 同步 → 后端）、make clean、make V=x.y.z
├── backend/               # Go 后端源码目录（独立 Go module，root 位于 backend/go.mod）
│   ├── main.go            # 程序入口：参数/环境变量解析、路由注册、监听启动、优雅退出，
│   │                      #   并以 //go:embed dist 内嵌前端构建产物
│   ├── internal/          # 按功能域拆分的后端实现（详见「2.1 后端包结构」）
│   ├── go.mod / go.sum    # Go module 定义与依赖
│   └── dist/              # 构建产物目录（由 make 从 frontend/dist 同步，已 gitignore）
└── frontend/              # 主维护 Vue 3 前端源码目录
    ├── package.json       # Vue 3.5 + Pinia 4 + vue-i18n 11 + Vite 8 (Rolldown) + Tailwind CSS 4 + TypeScript 5.9 + @vicons/ionicons5
    ├── vite.config.js     # 构建输出到 dist/（index.html + assets/），集成 @tailwindcss/vite 插件
    ├── index.html         # HTML 入口（Go 模板：{{.BaseHref}} / {{.RawBase}}）
    └── src/
        ├── main.ts        # 挂载 Pinia + vue-i18n (Composition API, legacy:false)
        ├── App.vue        # 根组件：响应式侧边栏/移动端底部 Tab、亮暗/跟随系统主题、中英切换、Toast 队列、Promise 确认框
        ├── env.d.ts       # .vue 类型声明 & Window.BASE_URL 接口扩展
        ├── i18n.ts        # 全站国际化（zh/en），从 localStorage 读取语言偏好，禁止硬编码中文
        ├── index.css      # Tailwind v4 入口（@import/@source/@custom-variant/@theme/@utility，取代原 tailwind.config.js）
        │                  #   + CSS 变量亮暗主题（data-theme 选择器）+ 自定义滚动条
        ├── components/    # 公共及细粒度组件 (ProxyGroupCard, FormSwitch, CustomRulesDialog,
        │                  #   CustomNodeDialog（基础/传输层/TLS/高级四个分区 + 按 visible_when 条件显示）
        │                  #   + NodeFieldInput（含 map 与嵌套 group 递归渲染）+ FieldLabel（中文界面下给
        │                  #     纯中文配置标题补英文小字，仅该弹窗使用）：自定义模式的动态协议表单,
        │                  #   CustomNodeCard：自定义模式的节点卡片)
        ├── composables/   # 全局解耦组合式函数 (useTheme, useLanguage)
        ├── utils/
        │   ├── api.ts     # withBase()、apiFetch() HTTP 封装、wsConnect() WebSocket 封装、sseConnect() SSE 封装
        │   └── mock.ts    # 前端离线开发模拟器：拦截 HTTP/WS 请求提供 mock 数据，支持脱离后端独立测试
        ├── store/
        │   ├── global.ts   # 标签页激活状态、侧边栏折叠、亮暗/跟随系统主题、Toast 队列（3s 自动消失）、Promise 驱动确认框
        │   ├── config.ts   # 内核常规配置参数（allow-lan/ipv6/mode/log-level/tun/端口等，由 app.vue 统一订阅，与订阅解耦）
        │   ├── subscription.ts # 订阅管理 Pinia Store：订阅/节点配置 CRUD、解析及状态更新，由 config.ts 中拆分解耦而来
        │   │                   #   + 自定义模式：custom_nodes 列表、节点协议字段表（/subscribe/node-protocols 懒加载缓存）、
        │   │                   #     独立规则作用域（/subscribe/custom-mode-rules/custom）
        │   ├── overview.ts # 仪表盘实时统计（速度/流量/内存/连接数/版本/当前节点）、60 点流量历史、3 路 WS + 1 路 SSE
        │   ├── proxies.ts  # 代理组列表、节点延迟字典、手风琴展开状态、并发受限（10）批量测速、
        │   │               #   自定义测速地址（localStorage，单节点/单组/全部测速共用，非法值回落默认 204 端点）
        │   ├── connections.ts # 活跃/已关闭连接列表、汇总统计、排序/搜索、WS 瞬时速率计算（快照差分）
        │   ├── rules.ts    # 规则列表、规则提供商列表、fetch/refresh 方法
        │   └── logs.ts     # 日志缓冲区（上限 2000 条）、自动滚动、暂停/继续、指数退避重连（1s~30s）
        └── views/
            ├── Overview.vue     # 概览：4 指标卡（上传/下载速度+总量）+ 4 信息卡（内存/连接数/版本/外部面板）+ Canvas 自绘折线图（max 60 点）
            ├── Proxies.vue      # 代理：手风琴展开/折叠、点击切换选择、单节点/组/全部测速、延迟着色（绿≤150 / 黄≤300 / 红>300ms/超时）
            ├── Rules.vue        # 规则：搜索过滤、启用/禁用开关（乐观更新+回滚）、规则提供商单个/全部更新
            ├── Connections.vue  # 连接：活跃/已关闭双标签、多列排序、搜索过滤、单条/全部断开（乐观更新移入 closed）、清空已关闭
            ├── Logs.vue         # 日志：暗色终端风格、级别过滤（Debug/Info/Warning/Error）、搜索、暂停/继续、智能自动滚动
            ├── Config.vue       # 配置：内核状态卡（启动/停止/升级）、常规参数、端口校验（1025-65535+重复检测）、TUN（gVisor/System/Mixed）、高级运维（重载/清缓存/GEO）、内置 DNS 查询
            └── Subscription.vue # 订阅中心：三模式（融合/切换/自定义）分段控件、代理/面板/TProxy 端口、密钥显隐切换、
                                 #   规则集档位（仅融合模式渲染）、UI 面板选择、「保存并应用」。
                                 #   融合/切换模式 = 订阅 CRUD 模态框 + 流量/健康度/有效期卡片 + 卡片选中；
                                 #   自定义模式 = 「节点列表」+「添加节点」弹窗（协议下拉 → 基础/传输层/TLS/高级四段动态渲染，
                                 #     默认值预填、按 network 条件显示传输选项块、嵌套块递归渲染），
                                 #     节点改动先落在本地列表，保存并应用时才落库并重生成配置。
                                 #   「自定义规则」弹窗（components/CustomRulesDialog.vue，多作用域 + 页签）：
                                 #   切换模式由订阅卡片按钮打开（作用域=该订阅，单页签）；
                                 #   融合模式与自定义模式由标题行「添加订阅/添加节点」左侧按钮打开
                                 #   （融合=base/full 两页签；自定义=独立作用域 custom 的单页签，规则与融合模式分开存放），
                                 #   并传入 hint 文案说明作用域与切换模式的入口（文案由父组件按模式给定，组件内不判模式）。
                                 #   同一个弹窗兼管「流量隧道」：类型下拉末尾的 tunnels 选项把表单切成隧道字段
                                 #   （监听类型下拉 / 两个地址输入框 / proxy 选择框），隧道列表独立成段排在规则列表下方，
                                 #   每条带启停开关与编辑/换序/删除；两个前端接口（endpoint / tunnelEndpoint）由父组件按模式传入