文档更新

docs/design/agent-design.md

@@ -38,13 +38,13 @@ Agent 在生命周期中主要通过 **基于 Token 的自动注册** 和 **心
 
 ### 1. 自动注册流程
 若 Agent 启动时本地 `agent.json` 的 `access_token` 为空，但配置了 `discovery_token`，将触发自动注册流程：
-1. Agent 向控制面 `/api/agent/register` 发送注册请求，携带本地硬件摘要、IP 及主机名。
+1. Agent 向控制面 `/api/v1/agent/nodes/register` 发送注册请求，携带本地硬件摘要、IP 及主机名。
 2. Server 校验 `discovery_token` 有效后，在数据库生成唯一的 `NodeID` 与专属 `AccessToken`（即 `agent_token`）并返回。
 3. Agent 将获取的专用 Token 写入本地配置文件，擦除一次性 `discovery_token`，后续所有的通信均基于专属 `AccessToken` 进行鉴权认证。
 
 ### 2. 双通道心跳与同步机制
 * **HTTP 轮询通道（兜底与探测）**：Agent 默认按设定的 `heartbeat_interval` 间隔发送 POST 心跳包。上报指标的同时获取当前激活版本的摘要信息（Version & Checksum）。
-* **WebSocket 通道（实时通信）**：在 HTTP 心跳成功后，Agent 自动尝试将连接升级为 WebSocket (`/api/agent/ws`)。
+* **WebSocket 通道（实时通信）**：在 HTTP 心跳成功后，Agent 自动尝试将连接升级为 WebSocket (`/api/v1/agent/ws`)。
   * WS 连接建立后，心跳与指标上报全面转移到 WS 管道，降低网络开销。
   * Server 发布或激活新版本时，通过 WS 广播通知 Agent。Agent 收到变更事件后，**立即触发同步流程**，实现秒级配置生效。
   * 若 WS 链路因网络问题断开，Agent 自动降级为 HTTP 轮询，并采用指数退避机制尝试重建 WS。
@@ -67,7 +67,7 @@ sequenceDiagram
         Note over Agent, Server: HTTP 兜底与 WebSocket 升级
         Agent->>Server: 3. 发送 HTTP Heartbeat (上报系统状态与健康度)
         Server-->>Agent: 4. 返回 ActiveConfig 摘要及 AgentSettings
-        Agent->>Server: 5. 发起 WebSocket 升级请求 (/api/agent/ws)
+        Agent->>Server: 5. 发起 WebSocket 升级请求 (/api/v1/agent/ws)
         Server-->>Agent: 6. 升级成功 (建立双向持久实时通道)
     end
 
@@ -171,5 +171,5 @@ graph TD
 为保证数据与控制链路的安全边界，Agent 代码编写与二次开发必须严格遵守以下工程约束：
 
 1. **零特权指令通道**：Server 绝对禁止向 Agent 传递任何任意 shell 命令或远程执行脚本（如 exec/eval 等）。所有系统控制原语（如启动、停止、重载、更新）必须硬编码在 Agent 二进制内部。
-2. **严格的 Token 过滤与前缀验证**：Agent 侧向 Server 请求资源时，接口端点固定以 `/api/agent/` 为前缀，并强制携带 `X-Agent-Token` 进行签名或令牌核验。
+2. **严格的 Token 过滤与前缀验证**：Agent 侧向 Server 请求资源时，接口端点固定以 `/api/v1/agent/` 为前缀，并强制携带 `X-Agent-Token` 进行签名或令牌核验。
 3. **节点自治原则**：Agent 须具备完备的离线工作能力。在与 Server 失去连接期间，本地 OpenResty 必须依靠本地已落地的配置保持反向代理服务的绝对正常运行。