agent

type AgentConnection struct {
	// AgentID is the unique identifier of the Agent.
	// AgentID 是 Agent 的唯一标识符。
	AgentID string

	// HostID is the ID of the host this Agent is running on.
	// HostID 是此 Agent 运行所在主机的 ID。
	HostID uint

	// IPAddress is the IP address of the Agent.
	// IPAddress 是 Agent 的 IP 地址。
	IPAddress string

	// Hostname is the hostname of the Agent.
	// Hostname 是 Agent 的主机名。
	Hostname string

	// Version is the Agent version.
	// Version 是 Agent 版本。
	Version string

	// Stream is the bidirectional gRPC stream for commands.
	// Stream 是用于命令的双向 gRPC 流。
	Stream grpc.BidiStreamingServer[pb.CommandResponse, pb.CommandRequest]

	// LastHeartbeat is the timestamp of the last heartbeat received.
	// LastHeartbeat 是收到的最后一次心跳的时间戳。
	LastHeartbeat time.Time

	// Status is the current connection status.
	// Status 是当前连接状态。
	Status AgentStatus

	// ConnectedAt is the timestamp when the Agent connected.
	// ConnectedAt 是 Agent 连接的时间戳。
	ConnectedAt time.Time
	// contains filtered or unexported fields
}

type AgentConnectionSnapshot struct {
	AgentID       string
	HostID        uint
	IPAddress     string
	Hostname      string
	Version       string
	Status        AgentStatus
	ConnectedAt   time.Time
	LastHeartbeat time.Time
}

type AgentStatus string

type CommandContext struct {
	// CommandID is the unique identifier of the command.
	// CommandID 是命令的唯一标识符。
	CommandID string

	// AgentID is the ID of the Agent executing the command.
	// AgentID 是执行命令的 Agent 的 ID。
	AgentID string

	// Type is the command type.
	// Type 是命令类型。
	Type pb.CommandType

	// Parameters are the command parameters.
	// Parameters 是命令参数。
	Parameters map[string]string

	// Timeout is the command timeout duration.
	// Timeout 是命令超时时间。
	Timeout time.Duration

	// CreatedAt is when the command was created.
	// CreatedAt 是命令创建的时间。
	CreatedAt time.Time

	// ResultChan is the channel for receiving the command result.
	// ResultChan 是接收命令结果的通道。
	ResultChan chan *pb.CommandResponse

	// Done indicates if the command has completed.
	// Done 表示命令是否已完成。
	Done bool

	// LastStatus is the last known status of the command.
	// LastStatus 是命令的最后已知状态。
	LastStatus pb.CommandStatus

	// LastProgress is the last known progress (0-100).
	// LastProgress 是最后已知的进度 (0-100)。
	LastProgress int32

	// LastOutput is the last known output message.
	// LastOutput 是最后已知的输出消息。
	LastOutput string

	// LastError is the last known error message.
	// LastError 是最后已知的错误消息。
	LastError string
	// contains filtered or unexported fields
}

type CommandParamEnricher func(ctx context.Context, agentID string, cmdType pb.CommandType, params map[string]string) map[string]string

type ErrorResponse struct {
	ErrorMsg string `json:"error_msg"`
}

type Handler struct {
	// contains filtered or unexported fields
}

