1. 项目缘起为什么我要折腾一个叫 caveman 的东西先说清楚 caveman 是什么。它不是一个库不是一个框架更不是一个能跑起来就完事的脚手架。caveman 是我自己给一套AI coding agent 的最小化运行方案起的代号。核心思路就一句话把 AI 编码助手的能力塞进一个足够原始、足够笨、但足够可控的壳里让它只干一件事——在终端里帮我写代码、改代码、跑命令不搞花里胡哨的界面不依赖一堆我根本看不明白的云端服务。你可能会问现在市面上 AI coding agent 那么多为什么还要自己搭原因很直接token 用量不可控、代理链路不透明、npx 拉起来的工具链经常在关键时刻掉链子。我用过不少现成的方案刚开始都挺爽用着用着就发现要么是 token 烧得比我预期快得多要么是某个环节的 proxy 配置出了问题报一堆token exchange failed、cc switch local proxy failed之类的错误排查起来极其痛苦。caveman 就是在这种背景下诞生的——我要一个我能完全掌控每一层的东西从 prompt 怎么拼、token 怎么算、请求怎么发、代理怎么走到最终代码怎么落盘全部透明。这篇文章适合谁看如果你是一个经常在终端里干活的后端或全栈开发者对 AI coding agent 有兴趣但被各种 token 计费、代理配置、npx 安装失败搞烦过那这篇内容就是写给你的。如果你只是想找个开箱即用的图形化工具那 caveman 可能不适合你因为它本质上是一套你自己要理解每一层在干什么的方案。我不打算把它包装成一个产品它就是一份实操记录和思路拆解。2. 整体设计思路为什么选择“原始人”路线2.1 核心矛盾能力与可控性的取舍做 AI coding agent本质上是在解决一个矛盾你希望模型能力越强越好但能力越强意味着上下文越长、token 消耗越大、请求链路越复杂。现成的 agent 工具通常帮你把这一切封装好了你只需要填个 API key 就能用。但封装带来的问题是当出问题的时候你根本不知道是哪一层挂了。我踩过最典型的一个坑是某次用某个 agent 工具改一个中等规模的代码库改到一半突然开始报错日志里全是unexpected status 401 unauthorized和token exchange failed。我花了将近两个小时才定位到问题出在工具内部的一个 proxy 层它在 token 刷新的时候没有正确处理过期逻辑导致 refresh token 变成了空字符串然后整个链路就崩了。如果这套东西是我自己写的我五分钟就能看出来问题在哪。所以 caveman 的第一个设计原则就是每一层都必须是我能看懂、能改、能替换的。不追求功能大而全追求的是当它坏掉的时候我知道它为什么坏。2.2 架构选型为什么是终端 脚本 最小依赖caveman 的整体架构非常朴素朴素到有点“原始”这也是它名字的由来。它由三个部分组成一个终端交互层负责接收我的自然语言指令把当前工作目录的上下文拼进去然后调用模型。一个请求编排层负责管理 token 计数、prompt 组装、请求发送和响应解析。一个动作执行层负责把模型返回的代码变更或命令真正落到文件系统和 shell 里。这三层之间通过标准输入输出和文件来通信没有复杂的进程间通信没有消息队列没有数据库。为什么这么设计因为每一层都可以单独测试、单独替换。比如我后来把请求编排层从直接调用某家 API 换成了走一个本地转发只改了一个配置文件其他两层完全不用动。关于依赖我给自己定了一条硬规矩能用标准库解决的绝不引入第三方包。这不是因为我讨厌第三方库而是因为每引入一个依赖就多一个在关键时刻出问题的可能。你肯定遇到过npx playwright install失败的情况或者某个包在特定 Node 版本下行为不一致。caveman 的核心逻辑用 Python 标准库就能写完唯一的外部依赖是一个 HTTP 客户端库而且我把它封装得很薄随时可以换掉。2.3 token 管理的设计哲学把账算清楚token 是这个方案里最敏感的东西。不是因为它贵而是因为它不可见。大多数 agent 工具不会告诉你每次请求到底用了多少 token你只能月底看账单。caveman 的做法是在请求编排层里内置一个 token 计数器每次请求前后都记录本次请求的 prompt token 数本次请求的 completion token 数累计消耗当前上下文窗口的占用比例这个计数器不是精确到每一个 token 的那需要引入 tokenizer 库会增加依赖而是基于字符数和经验系数做估算。实测下来对于英文和代码混合的内容估算误差在 10% 以内足够我判断“这次改动会不会把上下文撑爆”。提示如果你对 token 精度要求极高可以在编排层里挂一个真正的 tokenizer但要注意它本身也会消耗内存和启动时间。我的建议是日常开发用估算就够了只有在做成本核算的时候才需要精确值。3. 核心细节拆解从 prompt 到代码落盘3.1 prompt 组装上下文不是越多越好很多人用 AI coding agent 的时候习惯把整个项目目录都塞进上下文觉得信息越多模型越聪明。实测下来这是个误区。上下文越长模型越容易“迷失”在无关信息里而且 token 消耗会指数级上升。caveman 的 prompt 组装策略是按需注入。具体来说每次请求只包含以下几类信息当前任务描述我输入的自然语言指令原样保留。当前文件内容如果任务涉及某个具体文件只注入那个文件的内容不注入整个目录。相关文件摘要如果任务需要跨文件理解注入相关文件的函数签名和注释不注入完整实现。最近几次操作记录保留最近 3 到 5 次的操作和结果让模型知道上下文但不无限累积。这个策略的核心是控制上下文窗口的占用。我做过一个对比测试同一个重构任务全量注入项目上下文时prompt token 数大约是 12000而按需注入只有 2800 左右模型输出的质量反而更好因为它不会被无关代码干扰。3.2 请求发送代理链路要透明请求发送这一层是我踩坑最多的地方。因为网络环境的复杂性很多时候请求不是直接发到目标服务的中间会经过各种转发。问题在于很多工具把这一层封装得太好导致出问题的时候你根本不知道请求到底走到哪一步挂了。caveman 的做法是把代理配置显式化。我在配置文件里明确写出请求要经过哪些环节每一跳的地址、端口、认证方式都写清楚。这样做的好处是当出现token exchange failed或者unexpected status 403 forbidden这类错误时我可以逐跳排查快速定位是哪一段链路出了问题。具体配置上我遵循几个原则认证信息不硬编码token 和密钥从环境变量读取不写进代码或配置文件。超时时间显式设置每个请求都设置连接超时和读取超时避免请求卡死。失败重试有上限重试次数不超过 3 次且每次重试间隔递增避免雪崩。注意如果你在请求链路里用了任何形式的转发一定要确保转发层对 token 刷新逻辑的处理是正确的。我遇到过好几次failed to refresh token: 400 bad request的错误根源都是转发层在 token 过期后没有正确传递刷新请求。3.3 动作执行代码落盘前的三道检查模型返回代码变更后不能直接写进文件。caveman 在执行层设置了三道检查语法检查对返回的代码片段做基本的语法解析如果解析失败直接拒绝执行把错误返回给模型让它重新生成。差异检查把模型返回的变更和当前文件内容做 diff如果 diff 过大比如超过文件内容的 50%触发人工确认。备份检查每次修改前自动备份原文件到临时目录保留最近 10 个版本。这三道检查看起来简单但实际用下来能挡掉大部分“模型幻觉”导致的问题。尤其是差异检查有好几次模型返回的代码看起来没问题但 diff 一出来发现它把整个文件重写了这种时候人工确认一下往往能发现模型理解错了任务。4. 实操过程从零搭起 caveman 的完整步骤4.1 环境准备与依赖安装先说环境。我用的是 Python 3.10 以上操作系统不限macOS、Linux、Windows 的 WSL 都跑过。核心依赖只有一个 HTTP 客户端库我选的是httpx因为它支持同步和异步两种模式而且对超时和重试的控制比较细。安装步骤很简单python3 -m venv caveman-env source caveman-env/bin/activate pip install httpx如果你不想用虚拟环境直接全局安装也行但我不推荐因为 caveman 的依赖虽然少但版本冲突这种事一旦发生就很烦。关于npx相关的问题这里要特别说明一下。caveman 本身不依赖 Node.js但如果你要在方案里集成某些基于 Node 的工具比如某些 MCP server就会用到npx。我遇到过npx playwright install失败的情况排查下来通常是网络问题或者缓存损坏。解决办法是清理 npm 缓存后重试npm cache clean --force npx playwright install --with-deps如果还是失败检查一下你的 npm registry 配置确保指向的是可访问的源。4.2 配置文件的结构与参数说明caveman 的配置文件是一个 JSON 文件结构如下{ model: { endpoint: https://api.example.com/v1/chat/completions, model_name: coding-model-v1, max_tokens: 4096, temperature: 0.2 }, token: { estimate_ratio: 0.75, context_limit: 128000, warn_threshold: 0.8 }, proxy: { enabled: false, hops: [] }, execution: { backup_dir: ./.caveman_backups, max_backups: 10, diff_threshold: 0.5 } }几个关键参数的解释temperature设为 0.2是因为编码任务需要确定性太高的温度会让模型输出不稳定。estimate_ratio是 token 估算系数0.75 是我实测下来对代码内容比较准的值。warn_threshold设为 0.8意思是当上下文占用超过 80% 时终端会给出警告提醒我该清理上下文了。diff_threshold设为 0.5意思是变更超过文件内容的 50% 时触发人工确认。4.3 核心代码实现请求编排层请求编排层是 caveman 的心脏。它的主要职责是接收任务描述组装 prompt发送请求解析响应返回结果。下面是一个简化版的实现import os import json import httpx from pathlib import Path class CavemanOrchestrator: def __init__(self, config_path): with open(config_path) as f: self.config json.load(f) self.token_used 0 self.history [] def estimate_tokens(self, text): return int(len(text) * self.config[token][estimate_ratio]) def build_prompt(self, task, file_pathNone): parts [fTask: {task}] if file_path: content Path(file_path).read_text() parts.append(fFile: {file_path}\n\n{content}\n) if self.history: recent self.history[-3:] parts.append(Recent actions:\n \n.join(recent)) return \n\n.join(parts) def send_request(self, prompt): headers { Authorization: fBearer {os.environ[CAVEMAN_API_KEY]}, Content-Type: application/json } payload { model: self.config[model][model_name], messages: [{role: user, content: prompt}], max_tokens: self.config[model][max_tokens], temperature: self.config[model][temperature] } with httpx.Client(timeout60.0) as client: resp client.post( self.config[model][endpoint], headersheaders, jsonpayload ) resp.raise_for_status() return resp.json() def run(self, task, file_pathNone): prompt self.build_prompt(task, file_path) prompt_tokens self.estimate_tokens(prompt) if prompt_tokens self.config[token][context_limit] * self.config[token][warn_threshold]: print(Warning: context usage high, consider clearing history) result self.send_request(prompt) content result[choices][0][message][content] completion_tokens self.estimate_tokens(content) self.token_used prompt_tokens completion_tokens self.history.append(fTask: {task} - {completion_tokens} tokens) return content这段代码看起来简单但每一行都有它的道理。比如estimate_tokens用字符数乘以系数而不是引入 tokenizer就是为了减少依赖。build_prompt里只保留最近 3 次历史是为了控制上下文长度。send_request里用环境变量读 API key是为了避免密钥泄露。4.4 动作执行层的实现与安全检查动作执行层负责把模型返回的内容变成实际的文件变更。这里最关键的是安全检查import shutil from pathlib import Path from datetime import datetime class CavemanExecutor: def __init__(self, config): self.config config self.backup_dir Path(config[execution][backup_dir]) self.backup_dir.mkdir(exist_okTrue) def backup(self, file_path): src Path(file_path) if not src.exists(): return timestamp datetime.now().strftime(%Y%m%d_%H%M%S) dst self.backup_dir / f{src.name}.{timestamp}.bak shutil.copy2(src, dst) backups sorted(self.backup_dir.glob(f{src.name}.*.bak)) while len(backups) self.config[execution][max_backups]: backups.pop(0).unlink() def apply_change(self, file_path, new_content): src Path(file_path) old_content src.read_text() if src.exists() else if old_content: diff_ratio self.compute_diff_ratio(old_content, new_content) if diff_ratio self.config[execution][diff_threshold]: confirm input(fLarge change detected ({diff_ratio:.0%}). Proceed? [y/N] ) if confirm.lower() ! y: return False self.backup(file_path) src.write_text(new_content) return True def compute_diff_ratio(self, old, new): old_lines set(old.splitlines()) new_lines set(new.splitlines()) if not old_lines: return 1.0 changed len(old_lines.symmetric_difference(new_lines)) return changed / len(old_lines)这段代码里backup方法会在每次修改前备份原文件并自动清理旧备份。apply_change方法会计算新旧内容的差异比例超过阈值就要求人工确认。compute_diff_ratio用的是集合对称差虽然不是最精确的 diff 算法但胜在简单快速对于判断“改动是否过大”这个需求来说足够了。5. 常见问题与排查技巧实录5.1 token 相关问题的排查思路token 问题是 caveman 使用过程中最高频的问题没有之一。我把常见问题整理成了下面这张表问题现象可能原因排查方法解决方案token exchange failed认证信息过期或格式错误检查环境变量中的 token 是否为空重新获取 token 并更新环境变量failed to refresh token: 400refresh token 为空或格式不对打印 refresh token 的长度和前缀确保 refresh token 非空且格式正确unexpected status 401token 无效或权限不足用 curl 直接测试接口检查 token 权限范围token 消耗异常快上下文注入过多打印每次请求的 prompt token 数优化 prompt 组装策略token endpoint returned status 403请求被拒绝检查请求来源和认证方式确认认证信息正确排查 token 问题的核心思路是逐层验证。先确认 token 本身是否有效再确认请求是否正确携带了 token最后确认服务端是否接受了这个 token。不要一上来就怀疑最复杂的环节很多时候问题就出在最简单的地方比如环境变量没设置或者 token 字符串里多了个空格。5.2 代理链路故障的定位方法代理链路的问题通常表现为各种unexpected status错误。我的排查方法是二分法先把请求直接发到目标服务如果通了说明问题在中间链路如果不通说明问题在目标服务或认证。然后逐步加上中间环节每加一层测一次直到复现问题。具体操作上我会用curl做最小化测试curl -v -X POST https://api.example.com/v1/chat/completions \ -H Authorization: Bearer $CAVEMAN_API_KEY \ -H Content-Type: application/json \ -d {model:coding-model-v1,messages:[{role:user,content:test}]}-v参数会打印完整的请求和响应头对于定位问题非常有帮助。如果直接请求通了但通过 caveman 请求不通那就对比两者的请求头、请求体、超时设置差异点往往就是问题所在。提示排查代理问题时一定要把日志级别调到最详细。caveman 的编排层支持通过环境变量CAVEMAN_LOG_LEVELdebug开启详细日志会打印每一跳的请求和响应摘要。5.3 npx 与外部工具集成时的坑虽然 caveman 本身不依赖 Node.js但在集成某些外部工具时npx是绕不开的。我遇到过几次npx相关的问题总结下来主要有两类第一类是安装失败。典型表现是npx playwright install卡住或者报网络错误。解决办法前面提过清理缓存后重试。如果还是不行检查一下磁盘空间和权限有时候是临时目录满了或者没有写权限。第二类是版本不一致。npx默认会下载最新版本但最新版本可能和你的环境不兼容。解决办法是显式指定版本npx playwright1.40.0 install另外如果你在 CI 环境里用npx建议加上--yes参数避免交互式确认导致流程卡住。5.4 上下文窗口撑爆的预防与处理上下文窗口撑爆的表现是模型开始“胡言乱语”或者直接返回错误。预防措施前面讲过就是按需注入上下文。但如果已经撑爆了怎么处理我的做法是分段处理。把一个大任务拆成多个小任务每个小任务单独请求然后把结果拼起来。比如重构一个 500 行的文件不要一次性让模型改完而是按函数拆开一次改一个函数。这样每次请求的上下文都很小模型的表现也更稳定。另外caveman 的编排层支持手动清理历史记录。当上下文占用超过阈值时终端会提示这时候可以执行clear history命令把历史记录清空释放上下文空间。6. 实操心得那些文档里不会写的东西6.1 关于 token 估算的校准token 估算系数不是一成不变的。我一开始用 0.75后来发现对于纯英文内容这个系数偏高实际 token 数更接近字符数的 0.25 倍对于代码内容0.75 比较准对于中文内容系数要调到 1.5 左右。所以我的建议是根据你的主要使用场景校准这个系数。校准方法很简单找一段典型内容用真正的 tokenizer 算一次然后除以字符数得到的就是你的系数。6.2 关于模型温度的选择编码任务的温度我建议设在 0.1 到 0.3 之间。太低0会导致模型过于死板遇到需要一点创造力的任务比如起变量名表现不好太高0.7 以上会导致输出不稳定同样的输入两次结果差异很大。0.2 是我实测下来比较平衡的值。6.3 关于备份策略的调整默认保留 10 个备份对于大多数场景够用。但如果你在做大规模重构建议把max_backups调到 20 甚至 30。因为重构过程中可能会反复修改同一个文件备份不够的话想回退到某个中间状态就找不到了。另外备份目录建议放在项目目录之外避免被误提交到版本控制里。6.4 关于错误重试的边界重试不是万能的。我给自己定了一条规矩认证类错误不重试网络类错误才重试。因为认证错误重试多少次都不会成功只会浪费时间网络错误重试往往能解决临时性问题。caveman 的编排层里我根据 HTTP 状态码来判断是否重试401 和 403 直接失败500 和 503 才重试。7. 后续可以怎么扩展caveman 目前是一个很朴素的方案但它的架构留了很多扩展点。比如你可以在编排层里加一个多模型路由根据任务类型自动选择不同的模型简单的代码补全用便宜的小模型复杂的重构用贵的大模型。这样能在保证质量的前提下显著降低 token 成本。另一个扩展方向是本地缓存。对于重复性高的请求比如“解释这段代码”可以把结果缓存起来下次遇到相同请求直接返回缓存不消耗 token。缓存可以用文件系统实现简单可靠。还有一个方向是与版本控制集成。每次 caveman 修改文件后自动创建一个 git commitcommit message 由模型生成。这样既能保留完整的修改历史又能在出问题的时候快速回退。这些扩展我都在陆续尝试但核心原则不变每一层都要透明可控不引入不必要的依赖不把简单问题复杂化。caveman 的价值不在于它有多强大而在于它有多“笨”——笨到你完全能理解它在干什么笨到出问题的时候你能五分钟定位笨到你敢在关键项目上用它。