# 氛围概念 TypeScript CLI 工具，使 AI 代理和人类能够通过非官方私有 API 与 Notion 工作区进行交互。支持页面、数据库、块、搜索和用户管理的完整 CRUD 操作。 > **注意**：该技能使用Notion的内部/私有API（`/api/v3/`），它与官方公共API是分开的。如需访问官方 API，请使用“vibe-notionbot”。 ## 使用哪个 CLI 该软件包附带两个 CLI。根据您的情况选择合适的： | `vibe-notion`（此 CLI）| `vibe-notionbot` ---|---|--- 应用程序接口 |非官方私有API |官方概念API 授权 |从 Notion 桌面应用程序自动提取“token_v2” | `NOTION_TOKEN` env var（集成令牌）身份 |作为用户 |充当机器人设置 |零 — 自动提取的凭据 |手动 — 在 notion.so/my-integrations 创建集成数据库行| `添加行`、`更新行` |通过 `page create --database` 创建查看管理 | `视图获取`、`视图更新`、`视图列表`、`视图添加`、`视图删除` |不支持工作空间列表 |支持 |不支持稳定性|私有 API — 可能会因概念更改而中断 |官方版本 API — 稳定 **决策流程：** 1. 如果安装了 Notion 桌面应用程序 → 使用 `vibe-notion` （此 CLI） 2. 如果设置了`NOTION_TOKEN`但没有桌面应用→使用`vibe-notionbot` 3. 如果两者都可用 → 更喜欢“vibe-notion”（更广泛的功能，零设置） 4. 如果两者都不是 → 要求用户设置两者之一 ## 重要提示：仅限 CLI **切勿直接调用 Notion 的内部 API。** 始终使用本技能中描述的 `vibe-notion` CLI 命令。不要向“notion.so/api/v3/”发出原始 HTTP 请求或使用任何 Notion 客户端库。直接 API 调用存在暴露凭据的风险，并可能触发 Notion 的滥用检测，从而导致用户的帐户被阻止。如果“vibe-notion”不支持您需要的功能，请让用户知道并代表他们在 [devxoul/vibe-notion]() 提交功能请求。在提交之前，删除任何真实的用户数据——ID、姓名、电子邮件、令牌、页面内容或任何其他可以识别用户或其工作空间的内容。请改用通用占位符，并将问题集中在描述缺失的功能上。 ## 重要提示：切勿编写脚本 **永远不要编写脚本（Python、TypeScript、Bash 等）来自动化 Notion 操作。** `batch` 命令已经可以处理任何大小的批量操作。编写脚本来循环 API 调用总是错误的 - 请使用带有“--file”的“batch”。即使在以下情况下，这也适用： * 您需要创建100+行 * 您需要在新创建的行之间进行交叉引用（使用多遍批处理 - 请参阅 [references/batch-operations.md]()） * 对于单个命令来说操作感觉“太大” 如果您发现自己在想“我应该为此编写一个脚本”，请停止并使用“batch”。 ## 快速入门 # 1. 找到您的工作区 ID vivi-notion 工作区列表 --pretty # 2. 搜索页面 vivi-notion 搜索“路线图” --workspace-id --pretty # 3.获取页面内容 vivi-notion page get --workspace-id --pretty # 4. 查询数据库 vivi-notion 数据库查询 --workspace-id --pretty 首次使用时，会从 Notion 桌面应用程序中自动提取凭证。无需手动设置。 > **重要**：在特定工作空间内运行的所有命令都需要“--workspace-id”。使用“vibe-notion 工作区列表”查找您的工作区 ID。 ## 身份验证当您运行任何命令时，凭证 (`token_v2`) 会自动从 Notion 桌面应用程序中提取。无需 API 密钥、OAuth 或手动提取。在 macOS 上，您的系统可能会在首次使用时提示进行钥匙串访问 — 这是正常现象，也是解密 cookie 所必需的。提取的“token_v2”存储在“~/.config/vibe-notion/credentials.json”中，具有“0600”权限。 ## 内存代理维护一个 `~/.config/vibe-notion/MEMORY.md` 文件作为跨会话的持久内存。这是代理管理的 — CLI 不会读取或写入此文件。使用“读取”和“写入”工具来管理您的内存文件。 ### 读取内存在**每个任务开始**时，使用“Read”工具读取“~/.config/vibe-notion/MEMORY.md”，以加载任何先前发现的工作区 ID、页面 ID、数据库 ID 和用户首选项。 * 如果该文件尚不存在，那也没有问题 — 无需该文件即可继续操作，并在您第一次存储有用信息时创建该文件。 * 如果无法读取文件（权限、缺少目录），则无需记忆即可继续操作 — 不要出错。 ### 写入内存发现有用信息后，使用“Write”工具更新“~/.config/vibe-notion/MEMORY.md”。写触发器包括： * 发现工作区 ID 后（从“工作区列表”） * 发现有用的页面ID、数据库ID、集合ID后（从‘搜索’、‘页面列表’、‘页面获取’、‘数据库列表’等） * 用户为您提供别名或首选项后（“将此称为任务数据库”，“我的主工作区是 X”） * 发现页面/数据库结构后（父子关系，哪些数据库位于哪些页面下）写入时，请包含**完整的文件内容** - “写入”工具会覆盖整个文件。 ### 存储什么 * 带有名称的工作区 ID * 带有标题和父上下文的页面 ID * 带有标题和父上下文的数据库/集合 ID * 用户指定的别名（“任务数据库”、“主工作区”） * 常用视图ID * 亲子关系（哪些数据库在哪些页面下） * 交互过程中表达的任何用户偏好 ### 不应该存储什么切勿存储“token_v2”、凭据、API 密钥或任何敏感数据。切勿存储整页内容（仅 ID 和标题）。切勿存储块级 ID，除非它们是持久引用（如数据库块）。 ### 处理陈旧数据如果记住的 ID 返回错误（未找到页面、访问被拒绝），请将其从“MEMORY.md”中删除。不要盲目相信记忆的数据——当出现问题时进行验证。宁愿重新搜索，也不要使用可能已过时的记忆 ID。 ### 格式/示例这是如何构建“MEMORY.md”的具体示例： # Vibe 概念记忆 ## 工作空间 - `abc123-...` — Acme Corp（默认） ## 页面（Acme 公司） - `page-id-1` — 产品路线图（顶层） - `page-id-2` — 第一季度规划（在产品路线图下） ## 数据库（Acme Corp） - `coll-id-1` — 任务（在产品路线图下，视图：`view-1`） - `coll-id-2` — 联系人（顶级） ## 别名 - “路线图”→ `page-id-1`（产品路线图） - “任务”→ `coll-id-1`（任务数据库） ## 注释 - 用户更喜欢搜索结果的漂亮输出 - 主要工作区是“Acme Corp” > 内存可让您跳过重复的“搜索”和“工作区列表”调用。如果您已经知道之前会话的 ID，请直接使用它。 ## 命令 ### 验证命令 vivi-notion auth status # 检查身份验证状态 vivi-notion auth logout # 删除存储的 token_v2 vivi-notion auth extract # 手动重新提取 token_v2 （用于故障排除） ### 页面命令 # 列出空间中的页面（仅限顶层） vivi-notion 页面列表 --workspace-id --pretty vivi-notion 页面列表 --workspace-id --深度 2 --pretty # 获取一个页面及其所有内容块 vivi-notion page get --workspace-id --pretty vivi-notion 页面获取 --workspace-id --limit 50 vivi-notion page get --workspace-id --backlinks --pretty # 创建一个新页面（--parent 是可选的；省略在工作区根目录创建） vivi-notion页面创建--workspace-id --parent --title“我的页面”--pretty vivi-notion page create --workspace-id --title "新根页面" --pretty # 创建一个包含 markdown 内容的页面 vivi-notion page create --workspace-id --parent --title "My Doc" --markdown '# Hello\n\n这是**粗体**文本。' # 从文件创建带有 markdown 的页面 vivi-notion页面创建 --workspace-id --parent --title "我的文档" --markdown-file ./content.md # 创建一个包含本地图像的 markdown 页面（自动上传到 Notion） vivi-notion页面创建 --workspace-id --parent --title "我的文档" --markdown-file ./doc-with-images.md # 用新的 markdown 替换页面上的所有内容 vivi-notion 页面更新 --workspace-id --replace-content --markdown '# 新内容' vivi-notion 页面更新 --workspace-id --replace-content --markdown-file ./updated.md # 更新页面标题或图标 vivi-notion 页面更新 --workspace-id --title "新标题" --pretty vivi-notion 页面更新 --workspace-id --icon "🚀" --pretty # 归档页面 vivi-notion 页面存档 --workspace-id --pretty # 获取页面或数据库行属性（没有内容块——页面获取的轻量级替代方案） vivi-notion 页面属性 --workspace-id --pretty ### 数据库命令 # 获取数据库模式 vivi-notion 数据库 get --workspace-id --pretty # 查询数据库（自动解析默认视图） vivi-notion 数据库查询 --workspace-id --pretty vivi-notion 数据库查询 --workspace-id --limit 10 --pretty vivi-notion 数据库查询 --workspace-id --view-id --pretty vivi-notion 数据库查询 --workspace-id --search-query "keyword" --pretty vivi-notion 数据库查询 --workspace-id --timezone "America/New_York" --pretty # 使用过滤器和排序进行查询（使用数据库获取模式中的属性 ID） vivi-notion 数据库查询 --workspace-id --filter '' --pretty vivi-notion 数据库查询 --workspace-id --sort '' --pretty # 列出工作区中的所有数据库 vivi-notion 数据库列表 --workspace-id --pretty # 创建数据库 vivi-notion 数据库创建 --workspace-id --parent --title "任务" --pretty vivi-notion 数据库创建 --workspace-id --parent --title "任务" --properties '{"status":{"name":"Status","type":"select"}}' --pretty # 更新数据库标题或模式 vivi-notion 数据库更新 --workspace-id --title "新名称" --pretty vivi-notion 数据库更新 --workspace-id --properties '{"status":{"name":"Status","type":"select"}}' --pretty vivi-notion 数据库更新 --workspace-id --title "新名称" --properties '{"status":{"name":"Status","type":"select"}}' --pretty # 向数据库添加一行 vivi-notion 数据库 add-row --workspace-id --title "行标题" --pretty vivi-notion 数据库 add-row --workspace-id --title "行标题" --properties '{"Status":"In Progress","Due":{"start":"2025-03-01"}}' --pretty # 添加包含日期范围的行 vivi-notion数据库add-row --workspace-id --title "Event" --properties '{"Due":{"start":"2026-01-01","end":"2026-01-15"}}' --pretty # 更新现有数据库行的属性（来自数据库查询的 row_id） vivi-notion 数据库更新行 --workspace-id --properties '{"Status":"Done"}' --pretty vivi-notion 数据库 update-row --workspace-id --properties '{"Priority":"High","Tags":["backend","infra"]}' --pretty vivi-notion 数据库 update-row --workspace-id --properties '{"Due":{"start":"2026-06-01"},"Status":"In Progress"}' --pretty vivi-notion数据库更新行 --workspace-id --properties '{"Due":{"start":"2026-01-01","end":"2026-01-15"}}' --pretty vivi-notion 数据库 update-row --workspace-id --properties '{"Related":[""]}' --pretty # 从数据库中删除属性（不能删除标题属性） vivi-notion 数据库删除属性 --workspace-id --property "Status" --pretty # 获取视图配置和属性可见性 vivi-notion 数据库 view-get --workspace-id --pretty # 显示或隐藏视图上的属性（逗号分隔的名称） vivi-notion 数据库视图更新 --workspace-id --show "ID,Due" --pretty vivi-notion 数据库视图更新 --workspace-id --hide“受让人”--pretty vivi-notion数据库视图更新 --workspace-id --show“状态”--隐藏“到期”--pretty # 对列重新排序（按所需顺序以逗号分隔的名称；附加未提及的列） vivi-notion 数据库视图更新 --workspace-id --reorder "名称、状态、优先级、日期" --pretty vivi-notion数据库视图更新--workspace-id--重新排序“名称，状态”--显示“状态”--pretty # 调整列大小（JSON 将属性名称映射到像素宽度）振动概念数据库视图更新 --workspace-id --resize '{"Name":200,"Status":150}' --pretty # 列出数据库的所有视图 vivi-notion 数据库视图列表 --workspace-id --pretty # 向数据库添加新视图（默认类型：表） vivi-notion 数据库视图添加 --workspace-id --pretty vivi-notion 数据库视图-add --workspace-id --type board --name "Board View" --pretty # 从数据库中删除一个视图（不能删除最后一个视图） vivi-notion 数据库视图删除 --workspace-id --pretty ### 块命令 # 获取特定块 vivi-notion block get --workspace-id --pretty vivi-notion block get --workspace-id --backlinks --pretty # 列出子块 vivi-notion 块子元素 --workspace-id --pretty vivi-notion 块子元素 --workspace-id --limit 50 --pretty vivi-notion 块子元素 --workspace-id --start-cursor '' --pretty # 追加子块 vivi-notion 块附加 --workspace-id --content '[{"type":"text","properties":{"title":[["Hello world"]]}}]' --pretty # 将 Markdown 内容作为块附加 vivi-notion block append --workspace-id --markdown '# Hello\n\n这是 **粗体** 文本。' # 从文件追加 markdown vivi-notion 块附加 --workspace-id --markdown-file ./content.md # 附加 markdown 和本地图像（自动上传到 Notion） vivi-notion 块附加 --workspace-id --markdown-file ./doc-with-images.md # 附加嵌套 markdown （缩进列表成为嵌套子块） vivi-notion 块附加 --workspace-id --markdown '- 父项\n - 子项\n - 孙项' # 在特定块之后追加块（位置插入） vivi-notion block append --workspace-id --after --markdown '# 在特定块之后插入' vivi-notion 块附加 --workspace-id --after --content '[{"type":"text","properties":{"title":[["插入在"]]}}]' # 在特定块之前追加块 vivi-notion block append --workspace-id --before --markdown '# 在特定块之前插入' # 更新一个区块 vivi-notion 块更新 --workspace-id --content '{"properties":{"title":[["更新的文本"]]}}' --pretty # 删除一个块 vivi-notion 块删除 --workspace-id --pretty # 将文件作为块上传（图像或文件块） vivi-notion 块上传 --workspace-id --file ./image.png --pretty vivi-notion 块上传 --workspace-id --file ./document.pdf --pretty vivi-notion 块上传 --workspace-id --file ./image.png --after --pretty vivi-notion 块上传 --workspace-id --file ./image.png --before --pretty # 将块移动到新位置 vivi-notion 块移动 --workspace-id --parent --pretty vivi-notion 块移动 --workspace-id --parent --after --pretty vivi-notion块移动 --workspace-id --parent --before --pretty ### 块类型和富文本参考对于块类型 JSON 格式（标题、文本、列表、待办事项、代码、引用、分隔符）和富文本格式代码，请参阅 [references/block-types.md]()。 ### 评论命令 # 列出页面上的评论 vivi-notion评论列表 --page --workspace-id --pretty # 列出特定块上的内联注释 vivi-notion评论列表 --page --block --workspace-id --pretty # 在页面上创建评论（开始新的讨论） vivi-notion comment create "这是一条评论" --page --workspace-id --pretty # 回复现有的讨论话题 vivi-notion comment create“回复线程”--discussion --workspace-id --pretty # 根据ID获取特定评论 vivi-notion comment get --workspace-id --pretty ## 批量操作有关批处理命令格式、支持的操作（总共 14 个）、操作 JSON 结构、输出格式、快速失败行为、批量操作策略（多遍模式）和速率限制处理，请参阅 [references/batch-operations.md]()。 **快速使用：** # 内联 JSON vivi-notion batch --workspace-id '' # 来自文件（对于大负载） vivi-notion batch --workspace-id --file ./operations.json '[]' ### 搜索命令 # 跨工作空间搜索（--workspace-id 是必需的） vivi-notion 搜索“查询”--workspace-id --pretty vivi-notion搜索“查询”--workspace-id --limit 10 --pretty vivi-notion搜索“查询”--workspace-id --start-cursor --pretty vivi-notion搜索“查询”--workspace-id --sort lastEdited --pretty ### 用户命令 # 获取当前用户信息振动概念用户我——漂亮 # 获取特定用户 vivi-notion user get --workspace-id --pretty ## 输出格式所有命令默认输出 JSON。使用“--pretty”以获得人类可读的输出。有关 JSON 响应形状（搜索、数据库查询、页面获取、块获取、反向链接）、“$hints”架构警告和详细示例，请参阅 [references/output-format.md]()。 ## 何时使用 `--backlinks` 反向链接显示哪些页面/数据库**链接到**给定页面。这对于高效导航至关重要。 **在以下情况下使用`--backlinks`：** * **跟踪关系**：搜索结果看起来像选择选项、枚举值或关系目标（例如计划名称或类别）。反向链接立即显示通过关系属性引用它的所有行/页面 - 无需寻找父数据库。 * **查找参考** ：您找到了一个页面并想知道其他页面提到或链接到该页面的内容。 * **反向查找** ：无需查询每个数据库来查找指向页面的行，而是使用目标页面上的反向链接直接获取它们。 **示例 - 查找谁使用特定计划：** # 不好：15 个 API 调用 — 搜索、打开空页面、跟踪父级、查找数据库、查询 vivi-notion 搜索“企业计划”... vivi-notion page get ... # 空 vivi-notion block get ... # 查找父级 # ...更多调用来发现数据库 # 好：2-3 个 API 调用 — 搜索，然后反向链接到目标 vivi-notion 搜索“企业计划”... vivi-notion page get --backlinks --pretty # → 反向链接立即显示链接到该计划的所有人员/行 ## 分页返回列表的命令支持通过“has_more”、“next_cursor”字段进行分页： * **`阻止子项`** ：基于游标。将上一个响应中的“next_cursor”值作为“--start-cursor”传递。 * **`搜索`** ：基于偏移量。将“next_cursor”值（数字）传递为“--start-cursor”。 * **`数据库查询`** : 使用`--limit`控制页面大小。 `has_more` 表示存在更多结果，但私有 API 不支持基于游标的分页 — 增加 `--limit` 以获取更多行。 ## 故障排除 ### 身份验证失败如果自动提取失败（例如，Notion 桌面应用程序未安装或未登录），请手动运行提取命令以获取调试输出： vivi-notion auth 提取 --debug 这显示了 Notion 目录路径和提取步骤，以帮助诊断问题。 ### `vibe-notion：找不到命令` 未安装“vibe-notion”软件包。使用包运行器直接运行它。询问用户使用哪一个： npx 振动概念 ... Bunx氛围概念... pnpm dlx 振动概念 ... 如果您已经知道用户首选的包运行程序，请直接使用它而不是询问。 ## 限制 * 自动解压支持 macOS 和 Linux。尚不支持 Windows DPAPI 解密。 * `token_v2` 使用非官方内部 API，如果 Notion 对其进行更改，可能会损坏。 * 这是私有/非官方 API，不受 Notion 支持。

氛围概念

包含技能