fischer-agentkit/docs/brainstorms/2026-07-03-bitable-comparative-evaluation-requirements.md

---
date: 2026-07-03
topic: bitable-comparative-evaluation
---

# 多维表格三向对比评估与优先级建议

## Summary

评估 agentkit bitable 当前实现与 Twenty、飞书多维表格在样式/功能/UX 三维的差距，按 C 先行（UX 打磨）→ A 跟进（功能广度）策略给出分优先级建议，并把 P0 差距交接给 ce-plan。Agent-as-data-author 作为贯穿差异化主线不阻塞任何一条。

---

## Problem Frame

agentkit bitable 后端 v1 已基本齐全：`BitableFile→Table→Field/Record/View` 三层骨架、28 个 REST 端点、公式引擎（10 函数 + AST 白名单 + DAG + 异步重算）、三类采集（Excel/DB/API）全部就位。但前端产品形态残缺——`ViewType` 枚举列 5 种只渲染 grid、列头菜单"编辑"仍跳右侧抽屉、无记录详情抽屉、无分组/条件格式、视觉未达飞书/Twenty 水准。

既有的 2026-06-24 模块需求与 2026-06-29 UI 完善需求两份文档已规划方向，但缺乏一份**基于实际代码盘点 + 竞品对标**的差距评估来驱动下一轮优先级决策。本评估填补这个空缺：用 grounding 实证当前实现状态（非规划状态），用竞品研究锁定差距坐标，用优先级策略锚定 ce-plan 交接范围。

---

## Current Implementation Inventory

以下为代码盘点的实证状态（已逐条验证）。

**后端（已就位）：**

- 容器层级：`BitableFile`（`src/agentkit/bitable/models.py:65-84`）→ `Table`（`file_id` 外键）→ `Field`/`Record`/`View`，schema V2（`src/agentkit/bitable/db.py:40`，含 `bitable_files` 表 + `file_id` 列迁移）
- REST 端点：28 个，前缀 `/api/v1/bitable`（`src/agentkit/server/routes/bitable.py`），JWT 或 `X-Internal-Token` 认证，404-before-403 所有权检查
- 字段类型（后端 `FieldType` 枚举）：`text`/`number`/`date`/`select`/`multiselect`/`attachment`/`image`/`formula`/`lookup`（9 种）
- 字段所有权：`FieldOwner.agent`/`user`，upsert 只更新 agent 列，用户列不被覆盖
- 默认字段：5 个模板（标题 `text` / 状态 `select` / 日期 `date` / 创建人 `text` / 创建时间 `date`）——注意 `FieldType` 枚举无 `user`/`datetime` 类型，创建人与创建时间实际是 `text`/`date`（R8 schema V3 后将迁移为 `user`/`datetime`，见默认字段迁移矩阵）
- 公式引擎：10 函数（`SUM`/`AVG`/`COUNT`/`MIN`/`MAX`/`ABS`/`ROUND`/`IF`/`LEN`/`CONCAT`），AST 节点白名单（见 `formula/parser.py`，永不 eval/exec），DAG 拓扑排序 + 环检测，异步 `RecalcWorker`（0.5s 轮询、300s reaper、600s 过期阈值）
- 跨表引用：单向 `lookup`（`lookup_target` 配 `table_id`/`field_id`/`filter_field_id`/`filter_value`）
- 采集：Excel（SSRF 守护的 URL 抓取 + openpyxl，`src/agentkit/bitable/ingestion/excel.py`）、数据库（SQLAlchemy 反射，`database.py`）、API（形状变换，`api_collector.py`）
- CLI：4 命令（list-tables / create-table / import-excel / query，`src/agentkit/cli/bitable.py`）

**前端（部分就位）：**

- 文件层：`BitableFileListView.vue`（文件列表 + `FileCard` + `FileCreateModal`）、`BitableFileDetailView.vue`（文件详情 + 顶栏 + 左侧表列表 + 主区 grid）
- grid 视图：`BitableGrid.vue`（vxe-grid 封装，列头菜单 `ColumnHeaderMenu` 编辑/隐藏/删除，select/multiselect 编辑器 `SelectCellEditor`/`SelectDisplay`，附件/图片单元格 `AttachmentCell`/`ImageCell`）
- 字段配置：`FieldManagePanel.vue`（右侧抽屉，宽 480）+ `FieldConfigForm.vue`（8 类型：text/number/date/select/multiselect/formula/attachment/image——**UI 无 `lookup` 选项**，尽管后端支持）
- 视图切换：`ViewSwitcher.vue`（editable-card tabs，**无视图类型选择**，`handleCreateView` 硬编码 `'grid'`，`src/agentkit/server/frontend/src/views/BitableFileDetailView.vue:242`）
- 视图配置：`ViewConfigPanel.vue`（筛选 `FilterBuilder` + 排序 + 隐藏字段，**无分组、无条件格式**）
- store：`src/agentkit/server/frontend/src/stores/bitable.ts`（Pinia，含 recalc 轮询 2s 间隔）
- API 客户端：`src/agentkit/server/frontend/src/api/bitable.ts`（**无 `deleteView` 方法**，后端也无 DELETE 视图端点）

**未就位：**

- 视图组件：仅 `BitableGrid`，无 `KanbanView`/`GalleryView`/`GanttView`/`FormView`
- 记录详情抽屉：无（仅 grid 单元格编辑）
- 列内联字段配置：无（列头"编辑"跳右侧 `FieldManagePanel`，非内联）
- 分组、条件格式：无
- 仪表盘、自动化、表单、甘特：无
- 字段级/记录级权限：无（仅文件/表所有权）
- 前端采集入口 UI：无（后端三类采集已就位，前端无触发入口）

