1. 从一句提示词到能跑的 Notion 同步程序很多人第一次用 claude code 写 Python 项目卡住的地方不是代码本身而是「提示词怎么给」和「config.json 里 API 通道怎么配」。我这次要做的是一个把 Notion 工作空间单向同步到本地硬盘的 Python 程序支持增量同步、带 Web 界面、能登录改密码、能看业务日志和系统日志、监听端口写在 config.json 里。听起来功能不少但拆开看就是「提示词驱动开发 统一 Key 接入」两件事。先说清楚这个程序是什么、能做什么、适合谁。它是一个本地运行的 Python 服务启动后监听一个端口浏览器打开就能登录登录后可以触发同步、查看同步日志和运行日志。同步逻辑是单向的从 Notion 拉到本地目录第二次运行只拉变化的部分也就是增量同步。适合谁适合手里有一堆 Notion 页面、想定期备份到本地、又不想手动导出的人也适合想练手 claude code 提示词工程、顺便把 API 通道配置跑通的开发者。核心检索词就三个claude code 提示词、Notion 同步程序、config.json 配置。这三个词贯穿全文。我会先讲提示词怎么组织再讲 config.json 骨架长什么样然后给出可复制的配置片段最后用真实请求验证同步是否跑通并把常见报错一个个拆开。提示词这块我的经验是别一次性把需求全丢进去。claude code 在 plan 模式下更擅长「先规划再动手」所以第一步是让它输出模块划分而不是直接写代码。你可以这样给第一段提示词我要用 Python 写一个 Notion 单向同步程序需求如下 1. 从 Notion 工作空间拉取页面保存到本地目录 2. 支持增量同步第二次运行只拉变化内容 3. 带 Web 界面可登录默认 admin/admin123可改密码 4. 配置界面能填 Notion 凭据保存到 config.json 5. 显示业务日志和系统日志 6. 监听端口写在 config.json可手动改 请先输出模块划分和文件结构不要写完整代码。这段提示词的关键是最后一句「先输出模块划分」。如果不加这句claude code 容易一口气生成几百行改起来反而麻烦。等它给出结构你再逐模块让它补代码比如「实现 config.json 的读写模块」「实现增量同步的比对逻辑」。这样每一步都可验证出错也好定位。模块划分大概会是这样config.py管配置读写notion_client.py管 API 调用sync.py管增量比对web.py管界面和登录logger.py管双日志。文件结构清楚了后面填代码就是体力活。这里有个坑Notion 官方 API 需要 integration token而不是邮箱密码。excerpt 里提到「配置 notion 的 email 和密码」实际落地时你会发现官方通道走的是 token。所以 config.json 里我保留了 email 字段做展示但真正用于请求的是 token 字段。这一点在提示词里要提前说明否则生成的代码会去调一个不存在的登录接口。2. TaoToken 前置统一 Key 与 config.json 通道设计在写同步逻辑之前先把 API 通道定下来。程序里所有需要调用模型能力的地方比如让模型帮你总结页面内容、生成同步摘要都走同一个入口这样 Key 只需要配一次。我用的是 TaoToken 的统一 Key 方案官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 入口是 https://taotoken.net/api 。注意 API 地址后面不加任何查询参数保持干净。为什么要在 config.json 里单独设计一个 API 通道段因为同步程序不只是「拉数据」它还要在拉取后做内容处理。如果每次处理都硬编码一个地址和 Key换环境就得改代码。把通道信息抽到 config.json改配置不动代码这是基本工程习惯。config.json 的通道段我设计成三个字段base_url、api_key、model。这三个就是常说的「三件套」缺一不可。base_url 填 https://taotoken.net/api api_key 填你在控制台生成的 Keymodel 填你要用的模型 ID。这里要提醒一句model ID 必须和你账号里可用的模型一致填错会直接报模型不存在。获取 Key 的路径是先打开 https://taotoken.net/api-keys 登录后创建 Key复制出来。这个 Key 只显示一次建议直接粘进 config.json别放聊天记录里。如果你还没决定用哪个模型可以先去 https://taotoken.net/models 看看可用列表或者在 https://taotoken.net/chat 里试一次对话确认通道通不通。这里有个容易混淆的点TaoToken 是统一接入层不是让你绕过什么。它的作用是把你对多个模型通道的调用收敛到一个 Key、一个 base_url 上。对同步程序来说好处是配置简单、切换模型只改一个字段。我在提示词里会明确告诉 claude code「所有模型调用统一走 config.json 里的 api 段不要硬编码地址和 Key。」这样生成的代码天然就是可配置的。如果你打算长期跑这个同步程序甚至后面接 Agent 做自动整理可以考虑 Coding Plan 这类长期方案入口在 https://taotoken.net/coding-plan 。它的意义是把调用额度前置规划好避免程序跑一半因为额度问题中断。同步程序如果是定时任务这点尤其重要。配置段设计好之后下一步就是把它写进 config.json 骨架并让 Python 代码能正确读取。这里我不建议用环境变量兜底因为需求里明确说「配置保存在 config.json」那就以文件为准环境变量只做覆盖用。读取逻辑要处理文件不存在的情况首次启动时如果 config.json 不存在程序应该生成一份默认配置而不是直接崩溃。这个默认配置里api 段的 base_url 预填 https://taotoken.net/api api_key 留空model 留一个占位值提示用户去填。3. 可复制 config.json 骨架与 settings 片段这一节直接给可复制的内容。config.json 放在项目根目录和main.py同级。骨架如下{ server: { host: 0.0.0.0, port: 8080, secret_key: change-this-to-a-random-string }, auth: { username: admin, password: admin123 }, notion: { email: youexample.com, token: ntn_xxxxxxxxxxxxxxxx, root_page_id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, local_dir: ./backup }, api: { base_url: https://taotoken.net/api, api_key: sk-xxxxxxxxxxxxxxxx, model: your-model-id }, sync: { interval_minutes: 30, incremental: true }, log: { business_log: ./logs/business.log, system_log: ./logs/system.log, level: INFO } }几个字段说明一下。server.port就是监听端口改完重启生效不需要动 Web 界面。auth段是登录凭据默认 admin/admin123程序里要提供改密码接口改完写回这个文件。notion.token是真正的请求凭据email只做展示。notion.root_page_id是你要同步的根页面 ID从 Notion 页面 URL 里取最后一段。api段就是前面说的三件套base_url 固定 https://taotoken.net/api api_key 换成你自己的model 换成可用模型 ID。如果你用的是带 settings 的框架比如某些 Python Web 框架的配置文件可以写成 TOML[server] host 0.0.0.0 port 8080 [api] base_url https://taotoken.net/api api_key sk-xxxxxxxxxxxxxxxx model your-model-id [notion] token ntn_xxxxxxxxxxxxxxxx local_dir ./backupTOML 和 JSON 二选一关键是字段名和层级保持一致这样代码里读取路径不用改。我实测下来JSON 更适合让 claude code 生成因为它对 JSON 结构的理解更稳不容易漏括号。配置写好后Python 读取代码大概长这样import json from pathlib import Path CONFIG_PATH Path(config.json) def load_config(): if not CONFIG_PATH.exists(): raise FileNotFoundError(config.json 不存在请先创建) with CONFIG_PATH.open(r, encodingutf-8) as f: cfg json.load(f) api cfg.get(api, {}) if not api.get(api_key): raise ValueError(api.api_key 未配置) if not api.get(base_url): raise ValueError(api.base_url 未配置) return cfg这段代码做了两件事文件不存在时报明确错误api_key 或 base_url 为空时提前拦截。别小看这两个检查后面排错时能省很多时间。如果你在提示词里让 claude code 生成读取逻辑记得加上「对 api 段做非空校验」这一句。还有一个细节secret_key用于 Web 登录的会话签名默认值必须改。程序首次启动时可以检测它是否还是默认值如果是就打印警告。这个逻辑也写进提示词里让 claude code 一并生成。4. 验证请求从登录到增量同步跑通配置就绪后验证分三步先验证 API 通道再验证 Notion 拉取最后验证增量同步。第一步验证 API 通道。写一个最小脚本用 config.json 里的 api 段发一次请求import json import requests cfg json.load(open(config.json, encodingutf-8)) api cfg[api] resp requests.post( f{api[base_url]}/v1/chat/completions, headers{ Authorization: fBearer {api[api_key]}, Content-Type: application/json }, json{ model: api[model], messages: [{role: user, content: ping}] }, timeout30 ) print(resp.status_code) print(resp.text[:500])如果返回 200 并且 body 里有 choices 字段说明通道通了。如果返回 401说明 Key 不对如果返回 404多半是 base_url 写错检查是不是多写了斜杠或路径。这一步过了再往下走。第二步验证 Notion 拉取。用 notion.token 调一次查询接口确认能拿到页面列表import requests cfg json.load(open(config.json, encodingutf-8)) notion cfg[notion] resp requests.post( https://api.notion.com/v1/search, headers{ Authorization: fBearer {notion[token]}, Notion-Version: 2022-06-28, Content-Type: application/json }, json{page_size: 5}, timeout30 ) print(resp.status_code) print(len(resp.json().get(results, [])))能打印出结果数量说明 token 和权限没问题。注意 Notion integration 必须被显式授权到目标页面否则返回空列表。这一步的坑我在下一节细说。第三步验证增量同步。启动 Web 服务浏览器打开http://localhost:8080用 admin/admin123 登录点「开始同步」。第一次会全量拉取日志里能看到每个页面的处理记录。等第一次跑完手动改一个 Notion 页面的标题再点一次同步观察日志里是否只处理了那一个页面。如果只处理了变化页面增量逻辑就对了。增量比对的核心是记录每个页面的last_edited_time。本地维护一个sync_state.json结构如下{ pages: { page-id-1: {last_edited_time: 2024-01-01T00:00:00.000Z, local_path: ./backup/page-1.md}, page-id-2: {last_edited_time: 2024-01-02T00:00:00.000Z, local_path: ./backup/page-2.md} } }每次同步时先拉 Notion 端的last_edited_time和本地记录比对不一致才重新拉取内容并覆盖本地文件。这个逻辑不复杂但提示词里要写清楚「用 last_edited_time 做增量判断状态存 sync_state.json」否则 claude code 可能用文件修改时间做比对那就不准了。验证通过后你可以把同步设成定时任务sync.interval_minutes控制间隔。日志分两个文件业务日志记「哪个页面同步成功/失败」系统日志记「程序启动、异常堆栈、请求耗时」。两个日志分开排错时一眼能看出是业务问题还是程序问题。5. 常见报错排查401、local proxy failed、reading choices这一节按真实报错来。第一个401 Unauthorized。出现在 API 请求时说明 api_key 无效或没带上。检查三处config.json 里 api_key 是否为空、请求头是否是Bearer加 Key、Key 是否被复制时带了空格。我踩过的坑是 Key 末尾多了个换行肉眼看不出来用repr()打印一下就能发现。第二个local proxy failed。这个报错通常出现在请求发不出去的时候本质是网络层没通。先确认 base_url 是不是 https://taotoken.net/api 别写成别的路径。再确认本机能不能正常访问外网。如果程序跑在容器里检查容器网络配置。这个报错和 Key 无关别去反复改 Key。第三个reading choices 报错完整信息类似KeyError: choices或Cannot read property choices of undefined。这说明请求返回了但返回体里没有 choices 字段。常见原因有两个一是 model ID 填错服务端返回了错误信息而不是正常响应二是请求体格式不对比如 messages 字段拼错。排查方法把resp.text完整打印出来看服务端到底返回了什么。如果是模型不存在换一个可用 model ID如果是参数错误对照文档改请求体。第四个OAuth 相关报错。如果你在配置 Notion 时看到 OAuth 字样说明你走的是 OAuth 授权流程而不是 integration token。两条路都行但配置字段不同。走 token 的话config.json 里填notion.token走 OAuth 的话需要额外的 client_id 和 client_secret。我建议先用 token简单直接。如果你确实要用 OAuth记得把回调地址配成http://localhost:8080/callback和 server.port 保持一致。第五个同步后本地文件为空。这通常不是报错而是权限问题。Notion integration 创建后必须手动把目标页面「分享」给它否则 search 接口返回空列表程序以为没有页面可同步。检查方法在 Notion 页面右上角点分享看 integration 是否在列表里。不在就加上。第六个改密码后登录失败。改密码接口写回 config.json 时如果没做原子写入文件可能被截断。建议先写临时文件再替换import os, json, tempfile def save_config(cfg, pathconfig.json): fd, tmp tempfile.mkstemp(dir.) with os.fdopen(fd, w, encodingutf-8) as f: json.dump(cfg, f, ensure_asciiFalse, indent2) os.replace(tmp, path)这样即使写入过程中断电原文件也不会坏。这个细节写进提示词让 claude code 生成安全的写回逻辑。排错时如果拿不准是通道问题还是代码问题可以先去 https://taotoken.net/chat 手动发一条消息确认通道本身可用。通道可用而程序报错那就是代码或配置字段的问题范围就缩小了。接入相关的文档在 https://taotoken.net/doc 字段含义和请求格式都能查到。6. 把提示词、配置、验证串成一条流水线到这里整个流程其实是一条流水线提示词驱动 claude code 生成模块 → config.json 承载所有可变配置 → 三件套base_url、api_key、model统一走 TaoToken → 验证请求分三步走 → 报错按类型定位。每一步都可单独验证不用等全部写完才跑。如果你要长期维护这个同步程序建议把 config.json 纳入版本管理时排除敏感字段或者用config.example.json做模板真实文件加进.gitignore。api_key 和 notion.token 都不要提交。程序启动时读取真实文件模板只做参考。另外增量同步的状态文件sync_state.json也要注意如果本地目录被清空但状态文件还在程序会以为页面已同步而跳过导致本地没有文件。解决办法是启动时校验状态文件里记录的 local_path 是否存在不存在就强制重新拉取。这个校验逻辑值得加进提示词。最后给一个实用技巧把同步程序做成命令行可触发比如python main.py --sync-once这样你可以先用命令行验证逻辑再开 Web 界面。Web 界面只是壳核心逻辑在命令行能跑通排错会快很多。提示词里加一句「提供 --sync-once 参数执行一次同步后退出」claude code 会帮你把入口拆干净。整套跑下来你会发现 claude code 提示词的关键不是写得多长而是每一步都给明确的验收标准先要结构再要模块再要校验最后要验证命令。config.json 的关键不是字段多而是把通道信息收敛成三件套改配置不动代码。这两点做到Notion 同步程序就能稳定跑起来。