跳到导航

如何用飞书 CLI 把公众号文章写入多维表格,并避免重复新增?

要把公众号文章写入飞书多维表格又不产生重复行:用 wechat_mp.v2.fetch_article_detail_h5 读取文章,用 prepare_feishu_fields.py 生成 record-fields.json,用带 --dry-run 的 lark-cli base +record-upsert 预览写入,然后新增一行。保存返回的记录 ID,之后每次更新都用 --record-id 传入这个记录 ID:不带 --record-id 的 lark-cli base +record-upsert 会新增一行,不会按 Article URL 查找已有行。最后用 lark-cli base +record-get 读回,检查原文链接能打开、每个值落在正确的列。

选题理由、阅读状态和结论由同事写在各自的列,之后更新四个索引字段时,同事写的内容保持不变。

先决定这条资料要帮助团队做什么

例如研究同行的产品公告:核对产品与版本后,保留文章链接、标题和账号,再人工记录对应的研究问题、选题理由和未确认条件。公众号文章是来源材料,文章里的宣传说法不是团队已验证的结论。

下面的 prepare_feishu_fields.py 只写四个字段:Article URL、Title、Account ID、Request ID。阅读状态、研究主题、选题理由、负责人和分析不来自 API。要记录这些内容,先确认表里有可写的列,再由人工填写,或另外设计映射。负责人列里写了某人的名字,不代表此人已接下任务。

写表前后,怎样判断资料交接是否可靠?

你手里的结果能证明什么还要检查什么
record-fields.json 已生成本地索引已准备好目标表、真实字段与来源还没经过写入验证
--dry-run 打印了预期请求可以在本地检查准备写入的表和值远端字段是否可写、记录是否存在仍未确认
新增返回了记录 ID得到新记录的定位依据用记录 ID 读回,逐项核对文章 URL、标题和账号
已入表的文章再次出现先查已保存的映射和表内记录不带 --record-id 的 +record-upsert 可能再新增一行
超时且不知道是否成功记录可能已创建,也可能没有先在目标表里查找这篇文章的链接,再决定是否重新新增

读回正确后,才把本地“文章 → 记录 ID”映射标为完成。缺失的值不写进 record-fields.json,更新时就不会清空已有单元格。同一篇文章若有长短两种链接,先确认是同一篇,再决定是否当作两篇;标题相同不能证明是同一篇文章。

同事接到表格后,怎样继续工作?

保留原文链接,并用“待读、已核对、仍需补证”等人工状态区分进度。每条判断写明依据和下一步。文章已入表,不等于文章已读,也不等于问题已解决。需要正文时回到已保存的文章或原文页面,不把整篇文本塞进类型和长度限制未核对的单元格。

新增前确认表里还没有这篇文章;更新时只写这次核实的字段,保留同事写的分析和批注。lark-cli base +record-upsert 一次写一条记录,不提供业务键唯一约束,所以多人或定时任务同时写同一张表时,需要另外协调并发与查重。

下面第 1–6 步依次是字段核对、生成字段文件、dry-run、新增或更新、读回。飞书原生自动化回填、账号定时检查和群机器人推送是另外的任务,本页的写表流程不会接通这些功能。

例如同事把《安装手册更新》标为「待核新版入口」。如果这次只核实了标题和文章链接,就按已知的记录 ID 只更新这两列,同事的备注保持不变。读回时按同一个记录 ID 取出该行,核对文章链接与备注是否仍对应这篇文章。

1. 复用已保存正文,或先读取一次

先用免费的 /v1/capabilities/inspect 查看 data:wechat_mp.v2.fetch_article_detail_h5。执行这个动作会消耗余额;已有成功结果时直接复用,不重复读取同一篇文章。

curl -sS https://api.beatapi.io/v1/capabilities/inspect \
-H 'Content-Type: application/json' \
-d '{"reference":"data:wechat_mp.v2.fetch_article_detail_h5"}'
curl -sS https://api.beatapi.io/v1/social-data/call \
-H "Authorization: Bearer $BEATAPI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"wechat_mp.v2.fetch_article_detail_h5","params":{"url":"<article_url>"}}' \
-o wechat-article.json

按正文读取指南生成 wechat-article-source.json。article_url 是当前文章的链接,不用作者的 source_url 替代;响应里缺少链接时,先核对原请求再补入。飞书这一行只存文章索引,不存长篇正文。

2. 解析你确认的目标表

安装并授权飞书 CLI(lark-cli)后,先检查本机版本与命令帮助;本页使用 1.0.89 版本。不要切换身份绕过权限,也不要公开 token。

lark-cli --version
lark-cli base +record-upsert --help
lark-cli base +url-resolve --url '<your_base_url>' --as user
lark-cli base +field-list --base-token '<base_token>' --table-id '<table_id>' --as user

传入 +url-resolve 返回的 base_token 和 table_id。目标必须是多维表格中的表;电子表格的 sheet_id 或 BaseApp 的 app_token 不能代替 base_token 和 table_id。