**测试覆盖：**

- 单元测试：`tests/unit/bitable/` 13 个文件（test_service/test_routes/test_recalc/test_models/test_ingestion_excel/test_formula_parser/test_formula_engine/test_file_crud/test_default_fields/test_db/test_cli/test_bitable_tool/test_attachment）
- e2e 测试：`src/agentkit/server/frontend/e2e/` 含 3 个 bitable spec（bitable-view / bitable-file-flow / bitable-field-ops）

**既有规划执行进度（对照 2026-06-29 UI 完善需求）：**

- 阶段一：2026-06-29-R1 文件层 [OK]、2026-06-29-R2 默认字段 [OK]（受限：无 user/datetime 类型）、2026-06-29-R3 表内字段操作 部分（列头菜单存在但编辑跳抽屉）、2026-06-29-R4 select 编辑器 [OK]、2026-06-29-R5 三层导航 [OK]
- 阶段二/三/四：未开始

---

## Three-Way Comparison

| 维度 | agentkit bitable（当前） | Twenty | 飞书多维表格 |
|---|---|---|---|
| **样式** | | | |
| 视觉密度 | 中等，vxe-grid 默认 | 中低，Notion/Linear 风 | 中高，业务工具质感 |
| 配色体系 | 功能性，无强设计语言 | 浅色 + 蓝紫主调，克制留白 | 浅色 + 蓝紫，彩色 chip 标签活泼 |
| 字段类型图标 | 无 | 有 | 有，清晰 |
| 彩色标签 chip | select 有 `SelectDisplay`，未达飞书水准 | 有 | 有，活泼成熟 |
| 整体质感 | "薄、形态残缺" | Figma 级，开源最佳之一 | 业务工具成熟质感 |
| **功能** | | | |
| 容器层级 | `BitableFile→Table` [OK] | `Object→Record`（无文件层） | `App→Table` [OK] |
| 字段类型数 | 9（后端）/ 8（前端 UI 无 lookup） | 20+ | 25+ |
| 视图类型 | 枚举 5，实际只渲染 grid | 3（Table/Kanban/Calendar） | 5-6（grid/kanban/gallery/gantt/form/+calendar） |
| 公式 | 10 函数 + AST 白名单 + DAG + 异步重算 | 无原生（Workflow + Code Action 替代） | 丰富函数库 + LOOKUP/ROLLUP/FILTER + AI 生成 |
| 跨表关联 | 单向 lookup | Relation（多向）+ 关系上挂属性 | 单向/双向 link + Lookup + Rollup |
| 采集/导入 | [OK] Excel/DB/API 三类（agent 驱动） | 无（CRM 手动录入） | Excel 导入 + OpenAPI（无 agent） |
| 字段所有权 | [OK] agent/user 列 + upsert 保留用户列 | 无 | 无 |
| 仪表盘 | 无 | 基础 | 12+ 图表 + 关联多表 + 千人千面 + AI 解释 |
| 表单视图 | 无 | 无 | [OK]（NPS/评分 + AI 搭建） |
| 自动化 | 无 | Workflows（Beta）+ Serverless + MCP | 6 触发 × 9 动作 + AI 节点 + 字段捷径 |
| 单表容量 | PG 部门级（<10 万行规划） | PG（未公开） | 百万热行 |
| **UX** | | | |
| 字段管理入口 | 列头菜单（编辑跳右侧抽屉）+ 字段管理抽屉 | Settings 后台集中 + 表头 `+` | 列头 `+`/字段配置面板/记录详情页/AI 生成 |
| 记录详情 | 无（仅 grid 单元格） | 右侧抽屉（Notes/Tasks/活动线） | 展开记录详情面板 |
| 内联编辑 | grid 单元格可编辑，字段配置非内联 | 单元格内联编辑 | 单元格内联 + 字段内联配置 |
| 命令面板 | 无 | ⌘K 全局命令 | 无（飞书系全局搜索替代） |
| 视图切换 | tabs，无类型选择 | 视图保存 + 可见性控制 | 视图切换 + 类型绑定字段自动生成 |
| 分组 | 无 | 有 | 有（多字段分组） |
| 条件格式 | 无 | 无 | 有 |
| 筛选/排序 | [OK] 有 | [OK] AND/OR + 多字段 | [OK] + 字段名搜索 |
| 协作 | 单用户 | Notes/Tasks/@mention + 邮件日历同步 | 实时 + 评论 + 机器人通知 + 飞书 IM |
| 移动端 | 响应式 web | 响应式 web（无原生 App） | 飞书 App 原生 + 移动 web |
| 权限 | 文件/表所有权 | RBAC（对象/字段/记录）+ SSO + 审计 | 高级权限（颗粒级）+ AI 配置 + 组织架构继承 |
| 默认字段 | [OK] 5 字段（但创建人=text、创建时间=date） | 无默认集 | 主索引字段（1-2 列） |
| AI 能力 | Agent-as-data-author（差异化） | AI Agents + MCP Server（Cloud） | 全家桶（搭建/问数/公式/选项/配色/解释/侧边栏） |

---

## Gap Analysis

### 样式差距

- **G1.** 无字段类型图标（飞书/Twenty 均有，列头视觉辨识度低）
- **G2.** 彩色标签 chip 未达飞书水准（select 选项有 `SelectDisplay` 但配色/质感粗糙）
- **G3.** 整体质感"薄"（密度/留白/配色无统一设计语言，未达 Twenty 的 Figma 级或飞书的业务成熟感）

### 功能差距

