飞书多维表格同步

技能文档

---
name: content-system-feishu-bitable-sync
title: 飞书多维表格同步
description: 把本地公众号采集报告同步到飞书多维表格的工具，读取 wechat-report 产出的 Markdown 或 raw JSON，按一篇文章一行写入多维表，使用 source_url 去重更新（重复同步更新已有行而非重复新增），直写失败时自动导出 CSV 兜底文件供手工导入，支持用户授权与应用身份两种鉴权模式。当用户确认要把公众号报告、文章采集结果发送到飞书多维表时触发。触发词：飞书同步、多维表格、发送到飞书、公众号报告同步、bitable、文章入库。
category: 办公效率
---

# 飞书多维表格同步

本技能不会自动触发，只有在用户明确确认「发送到飞书」后才运行。

## 技能工作流

### 步骤1：确认输入文件

支持两种输入：

- `content-production/inbox/YYYYMMDD-{slug}-wechat-report.md`（报告 Markdown，内含 Raw JSON 路径）
- `content-production/inbox/raw/wechat-report/YYYY-MM-DD/{slug}.json`（raw JSON）

用户只给报告名时，按日期目录推断完整路径并与用户确认。

### 步骤2：检查配置与授权

运行前需要配置环境变量：

- `FEISHU_APP_ID`、`FEISHU_APP_SECRET`（飞书应用凭证）
- `FEISHU_BITABLE_APP_TOKEN`、`FEISHU_BITABLE_TABLE_ID`（目标多维表）
- 可选：`FEISHU_SYNC_AUTH_MODE`，默认 `user`；`FEISHU_OAUTH_REDIRECT_URI`，默认 `http://127.0.0.1:14578/callback`

用户授权模式下优先读取本机缓存的 `user_access_token`；若尚未授权，执行：

```bash
python3 feishu_auth.py authorize
```

按提示在浏览器完成授权，token 会缓存到本机（`~/.cache/feishu-sync/`）。

### 步骤3：执行同步

```bash
python3 runtime.py run --input content-production/inbox/YYYYMMDD-{slug}-wechat-report.md
```

同步策略：

- 每篇文章一行，使用 `source_url` 去重
- 重复同步会更新已有行，而不是重复新增
- 表中已存在的空行会被优先复用
- 写入前自动读取表结构，按字段类型归一化取值

### 步骤4：处理同步结果

输出回执：

- `content-production/published/YYYYMMDD-{slug}-feishu-sync.md`（同步结果清单，含新增/更新行数与逐篇明细）
- 直写失败时额外导出：`content-production/published/YYYYMMDD-{slug}-feishu-import.csv`（兜底文件，可在飞书多维表中「导入 Excel/CSV」入库）

按回执 `status` 处理：

- `synced`：向用户报告新增/更新行数
- `auth_required`：提示先运行 `python3 feishu_auth.py authorize` 完成授权后重试
- `csv_exported`：告知直写未成功，已生成 CSV 兜底，可手工导入或稍后重试
- `sync_failed`：展示错误信息，排查环境变量与网络后重试

## 环境变量说明

| 变量 | 必填 | 说明 |
|------|------|------|
| `FEISHU_APP_ID` | 是 | 飞书应用 App ID |
| `FEISHU_APP_SECRET` | 是 | 飞书应用 App Secret |
| `FEISHU_BITABLE_APP_TOKEN` | 是 | 目标多维表格 app_token |
| `FEISHU_BITABLE_TABLE_ID` | 是 | 目标数据表 table_id |
| `FEISHU_SYNC_AUTH_MODE` | 否 | `user`（默认）或 `tenant` |
| `FEISHU_OAUTH_REDIRECT_URI` | 否 | 授权回调地址，默认本地 14578 端口 |
| `FEISHU_TOKEN_CACHE` | 否 | token 缓存文件路径，默认 `~/.cache/feishu-sync/user_access_token.json` |
| `FEISHU_SYNC_WORKSPACE_ROOT` | 否 | 输出根目录，默认当前目录 |

## 注意事项

- 本技能应放在「用户确认后」执行，不应默认自动触发
- 应用需开通多维表格读写权限；用户授权模式需在飞书开放平台配置回调地址
- 目标数据表字段与回执字段一致时可获得最佳写入效果（缺失字段会跳过）

使用说明

# 飞书多维表格同步

把本地公众号采集报告同步到飞书多维表格，按 `source_url` 去重，直写失败自动导出 CSV 兜底。

## 能做什么

- 读取 wechat-report 产出的 Markdown 或 raw JSON
- 一篇文章一行写入飞书多维表，重复同步更新已有行
- 优先使用用户授权 token，也支持应用身份（tenant）模式
- 直写失败时导出 CSV，供手工导入兜底

## 何时使用

- 已确认要把公众号对比报告沉淀为多维表资产
- 需要把文章采集结果按期入库、可检索可筛选

## 快速上手

```bash
# 1. 配置环境变量（APP_ID/APP_SECRET/BITABLE_APP_TOKEN/TABLE_ID）
# 2. 首次使用先完成授权
python3 feishu_auth.py authorize
# 3. 执行同步
python3 runtime.py run --input content-production/inbox/20260407-demo-wechat-report.md
```

同步结果输出到 `content-production/published/YYYYMMDD-{slug}-feishu-sync.md`。

## 注意事项

- 本技能在用户确认「发送到飞书」后才执行，不自动触发
- 无授权缓存时会生成 `auth_required` 回执，先跑 `feishu_auth.py authorize`

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。