1. 为什么我要自己造一个 AI IDE市面上的 AI 编程工具我几乎用了个遍。从最早的代码补全插件到后来的对话式编程助手再到最近一年冒出来的各种 Agent 形态的编辑器我算是深度体验了这条赛道的完整演化。但用得越多心里越不踏实——我根本不知道模型到底看到了什么。这个问题听起来好像不重要但你仔细想想当你让 AI 帮你改一个函数它到底是只看了这个函数还是把整个文件都塞进去了当你让它修一个 bug它是真的理解了上下文还是只是碰巧猜对了当你的 token 用量突然飙升你能说清楚是哪个环节吃掉了预算吗绝大多数 AI IDE 给你的答案是你不需要知道。它们把 prompt 组装、上下文裁剪、工具调用、结果回填这一整套流程全部封装在一个黑盒里你只能看到最终的输出。这就像你雇了一个助理帮你处理邮件但你不知道他到底读了哪些邮件、删了哪些、又偷偷转发了哪些——结果对了还好结果错了你连排查的方向都没有。所以我决定自己造一个。核心目标只有一个把发给模型的每一个 token 都摆在你面前。不是给你一个模糊的上下文长度数字而是让你能逐条看到哪些内容被选中了、以什么顺序拼接、占了多少 token、为什么被保留或被丢弃。这个项目我断断续续做了几个月踩了不少坑也积累了一些在常规文档里看不到的经验今天完整地分享出来。这篇文章适合几类人看一是正在用 AI 编程工具但总觉得心里没底的开发者二是想自己动手做 Agent 或 AI IDE 的工程师三是对 token 管理和上下文工程感兴趣的技术人。哪怕你暂时不打算自己造轮子理解这套机制也能让你在用现有工具时更有判断力。2. 整体架构设计与核心思路拆解2.1 为什么透明比聪明更重要在动手之前我先想清楚了一个问题AI IDE 的核心竞争力到底是什么很多人第一反应是模型能力但模型是别人的你调 GPT 也好、调 Claude 也好、接开源模型也好能力上限是固定的。真正能拉开差距的是你怎么组织上下文、怎么管理 token、怎么让模型在有限的窗口里看到最有用的信息。这就引出了我的第一个设计原则可观测性优先于自动化。市面上很多工具追求一键搞定用户输入一句话它自动规划、自动执行、自动修复。听起来很爽但一旦出错你完全不知道是哪一步的问题。我反其道而行之把每一个中间步骤都暴露出来哪怕这样会让界面看起来更复杂。具体来说我把整个流程拆成了四个可观测的环节上下文采集从当前工作区收集哪些文件、哪些片段Token 预算分配给系统提示、对话历史、代码上下文、工具结果各分配多少额度Prompt 组装最终发给模型的完整消息序列长什么样响应解析与回填模型返回的内容如何被解析成具体的操作每个环节都有独立的可视化面板你可以随时暂停、检查、修改。这种设计在初期确实增加了使用成本但用久了你会发现你对模型行为的直觉会变得非常准因为你见过足够多的真实案例。2.2 技术选型为什么不用现成的框架一开始我也想过直接用 LangChain 或者类似的 Agent 框架。试了两周之后放弃了原因有三个。第一框架的抽象层太厚。LangChain 把 prompt 模板、memory、tool 都封装成了对象你想看最终发给模型的原始字符串得扒好几层。而我的核心需求恰恰就是看这个原始字符串用框架等于给自己添堵。第二token 计数的精度不够。不同模型的 tokenizer 不一样框架通常只提供一个估算值。我要的是精确到每个片段的计数这样才能做精细的预算分配。自己接 tokenizer 反而更直接。第三调试体验差。Agent 框架的调用链很深出问题的时候堆栈信息很难读。我自己写的代码每一层都是透明的断点打在哪里都清楚。最终的技术栈是这样的前端用 React TypeScript后端用 Node.js模型调用直接走各家官方 SDKtokenizer 用 tiktoken 和各家自己的库。整个项目没有引入任何重型框架核心逻辑加起来大概几千行但每一行我都能说清楚它在干什么。2.3 数据流设计一次请求的完整生命周期理解这个项目最好的方式是跟着一次完整的请求走一遍。假设你在编辑器里选中一段代码输入帮我优化这个函数然后回车。接下来发生的事情是这样的第一步上下文采集器被触发。它会扫描当前打开的文件、最近编辑过的文件、以及项目里被引用的相关文件。注意这里有个关键决策不是把所有文件都塞进去而是根据相关性打分。打分逻辑包括文件是否被 import、是否在最近编辑历史里、是否与当前选中的代码有符号关联等。第二步Token 预算分配器介入。它拿到采集到的候选内容按照预设的优先级分配 token 额度。比如系统提示固定占 500 token对话历史最多占 2000 token代码上下文最多占 8000 token剩下的留给模型输出。如果候选内容超出预算就按打分从低到高裁剪。第三步Prompt 组装器把选中的内容按特定顺序拼接成最终的消息序列。这个顺序很讲究后面会详细讲。第四步模型调用发出请求拿到响应。第五步响应解析器把模型返回的文本解析成结构化的操作比如替换第 10 到 20 行或者在文件末尾追加代码。第六步回填与展示把操作应用到编辑器同时把整个流程的所有中间数据记录到可视化面板。这六步里每一步的数据都被完整保留你可以随时回看。这就是把每一个 token 摆在你面前的具体含义。3. 核心细节解析与实操要点3.1 Token 计数别信估算要精确这是整个项目里最基础也最容易踩坑的部分。很多人以为 token 计数就是字数除以四这个经验法则在英文里勉强能用在中文里完全失效。中文一个汉字通常对应 1 到 2 个 token具体取决于 tokenizer。我一开始用的是一个第三方的估算库结果发现同样的文本估算值和实际值能差 30% 以上。这在预算紧张的时候是致命的——你以为还剩 2000 token实际已经超了。后来我改成了直接用官方 tokenizer。OpenAI 系用 tiktokenAnthropic 系用他们自己的计数接口开源模型用 HuggingFace 的 tokenizer。虽然这样会增加一些依赖但精度是值得的。这里有个实操技巧tokenizer 的加载是有开销的不要每次请求都重新加载。我的做法是在服务启动时就把常用的 tokenizer 加载到内存里做成单例。实测下来这样能把单次计数的耗时从几十毫秒降到几毫秒。还有一个细节不同模型的特殊 token 要单独处理。比如对话格式里的|im_start|、|im_end|这类标记它们本身也占 token而且往往容易被忽略。我在组装 prompt 的时候会把这些特殊 token 单独列出来计数确保预算准确。3.2 上下文裁剪怎么决定丢什么这是最能体现透明价值的地方。上下文裁剪本质上是一个取舍问题窗口就这么大什么该留什么该丢我的策略是分层打分 硬性保底。分层的意思是把候选内容分成几个优先级优先级内容类型是否可裁剪典型 token 占比P0系统提示、当前用户指令不可裁剪5% - 10%P1当前选中的代码片段不可裁剪10% - 20%P2当前文件的完整内容可部分裁剪20% - 30%P3直接依赖的文件可裁剪15% - 25%P4对话历史可裁剪10% - 20%P5间接相关文件优先裁剪0% - 10%硬性保底的意思是P0 和 P1 永远不裁剪哪怕超预算也要保留。因为这两部分是任务的直接依据丢了它们模型就完全跑偏了。裁剪 P2 到 P5 的时候我用的是滑动窗口 语义边界的组合策略。滑动窗口好理解就是保留离当前编辑位置最近的内容。但纯滑动窗口有个问题它可能把一个函数从中间切断留下半截代码反而干扰模型。所以我在滑动窗口的基础上加了语义边界检测尽量在函数、类、代码块的边界处切割。提示语义边界检测不需要做到完美用简单的括号匹配和缩进分析就能覆盖 80% 的情况。追求 100% 准确会引入大量复杂度性价比不高。3.3 Prompt 组装顺序位置决定注意力这个细节很多人不注意但对结果影响很大。模型对 prompt 里不同位置的内容注意力权重是不一样的。通常来说开头和结尾的内容权重最高中间的内容容易被忽略。这就是所谓的迷失在中间现象。基于这个特性我的组装顺序是这样的系统提示放在最开头明确角色和规则当前用户指令紧跟在系统提示后面确保被充分关注代码上下文放在中间按相关性从低到高排列最相关的靠近结尾对话历史放在代码上下文之前最后再重复一次当前指令作为结尾强调这个顺序是经过大量实测调出来的。同样的内容换个顺序模型的表现能差出一大截。我建议你在自己的项目里也做类似的 A/B 测试别照搬别人的顺序因为不同模型的注意力分布不一样。3.4 工具调用的透明化Agent 形态的 AI IDE 离不开工具调用读文件、写文件、执行命令、搜索代码。这些工具调用的参数和返回值同样占 token同样需要透明化。我的做法是给每个工具调用建立一个完整的记录调用了什么工具、传了什么参数、返回了什么结果、消耗了多少 token。这些记录会显示在时间线上你可以清楚地看到模型在第几轮决定调用什么工具以及这个决定是基于什么信息做出的。这里有个容易忽略的点工具返回的结果往往很长需要二次裁剪。比如你让模型读一个 500 行的文件返回的内容可能就吃掉了大半预算。我的处理方式是工具返回结果先经过一个摘要器提取关键信息再决定是否把完整内容塞进上下文。摘要器可以用规则实现也可以用小模型实现看你的精度要求。4. 实操过程与核心环节实现4.1 环境搭建与依赖安装先说环境。我用的是 Node.js 20 以上的版本因为要用到一些新的 API。前端构建用 Vite比 Webpack 快很多。整个项目没有用 monorepo就是简单的前后端分离前端在client目录后端在server目录。核心依赖清单如下# 后端核心依赖 npm install express ws tiktoken anthropic-ai/sdk openai npm install huggingface/tokenizers # 开源模型 tokenizer # 前端核心依赖 npm install react react-dom zustand npm install monaco-editor/react # 代码编辑器 npm install recharts # 可视化图表这里解释几个关键选择。用ws而不是 socket.io是因为我只需要原生的 WebSocket不需要 socket.io 那些额外的功能少一层抽象少一层坑。用zustand而不是 Redux是因为状态管理没那么复杂zustand 更轻量。用 Monaco 是因为它本来就是 VS Code 的编辑器内核对代码高亮和 diff 的支持最好。4.2 Token 计数模块的实现这是最核心的模块我单独抽出来讲。先看代码结构// server/tokenizer/index.ts import { encoding_for_model, TiktokenModel } from tiktoken; class TokenizerManager { private encoders: Mapstring, any new Map(); getEncoder(model: string) { if (this.encoders.has(model)) { return this.encoders.get(model); } // 根据模型名映射到对应的 tokenizer const encoder this.createEncoder(model); this.encoders.set(model, encoder); return encoder; } count(text: string, model: string): number { const encoder this.getEncoder(model); return encoder.encode(text).length; } // 批量计数用于统计多个片段 countBatch(segments: string[], model: string): number[] { const encoder this.getEncoder(model); return segments.map(s encoder.encode(s).length); } } export const tokenizerManager new TokenizerManager();关键点在于缓存 encoder。tiktoken 的 encoder 初始化比较慢如果每次计数都重新创建性能会很差。用 Map 缓存之后同一个模型的计数就是纯计算非常快。对于 Anthropic 的模型情况稍微特殊一点他们没有提供本地的 tokenizer只能调他们的计数接口。我的做法是加一层缓存把已经计过数的文本的 hash 和结果存起来避免重复请求。4.3 上下文采集器的实现上下文采集器的核心是相关性打分。我实现了一个简单的打分函数输入是一个文件路径输出是一个 0 到 1 的分数function scoreFile(filePath: string, context: Context): number { let score 0; // 是否被当前文件 import if (context.imports.includes(filePath)) { score 0.4; } // 是否在最近编辑历史里 const recencyIndex context.recentFiles.indexOf(filePath); if (recencyIndex 0) { score 0.3 * (1 - recencyIndex / context.recentFiles.length); } // 是否与选中代码有符号关联 if (hasSymbolOverlap(filePath, context.selectedCode)) { score 0.2; } // 文件大小惩罚太大的文件降低优先级 const size getFileSize(filePath); if (size 50000) { score - 0.1; } return Math.max(0, Math.min(1, score)); }这个打分函数看起来很粗糙但实测效果不错。关键是各个权重的比例我是通过观察大量真实案例调出来的。你可以根据自己的使用习惯调整比如你经常跨文件重构那 import 的权重可以调高一点。采集器还有一个重要的功能是片段提取。对于大文件不是整个塞进去而是提取相关片段。我用的是基于符号的分析先解析出文件里的函数、类、变量定义然后根据当前任务匹配最相关的几个。4.4 Prompt 组装与可视化组装器把前面采集和裁剪好的内容按预定顺序拼成最终的消息序列。这里我用了一个中间数据结构来描述interface PromptSegment { id: string; type: system | user | assistant | code | tool_result; content: string; tokenCount: number; priority: number; source?: string; // 来源文件路径 reason: string; // 为什么被选中 }注意reason字段这是透明化的关键。每个片段都要记录它为什么被选中这样在可视化面板里用户可以点开任何一个片段看到它的来源和入选理由。可视化面板我用的是分栏布局左边是 token 预算的饼图显示各类内容的占比中间是消息序列的列表每个片段可以展开看详情右边是最终的原始 prompt 文本可以复制出来自己验证。这个面板看起来简单但实现起来有不少细节。比如 token 预算的实时更新我用的是 WebSocket 推送每次组装完成就推一次数据。再比如原始 prompt 的展示要注意转义和换行不然看起来会很乱。4.5 响应解析与操作回填模型返回的内容通常是自然语言加代码块需要解析成具体的编辑操作。我用的是一个基于规则的解析器识别几种常见的模式完整的代码块替换选中的内容带文件路径的代码块写入指定文件diff 格式的内容应用补丁纯文本说明只展示不修改解析器用正则加状态机实现不复杂但需要处理各种边界情况。比如模型有时候会用不同的代码块标记有时候会在代码块前后加说明文字这些都要兼容。回填的时候我会把操作先展示给用户确认而不是直接应用。这是刻意的设计——AI 可以建议但最终决定权在人。用户确认后操作才会真正写入文件同时记录到操作历史里方便回滚。5. 常见问题与排查技巧实录5.1 Token 用量异常飙升怎么排查这是最常见的问题。明明只是改一个小函数token 用量却比预期高好几倍。我的排查思路是这样的首先看可视化面板里的 token 预算饼图确认是哪一类内容占比异常。如果是代码上下文占比过高说明采集器选进了太多不相关的文件需要调整相关性打分的阈值。如果是对话历史占比过高说明历史没有及时裁剪需要检查裁剪逻辑。其次看单个片段的 token 数找出大户。有时候一个看起来不大的文件因为包含大量注释或者长字符串token 数会超出预期。这种情况可以考虑对注释和字符串做特殊处理。最后检查特殊 token 的计数。前面提到过对话格式的标记容易被忽略如果这部分没算进去实际用量会比显示的高。5.2 模型忘记了前面的指令怎么办这是上下文管理的经典问题。模型在长对话里容易忽略早期的指令尤其是当中间塞了大量代码之后。我的解决方案是指令重述。在 prompt 的结尾把当前的核心指令再重复一遍。这个技巧看起来简单但效果非常明显。实测下来加了指令重述之后模型跑偏的概率能降低一半以上。另一个技巧是关键约束前置。如果有一些硬性约束比如不要修改函数签名、保持代码风格一致把这些放在系统提示的最前面而不是混在用户指令里。5.3 工具调用陷入死循环Agent 形态的工具很容易陷入死循环模型调用工具结果不理想再调用再不理想来回几次就把预算耗光了。我的处理方式是加调用次数上限和重复检测。每个工具在单次任务里的调用次数有上限超过就强制停止。同时检测重复调用如果连续两次调用的参数高度相似就中断并提示用户。还有一个技巧是给工具结果加摘要。有时候模型反复调用同一个工具是因为它没看懂上一次的结果。如果结果太长模型可能只看到了开头。加一个简短的摘要放在结果最前面能有效减少重复调用。5.4 常见问题速查表问题现象可能原因排查方向解决技巧Token 用量异常上下文采集过多查看预算饼图调高相关性阈值模型忽略指令指令位置太靠前检查 prompt 顺序结尾重述指令工具死循环结果未被理解查看工具调用记录加摘要和次数上限响应解析失败格式不符合预期查看原始响应放宽解析规则计数与实际不符特殊 token 未计对比官方计数单独处理特殊 token上下文被截断预算分配不合理检查优先级设置调整 P0/P1 保底5.5 几个踩过的坑第一个坑是过度依赖估算。前面提过我一开始用估算库结果预算经常算错。后来改成精确计数虽然慢一点但省心很多。第二个坑是忽略了 tokenizer 的版本差异。同一个模型的不同版本tokenizer 可能不一样。我有一次升级了模型版本没更新 tokenizer导致计数全错。现在的做法是把 tokenizer 版本和模型版本绑定一起管理。第三个坑是可视化面板的性能。一开始我把所有中间数据都实时推送到前端结果数据量大的时候页面会卡。后来改成了按需加载只推送摘要详情在用户点击时才拉取。第四个坑是没有考虑多模型切换。项目初期只支持一个模型后来要支持多个发现很多地方写死了模型名。重构的时候把模型相关的逻辑都抽成了配置现在切换模型只需要改配置。6. 这套方案还能怎么扩展做这个项目的过程中我越来越觉得透明化这个思路可以走得更远。目前实现的是 token 级别的透明未来可以往几个方向扩展。一个是决策级别的透明。现在你能看到模型看到了什么但看不到它为什么这么决策。如果能记录模型的推理过程或者用可解释性工具分析注意力分布就能更进一步。另一个是跨会话的 token 分析。现在只能看单次请求的 token 分布如果能统计一段时间内的使用模式就能发现一些系统性的问题比如某类任务总是消耗过多 token然后针对性优化。还有一个是团队协作场景。如果多人共用一套 AI IDEtoken 的透明化就更有价值了可以清楚地看到每个人的使用情况做成本分摊和优化。我个人在实际操作中的体会是透明化带来的最大价值不是省钱而是建立信任。当你清楚地知道模型在做什么你就敢把更重要的任务交给它。这种信任是任何一键搞定的工具都给不了的。最后再分享一个小技巧如果你暂时不想自己造轮子至少在用现有工具的时候养成看 token 用量的习惯时间长了你会对模型的胃口有很准的判断。