From 9a9e83dda0065041432da5bfecd92fd015f44c2c Mon Sep 17 00:00:00 2001 From: sagit <36596628+Sagit-chu@users.noreply.github.com> Date: Sun, 15 Feb 2026 22:33:00 +0800 Subject: [PATCH] docs(agents): update knowledge base with encryption, API envelope, and build conventions (#127) Add comprehensive documentation of project conventions including: - Encryption patterns (AES with node secret PSK) - API envelope structure (code, msg, data, ts) - Build peculiarities (minify: false, rolldown-vite, UPX compression) - Unique styles (flat monorepo, asymmetric Go layout, hybrid frontend mode) - Module boundaries and anti-patterns - Large file hotspots and code map references Updated 7 AGENTS.md files across root and submodules. --- AGENTS.md | 26 ++++++++++++++++------ go-backend/AGENTS.md | 13 ++++++++--- go-backend/internal/http/handler/AGENTS.md | 5 +++-- go-gost/AGENTS.md | 7 +++++- go-gost/x/AGENTS.md | 4 +++- go-gost/x/socket/AGENTS.md | 24 +++++++++++++------- vite-frontend/AGENTS.md | 18 +++++++++++---- 7 files changed, 71 insertions(+), 26 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1261f55..206e2ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ # PROJECT KNOWLEDGE BASE -**Generated:** Fri Feb 13 2026 -**Commit:** 3799729 -**Branch:** (detached) +**Generated:** Sun Feb 15 2026 +**Commit:** e5e22ba +**Branch:** main ## OVERVIEW FLVX (formerly Flux Panel) is a traffic forwarding management system built on a forked GOST v3 stack. It ships as a Go-based admin API (SQLite) + Vite/React UI + Go forwarding agent, with optional mobile WebView wrappers. @@ -43,8 +43,10 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a ## CONVENTIONS -- `Authorization` header carries the raw JWT token (no `Bearer` prefix) between `vite-frontend/` and `go-backend/`. -- `go-gost/` uses `replace github.com/go-gost/x => ./x` and `go-gost/x/` is also its own Go module. +- **Auth**: `Authorization` header carries the raw JWT token (no `Bearer` prefix) between `vite-frontend/` and `go-backend/`. +- **Module Fork**: `go-gost/` uses `replace github.com/go-gost/x => ./x` and `go-gost/x/` is also its own Go module. +- **Encryption**: Agent-to-panel communication uses AES encryption with node `secret` as PSK. +- **API Envelope**: All REST responses follow `{code, msg, data, ts}` structure (code 0 = success). ## ANTI-PATTERNS (THIS PROJECT) - **DO NOT EDIT** generated protobuf output: `go-gost/x/internal/util/grpc/proto/*.pb.go`, `go-gost/x/internal/util/grpc/proto/*_grpc.pb.go`. @@ -69,9 +71,19 @@ docker compose -f docker-compose-v6.yml up -d (cd go-gost && go run .) ``` +## UNIQUE STYLES +- **Flat Monorepo**: Language-prefixed dirs (`go-backend`, `go-gost`, `vite-frontend`) instead of `apps/`/`libs/`. +- **Asymmetric Go Layout**: `go-backend` follows `cmd//main.go` while `go-gost` uses `root/main.go`. +- **Frontend Hybrid Mode**: `App.tsx` detects "H5 mode" (mobile WebView) vs desktop, dictating layout strategy. + ## NOTES - LSP servers are not installed in this environment (gopls/jdtls/typescript-language-server); rely on grep-based navigation. - `vite-frontend/vite.config.ts` sets `minify: false` and disables treeshake; expect larger bundles. +- `vite-frontend` uses `rolldown-vite` (experimental Rust bundler) instead of standard Vite. - Install scripts (`install.sh`, `panel_install.sh`) self-delete after execution - common pattern in one-liner installs. -- CI uses UPX compression on Go binaries before release. -- Backend has contract tests in `go-backend/tests/contract/` - frontend has no test infrastructure. +- CI uses UPX compression (`--best --lzma`) on Go binaries before release. +- CI dynamically injects `PINNED_VERSION` into install scripts and docker-compose files during releases. +- `panel_install.sh` auto-detects IPv6 and modifies `/etc/docker/daemon.json` to enable IPv6 bridge. +- Download proxy `https://gcode.hostcentral.cc/` used for GitHub downloads in China/restricted environments. +- Backend has contract tests in `go-backend/tests/contract/` - frontend has no test infrastructure (Vitest/Jest not configured). +- `analysis/3x-ui/` contains a separate git repo for reference/comparison - not part of FLVX core. diff --git a/go-backend/AGENTS.md b/go-backend/AGENTS.md index 204c8e9..7efa6dc 100644 --- a/go-backend/AGENTS.md +++ b/go-backend/AGENTS.md @@ -1,8 +1,8 @@ # GO BACKEND KNOWLEDGE BASE ## OVERVIEW -Go-based Admin API for FLVX (formerly Flux Panel). Replaces the legacy Spring Boot backend. -**Stack:** Go 1.23, net/http (std lib), SQLite (modernc.org/sqlite). +Go-based Admin API for FLVX. Replaced legacy Spring Boot backend. +**Stack:** Go 1.23, net/http (std lib), SQLite/PostgreSQL (modernc.org/sqlite - CGO-free). ## STRUCTURE ``` @@ -34,14 +34,21 @@ go-backend/ ## CONVENTIONS - **No ORM**: Uses raw SQL with `database/sql` and `modernc.org/sqlite`. +- **CGO-Free SQLite**: `modernc.org/sqlite` instead of `mattn/go-sqlite3` - builds without CGO. - **Standard Lib**: Uses `net/http` for routing (Go 1.22+ patterns). - **Auth**: Expects raw JWT in `Authorization` header (no `Bearer` prefix). +- **API Envelope**: All responses use `response.R{code, msg, data, ts}` structure. - **Config**: Loaded from environment variables (see `cmd/paneld/main.go`). +- **SQL Idempotency**: Prefer `ON CONFLICT DO NOTHING` for inserts in migrations/sync. + +## ANTI-PATTERNS +- **DO NOT USE** ORM - uses raw SQL throughout. +- **DO NOT CHANGE** handler signatures without updating `router.go`. ## COMMANDS ```bash cd go-backend -go run ./cmd/paneld +go run ./cmd/paneld # Default: SERVER_ADDR=:6365 go test ./... make build ``` diff --git a/go-backend/internal/http/handler/AGENTS.md b/go-backend/internal/http/handler/AGENTS.md index b6660e1..d447ea5 100644 --- a/go-backend/internal/http/handler/AGENTS.md +++ b/go-backend/internal/http/handler/AGENTS.md @@ -1,6 +1,6 @@ # BACKEND HTTP HANDLER KNOWLEDGE BASE -**Generated:** Fri Feb 13 2026 +**Generated:** Sun Feb 15 2026 ## OVERVIEW HTTP request handlers for FLVX Admin API. Core business logic layer. @@ -29,8 +29,9 @@ handler/ ## CONVENTIONS - Inherits from parent: raw SQL, no ORM, JWT in Authorization header. -- Large files expected (`mutations.go` >100k LOC). +- Large files expected (`mutations.go` 3716 LOC - central mutation hub). - Uses `sqlite.Repository` for DB access via `repo.XXX()` methods. +- Domain-driven file split: one file per functional area (federation, jobs, etc.). ## ANTI-PATTERNS - Do NOT add ORM here - uses raw SQL throughout. diff --git a/go-gost/AGENTS.md b/go-gost/AGENTS.md index c87f202..6d97324 100644 --- a/go-gost/AGENTS.md +++ b/go-gost/AGENTS.md @@ -1,6 +1,6 @@ # GO-GOST SERVICE KNOWLEDGE BASE -**Generated:** Mon Feb 02 2026 +**Generated:** Sun Feb 15 2026 ## OVERVIEW Forwarding agent built on GOST v3 with a local fork of `github.com/go-gost/x` under `x/`. @@ -27,6 +27,11 @@ go-gost/ ## CONVENTIONS - Two configs exist: panel integration uses `config.json`; forwarding services use GOST config (defaults to `gost.{json,yaml}` via viper search paths). - `go-gost/x/` is the primary extension surface; avoid editing vendored deps. +- Agent communicates with panel via WebSocket (real-time commands) + HTTP (batch traffic reports). +- All panel communication uses AES encryption with node `secret` as PSK. + +## ANTI-PATTERNS +- **DO NOT EDIT** generated protobuf in `x/internal/util/grpc/proto/`. ## COMMANDS ```bash diff --git a/go-gost/x/AGENTS.md b/go-gost/x/AGENTS.md index bb36c85..057ac0b 100644 --- a/go-gost/x/AGENTS.md +++ b/go-gost/x/AGENTS.md @@ -1,7 +1,7 @@ # GO-GOST/X KNOWLEDGE BASE ## OVERVIEW -Local fork of `github.com/go-gost/x` used by `go-gost/` via `replace github.com/go-gost/x => ./x`. Most protocol/runtime behavior changes happen here. +Local fork of `github.com/go-gost/x` used by `go-gost/` via `replace github.com/go-gost/x => ./x`. Most protocol/runtime behavior changes happen here. 30+ top-level packages - framework-style layout. ## STRUCTURE ``` @@ -31,6 +31,8 @@ go-gost/x/ ## CONVENTIONS - `go-gost/x/` is a standalone Go module (`go-gost/x/go.mod`); run go tooling from this dir when debugging module resolution. - Generated gRPC/proto code lives under `go-gost/x/internal/util/grpc/proto/`. +- Handlers/listeners/dialers follow consistent pattern: `{type}.go` + `metadata.go` per protocol. +- OS-specific code uses `name_[os].go` suffix (e.g., `tun_linux.go`, `tun_darwin.go`). ## ANTI-PATTERNS - Do not edit generated files in `go-gost/x/internal/util/grpc/proto/` (`*.pb.go`, `*_grpc.pb.go`). diff --git a/go-gost/x/socket/AGENTS.md b/go-gost/x/socket/AGENTS.md index 413ef85..388730d 100644 --- a/go-gost/x/socket/AGENTS.md +++ b/go-gost/x/socket/AGENTS.md @@ -1,24 +1,32 @@ # GOST SOCKET KNOWLEDGE BASE -**Generated:** Fri Feb 13 2026 +**Generated:** Sun Feb 15 2026 ## OVERVIEW -Socket utilities and wrappers for GOST forwarding. -**Stack:** Go, GOST core. +WebSocket reporter and socket utilities for panel integration. +**Stack:** Go, GOST core, gorilla/websocket. ## STRUCTURE ``` socket/ -├── socket.go # Core socket interface -├── udp.go # UDP socket handling -├── packet.go # Packet framing -├── packetconn.go # Packet connection wrapper -└── ... # Additional socket utilities +├── websocket_reporter.go # Agent-to-panel telemetry (1504 LOC) +├── service.go # Socket service orchestration (534 LOC) +├── socket.go # Core socket interface +├── udp.go # UDP socket handling +├── packet.go # Packet framing +└── packetconn.go # Packet connection wrapper ``` +## WHERE TO LOOK +| Task | Location | Notes | +|------|----------|-------| +| **Panel Reporting** | `websocket_reporter.go` | Real-time system info (CPU, mem, uptime) every 2s | +| **Command Handling** | `websocket_reporter.go` | Processes `AddService`, `UpgradeAgent`, etc. | + ## CONVENTIONS - Inherits from parent `go-gost/x/` conventions. - Low-level network primitives. +- All panel communication is AES-encrypted using node `secret`. ## ANTI-PATTERNS - DO NOT EDIT generated protobuf. diff --git a/vite-frontend/AGENTS.md b/vite-frontend/AGENTS.md index 88ff6a1..c3ec8ab 100644 --- a/vite-frontend/AGENTS.md +++ b/vite-frontend/AGENTS.md @@ -1,10 +1,10 @@ # VITE FRONTEND KNOWLEDGE BASE -**Generated:** Mon Feb 02 2026 +**Generated:** Sun Feb 15 2026 ## OVERVIEW -Web management console for FLVX (formerly Flux Panel). -**Stack:** React 18, Vite 5, TypeScript, TailwindCSS 4, HeroUI. +Web management console for FLVX. +**Stack:** React 18, Vite 5 (rolldown-vite), TypeScript, TailwindCSS 4, HeroUI. ## STRUCTURE ``` @@ -37,9 +37,19 @@ vite-frontend/ ## CONVENTIONS - **Auth**: JWT stored as `localStorage.token`. Sent in `Authorization` header (no "Bearer" prefix). -- **API**: Default base URL is `/api/v1/`. +- **API**: Default base URL is `/api/v1/`. Responses follow `{code, msg, data, ts}` structure. - **WebView**: In WebView mode, base URL is derived from selected panel address. If unset, API returns `code: -1`. - **Routing**: URL query param `h5=true` forces mobile layout. +- **Build**: `minify: false`, `treeshake: false` - unoptimized production bundles for debugging. +- **ESLint**: `react-hooks/exhaustive-deps` disabled, unused vars starting with `_` ignored. +- **Large Pages**: `forward.tsx` (3263 LOC), `tunnel.tsx` (2552 LOC), `node.tsx` (2194 LOC). + +## ANTI-PATTERNS +- **DO NOT ADD** tests - no test infrastructure (Vitest/Jest not configured). + +## NOTES +- Uses `rolldown-vite` (experimental Rust bundler) instead of standard Vite. +- ESLint Flat Config format with custom import ordering rules. ## COMMANDS ```bash