solid-notion：为Notion AI自动化引入Git式版本控制的CLI工具

1. 项目概述：为Notion操作引入“版本控制”的CLI工具

如果你正在构建一个需要与Notion深度交互的AI助手，或者你本人就是一个重度Notion用户，经常需要通过脚本自动化处理页面内容，那么你一定遇到过这样的困境：直接调用Notion API进行修改，就像在云端走钢丝，一旦操作失误，恢复起来既麻烦又缺乏清晰的记录。solid-notion这个CLI工具，正是为了解决这个痛点而生。它的核心思想，是为Notion的读写操作，尤其是AI驱动的自动化流程，引入一套类似Git的“版本控制”机制，让每一次修改都变得可回退、可观察、可审计。

简单来说，solid-notion不是一个简单的Notion API封装器。它通过一套精心设计的工作流，将远程的Notion页面“拉取”到本地，形成一个包含完整历史记录的安全沙箱。你或你的AI助手可以在这个沙箱里放心地进行编辑、提交，所有的变更都会被记录下来。如果对修改不满意，你可以像使用git revert一样，轻松地将页面恢复到历史上的任何一个版本。这对于需要频繁、批量修改Notion内容，同时又对数据安全有高要求的场景——比如用AI整理知识库、批量更新项目状态、自动化生成报告——来说，无疑是一剂强心针。

2. 核心设计理念：为何要“重造轮子”？

你可能会问，Notion官方提供了完善的API，市面上也有不少封装库，为什么还需要solid-notion？答案在于，直接使用原始API或通用封装库进行自动化操作，尤其是在AI介入的场景下，存在几个固有的、影响效率和安全的短板。

2.1 直接调用API的三大痛点

首先，数据噪声过大。Notion API返回的是完整的、嵌套极深的JSON块结构。对于一个内容稍多的页面，这个JSON会异常庞大，包含大量用于描述页面UI和结构的元数据。当AI模型（如GPT）需要理解页面内容以做出修改决策时，这些结构性噪声会消耗大量宝贵的上下文令牌（Tokens），却对理解核心内容帮助有限，导致成本高昂且效率低下。

其次，变更难以追溯。当你通过API直接更新一个块（Block）的内容时，这个操作是“静默”的。除非你自己额外实现一套复杂的日志系统，否则你很难清晰地回答：“刚才AI到底改了哪里？它为什么这么改？” 缺乏直观的差异对比（Diff）和历史记录，使得调试和审查自动化流程变得异常困难。

最后，回滚机制缺失。API本身不提供“撤销”操作。一旦内容被覆盖，想要恢复，你只能依赖Notion页面自带的版本历史（如果有且足够细粒度），或者自己事先备份。这给自动化操作带来了巨大的心理负担和实际风险。

2.2 solid-notion的破局思路：三原则实践

solid-notion正是针对上述痛点，提出了三个核心设计原则，并将其贯穿于整个工具链。

1. 可回退这是最核心的安全网。工具的所有修改都基于“提交”概念。当你通过edit和submit命令完成一次修改后，本地会生成一个唯一的版本哈希（Hash）和对应的变更集。history命令可以列出所有历史版本。如果新提交的内容有问题，你可以使用restore命令，指定一个历史哈希，工具会自动计算并应用一个反向补丁，将页面内容回退到那个时间点。这个过程是确定性的，并且会在本地留下清晰的恢复记录。

2. 可观察工具致力于让状态一目了然。ls命令可以快速查看本地已拉取的所有页面。show page --format markdown命令能将一个Notion页面转换为纯净的Markdown格式输出。对于人类审查者或AI模型来说，Markdown格式剔除了JSON的结构噪声，只保留标题、列表、代码块等语义化内容，信息密度和可读性远高于原始JSON，极大提升了“观察”效率。

3. 可审计每一次关键操作都会在本地文件系统中留下“证据”。这包括原始的拉取文件、每次编辑生成的JSON补丁文件、提交时生成的版本记录文件。这些文件共同构成了一个完整的本地审计追踪。当自动化流程出现意外结果时，你可以像侦探一样，通过检查这些本地文件，精确复盘整个操作序列，定位问题根源。

