Notion

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

Pitfalls

-

-

Verification

-

-

-

-

1. 2. 3. prerequisites: env_vars:

• NOTION_API_KEY

IO_CONTRACT

• input: request: str, context: dict — 用户请求描述、上下文信息
• output: result: dict — 技能执行结果（结构因技能而异）

对应原则：P2（机械原子暴露输入输出规范）

Notion API

Use the Notion API via curl to create, read, update pages, databases (data sources), and blocks. No extra tools needed — just curl and a Notion API key.

Prerequisites

1. Create an integration at https://notion.so/my-integrations
2. Copy the API key (starts with ntn_ or secret_)
3. Store it in ~/.hermes/.env:

   NOTION_API_KEY=ntn_your_key_here
   

4. Important: Share target pages/databases with your integration in Notion (click "..." → "Connect to" → your integration name)

API Basics

All requests use this pattern:

curl -s -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

The Notion-Version header is required. This skill uses 2025-09-03 (latest). In this version, databases are called "data sources" in the API.

Common Operations

Search

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "page title"}'

Get Page

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

Get Page Content (blocks)

curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

Create Page in a Database

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New Item"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

Query a Database

curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

Create a Database

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "My Database"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

Update Page Properties

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

Add Content to a Page

curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello from Hermes!"}}]}}
    ]
  }'

Property Types

Common property formats for database items:

• Title: {"title": [{"text": {"content": "..."}}]}
• Rich text: {"rich_text": [{"text": {"content": "..."}}]}
• Select: {"select": {"name": "Option"}}
• Multi-select: {"multi_select": [{"name": "A"}, {"name": "B"}]}
• Date: {"date": {"start": "2026-01-15", "end": "2026-01-16"}}
• Checkbox: {"checkbox": true}
• Number: {"number": 42}
• URL: {"url": "https://..."}
• Email: {"email": "user@example.com"}
• Relation: {"relation": [{"id": "page_id"}]}

Key Differences in API Version 2025-09-03

• Databases → Data Sources: Use /data_sources/ endpoints for queries and retrieval
• Two IDs: Each database has both a database_id and a data_source_id
  • Use database_id when creating pages (parent: {"database_id": "..."})
  • Use data_source_id when querying (POST /v1/data_sources/{id}/query)
• Search results: Databases return as "object": "data_source" with their data_source_id

Notes

• Page/database IDs are UUIDs (with or without dashes)
• Rate limit: ~3 requests/second average
• The API cannot set database view filters — that's UI-only
• Use is_inline: true when creating data sources to embed them in pages
• Add -s flag to curl to suppress progress bars (cleaner output for Hermes)
• Pipe output through jq for readable JSON: ... | jq '.results[0].properties'

验证清单 · VERIFICATION

• 环境变量 NOTION_API_KEY 已从 ~/.hermes/.env 读取（ntn_/secret_ 前缀），未硬编码
• 每个 curl 请求均携带 Notion-Version: 2025-09-03 请求头，缺失时不发起调用
• 目标页面/数据库已通过 Notion UI 共享给对应 Integration，避免 404/permission 错误
• 创建页面使用 database_id，查询数据使用 data_source_id（/v1/data_sources/{id}/query 端点），两个 ID 未混用
• 属性 JSON 结构符合类型规范（Title 嵌套 text.content、Select 用 name 字段等），请求频率控制在 ~3 req/s 以内
• API 响应经 jq 管道解析确认结构正确（如 .results[0].properties），错误响应含明确原因

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Notion

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [NOTI-001] 调用 Notion API 时 → 必须包含 Notion-Version: 2025-09-03 请求头以符合最新 API 规范
• [NOTI-002] 区分数据库操作场景时 → 创建页面使用 database_id，查询数据使用 data_source_id
• [NOTI-003] 执行 API 请求前 → 确保目标页面或数据库已通过 Notion UI 共享给对应的 Integration
• [NOTI-004] 处理数据库查询或创建时 → 使用 /data_sources/ 端点替代旧版 /databases/ 端点
• [NOTI-005] 构建数据库属性数据时 → 严格遵循特定类型的 JSON 结构（如 Title 需嵌套 text.content，Select 需 name 字段）
• [NOTI-006] 处理 API 响应数据时 → 使用 jq 管道解析 JSON 输出以提升可读性和处理效率
• [NOTI-007] 执行高频 API 请求时 → 控制请求频率在平均 3 次/秒以内以遵守速率限制