SheetBot 数据执行层架构：连接器、语义层与自然语言交付
解读 SheetBot 数据执行层：我要连接六类适配器入库、excel_state 元数据与指标口径、Agent 确定性 plan_compiler 执行、我要报表 DuckDB 流水线至分享交付；并说明 user_id 隔离、口径版本治理及与 GeoOps、AtlasBot 的可选只读联动与三阶段演进。
问题定义
企业报表链路常见断裂：源系统异构（ERP/MES/Excel/IM 表格）、口径在人与表之间分裂、交付依赖手工排版。传统 BI 项目周期长；纯聊天式 AI 又缺乏可审计的执行路径。SheetBot 定位在「数据执行层」：把自然语言约束为可执行操作与可验证结果，而不是一次性生成不可追溯的文本。
- 输入侧：多源数据需进入统一工作簿模型，且不能污染原始业务区。
- 理解侧：LLM 只能决定「分析什么」，布局与操作序列应由确定性编译器生成。
- 输出侧：既要 Excel 画布可编辑，也要报表快照、分享与导出可交付。
- 治理侧：用户级文件隔离、配额、操作注册表校验与错误脱敏需贯穿全链路。
架构全景
SheetBot 数据执行层可抽象为四段：连接器入库 → 工作簿元数据与口径 → NL 解析与确定性执行 → 报表/文件交付。普通模式（<50MB）数据在浏览器工作簿 JSON 与 Univer Canvas 间双向同步，Agent 经 SSE 推送操作；大文件模式（>50MB）数据在服务端 DuckDB，REST 执行。两种模式模块隔离，禁止交叉 import。
示意图（文字版）：外部系统 → connect/sync_engine → xlsx 工作簿 → excel_state + Agent → operations 前端执行；并行路径 report/planner + DuckDB → 报表快照/分享。
核心分层
连接器层（我要连接）
模块路径 backend/app/connect/。六类适配器：shopify、dingtalk、wecom、database（MySQL/PostgreSQL）、webhook、custom_api。同步引擎拉取 → 字段映射 → writer 追加写入用户 xlsx；调度器支持定时同步。与 Agent、大文件模块无耦合，仅共享文件归属校验。
工作簿与元数据层
前端维护 SheetBot JSON（单元格值/公式/样式/合并/图表）。发令前构建 excel_state：headerRow、headers、sampleData、行数等，供 Agent 与只读 QueryBridge 全表查询。表头检测采用 DISTINCT 非空计数，避免合并标题行误导。用户可在工作簿内维护「口径说明」表作为轻量语义层。
NL 解析与确定性执行层（Agent）
模块 backend/app/agent/。分析类任务强制 submit_analysis_plan → plan_contract 验证 → plan_compiler 编译为 operations；非分析类走 MCP 工具链。操作类型由 operation_registry 单一真相源定义，前后端 operation_validator 对齐。SSE 分发带节拍，前端 Univer 逐条渲染。只读查询经 QueryBridge 回传全表精确结果，禁止从 20 行样本推断全表统计。
报表与交付层（我要报表 + 导出）
模块 backend/app/report/：结构分析 → LLM 规划（KPI/图表/SQL）→ DuckDB 聚合 → 图表构建 → 洞察生成 → 快照存储与分享。大文件场景复用 large_file DuckDB 会话。并行能力：PPTX 汇报、批量转 Word、Skill 技能编排、xlsx 图表原生注入导出。
关键数据流
- 入库流：连接器/上传 → UGC 路径
uploads/excel_files/YYYY-MM-DD/→ 用户 file_id 归属 → 工作簿加载。 - 分析流：用户 NL 指令 → prompt_expander 元数据扩展 → Agent 选 plan → 编译 operations → SSE → 前端 executeOperation → Canvas 回写 JSON。
- 查询流：Agent 只读工具 → SSE data_query → 前端内存计算 → POST operation-result 回填。
- 报表流：选择模板 → planner 输出 SQL 计划 → aggregator 执行 → insight 质量门禁 → 快照/分享 URL → 可选导出。
治理与安全
- 权限：文件、连接器、报表、任务均
user_id归属断言，跨账号 IDOR 拒绝（见test_resource_isolation）。 - 配额：
QuotaGuard限制 AI 指令、报表、上传存储等，按套餐 enforcement。 - 口径版本：建议口径表与工作簿同版本管理；连接器字段映射变更应触发回归对账。
- 审计与诚实交付：操作注册表校验失败即拒绝；分析汇总无图表等半交付场景有原子守卫；用户可见错误脱敏。
- 数据保护：分析结果禁止覆盖原始数据区，须新工作表或安全 outputRow。
与比特意图产品映射
| 架构组件 | SheetBot 模块 | 可选联动 |
|---|---|---|
| 连接器入库 | connect/adapters + sync_engine | — |
| NL 执行 | agent/plan_compiler + excel_tools | — |
| 大数分析 | large_file/DuckDB | 与 report 共用 SQL 执行 |
| 报表交付 | report/assembler + share_service | GeoOps 可见度 CSV 可作只读源 |
| 指标定义治理 | 工作簿口径表 + 自定义公式 formula/ | AtlasBot 本体可收录指标定义（只读引用） |
| 流程复用 | skill/ + Skill 执行引擎 | — |
官方产品参数以 llms.txt 为准；本站描述基于开源/交付代码结构，不构成实施承诺。
演进路线
阶段 A（2–4 周）：单表/单连接器 + 单域指标 + 首份 NL 周报 — 见 入门实践。阶段 B（1–2 月）：多连接器、Skill 固化、我要报表模板库，口径表纳入变更评审 — 见 制造案例。阶段 C（季度+）：跨系统指标对齐、与 AtlasBot 指标本体及 GeoOps 增长数据只读联动，纳入企业「执行—增长—治理」三层架构（参见联合架构系列 #7）。