Notion

通过 API 对 Notion 页面和数据库进行增删改查 — 使用 Notion API 直接在 CLI-JAW 中创建、读取、更新和查询 Notion 页面、数据源（数据库）和块。

快速参考

概述

notion 技能通过 Notion API 提供对 Notion 工作区的完整增删改查访问。它使 CLI-JAW 能够搜索页面、创建和更新内容、查询数据库（数据源）、管理块以及应用视觉设计模式 — 所有操作均无需离开终端。

核心功能：

• 搜索 — 按标题或内容查找页面和数据源
• 读取 — 获取页面属性和块级内容
• 创建 — 向工作区或数据源添加新页面，创建新数据源
• 更新 — 修改页面属性、追加块、更改状态字段
• 查询 — 使用结构化查询对数据源条目进行筛选和排序
• 设计 — 应用 Notion 原生视觉模式（提及链接、标注块、图标）

设置

在使用 Notion 技能之前，您需要一个 API 集成密钥和正确的权限。

# Store your API key
mkdir -p ~/.config/notion
echo "ntn_your_api_key_here" > ~/.config/notion/api_key
chmod 600 ~/.config/notion/api_key

API 辅助函数

该技能定义了一个可复用的 Shell 辅助函数，所有操作均基于此构建。CLI-JAW 在执行 Notion 命令时内部使用此函数：

NOTION_KEY=$(cat ~/.config/notion/api_key)

# Helper function used by all API calls
notion_api() {
  local method=$1 endpoint=$2 data=$3
  curl -s -X "$method" "https://api.notion.com/v1$endpoint" \
    -H "Authorization: Bearer $NOTION_KEY" \
    -H "Notion-Version: 2025-09-03" \
    -H "Content-Type: application/json" \
    ${data:+-d "$data"}
}

常用操作

搜索

按标题查找页面和数据源。返回匹配的对象及其 ID。

# Search for pages by title
notion_api POST /search '{"query": "page title"}'

# Discover workspace page IDs
notion_api POST /search '{"query": "Meeting Notes"}'

读取页面和块

获取页面属性及其块级内容。

# Get page properties
notion_api GET /pages/{page_id}

# Get page content (all child blocks)
notion_api GET /blocks/{page_id}/children

创建页面

在数据源（数据库）中创建带属性的新页面，或作为现有页面的子页面创建。

# Create a page in a data source
notion_api POST /pages '{
  "parent": {"database_id": "xxx"},
  "properties": {
    "Name": {"title": [{"text": {"content": "New Item"}}]},
    "Status": {"select": {"name": "Todo"}}
  }
}'

更新页面

修改页面属性，不影响页面内容（块）。

# Update a status property
notion_api PATCH /pages/{page_id} \
  '{"properties": {"Status": {"select": {"name": "Done"}}}}'

追加块

向现有页面添加新的内容块。

# Add a paragraph block
notion_api PATCH /blocks/{page_id}/children '{
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{"text": {"content": "Hello, world!"}}]
      }
    }
  ]
}'

查询数据源

使用结构化查询对数据库条目进行筛选和排序。

# Query with filter and sort
notion_api POST /data_sources/{data_source_id}/query '{
  "filter": {
    "property": "Status",
    "select": {"equals": "Active"}
  },
  "sorts": [
    {"property": "Date", "direction": "descending"}
  ]
}'

创建数据源

创建一个具有定义架构的新数据库（数据源）。

# Create a new data source with properties
notion_api POST /data_sources '{
  "parent": {"page_id": "xxx"},
  "title": [{"text": {"content": "My Database"}}],
  "properties": {
    "Name": {"title": {}},
    "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
    "Date": {"date": {}}
  }
}'

属性类型参考

每种属性类型都有特定的 JSON 结构。创建或更新页面属性时请使用正确的格式。

{"title": [{"text": {"content": "..."}}]}

{"rich_text": [{"text": {"content": "..."}}]}

{"select": {"name": "Option"}}

{"multi_select": [{"name": "A"}, {"name": "B"}]}

{"date": {"start": "2024-01-15", "end": "2024-01-16"}}

{"checkbox": true}

{"number": 42}

{"url": "https://..."}

{"email": "user@example.com"}

{"relation": [{"id": "page_id"}]}

2025-09-03 API 变更

最新的 Notion API 版本对数据库的处理方式引入了重大变更。该技能基于此版本构建。

视觉设计规则

该技能包含一组视觉设计规则（称为"美学指南"），确保 CLI-JAW 创建的 Notion 页面外观精美并遵循 Notion 原生模式。

// Correct: mention link (creates backlink, shows icon)
{"type": "mention", "mention": {"type": "page", "page": {"id": "page-UUID"}}}

// Incorrect: plain text (no backlink, no icon)
{"type": "text", "text": {"content": "Page Name"}}

{"object": "block", "type": "callout", "callout": {
    "rich_text": [
        {"type": "mention", "mention": {"type": "page", "page": {"id": "dashboard-UUID"}}},
        {"type": "text", "text": {"content": " · "}},
        {"type": "mention", "mention": {"type": "page", "page": {"id": "operations-UUID"}}}
    ],
    "icon": {"type": "emoji", "emoji": "🏠"},
    "color": "gray_background"
}}

# Python: safely clear blocks without archiving subpages
for block in children:
    if block["type"] != "child_page":
        delete_block(block["id"])

环境与配置

要发现工作区页面 ID 以用于脚本和命令：

# Search by name to find page/database UUIDs
notion_api POST /search '{"query": "page name"}'

使用示例

以 CLI-JAW 能理解的自然韩语风格展示的实际使用模式。

重要注意事项

• 页面/数据库 ID 是 UUID — 破折号可选（abc123def456 和 abc123-def4-56... 均可使用）
• 数据库视图筛选器仅限 UI 使用，无法通过 API 设置或读取
• 内联数据源：创建数据源时使用 is_inline: true 可将其嵌入页面内，而非作为独立的全页数据库
• child_page 安全：清除内容时切勿删除 child_page 块 — 这会永久归档子页面
• 双 ID 系统：在 2025-09-03 API 中，数据库同时具有 database_id（用于创建页面）和 data_source_id（用于查询）— 请为每个操作使用正确的 ID
• 速率限制：Notion API 允许约 3 次请求/秒；在批量脚本中请在调用之间插入 time.sleep(0.35)
• 集成访问权限：您要访问的每个页面和数据库都必须在 Notion 的共享对话框中显式与集成共享

相关内容

• Notion API Documentation — Notion API 官方参考文档
• 生产力技能 — Notion 及相关生产力技能的分类页面
• 记忆 — 跨会话的持久知识存储
• 技能目录 — 浏览所有技能
• CLI 命令 — 完整的 CLI-JAW 命令参考