Holarch

参考

实践示例:GitHub

从 GitHub Actions 运行 Holarch 模型检查并将发现项作为 GitHub 问题跟踪,并让命令行 AI 工具为某个分支实现的需求提出测试用例;涵盖设置、工作流文件、完整示例和故障排除。

使用方法 →

本页内容
  1. 概述
  2. 前提条件
  3. 如何使用
    1. 何时使用及原因
    2. 设置仓库
    3. 按计划运行模型检查
    4. 借助命令行 AI 工具 为分支提议测试用例
    5. 实例:CubeSat EO-1 演示
    6. 提示
  4. 故障排除
  5. 相关页面

概述

本实践示例将 GitHub 仓库与 Holarch 项目连接起来。它分为两部分:

  • GitHub Actions 中的模型检查(REST API):一个计划工作流对项目的需求运行 Holarch 的模型检查。它将发现项写入运行摘要,并使一个 GitHub issue 保持与之同步。
  • 代码评审中的需求(MCP,通过命令行 AI 工具):命令行 AI 工具读取您正在处理的分支,在 Holarch 中找到它所实现的需求,并提议验证这些需求的测试用例。在任何内容更改之前,您会在 Holarch 中评审该提议。

Holarch 没有内置的 GitHub 应用。本实践示例使用 REST API 和 MCP,因此每一步都可以按需调整。

前提条件

  • 包含 API 和 MCP 的方案:Individual 或 Team,或 Individual 试用。在 Free 方案中,拥有已验证学术邮箱地址或属于活跃班级组织的账户也可使用它们(方案和限制)。
  • 一个 Holarch 项目。工作流只读取它;来自命令行 AI 工具的提议需要编辑者或所有者角色。
  • 一个 GitHub 仓库,您可以在其中添加 Actions 密钥和变量,且 Actions 可以在其中创建 issue。
  • AI 应用部分:以读取并提出更改访问权限连接到 Holarch 的命令行 AI 工具(将 Holarch 连接到 AI 应用)。

如何使用

何时使用及原因

模型检查会发现模型中的缺口,例如没有验证测试用例的需求。按计划运行它们,并在团队已经工作的地方跟踪发现项,可以使缺口在两次评审之间保持可见。命令行 AI 工具从另一侧完成闭环:当代码实现某个需求时,它会起草验证该需求的测试用例。

设置仓库

  1. 在 Holarch 中创建一个限制在该项目内的只读令牌:账户设置 → API 令牌 → 新令牌(创建令牌)。
  2. 查找项目 ID:GET /api/v1/projects 列出您的项目及其 id。
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. 在 GitHub 中打开仓库的 Settings → Secrets and variables → Actions:
    • 在 Secrets 下,添加值为该令牌的 HOLARCH_TOKEN。
    • 在 Variables 下,添加值为项目 ID 的 HOLARCH_PROJECT。
  2. 在 Issues → Labels 下,创建标签 holarch。工作流用它来查找其 issue。

按计划运行模型检查

将此文件另存为 .github/workflows/holarch-checks.yml 并提交。

# Holarch Model Checks: requirement findings in the run summary and in one GitHub issue.
name: Holarch model checks
on:
  schedule:
    - cron: "0 6 * * 1-5"   # weekdays at 06:00 UTC
  workflow_dispatch:
permissions:
  issues: write
jobs:
  checks:
    runs-on: ubuntu-latest
    env:
      HOLARCH_TOKEN: ${{ secrets.HOLARCH_TOKEN }}
      HOLARCH_PROJECT: ${{ vars.HOLARCH_PROJECT }}
      GH_TOKEN: ${{ github.token }}
      GH_REPO: ${{ github.repository }}
    steps:
      - name: Run Model Checks
        run: |
          curl -sS --fail-with-body -H "Authorization: Bearer $HOLARCH_TOKEN" \
            "https://app.holarch.app/api/v1/projects/$HOLARCH_PROJECT/model-checks?class=Requirement" > checks.json
          jq -r '"Holarch Model Checks: \(.total) requirement findings\n",
                 (.issues[] | "- [ ] \(.rule) \(.entity.number) \(.entity.name): \(.heading)")' checks.json > findings.md
          cat findings.md >> "$GITHUB_STEP_SUMMARY"
      - name: Update the tracking issue
        run: |
          total=$(jq .total checks.json)
          issue=$(gh issue list --label holarch --state open --json number --jq '.[0].number')
          if [ "$total" -gt 0 ] && [ -z "$issue" ]; then
            gh issue create --title "Holarch Model Checks findings" --label holarch --body-file findings.md
          elif [ "$total" -gt 0 ]; then
            gh issue edit "$issue" --body-file findings.md
          elif [ -n "$issue" ]; then
            gh issue close "$issue" --comment "Holarch Model Checks find no requirement issues."
          fi

要立即运行,请打开 Actions → Holarch model checks → Run workflow。

