一个笔记产品的质量，往往在三处暴露：输入时有没有吞字，整理后能不能找回，导出后还能不能阅读。本文用虚构的社区剧场资料库贯穿三类工作：编辑演出说明、把排练资料整理进 Notion、向志愿者交付 PDF 与 Word。这里的步骤是可实施方案，案例数据是演示，不代表已经运行某个编辑器或连接读者的工作空间。
先选择可维护的编辑器边界
先写验收样本，再选框架。这个资料库需要段落、标题、列表、引用、链接和一种“资料卡”，卡片包含来源标识、标题与审核状态。多人协作、复杂表格和修订追踪暂不进入首版。需求清单还应标出中文输入、键盘访问、移动设备、导入旧文档及未来迁移要求，避免功能菜单漂亮却无法保存旧内容。
本次参考 GitHub 上的 Tiptap：它建立在 ProseMirror 之上，以扩展组织编辑能力，适合用一个小原型检验模型与交互。开源编辑器代码的 MIT 许可与商业 Pro 扩展的订阅条件需要分开看。成熟度应结合文档、维护、扩展方式、迁移成本和项目所需版本判断，不能只看下载数或 Stars。业务有差异也不意味着从零自研更便宜；选择、撤销、输入法和序列化都要长期维护。
做一页比较记录：现成节点能覆盖什么、资料卡需要新增什么、哪些行为必须修改底层、升级如何回归。若扩展就能满足模型，先保留上游升级通道。确需自研时，给文档模式、事务、选择映射、剪贴板、历史与安全分别安排负责人和测试预算，而不是把 contenteditable 当作完整编辑器。
场景一：先建文档模型，再写节点与扩展
把持久化文档和屏幕 DOM 分开。资料卡应有稳定 ID、允许的属性和默认值；审核状态只能从约定值中选择。明确它是独立块还是能嵌在段落内、是否可选中、删除键怎样处理、能否包含可编辑子内容。加粗这类文字样式用标记表达，资料卡这类有结构的内容用节点表达，快捷键或命令等行为再由扩展组织。
用三份夹具描述预期：空文档、包含中文与链接的普通说明、带两张资料卡的说明。写出 JSON 与 HTML 的映射及文档模式版本，保留迁移样本。未知节点导入时应提示或转换成可读占位，不能悄悄删除。HTML 是交换格式之一，不要让任意 HTML 成为可信的内部模型。
自定义卡片先实现最小闭环：插入命令校验属性，节点视图展示标题和状态，序列化输出约定结构，解析时恢复受支持属性。输入规则只处理清晰的短语法，粘贴规则另设允许类型；不要让输入规则在中文组字中途抢先替换。粘贴一个网址和粘贴整段网页是不同测试，后者可能带样式、图片、脚本相关属性和不可接受的链接协议。
React 集成时，记录编辑器实例的创建与销毁边界，避免每次父组件渲染都重建编辑器。区分用户编辑事件与外部文档更新，外部内容回填不能不断触发“修改—保存—回填”循环。保存接口携带文档 ID、版本和请求标识；过期响应不能覆盖刚输入的内容。断网时显示未保存状态，并明确草稿恢复策略。
交付物不是一张截图，而是模型说明、可复现夹具、节点实现、序列化对照和回归记录。示例请求可以写为：“为演出说明增加资料卡，允许 sourceId、title、reviewState；未知来源保留占位。先给模型与往返样例，再实现插入、修改、删除和撤销，列出版本兼容限制。”
把中文输入与编辑故障拆成可观察事件
中文重复上屏时，记录操作系统、浏览器、输入法、组字过程以及提交前后的文档变化。检查是否在 composition 期间同时处理键盘与输入事件，或每次变化都用外部状态替换全文。不要用固定延迟掩盖问题。自动化直接填入完整字符串，不能证明真实输入法的组字过程兼容；需要实际输入法复测。
光标跳动要对照事务前后的选择位置、节点 ID 和重渲染，检查外部回填是否重建文档。撤销错乱要看一次用户动作被拆成多少历史项，以及程序更新是否不当进入历史。协作历史与本地撤销的组合需要按所用扩展版本设计，不能随意叠加两套历史。空段落问题则分别测试文首、文尾、列表退出和卡片旁的回车。
HTML 往返丢失时，定位是解析、模型、序列化还是展示阶段缺少规则。用语义比较检查标题、链接、卡片 ID 与文本，不能仅比较 HTML 字节，因为等价 HTML 可能不同。对粘贴和展示分别制定内容策略，清洗危险属性与不允许的协议；前端显示正常不等于通过 XSS 审计。
大文档卡顿应拆开测量解析、事务、节点视图、保存和排版。用短、中、长三档夹具，在同一设备记录输入延迟与耗时；先定位频繁全量序列化或多余渲染，再决定节流、分块或结构调整。不要用单个长文成功打开，就宣称任意文档流畅。
在回归步骤使用可核验的 Skill
Webapp Testing适用于模型与界面完成后的本地浏览器回归。已核对其 SkillPI 详情、Anthropic 固定版本来源及 Apache-2.0 许可记录；这属于来源核验，不是我们执行过安全扫描或替你的编辑器跑过测试。
使用前准备 Python、Playwright、对应浏览器二进制、应用启动命令与端口，以及获准使用的虚构夹具。让 Agent 先观察实际 DOM，再选择稳定控件，验证插入卡片、修改标题、撤销恢复、保存失败提示和重新打开后的内容，保存日志、截图与重现步骤。测试应明确浏览器和断言范围。真实输入法、服务端持久化、完整安全与所有设备兼容仍需各自验证。
场景二：把 Notion 收件箱变成可找回的知识库
先定义整理目标：剧场资料以“项目、资料类型、来源、记录日期、审核状态、负责人”检索，而不是堆几十个标签。将待处理、待核验、已整理分开，原始出处和原文摘录独立保存，摘要不能替代来源。先用少量虚构页面检验属性类型、空值和重复情况，再导入真实获准资料。
制作一份变更预览：页面 ID、原位置、建议项目、标签依据、拟改属性、是否移动以及冲突原因。标题相似不是重复的充分证据；同一剧目可能有不同版本排练记录。无法判断的页面进入人工复核，不能按关键词直接归档。dry-run 只显示计划，不说明后续 apply 必然安全；执行时仍应重新读取状态，并跳过已被其他人修改的页面。
若采用 API 或 CLI，先确认当前 Notion 接口版本、集成授权与页面共享范围，令牌留在主机的合适凭据配置中，不写进提示、笔记或公开日志。没有权限时先检查共享与目标 ID，不要一开始就扩大整个工作空间权限。每批少量更新，记录成功与失败页面；重试仅处理未完成项，避免重复追加摘要。移动或归档前保留可追踪的原位置及恢复方案。
模板从实际查询需求出发：项目表关联资料表，仪表盘只显示待审核与近期变化。公式先写输入与输出示例，再核对属性类型、空列表和日期边界；不要盲复制 substr、filter 或 map 的旧例子。导入 Markdown 模板后逐项确认数据库属性、关系和视图，不能把“生成了 Markdown”当成“完整搭好了数据库”。当前套餐与自动化能力以实际账户为准。
场景三：从语义化 Markdown 到可交付文件
先约定哪些内容能映射到 Markdown。标题、列表和普通链接通常容易表达；资料卡可降级成带来源与状态的引用块，同时保存原始 JSON。复杂表格、批注、交互控件可能损失信息，导出前给出转换清单。输出 PDF 用于稳定阅读，DOCX 用于后续编辑，HTML 用于网页展示；表格数据再单独设计 CSV 或 XLSX，不承诺所有格式互转都保真。
转换可参考 Pandoc 官方手册，先检查安装版本、支持格式及目标引擎。HTML 与 DOCX 可分别生成，PDF 还需要所选 PDF 引擎及字体依赖。以下是命令意图的示例：“从已审核的 programme.md 生成独立 HTML 和 Word；用已安装并核对的 PDF 引擎生成 PDF，输出到新目录，不覆盖源文件；列出缺失字体、图片或不支持节点。”具体命令参数随引擎和版本确认。
中文字体必须在实际导出环境可用且许可允许相应用途。图片使用可访问的受控路径，离线交付时一起打包；不要因远程图片失效而交付空白页。检查长网址换行、代码高亮、表格跨页、目录、页码、链接目标与 PDF 文本能否搜索复制。多端预览至少覆盖目标阅读器与页面尺寸，逐页检查，而不是只看首页。
FAQ 与交付验收
自研还是二开？先用最难的模型和输入样本验证扩展边界，再比较升级、迁移和长期测试成本；差异多不是自研必然更高效的证据。
粘贴后看起来正确，是否可以发布？还要核验保存后重开、模型往返、撤销、危险输入策略和导出；视觉一致只能证明其中一层。整理 Notion 是否需要给 Agent 所有页面？只给任务所需范围，搜索不到先核对授权与页面标识。
为什么 PDF 缺字？核对引擎、字体、字符覆盖与嵌入结果，保存中间 HTML 或其他中间格式帮助定位。为什么表格导出不完整？检查源表是否真有结构、目标格式是否支持合并单元格，再决定拆表或保留附件，不通过删内容来“修好”版面。
最终交付包含文档模型和版本、三类夹具、编辑回归记录、Notion 变更清单及结果、导出源文件与逐页检查记录。发现新的 Skill 时按任务重新查 SkillPI 详情、固定来源、许可与前提，只有确实覆盖某一步才替换关联，不按名称或热度堆链接。
来源与适用范围
场景参考保留中英文原文来源记录，本文以原创剧场资料库案例重写，不沿用未核实的用户引语、安装量、套餐结论或安全保证。技术选型参考 Tiptap 仓库，转换边界与 PDF 前提参考 Pandoc 手册。这些是方法与工具资料，不表示已安装、已连接 Notion 或已执行本文示例。