# KB-FEISHU-002：飞书表格配置与可选输出

| 项目 | 内容 |
|---|---|
| 适用版本 | 插件精灵 1.8.1 |
| 整理日期 | 2026-09-14 |
| 验证方式 | 自动化测试、本地浏览器流程测试、官网线上页面检查 |
| 验证边界 | 字段 API 使用模拟响应；本轮没有使用真实飞书账号验证写入 |

## 1. 如何识别飞书能力

插件读取脚本的 `@sellerfeeds-table`，不会通过脚本名称、描述或 `@connect` 域名猜测。该声明必须引用有效的 `@sellerfeeds-variable` 配置模板，并声明 `@connect https://base-api.feishu.cn/*`。

`required: true` 表示必须配置；省略时也按必须处理。`required: false` 表示可选，必须是 JSON 布尔值，字符串 `"false"` 会被拒绝。完整契约和参数示例见[脚本开发说明](/docs/development)。

## 2. 已验证的安装与运行流程

- 必选：主按钮“安装并配置表格”，次按钮“仅安装，稍后配置”；运行前要求完整的目标表格配置。
- 可选：主按钮“确认并安装”，安装后不会自动打开配置表单；次按钮“安装并配置飞书”会打开该脚本的配置模板。
- 未声明表格能力：不显示飞书表格引导；原有普通安装和配置模板流程保持可用。

当前版本使用 `x-sellerfeeds-input-groups` 参数组：整组留空跳过、部分填写阻止运行、完整填写自动回传。常用配置只快速填值，以本次参数为准；脚本在采集前再次复核。

## 3. 在运行窗口保存常用配置

在运行窗口的飞书参数组中填写表格链接和授权码，点击“保存为常用配置”即可直接保存到本机，保持当前运行窗口和其他任务参数不变。不再跳到另一张表单重复填写。

如果已选择与当前脚本对应的常用配置，保存会更新该配置中的飞书参数并保留其他字段；否则新建一份以脚本命名的配置，同名时自动加序号。保存后自动选中新配置，用户可在常用配置页面改名或编辑。保存本身不发起飞书请求，也不自动同步云端。

常用配置弹窗不再展示表头复制、模板介绍、字段列表和手动检查表结构步骤。脚本在执行写入时按声明处理目标表结构，用户无需提前复制表头。字段的新增、类型转换或删除由具体脚本的实现和授权范围决定，保存配置不会修改表格。

## 4. 链接识别边界

用户只填飞书多维表格链接和飞书授权码，不手填 App Token、Table ID，也不勾选写入开关。脚本在内部识别飞书 HTTPS 链接中 `/base/` 后的 App Token，以及 `?table=` 指定的 Table ID。识别后去掉无关的视图参数。知识库 `/wiki/` 链接、缺少具体数据表的链接及非飞书地址会被拒绝，不会猜测标识。

## 5. 配置校验与状态

保存前在本地校验飞书链接格式及授权码是否完整，不把“已保存配置”当作已经验证写入权限。脚本在实际请求飞书时处理权限不足、字段不匹配等错误。脚本中心对已保存的配置显示“已保存配置”，不再提示用户进行手动字段检查。

## 6. 验证证据与未覆盖范围

1.5.2 发布前全量 396 项自动化测试通过，包含表格声明、链接解析、字段检查与状态隔离；浏览器实测可选脚本的直接安装和主动配置两个入口。官网实测复制表头成功，390px 页面无横向溢出。

本轮没有新建真实飞书模板、没有使用真实授权码验证写入，也没有验证所有脚本作者的可选输出实现。飞书平台写入接口的历史实跑结论单独记录于[KB-FEISHU-001](/docs/knowledge/feishu-personal-base-token)。

## 7. 字段类型设计与不匹配时的转换

面向普通用户发布写入飞书的脚本时，建议把表格字段默认全部声明为文本，并在飞书写入层把 number、boolean 等值显式转成字符串。脚本自动创建文本列，用户可以保留飞书默认字段类型，不需要逐列设置数字、单选或复选框；Tool 的 JSON 返回仍可保留原始 number/boolean 类型，只有飞书展示层文本化。只有确实需要在飞书内做数值排序、聚合、公式计算或类型校验时，才建议声明数字等专用字段，并在建表说明中明确标出。

还要兼容用户已经建好但字段类型与脚本声明不一致的表格。推荐的转换流程是：先按声明类型正常写入；收到 `1254060 TextFieldConvFail` 或 `1254061 NumberFieldConvFail` 后，读取目标数据表的真实字段列表，按字段名建立类型映射；文本列使用 `String(value)`，数字列只接受可转换且有限的数字，空值保持为空；然后仅重试本条记录一次。读取到的字段结构可按 App Token 与 Table ID 缓存几分钟，供同一批后续记录复用。缺失字段自动新增；数字转换失败或遇到脚本不支持的飞书字段类型时，应返回具体字段名并停止该条写入，不能静默丢值，也不能无限重试。

批量任务尤其需要这层兼容。SellerFeeds 会把多条输入逐项执行，脚本通常为每个商品追加一行；某些字段可能在前几条为空，到后面的商品才第一次出现数字或布尔值，因此常见现象是“单条正常、批量写到中途才报类型转换错误”。首个失败项应触发上述字段结构读取，转换后重试当前行；同批后续项直接按已缓存的真实类型转换再写入，避免每一行都先失败一次或重复请求字段接口。每项仍应独立返回写入结果，某一项失败时保留准确错误和已成功行的状态，不能把部分成功误报为整批成功，也不要重复追加已经写入成功的记录。

## 8. 通用可选回传与批次节流

新开发的数据查询、采集和监控脚本，建议都提供飞书多维表格回传，但统一使用 `required:false` 和可整体留空的目标参数组。这是可选输出，不是使用脚本的前置条件；整组留空时不校验飞书 Token、不发出飞书请求。

新表继续优先使用全文本字段，数字和布尔值只在飞书落表层字符串化。旧表类型不同时，按第 7 节读取实际字段后转换，不能要求用户为每个脚本重复调整大量列类型。

批量追加的统一基线是：调用 `records/batch_create`，每批最多 500 行，相邻写入批次间等待 700ms，保持单文档约 2 QPS 以内。飞书明确限流时按 1s、2s、4s 退避，最多重试 3 次；不要立即循环重试，也不要无限重试。中途失败时返回已成功行数和明确的业务去重键，让用户可以安全续跑。

手动、批量、定时和 MCP 任务必须共用同一套参数组语义、字段映射、节流和重试逻辑，不要只修单条手动调用分支。这套写表能力与“任务完成后推送飞书机器人消息/文件”相互独立。

## 9. 自动补齐字段

写入前读取目标字段，按名称复用已有列，按声明类型自动创建缺失列，然后写入记录。用户无需逐个填表头；表格模板、复制表头仍可选用。多余列保留，不自动删列、重命名或改变类型。建列要求结构编辑权限，响应不确定时停止，重新操作前先读取结构以复用已创建字段。参数组具体定义见[开发说明](/docs/development)。1.7.0 流程以[自动写表公约](/docs/development/feishu-contract)为准。