rhdh-jira-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RHDH Jira API

One home for talking to Jira. The command syntax, the field IDs, the query patterns, and the workflow rules live here so that the create, refine, update, and sprint skills carry none of their own copies.

This skill reads. It never decides what to file and never approves a write — though it does define exactly what a write costs, because the payload shapes are here.

所有与Jira交互的统一入口。命令语法、字段ID、查询模式和工作流规则都集中在此，这样创建、优化、更新和迭代相关技能就无需各自维护这些内容的副本。

本技能仅负责读取操作。它从不决定要创建什么工单，也从不批准写入操作——不过它会明确定义写入操作的具体要求，因为请求体的格式在此处定义。

Route by question

按问题路由

Question	Load
Is Jira reachable? Is `acli` authenticated?	references/auth.md, then `uv run scripts/setup.py --json`
Which `acli` flag does this, and what breaks?	references/acli-commands.md
What JQL answers this? Which board or sprint?	references/jql-patterns.md
Which custom field, label, link type, component, or priority?	references/fields.md
What must be true before this status transition?	references/workflows.md
I need a relationship-heavy bulk read or a team roster	references/graphql-queries.md
`acli` cannot read or set this field	references/rest-api-fallback.md

Load the one branch the question needs.

问题	参考内容
Jira是否可达？ `acli` 是否已完成认证？	references/auth.md，然后执行 `uv run scripts/setup.py --json`
哪个 `acli` 参数能实现此功能，可能会出现什么问题？	references/acli-commands.md
用什么JQL可以解答这个问题？对应哪个看板或迭代？	references/jql-patterns.md
对应的自定义字段、标签、链接类型、组件或优先级是什么？	references/fields.md
状态转换前必须满足哪些条件？	references/workflows.md
我需要进行关联关系密集的批量读取或获取团队成员列表	references/graphql-queries.md
`acli` 无法读取或设置此字段	references/rest-api-fallback.md

只需加载对应问题所需的分支内容即可。

The two traps that produce wrong answers

导致错误结果的两个陷阱

Both fail silently, and both have burned this pack before.

Default page size is 30. Rows past the thirtieth are dropped with no warning, so a query that should return 140 issues quietly returns 30 and every count built on it is wrong. Pass

--limit 500

--paginate

on every bulk search, and use

--count

first when the total matters.

Custom fields are absent unless you ask for them.

search --json

and

view KEY --json

return only assignee, issuetype, priority, status, and summary. Story Points, Team, Size, and Sprint come back empty — which looks exactly like a field nobody set. Enrich with

scripts/parse_issues.py --enrich

view KEY --fields '*all' --json

before claiming any of them is missing.

A field you could not retrieve is reported as unretrieved, never as empty.

这两个陷阱都会静默失败，并且之前都曾给团队造成过困扰。

默认分页大小为30。超过第30条的结果会被无警告丢弃，因此一个本应返回140条工单的查询会悄悄只返回30条，基于此的所有统计数据都会出错。在所有批量搜索中都要传入

--limit 500

或

--paginate

参数，当总数很重要时，先使用

--count

参数获取总数。

自定义字段默认不返回。

search --json

和

view KEY --json

仅返回经办人、工单类型、优先级、状态和摘要。Story Points、团队、规模和迭代字段会返回空值——这看起来和未设置过的字段完全一样。在断言这些字段不存在之前，先使用

scripts/parse_issues.py --enrich

或

view KEY --fields '*all' --json

来补充字段信息。

无法获取的字段会被标记为未获取，绝不会被报告为空值。

Bundled scripts

内置脚本

Run these from this skill's directory.

Script	Purpose
`scripts/setup.py`	Capability and auth detection; `--json` for structured output
`scripts/parse_issues.py`	Enrich, flatten, select, filter, or CSV-export `acli` JSON
`scripts/validate_components.py`	Compare the documented component catalog against live Jira
`scripts/jira-wiki-to-adf.py`	Convert a filled wiki-markup template to ADF JSON

Stdlib only. Another skill invokes

/rhdh-jira-api

by name and lets this skill run them; it never reaches into this directory by path.

请在本技能的目录下运行这些脚本。

脚本	用途
`scripts/setup.py`	功能与认证检测；使用 `--json` 参数可获取结构化输出
`scripts/parse_issues.py`	对 `acli` 返回的JSON数据进行补充、扁平化、筛选、过滤或导出为CSV格式
`scripts/validate_components.py`	将文档化的组件目录与Jira实时数据进行对比
`scripts/jira-wiki-to-adf.py`	将填写好的wiki标记模板转换为ADF JSON格式

仅使用标准库。其他技能通过名称调用

/rhdh-jira-api

，由本技能运行这些脚本；绝不会通过路径直接访问本目录。

Writes

写入操作

This skill does not perform writes, but the payloads live here because the field IDs do. It hands the caller a command or a payload, never an effect. Whichever skill owns the verb invokes

/mutation-gate

and runs it from there.

Credentials never appear in an argument, a preview, a log, or the answer. A command built here takes its credential from

acli

's own store or the authenticated host adapter at run time, so nothing this skill hands back carries one.

本技能不执行写入操作，但由于字段ID在此处定义，写入请求体也存储在此。它会向调用者提供命令或请求体，绝不会直接产生执行效果。负责对应动词的技能会调用

/mutation-gate

并从那里执行写入操作。

凭证绝不会出现在参数、预览、日志或回答中。此处生成的命令会在运行时从

acli

自身的存储或已认证的主机适配器获取凭证，因此本技能返回的任何内容都不会携带凭证。

Boundary with the neighbouring skills

与相邻技能的边界

Opening new work is
```
/rhdh-jira-create
```
.
Judging whether existing work is ready is
```
/rhdh-jira-refine
```
.
Changing a field, status, assignee, comment, or link on a known key is
```
/rhdh-jira-update
```
.
Sprint carryover, velocity, and capacity are
```
/rhdh-jira-sprint-plan
```
; the end-of-sprint summary is
```
/rhdh-jira-sprint-report
```
.
Issue templates, the grill matrix, sizing scales, and decomposition rules are
```
/rhdh-jira-authoring
```
.
What is still open against a release is
```
/rhdh-release-status
```
.
Creating or repairing a credential is
```
/setup-rhdh-skills
```
.

创建新工单属于
```
/rhdh-jira-create
```
。
判断现有工单是否就绪属于
```
/rhdh-jira-refine
```
。
修改已知工单号的字段、状态、经办人、评论或链接属于
```
/rhdh-jira-update
```
。
迭代结转、速度和容量规划属于
```
/rhdh-jira-sprint-plan
```
；迭代结束总结属于
```
/rhdh-jira-sprint-report
```
。
工单模板、审查矩阵、规模分级和拆分规则属于
```
/rhdh-jira-authoring
```
。
版本相关的未完成工单查询属于
```
/rhdh-release-status
```
。
创建或修复凭证属于
```
/setup-rhdh-skills
```
。

Completion

完成标准

A read is complete when every field the answer asserts was actually fetched. Report the exact JQL or command used, the number of issues returned, and whether the result was truncated — a truncated result is an incomplete answer, not a finding. Say which adapter produced each fact,

acli

or the host adapter. A field the API could not supply is named as unretrieved rather than reported as empty or carried over from an earlier query.

当答案中声明的每个字段都已实际获取到，读取操作才算完成。需要报告所使用的精确JQL或命令、返回的工单数量，以及结果是否被截断——截断的结果属于不完整的答案，而非有效结论。要说明每个事实由哪个适配器生成，是

acli

还是主机适配器。API无法提供的字段会标记为未获取，而非报告为空值或沿用之前查询的结果。