Notion同步

实现Markdown文件与Notion页面的双向同步，并提供用于研究跟踪和项目管理的数据库管理工具。

升级说明

从v2.0版本开始：请将--token "ntn_..."替换为--token-file、--token-stdin或NOTION_API_KEY环境变量。不再接受裸--token参数（凭证不应出现在进程列表中）。

从v1.x版本升级：迁移详情请参阅v2.0版本变更日志。

系统要求

• Node.jsv18或更高版本
• 一个Notion集成令牌（以ntn_或secret_)

设置

1. 前往https://www.notion.so/my-integrations

2. 创建一个新的集成（或使用现有的）

3. 复制“内部集成令牌”

4. 使用以下方法之一传递令牌（脚本使用的优先级顺序）：

   选项 A — 令牌文件（推荐）：

   echo "ntn_your_token" > ~/.notion-token && chmod 600 ~/.notion-token
   node scripts/search-notion.js "query" --token-file ~/.notion-token
   

   选项 B — 标准输入管道：

   echo "$NOTION_API_KEY" | node scripts/search-notion.js "query" --token-stdin
   

   选项 C — 环境变量：

   export NOTION_API_KEY="ntn_your_token"
   node scripts/search-notion.js "query"
   

   自动默认设置：如果~/.notion-token存在，即使没有--token-file参数，脚本也会自动使用它。

5. 与集成共享您的 Notion 页面/数据库：

   • 在 Notion 中打开页面/数据库
   • 点击“分享” → “邀请”
   • 选择您的集成

JSON输出模式

所有脚本都支持全局--json标志。

• 抑制写入stderr的进度日志
• 保持stdout机器可读以支持自动化
• 错误以JSON格式输出：{ "error": "..." }

示例：

node scripts/query-database.js <db-id> --limit 5 --json

路径安全模式

默认情况下，读写本地文件的脚本被限制在当前工作目录内。

• 防止在意向工作区之外意外读写
• 适用于：md-to-notion.js、add-to-database.js、notion-to-md.js、watch-notion.js
• 可通过以下命令有意覆盖此限制：--allow-unsafe-paths

示例：

# Default (safe): path must be inside current workspace
node scripts/md-to-notion.js docs/draft.md <parent-id> "Draft"

# Intentional override (outside workspace)
node scripts/notion-to-md.js <page-id> ~/Downloads/export.md --allow-unsafe-paths

核心操作

1. 搜索页面和数据库

通过标题或内容在你的 Notion 工作空间中搜索。

node scripts/search-notion.js "<query>" [--filter page|database] [--limit 10] [--json]

示例：

# Search for newsletter-related pages
node scripts/search-notion.js "newsletter"

# Find only databases
node scripts/search-notion.js "research" --filter database

# Limit results
node scripts/search-notion.js "AI" --limit 5

输出：

[
  {
    "id": "page-id-here",
    "object": "page",
    "title": "Newsletter Draft",
    "url": "https://notion.so/...",
    "lastEdited": "2026-02-01T09:00:00.000Z"
  }
]

2. 使用筛选器查询数据库

使用高级筛选和排序功能查询数据库内容。

node scripts/query-database.js <database-id> [--filter <json>] [--sort <json>] [--limit 10] [--json]

示例：

# Get all items
node scripts/query-database.js xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Filter by Status = "Complete"
node scripts/query-database.js <db-id> \
  --filter '{"property": "Status", "select": {"equals": "Complete"}}'

# Filter by Tags containing "AI"
node scripts/query-database.js <db-id> \
  --filter '{"property": "Tags", "multi_select": {"contains": "AI"}}'

# Sort by Date descending
node scripts/query-database.js <db-id> \
  --sort '[{"property": "Date", "direction": "descending"}]'

# Combine filter + sort
node scripts/query-database.js <db-id> \
  --filter '{"property": "Status", "select": {"equals": "Complete"}}' \
  --sort '[{"property": "Date", "direction": "descending"}]'

常见筛选模式：

• 选择等于：{"property": "Status", "select": {"equals": "Done"}}
• 多选包含：{"property": "Tags", "multi_select": {"contains": "AI"}}
• 日期在...之后：{"property": "Date", "date": {"after": "2024-01-01"}}
• 复选框为真：{"property": "Published", "checkbox": {"equals": true}}
• 数字大于：{"property": "Count", "number": {"greater_than": 100}}

3. 更新页面属性

更新数据库页面的属性（状态、标签、日期等）。

node scripts/update-page-properties.js <page-id> <property-name> <value> [--type <type>] [--json]

