---
name: whistle-config
description: 配置 whistle 代理规则，包括静态资源本地代理、API mock、请求修改、调试工具等。当用户需要配置 whistle 规则、设置代理、mock 接口或调试网络请求时使用。
allowed-tools: "Read Glob"
---

# Whistle 代理配置技能

帮助用户配置 whistle 代理规则，实现本地开发、API mock、请求调试等场景。

## 快速开始

### 最常用场景：Web 开发本地代理

**场景描述**: 将网站的静态资源代理到本地开发服务器，其他 API 请求保持调用服务端。

**配置模板**:
```txt
# 主站点流量转发到本地开发服务器（排除 API 路径）
www.example.com http://localhost:3000 excludeFilter://*/api/*

# 或者：仅代理特定路径到本地
www.example.com/static file:///User/yourname/project/static
www.example.com/assets http://localhost:5173/assets

# API 保持调用服务端（可选：如果需要指定服务器 IP）
www.example.com/api 192.168.1.100:8080
```

**配置步骤**:
1. 询问用户：目标域名、本地开发服务器地址（host:port）、需要排除的路径
2. 使用 `excludeFilter` 或 `includeFilter` 精确控制规则作用范围
3. 生成规则配置
4. 提醒用户在 whistle UI 的 Rules 面板中添加规则

### 常用场景 2：API Mock

**场景描述**: Mock API 返回特定的 JSON 数据，用于前端开发和测试。

**配置模板**:
```txt
# 方式 1：内联 JSON
www.example.com/api/user file://({"id":1,"name":"张三","status":"success"})

# 方式 2：使用 Values 引用
www.example.com/api/data file://{mock-data.json}

# 方式 3：本地文件
www.example.com/api/config file:///User/yourname/mocks/config.json

# 方式 4：根据请求方法过滤
www.example.com/api/submit file://{success.json} includeFilter://m:POST
www.example.com/api/submit file://{error.json} includeFilter://m:GET
```

**配置步骤**:
1. 询问用户：API 路径、期望的响应数据、是否需要根据请求方法区分
2. 推荐使用内联方式（简单数据）或 Values 引用（复杂数据、需要复用）
3. 如果数据较复杂，建议用户在 whistle UI 的 Values 面板中创建内容
4. 生成规则配置

### 常用场景 3：请求/响应修改

**场景描述**: 修改请求头、响应头、响应内容等。

**配置模板**:
```txt
# 添加/修改请求头
www.example.com reqHeaders://({"X-Custom-Header":"test","Authorization":"Bearer token123"})

# 修改响应头（例如 CORS）
www.example.com resHeaders://({"Access-Control-Allow-Origin":"*"})

# 合并修改响应 JSON（不完全替换）
www.example.com/api/data resMerge://({"newField":"value"})

# 替换响应内容
www.example.com/api/status resBody://({"status":"ok"})

# 修改状态码
www.example.com/error statusCode://200
```

## 核心工作流

### 步骤 1：理解用户需求

询问用户以下信息：
1. **目标域名/路径**: 需要代理的 URL 模式
2. **代理目标**: 本地服务器、本地文件、mock 数据、代理服务器等
3. **作用范围**: 是否需要排除某些路径（API、静态资源等）
4. **特殊需求**: 请求方法过滤、请求头修改、调试工具等

### 步骤 2：选择合适的协议

根据需求选择协议（详见 [references/protocols-core.md](references/protocols-core.md)）：

**代理转发类**:
- `host://` - 修改 DNS 解析到指定 IP:端口
- `proxy://` - HTTP 代理转发
- `socks://` - SOCKS5 代理
- `http://` 或 `https://` - 直接指定目标地址

**文件映射类**:
- `file://` - 映射到本地文件/目录/内联内容
- `xfile://` - 带回退的文件映射（本地无文件时请求服务器）

**修改类**:
- `reqHeaders://`、`resHeaders://` - 修改请求/响应头
- `reqBody://`、`resBody://` - 修改请求/响应体
- `resMerge://` - 合并修改响应 JSON
- `statusCode://` - 修改响应状态码

**调试类**:
- `weinre://` - 远程 DOM 调试
- `log://` - 捕获 console 日志
- `reqSpeed://`、`resSpeed://` - 限制请求/响应速度
- `reqDelay://`、`resDelay://` - 添加延迟

**完整协议列表**: 见 [references/protocols-core.md](references/protocols-core.md)、[references/protocols-modification.md](references/protocols-modification.md)、[references/protocols-advanced.md](references/protocols-advanced.md)

### 步骤 3：编写 Pattern 匹配规则

Pattern 用于匹配需要代理的 URL（详见 [references/pattern-matching.md](references/pattern-matching.md)）：

**基础匹配**:
```txt
# 精确域名
www.example.com

# 域名 + 路径
www.example.com/api/users

# 单级子域名通配
*.example.com

# 多级子域名通配
**.example.com

# 路径通配符
www.example.com/*/profile
```

**高级匹配**:
```txt
# 正则表达式
/^https?://www\.example\.com/user/(\d+)/

# 协议通配
^http*://www.example.com

# 捕获组（用于动态替换）
^www.example.com/user/*/profile file:///path/to/user-$1.json
```

### 步骤 4：选择 Value 来源

Value 是协议操作的具体内容（详见 [references/value-sources.md](references/value-sources.md)）：

**内联值** - 适合简单内容:
```txt
pattern file://({"status":"ok"})
pattern reqHeaders://({"X-Custom":"value"})
```

**Values 引用** - 适合复杂内容、需要复用:
```txt
pattern file://{mock-data.json}
pattern resBody://{response-template.html}
```

