Shermie-Proxy：AI Agent 时代的网络调试利器

场景切入：为什么你需要一个"协议万能代理"？

你在调试一个 AI Agent，它的 Web Search 工具通过 WebSocket 连接到搜索服务，同时 Agent 内部调用了 SOCKS5 代理访问外部 API，HTTP 请求走了透明代理，图片下载又直接走了 TCP 连接——六种协议并发运行，一堆工具各自为政。你用什么工具同时看到所有流量、并且还能实时修改数据？

传统方案是 Charles（Fiddler）负责 HTTP/HTTPS，Wireshark 负责 TCP，额外开一个 SOCKS5 代理工具……工具链割裂、配置繁琐、无法联动。Shermie-Proxy 的思路完全不同：一个端口，监听所有协议，自动识别，自动处理。

图1：Shermie-Proxy 核心设计——单端口多协议自动识别（仓库内置架构图）

项目背景：从调试痛点中诞生的工具

Shermie-Proxy 由开发者 kxg3030 用 Go 语言编写，当前版本 1.1，GitHub 收录 268 颗星，76 个 Fork，Apache-2.0 开源许可。项目最早发布于 2024 年，定位是一个面向开发者的网络调试代理库，核心解决多协议流量同时捕获和修改的问题。

在 AI Agent 开发场景中，这个工具的价值尤为突出：AI Agent 通常需要同时调用多种网络工具（搜索 API 用 HTTP、实时通讯用 WebSocket、文件传输用 TCP），传统抓包工具难以统一处理，而 Shermie-Proxy 通过一个统一的回调钩子（Hook）机制，让开发者可以在同一种编程模型下处理所有协议。

核心功能：六种协议，一个入口

1. 自动协议识别

Shermie-Proxy 在 TCP 连接建立后，通过消息头特征自动判断流量类型：

协议	识别依据	典型端口
HTTP/HTTPS	CONNECT 方法、HTTP 首行	80/443
WebSocket (WS/WSS)	Upgrade: websocket	80/443
SOCKS5	0x05 版本号 + 认证握手	1080
TCP 直连	以上均不匹配	自定义

这种设计的好处是无需事先指定协议，代理自动适应，非常适合混合流量场景。

2. 数据拦截与修改

每个协议的请求和响应都可以注册回调函数，在回调中读取甚至修改数据：

// HTTP 请求拦截——在发出去之前修改 body
s.OnHttpRequestEvent = func(message []byte, request *http.Request, resolve Core.ResolveHttpRequest, conn net.Conn) bool {
    Log.Log.Println("HTTP请求：" + conn.RemoteAddr().String())
    resolve(message, request)  // 处理完必须调用 resolve
    return true               // 返回 true 才将数据继续传递
}

// WebSocket 消息拦截
s.OnWsRequestEvent = func(msgType int, message []byte, resolve Core.ResolveWs, conn net.Conn) error {
    modified := bytes.Replace(message, []byte("OLD"), []byte("NEW"), 1)
    return resolve(msgType, modified)
}

3. HTTPS 劫持（MITM）

内置根证书自动生成功能，支持解密 HTTPS 流量。首次运行自动初始化 cert.crt 和 cert.key，导入系统信任链后即可拦截 HTTPS：

Core.NewCertificate().Init()  // 只需执行一次

4. 上游代理链

支持串联多个代理节点：

./proxy --port=9090 --proxy=192.168.1.1:1080

Agent 的流量经过本地 Shermie-Proxy，再通过上级 SOCKS5 代理出去，适合需要多层代理的调试场景。

5. TCP 连接复用（TODO）

目前官方 Roadmap 中规划了 TCP 连接复用功能，这将显著降低高频短连接的延迟开销。

代码架构：清晰模块化的 Go 实践

shermie-proxy/
├── Core/               # 核心代理引擎
│   ├── ProxyServer.go  # 服务端主入口，事件注册中枢
│   ├── ProxyHttp.go    # HTTP/HTTPS 代理逻辑
│   ├── ProxySocks5.go  # SOCKS5 代理实现
│   ├── ProxyTcp.go     # 原始 TCP 透传
│   ├── Certificate.go  # MITM 根证书生成
│   └── Websocket/      # 完整 WebSocket 协议栈（17个文件）
├── Contract/           # 接口契约（IServerProcesser）
├── Constant/           # 常量定义
├── Log/                # 日志模块
├── Utils/              # 平台工具（Linux/Windows）
└── Main.go             # 入口程序示例

核心技术亮点

WebSocket 实现：Core/Websocket/ 目录下有 17 个文件，实现了完整的 RFC 6455 WebSocket 协议，包括：

Mask.go / MaskSafe.go：帧掩码处理
Compression.go：WebSocket 压缩扩展（permessage-deflate）
Prepared.go：预编译握手
ClientClone.go / ClientCloneLegacy.go：WebSocket 克隆连接

