用WorkBuddy做AI工具站加餐04:同步飞书表格

大家好，我是宇哥，专注AI编程、智能体，解决小白AI编程问题。

前面加餐 03，我们已经做了一个“工具提交入口”：读者可以把新工具提交进来，但还不能直接进入工具站。

这一篇继续用 WorkBuddy，把这些提交候选整理成一个飞书表格同步预览包。

注意，这里不是“自动上架”。我们要做的是：先把通过初审的候选筛出来，转换成飞书表格能读的字段，再交给人工终审。

这篇你能做出什么

跟着这篇做完，你会得到 5 个文件：

tutorials/workbuddy-tool-directory-extras/demo/extra-04/
├── data/
│   ├── feishu-field-mapping.json
│   ├── feishu-sync-preview.csv
│   └── feishu-sync-preview.json
├── reports/
│   └── feishu-sync-preview-report.md
└── scripts/
    └── check-feishu-sync-preview.py

它们分别负责：

最后你会看到真实校验结果：

校验通过
输入候选: 5
进入同步预览: 1
字段数量: 8
输出文件:
- data/feishu-field-mapping.json
- data/feishu-sync-preview.csv
- data/feishu-sync-preview.json
- reports/feishu-sync-preview-report.md

适合谁，不适合谁

适合你，如果你已经做到这一步：

• 有一个 AI 工具站；
• 有工具提交入口；
• 想把提交候选放进飞书表格里继续审核；
• 不想一上来就写复杂的飞书 API 代码。

不适合你，如果你现在想要的是：

• 提交后立刻自动上架；
• 不做人工复核，直接相信用户提交内容；
• 采集或同步真实敏感数据。

这一篇的重点是安全的同步预览，不是把飞书 API 全部接完。

准备环境

你需要准备：

1. 已经完成加餐 03；
2. 本地有上一篇生成的提交样例文件；
3. Python 3；
4. 一个可以编辑文件的环境；
5. WorkBuddy，或者 Cursor / Claude Code / Codex 这类 AI 编程助手。

上一篇的输入文件是：

tutorials/workbuddy-tool-directory-extras/demo/extra-03/data/sample-tool-submissions.jsonl

里面有 5 条本地样例提交，其中只有 1 条是通过初审的候选。

先看最终效果

这一篇完成后，你会把上一篇的 JSONL 提交候选整理成下面这条链路：

工具提交样例 → 只筛通过初审的候选 → 转成飞书字段 → 生成 CSV/JSON → 人工终审

这个边界很重要：

• accepted 只是“通过初审”；
• 价格字段只作为“价格线索”；
• 飞书表格只是审核区；
• 是否进入公开工具库，还要人工最后确认。

第一步｜新建本篇 demo 目录

打开项目根目录，新建本篇目录：

mkdir -p tutorials/workbuddy-tool-directory-extras/demo/extra-04/{data,reports,scripts,prompts}

你可以先检查一下目录：

ls tutorials/workbuddy-tool-directory-extras/demo/extra-04

看到这些目录就算成功：

data
prompts
reports
scripts

第二步｜把任务交给 WorkBuddy

把下面这段提示词复制给 WorkBuddy：

你是我的 AI 编程助手。请基于上一篇生成的 data/sample-tool-submissions.jsonl，帮我做一个飞书表格同步预览包。

要求：
1. 读取 JSONL，每行是一条工具提交候选。
2. 只筛选 review_status = accepted 的记录。
3. 生成 data/feishu-field-mapping.json，把工具站字段映射到飞书表格字段。
4. 生成 data/feishu-sync-preview.csv 和 data/feishu-sync-preview.json。
5. 生成 reports/feishu-sync-preview-report.md，写清楚同步边界：这里只做预览，不直接写入正式表格；价格字段只作为线索；进入飞书后仍需要人工终审。
6. 写一个检查脚本，确认字段映射、CSV/JSON 数量、导出边界都正确。

不要把未通过初审的候选写进预览区。

如果你担心 WorkBuddy 一次生成太多，可以让它先只生成脚本，再运行脚本生成数据文件。

本篇我采用的做法是：先写一个 create-extra-04-demo.py，让它统一生成字段映射、CSV、JSON 和报告。

第三步｜生成字段映射

新建文件：

tutorials/workbuddy-tool-directory-extras/demo/extra-04/data/feishu-field-mapping.json

填入下面这份字段映射：

{
  "table_name": "AI工具候选审核区",
  "source_file": "../extra-03/data/sample-tool-submissions.jsonl",
  "sync_boundary": "only accepted submissions are exported; human review remains required before public listing",
  "fields": [
    {"source": "id", "feishu_field": "提交ID", "type": "text", "required": true},
    {"source": "tool_name", "feishu_field": "工具名称", "type": "text", "required": true},
    {"source": "tool_url", "feishu_field": "官网链接", "type": "url", "required": true},
    {"source": "category", "feishu_field": "分类", "type": "single_select", "required": true},
    {"source": "use_case", "feishu_field": "适用场景", "type": "long_text", "required": true},
    {"source": "pricing_hint", "feishu_field": "价格线索", "type": "text", "required": false},
    {"source": "submitter_note", "feishu_field": "复核备注", "type": "long_text", "required": false},
    {"constant": "待人工终审", "feishu_field": "同步状态", "type": "single_select", "required": true}
  ]
}

这里最关键的是最后一列：同步状态。

它不是来自用户提交，而是我们人为加上的固定值：待人工终审。

这样飞书表格里一眼就能看出：这批数据只是进入审核区，还没有成为正式工具库数据。

