# MFD Monitor Agent 开发流程

本文档记录当前仓库的构建、测试和跨平台验证流程。

## 本地环境

- Go 版本见 [go.mod](../go.mod)
- Linux 服务化验证需要 systemd
- Windows 服务化验证需要管理员 PowerShell
- 构建产物默认写入 `dist/`，该目录不提交到 Git

## 测试命令

运行全部单元测试：

```bash
go test ./...
```

按包运行：

```bash
go test ./internal/collector
go test ./internal/httpapi
go test ./internal/reporter
go test ./internal/service
go test ./internal/snapshot
```

Windows 编译与测试验证：

```bash
GOOS=windows GOARCH=amd64 go test ./...
```

## Linux 构建

```bash
./scripts/build-linux.sh
```

默认产物：

```text
dist/agent-linux-amd64
```

常用变量：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OUT_DIR` | 输出目录 | `dist` |
| `VERSION` | 注入到 `cmd/agent.version` 的版本号 | `0.1.0` |
| `GOOS_TARGET` | 目标系统 | `linux` |
| `GOARCH_TARGET` | 目标架构 | `amd64` |
| `OUTPUT_NAME` | 输出文件名 | `agent-<goos>-<goarch>` |
| `CGO_ENABLED` | CGO 开关 | `0` |

版本号注入示例：

```bash
VERSION=1.0.0 ./scripts/build-linux.sh
./dist/agent-linux-amd64 version
```

## Windows 构建

在 Windows PowerShell：

```powershell
.\scripts\build-windows.ps1
```

默认产物：

```text
dist\agent-windows-amd64.exe
```

从 Linux 交叉编译 Windows：

```bash
GOOS_TARGET=windows GOARCH_TARGET=amd64 OUTPUT_NAME=agent-windows-amd64.exe ./scripts/build-linux.sh
```

## 全平台构建

仓库包含 `scripts/build-all.sh`，用于一次构建 Linux amd64 与 Windows amd64 产物：

```bash
./scripts/build-all.sh
```

建议发布前执行：

```bash
go test ./...
GOOS=windows GOARCH=amd64 go test ./...
./scripts/build-all.sh
```

## 开发验证重点

变更采集逻辑时，重点验证：

- 单个子采集器失败后 `agent.snapshot_status=partial`
- `errors[]` 包含失败采集器名称和错误摘要
- `processes.status` 与 `tcp_listeners.status` 正确反映 `ok`、`partial`、`error`
- HTTP 请求只读取缓存，不触发实时采集
- 上报载荷与 `/status` 的 `HostStatus` 结构一致
- 上报失败不会影响本地 HTTP 服务

变更服务逻辑时，重点验证：

- Linux `install` 非 root 返回错误
- systemd unit 的 `ExecStart` 保留 `run -config <path>`
- Windows `sc.exe create` 的 `binPath` 包含 `run -config <path>`
- `uninstall` 对已停止或不存在的服务尽力清理

## 文档关系

- [README.md](../README.md)：项目入口与快速命令
- [DEPLOYMENT.md](DEPLOYMENT.md)：部署、验收、安全与排障
- [ARCHITECTURE.md](ARCHITECTURE.md)：运行时架构和工作流程
- [AGENTS.md](../AGENTS.md)：仓库规则与功能边界
- [plan.md](../plan.md)：历史设计草案，当前行为以代码和 docs 文档为准