markstream-migration

Markstream 迁移

当仓库已能渲染 Markdown，且任务是安全地采用 Markstream 或将现有的 markstream-vue 1.x 集成升级到 2.x 时，请使用此技能。

选择迁移路线

更改代码前，请检查 package.json、锁文件、导入内容和渲染器属性。

• 如果仓库已依赖 markstream-vue 1.x，请阅读 references/vue-1x-to-2x.md 并遵循 路线 B。请确认软件包依赖，而不要仅根据 MarkdownCodeBlockNode 或 InternalParseOptions 等共有名称选择路线，因为其他适配器中也可能出现这些名称。
• 否则，如果要用 Markstream 软件包替换 react-markdown、markdown-it、marked 或其他渲染器，请阅读 references/adoption-checklist.md 并遵循 路线 A。
• 如果两种情况都适用，请先完成从 1.x 到 2.x 的软件包和 API 升级，然后再将单独的渲染器替换作为采用任务进行审核。

路线 A：从其他渲染器迁移到 Markstream

1. 审查仓库当前对渲染器的使用情况。
   • 搜索 Markdown 渲染器、插件链、原始 HTML 处理、安全属性和自定义渲染器。
   • 列出所有需要修改的调用点。
2. 对迁移进行分类。
   • direct：简单地替换字符串输入的渲染器。
   • renderer-custom：使用了自定义渲染器，但解析器工作有限。
   • plugin-heavy：使用了 remark、rehype、markdown-it 或其他转换密集型流水线。
   • security-heavy：涉及允许或拒绝列表、URL 重写、清理或原始 HTML 策略。
3. 先替换渲染器。
   • 引入合适的 Markstream 包和 CSS。
   • 通过包的 CSS 子路径导入 Markstream CSS；不要依赖渲染器导入来注入样式。
   • 添加更丰富的 Markstream 专属功能之前，先保留用户可见行为。
   • 在宣称行为一致之前，检查旧渲染器是否允许宽泛的原始 HTML 或 Mermaid 宽松模式 HTML 标签。
4. 迁移自定义渲染器。
   • 将内置节点渲染器转换为限定范围的节点类型覆盖。
   • 在 React 中，对于由解析器处理的标签，优先使用渲染器本地的 streamingComponents；对于经过清理的 HTML 属性组件，优先使用 htmlComponents；对于内置节点覆盖或共享兼容性注册，使用 setCustomComponents。
   • 在 Svelte 或 Angular 中，如果映射不需要共享注册，优先使用渲染器本地的 customComponents 输入。
   • 对于可信的类标签内容，优先使用 customHtmlTags。
   • 只有当旧流水线确实需要令牌或 AST 转换时，才使用 parseOptions.preTransformTokens、postTransformTokens 或 postTransformNodes。
5. 如实审查差异。
   • 不要在无法做到时宣称完全一致。
   • 明确指出仍需人工审查的解析器、插件、安全或 HTML 行为。
6. 在转向 nodes 之前，先考虑渲染器模式和平滑流式输出。
   • 对于 Vue 3，AI/SSE 输出请选择 mode="chat"，丰富的文档界面请选择 mode="docs"，轻量的非聊天界面请选择 mode="minimal"。
   • 如果应用流式传输 content，且只需要控制节奏，smooth-streaming="auto"（默认值）即可满足需求，无需使用 nodes。
   • 仅当应用需要自定义 AST 控制、在 worker 中预解析或进行高频结构更新时，才改用 nodes。
   • 在 Vue 3（包括 Nuxt）中，smooth-streaming 控制输出节奏，fade 控制不透明度；两者可以同时启用。mode="chat" 默认将 fade 设为 false，以保持轻量。需要逐渐显示文本时添加 fade；更在意动画开销时则保持关闭。迁移 Vue 3 时，不要照搬旧版 :fade="!isStreaming" 绑定，除非宿主应用需要该策略。
   • 流式输出与恢复历史记录：迁移聊天 UI 时，在同一聊天行中保留 mode="chat"，改用其他节奏或动画属性。Vue 3 流式输出：使用 mode="chat"、final，以及可选的 fade。Vue 3 已完成的聊天历史记录：保留 mode="chat"，无需控制节奏时使用 :smooth-streaming="false"，并独立选择是否启用渐显效果。仅在独立的丰富文档界面中使用 mode="docs"。
7. 验证并总结。
   • 运行范围最小且相关的测试或构建。
   • 报告直接映射关系、待办事项和仍需完成的验证工作。

路线 B：将 markstream-vue 1.x 升级到 2.x

1. 冻结当前集成接口。
   • 记录已安装的 markstream-vue 版本和包管理器解析结果。
   • 找出旧的代码块依赖项、渲染器值、属性、公共类型、运行时辅助工具、预览处理器和直接导入的解析器。
   • 确定能够验证当前行为所需的最小构建、类型检查、SSR 和代码块检查。
2. 选择一个发布系列。
   • 仅在协调一致的 beta 系列发布后，且 next 指向该代版本时使用；或者在稳定版发布后使用 markstream-vue@2。
   • 编辑清单前检查注册表版本和 dist-tags；仓库中的版本变更不能证明某个包可安装。
   • 仅安装应用使用的适配器。仅当应用直接导入解析器或核心包时，才直接添加它们。
   • 让各个包保持在同一预发布代；不要混用无关的 beta 版本。
3. 仅根据references/vue-1x-to-2x.md应用必要的依赖项和 API 变更。
   • 移除两个旧版代码块运行时。将受支持的 monacoOptions / codeBlockMonacoOptions 字段重命名为共享的 codeBlockOptions 契约，并删除仅适用于 Monaco 的不受支持字段。
   • 仅在需要增强代码块或差异代码块时添加 stream-diffs；否则使用纯文本回退方案。
   • 保留现有的 Markdown、图表、数学、HTML 策略、worker、CSS、流式处理和虚拟化设置，除非有文档记录的 2.x 重大变更要求修改。
4. 验证迁移后的行为，并保留回滚路径。
   • 视情况检查包解析结果、公共类型、预览负载使用方、普通和差异代码围栏、主题、响应式差异布局，以及 SSR 或打包安装。
   • 报告可恢复到先前系列的确切 1.x 版本或旧版 dist-tag。

默认决策

• 先替换渲染器，再优化流式处理。
• 不要把现有 Markstream 版本升级当成渲染器迁移改写。
• 从 1.x 升级到 2.x 时，保留应用中除文档记录的代码块和解析器变更之外的行为。
• 协调一致的 beta 系列应保持在同一预发布代；更改依赖项前明确回滚方案。
• 平滑流式处理是“仅内容”和“完整节点迁移”之间的中间选项：它无需控制 AST，即可按节奏呈现可见输出。
• 涉及 HTML 或安全规则时，安全性优先于功能对等。
• 优先使用明确的 TODO，而非含糊的说法。
• 目标框架提供组件映射时，优先使用渲染器本地的组件映射。
• 如果当前技术栈严重依赖 Markstream 无法直接对应的转换，应建议不要迁移。
• 必须保留可信的旧版行为时，应使用作用域受限的 htmlPolicy / html-policy="trusted" 和 mermaidProps.isStrict = false，而不是在所有地方放宽默认设置。

有用的文档目标

• docs/guide/migration-2-0.md
• docs/guide/react-markdown-migration.md
• docs/guide/react-markdown-migration-cookbook.md
• docs/guide/ai-chat-streaming.md
• docs/guide/installation.md
• docs/guide/component-overrides.md
• docs/guide/advanced.md