支持的类型：选择、多选、复选框、数字、网址、电子邮件、日期、富文本

示例：

# Set status
node scripts/update-page-properties.js <page-id> Status "Complete" --type select

# Add multiple tags
node scripts/update-page-properties.js <page-id> Tags "AI,Leadership,Research" --type multi_select

# Set checkbox
node scripts/update-page-properties.js <page-id> Published true --type checkbox

# Set date
node scripts/update-page-properties.js <page-id> "Publish Date" "2024-02-01" --type date

# Set URL
node scripts/update-page-properties.js <page-id> "Source URL" "https://example.com" --type url

# Set number
node scripts/update-page-properties.js <page-id> "Word Count" 1200 --type number

4. 批量更新

通过一条命令跨多个页面批量更新单个属性。

模式 1 — 查询 + 更新：

node scripts/batch-update.js <database-id> <property-name> <value> --filter '<json>' [--type select] [--dry-run] [--limit 100]

示例：

node scripts/batch-update.js <db-id> Status Review \
  --filter '{"property":"Status","select":{"equals":"Draft"}}' \
  --type select

模式 2 — 从标准输入读取页面ID：

echo "page-id-1\npage-id-2\npage-id-3" | \
  node scripts/batch-update.js --stdin <property-name> <value> [--type select] [--dry-run]

功能：

• --dry-run：打印将被更新的页面（包含当前属性值），但不实际写入
• --limit <n>：最大处理页面数（默认100）
• 查询模式下的分页（has_more/next_cursor）直至达到限制
• 对速率限制友好的更新（页面更新之间间隔300毫秒）
• 将进度和摘要输出到标准错误流，JSON结果数组输出到标准输出流

5. Markdown → Notion 同步

将 Markdown 内容推送到 Notion，支持完整格式

node scripts/md-to-notion.js \
  "<markdown-file-path>" \
  "<notion-parent-page-id>" \
  "<page-title>" [--json] [--allow-unsafe-paths]

示例：

node scripts/md-to-notion.js \
  "projects/newsletter-draft.md" \
  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  "Newsletter Draft - Feb 2026"

支持的格式：

• 标题（H1-H3）
• 粗体/斜体文本
• 链接
• 项目符号列表
• 带语法高亮的代码块
• 水平分隔线
• 段落

功能：

• 批量上传（每次请求100个区块）
• 自动速率限制（批次间间隔350毫秒）
• 富文本自动分块以适应Notion的2000字符限制（包括粗体/斜体/链接范围）
• 返回Notion页面URL和ID

输出：

Parsed 294 blocks from markdown
✓ Created page: https://www.notion.so/[title-and-id]
✓ Appended 100 blocks (100-200)
✓ Appended 94 blocks (200-294)

✅ Successfully created Notion page!

6. Notion → Markdown 同步

拉取Notion页面内容并转换为Markdown

node scripts/notion-to-md.js <page-id> [output-file] [--json] [--allow-unsafe-paths]

示例：

node scripts/notion-to-md.js \
  "abc123-example-page-id-456def" \
  "newsletter-updated.md"

功能：

• 将Notion块转换为Markdown
• 保留格式（标题、列表、代码、引用）
• 可选文件输出（写入文件或标准输出）

7. 变更检测与监控

监控Notion页面的编辑，并与本地Markdown文件进行比较。

node scripts/watch-notion.js "<page-id>" "<local-markdown-path>" [--state-file <path>] [--json] [--allow-unsafe-paths]

示例：

node scripts/watch-notion.js \
  "abc123-example-page-id-456def" \
  "projects/newsletter-draft.md"

状态跟踪：默认情况下，状态保存在内存/notion-watch-state.json（相对于当前工作目录）。您可以使用--state-file <路径>覆盖此设置（支持~

node scripts/watch-notion.js "<page-id>" "<local-path>" --state-file ~/.cache/notion-watch-state.json

扩展）：

{
  "pages": {
    "<page-id>": {
      "lastEditedTime": "2026-01-30T08:57:00.000Z",
      "lastChecked": "2026-01-31T19:41:54.000Z",
      "title": "Your Page Title"
    }
  }
}

默认状态模式：

{
  "pageId": "<page-id>",
  "title": "Your Page Title",
  "lastEditedTime": "2026-01-30T08:57:00.000Z",
  "hasChanges": false,
  "localPath": "/path/to/your-draft.md",
  "actions": ["✓ No changes since last check"]
}

输出：自动化监控：

# Example: cron job every 2 hours during work hours
0 9-21/2 * * * cd /path/to/workspace && node scripts/watch-notion.js "<page-id>" "<local-path>"

