From f01c0481cd8894a150bcb6aa9f81b608d9bf42f7 Mon Sep 17 00:00:00 2001 From: sagit Date: Fri, 13 Feb 2026 07:52:17 +0000 Subject: [PATCH] docs: update AGENTS.md hierarchy with new subdirectory docs - Update root AGENTS.md with expanded anti-patterns and notes - Add handler/AGENTS.md for high-complexity backend handlers - Add connector/AGENTS.md for GOST connector protocols - Add socket/AGENTS.md for GOST socket utilities --- AGENTS.md | 15 ++++++-- go-backend/internal/http/handler/AGENTS.md | 43 ++++++++++++++++++++++ go-gost/x/connector/AGENTS.md | 39 ++++++++++++++++++++ go-gost/x/socket/AGENTS.md | 30 +++++++++++++++ 4 files changed, 123 insertions(+), 4 deletions(-) create mode 100644 go-backend/internal/http/handler/AGENTS.md create mode 100644 go-gost/x/connector/AGENTS.md create mode 100644 go-gost/x/socket/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 88e8172..1261f55 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ # PROJECT KNOWLEDGE BASE -**Generated:** Mon Feb 02 2026 -**Commit:** 7ca01ab -**Branch:** beta +**Generated:** Fri Feb 13 2026 +**Commit:** 3799729 +**Branch:** (detached) ## 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. @@ -47,7 +47,11 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a - `go-gost/` uses `replace github.com/go-gost/x => ./x` and `go-gost/x/` is also its own Go module. ## 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`. +- **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`. +- **DO NOT ADD** `Bearer` prefix to Authorization header - expects raw JWT token. +- **DO NOT MODIFY** `install.sh` or `panel_install.sh` locally - CI overwrites these on release. +- **DO NOT USE** ORM in backend - uses raw SQL with `database/sql`. +- **DO NOT ADD** frontend tests - project has no test infrastructure (Vitest/Jest not configured). ## COMMANDS ```bash @@ -68,3 +72,6 @@ docker compose -f docker-compose-v6.yml up -d ## 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. +- 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. diff --git a/go-backend/internal/http/handler/AGENTS.md b/go-backend/internal/http/handler/AGENTS.md new file mode 100644 index 0000000..b6660e1 --- /dev/null +++ b/go-backend/internal/http/handler/AGENTS.md @@ -0,0 +1,43 @@ +# BACKEND HTTP HANDLER KNOWLEDGE BASE + +**Generated:** Fri Feb 13 2026 + +## OVERVIEW +HTTP request handlers for FLVX Admin API. Core business logic layer. +**Stack:** Go 1.23, net/http, raw SQL (no ORM). + +## STRUCTURE +``` +handler/ +├── handler.go # Main Handler struct, login/captcha, job scheduling +├── control_plane.go # Node control plane API (add/delete/list) +├── federation.go # Federation/cluster sync API +├── flow_policy.go # Traffic policy API +├── jobs.go # Background job management (sync, cleanup) +├── mutations.go # CRUD for users, tunnels, forwards (largest: 100k+ LOC) +└── upgrade.go # System upgrade API +``` + +## WHERE TO LOOK +| Task | Location | Notes | +|------|----------|-------| +| **User/Tunnel CRUD** | `mutations.go` | Largest file; all create/update/delete ops | +| **Login/Captcha** | `handler.go` | Login flow, captcha verification | +| **Federation Sync** | `federation.go` | Panel-to-panel sync | +| **Traffic Policies** | `flow_policy.go` | Flow limiting, quota management | +| **Background Jobs** | `jobs.go` | Scheduled sync/cleanup tasks | + +## CONVENTIONS +- Inherits from parent: raw SQL, no ORM, JWT in Authorization header. +- Large files expected (`mutations.go` >100k LOC). +- Uses `sqlite.Repository` for DB access via `repo.XXX()` methods. + +## ANTI-PATTERNS +- Do NOT add ORM here - uses raw SQL throughout. +- Do NOT change handler signatures without updating router.go. + +## COMMANDS +```bash +cd go-backend +go test ./internal/http/handler/... +``` diff --git a/go-gost/x/connector/AGENTS.md b/go-gost/x/connector/AGENTS.md new file mode 100644 index 0000000..581fbe8 --- /dev/null +++ b/go-gost/x/connector/AGENTS.md @@ -0,0 +1,39 @@ +# GOST CONNECTOR KNOWLEDGE BASE + +**Generated:** Fri Feb 13 2026 + +## OVERVIEW +Connection initiators (clients) for various protocols in GOST forwarding. +**Stack:** Go, GOST core. + +## STRUCTURE +``` +connector/ +├── direct/ # Direct connection +├── forward/ # Forward proxy +├── http/ # HTTP connector +├── http2/ # HTTP/2 connector +├── relay/ # Relay protocol +├── router/ # Router connector +├── serial/ # Serial port +├── sni/ # SNI routing +├── socks/ # SOCKS4/5 +├── ss/ # Shadowsocks +├── sshd/ # SSH daemon +├── tcp/ # TCP connector +├── tunnel/ # Tunnel mode +└── unix/ # Unix socket +``` + +## CONVENTIONS +- Inherits from parent `go-gost/x/` conventions. +- Each subdir implements `Connector` interface from GOST core. + +## ANTI-PATTERNS +- DO NOT EDIT generated protobuf in `go-gost/x/internal/util/grpc/proto/`. + +## COMMANDS +```bash +cd go-gost +go test ./x/connector/... +``` diff --git a/go-gost/x/socket/AGENTS.md b/go-gost/x/socket/AGENTS.md new file mode 100644 index 0000000..413ef85 --- /dev/null +++ b/go-gost/x/socket/AGENTS.md @@ -0,0 +1,30 @@ +# GOST SOCKET KNOWLEDGE BASE + +**Generated:** Fri Feb 13 2026 + +## OVERVIEW +Socket utilities and wrappers for GOST forwarding. +**Stack:** Go, GOST core. + +## STRUCTURE +``` +socket/ +├── socket.go # Core socket interface +├── udp.go # UDP socket handling +├── packet.go # Packet framing +├── packetconn.go # Packet connection wrapper +└── ... # Additional socket utilities +``` + +## CONVENTIONS +- Inherits from parent `go-gost/x/` conventions. +- Low-level network primitives. + +## ANTI-PATTERNS +- DO NOT EDIT generated protobuf. + +## COMMANDS +```bash +cd go-gost +go test ./x/socket/... +```