飞书自动写表开发公约
可直接交给 AI 阅读的开发流程、完整示例与验收边界。
本页目录
当前本地产品预览的覆盖规则（2026-10-16）
第四十二轮覆盖旧重试说明：钉钉追加的网络断开、5xx 或成功回执不完整属于结果未确认，暂停自动追加，用户核实后手动决定是否重试。飞书仍复用持久批次与 client_token；网络及限流退避，明确权限、地址、容量等错误停止自动重试。换机携带成功证据与未确认标记，未知结果不当成功，也不自动开启另一个新批次。详细备份与重试边界以数据保存与输出公约为准。
2.1.79 本地候选由数据中心管理常规采集结果回传。新脚本默认保存本机数据并返回任务报告；用户在数据中心确认绑定飞书或钉钉。作者主动声明且获授权的 table.feishu.append/update 和 HTTP 表格调用在第二十八轮已恢复，不按字段名隐藏输入，也不自动把数据中心密钥交给脚本。两条写表路径须明确归属，迁移时避免同时写同一结果。
数据中心新增记录提交后唤醒，按同运行分批追加，飞书最多 500 行、钉钉当前 100 行；每批核对字段并补建缺列。只处理新增及失败待办，已成功数据不重写，空队列不请求远端。追加只依据写入接口回执，不读取业务记录查重或写后读回；失败批次及飞书 client_token 持久化后按退避重试。标识列仍为插件管理列，用于记录归属与显式云端删除；删除路径单独定位和确认。飞书当前支持文本／数字／复选框，钉钉支持文本／数字；不承诺钉钉响应丢失后重试零重复。
以下保留历史脚本直写约定；其查重、字段及通知策略不能混入新的数据中心追加路径。现行 SDK 为 27 项可用操作，脚本直写 SDK 仍有自身的映射及读回契约；不等于数据中心批量适配器。当前批量数据中心路径仅完成合成协议验证，尚未完成新版真实飞书／钉钉全流程验收；未发布官网或云端。完整状态与通知规则以[数据保存与输出公约](data-output-contract.md)当前章节为准。
历史脚本兼容参考
原飞书接口约定沿用插件精灵 1.7.0 基线；2026-09-14 曾补充本地保存、任务汇总报告与通知约定。
绑定者可在应用启用长连接事件订阅后，向飞书机器人私聊发送近期文本指令。插件按事件编号本机去重入队并 ACK；“运行 Tool名称 {参数 JSON}”在本机解析。自然语言仅在用户明确选择 AI 配置后，由浏览器直连该 AI 服务，不再发到个人 MCP Worker 的 AI 路由。插件再次校验 Tool 授权、输入 Schema、接收开关及账号身份，执行后回复实际摘要、已确认表格链接或报告文件。接收指令与发送通知分别开启，只有通知不会建立接收长连接。本机独立接收只应在一台电脑开启，没有跨设备全局去重承诺；旧协调接收配置仍保留设备角色检查。飞书控制台仍需订阅 im.message.receive_v1 并发布应用；握手不表示订阅完成。新接收路径无需 Workers AI binding；旧服务端 AI 路由只为旧客户端兼容，不作为当前插件依赖。来源为 feishu 的任务不另发通用任务通知。
先读[数据保存与输出开发公约](/docs/development/data-output-contract)：本地完整保存是默认必达环节，飞书写表是可选的附加输出。 飞书参数留空、写表失败或机器人未启用，都不能作为跳过本地业务归档的理由。任务历史和可下载报告不能代替数据中心落库验收。
用户只填两项
用户只需准备一个可访问的飞书多维表格，并填写：
| 参数 | 含义 | 录入方式 |
|---|---|---|
baseUrl | 具体数据表的 HTTPS 链接 | 粘贴一次，须包含 /base/…?table=… |
baseToken | 有该表访问、写记录和编辑结构权限的授权码 | 填写一次或从常用配置选择 |
App Token 和 Table ID 由脚本内部解析，不出现在需要用户填写的参数中。飞书 API 地址由脚本固定为受支持的官方端点，不要求用户填写 API 地址。授权码不是 App Token，也不是机器人 Webhook。
不再要求勾选“写入飞书”，不需要点击“识别链接”，也不要求复制表头、粘贴表头或逐列修改类型。已有的模板、复制表头和字段说明可以保留为可选辅助入口，不得成为执行前置条件。
通过 @sellerfeeds-table 声明字段及 required:false，通过 x-sellerfeeds-input-groups 声明可选飞书参数组。两项全空仍采集并保存本地数据，不请求飞书；只填一项在采集前提示补齐或整组清空；两项完整则自动写表。常用配置仅提供快速填值，本次手动修改或清空优先。手动、定时、批量和 MCP 必须共用该规则。
默认一个任务一行完整报告
报告类脚本向飞书回传时，默认一次任务写一行汇总报告。 一个任务采集到多个问题、多个回答或其他明细，不因此增加报告行数。只有用户明确要求按明细逐行分析时，才采用对应的明细行结构；不能沿用旧示例或内部数组结构，擅自把任务报告拆成多行。
- “完整报告”列按业务顺序保留本次任务的全部内容。问答报告按问题编号组织，每问保留完整答案与推荐追问；商品图片、价格和链接属于答案中的表格，不另拆成报告行。
- 任务编号、采集时间、业务对象标识、标题、明细总数、成功数、失败数、状态和错误说明分别使用独立列。具体名称按业务确定，不为每个问题动态新建一组列。
- 本地默认展示和保存同一任务的完整汇总报告。内部结构化明细、分批处理和任务 JSON 可以保留，但不能把每条明细都当成独立报告交付。
- 不创建或写入额外的“记录键”列。使用已有的任务编号和业务对象标识组合判断重复；读取时兼容飞书文本字段的实际返回结构。同一任务重试不重复追加，同一对象的新任务保留新报告。
- 采集部分失败时，仍在这一行保留已取得的内容和失败说明；写入成功不能掩盖采集或本地保存失败。写入数量按报告行计数，明细数量单独统计。
- 报告过长触及本地单记录或飞书字段容量时，明确报错并保留可恢复的完整结果；不得静默截断，也不得未经确认擅自拆成多个报告行。不能假设补存能绕过容量限制。
- 新规则适用于新开发和升级时的输出设计，不会自动合并或删除已有明细行、旧列和历史报告。旧表头保留，“记录键”旧列不再使用。
Alexa 默认问题 1.4.0 是用户明确要求的明细行示例。 一次仍只输入一个美国站 ASIN；任务 JSON 是一份紧凑报告，本地明细表、Excel 和飞书按一个问题一行。七条问答是七行，问题、答案和关联问题1至5分列。同任务重试按任务编号、ASIN、问题编号与问题文本读回，只补缺失行；新任务追加新行。旧版一任务一行的历史报告保留。具体结构见功能说明。
| 一次任务的内容 | 任务 JSON 报告数 | 本地明细行数 | 飞书新增行数 |
|---|---|---|---|
| 一个 ASIN，7 条问答 | 1 | 7 | 7 |
| 一个 ASIN，501 条问答 | 1 | 501 | 501 |
| 同一任务全部写入后重试 | 1 | 仍为原有行 | 0 |
自动适配表格结构
- 解析链接、验证参数，通过官方 API 分页读取实际字段列表。
- 按名称复用已有字段。字段顺序不影响写入。
- 按声明自动创建缺失字段。新建业务字段默认全部为文本（
type:1）；不要把建列工作交给用户。 - 等待建列成功后才写入记录。同一次写入复用已取得的结构，避免每条记录重复查表、建列。
- 已有文本列直接写文本。已有数字列仅在值可无损表达且为有限数字时转换；类型不支持或不能转换时，指出字段名并停止该批写入。
“自动修正”指自动补齐所需列和适配写入值。不得默默删除用户已有列、重命名列、清空记录或强制改变已有字段类型；这些操作可能破坏用户的数据、公式和其他脚本。
建列或写入请求超时、响应不确定时，不得盲目重复追加。下次尝试先读取结构以复用已创建字段，按业务去重键检查记录；无法确定写入结果时明确提示“结果待确认”。缺少权限时说明需要该表的结构编辑或记录写入权限，不让用户逐个手建字段绕过问题。
全文本落表，不改变业务数据类型
默认所有飞书业务字段声明为 text，包括价格、数量、布尔值、时间、ASIN 和任务 ID。普通数值转十进制字符串，布尔值转 true/false，数组和对象转可读的 JSON 字符串；空值按约定写空文本或省略，不能把缺失价格写成 0。不要输出 [object Object]。
此约定仅针对飞书落表层。Tool 输入、JSON 报告与本地数据库仍按真实类型保存 number、boolean、array、object、null，不能为了飞书把所有脚本参数都改成字符串。只有用户明确需要飞书数字计算等功能时，才另行约定专用列类型。
批量、错误与通知
项目基线：批量追加每批最多 500 行（任务报告行，或用户明确要求的明细行），批次间等待 700ms；明确限流时按 1s、2s、4s 退避，最多重试三次。不能把网络超时当成确定未写入。选择业务去重键，保留成功数量，失败后只处理未成功项。
同时校验 HTTP 状态与响应体。采集成功、写表失败时保留业务数据，返回 wrote_feishu:false、output_error 和可理解的说明；不能把部分成功报告为全部成功，也不能因远端写入失败丢弃本地结果。
写表与机器人通知使用不同凭据。声明 @sellerfeeds-notification 的 link-on-success 策略后，只有采集、本地保存及飞书写入均确认成功，并返回有效表格链接，通知摘要才能附上该链接；机器人仍发送实际报告文件，脚本声明 Excel 时优先发送 .xlsx。任一环节失败、部分成功或待确认都应明示并保留报告。wrote_feishu 仅表示飞书事实，不能替代本地保存状态；当前运行器的通知门槛实现边界见通用公约。不能仅凭用户填了授权码就宣称写入成功。
提交与验收
本地始终完整保存，无需配置保存方式。首先验证未配置飞书时数据中心可按任务 ID 读回完整结果。再验证：整组留空零飞书请求、半填在采集前拦截、完整填写自动写入、空白表自动创建全部文本列、已有列不重复创建、多余列保留、分页读取、已有数字列兼容、非法值停止写入、建列权限不足、响应不确定与部分成功。任务汇总脚本须验证报告数量与明细数量分开；Alexa 默认问题 1.4.0 已由用户明确要求逐问输出，应验证 7／501 个问题分别写 7／501 行，501 行按 500+1 拆批，同任务只补缺失行。需要批量写入的脚本另验节流和重试。本地落库失败必须可见且支持从现有结果补存；补存不得重新采集、重复写表或再次通知。
文档与示例必须来自同一版本，发布后校验官网 Markdown 与仓库哈希一致。模拟 API 测试与真实账号写入验证分别记录，不用测试通过代替真实环境权限保证。