vibe-notionbot

Vibe Notionbot

一个 TypeScript 命令行工具，可让 AI Agent 和用户通过官方 Notion API 与 Notion 工作区交互。支持页面、数据库、块、用户、评论和搜索。

使用哪个 CLI

此软件包提供两个 CLI。根据你的情况选择合适的一个：

	vibe-notion	vibe-notionbot（此 CLI）
API	非官方私有 API	官方 Notion API
身份验证	从 Notion 桌面应用自动提取 token_v2	NOTION_TOKEN 环境变量（Integration 令牌）
身份	以用户身份操作	以机器人身份操作
设置	无需设置——自动提取凭据	手动设置——在 notion.so/my-integrations 创建 Integration
数据库行	add-row、update-row	通过 page create --database 创建
视图管理	view-get、view-update、view-list、view-add、view-delete	不支持
工作区列表	支持	不支持
稳定性	私有 API——Notion 变更时可能失效	官方版本化 API——稳定

选择流程：

1. 如果已安装 Notion 桌面应用 → 使用 vibe-notion
2. 如果已设置 NOTION_TOKEN，但没有桌面应用 → 使用 vibe-notionbot（此 CLI）
3. 如果两者都可用 → 优先使用 vibe-notion（功能更全面，且无需设置）
4. 如果两者都不可用 → 请用户设置其中一种

重要：仅使用 CLI

绝不要直接调用 Notion API。 始终使用此技能中介绍的 vibe-notionbot CLI 命令。不要向 Notion API 发送原始 HTTP 请求，也不要直接使用 @notionhq/client。直接调用 API 可能会泄露凭据，并触发 Notion 的滥用检测，导致用户账号被封禁。

如果 vibe-notionbot 不支持你需要的功能，请告知用户，并提出代表他们在 devxoul/vibe-notion 提交功能请求。提交前，请删除所有真实用户数据——ID、姓名、邮箱、令牌、页面内容，以及任何其他可用于识别用户或其工作区的信息。改用通用占位符，并聚焦描述缺少的功能。

重要：绝不编写脚本

绝不要编写脚本（Python、TypeScript、Bash 等）来自动执行 Notion 操作。 batch 命令已能处理任意规模的批量操作。编写脚本循环调用 API 总是不对的——请改用带 --file 的 batch。

以下情况也适用：

• 需要创建 100 行或页面以上
• 需要在新创建的项目之间建立交叉引用（使用多轮 batch——参见批量操作策略）
• 操作看起来“太大”，无法用单条命令完成

如果你发现自己在想“我应该为此编写一个脚本”，请停下来改用 batch。

快速开始

# Check authentication status
vibe-notionbot auth status

# Search for a page or database
vibe-notionbot search "Project Roadmap"

# List all databases
vibe-notionbot database list

# Create a new page
vibe-notionbot page create --parent <parent_id> --title "My New Page"

身份验证

Integration 令牌（官方 API）

在 NOTION_TOKEN 环境变量中设置从 Notion Developer Portal 获取的 Integration 令牌。

export NOTION_TOKEN=secret_xxx
vibe-notionbot auth status

Integration 令牌可访问官方 Notion API（@notionhq/client）。

命令

页面命令

# Retrieve a page
vibe-notionbot page get <page_id>

# Create a new page under a parent page or database
vibe-notionbot page create --parent <parent_id> --title "New Page Title"
vibe-notionbot page create --parent <database_id> --title "New Database Item" --database

# Create a page with markdown content
vibe-notionbot page create --parent <parent_id> --title "My Doc" --markdown '# Hello\n\nThis is **bold** text.'

# Create a page with markdown from a file
vibe-notionbot page create --parent <parent_id> --title "My Doc" --markdown-file ./content.md

# Create a page with markdown containing local images (auto-uploaded to Notion)
vibe-notionbot page create --parent <parent_id> --title "My Doc" --markdown-file ./doc-with-images.md

# Update page properties
vibe-notionbot page update <page_id> --set "Status=In Progress" --set "Priority=High"

# Replace all content on a page with new markdown
vibe-notionbot page update <page_id> --replace-content --markdown '# New Content'
vibe-notionbot page update <page_id> --replace-content --markdown-file ./updated.md

# Archive (delete) a page
vibe-notionbot page archive <page_id>

# Retrieve a specific page property
vibe-notionbot page property <page_id> <property_id>

数据库命令

# Retrieve a database schema
vibe-notionbot database get <database_id>