type HandlerConfig struct {
	// ControlPlaneAddr is the address of the Control Plane.
	// ControlPlaneAddr 是 Control Plane 的地址。
	ControlPlaneAddr string

	// AgentBinaryDir is the directory containing Agent binary files.
	// AgentBinaryDir 是包含 Agent 二进制文件的目录。
	AgentBinaryDir string

	// STXJavaProxyJarPath is the path to the packaged stx-java-proxy thin jar.
	// STXJavaProxyJarPath 是 stx-java-proxy 薄 jar 的打包路径。
	STXJavaProxyJarPath string

	// STXJavaProxyScriptPath is the path to the packaged stx-java-proxy launcher script.
	// STXJavaProxyScriptPath 是 stx-java-proxy 启动脚本的打包路径。
	STXJavaProxyScriptPath string

	// GRPCPort is the gRPC port for Agent connections.
	// GRPCPort 是 Agent 连接的 gRPC 端口。
	GRPCPort string

	// HeartbeatInterval is the heartbeat interval in seconds.
	// HeartbeatInterval 是心跳间隔（秒）。
	HeartbeatInterval int

	// TLSEnabled indicates whether Control Plane gRPC TLS is enabled.
	// TLSEnabled 表示 Control Plane gRPC TLS 是否已启用。
	TLSEnabled bool

	// CAFile is the local path to the CA certificate Agents should trust.
	// CAFile 是 Agent 应信任的 CA 证书本地路径。
	CAFile string
}

type HostServiceAdapter struct {
	// contains filtered or unexported fields
}

type HostStatusUpdater interface {
	// UpdateAgentStatus updates the agent status for a host by pre-bound host ID or IP address.
	// UpdateAgentStatus 根据预绑定主机 ID 或 IP 地址更新主机的 Agent 状态。
	// hostname is used when auto-creating a host (e.g. no host matches by IP).
	// localIPs is the Agent local address set used to detect wrong user-entered host IPs.
	// localIPs 为本机地址集合，用于识别用户填错的主机 IP。
	UpdateAgentStatus(ctx context.Context, hostID uint, ipAddress string, agentID string, version string, systemInfo *SystemInfo, hostname string, localIPs []string) (hostIDOut uint, err error)

	// UpdateHeartbeat updates the heartbeat data for a host.
	// UpdateHeartbeat 更新主机的心跳数据。
	UpdateHeartbeat(ctx context.Context, agentID string, cpuUsage, memoryUsage, diskUsage float64) error

	// MarkHostOffline marks a host as offline by agent ID.
	// MarkHostOffline 根据 Agent ID 将主机标记为离线。
	MarkHostOffline(ctx context.Context, agentID string) error
}

type InstallScriptConfig struct {
	// ControlPlaneAddr is the HTTP address of the Control Plane.
	// ControlPlaneAddr 是 Control Plane 的 HTTP 地址。
	ControlPlaneAddr string

	// GRPCAddr is the gRPC address for Agent connection.
	// GRPCAddr 是 Agent 连接的 gRPC 地址。
	GRPCAddr string

	// HeartbeatInterval is the heartbeat interval in seconds from Control Plane config.
	// HeartbeatInterval 是来自 Control Plane 配置的心跳间隔（秒）。
	HeartbeatInterval int

	// TLSEnabled indicates whether Control Plane gRPC TLS is enabled (Agent should fetch CA).
	// TLSEnabled 表示 Control Plane gRPC TLS 是否已启用（Agent 应拉取 CA）。
	TLSEnabled bool

	// HostID is the optional pre-bound host ID.
	// HostID 是可选的预绑定主机 ID。
	HostID uint64
}

