rhdh-forge

RHDH Forge

集中读取 Forge 信息并构造写入载荷。问题解析、问题获取、工作区解析、检查和流水线读取、仓库内容读取，以及容易误导初次使用者的 gh 和 glab 行为，都集中在这里。否则，每个涉及 Forge 的技能都会保留一份各自逐渐偏离的副本。

此技能只读取信息，不会执行写入操作。

GitHub 操作通过 gh 进行。GitLab 操作——gitlab.cee.redhat.com 上的 rhidp/rhdh 和 rhidp/rhdh-plugin-catalog——通过 glab 进行；只有涉及 GitLab 主机时才需要 glab。

按结果选择路径

结果	加载并遵循
将 GitHub 问题引用转换为结构化上下文	运行 uv run scripts/fetch_issue_context.py <reference>
无需网络调用即可解析 GitHub 或 GitLab 引用	references/issue-context.md
确定问题所属的插件工作区	references/issue-context.md
读取 PR 状态、标签、受指派人、文件或检查状态	references/gh-cli.md
说明检查失败、过期或缺失的原因	references/gh-cli.md
从仓库或 PR 分支读取文件	references/gh-cli.md
读取 GitLab 问题、MR 状态、流水线状态或文件	references/glab-cli.md
准备 GitHub 拉取请求创建载荷	references/gh-cli.md，然后遵循调用方的变更门控
准备 GitLab 合并请求创建载荷	references/glab-cli.md，然后遵循调用方的变更门控
准备评论、标签、受指派人或 /publish 载荷	references/issue-context.md，然后遵循调用方的变更门控
准备 GitLab 评论、标签或批准载荷	references/glab-cli.md，然后遵循调用方的变更门控

调用方按名称调用此技能并使用其返回内容。不要从其他技能加载此技能的文件。

不变量

• 此处的所有路径均为只读。调用方需要写入时，获取的是载荷，而不是执行操作。
• 使用已解析的命名空间、仓库和编号构造问题、PR 或 MR URL。绝不保留用户提供的原始 URL；其中可能带有片段或查询字符串。
• Jira 键不属于此技能的工作范围。提取该键并交还给调用方，由调用方调用 /rhdh-jira-api 获取详细信息。
• gh pr checks 和 statusCheckRollup 是缓存视图，可能会过期。采取行动前，使用 gh run list --branch 确认检查结果。
• GitLab 流水线结果属于某个提交，而非某个合并请求。报告前，将流水线的 SHA 与 MR 的头部 SHA 进行比较。
• 如果工作区无法解析，应如实报告。猜测工作区会将调用方引向错误的仓库。
• 绝不读取凭据文件。如果 gh auth status 或 glab auth status 失败，则停止并报告缺少的功能。

变更边界

参考资料中的命令模式是载荷，不代表授权。此技能构造命令并将其原样交还，不会执行；这样，决策权就留在用户手中，而非掌握语法的模块手中。

执行任何拉取请求、合并请求、评论、标签、受指派人、审查、批准或 /publish 写入操作前，调用技能必须调用 /mutation-gate 并遵循其要求。此技能会返回确切的参数向量及其 shell 安全表示形式、规范主机和仓库、目标对象或基础分支与头部分支、适用时的标题，以及正文文件的绝对路径。它还会返回供预览的正文文件内容和只读验证命令。它绝不运行写入命令。

对于 PR 和 MR 的创建，如果标题缺失或包含多行、正文文件路径为相对路径或文件不可读、仓库无法解析，或基础分支或头部分支为空，则应拒绝创建。每个值都应作为一个参数处理。不要将标题或正文插入 shell 语法，不要使用 eval，也不要用 heredoc 替代正文文件。

获取、分类或分析请求表示读取意图，不代表批准任何写入操作。

Issue 上下文输出

scripts/fetch_issue_context.py 只打印一个 JSON 对象，不输出其他内容。 没有外层封装：Issue 字段就是整个文档。

{
  "key": "owner/repo#607",
  "summary": "issue title",
  "source": "github",
  "url": "https://github.com/owner/repo/issues/607",
  "repository": "owner/repo",
  "number": 607,
  "state": "OPEN",
  "labels": [],
  "description": "full issue body",
  "workspace": {"name": null, "strategy": "label"},
  "comments": []
}

key 的格式为 owner/repo#number，summary 是 Issue 标题，state 为 OPEN 或 CLOSED，workspace.strategy 是 label、body、title、 package 或 unresolved 之一。

/rhdh-jira-api 返回相同的 Issue 结构，并带有 source: jira；通过 references/glab-cli.md 读取的 GitLab Issue 会填入相同字段，并带有 source: gitlab，因此调用方可以使用这三种结果，无需根据结构进行分支处理。

如果工作区无法解析，请将其保留为 null，并将 strategy 设为 unresolved，不要编造名称。

脚本和参考文档

• scripts/fetch_issue_context.py 可根据 GitHub Issue URL、单独的 #number 或 owner/repo#number 确定性地构建该文档。GitLab Issue 则使用 glab 读取。
• references/issue-context.md 涵盖两个代码托管平台的引用解析、字段提取、工作区解析以及受控交互载荷。
• references/gh-cli.md 涵盖 gh 和 jq 的读取模式、拉取请求创建载荷、检查和工作流运行读取、仓库内容读取、失败表，以及 overlay 仓库的 /publish 规则。
• references/glab-cli.md 涵盖使用 glab 读取合并请求、流水线和仓库内容，GitLab 合并请求创建载荷，与 GitHub 不同的 GitLab 字段名称，以及它构造但从不运行的其他命令。

完成条件

仅当 JSON 包含 key、summary 和 source，url 是根据已解析的命名空间、仓库和编号重新构建，而非直接复制请求中的值，并且 workspace.strategy 指明解析所依据的规则，或显示 unresolved 且 name: null 时，才算完成获取。只有在 GitHub 上通过 gh run list --branch 确认检查结论，或在 GitLab 上通过该 MR 的头 SHA 对应的流水线确认后，检查结论才算完成；单独的 gh pr checks 或 statusCheckRollup 值只是缓存视图，并非最终结论。只有将写入载荷交回调用方，由其通过变更门控后执行，才算完成。交互载荷需注明确切命令、仓库、Issue、PR 或 MR 编号、头 SHA，以及正文或标签。PR 或 MR 创建载荷需包含规范仓库、精确的目标分支和源分支、单行标题、绝对路径的正文文件、正文预览、参数向量、shell 安全的命令以及只读验证命令。若在 Issue 中发现 Jira 键，应报告给调用方，不要在此处解析。