- **G4.** 视图只有 grid（枚举 5 种但只渲染 1 种）——飞书 5-6 种、Twenty 3 种
- **G5.** 字段类型 9 种（前端 UI 8 种无 lookup）——飞书 25+、Twenty 20+；关键缺：`user`/`checkbox`/`url`/`email`/`phone`/`auto-number`/`datetime`/`modified-by`/`location`/`barcode`/`rating`/`progress`/`currency`/`rich-text`/`date-range`/`json`/双向关联
- **G6.** 默认字段"创建人"=`text`、"创建时间"=`date`——因 `FieldType` 无 `user`/`datetime`，默认字段集本身暴露字段类型缺口（R8 schema V3 迁移将修正：`text` → `user`、`date` → `datetime`）
- **G7.** 公式仅 10 函数——缺 `LOOKUP`/`ROLLUP`/`FILTER`/`SORT`/日期函数/条件函数/字符串函数；飞书有丰富函数库 + AI 生成公式
- **G8.** 跨表关联仅单向 lookup——无双向关联、无 rollup 聚合
- **G9.** 无仪表盘——飞书 12+ 图表类型 + 关联多表 + 千人千面
- **G10.** 无表单视图——飞书有（含 NPS/评分 + AI 搭建）
- **G11.** 无自动化触发器——飞书 6 触发 × 9 动作 + AI 节点；Twenty 有 Workflows + Serverless + MCP
- **G12.** 无甘特视图——飞书有（基于日期+状态）
- **G13.** 单表容量部门级——飞书百万热行（v3 规划列式/分区，尚未实施）

### UX 差距

- **G14.** 字段配置非内联——列头"编辑"跳右侧抽屉，飞书/Twenty 支持列头直接管理
- **G15.** 无记录详情抽屉——飞书/Twenty 均有（行点击展开详情面板）
- **G16.** 无视图类型选择——`ViewSwitcher` 无类型切换，`handleCreateView` 硬编码 grid
- **G17.** 无分组——飞书/Twenty 均有（多字段分组）
- **G18.** 无条件格式——飞书有（规则自动着色）
- **G19.** 无命令面板（⌘K）——Twenty 有全局快捷操作
- **G20.** 协作单用户——飞书实时 + 评论 + 通知；Twenty 有 Notes/Tasks/@mention
- **G21.** 无移动端原生——飞书有原生 App
- **G22.** 权限粗粒度——仅文件/表所有权，飞书/Twenty 有字段级/记录级 + SSO + 审计
- **G23.** 前端无采集入口 UI——后端三类采集就位但前端无触发入口（2026-06-29 阶段二未做）。**闭合路径**：R15c（路径 (a) 新增 `/collections` 端点 + 前端采集入口 UI；路径 (b) 由 agent 通过 BitableTool 触发——依赖 R15a 完成）

### 差异化优势（非差距，应加倍投入）

- **D1.** Agent-as-data-author：三类 agent 驱动采集 + upsert 保留用户列——飞书/Twenty 均无 agent 原生模型
- **D2.** 字段所有权模型：agent/user 列分离，用户列跨采集保留——独一无二
- **D3.** 内部服务令牌：agent 用 `X-Internal-Token` 认证——agent 原生设计
- **D4.** 公式引擎安全：AST 白名单 + DAG + 异步重算——比 Twenty 的 Workflow 变通方案更原生

---

## Key Decisions

**KD1. 优先级策略：C 先行（UX 打磨）→ A 跟进（功能广度），B（Agent 差异化）作为贯穿主线。** 理由：后端已齐，最大感知差距是已存在的 grid 体验未达飞书/Twenty 水准（G14-G19）；先打磨已有功能到竞品水准，再补广度。B 不阻塞任何一条，作为持续投入线。

**KD2. 飞书为主标杆，Twenty 为辅。** 飞书是更接近的纯多维表格形态（通用结构化数据载体），agentkit bitable 不是 CRM，Twenty 的 CRM 领域特性不适用。Twenty 贡献 UX 模式（⌘K 命令面板、记录详情抽屉、代码优先 `defineObject`）而非功能广度。

**KD3. Agent-as-data-author 是差异化强项，评估中不当差距处理。** 飞书的 AI 全家桶（搭建/问数/公式生成）与 agentkit 的 agent 采集是不同范式——飞书 AI 辅助人类建表，agentkit agent 自主建表写入。后者是 agentkit 身份主线，应加倍投入而非追赶飞书的 AI 辅助形态。

**KD4. 评估覆盖样式/功能/UX + 邻近能力（仪表盘/自动化/协作/移动/AI），但以 agentkit 产品身份过滤。** 飞书生态绑定（IM/文档/日历深度集成）与 Twenty 的 CRM 特性（管线/邮件同步）标记为本产品身份之外，不纳入优先级。

**KD5. 视觉决策用文字探讨，不开浏览器探针。** 沿用 2026-06-29 KD5，本次评估为分析交付，形状决策留待 ce-plan。

**KD6. P0/P1 关键范围决议（Resolve Before Planning 解决）。**
- R3 视图切换器：P0 暴露全部 5 种类型（grid/kanban/gallery/gantt/form），未实现的禁用态展示并标注"规划中"，预告路线图而非隐藏。
- R5 视觉对齐：P0 引入统一设计 token 系统（CSS 变量层：颜色/间距/圆角/字号），以 token 驱动重写列头/chip/密度等，避免后续 P1/P2 视觉不一致。
- R8 字段类型扩展：P1 一次性补全 16 字段类型 + 1 双向关联 = 17 项，与飞书对齐全面；schema V3 迁移复杂度接受。

---

## Agent 对等评估方法

