> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

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

> 用 prepare_feishu_fields.py 从已核对的公众号文章记录生成字段映射，通过 lark-cli base +record-upsert --dry-run 预览写入，按 --record-id 定向更新并用 +record-get 读回校验。

要把公众号文章写入飞书多维表格又不产生重复行：用 `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`。执行这个动作会消耗余额；已有成功结果时直接复用，不重复读取同一篇文章。

```bash
curl -sS https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:wechat_mp.v2.fetch_article_detail_h5"}'
```

```bash
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
```

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

## 2. 解析你确认的目标表

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

```bash
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 清空已有单元格。

```python
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. 先预览，再批准写入

```bash
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：

```bash
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 读回核对，再把本地文章映射标为完成：

```bash
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` 不等于已写入飞书。周期更新使用[增量检查](/zh/guides/wechat-incremental-articles)；外部调度、通知和长正文存储是另外的任务。

参考：`lark-cli` 1.0.89 命令帮助与[飞书多维表格服务端文档](https://open.feishu.cn/document/server-docs/docs/bitable-v1/app-table-record/create)。