注意：该项目作者明确表示这是一个为满足自身需求而构建的实验性项目。虽然它旨在帮助你安全地实验更改，但无法保证每次恢复都完美无缺。请务必先在非关键页面上进行充分测试，重要数据操作前建议手动备份。

3. 工作流深度解析：从拉取到回滚的全过程

理解solid-notion的最佳方式，就是走一遍它的核心工作流。我们将以一个常见的场景为例：你有一个名为“项目周报模板”的Notion页面，需要让AI助手根据本周数据自动填充内容。

3.1 环境准备与初始化

首先，你需要安装工具并完成认证。虽然文档提到了通过npm全局安装，但在开发或深度使用阶段，我更推荐从源码构建，以便随时查阅或修改逻辑。

# 克隆仓库 git clone https://github.com/vincentdchan/solid-notion.git cd solid-notion # 使用 pnpm 安装依赖（项目推荐） pnpm install # 编译TypeScript源码 pnpm build

接下来是获取Notion集成令牌。这个过程是标准化的：

1. 访问https://www.notion.so/profile/integrations/internal。
2. 点击“New integration”，创建一个新的内部集成。
3. 为其命名，例如“My Solid Notion CLI”。
4. 在生成的页面中，复制“Internal Integration Token”（以secret_开头的一长串字符）。
5. 关键一步：将该集成邀请到你想要操作的Notion工作空间，并授予它需要操作的页面权限。没有这一步，API调用会因权限不足而失败。

初始化工具，将令牌安全地配置到本地：

# 通过标准输入传递令牌，避免在shell历史中留下记录 echo "你的_secret_令牌_在这里" | pnpm exec solid-notion init --token-stdin

这个命令会在用户主目录下的.solid-notion文件夹中创建配置文件，保存你的令牌和后续拉取的所有页面数据。

3.2 核心双工作流实操

solid-notion主要支持两种工作流：读取工作流和补丁工作流。前者用于观察和消费内容，后者用于安全地修改内容。

读取工作流：pull -> inspect假设我们的目标页面ID是a1b2c3d4e5f6（你可以在Notion页面链接中找到它）。

# 1. 将页面拉取到本地。默认会存储在 $SOLID_NOTION_HOME 下按页面ID命名的文件夹中。 pnpm exec solid-notion pull page a1b2c3d4e5f6 --format markdown # 2. 使用 `ls` 查看本地已管理的页面列表 pnpm exec solid-notion ls # 输出可能类似： # a1b2c3d4e5f6 项目周报模板 (latest) # 3. 以高可读性的方式查看页面内容，供AI或人工分析 pnpm exec solid-notion show page a1b2c3d4e5f6 --format markdown > weekly_report.md

现在，weekly_report.md文件里就是纯净的Markdown内容。你可以将这个文件直接送入AI的上下文，让它分析现有结构并规划如何修改。相比传递原始JSON，这通常能节省60%以上的令牌消耗，并且AI的理解准确率会显著提升。

补丁工作流：edit -> submit -> history -> restore这是实现安全修改的关键循环。solid-notion的edit命令是其精髓所在。它并不直接让你编辑原始Markdown文件，而是引导你通过生成一个JSON补丁来描述变更。

# 1. 启动编辑会话。你可以传入页面ID或上一步生成的markdown文件路径。 pnpm exec solid-notion edit weekly_report.md

执行这个命令后，工具会做几件事：首先，它会计算当前本地存储的页面内容（基于最后一次pull或submit的状态）与weekly_report.md文件内容之间的差异。然后，它会打开你的默认文本编辑器（通过$EDITOR环境变量设置，如VSCode、Vim、Nano），并呈现一个特殊的编辑界面。这个界面里包含的正是计算出的JSON Patch文档。

JSON Patch是一种标准格式（RFC 6902），用于描述JSON文档的更改。它由一系列操作组成，如add、remove、replace、move、copy。例如，AI分析后决定将“本周总结”段落下的第一项列表内容替换掉，生成的补丁可能长这样：

