API 规范与稳定性
本页汇总了适用于所有指南的契约：次版本更新下哪些内容保持稳定、共享包与适配器之间的关系、示例的编写方式，以及如何对照实现核对指南内容。按任务组织的页面见指南目录。
公开 API 自 3.0.0 起遵循语义化版本规范。请将统一版本发布的相关包一同升级。下表描述了稳定的 React API 策略；早期预发布版本可能存在不同的契约。Vue 拥有独立的公开属性与类型，具体记录在其参考文档中。
| 层面 | 次版本（Minor）更新下的稳定性保证 |
|---|---|
组件属性（AIMarkdownProps、MantineAIMarkdownProps） | 稳定。新增属性属于非破坏性变更；属性更名或移除需要主版本（Major）递增 |
Hook 签名（五个窄粒度 Hook、useAIMarkdown、useDocumentRegistry、useStableValue、useStableRecord） | 稳定 |
| 平铺属性名称与职责（包括密封插件名称） | 稳定 |
| 平铺属性默认值 | 可能会随默认行为优化在次版本中微调——若需锁定行为请显式覆盖 |
CSS 自定义属性名称（设计变量，例如 --aim-spacing-md） | 稳定 |
| CSS 自定义属性默认值 | 可能会随视觉设计演进而调整 |
UrlTransform、SanitizeSchema 类型 | 跟踪上游 react-markdown / rehype-sanitize；随上游主版本升级而变更 |
Registry 接口 | 稳定的只读接口；修改器方法故意不导出 |
| 内部逐字节对应的 HTML 输出 | 不保证稳定——应用测试建议使用语义化查询和断言 |
@ai-markdown/engine 导出的全部内容 | 3.0.0 起记录的稳定公开契约——详见下文 |
若有疑问，建议显式传入配置覆盖项，而不要依赖默认值。
@ai-markdown/core 负责与框架无关的会话、规划、贡献及平滑协调；@ai-markdown/engine 负责语法解析、语法树算法及注册表原语。两者均为具有明确导出的公开包。安装 @ai-markdown/react 或 @ai-markdown/vue 时，会将二者解析为精确版本依赖项。适配器开发者可以直接使用它们，保持五个统一版本发布相关包（engine、core、react、vue 和 react-mantine）处于严格相同的版本。对其已记录公开契约的破坏性变更需要升级主版本；React 包提供了在应用指南中使用的组件和 Hook API。已记录的契约本身见 Core 与 Engine 契约。
指南中的约定
Section titled “指南中的约定”- 代码块按用途进行标注。完整方案包含所需的导入语句；较小的片段假定已存在周围的应用上下文变量；封装模板使用明确命名的占位符模块。在使用前请安装相关包的对等依赖并导入必需的 CSS。
- 避坑指南章节收集了常见反模式与稳定性陷阱。有关跨适配器的故障现象与修复方案，请参阅故障排查。
// ✅与// ⚠️标注分别标识推荐模式与反模式代码行。- 当某项行为由
@ai-markdown/react与@ai-markdown/react-mantine共享时，示例使用AIMarkdown（React 适配器）；该用法同样适用于MantineAIMarkdown。
文档问题反馈
Section titled “文档问题反馈”如果你发现文档记录的 API 行为与实际不符，或者自定义配置在版本边界处发生破坏，请提交 Issue 并提供以下信息：
- 文档名称与所在章节，
- 精确的相关包版本（
@ai-markdown/react@x.y.z等）， - 最小化复现用例，
- 观察到的实际行为与预期行为。
Issue 追踪平台：https://github.com/ai-markdown/ai-markdown/issues
结合源码实现阅读指南
Section titled “结合源码实现阅读指南”在修改某项特性的文档之前，请沿其归属模块追踪该数据。公开属性在 React 适配器中解析；语法与增量算法归属于 engine；流水线会话、规划与贡献编排归属于共享 core；React Provider、生命周期 Effect 与缓存元素构建归属于 React 适配器；Mantine 负责自身的代码展示与分组默认值。在 engine 中导出的符号并不自动等同于受支持的 React API。
| 疑问点 | 应查阅的源码实现 | 应保持同步的指南 |
|---|---|---|
| 省略某个属性会产生什么行为？ | React 属性解析器与包装层的参数默认值 | 属性参考文档、迁移指南 |
| 何时可以复用原有的解析结果或块结构？ | 增量步进算法、块规划器、MarkdownContent | 架构设计、流式输出与性能 |
| 哪个片段拥有某项引用？ | 文档注册表与使用端占位符 | 跨片段协调、URL 安全清洗 |
| 展示或复制的文本具体是什么？ | 引擎预处理器链与 Mantine 代码渲染器 | 内容预处理器、Mantine 参考 |
| 流式结果何时宣告完成？ | 传输状态、平滑控制器、文档队列 | 对话示例、平滑流式输出 |
| 哪些测试证据能证明优化确实被执行了？ | 覆盖映射表、Oracle 测试、压测清单 | 压测覆盖、实验记录 |
在贡献文档时，请保留有价值的示例与历史测量数据，但须注明其对应版本与适用范围。请对照当前代码检出分支核对 API 名称、默认值、相对链接与 CLI 命令。构建成功仅证明相关包产物能够通过编译，本身并不足以验证所有正文论断或性能估算。