infrahub-reporting-issues

Infrahub 问题报告

概述

帮助用户在 GitHub 上向正确的 Infrahub 生态系统仓库提交错误报告或功能请求。此技能不会自动提交，而是准备一份完整且经过清理的问题报告，并在用户审核关口处停止。只有用户明确批准内容和提交方式后，才会提交。

该生态系统有 11 个候选仓库。大多数用户不知道哪个仓库负责处理自己的问题。此技能的任务是根据本地仓库上下文做出有把握的判断，与用户确认，搜索重复问题，并生成符合目标仓库提交表单要求的草稿。

何时使用

当用户表达类似以下意图时，触发此技能：

• “我觉得我在 Infrahub 中发现了一个错误”
• “如何报告这个问题？”
• “我想请求一项功能”
• “我应该在哪里提交这个问题？”
• “这个功能不起作用——我想开一张工单”

如果用户只是在本地调试，并未表示要提交问题，请勿触发。提交问题这一操作，正是此技能与常规故障排查的区别。

如果问题出在 Infrahub 技能自身的指南上（某条规则有误、缺失或令人困惑），而非 Infrahub 产品本身，请勿直接触发。此类问题应交由 infrahub-reporting-skill-gaps 处理；该技能会检查跟踪系统中是否已有报告，并在将内容交给此技能前判断这是错误还是功能请求。

技能缺陷受理

infrahub-reporting-skill-gaps 也可以直接调用此技能，并传入准备好的内容： {type, title, body, searched, issue?}。对于该调用方，type 为 bug、feature 或 docs gap，类型已由该技能的两级分类确定。

此内容不包含 repo，由你负责路由。 调用方有意不指定目标仓库，因此只有此表列出了映射关系：

type	仓库
bug	opsmill/infrahub-skills
feature	opsmill/infrahub-skills
docs gap	opsmill/infrahub

错误或功能请求涉及规则文件，该文件位于技能仓库中。文档缺陷则涉及 Infrahub 自身的文档，该文档位于主仓库中，技能维护者无权编写。请在第 4 步之前根据此表确定仓库，然后继续执行，视同第 3 步已完成。

对于文档缺陷，标题使用 bug(docs):，不带 [skill] 部分，因为来源技能与 opsmill/infrahub 的维护者无关；该仓库自身的标题说明以及与之配套的 bug:/feat: 约定，请参阅 reference.md。

searched 指明调用方在自己的第 2 步中已搜索过的仓库，issue 为可选项。如果存在 issue，说明调用方已匹配到现有问题：将其视为目标问题，将 body 作为评论呈现，并在第 8 步使用 gh issue comment 发布，而非使用 gh issue create。

第 4 步取决于 searched。 如果 searched 与你刚确定的仓库相同，则跳过该步骤：调用方已执行过完全相同的搜索，重复搜索可能得到与已写入 body 的答案相矛盾的结果。如果两者不同，则照常执行；这适用于文档缺陷的情况：调用方会先搜索 opsmill/infrahub-skills，之后才确定问题类型，但文档缺陷会路由至 opsmill/infrahub，因此还没有人检查过该跟踪系统。

通过此方式调用时，分类（第 2 步）已确定，请跳过。第 3 步的检测逻辑也不适用；上述表格已取代该逻辑，且无需向用户确认，因为问题类型已根据会话中的证据确定。也跳过环境信息收集（第 5 步）；该步骤收集 Infrahub 服务、SDK 和操作系统版本，这些信息既不适用于有关技能自身指南的报告，也不适用于缺失文档的报告。在第 6 步中，使用调用方提供的标题和正文进行呈现，而非使用通用模板。之后照常继续执行第 7 至第 9 步：审核关口、提交方式、确认。

工作流

按顺序执行以下步骤。每当遇到用户确认步骤时都要停下——未经明确确认，绝不继续。

1. 了解问题

如果用户还没有描述问题，请让他们用自己的话说明。暂时不要追问——只需倾听。记录他们提到的任何产品名称、版本号、错误消息或工作流背景；这些信息会用于后续的每一步。

2. 分类

判断这是一个错误、功能请求还是问题／使用帮助。只有在分类不明确时，才追问 1～2 个问题：

