Skip to content

README.zh.md

Latest commit

 

History

History
207 lines (149 loc) · 8.26 KB

README.zh.md

File metadata and controls

207 lines (149 loc) · 8.26 KB
Raw

context-tracker

CI npm license

语言: English · 简体中文

将 AI 编码工具(OpenCode / Claude Code / Codex)发送给模型的 HTTP 请求镜像到本地查看器，用于查看完整的请求上下文(headers、system prompt、tools 定义、messages)以及(可选)模型响应。

架构

Claude Code ──ANTHROPIC_BASE_URL──▶ ┐
Codex CLI  ──config.toml base_url─▶ ├─▶ proxy ──HTTPS──▶ AI API
OpenCode   ──opencode.json baseURL▶ ┘      │
                                            └──POST──▶ viewer (:39877)

proxy 向 viewer 发送镜像数据，不影响主链路的正常通信。支持单端口按路径路由到多个上游，viewer 按来源(source)与协议(api)分类展示。

安装

要求 Node.js >= 18，零运行时依赖。

全局安装(推荐)：

npm install -g context-tracker
# 或从源码:git clone https://github.com/conrad621/context-tracker.git && cd context-tracker && npm link

安装后提供单入口命令 context-tracker,带 proxy / viewer 子命令：

context-tracker help            # 查看用法
context-tracker viewer          # 启动查看器
context-tracker proxy anthropic # 用 profile 启动代理

未安装也可直接用脚本:node src/viewer.js、node src/proxy.js <profile>。下文两种写法通用。

使用

1. 启动 viewer

context-tracker viewer          # 或 node src/viewer.js

终端实时打印每个请求(含 model / system / tools / messages 概览)，Web 界面：http://localhost:39877。

设置 REDACT_AUTH=1 自动脱敏 API key：

REDACT_AUTH=1 node src/viewer.js

2. 启动 proxy

推荐:用 profile 启动(免敲 TARGET_URL)

profiles.json 里预置了常用 provider,按名字启动即可：

context-tracker proxy anthropic     # 读 profiles.json 里的 anthropic 预设
context-tracker proxy openai
context-tracker proxy claude+codex  # 多上游路由预设

context-tracker proxy               # 不带参数:交互列出所有 profile 选择

环境变量始终覆盖 profile 值(如 PROXY_PORT=9000 context-tracker proxy anthropic)。

profiles.json 格式：

{
  "anthropic": {
    "target": "https://api.anthropic.com",  // 单上游
    "source": "claude-code",                 // 镜像来源标签(默认取 profile 名)
    "captureResponse": true                  // 可选:抓响应
  },
  "claude+codex": {
    "routes": [                              // 多上游按路径路由(替代 target)
      {"prefix":"/v1/messages","target":"https://api.anthropic.com","source":"claude-code"},
      {"prefix":"/v1/responses","target":"https://api.openai.com","source":"codex"}
    ],
    "captureResponse": true
  }
}

profile 可用字段:target、routes、source、port、mirrorPort、captureResponse、maxResponseBytes、redactAuth。

手动模式(不用 profile)

# 单上游
TARGET_URL=https://api.deepseek.com node src/proxy.js

# 多上游路由(一个端口同时抓 Claude + Codex)
ROUTES='[
  {"prefix":"/v1/messages","target":"https://api.anthropic.com","source":"claude-code"},
  {"prefix":"/v1/responses","target":"https://api.openai.com","source":"codex"}
]' node src/proxy.js

3. 配置各工具指向 proxy

Claude Code(调用 POST /v1/messages)：

export ANTHROPIC_BASE_URL=http://localhost:39876
export ANTHROPIC_API_KEY=sk-ant-...        # 或 ANTHROPIC_AUTH_TOKEN
claude

Codex CLI(调用 POST /v1/responses)——编辑 ~/.codex/config.toml：

model_provider = "capture"

[model_providers.capture]
name = "Capture Proxy"
base_url = "http://localhost:39876/v1"      # 客户端会发 /v1/responses
env_key = "OPENAI_API_KEY"
wire_api = "responses"
export OPENAI_API_KEY=sk-...
codex

Codex 默认走 ChatGPT 订阅登录，抓包需改用 API key 鉴权(上面的 env_key)。

