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

# 入口总览

库按子路径提供功能，宿主可以只加载需要的部分。根入口是主入口；`react-wikitext/view` 是不加载解析器的精简入口。

## 处理管线

```text
source
  └─ /parse ─▶ WikitextDocument（原始解析快照）
        └─ /hast prepare ─▶ WikitextRenderDocument（HAST + headings + meta）
              └─ /view ─▶ React
```

可选的前置阶段：

```text
source ─▶ /expand ─▶ 展开后的 WikitextDocument ─▶ /hast ─▶ /view
```

## 子路径

| 子路径                         | 内容                                                                      | 加载解析器     | 加载 React |
| --------------------------- | ----------------------------------------------------------------------- | --------- | -------- |
| `react-wikitext`            | `Wikitext`、`WikitextView`、`WikitextFragment`、Context Hook、组件类型与精选语义类型   | 是         | 是        |
| `react-wikitext/ast`        | 语义模型、查询、辅助函数、纯解析器工厂、源码归一化、序列化                                           | 否         | 否        |
| `react-wikitext/parse`      | 默认解析器、`parseWikitext`、解析选项、解析错误                                         | 是         | 否        |
| `react-wikitext/expand`     | `expandWikitext`、模板展开类型与错误                                              | 是         | 否        |
| `react-wikitext/hast`       | `prepareWikitext`、`prepareWikitextAsync`、解析函数、策略、文案、标题策略、URL 工具、渲染快照序列化 | 否         | 否        |
| `react-wikitext/unified`    | `wikitextParse`、`wikitextRehype`、`wikitextFinalize`                     | 否（需注入解析器） | 否        |
| `react-wikitext/view`       | `WikitextView`、`WikitextFragment`、Context Hook、组件类型                     | 否         | 是        |
| `react-wikitext/configs`    | `MEDIAWIKI_CONFIG`、`ParserConfig`                                       | 否         | 否        |
| `react-wikitext/styles.css` | 页面渲染样式                                                                  | —         | —        |

根入口不导出 parse、expand、hast 与 unified 的功能。`/ast`、`/hast`、`/unified`、`/configs` 不加载默认解析器；`/parse` 与 `/expand` 会加载；`/view` 只加载 React 与已准备好的文档。AST 树与节点检查器属于内部 playground，不是公共入口。

## 解析快照与渲染快照

### 解析快照 `WikitextDocument`

```ts
interface WikitextDocument {
  readonly source: string;
  readonly ast: WikitextRoot;
  readonly syntax?: WikitextSyntaxRoot;
  readonly meta: WikitextDocumentMeta;
  readonly diagnostics: readonly WikitextDiagnostic[];
}
```

- `ast` 是原始归一化结果，准备阶段不会修改它。
- `syntax` 只在 `retainSyntax: true` 时出现，供 playground 与源码坐标使用。
- `meta` 记录解析器名称与版本、页面名、归一化状态与原长度。

### 渲染快照 `WikitextRenderDocument`

```ts
interface WikitextRenderDocument {
  readonly source: string;
  readonly ast: WikitextRoot; // 本次工作树结果
  readonly hast: import("hast").Root; // 已清洗的最终 HAST
  readonly headings: readonly WikitextHeadingInfo[];
  readonly meta: WikitextRenderMeta;
  readonly diagnostics: readonly WikitextDiagnostic[];
}
```

- `ast` 是插件处理后的工作树，节点 id 已重新分配。
- `hast` 已完成清洗与最终整理，包含目录、引用区与分类底栏。
- `meta` 记录实际生效的策略、文案、标题策略与授权图片。
- `WikitextView` 只接受渲染快照，不接收源码。

查询转换后的节点时，必须使用渲染快照；不要用渲染快照里的 id 查原始解析快照。

## 如何选择

| 需求             | 使用                            |
| -------------- | ----------------------------- |
| 客户端直接渲染源码      | 根入口 `Wikitext`                |
| 服务端准备、客户端只渲染   | `/parse` + `/hast` + `/view`  |
| 只做解析或 AST 分析   | `/parse` + `/ast`             |
| 展开模板后再渲染       | `/expand` + `/hast` + `/view` |
| 接入 unified 处理器 | `/unified`（显式注入解析器）           |
| 只替换站点配置        | `/configs` + `/parse`         |

## 类型与错误

- 错误类按入口分别导出：`/ast`、`/parse` 提供 `WikitextError` / `WikitextParseError`；`/expand` 提供 `WikitextExpandError`；`/hast` 提供 `WikitextPrepareError`。根入口与 `/view` 不导出错误类。
- `WikitextLabels` 类型可从 `/ast` 与 `/view` 导入；默认值 `DEFAULT_WIKITEXT_LABELS` 与 `DEFAULT_PREPARE_POLICY` 从 `/hast` 导出。
- 完整节点子类型从 `/ast` 导入；根入口只导出视图组件会用到的精选语义类型。
- 错误码、`stage` 与诊断字段见[错误与诊断](/zh/api/errors.md)。

## 参考页面

| 子路径         | 页面                            |
| ----------- | ----------------------------- |
| 根入口、`/view` | [React 组件](/zh/api/react.md)  |
| `/parse`    | [解析](/zh/api/parse.md)        |
| `/ast`      | [AST](/zh/api/ast.md)         |
| `/hast`     | [准备](/zh/api/prepare.md)      |
| `/expand`   | [展开](/zh/api/expand.md)       |
| `/unified`  | [unified](/zh/api/unified.md) |
| `/configs`  | [configs](/zh/api/configs.md) |

## 下一步

- [React 组件](/zh/api/react.md)：源码组件、视图、Fragment 与 Context Hook。
- [解析 `/parse`](/zh/api/parse.md)：解析器、预算与自定义适配器。
- [准备 `/hast`](/zh/api/prepare.md)：插件、解析函数、策略与快照恢复。
- [错误与诊断](/zh/api/errors.md)：错误码与处理建议。
- [状态与兼容性](/zh/project/status.md)：版本、快照版本与运行时要求。