通用 Markdown 插件系统规范¶
合约概览¶
| 领域 | 合约 |
|---|---|
| 公开合约 | 一个附加的 plugins 属性和 createMarkdownPlugin()。插件仅暴露 syntax、不可变的 transform 和 renderers。文本匹配、语义围栏和源码装饰是由辅助程序编写的变换,而非独立的协议阶段。 |
| 行为 | 解析、变换、Markdown 渲染和 Outline 都观察同一个稳定、严格类型化、与 MDAST 对齐的树。有序的变换返回经过验证的替换树,而 Core 保留内置语义和可读的回退。 |
| Remark 兼容性 | 一个单独的适配器可以在文档所支持的 MDAST 子集上运行仅同步变换的 Remark 插件。解析器扩展、异步插件、编译器插件、任意 VFile 状态和不支持的节点种类都会被拒绝,而不是被近似处理。 |
| 终端用户影响 | 读者可能会获得额外语法和变换后的文档结构,而普通 Markdown、可复制回退、标题与 Outline 标识、无障碍、导航、图片、列表和表格仍保有规范归属。 |
| 构建器影响 | 现有构建器不执行任何操作。选择加入的构建器传递一个稳定的插件列表。简单的文本、围栏和装饰用例使用返回变换的辅助函数。 |
| 兼容性 | 省略插件与 plugins={[]} 在语义上是相同的空流水线。Core 可以跳过空准备和空分配,但不存在独立的行为模型。现有的 components、inlinePlugins、数学、引用、自动链接和解析器签名保留其含义。 |
| 评审检查 | 拒绝第二个插件属性、公开的特定生命周期阶段、可变的共享 AST、原始标记节点、插件对 Core 语义的覆盖、无界解析器钩子、静默的 Remark 不兼容、由变换驱动的重新解析,或与每个插件在每个源字符上成比例的计算工作量。 |
| 治理规则 | architecture:public-component-api;family:navigation-destinations;AST-002 FR4;AST-002 FR15;AST-002 FR17;AST-002 FR18;AST-002 FR20。 |
本节是评审投影视图;以下正文为权威内容。
意图¶
应用作者应该能够添加可复用的 Markdown 行为,而无需重写源文本、派生解析器或替换整个渲染器。一个易于理解的模型必须涵盖新的源语法、文档级语义变换和类型化渲染。
公开的概念应少于用例的数量。散文替换、语义代码围栏、源码装饰、标注框、frontmatter、目录、脚注和兼容的 Remark 变换都使用同一个不可变的变换边界,而不是成为独立的协议阶段。
归属边界¶
AST-036 负责共享插件准入、语法和变换排序、兼容性、校验、失败行为、解析标识、Remark 适配器限制以及可观察的资源约束。Markdown 负责其具体的 AST 声明、解析器集成、聚合渲染和辅助函数。Outline 负责其对 Markdown 标题标识的投影。第一方插件在自己的模块记录中负责其特定语义和证据。
非目标¶
- 不采用 Unified、可变 MDAST、
VFile或 Remark 作为 Core 运行时依赖。 - 不在获得单独批准的迁移之前破坏已发布的
parseMarkdown结果形态。 - 不承诺与任意 Remark 解析器、变换、编译器、异步或原始 HTML 插件兼容。
- 不暴露可变的共享 AST、不受限制的访问器、DOM 访问、包发现或注册表。
- 不替换通用 CodeBlock 高亮或 Core 拥有的文档、标题、导航、图片、列表或表格语义。
- 不使零插件文档成为一种独立的语义模式。
平台支持¶
- 特性与引擎下限: 与当前 Markdown/Core 包的支持保持一致;该协议不增加浏览器、React、Node 或 TypeScript 下限。
- 不支持的行为: 不支持的语法/变换/Remark 行为会安全失败(fail closed)至最后一个有效的可读文档,并且不能静默地近似输出。
- 浏览器证据: 交互式故事在真实 Chromium 中验证渲染输出、键盘/焦点顺序、可复制回退、导航归属以及不变的零插件行为;服务端渲染夹具覆盖非浏览器使用。
当前状态影响¶
| 当前接缝 | 保留的行为 | 新角色 |
|---|---|---|
components |
替换受支持的内置渲染器,包括全围栏代码渲染器。 | 优先于插件渲染;但若某个语义围栏提案先认领其围栏,则除外(FR17)。 |
inlinePlugins |
使用已发布的遍历、重叠、回调和错误行为来替换匹配到的散文。 | 保持兼容;后续迁移只会在完全对等之后,才通过由辅助函数支持的 transform 来适配它。 |
| 解析器与流式 API | 产生已发布的 AST,并复用已确定的增量输出。 | 接受语法插件并应用实时 transform,而不会让 transform 成为解析身份的一部分。 |
| Markdown 与大纲 | 共享内置标题文本和 slug 行为。 | 还共享转换后的标题投影和冲突分配。 |
语义模型¶
插件条目是一个不透明值,由 Markdown 的公共工厂函数 createMarkdownPlugin() 创建,并且只能通过有序的 plugins 数组接受。其公开形态为 {name, apiVersion: 1, syntax?, transform?, renderers?},并遵循以下规则:syntax 包含有序的有界行内/块级 tokenizer 声明,且必须提供 parseKey;transform 是一个同步的、不可变的 root-to-root 函数;renderers 是一个以节点名称为键的映射,其条目提供一个纯渲染回调和一个确定性的 toText 投影。插件不暴露其他生命周期阶段。普通对象不能伪装成插件条目,并且在严格的 TypeScript 下,异构列表会保留其扩展节点类型的并集。
公共构造表面是 createMarkdownPlugin()、createMarkdownTextTransform()、createMarkdownFenceTransform() 和 createMarkdownSourceDecoration()。有限的 Remark 兼容性是一个独立的、可摇树优化的 createMarkdownRemarkTransform() 导出,位于 @astryxdesign/core/Markdown/remark。这些辅助函数返回或标注单一的 transform 能力;它们从不接受 React 渲染回调,也不是额外的生命周期阶段。特别地,createMarkdownFenceTransform() 将符合条件的内置代码节点映射到所属插件的类型化扩展数据,而该插件的标准 renderers 映射负责呈现和 toText。详细的 TypeScript 签名和示例位于 Markdown 消费者文档中,而这些名称和职责属于本契约的一部分。
权威文档是一个不可变的、可判别联合的、Unist 形状的树,与下面受支持的 MDAST 子集对齐。MDAST 是由 syntax-tree/unified 生态维护的公共社区规范,而不是浏览器或标准机构的 API。 Astryx 的公共契约是其自身导出的、带版本号的 TypeScript 节点联合:它在一致之处使用所列出的 MDAST 节点名称和字段含义,记录每一个偏差,并且不承诺与任意 mdast、Unified 或第三方插件版本之间存在名义上或结构上的互换性。parseMarkdownAst() 和 parseInlineAst() 从服务端安全的 @astryxdesign/core/Markdown/parser 子路径额外暴露该树;组件 barrel 也会为客户端代码重新导出它们。解析、transform、Markdown 渲染和大纲投影遵循相同的节点含义。已发布的解析器入口通过兼容性边界保留其当前的结果类型和值;采用插件无需迁移。
Markdown 模块暴露稳定的节点联合和按节点类型收窄的遍历。插件定义的扩展类型扩充通用联合,而不会扩大无关的内置回调。transform 接收只读输入,并返回原始根或替换根。允许使用等效的验证和不可变性实现。
语法贡献声明非空的字面量前缀、有限待处理边界,以及一个同步确定性的 tokenizer。它只能发出其所属的类型化扩展节点。携带语法的插件声明稳定的解析身份;只有有序的语法身份参与增量解析身份。
transform 是同步且确定性的。它可以在允许编辑的矩阵内替换、插入、删除或标注可表示的节点。它不能修改输入、生成来源出处、引入原始标记或 React 值,也不能绕过 Core 拥有的语义。transform 的更改会刷新转换后的输出,而不会改变语法解析身份。
渲染器只接收类型化的扩展节点数据。每个通过语法或 transform 引入的扩展节点都有一个渲染器以及确定性的可感知文本投影。基于源码的叶子节点回退到精确的作者源码;合成叶子节点回退到其必需的文本投影;容器保留并渲染其经过验证的子节点。失败后,兄弟内容继续。
每种扩展类型声明 content: 'none' | 'phrasing' | 'flow',或一个有限允许列表,用于收窄 display 所隐含的类别。Core 在每个 transform 边界验证子节点。由语法创建的容器声明一个由 Core 解析的内部源码跨度;插件永远不会将原始源码转换为子节点。插件可以读取或删除另一个插件的节点,但只能创建、编辑或复制自己的节点。跨插件读取通过 dependsOn 声明,并对照列表顺序进行验证。
插件准入以及每个失败阶段在开发与生产环境中都使用同一个无源码、限速的 onPluginDiagnostic 通道。格式错误的条目和协议版本不匹配会在本地失败,而不是抛给调用方。插件生成的报告使用稳定的代码,绝不使用从文档派生的文本。
文本匹配、语义围栏和源码装饰都是可选的转换辅助工具,而非额外的公开阶段。只要保留有序转换语义和可观察结果,就允许进行等效的优化执行。
标准 MDAST 兼容性矩阵¶
| 节点或字段 | 支持的契约 | 被拒绝或受限的行为 |
|---|---|---|
root、children |
一个根节点;有序且有类型的子节点。 | 移除/重新类型化根节点;循环引用;共享的可变子节点。 |
text、value |
文本的替换、拆分、插入和移除。 | 函数、React 值或非字符串的 value。 |
paragraph、strong、emphasis、delete |
有序的短语子节点。 | 短语容器内的块级子节点。 |
heading、depth |
短语子节点可以转换;转换后的文本参与共享的 Markdown/Outline 身份。 | 更改由源码支持的标题的深度;渲染器定义的 ID。 |
inlineCode、break |
标准 MDAST 语义。 | 通过文本辅助工具转换受保护的内联代码内容。 |
link、url、children |
短语子节点;每个由 Astryx 持有的目标地址都由导航所有者重新验证。 | 嵌套链接;绕过目标地址策略;非字符串的 URL。 |
image、url、alt |
重新验证的资源 URL 和替代文本。 | 绕过资源策略或移除必需的替代文本。 |
blockquote |
有序的块级子节点。 | 无效的子节点类型。 |
list、listItem |
ordered、可选的 start、spread、可选的 checked,以及块级子节点。Astryx 还会保留作者编写的有序列表 delimiter,以实现精确的发布投影。 |
无效的任务/列表结构或非有限的 start 值。 |
code、lang、meta、value |
MDAST 语义:lang 在缺失时为 null,meta 是可选的。普通代码保持可复制;围栏辅助工具会标注原始节点。 |
通过围栏辅助工具替换/移除源码;为没有提案声明的围栏绕过 components.code。 |
| Astryx 流式图片 | 保留已发布的独立图片块行为(带有 url 和 alt);短语图片保持正常的 MDAST 位置。 |
在没有适配器证据的情况下将流式扩展视为可移植的 MDAST。 |
table、tableRow、tableCell、align |
矩形行、短语单元格、规范化对齐。 | 替换 Core 表格语义或生成参差不齐/无效的结构。 |
thematicBreak |
标准 MDAST 语义。 | 子节点或渲染器插槽。 |
math, inlineMath |
仅在已发布的数学公式(math)可选功能启用时出现。 | 仅通过转换单独启用数学功能。 |
position |
由核心(Core)提供的、位于源支持节点上的可选起始/结束 UTF-16 偏移量;在可获取且不改变已发布范围行为之前,行和列仍保持可选。合成节点省略 position。 |
编写、移动或伪造源位置。 |
data |
所属插件键下的有限类 JSON 插件数据;Core 簿记使用一个保留的 astryx 命名空间,其本身不产生渲染效果。 |
hName、hProperties、hChildren、函数、DOM/React 值、原始标记通道,或插件自行编写的 Core 保留数据。 |
| Astryx 扩展节点 | 稳定的 plugin/name/display/data 判别符;声明 none、phrasing、flow 或收窄后的允许列表内容;渲染器与文本投影。 |
外部铸造/编辑/复制、未声明的子节点、缺失投影/渲染器,或更改另一插件的判别符。 |
| Astryx 引文节点 | 作为 MDAST 子集的一个自有类型扩展被保留。 | 将其改写为链接以绕过引文所有权。 |
| 其他 MDAST 节点 | 除非后续当前合约新增它们,否则不受支持。 | html、定义/引用、脚注、frontmatter、指令、MDX 及其他未知节点在 Remark 适配器中一律拒绝(fail closed)。 |
允许的转换编辑¶
| 表面 | 允许的 | 被拒绝的 |
|---|---|---|
| 文档根节点 | 返回同一根节点或结构上有效的替换根节点。 | 移除/重设根节点类型,或添加独立渲染的文档外壳。 |
| 源支持的文本与措辞节点 | 在保留受保护上下文的同时,进行替换、拆分、插入、移除或注释。 | 文本辅助器在受保护代码、链接、图像、引文、数学公式或已接受的模糊语法内部进行匹配。 |
| 标题 | 转换措辞子节点;移除或重排标题;根据转换后的文本进行共享身份更新。 | 更改源支持的深度、伪造/复制来源或身份,或提供仅供渲染器使用的 ID。 |
| 链接与图像 | 插入或更新能通过当前导航/资源所有者校验的值。 | 绕过目标地址、协议、替代文本或可信资源策略。 |
| 列表与表格 | 插入、移除或转换有效后代节点,同时保留 Core 持有的语义。 | 更改角色、所有权,或产生无效结构。 |
| 代码围栏 | 语义围栏辅助器可将自有类型扩展数据附加到原始代码节点上。 | 通过辅助器替换源代码、在辅助器内部渲染,或声称某个它并未注释的围栏。 |
| 源装饰 | 将非语义、非交互的呈现元数据附加到受源支持的范围。 | 更改 AST 含义、焦点顺序、无障碍名称、导航、选择或可复制文本。 |
| 插件扩展节点 | 插入/编辑转换所有者的节点;读取或移除外部节点/子树;保留已验证的子节点。 | 铸造、编辑、复制或在内部重排另一插件的节点;未声明的子内容。 |
| 行内入口点 | 精确返回一个包含措辞节点的段落等价根节点。 | 块级节点、多个顶层块,或更改后的容器形态。 |
有限 Remark 兼容性配置¶
Remark 适配器接受仅限于上述矩阵的同步纯转换插件。每次调用都会获得一个全新的可变树副本和一个隔离的受限文件对象。该文件对象公开只读源代码文本、每次调用的有限 JSON 数据和诊断报告;它不公开处理器注册、跨运行状态、编译器、I/O 或异步完成。
适配器的输入类型在结构上与常规 Unified/Remark Plugin 值兼容,包括其宽泛声明的转换器返回联合类型,因此兼容包无需类型包装。运行时接受范围仍然更窄:实际返回 promise 或使用不受支持能力的调用会失败关闭(fail closed)。Astryx 导出自身受支持的子集树和文件类型,而不是重新导出或固定完整的 mdast/Unified 类型面,因此上游类型演化无法悄悄扩大 Astryx 的契约。
Remark 兼容性仅限内容,而非呈现兼容性。适配后的插件只能返回受支持的结构化节点和字段;Astryx 仍通过自己的组件、token、导航/资源策略和无障碍语义渲染这些节点。html、hName、hProperties、hChildren、自定义编译器输出、CSS 假设以及第三方渲染器约定都会被拒绝,而非近似处理。需要新呈现方式的插件必须使用 Astryx 自有的类型化扩展节点和渲染器,且位于 Remark 适配器之外。
适配器会在插件返回或变更的树可被观察到之前,依据矩阵对其进行校验。不支持的节点、原始 HTML、promise、共享的处理器状态、无效结构、伪造的源码位置以及无法表示的元数据,都会保留最后一个有效树,并报告一条无来源诊断。
兼容性是对每个插件和受测版本的显式承诺。“Remark 兼容”意味着等价的受支持子集测试夹具(fixtures)能通过适配器矩阵;仅凭包形态或生态系统成员身份不构成证据。使用处理器数据、micromark 扩展、异步工作、不受限制的 VFile 行为、不支持的节点、渲染器元数据或编译器钩子的插件不在该兼容性档案(profile)范围内。
要求¶
准入与兼容性¶
- FR1 — 单一公共插件模型。
plugins和createMarkdownPlugin()是规范的扩展接缝。协议能力仅限于syntax、transform和renderers;辅助 API 可将常见用例编译为转换。 - FR2 — 单一空管道行为。 省略插件与空列表在 AST、DOM、样式、目标、ID、错误和流式行为上完全一致。核心可以避免空的规范化和分配,但任何行为都不得依赖于空列表是否被显式指定。
- FR3 — 零破坏性变更。 现有的
components、inlinePlugins、引文、选择启用的 GFM 自动链接、数学公式、源码、解析器签名、字段、可选性、可变性、无插件结果类型、DOM、无障碍、标题/Outline 标识、流式复用及渲染器优先级均保留其已发布的意义和行为。选择启用插件只会为当前调用点新增行为。 - FR4 —
inlinePlugins仅在对等后迁移。 在辅助函数支持的转换保留每个已发布的遍历上下文、重叠规则、回调结果、null、抛出行为、迁移文档和 codemod 要求之前,不会发生弃用。 - FR5 — 条目是持久的包值。 一方插件并置于 Markdown 下并按常规导出;第三方插件是显式包导入,并带有兼容的 Core peer 范围。不存在注册表或发现机制。
解析与不可变转换¶
- FR6 — 固定顺序。 内置和扩展语法先行解析;转换随后按插件数组顺序运行;渲染最后运行。每个转换都能观察到所有先前转换的已校验结果。
- FR7 — 内置词法屏蔽在语法阶段优先。 转义、行内和围栏代码、链接、图片、引文、数学公式以及已被接受的不透明语法,都会根据其当前所有者保持受保护。块级扩展语法保持顶层,除非当前所有者明确将其扩展。
- FR8 — 有序语法声明。 重复的插件名无法通过校验。语法贡献按插件和声明顺序解析;首个匹配获胜,延后(defer)保留有界候选,最终解析处理所有待定源码。
- FR9 — 规范 AST 与 MDAST 对齐、严格类型化且可访问。 解析、转换、渲染和 Outline 投影使用一个稳定的 Unist 形状子集,并带有完整的可用源码位置。
parseMarkdownAst()和parseInlineAst()从服务器安全的@astryxdesign/core/Markdown/parser子路径以及 Markdown 组件桶文件(barrel)返回该规范树。公共节点类型遍历按判别式收窄回调,包括通用插件扩展。已发布的解析器函数在另行批准的迁移之前,保留其现有结果类型和值。 - FR10 — 转换输入不可变。 转换返回同一个根节点或替换根节点。尝试进行的修改无法改变任何已观察到的输入节点、数组、数据对象、源码位置、先前快照或后续插件的输入。
- FR11 — 转换输出可表示且经过校验。 输出是有限、无环、类型化的数据,满足上述两个矩阵。Core 会拒绝原始 HTML、React 值、DOM 节点、节点数据中的函数、无效内置结构、外来扩展所有权、人为创建/偏移的来源信息,以及来自行内入口点的块状输出。
- FR12 — 转换失败仅影响该插件。 抛错、promise、被拒绝的 thenable、无效结果或不受支持的适配器输出会报告一条无来源诊断,并将最后一个有效根节点传递给后续插件和渲染。Core 在拒绝异步 tokenizer 或转换之前会附加一个拒绝接收器(rejection sink),因此被拒绝的 promise 无法通过宿主的 unhandled-rejection 通道逃逸。基于源码的节点保留作者源码回退;合成扩展叶子使用其必需的可感知文本投影;扩展容器保留其经过校验的子节点。
- FR13 — 实时转换不会重新解析或修改已保留的输出。 添加、移除、重排或更新转换会刷新转换后的输出,而不会重新运行语法 tokenization。只有当前解析器选项和有序语法标识会使语法解析标识失效。先前的快照保持不变;不变且已定型的旧输出保留其已发布的复用和重新挂载行为。
渲染与跨表面身份¶
- FR14 — 扩展渲染是完整且本地的。 插件可能引入的每种扩展类型都有一个所属渲染器和可感知文本投影。当渲染缺失或失败时,对于以源码为支撑的叶子节点保留精确的作者源码,对于合成叶子节点保留所需的投影,对于容器保留已验证的 Markdown 子节点;兄弟节点继续运行。
- FR15 — 核心语义保持权威性。 插件不能替换文档根节点,也不能覆盖 Core 拥有的标题层级/ID、导航、图片策略、列表语义、表格语义或内置无障碍行为。受信任的渲染器创建的链接和资源仍归渲染器所有。
- FR16 — 单一选定的标题投影。 Markdown 与源自 Markdown 的 Outline 使用相同的语法列表、转换列表、文本投影和已安装的标题投影。已发布的投影保持顶层;
module:Markdown/headingLinks可以通过相同的不透明插件列表选择加入其单独拥有的投影,而无需更改 Outline 选择。渲染器输出不能改变身份。 - FR17 — 语义围栏在代码覆盖之前声明其围栏。 语义围栏辅助器可以标注一个符合条件的最初代码节点,但不能替换其源码。渲染首先解析辅助器提案:当所属插件的渲染器渲染它时,该输出替换围栏。
components.code渲染所有无提案声明的围栏,并且是已声明围栏在渲染器缺失、返回空、抛错或挂起时的本地回退。没有components.code时,普通可复制代码就是该回退。
Remark 兼容性¶
- FR18 — 适配器范围明确。 适配器仅支持文档化 MDAST 子集上的同步纯转换插件。它不模拟 Unified 解析器/编译器注册、异步执行、处理器状态或无限制的
VFile行为。 - FR19 — 转换无损耗或被拒绝。 每个被适配的节点和元数据字段都有文档化的往返过程。不支持的输入或输出会以可读源码的形式被拒绝;适配器绝不会静默丢弃或近似内容。
- FR20 — 兼容性按插件逐一测试。 只有在测试夹具证明了等价的受支持子集输出、受保护上下文行为、诊断、源码保留和服务端渲染之后,包才能被称为兼容。
资源¶
- FR21 — 未声明的工作是有界的。 辅助器回调仅在实际声明时运行;未匹配的源码无法调用它。稳定且重新创建的语义等价插件列表都必须满足 FR23,且无需任何特定的准备或分发实现。
- FR22 — 现有解析器预算仍然是最低标准。 权威的解析器性能测试夹具仍保持通过:完整解析在 10/50/200/500/2000 个节时保持在 20/50/100/400/1000 毫秒以下;完整与增量 50 字符流式解析在 50 个节时低于 5000 毫秒,在 500 个节时低于 30000 毫秒;增量时间最多为完整重新解析的 1.1 倍;其精确的稳定尾部工作量、对象复用、源码范围、中位数/最差块以及被跟踪的完整前缀断言保持不变。
- FR23 — 聚焦的开销预算覆盖两条转换路径。 根据下方证据协议,每个预算都指明其所测量的路径。第一方辅助器转换:在两种夹具规模下,五个零工作量辅助器最多增加 15%,代表性三辅助器组合最多增加 25%。插件编写的转换(需承担完整的不可变性和验证守卫):在两种夹具规模下,五个零工作量转换最多增加 30%,代表性三转换组合最多增加 50%。流式处理代表性插件编写组合时,保持在 FR22 的流式预算之内,且最多为空管道下同一流式的 1.25 倍。每个转换的守卫工作量受限于对该转换输出的一次遍历;全文档不变量收集每次管道运行只发生一次,而不是每个转换一次。仅当辅助器自身的构造已经保证该属性时,Core 才可以跳过对辅助器编写的转换的守卫,并且已发布的预算必须说明某个数字描述的是哪条路径。
- FR24 — 可选工作保持可选。 服务端安全的
@astryxdesign/core/Markdown/parser子路径不包含客户端指令或组件依赖。Remark 适配器、一致性测试套件和重型渲染器都是可摇树优化的,并且在仅解析器/服务端 bundle 中不存在,除非被导入。
扩展容器、所有权与节点数据¶
- FR25 — 扩展节点声明其内容。 每种扩展类型都声明
'none'、'phrasing'、'flow'或带可选有限基数界限的显式允许列表。允许列表收窄其display已暗示的类别,且永远不会加宽该类别;并且扩展类型的名称不得与受支持的内置节点名称冲突。Core 在准入时验证声明,并在每个转换边界验证实际子节点。由语法生成的容器声明一个 Core 解析的内部源码跨度;没有插件提供由原始源码构建的子节点。容器计入内置容器深度界限,既不会重新开始也不会独立界定 FR16 下选定的标题投影,并且在其渲染器失败时保留其子节点。 - FR26 — 所有权是铸造和编辑,而非存在。 转换可以读取另一个插件的扩展节点,也可以移除它们,包括移除包含这些节点的子树。它不得创建、编辑、重排另一个插件所拥有节点的内部结构,或复制该节点。源标题可以被移除或插入,但其深度不得更改,其身份不得被伪造或复制。根据此规则的每次拒绝都会报告一条诊断信息,指明所有权规则和所属插件,而不是通用的无效文档代码。
- FR27 — 插件声明其所读取的插件。
dependsOn列出插件所读取扩展节点的插件名称。准备阶段验证每个被指定的插件是否存在且排在更前。未满足或顺序错误的依赖是声明方插件的局部失败:其转换不会运行,其语法和渲染器保持激活,并且一条诊断信息区分缺失与顺序错误。不声明任何依赖则保持仅按数组顺序的行为。 - FR28 — Core 内部的每节点状态位于一个保留的数据命名空间中。 Core 自身的每节点簿记是节点
data的文档化保留键,而不是隐藏的、不可枚举的或签名匹配的通道。插件数据位于所属插件的键之下。插件可以读取保留数据;创建、编辑、伪造或移除该数据将被拒绝并附带诊断信息。
诊断与失败可见性¶
- FR29 — 单一诊断通道,生产环境同样生效。
onPluginDiagnostic在组件和解析器选项中均可用,每个失败或建议都会收到一个事件:插件名称、阶段(admission、syntax、transform、render 或 adapter)、稳定的枚举代码和严重级别。事件按构造即不携带来源——没有文档文本、节点值、目标或位置——并且在开发和生成环境中都会交付。交付按文档以及插件/阶段/代码维度进行限速,当达到上限时会通过抑制代码报告。在没有处理器的情况下,开发环境会将每个唯一代码显示一次,而生产环境保持静默。context.report()接受插件作者提供的稳定代码,而非文档派生文本,并以建议而非失败的形式交付。任何将文档静默降级为缩减插件行为的条件(包括超过校验大小限制)都会发出诊断。 - FR30 — 准入与版本失败是统一且软性的。 格式错误的条目、重复名称、不受支持的协议版本,或其他不可准入的列表,在组件和每个公开解析器入口上的表现完全一致:调用以最后一个有效配置成功——当没有任何可准入项时为空管道——报告一条诊断,并且绝不会向调用方抛出异常。协议版本不匹配绝不会在导入时或模块作用域内抛出。由兼容的重复 Core 副本创建的插件身份,会通过稳定的跨包品牌保持有效;该品牌的冻结形状和版本会得到验证。
创作、规范 API 与打包¶
- FR31 — 扩展类型是推断得出的。
createMarkdownPlugin()从其声明中推断插件的扩展节点联合。任何调用点都无需显式类型参数或手写节点别名,即可在renderers、transform、遍历以及聚合列表联合中获得正确的收窄。如果声明生成了扩展节点但没有匹配的渲染器,或者在使用扩展种类时解析为空扩展联合,这将是类型错误,而不是静默放行的never。 - FR32 — 规范 AST 具有公开解析入口。
parseMarkdownAst()和parseInlineAst()返回这些类型所描述的规范树,接受与组件相同的选项和有序插件列表,并与已发布的parseMarkdown系列并列,后者保持其投影后的结果形状。 - FR33 — 存在服务端安全的解析器入口。
@astryxdesign/core/Markdown/parser导出解析能力、规范 AST 类型和插件准入,且没有客户端边界指令,因此服务端导入方不会引入客户端引用。它像适配器入口一样,被注册到生成的导出映射中,并有一个导入夹具覆盖。 - FR34 — 一致性套件为每个插件生成证据。
@astryxdesign/core/Markdown/testing导出插件作者运行后能产生 FR20 所需证据的夹具:受保护上下文、不可变性、校验拒绝、失败回退与诊断、容器内容校验、流式幂等性以及服务端渲染。它是可被 tree-shake 的,不会出现在运行时打包产物中。 - FR35 — 兼容性与限制在使用方文档中有说明。 使用方文档发布受支持和被拒绝的类别,并给出 Astryx 对每一项的答案:仅转换内容的改写器受支持;任何扩展语法、输出 markup 或 hast、依赖处理器或文件状态、或仅报告消息的类别都不受支持。文档会直白说明不存在原始 markup 阶段,指出哪些原生能力让特定插件类别变得不必要,并说明渲染器是任意应用程序代码,因此信任边界是插件包而非文档。
流式、主题与稳定性¶
- FR36 — 转换在流式处理下是幂等的。 每次流式更新都会再次运行转换。给定相同的源前缀,它必须返回相同结果,并且其输出必须随着前缀增长而收敛而非振荡。其效果仅在完整输入上有效的转换使用最终输入信号。证据包括跨分块边界的无振荡夹具。
- FR37 — 扩展输出具有可选加入的主题目标。 扩展渲染器可以选择加入一个由 Markdown 拥有的扩展主题目标,从而使主题可以作用于插件输出。选择退出会使输出不指向任何主题目标。该目标除 Core 已应用的块间距和内容宽度外,不带有默认样式或结构,也不会让插件输出成为 Markdown 默认结构的一部分。
- FR38 — 相同列表会复用已准备的工作。 语义相等的插件列表会在各次渲染间复用已准备的语法和转换工作,无论数组引用是否稳定,因此准备成本不会与渲染次数成比例。在无法建立复用的情况下,开发环境会报告一条标识被重新创建列表的诊断,使用方文档也会给出提升(hoisting)指导。
- FR39 — 协议稳定性是公开的。 首次公开发布会明确
apiVersion覆盖什么——入口形状、能力名称、扩展节点判别值、声明的内容形状、诊断代码与阶段,以及规范节点联合——和不覆盖什么——辅助内部实现、未列出的 AST 字段、Core 保留的节点数据和诊断文本。会使现有符合规范的插件失效的变更会提升apiVersion;纯新增能力则不会。该策略会声明哪些 Core 版本接受给定的apiVersion,以及版本偏差如何失败,并与 FR30 一致。
规划的第一方范围¶
- FR40 — 第一方插件使用公开协议。 Astryx 通过公开的不透明插件列表发布一小套第一方插件——软换行、标题链接、可配置实体引用和提示框容器——每个插件都在自己的模块记录中拥有其语义和证据,并作为规范文档示例。任何第一方插件都不会获得第三方无法获得的公开能力、校验豁免、排序特权或类型便利;只有在模块记录拥有该行为且空管道保持不变的情况下,才允许内部组合接缝或快速路径,依据 FR3。
- FR41 — 脚注、定义和引用保持 Core 范围。 它们不属于插件表面:其本质是文档级 ID 分配、冲突处理和反向引用导航,这些由 Core 依据 FR15 和 FR16 拥有;若由插件拥有它们,就会分叉 Markdown 与 Outline 共享的标识系统。在另行批准的契约将它们添加为 Core 语法之前,它们不受支持,适配器会拒绝它们,使用方文档也会明确说明这一缺口,而不是暗示存在插件变通方案。
性能证据协议¶
- 测试夹具: 一份确定性的 200 节与 500 节文档;每节包含一个标题、一段带标识符和提及的正文、一个双项列表、一个块引用、一行表格,以及一个普通围栏代码块。
- 辅助器零工作量集合: 五个预制的第一方辅助器转换,其选择器有效但不匹配任何夹具节点或源跨度。
- 辅助器代表性集合: 三个辅助器,分别匹配正文标识符、注解符合条件的代码围栏,以及装饰已知的源范围。
- 插件编写的零工作量集合: 五个插件编写的转换,原样返回其输入根节点,走完整的不可变与验证路径。
- 插件编写的代表性集合: 三个插件编写的转换,分别重写匹配的正文文本、将某个节包装进扩展容器,以及在声明依赖下读取前一个插件的节点。
- 流式集合: 将插件编写的代表性集合应用于以 50 字符块流式传输的 200 节夹具,并与同一流上的空管道结果进行对比。
- 对比: 省略/空管道与具有稳定插件列表的同一解析-转换调用,在同一个隔离进程和运行器中进行比较。
- 采样: 十次不计时预热,随后九轮交替配对;每侧每轮平均执行 20 次迭代。报告比值是九轮配对比值的中位数。200 节和 500 节的比值都必须满足 FR23。超出测量有效性边界的 A/A 对照会使该样本无效;测试框架会重试,而不是认定噪声输出有效。在首次有效样本超出预算后,稳定列表与重建列表将分别按预算和夹具大小单独判定:在最多九个新进程有效样本(含第一个)中,若有五个超出预算,则该列表失败。
- 成本形态证据: 守卫遍历计数被直接断言,因此增加一个转换最多只能增加一次输出遍历,并且不得重复进行整文档不变量收集。
- 回归信号: 对未认领的源调用辅助器回调、多次调用已认领的辅助器、在解析/结果复用上出现回退,或发布数值却不指明其路径,都必须使工作量计数或阈值证据失败。
公有解析器集成¶
块级、行内、增量、规范 AST、Markdown 和 Outline 入口都接受相同的有序插件配置,并推断相同的扩展节点联合类型,同时保留其已发布的签名和预期结果形状。规范入口直接返回规范树;已发布入口保持其投影。服务器安全解析器入口在客户端边界之外暴露相同行为,Markdown 组件 barrel 会为客户端代码重新导出它。行内转换必须满足单段措辞约束。仅转换的更新不得增加语法分词器调用、不得修改先前的快照,也不得在当前行为之外重新挂载未更改的已定型输出。
公有 API 准入证据¶
| 调用方所有的区别 | 之前/未更改的默认行为 | 显式启用的调用点 | 为什么 Core 无法自行推导 |
|---|---|---|---|
| 无插件行为 | <Markdown>{source}</Markdown> 和 parseMarkdown(source) 保持已发布输出不变。 |
<Markdown plugins={plugins}>{source}</Markdown> |
只有应用程序知道它信任哪些扩展包及其在此文档中的顺序。 |
| 新式源语法 | 预处理源或分支解析;components 和 inlinePlugins 无法认领新的块级/行内语法。 |
createMarkdownPlugin({name, apiVersion: 1, parseKey, syntax, renderers}) |
应用程序拥有字面语法、有界分词器、解析版本键和扩展语义。 |
| 语义正文/围栏/范围工作 | 现有的 inlinePlugins 仍然可用;components.code 仍作为未认领围栏的代码覆盖项。 |
将 createMarkdownTextTransform()、createMarkdownFenceTransform() 或 createMarkdownSourceDecoration() 放入插件的唯一 transform;通过 renderers 渲染类型化输出。 |
只有插件知道哪些正文、语言或源范围具有领域含义;辅助器无法推断产品语义,也绝不拥有渲染。 |
| 富扩展容器 | 没有自定义容器语法或渲染器处于活动状态。 | 声明 content: 'phrasing' | 'flow' | {allow, min?, max?} 并通过所属渲染器渲染 Core 解析后的子节点。 |
Core 可以验证并解析子节点,但无法推断某个产品概念是 callout、card、tab 还是叶节点。 |
| 跨插件观察 | 仅凭数组顺序无法声明依赖关系。 | 在读取其节点之前添加 dependsOn: ['earlier-plugin']。 |
只有后一个插件知道其转换需要另一个插件的输出;Core 负责验证存在性和顺序。 |
| 诊断 | 在没有处理程序时,开发环境报告独特的失败,生产环境保持静默。 | 传入 onPluginDiagnostic={event => report(event)} 或解析器等价物。 |
宿主拥有遥测目标和保留策略;Astryx 拥有与来源无关的受限事件形状,而非日志系统。 |
| 规范/服务端解析 | 已发布的解析器调用保留其投影联合类型。 | 当服务端或转换工具需要规范树时,从 @astryxdesign/core/Markdown/parser 导入 parseMarkdownAst。 |
Core 无法推断调用方需要已发布的兼容性数据还是规范的扩展感知结构。 |
| 源自 Markdown 的 Outline | 现有调用省略选项并保留已发布的标题。 | 将相同的 plugins 和最终性传递给 Markdown 以及 parseOutlineFromMarkdown/useOutlineFromMarkdown。 |
调用方决定两个界面所代表的文档/插件配置;Core 则负责共享的文本/slug 标识。 |
| 主题可达性 | 默认情况下,渲染器输出不针对主题。 | 设置渲染器可选加入的 Markdown 扩展主题目标。 | 只有渲染器作者知道其应用自有的输出是否应参与设计系统主题化。 |
这些新决策是增量式的,且为可选加入。components 可以替换受支持的内置渲染,但无法添加源语法或文档转换。inlinePlugins 执行已发布的正文匹配,但无法添加块语法、规范的整树转换或类型化扩展所有权。现有解析器选项无法表达应用定义的语法、渲染器所有权、声明的跨插件依赖关系或宿主诊断。因此,这些保留下来的区分归属于调用方,Core 无法安全地推导它们。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR5 | 公共类型/导出夹具、DOM/AST 快照、重复 Core 副本夹具,以及上述调用点矩阵 | 省略、显式为空、稳定/重建列表、每个已发布的属性和解析器重载、一个图中存在两个 Core 副本 | 移除空值等价性、更改已发布的签名,或拒绝由兼容的第二个 Core 副本创建的条目,都会失败。 |
| FR6–FR13 | 语法断言矩阵;类型收窄;转换替换/插入/移除/注解;内联形状、变更、循环、原始、异步和来源拒绝 | 完整、内联、终端、增量部分/最终、仅语法更新、仅转换更新、先前快照 | 对转换重新排序会改变有序证据;添加分词器调用、修改先前的快照或泄漏拒绝,都会失败。 |
| FR14–FR17 | 渲染器/回退矩阵、语义所有者矩阵、标题/Outline 标识、代码覆盖优先级、服务端渲染 | 源支持的和合成的扩展、容器、重复标题、跨基础标题、自定义代码覆盖存在/不存在 | 失败的渲染会保留精确的源、所需的投影或子元素;components.code 绝不会抢占已声明的代码围栏。 |
| FR18–FR20 | 一个真实兼容变换,外加被拒绝的异步、解析器扩展、raw-HTML、不支持节点、伪造位置、处理器状态和 metadata fixtures | 每个受支持的矩阵行、受限的文件消息/数据、受保护上下文、服务端渲染 | 静默字段丢失、接受不支持节点、源信息丢失,或转义拒绝在 fixtures 中未能 fail closed,则失败。 |
| FR21–FR24 | 规范关联解析器预算、回调工作量计数、守卫遍历计数、bundle 检查,以及上述精确配对协议 | 200/500 个区块、稳定/重新创建的列表、由 helper 和插件编写的零工作量及代表性集合、流式集合 | 任何未匹配的回调、重复声明回调、重复的整文档守卫、解析器预算回归或违规,则失败。 |
| FR25–FR28 | 内容声明准入/树验证、所有权矩阵、依赖准备、保留数据拒绝 | 叶子、短语(phrasing)、流(flow)、允许列表;深度边界处的嵌套容器;外部读/移除/mint(铸造)/编辑;未满足或顺序错误的依赖 | 插件构建的 raw-source 子节点、无效内容、外部 mint(铸造)/编辑或通用所有权诊断,则失败。 |
| FR29–FR30 | 开发/生产环境中的诊断 fixtures,以及各入口之间的准入一致性 | 每个阶段/代码、告警、速率抑制、无处理器默认行为、畸形列表、重复 Core、版本偏差 | 静默生产失败、诊断中出现文档内容、模块作用域抛出或入口分歧,则失败。 |
| FR31–FR35 | 无显式类型参数的推理 fixtures、规范/服务端导入、conformance-kit 自测、文档检查 | 仅语法、仅变换、仅渲染器、异构列表、服务端导入、第三方 kit 运行 | 显式类型变通、服务端入口中的客户端引用,或未记录的拒绝类别,则失败。 |
| FR36–FR39 | 流式无振荡、主题可达性、prepared(预制备)复用计数、稳定性策略文档 | 分块边界、仅最终效果、主题化/未主题化输出、相同 new-identity 列表、版本偏差 | 振荡、不可达的选择性加入输出、每次渲染重新预制备或未发布的策略,则失败。 |
| FR40–FR41 | 第一方模块记录/证据和不支持节点 fixtures | 软换行、标题链接、可配置实体引用、标注(callouts);脚注/定义/引用来源通过解析器和适配器 | 第一方公共特权、更改后的空管道行为,或插件拥有的脚注/定义支持,则失败。 |
| 仓库完整性 | 知识验证、公共内容检查、类型检查、格式化和已变更文件审查 | 规范及每个实现 PR | 内部内容、过期的所有者记录、无关路径或格式化/类型失败会阻止合并。 |
相关所有者前提条件¶
在实现验收之前,当前所有者条款必须涵盖:
- 稳定的、与 MDAST 对齐的规范 AST;类型化 node-map/visitor API;已发布解析器兼容性投影;公共规范解析入口;以及由 Core 负责的语义验证;
- Markdown/Outline 共享的已变换标题身份,以及两个表面都使用的未改变顶层遍历;
- 可观察的失效身份,用于区分语法与实时变换;
- 已变换节点的导航/资源一致性;
- 在任何迁移之前保持
inlinePlugins的精确兼容; - 组件和解析器选项上的诊断通道;
- Markdown 主题结构中的可选扩展主题目标;
- 服务端安全的解析器和 conformance-kit 包入口;
- 软换行、标题链接、可配置实体引用和标注(callouts)的第一方插件模块所有者。
决策日志¶
DEC-1 — 仅暴露语法、变换和渲染器¶
参考: spec:AST-036/DEC-1
方向负责人: cixzhang,2026-09-15
公共协议包含三个概念。文本匹配、语义围栏和装饰是变换辅助工具(transform helpers),不是并行的生命周期 API,它们从不渲染——呈现始终来自所属插件的 renderers。这保持了单一心智模型,同时允许专门化的内部执行。
已否决:五个独立的公共能力阶段;第二个 transform 属性;接受渲染回调的辅助工具;用无界文档钩子取代简单的局部语法。
DEC-2 — 使不可变 AST 变换成为规范¶
参考: spec:AST-036/DEC-2
方向负责人: cixzhang,2026-09-15
变换接收由解析、渲染和 Outline 所观察到的、与 MDAST 对齐的规范树。公共节点类型遍历保持严格的判别式收窄(discriminated narrowing),包括插件扩展节点。输入不可变,变换返回经过验证的根节点。Core 所有者保留来源(provenance)、结构有效性、回退和语义权威。已发布的解析器结果在另行批准的迁移之前保持不变。
已拒绝:第二棵变换树、对规范状态的就地修改、由变换驱动的重新解析、原始标记、弱类型字符串访问器,以及由渲染器控制的标题身份。
DEC-3 — 支持有限的 Remark 兼容配置¶
参考: spec:AST-036/DEC-3
方向负责人: cixzhang,2026-09-15
一个可摇树(tree-shakeable)的适配器可以在明确的 MDAST 子集上运行仅做同步变换的 Remark 插件。兼容性以逐插件证据为准,绝不从包身份推断;支持与拒绝的类别会向消费者公布。
已拒绝:将 Unified/MDAST 作为 Core 的运行时、声称任意的 Remark 兼容性,或静默近似不支持的行为。
DEC-4 — 将语法身份与实时变换分离¶
参考: spec:AST-036/DEC-4
方向负责人: cixzhang,2026-09-15
只有语法和现有的解析器选项决定解析身份。变换和渲染器的更新复用已解析的输出,仅重新运行各自所属的解析后工作。
已拒绝:以对象身份作为解析身份、由变换驱动的重新解析、公共渲染键,或对语义等价的输入重复准备。
DEC-5 — 扩展节点可包含经过验证的 Markdown¶
参考: spec:AST-036/DEC-5
方向负责人: cixzhang,2026-09-16
Callout、admonition、details、tabs、cards 和 columns 需要真正的 Markdown 子内容。因此,扩展声明叶节点(leaf)、短语(phrasing)、流(flow)或收窄的允许列表内容,并由 Core 验证子内容。Core 解析语法容器的内部片段;插件绝不从原始源码构建子内容,因此来源和受保护上下文始终归 Core 所有。容器绝不选择或独立界定标题身份的作用域;它仅参与 FR16 下已选定的投影。失败的容器渲染器仍会暴露其经过验证的子内容。
已拒绝:仅叶节点的扩展节点;独立的嵌套文档外壳;插件编写的已解析子内容;无界嵌套。
DEC-6 — 所有权意味着铸造和编辑,而非存在¶
参考: spec:AST-036/DEC-6
方向负责人: cixzhang,2026-09-16
变换可以读取或移除另一插件的节点,包括已移除的子树,但不得创建、编辑、内部重排或复制它们。源标题可以被插入、移除或重排,但绝不能被重新定级或赋予伪造/重复的身份。dependsOn 使跨插件读取显式化,并验证其存在性和顺序。
已拒绝:外部节点不朽;标题不朽;静默的缺失/错序依赖;泛化的所有权诊断。
DEC-7 — 失败在生产环境中可见¶
参考: spec:AST-036/DEC-7
方向负责人: cixzhang,2026-09-16
Astryx 拥有一个无源码、限速的 onPluginDiagnostic 通道,覆盖开发和生产环境中的准入、语法、变换、渲染和适配器阶段。插件通告携带稳定代码,而非源自文档的文本。准入失败在组件和解析器入口点之间保持一致;版本偏差绝不会在导入时抛出异常。被拒绝的 tokenizer 和 transform thenable 会在拒绝前被解除(defused)。
已拒绝:仅限开发环境的报告;自由文本且源自文档的消息;静默的有界验证回退;一个入口点抛出异常而另一个恢复的情况。
DEC-8 — 规范 AST、服务端解析器和一致性套件是公开的¶
参考: spec:AST-036/DEC-8
方向负责人: cixzhang,2026-09-16
导出的规范节点类型具有公共解析生产者。服务端安全的解析器入口避免引用客户端。共享的一致性夹具(fixtures)让第三方能够产出所需的证据。插件声明推断扩展类型,无需手写别名或多个显式类型参数。
已拒绝:没有公共生产者的规范类型;仅能通过客户端 barrel 访问的解析器 API;没有共享套件的证据要求;将推断推迟到示例。
DEC-9 — 发布插件实际所走路径的成本¶
参考: spec:AST-036/DEC-9
方向负责人: cixzhang,2026-09-16
第一方辅助工具可以跳过其构造已证明的守卫,但其数据并不代表第三方成本。因此,预算分别命名辅助工具路径和插件编写路径,包含流式处理,并将守卫工作限制为对每个变换输出的一次遍历,整篇文档的不变量在每个流水线运行中只收集一次。
已拒绝:将辅助工具路径的数据发布为协议开销;未测量的流式处理;每个变换重复收集整篇文档不变量。
DEC-10 — 脚注、定义和引用保持在 Core 范围内¶
参考: spec:AST-036/DEC-10
方向负责人: cixzhang,2026-09-16
这些概念需要文档级 ID 分配、冲突处理,以及与 Markdown 身份共享的反向引用导航。在单独的 Core 语法契约添加它们之前,它们仍不受支持并被适配器拒绝;文档会明确指出这一缺口。
已拒绝:第一方或第三方脚注插件;适配器将其转换为普通链接;让该限制不被记录在文档中。
DEC-11 — 第一方插件是普通插件¶
参考: spec:AST-036/DEC-11
方向负责人: cixzhang,2026-09-22
软换行(soft breaks)、标题链接、可配置实体引用和 callout 示例使用公共的不透明插件列表,在模块记录中拥有自己的语义和证据,并且不会获得第三方无法获得的公共能力、豁免、排序特权或类型便利。仅当内部组合接缝或快速路径的模块记录拥有其结果,且空流水线在观察上保持不变时,才允许使用。
已拒绝:特权化的第一方能力;演练私有路径的演示;没有真正第一方使用者的公开协议。
DEC-12 — 语义围栏优先于宿主代码渲染器¶
参考: spec:AST-036/DEC-12
方向负责人: cixzhang,2026-10-09
提供 components.code 的宿主通常是为了高亮普通代码,而这样的宿主也最有可能额外安装用于图表、图示或 diff 的围栏插件。围栏提案是更具体的声明:它指定一种语言及其所属插件,因此它优先渲染,而 components.code 渲染所有未被插件认领的围栏。已被认领的围栏,如果其渲染器拒绝渲染或渲染失败,则回退到宿主的代码渲染器,因此读者仍能以宿主绘制的方式看到代码。赋予围栏语言含义的产品功能应作为围栏插件发布,而不是作为宿主代码渲染器内部的分支。只有当宿主同时提供 components.code 和认领同一语言的围栏插件时,行为才会改变:该语言的围栏将通过插件渲染。只具备两者之一的宿主,其渲染行为与之前完全相同。
已拒绝:将提案传递给 components.code,由各宿主重新分发,这会让插件渲染重新回到宿主组件内部。
开放问题¶
无。契约是当前的;实现与兼容性证据仍待补充。
内容边界¶
本记录不重复消费者签名、示例、私有分发/缓存设计、仓库布局、第一方插件行为或当前审计结果。这些内容归其规范所有者所有。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx