名称: notion-api 描述: 当用户要求“搜索Notion”、“在Notion中查找”、“搜索我的Notion工作区”、“创建Notion页面”、“制作Notion页面”、“更新Notion页面”、“编辑Notion页面”、“查询Notion数据库”、“获取Notion数据库”、“读取Notion页面”、“从Notion获取页面内容”、“列出Notion页面”，或提及Notion集成、Notion工作区或Notion API访问时，应使用此技能。版本: 0.1.0

Notion API集成

通过Bun执行的TypeScript脚本访问Notion页面、数据库和内容。

概述

此技能提供对Notion API的访问，用于：

搜索：在整个工作区中查找页面和数据库
页面：获取、创建和更新页面
数据库：使用筛选器和排序查询数据库条目
块：以块的形式读取页面内容

所有脚本都返回JSON，并需要NOTION_TOKEN环境变量。

响应格式

所有脚本输出具有一致结构的JSON：

成功

{"status": "success", "data": {...}}

需要身份验证

{
  "status": "auth_required",
  "message": "设置NOTION_TOKEN环境变量，使用您的集成令牌...",
  "setupUrl": "https://www.notion.so/my-integrations"
}

当您收到auth_required时，向用户显示：

要访问Notion，您需要设置集成：
1. 前往：https://www.notion.so/my-integrations
2. 为您的workspace创建新集成
3. 复制“内部集成密钥”
4. 使用此令牌设置NOTION_TOKEN环境变量
5. 与集成共享您的页面/数据库（点击“...”菜单 > “添加连接”）

设置完成后请告诉我。

错误

{"status": "error", "error": "错误描述"}

搜索

在整个Notion工作区中搜索页面和数据库。

所有脚本位于${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/。

# 搜索匹配查询的页面/数据库
bun run ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/search.ts --query "会议记录"

# 仅搜索页面
bun run search.ts --query "项目" --filter page

# 仅搜索数据库
bun run search.ts --filter database --top 20

# 列出所有可访问的项目（无查询）
bun run search.ts --top 10

页面

获取、创建和更新Notion页面。

获取页面

bun run ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/pages.ts get --id <页面ID>

创建页面

# 作为另一个页面的子页面创建
bun run pages.ts create --parent-id <页面ID> --title "新页面"

# 作为另一个页面的子页面创建，带图标
bun run pages.ts create --parent-id <页面ID> --title "新页面" --icon "📝"

# 作为数据库条目创建
bun run pages.ts create --parent-id <数据库ID> --parent-type database --title "新条目"

# 创建带属性的数据库条目
bun run pages.ts create --parent-id <数据库ID> --parent-type database --title "任务" \
  --properties '{"状态": {"select": {"name": "待办"}}, "优先级": {"select": {"name": "高"}}}'

更新页面

# 更新标题
bun run pages.ts update --id <页面ID> --title "更新后的标题"

# 更新图标
bun run pages.ts update --id <页面ID> --icon "🎉"

# 归档页面
bun run pages.ts update --id <页面ID> --archived true

# 恢复已归档页面
bun run pages.ts update --id <页面ID> --archived false

# 更新数据库页面属性
bun run pages.ts update --id <页面ID> --properties '{"状态": {"select": {"name": "已完成"}}}'

数据库

查询和获取有关Notion数据库的信息。

获取数据库架构

bun run ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/databases.ts get --id <数据库ID>

返回数据库标题、描述和所有属性定义。

查询数据库

# 查询所有条目
bun run databases.ts query --id <数据库ID>

# 带限制查询
bun run databases.ts query --id <数据库ID> --top 20

# 带筛选器查询
bun run databases.ts query --id <数据库ID> --filter '{"property": "状态", "select": {"equals": "已完成"}}'

# 带多个条件查询（AND）
bun run databases.ts query --id <数据库ID> --filter '{"and": [
  {"property": "状态", "select": {"equals": "进行中"}},
  {"property": "优先级", "select": {"equals": "高"}}
]}'

# 带排序查询
bun run databases.ts query --id <数据库ID> --sorts '[{"property": "创建时间", "direction": "descending"}]'

# 按最后编辑时间排序
bun run databases.ts query --id <数据库ID> --sorts '[{"timestamp": "last_edited_time", "direction": "descending"}]'

常见筛选器示例

# 文本包含
--filter '{"property": "名称", "rich_text": {"contains": "项目"}}'

# 复选框已勾选
--filter '{"property": "已完成", "checkbox": {"equals": true}}'

# 日期在之后
--filter '{"property": "截止日期", "date": {"after": "2024-01-01"}}'

# 数字大于
--filter '{"property": "分数", "number": {"greater_than": 80}}'

# OR条件
--filter '{"or": [
  {"property": "状态", "select": {"equals": "已完成"}},
  {"property": "状态", "select": {"equals": "已归档"}}
]}'

块（页面内容）

以块的形式读取页面内容。

列出页面块

# 从页面获取块
bun run ${CLAUDE_PLUGIN_ROOT}/skills/notion/scripts/blocks.ts list --id <页面ID>

# 带限制获取块
bun run blocks.ts list --id <页面ID> --top 100

# 递归获取块（包括嵌套内容）
bun run blocks.ts list --id <页面ID> --recursive

获取特定块

bun run blocks.ts get --id <块ID>

块类型

块可以是：paragraph（段落）、heading_1（标题1）、heading_2（标题2）、heading_3（标题3）、bulleted_list_item（项目符号列表项）、numbered_list_item（编号列表项）、to_do（待办事项）、toggle（切换）、code（代码）、quote（引用）、callout（标注）、divider（分隔线）、table（表格）、image（图像）、bookmark（书签）等。

每个块包括：

id：块标识符
type：块类型
content：文本内容（如果适用）
hasChildren：块是否有嵌套块
children：嵌套块（使用–recursive时）

身份验证设置

前往 https://www.notion.so/my-integrations
点击“New integration”
为其命名并选择工作区
复制“Internal Integration Secret”
设置环境变量：
```
export NOTION_TOKEN=secret_xxxxx
```
与集成共享页面/数据库：
- 在Notion中打开页面或数据库
- 点击右上角的“…”菜单
- 选择“Add connections”
- 找到并选择您的集成

重要注意事项

需要共享：页面和数据库必须先与您的集成共享，然后才能访问
速率限制：Notion API平均允许约每秒3个请求
页面ID：可在页面URL中找到（页面名称后的32个字符字符串）
数据库ID：与页面ID格式相同，在数据库URL中找到

脚本参考

脚本	用途
`search.ts`	在整个工作区中搜索页面和数据库
`pages.ts`	获取、创建、更新页面
`databases.ts`	获取数据库架构，查询条目
`blocks.ts`	以块的形式读取页面内容

其他资源

有关详细API参考，请参阅：

references/notion-api.md - Notion API端点和参数