Lingma Tap

Lingma Tap 是一个专为 Lingma API 设计的数据包可视化与抓取工具。它受 cursor-tap 启发，旨在帮助开发者直观地分析和调试 Lingma 的通信流量。

功能特性

• 流量抓取：内置 MITM (Man-in-the-Middle) 代理，支持拦截和解析 HTTPS 流量。
• 自动解密：集成 QoderEncoding 逻辑，自动解码 Lingma 特有的 Base64 混淆载荷（参考并感谢 qoder2api 的实现）。
• 实时监控：基于 WebSocket 的实时数据流展示。
• 持久化存储：使用 SQLite 存储抓取记录，支持历史回溯。
• 跨平台界面：基于 Wails v2 + React + TypeScript 构建，提供原生应用体验。
• 现代 UI：包含记录列表、详细面板、JSON 查看器等。

技术栈

• 后端: Go, Wails v2, SQLite
• 前端: React 19, TypeScript, Vite, Tailwind CSS
• 核心逻辑: 自研 MITM 代理、Qoder 解码算法

快速开始

环境依赖

• Go (1.25+)
• Node.js (20+)
• Wails CLI (go install github.com/wailsapp/wails/v2/cmd/wails@v2.12.0)

开发运行

1. 克隆仓库：

   git clone git@github.com:coolxll/lingma-tap.git
   cd lingma-tap

2. 启动开发模式：

   wails dev

编译打包

• macOS: wails build (生成 .app 文件)
• Windows: wails build -platform windows/amd64 (生成 .exe 文件)

GitHub Actions

项目配置了自动化的 CI/CD 流程：

• 每次推送代码会自动触发编译。
• 推送 v* 格式的标签（如 v0.1.0）会自动创建 GitHub Release，并附带 Windows (zip) 和 macOS (dmg) 的安装包。

macOS 安装说明

由于本项目目前未加入 Apple Developer Program，因此导出的 DMG 在下载安装后可能会被 macOS 提示“无法打开”或“开发者身份不明”。

请按照以下步骤操作：

1. 将应用拖入 Applications 目录。
2. 在 Applications 中找到 Lingma Tap。
3. 右键点击应用图标，选择 打开 (Open)。
4. 在弹出的对话框中再次点击 打开 (Open)。
5. 在设置->隐私与安全性中，点击"允许"。

或者，你可以在终端中运行以下命令来手动清除隔离标记并重新签名：

xattr -cr /Applications/lingma-tap.app
codesign --force --deep --sign - /Applications/lingma-tap.app

调试与日志

为了方便排查问题，本项目内置了完善的日志和调试机制：

• 日志文件：所有后端日志以及前端渲染错误都会实时持久化到 ~/.lingma-tap/app.log。你可以使用 tail -f ~/.lingma-tap/app.log 实时查看。

• Debug 模式：启动时设置环境变量 GATEWAY_DEBUG=1 可以开启详细的网关协议调试日志（包括原始 SSE 数据流）：

  # 开发模式
  GATEWAY_DEBUG=1 wails dev
  
  # 运行打包后的应用 (macOS)
  GATEWAY_DEBUG=1 /Applications/lingma-tap.app/Contents/MacOS/Lingma\ Tap

• 上游恢复：网关默认会在尚未向调用方输出有效内容时，对 Lingma 的瞬时 HTTP/网络/SSE 错误最多尝试 3 次。大型 gm51model reasoning + 深工具历史请求可在显式配置首输出 watchdog 后，于超时时在同一入站请求内切换到非 reasoning 恢复 profile。可通过以下环境变量调整：

  LINGMA_UPSTREAM_MAX_ATTEMPTS=3
  LINGMA_UPSTREAM_RETRY_BASE_DELAY=200ms
  LINGMA_UPSTREAM_FIRST_ACTIONABLE_TIMEOUT=0
  LINGMA_THINKING_FALLBACK=true

  流式请求默认不设置首个有效输出超时；如需主动中止无输出连接，可显式设置 LINGMA_UPSTREAM_FIRST_ACTIONABLE_TIMEOUT=45s。LINGMA_THINKING_FALLBACK=false 可关闭大型 reasoning 请求的 profile 降级。重试采用有上限的指数退避和随机抖动，并遵守上游 Retry-After。已向调用方输出 content/tool-call 后不会自动重试，避免重复输出或重复工具调用。

  Gateway Log 会记录 upstream_attempts、recovery_applied、upstream_error_class、first_actionable_ms、reasoning_only_bytes 以及 requested/effective profile；这些字段不包含 prompt 或工具结果。

• UI 容错：前端集成了全局错误边界（Error Boundary）。如果界面发生崩溃，会显示红色错误页面并自动将堆栈信息记录到上述日志文件中。

致谢

• qoder2api: 感谢该项目提供的 QoderEncoding 解码思路，使本项目能够解析 Lingma 的加密数据包。
• cursor-tap: 感谢该项目带来的灵感。

许可证

MIT License (如果适用)