SmallCode

简体中文 | English

---

专为小型 LLM (8B-35B 参数) 优化的 AI 编程助手

SmallCode 是一款原生终端编程助手，从零开始设计，旨在从运行在消费级硬件上的本地模型（8B-35B）中挖掘出色的工作效率。虽然 OpenCode 等工具假设用户拥有具备 128k+ 上下文和完美工具调用能力的尖端模型，但 SmallCode 通过智能架构弥补了小型模型的局限性。

推荐模型尺寸：8B-35B 参数。 更小的模型 (≤4B) 在多步工具使用方面表现吃力，且容易在多轮对话中丢失上下文。更大的模型 (>35B) 不需要 SmallCode 的适配，更适合使用为尖端模型设计的工具。

为什么选择 SmallCode？

	OpenCode	SmallCode
目标模型	尖端模型 (Claude, GPT-5)	8B-35B 本地模型
上下文	完整输出	预算管理、摘要总结
工具调用	假设 JSON 可靠	宽容的多格式解析器
任务规划	单次处理	TODO 文件分解步骤
文件编辑	全量写入	搜索并替换补丁
隐私	需 API 调用云端	完全本地，无需联网

快速上手

# 通过 npm 全局安装
npm install -g smallcode

# 或者直接使用 npx 运行
npx smallcode

# 在你的项目目录中启动
cd my-project
smallcode
# 或者使用封装后的命令别名：
smolv2

预编译二进制文件（无需 Node.js）

每个版本都会构建适用于 Windows、macOS 和 Linux 的预编译压缩包 —— 它们打包了 Node.js 以及所有原生插件，因此你永远不需要 node-gyp 或 C++ 构建工具。

平台	一键安装
Linux / macOS	bash <(curl -s https://raw.githubusercontent.com/Doorman11991/smallcode/main/install.sh)
Windows	`powershell -Command "irm https://raw.githubusercontent.com/Doorman11991/smallcode/main/install.ps1

关于 prebuild-install@7.1.3: No longer maintained 警告的说明 (Issue #57)： 这是一个来自传递依赖 (budget-aware-mcp → better-sqlite3 → prebuild-install) 的无害上游弃用通知。prebuild-install 没有发布更新版本，而 better-sqlite3 仍然依赖它，因此无法通过版本升级消除该警告。它不会影响安装 —— npm 警告仅供参考，包可以正常安装。如果你希望完全跳过原生依赖，请使用以下命令安装（你将失去 FTS5 内存搜索功能，但保留 JSON 内存回退机制）： npm install -g smallcode --omit=optional

配置

在项目根目录下创建一个 .env 文件：

# 必填
SMALLCODE_MODEL=your-model-name
SMALLCODE_BASE_URL=http://localhost:1234/v1

# 可选：升级策略（在发生严重错误时自动回退到云端）
# ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# OPENROUTER_API_KEY=sk-or-v1-...
# DEEPSEEK_API_KEY=sk-...

查看 .env.example 获取所有选项。同时也支持 smallcode.toml 以实现向后兼容。

SmallCode 可以将不同的模型层级路由到不同的端点。这使你可以将快速/默认任务保持在本地，同时将复杂任务发送给更大的 OpenRouter 模型：

SMALLCODE_MODEL=qwen3:8b
SMALLCODE_BASE_URL=http://localhost:11434/v1

SMALLCODE_MODEL_STRONG=openai/gpt-4o-mini
SMALLCODE_BASE_URL_STRONG=https://openrouter.ai/api/v1
OPENROUTER_API_KEY=sk-or-v1-...

对应的 smallcode.toml 写法：

[model]
provider = "openai"
name = "qwen3:8b"
baseUrl = "http://localhost:11434/v1"

[models.strong]
name = "openai/gpt-4o-mini"
baseUrl = "https://openrouter.ai/api/v1"

层级 URL 是可选的。如果省略 SMALLCODE_BASE_URL_STRONG 或 [models.strong].baseUrl，该层级将使用主基础 URL。

架构

SmallCode 采用模块化架构构建：

bin/
├── smallcode.js        入口点，Agent 循环，TUI 编排 (1570 行)
├── config.js           配置加载，端点检测，认证头部
├── executor.js         工具执行 (全部 18 个工具)
├── tools.js            工具定义 + 两阶段路由
├── mcp_bridge.js       内置代码图谱 MCP 通信
├── model_client.js     LLM API 调用，流式传输，验证
├── governor.js         工具评分，验证，任务分解
├── escalation.js       云端模型回退 (Claude/OpenAI/DeepSeek)
├── commands.js         TUI 斜杠命令
├── tui.js              经典 TUI 渲染器
└── bonescript_guide.js BoneScript 语法参考

src/
├── api/index.js        编程 API (require('smallcode'))
├── tui/fullscreen.js   全屏备用缓冲区 TUI
├── tui/terminal.js     终端生命周期 (raw 模式 / 鼠标 / 保证还原)
├── plugins/loader.js   插件系统
├── plugins/skills.js   技能系统
├── tools/              工具路由，MCP 客户端，验证器
├── governor/           提前停止检测，验证器，工具评分器
├── model/              多模型配置 + 路由
└── session/            持久化，撤销，共享，引用

核心特性

MarrowScript 认知层

SmallCode 的智能特性尚在完善中...