Skills 错误处理与容错

Skills 错误处理与容错是 AI 技能工程化开发的重要能力。在真实使用场景中，用户输入不规范、参数非法、命令执行失败、脚本报错等问题无法完全避免。如果技能没有容错机制，一旦遇到异常就会崩溃、报错、输出混乱，严重影响使用体验。

Skills 错误处理与容错，就是通过预判错误、拦截异常、兜底处理、友好反馈，让技能在各种异常场景下依然稳定运行，保证程序健壮性与可用性。

一、Skill 常见错误类型

在 TraeCode 技能体系中，常见错误主要分为四类：

输入参数错误：负数、零、非数字、空参数、超出范围参数
用户指令错误：语义模糊、指令残缺、无法识别意图
执行运行错误：终端命令报错、脚本语法错误、逻辑异常
匹配触发错误：误触发、不触发、多技能冲突

以上任意一种错误都会导致技能执行失败，因此必须加入容错机制。

二、错误处理与容错的核心概念

1. 错误处理

指技能主动识别错误、捕获异常、终止错误流程的能力。当检测到非法输入或异常执行时，不再继续运行错误逻辑，而是进入专门的异常流程。

2. 容错机制

容错是比错误处理更高阶的能力，指不报错、不崩溃、自动兜底修复。遇到不规范输入时，智能修正参数、自动补全默认值、兼容异常场景，让任务依然可以正常完成。

简单总结：错误处理负责止损，容错负责兜底。

三、为什么需要容错设计

提升稳定性：避免一句错误输入导致技能卡死、报错、中断
提升用户体验：不输出代码报错信息，只输出友好中文提示
降低调试成本：提前拦截已知异常，减少线上故障
工程化必备：具备容错的技能，才能长期复用、批量部署、团队共用
兼容口语化输入：用户输入随意、不规范，容错可以智能兼容

四、Skills 容错与错误处理实现方式

Skill 的容错分为两层：**规则层容错（SKILL.md）**与 脚本层容错（scripts）。

1. 规则层容错（基础容错）

在 SKILL.md 正文中提前定义异常处理规则，无需代码即可实现基础容错。

设置参数默认值：用户不传参数时自动使用默认值，避免空执行
限定参数合法范围：只允许正整数、限定最大最小值
定义异常提示文案：非法输入返回标准化中文提示
禁止模型自由发挥：开启 disable-model-invocation 固定输出逻辑

示例：roll-dice 容错规则：无参数默认 1d6，负数、零禁止执行。

2. 脚本层容错（高级容错）

针对复杂场景，通过 Python 脚本实现精准异常捕获，是工业级容错方案。

使用 try-except 捕获运行报错
主动判断参数范围，拦截非法数据
数据类型校验，防止字符、空值、特殊符号传入
异常时返回自定义友好信息，不抛出原始报错堆栈

脚本容错可以解决所有规则层无法处理的复杂异常。

五、标准容错执行流程

完整容错链路遵循 Skill 运行机制，分为五步：

接收用户输入：接收自然语言或精准指令参数
参数校验拦截：判断是否为空、是否合法、是否超出范围
容错兜底处理：合法参数正常执行，非法参数触发容错逻辑
分支执行：正常走业务逻辑，异常走提示逻辑
统一输出：无论成功失败，输出格式统一、文案友好

六、典型容错案例（掷骰子技能）

异常场景1：用户空参数

容错处理：自动兜底为 1d6，正常投掷。

异常场景2：用户输入负数、0

容错处理：拦截执行，提示：骰子数量和面数必须为正整数。

异常场景3：输入非法字符、乱码

容错处理：识别参数解析失败，返回友好提示，不崩溃。

七、容错设计最佳实践

能兼容则兼容，不能兼容则友好提示
优先默认值兜底，尽量保证任务可完成
隐藏底层报错，用户只看中文提示
参数严格校验，从源头杜绝异常执行
分层容错：简单异常规则层处理，复杂异常脚本层处理

八、总结

Skills 错误处理与容错是技能从能用、到好用、再到稳定可用的关键升级。错误处理负责精准捕获异常、阻断错误流程；容错机制负责自动兜底、兼容不规范输入、保障任务不中断。

通过规则层与脚本层双层容错设计，可以彻底解决参数异常、输入不规范、执行报错等问题，让 Skill 具备工业级稳定性，真正满足工程化、自动化、规模化的 AI 智能体开发需求。