/ce-report-bug

面向用户的技能文档 docs/skills/ce-report-bug.zh-CN.md

ce-report-bug

报告复合工程插件中的错误 - 收集结构化信息并在 EveryInc/compound-engineering-plugin 创建 GitHub 问题。

ce-report-bug 是 bug-filing 技能。它引导用户解决六个结构化问题（类别、组件、发生了什么、预期行为、重现步骤、错误消息），自动收集环境信息（操作系统、插件版本、代理 CLI 版本）、格式化完整的错误报告，并通过 gh 创建 GitHub 问题。这项技能可以让您快速提交有用的错误报告——另一种方法是打开 GitHub，找到正确的存储库，记住要包含的内容，然后从头开始输入。

仅 Beta 风格的显式调用 (disable-model-invocation: true)。

TL;DR

问题 回答
它有什么作用？ 通过 6 个问题收集结构化错误信息，自动收集环境数据，在 EveryInc/compound-engineering-plugin 提交 GitHub 问题
何时使用它 当复合工程插件中的某些内容不起作用并且您想要报告它时
它生产什么 GitHub 问题 URL（或者如果 gh 不可用，您可以手动提交格式化的错误报告）
隐私 不收集个人信息、API 密钥、凭据或私人代码

＃＃ 问题

提交有用的错误报告会遇到很大的麻烦：

  • 找到正确的存储库 - 哪个组织、哪个存储库、哪个标签？
  • 记住要包含的内容 - 环境信息、重现步骤、错误消息、预期行为与实际行为 - 很容易错过维护者需要的东西
  • 手动环境收集 — 运行 uname，查找插件版本，检查 CLI 版本，全部格式化
  • 没有模板 - 每个错误报告都从头开始；有些很好，有些则“坏了”
  • 不使用 gh 进行归档 — 如果没有 CLI，用户必须通过 GitHub UI 手动复制粘贴
  • 隐私问题 - 天真的环境收集风险，包括泄露太多信息的 API 密钥或路径

解决方案

ce-report-bug 将报告作为结构化摄入 → 格式 → 文件流运行：

  • 6 个问题 按结构化顺序排列 — 类别、组件、实际、预期、重现步骤、错误消息
  • 自动环境收集 — 操作系统通过 uname -a，插件版本通过清单读取，代理 CLI 版本通过 --version
  • 基于模板的格式 - 每个报告都具有相同的形状，因此维护人员可以快速扫描
  • gh issue create 具有正确的存储库、标题前缀和标签（或没有标签的后备）
  • 当 gh 不可用时，手动回退 — 显示格式化报告，供用户手动归档
  • 隐私设计 — 仅提供技术信息；绝不是个人信息、凭证或代码

是什么让它如此新颖

1. 六个按故意顺序排列的结构化问题

技能要求：

  1. Bug类别（多选）——代理/命令/技能/MCP服务器/安装/其他
  2. 特定组件（自由文本）- 代理、命令、技能或 MCP 服务器的名称
  3. 发生了什么（实际行为） — 清楚描述用户观察到的情况
  4. 应该发生什么（预期行为） — 清晰描述预期行为
  5. 重现步骤 — 用户在错误发生之前做了什么
  6. 错误消息 — 任何错误输出

The order matters: category and component first scope the bug; actual vs expected establishes the disconnect; repro steps + errors give the maintainer the diagnostic foothold.

2.自动环境采集

技能运行：

  • uname -a 用于操作系统信息
  • 从特定于平台的位置读取插件清单（Claude Code：~/.claude/plugins/installed_plugins.json；Codex：.codex/plugins/；等等）
  • 运行平台的 CLI 版本命令（claude --version、codex --version 等）

如果其中任何一个失败，该技能会注明“未知”并继续 - 不要阻止有关环境收集问题的报告。

3.单一模板，形状一致

每个报告都使用相同的模板：

``降价

错误描述

组件： [类型] - [名称] 总结： [简述]

环境

  • 插件版本： ...
  • 代理平台： ...
  • 代理版本： ...
  • 操作系统： ...

＃＃ 发生了什么 ...

预期行为

...

重现步骤

1....

错误信息

...

附加上下文

...

通过/ce-report-bug技能报告


页脚将报告标记为技能生成，以便维护人员知道它遵循规范模板。

### 4. `gh issue create` 具有正确的范围

技能文件通过：

```bash
gh issue create \
  --repo EveryInc/compound-engineering-plugin \
  --title "[compound-engineering] Bug: [description]" \
  --body "[formatted report]" \
  --label "bug,compound-engineering"
```

正确的存储库、正确的标题前缀、正确的标签。如果标签不存在（某些分叉/克隆可能缺少标签），则技能会在没有 `--label` 的情况下重试，而不是失败。

### 5. `gh` 不可用时手动回退

如果未安装或验证 `gh`，该技能会向用户显示完整格式的报告，以便他们可以手动将其粘贴到 GitHub Web UI 中。没有任何摩擦——报告工作已经完成。

### 6. 隐私设计

该技能明确**不**收集：

- 个人信息
- API 密钥或凭证
- 项目的私有代码
- 超出 `uname` 的基本操作系统信息的文件路径

