Documentation Portal
Documentation
从第一次转换开始，逐步理解 Schema Transformation Toolkit 的工作方式，以及 parser、generator 应该如何扩展。
Transformation pipeline
TypeScriptShape IRRust从这里开始
选择和你当前目标匹配的路径
先按当前目标选路径，而不是把所有模块从头到尾扫一遍。
按角色浏览
先从你当前扮演的角色开始
直接按当前角色进入最相关的文档，而不是自己从所有页面里猜入口。
01
探索时先用 playground，集成时优先使用已发布的 toolkit package。
推荐阅读
快速开始
完成第一次转换
02
Shape IR 是共享语义层，让多格式转换工作保持一致和可扩展。
推荐阅读
What is Shape IR?
Traversal explained
03
通过 diagnostics 判断哪些语义发生了降级，哪些能力还未被支持。
推荐阅读
理解 loss analysis
API 与 package 参考
04
从一小块稳定的 Shape IR 开始，逐步扩展到目标格式。
推荐阅读
创建自定义 generator
05
理解 parser、IR、traversal、generator 和 diagnostics 如何在同一条流水线里保持分层。
推荐阅读
系统架构
06
集中回答 IR、可信度、浏览器支持和性能这些高频问题。
推荐阅读
常见问题
快速开始
先把整体路径跑通
让第一次来的用户在几分钟内找到正确入口，而不是先去猜项目目录结构。
学习路径
按照理解深度选择合适路径
文档应该让用户很快判断自己是刚开始、准备集成，还是在研究内部架构。
Introduction
↓Installation
↓Playground
↓First transformation
↓Concepts
Shape IR
↓Traversal
↓Parser
↓Generator
↓Transformation workflow
Architecture
↓Diagnostics
↓Performance
↓Plugin development
↓Future IR
文档分类
按目标学习，而不是按文件夹学习
按使用目的而不是源码目录来浏览工具包。每个分类都应该帮助用户判断下一步该学什么。
理解 Shape IR、traversal、parser、generator 和 diagnostics 背后的核心模型。
• Shape IR
• Traversal
• Parser 模型
• Generator 模型
围绕任务来学习：如何安装、如何跑第一次转换、如何扩展现有流水线。
• 安装工具包
• 第一次转换
• 扩展工作流
直接看可运行示例，对比输入、输出以及 diagnostics 的表现。
• 基础类型
• 对象结构
• 枚举与联合
• 数组
集中查看真实集成时最关心的 API、类型边界和工具层能力。
• Parser API
• Generator API
• Traversal API
• Utilities
理解内部流水线、模块边界以及为什么这些设计能保持转换可预测。
• Pipeline
• Modules
• Design decisions
• Future IR
快速回答为什么要 IR、浏览器支持如何、性能如何这类反复出现的问题。
• Why IR?
• Why not AST?
• 浏览器支持
• 性能
精选主题
先从最高价值的主题开始
先从当前最值得读的内容开始，而不是按最近编辑时间去找。
用最短的路径理解为什么共享 IR 对跨格式转换至关重要。
看看 traversal 如何支撑 parser、generator 和未来分析层的复用。
直接去真实应用里体验当前支持的转换路径与反馈。
理解 diagnostics 和 semantic caveats 在下游应该如何解释。
读完就试
从文档路径直接进入可验证的交互流程
不用自己猜下一步该去哪。每条路径都把一篇文档和一个明确的 playground 验证动作绑在一起。
先看文档
先读最短的上手路径，再确认一个基础 schema round trip 是否和文档描述一致。
验证重点
至少检查一个 object、一个 array 和一个 enum。
先看文档
先看文档如何解释有损场景，再到交互流程里对照输出和诊断信息。
验证重点
重点看 warning、unsupported node 和 fallback 输出。
先看文档
先建立 Shape IR 的概念模型，再确认当前 playground 的真实流程是不是符合这套模型。
验证重点
按 source format -> Shape IR -> target format 的顺序去观察。
最近更新
先看最近推进了什么
用结构化 metadata 快速找到最近变化的页面，而不是靠猜测目录或编辑顺序。
路线图
明确哪些已经稳，哪些还在推进
通过能力快照了解工具链当前最成熟的部分，以及仍在扩展中的方向。
Parser
92%
Generator
68%
Traversal
90%
Shape IR
94%
Constraint IR
18%
Value IR
8%
Constraint IR
在不破坏当前 Shape IR 清晰度的前提下扩展下一层 IR。
OpenAPI parser
继续扩展输入格式支持，同时保持整体流水线可理解。
Generator expansion
把更多转换路径做成可信的公开产品入口，而不是只停在内部能力。
社区与项目
持续跟上项目演进方向
随着工具包能力扩展，保持和项目方向同步。这里的入口应该帮助用户提问、试用和跟踪进展。