学习指南: 应用部分 7. Specification CI：规范作为可执行制品

模块「应用部分 7. Specification CI：规范作为可执行制品」中第 3 / 5 节课

您正在未登录状态下查看课程。请登录，以保存进度并参加测试。

主题: 实践部分 7. Specification CI：作为可执行制品的规范

难度等级: 中级

预计学习时间: 3-4 小时

前置要求: 理解 CI/CD 的工作原理（例如 GitHub Actions）

具有 Markdown 和 JSON 使用经验

具备 Python 基础知识以便修改检查脚本

熟悉开发中的需求（requirements）和计划（plans）概念

学习目标: 配置 CI 流水线以自动验证规范（requirements.md、plan.md）。

实现覆盖率检查（Coverage Check），用于关联需求（REQ-*）与计划任务。

为从 validation.md 中提取的夹具（fixtures）创建 JSON Schema 验证，包括负向测试检查。

生成清晰的 CI 错误诊断消息，指示文件、行号以及修复操作。

应用 Spec CI 验证智能体系统的原子计划（AoT 网关）。

概述: 本学习指南专注于将静态文档（规范）转化为可在 CI/CD 中检查的可执行制品。我们将探讨如何借助 GitHub Actions 和 Python 脚本自动化规范质量检查。核心思想是创建“规范网关”（Spec Gate），在存在违规时阻止 Pull Request 的合并：未覆盖的需求、超出域范围（Scope）的操作或 JSON 夹具中的错误。该方法基于以下原则：规范只有在可以被自动拒绝时才有价值。

关键概念: 规范网关（spec gate）：CI 中的强制阶段，像常规测试检查代码一样严格地检查规范。它在发现文档中存在语义或结构错误时阻止 PR 合并。

覆盖率检查（coverage check）：验证 requirements.md 和 plan.md 之间关联图的过程。每个需求（REQ-）必须在计划中有一个实现任务（implements: [REQ-]），而每个任务必须与需求相关联（不存在“孤立任务”）。

范围检查（scope check）：验证 plan.md 中的操作是否与域模型（例如 incident-response.yaml）允许的操作相匹配。阻止“外部”场景，例如未经授权的自动关闭事件。

架构检查（schema check）：从 validation.md 提取 JSON 示例（夹具）并检查其是否符合 JSON Schema。包括检查正向场景（应通过）和负向场景（应可预测地失败）。

Aot 网关（atom of thought gate）：针对 AI 智能体生成的计划的专业检查。计划以原子动作图的形式表示，在执行之前针对未知工具、依赖循环和超出域范围进行验证。

练习题: 名称: 需求覆盖率的本地检查

问题: 您有 requirements.md 和 plan.md 文件。需要确保 requirements.md 中的所有需求在 plan.md 中都有相应的任务，并且没有“孤立”（rogue）任务。在本地运行覆盖率检查脚本。

解决方案: 1. 切换到示例目录：cd book2/examples/spec-ci。2. 运行脚本：python3 scripts/check_coverage.py --requirements requirements.md --plan plan.md。3. 确认脚本返回代码 0（成功）并输出成功覆盖所有 REQ-* 标识符的消息。

难度: 初级

名称: JSON Schema 验证和负向测试

问题: 需要根据架构 incident_payload.schema.json 检查事件的 JSON 夹具。其中一个夹具故意不正确（缺少 incident_id）。需要确保脚本正确地拒绝它。

解决方案: 1. 在 book2/examples/spec-ci 中，执行：python3 scripts/validate_schema.py --schema schemas/incident_payload.schema.json --fixtures fixtures。2. 检查输出：有效的夹具应通过，无效的夹具应输出错误消息（例如“missing required property incident_id”）。3. 确认进程正常结束，指示已发现差异。

难度: 中级

名称: 格式化 CI 诊断消息

问题: 脚本 check_scope.py 发现在 plan.md 中使用了域模型不允许的操作“force_resolve”。生成一个符合良好诊断要求的错误 JSON 对象：清晰的原因、文件链接、规则标识符和修复操作。

解决方案: JSON 响应应如下所示： { "status": "failed", "check": "scope", "file": "plan.md", "line": 48, "rule": "IR-SCOPE-007", "reason": "Autonomous force resolve is outside the incident-response domain model", "action": "Replace with POST /incidents/{id}/ack or add an approved requirement and domain rule" }

难度: 中级

名称: 智能体计划（AoT）验证

问题: 智能体生成了一个 JSON 格式的计划，其中包含 atoms 数组。创建一个规则（或脚本概念）来在原子引用不存在的工具“delete_database”时拒绝该计划。

解决方案: 脚本应读取每个原子的“name”字段，并将其与域模型中允许的工具列表（白名单）进行比较。如果“delete_database”不在白名单中，脚本应返回 error.fail 和如下 JSON 诊断：{'reason': 'Unknown tool', 'action': 'Remove atom or update domain model'}。

难度: 高级

案例研究: 名称: 阻止未经授权的事件关闭

场景: 团队正在开发现事件管理自动化。一名开发人员创建了一个 Pull Request，在 plan.md 中添加了一个新步骤，用于在无值班工程师确认的情况下自动解决事件（force-resolve），以“加快”流程。

挑战: 如果该改动在形式上与某个需求绑定，文本审查可能会漏掉它。然而，此类操作违反了业务流程和安全性（可能掩盖严重故障）。

解决方案: 部署了带有范围检查（Scope Check）的规范网关 Spec CI。脚本 check_scope.py 将“force_resolve”操作与域模型 incident-response.yaml 进行了匹配，发现该操作不允许用于自治系统。

结果: GitHub Actions 阻止了 PR 的合并。开发人员收到了自动评论，指明文件（plan.md）、行号以及禁止自治关闭的规则。危险的逻辑未能进入生产环境。

经验教训: 仅检查需求文本是不够的；必须检查操作的语义。

自动化规范审查可降低团队负担并防止“人因”错误。

网关不仅应检查引用（coverage）的存在，还应检查内容（scope）。