核心用法
notion-sync 是一套基于 Notion API 的双向同步工具集，专为协作编辑、研究追踪和项目管理场景设计。核心功能包括：
双向内容同步
- Markdown → Notion：支持 H1-H3 标题、粗斜体、链接、列表、代码块等完整格式，自动分批次上传（100 blocks/次，350ms 延迟规避限流）
- Notion → Markdown：将页面内容完整导出为本地 Markdown 文件
数据库管理
- 高级查询：支持 select/multi_select、date、checkbox、number 等多类型属性过滤与排序
- 属性更新：可程序化修改页面状态、标签、日期等元数据
- 数据库注入：将 Markdown 文档直接创建为数据库条目
变更监控
watch-notion.js实时监控页面编辑时间戳，维护本地状态文件，输出结构化 JSON 便于接入自动化通知系统
显著优点
- 零依赖：纯 Node.js 内置模块（https/fs），无需 npm install，部署极轻量
- MIT 开源：代码完全透明，可自由审计与二次开发
- 自动化友好：所有脚本输出结构化 JSON，完美契合 CI/CD、Cron 定时任务
- 协作闭环：本地编辑 → 推送 Notion → 他人协作 → 监控变更 → 拉回本地，形成完整工作流
局限性与风险
- API 限制：Notion 限流约 3 req/s，超大文档（>1000 blocks）同步可能耗时数分钟
- 格式损失：复杂表格、三层以上嵌套列表转换可能不完美
- 属性限制：数据库附加属性（Type/Tags/Status）创建后需手动在 Notion UI 补充，API 对 inline database 的属性更新不稳定
- 权限依赖：必须显式分享页面给 Integration，否则返回 "Could not find page"
适用人群
- 技术写作者/开发者：需要本地 Markdown 编辑与团队 Notion 协作的混合工作流
- 研究人员：追踪研究产出、自动化归档至结构化数据库
- 项目经理：通过 API 批量更新任务状态、监控项目页面变更
安全考量
- 仅依赖
NOTION_API_KEY单一环境变量，无敏感信息硬编码 - 无外部网络请求（除 Notion API 外）
- 归档操作软删除（
archived: true），非永久销毁，误操作可逆