Holarch

參考資料

Python 用戶端

使用免費的 holarch-api 套件,從 Python 指令碼讀取 Holarch 專案、搜尋項目並提出變更供審查;安裝、登入、每個方法、提案、錯誤與限制。

使用方式 →

本頁內容
  1. 概觀
  2. 概念
  3. 使用方式
    1. 使用時機與原因
    2. 安裝並登入
    3. 讀取專案
    4. 提出變更
    5. 實例演練:CubeSat EO-1 示範
    6. SysML v2 專案
    7. 提示與良好做法
    8. 常見錯誤
  4. 參考資料
    1. 用戶端
    2. 提議
    3. 錯誤
  5. 限制
  6. 相關頁面

概觀

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。

使用方式

使用時機與原因

將此用戶端用於專案周邊的指令碼:以您自己的格式產生報告與匯出、在夜間工作中執行檢查、從其他工具匯入需要有人先審查的內容。由於變更以提議形式送達,指令碼絕不會讓團隊措手不及:擁有者會在套用之前看到每項變更。

安裝並登入

  1. 安裝 Python 3.9 或更新版本,然後安裝此套件:python3 -m pip install holarch-api。除了 Python 以外不需要其他任何東西。
  2. 在 Holarch 中,開啟帳戶設定 → API 權杖並建立權杖:只讀取的指令碼使用唯讀,會提出變更的指令碼使用讀寫。將其限制在指令碼所需的專案。
  3. 將權杖放入 HOLARCH_API_KEY 環境變數。
  4. 檢查連線:
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") 會找出名稱、編號、描述或類別包含該文字的實體。

提出變更

  1. 開始提議:p = c.proposal(pid)。
  2. 新增變更。每次呼叫都會立即由伺服器檢查,當類別、關係或屬性不存在時會以錯誤失敗:
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…")
  1. 查看收集到的內容:p.get()["changes"]。專案尚未變更。
  2. 送出: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 示範

  1. 為 CubeSat 專案建立唯讀權杖並設定 HOLARCH_API_KEY。
  2. 列出模型檢查中的需求發現事項:
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")
  1. 為需求評分:c.quality(pid)["results"] 會列出每個需求及其分數與發現事項。
  2. 使用讀寫權杖,依提出變更中的方式,為沒有測試案例的需求提議一個測試案例並送出。擁有者套用後,模型檢查就不再列出該需求。

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 天後到期。
  • 此用戶端適用於託管服務。