# @ai-markdown/core 中文文档

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

版本：3\.5\.0
npm 元数据更新时间：2026-10-23T00:34:05.803Z
中文译文更新时间：2026-11-08T06:21:15.567Z
软件包许可：MIT

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

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

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

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

## 中文简介

框架独立的管线会话,块规划,跨圆形贡献和Ai-markdown适配器的流协调.

## 安装

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

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

## README

# @ ai- markdown/ 核心

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

[![@ai-markdown/core stable](https://img.shields.io/npm/v/@ai-markdown/core?label=npm&color=blue)](https://www.npmjs.com/package/@ai-markdown/core?activeTab=versions) [![@ai-markdown/core monthly downloads](https://img.shields.io/npm/dm/@ai-markdown/core?label=downloads%2Fmonth&color=blue)](https://www.npmjs.com/package/@ai-markdown/core) [![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/core) [![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/ai-markdown/ai-markdown/blob/main/LICENSE)

为ai-markdown适配器进行框架独立管弦,与React和Vue适配器在同一放行列车上. 它提供管道会议、区块规划、交叉贡献、总的脚注树和溪流协调。 应用程序安装 `@ai-markdown/react` 或者说 `@ai-markdown/vue`; 适配器作者可以安装 `@ai-markdown/core` 财务报告和审定财务报表 `@ai-markdown/engine` 直接说.

这个软件包是遗产 v2.14.1 发行中的私人运行时间. 现在,这已成为两个框架适配器的一个真正的外部依赖,并有明确的公共出口清单。 旧的 `@ai-react-markdown/core` 将软件包映射到 `@ai-markdown/react`而不是这个包裹。 见 [移徙指南](https://ai-markdown.github.io/docs/guides/framework-transition/). 公共合同采用3.0.0的语义化版本;将共享包保存在相同的准确列车版本.

## 责任和依附方向

```text
@ai-markdown/react-mantine → @ai-markdown/react (peer)
@ai-markdown/react         → @ai-markdown/core + @ai-markdown/engine
@ai-markdown/vue           → @ai-markdown/core + @ai-markdown/engine
@ai-markdown/core          → @ai-markdown/engine
```

适配器也可能直接消耗引擎原始. 共享核心并不重复引擎的公共管或包住每个引擎的功能,仅仅是为了重命名. 它拥有可再使用的管弦乐,否则就必须被复制到另一个框架适配器.

| 模块 | 责任 | 国有所有者 |
| --- | --- | --- |
| `coordinationPreparation.ts` | 衍生的幽灵目标,选择协调/孤儿处理者和收割政策,建立贡献无效拖拉机 | 纯决定; 先前的快照属于呼叫者 |
| `pipelineSession.ts` | 合并协调解析选项, 附加保护幽灵后缀, 选择完整/ 递增解析, 无效状态, 返回完整解析, 或仅在引擎的原始深度出错时, 返回纯文本框架 | 每块一个会话 |
| `blockPlan.ts` | 关联转换 HAST与源 MDAST, 生成稳定的密钥, 分类参考依赖度并吞入 HTML, 计算注册指纹 | 对所提供的树木和登记册的纯功能 |
| `blockPlanner.ts` | 在保留整个文档参考上下文的同时重新使用符合条件的保留前缀计划 | 每块一个计划员 |
| `contribution.ts` | 比较来源和政策指纹、收获改变的定义机构、公布改变的承诺捐款 | 每个挂载块有一个出版商 |
| `aggregateFootnotes.ts` | 将文件命令的脚注和出错背面集合为 HAST | 回回树属于呼叫者 |
| `cloneHastForRender.ts` | 克隆节点/儿童/财产/数据以及原始-URL容器在变异之前 | 返回的克隆属于呼叫者 |
| `smoothCoordinator.ts` | 命令块显示、保持粘性完成、推迟清理和联合通知 | 每个逻辑文件一名协调员 |
| `tailSignal.ts` | 分类在脚注中或作为无形链接定义的源尾 | MDAST 上的纯函数 |

该引擎仍然负责语法,预处理,插件链,扫描仪,增量剖析算法,注册存储/索引,参考解析和URL政策原始. 共享核心使用这些算法执行可重复使用的渲染决定.

框架适配器保留组件构建和生命周期整合. 反应保留 `ReactNode` 缓存、背景、效果、, `useSyncExternalStore`、登记寿命、来源证书分配、最后元素转换和DOM光标测量。 共享核心的根没有反应,Vue,斯维尔特或DOM依赖. 其制作来源在没有DOM库的情况下进行打字检查. 节点类型 为跨主机原始人提供声明,例如: `queueMicrotask`;它们不添加节点运行时间依赖.

## 管道会话是本地到一个消费者

为一个逻辑转换块创建一次会话 。 将预处理的累积内容、稳定的插件阵列和当前协调事实传递到 `parse`。结果包含 MDAST 和 HAST;它没有框架节点.

```ts
import { createBlockPlanner, createPipelineSession } from '@ai-markdown/core';
import {
  buildCoreRemarkPlugins,
  buildCoreRehypePlugins,
  buildCoreRemarkRehypeOptions,
  sanitizeSchema,
} from '@ai-markdown/engine';

const pipeline = createPipelineSession();
const planBlocks = createBlockPlanner();
const remarkPlugins = buildCoreRemarkPlugins([]);
const rehypePlugins = buildCoreRehypePlugins(sanitizeSchema, 'example-');
const remarkRehypeOptions = buildCoreRemarkRehypeOptions(false);
const targetPhantoms = { missingFootnotes: new Set<string>(), missingLinks: new Set<string>() };
const content = 'A **framework-neutral** frame.';

const trees = pipeline.parse({
  content,
  targetPhantoms,
  remarkPlugins,
  rehypePlugins,
  remarkRehypeOptions,
  preserveForBodyHarvest: false,
  documentId: 'example',
  provenance: 'standalone-example',
  incrementalParse: false,
  defListEnabled: false,
});
const blocks = planBlocks(trees.mdast, trees.hast, content);
// Convert blocks.plan using the host renderer; use item.key for sibling identity.
```

这是一个使用公共软件包条目的独立实例. 被协调的适配器必须获得出处证书,将同样的证书传递给发动机的验证人和被协调的处理人,获得实际的幽灵目标,并在注册时保留定义机构. 从一个例子中不断获得证书并不适合这种路径.

主机选择 `incrementalParse: false` 用于一发服务器渲染. 共享核心不检查 `window` 以推断宿主。 后来的递增框架从非递增框架后的新状态开始. 打电话 `reset()` 当主机无效保留了剖析状态,因为使策略改变。 解析输入身份也被引擎的依赖密钥所检查;幽灵后缀变化始终是-尾输入,而不是将所有保留来源无效.

在重新试验整条输油管之前,递增的失败清除了保留状态。 整个管道有一个退化的结果:当发动机的生-HTML步骤报告时 `EngineRawHtmlDepthError` (元素筑巢比发动机的束缚更深, `RAW_HTML_MAX_DEPTH`数百个巢穴生地 `<div>` 标记超过),会话记录了开发过程中的错误建立并返回框架为一个纯文本段落,其位置覆盖了整个源,因此一个有敌意的消息不能将主机表面下移;下一个框架通常会解析. 这最后的手段使案文成为逃避的文本,而不是僵硬的框架。 整个输油管的所有其他例外都向东道主传播,包括 `RangeError` 这不是溢出,也不是从所提供主机的语句或重奏插件或处理器中扔出的任何:这些是浮出水面的bug,不是以文本形式渲染的框架,而倒置不能取代适配器代码周围的错误边界。 每个会话和规划器都是可变的本地计算状态:不共享一个独立块或同时执行消费者.

## 共同的筹备决定

`coordinationPreparation.ts` 包含反应适配器和 [Vue 适配器](https://npmcn.com/package/%40ai-markdown/vue/README.md)数字 :

-   `derivePhantomTargets({ content, ownLabels, labels }, previous?)` 排除本地拥有的定义,然后将正版源与外部标签相匹配。 脚注和链接命名空间仍然分开。 如果没有候选人,则跳过源正常化;如果结果设定匹配 `previous`,它返回同一个对象。 匹配仍然是遗留的子字符串超近似,而不是一个新的Markdown参考解析器.
-   `deriveCoordinationPolicy({ coordinated, registered, preserveOrphanReferences }, previous?)` 选择所有协调的处理器,只选择孤儿-脚注处理器,或正常的独立行为. 登记使得即使在可见的孤儿渲染功能丧失的情况下也能收割尸体。 只收割的改变保留了处理者的身份. 主机在调用此函数前解决了任何包件覆盖 .
-   `buildContributionChain(inputs)` 明确命名策略的依赖性: 备注/重写数组, 备注-重写选项, 处理器, 收割政策, 弹片前缀, 文件编号和出处 。 来源,奇幻相机,注册和符号仍然是出版商自己的指纹输入.

这些函数不注册、订阅、发布或更改所提供的快照。 将标签集和返回对象视为不可变;仅通过同一逻辑消费者的上一个结果。 反应保留先前的快照在回放中并使用记忆; Vue 在计算值后面使用本地变量。 当一个源被替换或一个被保留的渲染被丢弃时,发动机和规划师仍然拥有正确性.

发表 [Vue 适配器](https://npmcn.com/package/%40ai-markdown/vue/README.md) 使用这些决定在其组件生命周期中,同时使AST/登记对象远离深活性代理。 它有SSR,水合,插槽,基底样式和光标支持,在Chromium,Firefox和WebKit中设有功能适配器检查,在Chromium中设有强制-GC生命周期检查. 先前的私人原型机存档于 `prototypes/` 而不是应用程序的切入点.

## 准备和承诺具有不同的效果

分析、规划和构建一个贡献会话并不登记块或公布文件事实。 东道主在其承诺/生命周期阶段登记一个块,接收一个符号,并呼叫 `createContributionSession().commit(options)` 仅针对其文号属于当前登记册的已实施渲染.

在反应中, `useRegistryContribution` 拥有一个会话并引用 `commit` 从效果。 注册符号与它的注册符号配对;切换文档不能在旧文档符号下短暂地发布一个框架. SSR不运行这种效果,所以它保留了本地的脚注语义. 其他适配器必须提供相应的生命周期保障.

贡献指纹涵盖订购的参考文献、定义来源、原始链接目的地、拥有的标签集、奇幻目标集和解释政策的身份翻转。 具有已更改插件的等同源不等于贡献 。 定义机构内有明确幽灵的等同来源也不是平等的贡献。 只有改变指纹/政策,才能触发从后管线HAST中收获的更昂贵的体能.

出版商不会在贡献时间对链接URL进行消毒:每个消耗元素应用自己的最终URL政策. 收获的脚注机构保留插件输出 . `buildAggregateTree` 在附加后补体之前克隆结构容器,所以组装不会使注册拥有的身体发生突变. 复制件 `data` 联 合 国 `originalUrls` 共享时的容器 `position`,其他嵌入式插件数据和个人属性值;它不是任意消费突变的一种不受限制的深克隆.

清理也是东道主的责任. 当块卸载时, 解除其注册和平滑的协调员空档 。 协调员将清除工作推迟到一个微任务上,这样一对立即清理/重新登记者就可以恢复同一个槽而无需重新排序. 注册时补全为粘滞; 进度心跳不通知每个显示框上的每个订阅者 .

## 规划和提供合同

计划跟随HAST儿童,因为转型可以下降或重组源节点. 每个项目都有中性 `key` 和一类: `block`, (中文(简体) ), `inline` 或者说 `synthetic`区块带有源域、行/栏位置、依赖性标签和可选吞吞-HTML文摘。 规划师的密钥是兄弟身份;它们不足以验证缓存输出.

渲染器还必须比较在等源水桶内的发生,依赖指纹,位置,HTML文摘以及剥去被吞入的本地脚注部分的决定. React 适配器保存此缓存 `packages/react/src/components/blockMemo.ts`它在解剖学上取代了它以前的机身缓存,因此被移除的块释放出它们的节点. 将缓存批发移入核心将暴露回放自有价值,而无需订立有用的跨框架合同.

所保留的-前缀规划器只重复使用身份证明合格的节点. 它保留了围绕原始的HTML和定义的全面规划,以及整个文件在规划尾部时的参考上下文,尾部沿有参考的被保留块. 这并不是说每个附件只花费附加字符的数量:顶级的倒转和参考文本工作仍可随文档而缩放.

## 构建和验证

```bash
pnpm install --frozen-lockfile
pnpm build
pnpm --filter @ai-markdown/core typecheck
pnpm --filter @ai-markdown/core test
pnpm test:core-contracts
pnpm preflight
```

在运行发行测试前构建:它们将实际的ESM/CJS制作和开发文件装入独立的节点进程,以转接方式拒绝UI框架分辨率,并在没有浏览器全局的情况下解析. 其他测试将会话输出与独立的全引擎管道进行比较,进行重排/倒计时,证明有明确的贡献时间并检查聚合体的不可用性. 已存在的回放测试仍然行使适配器的分权,记忆,字节等同,协调和浏览器行为.

奉献 `test:core-contracts` 闸门构建了核心及其工作空间的依赖性,对它进行打字检查,并独立于React/Vue运行所有核心测试. 它在飞行前运行,一个专门的CI任务和发布工作流程. 纯计划员、协调员、尾信号和块状平面试验与核心进行现场试验;React保留了渲染器/缓存综合试验。 固定种子序列将保留的管线/规划和贡献状态与全面重建进行比较,将协调员生命周期与单独的模式进行比较。 见 [核心测试](https://ai-markdown.github.io/docs/guides/core-testing/) 用于模块映射、固定预算、重放命令和限制.

`assert-boundary.mjs` 检查公共包装标识,允许生产依赖,源导入方向和折叠环境门. React发行守护需要外部核心和引擎导入. 核心的声明不能暴露 `RegistryInternal`, (中文(简体) ), `SmoothCoordinatorInternal` 或私人重计/订户容器.

发售列车为发动机/核心/反应/反应-mantine/vue同版本. Vue现在使用相同的共享合同;见 [API合同](https://ai-markdown.github.io/docs/guides/api/core-engine-contracts/) 用于稳定签名和从β.1移出。 核心取决于引擎通过 `workspace:*`,这成为了公布的车单中准确的列车版本. 无害环境管理和CJS都有生产和开发条目;每个建筑分别叠叠环境门. 核心没有 `use client` 指令,而不插入第二个引擎执行.

## 公共 API 和写入能力

根条目明确列出支持稳定出口。 会话的创建,解析,规划,纯粹的协调准备,贡献承诺,综合构建,结构克隆和源尾分类都是适配合同. 现有的块摘要和指纹功能仍然可用,因为React消耗它们;上面的源/所有权假设仍然适用.

`createSmoothCoordinator` 返回仅读状态和文档方法 `SmoothCoordinator`,不包括内部重计和通知集装箱. `ContributionOptions.registry` 只接受一个 `ContributionRegistry` 写入能力 `contributeChunkData`;不需要执行登记册。 通过引擎创建注册 `createRegistry`,其 `RegistryController` 添加只读的注册和出版物 `Registry` 合同。 在自有适配器中将每个注册与发行对等.

这些是类型级的API边界,而不是对象被冻结或任意的深克隆. 变换返回的集、树数据或无文件执行字段不支持。 公共合同和经核对的签名记录在 [API 合同文件](https://ai-markdown.github.io/docs/guides/api/core-engine-contracts/)。 。 。 .

## 常见问题

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

框架独立的管线会话,块规划,跨圆形贡献和Ai-markdown适配器的流协调\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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