notion

name: notion description: 与 Notion 工作区交互 — 搜索、查找、添加、创建、编辑、更新、删除、导出、查询页面/数据库/内容块/待办事项。当用户提到 Notion 并涉及任何操作（搜索文档、添加数据库行、加 todo、导出 markdown、查询任务状态、记笔记、写会议纪要、配置 token）时使用。这是直接执行 Notion API 操作的 CLI 工具，无需编码。不用于：编写调用 Notion API 的脚本、排查 Notion UI 显示问题、规划迁移方案。 user-invocable: true disable-model-invocation: false allowed-tools: Bash, Read

Notion CLI Skill

使用 notion-cli 工具与 Notion 工作区交互，支持页面、数据库、内容块的完整 CRUD 操作。

命令前缀

所有命令使用 uv run 执行：

cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli <command>

当前配置

• 配置文件: ~/.notion-cli/config.yaml
• Token 状态: !cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli config show 2>/dev/null | head -3

前置条件

使用前需要配置 Notion Integration Token：

# 设置 Token（从 https://www.notion.so/my-integrations 获取）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli config set-token

命令参考

搜索

# 搜索所有内容（位置参数，推荐写法）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "关键词"

# 等价写法：用 -q 选项
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search -q "关键词"

# 仅搜索页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "关键词" --filter page

# 仅搜索数据库
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "关键词" --filter database

# 限制结果数量
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "关键词" --limit 5

页面操作

# 获取页面信息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page get --id <page_id>

# 创建新页面（在父页面下）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page create --title "页面标题" --parent <parent_id>

# 创建新页面（在数据库下）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page create --title "页面标题" --parent <database_id> --parent-type database

# 更新页面标题
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page update --id <page_id> --title "新标题"

# 归档页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page update --id <page_id> --archive

# 删除页面（归档）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page delete --id <page_id>
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page delete --id <page_id> --yes  # 跳过确认

已知 Database 速查表（避免每次 list/search）

R- 系列 = Resources（参考资料），L- 系列 = Library / Likes（兴趣库）。需要写入这些 database 时直接用下面的 id，不要先跑 database list 或 search --filter database 再去定位（既慢又可能落到旧版本 client-side 过滤翻车的边界）。

用法：用户说"收进 R-信息资料 / 加到 L-Notes / 写到 Ideas" → 直接 database add-row --id <对应 ID>，先 database info --id <ID> 拿 schema 再填属性。如果某个常用 database 不在表里，再走 database list（已修复 paginate）做兜底。

数据库操作

# 列出所有可访问的数据库（已用 server-side filter，会全量 paginate）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database list

# 获取数据库信息（含属性 schema）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database info --id <database_id>

# 查询数据库（返回完整条目）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database query --id <database_id>
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database query --id <database_id> --limit 10

# 以表格形式显示数据库行
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database rows --id <database_id>
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database rows --id <database_id> --limit 20
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database rows --id <database_id> -c "Name,Status,Priority"

# 获取特定行
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database get-row --id <row_id>

# 添加数据库行
# 格式：-p "属性名=值" 或 -p "属性名:类型=值"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database add-row --id <database_id> \
  -p "Name=任务名称" \
  -p "Status:select=In Progress" \
  -p "Priority:number=1" \
  -p "Done:checkbox=false"

# 更新行
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database update-row --id <row_id> \
  -p "Status:select=Done" \
  -p "Done:checkbox=true"

# 删除行（归档）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database delete-row --id <row_id>
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database delete-row --id <row_id> --yes

属性类型参考

在 add-row 和 update-row 命令中，使用 -p "属性名:类型=值" 格式：

内容块操作

# 列出支持的块类型
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block types

# 列出页面中的块（表格形式）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block list --page <page_id>

# 树形结构显示
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block list --page <page_id> --tree

# 递归列出所有嵌套块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block list --page <page_id> --recursive

# 获取单个块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block get --id <block_id>

# 添加文本块（-t 指定类型，-c 指定内容）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t paragraph -c "段落内容"

# 添加标题
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_1 -c "一级标题"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_2 -c "二级标题"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_3 -c "三级标题"

# 添加列表项
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t bulleted_list_item -c "无序列表项"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t numbered_list_item -c "有序列表项"

# 添加待办事项
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t to_do -c "待办事项"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t to_do -c "已完成" --checked

# 添加代码块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t code -c "print('hello')" -l python

# 添加引用块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t quote -c "引用内容"

