核心用法
notion-sync 是一套基于 Node.js 的 Notion 工作流工具集，提供 Markdown 与 Notion 的双向同步能力，支持页面搜索、数据库查询、属性更新、变更监控等完整生命周期管理。
主要功能模块：
- 双向同步：
md-to-notion.js将本地 Markdown 推送至 Notion（支持 H1-H3、加粗、链接、代码块等格式），notion-to-md.js反向拉取为 Markdown - 数据库操作：
query-database.js支持复杂过滤与排序，add-to-database.js将 Markdown 添加为数据库条目，update-page-properties.js批量更新页面属性 - 变更监控：
watch-notion.js持续追踪页面编辑时间戳，输出 JSON 状态供自动化流程集成（如 cron 定时检查） - 搜索与发现：
search-notion.js按标题/内容搜索页面和数据库
安全设计亮点：v2.0 强制移除命令行明文 --token，改用 --token-file、--token-stdin 或 NOTION_API_KEY 环境变量，避免凭证泄露于进程列表；默认自动读取 ~/.notion-token（权限建议 600）。
显著优点
1. 零依赖：纯 Node.js 内置模块（https/fs），无需 npm install，部署极轻量
2. 批量与限流：自动分批上传（100 blocks/请求）、350ms 间隔，适配 Notion API 速率限制
3. 状态持久化：监控状态保存于 JSON，支持自定义路径与 ~ 展开
4. 工作流友好：输出结构化 JSON，易于接入 CI/CD、通知系统或脚本流水线
潜在局限
- 属性限制：数据库自定义属性（Type/Tags/Status）需手动在 Notion UI 补充，API 对 inline database 支持不稳定
- 格式边界：复杂表格、三层以上嵌套列表转换可能不完美
- 大文件延迟：>1000 blocks 文件因限流需数分钟完成同步
- 仅支持 Internal Integration：需手动分享页面/数据库给集成，不支持 OAuth 用户授权
适合人群
- 技术写作者、研究员：本地 Markdown 编辑 + Notion 发布/归档
- 产品经理/项目经理：数据库驱动的任务追踪、研究素材库
- 开发团队：文档即代码（Docs as Code）工作流，结合 Git 与 Notion
- 自动化爱好者：通过 cron/GitHub Actions 实现定时同步与变更提醒
常规风险
- Token 泄露：若误用旧版
--token或权限设置不当的 token 文件，可能导致工作区数据暴露 - 归档误操作：
delete-notion-page.js实为 archive 而非永久删除，但恢复仍需手动操作 - API 变更：Notion API 版本迭代可能导致脚本兼容性问题（当前基于 2022-06-28 版 API）