Notion 区块转换 yuehancn/dsh-tool-notion

dsh-tool-notion

Notion 区块与 Markdown 的双向转换插件，给 DeepSeek Harness 用。

没有 API 客户端，没有外部依赖。 你从 Notion 导出（或从 API 拿到）一份区块数组，它转成 Markdown；你有一份 Markdown，它转成可以直接回写的区块数组。中间不做网络请求 —— 所以它能离线跑、能进测试、也不会因为一个 token 过期就整个失败。

notion_to_md blocks → Markdown
notion_to_blocks Markdown → blocks
notion_validate 两边都收，报出结构问题 notion_status 先说清楚哪些块类型它认得

为什么要单独做这个

看起来是「数组 ↔ 字符串」，写起来才知道反了。

Notion 的段落是一组富文本 run，Markdown 的段落是一个字符串。

Notion: [ {content:"Hello ",annotations:{}}, {content:"world",annotations:{bold:true}} ]
Markdown: "Hello world"

一个段落能有任意多个 run，每个 run 带自己的 bold / italic / strikethrough / underline / code，还能各带各的链接。要变成一行文本，就得在每一个注解边界切开插标记；要从一行文本变回去，就得把相邻的、注解相同的 run 合并才能得到 Notion 原本想要的形状。

这两个方向不是互逆操作。 一个是切分，一个是合并。这就是本插件里代码量的主要来源，也是测试里绝大多数断言在盯的地方。

安装

cordis.patch.yml
plugins:
dsh-tool-notion:
workDir: "."
outputDir: "notion-output"

dsh plugin add dsh-tool-notion

工具

notion_status

在转换之前先问它。它返回：

- toMarkdown —— 能转成 Markdown 的块类型列表和它们的标记
- toBlocks —— 能转回区块的 Markdown 构造
- annotations —— 认识哪五个注解键
- callouts —— 五种 callout 标签 ↔ emoji 的对应表
- directories —— workDir / outputDir 的绝对路径

先看这个，就能把「不支持的块类型」变成一条已知边界，而不是转换到一半发现丢了东西。

notion_to_md

收一份区块数组，产出 Notion 风格的 Markdown。

// 参数（三选一） { blocks: [ … ] } // 区块数组本身 { blocksJson: "[…]" } // 原始 API 响应（字符串），内部 JSON.parse { results: { … } } // 带 results 的 API 包装对象，会自动认出来

为什么要有 blocksJson： defineTool 会在 execute 跑之前就校验参数类型，所以 blocks 这个参数只能收数组。而 Notion API 返回的是一个带 results 的对象。把对象塞进 blocks 会在你还没机会处理之前就被框架拒掉（invalid arguments: "blocks" must be an array）。所以留了一个字符串入口，让原始响应能原样递进来。

输出会在遇到无法表示的结构时显式报告，而不是默默吞掉。

notion_to_blocks

收 Markdown，产出区块数组。

{ markdown: "# Title\n\nSome bold text." }
{ path: "notes/export.md" } // 相对路径，按 workDir 解析

产出的数组可以直接喂给 Notion 的 append 接口。

notion_validate

不转换，只检查。收 blocks / blocksJson，报出：

- 区块数组的结构错误（缺 type、payload 形状不对）
- 不认识的块类型
- 空 run、缺 content 的 run
- callout 标签无法回读的情况

要判断的是「这份数据能不能安全往返」，不是「这份数据合不合法」。 所以它盯的是会静默丢信息的地方。

五个注解，和有顺序的标记

annotations 有五个键：bold italic strikethrough underline code。

写标记的时候顺序是定死的，因为顺序变了意思就变了：

| 场景 | 写法 | 为什么 |
| 粗体 + 斜体 | x | 不是 __x__，粗体在外、斜体在内 |
| 行内代码 | 最内层 | 反引号会压制其他所有标记，所以代码必须包在最里面 |
| 删除线 | x | |

INLINE_MARKERS 表是按从长到短扫的（ 先于 ，___ 先于 _），否则 x* 会被解析成三个独立的 。

反斜杠奇偶性决定标记是不是活的 —— 这是行内扫描里最容易写错的一条：

"a \ b c" → 7 个字符：反斜杠转义了 ，标记没生效 "a \\ b c" → 4 个字符：反斜杠自己被转义，标记是活的

同一个形状，一个反斜杠之差，结果完全不同。测试里两种情况都钉了。

反引号要加宽围栏：如果内容里本身有反引号，外面的围栏就得比里面长。行内代码和围栏代码块都是这个规则。

Callout 的标签 ↔ emoji 必须是双射

这是开发过程中测试自己抓出来的一个真 bug，值得单独说。

Markdown 写 callout 用的是语义标签：

[!WARNING]
这会删库。
Notion 存 callout 用的是图标 emoji。所以中间要做一次映射。第一版写了单向映射：解析时把 WARNING 存进 icon，回写时又把 emoji 写进 icon，再读回来时期待看到标签 —— 结果每一个 [!WARNING] 都变成了 [!NOTE]。

