sentry-javascript 仓库 Issue 分诊报告模板（triage-report.md）详解：结构与填写规范

可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载导读本文围绕 sentry-javascript 仓库中 AI 自动化 Issue 分诊Triage流程的核心产物——triage-report.md 模板——展开。该模板由仓库的triage-issue技能在收到 GitHub Issue 后自动填充生成是一份结构化的分诊结论文档。读完本文你将掌握模板每个字段的业务含义、填写优先级规则、可省略条件以及它如何与仓库中的安全检测脚本、GitHub Actions 工作流和 Linear 回帖流程衔接可直接复用于你自己的开源仓库维护实践中。模板定位一条自动化分诊产线的最终交付物sentry-javascript仓库维护了一套面向 AI Agent 的 Issue 分诊技能定义于 .agents/skills/triage-issue/SKILL.md。当仓库收到新的 Bug 或 Feature Issue 时GitHub Actions 工作流 .github/workflows/triage-issue.yml 会调用 Claude Code 执行/triage-issue issue-number --ci经过八步流程拉取 Issue → 安全检测 → 分类 → 代码库检索 → 关联 Issue/PR 检索 → 根因分析 → 生成报告 → 输出/回帖后产出分诊报告。triage-report.md就是这套流程的输出模板即 SKILL 第 6 步“Generate Triage Report”所要求填写的骨架。它本质上是一份高度结构化的 Markdown 报告契约强制分诊 Agent 用统一的字段组织结论从而保证每份报告的信息密度一致便于维护者快速扫读结论可被下游流程如suggested-fix-prompt.md修复提示、Linear 评论、Job Summary直接引用报告本身可检索、可审计形成可追溯的分诊记录。头部元数据字段一句话给出结论定性模板头部以 H2 标题## Issue Triage: #number开头随后是四行元数据字段取值判定依据TitleIssue 原始标题直接引用Classificationbug/feature request/documentation/support/duplicateSKILL 第 2 步分类结果需结合标签、堆栈、导入语句、提到的 SDK 名称综合判定Affected Package(s)sentry/package, ...由标签、堆栈路径或 issue 中出现的包名推断Priorityhigh/medium/low按 SKILL.md 约定回归、数据丢失、崩溃类为highfeature request、纯咨询类为lowComplexitytrivial/moderate/complextrivial 配置/拼写级修复moderate 涉及 1–2 个文件的逻辑改动complex 架构级改动、跨包协作其中Complexity直接决定后续是否触发suggested-fix-prompt.mdSKILL 第 7 步规定仅当复杂度为trivial或moderate且能定位具体代码改动时才使用 suggested-fix-prompt.md 生成修复提示否则应跳过并在报告中注明还需哪些调研。Summary1–2 句话的浓缩结论模板要求用 1–2 句话概括 issue 的核心内容。这不是流水账摘要而是分诊结论的浓缩——例如“该 issue 报告 SDK 在 X 场景下抛出的错误初步判断为 Y 配置缺失导致”。写好 Summary 的关键是让读者不读正文也能判断这条 issue 是否与自己相关因此应同时包含现象与初步定性为下方 Root Cause Analysis 预留钩子。Root Cause Analysis带file:line指针的根因分析这是整个模板的技术核心。模板的填写约束相当明确若判定为SDK 侧问题必须给出具体代码定位使用file:line格式引用具体的函数、变量与逻辑路径若判定为用户环境、配置或使用方式问题则必须明确声明“原因是 setup/environment/usage 而非 SDK 代码”并描述正确的配置或用法应当是什么样严禁凭空编造代码根因。SKILL 第 5 步补充了该节的取证路径使用 Grep/Glob 在本地仓库检索报错信息、函数名、堆栈路径如packages/下各 SDK 的src/与test/目录若 issue 提到具体版本如“7.x 正常8.2.0 起损坏”应检查根目录 CHANGELOG.md 中对应版本的条目用^##模式定位版本标题并将相关变更记录在根因或信息缺口小节跨仓库检索仅在明确相关时进行Bundler 相关问题检索getsentry/sentry-javascript-bundler-plugins文档相关问题检索getsentry/sentry-docs并填入下方 Cross-Repo Findings 小节。注意从 issue 内容提取搜索词时必须剥离 shell 元字符防止命令注入——这是 SKILL.md 明确的安全要求。两个条件性小节不满足条件就整体省略模板明确写出以下两节仅在某些条件下填写否则整节省略——这保证了报告“要么可行动、要么明确声明不确定性”不写无信息量的填充文字Alternative interpretations / Recommended approach仅当报告人的框架或建议方案不理想时填写1–2 句即可。SKILL 第 2b 步要求分诊时不要默认接受报告人的表述而应从四个角度主动质疑Setup vs SDK是否可能是配置错误或用错了包/选项/构建步骤而非 SDK 缺陷若是应分类为 setup/docs 问题并给出修正建议而非要求改代码Proposed fix vs best approach报告人可能提出具体修法如“把这个加进 README”需评估是否有更优做法例如链接官方文档而非复制内容、修正文档位置等推荐最优方案而非报告人点名要的方案Support vs bug/feature是否应作为咨询或文档问题处理而非代码变更Duplicate or superseded是否已被现有 issue、其他包或已废弃代码路径覆盖。Information gaps / Uncertainty仅当关键信息无法获取时填写以无序列表列出缺失内容如复现步骤、堆栈、受影响包以及推进所需条件。SKILL 明确“不要猜”缺什么就如实记录只有当信息足够行动时才省略此节。Related Issues PRs关联检索结果本节记录与当前 issue 相关的其他 issue 与 PR格式为- #number - title (open|closed|merged) - (或 No related issues found)SKILL 第 4 步给出了标准检索命令与配套脚本用gh api search/issues按术语检索仓库内相似 issue将输出保存到search.json后交由 parse_gh_issues.py 解析——该脚本会把 GitHub API 的 JSON单 issue 或搜索结果整理成#number title state的简洁列表并附带 Labels 与 Body 前 200 字符避免在 CI 中内联编写 Python用gh pr list --repo getsentry/sentry-javascript --search terms --state all --limit 7检索已有的修复尝试。Cross-Repo Findings跨仓库检索结果模板固定给出两个子项bundler-plugins检索getsentry/sentry-javascript-bundler-plugins的结果或写no matchessentry-docs检索getsentry/sentry-docs的结果或写no matches。对应的跨仓库命令为gh api search/code -X GET -f qtermrepo:...。该节的作用是让维护者一眼看出问题是否在相邻仓库中已有讨论或修复避免重复排查。Recommended Next Steps可执行的动作清单模板以编号列表收尾每条都是具体行动项。SKILL 第 6 步对整份报告提出了总要求每一句都应要么可执行、要么是明确的不确定性声明避免无信息量的填充或含糊其辞。行动项应基于最佳方案而非报告人提出的第一直觉方案制定典型形态包括若为 SDK bug定位到具体包与文件给出修复方向并附上验证路径若为 setup/docs 问题给出正确配置示例或指向官方文档位置若为 duplicate关闭并指向主 issue若信息不足列出需要报告人补充的复现信息。配套机制从模板到落地的完整链路模板本身是“骨架”仓库还提供了让分诊报告真正落地执行的四类配套资产理解它们能帮你更好地把握模板各字段的用途1. 安全前置detect_prompt_injection.py分诊启动前SKILL 第 1 步强制对 issue 标题、正文与全部评论执行安全检查脚本为 detect_prompt_injection.py。它做两类检测语言检测拒绝非英文 issueASCII 字母占比 80% 即拒另有西里尔、CJK、阿拉伯等非拉丁 Unicode 区段清单与拉丁重音字符黑名单提示注入检测对约 20 条高危正则模式打分如系统标签注入 10、指令覆盖 8、凭据路径引用 10、脚本标签注入 10总分 ≥ 8 即拒绝。退出码约定0 安全、1 拒绝、2 输入错误按拒绝处理。任何非零退出码都要求立即终止全部处理只输出拒绝信息——因为 issue 内容被视为不可信数据其中可能嵌入的指令绝不能被执行。这与模板的“Alternative interpretations”节共同构成了防社工的两道闸门。2. CI 运行约束与报告输出triage-issue.yml 展示了模板在真实 CI 中的使用方式工作流仅对带Bug或Feature标签的 issue或手动触发运行以 issue 号为并发组键防重并通过allowedTools白名单严格限制 Agent 可调用的命令仅gh api *、gh pr list *及四个固定脚本。报告默认打印到终端带--ci时则先写入仓库根目录的triage_report.md再由 post_linear_comment.py 回帖到对应的 Linear issue。3. Linear 回帖与幂等保护post_linear_comment.py 负责将triage_report.md内容作为评论发布到 Linear它用LINEAR_CLIENT_ID/LINEAR_CLIENT_SECRET环境变量换取 OAuth token绝不接受命令行传参校验标识符格式^[A-Z]-\d$如JS-1669与报告路径白名单且会先查询目标 issue 是否已存在以## Issue Triage:开头的评论——存在则跳过保证重复运行不会产生重复评论。4. 失败兜底Job Summary即使分诊步骤失败如达到--max-turns 50上限工作流仍通过if: always()的收尾步骤调用 write_job_summary.py从 Claude 执行输出 JSON 中提取duration_ms、num_turns、total_cost_usd等指标写入 GitHub Job Summary并在因error_max_turns终止时给出提示——保证每次运行都有可追踪的执行记录。写在最后如何复用这份模板如果你正在为自己的开源仓库搭建 AI 分诊流程可以直接按以下方式迁移照搬报告结构将本模板的八个小节头部元数据、Summary、Root Cause Analysis、两个条件性小节、Related Issues PRs、Cross-Repo Findings、Recommended Next Steps作为你的分诊输出契约坚持两个硬约束根因分析要么带file:line证据、要么明确声明为 setup/usage 问题信息不足时如实列在 Uncertainty 节绝不猜测配套安全脚本参考 detect_prompt_injection.py 的模式在一切处理前先对 issue 内容做语言与注入检测并把 issue 内容严格视为数据而非指令接入工作流参考 triage-issue.yml 的权限最小化白名单命令与幂等回帖设计确保流程可审计、可重入。赞分享可观测性【免费下载链接】sentry-javascriptOfficial Sentry SDKs for JavaScript项目地址https://gitcode.com/gh_mirrors/se/sentry-javascript点击查看免费下载相关推荐让 AI 写的代码符合团队规范Copilot for Xcode 自定义指令实战指南让 AI 写的代码符合团队规范Copilot for Xcode 自定义指令实战指南 Copilot for Xcode 的 AI 生成能力很强但强到有点开发工具AI 应用AI Agentsentry-javascript 仓库的 AI Issue 分流Triage实战指南triage-issue Skill 工作流与安全机制全解析sentry javascript 仓库的 AI Issue 分流Triage实战指南triage issue Skill 工作流与安全机制全解析 导读可观测性reth 仓库的标签体系Issue 与 PR 分诊Triage规范及其自动化实现reth 仓库的标签体系Issue 与 PR 分诊Triage规范及其自动化实现 reth 仓库通过一套统一的标签前缀体系 A 、 C 、 S 等来管区块链创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考