一个想法

以前聊 AI 编程，绕不开 Claude、GPT-4 这些大模型。API 贵，数据还要往外送。

我有个朋友，公司代码敏感，什么 AI 工具都不让用。他想搞个本地编程助手，试了一圈都不行——Codex 要 128k 上下文，OpenCode 调一次 Claude 几十美分，Cursor 便宜但也不让走本地。

这事我以前也觉得无解，直到刷到了 SmallCode。

这项目今年 5 月刚发，两天 488⭐，设计思路很有意思——不是给 Claude/GPT-4 用的，是给 7B-20B 小模型用的。你甚至可以用一个 4B 的小模型跑出 87% 的基准成绩。我跑了一遍，写了这篇东西。

第一步：安装和配置

安装很简单，一行命令：

npm install -g smallcode

然后在项目根目录建一个 .env 文件：

SMALLCODE_MODEL=qwen2.5-coder-7b-instructSMALLCODE_BASE_URL=http://localhost:1234/v1

这是给 LM Studio / Ollama 用的。你跑哪个模型就填哪个名字。如果本地模型搞不定，还能配一个云模型做后备：

可选：本地不行时自动切到云

ANTHROPIC_API_KEY=sk-ant-…OPENAI_API_KEY=sk-…

后备机制是 opt-in 的，不配 key 就不会联网。代码完全本地跑。

试跑：

cd my-projectsmallcode

一个 TUI 界面就启动了，命令行交互，对，就是那种终端里干活的风格。

第二步：理解它的核心设计

翻完文档我觉得，SmallCode 最聪明的地方不是功能多，而是知道自家模型不行。

大模型编程助手假设你用的是 Claude Sonnet 4 级别——128k 上下文，JSON 输出稳定，全量文件读写无压力。

SmallCode 做了完全相反的假设：我的模型可能只有 8k 上下文，输出会乱，文件写不全。

所以它做了几件事：

上下文预算引擎

模型上下文只有 8k-16k，SmallCode 就自动压缩。大文件只保留函数签名，旧消息被驱逐，实时追踪 token 用量。

宽容的工具调用解析器

小模型输出乱七八糟。SmallCode 能从 JSON、YAML、XML、纯文本里解析出工具调用。参数名写错了？自动修复。类型不对？自动转换。不像前沿模型那么精准，但经得起折腾。

TODO 驱动规划

复杂任务不会一次丢给模型让它自己发挥。SmallCode 先把任务拆成原子步骤写到一个 TODO 文件里，模型每轮读 TODO 文件确认自己在哪步。每步做完都会 lint/编译验证，没过就不往下走。

Patch 优先的编辑策略

这是我最认同的一点。大模型项目喜欢全量文件写入——模型生成整个文件内容，直接覆盖。小模型做不到，生成 500 行的文件，写到后面就记不住前面的，不是截断就是跑偏。

SmallCode 用搜索替换（patch）作为主要编辑方式。只改需要改动的地方，Context 更省，结果更可靠。

第三步：动手跑一个 Express API 生成

SmallCode 内置了一个叫 BoneScript 的东西。写一个 .bone 文件，编译成完整项目——路由、认证、数据库、事件、迁移、SDK、管理后台、Docker、CI，一套全出。

我试了一下，新建一个 api.bone：

api Userfields: name email passwordroutes: crudauth: jwtdatabase: sqlite

就这五行，然后：

smallcode

SmallCode 识别到 .bone 文件，调起编译流程。如果是用本地小模型跑，它会走 TODO 分解流程：先读文件 → 理解结构 → 生成路由 → 写数据库层 → 加认证 → 验证编译。

对比手动写，这个调用链能从 8-15 次工具调用压缩到 1-2 次，在小模型上可靠性提升很大。

另一个场景：我有一个老项目的代码生成太慢，SmallCode 的 graph_search 和 explain_symbol 工具可以快速定位跨文件调用链，不用自己翻几十个文件。

第四步：三个实战场景

场景 1：给 Vue 项目加一个组件

假设你要在现有的 Vue3 项目里加一个数据表格组件，带筛选和导出：

路径：/my-admin-app模型：qwen2.5-coder-7b-instruct

在 SmallCode 终端输入：

给 /src/components/ 创建一个用户管理表格组件，包含搜索、分页、导出 CSV。用 Element Plus 的 el-table。

SmallCode 会先 graph_search 扫描项目结构，理解现有代码风格，然后生成组件代码，调用 patch 写入，最后检查编译。

场景 2：修复一个 bug

传统的做法：报错日志贴到 ChatGPT → 它给你一段代码 → 你手动改 → 可能引入新问题。

SmallCode 的做法：

