huhuhuhr-1 · huhuhuhr-1 · Mar 12, 2026 · Mar 12, 2026
diff --git a/backend/main.py b/backend/main.py
@@ -85,6 +85,7 @@ def custom_generate_unique_id(route: APIRoute) -> str:
 # cache docs for different text
 _openapi_cache: Dict[str, Dict[str, Any]] = {}
 
+
 # replace placeholder
 def replace_placeholders_in_schema(schema: Dict[str, Any], trans: Dict[str, str]) -> None:
     """
@@ -102,7 +103,6 @@ def replace_placeholders_in_schema(schema: Dict[str, Any], trans: Dict[str, str]
             replace_placeholders_in_schema(item, trans)
 
 
-
 # OpenAPI build
 def get_language_from_request(request: Request) -> str:
     # get param from query ?lang=zh
@@ -155,7 +155,6 @@ def generate_openapi_for_lang(lang: str) -> Dict[str, Any]:
     return openapi_schema
 
 
-
 # custom /openapi.json and /docs
 @app.get("/openapi.json", include_in_schema=False)
 async def custom_openapi(request: Request):

diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,99 @@
+# 小助手嵌入示例
+
+本目录提供四个示例页面，演示如何在第三方页面中嵌入 SQLBot 小助手：**基础应用 / 高级应用** × **浮窗模式 / 全屏模式**。
+
+## 前置条件
+
+- **Node.js**：用于运行示例静态服务（建议 14+）
+- **SQLBot 服务**：已部署并可访问（如 `http://localhost:5173`）
+- **小助手应用**：在 SQLBot「小助手应用」中已创建至少一个**基础应用**和一个**高级应用**，并记下对应的应用 ID
+
+## 配置
+
+1. 打开 `config.js`，按实际环境修改：
+   - **SQLBOT_BASE_URL**：SQLBot 前端访问地址（末尾不要加 `/`），例如 `http://localhost:5173`
+   - **BASIC_ASSISTANT_ID**：基础应用的小助手 ID
+   - **ADVANCED_ASSISTANT_ID**：高级应用的小助手 ID
+
+2. 在 SQLBot 管理后台，为上述两个小助手应用的「跨域设置」中增加示例服务地址，例如：
+   - 若示例运行在 3000 端口：`http://localhost:3000`
+
+## 一键启动
+
+- **Linux / macOS**：在终端执行  
+  `./start.sh`  
+  或指定端口：`PORT=8080 ./start.sh`
+
+- **Windows**：双击 `start.bat`，或在 cmd 中执行  
+  `start.bat`  
+  修改端口可在执行前设置环境变量：`set PORT=8080` 后执行 `node server.js`
+
+启动后终端会输出访问地址（默认 `http://localhost:3000`），在浏览器打开即可从导航页进入四个示例。
+
+## 四种模式说明
+
+| 模式       | 说明 |
+|------------|------|
+| 基础 · 浮窗 | 通过 `assistant.js` 加载，页面右下角出现浮窗按钮，点击打开对话。数据源来自 SQLBot 中为该基础应用配置的数据源列表。 |
+| 基础 · 全屏 | 通过 `sqlbot-embedded-dynamic.umd.js` 在页面内挂载全屏对话区域。数据源同上。 |
+| 高级 · 浮窗 | 同上浮窗交互，但使用「高级应用」ID。数据源由第三方接口动态返回，需在 SQLBot 中配置接口 URL 与凭证。 |
+| 高级 · 全屏 | 同上全屏挂载，但使用「高级应用」ID。 |
+
+---
+
+## 详细测试方案
+
+### 测试环境
+
+- **浏览器**：Chrome、Edge 或 Safari（建议使用最新版）
+- **示例服务**：本目录通过 `start.sh` / `start.bat` 或 `node server.js` 启动后的地址（如 `http://localhost:3000`）
+- **SQLBot**：已配置的 `SQLBOT_BASE_URL` 对应服务可正常访问
+
+### 测试前准备
+
+1. 在 SQLBot「小助手应用」中，为将要使用的**基础应用**和**高级应用**在「跨域设置」中填入示例服务地址（如 `http://localhost:3000`），并保存。
+2. 确认 `config.js` 中 `SQLBOT_BASE_URL`、`BASIC_ASSISTANT_ID`、`ADVANCED_ASSISTANT_ID` 已正确填写。
+3. 启动示例服务并打开导航页 `http://localhost:3000`（或你设置的端口），确认页面底部「当前配置」显示正确。
+
+### 用例 1：基础应用 · 浮窗模式
+
+1. 在导航页点击「基础应用 · 浮窗」进入示例页。
+2. **预期**：页面右下角出现小助手浮窗按钮（图标或配置的 Logo）。
+3. 点击浮窗按钮，**预期**：弹出对话窗口，可输入内容。
+4. 发送一条简单问句（如「你好」或一个与已配置数据源相关的问题），**预期**：能收到回复或至少无控制台报错（若未配置数据源则可能提示无数据源，属正常）。
+5. **失败排查**：若未出现浮窗，检查浏览器控制台是否有跨域或脚本加载错误；确认跨域设置包含当前示例页的 origin（如 `http://localhost:3000`）。
+
+### 用例 2：基础应用 · 全屏模式
+
+1. 在导航页点击「基础应用 · 全屏」进入示例页。
+2. **预期**：页面主体为小助手对话界面（可能需等待 1～2 秒加载 UMD）。
+3. 在输入框中输入问题并发送，**预期**：能正常对话或看到加载/错误提示（与 SQLBot 及数据源配置一致）。
+4. **失败排查**：若白屏或一直加载，打开控制台查看是否 404（如 `sqlbot-embedded-dynamic.umd.js` 不存在）或跨域错误；确认 SQLBot 已部署包含该 UMD 的包（如 xpack）。
+
+### 用例 3：高级应用 · 浮窗模式
+
+1. 在导航页点击「高级应用 · 浮窗」进入示例页。
+2. **预期**：同样出现右下角浮窗按钮，点击后打开对话。
+3. 发送问题，**预期**：若已配置数据源接口且凭证正确，则与基础应用类似可正常对话；若未配置或接口不可用，可能提示无数据源或接口错误，属预期行为。
+4. **失败排查**：与用例 1 相同，另需在 SQLBot 中确认该高级应用的「配置接口」与「接口凭证」已正确填写。
+
+### 用例 4：高级应用 · 全屏模式
+
+1. 在导航页点击「高级应用 · 全屏」进入示例页。
+2. **预期**：全屏展示小助手对话界面，行为与用例 2 类似，但使用高级应用的数据源逻辑。
+3. 发送问题，**预期**：与用例 3 一致，取决于第三方数据源接口是否配置并可用。
+4. **失败排查**：同用例 2 与用例 3。
+
+### 常见问题与排查
+
+| 现象 | 可能原因 | 处理建议 |
+|------|----------|----------|
+| **浮窗/全屏完全没有效果** | 未配置 config.js 或 ID 为空 | 编辑 `example/config.js`，填写 `SQLBOT_BASE_URL`（如 `http://localhost:5173`）和 `BASIC_ASSISTANT_ID` / `ADVANCED_ASSISTANT_ID`（在「小助手应用」列表或编辑页可看到应用 ID），保存后刷新示例页。示例页在未配置时会显示黄色提示框。 |
+| 浮窗不出现或控制台跨域报错 | 小助手跨域设置未包含当前页面 origin | 在 SQLBot「小助手应用」中编辑对应小助手，在「跨域设置」中增加示例地址（如 `http://localhost:3000`），保存。 |
+| assistant.js 加载失败 / 404 | SQLBot 前端未启动或地址填错 | 确认 SQLBot 前端已启动（与 config 中 `SQLBOT_BASE_URL` 一致），浏览器可直接访问该地址。 |
+| 嵌入失败 / 接口报错 | 跨域未包含示例地址，或小助手不存在 | 同上「跨域设置」；并确认填写的 assistant ID 在「小助手应用」中存在。 |
+| 全屏页白屏或一直加载 | UMD 未部署或路径错误 | 确认 SQLBot 前端存在 `/xpack_static/sqlbot-embedded-dynamic.umd.js`；若项目无 xpack，全屏模式可能不可用，仅验证浮窗即可。 |
+| 对话提示无数据源 / 接口错误 | 基础应用未选数据源，或高级应用未配置/不可用接口 | 基础应用：在 SQLBot 中为该应用配置数据源；高级应用：配置接口 URL 与凭证，并确保接口返回约定格式。 |
+| 配置已改但页面仍显示旧 ID | 浏览器缓存 | 硬刷新（Ctrl+F5）或清缓存后重试。 |
+
+完成上述四个用例且行为符合预期，即可认为示例与当前 SQLBot 环境集成正常。
diff --git a/example/advanced-floating.html b/example/advanced-floating.html
@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>高级应用 - 浮窗模式</title>
+  <script src="config.js"></script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; background: #f5f6f8; color: #1f2329; line-height: 1.5; min-height: 100vh; }
+    .bar { background: #fff; padding: 12px 24px; box-shadow: 0 1px 2px rgba(0,0,0,.06); }
+    .bar a { color: #1cba90; text-decoration: none; font-size: 14px; }
+    .bar a:hover { text-decoration: underline; }
+    .main { max-width: 720px; margin: 0 auto; padding: 40px 24px; }
+    .main h1 { font-size: 20px; font-weight: 600; margin-bottom: 8px; }
+    .main p { color: #646a73; font-size: 14px; }
+  </style>
+</head>
+<body>
+  <div class="bar"><a href="index.html">← 返回示例首页</a></div>
+  <div class="main">
+    <h1>高级应用 · 浮窗模式</h1>
+    <p>本页嵌入的是「高级应用」小助手，右下角为浮窗入口。高级应用的数据源由第三方接口动态返回，需在 SQLBot 中配置接口 URL 与凭证后方可正常使用。</p>
+    <div id="config-tip" class="tip" style="display: none; margin-top: 16px; padding: 12px 16px; background: #fff3cd; border-radius: 8px; font-size: 14px; color: #856404;">
+      <strong>未检测到配置：</strong>请编辑 <code>example/config.js</code>，填写 <code>SQLBOT_BASE_URL</code> 和 <code>ADVANCED_ASSISTANT_ID</code>，并在小助手跨域设置中包含本页地址（如 http://localhost:3000）。
+    </div>
+    <div id="hint-tip" class="tip" style="display: none; margin-top: 16px; padding: 12px 16px; background: #e7f4ff; border-radius: 8px; font-size: 14px; color: #0c5394;">
+      <strong>若浮窗未出现：</strong>请确认 SQLBot 已启动、跨域包含本页地址，并打开控制台（F12）查看报错。
+    </div>
+  </div>
+  <script>
+    (function () {
+      var c = window.SQLBOT_EXAMPLE_CONFIG || {};
+      var id = (c.ADVANCED_ASSISTANT_ID || '').toString().trim();
+      var base = (c.SQLBOT_BASE_URL || '').toString().replace(/\/$/, '');
+      if (!id || !base) {
+        document.getElementById('config-tip').style.display = 'block';
+        return;
+      }
+      document.getElementById('hint-tip').style.display = 'block';
+      var script = document.createElement('script');
+      script.async = true;
+      script.defer = true;
+      script.id = 'sqlbot-assistant-float-script-' + id;
+      script.src = base + '/assistant.js?id=' + encodeURIComponent(id);
+      script.onerror = function () { console.error('assistant.js 加载失败：' + base); };
+      document.head.appendChild(script);
+    })();
+  </script>
+</body>
+</html>
diff --git a/example/advanced-fullscreen.html b/example/advanced-fullscreen.html
@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>高级应用 - 全屏模式</title>
+  <script src="config.js"></script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; background: #fff; color: #1f2329; height: 100vh; overflow: hidden; }
+    .bar { background: #fff; padding: 10px 24px; border-bottom: 1px solid #e5e6eb; flex-shrink: 0; }
+    .bar a { color: #1cba90; text-decoration: none; font-size: 14px; }
+    .bar a:hover { text-decoration: underline; }
+    .wrap { display: flex; flex-direction: column; height: 100vh; }
+    .copilot { flex: 1; min-height: 0; }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <div class="bar"><a href="index.html">← 返回示例首页</a></div>
+    <div class="copilot" id="copilot-root"></div>
+  </div>
+  <script>
+    (function () {
+      var c = window.SQLBOT_EXAMPLE_CONFIG || {};
+      var id = c.ADVANCED_ASSISTANT_ID;
+      var base = (c.SQLBOT_BASE_URL || '').replace(/\/$/, '');
+      if (!id || !base) {
+        document.getElementById('copilot-root').innerHTML = '<p style="padding:24px;color:#8f959e;">请在 config.js 中配置 SQLBOT_BASE_URL 和 ADVANCED_ASSISTANT_ID</p>';
+        return;
+      }
+      var script = document.createElement('script');
+      script.src = base + '/xpack_static/sqlbot-embedded-dynamic.umd.js';
+      script.onload = function () {
+        var timer = setInterval(function () {
+          if (window.sqlbot_embedded_handler && window.sqlbot_embedded_handler.mounted) {
+            clearInterval(timer);
+            window.sqlbot_embedded_handler.mounted('.copilot', { embeddedId: String(id) });
+          }
+        }, 100);
+        setTimeout(function () { clearInterval(timer); }, 15000);
+      };
+      document.head.appendChild(script);
+    })();
+  </script>
+</body>
+</html>
diff --git a/example/basic-floating.html b/example/basic-floating.html
@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>基础应用 - 浮窗模式</title>
+  <script src="config.js"></script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; background: #f5f6f8; color: #1f2329; line-height: 1.5; min-height: 100vh; }
+    .bar { background: #fff; padding: 12px 24px; box-shadow: 0 1px 2px rgba(0,0,0,.06); }
+    .bar a { color: #1cba90; text-decoration: none; font-size: 14px; }
+    .bar a:hover { text-decoration: underline; }
+    .main { max-width: 720px; margin: 0 auto; padding: 40px 24px; }
+    .main h1 { font-size: 20px; font-weight: 600; margin-bottom: 8px; }
+    .main p { color: #646a73; font-size: 14px; }
+  </style>
+</head>
+<body>
+  <div class="bar"><a href="index.html">← 返回示例首页</a></div>
+  <div class="main">
+    <h1>基础应用 · 浮窗模式</h1>
+    <p>本页通过 assistant.js 嵌入小助手，右下角会出现浮窗按钮，点击即可打开对话。数据源由 SQLBot 中配置的「基础应用」数据源列表决定。</p>
+    <div id="config-tip" class="tip" style="display: none; margin-top: 16px; padding: 12px 16px; background: #fff3cd; border-radius: 8px; font-size: 14px; color: #856404;">
+      <strong>未检测到配置：</strong>请编辑 <code>example/config.js</code>，填写 <code>SQLBOT_BASE_URL</code>（如 http://localhost:5173）和 <code>BASIC_ASSISTANT_ID</code>（小助手应用 ID），保存后刷新本页。并在 SQLBot「小助手应用」中将该小助手的跨域设置包含本页地址（如 http://localhost:3000）。
+    </div>
+    <div id="hint-tip" class="tip" style="display: none; margin-top: 16px; padding: 12px 16px; background: #e7f4ff; border-radius: 8px; font-size: 14px; color: #0c5394;">
+      <strong>若浮窗未出现：</strong>请确认 SQLBot 前端已启动（与 config 中地址一致）、小助手跨域设置包含本页地址，并打开浏览器控制台（F12）查看是否有报错或「嵌入失败」提示。
+    </div>
+  </div>
+  <script>
+    (function () {
+      var c = window.SQLBOT_EXAMPLE_CONFIG || {};
+      var id = (c.BASIC_ASSISTANT_ID || '').toString().trim();
+      var base = (c.SQLBOT_BASE_URL || '').toString().replace(/\/$/, '');
+      if (!id || !base) {
+        document.getElementById('config-tip').style.display = 'block';
+        return;
+      }
+      document.getElementById('hint-tip').style.display = 'block';
+      var script = document.createElement('script');
+      script.async = true;
+      script.defer = true;
+      script.id = 'sqlbot-assistant-float-script-' + id;
+      script.src = base + '/assistant.js?id=' + encodeURIComponent(id);
+      script.onerror = function () {
+        console.error('assistant.js 加载失败，请确认 SQLBOT_BASE_URL 可访问且 SQLBot 前端已启动：' + base);
+      };
+      document.head.appendChild(script);
+    })();
+  </script>
+</body>
+</html>
diff --git a/example/basic-fullscreen.html b/example/basic-fullscreen.html
@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>基础应用 - 全屏模式</title>
+  <script src="config.js"></script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif; background: #fff; color: #1f2329; height: 100vh; overflow: hidden; }
+    .bar { background: #fff; padding: 10px 24px; border-bottom: 1px solid #e5e6eb; flex-shrink: 0; }
+    .bar a { color: #1cba90; text-decoration: none; font-size: 14px; }
+    .bar a:hover { text-decoration: underline; }
+    .wrap { display: flex; flex-direction: column; height: 100vh; }
+    .copilot { flex: 1; min-height: 0; }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <div class="bar"><a href="index.html">← 返回示例首页</a></div>
+    <div class="copilot" id="copilot-root"></div>
+  </div>
+  <script>
+    (function () {
+      var c = window.SQLBOT_EXAMPLE_CONFIG || {};
+      var id = c.BASIC_ASSISTANT_ID;
+      var base = (c.SQLBOT_BASE_URL || '').replace(/\/$/, '');
+      if (!id || !base) {
+        document.getElementById('copilot-root').innerHTML = '<p style="padding:24px;color:#8f959e;">请在 config.js 中配置 SQLBOT_BASE_URL 和 BASIC_ASSISTANT_ID</p>';
+        return;
+      }
+      var script = document.createElement('script');
+      script.src = base + '/xpack_static/sqlbot-embedded-dynamic.umd.js';
+      script.onload = function () {
+        var timer = setInterval(function () {
+          if (window.sqlbot_embedded_handler && window.sqlbot_embedded_handler.mounted) {
+            clearInterval(timer);
+            window.sqlbot_embedded_handler.mounted('.copilot', { embeddedId: String(id) });
+          }
+        }, 100);
+        setTimeout(function () { clearInterval(timer); }, 15000);
+      };
+      document.head.appendChild(script);
+    })();
+  </script>
+</body>
+</html>
diff --git a/example/config.js b/example/config.js
@@ -0,0 +1,12 @@
+/**
+ * 小助手示例配置（浏览器端）
+ * 请在运行示例前修改 SQLBOT_BASE_URL 与两个 ID。
+ */
+window.SQLBOT_EXAMPLE_CONFIG = {
+  /** SQLBot 服务地址，末尾不要加 /，例如 http://localhost:8000 */
+  SQLBOT_BASE_URL: 'http://localhost:8000',
+  /** 基础应用的小助手 ID（在「小助手应用」中创建基础应用后获得） */
+  BASIC_ASSISTANT_ID: '7437401056310464512',
+  /** 高级应用的小助手 ID（在「小助手应用」中创建高级应用后获得） */
+  ADVANCED_ASSISTANT_ID: '7437401056310464512',
+};