vibe-notion

Vibe Notion

一个 TypeScript 命令行工具，可让 AI Agent 和用户通过非官方私有 API 与 Notion 工作区交互。支持对页面、数据库、内容块进行完整的增删改查，以及搜索和用户管理。

注意：此技能使用 Notion 的内部／私有 API（/api/v3/），它与官方公共 API 相互独立。如需访问官方 API，请使用 vibe-notionbot。

选择使用哪个命令行工具

此软件包提供两个命令行工具。请根据你的情况选择合适的工具：

	vibe-notion（此命令行工具）	vibe-notionbot
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
3. 如果两者都可用 → 优先使用 vibe-notion（功能更全面，无需设置）
4. 如果两者都不可用 → 请用户设置其中一种

重要：只能使用命令行工具

绝不要直接调用 Notion 的内部 API。 始终使用此技能中介绍的 vibe-notion 命令行工具命令。不要向 notion.so/api/v3/ 发送原始 HTTP 请求，也不要使用任何 Notion 客户端库。直接调用 API 有暴露凭据的风险，还可能触发 Notion 的滥用检测，导致用户账号被封禁。

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

重要：绝不要编写脚本

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

以下情况也同样适用：

• 你需要创建 100 行以上的数据
• 你需要在新创建的行之间建立交叉引用（使用多轮 batch — 参见 references/batch-operations.md）
• 操作看起来“太庞大”，无法通过单个命令完成

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

快速开始

# 1. Find your workspace ID
vibe-notion workspace list --pretty

# 2. Search for a page
vibe-notion search "Roadmap" --workspace-id <workspace-id> --pretty

# 3. Get page content
vibe-notion page get <page-id> --workspace-id <workspace-id> --pretty

# 4. Query a database
vibe-notion database query <collection-id> --workspace-id <workspace-id> --pretty

首次使用时，会从 Notion 桌面应用自动提取凭据。无需手动设置。

提示：对于大多数需要指定目标页面／内容块／数据库 ID 的命令，现在可以省略 --workspace-id。省略时，系统会探测每个已通过身份验证的账号并自动解析工作区 ID。没有主要目标的命令仍必须指定此标志 — page list、database list、search、user list、user get、database create --parent（根级）、不带 --parent 的 page create、batch，以及 comment get／comment create --discussion。使用 vibe-notion workspace list 查找工作区 ID，或使用 vibe-notion workspace resolve <page_id_or_url> 直接从 Notion URL 查询工作区 ID。

身份验证

运行任意命令时，都会从 Notion 桌面应用中自动提取凭据（token_v2）。无需 API 密钥、OAuth 或手动提取。

在 macOS 上，首次使用时，系统可能会提示你授权访问钥匙串——这是正常情况，也是解密 Cookie 所必需的。

提取的 token_v2 会以 0600 权限存储在 ~/.config/vibe-notion/credentials.json。设置 VIBE_NOTION_CONFIG_DIR 环境变量即可使用自定义配置目录。

记忆

Agent 会将 ~/.config/vibe-notion/MEMORY.md 文件用作跨会话持久记忆。该文件由 Agent 管理——CLI 不会读取或写入此文件。请使用 Read 和 Write 工具管理记忆文件。

读取记忆

每项任务开始时，都使用 Read 工具读取 ~/.config/vibe-notion/MEMORY.md，以加载此前发现的工作区 ID、页面 ID、数据库 ID 和用户偏好。

• 如果文件尚不存在，无妨——继续执行，并在首次获得值得保存的信息时创建文件。
• 如果无法读取文件（权限问题或目录不存在），则不使用记忆继续执行——不要报错退出。

写入记忆

发现有用信息后，使用 Write 工具更新 ~/.config/vibe-notion/MEMORY.md。以下情况应写入记忆：

• 发现工作区 ID 后（通过 workspace list）
• 发现有用的页面 ID、数据库 ID、集合 ID 后（通过 search、page list、page get、database list 等）
• 用户提供别名或偏好后（例如“把它称为 Tasks DB”“我的主工作区是 X”）
• 发现页面／数据库结构后（父子关系、哪些数据库位于哪些页面下）

写入时，请包含完整文件内容——Write 工具会覆盖整个文件。

存储内容

• 带名称的工作区 ID
• 带标题和父级上下文的页面 ID
• 带标题和父级上下文的数据库／集合 ID
• 用户提供的别名（“Tasks DB”“主工作区”）
• 常用视图 ID
• 父子关系（哪些数据库位于哪些页面下）
• 交互过程中表达的任何用户偏好

不应存储的内容

