filing-bug-reports

提交 Bug 报告

生成一份独立的 Markdown Bug 报告文件，为接手的开发者提供复现问题所需的一切信息，但不指定根本原因或解决方案。

适用场景

• 用户要求提交、撰写或记录 Bug
• 用户想将缺陷交由另一位开发者调查
• 用户想记录可复现的异常行为

不适用场景

• 用户想立即自行调试并修复问题——直接帮助他们即可
• 用户想进行设计评审或代码评审——改用 code-review 技能

输出约定

• 文件： issues/BUG-<NNN>-<slug>.md（使用下一个可用编号，以及根据标题生成的 kebab-case slug）
• 如果 issues/ 目录不存在，则创建该目录
• 每个文件仅记录一个 Bug——绝不合并多个 Bug

工作流程

1. 根据对话上下文还原情况。 你在 Bug 发生时就在场——利用对话历史提取以下信息：

   • 用户当时在做什么（操作和意图）
   • 实际发生了什么（错误消息、工具输出、异常行为）
   • 预期发生什么（根据用户目标推断——例如，用户要求读取模型却收到错误，则预期行为是成功读取）

2. 通过程序收集环境详情。 不要询问你可以自行查到的信息：

   • Agent 工作区根目录、操作系统、架构：从系统上下文获取

   技能状态术语。 技能规范采用渐进式披露：元数据（名称和描述）始终处于上下文中；只有在触发时才会加载正文。这些术语描述的是可观察到的状态，与 Agent 无关——适用于任何实现了 Agent Skills 标准的宿主，而不仅限于 Claude Code：

   • 已注册——本次会话中，该技能显示在宿主 Agent 的可用技能列表中。

   • 已描述——已注册，且元数据中包含非空的 description。（默认状态，不带标记。）

   • 仅名称（⊘）——已注册，但 Agent 的注册条目中没有 description 字段。记录哪些技能仅有名称，然后到此为止。不要读取磁盘上的 SKILL.md 文件来确认是否存在描述——可用技能列表是 Bug 报告唯一记录的状态。读取源文件的 frontmatter 属于原因调查，不在此任务范围内。

     注意：有些宿主 Agent 会在技能文本总量超过内部预算时自动从列表中移除描述——例如，Claude Code 会根据上下文窗口大小分配字符预算，超出预算时优先移除最近较少调用的技能描述。因此，在加载了许多技能的会话中，仅有名称通常是宿主的预期行为，并非 SATK 缺陷。记录此状态，但除非同一技能在预算显然未耗尽的会话中仍仅有名称（技能数量较少，或宿主报告未发生截断），否则不要将 Bug 报告表述为“SATK 技能注册已损坏”。

   • 已调用（▶）——本次会话中，技能正文已读入 Agent 的上下文。

   • 未注册的 SATK 技能（✗）——SKILL.md 存在于工具包的 skills-catalog/ 目录下，但未出现在可用技能列表中。✗ 仅适用于 SATK——我们不跟踪来自其他来源的未注册技能。 根据这些定义：

   • Skills（堆栈视图）：直接读取可用技能列表（不要读取之前的错误报告或文档），并根据术语表标记每个已注册技能。对于 ✗，还要查阅工具包根目录中的 SATK 技能清单，并列出其中声明但不在已注册集合中的 SATK 技能。按照 assets/bug-report-template.md 的 Skills 小节格式呈现。

   • 技能冲突分析：仅考虑正文已在上下文中的 SATK model-based-design-core 技能，并且仅当你在执行工作时注意到这些技能之间存在可能与此错误相关的冲突时才考虑。不要重新阅读技能正文来寻找冲突；如果没有自然发现任何冲突，请写 N/A — <原因>。

   • 可用的 MCP 工具：列出你可以使用的 MCP 工具

   • 相关源文件：读取故障涉及的文件

   SATK 专属（当 Simulink MCP 工具可用时）：

   • SATK 版本：读取 SATK 根目录中的 VERSION 文件。如果该文件不存在但存在 .git/ 文件夹，则读取最新提交哈希并注明“开发版本（）”。如果两者都不存在，请询问用户使用的是哪个版本的 Simulink Agentic Toolkit
   • MATLAB：evaluate_matlab_code → disp(version); ver('simulink'); disp(pwd); disp(computer('arch'))
   • SATK 工具箱状态：evaluate_matlab_code → which('model_read')（为空 = 未安装工具箱）
   • Connector：evaluate_matlab_code → try; disp(connector.securePort); catch; disp('not running'); end
   • MCP 配置：读取 .vscode/mcp.json，了解服务器模式和二进制文件路径
   • 如果这是布局问题且 SATK 状态正常：evaluate_matlab_code → layout.LayoutStateManager.instance().getAnonymizedLayoutSnapshotsPath()，但请先询问用户是否同意分享匿名化布局信息。如果获得用户许可，不要读取 getAnonymizedLayoutSnapshotsPath 返回路径中的文件内容，而应使用工具调用将这个非常大的文件直接附加到最终错误报告中。

3. 重现错误。 重新运行失败的操作，确认问题可以重现并捕获确切输出。如果重试成功，请注明问题是间歇性出现的，并尝试确定差异所在。

4. 精简至最小复现。 移除所有并非触发错误所必需的步骤、文件和变量。目标是找到仍能触发错误的最小输入。

5. 仅询问用户你无法确定的信息：

   • 预期行为——仅当输出看起来合理但用户表示有误时询问（你无法知道什么才是“正确”的结果）
   • 严重程度／业务影响——仅当情况不明确时询问（直接崩溃显然属于严重问题；格式细节显然属于轻微问题）
   • 本次会话之外的上下文——如果用户提及了你未亲历的内容

6. 撰写报告，使用 assets/bug-report-template.md 中的模板。填写所有必填部分。不适用的可选部分标记为 N/A。

7. 保存前检查。 确认：

   • 不熟悉项目的开发者无需提问即可理解操作步骤
   • 未指定根本原因或修复方案（观察结果和假设仅写在 Notes 部分）
   • 错误消息和日志为精确副本，不得转述
   • 标题遵循以下格式：[Area] — Action — Unexpected result

防护要求

• 始终： 从干净／已知状态开始，提供准确的复现步骤
• 始终： 原样包含错误消息和日志输出（不得转述）
• 始终： 指明环境（版本、操作系统、平台）
• 绝不： 陈述根本原因——这是调查人员的工作
• 绝不： 在报告正文中提出修复方案（假设仅写在 Notes 中，并明确标记为推测）
• 绝不： 包含机密、令牌、密码或个人身份信息——使用 <REDACTED> 遮盖

参考资料

• assets/bug-report-template.md — 输出模板（始终使用此结构）

---

版权所有 2026 The MathWorks, Inc.

---