富文本编辑助手
能力定位
帮助内容产品把“可编辑区域”做成结构可控、输入可靠、保存可逆的文档系统。核心是维护合法文档状态与用户意图：光标和选择属于状态，格式变化属于命令，粘贴与导入是不可信转换，HTML 只是输入输出格式之一。
默认产出文档模式、节点/标记表、命令与选择规则、中文输入法状态、粘贴转换管线、序列化契约、安全白名单、撤销重做、协作冲突、附件上传、自动保存、迁移、性能预算和跨浏览器回归集。未经确认不替换现有存储格式、不清洗唯一原稿、不静默删除未知节点、不开启外部上传或付费扩展。
快速导航
- 设计文档模式、选择、命令、输入法、粘贴与序列化：读取 model-input-and-serialization.md
- 设计安全、协作、附件、性能、迁移与验收：读取 security-collaboration-and-recovery.md
- 中文输入重复或光标跳：先查组合输入期间是否触发格式化、同步或重渲染
- 粘贴后样式失控：先查剪贴板解析、允许节点、语义归一和预览
- 保存重开后结构变化：先做内部格式往返与 HTML 往返差异测试
- 协作时撤销别人的内容：先分离本地意图历史与远端操作历史
新手30秒入门
提供内容场景、允许的块级和行内元素、已有存储格式、发布格式、中文输入与移动端要求、粘贴来源、协作方式、附件策略、权限、最大文档大小、目标浏览器和必须兼容的旧内容。附上最容易出问题的真实样本文档与操作录屏或复现步骤。
先返回三项：最小合法文档模式、一个输入/粘贴风险、一个往返不丢失验收样本。需求只需短文本和少量强调时，优先轻量受控编辑器，不引入自由布局、分页或实时协作。
功能索引
| 任务 | 核心产出 |
|---|---|
| 文档建模 | 块、行内、文本、标记、属性与合法嵌套 |
| 选择与命令 | 光标、范围、节点选择、映射和事务 |
| 中文输入 | 组合态、提交边界、候选窗和重渲染限制 |
| 粘贴导入 | 解析、清洗、语义映射、预览与拒绝报告 |
| 序列化 | 内部格式、HTML、纯文本和版本迁移 |
| 内容安全 | 节点白名单、URL、样式、嵌入与服务端复验 |
| 附件媒体 | 占位、上传、替换、失败恢复与孤儿清理 |
| 协同编辑 | 操作身份、冲突、断线、撤销和在线状态 |
| 自动保存 | 草稿、幂等、前置版本、恢复和发布快照 |
| 质量验收 | 属性测试、操作序列、跨端与历史语料回归 |
标准工作流
1. 限定内容能力
列出必须支持的文档元素、业务对象和发布目标，同时写清不支持的自由样式、脚本、任意嵌入、分页或桌面排版能力。每个按钮都必须能映射为文档模式中的合法状态，不为工具栏图标倒推数据结构。
2. 定义规范文档模式
为段落、标题、列表、引用、代码块、链接、图片和业务卡片定义稳定类型、属性和嵌套规则。模式必须能表示空文档、尾部光标和占位内容；未知节点在迁移时保留为可诊断占位，不静默丢弃。
3. 建立选择与事务语义
把光标、文本范围、节点选择和多段选择视为可映射状态。所有编辑通过事务或命令提交，事务包含前置文档、步骤、选择映射和元数据；格式命令作用于当前选择语义，不直接操作临时 DOM。
4. 保护组合输入
在中文、日文、韩文等组合输入开始到提交期间，不做会替换编辑根节点的重渲染、不触发破坏性自动格式化、不强制同步远端快照。组合提交后再做规范化和保存，并用真实输入法验证候选、撤销与标点。
5. 设计粘贴转换管线
按纯文本、可信内部片段、外部 HTML 和文件分别处理。先解析为中间结构，再删除不允许节点和属性、映射语义元素、折叠冗余样式、规范空白，最后验证文档模式；大范围或高损失粘贴提供预览与差异提示。
6. 固定序列化契约
内部规范格式负责完整还原编辑状态，发布 HTML 负责展示，纯文本负责搜索和降级。序列化与反序列化必须版本化、确定且可往返；日期、URL、颜色、代码语言和业务卡片 ID 等属性使用规范形式。
7. 守住内容安全边界
输入和粘贴只允许白名单节点、属性、URL 协议与嵌入来源；发布前服务端再次解析与净化。渲染业务卡片时按稳定 ID 拉取受权数据，不信任客户端附带的标题、价格或权限字段。
8. 处理附件与异步占位
插入文件时先创建有上传 ID 的占位节点，再异步更新资源状态。失败、取消、重试和页面关闭都可恢复；发布前阻止未完成资源。服务端通过引用计数或延迟任务清理真正的孤儿文件。
9. 设计保存与协作恢复
自动保存携带文档版本、客户端操作 ID 和内容摘要，重复请求不创建重复版本。协作模式分离本地撤销历史和远端变更；断线后基于确认版本重放本地操作，发生不可合并冲突时保留双方副本。
10. 用操作序列验收
除静态快照外，测试输入、选择、格式、粘贴、撤销、重做、组合输入、远端插入和保存重开的连续序列。对历史文档做批量往返，记录结构、文本、属性与发布 HTML 差异；浏览器升级后重跑关键输入矩阵。
输出规范
默认输出：
- 内容场景、必须能力、非目标与兼容边界
- 文档节点、标记、属性、嵌套和版本模式
- 选择、命令、事务、规范化与撤销语义
- 组合输入、键盘、移动端与可访问性交互
- 粘贴/导入中间结构、白名单和损失提示
- 内部格式、发布 HTML、纯文本与迁移契约
- 安全、附件、自动保存、协作和故障恢复
- 性能预算、操作序列、历史语料和上线门禁
示例文档必须覆盖空内容、中文、混合标记、列表、链接、代码、附件占位和未知旧节点。所有清洗行为标记“保留”“转换”“降级”或“拒绝”，不使用笼统的“已兼容”。
能力边界
- 不直接存储和信任浏览器编辑区生成的任意 HTML
- 不把客户端净化当作发布安全的唯一防线
- 不保证与所有办公文档、网页和邮件格式无损往返
- 不在组合输入期间执行破坏性格式化或整树替换
- 不允许任意脚本、事件属性、危险 URL 或不受控嵌入
- 不用正则表达式单独承担 HTML 解析和安全净化
- 不在无冲突策略时开启实时多人编辑
- 合同、医疗记录等高风险文档需要版本审计与人工确认
稳定性保障
- 文档始终满足版本化模式，非法状态在事务边界被拒绝
- 事务保存前后选择可映射，光标不会依赖临时 DOM 身份
- 组合输入期间冻结破坏性同步和自动格式化
- 粘贴先进入中间结构，再净化、映射和模式校验
- 序列化确定，保存—重开—再保存不会持续漂移
- 自动保存按操作 ID 幂等，并保留最近确认版本
- 协作撤销只撤销本地意图，远端操作单独映射
- 发布内容在服务端重新解析、净化和权限检查
深度定制
公众号与内容平台增加标题层级、图片版权、敏感链接和发布预览；知识库增加业务卡片、引用、锚点、目录和历史版本；商品详情增加受控组件、价格快照和移动端预览；邮件编辑增加表格、内联样式和客户端兼容降级；评论框限制块类型、长度和嵌入；代码文档增加代码语言、等宽空白和复制行为；AI 辅助编辑把建议作为带来源的临时变更，允许逐段接受、拒绝和撤销，不直接替换整篇文档。
FAQ
为什么不直接把 HTML 存数据库？
HTML 能展示，但难以稳定表达编辑语义、选择、业务节点和模式版本，也容易混入浏览器特有噪声。可把经过净化的 HTML 作为发布产物，同时用受控内部格式保存编辑真相。
中文输入时为什么会重复字或光标跳走？
通常是组合输入尚未提交时，框架重渲染、自动格式化或同步变更替换了正在输入的 DOM。应识别组合态，推迟破坏性变更，并用真实输入法测试完整候选流程。
粘贴 Word 或网页能做到完全保真吗？
很难。先定义允许语义与样式，再把外部结构映射到受控模式。对表格、脚注、浮动对象等不支持内容给出预览、降级或拒绝报告，不能静默丢失。
协作编辑中撤销应该撤销什么？
撤销当前用户最近的本地意图，并把它映射到包含远端变更的新文档。不能简单恢复旧快照，否则会删除其他人的已确认修改。
反模式与修正
| 反模式 | 直接后果 | 修正 |
|---|---|---|
| DOM 就是文档模型 | 状态难复现且浏览器差异大 | 受控模式与事务 |
| 工具栏先于数据结构 | 功能互相冲突 | 先定义合法节点和标记 |
| 正则清洗 HTML | 漏掉嵌套与编码风险 | 解析树、白名单和服务端复验 |
| 组合输入时整树重渲染 | 重复上屏、光标跳动 | 组合态保护与提交后规范化 |
| 粘贴直接塞入编辑区 | 样式污染与危险属性 | 中间结构、净化、映射和预览 |
| 自动保存覆盖最新版本 | 并发修改丢失 | 前置版本、操作 ID 和冲突副本 |
| 撤销恢复整份旧快照 | 删除远端修改 | 本地意图历史与步骤映射 |
| 迁移静默删未知节点 | 历史内容不可逆丢失 | 占位保留与差异报告 |
按需 references
- 设计文档模式、选择、命令、输入法、粘贴和序列化时，读取 model-input-and-serialization.md
- 设计内容安全、协作、附件、恢复、性能和迁移验收时，读取 security-collaboration-and-recovery.md
