极简编码代理caveman：用CLI和按需上下文降低token消耗

1. 从“caveman”说起：一个极简编码代理的诞生逻辑

第一次看到“caveman”这个词，我脑子里蹦出来的画面是拿着石斧、围着兽皮、用最原始方式解决问题的远古人类。把这个词用在编码代理（coding agents）上，其实是一种非常精准的自嘲式命名——它想表达的核心意思是：别整那些花里胡哨的，用最原始、最直接的方式把代码任务干掉就行。

我接触过不少编码代理工具，从早期的命令行助手到后来各种带图形界面的智能编程平台，一个共同的痛点是：上下文越堆越多，token 消耗越来越夸张，最后代理还没开始干活，光是理解环境就烧掉了一大半预算。caveman 这个项目切入的角度恰恰相反，它把“原始”当成一种设计哲学——用最少的 token、最直接的 CLI 交互、最朴素的代理逻辑，完成代码生成、修改、调试这类核心任务。

这个项目适合谁？三类人最值得关注。第一类是经常在终端里干活的开发者，他们不想为了用个 AI 辅助就切换到笨重的 IDE 插件；第二类是对 token 成本敏感的个人开发者或小团队，每一分钱都要花在刀刃上；第三类是喜欢折腾 CLI 工具链的技术爱好者，他们享受把一堆小工具串起来解决大问题的过程。哪怕你只是刚听说“编码代理”这个词，只要你会用命令行，caveman 的思路都能给你启发。

需要先说明的是，caveman 本身是一个相对轻量的项目，网络上关于它的完整文档并不算多，很多细节需要结合编码代理这个领域的通用实践来补全。下面我会把它的设计思路、核心机制、实操流程、踩坑经验一层层拆开讲，尽量做到你看完就能自己动手复现一套类似的极简代理。

2. 编码代理的核心痛点与 caveman 的破局思路

2.1 为什么传统编码代理越用越“重”

要理解 caveman 的价值，得先搞清楚现在主流编码代理为什么让人又爱又恨。一个典型的编码代理工作流程是这样的：用户输入一个任务描述，代理把当前项目目录结构、相关文件内容、历史对话、系统提示词全部打包成一个巨大的上下文，发给大模型，模型返回操作指令，代理再执行、再读取结果、再打包……这个循环每转一圈，token 消耗就往上跳一截。

问题出在三个地方。第一是上下文膨胀，代理为了“保险起见”会把大量可能用不到的文件内容塞进提示词，导致每次请求都带着一堆冗余信息。第二是交互层级过多，很多代理在 CLI 之上又套了一层抽象，用户想改个参数得翻半天配置。第三是代理逻辑不透明，你不知道它到底读了哪些文件、为什么做这个决策，出了问题只能干瞪眼。

我实测过一个中等规模的 TypeScript 项目，用某主流编码代理跑一个“给所有 API 路由加上参数校验”的任务，光是上下文准备阶段就消耗了将近 4 万 token，而真正用于生成代码的 token 不到 8 千。这种比例放在长期使用中，成本会非常吓人。

2.2 caveman 的“原始主义”设计哲学

caveman 的破局思路可以用一句话概括：把代理的每一步都暴露在 CLI 里，让用户自己决定给模型看什么。它不追求全自动的“黑盒代理”，而是提供一个极简的代理循环框架，核心组件只有几个：一个任务解析器、一个文件读取器、一个模型调用封装、一个结果执行器。每个组件都可以通过命令行参数直接控制。

这种设计带来的直接好处是 token 可控。因为文件读取不是自动扫描整个项目，而是由用户通过参数指定要纳入上下文的文件或目录，代理只读你让它读的东西。我在自己的项目里试过，同样的任务，用 caveman 风格的显式上下文指定，token 消耗能压到自动扫描方案的三分之一甚至更低。

另一个好处是调试友好。因为每一步都是显式的 CLI 调用，你可以在任何环节插入自己的检查。比如代理生成了一个修改方案，你可以先让它输出 diff 而不直接执行，确认无误后再跑执行命令。这种“人在回路”的设计，在编码代理这个领域其实比全自动更实用，毕竟代码改错了回滚成本很高。

2.3 与主流方案的对比：什么时候该用 caveman

这张表不是要分出谁优谁劣，而是帮你判断场景。如果你在一个几十人的团队里做标准化开发，全自动代理的规范性可能更重要；但如果你是独立开发者，或者在一个快速试错的项目里，caveman 这种“原始”方式反而更灵活、更省钱。

