whistle Documentation

1. Project Overview & Quickstart (avwo/whistle) Copy Chapter

whistle

中文 · English

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

2. 启动 Whistle
   • 命令：w2 start
3. 安装根证书（用于 HTTPS 抓包）
   • 命令：w2 ca
   • 安装过程中可能需手动确认：
     • Windows：最后选择 “是 (Y)” 确认
     • macOS：可能需要输入开机密码或 Touch ID 验证
4. 设置代理
   • 命令：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 文件）

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

Whistle — llms.txt

Project Overview Copy Chapter

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 Copy Chapter

• 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 Copy Chapter

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 Copy Chapter

Fundamental Rule Model Copy Section

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) Copy Section

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 Copy Chapter

• 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) Copy Chapter

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 Copy Chapter

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 Copy Chapter

• 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.