SmallCode架构全解你按下回车之后在模型生成第一个Token前发生的8件事【免费下载链接】smallcodeAI coding agent optimized for small LLMs. 87% benchmark with 4B-active model.项目地址: https://gitcode.com/gh_mirrors/sm/smallcodeSmallCode 是一款专为 7B–20B 小型 LLM 优化的AI 编程代理AI coding agent它在消费级硬件上完全本地运行。很多人以为输入 → 模型输出之间只有网络请求但实际上 SmallCode 在你按下回车的瞬间会先完成一整套零成本的前置流水线——消息澄清检测、文件展开、Git 上下文注入、确定性工具路由、计划锚点重注入……这些步骤不调用一次大模型却决定了小模型能否稳定干活。本文带你逐条拆解这8 件事全部对应真实源码路径方便你跟着代码理解。先搞懂为什么小模型需要这些前处理SmallCode 的核心假设与 Cursor 等工具正好相反你的模型上下文可能只有 8–32k、工具调用 JSON 时有时无、三步之后就会忘记自己在干什么。于是架构上每一处看起来多余的前置步骤都是在用小模型付不起的成本正则、文件扫描替代它付不起的能力长上下文记忆。核心设计文档可参考 ARCHITECTURE.md中文说明见 README_zh-CN.md。前置流水线总览8 件事一张表看懂顺序步骤成本关键源码1模糊消息检测纯正则0 tokenclarify.js2图片文件扫描本地 IOimages.js3文件引用展开本地 IOreferences.js4Git 变更上下文注入git diffgit_context.js5项目自举探测首轮本地扫描bootstrap.js6确定性工具路由加权正则评分two_stage_router.js7计划锚点重注入内存读取plan_tracker.js8上下文压缩 消息规范化本地计算message_normalizer.js 注意以上 8 步全部在本地完成没有一步需要请求模型。这就是小模型专用代理与通用代理的本质区别。第 1 件事正则分类器检查你的话是不是太模糊如果你只打了 fix it 这种没有上下文的话模型大概率会瞎猜。SmallCode 的做法很聪明不用 LLM 判断模糊性用一个成本为零的正则分类器。匹配到 fix it / do this / make it better 这类模式后系统会向模型注入一条指令先说出你的理解问一个澄清问题然后立刻基于最佳理解动手——不许干等确认。// 触发澄清的典型模糊模式 /^(fix|do|make|change|update|improve)\s(it|this|that|things?)$/i /^(help|please|can you|could you)$/i实现位置clarify.js细节回复模型问题的 yes / ok / go ahead 被明确排除在外不会误触发澄清。第 2 件事扫描你顺手丢进对话的图片如果你在输入时附带了图片文件比如报错截图系统会先扫描消息中引用到的图片文件确认其存在、可读、体积合规再决定是否随请求发给模型。这一步是纯本地 IO避免把不存在的图片路径丢给模型后白白浪费一轮调用。实现位置images.js多模态内容在后续消息规范化时会被原样保留见第 8 步。第 3 件事把 文件 引用展开成真实内容你在输入框里敲src/main.ts模型并不能凭空读到它。SmallCode 会解析消息中所有path引用把文件内容直接注入对话单文件读取内容超 500 行截断并标注目录列出前 50 个条目安全防护拒绝.ssh、.aws等敏感路径内容注入前会脱敏抹掉 API Key、Token单文件上限 4000 字符、总量约 2000 token 封顶。src/main.ts → 注入该文件内容 src/ → 注入目录列表实现位置references.js这一步等价于替模型省掉了 2–3 次 read_file 工具调用。第 4 件事自动注入最近的 Git 变更当你说 fix the failing test、what changed 这类话时系统会先跑一遍git diff --stat和git log把未暂存变更封顶 100 行、已暂存变更和最后一次 commit 信息自动塞进上下文。--- Recent git changes --- Unstaged changes: src/auth.js | 12 ------ 1 file changed Last commit: a1b2c3d fix login timeout触发词匹配git_context.js小模型最擅长修眼前刚改坏的东西这一步让它不用自己git status。第 5 件事首轮专属项目自举探测一句话告诉模型这是什么项目首次对话时SmallCode 会扫描工作区的package.json/pyproject.toml/Cargo.toml/go.mod等配置生成一行项目摘要直接注入系统提示词例如Project: Node 20 (npm) — Next.js app. Build: npm run build. Test: npm test. Entry: src/app.js没有这一步小模型要浪费 3–5 次工具调用才能搞清楚这是个 Node 项目、测试命令是 npm test。支持 Node、Python、Rust、Go、.NET、Java、Ruby 七大技术栈识别结果带缓存、可被SMALLCODE_BOOTSTRAPfalse关闭。实现位置bootstrap.js第 6 件事确定性工具路由——8 个类别里投票选出该带哪些工具这是 SmallCode 最核心的省 token 设计。每次调用前先用加权正则对消息打分在 read / write / search / run / plan / code-intelligence / web / respond 八个类别之间做置信度投票胜出类别决定哪些工具 schema 进入提示词判为respond纯聊天→注入 0 个工具省约 800 token判为write→ 只带 write 相关工具Explain 这类词会压低 write 分How does X work 触发代码智能类路由。平局时按优先级打破write run code-intelligence search plan read web respond——模糊的行动性消息默认偏向动手。对于 16k 以下上下文的模型还会切换为两阶段路由第一次调用只让模型选类别约 200 token第二次才注入该类完整工具 schema用一次额外往返换大幅 token 节省类别定义与模式切换two_stage_router.js完整路由评分设计说明ARCHITECTURE.md还有一个精妙的边界处理任务中途你回复 ok 时专门的肯定词守卫会保留上一次的类别避免写文件工具被误剥离。第 7 件事把计划锚点重新钉回模型眼前小模型最大的毛病是到第 4 步忘了第 3 步。SmallCode 对多步任务长消息、refactor/migrate 关键词、多个祈使句会要求模型先输出编号计划再调工具并把它作为锚点在后续每一轮重新注入ACTIVE PLAN (step 3 of 5): ✓ 1. Read the existing auth module ✓ 2. Identify the JWT validation function → 3. Add the refresh token handler 4. Update the route middleware 5. Run tests模型永远知道自己在哪一步。这是多文件任务可靠性的最大单一提升。启发式判断与锚点格式plan_tracker.js配套机制计划步骤还会做纯代码依赖分析同一文件的多步自动建立依赖为并行执行打基础。第 8 件事上下文预算压缩 系统消息规范化最后一道安检真正发出请求前还要过两道安检① 消息规范化Qwen3 等严格聊天模板要求 system 消息必须出现在数组第 0 位否则直接返回 HTTP 400。SmallCode 会在对话中途注入澄清指令、计划锚点、路径警告等多种 system 消息发送前统一把它们合并为一条居首的 system 消息顺序保留、内容不丢实现位置message_normalizer.js② 上下文预算管理实时估算 token 用量约 4 字符 ≈ 1 token大文件摘要为签名、旧消息按压力驱逐保证任何一轮都不超出模型上下文窗口Token 估算与成本追踪tokens.js✅ 到这里一个为这个小模型量身裁剪的请求才终于发出——上下文更短、工具更少、目标更明确这才是87% benchmark with 4B-active model 的真正来源。如何验证这些机制亲手试一遍想亲眼看到这套流水线工作最快的方式# 1. 全局安装含 BoneScript 等全部依赖 npm install -g smallcode # 2. 在项目目录创建 .env SMALLCODE_MODELqwen3:8b SMALLCODE_BASE_URLhttp://localhost:11434/v1 # 3. 启动 smallcode然后试试这些输入观察系统提示词变化你的输入触发的前置步骤fix it第 1 步澄清检测注入package.json 这个干嘛的第 3 步文件内容注入为什么最近的改动让测试挂了第 4 步git diff 注入纯闲聊你好呀第 6 步判为 respond0 工具重构这个模块要改多个文件并跑测试第 7 步计划锚点生成总结小模型的可靠性是用确定性代码换来的回头看这 8 件事你会发现一个共同点所有 SmallCode 在小模型身上做的补偿全部发生在模型生成第一个 Token 之前而且几乎全部是零 token 成本的本地计算——正则分类、文件扫描、git 快照、预算压缩。它不是更聪明的 Cursor而是一套围绕小模型会忘事、会写坏 JSON、上下文又短这三个弱点长出来的架构。理解这 8 步你就理解了 SmallCode 在 4B 激活参数模型上跑 87% benchmark 的全部秘密。【免费下载链接】smallcodeAI coding agent optimized for small LLMs. 87% benchmark with 4B-active model.项目地址: https://gitcode.com/gh_mirrors/sm/smallcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考