切勿存储 token_v2、凭据、API 密钥或任何敏感数据。切勿存储完整页面内容（只存储 ID 和标题）。除非是数据库块等持久引用，否则切勿存储块级 ID。

处理过期数据

如果记忆中的 ID 返回错误（页面不存在、访问被拒绝），请从 MEMORY.md 中删除该 ID。不要盲目信任记忆中的数据——发现异常时应进行验证。优先重新搜索，而不是使用可能已过期的记忆 ID。

格式／示例

下面是 MEMORY.md 的具体结构示例：

# Vibe Notion Memory

## Workspaces

- `abc123-...` — Acme Corp (default)

## Pages (Acme Corp)

- `page-id-1` — Product Roadmap (top-level)
- `page-id-2` — Q1 Planning (under Product Roadmap)

## Databases (Acme Corp)

- `coll-id-1` — Tasks (under Product Roadmap, views: `view-1`)
- `coll-id-2` — Contacts (top-level)

## Aliases

- "roadmap" → `page-id-1` (Product Roadmap)
- "tasks" → `coll-id-1` (Tasks database)

## Notes

- User prefers --pretty output for search results
- Main workspace is "Acme Corp"

记忆可让你跳过重复的 search 和 workspace list 调用。如果你已在之前的会话中获知某个 ID，请直接使用。

命令

身份验证命令

vibe-notion auth status     # Check authentication status
vibe-notion auth logout     # Remove stored token_v2
vibe-notion auth extract    # Manually re-extract token_v2 (for troubleshooting)

页面命令

# List pages in a space (top-level only)
vibe-notion page list --workspace-id <workspace_id> --pretty
vibe-notion page list --workspace-id <workspace_id> --depth 2 --pretty

# Get a page and all its content blocks
vibe-notion page get <page_id> --workspace-id <workspace_id> --pretty
vibe-notion page get <page_id> --workspace-id <workspace_id> --limit 50
vibe-notion page get <page_id> --workspace-id <workspace_id> --backlinks --pretty

# Create a new page (--parent is optional; omit to create at workspace root)
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Page" --pretty
vibe-notion page create --workspace-id <workspace_id> --title "New Root Page" --pretty


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

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

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

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

# Update page title or icon
vibe-notion page update <page_id> --workspace-id <workspace_id> --title "New Title" --pretty
vibe-notion page update <page_id> --workspace-id <workspace_id> --icon "🚀" --pretty

# Archive a page
vibe-notion page archive <page_id> --workspace-id <workspace_id> --pretty

# Get page or database row properties (without content blocks — lightweight alternative to page get)
vibe-notion page properties <page_id> --workspace-id <workspace_id> --pretty

数据库命令

# Get database schema
vibe-notion database get <database_id> --workspace-id <workspace_id> --pretty

# Query a database (auto-resolves default view)
vibe-notion database query <database_id> --workspace-id <workspace_id> --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --limit 10 --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --view-id <view_id> --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --search-query "keyword" --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --timezone "America/New_York" --pretty

# Query with filter and sort (uses property IDs from database get schema)
vibe-notion database query <database_id> --workspace-id <workspace_id> --filter '<filter_json>' --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --sort '<sort_json>' --pretty

# List all databases in workspace
vibe-notion database list --workspace-id <workspace_id> --pretty

# Create a database
vibe-notion database create --workspace-id <workspace_id> --parent <page_id> --title "Tasks" --pretty
vibe-notion database create --workspace-id <workspace_id> --parent <page_id> --title "Tasks" --properties '{"status":{"name":"Status","type":"select"}}' --pretty

# Update database title or schema
vibe-notion database update <database_id> --workspace-id <workspace_id> --title "New Name" --pretty
vibe-notion database update <database_id> --workspace-id <workspace_id> --properties '{"status":{"name":"Status","type":"select"}}' --pretty
vibe-notion database update <database_id> --workspace-id <workspace_id> --title "New Name" --properties '{"status":{"name":"Status","type":"select"}}' --pretty

# Add a row to a database
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Row title" --pretty
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Row title" --properties '{"Status":"In Progress","Due":{"start":"2025-03-01"}}' --pretty

# Add row with date range
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Event" --properties '{"Due":{"start":"2026-01-01","end":"2026-01-15"}}' --pretty

# Update properties on an existing database row (row_id from database query)
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Status":"Done"}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Priority":"High","Tags":["backend","infra"]}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Due":{"start":"2026-06-01"},"Status":"In Progress"}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Due":{"start":"2026-01-01","end":"2026-01-15"}}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Related":["<target_row_id>"]}' --pretty

