介绍
# Notion
此技能允许代理使用官方 Notion API 与 **Notion 页面和数据库** 进行交互。
该技能是声明式的：它记录了 **安全、推荐的操作**，并假设有一个本地 CLI（`notion-cli`）实际执行 API 调用。
## 身份验证
- 在 https://www.notion.so/my-integrations 创建一个 Notion Integration。 - 复制 Internal Integration Token。 - 将其导出为：
```bash export NOTION_API_KEY=secret_xxx ```
将此 Integration 共享给您想要访问的页面或数据库。 未共享的内容对 API 不可见。
## 配置文件（个人 / 工作）
您可以通过环境变量或配置定义多个配置文件（例如个人、工作）。
默认配置文件：personal
通过以下方式覆盖：
```bash export NOTION_PROFILE=work ```
## 页面
**读取页面：**
```bash notion-cli page get <page_id> ```
**追加块：**
```bash notion-cli block append <page_id> --markdown "..." ```
优先使用追加而不是重写内容。
**创建页面：**
```bash notion-cli page create --parent <page_id> --title "..." ```
## 数据库
**查看架构：**
```bash notion-cli db get <database_id> ```
**查询数据库：**
```bash notion-cli db query <database_id> --filter <json> --sort <json> ```
**创建行：**
```bash notion-cli page create --database <database_id> --props <json> ```
**更新行：**
```bash notion-cli page update <page_id> --props <json> ```
## 架构更改（高级）
在应用架构更改之前，请务必检查差异。
未经明确确认，切勿修改数据库架构。
推荐流程：
```bash notion-cli db schema diff <database_id> --desired <json> notion-cli db schema apply <database_id> --desired <json> ```
## 安全注意事项
- Notion API 有速率限制；请谨慎进行批量操作。 - 相比于破坏性操作，优先使用追加和更新。 - ID 是不透明的；请显式存储它们，不要从 URL 推断。