bitable 后端有 28 个 REST 端点，但 `BitableTool`（`src/agentkit/tools/bitable_tool.py`）仅暴露 6 个动作（`create_table`/`import_excel`/`import_database`/`collect_api`/`upsert_records`/`query_records`），存在系统性 agent 孤儿风险。下表为每个 R-ID 标注复用端点、需新增的 BitableTool 动作、以及 agent 孤儿风险等级。

| R-ID | 复用/新增端点 | BitableTool 需新动作 | Agent 孤儿风险 |
|------|--------------|---------------------|---------------|
| R1 | 复用 PATCH /fields | `update_field` | 高 — agent 无法内联改字段 |
| R2 | 复用 GET /records/{id} | （无需新动作，复用 `query_records`） | 低 |
| R3 | 复用 POST /views（需扩展 schema 接受 type） | `create_view` | 高 — agent 无法建非 grid 视图 |
| R4 | 复用 PATCH /views（需扩展 group_by/conditional_formatting） | `update_view` | 高 — agent 无法配置分组/条件格式 |
| R5 | 纯前端 token 系统 | （无需新动作） | 无 |
| R6/R7 | 复用 POST /views + PATCH /views | `create_view`/`update_view`（同 R3/R4） | 中 — 与 R3/R4 共享动作 |
| R8 | 复用 POST /fields（需扩展类型枚举） | `create_field`（**必需**——17 个新类型需 agent 能批量建字段，R1 的 `update_field` 不覆盖创建路径） | 中 |
| R9/R10 | 复用公式引擎（`formula/parser.py`）+ POST /fields（双向关联 schema） | （无需新动作，复用 `create_field`/`update_field`） | 低 |
| R11 | 复用 POST /views | `create_view`（同 R3） | 中 |
| R15a | 复用 DELETE /views（需新增后端端点） | `delete_view` | 高 — 后端 + agent 双侧缺口 |
| R15b | 复用 `create_table` + `create_field` + `create_view` 编排 | （无新动作，编排层） | 低 |
| R15c | 路径 (a) 新增 /collections 端点；路径 (b) 复用 BitableTool | 路径 (b) 需 `create_collection`/`update_collection` | 中 — 取决于路径决策 |

**评估结论**：R15a 是 agent 对等的最高优先级子项，应与 R3/R4 同步推进（共享 `create_view`/`update_view` 动作）。其余 R-ID 的 agent 孤儿风险可通过 R1/R3/R4/R15a 四个新动作一并闭合。

---

## Priority Recommendations

以下 R-ID 为分优先级的差距闭合建议，P0 交接 ce-plan。

### P0 — UX 打磨（C 先行，立即交接 ce-plan）

- R1. 列内联字段配置：列头菜单直接编辑字段（重命名/改类型/选项管理），不跳右侧抽屉。闭合 G14。
- R2. 记录详情侧边抽屉：行点击展开详情面板，含所有字段类型的可视化展示与编辑。闭合 G15。
- R3. 视图类型切换与创建：`ViewSwitcher` 支持选 grid/kanban/gallery/gantt/form，新建视图选类型（不再硬编码 grid）。P0 暴露全部 5 种类型，未实现的以禁用态展示并标注"规划中"（预告路线图）。**后端依赖**：POST /views 需扩展 schema 接受 `type` 字段（当前硬编码 grid）。闭合 G16，为 P1 视图实现铺路。
- R4. grid 视图内分组与条件格式：多字段分组 + 规则自动着色。**后端扩展**：View.config 新增 `group_by`/`conditional_formatting` schema，通过 PATCH /views 暴露。**Agent 对等**：BitableTool 的 `create_view`/`update_view` 动作需支持传入这些配置（见 Agent 对等评估方法）。闭合 G17、G18。
- R5. 视觉风格对齐：P0 引入统一设计 token 系统（CSS 变量层：颜色/间距/圆角/字号），以 token 驱动重写列头/chip/密度等，配套字段类型图标与彩色 chip 标签达飞书水准。闭合 G1、G2、G3。
- R15a. BitableTool 动作补全（P0 提升，agent 对等最高优先级子项）：从 6 个动作扩展到 10 个（新增 `create_view`/`update_view`/`update_field`/`delete_view`），消除与 28 个 REST 端点的 agent 孤儿风险。**与 R3/R4 同步推进**（共享 `create_view`/`update_view` 动作）。强化 D1、D2，闭合 Agent 对等缺口（见 Agent 对等评估方法）。

### P1 — 功能广度（A 跟进，下一轮 ce-plan）

- R6. 看板视图实现：按 select 字段分列 + 拖拽卡片改值。闭合 G4（部分）。
- R7. 画廊视图实现：以附件/图片为主视觉的卡片网格。闭合 G4（部分）。
- R8. 字段类型扩展：P1 一次性补全 16 字段类型 + 1 双向关联 = 17 项（`user`/`checkbox`/`url`/`email`/`phone`/`auto-number`/`datetime`/`modified-by`/`location`/`barcode`/`rating`/`progress`/`currency`/`rich-text`/`date-range`/`json` + 双向关联），与飞书对齐全面，修正默认字段的 `user`/`datetime` 缺口。注：`datetime` 为通用日期时间类型，默认字段「创建时间」使用 `datetime` 类型；`modified-by` 为自动管理的用户类型。闭合 G5、G6。
- R9. 公式库扩展：补 `LOOKUP`/`ROLLUP`/日期/条件/字符串函数，对标飞书函数库。闭合 G7。
- R10. 跨表关联增强：双向关联 + rollup 聚合。闭合 G8。

### P2 — 后续轮次

- R11. 甘特视图 + 表单视图。闭合 G4（完整）、G10、G12。
- R12. 自动化触发器：事件（记录新增/字段变更/定时）→ 动作（写字段/发通知/调 API）。闭合 G11。
- R13. 仪表盘：图表组件库 + 关联多表。闭合 G9。
- R14. 细粒度权限：字段级/记录级 + 角色自定义。闭合 G22。