# Delete a property from a database (cannot delete the title property)
vibe-notion database delete-property <database_id> --workspace-id <workspace_id> --property "Status" --pretty

# Get view configuration and property visibility
vibe-notion database view-get <view_id> --workspace-id <workspace_id> --pretty

# Show or hide properties on a view (comma-separated names)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --show "ID,Due" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --hide "Assignee" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --show "Status" --hide "Due" --pretty

# Reorder columns (comma-separated names in desired order; unmentioned columns appended)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --reorder "Name,Status,Priority,Date" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --reorder "Name,Status" --show "Status" --pretty

# Resize columns (JSON mapping property names to pixel widths)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --resize '{"Name":200,"Status":150}' --pretty

# List all views for a database
vibe-notion database view-list <database_id> --workspace-id <workspace_id> --pretty

# Add a new view to a database (default type: table)
vibe-notion database view-add <database_id> --workspace-id <workspace_id> --pretty
vibe-notion database view-add <database_id> --workspace-id <workspace_id> --type board --name "Board View" --pretty

# Delete a view from a database (cannot delete the last view)
vibe-notion database view-delete <view_id> --workspace-id <workspace_id> --pretty

表格命令

简单表格（非数据库）——嵌入页面的轻量级表格。

# Create a simple table with headers and optional rows
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "Name,Role,Score" --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "Name,Role,Score" --rows '[["Alice","Dev","95"],["Bob","PM","88"]]' --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "A,B" --after <block_id> --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "A,B" --before <block_id> --pretty

# Add a row to a simple table
vibe-notion table add-row <table_id> --workspace-id <workspace_id> --cells "Charlie,QA,92" --pretty

# Update a single cell (row and col are 0-indexed, excluding header row)
vibe-notion table update-cell <table_id> --workspace-id <workspace_id> --row 0 --col 1 --value "Lead" --pretty

# Delete a row (0-indexed, excluding header row)
vibe-notion table delete-row <table_id> --workspace-id <workspace_id> --row 0 --pretty

简单表格与数据库：简单表格是内嵌的轻量级网格，不包含架构、筛选器或视图。对于具有类型化属性、筛选和排序功能的结构化数据，请使用 database 命令。

块命令

# Get a specific block
vibe-notion block get <block_id> --workspace-id <workspace_id> --pretty
vibe-notion block get <block_id> --workspace-id <workspace_id> --backlinks --pretty

# List child blocks
vibe-notion block children <block_id> --workspace-id <workspace_id> --pretty
vibe-notion block children <block_id> --workspace-id <workspace_id> --limit 50 --pretty
vibe-notion block children <block_id> --workspace-id <workspace_id> --start-cursor '<next_cursor_json>' --pretty

# Append child blocks
vibe-notion block append <parent_id> --workspace-id <workspace_id> --content '[{"type":"text","properties":{"title":[["Hello world"]]}}]' --pretty

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

# Append markdown from a file
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown-file ./content.md

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

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

# Append blocks after a specific block (positional insertion)
vibe-notion block append <parent_id> --workspace-id <workspace_id> --after <block_id> --markdown '# Inserted after specific block'
vibe-notion block append <parent_id> --workspace-id <workspace_id> --after <block_id> --content '[{"type":"text","properties":{"title":[["Inserted after"]]}}]'

# Append blocks before a specific block
vibe-notion block append <parent_id> --workspace-id <workspace_id> --before <block_id> --markdown '# Inserted before specific block'

# Update a block
vibe-notion block update <block_id> --workspace-id <workspace_id> --content '{"properties":{"title":[["Updated text"]]}}' --pretty

# Delete a block
vibe-notion block delete <block_id> --workspace-id <workspace_id> --pretty

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

# Move a block to a new position
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --pretty
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --after <sibling_id> --pretty
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --before <sibling_id> --pretty

块类型与富文本参考

有关块类型 JSON 格式（标题、文本、列表、待办事项、代码、引用、分隔线）和富文本格式代码，请参阅 references/block-types.md。

评论命令

# List comments on a page
vibe-notion comment list --page <page_id> --workspace-id <workspace_id> --pretty

# List inline comments on a specific block
vibe-notion comment list --page <page_id> --block <block_id> --workspace-id <workspace_id> --pretty

# Create a comment on a page (starts a new discussion)
vibe-notion comment create "This is a comment" --page <page_id> --workspace-id <workspace_id> --pretty

# Reply to an existing discussion thread
vibe-notion comment create "Replying to thread" --discussion <discussion_id> --workspace-id <workspace_id> --pretty

# Get a specific comment by ID
vibe-notion comment get <comment_id> --workspace-id <workspace_id> --pretty

批量操作

