whistle.pastekitlab 1.0.0

package/EXAMPLES.md

@@ -0,0 +1,254 @@
+# 使用示例
+
+## 场景 1：拦截所有请求
+
+### whistle 规则配置
+```
+http://*.* pastekitlab
+https://*.* pastekitlab
+```
+
+### 效果
+- 所有 HTTP/HTTPS 请求都会被拦截
+- 请求和响应数据实时显示在 requestlistviewer 中
+- 适合全局调试和监控
+
+---
+
+## 场景 2：只拦截特定域名
+
+### whistle 规则配置
+```
+http://api.example.com/* pastekitlab
+https://api.example.com/* pastekitlab
+http://test.example.com/* pastekitlab
+https://test.example.com/* pastekitlab
+```
+
+### 效果
+- 只拦截指定域名的请求
+- 减少不必要的干扰
+- 提高性能
+
+---
+
+## 场景 3：拦截特定路径
+
+### whistle 规则配置
+```
+http://api.example.com/api/v1/* pastekitlab
+https://api.example.com/api/v1/* pastekitlab
+```
+
+### 效果
+- 只拦截特定 API 路径
+- 精确控制拦截范围
+- 适合调试特定接口
+
+---
+
+## 场景 4：排除某些域名
+
+### whistle 规则配置
+```
+# 先排除不需要拦截的域名
+http://exclude.com/* exclude
+https://exclude.com/* exclude
+
+# 然后拦截其他所有请求
+http://*.* pastekitlab
+https://*.* pastekitlab
+```
+
+### 效果
+- 排除敏感或不需要的域名
+- 拦截其他所有请求
+- 灵活控制拦截范围
+
+---
+
+## 场景 5：结合 Mock 使用
+
+### 步骤
+
+1. **在 PasteKit Lab 中配置 Mock 规则**
+   - 打开 Options 页面
+   - 进入 Mock Manager
+   - 添加 Mock 规则，例如：
+     - URL Pattern: `/api/users`
+     - Method: `GET`
+     - Response: `{"users": [...]}`
+
+2. **配置 whistle 规则**
+   ```
+   http://api.example.com/* pastekitlab
+   https://api.example.com/* pastekitlab
+   ```
+
+3. **启用 Mock**
+   - 在 Mock Manager 中启用该规则
+   - requestlistviewer 会自动发送域名配置到 whistle 插件
+
+4. **测试**
+   - 访问 `http://api.example.com/api/users`
+   - 看到返回的是 Mock 数据
+   - requestlistviewer 中显示 🎭 MOCK 标记
+
+---
+
+## 场景 6：调试加密请求
+
+### 步骤
+
+1. **配置解密规则**
+   - 在 PasteKit Lab 中配置域名解密规则
+   - 设置请求和响应的密钥配置
+
+2. **配置 whistle 规则**
+   ```
+   http://encrypted-api.com/* pastekitlab
+   https://encrypted-api.com/* pastekitlab
+   ```
+
+3. **查看解密结果**
+   - 浏览网页触发请求
+   - requestlistviewer 自动解密并显示明文
+   - 可以看到 ✓ Request Decrypted 和 ✓ Response Decrypted 标记
+
+---
+
+## 场景 7：多客户端同时连接
+
+### 说明
+whistle 插件支持多个客户端同时连接（默认最多 10 个）
+
+### 使用场景
+- 多个开发者同时查看请求
+- 不同的视图展示相同的数据
+- 开发和测试环境并行
+
+### 配置
+在 `index.js` 中修改：
+```javascript
+const CONFIG = {
+    maxConnections: 20 // 增加最大连接数
+};
+```
+
+---
+
+## 常见问题示例
+
+### Q1: 如何查看 WebSocket 连接状态？
+
+在浏览器控制台查看：
+```javascript
+// requestlistviewer 会输出连接状态
+[RequestList Viewer] 📊 检查连接状态：isConnected = true
+```
+
+### Q2: 如何确认请求被拦截？
+
+查看 whistle 日志：
+```bash
+w2 log | grep "Whistle Plugin"
+```
+
+应该看到：
+```
+[Whistle Plugin] 拦截请求：GET https://api.example.com/data
+[Whistle Plugin] 拦截响应：200 https://api.example.com/data
+```
+
+### Q3: 如何测试 WebSocket 连接？
+
+```bash
+cd plugins/whistle
+npm test
+```
+
+应该看到：
+```
+✅ WebSocket 连接成功！
+📨 收到消息：{ "msgType": "connected", "clientId": 1, ... }
+```
+
+### Q4: 请求未显示在 requestlistviewer 中？
+
+检查清单：
+1. ✅ whistle 插件已启动
+2. ✅ whistle 规则已配置
+3. ✅ requestlistviewer 已连接到 ws://127.0.0.1:8889/ws
+4. ✅ 浏览器代理指向 whistle (127.0.0.1:8899)
+5. ✅ HTTPS 证书已安装并信任
+
+### Q5: 如何过滤特定请求？
+
+在 requestlistviewer 中使用搜索框：
+- 输入 URL 关键词
+- 输入 HTTP 方法（GET, POST 等）
+- 输入状态码（200, 404 等）
+
+---
+
+## 高级用法
+
+### 自定义消息处理
+
+在 whistle 插件中添加自定义逻辑：
+
+```javascript
+// 在 beforeRequest 中
+beforeRequest: function(req, res, next) {
+    // 添加自定义逻辑
+    if (req.url.includes('/sensitive')) {
+        // 跳过敏感请求
+        return next();
+    }
+    
+    // 正常处理
+    // ...
+}
+```
+
+### 性能优化
+
+对于高流量场景：
+
+1. **限制拦截范围**
+   ```
+   # 只拦截必要的域名
+   http://api.example.com/* pastekitlab
+   ```
+
+2. **禁用日志**
+   ```javascript
+   const CONFIG = {
+       logEnabled: false // 减少日志输出
+   };
+   ```
+
+3. **调整缓冲区大小**
+   ```javascript
+   wss = new WebSocket.Server({ 
+       maxPayload: 50 * 1024 * 1024 // 增加到 50MB
+   });
+   ```
+
+---
+
+## 最佳实践
+
+1. **开发环境**：拦截所有请求，全面监控
+2. **测试环境**：只拦截测试域名，减少干扰
+3. **生产环境**：谨慎使用，注意性能和隐私
+4. **团队协作**：共享 whistle 规则配置
+5. **定期清理**：清除 requestlistviewer 中的旧数据
+
+---
+
+## 相关资源
+
+- [Whistle 官方文档](https://github.com/avwo/whistle)
+- [PasteKit Lab 文档](../../README.md)
+- [WebSocket 协议](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)

package/IMPLEMENTATION.md

@@ -0,0 +1,388 @@
+# Whistle 插件实现说明
+
+## 概述
+
+本插件实现了 whistle 与 PasteKit Lab requestlistviewer 之间的 WebSocket 通信，用于实时展示拦截的 HTTP/HTTPS 请求。
+
+## 架构设计
+
+### 组件关系
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Browser (Client)                        │
+│                     - Chrome/Firefox/etc                    │
+└──────────────────────┬──────────────────────────────────────┘
+                       │ HTTP/HTTPS Requests
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Whistle Proxy Server                      │
+│                     Port: 8899                              │
+│                                                             │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │         PasteKit Lab Plugin (index.js)               │  │
+│  │                                                       │  │
+│  │  • beforeRequest: 拦截请求                            │  │
+│  │  • afterResponse: 拦截响应                            │  │
+│  │  • WebSocket Server: ws://0.0.0.0:8889/ws            │  │
+│  └──────────────────┬───────────────────────────────────┘  │
+└─────────────────────┼──────────────────────────────────────┘
+                      │ WebSocket Messages
+                      │ (MOCK, RESPONSE, domain, etc.)
+                      ▼
+┌─────────────────────────────────────────────────────────────┐
+│              PasteKit Lab Extension                         │
+│                                                             │
+│  ┌────────────────────────────────────────────────────┐    │
+│  │   requestlistviewer.jsx                            │    │
+│  │                                                     │    │
+│  │   • ProxyWebSocketClient                           │    │
+│  │   • 连接到 ws://127.0.0.1:8889/ws                  │    │
+│  │   • 接收 MOCK/RESPONSE 消息                        │    │
+│  │   • 解密请求/响应                                   │    │
+│  │   • 展示在 UI 中                                    │    │
+│  └────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 核心功能
+
+### 1. WebSocket 服务器
+
+**位置**: `plugins/whistle/index.js`
+
+**功能**:
+- 监听端口 8889
+- 路径: `/ws`
+- 支持多客户端连接（默认最多 10 个）
+- 自动管理客户端生命周期
+
+**关键代码**:
+```javascript
+wss = new WebSocket.Server({ 
+    port: CONFIG.wsPort,
+    path: '/ws',
+    maxPayload: 10 * 1024 * 1024
+});
+
+wss.on('connection', (ws, req) => {
+    const clientId = ++clientIdCounter;
+    clients.set(clientId, { id: clientId, ws: ws, ... });
+    
+    // 发送欢迎消息
+    ws.send(JSON.stringify({
+        msgType: 'connected',
+        clientId: clientId,
+        timestamp: Date.now()
+    }));
+});
+```
+
+### 2. 请求拦截
+
+**Whistle 钩子**: `beforeRequest`
+
+**流程**:
+1. 生成唯一的 requestId
+2. 提取请求信息（URL、Method、Headers、Body）
+3. 将 Body 转换为字符串和 Base64
+4. 广播 MOCK 消息给所有客户端
+5. 保存请求信息用于后续关联响应
+
+**数据结构**:
+```javascript
+{
+    eventId: "req_1234567890_abc123",
+    url: "https://api.example.com/data",
+    method: "POST",
+    requestHeaders: { ... },
+    requestBody: "{\"key\":\"value\"}",
+    requestBodyBase64: "eyJrZXkiOiJ2YWx1ZSJ9",
+    timestamp: 1234567890123
+}
+```
+
+### 3. 响应拦截
+
+**Whistle 钩子**: `afterResponse`
+
+**流程**:
+1. 提取响应信息（StatusCode、Headers、Body）
+2. 查找对应的请求 ID（通过 URL 和时间匹配）
+3. 将 Body 转换为字符串和 Base64
+4. 广播 RESPONSE 消息给所有客户端
+
+**数据结构**:
+```javascript
+{
+    eventId: "req_1234567890_abc123",
+    url: "https://api.example.com/data",
+    method: "POST",
+    statusCode: 200,
+    responseHeaders: { ... },
+    responseBody: "{\"result\":\"success\"}",
+    responseBodyBase64: "eyJyZXN1bHQiOiJzdWNjZXNzIn0=",
+    timestamp: 1234567890456
+}
+```
+
+### 4. 域名配置管理
+
+**消息类型**: `domain`
+
+**流程**:
+1. requestlistviewer 发送域名配置
+2. 插件保存配置到对应客户端
+3. 可用于后续的过滤逻辑
+
+**数据结构**:
+```javascript
+{
+    msgType: "domain",
+    domain: ["api.example.com", "test.example.com"],
+    mockUrls: ["/api/mock/*"]
+}
+```
+
+### 5. 消息广播
+
+**函数**: `broadcastToClients(msgType, data)`
+
+**功能**:
+- 遍历所有连接的客户端
+- 检查 WebSocket 状态
+- 发送 JSON 格式的消息
+- 处理发送错误
+
+**实现**:
+```javascript
+function broadcastToClients(msgType, data) {
+    const message = JSON.stringify({
+        msgType: msgType,
+        ...data,
+        timestamp: Date.now()
+    });
+
+    clients.forEach((client, clientId) => {
+        if (client.ws.readyState === WebSocket.OPEN) {
+            client.ws.send(message);
+        }
+    });
+}
+```
+
+## 消息协议
+
+### 插件 → 客户端
+
+| 消息类型 | 说明 | 触发时机 |
+|---------|------|---------|
+| `connected` | 连接成功 | 客户端连接时 |
+| `MOCK` | 请求数据 | 拦截到 HTTP 请求 |
+| `RESPONSE` | 响应数据 | 拦截到 HTTP 响应 |
+
+### 客户端 → 插件
+
+| 消息类型 | 说明 | 用途 |
+|---------|------|------|
+| `domain` | 域名配置 | 设置需要拦截的域名和 Mock URL |
+| `MOCK_RESPONSE` | Mock 响应 | 客户端返回的 Mock 数据 |
+| `UNMOCK` | 未 Mock 标记 | 标记请求未使用 Mock |
+
+## 关键技术点
+
+### 1. Buffer 处理
+
+**问题**: whistle 中的请求/响应体是 Buffer 格式
+
+**解决方案**:
+```javascript
+// 转换为字符串（检查是否为文本）
+function bufferToString(buffer) {
+    const result = buffer.toString('utf8');
+    if (/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/.test(result)) {
+        return null; // 二进制数据
+    }
+    return result;
+}
+
+// 转换为 Base64（用于二进制数据）
+function bufferToBase64(buffer) {
+    return buffer.toString('base64');
+}
+```
+
+### 2. 请求-响应关联
+
+**挑战**: whistle 的 beforeRequest 和 afterResponse 是分开的
+
+**解决方案**:
+```javascript
+// 在 beforeRequest 中保存请求
+requestMap.set(requestId, { requestData, startTime });
+
+// 在 afterResponse 中查找
+for (const [id, data] of requestMap.entries()) {
+    if (data.requestData.url === url && 
+        Math.abs(Date.now() - data.startTime) < 30000) {
+        requestId = id;
+        requestMap.delete(id);
+        break;
+    }
+}
+```
+
+### 3. 多客户端支持
+
+**实现**:
+```javascript
+let clients = new Map();
+
+wss.on('connection', (ws, req) => {
+    const clientId = ++clientIdCounter;
+    clients.set(clientId, { id: clientId, ws, ... });
+});
+
+ws.on('close', () => {
+    clients.delete(clientId);
+});
+```
+
+### 4. 错误处理
+
+**策略**:
+- 所有异步操作都有 try-catch
+- WebSocket 错误不会导致插件崩溃
+- 详细的日志记录便于调试
+
+## 文件结构
+
+```
+plugins/whistle/
+├── index.js              # 插件主文件（351 行）
+│   ├── 配置部分
+│   ├── 工具函数
+│   ├── WebSocket 服务器
+│   ├── 消息处理
+│   └── Whistle 插件接口
+│
+├── package.json          # 依赖和脚本配置
+├── start-plugin.js       # 启动脚本（129 行）
+│   ├── 检查 whistle
+│   ├── 安装插件
+│   ├── 重启服务
+│   └── 显示使用说明
+│
+├── test-ws.js           # WebSocket 测试脚本（64 行）
+├── README.md            # 完整文档（275 行）
+├── QUICKSTART.md        # 快速开始指南（66 行）
+├── EXAMPLES.md          # 使用示例（255 行）
+├── IMPLEMENTATION.md    # 本文档
+└── .gitignore           # Git 忽略配置
+```
+
+## 性能考虑
+
+### 1. 内存管理
+- 请求映射表有清理机制（30秒超时）
+- 客户端断开时自动清理
+- 限制最大负载为 10MB
+
+### 2. 并发控制
+- 限制最大连接数为 10
+- WebSocket 消息队列由 ws 库管理
+- 异步处理避免阻塞
+
+### 3. 网络优化
+- JSON 序列化在发送前完成
+- 批量广播减少系统调用
+- 连接状态检查避免无效发送
+
+## 安全考虑
+
+### 1. 数据安全
+- 只在本地运行（127.0.0.1）
+- 不持久化敏感数据
+- 可配置启用/禁用
+
+### 2. 访问控制
+- 限制本地连接
+- 可配置最大连接数
+- 客户端 ID 追踪
+
+### 3. 证书管理
+- HTTPS 拦截需要安装根证书
+- 用户需手动信任证书
+- 提供证书安装指引
+
+## 扩展性
+
+### 可能的改进方向
+
+1. **过滤规则增强**
+   - 支持正则表达式
+   - 支持请求方法过滤
+   - 支持 Header 过滤
+
+2. **数据持久化**
+   - 保存历史请求
+   - 导出为 HAR 格式
+   - 数据库存储
+
+3. **高级功能**
+   - 请求重放
+   - 性能分析
+   - 自动化测试集成
+
+4. **UI 增强**
+   - 实时统计图表
+   - 请求瀑布图
+   - 搜索高亮
+
+## 故障排查指南
+
+### 常见问题
+
+| 问题 | 可能原因 | 解决方案 |
+|-----|---------|---------|
+| WebSocket 连接失败 | 插件未启动 | 运行 `node start-plugin.js` |
+| 请求未被拦截 | 规则配置错误 | 检查 whistle Rules |
+| 端口被占用 | 8889 已被使用 | `lsof -i :8889` 查看并关闭 |
+| HTTPS 证书错误 | 证书未安装 | 访问 http://127.0.0.1:8899 安装 |
+| 消息未收到 | 客户端未注册 handler | 检查 `wsClient.on()` 调用 |
+
+### 调试技巧
+
+1. **查看插件日志**
+   ```bash
+   w2 log | grep "Whistle Plugin"
+   ```
+
+2. **测试 WebSocket**
+   ```bash
+   npm test
+   ```
+
+3. **浏览器控制台**
+   - 打开 requestlistviewer
+   - 查看 Console 标签
+   - 搜索 "[RequestList Viewer]"
+
+4. **网络监控**
+   ```bash
+   lsof -i :8889
+   netstat -an | grep 8889
+   ```
+
+## 总结
+
+本插件成功实现了：
+- ✅ whistle 请求拦截
+- ✅ WebSocket 实时通信
+- ✅ 多客户端支持
+- ✅ 完整的消息协议
+- ✅ 请求-响应关联
+- ✅ 错误处理和日志
+- ✅ 详细的文档和示例
+
+通过与 requestlistviewer 的配合，提供了强大的 HTTP/HTTPS 请求调试和监控能力。

package/QUICKSTART.md

@@ -0,0 +1,65 @@
+# 快速开始指南
+
+## 一键启动
+
+```bash
+cd plugins/whistle
+npm install
+node start-plugin.js
+```
+
+## 配置 whistle 规则
+
+在浏览器打开 http://127.0.0.1:8899，在 Rules 标签添加：
+
+```
+http://*.* pastekitlab
+https://*.* pastekitlab
+```
+
+## 测试连接
+
+```bash
+npm test
+```
+
+应该看到：
+```
+✅ WebSocket 连接成功！
+📨 收到消息：{ "msgType": "connected", "clientId": 1, ... }
+```
+
+## 查看请求
+
+打开 PasteKit Lab 的 Options 页面，找到 requestlistviewer 组件，浏览网页即可看到拦截的请求。
+
+## 常用命令
+
+```bash
+# 查看日志
+w2 log
+
+# 重启 whistle
+w2 restart
+
+# 停止 whistle
+w2 stop
+```
+
+## 问题排查
+
+### 端口被占用
+```bash
+lsof -i :8889
+kill <PID>
+```
+
+### 插件未加载
+```bash
+w2 stop
+w2 start
+w2 log
+```
+
+### HTTPS 证书问题
+访问 http://127.0.0.1:8899 安装根证书并在系统中信任