在英语学习、备考或做个人知识库时把生词整理成带音标、释义和例句的卡片是很多人的刚需。真正消耗精力的不是“背单词”本身而是维护卡片的过程查词、复制释义、切到 Notion、新建页面、选择数据库、填写字段。一个词至少重复五六步坚持两周就很难继续。Workbuddy 这类 AI 自动化工具正好可以把“查单词、整理卡片、写入 Notion 数据库”这条链路合并成一个自动化任务。用户只需要把单词列表准备好触发一次任务Workbuddy 就能批量生成规范的单词卡片并导入 Notion。这篇文章以“Workbuddy 一键自动化生成单词卡片导入 Notion”为目标会先讲清自动化链路里的关键概念再从环境准备、数据设计、任务配置、API 写入到故障排查给出可以复用的完整流程。读者不需要事先熟悉 AI Agent 或 Notion 开发接口按章节走完就能在自己的环境里跑通最小版本。1. 先看清这条自动化链路里的三个关键角色在动手配置之前先理解这条链路为什么能成立。整条流程由三个角色组成Workbuddy 负责执行Notion API 负责接收数据单词卡片的数据结构负责约定格式。任何一个环节理解不到位后面都会出现“任务看起来执行成功数据库里却没有卡片”或“卡片写进去但字段错乱”这类问题。1.1 Workbuddy 在流程里充当什么角色Workbuddy 是一款 AI 自动化代理工具它的核心能力是接受用户的自然语言任务描述并把任务拆解成一系列动作来执行。你可以把它理解成一个“有执行权限的助手”你告诉它要做什么、按什么规则做它调用自己的模型推理能力、已配置的插件、本机脚本或外部 HTTP 接口逐步完成任务。在单词卡片场景里Workbuddy 做的事情可以拆成四步读取单词输入列表。对每个单词生成音标、中英文释义和一个简单例句。把结果填充成符合既定规则的卡片数据。把数据写入提供的 Notion 数据库 API 接口。不同版本的 Workbuddy 在入口和命名上可能不同比如通过对话会话触发、通过任务画布编排或者通过命令行调用。文章里给出的流程是通用执行逻辑实际使用时以你安装版本的交互方式为准。1.2 Notion API 为什么是导入操作的唯一通道Notion 本身是一个界面产品所有页面都可以手动创建但手动创建无法支撑批量自动化。Notion API 提供了对工作区和数据库的编程访问能力开发者可以通过 REST 接口创建一个页面、查询数据库、更新页面属性。用官方 API 写入数据有几个特点数据以结构化属性写入字段名和字段类型必须和数据库定义一致。请求需要携带鉴权 TokenToken 归属某个集成Integration。集成必须被显式添加到目标数据库或页面否则没有读取和写入权限。这意味着并不是拿到 API Token 就能写入任意数据库。你需要先创建集成再把该集成的访问权限关联到自己的数据库。这个环节最容易看漏。1.3 单词卡片数据是从自由文本变成结构化字段的过程手动维护卡片时人可以接受“音标在这里、释义在这里”这种模糊描述。但 API 不会猜测它要求每条数据都对应数据库里的一个字段名和字段类型。在 Notion 数据库里一张“单词卡片”实际上是一行记录包含一个标题字段通常保存单词本身。若干文本字段保存音标、释义、例句。一个选择或状态字段保存熟练度比如“新词”“熟悉”。字段类型决定了 API 请求里的 JSON 格式。例如数据库里若把“音标”定义为富文本类型请求里就必须写成 rich_text 数组若把“熟练度”定义为 Select 类型请求里就要用 select 对象。如果类型不一致Notion 会直接拒绝这次写入。所以设计数据库结构本质上是在设计任务输出规范。先定好字段结构再让 Workbuddy 按这个结构生成数据流程才能稳定。2. 环境准备安装 Workbuddy 并接入 Notion API这一节完成三件事把 Workbuddy 装好并能正常发起任务创建 Notion 集成并拿到 Token在 Notion 里设计好目标数据库字段。建议按顺序做不要先在数据库中建一堆字段再回头改因为字段类型一旦在数据库里固定API 写入就必须严格匹配。2.1 安装 Workbuddy 并确认运行方式Workbuddy 的安装方式在不同平台上并不完全一致。以通用的桌面端或本地服务端方式为例一般会提供安装包或命令行安装入口。安装完成后先在终端或控制台里确认命令可用workbuddy --version如果命令不存在可能是因为安装目录没有加入 PATH或者当前安装版本只提供图形界面。可以先打开图形客户端在帮助或设置页面查看版本号。如果准备使用本地部署方式还需要确认运行环境满足要求常见项目包括操作系统版本、可用的内存和磁盘空间、是否允许本地监听端口。生产环境使用前建议重新读一遍对应版本的安装文档避免依赖某个临时下载入口。学习环境下只需要一个能运行 Workbuddy 的机器即可。开发或生产环境还要考虑任务日志、网络策略、Token 保管方式和回滚方案这些内容在后面的最佳实践里继续展开。2.2 创建 Notion 集成并获取 TokenNotion API 使用集成Integration作为访问主体。你在 Notion 后台创建一个集成后会得到一个以secret_开头的 TokenAPI 请求通过请求头里的 Authorization 字段携带这个 Token。创建完集成后必须把集成关联到目标数据库具体方式是在数据库页面右上角打开“更多”菜单选择“连接到”并找到刚创建的集成。缺少这一步即使 Token 正确API 也会返回 403。同时要找到数据库 ID。打开目标数据库页面后URL 里那一串 32 位字符就是 database_id。建议复制到本地配置文件中不要在多个地方手写避免因复制遗漏导致后续 404。下面用一个 Python 代码示例说明如何用官方客户端检查数据库是否能访问from notion_client import Client NOTION_TOKEN secret_你的集成Token DATABASE_ID 你的数据库ID notion Client(authNOTION_TOKEN) try: db notion.databases.retrieve(database_idDATABASE_ID) print(数据库名称, db[title][0][plain_text]) print(数据库字段, list(db[properties].keys())) except Exception as e: print(访问失败, e)这段代码只要能打印出数据库名称和字段列表就说明 Token、数据库 ID 和集成权限三个环节都是通的。任何一个环节不对都会在这一步暴露。2.3 先设计好 Notion 数据库字段避免后面反复改结构Notion 数据库的字段结构决定了 Workbuddy 生成数据的格式。下面是一张推荐的最小字段表字段名属性类型说明单词Title数据库必须有一个标题字段这里保存单词本身音标Rich Text保存英式或美式音标释义Rich Text保存中英文释义可包含词性例句Rich Text一个典型例句熟练度Select分为“新词”“熟悉”“已掌握”三档来源Multi-select可选记录单词来自哪份材料创建数据库可以通过 Notion 界面手动创建也可以调用 API 创建。需要说明的是手动创建时属性类型选错了很难事后调整所以建议按表格选好类型。如果希望通过代码创建可以参考下面的 Python 片段该代码会在一个现有页面内创建新的数据库from notion_client import Client notion Client(authsecret_你的集成Token) parent_page_id 目标页面的Page ID db notion.databases.create( parent{page_id: parent_page_id}, title[{type: text, text: {content: 单词卡库}}], properties{ 单词: {title: {}}, 音标: {rich_text: {}}, 释义: {rich_text: {}}, 例句: {rich_text: {}}, 熟练度: { select: { options: [ {name: 新词}, {name: 熟悉}, {name: 已掌握} ] } }, 来源: {multi_select: {options: []}}, }, ) print(db[id])创建完成后把打印出来的数据库 ID 记录下来后续所有写入请求都指向这个 ID。3. 设计可复用的单词卡片自动化流程环境准备好之后重点就从“手工操作”转移到“让 Workbuddy 按规则工作”。这里的核心不是一次性生成几张卡片而是设计一套每次都能稳定输出相同质量数据的任务规范。3.1 准备输入源CSV 或纯文本推荐使用 CSV 文件作为单词输入源方便批量维护也方便 Workbuddy 读取。最简单的方式是只保留一列单词由 Workbuddy 去补全音标、释义和例句word abandon abroad absorb academic according如果已经有带释义的材料也可以设计成多列word,meaning,note abandon,v. 放弃抛弃,考研高频词 abroad,adv. 在国外,注意与 aboard 区别这里要注意编码问题。如果 Workbuddy 读取 CSV 后出现中文乱码优先检查文件是否保存为 UTF-8 格式。不建议使用 Excel 默认的本地编码因为不同操作系统对非 UTF-8 文件的支持不一致。从学习环境进入生产环境时输入文件应当纳入版本管理或统一目录管理避免每次都在任务描述里重新描述路径。3.2 用自定义指令约束 Workbuddy 的处理步骤Workbuddy 支持通过自定义指令或 skill 来固定任务行为。可以理解成把一段稳定的提示词保存成模板每次任务直接复用而不是每次临时重复输入。下面是一个可参考的 Markdown 指令模板建议先复制到本地再根据自己版本做调整任务名称: 批量生成单词卡片并导入Notion 输入: - 读取 CSV 文件路径为 data/word_list.csv - 每次任务运行前先确认文件存在且包含 word 列 处理规则: 1. 对每个单词生成美式音标。 2. 给出一个常见中文释义和词性标记。 3. 生成一个简单、贴近日常用法的英文例句。 4. 将每条结果整理成 Notion API 的 properties 结构。 5. 调用 Notion API 创建页面目标数据库 ID 由配置传入。 字段映射: - 单词 - title - 音标 - rich_text - 释义 - rich_text - 例句 - rich_text - 熟练度 - select默认新词 输出要求: - 每个单词对应一个 Notion 页面。 - 某个单词失败时记录失败原因继续处理下一个词。 - 任务结束后输出成功数量和失败数量。这段模板里的关键点有三个第一是规定输入来源第二是规定字段映射第三是规定失败处理方式。实际项目中建议把数据库 ID、文件路径和 Token 不要直接写死在指令里而是通过环境变量或配置文件传入。很多新手一开始只写“生成卡片并导入 Notion”结果每轮生成卡片的字段顺序不一致或者遇到失败词条直接中断整批任务。模板中明确“失败继续处理”和“输出统计信息”就是为了规避这个问题。3.3 生成符合 Notion API 要求的卡片数据当 Workbuddy 完成查词与整理后输出的数据应该尽量标准化。下面是一个单词 card 的对象示例{ properties: { 单词: { title: [ {text: {content: abandon}} ] }, 音标: { rich_text: [ {text: {content: /əˈbændən/}} ] }, 释义: { rich_text: [ {text: {content: v. 放弃抛弃}} ] }, 例句: { rich_text: [ {text: {content: He had to abandon the car.}} ] }, 熟练度: { select: {name: 新词} } } }需要特别强调Card 数据结构里最外层的字段名必须和 Notion 数据库的属性名完全一致包括大小写和空格。单词字段在数据库里是 Title 类型所以 JSON 里用title数组包住音标、释义、例句是富文本类型所以用rich_text数组熟练度是 Select 类型所以用select对象。如果你把单词误写成word或者把音标写成字符串而不是数组Notion API 会返回 400 错误。这些细节是自动化流程里最常见的失败来源。4. 执行导入调用 Notion API 写入数据库当 Workbuddy 生成多张卡片数据后还需要真正把数据写入 Notion。这一步可以直接交给 Workbuddy 调用 HTTP 接口完成也可以用本地脚本在工作流里执行。下面分别说明原理和最小实现。4.1 最小写入请求的代码示例Notion API 创建页面的接口是请求方法POST请求地址https://api.notion.com/v1/pages请求头Authorization、Notion-Version、Content-Type用 Python 的requests库写一个最小例子import requests NOTION_TOKEN secret_你的集成Token DATABASE_ID 你的数据库ID NOTION_VERSION 2022-06-28 headers { Authorization: fBearer {NOTION_TOKEN}, Notion-Version: NOTION_VERSION, Content-Type: application/json, } payload { parent: {database_id: DATABASE_ID}, properties: { 单词: { title: [{text: {content: abandon}}] }, 音标: { rich_text: [{text: {content: /əˈbændən/}}] }, 释义: { rich_text: [{text: {content: v. 放弃抛弃}}] }, 例句: { rich_text: [{text: {content: He had to abandon the car.}}] }, 熟练度: { select: {name: 新词} } } } resp requests.post( https://api.notion.com/v1/pages, headersheaders, jsonpayload, timeout15 ) print(resp.status_code) print(resp.json())正常响应返回200或200 OK并且resp.json()里会包含新创建的页面 ID。如果返回400、401、403或404说明数据结构、Token 权限、数据库 ID 或字段映射存在问题排查方式见第 6 节。4.2 在 Workbuddy 中组织批量导入单张卡片写入只适合验证链路是否畅通。真实场景下单词通常有几十个甚至上百个。批量处理时建议让 Workbuddy 或本地脚本按循环逐条写入并在每两条请求之间留出间隔避免短时间内请求量过大。下面是一个适用于批量的 Python 骨架可以直接放入任务流程中import time import requests NOTION_TOKEN secret_你的集成Token DATABASE_ID 你的数据库ID NOTION_VERSION 2022-06-28 headers { Authorization: fBearer {NOTION_TOKEN}, Notion-Version: NOTION_VERSION, Content-Type: application/json, } cards [ # 这里放 Workbuddy 生成的卡片数据列表 ] success_count 0 fail_list [] for card in cards: payload { parent: {database_id: DATABASE_ID}, properties: card[properties], } try: resp requests.post( https://api.notion.com/v1/pages, headersheaders, jsonpayload, timeout15 ) if resp.status_code in (200, 201): success_count 1 else: fail_list.append({ card: card, status: resp.status_code, message: resp.text }) except Exception as e: fail_list.append({ card: card, error: str(e) }) time.sleep(0.3) print(f成功 {success_count} 条失败 {len(fail_list)} 条)这里有几个有用实践每张卡片都单独捕获异常避免一条失败拖停整个批次。将失败信息记录到列表中任务结束后统一查看。请求之间增加time.sleep给 Notion API 留出处理余量。如果你用的是 Workbuddy 内置的 HTTP 调用能力而不是本地 Python逻辑也一样循环执行 HTTP 请求记录响应状态并按顺序处理。4.3 如何确认导入成功导入完成后不要只在 Workbuddy 里看到“成功”就结束。最稳妥的验证方式是查询数据库确认实际写入的记录数量。用 Notion API 查询数据库的接口是import requests headers { Authorization: fBearer {NOTION_TOKEN}, Notion-Version: NOTION_VERSION, Content-Type: application/json, } query { page_size: 10 } resp requests.post( fhttps://api.notion.com/v1/databases/{DATABASE_ID}/query, headersheaders, jsonquery, timeout15 ) results resp.json().get(results, []) for page in results: title_prop page[properties].get(单词, {}) if title_prop.get(type) title: titles title_prop.get(title, []) if titles: print(titles[0][text][content])如果能打印出刚导入的单词列表说明整条链路真实闭环。如果打印为空但 Workbuddy 提示成功需要回到权限或数据库 ID 环节检查。5. 稳定运行的边界条件与幂等设计一键自动化听起来像是“点击一次就万事大吉”但真正稳定运行需要处理三个边界条件请求频率、重复导入和部分失败。这三个问题如果不处理第一次跑通很简单长期使用却会不断出现脏数据。5.1 控制批次大小避免触发频率限制Notion API 对同一个集成的请求频率有一定限制具体阈值会随账户状态和官方政策变化。稳妥做法是控制请求速率例如每条请求之间间隔 200 到 300 毫秒并在收到限流响应时进行退避重试。批量导入时的建议不要并发请求先使用串行写入。单词量超过 100 个时拆成多个小批次每批之间暂停 30 到 60 秒。如果脚本逻辑允许把超时时间设置为 15 秒以上避免网络波动直接判失败。如果出现请求返回 429 或包含 rate limit 字样的错误说明写入速度过快。先暂停脚本等待一段时间后从失败列表继续而不是重新跑整批数据。5.2 用去重避免重复卡片重复执行同一个自动化任务很容易在 Notion 里产生同名词条的不同版本。一个简单的去重策略是在写入前先查询数据库里是否已存在相同单词。用 Notion 查询接口做去重检查import requests headers { Authorization: fBearer {NOTION_TOKEN}, Notion-Version: NOTION_VERSION, Content-Type: application/json, } def word_exists(word): body { filter: { property: 单词, title: { equals: word } } } resp requests.post( fhttps://api.notion.com/v1/databases/{DATABASE_ID}/query, headersheaders, jsonbody, timeout15 ) results resp.json().get(results, []) return len(results) 0写入前先调用word_exists(abandon)如果返回True可以选择跳过或更新已有记录。这种方法会多消耗查询请求所以在批次较大时可以先在本地用集合保存已处理单词减少重复请求。5.3 日志、重试与失败隔离任务的输出不能只给一行“完成”。建议让 Workbuddy 或脚本生成一个运行报告至少包含以下内容成功写入数量。失败写入数量。每个失败条目的单词、错误码和错误信息。本轮去重跳过的数量。失败条目的处理方式有三种跳过、重试、写入独立失败队列。对于单词卡片这类数据推荐先记录失败原因等整批跑完后统一重试失败队列避免单条网络问题导致整个流程反复重跑。6. 常见问题排查自动化流程的问题通常会集中在 API 鉴权、字段映射和数据处理三个方向。下面按现象给出排查顺序和处理建议。6.1 API 返回 401 或 403问题现象常见原因检查方式处理建议401 unauthorizedToken 复制不完整或已失效检查 Token 是否以secret_开头是否有多余空格重新复制 Token更新配置文件403 forbidden集成未连接到目标数据库回到数据库页面右上角“连接到集成”确认把集成添加到数据库后重试404 object not founddatabase_id 写错或跨工作区核对数据库 URL 中的 ID重新复制数据库 ID如果使用 curl 调试命令可以参考curl --request GET \ --url https://api.notion.com/v1/databases/{database_id} \ --header Authorization: Bearer {token} \ --header Notion-Version: 2022-06-28返回结果里如果能看到数据库属性说明鉴权链路正常。6.2 数据库字段类型与 JSON 结构不匹配Notion 对不同字段类型要求不同的 JSON 结构。下面整理了一张映射表排查时直接对照Notion 属性类型API 请求中的结构示例Title{title: [{text: {content: word}}]}Rich Text{rich_text: [{text: {content: 释义}}]}Select{select: {name: 新词}}Multi-select{multi_select: [{name: 标签A}]}Number{number: 12}Checkbox{checkbox: true}Date{date: {start: 2024-01-01}}如果报错信息中出现validation_error或body.max_property_keys_limit_reached几乎可以确定是字段类型或字段名不匹配。检查时先看数据库属性名是不是和 JSON 里的键完全一致再看属性类型是否对应正确的 JSON 结构。6.3 生成的卡片内容混乱如果卡片能够写入但音标、释义或例句不稳定说明任务指令里的规则不够具体。常见原因包括没有指定音标是英式还是美式。没有指定释义的详细程度。没有指定例句长度。没有要求生成结果必须包含固定字段。对策是在自定义指令中增加更明确的约束例如“音标使用美式 IPA 格式”“释义只保留一个最高频词义”“例句不超过 12 个单词适合初中级学习者”。6.4 导入速度过慢或超时问题现象常见原因解决方式单个请求超时网络环境不稳定增加 timeout并加入一次重试全批导入耗时过长每张卡都查询去重请求量大本地先去重再批量查询触发限流写入速度太快增加 sleep 间隔拆小批次6.5 多版本 Workbuddy 入口差异不同版本的 Workbuddy 在“自定义指令”和“skill”这两个位置上的叫法可能不同有的版本称为“技能”有的称为“插件”。遇到界面不一致时优先查对应版本的官方使用手册不要照搬别人的截图配置。如果你是通过本地部署方式使用还要确认服务端日志位置便于排查任务执行阶段是否报错。7. 长期可维护与再扩展的建议自动化流程跑通一次不算结束真正有价值的是能稳定复用。下面两个清单可以帮助你减少后续维护成本。7.1 运行前检查清单在每次批量导入前建议按顺序确认[ ] Workbuddy 能正常启动版本能支撑自定义指令或 skill 功能。[ ] Notion 集成的 Token 有效没有过期或被误删。[ ] 集成已连接到目标数据库。[ ] 数据库字段结构与任务指令里的字段映射一致。[ ] 输入 CSV 文件路径正确文件编码是 UTF-8。[ ] 上次导入产生的失败记录已处理避免重复数据累积。[ ] 脚本或任务中配置了请求间隔和超时时间。[ ] 日志输出目录可写能保存本次运行报告。这个清单在第一次搭建时就要建立后续每次运行只是逐项确认而不是重新推理。7.2 从单词卡片扩展到更多场景这套“AI 代理读取输入 - 生成结构化数据 - 调用 Notion API 写入”的流程并不只适用于单词卡片。改一下字段设计就能复用到其他场景书摘和读书笔记用 API 把高亮段落、感想、出处写入 Notion 数据库。法律案例或资讯案例库让 Workbuddy 从一段原文里提取案件名称、争议焦点、裁判观点等字段。产品需求沉淀从会议记录中提取需求主题、优先级、负责人和截止日期。个人模板库把常用资料整理成固定字段的表格方便后续通过 Notion 的视图和筛选功能查询。扩展时的核心仍在于字段设计。先在 Notion 里把属性类型定清楚再在 Workbuddy 的自定义指令里写明字段映射最后用一条最小请求验证写入链路。对于准备长期使用的项目建议把所有提示词模板、脚本代码和 CSV 样例纳入同一个代码仓库管理。这样即使团队成员换了电脑也能通过仓库和说明文档快速复现整套流程。更重要的是当 Notion API 版本或 Workbuddy 版本升级时你只需要在仓库中修改配置而不是重新搭建一次。自动化节省的时间应该花在更有价值的事情上把生成规则写得足够细致把异常处理做得足够健壮。等到某天你发现只需替换 CSV 文件、运行一次任务几十张单词卡片就能以统一格式出现在 Notion 里时这套链路才真正完成了它的使命。
Workbuddy+Notion API：一键自动化生成单词卡片并批量导入数据库
在英语学习、备考或做个人知识库时把生词整理成带音标、释义和例句的卡片是很多人的刚需。真正消耗精力的不是“背单词”本身而是维护卡片的过程查词、复制释义、切到 Notion、新建页面、选择数据库、填写字段。一个词至少重复五六步坚持两周就很难继续。Workbuddy 这类 AI 自动化工具正好可以把“查单词、整理卡片、写入 Notion 数据库”这条链路合并成一个自动化任务。用户只需要把单词列表准备好触发一次任务Workbuddy 就能批量生成规范的单词卡片并导入 Notion。这篇文章以“Workbuddy 一键自动化生成单词卡片导入 Notion”为目标会先讲清自动化链路里的关键概念再从环境准备、数据设计、任务配置、API 写入到故障排查给出可以复用的完整流程。读者不需要事先熟悉 AI Agent 或 Notion 开发接口按章节走完就能在自己的环境里跑通最小版本。1. 先看清这条自动化链路里的三个关键角色在动手配置之前先理解这条链路为什么能成立。整条流程由三个角色组成Workbuddy 负责执行Notion API 负责接收数据单词卡片的数据结构负责约定格式。任何一个环节理解不到位后面都会出现“任务看起来执行成功数据库里却没有卡片”或“卡片写进去但字段错乱”这类问题。1.1 Workbuddy 在流程里充当什么角色Workbuddy 是一款 AI 自动化代理工具它的核心能力是接受用户的自然语言任务描述并把任务拆解成一系列动作来执行。你可以把它理解成一个“有执行权限的助手”你告诉它要做什么、按什么规则做它调用自己的模型推理能力、已配置的插件、本机脚本或外部 HTTP 接口逐步完成任务。在单词卡片场景里Workbuddy 做的事情可以拆成四步读取单词输入列表。对每个单词生成音标、中英文释义和一个简单例句。把结果填充成符合既定规则的卡片数据。把数据写入提供的 Notion 数据库 API 接口。不同版本的 Workbuddy 在入口和命名上可能不同比如通过对话会话触发、通过任务画布编排或者通过命令行调用。文章里给出的流程是通用执行逻辑实际使用时以你安装版本的交互方式为准。1.2 Notion API 为什么是导入操作的唯一通道Notion 本身是一个界面产品所有页面都可以手动创建但手动创建无法支撑批量自动化。Notion API 提供了对工作区和数据库的编程访问能力开发者可以通过 REST 接口创建一个页面、查询数据库、更新页面属性。用官方 API 写入数据有几个特点数据以结构化属性写入字段名和字段类型必须和数据库定义一致。请求需要携带鉴权 TokenToken 归属某个集成Integration。集成必须被显式添加到目标数据库或页面否则没有读取和写入权限。这意味着并不是拿到 API Token 就能写入任意数据库。你需要先创建集成再把该集成的访问权限关联到自己的数据库。这个环节最容易看漏。1.3 单词卡片数据是从自由文本变成结构化字段的过程手动维护卡片时人可以接受“音标在这里、释义在这里”这种模糊描述。但 API 不会猜测它要求每条数据都对应数据库里的一个字段名和字段类型。在 Notion 数据库里一张“单词卡片”实际上是一行记录包含一个标题字段通常保存单词本身。若干文本字段保存音标、释义、例句。一个选择或状态字段保存熟练度比如“新词”“熟悉”。字段类型决定了 API 请求里的 JSON 格式。例如数据库里若把“音标”定义为富文本类型请求里就必须写成 rich_text 数组若把“熟练度”定义为 Select 类型请求里就要用 select 对象。如果类型不一致Notion 会直接拒绝这次写入。所以设计数据库结构本质上是在设计任务输出规范。先定好字段结构再让 Workbuddy 按这个结构生成数据流程才能稳定。2. 环境准备安装 Workbuddy 并接入 Notion API这一节完成三件事把 Workbuddy 装好并能正常发起任务创建 Notion 集成并拿到 Token在 Notion 里设计好目标数据库字段。建议按顺序做不要先在数据库中建一堆字段再回头改因为字段类型一旦在数据库里固定API 写入就必须严格匹配。2.1 安装 Workbuddy 并确认运行方式Workbuddy 的安装方式在不同平台上并不完全一致。以通用的桌面端或本地服务端方式为例一般会提供安装包或命令行安装入口。安装完成后先在终端或控制台里确认命令可用workbuddy --version如果命令不存在可能是因为安装目录没有加入 PATH或者当前安装版本只提供图形界面。可以先打开图形客户端在帮助或设置页面查看版本号。如果准备使用本地部署方式还需要确认运行环境满足要求常见项目包括操作系统版本、可用的内存和磁盘空间、是否允许本地监听端口。生产环境使用前建议重新读一遍对应版本的安装文档避免依赖某个临时下载入口。学习环境下只需要一个能运行 Workbuddy 的机器即可。开发或生产环境还要考虑任务日志、网络策略、Token 保管方式和回滚方案这些内容在后面的最佳实践里继续展开。2.2 创建 Notion 集成并获取 TokenNotion API 使用集成Integration作为访问主体。你在 Notion 后台创建一个集成后会得到一个以secret_开头的 TokenAPI 请求通过请求头里的 Authorization 字段携带这个 Token。创建完集成后必须把集成关联到目标数据库具体方式是在数据库页面右上角打开“更多”菜单选择“连接到”并找到刚创建的集成。缺少这一步即使 Token 正确API 也会返回 403。同时要找到数据库 ID。打开目标数据库页面后URL 里那一串 32 位字符就是 database_id。建议复制到本地配置文件中不要在多个地方手写避免因复制遗漏导致后续 404。下面用一个 Python 代码示例说明如何用官方客户端检查数据库是否能访问from notion_client import Client NOTION_TOKEN secret_你的集成Token DATABASE_ID 你的数据库ID notion Client(authNOTION_TOKEN) try: db notion.databases.retrieve(database_idDATABASE_ID) print(数据库名称, db[title][0][plain_text]) print(数据库字段, list(db[properties].keys())) except Exception as e: print(访问失败, e)这段代码只要能打印出数据库名称和字段列表就说明 Token、数据库 ID 和集成权限三个环节都是通的。任何一个环节不对都会在这一步暴露。2.3 先设计好 Notion 数据库字段避免后面反复改结构Notion 数据库的字段结构决定了 Workbuddy 生成数据的格式。下面是一张推荐的最小字段表字段名属性类型说明单词Title数据库必须有一个标题字段这里保存单词本身音标Rich Text保存英式或美式音标释义Rich Text保存中英文释义可包含词性例句Rich Text一个典型例句熟练度Select分为“新词”“熟悉”“已掌握”三档来源Multi-select可选记录单词来自哪份材料创建数据库可以通过 Notion 界面手动创建也可以调用 API 创建。需要说明的是手动创建时属性类型选错了很难事后调整所以建议按表格选好类型。如果希望通过代码创建可以参考下面的 Python 片段该代码会在一个现有页面内创建新的数据库from notion_client import Client notion Client(authsecret_你的集成Token) parent_page_id 目标页面的Page ID db notion.databases.create( parent{page_id: parent_page_id}, title[{type: text, text: {content: 单词卡库}}], properties{ 单词: {title: {}}, 音标: {rich_text: {}}, 释义: {rich_text: {}}, 例句: {rich_text: {}}, 熟练度: { select: { options: [ {name: 新词}, {name: 熟悉}, {name: 已掌握} ] } }, 来源: {multi_select: {options: []}}, }, ) print(db[id])创建完成后把打印出来的数据库 ID 记录下来后续所有写入请求都指向这个 ID。3. 设计可复用的单词卡片自动化流程环境准备好之后重点就从“手工操作”转移到“让 Workbuddy 按规则工作”。这里的核心不是一次性生成几张卡片而是设计一套每次都能稳定输出相同质量数据的任务规范。3.1 准备输入源CSV 或纯文本推荐使用 CSV 文件作为单词输入源方便批量维护也方便 Workbuddy 读取。最简单的方式是只保留一列单词由 Workbuddy 去补全音标、释义和例句word abandon abroad absorb academic according如果已经有带释义的材料也可以设计成多列word,meaning,note abandon,v. 放弃抛弃,考研高频词 abroad,adv. 在国外,注意与 aboard 区别这里要注意编码问题。如果 Workbuddy 读取 CSV 后出现中文乱码优先检查文件是否保存为 UTF-8 格式。不建议使用 Excel 默认的本地编码因为不同操作系统对非 UTF-8 文件的支持不一致。从学习环境进入生产环境时输入文件应当纳入版本管理或统一目录管理避免每次都在任务描述里重新描述路径。3.2 用自定义指令约束 Workbuddy 的处理步骤Workbuddy 支持通过自定义指令或 skill 来固定任务行为。可以理解成把一段稳定的提示词保存成模板每次任务直接复用而不是每次临时重复输入。下面是一个可参考的 Markdown 指令模板建议先复制到本地再根据自己版本做调整任务名称: 批量生成单词卡片并导入Notion 输入: - 读取 CSV 文件路径为 data/word_list.csv - 每次任务运行前先确认文件存在且包含 word 列 处理规则: 1. 对每个单词生成美式音标。 2. 给出一个常见中文释义和词性标记。 3. 生成一个简单、贴近日常用法的英文例句。 4. 将每条结果整理成 Notion API 的 properties 结构。 5. 调用 Notion API 创建页面目标数据库 ID 由配置传入。 字段映射: - 单词 - title - 音标 - rich_text - 释义 - rich_text - 例句 - rich_text - 熟练度 - select默认新词 输出要求: - 每个单词对应一个 Notion 页面。 - 某个单词失败时记录失败原因继续处理下一个词。 - 任务结束后输出成功数量和失败数量。这段模板里的关键点有三个第一是规定输入来源第二是规定字段映射第三是规定失败处理方式。实际项目中建议把数据库 ID、文件路径和 Token 不要直接写死在指令里而是通过环境变量或配置文件传入。很多新手一开始只写“生成卡片并导入 Notion”结果每轮生成卡片的字段顺序不一致或者遇到失败词条直接中断整批任务。模板中明确“失败继续处理”和“输出统计信息”就是为了规避这个问题。3.3 生成符合 Notion API 要求的卡片数据当 Workbuddy 完成查词与整理后输出的数据应该尽量标准化。下面是一个单词 card 的对象示例{ properties: { 单词: { title: [ {text: {content: abandon}} ] }, 音标: { rich_text: [ {text: {content: /əˈbændən/}} ] }, 释义: { rich_text: [ {text: {content: v. 放弃抛弃}} ] }, 例句: { rich_text: [ {text: {content: He had to abandon the car.}} ] }, 熟练度: { select: {name: 新词} } } }需要特别强调Card 数据结构里最外层的字段名必须和 Notion 数据库的属性名完全一致包括大小写和空格。单词字段在数据库里是 Title 类型所以 JSON 里用title数组包住音标、释义、例句是富文本类型所以用rich_text数组熟练度是 Select 类型所以用select对象。如果你把单词误写成word或者把音标写成字符串而不是数组Notion API 会返回 400 错误。这些细节是自动化流程里最常见的失败来源。4. 执行导入调用 Notion API 写入数据库当 Workbuddy 生成多张卡片数据后还需要真正把数据写入 Notion。这一步可以直接交给 Workbuddy 调用 HTTP 接口完成也可以用本地脚本在工作流里执行。下面分别说明原理和最小实现。4.1 最小写入请求的代码示例Notion API 创建页面的接口是请求方法POST请求地址https://api.notion.com/v1/pages请求头Authorization、Notion-Version、Content-Type用 Python 的requests库写一个最小例子import requests NOTION_TOKEN secret_你的集成Token DATABASE_ID 你的数据库ID NOTION_VERSION 2022-06-28 headers { Authorization: fBearer {NOTION_TOKEN}, Notion-Version: NOTION_VERSION, Content-Type: application/json, } payload { parent: {database_id: DATABASE_ID}, properties: { 单词: { title: [{text: {content: abandon}}] }, 音标: { rich_text: [{text: {content: /əˈbændən/}}] }, 释义: { rich_text: [{text: {content: v. 放弃抛弃}}] }, 例句: { rich_text: [{text: {content: He had to abandon the car.}}] }, 熟练度: { select: {name: 新词} } } } resp requests.post( https://api.notion.com/v1/pages, headersheaders, jsonpayload, timeout15 ) print(resp.status_code) print(resp.json())正常响应返回200或200 OK并且resp.json()里会包含新创建的页面 ID。如果返回400、401、403或404说明数据结构、Token 权限、数据库 ID 或字段映射存在问题排查方式见第 6 节。4.2 在 Workbuddy 中组织批量导入单张卡片写入只适合验证链路是否畅通。真实场景下单词通常有几十个甚至上百个。批量处理时建议让 Workbuddy 或本地脚本按循环逐条写入并在每两条请求之间留出间隔避免短时间内请求量过大。下面是一个适用于批量的 Python 骨架可以直接放入任务流程中import time import requests NOTION_TOKEN secret_你的集成Token DATABASE_ID 你的数据库ID NOTION_VERSION 2022-06-28 headers { Authorization: fBearer {NOTION_TOKEN}, Notion-Version: NOTION_VERSION, Content-Type: application/json, } cards [ # 这里放 Workbuddy 生成的卡片数据列表 ] success_count 0 fail_list [] for card in cards: payload { parent: {database_id: DATABASE_ID}, properties: card[properties], } try: resp requests.post( https://api.notion.com/v1/pages, headersheaders, jsonpayload, timeout15 ) if resp.status_code in (200, 201): success_count 1 else: fail_list.append({ card: card, status: resp.status_code, message: resp.text }) except Exception as e: fail_list.append({ card: card, error: str(e) }) time.sleep(0.3) print(f成功 {success_count} 条失败 {len(fail_list)} 条)这里有几个有用实践每张卡片都单独捕获异常避免一条失败拖停整个批次。将失败信息记录到列表中任务结束后统一查看。请求之间增加time.sleep给 Notion API 留出处理余量。如果你用的是 Workbuddy 内置的 HTTP 调用能力而不是本地 Python逻辑也一样循环执行 HTTP 请求记录响应状态并按顺序处理。4.3 如何确认导入成功导入完成后不要只在 Workbuddy 里看到“成功”就结束。最稳妥的验证方式是查询数据库确认实际写入的记录数量。用 Notion API 查询数据库的接口是import requests headers { Authorization: fBearer {NOTION_TOKEN}, Notion-Version: NOTION_VERSION, Content-Type: application/json, } query { page_size: 10 } resp requests.post( fhttps://api.notion.com/v1/databases/{DATABASE_ID}/query, headersheaders, jsonquery, timeout15 ) results resp.json().get(results, []) for page in results: title_prop page[properties].get(单词, {}) if title_prop.get(type) title: titles title_prop.get(title, []) if titles: print(titles[0][text][content])如果能打印出刚导入的单词列表说明整条链路真实闭环。如果打印为空但 Workbuddy 提示成功需要回到权限或数据库 ID 环节检查。5. 稳定运行的边界条件与幂等设计一键自动化听起来像是“点击一次就万事大吉”但真正稳定运行需要处理三个边界条件请求频率、重复导入和部分失败。这三个问题如果不处理第一次跑通很简单长期使用却会不断出现脏数据。5.1 控制批次大小避免触发频率限制Notion API 对同一个集成的请求频率有一定限制具体阈值会随账户状态和官方政策变化。稳妥做法是控制请求速率例如每条请求之间间隔 200 到 300 毫秒并在收到限流响应时进行退避重试。批量导入时的建议不要并发请求先使用串行写入。单词量超过 100 个时拆成多个小批次每批之间暂停 30 到 60 秒。如果脚本逻辑允许把超时时间设置为 15 秒以上避免网络波动直接判失败。如果出现请求返回 429 或包含 rate limit 字样的错误说明写入速度过快。先暂停脚本等待一段时间后从失败列表继续而不是重新跑整批数据。5.2 用去重避免重复卡片重复执行同一个自动化任务很容易在 Notion 里产生同名词条的不同版本。一个简单的去重策略是在写入前先查询数据库里是否已存在相同单词。用 Notion 查询接口做去重检查import requests headers { Authorization: fBearer {NOTION_TOKEN}, Notion-Version: NOTION_VERSION, Content-Type: application/json, } def word_exists(word): body { filter: { property: 单词, title: { equals: word } } } resp requests.post( fhttps://api.notion.com/v1/databases/{DATABASE_ID}/query, headersheaders, jsonbody, timeout15 ) results resp.json().get(results, []) return len(results) 0写入前先调用word_exists(abandon)如果返回True可以选择跳过或更新已有记录。这种方法会多消耗查询请求所以在批次较大时可以先在本地用集合保存已处理单词减少重复请求。5.3 日志、重试与失败隔离任务的输出不能只给一行“完成”。建议让 Workbuddy 或脚本生成一个运行报告至少包含以下内容成功写入数量。失败写入数量。每个失败条目的单词、错误码和错误信息。本轮去重跳过的数量。失败条目的处理方式有三种跳过、重试、写入独立失败队列。对于单词卡片这类数据推荐先记录失败原因等整批跑完后统一重试失败队列避免单条网络问题导致整个流程反复重跑。6. 常见问题排查自动化流程的问题通常会集中在 API 鉴权、字段映射和数据处理三个方向。下面按现象给出排查顺序和处理建议。6.1 API 返回 401 或 403问题现象常见原因检查方式处理建议401 unauthorizedToken 复制不完整或已失效检查 Token 是否以secret_开头是否有多余空格重新复制 Token更新配置文件403 forbidden集成未连接到目标数据库回到数据库页面右上角“连接到集成”确认把集成添加到数据库后重试404 object not founddatabase_id 写错或跨工作区核对数据库 URL 中的 ID重新复制数据库 ID如果使用 curl 调试命令可以参考curl --request GET \ --url https://api.notion.com/v1/databases/{database_id} \ --header Authorization: Bearer {token} \ --header Notion-Version: 2022-06-28返回结果里如果能看到数据库属性说明鉴权链路正常。6.2 数据库字段类型与 JSON 结构不匹配Notion 对不同字段类型要求不同的 JSON 结构。下面整理了一张映射表排查时直接对照Notion 属性类型API 请求中的结构示例Title{title: [{text: {content: word}}]}Rich Text{rich_text: [{text: {content: 释义}}]}Select{select: {name: 新词}}Multi-select{multi_select: [{name: 标签A}]}Number{number: 12}Checkbox{checkbox: true}Date{date: {start: 2024-01-01}}如果报错信息中出现validation_error或body.max_property_keys_limit_reached几乎可以确定是字段类型或字段名不匹配。检查时先看数据库属性名是不是和 JSON 里的键完全一致再看属性类型是否对应正确的 JSON 结构。6.3 生成的卡片内容混乱如果卡片能够写入但音标、释义或例句不稳定说明任务指令里的规则不够具体。常见原因包括没有指定音标是英式还是美式。没有指定释义的详细程度。没有指定例句长度。没有要求生成结果必须包含固定字段。对策是在自定义指令中增加更明确的约束例如“音标使用美式 IPA 格式”“释义只保留一个最高频词义”“例句不超过 12 个单词适合初中级学习者”。6.4 导入速度过慢或超时问题现象常见原因解决方式单个请求超时网络环境不稳定增加 timeout并加入一次重试全批导入耗时过长每张卡都查询去重请求量大本地先去重再批量查询触发限流写入速度太快增加 sleep 间隔拆小批次6.5 多版本 Workbuddy 入口差异不同版本的 Workbuddy 在“自定义指令”和“skill”这两个位置上的叫法可能不同有的版本称为“技能”有的称为“插件”。遇到界面不一致时优先查对应版本的官方使用手册不要照搬别人的截图配置。如果你是通过本地部署方式使用还要确认服务端日志位置便于排查任务执行阶段是否报错。7. 长期可维护与再扩展的建议自动化流程跑通一次不算结束真正有价值的是能稳定复用。下面两个清单可以帮助你减少后续维护成本。7.1 运行前检查清单在每次批量导入前建议按顺序确认[ ] Workbuddy 能正常启动版本能支撑自定义指令或 skill 功能。[ ] Notion 集成的 Token 有效没有过期或被误删。[ ] 集成已连接到目标数据库。[ ] 数据库字段结构与任务指令里的字段映射一致。[ ] 输入 CSV 文件路径正确文件编码是 UTF-8。[ ] 上次导入产生的失败记录已处理避免重复数据累积。[ ] 脚本或任务中配置了请求间隔和超时时间。[ ] 日志输出目录可写能保存本次运行报告。这个清单在第一次搭建时就要建立后续每次运行只是逐项确认而不是重新推理。7.2 从单词卡片扩展到更多场景这套“AI 代理读取输入 - 生成结构化数据 - 调用 Notion API 写入”的流程并不只适用于单词卡片。改一下字段设计就能复用到其他场景书摘和读书笔记用 API 把高亮段落、感想、出处写入 Notion 数据库。法律案例或资讯案例库让 Workbuddy 从一段原文里提取案件名称、争议焦点、裁判观点等字段。产品需求沉淀从会议记录中提取需求主题、优先级、负责人和截止日期。个人模板库把常用资料整理成固定字段的表格方便后续通过 Notion 的视图和筛选功能查询。扩展时的核心仍在于字段设计。先在 Notion 里把属性类型定清楚再在 Workbuddy 的自定义指令里写明字段映射最后用一条最小请求验证写入链路。对于准备长期使用的项目建议把所有提示词模板、脚本代码和 CSV 样例纳入同一个代码仓库管理。这样即使团队成员换了电脑也能通过仓库和说明文档快速复现整套流程。更重要的是当 Notion API 版本或 Workbuddy 版本升级时你只需要在仓库中修改配置而不是重新搭建一次。自动化节省的时间应该花在更有价值的事情上把生成规则写得足够细致把异常处理做得足够健壮。等到某天你发现只需替换 CSV 文件、运行一次任务几十张单词卡片就能以统一格式出现在 Notion 里时这套链路才真正完成了它的使命。
