dsh-notion-toolkit

Notion 连接器（DSH 插件）

English: README.en.md

让 DSH 里的 Agent 直接读写你的 Notion 工作区：搜索、按 Markdown 读取页面、新建页面、修改正文、查询数据库。

这是一个 Host 插件，不依赖任何 npm 包，只注册 Agent 工具。安装后立即生效；改动插件代码后需要重启 DSH 才会加载新的模块。

安装

dsh plugin add github:xsxElricor/dsh-notion-toolkit

装完重启 dsh web。本地开发时直接装目录：

dsh plugin add /path/to/dsh-notion-toolkit

它提供什么

工具	作用
notion_status	检查 token 属于哪个连接、哪个工作区。出错时先跑它。
notion_search	按标题搜索页面和数据源（数据库），支持翻页。
notion_read_page	读一个页面：标题、URL、时间、属性，以及整篇正文（Markdown）。
notion_get_data_source	读数据库结构：每个属性的名字和类型。写行之前先看它。
notion_query_data_source	查询数据库的行（支持 where 简写 / 原生 filter / 排序 / 分页）。
notion_create_page	在页面下新建子页面，或在数据库里新建一行（可同时写入正文）。
notion_update_page	修改页面属性、标题、图标。
notion_write_page_content	修改正文：追加 / 整页替换 / 替换某段 / 查找替换。带版本校验、可先预览 diff。
notion_undo	撤销本插件最近的内容改动（最多 5 步）。
notion_archive_page	把页面或数据库行移进回收站；restore: true 可以从回收站恢复。

正文读写走的是 Notion 的 Markdown 接口（/v1/pages/{id}/markdown，markdown_version=v2），所以模型看到和写回的都是 Markdown，而不是 Notion 的 block 对象。

where 简写

查库时不用手写 Notion 的 filter JSON，直接给"属性名: 条件"，插件会按 schema 里的属性类型翻成正确的 filter，多个条件用 AND 连接：

{"Status": "Done", "Date": ">=2026-11-01", "Project": "组会"}

规则按属性类型走：

属性类型	行为
title / rich_text	子串匹配（contains）
select / status	精确匹配（equals）
number	数字，支持 >= <= > < 前缀
date	日期，支持 >= <= > < 前缀（on_or_after / on_or_before / after / before）
checkbox	true / false
multi_select	子串匹配，给数组则任一命中
值为 null	匹配空值

复杂条件（OR、people、relation 等）还是用原生的 filter，两者可以同时给，会 AND 在一起。

改动安全：版本校验、预览、撤销

Notion 的 API 没有撤销，也没有并发保护。插件自己补了这三样。

版本校验。 notion_read_page 返回一个 version（页面正文的哈希）。replace_all 和 replace_range 必须带上它：

{ "mode": "replace_all", "expected_version": "7a1e6ac33a4dae09", "content": "新正文" }

如果这期间你在 Notion 里手改过这一页，写入会直接失败并提示重新读，而不是把你的修改覆盖掉。

用的不是 last_edited_time。实测它在同一秒内不更新，同秒的并发编辑能绕过它；内容哈希是即时且精确的。

先预览。 preview: true 只算 diff、不落盘：

Preview only — nothing was written. "发布到github" (40e23b19-...).
estimated diff:
  (context)
- 旧的一行
+ 新的一行

预览是本地估算的：search_replace 的最终排版由 Notion 决定，可能和估算差一点空白。

能撤销。 每次写入前把旧正文存进 ~/.dsh/notion-toolkit/journal.json（最近 20 条），notion_undo 一键还原。如果那一页在你写完之后又被改过，撤销会拒绝，除非传 force: true。

第一步：拿一个 Notion token

Notion 的 API 不接受账号密码，只接受一个 集成 token（一长串以 ntn_ 开头的密钥）。你没有它，插件就什么都读不到。两条路选一条：

方式 A：Internal connection（最通用）

1. 打开 https://www.notion.so/my-integrations（或开发者门户 https://app.notion.com/developers/connections），点 New integration / 新建连接。
2. 名字随便填，绑定你的工作区，类型选 Internal。
3. 在 Capabilities（能力） 里至少勾上：
   • Read content（读正文）
   • Update content（改正文）
   • Insert content（新建页面 / 追加内容）
4. 保存后回到 Secrets 页，复制 Internal Integration Secret。
5. 关键一步：Notion 默认什么都不给这个连接看。打开你要让 DSH 读写的页面或数据库，右上角 ··· → Connections / 连接 → 添加你刚建的连接。父页面授权后，子页面会一起授权。

如果漏了第 5 步，API 会返回 404 而不是 403——这是 Notion 故意的，表示"我看不到这个东西"。

方式 B：Personal access token（个人用更省事）

开发者门户里可以创建 personal access token，它代表你本人、直接继承你已有的权限，不需要逐个页面去 Share。适合"只给我自己用"的场景。

两种方式拿到的都是同一类 Bearer token，插件不区分。

第二步：把 token 交给 DSH

按优先级，插件会依次找这三个地方：

1. 插件配置里的 token
2. DSH 凭据存储 / 环境变量里的 NOTION_TOKEN（其次是 NOTION_API_KEY）
3. 进程环境变量里的同名变量

最省事的是给 DSH 进程设环境变量 NOTION_TOKEN。想写进 profile 配置的话，编辑 C:\Users\Elricor\.dsh\profiles\desktop\cordis.patch.yml，追加一段：

- id: notion-connector
  config:
    token: ntn_你的token

（这个文件是明文，注意别把它提交进任何仓库。）

配好后让 Agent 跑一次 notion_status：能看到连接名和工作区名就说明通了。

权限与安全

• notion_archive_page 是唯一的"删除"路径，而它只是移进回收站：Notion 的 API 不支持永久删除， 页面进了 Trash 之后还能用 restore: true 拉回来，要彻底清掉得你在 Notion 里手动清空回收站。
• notion_write_page_content 的 replace_all 和 replace_range 能改写或清空正文，但 Notion 默认拒绝 删掉区间内的子页面和子数据库，除非显式传 allow_deleting_content。
• Agent 能做的事，就是那个 token 背后的连接能做的事。最小权限原则：只把需要的页面 Share 给连接。
• 所有写操作都会立刻生效并对工作区成员可见，不是草稿。

可配置项

写在 cordis.patch.yml 的 config 里，都是可选的：

键	默认值	说明
token	空	直接写死 token（优先级最高）。
version	2026-03-11	请求头 Notion-Version。
timeoutMs	45000	单次工具调用的时间预算。

这一版没做

• 删除单个 block、页面移动（move）、永久删除（API 不支持）。
• 评论（comments）、文件上传、页面历史。
• 数据库结构修改（加/改属性）、视图（views）。
• Webhook：现在只有 DSH 主动拉，Notion 改了你不会被动收到通知。

需要哪一项，说一声就能加。