fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/brainstorms/2026-06-24-bitable-module-r...

12 KiB
Raw 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 驱动）：

  1. 上传 Excel 或提供在线 Excel 地址 → 读取内容 → 按字段写入多维表格
  2. 指定数据库 → 根据数据表 → 生成多张多维表格数据表
  3. 根据指令执行数据采集（爬虫或具体 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 之外的能力
  • 缺点：用户主动建表流程次要；底座抽象需更多架构思考

推荐：方案 1 自建 + 方案 3 底座心智

理由：

  1. 三类采集场景全是 Agent 驱动——本质是"Agent 作为数据作者"，方案 3 心智天然契合；但用户也要精修，需方案 1 的完整引擎
  2. upsert-保留用户列的字段所有权模型是定制的——外部 bitable 没有此概念，硬套很痛；AGPL 对可能商业化的产品是真实风险
  3. 现有基础设施齐全（PG + pgvector + Redis + SQLAlchemy 2 + Vue3 + Ant Design Vue），自建边际成本可控
  4. 伴生服务架构约束天然要求 API/CLI 边界——方案 1 自建反而最契合，因为所有权模型内建在服务自身
  5. 分阶段控制风险——v1 先验证核心闭环

与方案 3 的融合：架构上以"Agent 的持久化结构化数据底座"心智设计领域模型，使多维表格不仅是"一个表格功能"，而是 Agent 的数据编排能力的载体。这让底座未来可驱动表格 UI 之外的能力（仪表盘、报表、Agent 记忆）。

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 验证成功的标志：

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

10. 下一步

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

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