# Vibe Notionbot TypeScript CLI 工具，使 AI 代理和人类能够通过官方 Notion API 与 Notion 工作区进行交互。支持页面、数据库、块、用户、评论和搜索。 ## 使用哪个 CLI 该软件包附带两个 CLI。根据您的情况选择合适的： | `氛围概念` | `vibe-notionbot`（此 CLI） ---|---|--- 应用程序接口 |非官方私有API |官方概念API 授权 |从 Notion 桌面应用程序自动提取“token_v2” | `NOTION_TOKEN` env var（集成令牌）身份 |作为用户 |充当机器人设置 |零 — 自动提取的凭据 |手动 — 在 notion.so/my-integrations 创建集成数据库行| `添加行`、`更新行` |通过 `page create --database` 创建查看管理 | `视图获取`、`视图更新`、`视图列表`、`视图添加`、`视图删除` |不支持工作空间列表 |支持 |不支持稳定性|私有 API — 可能会因概念更改而中断 |官方版本 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”。 ## 快速入门 # 检查认证状态 vivi-notionbot 身份验证状态 # 搜索页面或数据库 vivi-notionbot 搜索“项目路线图” # 列出所有数据库 vivi-notionbot 数据库列表 # 创建一个新页面 vivi-notionbot page create --parent --title "我的新页面" ## 身份验证 ### 集成令牌（官方API）使用 [Notion 开发者门户]() 中的集成令牌设置“NOTION_TOKEN”环境变量。导出NOTION_TOKEN=secret_xxx vivi-notionbot 身份验证状态集成令牌提供对官方 Notion API (`@notionhq/client`) 的访问。 ## 命令 ### 页面命令 # 检索页面 vivi-notionbot 页面获取 # 在父页面或数据库下创建一个新页面 vivi-notionbot page create --parent --title "新页面标题" vivi-notionbot 页面创建 --parent --title "新数据库项" --database # 创建一个包含 markdown 内容的页面 vivi-notionbot page create --parent --title "My Doc" --markdown '# Hello\n\n这是 **粗体** 文本。' # 从文件创建带有 markdown 的页面 vivi-notionbot 页面创建 --parent --title "我的文档" --markdown-file ./content.md # 创建一个包含本地图像的 markdown 页面（自动上传到 Notion） vivi-notionbot 页面创建 --parent --title "我的文档" --markdown-file ./doc-with-images.md # 更新页面属性 vivi-notionbot 页面更新 --set "Status=In Progress" --set "Priority=High" # 用新的 markdown 替换页面上的所有内容 vivi-notionbot 页面更新 --replace-content --markdown '# 新内容' vivi-notionbot 页面更新 --replace-content --markdown-file ./updated.md # 归档（删除）页面 vivi-notionbot 页面存档 # 检索特定页面属性 vivi-notionbot 页面属性 ### 数据库命令 # 检索数据库模式 vivi-notionbot 数据库获取 # 使用可选的过滤器和排序查询数据库 vivi-notionbot 数据库查询 --filter '{"property": "Status", "select": {"equals": "In Progress"}}' vivi-notionbot 数据库查询 --sort '[{"property": "创建时间", "direction": "降序"}]' vivi-notionbot 数据库查询 --page-size 10 --start-cursor # 在父页面下创建数据库 vivi-notionbot 数据库创建 --parent --title "我的数据库" --properties '{"Name": {"title": {}}}' # 更新数据库架构或标题 vivi-notionbot 数据库更新 --title "更新的标题" vivi-notionbot 数据库更新 --properties '{"Status": {"select": {"options": [{"name": "Active"}, {"name": "Archived"}]}}}' vivi-notionbot 数据库更新 --title "更新的标题" --properties '{"Status": {"select": {}}}' # 从数据库中删除属性 vivi-notionbot 数据库删除属性 --property“状态” # 列出集成可访问的所有数据库 vivi-notionbot 数据库列表 vivi-notionbot 数据库列表 --page-size 10 --start-cursor <光标> ### 块命令 # 检索一个块 vivi-notionbot 块获取 # 列出块的直接子级（分页） vivi-notionbot 块子元素 vivi-notionbot 块子元素 --page-size 50 --start-cursor # 将子块附加到父块 vivi-notionbot 块附加 --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Hello World"}}]}}]' # 将 Markdown 内容作为块附加 vivi-notionbot block append --markdown '# Hello\n\n这是 **粗体** 文本。' # 从文件追加 markdown vivi-notionbot 块附加 --markdown-file ./content.md # 附加 markdown 和本地图像（自动上传到 Notion） vivi-notionbot 块附加 --markdown-file ./doc-with-images.md # 附加嵌套 markdown （缩进列表成为嵌套子块） vivi-notionbot 块附加 --markdown '- 父项\n - 子项\n - 孙项' # 在特定块之后追加块（位置插入） vivi-notionbot block append --after --markdown '# 在特定块之后插入' vivi-notionbot 块附加 --after --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "插入在"}}]}}]' # 在特定块之前追加块 vivi-notionbot block append --before --markdown '# 在特定块之前插入' # 更新块的内容 vivi-notionbot block update --content '{"paragraph": {"rich_text": [{"type": "text", "text": {"content": "更新内容"}}]}}' # 删除（存档）一个块 vivi-notionbot 块删除 # 将文件作为块上传（图像或文件块） vivi-notionbot 块上传 --file ./image.png --pretty vivi-notionbot 块上传 --file ./document.pdf --pretty vivi-notionbot 块上传 --file ./image.png --after --pretty vivi-notionbot 块上传 --file ./image.png --before --pretty ### 用户命令 # 列出工作区中的所有用户 vivi-notionbot 用户列表 vivi-notionbot 用户列表 --page-size 10 --start-cursor <光标> # 获取特定用户的信息 vivi-notionbot 用户获取 # 获取当前机器人/集成的信息 vivi-notionbot 用户我 ### 搜索命令 # 搜索整个工作区 vivi-notionbot 搜索“查询文本” # 按对象类型过滤搜索 vivi-notionbot 搜索“项目”--过滤页面 vivi-notionbot 搜索“任务”--过滤数据库 # 对搜索结果进行排序 vivi-notionbot 搜索“会议”--sort desc # 对搜索结果进行分页 vivi-notionbot 搜索“注释” --page-size 10 --start-cursor <光标> ### 评论命令 # 列出页面上的评论 vivi-notionbot 评论列表 --page vivi-notionbot 评论列表 --page --page-size 10 --start-cursor <光标> # 列出特定块上的内联注释 vivi-notionbot 评论列表 --block # 在页面上创建评论 vivi-notionbot comment create“这是一条评论”--page # 回复评论线程（讨论） vivi-notionbot 评论创建“回复主题”--discussion # 检索特定评论 vivi-notionbot 评论获取 ## 批量操作在单个 CLI 调用中运行多个写入操作。当您需要一次创建、更新或删除多个内容时，请使用此方法，而不是重复调用 CLI。节省令牌并减少往返。 # 内联 JSON（不需要 --workspace-id，使用 NOTION_TOKEN） vivi-notionbot 批处理 '' # 来自文件（对于大负载） vivi-notionbot 批处理 --file ./operations.json '[]' **支持的操作**（共 11 项）：行动|描述 ---|--- `页面.创建` |创建页面 `页面.更新` |更新页面属性 `页面.archive` |归档页面 `块.append` |将块附加到父级 `块.更新` |更新一个区块 `块.删除` |删除一个块 `comment.create` |创建评论 `数据库.创建` |创建数据库 `数据库.更新` |更新数据库标题或架构 `database.delete-property` |删除数据库属性 `块.上传` |将文件作为图像或文件块上传 **操作格式**：每个操作都是一个带有“action”的对象，加上您传递给单个命令处理程序的相同字段。混合动作示例： [ {"action": "page.create", "parent": "", "title": "会议笔记"}, {"action": "block.append", "parent_id": "", "markdown": "# 议程\n\n- 项目 1\n- 项目 2"}, {"action": "comment.create", "content": "批量创建页面", "page": ""} ] **输出格式**： { “结果”：[ {"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”，“...”：“...”}} ], “总计”：3， “成功”：3， “失败”：0 } **快速失败行为**：操作按顺序运行。如果任何操作失败，执行将立即停止。输出将包含所有已完成操作以及失败操作的结果。失败时进程退出，代码为 1，成功时代码为 0。 { “结果”：[ {"index": 0, "action": "page.create", "success": true, "data": {"...": "..."}}, {"index": 1, "action": "block.append", "success": false, "error": "块未找到"} ], “总计”：3， “成功”：1， “失败”：1 } ### 批量运营策略对于大型操作（数十或数百个项目），请使用“--file”来避免 shell 参数限制并使事情易于管理。 **第 1 步**：将操作 JSON 写入文件，然后使用 `--file` 运行批处理： # 将操作写入文件（使用写入工具），然后： vivi-notionbot 批处理 --file ./operations.json '[]' **多遍模式** - 当新项目需要相互引用时（例如，链接到另一个新创建的页面的页面属性）： 1. **第 1 步 — 创建所有项目**（无交叉引用）：编写包含所有创建操作的批处理 JSON 文件，省略指向其他新项目的属性。运行它。从输出中收集返回的 ID。 2. **第 2 步 — 设置交叉引用**：使用第 1 步中的 ID 设置引用属性的更新操作编写第二批 JSON 文件。运行它。第 1 遍：创建项目 A、B、C（无交叉引用）→ 获取 A、B、C 的 ID 第 2 遍：更新 A.lated=B、C.parent_ref=A（使用第 1 遍中的真实 ID）这与脚本的结果相同，但无需编写任何代码。只需两次批量调用。 ### 速率限制 Notion 对其 API 实施速率限制。批量操作按顺序运行，因此大批量（30 多个操作）可能会触发 **429 Too Many Requests** 错误。为了避免这种情况： **将大批次分成每个批次调用约 25-30 个操作的块** 如果批次在中途失败并返回 429，则仅使用剩余（未处理的）操作重新运行 “batch” 输出显示哪些操作在失败之前成功 — 使用 “index” 字段来确定从何处恢复 ## 输出格式 ### JSON（默认）所有命令默认输出 JSON 以供 AI 使用： { "id": "...", “对象”：“页面”， “属性”：{ ... } } ### 漂亮（人类可读）使用“--pretty”标志进行格式化输出： vivi-notionbot 搜索“项目”--pretty ## 错误处理 Notion API 的常见错误： * `object_not_found`：ID 不正确或集成无权访问。 * `unauthorized`: `NOTION_TOKEN` 无效。 * `rate_limited`：请求过多。 ## 故障排除 ### `vibe-notionbot：找不到命令` 未安装“vibe-notion”软件包。使用包运行器直接运行它。询问用户使用哪一个： npx -p 振动概念振动概念机器人 ... Bunx -p 振动概念振动概念机器人 ... pnpm dlx --package vivi-notion vivi-notionbot ... 如果您已经知道用户首选的包运行程序，请直接使用它而不是询问。 ## 限制 * 支持 Notion API 版本 2025-09-03。 * 不支持 OAuth（仅限令牌）。 * 通过“块上传”支持文件上传。 * 页面属性更新仅限于通过“--set”的简单键=值对。

Vibe Notionbot

包含技能