夜雨聆风
基于文档即代码的卫星开发MBSE案例
一起学习，共同精进
凡人导语：
前几天刚看到这篇批判SysML V2的文章前BAE专家说“SysML V2死而不僵”，并在共进群里和大家做了讨论，本来想把讨论内容转换成文章的，但实在没有时间。正好最近就发现了今天的这份资料，也是说SysML不符合实际的，就分享出来希望能启发大家，深入思考如何才能推进MBSE落地。
SysML v2 建模语言配套的文本表示法引发了大量讨论，而美国欧道明大学的海狮项目团队并未止步于探讨，而是将相关理念付诸实践。该项目是美国多所高校合作开展的立方星联合研发项目，核心目标是借助基于模型的文本化文档系统（文档即代码），让系统开发流程更高效、更易落地，值得一提的是，该项目的实现并未采用 SysML v2。
—
该项目的研发目标是打造一款搭载三款不同科学有效载荷的 3U 规格立方星，并将其发射入轨。除了完成硬件的在轨飞行验证，海狮项目还肩负着测试系统开发新方法的使命，其中核心便是基于模型的文档即代码方法。
海狮立方星的三款科学有效载荷均由合作高校研发，具体包括：
-
等离子体诊断阻抗传感器 -
多光谱像素传感器 -
可展开复合材料结构
海狮立方星（VSCP 1A）
海狮立方星系统原定 2023 年发射入轨，遗憾的是发射计划已数次推迟。考虑到美国国家航空航天局目前的预算削减情况，若该项目暂时搁置，我也不会感到意外。
—
文档即代码的理念在软件领域早已成熟落地：开发人员使用 Markdown 格式维护文档，通过 Git 工具进行版本管理，再借助持续集成（CI）机制，确保文档构建成果与相关制品始终保持最新。海狮项目团队则将这一理念直接应用于系统架构设计与文档管理工作中。
该项目以Mach 30 建模语言（M30ML） 为技术基础。这一语言基于 YAML 格式开发，兼具人类可读性与机器可解析性。项目团队将整个系统架构以代码形式进行维护，覆盖需求定义、架构设计、用户故事梳理、遥测数据结构设计等全流程，图表、表格与 PDF 文档均由系统自动生成。
以下是一个用户故事的示例，该内容在 GitHub 中以独立的 YAML 文件进行管理：
id: 4.1
name: Request Satellite Health Data
actor: Ground Station Operator
behavior: request satellite health data packet
rationale: verify/validate AODS sensors & GPS data are within nominal parameters
derivedFrom:
– “2-UserStories/4-RequestTelemetryData.yaml”
example: Request satellite health data packet to verify or validate state vector corresponding to expected orbit profile based on pre-computed orbit propagation model
YAML 格式的「调取卫星健康数据」用户故事
—
该论文中阐述了文档即代码方法在海狮项目中的以下核心应用场景：
- 利益相关方分析与需求获取：将系统需求以 YAML 格式记录在文本文件中；
- 需求追溯：通过自动生成的统一建模语言（UML）图表，直观展示需求、用户故事与数据结构之间的关联关系；
- 技术文档编制：直接基于系统模型自动生成表格与图表，从根源上消除文档冗余；
- 评审与变更管理：借助 Git 的拉取请求功能，实现需求与架构要素的协同评审；
- 新团队成员融入：工作人员可使用任意文本编辑器开展工作，仅需简单学习 YAML 格式即可上手。
本数据结构 UML 图由 YAML 文件自动生成
可清晰追溯至前文所述的 4.1 号用户故事
—
海狮项目团队对多款建模语言进行了评估，其中也包括 SysML v2，但最终选择弃用，原因主要有三点：
- 无文档即代码适配性：尽管 SysML v2 支持文本表示法，但其并非为文件化管理设计，这意味着该语言对源于软件开发领域的文档即代码范式缺乏良好支持；
- 配套工具不完善：项目团队认为，目前市面上的 SysML v2 配套工具过于笨重。当然，2023 年至今，相关工具已有了诸多改进；
- 语言本身过于复杂：团队认为 SysML v2 对于本项目而言复杂度过高，即便忽略该语言的诸多功能特性，仍需要投入大量精力开展团队培训。
而 M30ML 建模语言作为链接建模语言规范（LinkML）的扩展版本，具备轻量、兼容 Git、基于 YAML 格式的特点。该语言的设计受众不仅包括系统工程师，还充分考虑了非工程技术人员的使用需求，确保这类人群也能高效参与建模工作。
M30ML 能够实现语义严谨且易于上手的系统建模，在海狮项目中，这一建模语言还得到了分布式开源硬件框架（DOF） 的辅助 —— 该框架可对立方星的装配结构进行建模，同时还能管理装配说明、接口定义与零部件清单等内容。
—
海狮项目对工具的选择秉持极简原则，核心使用工具如下：
-
Visual Studio Code：首选代码编辑器； -
YAML：所有架构要素的统一表示格式； -
Jinja2 模板引擎 + Shell 脚本：实现文档的自动生成； -
Git/GitHub：用于版本管理、协同开发与评审流程管理； -
PlantUML：自动生成 UML 图表； -
Asciidoctor/LaTeX：生成人类可读的文档输出格式。
这些工具对开放式科研项目而言优势显著：全部免费使用（大部分为开源工具），且支持离线工作模式。
—
论文作者虽提及了该方法在项目应用中的不足，但在我看来，分析仍不够深入。显然，团队仅意识到了该方法在学术研究场景中面临的挑战，却未关注到工业界落地时将遇到的问题。
项目实际遇到的问题主要包括：
- 对团队沟通的高度依赖：与众多项目一样，团队沟通存在诸多阻碍，项目沟通主要依托 GitHub 提供的功能，包括各类工作流工具；
- 后期建模成本高：在引入建模系统前做出的决策，需要投入大量精力才能迁移至模型中；
- 培训资料缺失：项目相关文档寥寥无几，且部分内容不完整，新成员难以快速熟悉整个系统；
- 高级功能实现难度大：对组件和接口进行建模需要额外的工具支持，而部分所需工具当时尚未开发完成。
在我看来，该方法若要在工业界落地，还将面临更多阻碍：
- 规模化拓展难题：海狮项目仅涉及数十个开发制品，而工业界项目往往需要管理数千甚至数万个制品；
- 功能与易用性不足：若要获得广泛认可，用户会期待更多实用功能，例如在需求文档中嵌入图片、使用操作友好的专用工具等；
- 集成能力欠缺：当前的工具链仅能覆盖 V 模型的一小部分流程，缺乏产品生命周期管理（PLM）、测试环节集成等关键功能；
- 权限与角色管理不足：GitHub 提供的相关功能，无法满足工业界项目的访问模型需求。
这些问题并非无法解决，只是在科研项目的框架下难以实现。在我看来，工具开发商是解决这些问题的最佳主体。在软件开发领域，已有多家企业依托文档即代码理念打造了成功的商业模式，例如 GitHub、GitLab、Read the Docs、MkDocs 以及 Atlassian 等。
—
海狮项目证明，文档即代码的理念同样可应用于系统工程领域。尽管目前尚无法确定该方法在工业界的适配程度，但这一真实的案例研究为该理念的进一步探索提供了宝贵的参考。
—
今天的文章灵感来自本次仅提供《文档即代码方式的卫星开发MBSE案例》原文共22页，2种获取方式如下：
—END—
业余时间写文不易，有收获的朋友敬请：
-
转发、分享、在看三连，帮助推广
-
关注、星标公众号“SE与MBSE漫谈”
-
扫码加微信，邀请加入“SE&MBSE共进群”，与同道共同交流
-
加入“数字工程”社群，获得更多专业资料。
公众号加“星标”，及时接收文章！
