Holarch

参考

实践示例:Jira

通过 REST API 将 Holarch 需求连接到 Jira 问题,并借助 AI 应用将 Jira 问题转为经评审的 Holarch 变更;涵盖设置、同步脚本、完整示例和故障排除。

使用方法 →

本页内容
  1. 概述
  2. 前提条件
  3. 如何使用
    1. 何时使用及原因
    2. 设置同步
    3. 根据已审批的需求创建 Jira 问题
    4. 在 Holarch 中保存 Jira 键(可选)
    5. 借助 AI 应用将 Jira 问题转化为 Holarch 提议
    6. 实例:CubeSat EO-1 演示
    7. 提示
  4. 故障排除
  5. 相关页面

概述

本实践示例将 Jira 中的工程工作与 Holarch 中的需求关联起来。它分为两部分:

  • Holarch 到 Jira(REST API):脚本为每个已审批的需求创建一个 Jira 问题。每个问题都链接回 Holarch 中的需求。可随时再次运行:已有问题的需求会被跳过。
  • Jira 到 Holarch(MCP,通过 AI 应用):AI 应用读取一个 Jira 问题(例如客户变更请求),并在 Holarch 中提议相应的需求更改。在您于 Holarch 中评审并应用提议之前,不会有任何更改。

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

前提条件

  • 包含 API 和 MCP 的方案:Individual 或 Team,或 Individual 试用。在 Free 方案中,拥有已验证学术邮箱地址或属于活跃班级组织的账户也可使用它们(方案和限制)。
  • 一个 Holarch 项目,您是其编辑者或所有者。提议需要编辑者角色。
  • 个人访问令牌:账户设置 → API 令牌 → 新令牌。为 Holarch 到 Jira 的脚本使用只读,并将其限制在该项目内(创建令牌)。
  • Jira Cloud:一个您可以在其中创建问题的 Jira 项目,以及一个 Atlassian API 令牌(Atlassian 账户设置 → Security → API tokens)。Jira Data Center 则使用 /rest/api/2/ 路径和个人访问令牌;请查阅其 API 参考。
  • 用于运行脚本的 Python 3.9 或更高版本及 requests 包(python3 -m pip install requests)。
  • AI 应用部分:已连接到 Holarch 的 AI 应用(将 Holarch 连接到 AI 应用)。只有在该 AI 应用还拥有 Jira 连接器时,它才能自己读取 Jira 问题;否则请将问题文本粘贴到对话中。

如何使用

何时使用及原因

需求存放在 Holarch 中;构建和测试它们的工作通常在 Jira 中规划。将两者关联可以回答两个问题:“哪些 Jira 工作实现了这个需求?”和“这个变更请求涉及哪些需求?”。每次需求评审之后、新需求达到 Approved 时,运行同步。

设置同步

  1. 在 Holarch 中创建一个限制在该项目内的只读令牌。复制它。
  2. 查找项目 ID:GET /api/v1/projects 列出您的项目及其 id。
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. 设置脚本读取的环境变量:
    • HOLARCH_TOKEN:Holarch 令牌。
    • HOLARCH_PROJECT:项目 ID。
    • JIRA_URL:您的 Jira 站点,例如 https://your-site.atlassian.net。
    • JIRA_EMAIL 和 JIRA_API_TOKEN:您的 Atlassian 登录邮箱和 API 令牌。
    • JIRA_PROJECT:Jira 项目键,例如 EO。
  2. 将下面的脚本另存为 holarch_to_jira.py。

根据已审批的需求创建 Jira 问题

该脚本通过 REST API 读取每个需求,跳过已有 Jira 问题的需求,并为其余状态为 Approved 的每个需求创建一个 Task。

# holarch_to_jira.py: one Jira issue per approved Holarch requirement. Safe to run again.
import os

import requests

HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
JIRA = os.environ["JIRA_URL"].rstrip("/")
JIRA_AUTH = (os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"])
JIRA_PROJECT = os.environ["JIRA_PROJECT"]


def holarch(method, path, **kw):
    r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
    if r.status_code >= 400:
        d = r.json()
        raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
    return r.json()


def requirements():
    offset = 0
    while True:
        page = holarch("GET", f"/projects/{PROJECT}/entities",
                       params={"class": "Requirement", "limit": 500, "offset": offset})
        yield from page["entities"]
        offset += page["limit"]
        if offset >= page["total"]:
            return


def linked_in_jira():
    """The Jira labels holarch-<requirement id> already on issues of the Jira project."""
    seen, token = set(), None
    while True:
        params = {"jql": f'project = "{JIRA_PROJECT}" AND labels = holarch', "fields": "labels", "maxResults": 100}
        if token:
            params["nextPageToken"] = token
        r = requests.get(JIRA + "/rest/api/3/search/jql", params=params, auth=JIRA_AUTH, timeout=60)
        r.raise_for_status()
        d = r.json()
        for issue in d.get("issues", []):
            seen.update(x for x in issue["fields"]["labels"] if x.startswith("holarch-"))
        token = d.get("nextPageToken")
        if not token:
            return seen


seen = linked_in_jira()
for req in requirements():
    if "holarch-" + req["id"] in seen:
        continue
    e = holarch("GET", f"/projects/{PROJECT}/entities/{req['id']}")["entity"]
    if e["attributes"].get("Status") != "Approved":
        continue
    text = (e["description"] + "\n\n" if e["description"] else "") + "Requirement in Holarch: " + e["url"]
    fields = {
        "project": {"key": JIRA_PROJECT},
        "issuetype": {"name": "Task"},
        "summary": f"{e['number']} {e['name']}".strip(),
        "labels": ["holarch", "holarch-" + e["id"]],
        "description": {"type": "doc", "version": 1, "content": [
            {"type": "paragraph", "content": [{"type": "text", "text": text}]}]},
    }
    issue = requests.post(JIRA + "/rest/api/3/issue", json={"fields": fields}, auth=JIRA_AUTH, timeout=60)
    issue.raise_for_status()
    key = issue.json()["key"]
    print(f"{e['number']} {e['name']} -> {key}")
  1. 运行 python3 holarch_to_jira.py。

    每个新问题显示一行,例如 2.1 Pointing Accuracy -> EO-12。

工作原理:

  • GET /api/v1/projects/<project>/entities?class=Requirement 列出需求,每次 500 个。
  • GET /api/v1/projects/<project>/entities/<id> 给出每个需求的属性(此处为状态)及其 url,即在 Holarch 中打开它的链接。
  • 每个问题都会获得 Jira 标签 holarch 和 holarch-<id>。下次运行时通过 Jira 搜索找到它们,并跳过这些需求。
  • 需求只会被读取。脚本不会更改 Holarch 中的任何内容。

在 Holarch 中保存 Jira 键(可选)

要在 Holarch 的需求上看到 Jira 键,请添加一个文本属性并将键写入其中。

  1. 在 Holarch 中打开设置 → 架构,点击 Requirement,然后添加一个名为 Jira Key、类型为短文本的属性(为类添加属性)。
  2. 为脚本创建一个读写令牌,代替只读令牌。
  3. 在脚本最后一个循环的末尾、print(…) 行之后,添加:
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

该更改与应用中的编辑一样写入:以您的名义记录,所有打开该项目的人都能看到。设置此属性不会将已审批的需求退回评审。当项目使用配置控制时,已审批的需求会拒绝直接更改(409 change-control);请只在 Jira 中保存该键,或通过变更请求进行更改。

借助 AI 应用将 Jira 问题转化为 Holarch 提议

当 Jira 问题要求更改需求时(例如客户要求收紧某个值),请使用此方法。

  1. 打开以读取并提出更改访问权限连接到 Holarch 的 AI 应用。
  2. 例如,可以询问:“读取 Jira 问题 EO-31。在 CubeSat 项目中找出它影响的 Holarch 需求,并提议它所要求的更改。在提议摘要中提及 EO-31。”

    没有 Jira 连接器时,请改为将问题的摘要和描述粘贴到消息中。

  3. AI 应用使用 list_projects、search_entities 和 get_entity 读取项目。它用 update_entity(对于新需求,用 create_entity 和 relate)将每项更改添加到提议中,然后用 propose_changes 发送。

    AI 应用会回复提议的标题和评审链接。

  4. 在 Holarch 中打开 ✦ AI ▾ → 评审“<title>”…,或铃铛下的通知。
  5. 检查每项更改。取消勾选不需要的内容,然后点击应用所选项。

    这些更改会被应用,一次撤销即可全部撤回。更改的需求文本会将其追溯关联标记为待审查,已审批的需求会退回 In Review,与任何编辑一样。

脚本无需 AI 应用也能提出相同的提议:每项更改 POST 一次 /api/v1/projects/<project>/proposal/changes,然后带 title 和 summary POST /api/v1/projects/<project>/proposal。

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"op": "update", "entity": "<requirement id>", "description": "The ADCS shall point the payload boresight within 0.08 degrees of the commanded target."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal/changes
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"title": "EO-31: tighter pointing", "summary": "Customer request EO-31 tightens pointing accuracy to 0.08 degrees."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal

实例:CubeSat EO-1 演示

  1. 通过管理项目 → 项目文件 ▾ → 新建演示项目创建演示。
  2. 创建一个限制在演示项目内的只读令牌,并针对一个测试 Jira 项目运行 holarch_to_jira.py。

    每个已审批的需求都会得到一个问题,例如 2.1 Pointing Accuracy,文本为“The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.”,并附有指向该需求的链接。

  3. 再次运行脚本。

    它不输出任何内容:每个已审批的需求都已有其问题。

  4. 在 Jira 中创建一个问题 EO-31,要求将 0.1 度改为 0.08 度。按上述方法让 AI 应用提议该更改。
  5. 在 Holarch 中评审该提议。它更改 2.1 Pointing Accuracy 的文本,其影响列表显示验证它的 TC-04 Pointing Accuracy Test。

提示

  • 为同步脚本提供其自己的只读令牌,并限制在该项目内。为 AI 应用提供单独的连接。
  • 将令牌保存在您的密钥存储或环境变量中,绝不要写在脚本里。
  • 在 Jira 中用标签 holarch 搜索某个冲刺背后的需求。
  • 需求编号可能会变;holarch-<id> 标签不会变。请按标签匹配,而不是按摘要中的编号匹配。

故障排除

消息或症状原因和解决方法
Holarch answered 401 token-invalid令牌错误、已撤销或已到期。请在账户设置 → API 令牌下创建新令牌。
Holarch answered 403 plan-api账户的方案不包含 API 和 MCP。请开始 Individual 试用或选择方案;之后令牌即可再次使用。
Holarch answered 403 org-policy项目所属组织已关闭 API 访问。请联系组织管理员。
Holarch answered 403 read-only-token写入 Jira Key 需要读写令牌。
Holarch answered 400 unknown-attribute项目中 Requirement 没有 Jira Key 属性。请在设置 → 架构中添加它,或省略这一可选步骤。
Holarch answered 409 change-control该需求处于配置控制之下。请通过变更请求更改它,或只在 Jira 中保存该键。
Holarch answered 429 rate-limited每分钟超过 600 个请求或 120 次更改。请等待 Retry-After 中的秒数,然后再次运行;已完成的问题会被跳过。
Jira 返回 400Jira 拒绝了问题字段,例如项目中没有的问题类型。请使用项目中的某个问题类型代替 Task。
Jira 返回 401 或 403请检查 JIRA_EMAIL、JIRA_API_TOKEN 以及您在该 Jira 项目中创建问题的权限。
AI 应用不显示 Holarch 写入工具该连接为只读。请以读取并提出更改重新连接,然后开始新的对话。