mini-excel-ai 集成手册

三种集成形态说明与选型

mini-excel-ai 提供同一套后端能力，仅用是否加载前端、AI 由谁承载区分三种接入方式。下表中文名为集成手册用语；与开放 API 中 mode / 查询参数的对应关系见表后对照。

名称与 API 对照：创建会话、统计或审计场景中 mode 仍使用下列取值（与文档中文名一一对应）：zero-ui → API 集成模式；hybrid → AI 窗口集成；full → 嵌入式集成。iframe 地址参数 ?mode=hybrid、?mode=full 同理。

通用约定

Base URL

下文用 {BASE} 表示部署根地址，例如 https://mini.example.com。前后端同源时可为空字符串，由网关反代统一到 /api/mini/...。

鉴权（会话）

系统无用户 JWT。多数写操作与部分读操作在 Header 中携带：

Authorization: Bearer <session_id>

部分路由将会话 ID 写在 URL 路径中（如 /session/{session_id}/files），上传等接口以具体 API 为准。

创建会话

CORS

跨域嵌入或浏览器直连 API 时，需在服务端配置允许的 Origin（如环境变量中的白名单）。平台配置接口会返回 embed_allowed_origins 等字段供前端校验。

核心 HTTP 接口速查表

下列为常见集成路径；实际以你方网关与部署拓扑为准，对浏览器暴露的 URL 通常与下表一致。

模式一：API 集成模式（纯 API）

  宿主 UI  ⇄  REST / SSE  ⇄  mini-excel-ai 服务端  ⇄  数据分析与 AI 能力（实现细节对集成方透明）

推荐主路径：大文件分析

1. POST /api/mini/session 取 session_id
2. POST /api/mini/session/{id}/files 上传文件，得 file_id
3. POST /api/mini/large-file/prepare/{session_id}/{file_id} 确保就绪
4. POST /api/mini/large-file/operation/stream 发送指令，消费 SSE（文本块、工具结果、完成）
5. 需要合并结果 Excel：GET .../download-results/...（可带 ?sheets=表1,表2 与画布对齐）

上传响应（典型字段）

上传成功响应常见字段：file_id, original_name, file_size, is_large_file, large_file_status, session_id。sheet_names 等详情可在 prepare / preview 响应中补充。

SSE（大文件流）事件（概念）

示例（Fetch + 流）

// 1. 创建会话
const r1 = await fetch('{BASE}/api/mini/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ mode: 'zero-ui', external_ref: 'tenant-1' }),
});
const { session_id } = await r1.json();

// 2. 上传（FormData）
const fd = new FormData();
fd.append('file', fileBlob, 'data.xlsx');
const r2 = await fetch(`{BASE}/api/mini/session/${session_id}/files`, { method: 'POST', body: fd });
const fileInfo = await r2.json();

// 3. Prepare + Stream（伪代码：按项目 SSE 解析器读取 event/data）
await fetch(`{BASE}/api/mini/large-file/prepare/${session_id}/${fileInfo.file_id}`, { method: 'POST' });

生产环境建议使用随部署提供的浏览器 SDK（如 MiniExcelAI.api(baseUrl)），已封装取消、解析与 URL 拼接；无需关心服务端内部实现。

演示页：部署后访问 /zero-ui-demo.html。

模式二：AI 窗口集成（iframe + 外置 AI）

┌─ 宿主：自建 AI 窗口（SDK） ─┐    postMessage    ┌─ iframe：表格 + 三视图 ─┐
│  sendAnalyzeCommand / …    │ ←──────────────→ │  无内置 AI              │
└────────────────────────────┘                  └────────────────────────┘

iframe 地址

{BASE}/index.html?mode=hybrid&session_id=auto

session_id=auto 由应用自动建连；也可传入已有 session_id 复用会话。

SDK 引入

const sdk = MiniExcelAI.connect(document.getElementById('mini-frame'), {
  origin: 'https://mini.example.com',
});
await sdk.ready(); // { session_id }
sdk.sendAnalyzeCommand('按地区汇总销售额');
sdk.changeView('reportCard'); // analyze | reportCard | presentation

常用事件（sdk.on(name, handler)）

演示页：/hybrid-demo.html（或你站点等价路径）。iframe 建议 sandbox 含 allow-scripts allow-same-origin allow-forms allow-popups allow-downloads，并按需 allow 剪贴板。

模式三：嵌入式集成（完整内置 UI）

┌────────────────── iframe：嵌入式工作台 ─────────────────┐
│  [ 我要分析 | 我要报表 | 我要汇报 ]  +  内置 AI 助手    │
│  电子表格画布                                           │
└─────────────────────────────────────────────────────────┘

iframe 地址

{BASE}/index.html?mode=full

可选：宿主先 POST /api/mini/session，再把 session_id 传入 URL，便于与 external_ref 对齐。

宿主侧监听（可选）

仍可 MiniExcelAI.connect(iframe) 仅订阅 artifactReady 等事件，无需代替用户操作。

适合最快交付：用户上传、对话、导出均在 iframe 内完成。

产物下载与报表格式

注意事项与排错

• 配置隔离：服务端运维配置与宿主主系统分开维护，避免共用同一套环境变量文件导致互相覆盖。
• 数据隔离：会话与上传文件由 mini-excel-ai 侧独立托管，不依赖宿主用户表或主业务库。
• 大文件 vs 小表分析：/api/mini/large-file/* 面向大体量工作簿；/api/mini/excel/* 与 /mini/sse/* 为通用分析路径，部分场景需按协议回传数据查询结果。API 集成模式可优先采用大文件相关接口以降低前端配合成本。
• 嵌入安全：connect 必须传入可信 origin；CSP 配置 frame-src 白名单。
• 502 / 工作台超时：检查静态资源是否完整（index.html、assets/），以及网关到 mini-excel-ai API 上游是否可达。
• 静态资源：发布前请完成官方推荐的前端构建流程，避免静态目录不完整导致 iframe 空白或 404。

更细的 Markdown 说明见项目内 docs/integration-zero-ui.md、integration-hybrid-ai-window.md、integration-full-ui.md。