Loading... # Sherlock LLM Token 追踪工具技术分析 # 一、概述 ## 1. 简介 ### A. 是什么 Sherlock 是一个专为 LLM CLI 工具设计的 Token 追踪器，通过实时终端仪表盘拦截和可视化 LLM API 流量，帮助开发者跟踪成本、调试提示词并监控上下文窗口使用情况。 ### B. 为什么需要 随着 LLM 应用开发日益普及，开发者面临以下挑战： - Token 消耗难以精确跟踪，导致成本超预算 - 上下文窗口使用情况不透明，容易超出限制 - 提示词调试缺乏有效工具，难以优化性能 - 需要零配置的解决方案，避免复杂的证书设置 ### C. 能做什么 - 实时追踪每次请求的 Token 消耗量 - 可视化显示上下文窗口使用率的燃料仪表盘 - 自动保存所有提示词为 Markdown 和 JSON 格式 - 无需证书或复杂配置，安装即用 ## 2. 前置知识 ### A. 必备技能 - 基本的终端命令行操作 - Python 环境管理和包安装 - 了解 LLM API 基本概念（Token、上下文窗口） ### B. 推荐知识 - HTTP 代理原理 - Claude Code、Gemini CLI 等 LLM CLI 工具的使用 # 二、环境准备 ## 1. 系统要求 - Python 3.10 或更高版本 - macOS、Linux 或 Windows 操作系统 - 支持的 LLM CLI 工具：Claude Code、OpenAI Codex、Gemini CLI ## 2. 安装步骤 通过 Git 克隆并安装： ```bash git clone https://github.com/jmuncor/sherlock.git cd sherlock pip install -e . ``` ## 3. 验证安装 ```bash sherlock --help ``` # 三、核心概念 ## 1. 基本术语 - Token：LLM 处理文本的基本单位，消耗与计费依据 - 上下文窗口：单次对话允许的最大 Token 数量 - HTTP 代理：拦截和转发 LLM API 请求的中介服务 - 燃料仪表盘：可视化显示 Token 使用率的进度条 ## 2. 工作原理 Sherlock 通过本地 HTTP 代理拦截 LLM CLI 工具的 API 请求，解析 Token 使用情况，并在终端仪表盘实时展示。 ```mermaid graph TB A[终端1: sherlock start] --> B[HTTP代理 localhost:8080] B --> C[仪表盘] B --> D[提示词归档] E[终端2: sherlock claude] --> F[设置环境变量] F --> G[运行claude命令] G --> B B -->|HTTPS转发| H[api.anthropic.com] ```  ## 3. 架构设计 ```mermaid graph LR A[LLM CLI工具] -->|HTTP请求| B[Sherlock代理] B -->|解析Token| C[仪表盘显示] B -->|保存| D[Markdown文件] B -->|保存| E[JSON文件] B -->|转发| F[LLM API] F -->|响应| B B -->|返回| A ```  # 四、快速上手 ## 1. 启动仪表盘 在第一个终端启动 Sherlock： ```bash sherlock start ``` 首次运行时会提示选择提示词保存目录，然后显示仪表盘： ``` ┌─────────────────────────────────────────────────────────────┐ │ SHERLOCK - LLM Traffic Inspector │ ├─────────────────────────────────────────────────────────────┤ │ Context Usage ████████████░░░░░░░░░░░░░░░░ 42% │ │ (84,231 / 200,000 tokens) │ ├─────────────────────────────────────────────────────────────┤ │ Time Provider Model Tokens│ │ 14:23:01 Anthropic claude-sonnet-4-20250514 12,847│ │ 14:23:45 Anthropic claude-sonnet-4-20250514 8,234│ │ 14:24:12 Anthropic claude-sonnet-4-20250514 15,102│ ├─────────────────────────────────────────────────────────────┤ │ Last Prompt: "Can you help me refactor this function..." │ └─────────────────────────────────────────────────────────────┘ ``` ## 2. 运行 LLM 工具 在第二个终端运行支持的 LLM CLI 工具： Claude Code： ```bash sherlock claude ``` OpenAI Codex： ```bash sherlock codex ``` Gemini CLI（存在上游问题）： ```bash sherlock gemini ``` ## 3. 实时监控 仪表盘会实时更新，显示： - 当前 Token 使用量和百分比 - 每次 API 调用的详细记录 - 燃料仪表盘颜色变化：绿色（<50%）、黄色（50-80%）、红色（>80%） # 五、核心功能 ## 1. 实时仪表盘 ### A. 燃料仪表盘 可视化显示 Token 使用率，颜色编码： - 绿色：使用率低于 50% - 黄色：使用率 50-80% - 红色：使用率超过 80% ### B. 请求历史表格 显示每次 API 调用的详细信息： - 时间戳 - 服务提供商 - 模型名称 - Token 消耗量 ## 2. 提示词归档 所有拦截的请求自动保存到指定目录： Markdown 格式： - 人类可读的格式 - 包含元数据（时间、模型、Token 数） - 便于审查和分享 JSON 格式： - 原始 API 请求体 - 完整的请求和响应数据 - 用于调试和分析 ## 3. 会话摘要 退出时显示总体使用情况： ``` Session complete. Total: 84,231 tokens across 12 requests. ``` # 六、命令详解 ## 1. 启动命令 ```bash sherlock start [OPTIONS] ``` 选项： - -p, --port NUM：代理端口（默认：8080） - -l, --limit NUM：燃料仪表盘的 Token 限制（默认：200000） ## 2. Claude Code 命令 ```bash sherlock claude [OPTIONS] [ARGS]... ``` 选项： - -p, --port NUM：代理端口（默认：8080） 说明：自动设置 ANTHROPIC_BASE_URL 环境变量并运行 claude 命令。 ## 3. 通用运行命令 ```bash sherlock run --provider <name> <cmd> ``` 说明：运行任何命令并配置代理环境变量。 # 七、支持的服务商 | 服务商 | 命令 | 状态 | |--------|------|------| | Anthropic (Claude Code) | sherlock claude | 支持 | | Google (Gemini CLI) | sherlock gemini | 受上游问题阻拦 | | OpenAI (Codex) | sherlock codex | 支持 | ## 1. Gemini CLI 已知问题 Gemini CLI 存在已知问题，在使用 OAuth 认证时会忽略自定义基础 URL。该问题由上游项目导致，详情参考：https://github.com/google-gemini/gemini-cli/issues/15430 # 八、技术实现 ## 1. 代理机制 Sherlock 使用 HTTP relay proxy 替代原有的 mitmproxy，实现更轻量级的流量拦截： ```mermaid sequenceDiagram participant U as 用户命令 participant S as Sherlock代理 participant L as LLM API U->>S: HTTP请求 S->>S: 解析Token S->>S: 更新仪表盘 S->>S: 保存提示词 S->>L: 转发请求 L-->>S: API响应 S-->>U: 返回结果 ```  ## 2. 环境变量注入 Sherlock 通过设置特定环境变量将 LLM CLI 工具的请求路由到本地代理： Claude Code： - ANTHROPIC_BASE_URL=http://localhost:8080 OpenAI Codex： - OPENAI_API_BASE=http://localhost:8080 Gemini CLI： - GEMINI_API_BASE=http://localhost:8080 ## 3. Token 解析 Sherlock 解析 API 响应中的 Token 使用信息： - 输入 Token 数量 - 输出 Token 数量 - 总计 Token 数量 # 九、使用场景 ## 1. 成本追踪 实时监控 Token 消耗，避免超预算： - 设置 Token 限制提醒 - 统计会话总消耗 - 分析不同模型的成本差异 ## 2. 提示词优化 通过归档的提示词进行优化： - 对比不同提示词的效果 - 分析 Token 效率 - 复用高效提示词模板 ## 3. 上下文管理 监控上下文窗口使用情况： - 避免超出上下文限制 - 优化对话历史长度 - 提升响应准确性 # 十、最佳实践 ## 1. 开发工作流 建议的开发流程： 1. 启动 Sherlock 仪表盘 2. 在独立终端运行 LLM 工具 3. 实时监控 Token 使用 4. 定期审查提示词归档 5. 根据数据优化提示词 ## 2. 成本控制 设置合理的 Token 限制： - 开发环境：50,000-100,000 tokens - 测试环境：100,000-200,000 tokens - 生产环境：根据实际需求调整 ## 3. 团队协作 共享提示词归档： - 建立团队提示词库 - 标注高效提示词 - 定期分享最佳实践 # 十一、故障排除 ## 1. 代理无法启动 检查端口占用： ```bash lsof -i :8080 ``` 使用其他端口： ```bash sherlock start --port 8888 ``` ## 2. LLM 工具无法连接 确认环境变量设置： ```bash echo $ANTHROPIC_BASE_URL ``` 手动设置环境变量： ```bash export ANTHROPIC_BASE_URL=http://localhost:8080 ``` ## 3. Token 统计不准确 某些服务商可能不返回详细的 Token 使用信息，Sherlock 会显示可用数据。 # 十二、开发与贡献 ## 1. 开发环境设置 ```bash git clone https://github.com/jmuncor/sherlock.git cd sherlock python -m venv venv source venv/bin/activate pip install -e . ``` ## 2. 贡献流程 1. Fork 项目仓库 2. 创建功能分支：git checkout -b feature/amazing-feature 3. 提交更改：git commit -m 'Add amazing feature' 4. 推送分支：git push origin feature/amazing-feature 5. 创建 Pull Request ## 3. 项目结构 ``` sherlock/ ├── sherlock/ # 核心代码 ├── pyproject.toml # 项目配置 ├── LICENSE # MIT 许可证 └── README.md # 项目文档 ``` # 十三、技术特点 ## 1. 零配置设计 无需安装证书或修改系统配置： - 自动启动本地代理 - 自动注入环境变量 - 自动保存提示词归档 ## 2. 轻量级实现 使用 HTTP relay proxy 替代重量级方案： - 更少的依赖 - 更快的启动速度 - 更低的资源占用 ## 3. 终端原生界面 使用 Rich 库构建美观的终端界面： - 实时更新 - 颜色编码 - 响应式布局 # 十四、未来展望 ## 1. 支持更多服务商 计划添加对以下服务的支持： - 更多 LLM 提供商 - 自定义 API 端点 - 本地部署的模型 ## 2. 增强分析功能 计划添加： - Token 消耗趋势图表 - 成本预测 - 提示词效率分析 ## 3. 团队协作功能 计划添加： - 共享提示词库 - 团队使用统计 - 成本分摊计算 *** ## 参考资料 1. [Sherlock GitHub 仓库](https://github.com/jmuncor/sherlock) 2. [Claude Code 官方文档](https://docs.anthropic.com/) 3. [Gemini CLI 已知问题](https://github.com/google-gemini/gemini-cli/issues/15430) 最后修改：2026 年 01 月 29 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