12 KiB

Raw Permalink Blame History

多维表格（Bitable）伴生服务需求文档

日期：2026-06-24
状态：已对齐，待规划
范围分级：Deep — feature
后续：交由 /ce-plan 做实现规划

1. 问题与机会

AgentKit 当前缺少一个统一的持久化结构化数据落地载体。当出现以下需求时，没有合适的地方承接数据：

多系统数据汇总（需把多个来源的结构化数据合并到一处）
本地 Excel 上传后持久化（当前 Excel 仅能单向导出或解析为文本进 RAG，无法作为可编辑的结构化表留存）
外部数据采集（爬虫/API 抓取的结果需要按字段落地为可查询、可视图、可分析的表）

现状：Excel 导出是单向的（src/agentkit/documents/renderers/excel_renderer.py），Excel 解析只转文本进知识库（src/agentkit/memory/document_loader.py），MultiSourceRetriever 只做读侧多源检索，SharedWorkspace 是带 TTL 的临时 KV。没有任何模块能把异构数据源的结构化数据持久化为可编辑、可视图、可计算的多维表格。

机会：引入多维表格伴生服务，作为 AgentKit 异构数据的统一落地载体。Agent 作为数据的主要作者（采集写入），用户在落地后的表上精修、配视图、做分析。这既补齐了结构化数据持久化的缺口，又让 Agent 获得"数据编排者"的战略能力。

2. 主要使用者与核心价值

维度	决策
形态	混合模式——Agent 采集 + 用户精修
Agent 角色	数据作者：执行三类采集（Excel/数据库/爬虫API），按字段写入多维表格
用户角色	数据精修者与分析者：在落地后的表上编辑用户列、配置视图、做分析
核心价值	异构数据源的统一持久化落地载体，其上承载视图、分析、公式、引用

三类采集场景（均为 Agent 驱动）：

上传 Excel 或提供在线 Excel 地址 → 读取内容 → 按字段写入多维表格
指定数据库 → 根据数据表 → 生成多张多维表格数据表
根据指令执行数据采集（爬虫或具体 API）→ 获取到的数据按字段写入多维表格

3. 服务架构

多维表格是 AgentKit 的伴生服务：

逻辑独立：自有 API/CLI、自有领域模型（表/字段/记录/视图/公式）、自有存储边界
当前共部署：物理上与 AgentKit 同进程或同部署单元，UI 级集成于 AgentKit 前端
调用边界：AgentKit ↔ 多维表格走 API/CLI，不做进程内紧耦合
未来演进：可零成本抽离为独立服务，只是部署变更，不改代码
存储边界：当前共享 AgentKit 的 PostgreSQL，使用独立 schema 隔离；未来抽离时迁移

设计含义：所有跨服务交互按"远程调用"心智设计，即使当前是本地调用。字段所有权模型、upsert 语义、公式引擎都内建在多维表格服务自身，而非套在外部工具上。

4. 关键产品决策

4.1 写入语义：按主键 upsert + 字段所有权模型

Agent 重复采集时，按表的主键字段 upsert：

匹配到的记录：更新"数据列"（Agent 管理的列），保留"用户列"
未匹配的记录：新增
用户列永不被 Agent 覆盖

字段所有权（每列标记为"数据列"或"用户列"）：

自动推断：公式列、引用列、手动标注列 → 用户列；Agent 采集写入的列 → 数据列
Agent 声明：Agent 采集时可显式声明列的所有权，覆盖自动推断
公式列天然是用户列（派生的，永不被覆盖）

4.2 公式与引用：身份核心，深度分阶段

公式列和引用列是"多维表格"身份的核心，必须从 v1 存在，但支持深度分阶段扩展：

v1：基础公式（算术、字符串、简单聚合如 SUM/AVG/COUNT）+ 基础引用（lookup 到另一张表的字段）
v2+：高级公式（日期、条件、跨表 rollup）+ 函数库扩展

公式重算策略：异步重算 + "计算中"状态标记。Agent 写入数据列后，依赖该列的公式列进入"计算中"状态，由后台异步重算管道更新。避免同步重算阻塞写入，代价是短暂的不一致窗口（用户可见"计算中"标记）。

4.3 规模与存储：可演进

起步规模：单表 < 10 万行，总表 < 1000 张（部门级）
架构目标：支持未来向大规模（10万+行）演进
存储选型：规范化存储（字段定义、记录、单元格分离）+ 索引 + 分页，不用 JSONB 整表塞单行
大规模演进路径（v3）：列式存储、分区、物化视图、异步重算管道

5. 能力范围与分阶段

用户提出的 6 项能力，按复杂度与依赖关系分三阶段：

能力	复杂度	v1	v2	v3
① 模块搭建（服务骨架+领域模型+API）	基础	✅	—	—
② 数据采集落地（Excel/DB/爬虫API 三类）	中	✅	—	—
③ 多视图展示	中	网格视图	看板/甘特/画廊	表单
④ 分析计算	中高	—	分组/透视	高级聚合
⑤ 公式列+引用列	高	基础公式+lookup	高级公式+rollup	函数库扩展
⑥ 图片+附件	低中	✅	—	—

v1：核心闭环验证

验证"Agent 采集 → 持久化落地 → 用户查看/精修"的核心闭环：