一个警告被静默降级成了提示。这种 bug 不会报错、不会崩，只会在某天有人因为没看到警告而删了库。

修法是把它做成真正的双射：

const CALLOUT_EMOJI = { NOTE: "📘", TIP: "💡", IMPORTANT: "❗", WARNING: "⚠️", CAUTION: "🛑" };
const EMOJI_CALLOUT = Object.fromEntries(
Object.entries(CALLOUT_EMOJI).map(([label, emoji]) => [emoji, label])
);

function calloutLabel(payload) { // 读：emoji → 标签 const icon = payload?.icon; const emoji = typeof icon === "string" ? icon : icon?.emoji;
if (emoji === undefined) return "NOTE";
return EMOJI_CALLOUT[emoji] ?? "NOTE"; // 不认识的 emoji 退回 NOTE，不是丢 callout }

五个标签全部在测试里钉了往返。另外还钉了两种输入形状：icon 是裸字符串、icon 是 { type:"emoji", emoji } 对象 —— Notion 两种都会返回。

通用的教训：凡是「语义值 ↔ 表示值」的映射，都要有反向表和反向断言。单向映射静静吃掉信息的方式是无声的。

parseNotionId 要认带 slug 的 URL

Notion 分享链接把 id 粘在人类可读的 slug 后面：

https://www.notion.so/My-Page-1f2e3d4c5b6a7c8d9e0f1a2b3c4d5e6f
^^^^^^^ 这一段不是 hex

所以不能拿最后一段去匹配 ^[0-9a-f]{32}$ —— 会返回 null。正确做法是先剥掉 query 和 hash，再在整串里找 32 位 hex（或者带连字符的标准 UUID 形式）：

const withoutQuery = text.split(/[?#]/u)[0];
const match = /([0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/iu
.exec(withoutQuery);

一个被测试逼出来的框架规则

defineTool 的 JSON schema 里，每一个嵌套的 { type: "object" } 都必须显式声明 additionalProperties —— 固定形状写 false，自由映射写 true。不写就抛：

JsonSchemaError: … additionalProperties must be explicitly true or false

这个坑在本插件里踩了三次：嵌套的 directories 对象、blocks 数组的 items、以及 byType 这种自由映射。三次都是同一个错误，只是位置不同。数组的 items 也算嵌套对象，也要声明。

测试

node _test/run-all.mjs

三个套件跑在各自独立的子进程里 —— 每个套件都会用 new Function 重建一份插件副本，同进程会互相污染模块缓存。

notion logic: 230 passed, 0 failed
notion integration: 117 passed, 0 failed
notion end to end: 56 passed, 0 failed

共 403 条断言。

三个套件的分工：

- test-logic.mjs（230） —— 纯函数白盒。行内扫描（含反斜杠奇偶性）、run 合并、注解边界切分、围栏加宽、callout 双射、缩进层级、块校验。
- test-integration.mjs（117） —— 通过 defineTool 注册后的真实工具调用。参数 schema 形状（required 被提到顶层、parameters.properties 才是子项）、注册开关、错误信息、workDir 解析规则。
- test-e2e.mjs（56） —— 一份故意难伺候的 "Deploy Runbook" 文档，从 Markdown 一路走到区块再走回来。里面塞了：带 # 注释的 shell 围栏、嵌套围栏、含代码的粗体、粗体链接、嵌套清单、callout、字面星号。

一条钉住的路径规则

path 参数按 workDir 解析 —— 绝对路径会被拼到 workDir 后面，而不是被当成绝对路径使用。这不是 bug，这正是「读不到配置根目录之外」的保证。集成测试里有一条断言专门钉这个行为，免得以后有人「顺手修好」它。

白盒断言的代价与收益

测试通过 new Function 把插件的内部函数（parseInline、mergeRuns、calloutLabel …）取出来直接断言。代价是 harness 要维护一份 INTERNALS 清单，漏一个就是 plugin.X is not a function。收益是不用为了测一个纯函数去套一层 JSON 管道 —— 上面那个 callout bug 就是这么被抓到的。

目录

dsh-tool-notion/
├── lib/index.js 插件本体（4 个工具 + 全部转换逻辑） ├── cordis.patch.yml 插件加载配置 ├── _test/ │ ├── harness.mjs 用真实 dsh-tools 重建 apply，并暴露内部函数 │ ├── test-logic.mjs 230 条 │ ├── test-integration.mjs 117 条 │ ├── test-e2e.mjs 56 条 │ └── run-all.mjs 三个套件各自跑在子进程 ├── LICENSE MIT └── README.md

许可证

MIT © yuehancn

本插件属于 DeepSeek Harness 工具插件系列。同一系列还有 dsh-tool-comfyui、dsh-tool-gzh-publisher、dsh-tool-ocr、dsh-tool-media、dsh-tool-subtitle、dsh-tool-invoice、dsh-tool-qrcode、dsh-tool-epub、dsh-tool-podcast、dsh-tool-mining。*