437 lines
14 KiB
Markdown
437 lines
14 KiB
Markdown
# 工作台问答 · iframe 嵌入开发说明
|
||
|
||
本文档说明如何将 DeerFlow **通用工作台问答**（与 `/page/workspace/chats/*` 同一套 LangGraph 流式能力）以**普通 iframe** 形式嵌入第三方页面，并在**父页面无法读取子 frame 内 `thread_id`** 的前提下，轮询「本次问答是否已结束」。
|
||
|
||
后端公开 API 实现见：`offline-backend-20260512/backend/app/gateway/routers/public_embed.py`
|
||
数据表：`embed_sessions`（迁移 `20260602_01`）
|
||
|
||
---
|
||
|
||
## 0. 速读
|
||
|
||
| 角色 | 要做的事 |
|
||
|------|----------|
|
||
| **父页面** | 自己生成 `sessionId`（UUID），拼进 iframe `src`；用 `sessionId` 调公开 API 轮询 `finished` |
|
||
| **iframe（DeerFlow）** | 打开 `/embed/chats/...`，自动登录、自动发问、登记 `sessionId → thread_id` |
|
||
| **不需要** | 无界（wujie）、父页面拿 `thread_id`、DeerFlow 登录态 Cookie |
|
||
|
||
**完成条件**：`GET .../sessions/{sessionId}/status` 返回 `finished === true`（且无进行中的 run，非澄清中断）。
|
||
|
||
---
|
||
|
||
## 1. 背景与约束
|
||
|
||
### 1.1 业务目标
|
||
|
||
- 第三方系统用 **iframe** 嵌 DeerFlow 问答 UI。
|
||
- 传入：**问题文案**、**用户名**（走现有 `login/username`）、**主题色**。
|
||
- 展示：**消息列表** + **沙箱/产物侧栏**（与主聊天相同的 `ChatBox`）；**隐藏**页面左侧栏、Workspace 侧栏、底部输入框。
|
||
- 进入后 **自动发送** 首条用户消息并走流式问答。
|
||
|
||
### 1.2 为何需要 `sessionId`
|
||
|
||
iframe 与父页面通常 **跨域**，父页面 **不能** 读取子应用 URL 里的 `thread_id`（hash 路由在子 frame 内）。
|
||
因此约定：
|
||
|
||
1. **父页面**在打开 iframe 前生成全局唯一的 `sessionId`；
|
||
2. **子页面**在创建/确定 `thread_id` 后，调用后端 **登记接口** 写入 `session_id → thread_id`；
|
||
3. **父页面**只凭 `sessionId` 查询状态，必要时响应里会带上 `thread_id`（可选使用）。
|
||
|
||
---
|
||
|
||
## 2. 端到端流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Parent as 父页面
|
||
participant Iframe as DeerFlow iframe
|
||
participant API as Gateway /api/public/embed
|
||
|
||
Parent->>Parent: sessionId = crypto.randomUUID()
|
||
Parent->>Iframe: iframe src 含 sessionId、message、username、theme
|
||
Iframe->>Iframe: loginByUsername + 自动 sendMessage
|
||
Iframe->>API: POST /sessions { session_id, thread_id }
|
||
loop 每 1–3s
|
||
Parent->>API: GET /sessions/{sessionId}/status
|
||
API-->>Parent: registered, finished, thread_id
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 前端路由与页面
|
||
|
||
### 3.1 路由（独立于 `/page/*`）
|
||
|
||
在 `App.tsx` 注册，**不经过** `PageRoutes` / `PageSidebar`，因此无外层导航与 Workspace 侧栏。
|
||
|
||
| 路由 | 组件 | 说明 |
|
||
|------|------|------|
|
||
| `/embed/chats/:thread_id` | `EmbedChatPage`（外包 `ChatRuntime`） | `thread_id` 可为 `new` 或已有 UUID |
|
||
|
||
示例（HashRouter，注意 `#`）：
|
||
|
||
```
|
||
http://localhost:5173/#/embed/chats/new?sessionId=...&message=...&username=guest&theme=red
|
||
```
|
||
|
||
开发环境端口以本地 Vite 为准（如 5173 / 5174）。
|
||
|
||
### 3.2 URL 查询参数
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `sessionId` 或 `session_id` | **是** | 父页面生成的关联 id，8–128 位，仅字母数字 `_` `-` |
|
||
| `message` / `question` / `text` | 建议 | 首条用户问题；有则进入后自动发送 |
|
||
| `username` / `userName` | 否 | 默认 `guest`，对应 `POST /api/v1/auth/login/username` |
|
||
| `theme` | 否 | `dark-blue` → 深色；`red` 等 → 浅色（与 `LoginPage` 一致） |
|
||
|
||
缺少 `sessionId` 时，嵌入页会提示错误，不会发起登记。
|
||
|
||
### 3.3 相关源码
|
||
|
||
| 路径 | 职责 |
|
||
|------|------|
|
||
| [src/pages/EmbedChatPage.tsx](../src/pages/EmbedChatPage.tsx) | 嵌入页：登录、自动发问、登记 session、仅消息列表 + ChatBox |
|
||
| [src/core/embed/params.ts](../src/core/embed/params.ts) | 从 URL 解析嵌入参数 |
|
||
| [src/core/embed/status-api.ts](../src/core/embed/status-api.ts) | 登记 / 轮询 API 封装 |
|
||
| [src/App.tsx](../src/App.tsx) | 路由注册 |
|
||
|
||
### 3.4 UI 行为说明
|
||
|
||
- **隐藏**：`PageSidebar`、`WorkspaceSidebar`、`InputBox`、顶栏标题栏等（相对完整 `ChatPage`）。
|
||
- **保留**：`MessageList`、流式指示、澄清卡片（若 agent 触发 `ask_clarification`）、右侧 **产物/沙箱**（`ChatBox` 内 60/40 分栏逻辑与主聊天一致）。
|
||
- **线程 id**：新建会话时客户端先分配 UUID，`onStart` 后 `history.replaceState` 更新 hash 为 `/embed/chats/{真实id}`（与主聊天 `ChatPage` 相同手法，避免整页重载）。
|
||
|
||
---
|
||
|
||
## 4. 公开 HTTP API（无需鉴权）
|
||
|
||
前缀：`/api/public/embed/`（走 Gateway，与 `VITE_BACKEND_BASE_URL` 一致，默认 `http://47.88.25.99:7001/`）。
|
||
|
||
CSRF / Auth 中间件对 `/api/public/` 放行；请求 **不需要** Cookie。
|
||
|
||
### 4.1 登记映射（iframe 内自动调用）
|
||
|
||
```http
|
||
POST /api/public/embed/sessions
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"session_id": "parent-generated-uuid",
|
||
"thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b"
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"session_id": "parent-generated-uuid",
|
||
"thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b",
|
||
"registered": true
|
||
}
|
||
```
|
||
|
||
同一 `session_id` 再次 POST 会 **更新** `thread_id`（例如 `onStart` 后 id 变化）。
|
||
|
||
### 4.2 轮询状态（父页面使用）
|
||
|
||
```http
|
||
GET /api/public/embed/sessions/{session_id}/status
|
||
```
|
||
|
||
**尚未登记**（iframe 仍在加载或未 POST）：
|
||
|
||
```json
|
||
{
|
||
"session_id": "parent-generated-uuid",
|
||
"registered": false,
|
||
"thread_id": null,
|
||
"finished": false,
|
||
"thread_status": "pending",
|
||
"has_active_run": false,
|
||
"latest_run_status": null
|
||
}
|
||
```
|
||
|
||
**已登记且问答进行中：**
|
||
|
||
```json
|
||
{
|
||
"session_id": "parent-generated-uuid",
|
||
"registered": true,
|
||
"thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b",
|
||
"finished": false,
|
||
"thread_status": "idle",
|
||
"has_active_run": true,
|
||
"latest_run_status": "running"
|
||
}
|
||
```
|
||
|
||
**已登记且已结束：**
|
||
|
||
```json
|
||
{
|
||
"session_id": "parent-generated-uuid",
|
||
"registered": true,
|
||
"thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b",
|
||
"finished": true,
|
||
"thread_status": "idle",
|
||
"has_active_run": false,
|
||
"latest_run_status": "success"
|
||
}
|
||
```
|
||
|
||
#### 字段说明
|
||
|
||
| 字段 | 含义 |
|
||
|------|------|
|
||
| `registered` | 是否已收到 iframe 的 POST 登记 |
|
||
| `finished` | **父页面应以此为准**：无 inflight run，且线程非 running/busy，且非 `interrupted`（澄清等待用户） |
|
||
| `thread_status` | 从 checkpoint 推导：`idle` / `interrupted` / `error` 等 |
|
||
| `has_active_run` | 是否存在 pending/running 的 LangGraph run |
|
||
| `latest_run_status` | 该线程最近一次 run 的状态：`success` / `error` / … |
|
||
| `thread_id` | 解析出的 DeerFlow 线程 id（父页面可选用，非必须） |
|
||
|
||
### 4.3 获取生成结果（父页面使用）
|
||
|
||
问答结束后（建议先确认 `finished === true`），拉取本次模型输出：
|
||
|
||
```http
|
||
GET /api/public/embed/sessions/{session_id}/result
|
||
```
|
||
|
||
**尚未登记：**
|
||
|
||
```json
|
||
{
|
||
"session_id": "parent-generated-uuid",
|
||
"registered": false,
|
||
"thread_id": null,
|
||
"finished": false,
|
||
"thread_status": "pending",
|
||
"has_active_run": false,
|
||
"latest_run_status": null,
|
||
"messages": [],
|
||
"generated_text": "",
|
||
"generated_files": []
|
||
}
|
||
```
|
||
|
||
**已登记且已有内容：**
|
||
|
||
```json
|
||
{
|
||
"session_id": "parent-generated-uuid",
|
||
"registered": true,
|
||
"thread_id": "e9c7d09e-821d-421f-ae24-e5ddfe0cff5b",
|
||
"finished": true,
|
||
"thread_status": "idle",
|
||
"has_active_run": false,
|
||
"latest_run_status": "success",
|
||
"messages": [
|
||
{ "type": "human", "content": "请总结要点", "id": "..." },
|
||
{ "type": "ai", "content": "根据分析，要点如下：...", "id": "..." }
|
||
],
|
||
"generated_text": "根据分析，要点如下：...",
|
||
"generated_files": [
|
||
"/mnt/user-data/outputs/summary.md",
|
||
"/mnt/user-data/outputs/chart.png"
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 结果字段说明
|
||
|
||
| 字段 | 含义 |
|
||
|------|------|
|
||
| `messages` | 完整消息列表（与 checkpoint 中序列化结构一致，含 human / ai / tool 等） |
|
||
| `generated_text` | 所有 `ai` / `assistant` 消息正文按顺序拼接（段落间空一行） |
|
||
| `generated_files` | 本次会话产物的虚拟路径列表（与 UI 产物栏 `artifacts` 一致） |
|
||
|
||
未结束时也可调用，会返回当前已有内容；`finished` 仍为 false 表示可能还会继续生成。
|
||
|
||
### 4.4 按 thread_id 查询（可选）
|
||
|
||
调试或父页面已持有 thread_id 时：
|
||
|
||
```http
|
||
GET /api/public/embed/threads/{thread_id}/status
|
||
GET /api/public/embed/threads/{thread_id}/result
|
||
```
|
||
|
||
状态接口响应不含 `messages` / `generated_text` / `generated_files`；结果接口字段与 §4.3 相同（无 `session_id` / `registered`）。
|
||
|
||
### 4.5 前端封装
|
||
|
||
```ts
|
||
import {
|
||
getEmbedSessionResult,
|
||
getEmbedSessionStatus,
|
||
registerEmbedSession,
|
||
} from "@/core/embed/status-api";
|
||
|
||
// 父页面（或你们自己的脚本）
|
||
const status = await getEmbedSessionStatus(sessionId);
|
||
if (status.registered && status.finished) {
|
||
const result = await getEmbedSessionResult(sessionId);
|
||
console.log(result.generated_text, result.generated_files);
|
||
}
|
||
|
||
// 仅 iframe 内需要
|
||
await registerEmbedSession(sessionId, threadId);
|
||
```
|
||
|
||
`fetch` 使用 `credentials: "omit"`，不携带 DeerFlow 会话。
|
||
|
||
---
|
||
|
||
## 5. 父页面集成示例
|
||
|
||
### 5.1 拼接 iframe
|
||
|
||
```html
|
||
<iframe
|
||
id="deerflow-embed"
|
||
title="DeerFlow 问答"
|
||
style="width:100%;height:600px;border:0"
|
||
></iframe>
|
||
```
|
||
|
||
```javascript
|
||
const sessionId = crypto.randomUUID();
|
||
const base = "http://localhost:5173"; // 换成你们部署的前端 origin
|
||
const params = new URLSearchParams({
|
||
sessionId,
|
||
message: "请根据附件总结要点",
|
||
username: "guest",
|
||
theme: "red",
|
||
});
|
||
document.getElementById("deerflow-embed").src =
|
||
`${base}/#/embed/chats/new?${params.toString()}`;
|
||
```
|
||
|
||
### 5.2 轮询直到结束
|
||
|
||
```javascript
|
||
const API = "http://47.88.25.99:7001/"; // VITE_BACKEND_BASE_URL
|
||
|
||
async function pollUntilFinished(sessionId) {
|
||
const res = await fetch(
|
||
`${API}/api/public/embed/sessions/${encodeURIComponent(sessionId)}/status`,
|
||
{ credentials: "omit" },
|
||
);
|
||
if (!res.ok) throw new Error(`status HTTP ${res.status}`);
|
||
const data = await res.json();
|
||
if (!data.registered) return { done: false, reason: "pending" };
|
||
if (data.finished) return { done: true, data };
|
||
return { done: false, reason: "running" };
|
||
}
|
||
|
||
const timer = setInterval(async () => {
|
||
try {
|
||
const poll = await pollUntilFinished(sessionId);
|
||
if (poll.done) {
|
||
clearInterval(timer);
|
||
const output = await fetch(
|
||
`${API}/api/public/embed/sessions/${encodeURIComponent(sessionId)}/result`,
|
||
{ credentials: "omit" },
|
||
).then((r) => r.json());
|
||
console.log("问答已结束", output.generated_text, output.generated_files);
|
||
}
|
||
} catch (e) {
|
||
console.error(e);
|
||
}
|
||
}, 2000);
|
||
```
|
||
|
||
### 5.3 跨域注意
|
||
|
||
父页面从浏览器 `fetch` Gateway（如 `http://47.88.25.99:7001/`）时，**Origin 必须是后端 CORS 白名单里的完整地址**（含协议、主机、端口），与 API 地址是否写 `localhost` / `127.0.0.1` 无关。
|
||
|
||
**本地开发**（前端默认 `5174`）请在 Gateway 环境变量中配置：
|
||
|
||
```bash
|
||
# offline-backend-20260512/.env 或启动脚本注入
|
||
GATEWAY_CORS_ORIGINS=http://localhost:5174,http://127.0.0.1:5174,http://localhost:5173,http://127.0.0.1:5173
|
||
```
|
||
|
||
修改后**重启 Gateway**（`make dev` / `make gateway`）。若父页面部署在其它域名，把该域名的 origin 一并加入逗号分隔列表。
|
||
|
||
临时调试（勿用于公网生产）：
|
||
|
||
```bash
|
||
GATEWAY_CORS_ALLOW_ALL=1
|
||
```
|
||
|
||
常见报错：`No 'Access-Control-Allow-Origin' header` → 当前页面的 origin 未出现在 `GATEWAY_CORS_ORIGINS` 中。
|
||
|
||
### 5.4 其它部署注意
|
||
|
||
---
|
||
|
||
## 6. 部署与数据库
|
||
|
||
1. **跑迁移**（SQL 持久化后端）：
|
||
|
||
```bash
|
||
cd offline-backend-20260512/backend
|
||
# 按项目惯例执行 alembic upgrade head
|
||
```
|
||
|
||
表：`embed_sessions(session_id PK, thread_id, created_at, updated_at)`。
|
||
|
||
2. **重启 Gateway**，确认路由已挂载：`public_embed.router`（`app/gateway/app.py`）。
|
||
|
||
3. **前端构建** 后，将嵌入地址配给第三方；`VITE_BACKEND_BASE_URL` 指向可达的 Gateway。
|
||
|
||
无 SQL 时开发环境会退化为 **内存** `MemoryEmbedSessionStore`（进程重启后映射丢失）；生产请使用持久化库。
|
||
|
||
---
|
||
|
||
## 7. 安全说明
|
||
|
||
- `sessionId` 与 `thread_id` 均视为 **不透明能力令牌**：知晓即可查询状态（公开 API **无登录**）。
|
||
- 建议：父系统自行生成不可猜测的 UUID；敏感场景在贵司 API 网关再加鉴权或 IP 限制。
|
||
- 登记接口为 **POST upsert**，不校验「session 是否属于某租户」——若需多租户隔离，请在业务层约定 `sessionId` 命名空间或增加网关校验。
|
||
|
||
---
|
||
|
||
## 8. 与主聊天 `/page/workspace/chats` 的差异
|
||
|
||
| 项目 | 主聊天 | iframe 嵌入 |
|
||
|------|--------|-------------|
|
||
| 路由 | `/page/workspace/chats/:id` | `/embed/chats/:id` |
|
||
| 布局 | 完整 Workspace + 输入框 | 仅消息区 + 产物栏 |
|
||
| 登录 | 常规登录流 | URL `username` 自动 `login/username` |
|
||
| 首条消息 | 用户输入 | URL `message` 自动发送 |
|
||
| 完成态查询 | 无公开 API | `sessionId` + `/api/public/embed/sessions/.../status` |
|
||
|
||
能力上仍走同一 `useThreadStream` + `lead_agent` 流式链路，沙箱与产物行为与主聊天一致。
|
||
|
||
---
|
||
|
||
## 9. 常见问题
|
||
|
||
**Q：`registered` 一直为 false？**
|
||
A：检查 iframe URL 是否带 `sessionId`；子页是否登录成功；Network 里是否有 `POST /api/public/embed/sessions` 且 200。
|
||
|
||
**Q：`finished` 一直 false？**
|
||
A：可能仍在流式生成（`has_active_run: true`），或 agent 进入澄清（`thread_status: interrupted`）。嵌入模式无底部输入框，澄清需产品侧另行处理或避免触发澄清类工具。
|
||
|
||
**Q：父页面能否不用轮询？**
|
||
A：当前标准方案为公开 GET 轮询。若同源可考虑 `postMessage` 扩展（未默认实现）。
|
||
|
||
**Q：能否继续用已有 thread_id 嵌入？**
|
||
A：可以：`#/embed/chats/{thread_id}?sessionId=...`，可选再带 `message` 追加一轮；登记会在已知 id 上 upsert。
|
||
|
||
---
|
||
|
||
## 10. 变更记录
|
||
|
||
| 日期 | 说明 |
|
||
|------|------|
|
||
| 2026-06-02 | 初版：iframe 嵌入路由、`sessionId` 映射表、公开登记与状态 API |
|
||
| 2026-06-02 | 新增 `GET /sessions/{session_id}/result`：返回 messages、generated_text、generated_files |
|