---

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

Whistle 代理配置技能

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

快速开始

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

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

配置模板:

# 主站点流量转发到本地开发服务器（排除 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 数据，用于前端开发和测试。

配置模板:

# 方式 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：请求/响应修改

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

配置模板:

# 添加/修改请求头
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）：

代理转发类:

• 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-modification.md、references/protocols-advanced.md

步骤 3：编写 Pattern 匹配规则

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

基础匹配:

# 精确域名
www.example.com

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

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

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

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

高级匹配:

# 正则表达式
/^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）：

内联值 - 适合简单内容:

pattern file://({"status":"ok"})
pattern reqHeaders://({"X-Custom":"value"})

Values 引用 - 适合复杂内容、需要复用:

pattern file://{mock-data.json}
pattern resBody://{response-template.html}

本地文件 - 适合已有文件:

pattern file:///User/yourname/project/dist/index.html
pattern file:///User/yourname/mocks

远程 URL - 适合引用线上资源:

pattern file://https://example.com/template.json

模板字符串 - 适合动态内容:

# Values 中创建 template.txt，内容包含变量：
# {"timestamp": "${now}", "url": "${url}", "query": "${query.name}"}

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

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

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

路径过滤:

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

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

请求方法过滤:

# 仅 POST 请求
pattern file://{success.json} includeFilter://m:POST

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

请求头过滤:

# 仅匹配包含特定 header
pattern operation includeFilter://reqH:X-Custom-Header=value

请求体过滤:

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

步骤 6：生成完整规则

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

# 基本格式
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，包含：

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

进阶功能

使用变量和模板

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

规则优先级和继承

详见 references/protocols-advanced.md 中的 lineProps 章节。

插件扩展

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

配置原则

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

参考文档

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