# 添加 callout 块（带图标）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t callout -c "提示内容" --icon 💡

# 添加分割线
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t divider

# 在指定块之后插入
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t paragraph -c "新段落" --after <block_id>

# 添加多个同类型块（内容用位置参数传入）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-multiple --page <page_id> -t bulleted_list_item \
  "第一项" "第二项" "第三项"

# 添加表格（--width/-w 指定列数，--rows/-r 传 JSON 数据）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-table --page <page_id> -w 3 --header-row \
  -r '[["列1","列2","列3"],["值1","值2","值3"]]'

# 更新块内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block update --id <block_id> -c "新内容"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block update --id <block_id> --color blue
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block update --id <block_id> --checked true

# 删除块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block delete --id <block_id>
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block delete --id <block_id> --yes

支持的块类型

ToDo 块操作

# 列出页面中的所有待办事项（仅未完成）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo list --page <page_id>

# 列出所有待办（含已完成）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo list --page <page_id> --all

# 添加待办事项
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo add --page <page_id> -t "待办内容"

# 添加已勾选的待办
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo add --page <page_id> -t "已完成事项" --checked

# 勾选待办（标记完成）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo check --id <block_id>

# 取消勾选
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo uncheck --id <block_id>

媒体块操作

# 添加图片
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block media add --page <page_id> -t image -u "https://example.com/image.png"

# 添加视频
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block media add --page <page_id> -t video -u "https://example.com/video.mp4"

# 添加文件/PDF
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block media add --page <page_id> -t file -u "https://example.com/doc.pdf"

# 带说明的媒体
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block media add --page <page_id> -t image \
  -u "https://example.com/image.png" -c "图片说明"

媒体类型支持：image, video, audio, file, pdf

导出页面

# 导出为 Markdown（默认）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id>

# 导出为 JSON
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> -f json

# 导出为纯文本
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> -f text

# 保存到文件
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> -o ./output.md

# 递归导出（含子块）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> -r

# 不递归
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> --no-recursive

终端预览

# 在终端中查看页面内容（带语法高亮）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli view --page <page_id>

配置管理

# 设置 Token
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli config set-token

# 查看当前配置
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli config show

# 清除 Token
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli config clear

# 显示配置文件路径
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli config path

工作区设置（高级）

使用浏览器 token_v2 进行批量设置操作：

# 列出所有顶级页面（需要 token_v2）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli setup list-pages

# 列出可用的 Integration
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli setup list-bots

# 批量添加 Integration 访问权限
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli setup add-connection --bot-id <bot_id>

# 查看 Token 信息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli setup token-info

请求映射

当用户请求时：

1. "搜索 Notion" → 使用 search 命令
2. "查找笔记" → 使用 search 命令
3. "列出数据库" → 使用 database list 命令
4. "查看数据库内容" → 使用 database rows --id 或 database query --id 命令
5. "添加数据库记录" → 使用 database add-row --id 命令
6. "创建页面" → 使用 page create 命令
7. "编辑页面" → 使用 block add/update 命令
8. "添加待办事项" → 使用 block todo add --page 命令
9. "导出笔记" → 使用 export --page 命令
10. "查看页面内容" → 使用 view --id 或 export --page -f markdown 命令
11. "设置 Notion Token" → 使用 config set-token 命令

$ARGUMENTS 包含用户的具体请求，解析后决定运行哪个命令。

ID 格式说明

Notion 的 ID 支持两种格式：

• 完整格式：12345678-1234-1234-1234-123456789abc
• 短格式：123456781234123412341234567890abc

从 Notion URL 获取 ID：

• 页面 URL：https://www.notion.so/Title-<page_id>
• 数据库 URL：https://www.notion.so/<database_id>?v=...

常见使用场景和工作流

场景 1：写文章/创建文档

用户需求："在 Notion 中写一篇文章关于 XXX"

# 1. 搜索合适的父页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "博客" --filter page

# 2. 创建新页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page create --title "文章标题" --parent <parent_id>

# 3. 添加文章结构和内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_1 -c "引言"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t paragraph -c "文章开头..."
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_2 -c "第一部分"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t paragraph -c "详细内容..."
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t divider
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t quote -c "重要引用"

# 4. 添加代码示例（如果需要）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t code -c "代码内容" -l python

场景 2：修改/编辑现有文章

用户需求："修改 Notion 中关于 XXX 的文章"

# 1. 搜索要修改的文章
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "文章关键词" --filter page

