Notion CLI Skill

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

命令前缀

所有命令使用 uv run 执行：

bash

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：

bash

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

命令参考

搜索

bash

# 搜索所有内容（页面和数据库）
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "关键词"

# 仅搜索页面
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

页面操作

bash

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

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

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

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

数据库操作

bash

# 列出所有可访问的数据库
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database list

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

# 查询数据库
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database query <database_id>
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database query <database_id> --limit 10

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

# 添加数据库行
# 格式：-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 get-row <row_id>

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

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

属性类型参考

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

类型	格式	示例
文本	`属性名=值`	`-p "Name=任务"`
数字	`属性名:number=值`	`-p "Age:number=30"`
选择	`属性名:select=值`	`-p "Status:select=Done"`
多选	`属性名:multi_select=值1,值2`	`-p "Tags:multi_select=Work,Urgent"`
复选框	`属性名:checkbox=true/false`	`-p "Done:checkbox=true"`
日期	`属性名:date=YYYY-MM-DD`	`-p "Due:date=2024-12-31"`
URL	`属性名:url=链接`	`-p "Link:url=https://example.com"`
邮箱	`属性名:email=地址`	`-p "Email:email=test@example.com"`

内容块操作

bash

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

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

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

# 添加文本块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add <page_id> --type paragraph --content "段落内容"

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

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

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

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

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

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

# 添加多个块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-multiple <page_id> --type bulleted_list_item \
  --content "第一项" --content "第二项" --content "第三项"

# 添加表格
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-table <page_id> \
  --columns 3 --header \
  --data "列1,列2,列3" --data "值1,值2,值3"

# 更新块内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block update <block_id> --content "新内容"

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

支持的块类型

类别	类型
文本	`paragraph`, `heading_1`, `heading_2`, `heading_3`
列表	`bulleted_list_item`, `numbered_list_item`, `to_do`, `toggle`
特殊	`quote`, `callout`, `code`, `equation`, `divider`
媒体	`image`, `video`, `audio`, `file`, `pdf`, `bookmark`, `embed`
结构	`table`, `table_of_contents`, `breadcrumb`

ToDo 块操作

bash

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

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

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

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

媒体块操作

bash

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

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

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

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

导出页面

bash

# 导出为 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> --format json

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

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

# 不包含嵌套块
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> --no-recursive

终端预览

bash

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

配置管理

bash

# 设置 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 进行批量设置操作：

bash

# 列出所有顶级页面（需要 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

请求映射

当用户请求时：

•"搜索 Notion" → 使用 search 命令
•"查找笔记" → 使用 search 命令
•"列出数据库" → 使用 database list 命令
•"查看数据库内容" → 使用 database rows 或 database query 命令
•"添加数据库记录" → 使用 database add-row 命令
•"创建页面" → 使用 page create 命令
•"编辑页面" → 使用 block add/update 命令
•"添加待办事项" → 使用 block todo add 命令
•"导出笔记" → 使用 export 命令
•"查看页面内容" → 使用 view 或 export --format markdown 命令
•"设置 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"

执行步骤：

bash

# 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 --parent <parent_id> --title "文章标题"

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

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

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

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

执行步骤：

bash

# 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_id>
# 或导出为 Markdown 查看
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> --format markdown

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

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

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

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

场景 3：管理待办事项（ToDo List）

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

执行步骤：

bash

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

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

# 3. 批量添加待办
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-multiple <page_id> --type to_do \
  --content "任务1" --content "任务2" --content "任务3"

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

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

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

执行步骤：

bash

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

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

# 3. 批量完成多个待办
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo check <block_id_1>
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block todo check <block_id_2>

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

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

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

执行步骤：

bash

# 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 <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 "Assignee:select=张三" \
  -p "Due:date=2024-12-31" \
  -p "Estimate:number=8"

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

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

# 6. 完成任务
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database update-row <row_id> \
  -p "Status:select=Done" \
  -p "Progress:number=100" \
  -p "Completed:date=2024-01-20"

场景 6：会议记录

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

执行步骤：

bash

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

# 2. 添加会议信息
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add <page_id> --type callout --content "📅 时间：2024-01-20 14:00-15:00\n📍 地点：会议室A\n👥 参会人：张三、李四、王五"

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

# 4. 添加讨论内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add <page_id> --type heading_2 --content "讨论要点"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add <page_id> --type toggle --content "产品路线图"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add <page_id> --type paragraph --content "详细讨论内容..."

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

场景 7：知识库管理

用户需求："整理 Notion 知识库"

执行步骤：

bash

# 1. 搜索相关内容
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli search "技术文档" --limit 20

# 2. 创建分类页面
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli page create --parent <kb_root_id> --title "前端技术栈"

# 3. 添加目录结构
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add <page_id> --type table_of_contents

# 4. 创建子页面链接
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add <page_id> --type bookmark --url "notion://..."

# 5. 导出备份
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli export --page <page_id> --format markdown --output ./kb_backup.md

场景 8：周报/日报

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

执行步骤：

bash

# 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_id> --type heading_2 --content "本周完成"
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli block add-multiple <page_id> --type bulleted_list_item \
  --content "✅ 完成用户认证模块" \
  --content "✅ 修复3个生产环境bug" \
  --content "✅ 代码审查5个PR"

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

# 4. 更新状态为已完成
cd ${CLAUDE_PLUGIN_ROOT}/src && uv run notion-cli database update-row <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 设置

执行顺序建议

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

常见组合模式

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