mfd-monitor-agent/AGENTS.md

仓库规则

项目要求

项目简介

• 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 行为不同的代码路径，需要使用清晰命名和注释说明差异。