### B 线 — Agent 差异化（贯穿，不阻塞 P0/P1）

- R15b. 自然语言→表结构 agent 技能：agent 接收自然语言描述，调用 BitableTool 完成「建表 + 建字段 + 建视图」一站式编排，作为 agentkit 差异化主线。强化 D1、D2。
- R15c. 定时采集 + 前端采集入口 UI：在现有 Excel/DB/API 三类采集基础上，新增定时调度能力（cron 表达式驱动）+ 前端采集入口 UI（闭合 G23）。**路径决策**：(a) 新增 REST 端点 `/api/v1/bitable/collections`（CRUD + 调度器管理）；(b) 由 agent 通过 BitableTool 触发（依赖 R15a 完成）。ce-plan 阶段二选一。

---

## Acceptance Criteria (P0)

每个 P0 R-ID 的可测试验收标准（Given/When/Then），供 ce-plan 估算测试工作量。

**R1. 列内联字段配置**
- Given select 字段有 3 选项，When 用户点击列头菜单，Then 重命名/改类型/选项管理均内联完成（不跳右侧抽屉）
- Given 字段名变更提交，When 后端 PATCH /fields/{id}，Then 返回 200 + grid 在 1 帧内重渲染新标签
- Given 字段类型从 text 改为 number，When 现有记录值不可转换，Then 显示警告 + 阻止提交

**R2. 记录详情侧边抽屉**
- Given grid 行，When 用户点击行，Then 右侧抽屉展开显示所有字段（含 attachment/formula/lookup）
- Given 抽屉打开且字段为 attachment/image，When 渲染，Then 显示缩略图/预览（非原始 URL）
- Given 抽屉打开且字段为 formula，When 渲染，Then 显示计算结果（只读，不可编辑）
- Given 抽屉中编辑 user-owned 字段并提交，When 后端 upsert，Then agent 列不被覆盖

**R3. 视图类型切换与创建**
- Given ViewSwitcher，When 用户点击新建视图，Then 显示 5 种类型选择（grid/kanban/gallery/gantt/form）
- Given kanban/gallery/gantt/form 未实现，When 渲染，Then 以禁用态展示 + 标注"规划中" + tooltip 说明
- Given 新建视图选 grid，When 创建，Then 调用 POST /views 传 type=grid（不再硬编码）
- Given 禁用态类型，When 点击，Then 不触发创建 + 显示路线图提示

**R4. grid 视图内分组与条件格式**
- Given grid 视图，When 用户开启分组，Then 支持最多 3 字段分组（对标飞书/Twenty）
- Given 条件格式规则，When 运算符为 equals/not-equals/contains/is-empty/greater-than/less-than/between，Then 匹配单元格自动着色
- Given 两条规则匹配同一单元格，When 冲突，Then 首条规则优先（按用户排序）
- Given 着色，When 颜色来源审计，Then 全部来自 design token 调色板（8 色预设，无硬编码 hex）

**R5. 视觉风格对齐**
- Given 任何 bitable 组件，When 审计 CSS，Then 所有颜色来自 design token（grep 无硬编码 hex）
- Given 字段类型渲染，When 列头图标，Then 9 种（P0）类型各有 Ant Design Outlined icon（Component 类型）
- Given select 选项 chip，When 渲染，Then 对比度 ≥4.5:1（WCAG AA，axe-core 可测试）
- Given chip 配色，When 审计，Then 全部来自 design token 调色板

**R15a. BitableTool 动作补全 + 视图删除端点**
- Given BitableTool，When 调用 `create_view`/`update_view`/`update_field`/`delete_view`，Then 4 个新动作全部可用（BitableTool 从 6 扩展到 10 个动作）
- Given 视图列表，When 用户点击删除，Then 调用 DELETE /views/{id}（**后端需新增端点**，前端 api/bitable.ts 需补 `deleteView` 方法——见 Outstanding Questions）
- Given R3/R4 配置变更，When agent 调用 `create_view`/`update_view` 传 `type`/`group_by`/`conditional_formatting`，Then 配置成功写入（与 REST PATCH /views 等价）
- Given 字段配置，When agent 调用 `update_field`，Then 与 PATCH /fields/{id} 等价（agent 不再需要绕过工具直接调 REST）

**横切验收标准（适用所有 P0 R-ID）**

可访问性（WCAG AA）：
- Given 任何交互元素（按钮/链接/单元格/抽屉触发），When 键盘 Tab 导航，Then 可达且焦点可见（focus-visible 样式）
- Given grid 视图，When 屏幕阅读器遍历，Then 列头/单元格有正确 ARIA role 与 label（`role="grid"`/`role="columnheader"`/`aria-label`）
- Given select/multiselect 编辑器，When 键盘操作，Then 方向键导航 + Enter 选中 + Esc 关闭（不依赖鼠标）
- Given 颜色对比度审计，When axe-core 扫描，Then 所有关键文本 ≥4.5:1、大字号 ≥3:1（WCAG AA）

空状态（无数据时）：
- Given 新建表无字段无记录，When 渲染 grid，Then 显示"暂无字段，点击列头 + 创建"+ "暂无记录"双空状态
- Given 视图列表为空，When 渲染 ViewSwitcher，Then 显示"暂无视图，新建 grid 视图"提示（非空白）
- Given 抽屉/筛选器/分组无数据，When 渲染，Then 显示对应空状态文案（非空白、非报错）

---

## Test Strategy

**测试约定**：后端 pytest（asyncio_mode=auto，标记 integration/redis/postgres）；前端 vitest（纯函数抽 helpers/，不用 @vue/test-utils）；e2e Playwright。

