前言¶
在 DeepSeek Harness（DSH）里做笔记、文档或 Runbook 类内容时，常见路径是：从 Notion 导出或通过 API 拿到区块数组，再在本地用 Markdown 编辑、进测试或交给智能体处理；写完后又要变回 Notion 能 append 的区块形状。手写「数组 ↔ 字符串」往往低估富文本 run、注解边界和 callout 映射带来的不对称。下面介绍社区插件 dsh-tool-notion（维护者 yuehancn），它在 DSH 进程内提供离线转换工具，不发起 Notion 网络请求。
这是什么¶
dsh-tool-notion 是面向 DeepSeek Harness 的工具插件：把 Notion 区块数组转成 Notion 风格 Markdown，再把 Markdown 转回可回写的区块数组，并附带结构校验与能力查询。README 明确说明没有 Notion API 客户端；转换过程不做外部网络请求，适合离线跑和自动化测试。
在 SkillHub 插件目录 中该条目分类为「模型推理」，与目录简介「DeepSeek Harness plugin」一致；具体能力以仓库 README 为准。当前 GitHub 星标为 0；package.json 版本为 1.0.0，许可证 MIT。DSH 社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
插件通过四个工具暴露能力（名称来自 README）：
| 工具 | 作用 |
|---|---|
notion_status |
转换前查询：支持转 Markdown / 转区块的块类型、五种注解键、callout 标签与 emoji 对应、workDir / outputDir 绝对路径 |
notion_to_md |
区块数组 → Notion 风格 Markdown；无法表示的结构会显式报告 |
notion_to_blocks |
Markdown → 区块数组，产出可直接对接 Notion append 类接口的数据形状 |
notion_validate |
不转换，检查区块结构、未知块类型、空 run、callout 回读风险等「往返是否会丢信息」的问题 |
参数入口（摘录自 README）：
notion_to_md 三选一：
{ blocks: [ … ] }
{ blocksJson: "[…]" } // 字符串形式的 API 响应，内部 JSON.parse
{ results: { … } } // 带 results 的 API 包装对象
README 说明：因 defineTool 会在 execute 前校验类型，blocks 只能收数组；原始 API 对象需走 blocksJson 或带 results 的包装，避免 "blocks" must be an array 被框架提前拒绝。
notion_to_blocks：
{ markdown: "# Title\n\nSome **bold** text." }
{ path: "notes/export.md" } // 相对 workDir 解析
notion_validate 收 blocks / blocksJson，聚焦会静默丢信息的结构问题，而非 Notion 侧「是否合法」的完整判定。
实现上，Notion 段落是多段富文本 run（各自带 bold / italic / strikethrough / underline / code 与链接），Markdown 段落是单字符串；切分 run 与合并 run 不是互逆的简单反转，这是插件逻辑与测试的主要关注点。行内标记顺序、反斜杠奇偶性、围栏加宽、callout 语义标签与 emoji 的双射映射等细节在 README 中有说明，并配有 403 条测试断言（三个套件）。
安装与启用¶
1、在 DSH 插件配置中声明工作目录与输出目录（来自 README 的 cordis.patch.yml 示例）：
# cordis.patch.yml
plugins:
dsh-tool-notion:
workDir: "."
outputDir: "notion-output"
2、安装插件（命令须与资料一致）：
dsh plugin add dsh-tool-notion
package.json 要求 dsh 引擎 >=0.2.0-rc.2，并声明 @deepseek-ai/cordis、@deepseek-ai/dsh-tools 等 peer 依赖；安装后按你的 Harness 项目方式加载 cordis.patch.yml 即可。
典型用法¶
先看能力边界
在批量转换前调用 notion_status，对照 toMarkdown、toBlocks、annotations、callouts 与 directories，把「不支持的块类型」列为已知边界，避免转换中途才发现内容丢失。
导出 → Markdown
将从 Notion 导出或 API 拿到的区块数组（或 blocksJson / results 包装）传给 notion_to_md，得到可在仓库或编辑器中维护的 Markdown。需要确认结构时，可先 notion_validate 再转换。
Markdown → 回写区块
本地改完 Markdown 后，用 notion_to_blocks 传入字符串，或通过 path 读取相对 workDir 的文件（README 注明：path 按 workDir 解析，绝对路径会被拼到 workDir 之后，用于限制读配置根目录之外）。产出的数组再交给你们自有的 Notion API 调用层 append。
本地验证
维护者提供的测试入口：
node _test/run-all.mjs
README 记录当前三套合计 403 passed（logic / integration / e2e），用于回归行内扫描、工具 schema、workDir 路径规则与端到端往返文档。
适用场景与注意¶
适合谁
- 已在 DSH 或 Cordis 生态中编排工具，需要把 Notion 区块与 Markdown 在无 API 客户端、无网络前提下做往返转换的团队或个人。
- 希望转换失败或信息损失有报告，而不是静默吞掉 run、callout 或未知块类型的场景。
- 需要把笔记导出进 Git、CI 测试或智能体可读文本，再生成 Notion 区块 payload 的工作流（网络与鉴权仍由你们自己的 Notion 集成负责）。
注意
- 插件在当前 DSH 进程权限下运行；
notion_to_blocks的path受workDir约束。安装前应阅读 源码仓库 与 MIT 许可证，确认符合内网与合规要求。 - 不支持或未映射的块类型不会 magically 变成 Notion 全功能等价物；务必结合
notion_status与notion_validate评估损失面。 - SkillHub 分类「模型推理」描述的是目录归类，不等同于插件内置大模型推理；本质是格式转换工具。
结尾¶
dsh-tool-notion 把 Notion 区块数组与 Notion 风味 Markdown 之间的双向转换、校验和能力查询收进 DSH 四个工具，强调注解边界、callout 双射与显式报错，便于离线测试与文档流水线。进一步了解可访问 SkillHub 目录页 与 GitHub 仓库。
