@ ai- markdown/ 引擎
自3.0.0起: React and Vue 适配器共享公众
@ai-markdown/core财务报告和审定财务报表@ai-markdown/engine软件包。 见 移徙指南。 。 。 .
@ai-markdown/engine 包含 ai-markdown 使用的字符串和语法-树处理: LaTeX 预处理, 统一的插件链, 递增解析, 以及共享的参考书目. 它没有反应依赖。 一个框架适配器提供组件生命周期,DOM渲染,上下文订阅,以及任何诸如语法突出显示等演示文稿.
这是适配器作者的算法层 . 共享核心,React和Vue在同一列车版本消耗. 公共原产地出口分析、预处理、登记和政策合同;固定装置和私人登记集装箱除外。 公共合同采用3.0.0的语义化版本;打破修改需要一个新的主要版本. 应用程序应安装 @ai-markdown/react 或者说 @ai-markdown/vue; 见 开始。 。 。 .
以下例子说明个别入境点。 它们不组装一个完整的框架适配器:URL转换,协调占位符渲染,效果计时,CSS仍然是适配器的责任.
里面的东西
从软件包根中导出所有东西( E)import { … } from '@ai-markdown/engine'); 桶按层分:
| 层 | 模块 | 要点 |
|---|---|---|
| 预处理器 | preprocessors/latex, (中文(简体) ), preprocessors/remend, (中文(简体) ), preprocessAIMDContent | preprocessLaTeX(text) (货币) $, (中文(简体) ), \[…\] 编号 : \(…\) 正常化、密码栅栏和内线码保护), createIncrementalLatexPreprocessor() 仅供附件流使用, remend 未终止标记的修补 |
| 递增分析 | incrementalParse/* | advanceIncrementalParse(state, content, options) ——前缀被冻结引擎:一行扫描仪决定一个经过验证的安全被冻结的边界,只有尾部再分割,两棵树被分出;每帧被深等于一个全剖面(由仲裁人套件所强制)或倒回一个 |
| 管道组装 | markdown/*, (中文(简体) ), pluginChain, (中文(简体) ), plugins/catalog, (中文(简体) ), customMdastHandlers, (中文(简体) ), remarkInjectPhantomDefs, (中文(简体) ), rehypeRebaseHashLinks, (中文(简体) ), rehypeFooterAdorn, (中文(简体) ), rehypeRawGuard | buildCoreRemarkPlugins 编号 : buildCoreRehypePlugins 编号 : buildCoreRemarkRehypeOptions ——React和Vue渲染器使用的共享链;被封装的发动机-插件目录(highlight, (中文(简体) ), definitionList, (中文(简体) ), removeComments, (中文(简体) ), smartypants, (中文(简体) ), pangu, (中文(简体) ), defaultEnginePlugins(三); EngineRawHtmlDepthError,在元素筑巢超过时被链条所保护的生-HTML步骤所抛出 RAW_HTML_MAX_DEPTH (256;见下文)或步自走会使调用堆排出(警卫本身是内部) |
| 跨部门协调 | documentRegistry, (中文(简体) ), collectDefLabels, (中文(简体) ), extractContributions, (中文(简体) ), extractDefBodiesFromHast, (中文(简体) ), crossChunkUrlSanitize | createRegistry() 每一文件储存,编号脚注并解决跨块定义的联系; resolveCrossChunkReference() 将计划、散列重置和URL转换为已解析的跨圆链路或图像,即独立管道适用的同一闸门; sanitizeCrossChunkUrl() 已贬值: 它只运行协议门和 URL 在赤裸的 URL 上变换( 不重置散列, 不) title编号 :alt 操作),不在适配器的渲染路径上,并且通过 3.x 继续导出 – 使用 resolveCrossChunkReference() |
| 卫生 | sanitizeSchema, (中文(简体) ), extendSanitizeSchema, (中文(简体) ), markdown/urlTransform | 库默认值 rehype-sanitize schema(只读单通-克隆 extendSanitizeSchema, (中文(简体) ), defaultUrlTransform |
| 流线 | smoothStream/controller | createSmoothStreamController() ——框架-不可知型打字机后起步状态机 <AIMarkdownSmoothStream>,与 SMOOTH_STREAM_PACING_PRESETS |
| 叶子 | hastPredicates, (中文(简体) ), normalizeId, (中文(简体) ), shortenDocumentId, (中文(简体) ), devStageTimings | 小型纯辅助器; 共享测试程序只保留源, 不导出 |
用于定义标签扫描, 使用 collectDefLabels(source, { math: true }) 或者说 createDefLabelScanner({ math: true }) 当渲染管道包括 remark-math,就像运出的反应和Vue适配器一样。 Omiting 选项保留了原CommonMark + GFM 语法而不用数学. 此语法选择将显示- math的内容与真实链接和脚注定义区分开来.
安装
npm install @ai-markdown/engine
建立具有两种类型的双重无害环境管理/CJS。 无害环境管理使管道依赖性保持外部。 CJS 构建捆绑只使用 EME 默认导出插件, 因此节点接收可调用插件, 不尝试解决只使用导入的 remend 输入通过 require. 装订的第三方许可证 dist/THIRD_PARTY_LICENSES.txt。没有反应依赖。 唯一的对等者是 katex (单位:千美元)^0.16 || ^0.17, (中文(简体) ), 选项 需要的只有你做数学。 输油管还经过KaTeX rehype-katex。如果您的应用程序导入了 KaTeX CSS, 请直接声明 KaTeX , 以不依赖悬浮的方式解决导入问题。 只使用树的消费者不需要加载浏览器样式表.
示例: LaTeX 自行预处理器
import { preprocessLaTeX } from '@ai-markdown/engine';
preprocessLaTeX('Price is $100, and \\(x^2\\) is inline math.');
// → 'Price is \\$100, and $$x^2$$ is inline math.'
// (currency `$` escaped; `\\(…\\)` normalized to the `$$…$$` form remark-math's inline rule accepts)
同一功能运行在内部 @ai-markdown/react 每段之前; 递增变体(createIncrementalLatexPreprocessor) 重复使用可跨附件框工作.
示例:驱动递增参数
import {
advanceIncrementalParse,
buildCoreRemarkPlugins,
buildCoreRehypePlugins,
buildCoreRemarkRehypeOptions,
defaultEnginePlugins,
sanitizeSchema,
type IncrementalParseState,
type AdvanceOptions,
} from '@ai-markdown/engine';
const remarkPlugins = buildCoreRemarkPlugins(defaultEnginePlugins);
const rehypePlugins = buildCoreRehypePlugins(sanitizeSchema, 'example-user-content-');
const remarkRehypeOptions = buildCoreRemarkRehypeOptions(true);
const options: AdvanceOptions = {
remarkPlugins,
rehypePlugins,
remarkRehypeOptions,
// Keep this key stable until a pipeline input changes.
depsKey: [remarkPlugins, rehypePlugins, remarkRehypeOptions],
defListEnabled: true, // defaultEnginePlugins includes definitionList.
};
let state: IncrementalParseState | null = null;
for (const frame of ['# Hello', '# Hello\n\nworld', '# Hello\n\nworld and more']) {
const result = advanceIncrementalParse(state, frame, options);
state = result.nextState;
// result.hast — the full-document hast for this frame
// result.usedIncremental / result.boundary — whether the frame spliced, and where
}
AdvanceOptions 记录在 incrementalParse/advanceIncrementalParse.ts;反应渲染器 MarkdownContent 是参考消费者.
核查
增量发动机船有五层等同堆(固定接针、模糊仲裁器、方向电池、详尽普查、仲裁敏感性元套件)外加六条腿放出口浸泡(scripts/soak/soak.sh,并附有完整的发布简介和新鲜种子基础 src/experiments/prefixFreeze/README.md迄今发现的每一个可达到的相差点都作为确定性的测试.
运行时间支持
纯计算于字符串和语法树:没有 DOM 访问,没有 只有节点的 API , 没有未保护的环境读取 。 在浏览器中运行, 节点、工人和嵌入式JS运行时间(如赫尔墨斯/贾瓦斯克里普特公司).
嵌入深度绑定
生HTML后每个行走者每个筑巢水平都会重复一次,所以
几百到几千个嵌入式标签的框架 使呼叫堆排尽了
介于 HTML 回放和适配器渲染器之间,以及
取决于引擎。 因此,原HTML步骤衡量元素筑巢
一旦树被重新植入并抛出
EngineRawHtmlDepthError 过去 RAW_HTML_MAX_DEPTH (256) (英语). 第一次失败
嵌入深度 <div>,用 scripts/measure-raw-depth.mjs
(2026-09-11, Playwright, 默认堆栈; 近似, 堆栈限制移动
与JIT状态:
| 浏览器 | 原始步骤( E)hast-util-from-parse5(中文(简体) ) | Vue 适配器 | 反应适配器 |
|---|---|---|---|
| 铬 | ~1920年(平时) | ~1024 (英语) | 在生步骤上方( 它首先失败) |
| 火花 | ~8193 (中文(简体) ) | ~2048年 (中文(简体) ) | ~4864 (英语) |
| 网络Kit | ~8193 (中文(简体) ) | ~4096年 (中文(简体) ) | 在生步骤上方( 它首先失败) |
捆绑在最浅和最深处的四倍
普通内容(64个嵌入式列表为深度128). 消费者
createPipelineSession 内 @ai-markdown/core 使这种框架成为:
纯文本; 手接管道看到错误 。 重运行脚本
当一个渲染器或浏览器改变时.
版本
锁定步骤 @ai-markdown/react,该套件的标点 没错 ——引擎和共享核心暴露出在3.0.0语义版本之后的明确适配器合同(见上文状况说明). 释放注释 : 发布亮点。 。 。 .
软件包家族
| 软件包 | 作用 | 版本政策 |
|---|---|---|
@ai-markdown/core | 独立框架会议、分组规划、贡献和平稳协调 | 释放列车; 精确的引擎依赖性 |
@ai-markdown/react | 反应渲染器—— <AIMarkdown>, (中文(简体) ), <AIMarkdownSmoothStream>, (中文(简体) ), <AIMarkdownDocuments>、 钩子、 提供者 | 释放列车 |
@ai-markdown/vue | Vue 3.5 渲染器——组件、范围槽、SSR/水分和平滑堆肥 | 释放列车; 精确的核心和引擎依赖性 |
@ai-markdown/react-mantine | Mantine UI 绑定——主题打字,代码高亮标签,美人鱼,彩相图接线 | 释放列车; 兼容的 React 3.x 端点 |
@ai-markdown/engine | 框架不可知引擎——增量剖析,LaTeX预处理,插件管道,跨整流器登记册 | 释放列车;完全由共享核心和适配器所固定 |
@ai-markdown/remark-mark-highlight | 注释插件 ==mark== 突出显示语法 | 独立铸币局 |
@ai-markdown/code-language-detector | 对无标签的代码块进行高压语言检测,并用栅栏语言名称映射到Shiki或突出显示. js 名称; 由 Maintine 集成使用 | 独立铸币局 |
拥有增量状态
每个逻辑输入流保持一个解析状态 。 向 advanceIncrementalParse,然后只保留返回的 nextState 下一个框。 替换或安全门故障可选择完整的剖析; usedIncremental: false 是预期的结果,而不是错误。 返回的仓促仍然代表整个当前文件.
当下一个框架恢复时,该州内部的扫描检查点将提前到位. 将每个状态输入到一个完全的后继框架:为两个不同的续作重用一个状态离开描述第一个续作的检查点,第二个可以先冻结一个新扫描不会的前缀. React和Vue适配器每块保持一个线性状态,当一个帧抛出时清除.
成功接通取决于源头的连续性和管道相容性。 如果选中的插件、 方案、 命名空间或转换选项发生变化, 也更新依赖键 。 在保留其身份的同时对插件阵列进行突变,可以在错误的假设下形成手建适配器再利用状态. 此示例一次创建其管道,并使得定义列表处理在解析选项和插件选择中都一致.
两种选项宣告边界扫描仪无法在插件阵列中看到语法能力 . gfmTaskListItems: true 表示链条 解析 GFM 任务列表项, 它允许一个已验证的复选框留下引用的标签; 把它留到一个链条上, 而不留注- gfm . mathFlow 有三个州. true 宣布备注: a $$ 区域是逐字算术,内部没有扫描. false 宣布缺席: $$ 行为普通段落文本。 Oindicent的意思是未知的,然后扫描器将两种语法的结合——这个区域仍然把每个被冻结的候选者都保留到更接近,它的行也被扫描成文本,用于参考,html和栅栏. 无论哪个语法都是正确的, 当你不知道时, 选择是正确的; 它在周围更冷 $$ 并且永远不要放出一个任务框,所以当您知道时,请声明真实值。 三个州中每个州都是保留州的一部分,任何两个州之间的切换会像依赖键变化一样将所保留的树放下来. 反应和 Vue 适配器通过 gfmTaskListItems: true 财务报告和审定财务报表 mathFlow: true 因为 buildCoreRemarkPlugins 总是包括评论 -gfm和评论 -math.
advanceIncrementalParse 并不隐含地应用核心所暴露出的每一预处理便利。 当您需要核心 LaTeX 行为时,首先将原始输入规范化,如果使用其状态形式,则每个流保留单独的增量 LaTeX 预处理器. 用户变换运行在核心的正态字符串上;只再现解析调用并不一定等同于再现适配器的整个输入管道.
适应者的责任
Hast树是一种中间代表,没有完成HTML或React输出. Rehype sanitiers在链中运行,而URL变换则是后发的担忧. 直接消费者必须对幸存的URL属性适用相关的URL政策,如果重新审视所保留的树,必须保持趋同.
跨部门协调需要的不仅仅是创建一个登记册。 框架适配器使用核心来注册块并提交承诺后处理的数据. 他们订阅文件和标签的更改,使占位符处于消费块政策之下,并放出一个总页脚。 发动机所建造的私人占地标记在所运管道中也使用出处边界. 一个没有匹配的证书生命周期的手装链不是滴入相协调的渲染器.
在构建另一个主机时使用回放适配器作为源级参考,并给予该主机自己的生命周期和等同测试. 这个 架构指南 跟踪舞台顺序,同时 溶胶覆盖 区分成功的甲骨文比较和行使优化路径的证据.
仓库命令
安装工作空间依赖性后, 以 pnpm --filter @ai-markdown/engine build 和类型检查 pnpm --filter @ai-markdown/engine typecheck软件包 fuzz:splice 命令运行相机属性套件; soak:coverage 验证覆盖图 。 开发浸泡跑道使用烟雾剖面,再利用的诊断种子被标记为回放跑道. 只有完整的释放证据才能建立释放PASS.
实验性README保留了原始的L0-L4研究并保存了后期的验证历史. 其历史计数和分级不能取代目前的生产扫描仪、覆盖图或释放跑道配置.
许可证
麻省理工学院