**Test File Mapping**（R-ID → 测试文件映射）：

| R-ID | 后端单元测试 | 前端单元测试 | e2e 测试 | 集成标记 |
|---|---|---|---|---|
| R1 | tests/unit/bitable/test_routes.py（PATCH /fields/{id}） | helpers/fieldRenderUtils.ts | bitable-field-ops.spec.ts（extend） | - |
| R2 | tests/unit/bitable/test_service.py（upsert 保留 user 列） | helpers/recordDrawerUtils.ts | new: bitable-record-drawer.spec.ts | - |
| R3 | tests/unit/bitable/test_routes.py（POST /views type 参数） | helpers/viewSwitcherUtils.ts | bitable-view.spec.ts（extend） | - |
| R4 | new: test_grouping.py + test_conditional_formatting.py | helpers/groupingRulesUtils.ts | new: bitable-grouping.spec.ts | - |
| R5 | - | helpers/designTokenAudit.ts（grep token 使用） | bitable-view.spec.ts（visual regression） | - |
| R8 | test_models.py + test_default_fields.py + test_service.py | helpers/fieldTypeUtils.ts | bitable-field-ops.spec.ts（extend） | integration（schema V3 迁移） |
| R15a | test_bitable_tool.py（4 new actions: create_view/update_view/update_field/delete_view） | - | new: bitable-agent-parity.spec.ts | redis（notify_callback） |
| R15b | new: test_nl_to_table.py（agent 编排：建表 + 建字段 + 建视图） | helpers/nlTableUtils.ts | new: bitable-nl-table.spec.ts | redis（agent 编排） |
| R15c | new: test_collections.py（CRUD + 调度器）+ test_collection_security.py（SSRF/凭据） | helpers/collectionSchedulerUtils.ts | new: bitable-collection-ui.spec.ts | postgres（调度持久化）、redis（cron 触发） |

**Agent 对等测试契约**：每个 P0/P1 R-ID 交付时，附 BitableTool 调用契约测试——验证 agent 能完成等价操作（人类可做的 agent 也能做）。BitableTool 当前 6 actions vs 28 REST 端点，新增端点的 R-ID 需同步补 BitableTool 动作 + 契约测试。

**R15c 测试策略补充**：路径 (a) `/collections` 端点需覆盖 (1) CRUD 正常路径；(2) cron 表达式校验与调度触发；(3) SSRF 守护复用 `excel.py` 的 URL 白名单逻辑；(4) 凭据加密存储（建议复用 agentkit 现有 secrets 模块，禁明文）；(5) 端点访问控制：JWT 或 `X-Internal-Token`（与 28 个既有端点一致）。路径 (b) 由 agent 通过 BitableTool 触发，复用 R15a 测试契约，无需单独端点测试。

---

## R8 Field Type Acceptance Matrix

R8 扩展的 16 字段类型 + 1 双向关联的逐类型验收标准（**覆盖 P1 范围，非 P0**——P0 验收标准见 Acceptance Criteria (P0)）。每行映射约 4-6 个单元测试（test_models.py / test_service.py / test_default_fields.py）。

**Schema V3 迁移成本估算**：17 个新类型中 2 个需 V2→V3 数据迁移（`user`/`datetime`），1 个需双向关联 schema（无 V2 数据）。预估后端工作量：models.py 扩展 + migration 脚本 + RecalcWorker cache 失效路径 + service 兼容层 ≈ 3-5 个工作日。前端工作量：FieldConfigForm.vue 8 类型 → 24 类型 + SelectCellEditor 扩展 ≈ 4-6 个工作日。回滚策略见 Outstanding Questions。

| 类型 | 有效输入 | 无效输入（422） | 所有权 | 公式参与 | V2→V3 迁移 | PII / 安全 |
|---|---|---|---|---|---|---|
| `user` | user_id 字符串 | 非存在 user_id | both | 不支持 | 创建人 `text` → `user` | **PII**：user_id 不直接暴露用户邮箱/手机，但需脱敏日志 |
| `checkbox` | `true`/`false` | 非布尔值 | both | 支持（IF 条件） | - | - |
| `url` | `https://example.com` | 非合法 URL | both | 不支持 | - | - |
| `email` | `a@b.com` | 非合法邮箱 | both | 不支持 | - | **PII**：列表/导出需脱敏选项；agent 写入需脱敏审计 |
| `phone` | `+86-...` 字符串 | 空字符串 OK | both | 不支持 | - | **PII**：同 `email` |
| `auto-number` | 自增整数（后端分配） | 不可手动写（agent 侧写保护：BitableTool `create_record`/`upsert_records` 拒绝传 auto-number 字段） | agent only | 不支持 | - | - |
| `datetime` | ISO 8601 `2026-07-03T12:00:00Z` | 非日期格式 | both | 支持（日期函数） | 创建时间 `date` → `datetime` | - |
| `modified-by` | user_id（自动管理） | 不可手动写（agent 侧同 `auto-number`） | agent only | 不支持 | - | **PII**：同 `user` |
| `location` | `{lat: float, lng: float}` | 非合法坐标 | both | 不支持 | - | - |
| `barcode` | 字符串 | 空字符串 OK | both | 不支持 | - | - |
| `rating` | 1-5 整数 | 超范围 | both | 支持（AVG） | - | - |
| `progress` | 0-100 整数 | 超范围 | both | 支持（AVG） | - | - |
| `currency` | `{amount: number, code: str}` | 负数 OK | both | 支持（SUM） | - | - |
| `rich-text` | HTML 子集（白名单标签/属性，**服务端 sanitize**——禁 `<script>`/`<iframe>`/`on*` 事件属性，建议复用 `bleach` 或等价库；前端渲染前再过一遍 DOMPurify） | 含 `<script>`/`<iframe>`/`on*` 事件属性 | both | 不支持 | - | **XSS**：双清洗（服务端 + 前端），CSP 头限制 |
| `date-range` | `{start: ISO, end: ISO}` | `end < start` | both | 不支持 | - | - |
| `json` | 任意合法 JSON | 非法 JSON | both | 不支持 | - | - |
| 双向关联 | `target_record_id` | 非存在 record | both | 支持（ROLLUP） | 新增，无 V2 数据 | - |

