@chronoai/toolkit/dom

将时间轴的内容自动挂载到指定 DOM 元素上。支持多条时间轴同时挂载、流式更新、多种写入模式。仅用于浏览器环境。

AI 原始输出的提取和格式转换请使用 @chronoai/toolkit/output-parser。

安装

已包含在 @chronoai/toolkit 中，无需单独安装。

import { DomMountFeature } from '@chronoai/toolkit/dom';

为什么需要这个 Feature？

在使用 ChronoAI 时，AI 响应经过 output-parser 提取文本、经过格式转换后，最终都存储在时间轴上。但从时间轴到页面渲染这一步，通常需要在每个项目中手写 useObserver + DOM 操作逻辑。

DomMountFeature 把这段重复逻辑标准化：声明"哪条时间轴的内容挂到哪个 DOM 元素上"，Feature 自动处理流式更新、元素查找、写入策略。

快速开始

agent.use(DomMountFeature, {
  mounts: [
    { source: 'rendered-html', target: '#output' },
  ],
});

当 rendered-html 时间轴写入新值时，内容会自动同步到 #output 元素的 innerHTML。

多条时间轴挂载

agent.use(DomMountFeature, {
  mounts: [
    { source: 'rendered-html', target: '#output' },
    { source: 'thinking-html', target: '#thinking', mode: 'text' },
    { source: 'chat-bubble',   target: '#chat',     mode: 'append' },
  ],
});

每条挂载独立运作，互不影响。

写入模式

通过 mode 参数控制内容如何写入 DOM 元素：

自定义写入函数

agent.use(DomMountFeature, {
  mounts: [{
    source: 'rendered-html',
    target: '#output',
    mode: (el, value) => {
      el.innerHTML = value;
      el.scrollTop = el.scrollHeight; // 自动滚到底部
    },
  }],
});

target 指定方式

target 支持三种形式：

// 工厂函数：DOM 延迟渲染时使用
agent.use(DomMountFeature, {
  mounts: [{
    source: 'rendered-html',
    target: () => document.querySelector('.dynamic-container'),
  }],
});

流式更新

默认开启流式监听（streaming: true）。当源时间轴通过 stream().feed() 推送流式帧时，DOM 会实时更新，无需等到 commit。

如果只需在最终 commit 后才更新 DOM：

{
  source: 'rendered-html',
  target: '#output',
  streaming: false,
}

完整链路示例

从 AI 原始输出到页面渲染的完整管道：

import { OutputParserFeature, stripFences, xmlTag } from '@chronoai/toolkit/output-parser';
import { DomMountFeature } from '@chronoai/toolkit/dom';

// 1. 解析：从 AI 响应中提取 <response> 标签内容
agent.use(OutputParserFeature, {
  source: 'ai-response',
  timeline: 'ai-parsed',
  pipeline: [
    stripFences(),
    xmlTag('response'),
  ],
});

// 2. 挂载：将解析结果的某个字段渲染到页面
agent.use(DomMountFeature, {
  mounts: [
    { source: 'ai-parsed', target: '#output' },
  ],
});

如果中间需要 Markdown → HTML 转换或 XSS 消毒，可在 output-parser 的 custom 步骤中完成，也可以在 DomMountFeature 的自定义 mode 函数中处理。

类型导出

时间轴

外部时间轴

内部时间轴

无。

配置参数

agent.use(DomMountFeature, config) 的 config 支持以下参数：

DomMountEntry