✨ feat(agent): 添加 token 鉴权和流程文档

* 默认监听调整为 0.0.0.0:8080，并要求查询参数 token
* 支持首次 run 自动生成含随机 token 的配置文件
* 补充 HTTP 鉴权、配置校验和相关测试
* 完善代码注释，覆盖缓存、上报、服务和平台采集路径
* 新增架构与开发流程文档，补充一键构建脚本

docs/DEPLOYMENT.md

@@ -7,12 +7,28 @@
 MFD Monitor Agent 是单二进制主机状态采集程序，具备以下能力：
 
 - 后台周期采集主机状态并写入内存缓存
-- 本地 HTTP API：`GET /health`、`GET /status`（默认仅监听 `127.0.0.1:8080`）
+- 本地 HTTP API：`GET /health?token=...`、`GET /status?token=...`（默认监听 `0.0.0.0:8080`，需配置 `http.token`）
 - 可选周期性向中心端 POST 与 `/status` 相同结构的 `HostStatus` JSON
 - CLI 管理服务生命周期：`run`、`install`、`uninstall`、`start`、`stop`、`version`
 
 HTTP 接口与上报均读取同一份缓存，**不会在每次请求时实时扫描系统**。
 
+更多内部流程见 [架构与工作流程](ARCHITECTURE.md)，构建测试流程见 [开发流程](DEVELOPMENT.md)。
+
+## 运行流程
+
+`agent run` 的运行链路如下：
+
+1. 解析 `-config`；未指定时使用当前目录 `config.json`。
+2. 配置不存在时自动生成默认配置与随机 `http.token`，文件权限为 `0600`。
+3. 加载 JSON，并应用 `MFD_AGENT_*` 环境变量覆盖。
+4. 启动 `snapshot.Cache.Run`，立即采集一次并按 `collect.interval` 周期刷新缓存。
+5. 如果 `report.enabled=true`，启动主动上报循环。
+6. 启动 HTTP API，默认监听 `0.0.0.0:8080`。
+7. 收到退出信号后优雅关闭 HTTP server。
+
+单轮采集使用 `collect.timeout` 作为整体超时。子采集器失败不会导致整份 `/status` 失败，而是记录到 `errors[]` 并将 `agent.snapshot_status` 标记为 `partial`。
+
 ## 环境要求
 
 | 项目 | 要求 |
@@ -92,13 +108,16 @@ C:\ProgramData\MFD\config.json
 
 ### JSON 配置文件
 
-所有字段均有安全默认值；未提供配置文件时也可仅依赖环境变量启动。
+`agent run` 在未指定 `-config` 时使用当前工作目录下的 `config.json`；若文件不存在，会自动生成含随机 `http.token` 的默认配置（权限 `0600`）。
+
+`install` / `start` 等命令不会自动创建配置文件，需事先准备好 JSON。
 
 ```json
 {
   "host_id": "host-a",
   "http": {
-    "listen_address": "127.0.0.1:8080"
+    "listen_address": "0.0.0.0:8080",
+    "token": "请替换为强随机值"
   },
   "collect": {
     "interval": "30s",
@@ -121,7 +140,8 @@ C:\ProgramData\MFD\config.json
 | 字段 | 说明 | 默认值 |
 |------|------|--------|
 | `host_id` | 机器标识；为空时采集器可回退为主机名 | `""` |
-| `http.listen_address` | 本地 HTTP 监听地址 | `127.0.0.1:8080` |
+| `http.listen_address` | HTTP 监听地址 | `0.0.0.0:8080` |
+| `http.token` | API 查询参数 `?token=` 鉴权密钥（必填） | 无（`run` 自动生成） |
 | `collect.interval` | 采集周期 | `30s` |
 | `collect.timeout` | 单次采集总超时 | `10s` |
 | `report.enabled` | 是否启用主动上报 | `false` |
@@ -132,18 +152,22 @@ C:\ProgramData\MFD\config.json
 | `service.display_name` | Windows 显示名称 | `MFD Monitor Agent` |
 | `service.description` | systemd unit 描述 | 见默认配置 |
 
-**校验规则：** `report.enabled=true` 时必须设置 `report.endpoint`，否则 `config.Load` 失败。
+**校验规则：**
+
+- `http.token` 不能为空，否则 `config.Load` 失败。
+- `report.enabled=true` 时必须设置 `report.endpoint`，否则 `config.Load` 失败。
 
 时长字段使用 Go duration 字符串，例如 `"30s"`、`"1m"`。
 
 ### 环境变量覆盖
 
-在 JSON 加载后，以下环境变量可覆盖对应配置（`Load("")` 时同样生效）：
+在 JSON 加载后，以下环境变量可覆盖对应配置：
 
 | 环境变量 | 配置字段 |
 |----------|----------|
 | `MFD_AGENT_HOST_ID` | `host_id` |
 | `MFD_AGENT_LISTEN` | `http.listen_address` |
+| `MFD_AGENT_TOKEN` | `http.token` |
 | `MFD_AGENT_COLLECT_INTERVAL` | `collect.interval` |
 | `MFD_AGENT_COLLECT_TIMEOUT` | `collect.timeout` |
 | `MFD_AGENT_REPORT_ENABLED` | `report.enabled` |
@@ -260,8 +284,10 @@ sc.exe query mfd-monitor-agent
 
 ### 健康检查
 
+将 `YOUR_TOKEN` 替换为配置文件中的 `http.token`：
+
 ```bash