3. 核心机制拆解：caveman 是怎么把任务跑起来的

3.1 任务解析：从自然语言到可执行指令

caveman 的第一步是把用户输入的自然语言任务转成结构化的操作意图。这一步看起来简单，实际上决定了整个代理的走向。我见过很多代理在这里翻车，原因是它们试图用一套复杂的意图分类模型，结果分类错了后面全错。

caveman 的做法更朴素：用提示词工程把任务约束到几个固定动作上，比如“读取文件”“修改文件”“创建文件”“运行命令”“搜索代码”。代理在调用模型时，系统提示词里会明确列出这些动作及其参数格式，模型返回的必须是符合格式的 JSON 或类似结构。这样做的好处是解析逻辑极简，不需要额外的分类器，出错也容易定位。

具体来说，一个典型的任务解析提示词会包含这样的约束：

你是一个编码代理，只能执行以下动作之一： - read_file: 参数 path - write_file: 参数 path, content - run_command: 参数 command - search: 参数 pattern, path 请以 JSON 格式返回你的下一步动作。

这种约束式提示词的效果，实测下来比让模型自由发挥要稳定得多。模型不需要“理解”整个任务，只需要决定下一步做什么，然后根据执行结果再决定下一步。这就是所谓的 ReAct 模式（推理加行动）的极简实现。

3.2 上下文管理：只给模型看它该看的

上下文管理是 caveman 最值得学习的地方。传统代理喜欢把整个项目目录树和所有相关文件一次性塞给模型，理由是“让模型有全局视野”。但实际使用中，模型并不需要全局视野，它只需要当前这一步所需的信息。

caveman 的策略是按需加载。代理在执行 read_file 动作后，才会把文件内容加入上下文；执行 search 动作后，只把匹配到的代码片段加入上下文。而且每次模型调用后，旧的中间结果可以选择性地丢弃，只保留关键状态。这样上下文始终维持在一个较小的规模。

我自己的经验是，对于一个 50 个文件左右的项目，如果任务只涉及其中 3 到 5 个文件，按需加载的上下文大小通常能控制在 8 千到 1.5 万 token 之间，而全量扫描方案往往要 3 万 token 起步。这个差距在长期使用中非常可观。

注意：按需加载的前提是代理能准确判断“需要哪些文件”。caveman 在这里依赖模型的 search 动作，让模型自己决定搜什么。如果模型判断失误，可能需要多轮搜索才能找到目标文件，这会增加交互轮次。实践中可以在提示词里加入项目结构摘要，帮助模型更快定位。

3.3 执行与反馈：让代理形成闭环

代理光有推理不够，还得能执行并看到结果。caveman 的执行层非常薄，基本上就是把模型返回的动作直接映射到系统调用或文件操作上。read_file 就是读文件，write_file 就是写文件，run_command 就是跑 shell 命令。执行结果再作为下一轮的输入反馈给模型。

这个闭环的关键在于反馈信息的精简。比如 run_command 执行后，如果命令输出很长，不能把全部输出都塞回上下文，而是要做截断或摘要。我通常的做法是只保留输出的前 50 行和后 20 行，中间用省略号代替，并在提示词里告诉模型“输出已被截断”。这样既保留了关键信息，又控制了 token。

另一个细节是错误处理。当命令执行失败时，错误信息要完整反馈给模型，因为错误信息往往包含解决问题的线索。但同样要注意长度控制，比如编译错误可能几百行，这时候可以只保留错误类型和第一个错误位置，让模型先解决主要矛盾。

3.4 工具选型：为什么是 CLI 而不是别的

caveman 选择 CLI 作为唯一交互界面，这个决策背后有实际考量。CLI 的优势在于可组合性。你可以用管道把 caveman 的输出接到其他工具上，可以用 shell 脚本批量调用，可以把它嵌入 CI 流程。图形界面虽然直观，但很难做到这种灵活性。

而且 CLI 天然适合“人在回路”的工作方式。你可以在终端里看到代理的每一步输出，随时按 Ctrl+C 中断，随时修改参数重跑。这种掌控感在调试复杂任务时非常重要。我用过一些图形界面的编码代理，出问题时只能看着它一直转圈，不知道卡在哪一步，体验很差。

