pxc · 抓包代理与团队协作

$

抓包不是终点，可复现的调试现场才是。

Design

设计要点

这个工具为什么这么做，以及这样做换来了什么。

内核与 UI 解耦

内核只暴露 /v1 API，任何端（Swift / WinUI / Flutter / CLI）都是平等消费者，跨平台行为天然一致。

Agent 友好

pxc status / sessions / body / curl 全部结构化输出，AI 可直接读流量定位问题，不需要截图。

断点即调试器

一行规则把目标流量挂住，实时查看 body 并决定放行、mock 或中止，改包重放不用写脚本。

团队共享

抓包现场可导出 HAR 与 cURL，附在 issue 里即可复现，不再靠「你那边再试一次」。

Highlights

能力一览

Go 内核 + 多端壳，UI 层可替换，/v1 HTTP/WS 是唯一契约
pxc CLI 为 Agent 而生：JSON 默认输出、退出码语义化、token 自动解析
服务端过滤与全文检索：按 host、状态码、body 关键词直接定位
断点调试：挂起流量后可改 method / url / header / body 再放行
故障注入与 mock：不连上游直接应答，构造异常分支
HAR 1.2 全量导出与 cURL 重放，调试现场一键分享给同事

Metrics

设计指标

每一条都对应实现里的一个具体决定。

共用内核的端

3 端

macOS Swift / Windows WinUI / Flutter，UI 可替换

内核验收项

61

内核 E2E 验收覆盖，跨端行为一致的前提

规则热加载

1s

规则文件保存后 1 秒内生效，不用重启内核

退出码语义

0 / 1 / 2

成功 / 失败 / 用法错误，便于脚本与 Agent 判断

检索方式

FTS

全文检索，按 body 关键词直接定位，不靠肉眼翻

导出格式

HAR 1.2

全量导出 + cURL 重放，调试现场可分享

Platforms

平台支持

内核与界面分离之后，每个平台的支持程度可以单独推进。

macOS

完整

Swift 桌面壳，与内核经 /v1 HTTP/WS 通信

Windows

完整

WinUI 桌面壳，共用同一 Go 内核

CLI

完整

JSON 默认输出、退出码语义化、token 自动解析

Flutter / 移动端

部分

移动端抓包与查看，绑定层已在 kernel/bindings

Web UI

部分

内核自带 Web 界面产物，浏览器内查看流量

Comparison

与常见做法的差别

差别通常不在功能表上，而在「边界画在哪里」。

内核与界面

Go 内核只暴露 /v1 HTTP/WS，所有端是平等消费者

抓包逻辑写在界面里，每端各实现一遍

给 AI 用

CLI 默认 JSON、退出码语义化，Agent 可直接读流量

只能人肉看界面，AI 拿不到结构化数据

调试方式

断点挂起 + 实时改包 + mock 应答，不写脚本

要改包就得写拦截脚本或改代码重新部署

检索能力

服务端 FTS 全文检索，按 body 关键词定位

列表里肉眼翻，流量一多就找不到

团队协作

HAR 全量导出 + cURL 重放，现场可复现可分享

「你那边再试一次，看看能不能复现」

Commands

命令速览

完整手册见 CLI 手册页。全部命令默认输出结构化结果。

完整命令表

pxc status

查看内核运行状态、监听端口与授权信息

--json

pxc sessions

检索已捕获的流量，支持多条件组合

--host--status--method--limit--q

pxc body <id>

读取指定请求的完整请求体与响应体

--req--res--raw

pxc curl <id>

导出为可重放的 cURL 命令

--no-headers

In Practice

实际输出

pxc

01$ pxc sessions --host api.github.com --status 500 --limit 20
02[ { "id": 42, "method": "POST", "path": "/v1/pay", "status": 500 } ]
03
04$ pxc bp respond 7 --status 201 --body '{"ok":true}'
05{ "released": true, "mode": "mock" }

Source

代码模块

3 组、15 个模块，全部来自仓库真实目录结构。

Go · Swift · WinUI · Flutter · WebSocket · HAR · FTS

内核

Go 写的 pxc-core，是唯一的事实来源。

internal/engine

流量捕获与代理引擎，断点挂起与放行的执行主体

kernel/internal/engine

internal/store

流量落库与检索，FTS 全文检索支撑按 body 关键词定位

kernel/internal/store

internal/rules

规则引擎：文本 DSL 规则，保存后 1s 热加载

kernel/internal/rules

internal/api

/v1 HTTP + WebSocket 契约实现，内核对外的唯一接口

