refactor(edge): Server 协议统一与 wsclient 收敛（Phase 3 Batch 3）

- openflare/agent/relay/flared 协议类型改为 pkg/protocol 别名，删除重复 struct
- 新增 edge/wsclient Preset 表，三组件 wsclient 改为薄包装
- 更新设计文档、计划与 changelog

internal/apps/edge/wsclient/client.go

@@ -0,0 +1,130 @@
+package wsclient
+
+import (
+	"context"
+	"time"
+
+	pkgprotocol "github.com/Rain-kl/Wavelet/pkg/protocol"
+	shared "github.com/Rain-kl/Wavelet/pkg/wsclient"
+)
+
+type WSMessage = shared.WSMessage
+type MessageHandler = shared.MessageHandler
+
+type Preset int
+
+const (
+	PresetAgent Preset = iota
+	PresetRelay
+	PresetFlared
+)
+
+type presetConfig struct {
+	HeaderKey string
+	WSPath    string
+}
+
+var presets = map[Preset]presetConfig{
+	PresetAgent:  {HeaderKey: "X-Agent-Token", WSPath: "/api/v1/agent/ws"},
+	PresetRelay:  {HeaderKey: "X-Agent-Token", WSPath: "/api/v1/relay/ws"},
+	PresetFlared: {HeaderKey: "X-Tunnel-Token", WSPath: "/api/v1/tunnel/ws"},
+}
+
+func PresetHeaderKey(preset Preset) string {
+	return presets[preset].HeaderKey
+}
+
+func PresetWSPath(preset Preset) string {
+	return presets[preset].WSPath
+}
+
+type Client struct {
+	sharedClient *shared.Client
+}
+
+func New(preset Preset, baseURL, token string, timeout time.Duration) *Client {
+	cfg := presets[preset]
+	return &Client{
+		sharedClient: shared.New(shared.Config{
+			BaseURL:   baseURL,
+			Token:     token,
+			Timeout:   timeout,
+			HeaderKey: cfg.HeaderKey,
+			WSPath:    cfg.WSPath,
+		}),
+	}
+}
+
+func (c *Client) SetToken(token string) {
+	c.sharedClient.SetToken(token)
+}
+
+func (c *Client) URL() string {
+	return c.sharedClient.URL()
+}
+
+type Connection struct {
+	sharedConn *shared.Connection
+}
+
+func (c *Client) Connect(ctx context.Context) (*Connection, error) {
+	conn, err := c.sharedClient.Connect(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return &Connection{sharedConn: conn}, nil
+}
+
+type AgentConnection struct {
+	Connection
+}
+
+func (c *Client) ConnectAgent(ctx context.Context) (*AgentConnection, error) {
+	conn, err := c.Connect(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return &AgentConnection{Connection: *conn}, nil
+}
+
+func (conn *Connection) URL() string {
+	if conn == nil || conn.sharedConn == nil {
+		return ""
+	}
+	return conn.sharedConn.URL
+}
+
+func (conn *Connection) SendPing() error {
+	return conn.sharedConn.SendMessage(pkgprotocol.WSMessageTypePing, nil)
+}
+
+func (conn *Connection) SendPong() error {
+	return conn.sharedConn.SendMessage(pkgprotocol.WSMessageTypePong, nil)
+}
+
+func (conn *Connection) SendMessage(msgType string, payload any) error {
+	return conn.sharedConn.SendMessage(msgType, payload)
+}
+
+func (conn *Connection) Receive() (pkgprotocol.WSMessage, error) {
+	var message pkgprotocol.WSMessage
+	if err := conn.sharedConn.Receive(&message); err != nil {
+		return message, err
+	}
+	return message, nil
+}
+
+func (conn *Connection) RunReceiveLoop(ctx context.Context, handler MessageHandler) error {
+	return conn.sharedConn.RunReceiveLoop(ctx, handler)
+}
+
+func (conn *Connection) Close() error {
+	if conn == nil || conn.sharedConn == nil {
+		return nil
+	}
+	return conn.sharedConn.Close()
+}
+
+func (conn *AgentConnection) SendStatus(payload pkgprotocol.NodePayload) error {
+	return conn.sharedConn.SendMessage(pkgprotocol.WSMessageTypeStatus, payload)
+}

internal/apps/edge/wsclient/client_test.go

@@ -0,0 +1,66 @@
+package wsclient
+
+import (
+	"testing"
+	"time"
+)
+
+func TestPresetConfig(t *testing.T) {
+	tests := []struct {
+		preset    Preset
+		headerKey string
+		wsPath    string
+	}{
+		{preset: PresetAgent, headerKey: "X-Agent-Token", wsPath: "/api/v1/agent/ws"},
+		{preset: PresetRelay, headerKey: "X-Agent-Token", wsPath: "/api/v1/relay/ws"},
+		{preset: PresetFlared, headerKey: "X-Tunnel-Token", wsPath: "/api/v1/tunnel/ws"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.wsPath, func(t *testing.T) {
+			if got := PresetHeaderKey(tt.preset); got != tt.headerKey {
+				t.Fatalf("PresetHeaderKey() = %q, want %q", got, tt.headerKey)
+			}
+			if got := PresetWSPath(tt.preset); got != tt.wsPath {
+				t.Fatalf("PresetWSPath() = %q, want %q", got, tt.wsPath)
+			}
+		})
+	}
+}
+
+func TestClientURL(t *testing.T) {
+	tests := []struct {
+		name    string
+		preset  Preset
+		baseURL string
+		want    string
+	}{
+		{
+			name:    "agent https",
+			preset:  PresetAgent,
+			baseURL: "https://example.com",
+			want:    "wss://example.com/api/v1/agent/ws",
+		},
+		{
+			name:    "relay http with path prefix",
+			preset:  PresetRelay,
+			baseURL: "http://example.com/api",
+			want:    "ws://example.com/api/api/v1/relay/ws",
+		},
+		{
+			name:    "flared wss",
+			preset:  PresetFlared,
+			baseURL: "wss://edge.example.com",
+			want:    "wss://edge.example.com/api/v1/tunnel/ws",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			client := New(tt.preset, tt.baseURL, "token", time.Second)
+			if got := client.URL(); got != tt.want {
+				t.Fatalf("URL() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}