# 2. 查看当前内容（了解结构）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli view --page <page_id>
# 或导出为 Markdown 查看
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> -f markdown

# 3. 列出所有块（获取 block_id）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block list --page <page_id>

# 4. 更新特定块的内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block update --id <block_id> -c "更新后的内容"

# 5. 在特定位置添加新内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t paragraph -c "新增段落"

# 6. 删除不需要的块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block delete --id <block_id>

场景 3：管理待办事项

用户需求："在 Notion 中记录待办事项"

# 1. 找到或创建待办页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "待办" --filter page
# 如果没有，创建新页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page create --title "待办清单" --parent <parent_id>

# 2. 添加待办事项
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo add --page <page_id> -t "完成项目报告"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo add --page <page_id> -t "准备会议材料"

# 3. 批量添加待办（位置参数传内容）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-multiple --page <page_id> -t to_do \
  "任务1" "任务2" "任务3"

# 4. 带分组的待办
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_3 -c "今日任务"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo add --page <page_id> -t "上午：完成设计稿"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo add --page <page_id> -t "下午：编写测试用例"

场景 4：完成/更新待办状态

用户需求："标记 Notion 中的待办为完成"

# 1. 查看当前待办列表
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo list --page <page_id>

# 2. 标记特定待办为完成
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo check --id <block_id>

# 3. 取消完成（重新打开）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo uncheck --id <block_id>

场景 5：项目任务管理（数据库）

用户需求："在任务数据库中添加/更新任务"

# 1. 找到任务数据库
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database list
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "任务" --filter database

# 2. 查看数据库结构（了解属性）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database info --id <database_id>

# 3. 添加新任务
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database add-row --id <database_id> \
  -p "Name=实现新功能" \
  -p "Status:select=Not Started" \
  -p "Priority:select=High" \
  -p "Due:date=2024-12-31"

# 4. 查看当前任务
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database rows --id <database_id> --limit 20

# 5. 更新任务状态
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database update-row --id <row_id> \
  -p "Status:select=In Progress"

# 6. 完成任务
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database update-row --id <row_id> \
  -p "Status:select=Done"

场景 6：会议记录

用户需求："在 Notion 中记录会议纪要"

# 1. 创建会议记录页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page create \
  --title "2024-01-20 产品会议" --parent <meetings_folder_id>

# 2. 添加议程
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_2 -c "议程"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-multiple --page <page_id> -t numbered_list_item \
  "产品路线图回顾" "Q1目标确定" "资源分配讨论"

# 3. 添加讨论内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_2 -c "讨论要点"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t paragraph -c "详细讨论内容..."

# 4. 添加行动项
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_2 -c "行动项"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo add --page <page_id> -t "张三：完成需求文档 - 截止1月25日"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo add --page <page_id> -t "李四：技术评估 - 截止1月22日"

场景 7：周报/日报

用户需求："写周报到 Notion"

# 1. 找到周报数据库或页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "周报" --filter database

# 2. 添加本周周报（数据库条目）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database add-row --id <database_id> \
  -p "Title=2024年第3周周报" \
  -p "Week:date=2024-01-15" \
  -p "Status:select=Draft"

# 3. 获取创建的页面ID并编辑内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_2 -c "本周完成"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-multiple --page <page_id> -t bulleted_list_item \
  "完成用户认证模块" "修复3个生产环境bug" "代码审查5个PR"

cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add --page <page_id> -t heading_2 -c "下周计划"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-multiple --page <page_id> -t numbered_list_item \
  "开始支付模块开发" "性能优化" "编写技术文档"

# 4. 更新状态为已发布
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database update-row --id <row_id> -p "Status:select=Published"

重要提示

配置管理

• Token 存储位置：~/.notion-cli/config.yaml
• 首次使用需运行：notion-cli config set-token
• Token 获取：https://www.notion.so/my-integrations
• 也可通过环境变量 NOTION_TOKEN 设置

执行顺序建议

1. 查找定位：先用 search 或 database list 找到目标
2. 查看结构：用 view --id 或 block list --page 了解现有内容
3. 执行操作：根据需求选择 add/update/delete
4. 验证结果：再次查看确认修改成功

常见组合模式

• 创建文档：search → page create → block add --page 系列
• 编辑内容：search → view --id → block list --page → block update --id
• 任务管理：database list → database rows --id → database add-row/update-row --id
• 待办管理：block todo list --page → block todo add --page / block todo check --id
• 导出备份：search → export --page