# @ai-markdown/engine 中文文档

规范地址：https://npmcn.com/package/%40ai-markdown/engine/

版本：3\.5\.0
npm 元数据更新时间：2026-10-23T00:32:54.745Z
中文译文更新时间：2026-11-07T00:25:24.842Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ai-markdown/engine
原文对照：https://npmcn.com/package/%40ai-markdown/engine/?lang=original
项目主页：https://github.com/ai-markdown/ai-markdown/tree/main/packages/engine#readme
源码仓库：https://github.com/ai-markdown/ai-markdown

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：10.8 MB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：29 个
- peer 依赖：katex ^0\.16\.0 \|\| ^0\.17\.0
- 首次发布：2026-09-09T04:12:47.151Z
- 最新版本发布：2026-10-23T00:32:54.335Z
- 近 30 天下载量：2109（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

框架独立的Markdown解析、递增转换、预处理和文件登记.

## 安装

```sh
npm install @ai-markdown/engine
```

也可以使用：`pnpm add @ai-markdown/engine`、`yarn add @ai-markdown/engine`、`bun add @ai-markdown/engine`

## README

# @ ai- markdown/ 引擎

[文档](https://ai-markdown.github.io/docs/engine/) • 妇女 [实例](https://ai-markdown.github.io/examples/) • 妇女 [网站](https://ai-markdown.github.io/)

[![@ai-markdown/engine stable](https://img.shields.io/npm/v/@ai-markdown/engine?label=npm&color=blue)](https://www.npmjs.com/package/@ai-markdown/engine?activeTab=versions) [![@ai-markdown/engine monthly downloads](https://img.shields.io/npm/dm/@ai-markdown/engine?label=downloads%2Fmonth&color=blue)](https://www.npmjs.com/package/@ai-markdown/engine) [![TypeScript declarations included](https://img.shields.io/badge/TypeScript-included-3178c6?logo=typescript&logoColor=white)](https://github.com/ai-markdown/ai-markdown/tree/main/packages/engine) [![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/ai-markdown/ai-markdown/blob/main/LICENSE)

> **自3.0.0起:** React and Vue 适配器共享公众 `@ai-markdown/core` 财务报告和审定财务报表 `@ai-markdown/engine` 软件包。 见 [移徙指南](https://ai-markdown.github.io/docs/guides/framework-transition/)。 。 。 .

`@ai-markdown/engine` 包含 ai-markdown 使用的字符串和语法-树处理: LaTeX 预处理, 统一的插件链, 递增解析, 以及共享的参考书目. 它没有反应依赖。 一个框架适配器提供组件生命周期,DOM渲染,上下文订阅,以及任何诸如语法突出显示等演示文稿.

**这是适配器作者的算法层 .** 共享核心,React和Vue在同一列车版本消耗. 公共原产地出口分析、预处理、登记和政策合同;固定装置和私人登记集装箱除外。 公共合同采用3.0.0的语义化版本;打破修改需要一个新的主要版本. 应用程序应安装 `@ai-markdown/react` 或者说 `@ai-markdown/vue`; 见 [开始](https://ai-markdown.github.io/docs/guides/getting-started/)。 。 。 .

以下例子说明个别入境点。 它们不组装一个完整的框架适配器: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的内容与真实链接和脚注定义区分开来.

## 安装

```bash
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 自行预处理器

```ts
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`) 重复使用可跨附件框工作.

## 示例:驱动递增参数

```ts
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语义版本之后的明确适配器合同(见上文状况说明). 释放注释 : [发布亮点](https://ai-markdown.github.io/docs/guides/release-highlights/)。 。 。 .

## 软件包家族

| 软件包 | 作用 | 版本政策 |
| --- | --- | --- |
| [`@ai-markdown/core`](https://www.npmjs.com/package/@ai-markdown/core) | 独立框架会议、分组规划、贡献和平稳协调 | 释放列车; 精确的引擎依赖性 |
| [`@ai-markdown/react`](https://www.npmjs.com/package/@ai-markdown/react) | 反应渲染器—— `<AIMarkdown>`, (中文(简体) ), `<AIMarkdownSmoothStream>`, (中文(简体) ), `<AIMarkdownDocuments>`、 钩子、 提供者 | 释放列车 |
| [`@ai-markdown/vue`](https://www.npmjs.com/package/@ai-markdown/vue) | Vue 3.5 渲染器——组件、范围槽、SSR/水分和平滑堆肥 | 释放列车; 精确的核心和引擎依赖性 |
| [`@ai-markdown/react-mantine`](https://www.npmjs.com/package/@ai-markdown/react-mantine) | Mantine UI 绑定——主题打字,代码高亮标签,美人鱼,彩相图接线 | 释放列车; 兼容的 React 3.x 端点 |
| [`@ai-markdown/engine`](https://www.npmjs.com/package/@ai-markdown/engine) | 框架不可知引擎——增量剖析,LaTeX预处理,插件管道,跨整流器登记册 | 释放列车;完全由共享核心和适配器所固定 |
| [`@ai-markdown/remark-mark-highlight`](https://www.npmjs.com/package/@ai-markdown/remark-mark-highlight) | 注释插件 `==mark==` 突出显示语法 | 独立铸币局 |
| [`@ai-markdown/code-language-detector`](https://www.npmjs.com/package/@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政策,如果重新审视所保留的树,必须保持趋同.

跨部门协调需要的不仅仅是创建一个登记册。 框架适配器使用核心来注册块并提交承诺后处理的数据. 他们订阅文件和标签的更改,使占位符处于消费块政策之下,并放出一个总页脚。 发动机所建造的私人占地标记在所运管道中也使用出处边界. 一个没有匹配的证书生命周期的手装链不是滴入相协调的渲染器.

在构建另一个主机时使用回放适配器作为源级参考,并给予该主机自己的生命周期和等同测试. 这个 [架构指南](https://ai-markdown.github.io/docs/guides/architecture/) 跟踪舞台顺序,同时 [溶胶覆盖](https://ai-markdown.github.io/docs/guides/soak-coverage/) 区分成功的甲骨文比较和行使优化路径的证据.

## 仓库命令

安装工作空间依赖性后, 以 `pnpm --filter @ai-markdown/engine build` 和类型检查 `pnpm --filter @ai-markdown/engine typecheck`软件包 `fuzz:splice` 命令运行相机属性套件; `soak:coverage` 验证覆盖图 。 开发浸泡跑道使用烟雾剖面,再利用的诊断种子被标记为回放跑道. 只有完整的释放证据才能建立释放PASS.

实验性README保留了原始的L0-L4研究并保存了后期的验证历史. 其历史计数和分级不能取代目前的生产扫描仪、覆盖图或释放跑道配置.

## 许可证

麻省理工学院

## 常见问题

### @ai-markdown/engine 是什么？

框架独立的Markdown解析、递增转换、预处理和文件登记\.

### 如何安装 @ai-markdown/engine？

在项目目录运行 npm install @ai-markdown/engine，或使用 pnpm add / yarn add / bun add。

### @ai-markdown/engine 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ai-markdown/engine 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ai-markdown/engine 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ai-markdown/engine 可以商用吗？

@ai-markdown/engine 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ai-markdown/engine 的下载量有多少？

根据 npm 官方下载统计，@ai-markdown/engine 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,109 次，日均约 70 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ai-markdown/engine 还在维护吗？

最新版本 3\.5\.0 发布于 2026/10/23（15 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/09/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。