按流水线理解，而不是按文件夹理解
这条流水线从源格式 parser 开始，进入 Shape IR，再经过共享 traversal 逻辑，最后交给目标格式 generator。
diagnostics 应该跟着各阶段一起存在，而不是最后临时补上。只有这样，系统才能同时诚实解释成功和部分支持。
文档文章
系统架构
理解 parser、IR、traversal、generator 和 diagnostics 如何在同一条流水线里保持分层。
架构9 分钟
架构之所以重要，是因为这个项目想做的不只是一次性转换器。文档需要把 parser、Shape IR、traversal、generator 和 diagnostics 如何组成一条流水线讲清楚。
有用的 architecture 页面，不必一开始就非常全面，但应该先让扩展路径变得容易理解。
让每一层保持收敛
这些边界能让新增 route 的工作保持可评审，而不是每次都变成整栈重写。
- Parser 负责理解源格式。
- Shape IR 负责承载跨格式的结构语义。
- Traversal 负责可复用的走树逻辑。
- Generator 负责输出目标格式。
- Diagnostics 负责解释缺口、告警和语义损失。
把 handoff 文档化
重点不在箭头本身，而在于每次 handoff 都足够明确，能被测试、文档和扩展工作分别描述。
高层流水线视图
text
Source schema
-> parser
-> Shape IR
-> traversal helpers
-> generator
-> output + diagnostics