这个实现相当完整，完全可以作为学习 WebSocket 协议实现的学习资料。

MITM 证书系统：Core/Certificate.go 负责自动生成自签名根证书，这是所有 HTTPS 抓包工具的核心——有了根证书才能解密 TLS 流量。

日志模块：Log/Logger.go 提供结构化日志，支持输出到控制台或文件，HTTP 请求/响应日志默认打印 JSON 格式。

上手体验：纯库模式的门槛

优势：

作为 Go package 分发，天然支持版本管理：go get github.com/kxg3030/shermie-proxy
代码量适中（不含 WebSocket 实现约 10 个核心文件），适合阅读理解
回调钩子设计优雅，用户代码与代理逻辑完全解耦

门槛：

必须写 Go 代码才能使用，不提供命令行独立工具（proxy.exe 是预编译演示程序但非正式发布）
HTTPS 劫持需要手动导入根证书，对非开发人员有一定门槛
无 Web UI，全靠回调函数中的日志输出，调试体验偏向程序员风格

局限与风险

HTTPS 劫持的法律与隐私风险：MITM 证书本质上是中间人攻击的实现，只应在授权测试环境中使用，切勿用于未授权的网络。
缺少测试覆盖：代码仓库中未发现测试文件，生产环境使用需自行评估稳定性。
无 CI/CD：缺少 GitHub Actions 自动化测试/构建流程，版本发布依赖作者手动维护。
go.mod 依赖版本较旧：dnscache 依赖来自 2013 年快照版本，可能存在潜在安全漏洞。

行业意义：AI Agent 调试的工具链空白

Shermie-Proxy 的出现填补了一个细分但重要的空白——多协议统一调试。随着 AI Agent 系统变得越来越复杂（LLM + 搜索 + 文件下载 + 实时通讯），传统的单一协议抓包工具已无法满足需求。像 Shermie-Proxy 这样能够在一个入口同时处理 HTTP、WebSocket、SOCKS5、TCP 的工具，将成为 AI Agent 开发者的标配工具之一。

当前版本 1.1 的功能已经稳定可用，TODO 中的 TCP 连接复用一旦实现，将进一步提升工具的实用价值。

快速开始

package main

import (
    "flag"
    "github.com/kxg3030/shermie-proxy/Core"
    "github.com/kxg3030/shermie-proxy/Log"
    "net/http"
)

func init() {
    Log.NewLogger().Init()
    Core.NewCertificate().Init()
}

func main() {
    port := flag.String("port", "9090", "listen port")
    flag.Parse()

    s := Core.NewProxyServer(*port, true, "", "")

    s.OnHttpRequestEvent = func(message []byte, request *http.Request, resolve Core.ResolveHttpRequest, conn net.Conn) bool {
        Log.Log.Println("请求: " + request.URL.String())
        resolve(message, request)
        return true
    }

    s.OnHttpResponseEvent = func(body []byte, response *http.Response, resolve Core.ResolveHttpResponse, conn net.Conn) bool {
        Log.Log.Println("响应: " + string(body))
        resolve(body, response)
        return true
    }

    s.Start()
}

运行后，将浏览器或 AI Agent 的代理地址设置为 http://127.0.0.1:9090，流量即可被捕获和修改。

分析基于 GitHub 仓库 v1.1 版本（master 分支），数据采集时间：2026-07-07。

Shermie-Proxy：AI Agent 时代的网络调试利器

场景切入：为什么你需要一个"协议万能代理"？

图1：Shermie-Proxy 核心设计——单端口多协议自动识别（仓库内置架构图）

项目背景：从调试痛点中诞生的工具

核心功能：六种协议，一个入口

1. 自动协议识别

Shermie-Proxy 在 TCP 连接建立后，通过消息头特征自动判断流量类型：

协议	识别依据	典型端口
HTTP/HTTPS	CONNECT 方法、HTTP 首行	80/443
WebSocket (WS/WSS)	Upgrade: websocket	80/443
SOCKS5	0x05 版本号 + 认证握手	1080
TCP 直连	以上均不匹配	自定义

这种设计的好处是无需事先指定协议，代理自动适应，非常适合混合流量场景。

2. 数据拦截与修改

每个协议的请求和响应都可以注册回调函数，在回调中读取甚至修改数据：

// HTTP 请求拦截——在发出去之前修改 body
s.OnHttpRequestEvent = func(message []byte, request *http.Request, resolve Core.ResolveHttpRequest, conn net.Conn) bool {
    Log.Log.Println("HTTP请求：" + conn.RemoteAddr().String())
    resolve(message, request)  // 处理完必须调用 resolve
    return true               // 返回 true 才将数据继续传递
}

// WebSocket 消息拦截
s.OnWsRequestEvent = func(msgType int, message []byte, resolve Core.ResolveWs, conn net.Conn) error {
    modified := bytes.Replace(message, []byte("OLD"), []byte("NEW"), 1)
    return resolve(msgType, modified)
}

