markstream-custom-components

Markstream 自定义组件

如果任务是更改 Markstream 对特定节点或自定义标签的渲染方式，请使用此技能。

选择覆盖策略前，请先阅读 references/patterns.md。

工作流

1. 对请求进行分类。
   • built-in override：替换现有渲染器，例如 image、link、code_block、mermaid、d2 或 inline_code。
   • custom tag：支持可信的类 HTML 标签，例如 thinking。
   • parser-level：需要转换 token 或重塑 AST。只有这种情况才应离开此技能并使用底层解析器钩子。
2. 优先使用限定作用域的映射。
   • Vue、Vue 2、Svelte 和共享的 Angular 注册：只要可行，就使用 setCustomComponents(customId, mapping)，而不是全局映射，并传入相同的 customId / custom-id。
   • React 自定义标签：对于解析器支持的节点，优先使用渲染器本地的 streamingComponents；对于经清理的 HTML 属性和 children，优先使用 htmlComponents。使用 defineStreamingComponents(...) / defineHtmlComponents(...) 定义带类型的映射。将 setCustomComponents 用于内置节点覆盖或共享的旧式注册。
   • 如果覆盖不应加入共享注册表，Svelte 和 Angular 也可以传入渲染器本地的 customComponents 映射。
   • 在 Vue 3 应用/插件设置中，从 markstream-vue 导入 { VueRendererMarkdown }，并通过 { components } 安装，以便将覆盖限定到 Vue 应用实例。
3. 从最小且安全的覆盖开始。
   • 类叶节点（image、link、inline_code、mermaid）比容器节点（heading、paragraph、list_item）更容易处理。
   • 如果请求只涉及 Mermaid，请使用 mermaid，不要使用 code_block。
4. 必要时保留嵌套 Markdown。
   • 对于包含内部 Markdown 的可信自定义标签，使用嵌套渲染器渲染 node.content。
   • 将相同的自定义标签允许列表传递给嵌套渲染器。
   • 在平滑流式传输的父级中，嵌套渲染器会自动停用，以避免重复节奏控制——不要给子渲染器添加 smooth-streaming。
   • 在 React 中，streamingComponents 会自动将其键加入有效的自定义标签列表；除非其他解析器路径需要这些键，否则不要在 customHtmlTags 中重复添加。
5. 保持属性和清理逻辑完整。
   • 保留 node、loading、indexKey、customId 和 isDark。
   • 对于 mermaid 和 infographic 覆盖，保留 estimatedPreviewHeightPx，以便异步预览外壳在重新挂载期间保持高度稳定。
   • 作用域不再需要时，使用 removeCustomComponents(customId) 移除临时的限定作用域映射。
6. 使用最精简且有效的检查进行验证。
   • 优先使用本地演示、针对性测试或文档构建。
   • 说明该实现对于重复和嵌套的自定义标签是否安全。

默认决策

• 优先使用限定作用域的覆盖；只有整个应用确实需要时才使用全局覆盖。
• 优先覆盖叶节点，而不是容器节点。
• 优先使用 customHtmlTags 加限定作用域的自定义组件，而不是解析器钩子。
• 在 React 中，优先使用渲染器本地组件映射，而不是修改注册表。
• 对于包含 Markdown 的标签主体，使用嵌套渲染器。

实用文档

• docs/guide/component-overrides.md
• docs/guide/custom-components.md
• docs/guide/react-components.md
• docs/guide/components.md
• docs/guide/advanced.md