rhdh-jira-api

用途

RHDH Jira API 是「与 Jira 对话」的统一入口。命令语法、字段 ID、查询模式和工作流规则都集中在这里，因此创建、精炼、更新和冲刺类技能无需各自维护副本。

该技能只做读取。它从不决定要提交什么，也从不批准写入——但它确实定义了写入的代价，因为载荷结构存放在此处。

按问题路由到对应参考文档：

Jira 是否可达？acli 是否已认证？→ references/auth.md，然后运行 uv run scripts/setup.py --json
某个 acli 标志怎么用、会出什么问题？→ references/acli-commands.md
用什么 JQL 回答这个问题？哪个看板或冲刺？→ references/jql-patterns.md
用哪个自定义字段、标签、链接类型、组件或优先级？→ references/fields.md
如何创建或查询私有（Security Level）问题？→ references/fields.md（私有问题；也涉及 jql-patterns / acli-commands）
状态转换前必须满足什么条件？→ references/workflows.md
需要关系密集的批量读取或团队名册 → references/graphql-queries.md
acli 无法读取或设置某字段 → references/rest-api-fallback.md
冲刺报告或燃尽图数字 → references/rest-api-fallback.md，然后运行 uv run scripts/greenhopper.py

只需加载问题所需的那一个分支。

两者都会静默失败，且都曾让本技能包吃亏。

默认分页大小为 30。第 30 行之后的行会被无警告丢弃，因此一个本应返回 140 个问题的查询会悄悄只返回 30 个，基于它构建的每个计数都是错的。每次批量搜索都要传 --limit 500 或 --paginate，当总数重要时先用 --count。
除非主动请求，否则自定义字段不会出现。search --json 和 view KEY --json 只返回 assignee、issuetype、priority、status 和 summary。Story Points、Team、Size 和 Sprint 会返回空——看起来就像没人设置过该字段。在声称某个字段缺失之前，先用 scripts/parse_issues.py --enrich 或 view KEY --fields '*all' --json 补充。

无法检索到的字段应报告为「未检索到」，绝不能报告为空。

随附脚本（从本技能目录运行）：

scripts/setup.py：能力与认证检测；--json 报告 token_file_found / token_file_status，但不打印文件内容
scripts/parse_issues.py：对 acli JSON 进行补充、展平、选择、过滤或 CSV 导出
scripts/greenhopper.py：使用本地令牌文件在进程内 GET Greenhopper sprintreport / scopechange
scripts/validate_components.py：将文档化的组件目录与实时 Jira 对比
scripts/jira-wiki-to-adf.py：将填写好的 wiki 标记模板转换为 ADF JSON

仅使用标准库。其他技能按名称调用 /rhdh-jira-api 并让它运行这些脚本；它从不按路径深入该目录。

该技能不执行写入，但载荷存放在此处，因为字段 ID 在这里。它把命令或载荷交给调用方，从不产生实际效果。拥有该动词的技能会调用 /mutation-gate 并从那里运行。

凭据绝不会出现在参数、预览、日志或答案中。此处构建的命令从 acli 自己的存储、本地令牌文件适配器（进程内，绝不打印）或运行时已认证的主机适配器获取凭据，因此该技能返回的任何内容都不携带凭据。

当答案断言的每个字段都确实被获取时，一次读取才算完成。报告所用的确切 JQL 或命令、返回的问题数量，以及结果是否被截断——截断的结果是不完整的答案，不是发现。说明每个事实由哪个适配器产生，acli 还是主机适配器。API 无法提供的字段应命名为「未检索到」，而不是报告为空或沿用早先查询的结果。