💥 feat(agent)!: 添加主机监控代理首版

* 实现周期采集、快照缓存、本地 HTTP API 和主动上报

* 补齐 Linux 和 Windows 主机、网络、资源、进程和 TCP 采集

* 添加服务生命周期管理、配置加载、构建脚本和测试覆盖

BREAKING CHANGE: network.ips 拆分为 network.ipv4s 和 network.ipv6s。

AGENTS.md

@@ -0,0 +1,115 @@
+# 仓库规则
+
+## 项目要求
+
+### 项目简介
+
+- MFD Monitor Agent 是一个使用 Go 实现的单二进制主机状态监控 agent。
+- agent 需要支持 Windows 和 Linux，用于采集并暴露完整主机状态。
+- agent 默认通过本地 HTTP API 提供查询能力，默认监听 `127.0.0.1:8080`。
+- `GET /health` 用于返回进程存活状态、版本信息、最近快照时间和最近采集状态。
+- `GET /status` 用于返回缓存中的完整 `HostStatus` 主机状态快照。
+- agent 通过后台周期采集刷新内存缓存，HTTP 接口和主动上报都读取同一份缓存。
+- agent 支持可选的周期性 HTTP POST 主动上报，上报数据必须复用 `/status` 的 `HostStatus` JSON 结构。
+- agent 需要通过 CLI 管理服务生命周期，包括 `run`、`install`、`uninstall`、`start`、`stop` 和 `version`。
+- Linux 侧面向 systemd service；Windows 侧面向 Windows Service。
+
+### 权限要求
+
+- 安装阶段必须要求管理员/root 权限。
+- 首版运行阶段默认使用高权限服务账户，以稳定采集完整进程列表和 TCP 监听端口到进程的映射。
+- 接口层必须支持部分成功：某些字段或子采集器失败时，不应导致整个 `/status` 失败，应返回 `partial` 或具体错误原因。
+- 默认监听地址必须尽量收敛到本地地址 `127.0.0.1`，避免默认暴露敏感主机信息。
+
+### 架构要求
+
+- 使用单进程一体化架构。
+- 一个 agent 进程同时负责周期采集、快照缓存、HTTP 查询、主动上报，以及 Windows/Linux 服务生命周期管理。
+- 代码应按职责拆分模块：
+  - `collector/system`：主机名、OS、架构、启动时间、采集时间。
+  - `collector/network`：网卡、IPv4/IPv6、MAC。
+  - `collector/resource`：CPU、内存、磁盘。
+  - `collector/process`：完整进程列表。
+  - `collector/socket`：TCP 监听端口及其进程映射。
+  - `snapshot`：聚合各采集器输出，形成统一 `HostStatus`。
+  - `httpapi`：提供 `GET /health` 和 `GET /status`。
+  - `reporter`：定时 POST `HostStatus` 到中心端。
+  - `service`：封装 Windows/Linux 服务生命周期和安装命令。
+  - `config`：统一加载监听地址、采集周期、上报周期、上报目标、机器标识等配置。
+
+### HostStatus 要求
+
+- `HostStatus` 应使用统一 JSON 结构，至少覆盖以下信息：
+  - `agent`：版本、启动时间、快照时间、快照状态。
+  - `host`：机器标识、主机名、平台、平台版本、架构、运行时长。
+  - `network`：网卡、IP、MAC、MTU、flags、地址列表。
+  - `cpu`：逻辑核心数、物理核心数、使用率、负载、型号。
+  - `memory`：总量、已用、空闲、可用、使用率。
+  - `disks`：设备、挂载点、文件系统类型、总量、已用、空闲、使用率。
+  - `processes`：状态和完整进程列表，包含 pid、ppid、名称、exe、cmdline、用户、状态、启动时间、CPU 和内存占用。
+  - `tcp_listeners`：状态和 TCP 监听列表，包含 IP、端口、pid、进程名、进程路径、地址族。
+  - `errors`：记录子采集器失败原因。
+- `processes.status` 和 `tcp_listeners.status` 必须支持 `ok`、`partial`、`error`。
+
+### 采集要求
+
+- 必须采用“周期采集 + 内存缓存”策略。
+- agent 启动后应立即采集一次，之后后台定时刷新缓存。
+- HTTP 接口不得在每次请求时实时扫描系统，应直接读取最近一次缓存。
+- 主动上报必须读取同一份缓存，避免重复采集。
+- 采集逻辑需要设置整体采集超时。
+- 单个子采集器失败不能拖垮整次快照。
+- 例如进程采集失败时，仍应返回 CPU、内存、磁盘等其他信息；TCP 监听采集不完整时，应将对应状态标记为 `partial`。
+
+### 主动上报要求
+
+- agent 除支持外部系统通过 HTTP 拉取状态外，还必须支持定时主动上报。
+- 上报目标使用配置中的固定中心服务 URL。
+- 上报方式为周期性 POST `HostStatus` JSON。
+- 配置项应包含 `report.enabled`、`report.endpoint`、`report.interval`、`report.timeout`。
+- 上报失败和超时应独立记录日志。
+- 上报失败可支持重试或简单退避，但不能影响本地 HTTP 服务，也不能导致进程退出。
+
+### CLI 和服务要求
+
+- CLI 至少提供以下命令：
+  - `agent run`
+  - `agent install`
+  - `agent uninstall`
+  - `agent start`
+  - `agent stop`
+  - `agent version`
+- Linux 下，agent 进程以前台模式运行，并额外提供 systemd unit 模板，由安装流程写入 unit 并启停。
+- Windows 下，使用服务包装库实现 install、uninstall、start、stop、run，不依赖外部 NSSM。
+
+### 技术和测试要求
+
+- 优先使用 Go 实现，保持单二进制部署。
+- 系统信息采集优先使用成熟跨平台库，例如 `gopsutil`。
+- 如果跨平台库在端口到进程映射能力上不足，可以针对 Windows/Linux 做补充实现。
+- 单元测试应覆盖采集器到 `HostStatus` 的映射、空结果、字段缺失、权限错误、`partial/error` 状态和 snapshot 聚合逻辑。
+- 集成测试应覆盖 `GET /health`、`GET /status`、主动 POST 上报载荷、超时和失败重试行为。
+- 平台验证应覆盖 Windows 服务安装/启动/停止/卸载，以及 Linux systemd 安装、enable、start、restart。
+- 性能与稳定性验证应覆盖大量进程场景、采集周期与 HTTP 并发访问并存、较大 `/status` 响应体的内存占用。
+
+### 首版边界
+
+- 首版默认包含 IP、MAC、主机名、CPU、内存、磁盘、完整进程列表、TCP 监听端口及进程映射、本地 HTTP 查询、主动 HTTP 上报、Windows/Linux 服务化。
+- 首版默认不包含历史存储、趋势分析、分页查询、UDP 监听信息、线程列表、进程句柄、连接状态详情、强制 Token/mTLS。
+
+## 注释规则
+
+- 所有导出和内部的方法、函数、类结构、结构体、接口都必须编写清晰注释。
+- Go 代码中，每个包级函数、方法、类型、结构体和接口都需要使用简短注释说明其用途和行为。
+- 结构体注释需要说明该结构体代表什么。字段不够直观、包含单位、涉及安全影响，或会影响外部 JSON/API 行为时，需要为字段补充注释。
+- 方法和函数注释需要说明其职责、重要输入输出、副作用，以及相关错误行为。
+- 关键实现步骤需要添加简洁的行内注释说明逻辑，尤其是操作系统相关采集、权限敏感操作、缓存、上报、服务生命周期处理和错误降级路径。
+- 注释应解释代码为什么存在，或说明不直观逻辑如何工作。避免只重复代码本身含义的注释。
+- 修改代码行为时必须同步更新注释。不要留下过期注释、缺少上下文的 TODO，或容易误导的说明。
+
+## 项目风格
+
+- 优先使用直接、清晰的 Go 代码，并保持与现有单二进制 agent 结构一致。
+- 代码变更应聚焦在请求的行为范围内。
+- 保留采集器的部分成功行为：某个子系统失败时，应报告该子系统自身错误，而不是导致整个状态响应失败。
+- Linux 和 Windows 行为不同的代码路径，需要使用清晰命名和注释说明差异。