[ { "op": "replace", "path": "/blocks/3/paragraph/text/0/text/content", "value": "完成了用户认证模块的重构，性能提升20%。" } ]

在这个编辑界面里，你可以直接修改这个JSON Patch数组。确认修改无误后，保存并关闭编辑器。

# 2. 提交补丁到本地历史，并同步到Notion。 pnpm exec solid-notion submit a1b2c3d4e5f6 -m “由AI助手更新本周项目进展”

submit命令是原子性的关键一步。它会：

• 将你编辑好的JSON Patch应用到本地存储的页面副本上。
• 将这个Patch连同提交信息一起，作为一个新的版本记录保存到本地历史中。
• 调用Notion API，将同样的变更应用到云端真实的Notion页面上。
• 生成一个本次提交的唯一哈希值（如abc123def）。

# 3. 查看该页面的操作历史 pnpm exec solid-notion history a1b2c3d4e5f6

history命令会输出一个清晰的时序列表，展示每次submit的哈希、时间戳和提交信息。这让你对所有的修改活动一览无余。

# 4. 如果发现最后一次提交有误，执行回滚 pnpm exec solid-notion restore a1b2c3d4e5f6 abc123def

restore命令是安全网的最终体现。它会找到目标哈希对应的版本，计算出从当前状态回到那个状态所需要的“反向补丁”，然后先应用到本地，再推送到Notion云端。执行成功后，Notion页面和你的本地副本都会回到提交abc123def时的状态。

3.3 高级功能与场景应用

除了核心工作流，solid-notion还提供了一些提升效率的辅助命令。

搜索与批量操作

# 在工作空间内搜索包含“TODO”的页面 pnpm exec solid-notion search “TODO” # 列出你有权限访问的所有页面（需要集成有对应权限） pnpm exec solid-notion pages

search功能对于让AI助手定位需要处理的页面非常有用。你可以先让AI根据搜索结果为任务排序，再针对性地拉取和修改特定页面。

与OpenClaw等AI技能平台集成这是solid-notion一个非常前瞻性的设计。项目提到了与OpenClaw技能的集成。其思路是，将solid-notion的这一套安全、可观察的工作流，封装成AI智能体（如OpenClaw上的技能）可以直接调用的标准化操作。AI智能体不再需要直接处理复杂的Notion API认证、错误处理和回滚逻辑，只需要学会调用pull、show、edit、submit这几个高层命令，就能在安全的边界内完成对Notion内容的操作。这极大地降低了为AI构建可靠内容编辑工具的复杂度。

4. 实战经验与避坑指南

在实际使用和测试中，我总结了一些关键经验和可能遇到的问题，这往往是官方文档不会详细提及的。

4.1 文件与目录结构解析

理解工具在背后如何管理数据，有助于你在出现问题时进行手动排查。所有本地数据默认位于~/.solid-notion/目录下（可通过$SOLID_NOTION_HOME环境变量自定义）。

~/.solid-notion/ ├── config.json # 保存你的Notion集成令牌 ├── pages/ # 每个页面一个子目录 │ └── <normalized_page_id>/ # 规范化后的页面ID作为目录名 │ ├── current.json # 当前本地副本的JSON表示 │ ├── current.md # 当前本地副本的Markdown表示（如果拉取时指定） │ ├── versions/ # 版本历史存储 │ │ ├── abc123.commit.json # 提交记录，含消息、哈希、时间戳 │ │ └── abc123.patch.json # 该版本对应的JSON Patch文件 │ └── changesets/ # 编辑会话中生成的补丁文件（未提交的） └── logs/ # 可能存在的操作日志（如果启用）

当你执行restore时，工具会读取versions/目录下对应的.patch.json文件，计算其反向操作，并更新current.json和current.md。

4.2 常见问题与解决方案实录

问题1：执行edit命令时，编辑器打开的是一个空文件或错误内容。