kernel/internal/api

internal/scripting

脚本化扩展能力

kernel/internal/scripting

internal/pairing / discovery

设备配对与实例发现，支撑多端协同调试

kernel/internal/{pairing,discovery}

internal/license / instance

授权与实例管理

kernel/internal/{license,instance}

命令与端

内核只认 /v1，所有端都是平等消费者。

cmd/pxc

CLI：JSON 默认输出、退出码语义化（0/1/2）、token 自动解析

kernel/cmd/pxc

cmd/pxc-core

内核服务进程

kernel/cmd/pxc-core

cmd/pxc-mobile / pxc-license

移动端与授权命令

kernel/cmd/

apps/desktop

桌面端壳（macOS Swift / Windows WinUI）

apps/desktop

apps/mobile / webui

Flutter 移动端与 Web UI

apps/{mobile,webui}

契约与绑定

跨平台一致性的保障。

shared/api-spec

/v1 API 规格，内核与所有端据此对齐

shared/api-spec

kernel/bindings

移动端绑定层

kernel/bindings

kernel/web

内核自带的 Web 界面产物

kernel/web

Go Deeper

继续深入

Use Cases

使用场景

4 个典型场景，每个都拆成可照做的步骤。

定位线上 500 到底错在哪

不用在客户端加日志，直接看真实请求与响应。

1pxc sessions --host api.example.com --status 500 筛选
2pxc body <id> 读出响应体里的错误栈
3必要时 pxc curl <id> 在本地重放复现
4pxc export 导出 HAR 附到 issue

断点改包验证假设

把目标流量挂住，改完再放行，不用写脚本。

1在规则文件里写一行匹配规则
2规则保存后 1s 内热加载生效
3目标请求被挂起，实时查看 method / url / header / body
4改包后放行，或直接 mock 应答

构造异常分支

不连上游就能返回你要的状态码与 body。

1pxc bp respond <id> --status 503 --body 指定响应
2客户端收到构造出的异常
3验证前端的降级与容错逻辑
4无需改动服务端或上游

让 Agent 读流量定位问题

AI 直接读结构化流量，不需要人截图描述。

1Agent 调用 pxc status 确认内核可用
2按 host 与状态码筛选出可疑会话
3读取 body 拿到真实错误信息
4结构化输出直接进入分析链路

Boundaries

数据边界与安全

这类工具的价值很大一部分在于「它不做什么」。下面每一条都标注了实现位置。

本地内核

抓包内核跑在本机，流量数据不经过第三方服务。

cmd/pxc-core

实例配对

设备配对与实例发现机制，非配对实例无法接入。

internal/pairing · discovery

令牌解析

CLI 自动发现并解析本地 token，无需在命令行明文传递凭据。

cmd/pxc

规则可控

规则是本地文本 DSL，文件位置与内容可审计，1s 热加载。

~/.pxc/project/rules.txt

授权与实例管理

授权与实例绑定，便于团队统一管理与回收。

internal/license · instance

导出可控

HAR 与 cURL 导出由用户主动触发，不会自动外传。

导出模块

Roadmap

版本节奏

已发布的写清交付了什么，开发中的写清正在做什么。

v0.3已发布内核

Go 抓包与代理引擎
/v1 HTTP + WebSocket 契约
FTS 全文检索
规则引擎与热加载

v0.6已发布调试与多端

断点挂起与改包放行
故障注入与 mock 应答
macOS Swift 桌面壳
HAR 1.2 导出与 cURL 重放

v0.8开发中协作与 Agent

pxc CLI 结构化输出完善
Windows WinUI 桌面壳
Flutter 移动端抓包
团队共享会话与权限

v1.0规划中生态

脚本化扩展开放
协议扩展（gRPC / WebSocket 增强）
CI 集成与自动化断言
团队工作区与审计

FAQ

常见问题

因为抓包能力要跨平台。内核只暴露 /v1 HTTP/WS，macOS Swift、Windows WinUI、Flutter、CLI 都是平等消费者——跨平台一致性由契约保证，而不是靠每个端各写一遍抓包逻辑。

Source Modules

代码模块

3 组、15 个模块。路径直接对应仓库目录，方便工程同学定位。

内核

Go 写的 pxc-core，是唯一的事实来源。

internal/engine

流量捕获与代理引擎，断点挂起与放行的执行主体

kernel/internal/engine

internal/store

流量落库与检索，FTS 全文检索支撑按 body 关键词定位

kernel/internal/store

internal/rules

规则引擎：文本 DSL 规则，保存后 1s 热加载

