参考
实践示例:GitHub
从 GitHub Actions 运行 Holarch 模型检查并将发现项作为 GitHub 问题跟踪,并让命令行 AI 工具为某个分支实现的需求提出测试用例;涵盖设置、工作流文件、完整示例和故障排除。
概述
本实践示例将 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 工具从另一侧完成闭环:当代码实现某个需求时,它会起草验证该需求的测试用例。
设置仓库
- 在 Holarch 中创建一个限制在该项目内的只读令牌:账户设置 → API 令牌 → 新令牌(创建令牌)。
- 查找项目 ID:
GET /api/v1/projects列出您的项目及其id。
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- 在 GitHub 中打开仓库的 Settings → Secrets and variables → Actions:
- 在 Secrets 下,添加值为该令牌的
HOLARCH_TOKEN。 - 在 Variables 下,添加值为项目 ID 的
HOLARCH_PROJECT。
- 在 Secrets 下,添加值为该令牌的
- 在 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 工具 为分支提议测试用例
在创建拉取请求之前使用此方法,使某项更改所实现的需求获得验证测试用例。
- 将命令行 AI 工具连接到 Holarch(只需一次):
claude mcp add --transport http holarch https://app.holarch.app/mcp
然后输入 /mcp,选择 holarch → 身份验证,登录 Holarch 并以读取并提出更改点击允许。
- 在仓库中,于您的分支上,例如向命令行 AI 工具询问:“将此分支与 main 进行比较。在 Holarch CubeSat 项目中找出此更改实现的需求,并为每个没有验证测试用例的需求提议一个测试用例。在提议摘要中写明分支名称。”
- 命令行 AI 工具用 git 读取差异。在 Holarch 中,它用
search_entities和get_entity查找需求,并用带规则Requirement.10的run_model_checks查看哪些需求没有验证测试用例。它用create_entity添加每个测试用例及其 verifies 关系,然后用propose_changes发送提议。命令行 AI 工具会回复提议的标题和评审链接。
- 在 Holarch 中打开 ✦ AI ▾ → 评审“<title>”…,或铃铛下的通知。
- 如有需要,编辑名称和描述,然后点击应用所选项。
测试用例会被创建,在历史中记录您的名字,一次撤销即可全部撤回。下一次计划的工作流运行不再列出这些需求。
将需求的链接粘贴到拉取请求描述中:get_entity 和 REST API 将其作为 url 返回。任何项目成员都可以通过它打开该需求。
实例:CubeSat EO-1 演示
- 通过管理项目 → 项目文件 ▾ → 新建演示项目创建演示,并将其 ID 用作
HOLARCH_PROJECT。 - 用 Run workflow 运行工作流。
摘要列出模型检查标记的需求,例如没有验证测试用例的叶需求。issue Holarch Model Checks findings 列出相同的内容。
- 在更改姿态控制代码的分支上,让命令行 AI 工具为该分支实现的需求提议测试用例。
该代码对应的需求是 2.1 Pointing Accuracy 和 2.2 Pointing Stability。两者都已由 TC-04 Pointing Accuracy Test 验证,因此不需要新的测试用例。
- 改为让它为 issue 列表中的某个需求提议测试用例,然后在 Holarch 中评审并应用该提议。
- 再次运行工作流。
该需求不再被列出。
提示
- 为工作流提供其自己的只读令牌,并限制在该项目内。移除工作流时,请在账户设置 → 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,然后开始新的对话。 |