3. 确认四个可写文本字段

本例要求目标表已有 Article URL、Title、Account ID、Request ID 四个文本列。用 +field-list 核对真实列名与类型;列名不同就修改 prepare_feishu_fields.py 里的映射,不顺手创建、改名或删除字段。公式字段和系统字段不能当普通文本列写。

下面的 Python 脚本只生成本地字段文件,不调用飞书。缺失的可选值不发送,避免 null 清空已有单元格。

import json
import tempfile
from pathlib import Path
from urllib.parse import parse_qs, urlsplit
record = json.loads(Path("wechat-article-source.json").read_text(encoding="utf-8"))
url = record.get("article_url")
parsed = urlsplit(url) if isinstance(url, str) else None
if not parsed or parsed.scheme not in {"http", "https"} or parsed.hostname != "mp.weixin.qq.com" or parsed.username:
raise SystemExit("Verify the current article URL before writing.")
query = parse_qs(parsed.query)
if not ((parsed.path == "/s" and all(query.get(key) for key in ["__biz", "mid", "idx"])) or (parsed.path.startswith("/s/") and parsed.path[3:].strip())):
raise SystemExit("Missing article identifier.")
fields = {"Article URL": url}
for local_key, field_name in [("title", "Title"), ("account_id", "Account ID"), ("request_id", "Request ID")]:
value = record.get(local_key)
if value is not None and not isinstance(value, str):
raise SystemExit(f"Invalid text field: {local_key}")
if isinstance(value, str) and value.strip():
fields[field_name] = value
target = Path("record-fields.json")
with tempfile.NamedTemporaryFile(mode="w", dir=target.parent, encoding="utf-8", delete=False) as output:
temporary = Path(output.name)
json.dump(fields, output, ensure_ascii=False, indent=2)
try:
temporary.replace(target)
finally:
temporary.unlink(missing_ok=True)

lark-cli base +record-upsert 要求 record-fields.json 顶层直接是字段映射,不再包一层 fields。CLI 的输入格式与飞书原生 OpenAPI 请求体不同。

把代码保存为 prepare_feishu_fields.py,运行 python3 prepare_feishu_fields.py,预览前先打开生成的 record-fields.json 检查:文件只含索引字段,不含正文或 API Key。

要存发布时间,先确认表里另有一个可写文本列,再把 ("published_at_utc", "Published UTC") 加入映射。ISO 时间按文本写入;日期类型列使用另一种 CLI 值格式,不能把 ISO 文本原样写进日期列。采集时间 collected_at 同理,但列名必须写明是采集时间,不能冒充发文时间。

4. 先预览,再批准写入

lark-cli base +record-upsert \
--base-token '<base_token>' --table-id '<table_id>' \
--json @record-fields.json --as user --dry-run

检查 dry-run 输出里的目标表和字段值。写入获批后,再去掉 --dry-run 真正写入。授权过程和账号凭据不要写进文章提示词。

5. upsert 不等于按文章链接自动去重

lark-cli base +record-upsert 不带 --record-id 时新增记录,带 --record-id 时更新那条记录;命令不会在 Article URL 列里查重。首次新增成功后,保存“核对过的文章键 → 记录 ID”的映射,后续更新带上这个记录 ID:

lark-cli base +record-upsert \
--base-token '<base_token>' --table-id '<table_id>' \
--record-id '<existing_record_id>' --json @record-fields.json --as user --dry-run

重新导入前,先检查已保存的映射和目标表。映射丢失时先查已有记录,不要直接再次新增。长短链接指向同一篇文章的识别,以及多人并发运行,都需要另定识别与协调规则;命令名叫 upsert,不代表有业务键唯一约束。

新增或更新获批并完成后,用 lark-cli base +record-get 按真实返回的记录 ID 读回核对,再把本地文章映射标为完成:

lark-cli base +record-get \
--base-token '<base_token>' --table-id '<table_id>' \
--record-id '<actual_returned_record_id>' \
--field-id 'Article URL' --field-id 'Title' --field-id 'Account ID' --field-id 'Request ID' --as user

启用了可选日期列时,也把对应列名加入读回命令的 --field-id 列表。把返回的 URL 和字段值与 record-fields.json 逐项比较。写入超时且没拿到记录 ID,不能证明记录没有创建:先核对目标表再重试,不能只因本地映射缺失就再新建一行。

6. 验收失败与更新结果

lark-cli 以退出码 0 或 ok=true 表示成功,不按旧 OpenAPI 顶层 code=0 判断。保存 CLI 实际返回的记录 ID,并核对这条记录就是目标记录;写入超时且结果未知时,先查表,不立即重新新增。

权限失败时,修复目标身份的授权或表访问权限。已生成 record-fields.json 不等于已写入飞书。周期更新使用增量检查;外部调度、通知和长正文存储是另外的任务。

参考:lark-cli 1.0.89 命令帮助与飞书多维表格服务端文档。