当然 CLI 也有代价，就是学习成本。你需要记住一些命令和参数。但 caveman 的设计尽量让参数直观，比如--files指定文件、--task指定任务、--dry-run只输出不执行。用几次就能记住。

4. 实操全流程：从零搭一个 caveman 风格的编码代理

4.1 环境准备与依赖安装

先说环境。caveman 本身是一个概念和一套实践，你可以用任何语言实现它。我这里用 Python 来演示，因为 Python 在文本处理和 CLI 开发上最顺手。你需要准备的东西不多：Python 3.9 以上、一个能调用大模型的 API 客户端、基本的 shell 环境。

安装依赖很简单：

pip install openai click rich

这里用 click 来做 CLI 参数解析，用 rich 来做终端输出美化。如果你不想引入额外依赖，用标准库的 argparse 也完全可以，只是输出没那么好看。

关于模型选择，caveman 不绑定特定模型，任何支持对话补全的模型都能用。我实测下来，代码能力强的模型在任务解析和代码生成上表现更好，但即使是中等能力的模型，在约束式提示词下也能跑出可用的结果。关键是提示词要写清楚动作格式。

提示：如果你在安装某些 CLI 工具时遇到网络慢的问题，可以配置国内镜像源。比如 pip 可以用-i https://pypi.tuna.tsinghua.edu.cn/simple加速。这是通用技巧，和具体项目无关。

4.2 核心代码结构：四个文件搞定

caveman 风格代理的核心代码可以拆成四个部分，我习惯放在四个文件里，结构清晰也好维护。

第一个是agent.py，主循环。它负责接收任务、调用模型、解析动作、执行动作、反馈结果，直到模型返回“完成”或达到最大轮次。

import json from llm import call_model from actions import execute_action def run_agent(task, max_steps=20): context = [{"role": "system", "content": SYSTEM_PROMPT}] context.append({"role": "user", "content": task}) for step in range(max_steps): response = call_model(context) action = parse_action(response) if action["type"] == "done": print("任务完成:", action.get("summary", "")) return result = execute_action(action) context.append({"role": "assistant", "content": response}) context.append({"role": "user", "content": f"执行结果:\n{result}"}) print("达到最大轮次，任务可能未完成")

第二个是llm.py，封装模型调用。这里的关键是控制上下文长度，我加了一个简单的截断逻辑。

def call_model(context, max_tokens=4000): # 实际调用模型 API # 这里省略具体 SDK 调用，按你用的模型文档来 response = client.chat.completions.create( model="your-model", messages=context, max_tokens=max_tokens ) return response.choices[0].message.content

第三个是actions.py，动作执行器。每个动作对应一个函数，执行结果返回字符串。

import subprocess def execute_action(action): t = action["type"] if t == "read_file": with open(action["path"], "r") as f: return f.read()[:3000] elif t == "write_file": with open(action["path"], "w") as f: f.write(action["content"]) return f"已写入 {action['path']}" elif t == "run_command": r = subprocess.run(action["command"], shell=True, capture_output=True, text=True, timeout=30) return (r.stdout + r.stderr)[:2000] elif t == "search": r = subprocess.run(f"grep -rn '{action['pattern']}' {action['path']}", shell=True, capture_output=True, text=True) return r.stdout[:2000] return "未知动作"

第四个是prompts.py，存放系统提示词。这是整个代理的“大脑”，写得好不好直接决定效果。

SYSTEM_PROMPT = """你是一个编码代理，通过执行动作来完成任务。 可用动作： - read_file: {"type":"read_file","path":"文件路径"} - write_file: {"type":"write_file","path":"路径","content":"内容"} - run_command: {"type":"run_command","command":"命令"} - search: {"type":"search","pattern":"模式","path":"路径"} - done: {"type":"done","summary":"完成说明"} 每次只返回一个 JSON 动作，不要返回其他内容。 """

这四个文件加起来不到 100 行，但已经能跑通一个完整的编码代理循环。这就是 caveman 哲学的魅力：核心逻辑极简，复杂度留给具体任务。

4.3 参数计算：token 预算怎么分配

token 预算是 caveman 使用中必须算清楚的一笔账。我的经验是把总预算分成三块：系统提示词占 10%，上下文历史占 40%，模型输出占 50%。以 8000 token 的总预算为例，系统提示词控制在 800 token 以内，上下文历史控制在 3200 token 以内，留给模型输出的空间是 4000 token。