**迁移测试**：V2 → V3 迁移需覆盖 (a) 创建人 `text` → `user`（现有值保留为字符串，运行时解析为 user_id）；(b) 创建时间 `date` → `datetime`（现有值追加 `T00:00:00Z`）；(c) 未迁移字段行为不变（旧字段 `type='text'` 不因新类型引入而变）。

**RecalcWorker cache 失效**：FieldType 枚举扩展后，`worker.invalidate_engine(table_id)` 必须在 schema 变更路径调用（见 `docs/solutions/architecture-patterns/bitable-companion-service-security-reliability-patterns.md` 模式 6）。

---

## Scope Boundaries

### 本次评估范围内

- 三向差距分析（样式/功能/UX + 邻近能力）
- 分优先级建议（P0/P1/P2/B 线）
- P0 交接 ce-plan 的范围界定

### 延后（后续轮次）

- P1/P2 差距的 ce-plan 规划（本次只界定范围，不规划实现）
- 大规模优化（列式存储/分区/物化视图，v3 范围）
- 多人实时协作（光标/选区同步）

### 本产品身份之外

- **CRM 领域特性**：Twenty 的管线阶段、邮件/日历同步、营销自动化——agentkit 不是 CRM
- **飞书生态绑定**：IM/文档/日历/知识库深度集成、组织架构继承——agentkit 不是飞书套件产品
- **通用电子表格**：单元格自由编辑——bitable 是字段化记录模型
- **BI 仪表盘产品**：R13 仪表盘服务于表格内聚合，非独立 BI
- **飞书式 AI 辅助建表**：agentkit 走 agent 自主建表路线（D1），不追飞书 AI 辅助形态

---

## Dependencies / Assumptions

- **依赖**：后端 v1 齐全（28 端点 + 公式引擎 + 三类采集），P0 主要在前端
- **依赖**：vxe-table 4 已用于 `BitableGrid`，继续作为 grid 实现基础。**注**：当前为幽灵依赖——`BitableGrid.vue` 直接 `import 'vxe-table'`，但 `src/agentkit/server/frontend/package.json` 未声明，仅靠主仓 `node_modules` hoisting 解析。R1/R3 实施前需在 frontend `package.json` 显式声明 `vxe-table` 与 `vxe-pc-ui` 版本（消除 hoisting 风险）
- **依赖**：Ant Design Vue 4 + Vue 3 + Pinia + TypeScript（强类型，禁 any）
- **假设**：现有 PostgreSQL 性能足以支撑 v1/v2 规模；大规模（百万行）延后 v3
- **假设**：用户接受分阶段交付，P0 先行可独立验证
- **假设**：`FieldType` 枚举扩展（补 `user`/`datetime`/`checkbox` 等）是 schema V3 升级，不破坏现有 V2
- **假设**：P0 视觉风格对齐不需引入新 UI 库，基于现有 Ant Design Vue + vxe-table 主题定制即可

---

## Outstanding Questions

### Resolve Before Planning

（已全部解决，见 KD6）

### Deferred to Planning

- 列内联字段配置（R1）用 vxe-table 内置能力还是自定义组件
- 记录详情抽屉（R2）的布局：单列纵向 vs 双列紧凑
- 看板视图（R6）组件选型：自建 vs 现成库
- 公式库扩展（R9）是否引入第三方 formula-parser
- `FieldType` 扩展的 schema V3 迁移策略

### From 2026-07-03 review

ce-doc-review（7 reviewers）经 best-judgment 路径处理的 12 个 manual findings，需 ce-plan 阶段决策：

- **user 字段用户模型** — R8 验收矩阵 (P1, feasibility, confidence 100)

  `user`/`modified-by` 字段类型引用 `user_id`，但 agentkit 当前无统一的 user 模型抽象（bitable 的 `FieldOwner.user` 仅标识所有权，不解析为用户实体）。需明确：(1) user_id 是 agentkit 内部 ID 还是外部系统 ID；(2) 是否复用 server/auth 的用户表；(3) 跨表查询用户名时如何解析。

- **C 先行优先级策略的实证依据** — Key Decisions KD1 (P1, adversarial, confidence 75)

  KD1 主张"C 先行（UX 打磨）→ A 跟进"，但未给出实证依据（无用户访谈、无 A/B 数据、无竞品上市时序分析）。产品价值判断需 ce-plan 阶段补充：(1) 飞书/Twenty 的迭代史是否支持 UX 先行；(2) agentkit 当前用户是否反馈过 grid 体验问题；(3) B 线（agent 差异化）是否才是真正护城河。

- **并发编辑 UX 策略** — Three-Way Comparison (P1, design-lens, confidence 75)

  飞书支持实时协作，agentkit 有 agent + 用户双写入场景（upsert 保留用户列）。需决策：(1) 同一记录被 agent 与用户同时编辑时的冲突解决（last-write-wins vs 字段级合并 vs 提示用户）；(2) 是否需要 optimistic locking（version 字段）；(3) UI 上是否提示"agent 已更新此字段"。

