參考資料
Python 用戶端
使用免費的 holarch-api 套件,從 Python 指令碼讀取 Holarch 專案、搜尋項目並提出變更供審查;安裝、登入、每個方法、提案、錯誤與限制。
概觀
holarch-api 是適用於 Holarch REST API 的小型 Python 套件。它可讀取專案、項目、文件與檢查結果、進行搜尋,並提出變更。它是免費的;API 本身隨附於包含它的方案,而套件使用您的個人存取權杖。
透過此套件進行的變更一律是提議:它們會收集在伺服器上,由專案的擁有者在 Holarch 中審查並套用,與來自 AI 用戶端的變更完全相同,每個已套用的提議都能以一次復原撤回。此套件沒有直接變更專案的方法。必須直接寫入的指令碼請使用 REST API 的寫入呼叫。
概念
- 用戶端:一個 Holarch 伺服器上的一個權杖。每個方法傳送一個請求(或每頁一個),並將 API 的 JSON 以 Python dict 與 list 傳回。
- 具型別的回應:此套件帶有型別資訊(
TypedDict形狀,例如Entity與ProjectSummary),因此編輯器可自動完成欄位名稱,mypy 等型別檢查器也能檢查它們。伺服器之後新增的欄位會直接出現在 dict 中。 - 提議:您在某個專案中開啟中的提議。每次呼叫會新增一項變更;
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 天後到期。
- 此用戶端適用於託管服務。