• “这个功能之前能用，但现在不能用了，还是说它从未存在过？”
• “你能提供复现步骤吗，还是这只是偶尔观察到的现象？”
• “是否有任何地方记录了预期行为，还是你在请求新增功能？”

如果用户描述了他们已经在使用的变通方法，倾向于归类为“功能请求”（错误已有变通方法 → 真正的问题是缺少易用性）。如果用户描述的是崩溃、错误输出或 500 级错误，倾向于归类为“错误”。如果用户是在询问如何执行某项操作，请引导他们前往 Discord／讨论区，而不是提交问题——不要为支持咨询创建问题。

3. 确定仓库

阅读 reference.md，了解完整的 11 个仓库注册表、检测线索和模板可用情况。按以下顺序应用检测逻辑：

1. 检查本地工作目录中的文件系统线索（infrahub.toml、pyproject.toml 依赖项、galaxy.yml、.claude-plugin/plugin.json 等）
2. 将检测到的线索与用户所述交叉核对。即使仓库中没有任何 Ansible 线索，如果用户反馈的是 Ansible playbook 问题，它仍然是 Ansible 问题。
3. 选择最具体匹配的仓库。

默认选择主仓库规则：如果检测结果不明确、多个仓库同样匹配、用户表示不确定是哪个组件导致问题，或者症状可能出现在平台层，默认选择 opsmill/infrahub。主仓库比子仓库更容易将收到的问题重新分派到子仓库。选主仓库的代价低于选错专用仓库的代价。

向用户说明你的判断，并用一句话解释理由，然后请他们确认或纠正。例如：

“根据你在 pyproject.toml 中的 infrahub-sdk，以及错误消息中提到的 InfrahubClient，这看起来是一个 opsmill/infrahub-sdk-python 问题。请确认？”

4. 搜索重复问题

始终搜索错误和功能请求。使用第一个可用的方法：

1. gh CLI — gh search issues --repo <owner/repo> "<keywords>"。从用户的描述和任何错误消息中提取关键词。如果第一次搜索没有结果，再用同义词搜索一次。
2. MCP GitHub 服务 — 如果未安装 gh，则使用用户环境中可用的任意 GitHub MCP 工具。
3. 手动搜索 — 如果两种方法都不可用，向用户提供 GitHub 搜索 URL，并请他们自行检查。

向用户展示最相关的 3～5 条结果，包括标题、状态（开放／已关闭）和一句话摘录。询问：

“这些问题中有涵盖你的问题的吗？如果有，我们会添加评论，而不是新建问题。”

如果找到匹配项，切换到评论模式，并选择以下两种方式之一。向用户说明选择了哪一种：

1. 补充信息：此次情况提供了现有问题中没有的信息，例如不同的触发条件、受影响的另一个技能或组件，或新的故障形式。只评论新增信息；不要重复问题中已有的内容。
2. 追加一例：此次情况没有提供任何新信息。发布一条简短评论，记录又出现了一次，以便维护者评估发生频率，不要重复现有描述。

无论哪种方式，都要向用户提供问题 URL。否则，继续起草新问题。

5. 收集环境信息（仅限 bug）

对于功能请求，请跳过此步骤。对于 bug，请仅收集：

• 相关产品版本 — 例如 Infrahub 服务版本、SDK 版本、Ansible collection 版本、插件版本。
• 操作系统 + 架构（例如，macOS 14 arm64、Ubuntu 22.04 x86_64）。
• 如果与该组件相关，提供 Python 或运行时版本。

仅此而已。不要收集文件路径、项目 结构、原样日志、环境转储、docker compose ps 输出，或任何可能泄露内部状态的内容。该 environment-info-sanitization rule 规定了 issue 正文中允许和禁止包含的内容 ——撰写 bug 部分前请先阅读。

版本查询方式：

组件	命令
Infrahub 服务	infrahubctl info（Infrahub Version 行），或查看 compose 文件中的 image: 标签
Python SDK	infrahubctl info（SDK Version 行），或运行 pip show infrahub-sdk
Ansible collection	ansible-galaxy collection list opsmill.infrahub
Nornir 插件	pip show nornir-infrahub
Helm chart	helm list -n <namespace>
infrahub-sync	infrahub-sync --version
infrahub-backup	infrahub-backup --version
MCP 服务	查看 MCP 客户端配置或运行 pip show infrahub-mcp
VS Code 扩展	VS Code 中的扩展面板
Skills 插件	.claude-plugin/plugin.json version 字段