kernel/internal/rules

internal/api

/v1 HTTP + WebSocket 契约实现，内核对外的唯一接口

kernel/internal/api

internal/scripting

脚本化扩展能力

kernel/internal/scripting

internal/pairing / discovery

设备配对与实例发现，支撑多端协同调试

kernel/internal/{pairing,discovery}

internal/license / instance

授权与实例管理

kernel/internal/{license,instance}

命令与端

内核只认 /v1，所有端都是平等消费者。

cmd/pxc

CLI：JSON 默认输出、退出码语义化（0/1/2）、token 自动解析

kernel/cmd/pxc

cmd/pxc-core

内核服务进程

kernel/cmd/pxc-core

cmd/pxc-mobile / pxc-license

移动端与授权命令

kernel/cmd/

apps/desktop

桌面端壳（macOS Swift / Windows WinUI）

apps/desktop

apps/mobile / webui

Flutter 移动端与 Web UI

apps/{mobile,webui}

契约与绑定

跨平台一致性的保障。

shared/api-spec

/v1 API 规格，内核与所有端据此对齐

shared/api-spec

kernel/bindings

移动端绑定层

kernel/bindings

kernel/web

内核自带的 Web 界面产物

kernel/web

Stack

技术栈

GoSwiftWinUIFlutterWebSocketHARFTS

Architecture

分层设计

从内核到界面，每一层负责什么、用什么实现。这类工具的核心设计是「内核与界面分离」。

01内核

Go pxc-core：流量捕获、FTS 检索、断点与规则引擎

02契约

/v1 HTTP + WebSocket，内核与所有端唯一接口

03多端壳

macOS Swift / Windows WinUI / Flutter

04CLI

cmd/pxc，JSON 输出、退出码 0/1/2、token 自动发现

05规则

~/.pxc/project/rules.txt 文本 DSL，保存 1s 热加载

06导出

HAR 1.2 全量导出、cURL 重放命令

Platforms

多端支持

同一个内核，不同平台只是换一层壳。支持程度可以按平台单独推进。

macOS

完整

Swift 桌面壳，与内核经 /v1 HTTP/WS 通信

Windows

完整

WinUI 桌面壳，共用同一 Go 内核

CLI

完整

JSON 默认输出、退出码语义化、token 自动解析

Flutter / 移动端

部分

移动端抓包与查看，绑定层已在 kernel/bindings

Web UI

部分

内核自带 Web 界面产物，浏览器内查看流量

Stack

技术栈

GoSwiftWinUIFlutterWebSocketHARFTS

CLI Reference

命令手册

8 条命令。设计前提：输出结构化、退出码语义化，让脚本和 AI Agent 都能可靠消费。

pxc status

查看内核运行状态、监听端口与授权信息

--json

pxc sessions

检索已捕获的流量，支持多条件组合

--host--status--method--limit--q

pxc body <id>

读取指定请求的完整请求体与响应体

--req--res--raw

pxc curl <id>

导出为可重放的 cURL 命令

--no-headers

pxc export

按筛选条件导出 HAR 1.2 全量记录

--out--host--since

pxc bp respond <id>

对挂起的请求直接应答（mock 模式）

--status--body--header

pxc rules reload

热加载规则文件，无需重启内核

--file

pxc discovery

发现局域网内可配对的实例与设备

--json

Output

输出约定

CLI 是给程序用的接口，人只是顺便看得懂。

结构化输出

默认输出 JSON，字段名稳定。人可读的格式化由调用方决定，不由 CLI 猜测。

退出码语义化

成功、失败、用法错误分别返回不同退出码，脚本与 Agent 据此分支，不用解析文本。

凭据不落命令行

自动发现本地令牌文件，避免在命令行明文传凭据（会被写入 shell 历史与进程列表）。

Example

一次实际调用

pxc

01$ pxc sessions --host api.github.com --status 500 --limit 20
02[ { "id": 42, "method": "POST", "path": "/v1/pay", "status": 500 } ]
03
04$ pxc bp respond 7 --status 201 --body '{"ok":true}'
05{ "released": true, "mode": "mock" }

pxc抓包代理与团队协作

设计要点

能力一览

设计指标

平台支持

与常见做法的差别

命令速览

实际输出

代码模块

继续深入

使用场景

数据边界与安全

版本节奏

常见问题

代码模块

技术栈

分层设计

多端支持

技术栈

命令手册

输出约定

一次实际调用

把身份、Agent 与私域的复杂度，交给一套可治理的内核