215 lines
12 KiB
Markdown
215 lines
12 KiB
Markdown
# 多维表格（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 写入工具设计
|
||
- 前端网格视图组件选型与集成
|