参考
Python 客户端
使用免费的 holarch-api 包,从 Python 脚本读取 Holarch 项目、搜索条目并提出供评审的变更;涵盖安装、登录、每个方法、提议、错误和限制。
概述
holarch-api 是一个用于 Holarch REST API 的小型 Python 包。它读取项目、条目、文档和检查结果,进行搜索并提议更改。它是免费的;API 本身随包含它的方案提供,该包使用您的个人访问令牌。
通过该包进行的更改始终是提议:它们汇集在服务器上,由项目所有者在 Holarch 中评审并应用,与来自 AI 客户端的更改完全相同,每个已应用的提议都可通过一次撤销撤回。该包没有直接更改项目的方法。必须直接写入的脚本请使用 REST API 的写入调用。
概念
- 客户端:一个 Holarch 服务器上的一个令牌。每个方法发送一个请求(或每页一个),并将 API 的 JSON 以 Python 字典和列表返回。
- 类型化的响应:该包带有类型信息(诸如
Entity和ProjectSummary的TypedDict结构),因此编辑器可以补全字段名,mypy 等类型检查器可以检查它们。服务器以后新增的字段会直接出现在字典中。 - 提议:您在一个项目中打开的提议。每次调用添加一项更改;
send()将提议交给项目所有者评审。一个令牌在每个项目中最多有一个打开的提议。 - 引用:在提议中创建的实体尚不存在。
create()返回一个引用(new:1、new:2…),同一提议中的后续更改用它代替 ID。
如何使用
何时使用及原因
将该客户端用于围绕项目的脚本:按您自己格式生成的报告和导出、夜间任务中的检查,以及从其他工具导入、需要有人在落地前评审的内容。由于更改以提议形式到达,脚本永远不会让团队措手不及:所有者在应用前会看到每一项更改。
安装和登录
- 安装 Python 3.9 或更高版本,然后安装该包:
python3 -m pip install holarch-api。除 Python 外它不需要任何其他东西。 - 在 Holarch 中打开账户设置 → API 令牌并创建一个令牌:只读取的脚本用只读,提议更改的脚本用读写。将其限制在脚本所需的项目内。
- 将令牌放入
HOLARCH_API_KEY环境变量中。 - 检查连接:
from holarch_api import Client
c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
print(p["id"], p["name"], p["role"])
读取项目
c = Client()
pid = "…" # the project id from c.projects()
info = c.project(pid) # name, description, items per class
for e in c.iter_entities(pid, cls="Requirement"):
print(e["number"], e["name"])
req = c.entity(pid, "…") # one entity with attributes and relationships
for r in req["relationships"]:
print(r["relation"], r["other"]["name"])
iter_entities 逐页获取所有匹配项;entities 返回一页(entities、total、offset、limit)。search(pid, "thermal") 查找名称、编号、描述或类中包含该文本的实体。
提议更改
- 开始一个提议:
p = c.proposal(pid)。 - 添加更改。服务器会立即检查每次调用,当类、关系或属性不存在时会以错误失败:
p = c.proposal(pid)
tc = p.create("Test Case", "Thermal vacuum test", description="Soak at -40 C for 8 hours.",
relationships=[("verifies", "…requirement id…")])
p.update("…", attributes={"Status": "Approved"})
p.relate(tc, "verifies", "…another requirement id…")
- 查看已收集的内容:
p.get()["changes"]。项目尚未更改。 - 发送它:
view = p.send("Add a TVAC test", "Covers the two thermal requirements.")。view["review"]是在 Holarch 中打开评审的链接。
所有者会收到通知,并从 ✦ AI ▾ 菜单评审该提议;请参阅来自 AI 客户端的提议。要在发送前丢弃提议,请调用 p.discard()。之后要跟进时,c.get_proposal(pid, view["id"])["status"] 为 ready、applied、rejected 或 expired。
实例:CubeSat EO-1 演示
- 为 CubeSat 项目创建只读令牌并设置
HOLARCH_API_KEY。 - 列出模型检查的需求发现项:
c = Client()
pid = next(p["id"] for p in c.projects() if p["name"].startswith("CubeSat"))
checks = c.model_checks(pid, cls="Requirement")
print(checks["total"], "findings")
- 为需求评分:
c.quality(pid)["results"]列出每个需求及其分数和发现项。 - 使用读写令牌,按提议更改中的方法为没有测试用例的需求提议一个测试用例并发送。所有者应用后,模型检查将不再列出该需求。
SysML v2 项目
同一客户端也能读取 SysML v2 项目:model(pid)(包和计数)、elements(pid, q=…, type=…)、element(pid, "Vehicles::Engine")、requirements(pid)、diagnostics(pid) 和 sysml_text(pid, root="Vehicles")。check_sysml(pid, text) 检查文本而不提议它。要提议更改,请用 p.sysml_text(text, root="Vehicles") 发送包的新文本,或用 p.sysml_edits([...]) 发送元素编辑;引擎会检查每项更改,并拒绝有错误的更改。请参阅 SysML v2 项目中的 API 和 MCP。
提示和良好做法
- 先读取架构(
c.schema(pid)):它列出项目使用的类、属性和关系名称。 - 为每个脚本提供各自的令牌,只读取的设为只读。
- 将相关更改收集到一个提议中,并附上说明原因的标题和摘要后发送:评审者可以一次看到完整的更改。
- 不要将令牌放在源文件中;客户端正是因此读取
HOLARCH_API_KEY。
常见错误
- 代码为
read-only-token的ApiError:令牌为只读;请为提议创建读写令牌。 - 在您能于 Holarch 中打开的项目上出现代码为
not-found的ApiError:令牌被限制在其他项目中。 - 用
entity()找不到已创建的实体:在所有者应用之前,它只存在于提议中。
参考
客户端
Client(token=None, server=None, timeout=30.0, retries=3)。token 默认为 HOLARCH_API_KEY,server 默认为 HOLARCH_SERVER 或 https://app.holarch.app。服务器必须是 https 地址。
| 方法 | 返回 |
|---|---|
me() | 令牌的账户、访问权限和到期时间 |
projects() | 您的项目:ID、名称、角色、条目数、语言、链接 |
project(pid) | 名称、描述、角色、条目数、每个类的条目数、文档数量 |
schema(pid) | 类及其属性和允许的关系;关系 |
entities(pid, cls=None, label=None, q=None, limit=100, offset=0) | 一页实体(最多 500 个) |
iter_entities(pid, cls=None, label=None, q=None, page_size=500) | 所有匹配的实体 |
search(pid, text, cls=None, limit=100) | 名称、编号、描述或类中包含该文本的实体 |
entity(pid, id) | 单个实体及其属性、标签和关系 |
documents(pid) | 文档及其类型和章节数 |
document(pid, id) | 单个文档及其按顺序排列、带编号的章节,以纯文本形式返回 |
model_checks(pid, cls=None, rule=None, limit=500, offset=0) | 模型检查发现项及摘要 |
quality(pid, ids=None) | 需求质量检查,针对指定的需求或全部需求 |
versions(pid) | 项目方案所保留的已保存版本 |
configurations(pid) | 产品线:特性、规则和配置,及其选择、判定结果和适用性 |
proposal(pid) | 代表您在该项目中打开的提议的 Proposal |
get_proposal(pid, proposal_id=None) | 打开的提议,或按 ID 指定的提议,及其状态和更改 |
request(method, path, params=None, body=None) | 任何其他 API 调用,相对于 /api/v1 |
project、entities、iter_entities、search、entity、documents、document、model_checks 和 quality 还接受 configuration=(配置的编号、名称或 ID)和 effectivity=("sn:23" 或 "date:2027-03-01"),以按产品线某个配置所显示的样子读取模型(产品线)。
提议
| 方法 | 它提议的内容 |
|---|---|
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None) | 一个新实体;relationships 为 (relation, target) 对;返回其引用 |
update(entity, name=None, number=None, description=None, labels=None, attributes=None) | 更改的字段;未提供的字段保持不变,设为 None 的属性会失去其值 |
delete(entity) | 将实体移到项目的回收站 |
relate(source, relation, target, attributes=None) | 一个新关系,从源端命名 |
unrelate(relationship) | 移除一个关系(其 ID 来自 entity()) |
get() | 无:返回提议及其更改 |
send(title, summary="") | 不再添加:将提议发送评审,并返回它及评审链接 |
discard() | 无:丢弃打开的提议 |
create 和 update 还接受 applies_to=("F-3 and not F-5";"" 将其清除)和 effectivity=({"serials": "1-20, 25"};{} 将其清除),每项更改都接受 configuration=,以将其作为该配置中的编辑来提议(产品线)。
错误
每个被拒绝的请求都会引发 holarch_api.ApiError,带有 message(服务器的文本)、code、status 和 body。代码与 REST API 的相同。以 429 rate-limited 被拒绝的请求会在服务器指定的时间后重试,最多 retries 次,然后才引发错误。
限制
- API 的限制适用(API 和 MCP):请求速率、每页最多 500 个实体,以及应用提议时项目的条目限制。
- 提议在开始 7 天后到期。
- 该客户端适用于托管服务。