read_file src/utils/parser.js → 看代码 → bash ‘node src/test/parser.test.js’ → 看报错 → 定位问题在第 45 行的正则 → patch 修复 → 重新跑测试 → 通过

整个过程模型控制，你只需要在 TUI 里看日志就行。

场景 3：本地小模型 + 云模型混合

小模型大部分场景都够用，但有时候就是搞不定。SmallCode 有一个 escalation 机制：

SMALLCODE_ESCALATE_ON_HARD_FAIL=true

当本地模型重试 + 分解后仍然失败，自动升级到配置的云模型。只解决这一个难点，不会整个流程切到云。会话级别限制，防止费用失控。

支持的云模型名单：Claude Sonnet 4.5/4.6、Haiku 4.5、GPT-5.4 Mini/Nano、DeepSeek V4。

第五步：进阶扩展

自定义技能

写一个 .smallcode/skills/vue-component.md：

Vue 组件创建规范

• 使用 Composition API + script setup
• 样式用 scoped，不用全局
• Props 必须写类型和默认值
• 事件用 emit，不直接修改父组件数据

以后创建 Vue 组件时，模型会自动加载这个技能文件。

Model Profile

不同模型有不同的强项。SmallCode 支持 per-model 配置：

{“qwen2.5-coder-7b”: {“context”: 32768,“tool_format”: “json”,“strengths”: [“code generation”, “debugging”],“weaknesses”: [“web research”, “large refactors”]}}

Web 搜索支持

给中型模型（20B+）开启网页能力：

SMALLCODE_WEB_BROWSE=true

Playwright 驱动，隐身模式防反爬。跑的时候会搜文档、查 API，辅助代码生成。

踩坑记录

1. Node 版本要 18+

第一次 run 直接报错。查了半天，SmallCode 依赖 Playwright，而 Playwright 需要 Node 18+。如果你还在 Node 16，升级或者用 nvm 切版本。nvm install 18 && nvm use 18 就解决了。

2. 模型名称要写 exact match

配置 SMALLCODE_MODEL 时，名字必须和 Ollama/LM Studio 里显示的一模一样。少一个冒号或大小写不对，返回 404 但不会报明显错误，就是空转。建议先在 Ollama 里跑 ollama list 确认名字。

3. .env 文件位置

.env 必须放在项目根目录，不是 home 目录也不是 smallcode 安装目录。我第一次放在了 ~/，读不到，模型一直连不上。SmallCode 默认从当前工作目录加载 .env。

4. BoneScript 不适合复杂迁移

.bone 文件编译出来的项目结构是模板化的。如果你要从一个已有的、结构混乱的项目迁移到 BoneScript 生成的结构，模型会困惑。建议只在新项目上用 BoneScript。

5. 小模型对中文的理解差异

我试了 Qwen2.5-Coder-7B，中文 prompt 输出没问题。但换到 DeepSeek-Coder-6.7B 时，同样的中文需求，它会在代码注释里写出英文注释。不是 bug，是训练数据偏向问题。建议用 Qwen 系列。

6. 第一次启动慢

首次运行会下载 Playwright 浏览器（chromium 约 150MB）。如果服务器在国内，下载可能会超时。可以手动设置 PUPPETEER_SKIP_DOWNLOAD=true 跳过，或者在有小文件需求的场景直接不开启 WEB_BROWSE。

7. TUI 模式下退出

/smallcode 习惯了 Cursor 的 GUI，SmallCode 的 TUI 是终端全屏模式。退出用 /quit 或 Ctrl+C。如果被卡在某个输出里，按 q 回到提示符。

8. 大型项目 graph_search 慢

如果你的项目有 10 万+ 文件（monorepo），graph_search 首次索引需要几分钟。可以提前跑 smallcode --index-only 预建索引，这样实际使用时就不等了。

9. 上下文丢消息

8k 上下文的模型配合默认配置，大概能处理 5-8 轮对话。如果对话长了，前面的决定会被驱逐。这时可以用 /memory 查看工作记忆，或者手动总结当前进度写到 /plan 文件里。

10. 云模型后备的超时

如果你配了 ANTHROPIC_API_KEY 但网络不好（比如服务器在境内访问 Claude），escalation 会超时。SmallCode 默认超时 60 秒，可以通过 SMALLCODE_ESCALATION_TIMEOUT=120 改长一点。

总结

SmallCode 不是那种"用最强模型解决一切"的项目，它是另一种思路——让弱模型也能干活。上下文预算、宽容解析、TODO 分解、patch 优先——这些设计对那些只能在本地跑模型的人来说，每一条都是实打实的痛点。

如果你公司代码敏感、不想用云 API，或者手上有台带显卡的机器想发挥点价值，可以试试。npm install -g smallcode 三秒装完，在本地项目跑一下，感受一下区别。