---
name: notion-notes
description: >-
  在 Notion 中创建、搜索、读取和管理笔记页面。Use when the user wants to create a Notion page,
  search notes in Notion, read page content, append content to a page, query a
  database, or retrieve page/database metadata via the Notion connector.
metadata:
  icon: "📝"
  title: Notion 笔记
---

# Notion 笔记

通过 oo CLI 的 Notion connector 在 Notion 中管理笔记。所有操作基于已认证的 Notion 连接器，无需手动传 token。

## 可用操作

### 1. 搜索笔记 `notion.search`

按关键词搜索 Notion 页面和数据库。

```bash
oo connector run "notion" \
  --action "search" \
  --data '{"query": "<搜索关键词>"}' \
  --json
```

可选参数：
- `filter`: 过滤条件对象，如 `{"property": "object", "value": "page"}`
- `sort`: 排序对象
- `pageSize`: 每页结果数（1-100）
- `startCursor`: 分页游标

输出包含 `results`（结果列表）、`hasMore`、`nextCursor`。

### 2. 创建页面 `notion.create_page`

在指定父页面下创建新笔记。

```bash
oo connector run "notion" \
  --action "create_page" \
  --data '{"parentId": "<父页面ID>", "title": "<页面标题>"}' \
  --json
```

可选参数：
- `children`: 子内容块数组（段落、标题、列表等）
- `properties`: 页面属性对象
- `icon`: 图标对象，如 `{"type": "emoji", "emoji": "📌"}`
- `cover`: 封面图片对象

输出返回 `pageId`。

### 3. 读取页面 `notion.get_page`

获取页面属性和一级子块内容。

```bash
oo connector run "notion" \
  --action "get_page" \
  --data '{"pageId": "<页面ID>"}' \
  --json
```

输出包含 `page`（页面对象）和 `blocks`（子块列表）。

### 4. 追加内容 `notion.append_block`

向已有页面追加一个段落块。

```bash
oo connector run "notion" \
  --action "append_block" \
  --data '{"pageId": "<页面ID>", "text": "<要追加的文本>"}' \
  --json
```

输出返回 `blockId`。多次追加需多次调用。

### 5. 查询数据库 `notion.query_data_source`

按条件查询 Notion 数据库记录。

```bash
oo connector run "notion" \
  --action "query_data_source" \
  --data '{"dataSourceId": "<数据库ID>"}' \
  --json
```

可选参数：
- `filter`: 过滤条件
- `sorts`: 排序数组
- `pageSize`: 每页结果数（1-100）
- `startCursor`: 分页游标
- `filterProperties`: 指定返回的属性名列表

### 6. 获取数据库结构 `notion.retrieve_database`

```bash
oo connector run "notion" \
  --action "retrieve_database" \
  --data '{"databaseId": "<数据库ID>"}' \
  --json
```

### 7. 获取页面属性 `notion.retrieve_page`

```bash
oo connector run "notion" \
  --action "retrieve_page" \
  --data '{"pageId": "<页面ID>"}' \
  --json
```

### 8. 获取单个属性 `notion.retrieve_page_property`

```bash
oo connector run "notion" \
  --action "retrieve_page_property" \
  --data '{"pageId": "<页面ID>", "propertyId": "<属性ID>"}' \
  --json
```

### 9. 获取内容块 `notion.retrieve_block`

```bash
oo connector run "notion" \
  --action "retrieve_block" \
  --data '{"blockId": "<块ID>"}' \
  --json
```

## 工作流程

1. **确定意图**：根据用户请求判断用哪个操作。
   - "写笔记/创建页面/新建笔记" → `create_page`
   - "搜索/找笔记" → `search`
   - "读取/查看笔记内容" → `get_page`
   - "追加内容/更新笔记" → `append_block`
   - "查询数据库/列表筛选" → `query_data_source`

2. **获取必要 ID**：
   - 如果用户未提供 pageId / databaseId / parentId，先执行 `search` 查找目标。
   - 从搜索结果的 `id` 字段提取。

3. **构建 payload**：
   - 使用 schema 中定义的最小必填字段。
   - 如需创建带内容的页面，在 `children` 中添加内容块。

4. **执行并报告**：
   - 所有命令加 `--json` 获取结构化输出。
   - 向用户报告关键结果（pageId、内容摘要等）。

## 注意事项

- Notion connector 需要先在 https://console.oomol.com/app-connections?provider=notion 完成授权认证。
- 如果执行返回 `scope_missing`、`credential_expired` 或 `app_not_ready`，引导用户到上述链接重新授权。
- pageId / databaseId 是 32 位无连字符字符串（如 `1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d`）。
- Notion API 对请求频率有限制，批量操作时注意间隔。