-curl -s http://127.0.0.1:8080/health | jq .
+curl -s 'http://127.0.0.1:8080/health?token=YOUR_TOKEN' | jq .
 ```
 
 首次采集完成前可能返回 `503` 且 `{"status":"starting"}`。就绪后示例：
@@ -280,9 +306,11 @@ curl -s http://127.0.0.1:8080/health | jq .
 ### 完整状态
 
 ```bash
-curl -s http://127.0.0.1:8080/status | jq '.agent, .host, .processes.status, .tcp_listeners.status'
+curl -s 'http://127.0.0.1:8080/status?token=YOUR_TOKEN' | jq '.agent, .host, .processes.status, .tcp_listeners.status'
 ```
 
+浏览器调试示例：`http://<host>:8080/status?token=YOUR_TOKEN`
+
 ### 主动上报验收
 
 1. 在配置中设置 `report.enabled=true` 与可达的 `report.endpoint`
@@ -311,8 +339,9 @@ sc.exe start mfd-monitor-agent
 
 ## 安全注意事项
 
-- **默认仅本机监听**（`127.0.0.1:8080`），避免将进程列表、监听端口等敏感信息默认暴露到网络。
-- 若需远程拉取，应通过反向代理、mTLS 或防火墙限制来源，而非直接绑定 `0.0.0.0`（除非明确接受风险）。
+- **默认监听所有网卡**（`0.0.0.0:8080`），`/health` 与 `/status` 均须通过查询参数 `?token=` 鉴权。
+- Token 会出现在 URL 中，代理与访问日志可能记录完整 URL；生产环境建议使用 HTTPS 反向代理、防火墙限制来源，并定期轮换 token。
+- 自动生成的 `config.json` 权限为 `0600`，请妥善保管其中的 `http.token`。
 - 服务账户权限越高，采集越完整；生产环境应在「采集完整性」与「最小权限」之间权衡。
 - `/status` 响应体可能较大（进程多、监听多时），注意中心端与本地内存占用。
 
@@ -320,7 +349,9 @@ sc.exe start mfd-monitor-agent
 
 | 现象 | 可能原因 | 处理建议 |
 |------|----------|----------|
+| 启动报错 `http.token is required` | 配置中 token 为空 | 在 JSON 中设置 `http.token`，或使用 `agent run` 自动生成 |
 | 启动报错 `report endpoint is required` | 开启上报但未配置 endpoint | 设置 `report.endpoint` 或关闭 `report.enabled` |
+| HTTP `401 unauthorized` | 缺少或错误的 `?token=` | 使用配置文件中的 `http.token` |
 | `install requires root` | Linux 非 root 执行 install | 使用 `sudo` |
 | `service install is not implemented` | 非 Linux/Windows | 仅使用 `run` 前台模式 |
 | `/health` 长期 `starting` | 首次采集未完成或采集卡住 | 检查 `collect.timeout`、系统负载与权限 |
@@ -332,5 +363,7 @@ sc.exe start mfd-monitor-agent
 ## 相关文档
 
 - 项目简介：[README.md](../README.md)
+- 架构与流程：[docs/ARCHITECTURE.md](ARCHITECTURE.md)
+- 开发与构建：[docs/DEVELOPMENT.md](DEVELOPMENT.md)
 - 架构与规范：[AGENTS.md](../AGENTS.md)
 - 示例配置：[configs/example.json](../configs/example.json)