# Query a database with optional filters and sorts
vibe-notionbot database query <database_id> --filter '{"property": "Status", "select": {"equals": "In Progress"}}'
vibe-notionbot database query <database_id> --sort '[{"property": "Created time", "direction": "descending"}]'
vibe-notionbot database query <database_id> --page-size 10 --start-cursor <cursor>

# Create a database under a parent page
vibe-notionbot database create --parent <page_id> --title "My Database" --properties '{"Name": {"title": {}}}'

# Update a database schema or title
vibe-notionbot database update <database_id> --title "Updated Title"
vibe-notionbot database update <database_id> --properties '{"Status": {"select": {"options": [{"name": "Active"}, {"name": "Archived"}]}}}'
vibe-notionbot database update <database_id> --title "Updated Title" --properties '{"Status": {"select": {}}}'

# Delete a property from a database
vibe-notionbot database delete-property <database_id> --property "Status"

# List all databases accessible by the integration
vibe-notionbot database list
vibe-notionbot database list --page-size 10 --start-cursor <cursor>

块命令

# Retrieve a block
vibe-notionbot block get <block_id>

# List direct children of a block (paginated)
vibe-notionbot block children <block_id>
vibe-notionbot block children <block_id> --page-size 50 --start-cursor <cursor>

# Append child blocks to a parent
vibe-notionbot block append <parent_id> --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Hello World"}}]}}]'

# Append markdown content as blocks
vibe-notionbot block append <parent_id> --markdown '# Hello\n\nThis is **bold** text.'

# Append markdown from a file
vibe-notionbot block append <parent_id> --markdown-file ./content.md

# Append markdown with local images (auto-uploaded to Notion)
vibe-notionbot block append <parent_id> --markdown-file ./doc-with-images.md

# Append nested markdown (indented lists become nested children blocks)
vibe-notionbot block append <parent_id> --markdown '- Parent item\n  - Child item\n    - Grandchild item'

# Append blocks after a specific block (positional insertion)
vibe-notionbot block append <parent_id> --after <block_id> --markdown '# Inserted after specific block'
vibe-notionbot block append <parent_id> --after <block_id> --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Inserted after"}}]}}]'

# Append blocks before a specific block
vibe-notionbot block append <parent_id> --before <block_id> --markdown '# Inserted before specific block'

# Update a block's content
vibe-notionbot block update <block_id> --content '{"paragraph": {"rich_text": [{"type": "text", "text": {"content": "Updated content"}}]}}'

# Delete (archive) a block
vibe-notionbot block delete <block_id>

# Upload a file as a block (image or file block)
vibe-notionbot block upload <parent_id> --file ./image.png --pretty
vibe-notionbot block upload <parent_id> --file ./document.pdf --pretty
vibe-notionbot block upload <parent_id> --file ./image.png --after <block_id> --pretty
vibe-notionbot block upload <parent_id> --file ./image.png --before <block_id> --pretty

用户命令

# List all users in the workspace
vibe-notionbot user list
vibe-notionbot user list --page-size 10 --start-cursor <cursor>

# Get info for a specific user
vibe-notionbot user get <user_id>

# Get info for the current bot/integration
vibe-notionbot user me

搜索命令

# Search across the entire workspace
vibe-notionbot search "query text"

# Filter search by object type
vibe-notionbot search "Project" --filter page
vibe-notionbot search "Tasks" --filter database

# Sort search results
vibe-notionbot search "Meeting" --sort desc

# Paginate search results
vibe-notionbot search "Notes" --page-size 10 --start-cursor <cursor>

评论命令

# List comments on a page
vibe-notionbot comment list --page <page_id>
vibe-notionbot comment list --page <page_id> --page-size 10 --start-cursor <cursor>

# List inline comments on a specific block
vibe-notionbot comment list --block <block_id>

# Create a comment on a page
vibe-notionbot comment create "This is a comment" --page <page_id>

# Reply to a comment thread (discussion)
vibe-notionbot comment create "Replying to thread" --discussion <discussion_id>

# Retrieve a specific comment
vibe-notionbot comment get <comment_id>

批量操作

在一次 CLI 调用中运行多个写入操作。当你需要一次创建、更新或删除多个项目时，请使用此方式，而不是重复调用 CLI。可节省令牌并减少往返次数。

# Inline JSON (no --workspace-id needed, uses NOTION_TOKEN)
vibe-notionbot batch '<operations_json>'

