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

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

internal/snapshot/snapshot.go

@@ -31,12 +31,17 @@ func (fn CollectorFunc) Collect(ctx context.Context, out *status.HostStatus) err
 
 // Cache 在并发安全接口后保存最近一次 HostStatus 快照。
 type Cache struct {
+	// collectors 是按固定顺序执行的子采集器集合。
 	collectors []Collector
-	version    string
-	startedAt  time.Time
-	mu         sync.RWMutex
-	last       status.HostStatus
-	hasLast    bool
+	// version 和 startedAt 会写入每次快照的 agent 元数据。
+	version   string
+	startedAt time.Time
+	// mu 保护 last 和 hasLast，允许 HTTP 与上报并发读取缓存。
+	mu sync.RWMutex
+	// last 保存最近一次完整或 partial 的 HostStatus。
+	last status.HostStatus
+	// hasLast 表示首次采集是否已经完成。
+	hasLast bool
 }
 
 // NewCache 使用给定采集器与 agent 元数据创建空的快照缓存。
@@ -59,6 +64,7 @@ func (c *Cache) Collect(ctx context.Context) status.HostStatus {
 
 	for _, collector := range c.collectors {
 		if err := collector.Collect(ctx, &out); err != nil {
+			// 单个子采集器失败只让整份快照降级为 partial，其他已成功字段继续对外可用。
 			out.Agent.SnapshotStatus = "partial"
 			out.Errors = append(out.Errors, status.StatusError{
 				Collector: collector.Name(),
@@ -67,6 +73,7 @@ func (c *Cache) Collect(ctx context.Context) status.HostStatus {
 		}
 	}
 
+	// 发布快照时一次性替换缓存，避免读者看到半写入的结构。
 	c.mu.Lock()
 	c.last = out
 	c.hasLast = true
@@ -83,6 +90,7 @@ func (c *Cache) Get() (status.HostStatus, bool) {
 
 // Run 立即采集一次，随后在 ctx 取消前按间隔刷新缓存。
 func (c *Cache) Run(ctx context.Context, interval time.Duration, timeout time.Duration) {
+	// 启动后先同步完成一轮采集，让 /health 和 /status 尽快进入就绪状态。
 	c.collectWithTimeout(ctx, timeout)
 	ticker := time.NewTicker(interval)
 	defer ticker.Stop()
@@ -98,6 +106,7 @@ func (c *Cache) Run(ctx context.Context, interval time.Duration, timeout time.Du
 
 // collectWithTimeout 在整体截止时间下执行一轮采集。
 func (c *Cache) collectWithTimeout(ctx context.Context, timeout time.Duration) {
+	// 超时通过 context 传递给子采集器；无法被 context 打断的系统调用仍依赖平台返回。
 	collectCtx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 	c.Collect(collectCtx)