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
如何创建或查询私有（安全级别）问题？	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 只会返回经办人、问题类型、优先级、状态和摘要。故事点数、团队、规模和冲刺会显示为空——看起来和从未设置字段一模一样。在断言这些字段缺失之前，请使用 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 冲刺报告 / 范围变更
scripts/validate_components.py	将文档中的组件目录与实时 Jira 数据进行比对
scripts/jira-wiki-to-adf.py	将填好的 wiki 标记模板转换为 ADF JSON

仅使用标准库。其他技能会按名称调用 /rhdh-jira-api，并由此技能运行这些脚本；它们不会通过路径访问此目录。

写入

此技能不会执行写入，但载荷保存在这里，因为字段 ID 也在这里。它只会向调用方提供命令或载荷，不会产生任何效果。负责相应操作的技能会调用 /mutation-gate，并从那里执行操作。

凭据绝不会出现在参数、预览、日志或答复中。在此构建的命令会在运行时从 acli 自身的存储、本地令牌文件适配器（在进程内使用，绝不打印），或经过身份验证的主机适配器中获取凭据，因此此技能返回的内容不会包含凭据。

与相邻技能的界限

• 开启新工作使用 /rhdh-jira-create。
• 判断现有工作是否已准备就绪使用 /rhdh-jira-refine。
• 修改已知键对应的字段、状态、经办人、评论或链接使用 /rhdh-jira-update。
• Sprint 结转、速率和下一 Sprint 的容量规划使用 /rhdh-jira-sprint-plan；Sprint 结束总结使用 /rhdh-jira-sprint-report。
• 判断团队能否在 Code Freeze 前完成 rhdh-X.Y-candidate Features，使用 /rhdh-release-capacity-plan。
• Issue 模板、grill 矩阵、规模量表和分解规则使用 /rhdh-jira-authoring。
• 查看某个版本仍有哪些未关闭事项，使用 /rhdh-release-status。
• 创建或修复凭据使用 /setup-rhdh-skills。

完成标准

只有在回答中断言的每个字段都已实际获取时，读取才算完成。 报告使用的确切 JQL 或命令、返回的 issue 数量，以及结果是否被截断—— 结果被截断意味着回答不完整，而非一项发现。说明每条事实由哪个适配器提供：acli 还是宿主适配器。API 无法提供的字段应标记为未获取，而不能报告为空，也不能沿用此前查询的结果。