使用cron、CI流水线或任何任务调度器安排定期检查：脚本输出JSON — 当hasChanges真实.

8. 数据库管理

添加 Markdown 内容到数据库

将 Markdown 文件作为新页面添加到任意 Notion 数据库中。

node scripts/add-to-database.js <database-id> "<page-title>" <markdown-file-path> [--json] [--allow-unsafe-paths]

示例：

# Add research output
node scripts/add-to-database.js \
  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  "Research Report - Feb 2026" \
  projects/research-insights.md

# Add project notes
node scripts/add-to-database.js \
  <project-db-id> \
  "Sprint Retrospective" \
  docs/retro-2026-02.md

# Add meeting notes
node scripts/add-to-database.js \
  <notes-db-id> \
  "Weekly Team Sync" \
  notes/sync-2026-02-06.md

功能：

• 创建带有标题属性的数据库页面
• 将 Markdown 转换为 Notion 块（标题、段落、分隔线）
• 通过批量上传处理大文件
• 返回页面 URL 以供即时访问

注意：其他属性（类型、标签、状态等）必须在创建后于 Notion 界面中手动设置。

检查数据库架构

node scripts/get-database-schema.js <database-id> [--json]

示例输出：

{
  "object": "database",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "title": [{"plain_text": "Ax Resources"}],
  "properties": {
    "Name": {"type": "title"},
    "Type": {"type": "select"},
    "Tags": {"type": "multi_select"}
  }
}

使用场景：

• 设置新的数据库集成
• 调试属性名称/类型
• 理解数据库结构

归档页面

node scripts/delete-notion-page.js <page-id> [--json]

注意：此操作将归档页面（设置已归档），而非永久删除。

常见工作流程

协作编辑工作流程

1. 将本地草稿推送到Notion：

   node scripts/md-to-notion.js draft.md <parent-id> "Draft Title"
   

2. 用户在Notion中进行编辑（任何地点，任何设备）

3. 监控变更：

   node scripts/watch-notion.js <page-id> <local-path>
   # Returns hasChanges: true when edited
   

4. 拉取更新回本地：

   node scripts/notion-to-md.js <page-id> draft-updated.md
   

5. 按需重复（更新同一页面，不创建v2/v3等版本）

研究成果追踪

1. 本地生成研究成果（例如，通过子代理）

2. 同步到Notion数据库：

   node scripts/add-research-to-db.js
   

3. 用户在Notion界面中添加元数据（类型、标签、状态等属性）

4. 随时随地访问通过Notion网页版/移动端

页面ID提取

从Notion URL中提取：https://notion.so/页面标题-abc123-示例页面ID-456def

提取：abc123-example-page-id-456def（标题后的最后部分）

或使用32字符格式：abc123examplepageid456def（连字符可选）

限制

• 属性更新：数据库属性（类型、标签、状态）必须在页面创建后通过Notion界面手动添加。API属性更新在内联数据库上可能不稳定。
• 块限制：非常大的Markdown文件（>1000个块）由于速率限制，可能需要几分钟才能同步。
• 格式：一些复杂的Markdown（表格、嵌套列表超过3级）可能无法完美转换。

故障排除

“找不到页面”错误：

• 确保页面/数据库已与您的集成共享
• 检查页面ID格式（32字符，字母数字 + 连字符）

“找不到模块”错误：

• 脚本使用内置的Node.js https模块（无需npm安装）
• 请确保从技能目录（即scripts/所在目录）运行

速率限制：

• Notion API有速率限制（约每秒3个请求）
• 脚本通过批次间350毫秒的延迟自动处理此限制

资源

scripts/

核心同步：

• md-to-notion.js- Markdown → Notion 同步，支持完整格式
• notion-to-md.js- Notion → Markdown 转换
• watch-notion.js- 变更检测与监控

搜索与查询：

• search-notion.js- 按查询搜索页面和数据库
• query-database.js- 使用筛选和排序查询数据库
• update-page-properties.js- 更新数据库页面属性
• batch-update.js- 批量更新多个页面的同一属性（通过查询或标准输入ID）

数据库管理：

• add-to-database.js- 将Markdown文件作为数据库页面添加
• get-database-schema.js- 检查数据库结构
• delete-notion-page.js- 归档页面

工具集：

• notion-utils.js- 共享工具（错误处理、属性格式化、API请求）

所有脚本仅使用内置的Node.js模块（https、fs）——无需外部依赖。

参考资料/

• database-patterns.md- 常见数据库模式与属性配置方案