3. HTTPS 劫持（MITM）

内置根证书自动生成功能，支持解密 HTTPS 流量。首次运行自动初始化 cert.crt 和 cert.key，导入系统信任链后即可拦截 HTTPS：

Core.NewCertificate().Init()  // 只需执行一次

4. 上游代理链

支持串联多个代理节点：

./proxy --port=9090 --proxy=192.168.1.1:1080

Agent 的流量经过本地 Shermie-Proxy，再通过上级 SOCKS5 代理出去，适合需要多层代理的调试场景。

5. TCP 连接复用（TODO）

目前官方 Roadmap 中规划了 TCP 连接复用功能，这将显著降低高频短连接的延迟开销。

代码架构：清晰模块化的 Go 实践

shermie-proxy/
├── Core/               # 核心代理引擎
│   ├── ProxyServer.go  # 服务端主入口，事件注册中枢
│   ├── ProxyHttp.go    # HTTP/HTTPS 代理逻辑
│   ├── ProxySocks5.go  # SOCKS5 代理实现
│   ├── ProxyTcp.go     # 原始 TCP 透传
│   ├── Certificate.go  # MITM 根证书生成
│   └── Websocket/      # 完整 WebSocket 协议栈（17个文件）
├── Contract/           # 接口契约（IServerProcesser）
├── Constant/           # 常量定义
├── Log/                # 日志模块
├── Utils/              # 平台工具（Linux/Windows）
└── Main.go             # 入口程序示例

核心技术亮点

WebSocket 实现：Core/Websocket/ 目录下有 17 个文件，实现了完整的 RFC 6455 WebSocket 协议，包括：

Mask.go / MaskSafe.go：帧掩码处理
Compression.go：WebSocket 压缩扩展（permessage-deflate）
Prepared.go：预编译握手
ClientClone.go / ClientCloneLegacy.go：WebSocket 克隆连接

这个实现相当完整，完全可以作为学习 WebSocket 协议实现的学习资料。

MITM 证书系统：Core/Certificate.go 负责自动生成自签名根证书，这是所有 HTTPS 抓包工具的核心——有了根证书才能解密 TLS 流量。

日志模块：Log/Logger.go 提供结构化日志，支持输出到控制台或文件，HTTP 请求/响应日志默认打印 JSON 格式。

上手体验：纯库模式的门槛

优势：

作为 Go package 分发，天然支持版本管理：go get github.com/kxg3030/shermie-proxy
代码量适中（不含 WebSocket 实现约 10 个核心文件），适合阅读理解
回调钩子设计优雅，用户代码与代理逻辑完全解耦

门槛：

必须写 Go 代码才能使用，不提供命令行独立工具（proxy.exe 是预编译演示程序但非正式发布）
HTTPS 劫持需要手动导入根证书，对非开发人员有一定门槛
无 Web UI，全靠回调函数中的日志输出，调试体验偏向程序员风格

局限与风险

HTTPS 劫持的法律与隐私风险：MITM 证书本质上是中间人攻击的实现，只应在授权测试环境中使用，切勿用于未授权的网络。
缺少测试覆盖：代码仓库中未发现测试文件，生产环境使用需自行评估稳定性。
无 CI/CD：缺少 GitHub Actions 自动化测试/构建流程，版本发布依赖作者手动维护。
go.mod 依赖版本较旧：dnscache 依赖来自 2013 年快照版本，可能存在潜在安全漏洞。

行业意义：AI Agent 调试的工具链空白

当前版本 1.1 的功能已经稳定可用，TODO 中的 TCP 连接复用一旦实现，将进一步提升工具的实用价值。

快速开始

package main

import (
    "flag"
    "github.com/kxg3030/shermie-proxy/Core"
    "github.com/kxg3030/shermie-proxy/Log"
    "net/http"
)

func init() {
    Log.NewLogger().Init()
    Core.NewCertificate().Init()
}

func main() {
    port := flag.String("port", "9090", "listen port")
    flag.Parse()

    s := Core.NewProxyServer(*port, true, "", "")

    s.OnHttpRequestEvent = func(message []byte, request *http.Request, resolve Core.ResolveHttpRequest, conn net.Conn) bool {
        Log.Log.Println("请求: " + request.URL.String())
        resolve(message, request)
        return true
    }

    s.OnHttpResponseEvent = func(body []byte, response *http.Response, resolve Core.ResolveHttpResponse, conn net.Conn) bool {
        Log.Log.Println("响应: " + string(body))
        resolve(body, response)
        return true
    }

    s.Start()
}

运行后，将浏览器或 AI Agent 的代理地址设置为 http://127.0.0.1:9090，流量即可被捕获和修改。

分析基于 GitHub 仓库 v1.1 版本（master 分支），数据采集时间：2026-07-07。