核心功能
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实为归档操作，误操作可恢复，但长期数据清理需人工介入