• 排查思路：这通常是因为工具在计算当前状态与目标（页面ID或文件）之间的差异时失败了。首先，确认你用于edit的参数是正确的。如果你传入的是一个Markdown文件路径，请确保这个文件是通过show page --format markdown导出的，或者是上一次成功pull生成的current.md。直接手写一个Markdown文件可能无法与内部的JSON结构正确对应。
• 解决方案：最可靠的方法是始终针对一个已拉取（pull）的页面ID进行操作。先pull page <id>，然后edit <id>。这样工具会基于本地存储的current.json来计算一个“空补丁”（因为你还没做任何修改），你在编辑器中看到的将是一个空的JSON数组[]，你可以在此基础上按照JSON Patch格式手动添加操作。

问题2：submit成功，但Notion页面上的更改未生效或部分生效。

• 排查思路：Notion API对请求速率和负载大小有限制。此外，复杂的嵌套块结构在应用Patch时可能会遇到意外。
• 解决方案：
  1. 检查API响应：solid-notion在提交时应该会输出API调用的反馈。关注是否有错误信息。
  2. 简化Patch：如果一次性修改的内容非常多，尝试将大的修改拆分成多个小的、顺序执行的edit->submit操作。
  3. 验证Patch路径：在edit阶段生成的JSON Patch中的path字段，指向的是页面JSON结构中的特定位置。如果页面结构在拉取后、提交前被其他人手动修改过，可能导致路径失效。此时，重新pull一次页面获取最新结构，再基于新结构生成Patch。
  4. 查看本地历史与文件：对比versions/目录下提交的.patch.json文件和提交后的current.json，看本地应用是否成功。如果本地成功但远程失败，问题很可能出在API交互上。

问题3：restore操作后，页面内容没有完全恢复到预期状态。

• 排查思路：这是最令人担心的情况。回滚的准确性依赖于历史Patch记录的完整性和正确性，以及反向Patch计算的正确性。
• 解决方案：
  1. 优先使用“快照”式备份：对于极其重要的页面，不要完全依赖增量Patch的回滚。在执行重大自动化修改前，可以手动使用pull page <id> --outdir <backup_path>将页面完整JSON导出到一个独立的备份目录，作为最终保障。
  2. 理解恢复原理：restore到某个历史哈希H，实质上是将H之后的所有提交的Patch进行“逆操作”。确保这些中间版本的Patch文件都存在且未被损坏。
  3. 分步恢复：如果恢复到很早的版本出现问题，可以尝试逐步向前恢复。先恢复到离当前较近的一个版本，确认成功后再恢复到更早的版本。

问题4：与AI协同工作时的提示工程优化。

• 核心技巧：当你设计AI助手（如基于GPT、Claude的智能体）来使用solid-notion时，给AI的指令（Prompt）需要特别设计。
  • 清晰的步骤链：指令应为：“1. 使用search或pages命令找到关于X的页面。2. 使用pull page <id>拉取该页面。3. 使用show page <id> --format markdown获取内容并分析。4. 根据分析结果，构建一个JSON Patch数组来描述以下更改：[具体更改描述]。5. 使用edit和submit命令应用这个Patch。”
  • 提供Patch示例：在指令中，提供2-3个不同操作类型（replace文本、add新块、remove块）的JSON Patch完整示例，能极大提高AI生成正确格式的能力。
  • 强调审查：指令中必须要求AI在submit前，先输出它生成的JSON Patch供人类审查确认。这是将AI的“建议”转化为“安全操作”的关键闸口。

4.3 性能与规模化考量

solid-notion目前看起来更适合于对少量或中等数量页面进行精细化的、需要审计的自动化操作。如果需要对成千上万个页面进行批量、统一的简单修改（例如批量添加一个标签），直接使用Notion API SDK编写脚本可能更高效，因为省去了本地文件管理和历史维护的开销。但对于需要AI进行内容理解、判断和复杂编辑的场景，solid-notion提供的安全框架所带来的信心和调试便利性，远超过其额外的管理成本。

这个工具体现了一种非常务实的工程思想：通过引入约束（本地化、版本化、补丁化）来换取更高的安全性、可观察性和可控性。它可能不是所有Notion自动化任务的终极答案，但对于那些错误成本高、需要人机协同或AI深度参与的任务，它提供了一个经过深思熟虑的、值得借鉴的解决方案范本。