Notion Sync

核心功能

Notion Sync 是一套基于 Node.js 的命令行工具集，实现本地 Markdown 文件与 Notion 工作空间的双向同步。核心能力包括：

• 双向同步：md-to-notion.js 将 Markdown 推送到 Notion（支持标题、列表、代码块等富文本），notion-to-md.js 将页面内容拉回本地
• 数据库操作：查询数据库（支持复杂过滤与排序）、批量更新属性、添加 Markdown 为数据库新条目
• 变更监控：watch-notion.js 跟踪页面最后编辑时间，检测 Notion 端修改并输出 JSON 状态
• 安全设计：Token 支持文件、stdin、环境变量三种传递方式，避免命令行暴露凭证；文件操作默认限制在当前工作目录

显著优点

1. 零依赖部署：仅使用 Node.js 内置模块（https、fs），无需 npm install
2. 企业级安全：v2.0 移除 --token 明文参数，强制使用文件或环境变量；支持 --allow-unsafe-paths 显式覆盖路径限制
3. 自动化友好：全局 --json 标志输出结构化数据，便于集成 CI/CD 或 cron 任务
4. 速率限制处理：内置 300-350ms 延迟，自动适应 Notion API 限制（~3 req/s）

局限性与风险

• 属性创建限制：数据库页面的附加属性（Type、Tags、Status）需在 Notion UI 手动设置，API 对行内数据库的属性更新不稳定
• 格式兼容性：复杂表格、三层以上嵌套列表转换可能不完美；超大文件（>1000 blocks）同步耗时较长
• 仅支持归档：delete-notion-page.js 实际执行 archive 操作，非永久删除

适合人群

• 技术写作者：本地 Markdown 写作 + Notion 协作发布的工作流
• 研发团队：将子代理生成的研究报告同步到 Notion 数据库追踪
• 项目经理：批量更新任务状态、监控页面变更触发通知

常规风险

• Token 泄露：若 ~/.notion-token 权限设置不当（建议 chmod 600），可能被同系统其他用户读取
• 数据覆盖：双向同步存在冲突风险，建议配合 watch-notion.js 检测变更后再执行覆盖操作
• API 限流：大规模批量更新时仍可能触发 Notion 速率限制，导致操作中断

核心用法

notion-sync 是一套基于 Node.js 的命令行工具集，实现 Markdown 文件与 Notion 页面的双向同步，并提供完整的数据库管理能力。核心功能包括：

• 双向同步：md-to-notion.js 将本地 Markdown 推送到 Notion 页面，notion-to-md.js 将 Notion 内容拉取为 Markdown
• 变更监控：watch-notion.js 持续监测 Notion 页面编辑状态，可配合 cron 实现自动化工作流
• 数据库操作：查询、筛选、批量更新属性，支持复杂过滤条件（多选标签、日期范围、状态等）
• 安全管理：路径安全模式限制文件访问在当前工作目录，需显式 --allow-unsafe-paths 才能覆盖

典型工作流：本地撰写 → 推送到 Notion 协作编辑 → 监控变更 → 拉回更新 → 版本控制归档

显著优点

• 零依赖攻击面：仅使用 Node.js 内置模块（https/fs/path/os），无 npm 依赖包，供应链风险为零
• 凭证安全设计：拒绝命令行直接传 Token，支持文件（推荐）、stdin、环境变量三种安全方式，避免凭证泄露在进程列表
• 速率限制友好：自动处理 Notion API 限流（350ms 批次间隔），支持大文件分批上传
• 格式化保留：完整支持标题、加粗/斜体、链接、列表、代码块、分隔线等 Markdown 元素
• 批量生产力：batch-update.js 支持查询条件批量更新或从 stdin 接收页面 ID 列表，适合 CI/CD 集成

潜在缺点与局限性

• 个人维护项目：作者 robansuini 为独立开发者，无大型组织背书，长期维护存在不确定性
• 属性创建限制：数据库页面的额外属性（Type、Tags、Status 等）需在 Notion UI 手动设置，API 无法一键配置
• 复杂格式边界：表格、三层以上嵌套列表转换可能不完美；超 1000 块的大文件同步耗时较长
• 非永久删除：delete-notion-page.js 仅执行归档操作（archived: true），非真正删除
• Token 轮换依赖用户：需手动在 Notion Integration 页面管理 Token 生命周期

适合人群

• 技术写作者、研究人员：需要本地 Markdown 版本控制 + Notion 协作分享的混合工作流
• 小型团队项目经理：利用 Notion 数据库进行任务追踪，需批量更新状态或导出报告
• 开发者/自动化工程师：需要通过 JSON 输出模式集成到 CI/CD、数据管道或自定义通知系统
• 隐私敏感用户：重视零外部依赖、无第三方数据上报、凭证不暴露于命令行历史

常规风险

• 凭证管理风险：虽支持安全传入方式，若用户误用 --token "ntn_..." 旧语法或明文写入脚本，存在泄露风险
• 路径覆盖误用：--allow-unsafe-paths 若与不可信路径变量结合，可能导致敏感文件读写
• API Token 权限：Notion Integration 需显式分享页面，权限过大时可能意外暴露工作区内容
• 状态文件冲突：memory/notion-watch-state.json 默认在工作目录，多项目并行时需用 --state-file 隔离
• Notion API 变更：依赖官方 API 行为，未来 Notion 更新可能导致部分功能需适配