- **加载/错误状态统一模式** — Acceptance Criteria (P2, design-lens, confidence 75)

  文档未规定异步加载（公式重算、采集、视图切换）与错误状态的统一交互模式。需 ce-plan 决策：(1) 加载态用骨架屏还是 spinner；(2) 错误态用 toast 还是行内提示；(3) RecalcWorker 失败时的回退展示。

- **条件格式规则构建器 UX 形态** — Acceptance Criteria R4 (P2, design-lens, confidence 75)

  R4 验收标准列出 7 个运算符，但未规定规则编辑器形态。需决策：(1) 向导式（step-by-step）vs 列表式（rule list）vs DSL（类 Excel 公式）；(2) 单规则多条件 vs 多规则单条件；(3) 规则预览如何展示（实时着色样本 vs 描述文本）。

- **分组交互细节** — Acceptance Criteria R4 (P2, design-lens, confidence 75)

  R4 验收"最多 3 字段分组"但未规定交互。需决策：(1) 分组层级折叠/展开（默认折叠还是展开）；(2) 多字段分组的排序规则（首字段优先 vs 用户可调）；(3) 分组头部是否显示聚合行（计数/求和/平均值）；(4) 拖拽分组字段调整层级。

- **响应式断点定义** — Scope Boundaries (P2, design-lens, confidence 75)

  文档标注"响应式 web"但未给断点。需 ce-plan 决策：(1) 移动/平板/桌面三档断点（建议 768/1024/1440）；(2) grid 视图在小屏是否降级为卡片列表；(3) 抽屉在小屏是否全屏覆盖。

- **R2 记录详情抽屉宽度** — Deferred to Planning (P2, coherence, confidence 75)

  既有"单列纵向 vs 双列紧凑"未决。补充考虑：(1) 字段数超过 20 时单列纵向滚动成本；(2) 双列紧凑在窄屏的退化形态；(3) 与 R5 design token 间距系统对齐（建议宽度 480/640/800 三档）。

- **vxe-table 容量上限评估** — Dependencies (P2, feasibility, confidence 100)

  依赖 vxe-table 4 但未评估单表行数上限。需 ce-plan 阶段实测：(1) vxe-table 4 在 1 万 / 10 万 / 100 万行下的渲染性能（首屏 / 滚动 / 编辑延迟）；(2) 是否需要虚拟滚动（vxe-table 内置 vs 自定义）；(3) 与"PG 部门级（<10 万行）"假设是否匹配。

- **R13 仪表盘图表库 buy-vs-build** — Priority Recommendations (P2, scope-guardian, confidence 75)

  R13 列"图表组件库 + 关联多表"但未选型。需决策：(1) 自建 SVG/Canvas 图表 vs 引入库（ECharts/Chart.js/AntV G2）；(2) 引入库的 license 兼容性（agentkit 非开源，需商业授权）；(3) 12+ 图表类型的实现优先级（先做柱/折/饼，还是全量）。

- **禁用态视图类型路线图** — Acceptance Criteria R3 (P3, product-lens, confidence 50)

  R3 规定未实现视图以禁用态展示 + "规划中"标注，但未规定解锁路径。需决策：(1) 禁用态点击是否弹出路线图（具体版本/时间）；(2) 路线图信息从哪里读取（hardcode vs config vs 远端）；(3) 用户是否能"投票"解锁（需求收集机制）。

- **schema V3 双向关联回滚策略** — R8 Field Type Acceptance Matrix (P3, feasibility, confidence 50)

  R8 矩阵列"双向关联：新增，无 V2 数据"，但 V3 迁移失败时的回滚未定义。需决策：(1) 双向关联是 schema-only 变更还是数据变更；(2) 回滚是 drop column 还是保留为 text 字段；(3) 已建立的双向关联数据在回滚后如何展示（只读 vs 隐藏）。

---

## Sources / Research

- **现有后端实现**：`src/agentkit/bitable/{models,db,service,repository,recalc_worker}.py` + `formula/{parser,functions,engine}.py` + `ingestion/{excel,database,api_collector}.py`
- **现有前端实现**：`src/agentkit/server/frontend/src/views/BitableFile{List,Detail}View.vue` + `src/agentkit/server/frontend/src/components/bitable/*.vue`（15 组件）+ `src/agentkit/server/frontend/src/stores/bitable.ts` + `src/agentkit/server/frontend/src/api/bitable.ts`
- **REST 路由**：`src/agentkit/server/routes/bitable.py`（28 端点）
- **测试**：`tests/unit/bitable/`（13 文件）+ `src/agentkit/server/frontend/e2e/{bitable-view,bitable-file-flow,bitable-field-ops}.spec.ts`
- **既有规划**：`docs/brainstorms/2026-06-24-bitable-module-requirements.md`（模块需求，自建+底座心智）+ `docs/brainstorms/2026-06-29-bitable-ui-completeness-requirements.md`（UI 完善四阶段）
- **领域词汇**：`CONCEPTS.md`（Bitable/BitableFile/Field Ownership/Recalc 四条目）
- **Twenty**：[twentyhq/twenty](https://github.com/twentyhq/twenty)（v2.8.0, 50.9k stars, AGPL-3.0）+ [官方文档](https://docs.twenty.com)（Fields/Views/Workflows/Formula Fields）
- **飞书多维表格**：[飞书帮助中心](https://www.feishu.cn/hc/zh-CN/articles/624094577996) + [OpenAPI Base 结构](https://open.larkoffice.com/document/server-docs/docs/bitable-v1/bitable-structure) + [功能变化路径 2026](https://www.feishu.cn/hc/zh-CN/articles/360043073734)
- **已记录方案**：`docs/solutions/architecture-patterns/bitable-companion-service-security-reliability-patterns.md`