diff --git a/docs/mqtt-commands.md b/docs/mqtt-commands.md
new file mode 100644
index 0000000..8320e64
--- /dev/null
+++ b/docs/mqtt-commands.md
@@ -0,0 +1,159 @@
+# MQTT 标准操作手册（OPC 智能园区大屏系统）
+
+> 通过 MQTT 对前端大屏进行集中控制：切页、页面操作、媒体控制、视觉开关、状态上报。
+
+## 1. Broker 连接
+
+| 项 | 值 | 说明 |
+|---|---|---|
+| 地址 | `192.168.1.3` | 局域网 EMQX Broker |
+| TCP 端口 | `1883` | MQTT 标准端口（后端/命令行用） |
+| WebSocket 端口 | `8083` | 前端浏览器用（`ws://192.168.1.3:8083/mqtt`） |
+| 用户名/密码 | `backend/.env` 的 `MQTT_USERNAME` / `MQTT_PASSWORD` | 连接鉴权 |
+
+## 2. 频道（Topic）
+
+| Topic | 方向 | 载荷 | 用途 |
+|---|---|---|---|
+| `opc/display/command` | 服务端 → 前端 | 指令信封 | **控制指令**（切页/页面操作/媒体/视觉） |
+| `opc/dashboard/tick` | 服务端 → 前端 | 园区数据快照 | 数据大屏实时刷新（2.2s） |
+| `opc/display/heartbeat` | 前端 → 服务端 | `{client_id, page, ts}` | 大屏在线心跳（10s） |
+| `opc/frontend/state` | 前端 → 服务端 | `{client_id, page, ts}` | **页面状态即时上报**（路由变化即发） |
+| `opc/display/ack` | 前端 → 服务端 | 指令回执 | 指令确认（可选） |
+
+## 3. 统一指令信封
+
+所有控制指令发到 `opc/display/command`，JSON 格式：
+
+```json
+{
+  "cmd_id": "uuid",          // 指令 ID（可选）
+  "ts": 1755490000000,       // 时间戳 ms（可选）
+  "action": "navigate",      // 命令名（必填）
+  "params": { "page": "/ai" } // 参数（按命令）
+}
+```
+
+后端 `hub.publish_command(action, params)` 自动生成信封；命令行手动发送时只需 `action` + `params`。
+
+## 4. 命令全集
+
+### 4.1 页面切换
+
+| action | params | 效果 |
+|---|---|---|
+| `navigate` | `page: "/" \| "/twin" \| "/ai" \| "/voice" \| "/screen"`（或别名 home/twin/ai/voice/screen/数据大屏…） | 切换到指定页面 |
+| `navigate_rel` | `delta: 1 \| -1` | 向右 / 向左循环切换页面 |
+
+### 4.2 全局视觉识别
+
+| action | params | 效果 |
+|---|---|---|
+| `vision_set` | `enabled: true \| false` | 开启 / 关闭全局人物识别（YOLO 人脸/姿态/手势） |
+
+### 4.3 AI 助手页（/ai）
+
+| action | params | 效果 |
+|---|---|---|
+| `ai_input` | `text: "介绍一下入驻政策"` | 输入问题并自动发送 |
+| `ai_preset` | `index: 0 \| 1 \| 2` | 选择预设问题并发送 |
+| `ai_company` | `action: "next" \| "prev"` | 切换展示企业 |
+| `ai_zone` | `zone: "加速区" \| "国际区" \| "成长区"` | 切换企业分区 |
+
+### 4.4 语音对话页（/voice）
+
+| action | params | 效果 |
+|---|---|---|
+| `voice_start` | — | 启动语音对话 |
+| `voice_stop` | — | 关闭语音对话 |
+| `voice_refresh` | — | 刷新页面 |
+
+### 4.5 媒体轮播页（/screen）
+
+| action | params | 效果 |
+|---|---|---|
+| `play` / `pause` | — | 播放 / 暂停 |
+| `next` / `prev` | — | 下一项 / 上一项 |
+| `set_mode` | `mode: sequential \| shuffle \| loop` | 播放模式 |
+| `play_target` | `path: "媒体路径"` | 播放指定媒体 |
+| `settings_changed` | 设置对象 | 应用设置变更 |
+| `playlist_changed` | — | 重新加载播放列表 |
+
+### 4.6 全局
+
+| action | params | 效果 |
+|---|---|---|
+| `alert` | `text: "通知内容"` | 全局通知弹窗 |
+| `show_card` | 卡片数据 | 展示信息卡片 |
+| `minimize` | — | 最小化窗口（Tauri） |
+
+## 5. 命令行发送
+
+### mosquitto_pub（推荐，需安装 `mosquitto-clients`）
+
+```bash
+# 切页到 AI 助手
+mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
+  -t opc/display/command \
+  -m '{"action":"navigate","params":{"page":"/ai"}}'
+
+# 向左切页
+mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
+  -t opc/display/command -m '{"action":"navigate_rel","params":{"delta":-1}}'
+
+# 关闭人物识别
+mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
+  -t opc/display/command -m '{"action":"vision_set","params":{"enabled":false}}'
+
+# AI 页提问
+mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
+  -t opc/display/command -m '{"action":"ai_input","params":{"text":"介绍一下入驻政策"}}'
+
+# 切换企业分区
+mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
+  -t opc/display/command -m '{"action":"ai_zone","params":{"zone":"国际区"}}'
+
+# 语音启动 / 媒体下一项
+mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
+  -t opc/display/command -m '{"action":"voice_start","params":{}}'
+mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
+  -t opc/display/command -m '{"action":"next","params":{}}'
+```
+
+### Python（paho-mqtt，后端 venv 自带）
+
+```bash
+cd /Volumes/Pine/mycode/DPM/dpm/backend
+.venv/bin/python - <<'EOF'
+import paho.mqtt.client as mqtt
+
+def send(action, params=None):
+    c = mqtt.Client()
+    c.username_pw_set("用户名", "密码")
+    c.connect("192.168.1.3", 1883, 30)
+    c.publish("opc/display/command", str({"action": action, "params": params or {}}))
+    c.disconnect()
+
+send("navigate", {"page": "/voice"})
+send("ai_company", {"action": "next"})
+send("voice_stop")
+EOF
+```
+
+### MQTTX（图形界面）
+
+1. 新建连接：`mqtt://192.168.1.3:1883`，填用户名/密码
+2. 发布到 `opc/display/command`，消息体如上 JSON
+
+## 6. 订阅调试
+
+```bash
+# 监听前端页面上报（验证"当前页面"）
+mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/frontend/state'
+
+# 监听心跳
+mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/display/heartbeat'
+
+# 监听全部指令
+mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/display/command' -v
+```