From f8927d1749cf42d90782bb4548727d256bc7c0e0 Mon Sep 17 00:00:00 2001 From: chiguyong Date: Fri, 3 Jul 2026 13:32:07 +0800 Subject: [PATCH] docs(bitable-eval): apply ce-doc-review best-judgment fixes (20 gated_auto + 12 manual) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ce-doc-review（7 reviewers, 39 raw findings → 32 actionable + 3 FYI 经合成管道）， 用户选择"自动用最佳判断处理"路径。本提交应用全部 20 个 gated_auto 修复，并把 12 个 manual findings 追加到 Outstanding Questions 的 From 2026-07-03 review 子节。 主要修复： - 修正 BitableTool 动作清单：实际为 create_table/import_excel/import_database/ collect_api/upsert_records/query_records（原文 4/6 错），消除 R15a 范围误判 - R15a 从 B 线提升至 P0（4 reviewers 独立标记的优先级矛盾——B 线"non-blocking" 与"agent 对等最高优先级子项"自相矛盾） - G23 闭合路径标注（R15c 路径 (a)/(b)） - 默认字段类型未来 user/datetime 标注（Inventory + G6） - R3 后端依赖标注（POST /views schema 扩展） - 视图删除端点补 P0 验收标准（R15a 验收 + 前端 deleteView 方法） - vxe-table 幽灵依赖标注（package.json 未声明，靠主仓 hoisting） - create_field 动作标注为必需（R8 17 新类型需 agent 能批量建字段） - R15 测试映射拆分为 R15a/R15b/R15c 三行 - R8 验收矩阵补 PII/XSS/auto-number 写保护列 + schema V3 迁移成本估算 - R15c 安全要求补 SSRF/认证/凭据加密 + 端点访问控制 - 横切验收标准补 WCAG AA 可访问性 + 空状态要求 - R8 矩阵范围标注（覆盖 P1，非 P0） Open Questions 新增 12 个 manual findings（ce-plan 阶段决策）： - user 字段用户模型 - C 先行优先级策略的实证依据 - 并发编辑 UX 策略 - 加载/错误状态统一模式 - 条件格式规则构建器 UX 形态 - 分组交互细节 - 响应式断点定义 - R2 记录详情抽屉宽度 - vxe-table 容量上限评估 - R13 仪表盘图表库 buy-vs-build - 禁用态视图类型路线图 - schema V3 双向关联回滚策略 文件：docs/brainstorms/2026-07-03-bitable-comparative-evaluation-requirements.md （107 insertions, 31 deletions） --- ...ble-comparative-evaluation-requirements.md | 136 ++++++++++++++---- 1 file changed, 106 insertions(+), 30 deletions(-) diff --git a/docs/brainstorms/2026-07-03-bitable-comparative-evaluation-requirements.md b/docs/brainstorms/2026-07-03-bitable-comparative-evaluation-requirements.md index f78d649..c9822a2 100644 --- a/docs/brainstorms/2026-07-03-bitable-comparative-evaluation-requirements.md +++ b/docs/brainstorms/2026-07-03-bitable-comparative-evaluation-requirements.md @@ -29,7 +29,7 @@ agentkit bitable 后端 v1 已基本齐全：`BitableFile→Table→Field/Record - 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` +- 默认字段：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`） @@ -118,7 +118,7 @@ agentkit bitable 后端 v1 已基本齐全：`BitableFile→Table→Field/Record - **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`，默认字段集本身暴露字段类型缺口 +- **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+ 图表类型 + 关联多表 + 千人千面 @@ -138,7 +138,7 @@ agentkit bitable 后端 v1 已基本齐全：`BitableFile→Table→Field/Record - **G20.** 协作单用户——飞书实时 + 评论 + 通知；Twenty 有 Notes/Tasks/@mention - **G21.** 无移动端原生——飞书有原生 App - **G22.** 权限粗粒度——仅文件/表所有权，飞书/Twenty 有字段级/记录级 + SSO + 审计 -- **G23.** 前端无采集入口 UI——后端三类采集就位但前端无触发入口（2026-06-29 阶段二未做） +- **G23.** 前端无采集入口 UI——后端三类采集就位但前端无触发入口（2026-06-29 阶段二未做）。**闭合路径**：R15c（路径 (a) 新增 `/collections` 端点 + 前端采集入口 UI；路径 (b) 由 agent 通过 BitableTool 触发——依赖 R15a 完成） ### 差异化优势（非差距，应加倍投入） @@ -170,7 +170,7 @@ agentkit bitable 后端 v1 已基本齐全：`BitableFile→Table→Field/Record ## Agent 对等评估方法 -bitable 后端有 28 个 REST 端点，但 `BitableTool`（`src/agentkit/tools/bitable_tool.py`）仅暴露 6 个动作（`create_table`/`list_tables`/`query_records`/`create_record`/`update_record`/`delete_record`），存在系统性 agent 孤儿风险。下表为每个 R-ID 标注复用端点、需新增的 BitableTool 动作、以及 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 孤儿风险 | |------|--------------|---------------------|---------------| @@ -180,7 +180,7 @@ bitable 后端有 28 个 REST 端点，但 `BitableTool`（`src/agentkit/tools/b | 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`（可选，R1 的 `update_field` 已覆盖部分） | 中 | +| 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 双侧缺口 | @@ -199,9 +199,10 @@ bitable 后端有 28 个 REST 端点，但 `BitableTool`（`src/agentkit/tools/b - R1. 列内联字段配置：列头菜单直接编辑字段（重命名/改类型/选项管理），不跳右侧抽屉。闭合 G14。 - R2. 记录详情侧边抽屉：行点击展开详情面板，含所有字段类型的可视化展示与编辑。闭合 G15。 -- R3. 视图类型切换与创建：`ViewSwitcher` 支持选 grid/kanban/gallery/gantt/form，新建视图选类型（不再硬编码 grid）。P0 暴露全部 5 种类型，未实现的以禁用态展示并标注"规划中"（预告路线图）。闭合 G16，为 P1 视图实现铺路。 +- 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） @@ -220,7 +221,6 @@ bitable 后端有 28 个 REST 端点，但 `BitableTool`（`src/agentkit/tools/b ### B 线 — Agent 差异化（贯穿，不阻塞 P0/P1） -- R15a. BitableTool 动作补全：从 6 个动作扩展到 10 个（新增 `create_view`/`update_view`/`update_field`/`delete_view`），消除与 28 个 REST 端点的 agent 孤儿风险。强化 D1、D2，闭合 Agent 对等缺口（见 Agent 对等评估方法）。 - 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 阶段二选一。 @@ -259,6 +259,25 @@ bitable 后端有 28 个 REST 端点，但 `BitableTool`（`src/agentkit/tools/b - 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 @@ -275,35 +294,41 @@ bitable 后端有 28 个 REST 端点，但 `BitableTool`（`src/agentkit/tools/b | 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 迁移） | -| R15 | test_bitable_tool.py（new actions） | - | new: bitable-agent-parity.spec.ts | redis（notify_callback） | +| 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 双向关联的逐类型验收标准。每行映射约 4-6 个单元测试（test_models.py / test_service.py / test_default_fields.py）。 +R8 扩展的 16 字段类型 + 1 双向关联的逐类型验收标准（**覆盖 P1 范围，非 P0**——P0 验收标准见 Acceptance Criteria (P0)）。每行映射约 4-6 个单元测试（test_models.py / test_service.py / test_default_fields.py）。 -| 类型 | 有效输入 | 无效输入（422） | 所有权 | 公式参与 | V2→V3 迁移 | -|---|---|---|---|---|---| -| `user` | user_id 字符串 | 非存在 user_id | both | 不支持 | 创建人 `text` → `user` | -| `checkbox` | `true`/`false` | 非布尔值 | both | 支持（IF 条件） | - | -| `url` | `https://example.com` | 非合法 URL | both | 不支持 | - | -| `email` | `a@b.com` | 非合法邮箱 | both | 不支持 | - | -| `phone` | `+86-...` 字符串 | 空字符串 OK | both | 不支持 | - | -| `auto-number` | 自增整数（后端分配） | 不可手动写 | agent only | 不支持 | - | -| `datetime` | ISO 8601 `2026-07-03T12:00:00Z` | 非日期格式 | both | 支持（日期函数） | 创建时间 `date` → `datetime` | -| `modified-by` | user_id（自动管理） | 不可手动写 | agent only | 不支持 | - | -| `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 子集（无 `