参数验证与错误提示设计

一个没有验证的 Skill，在错误输入下会产生难以理解的输出或悄悄失败。好的错误提示让用户在 30 秒内知道哪里出了问题、应该怎么修正。这一节讲如何在 Skill 文件中设计这套验证和反馈机制。

好的错误提示 vs 差的错误提示

验证的三个层次

层次一：参数存在性验证（是否提供了必填参数）

## 执行步骤
### 步骤 0：参数存在性检查
检查 $ARGUMENTS 中是否包含必填参数：
**`--target`（必填）**：
- 如果未在 $ARGUMENTS 中找到 `--target` 参数，立即停止并输出：
```
❌ 错误：缺少必填参数 --target
用法：/migrate-check --target <数据库名> [--env staging|production]
示例：
/migrate-check --target users_db
/migrate-check --target orders_db --env production
运行 /help migrate-check 查看完整说明。
```

层次二：参数值有效性验证（值是否符合规范）

**`--env` 值验证**：
- 有效值：`staging`、`production`
- 如果提供了其他值（如 `prod`、`dev`、`test`），停止并输出：
```
❌ 错误：--env 的值 '{用户输入}' 无效
有效值：
staging    → 测试/预发布环境
production → 生产环境
如果你想连接开发环境，请使用 /local-check Skill。
```

层次三：运行时验证（执行过程中的资源检查）

**文件存在性验证**（在读取文件之前）：
尝试使用 Read 工具读取目标文件。如果读取失败：
输出：

❌ 错误：无法读取文件 '{路径}'

可能的原因： 1. 文件路径错误（请检查拼写） 2. 文件不存在（已被删除或移动） 3. 文件权限不足

你提供的路径：{用户输入的路径} 当前工作目录：（运行 pwd 获取）

请确认文件路径后重试。

分级错误严重性

不是所有验证失败都应该终止 Skill 的执行：

## 验证结果处理规则
### 致命错误（立即终止）
- 必填参数缺失
- 参数值完全无效
- 核心资源（目标文件、数据库连接）不可访问
### 警告（提示后继续）
- 非推荐的参数组合（"你在 --dry-run 模式下使用了 --force，--force 将被忽略"）
- 可能影响结果质量的情况（"--limit 设置为 100 可能导致分析时间较长"）
- 检测到环境与预期不符但仍可继续（"当前在 feature 分支而非 main，继续分析..."）
### 信息提示（不影响执行）
- 参数使用了默认值（可以显示，也可以不显示）
- 跳过了某些不适用的检查步骤

错误提示的模板结构

一个好的错误提示应该包含以下要素：

[错误级别图标] 错误/警告/提示：[简洁的问题描述]
[如果有：问题的详细原因]
[如果有：用户提供的值 vs 期望的值]
[解决方案建议]
[如果有：相关帮助信息的链接或命令]

图标约定：

复杂验证的完整示例：migrate-check Skill

---
description: 验证数据库迁移脚本的安全性和正确性
allowed-tools: Bash, Read, Glob
---
# 数据库迁移检查
## 目标
在运行数据库迁移之前，验证迁移脚本的安全性，
检测潜在的数据丢失风险和不可逆操作。
## 参数说明（来自 $ARGUMENTS）
| 参数 | 类型 | 必填 | 默认值 | 有效值 |
|------|------|------|--------|--------|
| `--migration` | string | 否 | 最新未运行的迁移 | 迁移文件名或 `all` |
| `--env` | enum | 是 | — | `staging` / `production` |
| `--strict` | flag | 否 | false | 严格模式：任何警告都视为错误 |
## 执行步骤
### 步骤 0：参数验证
**验证 `--env`**：
- 如果未提供 `--env`，停止并输出：
```
❌ 错误：缺少必填参数 --env
用法：/migrate-check --env <staging|production> [--migration <文件名|all>]
示例：
/migrate-check --env staging
/migrate-check --env production --migration 20240315_add_user_index.sql
```
- 如果 `--env` 的值不是 `staging` 或 `production`，停止并输出：
```
❌ 错误：--env 的值 '{用户输入}' 无效
有效值：staging | production
```
- 如果 `--env` 为 `production`，输出：
```
⚠️  警告：你正在检查生产环境迁移。
本检查将在严格模式下运行，任何问题都将被视为阻断错误。
继续...
```
**验证迁移文件（如果提供了 `--migration`）**：
- 如果指定了具体文件名：
- 在 `db/migrations/` 目录中查找该文件
- 如果文件不存在：
```
❌ 错误：迁移文件 '{文件名}' 不存在
在 db/migrations/ 目录中找到以下迁移文件：
[列出最近 5 个 .sql 文件]
请确认文件名后重试。
```
### 步骤 1：读取迁移文件
1. 根据验证后的参数确定要检查的迁移文件
2. 使用 Read 工具读取文件内容
### 步骤 2：安全性分析
分析以下风险操作（按严重性分级）：
**严重风险（生产环境中应阻断）**：
- `DROP TABLE`、`DROP DATABASE`
- `DELETE FROM` 不带 `WHERE` 子句
- `TRUNCATE TABLE`
**中等风险（需要确认）**：
- `ALTER TABLE ... DROP COLUMN`（数据丢失）
- `UPDATE` 不带 `WHERE` 子句
- 添加 `NOT NULL` 列但没有 `DEFAULT` 值（可能导致插入失败）
**低风险（仅记录）**：
- `CREATE INDEX`（可能锁表，生产环境建议 `CONCURRENTLY`）
- `ALTER TABLE ... ADD COLUMN`（通常安全）
### 步骤 3：生成检查报告
## 输出格式

数据库迁移检查报告

迁移文件：{文件名} 目标环境：{env} 检查时间：[时间]

风险分析

检查结论

[✅ 可以安全运行] 或 [❌ 发现 N 个严重风险，建议在 staging 充分测试后再运行]

建议

[具体的改进建议，如添加 CONCURRENTLY、添加 WHERE 子句等]

本节记录清单

• [ ] 为你的 Skill 的每个必填参数添加存在性检查和清晰的用法说明
• [ ] 为枚举类型参数添加值有效性检查
• [ ] 区分"致命错误（终止）"和"警告（继续）"的处理逻辑
• [ ] 测试：在不提供任何参数时运行 Skill，检查错误提示是否清晰

下一章：多步工作流与工具调用——参数处理好了，现在让 Skill 做更复杂的事：在一个 Skill 中串联读文件、执行命令、调用 API 等多步操作。