技能介绍

要解决什么问题

很多团队把笔记写在本地 Markdown 里，却需要在 Notion 里给同事看或做知识库归档。手工复制粘贴会丢排版：标题层级、表格、代码块、本地图片的顺序和样式很难一致。Notion 官方导入对复杂 MD 的支持也有限，而直接调 Block API 又容易踩 rich_text 结构、表格 children 与代码块长度等坑。

技能如何工作

本技能在用户表达「把 Markdown 上传到 Notion」「同步本地笔记到 Notion」等意图时加载，按固定流程执行：校验 Notion Token 与目标页面 ID、可选清空页面、预上传本地图片，再解析 MD 并映射为 Notion Block，最后分批（每批 50 个）写入页面。

核心映射包括：

#～### → 原生标题；####～###### 用 callout、加粗段落、引用等方式模拟
围栏代码块 → code（语言映射，超过 2000 字符自动拆分）
表格 → table（使用 children + 二维 cells，不用错误的 rows 写法）
列表、引用、---、行内粗体 / 斜体 / 代码 / 链接 → 对应 Block 或 annotations

常见错误（Token 未配、文件不存在、限流、页面未分享给 Integration）会给出指向 references/SETUP_TOKEN.md 与 troubleshooting.md 的排查路径。

适用边界与注意点

必须先配置 Integration Token，且目标页面已在 Notion 里 Add connections 给该 Integration；不能用 workspace_id 当 parent，需用 URL 中的页面 ID 或搜索 API 拿到有效页面。
父页面写入权限由 Notion 侧决定；清空页面为可选步骤，执行前需确认不会误删已有内容。
H4～H6 为兼容方案，在 Notion 里观感与标准标题不完全一致；极长单文件或大量图片会受 API 限流与上传耗时影响。