docs: 接口注意事项（前缀 / 整表替换 / 必须 apply / reload 需等待）

验证过程中实际踩到的四点，写进 README 便于 agent 与人复用：
1. 管理接口前缀是 /admin/api；打根 /api/ 会拿到 200 + Dashy HTML 的假成功，
   判断是否命中要看返回体类型而非状态码
2. 路由表是整表替换，必须提交完整 {routes:[...]}；清空非空表需 force:true
3. 改完必须 apply（内部 nginx -t 校验，失败保留旧配置并回显 nginx 报错）
4. apply 是异步 reload：立刻探测会得到旧结果（表现为'apply 了却 404'），
   给出轮询等待入口就绪的示例脚本

README.md

@@ -590,6 +590,28 @@ curl -s http://127.0.0.1:18080/api/schema | jq        # 人读：items + resourc
 | 图标上传 | `POST /api/icon`（multipart，字段 `file`） |
 | 重建导航分区 | `POST /api/reload` |
 
+### 接口注意事项（agent 最容易踩的四点）
+
+1. **前缀是 `/admin/api`**（经统一入口）；容器内也可直连 `http://127.0.0.1:3005/api`。
+   根路径 `/api/` 不是管理接口：打到那里会得到 **200 + Dashy 的 HTML**，看着像成功其实什么都没改。
+   判断是否命中看返回体类型（JSON vs `<!DOCTYPE html>`），别只看状态码。
+2. **路由表是整表替换**：必须提交完整 `{"routes":[…]}`。只给单个路由对象会被 400 拒绝并提示；
+   清空非空表要显式 `force:true`。该接口只改路由表，**不会**动入口端口/TLS/认证地址等其它字段。
+3. **改完必须 apply**：`POST /admin/api/gateway/apply` 先做 `nginx -t` 校验，不通过则保留上一份
+   可用配置，并把 nginx 报错原文返回给你（不会把入口改坏）。
+4. **apply 之后是异步 reload**，不是同步生效：立刻探测可能拿到旧结果（表现为"明明 apply 了却 404"）。
+   正确做法是轮询等入口就绪：
+
+   ```bash
+   HOST=app.example.com
+   for i in $(seq 1 20); do
+     code=$(curl -s -o /dev/null -w '%{http_code}' -m 3 --resolve "$HOST:3080:127.0.0.1" "https://$HOST:3080/")
+     [ "$code" != "000" ] && break
+     sleep 0.5
+   done
+   echo "$code"
+   ```
+
 **示例：让 agent 一次性把站点改成你要的样子**
 
 ```bash