第四步｜生成同步预览 CSV 和 JSON

接着生成两个预览文件：

data/feishu-sync-preview.csv
data/feishu-sync-preview.json

筛选规则只有一个：

只导出 review_status = accepted 的记录

以上一篇的样例数据为例，5 条候选里只有 1 条进入同步预览：

[
  {
    "提交ID": "sub-005",
    "工具名称": "Excalidraw",
    "官网链接": "https://excalidraw.com/",
    "分类": "效率工具",
    "适用场景": "适合快速画产品草图、流程图和教程结构图。",
    "价格线索": "免费",
    "复核备注": "这条可作为非 AI 但高频效率工具候选。",
    "同步状态": "待人工终审"
  }
]

如果你用 WorkBuddy 生成脚本，一定要提醒它：不要把 new、needs_check 这些状态的记录也写进去。

第五步｜生成同步预览报告

新建报告文件：

reports/feishu-sync-preview-report.md

报告至少写 4 件事：

• 输入文件来自哪里；
• 一共有多少条候选；
• 多少条进入同步预览；
• 哪些地方仍然需要人工终审。

本篇真实报告里的统计是：

人工验收清单建议这样写：

- [ ] 飞书字段名和工具站字段一一对应。
- [ ] 只导出已通过初审的候选。
- [ ] 价格只作为线索，不当作最终结论。
- [ ] 复核备注保留，方便进入飞书后继续人工判断。
- [ ] 正式写入前再次确认链接、分类和版权边界。

这一步完成后，你就已经有一个可交给运营同学看的同步预览包了。

第六步｜写检查脚本

最后新建检查脚本：

scripts/check-feishu-sync-preview.py

检查脚本至少要确认：

1. 字段映射文件存在；
2. CSV 和 JSON 都存在；
3. CSV 和 JSON 数量一致；
4. 只导出了 accepted 的候选；
5. 每条记录都有 8 个飞书字段；
6. 报告里写清了“预览”和“人工终审”的边界。

运行命令：

cd tutorials/workbuddy-tool-directory-extras/demo/extra-04
python3 scripts/check-feishu-sync-preview.py

本篇真实运行结果：

校验通过
输入候选: 5
进入同步预览: 1
字段数量: 8
输出文件:
- data/feishu-field-mapping.json
- data/feishu-sync-preview.csv
- data/feishu-sync-preview.json
- reports/feishu-sync-preview-report.md

看到 校验通过，说明本篇交付物完成。

常见报错和排查

1. 找不到上一篇 JSONL 文件

如果脚本提示找不到：

../extra-03/data/sample-tool-submissions.jsonl

先确认你是不是在本篇 demo 目录里运行命令：

pwd

正确位置应该类似：

tutorials/workbuddy-tool-directory-extras/demo/extra-04

如果你在项目根目录运行，就要么先 cd 到本篇目录，要么把脚本里的相对路径改成从项目根目录出发的路径。

2. CSV 打开后中文乱码

CSV 文件建议用 utf-8-sig 编码保存。

如果你用 Python 写 CSV，可以这样打开文件：

open("data/feishu-sync-preview.csv", "w", encoding="utf-8-sig", newline="")

这样用常见表格软件打开时，中文更不容易乱码。

3. 预览记录数量不对

如果你看到 5 条候选都进入了预览，说明筛选条件写错了。

检查代码里是不是用了：

if r.get("review_status") == "accepted"

本篇只允许通过初审的候选进入同步预览。

4. 把同步写成自动上架

这是产品边界问题，不是代码问题。

这一篇的正确说法是：

同步预览 → 人工终审 → 再进入公开数据

不要写成：

用户提交 → 自动进入工具站

工具站一旦有用户提交入口，就必须把人审关口留住。

完整代码 / 配置汇总

本篇完整 demo 路径：

tutorials/workbuddy-tool-directory-extras/demo/extra-04/

核心输出文件：

data/feishu-field-mapping.json
data/feishu-sync-preview.csv
data/feishu-sync-preview.json
reports/feishu-sync-preview-report.md
prompts/workbuddy-feishu-sync-prompt.md
scripts/create-extra-04-demo.py
scripts/check-feishu-sync-preview.py

你可以用下面两条命令重建并检查本篇 demo：

cd tutorials/workbuddy-tool-directory-extras/demo/extra-04
python3 scripts/create-extra-04-demo.py
python3 scripts/check-feishu-sync-preview.py

这一篇你学会了什么

这一篇，我们没有急着接飞书 API，而是先做了一个更稳的中间层：

• 用 WorkBuddy 帮我们生成同步预览包；
• 用字段映射把工具站数据转成飞书表格字段；
• 只让通过初审的候选进入预览；
• 用检查脚本确认导出边界；
• 把人工终审留在正式写入之前。

对小白来说，这个顺序更安全：先把数据结构和边界跑通，再去接真实接口。

下一篇预告

第一季加餐到这里就完成了。

下一季我们会进入一个更实战的场景：

用WorkBuddy做网页采集器01：确定采集目标

也就是先不写采集脚本，而是先把“采什么、为什么采、哪些不能采、输出什么字段”定下来。

网页采集这件事，第一步不是写代码，而是写清楚边界。

资料来源

• 本系列本地 demo：tutorials/workbuddy-tool-directory-extras/demo/extra-04/
• 上一篇样例输入：tutorials/workbuddy-tool-directory-extras/demo/extra-03/data/sample-tool-submissions.jsonl
• 飞书开放平台文档：https://open.feishu.cn/document/