# 仓库规则

## 项目要求

### 项目简介

- MFD Monitor Agent 是一个使用 Go 实现的单二进制主机状态监控 agent。
- agent 需要支持 Windows 和 Linux，用于采集并暴露完整主机状态。
- agent 默认通过 HTTP API 提供查询能力，默认监听 `0.0.0.0:8080`。
- `GET /health?token=` 用于返回进程存活状态、版本信息、最近快照时间和最近采集状态。
- `GET /status?token=` 用于返回缓存中的完整 `HostStatus` 主机状态快照。
- `http.token` 配置在 JSON 中；`agent run` 时若工作目录无 `config.json` 则自动生成含随机 token 的默认文件。
- 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` 或具体错误原因。
- 默认监听 `0.0.0.0:8080`，必须通过查询参数 `?token=` 鉴权；`http.token` 不能为空。

### 架构要求

- 使用单进程一体化架构。
- 一个 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`：统一加载监听地址、HTTP token、采集周期、上报周期、上报目标、机器标识等配置。

### 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 监听信息、线程列表、进程句柄、连接状态详情、Bearer Token/mTLS。
- 首版 HTTP API 使用查询参数 token 鉴权（非 Bearer/mTLS）。

## 注释规则

- 所有导出和内部的方法、函数、类结构、结构体、接口都必须编写清晰注释。
- Go 代码中，每个包级函数、方法、类型、结构体和接口都需要使用简短注释说明其用途和行为。
- 结构体注释需要说明该结构体代表什么。字段不够直观、包含单位、涉及安全影响，或会影响外部 JSON/API 行为时，需要为字段补充注释。
- 方法和函数注释需要说明其职责、重要输入输出、副作用，以及相关错误行为。
- 关键实现步骤需要添加简洁的行内注释说明逻辑，尤其是操作系统相关采集、权限敏感操作、缓存、上报、服务生命周期处理和错误降级路径。
- 注释应解释代码为什么存在，或说明不直观逻辑如何工作。避免只重复代码本身含义的注释。
- 修改代码行为时必须同步更新注释。不要留下过期注释、缺少上下文的 TODO，或容易误导的说明。

## 项目风格

- 优先使用直接、清晰的 Go 代码，并保持与现有单二进制 agent 结构一致。
- 代码变更应聚焦在请求的行为范围内。
- 保留采集器的部分成功行为：某个子系统失败时，应报告该子系统自身错误，而不是导致整个状态响应失败。
- Linux 和 Windows 行为不同的代码路径，需要使用清晰命名和注释说明差异。