核心功能
Notion Sync 是一套基于 Node.js 的命令行工具集，实现 Markdown 文件与 Notion 工作空间的双向同步。核心能力包括：
- 双向内容同步：将本地 Markdown 推送为 Notion 页面（保留标题、列表、代码块等格式），也可将 Notion 内容导出为 Markdown
- 数据库操作：查询数据库、更新页面属性（状态、标签、日期等）、添加 Markdown 为新数据库条目
- 变更监控：持续跟踪 Notion 页面编辑时间戳，检测与本地文件的差异，支持自动化工作流集成
显著优点
- 零依赖：仅使用 Node.js 内置模块（https、fs），无需 npm install，部署极简
- 安全灵活的认证：支持文件、环境变量、stdin 管道等多种令牌传递方式，避免命令行历史泄露
- 批量与限速处理：自动分批上传（100 blocks/次）并内置 350ms 延迟，优雅应对 Notion API 限速
- 协作友好：支持「本地编辑 → 推送到 Notion → 他人协作编辑 → 监控变更 → 拉回本地」的完整闭环
局限性与风险
- 属性更新限制：数据库元数据（Type、Tags 等）创建后需手动在 Notion UI 中设置，API 对行内数据库支持不稳定
- 格式兼容边界：复杂表格、深层嵌套列表（>3 级）转换可能不完美；超大文件（>1000 blocks）同步耗时较长
- 令牌管理责任：用户需妥善保管
ntn_开头的 Integration Token，泄露可能导致工作空间数据暴露 - 非永久删除："删除"操作实际为归档（archived: true），数据仍占用存储
适用人群
- 技术写作者、研究员：需要在本地 Markdown 环境与 Notion 协作空间之间流转内容
- 项目经理：通过数据库跟踪任务状态、研究输出
- 自动化工程师：将 Notion 集成到 CI/CD 或定时任务，实现文档发布管道
安全风险
- 令牌泄露：若使用
--token参数直接传递，令牌会出现在进程列表（ps）和 shell 历史中 - API 权限：Integration 需显式共享页面/数据库，过度授权可能导致意外数据访问
- 网络传输：依赖 Notion 官方 API（notion.so），数据经 HTTPS 加密传输，但需信任 Notion 平台本身