1. 从“caveman”说起一个AI编码代理的极简主义实践第一次看到“caveman”这个词被用来命名一个AI coding agent项目时我脑子里浮现的画面是一个原始人拿着石斧对着键盘一顿猛敲。但真正用过之后才发现这个名字起得极其精准——它做的事情就是把那些花里胡哨的AI编码工具剥到只剩骨架用最原始、最直接的方式完成代码生成任务。这个项目解决的核心问题很具体当你手头有一堆零散的代码片段、配置文件、脚本想让AI帮你补全、重构或者生成新代码时大多数方案要么太重需要完整的IDE插件、复杂的项目索引要么太贵按token计费长上下文烧钱如流水。caveman的思路是用一个轻量的本地代理层把请求做最小化封装只传必要的上下文让AI coding agent在token消耗和响应质量之间找到一个平衡点。适合谁来参考如果你是一个经常用AI辅助写代码的开发者手头有多个模型API需要切换或者你在做本地化的代码生成工具链那这个项目的设计思路值得细看。它不依赖特定平台核心逻辑就是“代理转发上下文裁剪token控制”这套东西放在任何AI编码场景里都能复用。我花了大概两周时间把这个项目的核心机制拆了一遍又在自己的开发环境里复现了一套类似的代理层。下面把整个思路、实现细节、踩过的坑以及token管理的实操经验完整地分享出来。2. 整体架构设计为什么是“代理裁剪”而不是“全量直连”2.1 核心设计思路拆解caveman的架构可以用一句话概括在开发者和AI模型之间插入一个本地代理层这个代理层负责三件事——请求路由、上下文裁剪、token计量。为什么要在中间加一层直接调模型API不行吗行但有几个现实问题。第一当你同时用多个模型比如一个负责代码补全一个负责代码审查每个模型的API格式、认证方式、endpoint都不一样直接在代码里硬编码切换逻辑会非常乱。第二AI编码场景下上下文往往包含大量重复的代码文件内容如果每次都全量发送token消耗会迅速失控。第三本地开发环境经常需要离线或者半离线工作代理层可以做缓存和降级处理。这个设计思路的本质是“关注点分离”让代理层处理通信和资源管理让AI agent专注在代码生成逻辑上。我实测下来这种分层在项目规模变大之后优势非常明显——换模型只需要改代理配置不用动业务代码。2.2 代理层的选型考量代理层用什么实现caveman选择的是轻量级的本地HTTP服务而不是重量级的网关方案。这个选择背后有明确的取舍。重量级网关比如基于Nginx或者Kong的方案功能强大支持负载均衡、限流、鉴权但对于个人开发者或者小团队来说配置成本太高而且引入的依赖太多。caveman的场景是本地开发辅助请求量不大但要求启动快、配置简单、资源占用低。所以它用了一个简单的HTTP代理监听本地端口转发请求到目标模型API。这里有一个关键细节代理层需要支持多种认证方式。不同模型API的token传递方式不一样有的用Bearer token有的用自定义header有的把token放在query参数里。代理层要做的是统一入口然后根据目标endpoint自动适配认证方式。这个逻辑如果用硬编码会很难维护caveman的做法是维护一个endpoint配置表每个endpoint对应一套认证规则和请求模板。注意代理层处理认证信息时一定要确保token不会泄露到日志或者错误信息里。我见过不少项目在调试时把完整请求打出来结果token直接暴露在控制台。2.3 上下文裁剪的策略这是caveman最核心的部分。AI编码场景下上下文通常包括当前编辑的文件内容、相关的依赖文件、项目配置文件、历史对话记录。如果全部发送token消耗会非常夸张。一个中等规模的TypeScript项目光是把相关文件内容拼起来就可能超过10万token。caveman的裁剪策略是分层的。第一层是“必要上下文”包括当前光标附近的代码、最近修改的文件、显式引用的符号定义。第二层是“可选上下文”包括同目录下的其他文件、类型定义文件、配置文件。第三层是“按需加载”只有当AI明确请求某个文件内容时才发送。这个策略的实现依赖于一个简单的符号索引。代理层在启动时会扫描项目目录建立一个轻量的文件-符号映射表。当请求到来时根据当前文件和光标位置快速定位到相关符号只提取这些符号所在的代码片段。我试过在一个约5万行的项目里用这套逻辑平均每次请求的上下文从原来的8万token降到了1.2万token左右效果非常明显。2.4 token计量的实现方式token计量不是简单地数一下字符数。不同模型的tokenizer不一样同样的文本在不同模型下的token数可能差20%以上。caveman的做法是在代理层维护一个token计数模块根据目标模型选择对应的tokenizer。对于没有公开tokenizer的模型用一个近似算法英文按4个字符1个token中文按1.5个字符1个token代码按3个字符1个token。这个近似在实际使用中误差在10%以内对于预算控制来说足够了。计量结果会记录在本地的一个轻量数据库里按天、按模型、按项目维度统计。这个数据对于优化上下文裁剪策略非常有价值——你可以清楚地看到哪些请求消耗了大量token但产出质量不高然后针对性地调整裁剪规则。3. 核心细节解析请求路由与token管理的实操要点3.1 请求路由的配置方法代理层的路由配置是整个系统的入口。caveman用一个YAML文件来定义路由规则每条规则包含匹配模式、目标endpoint、认证方式、超时设置、重试策略。routes: - name: code-completion match: /v1/completions target: https://api.example.com/v1/completions auth: type: bearer token_env: CODE_MODEL_TOKEN timeout: 30 retry: 2 - name: code-review match: /v1/chat/completions target: https://api.another.com/v1/chat/completions auth: type: header header_name: X-API-Key token_env: REVIEW_MODEL_KEY timeout: 60 retry: 1这个配置的好处是新增一个模型只需要加一段配置不用改代码。token通过环境变量注入避免硬编码在配置文件里。实际配置时有一个容易忽略的点超时设置要根据模型响应速度来定。代码补全类请求通常要求快速返回超时设短一点15-30秒代码审查类请求可以接受较长等待超时设长一点60-120秒。如果超时设得太短复杂请求会被频繁中断设得太长代理层会堆积大量等待中的连接。3.2 token续签与失效处理AI模型的访问token通常有有效期短则几小时长则几天。token失效是开发过程中最常遇到的问题之一。caveman的处理方式是在代理层实现一个token刷新机制当检测到401或者403响应时自动触发刷新流程然后用新token重试原请求。刷新流程本身不复杂关键是并发控制。如果多个请求同时发现token失效不能每个请求都去刷新一次否则会触发多次刷新导致token冲突。正确的做法是用一个锁或者信号量保证同一时间只有一个刷新操作在进行其他请求等待刷新完成后复用新token。import threading class TokenManager: def __init__(self): self._token None self._lock threading.Lock() self._refreshing False def get_token(self): if self._token is None: self._refresh() return self._token def _refresh(self): with self._lock: if self._refreshing: return self._refreshing True try: self._token self._do_refresh() finally: self._refreshing False这个逻辑看起来简单但实际写的时候要注意异常处理。如果刷新失败比如网络问题或者认证服务不可用要有降级策略——要么返回明确的错误让上层处理要么使用一个短期有效的缓存token。提示token刷新失败时不要无限重试。设置一个最大重试次数比如3次超过后直接报错避免请求堆积。3.3 上下文裁剪的具体实现上下文裁剪的核心是“只发送必要的信息”。实现上分三步解析当前文件、提取相关符号、组装上下文。第一步解析当前文件。用轻量的语法分析器比如tree-sitter提取当前文件的AST找到光标位置对应的函数、类、变量声明。这一步不需要完整的类型信息只需要语法层面的结构。第二步提取相关符号。根据AST中的引用关系找到当前符号依赖的其他符号。比如当前函数调用了另一个模块的函数就把那个函数的定义提取出来。这里要控制递归深度通常两层就够了——再深的依赖关系对当前请求的帮助有限但token消耗会显著增加。第三步组装上下文。把提取到的代码片段按重要性排序重要的放前面次要的放后面。如果总token数超过预算从后往前截断。预算根据模型的最大上下文长度和当前请求的复杂度动态调整。我实测下来这套裁剪逻辑在大多数场景下能把上下文压缩到原来的15%-25%而代码生成质量几乎没有下降。唯一需要注意的是如果项目里有大量动态引用比如通过字符串反射调用的函数裁剪可能会漏掉一些关键上下文。这种情况下需要手动在请求里附加提示告诉AI去查找特定文件。3.4 多模型切换的实操细节caveman支持同时配置多个模型根据请求类型自动路由。比如代码补全用响应快的轻量模型代码审查用推理能力强的重量级模型。切换逻辑的关键是“请求分类”。代理层需要判断当前请求属于哪一类。判断依据可以是请求的endpoint、请求体里的参数、或者自定义的header。最简单的方式是在客户端显式指定比如在请求header里加一个X-Task-Type: completion代理层根据这个值选择路由。如果不想改客户端也可以用启发式规则请求体里包含max_tokens且值较小比如小于200判定为补全类包含messages数组且长度大于3判定为对话类包含temperature且值大于0.8判定为创意类。这些规则不是100%准确但在实际使用中覆盖率能达到90%以上。多模型切换还有一个隐藏问题不同模型的输出格式可能不一样。有的返回纯文本有的返回JSON有的返回带markdown代码块的文本。代理层需要做一层输出归一化把不同格式统一成客户端期望的格式。这个归一化逻辑要尽量简单只做必要的转换不要试图“美化”输出否则会引入不可预期的行为。4. 实操过程从零搭建一个本地AI编码代理4.1 环境准备与依赖安装搭建代理层不需要太重的环境。基础依赖就三个一个HTTP服务框架Python用FastAPI或者FlaskNode.js用Express、一个HTTP客户端Python用httpxNode.js用axios、一个YAML解析库。pip install fastapi uvicorn httpx pyyaml tiktokentiktoken是用来做token计数的如果你用的模型不是OpenAI系列可以换成对应的tokenizer库或者用前面提到的近似算法。环境变量配置export CODE_MODEL_TOKENyour-token-here export REVIEW_MODEL_KEYyour-key-here export PROXY_PORT8787注意token不要写在代码或者配置文件里用环境变量或者本地密钥管理工具。如果团队协作确保每个人用自己的token不要共享。4.2 代理服务的核心代码实现代理服务的核心逻辑就是一个请求转发器加上前面说的路由、认证、裁剪、计量四个模块。from fastapi import FastAPI, Request, HTTPException import httpx import yaml import os app FastAPI() config yaml.safe_load(open(routes.yaml)) app.post(/{path:path}) async def proxy(path: str, request: Request): body await request.json() route match_route(path, body) if not route: raise HTTPException(status_code404, detailNo matching route) token os.environ.get(route[auth][token_env]) if not token: raise HTTPException(status_code500, detailToken not configured) headers build_headers(route, token) trimmed_body trim_context(body, route) async with httpx.AsyncClient(timeoutroute[timeout]) as client: resp await client.post( route[target], jsontrimmed_body, headersheaders ) record_usage(route[name], trimmed_body, resp) return resp.json()这段代码看起来简单但每个函数里面都有细节。match_route要根据路径和请求体内容匹配路由规则build_headers要根据认证类型组装headertrim_context是上下文裁剪的核心逻辑record_usage负责token计量和记录。4.3 上下文裁剪模块的详细实现裁剪模块是整个代理层最复杂的部分。我用一个简化的例子来说明核心逻辑。假设当前请求是要补全一个TypeScript函数请求体里包含了当前文件的完整内容。裁剪模块要做的是解析文件AST找到光标位置对应的函数节点。提取该函数的完整代码包括函数签名和函数体。查找函数体内引用的其他符号变量、函数调用、类型引用。对于每个引用符号在项目索引里查找其定义位置提取定义代码。把提取到的代码片段按“当前函数 直接依赖 间接依赖”的顺序拼接。如果总token数超过预算从间接依赖开始截断。def trim_context(body, route): if route.get(trim, True) is False: return body messages body.get(messages, []) if not messages: return body last_message messages[-1][content] current_file extract_current_file(last_message) if not current_file: return body ast parse_ast(current_file) cursor_pos extract_cursor_position(last_message) symbol find_symbol_at(ast, cursor_pos) context_parts [extract_code(symbol)] dependencies find_dependencies(symbol, ast) for dep in dependencies[:5]: dep_code lookup_symbol(dep) if dep_code: context_parts.append(dep_code) trimmed_content \n\n.join(context_parts) messages[-1][content] trimmed_content return body这个实现是简化版实际项目中还需要处理很多边界情况光标不在任何符号内怎么办、依赖符号找不到定义怎么办、多个文件同时修改怎么办。但核心思路就是这样——用语法结构而不是文本匹配来定位相关代码。4.4 token计量与预算控制token计量模块负责两件事计算当前请求的token数、记录历史消耗。计算token数用tiktokenimport tiktoken def count_tokens(text, modelgpt-4): try: enc tiktoken.encoding_for_model(model) except KeyError: enc tiktoken.get_encoding(cl100k_base) return len(enc.encode(text))记录历史消耗用一个简单的SQLite数据库import sqlite3 def record_usage(route_name, request_body, response): conn sqlite3.connect(usage.db) conn.execute( CREATE TABLE IF NOT EXISTS usage ( id INTEGER PRIMARY KEY AUTOINCREMENT, route TEXT, prompt_tokens INTEGER, completion_tokens INTEGER, timestamp DATETIME DEFAULT CURRENT_TIMESTAMP ) ) prompt_tokens count_tokens(str(request_body)) completion_tokens count_tokens(str(response.json())) conn.execute( INSERT INTO usage (route, prompt_tokens, completion_tokens) VALUES (?, ?, ?), (route_name, prompt_tokens, completion_tokens) ) conn.commit() conn.close()预算控制是在裁剪阶段做的。每个路由可以配置一个max_prompt_tokens裁剪后的上下文如果超过这个值就从后往前截断。截断的粒度是代码片段不是字符避免把一段完整的代码切成两半。我一般把补全类请求的预算设在2000-4000 token审查类请求设在8000-12000 token。这个范围是根据实际使用经验定的——再低会影响生成质量再高token消耗增长太快。4.5 本地调试与验证方法代理层写完之后不要直接接到生产环境用。先用curl或者Postman做本地验证。curl -X POST http://localhost:8787/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [{role: user, content: 补全这个函数}], max_tokens: 200 }验证要点请求是否正确路由到目标endpoint、认证信息是否正确传递、响应是否正常返回、token计量是否记录。调试时建议打开详细日志但要注意日志里不能包含token。可以用一个中间件在记录日志前把敏感信息替换掉def sanitize_log(data): if isinstance(data, dict): return {k: *** if token in k.lower() or key in k.lower() else sanitize_log(v) for k, v in data.items()} return data5. 常见问题与排查技巧实录5.1 token失效与刷新失败的处理token失效是最高频的问题。表现通常是请求返回401或者403错误信息里包含“token expired”或者“invalid token”。排查步骤检查环境变量里的token是否设置正确。检查token是否过期有些token的过期时间编码在token本身里可以解码查看。检查刷新逻辑是否正常触发。检查刷新后的token是否正确保存和复用。如果刷新失败常见原因有刷新接口的认证信息也过期了、网络问题导致刷新请求超时、刷新返回的token格式和预期不一致。对于第一种情况需要重新走一遍完整的登录流程获取新token对于后两种情况检查网络连接和刷新接口的响应格式。提示在token管理模块里加一个“最后刷新时间”的记录如果超过一定时间没有刷新成功主动告警。5.2 代理请求超时与重试策略超时问题通常出现在模型响应慢或者网络不稳定的情况下。表现是请求长时间挂起最终返回504或者连接断开。处理策略分两层第一层是设置合理的超时时间第二层是配置重试。超时时间根据请求类型设置补全类15-30秒对话类30-60秒审查类60-120秒。重试策略用指数退避第一次重试等1秒第二次等2秒第三次等4秒最多重试3次。import asyncio async def request_with_retry(client, url, json, headers, max_retries3): for attempt in range(max_retries): try: resp await client.post(url, jsonjson, headersheaders) if resp.status_code 500: return resp except (httpx.TimeoutException, httpx.ConnectError): pass if attempt max_retries - 1: await asyncio.sleep(2 ** attempt) raise Exception(Max retries exceeded)注意不是所有错误都值得重试。4xx错误除了429通常重试也没用直接返回给客户端。5xx错误和网络错误才需要重试。5.3 上下文裁剪导致的生成质量下降裁剪上下文是为了省token但如果裁得太狠AI会因为缺少必要信息而生成错误代码。表现是生成的代码引用了不存在的变量、调用了未定义的函数、或者类型不匹配。排查方法对比裁剪前后的请求内容看是否漏掉了关键符号。可以在代理层加一个“裁剪日志”记录每次裁剪掉了哪些内容然后人工检查这些内容是否真的不重要。如果发现裁剪导致质量问题调整策略增加依赖查找的递归深度、提高token预算、或者对特定类型的请求关闭裁剪。我个人的经验是对于简单的补全请求比如补全一个函数体裁剪到只保留当前函数和直接依赖就够了对于复杂的重构请求需要保留更完整的上下文这时候宁可多花token也不要裁得太狠。5.4 多模型输出格式不一致的处理不同模型的输出格式差异很大。有的返回纯文本有的返回JSON有的在JSON里嵌套markdown代码块。如果客户端期望统一格式代理层需要做归一化。归一化策略模型输出格式归一化处理纯文本直接返回JSON带code字段提取code字段内容JSON带content字段提取content字段内容markdown代码块提取代码块内的内容混合格式按优先级提取优先取代码块归一化逻辑要尽量简单不要做复杂的解析。如果格式太复杂宁可返回原始内容让客户端处理也不要在代理层做过多转换。5.5 常见问题速查表问题现象可能原因排查方法解决方案401 Unauthorizedtoken失效或未配置检查环境变量和token有效期刷新token或重新配置403 Forbiddentoken权限不足检查token的scope申请更高权限的token404 Not Foundendpoint配置错误检查路由配置修正target地址504 Gateway Timeout模型响应超时检查网络和模型状态增加超时时间或重试生成质量下降上下文裁剪过度对比裁剪前后内容调整裁剪策略token消耗异常上下文未裁剪或裁剪失效检查裁剪模块日志修复裁剪逻辑代理启动失败端口被占用或配置错误检查端口和配置文件更换端口或修正配置6. 个人实操体会与后续扩展方向这套代理层的设计思路我在多个项目里复用过每次都会根据具体场景做调整。最大的体会是token管理不是简单地“省着用”而是“把token花在刀刃上”。该给的上下文一定要给足不该给的坚决裁掉。我见过太多项目为了省token把上下文裁得七零八落结果AI生成的代码根本不能用反而浪费了更多时间和token去调试。另一个体会是代理层的日志和监控非常重要。没有数据支撑你根本不知道token花在哪里了、哪些请求质量差、哪些模型性价比高。我一般会在代理层加一个简单的dashboard按天展示token消耗和请求量每周review一次根据数据调整路由策略和裁剪规则。后续可以扩展的方向有几个一是加入缓存层对于相同的请求直接返回缓存结果进一步降低token消耗二是支持流式响应对于长代码生成场景流式返回可以显著提升用户体验三是加入质量评估模块自动评估生成代码的质量低质量请求自动重试或者切换模型。最后分享一个小技巧在代理层加一个“dry run”模式只做上下文裁剪和token计算不实际发送请求。这个模式在调试裁剪策略时非常有用可以快速看到不同裁剪规则下的token消耗而不用真的花钱调模型。