proxyman-traffic-debugging

Proxyman 流量调试与 MCP 操作

使用 Proxyman MCP 作为运行中 Proxyman 应用的本地控制平面。先以只读方式操作，找出相关的已捕获流量或当前状态，然后只进行用户要求的更改。

如果 Proxyman 工具不可用，请使用 proxyman-mcp-setup。如果未安装 Proxyman，请使用 proxyman-download-setup。如需针对特定目标配置 HTTPS，请使用 proxyman-https-capture。如需查阅当前产品文档，请使用 proxyman-debugging-tools。如需进行 Shell 自动化，请使用 proxyman-cli。

信息来源优先级

如果信息来源之间存在冲突，请按以下顺序采用：

1. 已连接服务端的 tools/list、resources/list 和 prompts/list，以确认可用的 MCP 功能及准确的架构。
2. Proxyman 状态/列表工具返回的当前状态。
3. 内置 MCP 资源中与版本匹配的设置、CLI 和脚本编写指南。
4. 通过 proxyman-debugging-tools 查阅官方在线文档，了解 GUI 行为和内置设置索引未涵盖的功能。
5. 本技能附带的参考资料，作为导航索引。

切勿臆造工具、枚举值、参数、规则 ID、流量 ID、文件路径或命令标志。stdio 桥接器使用严格的架构。

心智模型

• MCP 客户端通过 stdio 启动 Proxyman 捆绑的 mcp-server。桥接器读取本地握手信息，并将调用转发到运行中应用内经过身份验证的 localhost 服务端。
• 切勿对 HTTP 端口或令牌进行硬编码。每个客户端桥接器仅在其 stdin 保持打开时有效。
• 流量工具使用由活动工作区侧边栏提供支持的流量范围。其中包括常规文件夹中的流量，以及存在时的已保存、已固定、已导入、Atlantis 和远程设备来源的流量；结果会跨文件夹去重，而不局限于所选文件夹。
• 列表/筛选结果是快照。清除、导入、来源更改或重启后，流量 ID 可能会消失。
• 某些操作因平台而异。系统代理、Terminal 注入、Electron .app 注入和应用控制主要适用于 macOS。在 Windows 和 Linux 上，请以实时发现结果为准。

每次 MCP 会话的启动步骤

1. 如果客户端支持发现功能，请发现工具、资源和提示词。
2. 调用 get_version，确认桥接器能够连接到 Proxyman。
3. 调用 get_proxy_status，了解录制状态、代理端口和 SSL 代理状态。
4. 使用能确定目标的最小只读操作：get_flows、filter_flows、状态调用或相关列表调用。
5. 使用返回的标识符读取详细信息。不要根据名称或可见顺序推断 ID。
6. 说明任何变更及其影响，在需要时征得同意，调用相应工具，然后通过只读操作验证结果。

选择工具时，请阅读 MCP 工具目录。执行多步骤任务时，请阅读 MCP 工作流。使用 Breakpoint、Map Local、Map Remote、Scripting 或处理存在重叠的修改规则时，请阅读 请求与响应规则。了解内置知识时，请阅读 MCP 资源与提示词。

隐私与同意

默认启用 Settings > MCP > Redact Sensitive Data Before Sending to AI。它会对 MCP 输出中的常见机密标头、Cookie、查询参数值、JWT、凭据以及类似机密的正文内容进行脱敏。

脱敏不会清理 export_flows 写入的原始 HAR 或 Proxyman 日志。请将导出的文件视为敏感信息。

执行以下操作前，必须立即征得用户明确同意：

• 清除会话、删除规则或 Compose 草稿、关闭 WebSocket、退出 Proxyman，或卸载证书；
• 在用户未提前明确要求进行该项更改时，更改系统代理、证书信任、录制、SSL Proxying、外部代理或全局调试工具状态；
• 运行引导式自动化、Terminal 注入、Electron 注入，或执行任何会启动或修改其他应用的操作；
• 导出原始流量或发送代理凭据；
• 禁用 MCP 脱敏或显示原始机密信息。

导出时使用明确获批的目标位置。不要仅因 MCP 预览已脱敏，就声称导出内容也已脱敏。

操作模式

检查并诊断流量

1. 使用 get_proxy_status 确认捕获状态。
2. 使用 get_flows 或 filter_flows 缩小候选范围。用户指定来源时，使用客户端／设备身份信息。
3. 使用 get_flow_detail 检查代表性 ID，并查看其摘要元数据、时间、大小、连接／TLS 详情、标头、查询参数、Cookie 和正文预览。
4. 关联方法、URL、状态、时间、请求序列、客户端和匹配的调试工具。
5. 给出结论：通过、可疑、失败或无法确定，并列出支持结论的流 ID 和观察结果。
6. 仅在用户需要可复现的产物时才导出或生成代码。

安全地修改 Proxyman