如果无法明确确定版本，请标记为 unknown，而不要猜测或运行范围更广的 探测命令。

6. 整理 issue

如果目标仓库有 .github/ISSUE_TEMPLATE/ 目录，请获取匹配的模板（bug 使用 bug_report.yml ，功能请求使用 feature_request.yml），并 按照其中的表单字段填写。使用：

gh api repos/<owner>/<repo>/contents/.github/ISSUE_TEMPLATE/bug_report.yml --jq '.content' | base64 -d

提供 issue 模板的仓库：

• opsmill/infrahub
• opsmill/infrahub-sdk-python
• opsmill/infrahub-ansible
• opsmill/nornir-infrahub

没有模板的仓库使用此 skill 中的 templates/bug.md 或 templates/feature.md。

标题规范：使用 <area>: <imperative summary> 格式，长度不超过 72 个字符，末尾不加标点。例如：

• SDK: InfrahubClient.create() raises on empty list payload
• Schema: hierarchical generic loses parent on rename
• Docs: clarify human_friendly_id behavior for inherited nodes

7. 用户审核关卡（必需）

向用户展示整理好的 issue。显示：

• 目标仓库和 URL
• 最终标题
• 完整正文（markdown）
• 这是新建 issue，还是对现有 issue 的评论

询问：“内容看起来合适吗？在继续之前，有什么需要添加 或删除的吗？”

不要跳过此步骤。 与用户反复确认内容， 直到用户明确批准。

8. 选择提交方式

内容获批后，询问用户希望如何 提交。新建 issue 和发表评论所用的命令不同；请根据步骤 7 确定的类型选择对应的列：

方式	新建 issue	对现有 issue 发表评论
CLI	gh issue create --repo <owner/repo> --title "..." --body "..."	gh issue comment <number> --repo <owner/repo> --body "..."
MCP GitHub 服务	如果用户有此服务则使用。调用前确认工具名称。	同样使用该服务的评论工具。
手动	输出可直接复制粘贴的 markdown 标题和正文，以及 https://github.com/<owner>/<repo>/issues/new。	输出可直接复制粘贴的 markdown 正文，以及 https://github.com/<owner>/<repo>/issues/<number>。

评论没有标题。如果整理出的内容仍有标题， 则步骤 6 生成的内容有误；请返回上一步，而不是把标题粘贴到评论正文中。

切勿默认选择任何方式——务必先询问。用户选定方式后，执行相应操作。

9. 确认

提交后，向用户提供：

• 问题 URL；如果通过 gh/MCP 提交的是评论，则提供该评论的永久链接
• 一句话概述提交的问题或评论内容
• 提醒用户可以订阅该问题以获取更新

规则类别

前缀	类别	说明
env	环境信息	问题正文中可以和不可以包含的内容

请参阅 rules/_sections.md 中的索引。

参考资料

• reference.md — 包含 11 个仓库的注册表，其中列有检测线索、描述和模板可用性。请在第 3 步阅读。
• templates/bug.md — 适用于没有 .github/ISSUE_TEMPLATE/ 的仓库的通用备用错误模板。
• templates/feature.md — 通用备用功能模板。
• rules/environment-info-sanitization.md — 提交前需要删除哪些信息。这对安全至关重要；每次提交错误报告时都要阅读。
• ../infrahub-common/rules/workflow-information-priority.md -- 优先查看技能内容；确实存在信息缺口时（例如删除节点），再了解如何查阅 docs.infrahub.app

反面模式

• 未经用户明确批准就提交。 第 7 步的用户确认环节不可省略。在公开仓库中突然创建 GitHub 问题，很难撤回。
• 症状不明确时在子仓库中提交。 如果不确定，请在 opsmill/infrahub 中提交，让维护人员重新分派。在错误的子仓库中提交会给所有人增加工作量。
• 提交重复问题。 如果搜索结果中存在匹配项，默认应添加包含新信息的评论，而不是创建新问题。
• 粘贴完整日志或 docker compose 输出。 这会泄露主机名、IP、容器名称，有时还会泄露机密信息。v1 中只需提供版本和操作系统信息。
• 将支持问题作为错误提交。“如何执行 X？”这类问题应发布在 Discord 或 GitHub Discussions 中，而不是 Issues。