服务骨架：领域模型（表/字段/记录/视图）、API/CLI、独立 schema 存储
字段所有权模型 + 按主键 upsert 语义
三类采集落地（Excel 上传/URL、数据库导入、爬虫/API 采集）
网格视图（表格视图，支持排序/筛选/分页/单元格编辑）
基础公式列（算术、字符串、SUM/AVG/COUNT 等简单聚合）
基础引用列（lookup 到另一张表的字段）
图片/附件字段类型（复用现有文件上传能力）
异步公式重算 + "计算中"状态

v2：多视图与分析

看板视图（按分组字段分列展示）
甘特视图（按日期字段排时间线）
画廊视图（以图片/附件为主视觉的卡片展示）
高级公式（日期函数、条件函数、跨表 rollup）
分析能力（分组聚合、透视表）

v3：规模化与协作

表单视图（以表单形式收集数据写入表）
公式函数库扩展
大规模优化（列式存储、分区、物化视图、异步重算管道升级）
多人实时协作

6. 方案探索与推荐

方案 1：自建多维表格引擎，分阶段交付

在 AgentKit 内构建原生 bitable 子系统，规范化存储，字段所有权模型原生内建，公式引擎自建分阶段。Agent 通过新增的 bitable API/CLI 写入。

优点：完全可控；与现有栈（PG/Redis/Vue/FastAPI）匹配；字段所有权模型原生；upsert 语义无摩擦
缺点：构建工作量最大；公式引擎是硬骨头；需长期维护
风险：公式引擎范围蔓延；大规模重算性能

方案 2：集成开源多维表格（APITable/NocoDB）作为子服务

部署开源 bitable 作为伴生服务，AgentKit 通过其 API 让 Agent 写入，用户编辑在 bitable 原生 UI 完成，上层叠加 upsert-保留用户列逻辑。

优点：视图/公式/附件白送，成熟，最快获完整功能
缺点：AGPL 协议有传染性风险（若商业化）；upsert-保留用户列需硬套（外部 bitable 无字段所有权概念）；集成走 API 较松
风险：协议冲突；外部模型与需求偏离

方案 3（挑战者）：Agent 结构化数据底座优先，UI 作为叠加层

反转优先级：多维表格首先是 Agent 的持久化结构化工作记忆/输出底座，用户侧多视图 UI 是读写底座的叠加层。

优点：最大化 Agent 协同；战略差异化；底座可驱动表格 UI 之外的能力
缺点：用户主动建表流程次要；底座抽象需更多架构思考

7. 范围边界

本次范围内（v1）

多维表格伴生服务骨架（领域模型、API/CLI、独立 schema 存储）
字段所有权模型 + 按主键 upsert 语义
三类采集落地（Excel/DB/爬虫API）
网格视图
基础公式列 + 基础引用列（lookup）
图片/附件字段
异步公式重算

延后（v2/v3）

看板/甘特/画廊/表单视图
高级公式（日期/条件/跨表 rollup）+ 函数库扩展
分析能力（分组/透视）
大规模优化（列式/分区/物化视图）
多人实时协作

本产品身份之外

不做通用电子表格（非单元格自由编辑，是字段化记录模型）
不做 ETL/数据管道平台（采集是 Agent 驱动的按需执行，非定时调度管道）
不做 BI 仪表盘产品（分析能力服务于表格内聚合，非独立 BI）
不替代知识库 RAG（多维表格是结构化数据载体，非非结构化文档检索）

8. 假设与依赖

假设：Agent 已具备执行采集任务的能力（爬虫/API 调用），多维表格只承接"写入"环节，不负责采集执行本身
假设：共享 PostgreSQL 的性能足以支撑 v1/v2 规模；v3 大规模时再评估独立数据库或列式存储
依赖：现有文件上传能力（src/agentkit/server/routes/chat.py 的上传端点、data/uploads/ 存储）可复用于附件字段
依赖：Agent 工具系统（src/agentkit/tools/base.py 的 execute() -> dict 契约）可扩展新增 bitable 写入工具
假设：公式异步重算的"计算中"窗口（秒级）对用户可接受

9. 成功标准

v1 验证成功的标志：

Agent 能把一份 Excel 上传的数据按字段写入多维表格，并在网格视图中查看
Agent 能指定一个数据库表，生成对应的多维表格
Agent 能执行一次 API 采集，把返回数据按字段写入多维表格
用户能在网格视图中编辑单元格、新增公式列（如 =SUM(数据列)）、看到异步重算结果
Agent 对同一表重复采集时，按主键 upsert 更新数据列，用户的公式列和手动编辑保留不变
多维表格服务通过 API/CLI 被 AgentKit 调用，无进程内紧耦合

10. 下一步

本需求文档交由 /ce-plan 做实现规划，重点规划：

v1 的领域模型设计（表/字段/记录/视图/公式的实体关系）
独立 schema 的存储设计（规范化表结构、索引、分页）
API/CLI 接口设计（CRUD + 采集写入 + upsert + 公式重算触发）
字段所有权模型的实现机制（自动推断 + Agent 声明）
异步重算管道设计
Agent bitable 写入工具设计
前端网格视图组件选型与集成

12 KiB Raw Permalink Blame History Unescape Escape