1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | error-handling-patterns（wshobson/agents 合集子技能） |
| 作者/维护者 | Seth Hobson（个人开发者） |
| 来源链接 | https://github.com/wshobson/agents/tree/main/plugins/developer-essentials/skills/error-handling-patterns |
| 许可证 | MIT（GitHub API，仓库级） |
| GitHub Stars | 38,638（GitHub API；属整个 agents 合集仓库，不代表本技能自身热度） |
| Forks | 4,121（GitHub API，同为仓库级数据） |
| 最新版本 | 所属插件 developer-essentials v1.0.4（plugin.json 声明；SKILL.md 本身未单独声明版本号） |
| 安装方式 | 见第 10 章 |
2. 功能介绍与亮点
error-handling-patterns 是一份跨语言（Python、TypeScript 等）的错误处理方法论指南，把“异常该怎么设计、什么时候用哪种模式”从零散经验整理成可复用的决策框架：
- 区分四种错误处理哲学（异常、Result 类型、错误码、Option/Maybe 类型）并给出各自适用场景，帮助开发者在设计 API 时选对错误传递方式，而非凭习惯
- 把错误分为“可恢复”（网络超时、缺失文件、非法输入、限流）与“不可恢复”（内存溢出、栈溢出、编程错误）两类，分别给出对应处理策略
- 内含一段完整的订单处理示例代码，演示输入校验、外部服务错误包裹（保留原始堆栈）、未预期异常兜底三层结构，而非零散代码片段
- 八条最佳实践（尽早失败、保留上下文、避免吞异常等）与七条常见陷阱（捕获过宽、空 catch 块、重复记录日志等）正反对照给出
- SKILL.md 采用分层设计，核心概念在主文件，更细的模式与实战案例延伸到
references/details.md，按需加载
3. 适用场景
所属分类：工程效率与代码质量
适用于正在设计新功能错误处理逻辑、构建 API、或希望系统性提升应用可靠性的开发者：初中级用户可以直接照搬“分层捕获、保留堆栈”的示例代码起步，不必自己摸索异常设计规范；有一定经验的开发者能用文中的哲学对比表格判断某个场景该用异常还是 Result 类型，减少团队内部关于错误处理风格的争论。
4. 跨 Agent 兼容性
- Claude Code：原生支持 ✅——仓库即 Claude Code 插件市场源码，
/plugin marketplace add wshobson/agents后/plugin install developer-essentials - Codex：原生支持 ✅——仓库文档明确将 Codex CLI 列为原生消费方，
npx codex-marketplace add wshobson/agents添加市场后按插件名安装 - OpenClaw：未验证——仓库文档未提及该平台
- Hermes Agent：未验证——仓库文档未提及该平台
5. 推荐理由
错误处理是几乎所有代码都绕不开的环节，但多数团队没有统一标准，容易出现“该重试的没重试、该记录的没记录、异常吞了没人知道”这类问题。这份指南把资深工程师脑子里的判断标准（什么时候用异常/Result 类型、错误该在哪一层捕获、日志该怎么写）整理成一张可直接套用的决策表和一段完整示例代码，对刚开始写生产代码的初中级用户尤其有用——不需要先踩几次线上故障的坑，也能一次性把错误处理的骨架搭对。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 合集子技能，不计仓库星数；按第三方数据面板 skills.sh 统计的独立安装量约 19.2K 次，在 wshobson/agents 全部 180 个子技能中排名第 17 位，处于中上游 |
| 可用性 | 9 | SKILL.md 结构完整、含可运行示例代码，配套 references/details.md 承载更深内容；所属仓库近期持续推送更新，维护活跃；无付费依赖，一条命令即可安装 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单
| 项目 | 结果 |
|---|---|
| ① shell 命令及权限范围 | 纯文档/方法论技能，不含可执行脚本，不要求 shell 权限 |
| ② 联网外发数据 | 无网络调用 |
| ③ API key/凭据 | 不涉及 |
| ④ 可疑指令 | 通读 SKILL.md 全文，未发现提示词注入或隐蔽指令 |
| ⑤ 作者信誉 | 个人开发者 Seth Hobson，仓库内容公开可审计、长期持续维护，未见刷星或 SEO 操纵等造假迹象 |
| ⑥ License | MIT，清晰 |
| ⑦ 维护时间 | 仓库最近一次推送为近日，维护活跃 |
无扣分项——纯提示词/文档类技能，无代码执行也无外联，判 9 分。
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与 error-handling-patterns 的差异 |
|---|---|---|
| n8n-error-handling（n8n 官方） | 面向 n8n 可视化工作流平台的节点级错误处理与重试配置 | 局限于 n8n 这一款特定工作流工具的节点设置，不涉及代码层面的异常设计；本技能面向通用编程语言，覆盖任意技术栈 |
| debugging-and-error-recovery（addyosmani 合集） | 面向“线上已经出错，如何定位并恢复”的调试与故障恢复流程指南 | 关注事后排障与恢复步骤；本技能关注事前设计——写代码时该如何组织错误处理结构，两者时间点互补而非替代 |
| python-error-handling（同仓库姊妹技能） | 专注 Python 语言特有的错误处理惯用法与标准库用法 | 局限于单一语言的具体语法层面；本技能覆盖跨语言通用的设计哲学与决策框架，不绑定特定语言 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价，GitHub 上也未检索到专门针对该技能的 issue 讨论。
9. 其他补充
除面向 Claude Code 与 Codex CLI 的原生安装外，所属仓库同时以生成方式支持 Cursor、OpenCode、Gemini CLI 与 GitHub Copilot，详见仓库 docs/harnesses.md。
10. 安装使用方式
- Claude Code：
/plugin marketplace add wshobson/agents，再/plugin install developer-essentials - Codex CLI：
npx codex-marketplace add wshobson/agents添加市场后安装 developer-essentials 插件 - 手动安装（任意支持 SKILL.md 规范的 agent）：从仓库
plugins/developer-essentials/skills/error-handling-patterns/复制 SKILL.md 与references/目录到本地 skills 目录 - 其他渠道（Cursor、OpenCode、Gemini CLI、Copilot）见仓库
docs/harnesses.md
安装后无需重启，技能按插件维度加载，用自然语言触发即可，例如“帮我设计这个 API 的错误处理逻辑”“这段代码的异常处理有什么问题”。
11. 注意事项
- 该技能隶属 wshobson/agents 合集仓库，仓库整体星数/装机量不代表本技能独立热度
- SKILL.md 主文件仅覆盖核心概念与最佳实践，更细的模式与案例在
references/details.md中，需要时才会被加载 - 内容以通用编程语言的错误处理原则为主，未针对特定框架（如 Spring、Django 的异常处理约定）做专项覆盖，实际落地时仍需结合具体技术栈调整