有关批量命令格式、支持的操作（共 14 种）、操作 JSON 结构、输出格式、快速失败行为、批量操作策略（多轮模式）和速率限制处理，请参阅 references/batch-operations.md。

快速用法：

# Inline JSON
vibe-notion batch --workspace-id <workspace_id> '<operations_json>'

# From file (for large payloads)
vibe-notion batch --workspace-id <workspace_id> --file ./operations.json '[]'

搜索命令

# Search across workspace (--workspace-id is required)
vibe-notion search "query" --workspace-id <workspace_id> --pretty
vibe-notion search "query" --workspace-id <workspace_id> --limit 10 --pretty
vibe-notion search "query" --workspace-id <workspace_id> --start-cursor <offset> --pretty
vibe-notion search "query" --workspace-id <workspace_id> --sort lastEdited --pretty

工作区命令

# List all workspaces accessible to the current user (members and guests)
vibe-notion workspace list --pretty

# Resolve the workspace ID that owns a page, block, database, or view.
# Accepts either a raw ID or a full Notion URL — the page ID is extracted from
# the URL path automatically. Useful when you only have a Notion URL and need
# to find the --workspace-id to use for other commands.
vibe-notion workspace resolve <page_id_or_url> --pretty

提示：block get、page get、page create 和 page update 的输出现在都包含 space_id 字段，该字段是拥有此页面或块的工作区 ID。后续操作时，可用它确定正确的 --workspace-id。

用户命令

# Get current user info
vibe-notion user me --pretty

# Get a specific user
vibe-notion user get <user_id> --workspace-id <workspace_id> --pretty

# List users in a workspace
vibe-notion user list --workspace-id <workspace_id> --pretty

输出格式

所有命令默认输出 JSON。使用 --pretty 可获得便于阅读的输出。

有关 JSON 响应结构（搜索、数据库查询、页面获取、块获取、反向链接）、$hints 架构警告以及详细示例，请参阅 references/output-format.md。

何时使用 --backlinks

反向链接会显示哪些页面或数据库链接到指定页面。这对高效导航至关重要。

在以下情况下使用 --backlinks：

• 追踪关联：搜索结果看起来像是一个选择选项、枚举值或关联目标（例如计划名称或类别）。反向链接会立即显示通过关联属性引用它的所有行或页面，无需费力寻找父数据库。
• 查找引用：你找到了一个页面，并想知道还有哪些页面提到或链接到它。
• 反向查找：无需查询每个数据库来查找指向某个页面的行，直接在目标页面上使用反向链接即可获取。

示例 — 查找哪些内容使用了特定计划：

# BAD: 15 API calls — search, open empty pages, trace parents, find database, query
vibe-notion search "Enterprise Plan" ...
vibe-notion page get <plan-page-id> ...  # empty
vibe-notion block get <plan-page-id> ...  # find parent
# ... many more calls to discover the database

# GOOD: 2-3 API calls — search, then backlinks on the target
vibe-notion search "Enterprise Plan" ...
vibe-notion page get <plan-page-id> --backlinks --pretty
# → backlinks immediately show all people/rows linked to this plan

分页

返回列表的命令支持通过 has_more、next_cursor 字段进行分页：

• block children：基于游标。将上一条响应中的 next_cursor 值作为 --start-cursor 传入。
• search：基于偏移量。将 next_cursor 值（数字）作为 --start-cursor 传入。
• database query：使用 --limit 控制页面大小。has_more 表示还有更多结果，但私有 API 不支持基于游标的分页；请增大 --limit 以获取更多行。

故障排除

身份验证失败

如果自动提取失败（例如，未安装 Notion 桌面应用或尚未登录），请手动运行提取命令以查看调试输出：

vibe-notion auth extract --debug

这会显示 Notion 目录路径和提取步骤，帮助诊断问题。

提取时数据库被锁定

如果 auth extract 失败并显示：

{"error":"No token_v2 found. Make sure Notion desktop app is installed and logged in."}

并且已安装 Notion 桌面应用且已登录，则 Cookie 数据库可能被正在运行的 Notion 应用锁定。请告知用户完全退出 Notion 桌面应用，然后重试命令。凭据提取完成后，用户可以重新打开 Notion。

vibe-notion: command not found

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

npx -y vibe-notion ...
bunx vibe-notion ...
pnpm dlx vibe-notion ...

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

限制

• 自动提取支持 macOS 和 Linux。尚不支持 Windows DPAPI 解密。
• token_v2 使用非官方内部 API；如果 Notion 对其进行更改，该 API 可能会失效。
• 这是一个私有／非官方 API，Notion 不提供支持。