上下文历史的 3200 token 怎么分配？文件内容占大头，大概 2000 token；命令执行结果占 800 token；对话历史占 400 token。这个分配不是固定的，如果任务涉及大文件，可以临时调高文件内容的占比，相应压缩其他部分。

实际操作中，我会在代码里加一个 token 估算函数，用简单的字符数除以 4 来粗略估算（英文），中文按字符数除以 1.5 估算。虽然不精确，但足够用来做截断决策。

def estimate_tokens(text): # 粗略估算，中文按 1.5 字符/token，英文按 4 字符/token chinese = sum(1 for c in text if '\u4e00' <= c <= '\u9fff') other = len(text) - chinese return int(chinese / 1.5 + other / 4)

这个估算函数在截断文件内容和命令输出时非常有用。我通常设定一个阈值，比如单次反馈不超过 2000 token，超过就截断并加提示。

4.4 一次完整任务实录：给项目加日志

光看代码不够直观，我拿一个真实任务走一遍。任务描述是：“给 src/utils.py 里的所有函数加上日志记录，使用 logging 模块。”

第一轮，模型返回 search 动作，搜索def在 src/utils.py 中的位置。执行后返回匹配行号和函数名。

第二轮，模型根据搜索结果返回 read_file 动作，读取 src/utils.py 的完整内容。执行后文件内容进入上下文。

第三轮，模型返回 write_file 动作，输出修改后的完整文件内容。这里有个细节，模型可能会输出整个文件，也可能只输出 diff。我倾向于让它输出完整文件，因为 diff 解析容易出错，而完整文件写入更可靠。代价是 token 消耗大一些，但胜在稳定。

第四轮，模型返回 run_command 动作，运行python -c "import src.utils"验证语法。执行成功，返回无错误。

第五轮，模型返回 done 动作，任务完成。

整个过程五轮，token 消耗大概在 6000 左右。如果用全自动代理，光是读取整个项目结构可能就要这个数。这就是显式上下文控制的价值。

注意：让模型输出完整文件时，要确保文件不太大。如果文件超过 500 行，建议让模型分段修改，或者只输出需要修改的函数。否则模型输出可能被 max_tokens 截断，导致文件不完整。

5. 常见问题与排查技巧实录

5.1 模型不按格式返回怎么办

这是最常见的问题。你要求模型返回 JSON，它偏偏返回一段解释文字。原因通常是提示词约束不够强，或者模型本身对格式遵循能力弱。

解决办法有三个层次。第一层是强化提示词，在系统提示词里反复强调“只返回 JSON，不要任何其他文字”，并且给出正例和反例。第二层是加解析容错，用正则从返回文本里提取 JSON 部分，忽略前后多余文字。第三层是换模型，如果某个模型怎么调都不听话，那就换一个格式遵循能力强的。

我自己的做法是前两层一起上。提示词里写清楚，解析时用正则兜底。这样即使模型偶尔跑偏，代理也不会直接崩溃。

import re def parse_action(response): # 尝试直接解析 try: return json.loads(response) except json.JSONDecodeError: pass # 正则提取 JSON match = re.search(r'\{.*\}', response, re.DOTALL) if match: try: return json.loads(match.group()) except json.JSONDecodeError: pass return {"type": "done", "summary": "解析失败"}

5.2 代理陷入死循环怎么破

死循环的表现是代理反复执行同一个动作，比如一直读同一个文件，或者一直运行同一个失败的命令。原因通常是模型没有从执行结果中获得有效反馈，或者任务本身无法完成但模型不肯放弃。

排查思路是看上下文里有没有重复的模式。我通常会在主循环里加一个检测：如果连续三轮的动作类型和参数完全相同，就强制中断并提示用户。

def is_repeating(history, window=3): if len(history) < window: return False recent = history[-window:] return all(h == recent[0] for h in recent)

另一个办法是在提示词里加入“如果连续两次执行结果相同，请尝试不同策略或返回 done”。这能引导模型主动跳出循环。

5.3 命令执行超时或卡住

run_command 动作如果执行了一个交互式命令，或者一个耗时很长的命令，代理就会卡住。解决办法是给 subprocess 加 timeout 参数，超时后返回错误信息给模型。

try: r = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=30) except subprocess.TimeoutExpired: return "命令执行超时（30秒），请检查命令是否需要交互输入"

