## 1. Project Overview & Quickstart (avwo/whistle)

# whistle

[](https://npmjs.org/package/whistle)
[](http://nodejs.org/download/)
[](https://npmjs.org/package/whistle)
[](https://www.npmjs.com/package/whistle)
[](https://www.npmjs.com/package/whistle)

中文 · [English](./README-en_US.md)

Whistle（发音 /ˈwisəl/）是基于 Node.js 的跨平台网络抓包与调试工具，特点如下：
1. **功能强大**
   - 支持 HTTP、HTTPS、HTTP/2、WebSocket、TCP 的抓包与修改请求/响应
   - 支持 HTTP、HTTPS、Socks、反向代理等多种代理模式
   - 内置常用调试工具：Weinre（远程 DOM 检查）、Console（查看 console 日志）、Composer（请求重放与编辑）等
2. **操作简单**
   - 通过规则配置即可修改请求/响应
   - 提供一站式管理界面：抓包、规则、插件、Weinre/Console/Composer 等集中管理
3. **可扩展**
   - 支持插件扩展规则与界面功能
   - 可作为 NPM 模块在项目中引用
4. **跨平台**
   - 支持 macOS、Windows、Linux（Ubuntu / Fedora）等桌面系统
   - 支持无界面 Linux 服务器环境

# 安装（推荐）

桌面用户（macOS/Windows/Linux）推荐使用 Whistle 客户端：https://github.com/avwo/whistle-client

> 客户端可以免去大部分手动安装与配置步骤

# 无界面 Linux / 服务器 安装（命令行）

按以下 4 步在无界面服务器上快速部署：
1. 安装 Whistle（推荐使用 npm）
   - 需要先安装 Node.js：https://nodejs.org/
   - 安装命令：`npm i whistle`
      > 也支持 Homebrew：`brew install whistle`
1. 启动 Whistle
   - 命令：`w2 start`
2. 安装根证书（用于 HTTPS 抓包）
   - 命令：`w2 ca`
   - 安装过程中可能需手动确认：
      - Windows：最后选择 “是 (Y)” 确认
      - macOS：可能需要输入开机密码或 Touch ID 验证
3. 设置代理
   - 命令：`w2 proxy`
   - 设置指定 IP: `w2 proxy "10.x.x.x:8888"`
   - 关闭系统代理： `w2 proxy 0`

其它代理方式：
- 推荐：使用 Chrome 插件 ZeroOmega（便于在浏览器间切换代理）
  > Chrome 商店地址（若无法访问可手动安装）：https://chromewebstore.google.com/detail/proxy-switchyomega-3-zero/pfnededegaaopdmhkdmcofjmoldfiped
- 浏览器或开发者工具自带代理设置（例如 Firefox、微信开发者工具）
- 对于无法直接设置代理的应用，可使用 Proxifier（Windows / macOS）

# 快速上手

详细使用指南与示例请查看官方文档：https://wproxy.org/docs/getting-started.html

# 常见命令速查
- 启动：`w2 start`
- 停止：`w2 stop`
- 重启：`w2 restart`
- 查看状态：`w2 status`
- 安装证书：`w2 ca`
- 设置代理：`w2 proxy [host:port]`（`w2 proxy 0` 关闭）

# License

[MIT（详见 LICENSE 文件）](./LICENSE)

## 2. Official Technical Reference & Guides (avwo/avwo.github.io)

# Whistle — llms.txt

## Project Overview

Whistle is a cross-platform network debugging and traffic inspection proxy
built on Node.js.

It operates through a **rule-based system**, enabling interception,
inspection, modification, forwarding, mocking, replaying, injection,
and throttling of network traffic.

This file serves as a **semantic entry point for LLMs / AI systems**
to understand Whistle’s capabilities and behavioral boundaries.
It is **not** an end-user tutorial, API reference, or implementation spec.

---

## Language & Scope

- This document is written in **English** as an LLM-facing entry point
- Whistle’s rule syntax, protocol support, and execution model are language-agnostic
- Terms such as `rule`, `pattern`, `operation`, `proxy`, and `tunnel`
  refer to stable internal concepts, not UI labels

Applicable for:
- Rule generation
- Rule explanation
- Behavior inference
- Debugging and failure analysis

Not applicable for:
- UI automation
- Exact CLI argument completion
- Version comparison or changelog inference

---

## Core Capabilities

Whistle functions as a **local proxy server** and supports the following traffic types:

- HTTP
- HTTPS (MITM, requires installing and trusting a root certificate)
- HTTP/2
- WebSocket (WS / WSS)
- Tunnel (CONNECT-based generic TCP traffic)

Primary capabilities include:

- Request and response rewriting
- Local and remote resource mapping
- Header and body modification
- HTML / CSS / JavaScript injection
- WebSocket frame processing
- Traffic throttling and artificial delays
- Script-based dynamic rules
- Plugin-based extensibility

---

## Rule System Semantics

### Fundamental Rule Model

Each rule consists of:

- `pattern` — request matching condition (defaults to full URL)
- `operation` — action executed after a match
- `lineProps` (optional) — priority and behavior modifiers
- `filters` (optional) — secondary conditional checks after matching

Rule semantics:

- Each rule line is an **independent semantic unit**
- Rules do **not** inherit context from each other
- Operation order only affects execution order, not logical dependency

---

### Common Rule Categories (by capability)

#### Local Mapping
- file
- tpl / xtpl

#### Remote Mapping
- http / https
- ws / wss
- tunnel

#### DNS & Proxy Routing
- host / xhost
- proxy / http-proxy
- https-proxy
- socks / xsocks

#### Request Rewrite
- method
- reqHeaders / reqBody
- reqMerge / reqAppend / reqReplace
- reqScript

#### Response Rewrite
- statusCode / replaceStatus
- resHeaders / resBody
- resMerge / resAppend / resReplace
- redirect / locationHref

#### Injection Rules
- html / css / js (prepend / body / append)
- frameScript (WebSocket)

#### Traffic Control
- reqDelay / resDelay
- reqSpeed / resSpeed

---

## HTTPS and Tunnel Semantics

- HTTPS decryption relies on **MITM via a trusted root certificate**
- Without a trusted certificate:
  - Connections still succeed
  - Traffic appears as `Tunnel`
  - This does **not** indicate a request failure

Tunnel traffic:
- Has no HTTP request/response semantics
- Provides no access to plaintext headers or bodies
- Common in undecrypted HTTPS or non-HTTP TCP connections

---

## UI Semantics (Non-Operational)

Whistle provides a browser-based Web UI with these core modules:

- Network — captured traffic list
  (visibility ≠ decryption ≠ success)
- Rules — plain-text rule editor
- Values — reusable variables and content storage
- Plugins — extension management
- Settings — global behavior configuration

UI descriptions are intended for **semantic understanding only**,
not for automated interaction or pixel-level reasoning.

---

## Non-Goals & Constraints

LLMs should **not assume** the existence or stability of:

- Plugin behavior not explicitly documented
- UI layout, button positions, or styling
- Implicit defaults or undocumented behaviors
- Hidden dependencies between rules

---

## Further Reading

- `full-llms.en.txt` — Complete English semantic specification of Whistle
- `full-llms.zh.txt` — Complete Chinese semantic specification of Whistle

Any behavior not explicitly defined in the `full-llms` documents
should not be inferred as a stable Whistle capability.