whistle 2.9.91 → 2.9.93

package/README-en_US.md

@@ -0,0 +1,297 @@
+<p align="center">
+  <a href="https://avwo.github.io/whistle/">
+    <img alt="whistle logo" src="https://user-images.githubusercontent.com/11450939/168828068-99e38862-d5fc-42bc-b5ab-6262b2ca27d6.png">
+  </a>
+</p>
+
+# whistle
+[![NPM version](https://img.shields.io/npm/v/whistle.svg?style=flat-square)](https://npmjs.org/package/whistle)
+[![node version](https://img.shields.io/badge/node.js-%3E=_8-green.svg?style=flat-square)](http://nodejs.org/download/)
+[![Test coverage](https://codecov.io/gh/avwo/whistle/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/avwo/whistle)
+[![npm download](https://img.shields.io/npm/dm/whistle.svg?style=flat-square)](https://npmjs.org/package/whistle)
+[![NPM count](https://img.shields.io/npm/dt/whistle.svg?style=flat-square)](https://www.npmjs.com/package/whistle)
+[![License](https://img.shields.io/aur/license/whistle?style=flat-square)](https://www.npmjs.com/package/whistle)
+
+[中文](./README-zh_CN.md) · English
+
+Whistle is a simple and powerful cross-platform packet capture and debugging tool based on Node.JS. It can be used as **HTTP proxy (default)**, **HTTPS proxy**, **Socks proxy**, **reverse proxy**, etc., for **packet capture analysis** or **modification through configuration rules** of HTTP, HTTPS, HTTP/2, WebSocket, TCP requests. It also has built-in **Weinre**, **Log**, **Composer** and other tools to view the DOM structure of remote pages, view console output content, replay and edit construction requests, etc. It also supports **plug-in extension functions** or **referenced by projects as NPM packages**.
+
+# Installation
+
+**Windows PC or Mac PC recommended client: [https://github.com/avwo/whistle-client](https://github.com/avwo/whistle-client)**.
+
+> If you use Whistle client, you can skip this installation step
+
+Linux PC, server and other systems can use the command line version, which needs to be installed strictly according to the following 4 steps:
+
+1. Install Whistle
+2. Start Whistle
+3. Install root certificate
+4. Set up proxy
+
+### Install Whistle
+
+Choose one of the following installation methods according to the actual situation:
+
+1. Install through npm (need to install Node.JS first: https://nodejs.org/ ):
+
+``` sh
+npm i -g whistle
+```
+
+2. Install through brew (need to install brew first: https://brew.sh/ ):
+
+``` sh
+brew install whistle
+```
+
+### Start Whistle
+
+``` sh
+w2 start
+```
+
+> Whistle starts HTTP proxy by default (IP: `127.0.0.1`, port: `8899`), which can be started through `w2 start -p 8888` Modify the port. If it has been started, restart it with `w2 restart -p 8888` to modify the port.
+
+For complete command line functions, please refer to the full document: https://wproxy.org/whistle/options.html
+
+### Install the root certificate
+
+After starting Whistle, you can install the root certificate with the following command:
+
+``` sh
+w2 ca --enable-https
+```
+
+<details>
+<summary>Windows needs to click "Yes (Y)" to confirm</summary>
+<img alt="Click Yes (Y)" width="420" src="https://user-images.githubusercontent.com/11450939/168846905-384e0540-e02f-46de-81d7-e395a496f032.jpeg">
+</details>
+
+<details>
+<summary>Mac You need to enter the power-on password or fingerprint verification</summary>
+<img alt="Enter the power-on password" width="330" src="https://user-images.githubusercontent.com/11450939/176977027-4a7b06a0-64f6-4580-b983-312515e9cd4e.png">
+<img alt="Enter fingerprint" width="330" src="https://user-images.githubusercontent.com/11450939/168847123-e66845d0-6002-4f24-874f-b6943f7f376b.png">
+</details>
+
+For how to install the root certificate on other terminals such as mobile phones, please refer to the complete document: https://wproxy.org/whistle/webui/https.html
+
+### Setting up a proxy
+
+**There are four ways to use Windows PC or Mac PC. You can choose one of them according to your actual situation:**
+
+1. **[Recommended]** Set up a proxy by installing the Chrome plug-in SwitchyOmega: https://chromewebstore.google.com/detail/proxy-switchyomega/padekgcemlokbadohgkifijomclgjgif
+
+> Chrome App Store requires a VPN. If you cannot access it, please install it manually: https://proxy-switchyomega.com/download/
+
+<details>
+<summary>SwitchyOmega setting method example diagram</summary>
+<img width="620" alt="image" src="https://github.com/user-attachments/assets/24016b7c-8f2a-45a3-9dc8-5ef3ddf46233" /><img width="180" alt="image" src="https://github.com/user-attachments/assets/43afd3cd-5c17-4d6a-82d0-20a7ef2e0d99" />
+</details>
+
+2. Set the system proxy through the command line:
+
+```. sh
+w2 proxy
+```
+
+> You can also specify the IP (default `127.0.0.1`) and port: `w2 proxy "10.x.x.x:8888"`, and use `w2 proxy 0` to turn off the system proxy setting
+
+3. Set the proxy directly on the client, such as FireFox, WeChat developer tools, etc., which have built-in proxy setting functions
+<details>
+<summary>FireFox proxy setting example image</summary>
+<img width="1100" alt="image" src="https://github.com/user-attachments/assets/98c1ec5d-4955-4e23-a49a-c1015b128d9d" />
+</details>
+4. Set up a proxy through Proxifier (for clients that cannot set up a proxy and do not use a system proxy): https://www.proxifier.com/docs/win-v4/http-proxy.html
+
+**Linux setting path: Settings > Network > VPN > Network Proxy > Manual**
+<details>
+<summary>Linux proxy setting example image</summary>
+<img width="1000" alt="image" src="https://github.com/user-attachments/assets/e9441d32-c818-4446-8be6-0fa3df3aed86" />
+</details>
+
+**Mobile devices such as mobile phones need to configure the current `Wi-Fi` proxy, taking iOS as an example:**
+<details>
+<summary>iOS proxy settings example image</summary>
+<img width="1000" alt="image" src="https://github.com/user-attachments/assets/e97dc311-2ace-4287-b6b0-0247b13974a9" />
+</details>
+
+# Use
+
+After installing Whistle according to the above steps, open the link http://local.whistlejs.com on the Chrome browser, and you can see the following operation interface:
+
+<img width="1200" alt="network" src="https://github.com/user-attachments/assets/3186e76a-486a-4e61-98a1-2d4b4f91fad0" />
+
+<img width="1200" alt="rules" src="https://github.com/user-attachments/assets/2e336403-4810-48e5-91c1-6f22dcda7388" />
+
+Among them, Network is the interface for viewing packet capture, Rules is the configuration rule, Values ​​is the configuration data interface (used with Rules), and Plugins is the list of installed plugins.
+
+### Interface functions
+
+<details>
+<summary>Replay request</summary>
+<img width="800" alt="image" src="https://github.com/user-attachments/assets/9f8276ac-e089-427b-97f4-becac250ae5e" />
+</details>
+
+<details>
+<summary>Edit or construct request</summary>
+<img width="1200" alt="image" src="https://github.com/user-attachments/assets/f2a5b088-72b6-4098-8ba6-3e42f15f3ad8" />
+</details>
+
+For other interface functions, see the full document: https://wproxy.org/whistle/webui/
+
+### Rule functions
+
+Whistle rules can be seen as an extension of the following system hosts rules:
+
+``` txt
+# One domain name corresponds to one IP
+127.0.0.1 localhost
+::1 localhost
+# Multiple domain names correspond to one IP
+10.2.55.3 www.test.com www.example.com
+```
+
+The system hosts rules have a single function, only supporting DNS modification and domain name matching, and there are DNS cache problems, which cannot meet daily work needs. Whistle rules extend the functions of system hosts rules. In terms of matching methods, they not only support domain name matching, path matching, wildcard matching, regular matching, etc., but also support further filtering by request method, response status code, request (response) header, request content, etc.; in terms of functions, they not only support DNS modification, but also support port modification, CNAME, proxy setting, request URL modification, request method, response status code, request header, response header, request content, response content, etc. In theory, everything in HTTP request can be modified. The format of Whistle rules is:
+
+1. Default format
+
+``` txt
+pattern operation
+```
+
+2. Support matching multiple operations
+
+``` txt
+pattern operation1 operation2 ...
+```
+
+3. Support filters
+
+``` txt
+pattern operation1 operation2 ... includeFilter://filterPattern1 ... excludeFilter://filterPatternN ...
+```
+
+> Multiple filters are in an or relationship, that is, one of the conditions must be met
+
+4. Support position swap (prerequisite: operation and pattern are not URLs or domain names at the same time)
+
+``` txt
+operation pattern [filters...]
+operation pattern1 pattern2 ... [filters...]
+```
+
+5. Support line breaks
+
+``` txt
+line`
+operation
+pattern1
+pattern2 ...
+[filters...]
+`
+```
+
+Specific examples are as follows:
+
+##### Modify DNS (set Hosts)
+
+1. Domain name matching
+
+``` txt
+www.test.com 127.0.0.1
+# Support port
+www.test.com 127.0.0.1:8080
+# CNAME function (port optional)
+www.test.com host://www.example.com:8181
+```
+
+> Unlike the system hosts rule, the Whistle rule adopts **left-to-right mapping** and **top-to-bottom priority** by default, but the operation and pattern can be swapped when they are different URLs or domain names, so it is also compatible with the system hosts rule, that is: `127.0.0.1:8080 www.test.com`
+
+2. Path matching
+
+``` txt
+www.test.com/path/to 127.0.0.1:8080
+# Support with protocol
+https://www.test.com/path/to 127.0.0.1:8080
+```
+
+3. Wildcard matching
+
+``` txt
+# Domain name wildcard, matching test.com All descendant domain names of
+**.test.com 127.0.0.1:8080
+# Support wildcards for domain names with protocols
+https://**.test.com 127.0.0.1:8080
+# Path wildcards (* is a legal character for paths, so add ^ in front to tell Whistle that it is a wildcard)
+^**.test.com/*/path/to 127.0.0.1:8080
+# Support wildcards for paths with protocols
+^https://**.test.com/*/path/to 127.0.0.1:8080
+```
+
+> `*`, `**`, `***` have different matching ranges, for details, see the full document: https://wproxy.org/whistle/pattern.html
+
+4. Regular matching
+
+``` txt
+# The internal `/` can be escaped, which is equivalent to `new RegExp('^https?://\w+\.test\.com')`
+/^https?://\w+\.test\.com/ 127.0.0.1:8080
+```
+
+5. Filter matching
+
+``` txt
+# `pattern` is the same as the domain name, path, and regular expression above, indicating that in addition to matching `pattern`, the request header `cookie` must also contain `env=test`
+pattern 127.0.0.1:8080 includeFilter://reqH.cookie=/env=test/
+```
+
+##### Modify form data
+
+``` txt
+# Modify the value of the `test` field in the form
+pattern reqMerge://test=123
+
+# Delete the `abc` field in the form
+pattern delete://reqBody.abc
+```
+
+##### Set the cross-domain response header
+
+``` txt
+# Taking path matching as an example, set the cross-domain response header Access-Control-Allow-Origin: * and exclude OPTION requests
+pattern resCors://* excludeFilter://m:option
+```
+
+For all rules, see the full document: https://wproxy.org/whistle/rules/
+
+### Install the plugin
+
+The plugin needs to be installed through the command line:
+
+``` sh
+w2 i whistle.inspect whistle.vase
+```
+
+> The above plug-in function introduction and source code: [https://github.com/whistle-plugins](https://github.com/whistle-plugins), the client can be installed through the interface: [https://github.com/avwo/whistle-client](https://github.com/avwo/whistle-client)
+
+After installation, you can see these two plug-ins in the Plugins of the management interface:
+
+<details>
+<summary>Plugin list example image</summary>
+<img width="1000" alt="image" src="https://github.com/user-attachments/assets/ec018691-c7a9-415e-9809-bf079694c024" />
+</details>
+
+Each plug-in can add two rule protocols by default:
+
+``` txt
+whistle.inspect://xxx
+inspect://xxx
+```
+
+> By configuring the custom rules of the plug-in, the matching request can be forwarded to the plug-in specified hook implements custom functions. If not needed, you can also set `"hideLongProtocol": true` or `"hideShortProtocol": true` in `whistleConfig` of `package.json` of the plugin to hide the corresponding rule protocol
+
+In addition to extending rules, the plugin also supports extending the Whistle interface, as well as providing operation interfaces, built-in rules and other functions. For installation, use and development of the plugin, please refer to the complete document: https://wproxy.org/whistle/plugins.html
+
+# License
+
+[MIT](./LICENSE)

package/README.md

@@ -4,91 +4,297 @@
   </a>
 </p>
 
-# whistle
+# Whistle
+
 [![NPM version](https://img.shields.io/npm/v/whistle.svg?style=flat-square)](https://npmjs.org/package/whistle)
-[![node version](https://img.shields.io/badge/node.js-%3E=_8-green.svg?style=flat-square)](http://nodejs.org/download/)
+[![node version](https://img.shields.io/badge/node.js->=_8-green.svg?style=flat-square)](http://nodejs.org/download/)
 [![Test coverage](https://codecov.io/gh/avwo/whistle/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/avwo/whistle)
 [![npm download](https://img.shields.io/npm/dm/whistle.svg?style=flat-square)](https://npmjs.org/package/whistle)
 [![NPM count](https://img.shields.io/npm/dt/whistle.svg?style=flat-square)](https://www.npmjs.com/package/whistle)
 [![License](https://img.shields.io/aur/license/whistle?style=flat-square)](https://www.npmjs.com/package/whistle)
 
-**Mac 或 Windows 系统推荐使用客户端版本：https://github.com/avwo/whistle-client**
+中文 · [English](./README-en_US.md)
+
+Whistle 是基于 Node.JS 实现的操作简单、功能强大的跨平台抓包调试工具，可作为 **HTTP 代理（默认）**、**HTTPS 代理**、**Socks 代理**、**反向代理**等，用于**抓包分析**或**通过配置规则修改** HTTP、HTTPS、HTTP/2、WebSocket、TCP 请求，且内置 **Weinre**、**Log** 、**Composer** 等工具可查看远程页面的 DOM 结构、查看 console 输出内容、重放编辑构造请求等，并支持 **插件扩展功能** 或 **作为 NPM 包被项目引用**。
+
+# 安装
+
+**Windows PC 或 Mac PC 推荐使用客户端：[https://github.com/avwo/whistle-client](https://github.com/avwo/whistle-client)**。
+
+>  如果采用 Whistle 客户端可以跳过该安装步骤
+
+Linux PC、服务器等其它系统可以用命令行版本，需严格按如下 4 个步骤安装：
+
+1. 安装 Whistle
+2. 启动 Whistle
+3. 安装根证书
+4. 设置代理
+
+### 安装 Whistle
+
+根据实际情况选择以下一种安装方式即可：
+
+1. 通过 npm 安装（需要先安装 Node.JS：https://nodejs.org/ ）：
+
+   ``` sh
+   npm i -g whistle
+   ```
+
+2. 通过 brew 安装（需要先安装 brew：https://brew.sh/ ）：
+
+   ``` sh
+   brew install whistle
+   ```
+
+### 启动 Whistle
+
+``` sh
+w2 start
+```
+
+> Whistle 默认启动 HTTP 代理（IP：`127.0.0.1`，端口： `8899`），可以通过 `w2 start -p 8888` 修改端口，如果已启动需要通过 `w2 restart -p 8888` 重启修改端口
+
+完整命令行功能参见完整文档：https://wproxy.org/whistle/options.html
+
+### 安装根证书
+
+启动 Whistle 后可以通过下面的命令安装根证书：
+
+``` sh
+w2 ca --enable-https
+```
+
+<details>
+  <summary>Windows 需要最后点击 “是(Y)” 确认</summary>
+  <img alt="点击 是(Y)" width="420" src="https://user-images.githubusercontent.com/11450939/168846905-384e0540-e02f-46de-81d7-e395a496f032.jpeg">
+</details>
+
+<details>
+  <summary>Mac 需要输入开机密码或指纹验证</summary>
+  <img alt="输入开机密码" width="330" src="https://user-images.githubusercontent.com/11450939/176977027-4a7b06a0-64f6-4580-b983-312515e9cd4e.png">
+  <img alt="输入指纹" width="330" src="https://user-images.githubusercontent.com/11450939/168847123-e66845d0-6002-4f24-874f-b6943f7f376b.png">
+</details>
+
+手机等其它端如何安装根证书参见完整文档：https://wproxy.org/whistle/webui/https.html
+
+### 设置代理
+
+**Windows PC 或 Mac PC 有以下四种方式，根据实际情况选择其中一种即可：**
+
+1. **【推荐】** 通过安装 Chrome 插件 SwitchyOmega 设置代理：https://chromewebstore.google.com/detail/proxy-switchyomega/padekgcemlokbadohgkifijomclgjgif
+
+   > Chrome 应用商店需要翻墙，如果无法访问请手动安装：https://proxy-switchyomega.com/download/
+
+   <details>
+     <summary>SwitchyOmega 设置方法示例图</summary>
+   	<img width="620" alt="image" src="https://github.com/user-attachments/assets/24016b7c-8f2a-45a3-9dc8-5ef3ddf46233" /><img width="180" alt="image" src="https://github.com/user-attachments/assets/43afd3cd-5c17-4d6a-82d0-20a7ef2e0d99" />
+   </details>
+
+2. 通过命令行设置系统代理：
+
+   ```. sh
+   w2 proxy
+   ```
+
+   > 也可以指定IP（默认`127.0.0.1`）和端口： `w2 proxy "10.x.x.x:8888"` ，关闭系统设置代理用 `w2 proxy 0`
+
+3. 直接在客户端上设置代理，如 FireFox、微信开发者工具等内置了设置代理功能
+    <details>
+      <summary>FireFox 设置代理示例图</summary>
+        <img width="1100" alt="image" src="https://github.com/user-attachments/assets/98c1ec5d-4955-4e23-a49a-c1015b128d9d" /> 
+    </details>
+4. 通过 Proxifier 设置代理（针对无法设置代理且不使用系统代理的客户端）：https://www.proxifier.com/docs/win-v4/http-proxy.html
+
+**Linux 设置路径: Settings > Network > VPN > Network Proxy > Manual**
+  <details>
+    <summary>Linux 设置代理示例图</summary>
+      <img width="1000" alt="image" src="https://github.com/user-attachments/assets/e9441d32-c818-4446-8be6-0fa3df3aed86" />
+  </details>
+
+**手机等移动端设备需要在 `设置` 中配置当前 `Wi-Fi` 的代理，以 iOS 为例：**
+  <details>
+    <summary>iOS 设置代理示例图</summary>
+      <img width="1000" alt="image" src="https://github.com/user-attachments/assets/e97dc311-2ace-4287-b6b0-0247b13974a9" />
+  </details>
+
+# 使用
+
+按上面步骤安装好 Whistle，在 Chrome 浏览器上打开链接 http://local.whistlejs.com ，即可看到如下操作界面：
 
-Whistle 是基于 Node 实现的跨平台抓包调试工具，其主要特点：
-1. **完全跨平台**：支持 Mac、Windows 等桌面系统，且支持服务端等命令行系统
-2. **功能强大（理论上可以对请求做任意修改）**：
-	* 支持作为 HTTP、HTTPS、SOCKS 代理及反向代理
-	* 支持抓包及修改 HTTP、HTTPS、HTTP2、WebSocket、TCP 请求
-	* 支持重放及构造 HTTP、HTTPS、HTTP2、WebSocket、TCP 请求
-	* 支持设置上游代理、PAC 脚本、Hosts、延迟（限速）请求响应等
-	* 支持查看远程页面的 console 日志及 DOM 节点
-	* 支持用 Node 开发插件扩展功能，也可以作为独立 npm 包引用
-3. **操作简单**：
-	* 直接通过浏览器查看抓包、修改请求
-	* 所有修改操作都可以通过配置方式实现（类似系统 Hosts），并支持分组管理
-	* 项目可以自带代理规则配置并一键设置到本地 Whistle 代理，也可以通过定制插件简化操作
+<img width="1200" alt="network" src="https://github.com/user-attachments/assets/3186e76a-486a-4e61-98a1-2d4b4f91fad0" />
 
-# 一键安装
-> 已安装 `brew` 的 PC，可以省略以下 1、2 步骤，直接通过以下方式一键安装：`brew install whistle && w2 start --init`
+<img width="1200" alt="rules" src="https://github.com/user-attachments/assets/2e336403-4810-48e5-91c1-6f22dcda7388" />
 
-1. 安装 Node（建议安装**最新的 LTS 版本**，如已安装忽略此步骤）：https://nodejs.org/
-2. 一键安装，在命令行执行以下命令：
-	``` sh
-	npm i -g whistle && w2 start --init
-	```
-	> 上述命令会先全局安装 Whistle 的 npm 包后，启动 Whistle 并设置系统全局代理，以及安装系统根证书，目前一键安装只支持 Mac & Windows 系统，其它系统按照下面 **手动安装** 的方式操作。
-	>
-	> 如果安装过程时报错 `Bad CPU type in executable`，在命令执行 `arch -x86_64 zsh` 再重新执行一键安装命令。
-3. 一键安装过程中注意事项：
-	* Mac 需要两次输入开机密码或指纹验证
-		<p>
-			<img alt="输入开机密码" width="330" src="https://user-images.githubusercontent.com/11450939/176977027-4a7b06a0-64f6-4580-b983-312515e9cd4e.png">
-		</p>
-		<img alt="输入指纹" width="330" src="https://user-images.githubusercontent.com/11450939/168847123-e66845d0-6002-4f24-874f-b6943f7f376b.png">
+其中，Network 为查看抓包界面，Rules 为配置规则，Values 为配置数据界面（配合 Rules 使用），Plugins 为已安装的插件列表。
 
-	* Windows 需要最后点击 “是(Y)” 确认
+### 界面功能
 
-		<img alt="点击 是(Y)" width="420" src="https://user-images.githubusercontent.com/11450939/168846905-384e0540-e02f-46de-81d7-e395a496f032.jpeg">
+<details>
+  <summary>重放请求</summary>
+  <img width="800" alt="image" src="https://github.com/user-attachments/assets/9f8276ac-e089-427b-97f4-becac250ae5e" />
+</details>
 
-如果需要自定义代理配置或根证书（如设置其它代理，根证书或代理白名单等）可以通过以下命令实现：
-1. `w2 proxy` 设置系统全局代理：https://wproxy.org/whistle/proxy.html
-2. `w2 ca` 设置系统根证书：https://wproxy.org/whistle/proxy.html
+<details>
+  <summary>编辑或构造请求</summary>
+  <img width="1200" alt="image" src="https://github.com/user-attachments/assets/f2a5b088-72b6-4098-8ba6-3e42f15f3ad8" />
+</details>
 
-也可以用下面 **手动安装** 方式。
-### 手动安装
-非 Mac & Windows 系统或一键安装失败可以按下面方式设置代理和安装根证书：
+其它界面功能参见完整文档：https://wproxy.org/whistle/webui/
 
-1. 设置代理：https://wproxy.org/whistle/install.html
-2. 安装根证书：https://wproxy.org/whistle/webui/https.html
+### 规则功能
 
-# 快速上手
-安装成功后，用 Chrome 打开链接 http://local.whistlejs.com 即可看到 Whistle 的抓包配置界面：
+Whistle 规则可看成是如下系统 hosts 规则的扩展：
 
-<img width="800" alt="抓包界面" src="https://user-images.githubusercontent.com/11450939/169521501-58e59e1b-1970-477c-a213-f28234628e4b.png">
+``` txt
+# 一个域名对应一个 IP
+127.0.0.1 localhost
+::1 localhost
+# 多个域名对应一个 IP
+10.2.55.3 www.test.com www.example.com
+```
 
-<img width="800" alt="image" src="https://user-images.githubusercontent.com/11450939/169634452-64e7bf4b-4cb1-4289-9ba2-3c1913d6c2dd.png">
+系统 hosts 规则的功能单一，只支持修改 DNS及匹配域名，且有 DNS 缓存问题，无法满足日常工作需求，Whistle 规则扩展了系统 hosts 规则的功能，匹配方式上不仅支持域名匹配、路径匹配、通配符匹配、正则匹配等，还支持通过请求方法，响应状态码、请求（响应）头、请求内容等进一步过滤；功能上不仅支持修改 DNS，还支持修改端口，CNAME，设置代理，修改请求 URL、请求方法、响应状态码、请求头、响应头、请求内容、响应内容等，理论上可以修改 HTTP 请求的所有东西，Whistle 规则格式为：
 
+1. 默认格式
 
-### 详细用法参见：[Whistle 帮助文档](https://wproxy.org/whistle/quickstart.html)
+   ``` txt
+   pattern operation
+   ```
 
-# 通过 SwitchyOmega 设置代理
-### 安装 SwitchyOmega
-打开 Chrome 扩展商店进行安装 https://chrome.google.com/webstore/detail/proxy-switchyomega/padekgcemlokbadohgkifijomclgjgif
+2. 支持匹配多个操作
 
-### 配置 SwitchyOmega
-全局代理如果会影响到某些客户端的请求（客户端设置了 ssl pinning），也可以使用 Chrome 插件设置代理（只对 Chrome 生效）：
-> 可以通过 `w2 proxy off` 关闭全局代理
+   ``` txt
+   pattern operation1 operation2 ...
+   ```
 
-1. 设置 Whistle 代理
+3. 支持过滤器
 
-    <img src="https://user-images.githubusercontent.com/11450939/36636618-132bb09e-1a05-11e8-8514-813fd34a5454.png" width="800" />
-2. 选择 Whistle 代理
+   ``` txt
+   pattern operation1 operation2 ... includeFilter://filterPattern1 ... excludeFilter://filterPatternN ...
+   ```
 
-    <img width="180" alt="image" src="https://user-images.githubusercontent.com/11450939/173984519-143615b2-2a99-4486-a22a-fec71fe00423.png">
+   > 多个 filter 之间是 或 的关系，即满足其中一个条件即可
 
-# 安全设置
-1. 通过启动参数给管理界面设置用户名密码：`w2 restart -n yourusername -w yourpassword`
-2. 通过插件给经过代理的请求设置用户名密码：https://github.com/whistle-plugins/whistle.proxyauth
+4. 支持位置调换（前提：operation 与 pattern 不同时为 URL 或域名）
+
+   ``` txt
+   operation pattern [filters...]
+   operation pattern1 pattern2 ... [filters...]
+   ```
+
+5. 支持换行
+
+   ``` txt
+   line`
+   operation
+   pattern1
+   pattern2 ...
+   [filters...]
+   `
+   ```
+
+具体例子如下：
+
+##### 修改 DNS（设置 Hosts）
+
+1. 域名匹配
+
+   ``` txt
+   www.test.com 127.0.0.1
+   # 支持带端口
+   www.test.com 127.0.0.1:8080
+   # CNAME 功能（端口可选）
+   www.test.com host://www.example.com:8181
+   ```
+
+   > 与系统 hosts 规则不同的是 Whistle 规则默认采用**从左到右的映射方式**，**从上到下的优先级**，但在 operation 与 pattern 不同时为 URL 或域名情况下可调换位置，所以也兼容系统 hosts 规则，即：`127.0.0.1:8080 www.test.com`
+
+2. 路径匹配
+
+   ``` txt
+   www.test.com/path/to 127.0.0.1:8080
+   # 支持带协议
+   https://www.test.com/path/to 127.0.0.1:8080
+   ```
+
+3. 通配符匹配
+
+   ``` txt
+   # 域名通配符，匹配 test.com 的所有子代域名
+   **.test.com 127.0.0.1:8080
+   # 支持带协议域名通配符
+   https://**.test.com 127.0.0.1:8080
+   # 路径通配符（* 是路径的合法字符，所以前面要加 ^ 告诉 Whistle 是通配符）
+   ^**.test.com/*/path/to 127.0.0.1:8080
+   # 支持带协议路径通配符
+   ^https://**.test.com/*/path/to 127.0.0.1:8080
+   ```
+
+   >  `*`、`**`、`***` 匹配的范围不同，详情参见完整文档：https://wproxy.org/whistle/pattern.html
+
+4. 正则匹配
+
+   ``` txt
+   # 内部的 `/` 可以不转义，等价于 `new RegExp('^https?://\w+\.test\.com')`
+   /^https?://\w+\.test\.com/ 127.0.0.1:8080
+   ```
+
+5. 过滤匹配
+
+   ``` txt
+   # `pattern` 同上面的域名、路径、正则，表示除了匹配 `pattern` 还要满足请求头 `cookie` 包含 `env=test`
+   pattern 127.0.0.1:8080 includeFilter://reqH.cookie=/env=test/
+   ```
+
+##### 修改表单数据
+
+``` txt
+# 修改表单里面的 `test` 字段的值
+pattern reqMerge://test=123
+
+# 删除表单里面的 `abc` 字段
+pattern delete://reqBody.abc
+```
+
+#####  设置跨域响应头
+
+``` txt
+# 以路径匹配为例，设置跨域响应头 Access-Control-Allow-Origin: *，且排除 OPTION 请求
+pattern resCors://* excludeFilter://m:option
+```
+
+
+所有规则参见完整文档：https://wproxy.org/whistle/rules/
+
+### 安装插件
+
+插件需通过命令行安装：
+
+``` sh
+w2 i whistle.inspect whistle.vase
+```
+
+> 上述插功能介绍及源码：[https://github.com/whistle-plugins](https://github.com/whistle-plugins)，客户端可通过界面安装 ：[https://github.com/avwo/whistle-client](https://github.com/avwo/whistle-client)
+
+安装后即可在管理界面的 Plugins 看到这两个插件：
+
+<details>
+  <summary>插件列表示例图</summary>
+  <img width="1000" alt="image" src="https://github.com/user-attachments/assets/ec018691-c7a9-415e-9809-bf079694c024" />
+</details>
+
+每个插件默认可以新增两个规则协议：
+
+``` txt
+whistle.inspect://xxx
+inspect://xxx
+```
+
+> 通过配置插件的自定义规则，可将匹配的请求转发到插件指定 hook 实现自定义功能，如果不需要也可通过插件的 `package.json ` 的 ` whistleConfig` 设置 `"hideLongProtocol": true` 或 `"hideShortProtocol": true` 隐藏对应规则协议
+
+除了扩展规则，插件还支持扩展 Whistle 界面，以及提供操作界面、自带规则等功能，关于插件的安装、使用、开发参见完整文档：https://wproxy.org/whistle/plugins.html
 
 # License
+
 [MIT](./LICENSE)
+