同时，在提示词里明确告诉模型“不要执行需要交互输入的命令，不要执行耗时超过 30 秒的命令”。这能减少很多麻烦。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是文件路径问题。模型返回的路径可能是相对路径，也可能是绝对路径，还可能是带引号的路径。执行前最好统一处理一下，去掉引号、转成绝对路径，避免因为路径问题导致读写失败。

第二个坑是编码问题。有些文件是 GBK 编码，用 UTF-8 读会报错。我现在的做法是读文件时先尝试 UTF-8，失败再尝试 GBK，还失败就用 errors='ignore' 兜底。

第三个坑是模型过度自信。有时候模型会直接返回 write_file 动作，但内容是基于它“想象”的文件内容，而不是实际读取的。解决办法是在提示词里强制要求“修改文件前必须先 read_file”。这个约束能避免很多低级错误。

第四个坑是上下文污染。如果某一轮的执行结果包含大量无关信息，会影响后续模型的判断。我现在的做法是每轮反馈前先做一次精简，只保留和任务相关的部分。比如命令输出只保留错误行和关键行。

6. 进阶玩法：把 caveman 接入你的工作流

6.1 与版本控制配合：改前先提交

编码代理最大的风险是改坏代码。我的习惯是在让代理执行任何写操作之前，先确保当前工作区是干净的，或者至少把当前状态提交到版本控制。这样即使代理改错了，也能一键回滚。

具体做法是在代理启动时加一个检查：如果 git status 有未提交的修改，提示用户先提交或 stash。这个检查可以用 shell 命令实现，几行代码的事。

if [ -n "$(git status --porcelain)" ]; then echo "工作区有未提交修改，请先提交或 stash" exit 1 fi

这个习惯救过我很多次。有一次代理把一个核心配置文件改得面目全非，因为提前提交了，直接git checkout .就恢复了。

6.2 批量任务：用脚本串起来

caveman 的 CLI 特性让它非常适合批量任务。比如你有一堆文件都要加同样的注释头，可以写一个 shell 脚本循环调用代理。

for f in src/*.py; do python agent.py --task "给 $f 加上文件头注释，包含作者和日期" --files "$f" done

这种批量处理在重构场景下特别有用。但要注意，批量任务要加失败重试和日志记录，否则一个文件失败可能影响后续。

6.3 自定义动作扩展

caveman 的动作集不是固定的，你可以根据自己的需求扩展。比如加一个run_tests动作，专门跑测试套件；加一个format_code动作，调用格式化工具。扩展的方式就是在 actions.py 里加分支，在系统提示词里加说明。

我加过一个git_diff动作，让代理在修改后自己看 diff，确认修改符合预期。这个动作在复杂重构中很有用，相当于给代理加了一层自我检查。

6.4 成本监控：别让账单吓到你

用 API 调用模型是要花钱的，caveman 虽然省 token，但架不住任务多。我建议加一个简单的成本统计，每次调用后累加 token 数，任务结束时输出总消耗。

total_tokens = 0 def call_model(context): global total_tokens response = client.chat.completions.create(...) total_tokens += response.usage.total_tokens return response.choices[0].message.content

有了这个统计，你就能清楚知道每个任务花了多少钱，哪些任务值得用代理，哪些任务自己动手更快。

7. 我对 caveman 这类极简代理的真实看法

用了几个月 caveman 风格的代理之后，我最大的体会是：编码代理的价值不在于“全自动”，而在于“可控的半自动”。那些试图完全替代人做决策的代理，往往在复杂任务上翻车，因为代码修改的上下文太丰富，模型很难一次性考虑周全。而 caveman 这种把控制权交还给用户的模式，反而在实际工作中更可靠。

另一个体会是提示词的质量决定一切。同样的代理框架，提示词写得好和写得差，效果能差出好几倍。我现在的习惯是每遇到一个新任务类型，先花十分钟打磨提示词，把动作格式、约束条件、常见错误都写清楚。这十分钟的投入，能省下后面大量的调试时间。

还有一点是关于 token 的。很多人觉得 token 便宜，不在乎消耗。但当你每天跑几十个任务时，token 成本会累积成一笔不小的开支。caveman 的按需加载思路，本质上是一种工程上的克制——只给模型它真正需要的信息。这个原则不仅适用于编码代理，也适用于任何和模型交互的场景。

最后分享一个小技巧：如果你觉得从零写代理太麻烦，可以先用现成的 CLI 工具加上自己的提示词模板，快速验证想法。等验证通过了，再考虑要不要自己实现一套。工具是为人服务的，别为了造轮子而造轮子。