1. 项目缘起为什么我要做“caveman”这个编码代理“caveman”这个名字听起来有点糙但它要解决的问题一点都不糙。简单说caveman 是一个面向编码代理coding agents的本地代理层核心工作是在代理工具和真实模型服务之间做一次“翻译管控”。你可能会问代理工具本身不是能直连模型吗为什么还要在中间插一层答案藏在两个词里token和proxy。先说 token。任何用过编码代理的人都有体会token 用量是个绕不开的成本项。一次复杂的代码重构代理可能来回调用几十次模型每次都要把上下文重新塞进去token 消耗像流水一样。更麻烦的是很多代理工具对 token 的统计是黑盒的你只知道月底账单涨了却不知道钱花在哪个环节。caveman 的第一个动机就是把这层黑盒打开让每一次请求的 token 消耗都可见、可统计、可归因。再说 proxy。这里的 proxy 不是网络意义上的转发而是一个对象转换层proxy object。编码代理发出的请求格式、模型服务期望的请求格式两者往往对不上。比如代理可能用一套自己的消息结构而模型端点要求特定的字段组织方式。caveman 在中间做格式适配把代理的请求“翻译”成模型能懂的形状再把模型的响应“翻译”回代理能解析的形状。这个转换过程如果做不好就会出现各种奇怪的报错比如cc switch local proxy failed while handling codex endpoint /responses或者unexpected status 404 not found。所以 caveman 的定位很清晰它是编码代理和模型服务之间的中间件负责请求格式转换、token 用量统计、错误拦截与重试、以及本地代理的稳定性保障。适合谁来参考如果你正在用或准备用编码代理做日常开发又对 token 成本和请求可控性有要求那 caveman 这套思路值得你花时间研究。哪怕你不直接用这个项目它拆解出来的问题——代理格式不兼容、token 统计缺失、端点报错难排查——都是编码代理落地时的通用痛点。我最初做这个东西是因为自己在用编码代理时被token exchange failed这类报错折腾得够呛。明明本地环境没问题代理一跑就报sign-in could not be completed token exchange failed排查半天发现是请求格式在中间环节被改坏了。与其每次手动 debug不如做一个专门的代理层把转换逻辑、统计逻辑、错误处理逻辑都收拢到一处。这就是 caveman 的起点。2. 整体架构设计代理层到底该放在哪一层2.1 三种可选架构的取舍做代理层第一个要决定的是它放在哪个位置。我试过三种方案各有优劣。第一种是进程内拦截也就是把代理逻辑做成编码代理的一个插件或中间件直接在代理进程内部改请求。好处是延迟最低没有额外的网络跳转。坏处是强耦合代理工具一升级插件可能就失效而且不同代理工具的插件机制不一样没法复用。第二种是本地 HTTP 代理caveman 起一个本地服务编码代理把请求发到这个本地端口caveman 处理完再转发给真正的模型端点。这是 caveman 最终采用的方案。它的好处是解耦彻底代理工具只需要把 base URL 指向本地端口就行不关心 caveman 内部怎么实现。坏处是多了一跳网络开销不过本地回环的延迟可以忽略不计。第三种是远程代理把转换逻辑部署在远端服务器上。这个方案我很快就放弃了因为编码代理的请求里经常包含代码片段走远程意味着代码要离开本地安全上不放心而且网络抖动会直接影响开发体验。最终选本地 HTTP 代理核心考量是解耦和可控性的平衡。本地回环保证了延迟和隐私HTTP 接口保证了通用性任何能配置 base URL 的代理工具都能接进来。2.2 请求生命周期拆解caveman 处理一个请求大致经过这几个阶段接收与解析本地服务收到代理发来的请求先解析出目标端点、请求方法、请求体。这一步要特别小心因为不同代理工具的请求体结构差异很大有的用messages数组有的用input字段解析逻辑必须足够宽容。格式转换把代理的请求格式转换成模型端点期望的格式。这是 proxy object 转换的核心。比如代理可能把系统提示放在单独的字段里而模型端点要求它作为第一条消息。转换规则需要可配置因为不同模型端点的要求不一样。token 预估与统计在转发之前先对请求体做一次 token 预估。预估不是为了精确而是为了给用户一个量级参考。真正的 token 数要等模型返回后才能确认但预估能让你在发请求前就知道这次调用大概要花多少。转发与响应处理把转换后的请求发给真正的模型端点拿到响应后再转换回代理能解析的格式。这一步要处理流式响应因为编码代理通常需要流式输出才能实时显示。错误拦截与重试如果模型端点返回错误比如 401、403、404、503caveman 要判断这个错误是暂时的还是永久的决定是否重试以及重试时要不要调整请求。这个生命周期看起来简单但每个阶段都有坑。比如格式转换阶段如果代理发来的是流式请求转换逻辑必须保持流式特性不能把流式响应缓冲成完整响应再返回否则代理的实时显示就废了。2.3 为什么不用现成的网关方案有人可能会问为什么不直接用 Nginx 或 Envoy 做代理答案是它们不懂 token 和编码代理的语义。Nginx 能做转发能做负载均衡但它不知道什么是 token 用量不知道编码代理的请求格式更不会在token exchange failed的时候帮你分析原因。caveman 的价值不在于转发而在于理解请求的内容并基于内容做决策。这是通用网关做不到的。3. 核心细节解析proxy object 转换与 token 统计3.1 proxy object 转换的三种模式proxy object 转换是 caveman 最核心的部分。我把它归纳为三种模式对应不同的转换需求。字段映射模式最简单的转换把代理请求里的字段 A 映射到模型端点的字段 B。比如代理用prompt字段模型端点用input字段那就做一个映射。这种模式适合结构差异不大的场景。结构重组模式代理和模型端点的请求结构差异较大需要重新组织。比如代理把对话历史放在history数组里当前消息放在message字段里而模型端点要求所有消息按顺序放在一个messages数组里。这时候就需要把history和message合并成一个数组并保证顺序正确。语义适配模式最复杂的转换不仅改结构还要改语义。比如代理发送的system提示可能包含工具定义而模型端点要求工具定义放在单独的tools字段里。这时候需要从system提示里解析出工具定义再放到正确的位置。caveman 的转换配置用一份声明式的规则文件描述每条规则指定源字段、目标字段、转换模式。这样新增一个模型端点时只需要加一份规则不用改代码。3.2 token 预估的实用算法token 预估不需要精确但需要稳定且可解释。我用的是一个基于字符类型的加权算法英文字母和数字每个字符约 0.25 token中文汉字每个字符约 1.5 token标点和符号每个字符约 0.5 token代码块在基础估算上乘以 1.2 的系数因为代码里的符号密度高这个算法当然不精确实测下来和真实 token 数的偏差在 15% 到 30% 之间。但它足够快能在请求发出前瞬间给出一个量级参考。更重要的是它可解释——用户能看懂为什么这次预估是 500 token 而不是 300 token。真正的 token 统计要等模型返回。模型响应里通常带usage字段包含prompt_tokens、completion_tokens、total_tokens。caveman 把这些数据记录下来按会话、按端点、按时间段聚合。这样你就能看到哪个会话最费 token哪个端点的响应最冗长。3.3 流式响应的处理要点编码代理大多需要流式响应因为用户要实时看到代码生成过程。caveman 处理流式响应时有几个关键点不能缓冲一旦缓冲流式就变成批式代理的实时显示会卡住。要能拦截错误流式响应中途可能出错caveman 要能在流中插入错误信息让代理知道出了问题。要能统计 token流式响应的 token 统计比较麻烦因为响应是分块到达的。我的做法是在流结束时根据累计的响应内容做一次估算再和模型返回的usage做校准。注意流式响应处理是 caveman 里最容易出 bug 的地方。我踩过的坑包括分块边界把 JSON 切断了、流中途断开没有正确关闭连接、错误信息混进了正常响应流。建议在实现时先把非流式路径跑通再逐步加流式支持。4. 实操过程从零搭建 caveman 代理层4.1 环境准备与依赖选择caveman 用 Python 实现核心依赖只有三个fastapi做 HTTP 服务httpx做异步转发pydantic做请求校验。选 Python 是因为编码代理生态里 Python 工具链最成熟调试也方便。选 FastAPI 是因为它原生支持异步和流式响应写起来简洁。安装依赖pip install fastapi httpx pydantic uvicorn启动服务uvicorn caveman.main:app --host 127.0.0.1 --port 8787端口选 8787 是随意的只要不和代理工具本身的端口冲突就行。启动后把编码代理的 base URL 指向http://127.0.0.1:8787caveman 就开始工作了。4.2 转换规则的编写与调试转换规则用 YAML 描述放在rules/目录下每个模型端点一份。以某个常见端点为例endpoint: /v1/responses mapping: - source: prompt target: input mode: field - source: history target: messages mode: restructure merge_with: message - source: system target: instructions mode: semantic extract_tools: true调试转换规则时我建议开一个--dry-run模式caveman 只做转换不转发把转换前后的请求体都打印出来。这样你能直观看到字段有没有映射对结构有没有重组对。我最初写规则时经常出现messages数组顺序错乱的问题用 dry-run 一眼就看出来了。4.3 token 统计的落地实现token 统计分两块预估和实测。预估在请求转发前做实测在响应返回后做。两者都记录到本地 SQLite 数据库表结构大致是字段类型说明idINTEGER自增主键session_idTEXT会话标识endpointTEXT目标端点estimated_tokensINTEGER预估 token 数actual_tokensINTEGER实测 token 数timestampDATETIME请求时间有了这张表你就能做各种聚合查询。比如查今天哪个会话最费 tokenSELECT session_id, SUM(actual_tokens) as total FROM token_usage WHERE date(timestamp) date(now) GROUP BY session_id ORDER BY total DESC LIMIT 10;这个查询我几乎每天都会跑一次用来发现异常的 token 消耗。有一次发现某个会话的 token 数是平时的十倍排查后发现是代理陷入了循环调用每次都在重复发送同样的上下文。如果没有 token 统计这种问题很难被发现。4.4 错误拦截与重试策略caveman 拦截的错误分三类处理策略不同认证类错误401、403不重试直接返回给代理。这类错误通常是 token 失效或权限不足重试没有意义。但 caveman 会在错误信息里附加排查建议比如“检查 token 是否过期”“确认端点权限配置”。端点类错误404、503有限重试最多三次每次间隔递增。404 可能是端点路径配错了503 可能是服务暂时不可用。重试时 caveman 会记录每次的请求体方便对比。转换类错误不重试因为转换逻辑是确定性的重试结果一样。这类错误需要人工介入caveman 会把转换前后的请求体都保存下来方便定位。实操心得重试策略一定要有上限而且要记录重试日志。我曾经因为重试没有上限导致代理在端点持续 503 时疯狂重试token 消耗瞬间飙升。后来加了上限和退避问题就解决了。5. 常见问题与排查技巧实录5.1 端点报错速查表报错信息可能原因排查方向cc switch local proxy failed while handling codex endpoint /responses转换规则不匹配端点格式检查 rules 目录下对应端点的规则文件unexpected status 404 not found端点路径配错确认模型端点的真实路径对比规则文件里的 endpointunexpected status 401 unauthorizedtoken 失效或未配置检查代理工具的认证配置确认 token 有效unexpected status 503 service unavailable模型服务暂时不可用等待后重试或切换到备用端点token exchange failed认证流程中断检查认证端点的可达性确认请求格式正确unsupport proxy type代理类型不支持确认 caveman 支持的代理类型列表这张表是我在实际使用中逐步积累的每次遇到新报错就加一行。现在它已经成了我排查问题的第一站大部分常见错误都能在表里找到方向。5.2 三个独家避坑技巧技巧一请求体快照。caveman 在转换前后各保存一份请求体快照存在snapshots/目录下按时间戳命名。出问题时对比两份快照就能看出转换逻辑哪里出了问题。这个功能帮我省了大量 debug 时间强烈建议实现。技巧二端点健康检查。caveman 启动时对配置的每个端点做一次健康检查确认端点可达、认证有效。这样能在代理开始工作前就发现配置问题而不是等代理报错才发现。健康检查的结果记录在日志里方便回溯。技巧三token 预算告警。给每个会话设置 token 预算当累计消耗超过预算的 80% 时caveman 在响应里附加告警信息。这样你能在 token 耗尽前及时调整避免代理突然中断。预算值可以按会话配置不同任务的预算不一样。5.3 性能调优的实测数据caveman 作为本地代理性能开销主要在两块格式转换和 token 预估。我做过实测在普通开发机上格式转换平均耗时 2 到 5 毫秒取决于请求体大小和规则复杂度。token 预估平均耗时 1 到 3 毫秒取决于文本长度。总开销相比直连模型端点caveman 增加的延迟在 10 毫秒以内。这个开销完全可以接受。如果发现延迟明显增加通常是转换规则写得太复杂或者 token 预估算法做了不必要的重复计算。优化方向是简化规则、缓存预估结果。6. 后续扩展方向与个人体会caveman 目前只做了最核心的代理转换和 token 统计但它的架构留了不少扩展空间。我接下来想做的几个方向一是多端点路由。根据请求内容自动选择最合适的模型端点比如代码生成走一个端点文本总结走另一个端点。这样能进一步优化成本和效果。二是请求缓存。对于重复的请求比如同样的代码片段反复询问caveman 可以缓存响应直接返回省掉一次模型调用。缓存键用请求体的哈希值缓存有效期可配置。三是可视化面板。现在 token 统计只能通过 SQL 查询不够直观。做一个简单的 Web 面板实时显示 token 消耗曲线、端点健康状态、错误分布会大大提升可用性。我个人在实际操作中的体会是做代理层这件事最难的不是转发而是理解。理解代理的请求语义理解模型端点的格式要求理解 token 的消耗规律。caveman 的每一行代码本质上都是在把这种理解固化下来。当你把理解变成规则、变成统计、变成告警编码代理的使用就从“凭感觉”变成了“有依据”。这个转变才是 caveman 真正的价值所在。最后分享一个小技巧如果你也在做类似的代理层建议从最小可用版本开始先只做转发和日志跑通链路后再逐步加转换和统计。我最初想一步到位结果转换规则写得太复杂反而把简单问题搞复杂了。后来退回去先做转发再加转换再加统计每一步都验证通过再往下走整个过程顺畅多了。