type InstallScriptData struct {
	// ControlPlaneAddr is the HTTP address of the Control Plane.
	// ControlPlaneAddr 是 Control Plane 的 HTTP 地址。
	ControlPlaneAddr string

	// GRPCAddr is the gRPC address for Agent connection.
	// GRPCAddr 是 Agent 连接的 gRPC 地址。
	GRPCAddr string

	// InstallDir is the Agent home root (bin/etc/logs/lib live underneath).
	// InstallDir 是 Agent 主目录（其下包含 bin/etc/logs/lib）。
	InstallDir string

	// ConfigDir is kept for compatibility; the install script always derives etc/ under InstallDir.
	// ConfigDir 为兼容字段保留；安装脚本始终从 InstallDir 推导 etc/。
	ConfigDir string

	// AgentBinary is the name of the Agent binary file.
	// AgentBinary 是 Agent 二进制文件的名称。
	AgentBinary string

	// ServiceName is the service name (systemd unit / launchd label suffix).
	// ServiceName 是服务名（systemd unit / launchd label 后缀）。
	ServiceName string

	// SupportDir is kept for compatibility; the install script always uses InstallDir as support root.
	// SupportDir 为兼容字段保留；安装脚本始终以 InstallDir 作为辅助资产根目录。
	SupportDir string

	// STXJavaProxyVersion is the default packaged stx-java-proxy version.
	// STXJavaProxyVersion 是默认打包的 stx-java-proxy 版本。
	STXJavaProxyVersion string

	// STXJavaProxyEpochs is the space-separated list of proxy epochs to install (e.g. "v2 v3").
	// STXJavaProxyEpochs 是要安装的 proxy 代际列表（空格分隔，如 "v2 v3"）。
	STXJavaProxyEpochs string

	// STXJavaProxyJarFileName is the packaged default stx-java-proxy jar file name.
	// STXJavaProxyJarFileName 是默认打包的 stx-java-proxy jar 文件名。
	STXJavaProxyJarFileName string

	// STXJavaProxyScriptFileName is the packaged stx-java-proxy script file name.
	// STXJavaProxyScriptFileName 是打包的 stx-java-proxy 脚本文件名。
	STXJavaProxyScriptFileName string

	// HeartbeatInterval is the heartbeat interval string (e.g., "60s").
	// HeartbeatInterval 是心跳间隔字符串（如 "60s"）。
	HeartbeatInterval string

	// TLSEnabled indicates whether Agent should enable gRPC TLS and download CA.
	// TLSEnabled 表示 Agent 是否应启用 gRPC TLS 并下载 CA。
	TLSEnabled bool

	// AgentCAFile is the on-host path where the downloaded CA certificate is stored.
	// AgentCAFile 是本机保存已下载 CA 证书的路径。
	AgentCAFile string

	// HostID is the optional pre-bound host ID.
	// HostID 是可选的预绑定主机 ID。
	HostID uint64
}

type InstallScriptGenerator struct {
	// contains filtered or unexported fields
}

type Manager struct {
	// contains filtered or unexported fields
}

type ManagerConfig struct {
	// HeartbeatInterval is the expected interval between heartbeats.
	// HeartbeatInterval 是心跳之间的预期间隔。
	HeartbeatInterval time.Duration

	// HeartbeatTimeout is the timeout for considering an Agent offline.
	// HeartbeatTimeout 是判断 Agent 离线的超时时间。
	HeartbeatTimeout time.Duration

	// CheckInterval is the interval for checking heartbeat timeouts.
	// CheckInterval 是检查心跳超时的间隔。
	CheckInterval time.Duration
}

type PackagePullOptions struct {
	StallTimeout time.Duration
	MaxDuration  time.Duration
	PollInterval time.Duration
	OnProgress   func(sent, total int64)
	// CachedRemotePath is where the Control Plane believes the Agent already holds this package;
	// the Agent reuses it only if size and SHA256 match.
	// CachedRemotePath 是 CP 认为 Agent 已持有该安装包的路径；仅当大小与 SHA256 一致时 Agent 才复用。
	CachedRemotePath string
}

type PackagePullResult struct {
	LocalPath string // path on the Agent / Agent 上的路径
	Reused    bool   // Agent already had an identical file / Agent 已有相同文件，未重新下载
}

type PackageServe struct {
	ID       string
	AgentID  string
	Path     string
	Size     int64
	Checksum string
	// contains filtered or unexported fields
}

type SupportedPlatform struct {
	// OS is the operating system (linux, darwin).
	// OS 是操作系统（linux, darwin）。
	OS string

	// Arch is the CPU architecture (amd64, arm64).
	// Arch 是 CPU 架构（amd64, arm64）。
	Arch string

	// BinaryName is the name of the binary file for this platform.
	// BinaryName 是此平台的二进制文件名称。
	BinaryName string
}

type SystemInfo struct {
	OSType      string
	Arch        string
	CPUCores    int
	TotalMemory int64
	TotalDisk   int64
}