今天介绍基于“文档即代码”理念的ICD文档的自动化流水线。

这篇研究通过“把技术文档当作代码来管理”，通过构建ICD文档流水线，解决了大型复杂体系中接口文件长期存在的“说不清、对不齐、改不动”的老大难问题。

ICD文档流水线 = 把接口文件当作“代码”来管理，自动检查、自动生成、自动同步、自动通知。

ICD文档流水线，把ICD接口文件从“静态文本”升级为“活的文档”，实现了：

• 一致性 ：接口需求与代码等制品之间的信息保持一致；

• 可追溯性 ：每个文档的部件都可跟踪历史版本和依赖关系；

• 可维护性 ：变更自动传播，减少人为错误；

• 可扩展性 ：适配不同领域（航天、汽车、医疗等）。

1. 背景知识

1.1 研究背景与目的

这项研究聚焦于“体系（SoS）”架构过程中， 接口控制文件（ICD）管理 这一长期存在的痛点问题。

• 体系定义 ：多个独立系统协作完成单一系统无法完成的复杂任务（如军用系统、能源、铁路、医疗等）。
• 核心痛点 ： ICD（描述系统间接口的技术文档）常因跨学科协作导致 信息不完整、术语歧义、更新滞后 等问题，进而引发集成失败、运行故障。
• 研究目标 ：将软件工程中的“文档即代码”理念引入ICD管理，解决上述问题，并验证其在不同领域的适用性。

1.2 管理 ICD时遇到的典型问题

这项研究总结出 管理 ICD时经常出现的典型问题及具体表现：

1.3 破局思路：文档即代码

把ICD接口控制文件当代码来构建（build）和管理——轻量标记语言 + Git 版本控制 + CI/CD（持续集成/持续交付）流水线，让 ICD 从静态文档变成“活的基础设施”。

核心思想：按照“文档即代码 （Docs-as-Code，DaC） ”的思想，把ICD文件当做源代码进行管理 ——用轻量级标记语言（如 Markdown、Asciidoc）写作，用 Git 做版本控制，用 CI/CD 完成自动构建、测试和发布。 。

“文档即代码” 是一种将技术文档的创建、维护、发布等流程完全软件工程化的方法论。

采用文档即代码可以带来如下效果：确保信息的一致性，减少重复工作量和出错概率；提高文档和代码质量；需求和开发人员更好地协作。

2. ICD接口控制文件流水线

2.1 接口文件管理到底出了哪些问题？

这项研究梳理出几类高频的ICD管理的问题：

• 缺乏清晰性和跨领域可理解性： ICD通常包含的术语对于参与其原始版本的人员来说可能是清楚的，但几年后可能会有不同的解释。当涉及多个学科（例如，硬件和软件工程）时也是如此，因为在许多情况下，这些学科之间有相似的术语，但含义不同。
• 信息不完整： 在ICD文档中， 一些关键的细节经常被省略，特别是在接口的硬件方面的描述。这会导致做出错误的假设，或容易出错的非形式化的信息交换。此外，接口的时间行为和状态相关方面很少包含在ICD中。尤其是包括导致故障状态的场景。
• ICD之间缺乏一致性： 在涉及许多接口的体系中，不同ICD之间缺乏一致性会导致混淆和误解。

• ICD更新后 缺乏及时的通知 ： ICD 文档改了后，相关人员不知情。要等到他们出现问题（比如开发人员发现接口调用失败，原因是ICD中的接口变了，而开发人员不知道，所以C语言头文件和实现都没改）。
• 重复的工作： 在ICD和基于ICD生成的制品中， 与接口相关的信息需要在不同地方重复（接口需求、接口API文档、接口源代码等）。保持所有这些信息源同步，需要投入许多时间和精力。而这些工作原本可以投入到接口的实际工程/开发活动中。

2.2 基于 “文档即代码”的 ICD管理工具链需要哪些重要功能？

这项研究筛选出 4 个高优先级的“文档即代码”的功能：

1.文档级质量门控 ：通过集中管理的可自动检查的质量规则，对ICD文档进行质量门控制。把文档问题对应的各种问题症状，翻译成可自动检查的质量规则，例如“寄存器必须写默认值”。

2.嵌入式机器可读规范 ：用轻量级的形式化语言描述ICD文档中的技术元素，例如 SystemRDL 描述寄存器、YAML 描述 帧格式 。

3.文档宏用于自动内容生成 ：为减轻文档编写工作量和避免重复和出错，开发相应的轻量级的形式化语言编辑器的扩展插件，用于自动生成不同地方相同的重复内容。比如，在 Asciidoc 里写 reg:: 宏，一键展开寄存器表、术语表、版本差异，减少复制粘贴。

4.集中化文档跟踪 ：跟踪记录项目和组织的ICD文档的发布记录、文档当前状态和依赖关系。

2.3 ICD 的自动检查的CI/CD流水线到底长什么样？

研究团队把 4 个功能映射到一条 GitLab-CI 流水线，形成下图所示的六步闭环：
① 管理人员/架构师 定义ICD文档的质量规则检查清单；并将这些质量检查清单中的检查规则转成CI/CD平台中的自动化检查动作；

② ICD 文档写作人员 在 VS Code 之类的编辑器中，用 Asciidoc 撰写 ICD文件；写好后 push 到 GitLab；

③ GitLab CI/CD工具自动触发质量门控，自动跑所有的质量检查规则；

④ 如果所有质量规则的检查都通过后，运行相应的形式化语言工具的扩展插件。例如自动生成接口描述的 HTML/PDF 文档和接口的 C语言头文件；然后提交到 版本控制系统 中；

⑤ 文档状态跟踪 API 接口更新文档状态，并给版本控制系统中的接口文件和制品（接口的 C 语言头文件）打 tag。 GitLab Pages 把结果发布到固定 URL；向相应开发人员发送通知提醒；

⑥ 开发人员收到相应通知后访问ICD文档，查看接口变化情况，然后拉取最新版本的接口的C语言头文件进行开发。

通过上图中的流程，ICD 文档也能像代码一样被“编译、测试、发布、消费” ，全流程自动化，把“人盯文档”变成“机器盯文档”。

2.4 文档状态跟踪API

对于每一份ICD接口文件，为了保持需求文档之间的一致性，需要搞清楚到底谁依赖它，什么时候必须进行修改等问题。

这项研究通过文档状态跟踪API，向可视化界面提供每个ICD文件的文档状态。

上图中，icd-b文件的v0.5版本，因为依赖引用了（ refs ）老版本（最新版未v1.5）的icd-a文件（ v1.1）。

所以在上图中，icd-b文件上面有黄色的 标记，意思是依赖的相关文件已经不是最新的了，所以icd-b文件的状态就变成了 “需要修订”。

下图为ICD的文档状态转换图。文档状态跟踪API根据这个图中的状态机，调整各个ICD文件的

下表为ICD文档的重要字段：

2.5 “文档即代码”的ICD管理与传统ICD管理的对比

3. 总结

3.1 创新性

首次将“文档即代码”引入体系的接口管理，打破传统人工维护文档的低效模式。

3.2 未来方向

1.扩展动态描述 ：增加对时间约束、错误恢复等动态行为的建模。

2.用户体验优化 ：开发一键式工具链配置向导，降低非开发者使用门槛。

3.跨领域案例研究 ：在自动驾驶（协作型SoS）等场景中测试这一方案的适应性。