Whistle Plugin for PasteKit Lab

这是一个 whistle 插件，用于拦截 HTTP/HTTPS 请求并通过 WebSocket 发送到 requestlistviewer 进行展示。

功能特性

• ✅ 拦截所有 HTTP/HTTPS 请求和响应
• ✅ 通过 WebSocket 实时推送请求数据到 requestlistviewer
• ✅ 支持域名过滤配置
• ✅ 支持 Mock 规则匹配
• ✅ 自动重连机制
• ✅ 完整的请求/响应数据捕获（包括 headers、body）

架构说明

┌─────────────┐         ┌──────────────┐         ┌─────────────────┐
│   Browser   │────────▶│   Whistle    │────────▶│ WebSocket Server│
│             │         │   + Plugin   │         │   (Port 8889)   │
└─────────────┘         └──────────────┘         └────────┬────────┘
                                                           │
                                                           │ WebSocket
                                                           │
                                                           ▼
                                                  ┌─────────────────┐
                                                  │requestlistviewer│
                                                  │   (UI Display)  │
                                                  └─────────────────┘

安装步骤

1. 安装依赖

cd plugins/whistle
npm install

2. 安装 whistle（如果未安装）

npm install -g whistle

3. 启动插件

node start-plugin.js

该脚本会自动：

• 检查 whistle 是否已安装
• 将插件链接到 whistle 插件目录
• 重启 whistle 服务
• 显示使用说明

4. 配置 whistle 规则

在浏览器中打开 Whistle 界面：http://127.0.0.1:8899

在 Rules 标签中添加以下规则：

# PasteKit Lab 拦截规则
http://*.* pastekitlab
https://*.* pastekitlab

或者只拦截特定域名：

# 只拦截特定域名
http://api.example.com/* pastekitlab
https://api.example.com/* pastekitlab

5. 启动 requestlistviewer

确保在 PasteKit Lab 的 Options 页面中打开了 requestlistviewer 组件，它会自动连接到 ws://127.0.0.1:8889。

使用方法

基本使用

1. 启动插件：node start-plugin.js
2. 配置 whistle 规则（如上所述）
3. 打开 requestlistviewer
4. 开始浏览网页，请求将自动显示在 requestlistviewer 中

查看日志

w2 log

停止 Whistle

w2 stop

重启 Whistle

w2 restart

消息协议

插件 → requestlistviewer

MOCK 消息（请求）

{
  "msgType": "MOCK",
  "eventId": "req_1234567890_abc123",
  "url": "https://api.example.com/data",
  "method": "POST",
  "requestHeaders": {
    "content-type": "application/json",
    ...
  },
  "requestBody": "{\"key\":\"value\"}",
  "requestBodyBase64": "eyJrZXkiOiJ2YWx1ZSJ9",
  "timestamp": 1234567890123
}

RESPONSE 消息（响应）

{
  "msgType": "RESPONSE",
  "eventId": "req_1234567890_abc123",
  "url": "https://api.example.com/data",
  "method": "POST",
  "statusCode": 200,
  "responseHeaders": {
    "content-type": "application/json",
    ...
  },
  "responseBody": "{\"result\":\"success\"}",
  "responseBodyBase64": "eyJyZXN1bHQiOiJzdWNjZXNzIn0=",
  "timestamp": 1234567890456
}

requestlistviewer → 插件

domain 消息（域名配置）

{
  "msgType": "domain",
  "domain": ["api.example.com", "test.example.com"],
  "mockUrls": ["/api/mock/*"]
}

MOCK_RESPONSE 消息（Mock 响应）

{
  "msgType": "MOCK_RESPONSE",
  "requestId": "req_1234567890_abc123",
  "responseBody": "{\"mocked\":true}"
}

UNMOCK 消息（未 Mock 标记）

{
  "msgType": "UNMOCK",
  "requestId": "req_1234567890_abc123"
}

配置选项

在 index.js 中可以修改以下配置：

const CONFIG = {
    // WebSocket 服务器端口（与 requestlistviewer 连接的端口一致）
    wsPort: 8889,
    // 是否启用日志
    logEnabled: true,
    // 是否启用插件
    enabled: true,
    // 最大连接数
    maxConnections: 10
};

故障排查

问题 1：WebSocket 连接失败

症状：requestlistviewer 显示 "disconnected"

解决方案：

1. 检查插件是否正常运行：w2 log
2. 确认端口 8889 未被占用：lsof -i :8889
3. 重启插件：w2 restart

问题 2：请求未被拦截

症状：浏览网页但 requestlistviewer 无数据显示

解决方案：

1. 检查 whistle 规则是否正确配置
2. 确认浏览器代理设置指向 whistle（默认 127.0.0.1:8899）
3. 检查插件是否启用：查看 CONFIG.enabled 是否为 true

问题 3：插件加载失败

症状：whistle 日志显示插件错误

解决方案：

1. 检查依赖是否安装：npm install
2. 验证插件路径是否正确
3. 查看完整错误日志：w2 log

开发调试

热重载开发

npm run dev

查看实时日志

w2 log | grep "Whistle Plugin"

测试 WebSocket 连接

# 使用 wscat 测试
npm install -g wscat
wscat -c ws://127.0.0.1:8889

文件结构

plugins/whistle/
├── index.js              # 插件主文件
├── package.json          # 插件配置和依赖
├── start-plugin.js       # 启动脚本
└── README.md            # 本文档

注意事项

1. 证书问题：拦截 HTTPS 请求需要安装 whistle 的根证书

   • 访问 http://127.0.0.1:8899 下载证书
   • 在系统中信任该证书

2. 性能考虑：大量请求可能影响性能，建议在生产环境谨慎使用

3. 数据安全：插件会捕获所有请求数据，请确保在可信环境中使用

4. 端口冲突：确保端口 8889 未被其他程序占用

许可证

MIT License

相关链接

• Whistle 官方文档
• PasteKit Lab
• ws 库文档