**本地文件** - 适合已有文件:
```txt
pattern file:///User/yourname/project/dist/index.html
pattern file:///User/yourname/mocks
```

**远程 URL** - 适合引用线上资源:
```txt
pattern file://https://example.com/template.json
```

**模板字符串** - 适合动态内容:
```txt
# Values 中创建 template.txt，内容包含变量：
# {"timestamp": "${now}", "url": "${url}", "query": "${query.name}"}

pattern file://`{template.txt}`
```

### 步骤 5：添加过滤器（可选）

使用过滤器精确控制规则作用范围（详见 [references/protocols-advanced.md](references/protocols-advanced.md)）：

**路径过滤**:
```txt
# 排除特定路径
www.example.com http://localhost:3000 excludeFilter://*/api/*

# 仅匹配特定路径
www.example.com file://{mock.json} includeFilter:///api/*
```

**请求方法过滤**:
```txt
# 仅 POST 请求
pattern file://{success.json} includeFilter://m:POST

# 排除 OPTIONS 请求
pattern operation excludeFilter://m:OPTIONS
```

**请求头过滤**:
```txt
# 仅匹配包含特定 header
pattern operation includeFilter://reqH:X-Custom-Header=value
```

**请求体过滤**:
```txt
# 仅匹配请求体包含特定内容
pattern operation includeFilter://b:type=advanced
```

### 步骤 6：生成完整规则

组合 Pattern + Operation + Filters，生成完整规则：

```txt
# 基本格式
pattern operation [filters...]

# 示例
www.example.com http://localhost:3000 excludeFilter://*/api/*
www.example.com/api file://{mock.json} includeFilter://m:POST
```

### 步骤 7：指导用户应用规则

1. **打开 whistle UI**: 浏览器访问 `http://local.whistlejs.com` 或 `http://127.0.0.1:8899`
2. **进入 Rules 面板**: 点击顶部 "Rules" 标签
3. **选择或创建规则组**: 在左侧规则列表中选择规则组（如 "Default"）
4. **粘贴规则**: 将生成的规则粘贴到右侧编辑器
5. **保存**: 规则自动保存并生效
6. **测试**:
   - 打开 Network 面板查看请求是否被代理
   - 检查请求的 "Rules" 列，查看匹配的规则
   - 如果规则未生效，检查 pattern 是否正确匹配

## 调试和验证

### 验证规则是否生效

1. **查看 Network 面板**:
   - 打开 whistle UI 的 Network 面板
   - 发起目标请求
   - 查看请求的 "Rules" 列，显示匹配的规则

2. **检查规则匹配**:
   - 如果 "Rules" 列为空，说明 pattern 未匹配成功
   - 检查域名、路径、协议是否正确
   - 检查是否有更高优先级的规则冲突

3. **查看规则详情**:
   - 点击请求，在右侧面板查看 "Rules" 标签
   - 显示该请求匹配的所有规则及执行顺序

### 常见问题排查

**问题 1：规则不生效**
- 检查 whistle 是否正常运行：`w2 status`
- 检查浏览器代理设置是否指向 whistle
- 检查规则 pattern 是否正确匹配 URL
- 检查是否有 filter 阻止了规则应用

**问题 2：HTTPS 请求无法代理**
- 确保已安装并信任 whistle HTTPS 证书
- 运行 `w2 restart -S` 启用 HTTPS 抓包
- 查看 whistle 文档：https://wproxy.org/docs/getting-started.html

**问题 3：文件路径无法访问**
- 确认本地文件路径正确（使用绝对路径）
- 检查文件权限
- Windows 使用正斜杠：`file:///C:/Users/name/file.txt`

**问题 4：多个规则冲突**
- 规则按从上到下顺序执行
- 后面的规则会覆盖前面的相同协议
- 使用 `excludeFilter` 或 `includeFilter` 精确控制作用范围

## Web 开发常见场景

详见 [references/web-dev-scenarios.md](references/web-dev-scenarios.md)，包含：

1. **前端开发环境** - 本地开发服务器 + 远程 API
2. **Vite/Webpack HMR** - 热更新配置
3. **微前端架构** - 多个子应用代理
4. **移动端调试** - 手机抓包配置
5. **API 接口测试** - Mock 和修改响应
6. **跨域问题解决** - CORS 配置
7. **性能测试** - 模拟慢速网络
8. **HTTPS 本地开发** - 本地 HTTPS 证书

## 进阶功能

### 使用变量和模板

详见 [references/value-sources.md](references/value-sources.md) 中的模板字符串章节。

### 规则优先级和继承

详见 [references/protocols-advanced.md](references/protocols-advanced.md) 中的 lineProps 章节。

### 插件扩展

whistle 支持通过插件扩展功能，详见项目文档。

## 配置原则

1. **简洁优先**: 使用最简单的方式实现需求
2. **明确范围**: 使用 filter 精确控制规则作用范围，避免影响不相关请求
3. **分组管理**: 将相关规则组织在同一规则组，方便启用/禁用
4. **注释说明**: 使用 `#` 添加注释，说明规则用途
5. **测试验证**: 每次修改规则后在 Network 面板验证效果

## 参考文档

- **核心协议**: [references/protocols-core.md](references/protocols-core.md)
- **修改协议**: [references/protocols-modification.md](references/protocols-modification.md)
- **高级功能**: [references/protocols-advanced.md](references/protocols-advanced.md)
- **模式匹配**: [references/pattern-matching.md](references/pattern-matching.md)
- **值来源**: [references/value-sources.md](references/value-sources.md)
- **Web 开发场景**: [references/web-dev-scenarios.md](references/web-dev-scenarios.md)
- **Whistle 官方文档**: https://wproxy.org/docs/getting-started.html