核心用法
Notion Sync 是一套基于 Node.js 的命令行工具集，通过 Notion 官方 API 实现本地 Markdown 文件与 Notion 工作空间的双向同步。核心功能包括：
1. 双向内容同步：md-to-notion.js 将本地 Markdown 推送为 Notion 页面（支持标题、列表、代码块等格式）；notion-to-md.js 将 Notion 页面导出为 Markdown 文件。
2. 数据库管理：支持查询数据库（query-database.js）、添加页面到数据库（add-to-database.js）、更新页面属性（update-page-properties.js），以及查看数据库结构（get-database-schema.js）。
3. 变更监控：watch-notion.js 可周期性检测 Notion 页面是否被编辑，输出 JSON 格式的状态报告，支持与 cron/CI 流水线集成实现自动化监控。
4. 搜索与归档：支持按标题/内容搜索工作空间（search-notion.js）和归档页面（delete-notion-page.js）。
显著优点
- 零外部依赖：所有脚本仅使用 Node.js 内置模块（https、fs），无需
npm install，部署极轻量。 - 批量处理与自动限流：支持 100 块/批次的批量上传，内置 350ms 延迟自动处理 Notion API 的速率限制（~3 req/s）。
- Token 安全升级：v2.0 强制通过
--token参数传递密钥，避免环境变量残留风险。 - 灵活的过滤与排序：数据库查询支持完整的 Notion 过滤语法（select/multi_select/date/checkbox/number 等）。
潜在缺点与局限
- 属性更新限制：创建数据库页面后，Type、Tags、Status 等属性需手动在 Notion UI 中设置，API 对行内数据库的属性更新不够稳定。
- 大文件同步慢：超过 1000 个 block 的 Markdown 文件因限流机制可能需要数分钟完成同步。
- 格式转换边界：复杂表格、三级以上嵌套列表可能转换不完美。
- 监控状态本地化：变更监控状态存储于本地 JSON 文件（
memory/notion-watch-state.json），多机部署需自行同步状态。
适合人群
- 使用 Notion 进行研究追踪、知识库管理的学术/咨询团队
- 需要本地 Markdown 编辑 + Notion 协作审阅混合工作流的创作者
- 希望通过 CI/CD 或定时任务自动化同步内容的开发者/DevOps 团队
- 追求轻量部署、无依赖环境的极简主义者
常规风险
- Token 泄露风险：需妥善保管
ntn_开头的 Integration Token，避免硬编码入版本控制；v2.0 虽改为参数传递，但仍需防止 shell history 泄露。 - 权限管理：需手动将页面/数据库共享给 Integration，权限配置不当可能导致同步失败或数据访问不完整。
- API 限流导致任务失败：高频自动化监控可能触发 Notion API 限流，建议监控频率不低于 5 分钟间隔。
- 非破坏性归档：
delete-notion-page.js仅设置archived: true，非永久删除，敏感数据需额外清理策略。