Exception Probe Laravel Package

Product Decisions This Supports

• 内部错误分类工具。该包的核心能力——将原始 PHP 堆栈跟踪转换为可读的、结构化的输出——是管理端“最近错误”面板、支持工单上下文附件或 CI 失败摘要器等功能的底层管道。如果这些功能中有任何一项在待办事项中，此包可以缩短工作流程中解析那一半的时间，而不是 UI/摄取那一半。
• 构建 vs. 购买（vs. 借用）。v1.0.0 被标记为初始发布，这会改变风险特征，但不会改变决策形态。该包不是你可以依赖的成熟供应商；它是一个刚发布、未经验证的库。可辩护的框架仍是借用方法，自己拥有代码：阅读它、fork 它，或在内部重新实现约解析并格式化的步骤。对于任何需要持久性的场景，购买（Sentry、Flare、Bugsnag、Rollbar）仍然是默认选择。
• 开发者体验路线图项目。减少工程师和支持人员的诊断时间。这是一个难以归因但真实存在的成本节省；它不是收入功能；因此它应属于 DX/质量类别，而不是面向客户的路线图主题。
• 真正适合的使用场景：本地/开发异常页面、美化打印跟踪的 CLI 日志尾部工具、基于现有日志表的内部仪表板、自动附加到错误报告的补充文本，以及测试运行器输出格式化。
• 明确不适合的使用场景：任何面向用户的内容（解析后的跟踪会暴露绝对文件路径、内部类名和库版本——存在信息泄露风险）、任何安全敏感的场景，以及任何需要维护 SLA 的场景。
• 此不支持的决策：将堆栈跟踪格式化视为差异化因素。每个成熟的 PHP 框架都已经附带渲染器；价值仅在于你自己工作流程的最后一英里。

何时考虑使用此包

考虑使用它，如果以下所有条件都成立：

• 消费者是内部的——工程师或支持人员——绝不是最终用户。
• 你已验证其兼容性，而不是假设它。没有发布数据，也没有变更日志细节——v1.0.0 的说明仅写着“初始发布”，因此无法从发布内容确认支持哪些 PHP 版本、框架版本或跟踪格式。先运行 spike；不要从版本号推断兼容性。
• 需求确实很小：少量调用点、没有插件架构、没有多租户隔离。
• 假设该包将不再有后续发布，并在此前提下规划。一个初始的 1.0.0 可能是一次性发布、一个副项目，或者一个长期维护库的第一版——仅凭一次发布无法区分这三种情况。准备将其 vendor 或 fork 到你自己的命名空间中并自行拥有。MIT 许可证使这变得干净，也是唯一负责任的采用方式。
• 你有 1–2 天的 spike 时间，而不是一个冲刺。如果估算超过这个时间，就根据有文档记录的跟踪格式自己编写解析器。
• 其输出形状恰好符合你的需求；如果你发现自己大量包装它，这就是停止的信号。

在以下情况下考虑其他方案：

• 你需要生产级错误跟踪、警报、聚合、发布标记或 PII 清理 → Sentry、Flare、Bugsnag、Rollbar。
• 你需要一个经过维护、久经考验的跟踪解析器或渲染器 → spatie/ignition、filp/whoops、symfony/error-handler、nunomaduro/collision。这些具有真实采用率、活跃维护，并与 PHP 版本保持同步。
• 你在 Laravel 内部 → 框架自身的异常处理器加上 Telescope 或 Flare 已经覆盖本地调试；增加第三方解析器是多余的接触面。
• 你需要结构化/兼容 OTel 的 span，而不是人类可读的文本 → 此包是错误抽象。
• 你需要以下任何一项：安全补丁、变更日志节奏、PHP 8.2+ 支持，或有人阅读的问题跟踪器。一个初始发布无法提供任何采用信号；采用会推动修复。
• 解析正确性位于关键路径上（账单对账、审计日志）。跟踪格式在 PHP 和框架版本之间会发生变化；过时的解析器会静默失败。

如何推介它（利益相关者）

面向高管（一段话）： 这是一个小巧、MIT 许可的 PHP 实用工具，能让错误报告变得可读。它不是平台赌注，也不是供应商关系——它是对内部工具的加速器，可缩短“出问题”到“我们知道原因”之间的时间。现实的请求是1–2 天的工程 spike，而不是季度承诺。需要坦诚说明的权衡：该项目刚刚发布首个版本（v1.0.0），没有可参考的记录，也没有可见的路线图，因此如果我们使用它，我们会将逻辑复制到自己的代码库中并拥有它——没有长期依赖风险，但也没有免费的持续改进。如果领导层想要错误可见性的持久解决方案，预算对话对象是 Sentry/Flare，而不是此包。

面向工程团队（争取支持的框架）：

• 已变更： 先前的评估将此标记为未维护；v1.0.0 是初始发布，因此问题不是弃用而是不成熟。在信任它之前，假设这是一次性发布。两种情况下建议相同，但理由不同——而“它刚刚发布”，对于 1.0 标签所暗示的 API 稳定性来说，是比“它已过时”更弱的保证。
• 范围： 窄。它解析和格式化跟踪。它不收集、存储、告警或清理。预计我们要自己构建摄取、存储和脱敏。
• 采用模式： 将源代码 vendor 到我们的命名空间下，置于薄接口（TraceFormatter::format(Throwable): string）之后，以便日后可以替换为 spatie/ignition 或第一方解析器，而无需改动调用点。
• 兼容性： 在做出任何承诺之前，对照我们的 PHP 版本进行验证。首次发布没有变更日志，也无法从“初始发布”中看到兼容性信号，因此跟踪格式变化和弃用是最可能的失败模式。对真实跟踪添加黄金文件测试，以便在 CI 中捕获漂移。
• 安全： 永远不要将输出暴露给未认证用户；在存储前剥离绝对路径和环境细节。将解析后的输出视为敏感数据。
• 退出成本： 接近零——MIT、小接触面、单一接口。这是尝试它而不是从头构建的主要理由。
• 建议： 限时进行 spike，在同一下午与 spatie/ignition 进行比较评估，并默认选择受维护的选项，除非此包在我们特定的跟踪形状上明显胜出。鉴于发布说明未描述任何功能，将其视为未经审计的代码，而不是已发布的产品。