当生产环境 Sentry 报错需要真修复时：用…

适用于需要借助 Sentry MCP 发现、分诊和修复生产问题，并通过根因分析而不是关闭或降噪 Sentry issue 来解决错误的场景。

适用场景

解决思路

1. 把 Sentry error 视为信号而不是问题本身；目标不是关闭 Sentry issue，而是发现根因、理解应用哪里出错并修复底层缺陷，关闭 issue 只是正确修复的副作用。
2. 始终问 "Why does this fail?"，而不是 "How do I make Sentry quiet?"；绝不把日志级别更改当作修复。
3. 遇到 fallback path 时视为用户体验降级；追踪主路径为什么失败，并在上游修复。
4. 不要未经调查就批量把 issue 分类为 "expected"；看到 fallback 不代表理解失败，必须追踪完整输入路径。
5. 不要把 "有 fallback" 当成 "不是问题"；追问主路径为什么失败，以及能否在上游预防。
6. 不要把多个 issue 合并到一个 PR；每个 issue 有自己的根因，除非调查证明根因相同，否则单独修复。
7. 不要丢弃错误细节；绝不要从 catch (error) 移除 error 或剥离状态码，这些数据是理解失败的方式。
8. 不要在 triage 阶段决定修复；triage 只能分类为 "Investigate" 或 "Ignore"，调查完成前不知道修复。
9. 降日志级别仅对真正预期状态有效（例如 optional column missing、resource deleted），不适用于有 fallback 的失败。
10. Phase 1：使用 Sentry MCP（先 ToolSearch 加载工具），依次调用 find_organizations → find_projects → search_issues，并传 naturalLanguageQuery: "all unresolved issues sorted by events"。
11. 建立 triage 表格，列包括 ID、Title、Events、Action、Reason，Action 仅能是 Investigate 或 Ignore。
12. 对多个 events、用户体验降级、高容量 warnings、每次运行都复现的 issue，标记 Action=Investigate。
13. 对浏览器扩展代码、ChunkLoadError（会自解决）、单个事件的瞬时问题、已修复的 issue，标记 Action=Ignore。
14. 对 Ignore 的 issue 调用 mcp__sentry__update_issue(..., status: "ignored")；对已修复的调用 status: "resolved"。
15. Phase 2：一次只调查一个 issue，按顺序执行步骤，不要跳过或批量处理 issue。
16. 拉取事件级数据：Issue summaries 会隐藏细节；使用 get_issue_details 和 search_issue_events，并传 naturalLanguageQuery: "all events with extra data"；提取 URLs、params、stack traces、status codes、timestamps。
17. 交叉引用 Axiom：事件有 traceId；运行 axiom query "['shiori-events'] | where traceId == '<traceId>'" -f json 获取周围上下文（authMethod、client_version、request metadata）。
18. 阅读失败代码路径：跟随 stack trace，阅读每个文件，在提出更改前先理解。
19. 上游追踪输入路径（最常被跳过且最重要）：确认什么数据到达失败函数、是否本应到达此路径、是否缺少过滤器、输入是否错误（binary URL、redirect、bad format），以及能否在上游阻止坏输入。
20. 复现：使用 Sentry 中的实际失败输入，用确切数据调用函数，fetch() 超时的 URLs，验证自己的理解。
21. 识别根因：问为什么此输入失败、为什么到达此路径、正确修复是什么（例如 "Filter binary URLs before Firecrawl"，而不是 "suppress the log"）。
22. 按 pattern 应用真实修复：External API fails on certain URLs → Filter/validate inputs before sending；Timeout → Investigate what's slow; adjust timeout or input size；DB "invalid json" → Sanitize before insert；Stale reference on cron → Detect staleness, auto-clean。
23. Phase 3：每个 issue 一个分支；运行 git checkout main && git pull && git checkout -b fix/<descriptive-name>。
24. 测试先行：使用实际 Sentry 事件的数据，确保测试在修复前失败、修复后通过。
25. 实现修复：修复根因而不是症状；如果修复主要是日志级别变更，STOP，并确认自己调查了为什么失败，还是只是压制。
26. 验证：测试通过、lint 通过、修复处理实际失败输入。
27. 提交 PR：包含 Root cause（上游原因）和 Fix（改了什么以及为什么能防止失败）；仅在 merge 后在 Sentry 中 resolve。

适用边界 · 注意事项

• 没有 Sentry MCP server，或无法先通过 ToolSearch 加载 Sentry MCP 工具时。
• 没有可用的 Sentry 生产错误/事件/traceId 数据，或问题不来自 Sentry 时。
• 事件属于真正预期状态（例如 optional column missing、resource deleted），只需要降日志级别而不需要根因修复时，不要套用完整调查/修复流程。