> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 状态与兼容性

## 版本状态

| 项目   | 当前状态                                                                           |
| ---- | ------------------------------------------------------------------------------ |
| 版本   | `0.1.0-alpha.1`                                                                |
| 发布渠道 | npm，alpha dist-tag；安装命令为 `pnpm add react-wikitext@alpha`                       |
| 稳定性  | 0.x 阶段按语义化版本约定，次版本可能包含破坏性变更                                                    |
| 变更记录 | 以 [GitHub Releases](https://github.com/BearBin1215/react-wikitext/releases) 为准 |
| 文档站  | [react-wikitext.pages.dev](https://react-wikitext.pages.dev)，与主分支同步；不提供按版本切换   |

安装步骤见[快速开始](/zh/guide/quick-start.md)。

## 运行时兼容

| 项目     | 支持范围                                    |
| ------ | --------------------------------------- |
| React  | `>=18.2 <20`（peer dependency）           |
| Node   | 运行时 `>=18.18`；仓库开发与 CI 主 job 使用 Node 24 |
| 模块格式   | ESM 与 CJS，均提供类型声明                       |
| 打包器    | Vite 与 webpack 5 的消费者构建有测试覆盖            |
| 浏览器    | 产物语法目标为 ES2022；不支持 IE 或更老的浏览器           |
| 运行环境依赖 | 不依赖 Wikimedia、字体 CDN 或外部 API            |

npm 包只包含 `dist/`、`NOTICE` 与 `THIRD_PARTY_LICENSES`；从源码构建与本地调试流程见[贡献指南](/zh/project/contributing.md)。

## 固定的上游

| 项目     | 值                                 |
| ------ | --------------------------------- |
| 解析器    | `wikiparser-node@1.48.1`          |
| 默认站点配置 | `MEDIAWIKI_CONFIG`，来源为同一版本的站点配置快照 |

升级解析器会改变 AST、源码范围与渲染基线，需要重新审查渲染与安全测试。

## 快照版本

| 常量                      | 当前值 | 适用     |
| ----------------------- | --- | ------ |
| `AST_SCHEMA_VERSION`    | `1` | 语义 AST |
| `SYNTAX_SCHEMA_VERSION` | `1` | 源码语法树  |
| `RENDER_SCHEMA_VERSION` | `1` | 渲染快照   |

版本变化意味着快照结构不兼容。缓存与跨进程传输时应把版本写入键；恢复函数会拒绝不匹配的数据。

## 样式与安全基线

- 样式在 `react-wikitext/styles.css`，需要显式引入；库不设置全局元素样式。
- 内联样式只保留白名单内的排版与外观声明，`url()`、`expression()`、`!important` 等值整条丢弃并产生诊断；不依赖 `eval`，严格 CSP 下如需这些声明生效，按需放行 `style-src`。
- 不使用 `dangerouslySetInnerHTML`；最终 HAST 由清洗器与 wiki 策略生成。
- 图片默认不加载；只有解析函数授权的地址（或显式开启的插件图片策略）才会成为 `<img>`。
- 渲染入口依赖 React Context，只能在客户端组件中运行；根入口与 `/view` 的产物顶部已带 `"use client"` 指令，宿主侧不需要重复标记。

完整边界见[安全模型](/zh/guide/security.md)与[渲染行为](/zh/guide/rendering.md)。

## 验证兼容性

仓库提供分层检查：

| 命令                         | 检查内容                                       |
| -------------------------- | ------------------------------------------ |
| `pnpm test`                | 单元与渲染测试                                    |
| `pnpm typecheck`           | 源码类型                                       |
| `pnpm test:types:consumer` | 消费者类型解析（Node16 与 bundler 解析）               |
| `pnpm test:consumer`       | dist 入口、子路径隔离、CSS、Vite/webpack 与 view-only |
| `pnpm bench`               | 解析与渲染基准                                    |

升级 React、解析器或打包配置后，至少运行 `test:consumer` 与 `test`。

## 许可

- 库以 **GPL-3.0-or-later** 发布。
- `wikiparser-node@1.48.1` 使用同一许可。
- 第三方依赖与署名见仓库根目录的 `NOTICE` 与 `THIRD_PARTY_LICENSES`。

在分发包含本库的产物前，请确认你的项目与 GPL-3.0-or-later 的兼容性。