Notion Sync

核心功能

notion-sync 是一套基于 Node.js 的 Notion 集成工具集，提供双向 Markdown ↔ Notion 同步、数据库查询与管理、页面变更监控等核心能力。无需额外依赖，仅使用 Node.js 内置模块即可运行。

显著优点

安全凭证管理：v2.0 版本强制移除命令行明文 token，支持文件、stdin、环境变量三种安全传递方式，符合最小权限原则。

完整双向同步：

• Markdown → Notion：支持标题、粗体/斜体、链接、列表、代码块等完整格式，自动分批上传并处理 API 限流
• Notion → Markdown：保留页面结构，输出标准 Markdown 文件

数据库操作灵活：支持复杂过滤（多选包含、日期范围、数值比较）、排序、属性更新，可程序化地将研究输出注入数据库。

变更监控机制：watch-notion.js 追踪页面 lastEditedTime，输出 JSON 状态供 CI/CD 或 cron 调度，实现"本地编辑→Notion 协作→拉回更新"的闭环工作流。

局限性与风险

属性更新限制：数据库自定义属性（Type/Tags/Status）需在 Notion UI 手动设置，API 对行内数据库的属性更新存在兼容性问题。

格式转换边界：表格、三级以上嵌套列表可能丢失或渲染异常；超大文件（>1000 blocks）因 350ms 批次延迟需数分钟完成同步。

API 依赖风险：完全依赖 Notion 官方 API，受限于其 ~3 req/s 的速率限制；token 泄露可导致工作区数据暴露，需严格管理 ~/.notion-token 文件权限（建议 chmod 600）。

适合人群

• 技术写作者：本地 Markdown 写作 + Notion 发布/协作
• 研究团队：程序化归档分析结果至结构化数据库
• 项目经理：自动化日报/周报生成与状态同步
• 开发团队：将文档同步纳入 CI/CD 流程

常规风险

• Token 安全：secret_/ntn_ 密钥需按推荐方式存储，避免出现在 shell history 或进程列表
• 数据一致性：双向同步存在冲突可能，建议以本地或 Notion 一端为权威源
• 归档非删除：delete-notion-page.js 实为归档操作，误操作可恢复，但长期数据清理需人工介入

核心用法

notion-sync 是一套完整的 Notion 工作空间命令行工具集，基于 Node.js 内置模块实现零依赖架构。核心功能涵盖七大场景：

1. 搜索与发现：search-notion.js 支持按标题或内容搜索页面/数据库，支持分页与类型过滤
2. 数据库查询：query-database.js 提供高级过滤（Select/Multi-select/Date/Checkbox/Number 等）与多字段排序
3. 属性更新：update-page-properties.js 支持 8 种属性类型的程序化修改
4. Markdown → Notion：md-to-notion.js 实现批量上传（100 块/批次）、自动速率限制（350ms 间隔），支持 H1-H3、加粗、链接、列表、代码块等完整格式
5. Notion → Markdown：notion-to-md.js 反向导出，保留原始结构
6. 变更监控：watch-notion.js 维护本地状态文件，检测页面编辑时间戳变化，输出 JSON 供自动化流水线消费
7. 数据库管理：add-to-database.js 将 Markdown 创建为数据库条目，get-database-schema.js 查看结构，delete-notion-page.js 归档页面

显著优点

• 安全设计领先：强制禁止命令行明文传 Token，提供文件/Stdin/环境变量三种安全凭证方式，防止进程列表泄露
• 零供应链风险：仅依赖 Node.js 内置 https/fs/path，无 npm 包，彻底规避依赖劫持
• 生产级鲁棒性：内置速率限制保护、批量分块、详细错误分类（401/404/429/500）
• 自动化友好：所有脚本输出结构化 JSON，易于与 cron/CI/通知系统集成
• 协作工作流完整：支持「本地编辑→推送到 Notion→他人协作→监控变更→拉回更新」的闭环

潜在缺点与局限性

• 属性创建限制：数据库条目创建后，Type/Tags/Status 等属性需手动在 Notion UI 补充，API 对行内数据库支持不稳定
• 大文件性能：>1000 块的 Markdown 因速率限制可能耗时数分钟
• 格式兼容性：嵌套列表（>3 层）、表格等复杂 Markdown 转换可能不完美
• 状态文件权限：监控状态未显式设置 600 权限，多用户环境存在轻微信息泄露风险
• 无请求超时：HTTP 请求未配置 timeout，极端网络条件下可能挂起

适合人群

• 技术写作者：本地 Markdown 编辑 + Notion 发布/协作的混合工作流
• 研发团队：研究追踪数据库、项目看板的自动化同步
• DevOps/自动化工程师：需将 Notion 作为数据源集成到 CI/CD 或监控体系
• 注重安全的组织：零依赖、MIT 协议、可审计源码

常规风险

| 风险类别 | 说明 | 缓解措施 |

|---------|------|---------|

| API 密钥泄露 | Integration Token 泄露可导致工作空间数据暴露 | 使用 `--token-file` + `chmod 600`，定期轮换 Token |

| 速率限制 | 频繁操作可能触发 Notion API 限制 | 脚本已内置 350ms 延迟，避免并发调用 |

| 数据覆盖 | 双向同步可能产生版本冲突 | 使用 `watch-notion.js` 检测变更，手动合并策略 |

| 状态文件泄露 | `memory/notion-watch-state.json` 含页面元数据 | 建议手动设置 600 权限，避免提交到版本控制 |

版本升级注意

• v2.0+：废弃 --token "ntn_..." 参数，迁移至 --token-file/--token-stdin/NOTION_API_KEY 环境变量
• 共享页面给 Integration 是必要前置步骤，否则报 "Could not find page"