diff --git a/docs/deployment.md b/docs/deployment.md
index 63230684..1a2e9aae 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -100,6 +100,33 @@ docker compose up -d
 * 用户名：`root`
 * 密码：`123456`
 
+### 2.5 Swagger 文档使用
+
+登录管理端后，访问：`http://localhost:3000/swagger/index.html`
+
+使用说明：
+
+* Swagger UI 受管理端登录态保护，未登录不可直接访问
+* 可在浏览器中查看当前 Server API 与 Agent API 定义，并直接发起调试请求
+* 当 Server API 新增或变更时，需要同步更新 Swag 注解并重新生成 `atsf_server/docs`
+
+如需在本地重新生成 Swagger 文档，先安装 `swag`：
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@latest
+```
+
+安装后请确保 Go 的二进制目录已加入 `PATH`，常见目录为：
+
+* Linux / macOS：`$HOME/go/bin`
+* Windows：`%USERPROFILE%\go\bin`
+
+如需在本地重新生成 Swagger 文档，可在 `atsf_server` 目录执行：
+
+```bash
+swag init -g main.go -o docs
+```
+
 ---
 
 ## 3. Agent 配置
@@ -342,6 +369,6 @@ GitHub Release 中的 Agent 二进制命名格式：
 
 ---
 
-## 8. 文档维护要求
+## 11. 文档维护要求
 
 当部署方式、配置字段、节点接入方式或联调流程变化时，同步更新本文档。
diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md
index 9c00e960..59416a66 100644
--- a/docs/development-guidelines.md
+++ b/docs/development-guidelines.md
@@ -296,13 +296,13 @@ V3 新增行为：
 
 更新顺序：
 
-1. `docs/design.md`
-2. `docs/development-guidelines.md`
-3. `docs/development-plan.md`
-4. `docs/deployment.md`
-
-## 12. Swagger 鏂囨。绾︽潫
-
-* Server 鎻愪緵 Swagger UI 鍏ュ彛锛?`/swagger/index.html`
-* Swagger UI 浠呭宸茬櫥褰曠殑绠＄悊绔敤鎴峰紑鏀撅紝涓嶅悜鍖垮悕鐢ㄦ埛鍏紑
-* 鏂板鎴栦慨鏀?API 鏃讹紝闇€鍚屾鏇存柊 Swag 娉ㄨВ骞堕噸鏂扮敓鎴?`atsf_server/docs`
+1. `docs/design.md`
+2. `docs/development-guidelines.md`
+3. `docs/development-plan.md`
+4. `docs/deployment.md`
+
+## 12. Swagger 文档约束
+
+* Server 提供 Swagger UI 入口：`/swagger/index.html`
+* Swagger UI 仅对已登录的管理端用户开放，不向匿名用户公开
+* 新增或修改 API 时，必须同步更新 Swag 注解并重新生成 `atsf_server/docs`