# From file (for large payloads)
vibe-notionbot batch --file ./operations.json '[]'

支持的操作（共 11 种）：

操作	说明
page.create	创建页面
page.update	更新页面属性
page.archive	归档页面
block.append	向父级追加区块
block.update	更新区块
block.delete	删除区块
comment.create	创建评论
database.create	创建数据库
database.update	更新数据库标题或架构
database.delete-property	删除数据库属性
block.upload	将文件上传为图片或文件区块

操作格式：每个操作都是一个包含 action 和传给单项命令处理器的相同字段的对象。混合操作示例：

[
  {"action": "page.create", "parent": "<parent_id>", "title": "Meeting Notes"},
  {"action": "block.append", "parent_id": "<page_id>", "markdown": "# Agenda\n\n- Item 1\n- Item 2"},
  {"action": "comment.create", "content": "Page created via batch", "page": "<page_id>"}
]

输出格式：

{
  "results": [
    {"index": 0, "action": "page.create", "success": true, "data": {"id": "page-uuid", "...": "..."}},
    {"index": 1, "action": "block.append", "success": true, "data": {"...": "..."}},
    {"index": 2, "action": "comment.create", "success": true, "data": {"id": "comment-uuid", "...": "..."}}
  ],
  "total": 3,
  "succeeded": 3,
  "failed": 0
}

快速失败行为：操作按顺序运行。如果任何操作失败，执行会立即停止。输出将包含所有已完成操作以及失败操作的结果。失败时进程以代码 1 退出，成功时以代码 0 退出。

{
  "results": [
    {"index": 0, "action": "page.create", "success": true, "data": {"...": "..."}},
    {"index": 1, "action": "block.append", "success": false, "error": "Block not found"}
  ],
  "total": 3,
  "succeeded": 1,
  "failed": 1
}

批量操作策略

对于大型操作（数十或数百个项目），使用 --file 以避免 shell 参数长度限制，并便于管理。

步骤 1：将操作 JSON 写入文件，然后使用 --file 运行批处理：

# Write operations to a file (using your Write tool), then:
vibe-notionbot batch --file ./operations.json '[]'

多轮处理模式 — 当新项目需要相互引用时（例如，某个页面属性链接到另一个新建页面）：

1. 第 1 轮 — 创建所有项目（不添加交叉引用）：创建包含所有创建操作的批处理 JSON 文件，并省略指向其他新建项目的属性。运行该文件，并从输出中收集返回的 ID。
2. 第 2 轮 — 设置交叉引用：创建第二个包含更新操作的批处理 JSON 文件，使用第 1 轮返回的 ID 设置引用属性。运行该文件。

Pass 1: Create items A, B, C (no cross-refs) → get IDs for A, B, C
Pass 2: Update A.related=B, C.parent_ref=A (using real IDs from Pass 1)

这与使用脚本达到的效果相同，但无需编写任何代码。只需调用两次批处理命令。

速率限制

Notion 会对其 API 实施速率限制。批量操作按顺序运行，因此大型批次（30 个及以上操作）可能会触发 429 Too Many Requests 错误。为避免此情况：

将大型批次拆分为多个区块，每次批处理调用约处理 25–30 个操作 如果批次中途因 429 失败，只需重新运行尚未处理的操作 batch 输出会显示失败前哪些操作已成功；使用 index 字段确定从哪里继续

输出格式

JSON（默认）

所有命令默认输出 JSON，便于 AI 使用：

{
  "id": "...",
  "object": "page",
  "properties": { ... }
}

美化格式（便于阅读）

使用 --pretty 标志输出格式化内容：

vibe-notionbot search "Project" --pretty

错误处理

Notion API 的常见错误：

• object_not_found：ID 不正确，或集成无权访问。
• unauthorized：NOTION_TOKEN 无效。
• rate_limited：请求过多。

故障排除

vibe-notionbot: command not found

未安装 vibe-notion 包。使用包运行器直接运行。询问用户要使用哪一种：

npx -y -p vibe-notion vibe-notionbot ...
bunx -p vibe-notion vibe-notionbot ...
pnpm dlx --package vibe-notion vibe-notionbot ...

如果你已了解用户偏好的包运行器，请直接使用，而无需询问。

限制

• 支持 Notion API 版本 2025-09-03。
• 不支持 OAuth（仅支持令牌）。
• 支持通过 block upload 上传文件。
• 页面属性更新仅支持通过 --set 设置简单的键值对。