OpenCode——在 opencode.json 中配置对应 provider 的 baseURL 为 http://localhost:39876。

⚠️ /v1 路径前缀：Claude Code 与 Codex 会自己发送带 /v1 的完整路径，因此 TARGET_URL / route target 必须是主机根(如 https://api.anthropic.com，不带 /v1)，否则会出现 /v1/v1/... 双前缀。OpenCode 若只发 /messages，则 TARGET_URL 需要带 /v1。

4. 开始对话

请求上下文会实时显示在 viewer 的终端和 Web 界面中。每条请求提供 structured / raw / headers /(可选)response 视图。

Web 界面特性：

  • 搜索:顶部搜索框按 path / model / 内容实时过滤并高亮(快捷键 / 聚焦,Esc 清除)
  • 过滤:source / api chip 点选,多选叠加
  • 实时指标:请求总数、当前显示数、每分钟请求数
  • 暂停 / 跟随 / 清空:pause 暂停实时更新,follow 自动滚动到最新,clear 清空视图
  • 文本框选取:hover 任意正文框弹出 select all / copy,双击整块选中
  • 增量同步:客户端只拉取新增/更新条目(/__history?since=),poll 开销与历史规模无关
  • 虚拟滚动:只渲染视口内条目,上千条请求也只有数十个 DOM 节点,不卡顿
  • 展开稳定:点击展开的条目在实时刷新时保持展开、保留当前 tab
  • 响应用量:开启响应抓取后,响应面板会把 SSE 流解析成 token 用量 / stop reason / tool call 摘要
  • 请求 diff:"diff" 视图把每个请求与同来源的上一个请求对比:system prompt 变化、tool 增删改、消息轮次增删
  • token 计量与构成:每条请求显示 token 数(抓到响应用真实用量,否则估算),并用堆叠条拆分为 system / tools / history / current,附各 tool 开销
  • 成本统计:Stats 面板按 model 和 source 聚合(请求数、token、预估美元成本);价格可在 config/pricing.json 配置
  • 浪费检测:标记超大 system prompt、过大/重复的 tool schema、过长历史、重复消息,并给出建议列表
  • 会话过滤:带 session 标识的请求(来自 header 或 body)可被单独筛出,把一个 agent 任务的多轮请求作为时间线查看
  • 导出:把当前视图、单条请求或整个会话导出为 JSON / Markdown / HAR(通过导出链接或 /__export 接口)

环境变量

变量 默认值 说明
PROFILES ./config/profiles.json profile 配置文件路径
PROXY_PORT 39876 proxy 监听端口
MIRROR_PORT 39877 viewer 监听端口
TARGET_URL - 单上游 base URL；配合或作为 ROUTES 的回落
ROUTES - JSON 数组，按 prefix 路由到不同 target，可带 source 标签
SOURCE - 单上游模式下手动指定来源标签
CAPTURE_RESPONSE - 设为 1 时 tee 并聚合 SSE 响应，关联到对应请求
MAX_RESPONSE_BYTES 2097152 响应聚合上限(超出截断)
MAX_HISTORY 2000 viewer 保留的最大请求条数
REDACT_AUTH - 设为 1 时脱敏 API key(viewer 渲染时生效)

测试

npm test        # 即 node --test

包含 protocols 抽取单测(Anthropic Messages / OpenAI Chat / OpenAI Responses)、config/profile 加载单测,与端到端测试(mock SSE 上游 + proxy + viewer，验证路由、流式透传、镜像分类、脱敏、响应聚合、profile 启动)。

支持的协议

API 路径 来源工具
Anthropic Messages /v1/messages Claude Code
OpenAI Responses /v1/responses Codex
OpenAI Chat Completions /v1/chat/completions OpenCode / DeepSeek 等

限制

  • 仅适用于 header 鉴权的 provider(Anthropic、OpenAI、DeepSeek、OpenRouter 等)；AWS Bedrock(SigV4)/ Google Vertex 等签名鉴权不适用。
  • Codex 订阅登录(ChatGPT)不可抓，需切换到 API key 鉴权。
  • 响应抓取有内存成本，受 MAX_RESPONSE_BYTES 上限约束，超长响应仅保留截断副本。

路线图

项目未来方向见 ROADMAP.md。

许可

MIT