1. 读取当前状态并记录相关 ID。
2. 说明拟进行的最小更改，以及它是否会影响捕获、信任、流量、磁盘或其他应用。
3. 使用准确的实时架构。仅当工具文档说明支持补丁语义时，才省略可选字段。
4. 验证返回的对象，并调用对应的列表／状态／详情工具。
5. 报告已更改的 ID，并在存在回滚操作时提供确切的回滚操作。

处理工具错误

1. 阅读完整的 MCP 错误信息；架构和验证错误旨在提供可执行的指导。
2. 应用更新后或出现 tool not found 结果时，刷新实时发现信息。
3. ID 已过期时，重新列出流或规则。
4. 只修正最小范围的无效字段；不要放宽用户要求的范围。
5. 如果未提供该功能，则转至 GUI 或 proxyman-cli，并说明此版本中的 MCP 无法执行该操作。

关键语义

• get_flows/filter_flows 最多返回 500 条结果，正文预览可能会被截断。要获取完整的归档数据，请使用经用户批准的导出。
• filter_flows 支持按 client 筛选；需要区分设备、模拟器、Atlantis 或应用来源时，优先使用它。
• Breakpoint、Map Local、Map Remote、Block List、Scripting、Allow List、Network Condition 和 DNS Spoofing 使用 list_rules。Reverse Proxy 有专用的列表工具。
• 创建/更新操作使用返回的 ID。更新会保留 ID。
• 成功执行规则的增删改查、规则开关和全局功能开关后，对应已打开的 Proxyman 列表/编辑器会刷新。删除当前正在编辑的规则会关闭该编辑器。
• 规则方法支持大写的 QUERY；仅在需要匹配所有方法时使用 ANY。请谨慎设置 include_paths，因为不同规则类型的默认值各不相同。
• 创建 Scripting、Allow List、Network Condition、DNS Spoofing 或 Reverse Proxy 规则会启用相应功能。使用 list_tool_status 确认其他功能的状态。
• 同一时间只能有一个 Network Condition 处于启用状态。
• Network Condition 配置文件名称和支持的作用范围以实时架构为准。如果仅提供预设值，不要自行编造带宽值。
• 更新 Map Local 字面响应时，应同时传入 response_body、status_code 和 content_type。
• 经审查的 MCP 可以管理 Breakpoint 规则，但无法编辑或执行/取消/中止处于暂停状态的断点；此类交互仍需在 Proxyman GUI 中完成。
• 经审查的 MCP Map Local 接口可以创建字面响应或基于已捕获流量的响应，不能创建任意文件/目录规则。经审查的 Map Remote MCP 架构未提供 CLI 中单独的保留原始 URL 选项。
• 对于相互重叠的 Map Local、Map Remote、Scripting 和 Breakpoint 规则，应查看按顺序排列的 Debugging Tools 摘要，不要假定每条匹配规则都会运行。
• 更改外部代理时，应为所选类型发送完整设置；省略的值不一定会可靠地保留。传入凭据前请先征求同意。
• Compose ID 保存在内存中。send_compose_http 仅支持 HTTP；WebSocket URL 会被拒绝。
• 经审查的 MCP 没有单独的一键 Repeat 操作。根据流量创建 Compose 草稿类似于 Edit & Repeat，但与 GUI 的 Repeat/历史记录功能并不完全一致。
• MCP 可以显示 Proxyman 解码后的 Protobuf 内容，但不能配置 Protobuf 架构/规则。经审查的 MCP 也只能通过 GUI 使用 TLS Key Logging。
• WebSocket 载荷预览有限且会进行脱敏。close_websocket_session 仅适用于由 Compose 创建且当前处于活动状态的 WebSocket 会话。
• Scripting 处理程序必须使用 Proxyman 的位置参数签名。生成较复杂的脚本前，请先阅读 docs://scripting/snippet-code。
• get_proxyman_cli_help 仅返回安全且与版本匹配的帮助信息，不会执行任何实际操作类 CLI 命令。

预期结果

完成后说明：

• 检查或更改了哪些内容；
• 相关的流量/规则/草稿 ID；
• 验证读取提供的证据；
• 隐私、导出或平台限制；
• 适当时提供回滚或下一步诊断措施。

如果捕获状态、时间范围、客户端来源或预览截断导致结果无法确定，不要声称流量已完整。

故障排查

• 缺少握手：启动 Proxyman 并启用 Settings > MCP，或使用 proxyman-mcp-setup。
• 握手无效／401：重启 Proxyman 并重新加载 MCP 客户端。
• 没有流量：检查录制状态、目标代理路由、根证书信任、SSL Proxying、客户端来源，以及通过 proxyman-https-capture 配置的目标专属设置。
• HTTPS 仍无法读取：先检查证书状态和 SSL Proxying 包含／排除规则，再考虑更改。
• 未显示 localhost：许多客户端会绕过系统代理；请使用 Reverse Proxy 工作流，或配置目标的显式代理。
• VPN 阻止设备捕获：针对受支持的 iOS 应用，使用 Atlantis 决策路径。
• 自动化失败：重试前检查操作系统中可见的权限提示、目标是否可用、证书状态，以及是否已获得所需的用户同意。