您会在运行摘要中看到发现项,每个发现项一行,例如 Requirement.10 <number> <name>: Leaf requirements with no verifying test case。issue Holarch Model Checks findings 包含相同的列表。发现项修复后,下一次运行会关闭它。

工作原理:

  • GET /api/v1/projects/<project>/model-checks?class=Requirement 按项目自身的规则设置运行检查并返回发现项:rule、heading、entity(id、number、name)以及相关条目。结果只返回,不存储。
  • curl --fail-with-body 在出错时使该步骤失败,并打印 Holarch 的消息,例如 {"error": "…", "code": "token-invalid"}。
  • GitHub 的 Ubuntu 运行器自带 gh 和 jq。

变化用法:

  • 其他规则:将 class=Requirement 改为其他类(Test Case、Asset,您的规则集用 Custom),或用 rule=Requirement.10 指定一条规则。
  • 需求质量:GET /api/v1/projects/<project>/quality 按九项质量属性为每个需求评分。以同样方式列出 score 低于您阈值的需求。
  • 有发现项时使运行失败:添加 test "$total" -eq 0 作为最后一行,例如用于发布分支的检查中。

借助命令行 AI 工具 为分支提议测试用例

在创建拉取请求之前使用此方法,使某项更改所实现的需求获得验证测试用例。

  1. 将命令行 AI 工具连接到 Holarch(只需一次):
claude mcp add --transport http holarch https://app.holarch.app/mcp

然后输入 /mcp,选择 holarch → 身份验证,登录 Holarch 并以读取并提出更改点击允许。

  1. 在仓库中,于您的分支上,例如向命令行 AI 工具询问:“将此分支与 main 进行比较。在 Holarch CubeSat 项目中找出此更改实现的需求,并为每个没有验证测试用例的需求提议一个测试用例。在提议摘要中写明分支名称。”
  2. 命令行 AI 工具用 git 读取差异。在 Holarch 中,它用 search_entities 和 get_entity 查找需求,并用带规则 Requirement.10 的 run_model_checks 查看哪些需求没有验证测试用例。它用 create_entity 添加每个测试用例及其 verifies 关系,然后用 propose_changes 发送提议。

    命令行 AI 工具会回复提议的标题和评审链接。

  3. 在 Holarch 中打开 ✦ AI ▾ → 评审“<title>”…,或铃铛下的通知。
  4. 如有需要,编辑名称和描述,然后点击应用所选项。

    测试用例会被创建,在历史中记录您的名字,一次撤销即可全部撤回。下一次计划的工作流运行不再列出这些需求。

将需求的链接粘贴到拉取请求描述中:get_entity 和 REST API 将其作为 url 返回。任何项目成员都可以通过它打开该需求。

实例:CubeSat EO-1 演示

  1. 通过管理项目 → 项目文件 ▾ → 新建演示项目创建演示,并将其 ID 用作 HOLARCH_PROJECT。
  2. 用 Run workflow 运行工作流。

    摘要列出模型检查标记的需求,例如没有验证测试用例的叶需求。issue Holarch Model Checks findings 列出相同的内容。

  3. 在更改姿态控制代码的分支上,让命令行 AI 工具为该分支实现的需求提议测试用例。

    该代码对应的需求是 2.1 Pointing Accuracy 和 2.2 Pointing Stability。两者都已由 TC-04 Pointing Accuracy Test 验证,因此不需要新的测试用例。

  4. 改为让它为 issue 列表中的某个需求提议测试用例,然后在 Holarch 中评审并应用该提议。
  5. 再次运行工作流。

    该需求不再被列出。

提示

  • 为工作流提供其自己的只读令牌,并限制在该项目内。移除工作流时,请在账户设置 → API 令牌下撤销它。
  • 计划工作流使用 Holarch 的规则设置:在模型检查中关闭某条规则或更改其级别,下一次运行即会遵循。
  • 令牌在您选择的日期到期。为工作流选择一年或永不到期,并记下该日期。

故障排除

消息或症状原因和解决方法
"code": "token-required"HOLARCH_TOKEN 密钥为空或缺失。请在 Settings → Secrets and variables → Actions 下添加它。
"code": "token-invalid"令牌错误、已撤销或已到期。请创建新令牌并更新该密钥。
"code": "plan-api"账户的方案不包含 API 和 MCP。请开始 Individual 试用或选择方案;之后令牌即可再次使用。
"code": "org-policy"项目所属组织已关闭 API 访问。请联系组织管理员。
"code": "not-found"HOLARCH_PROJECT 不是令牌可以使用的项目。请检查 ID 以及令牌的项目设置。
"code": "rate-limited"使用此令牌每分钟超过 600 个请求。请降低工作流的运行频率,或为其他脚本提供各自的令牌。
gh issue create 失败:找不到标签在仓库中创建标签 holarch。
gh 返回 HTTP 403工作流需要 permissions: issues: write,且仓库的 Actions 设置必须允许它。
命令行 AI 工具不提供 Holarch 写入工具该连接为只读。请运行 /mcp,以读取并提出更改重新连接 holarch,然后开始新的对话。