仅包含有关错误的技术信息。这已记录在技能中，以便用户知道共享的内容。

### 7. 仅显式调用

`disable-model-invocation: true` 防止该技能在散文提及错误时自动触发。错误报告是用户有意选择的——直接调用 `/ce-report-bug`。

---

## 简单示例

You hit a bug where `/ce-plan` produces a plan with U-IDs that aren't sequential. You invoke `/ce-report-bug`.

该技能会解决 6 个问题：

1. **类别**：技能不起作用
2. **组件**：ce-plan
3. **发生了什么**：“计划是使用 U-ID U1、U2、U4 生成的 - U3 被跳过，没有任何解释。”
4. **预期**：“U-ID 在初始生成时应该是连续的，没有间隙。”
5. **重现**：“从具有 4 个实施单元的头脑风暴文档中运行 `/ce-plan`。第三个单元的编号为 U4，而不是 U3。”
6. **错误消息**：“没有可见的；只是编号错误。”

环境收集在后台运行：
- `uname -a`：macOS arm64
- 插件版本：3.4.1
- 代理平台：克劳德码
- 代理版本：claude-code 1.2.3

格式化报告转到 `gh issue create --repo EveryInc/compound-engineering-plugin --title "[compound-engineering] Bug: U-ID numbering skips U3 in initial plan generation" --body "..." --label "bug,compound-engineering"`。

返回：

````文本
错误报告提交成功！

问题：https://github.com/EveryInc/compound-engineering-plugin/issues/812
标题：[复合工程] Bug：U-ID 编号在初始计划生成中跳过 U3

感谢您帮助改进复合工程插件！
维护人员将审核您的报告并尽快回复。

何时去实现它

在以下情况下使用 ce-report-bug：

  • 复合工程中的技能、命令、代理或 MCP 集成无法按预期工作
  • 您想要报告维护者可以采取行动而无需后续问题的内容
  • 您不确定要包括哪些细节 - 结构化问题抓住了需要的内容

在以下情况下跳过 ce-report-bug：

  • 该错误位于不同的插件或工具中（此归档目标被硬编码为复合工程）
  • 这是功能请求，而不是错误 → 手动提交讨论或功能请求问题
  • 您不确定这是错误还是预期的 - 首先检查 /ce-release-notes 以查看最近版本中的行为是否发生变化

用作工作流程的一部分

ce-report-bug 是一个独立的实用程序 - 不位于链内。当出现问题并且用户希望维护者知道时会调用它。

常见的同伴技能：

  • /ce-update — 首先检查版本；您可能报告的错误已在新版本中修复
  • /ce-release-notes — 检查最近行为是否发生变化；可能是故意的

使用独立版

直接调用：

  • /ce-report-bug — 演练 6 个问题
  • /ce-report-bug "brief description" — 使用描述作为初始上下文；仍然会遍历结构化问题以确保完整性

技能驱动摄入量。没有跳过问题的选项——结构化的摄入就是价值；如果一行报告太过分了，请直接通过 GitHub UI 进行归档。

＃＃ 参考

步骤 行动
1 收集错误信息（6 个结构化问题）
2 收集环境信息（操作系统、插件版本、代理 CLI 版本）
3 格式化错误报告（一致模板）
4 通过 gh 创建 GitHub 问题（带标签；后备不带标签）
5 确认提交并显示问题URL

回购目标：EveryInc/compound-engineering-plugin。标题前缀：[compound-engineering]。标签：bug,compound-engineering（如果丢失，则回退到无标签）。

＃＃ 常问问题

该技能收集了有关我的环境的哪些信息？ 仅技术信息：来自 uname -a 的操作系统字符串、清单中的插件版本、代理平台名称、代理 CLI 版本。没有个人信息、没有 API 密钥、没有凭据、没有私人代码。该报告的 Environment 部分准确显示了其中包含的内容。

如果未安装 gh 会怎样？ 该技能会显示完整格式的错误报告，并要求您通过 GitHub Web UI 手动归档。没有信息丢失——结构化的摄入和格式化仍然发生。

我可以报告非复合工程错误吗？ 该技能专门记录在 EveryInc/compound-engineering-plugin 中。对于其他插件或工具，请直接在各自的存储库中归档。该技能的结构是可通用的，但存储库目标是硬编码的。

如果仓库中不存在标签怎么办？ 该技能会在没有 --label 的情况下重试。某些分叉或克隆可能没有设置 bug 标签；如果没有它，报告仍然可以成功归档。

我可以在提交报告之前对其进行编辑吗？ 该技能以交互方式逐步解决问题，因此您可以在继续之前完善每个答案。报告格式化后，技能文件将直接通过 gh 生成。如果您想要手动审核，请拒绝 gh 并自行通过 Web UI 使用格式化文本进行归档。

如果我将同一个错误提交两次可以吗？ 该技能不会删除重复数据 - 它会归档您所要求的内容。如果您担心重复，请先搜索问题跟踪器。维护者可以根据需要关闭重复项。

另请参阅

  • /ce-update — 检查插件版本；旧版本可能已修复错误
  • /ce-release-notes — 检查最近版本中的行为是否发生变化；可能不是一个错误

← 返回技能概览