Refact：本地优先的 AI 编程 Agent 引擎

重新定义 IDE 中的 AI 助手

想象一下这样的场景：你正在开发一个复杂的 Python 后端服务，遇到了一个棘手的 bug——栈追踪很深，涉及异步代码和数据库查询。你打开 AI 助手窗口，它不仅能阅读你的代码，还能直接运行调试器、查询 PostgreSQL 数据库、访问 GitHub PR 记录，甚至打开 Chrome 浏览器帮你验证 UI 问题。这不是科幻，而是 Refact 正在做的事。

Refact 是一个开源、本地优先的 AI 编程 Agent 项目，核心由 Rust 编写（refact-lsp 二进制），通过 LSP 协议与 IDE（VSCode、IntelliJ）深度集成。它不是简单的代码补全工具，而是一个能真正替代部分开发工作的自主 Agent。

Refact 架构图

起源：从云端服务到本地优先的转型

Refact 最早由 smallcloudai 公司开发，曾运营过 Refact Cloud 云端服务。然而，随着开源社区对数据隐私的重视以及自托管需求的增长，项目团队做出了一个重要决定：关闭 Refact Cloud，将重心转向完全本地优先的部署模式。

这个转变极具行业代表性——它反映了一个更大的趋势：AI 编程工具正在从"云端大脑"转向"本地推理引擎"，代码和数据始终留在开发者机器上，模型选择权交给用户（BYOK, Bring Your Own Key）。

[!NOTE] 原维护方 smallcloudai 已于 2026 年停止活跃开发，项目已迁移至社区分支 JegernOUTT/refact。当前仓库作为历史存档保留。

技术架构：Rust 引擎 + React GUI + 插件生态

Refact 的架构设计体现了专业化分工的思路，整个项目拆分为四个主要组件：

1. Agent Engine（Rust 引擎）

这是 Refact 的核心大脑，一个同时充当 LSP 服务器和 HTTP 服务器的二进制程序（refact-lsp）。技术栈极为丰富：

• HTTP 框架：Axum（异步 Rust Web 框架）
• 语言服务器：tower-lsp（实现完整的 LSP 协议）
• 代码解析：tree-sitter（7 种语言的 AST 解析器：C/C++、Python、Java、Kotlin、JavaScript、Rust、TypeScript）
• 向量数据库：SQLite + vec0（本地语义搜索）
• 存储引擎：LMDB/Heed（高性能键值存储，用于 AST 缓存）
• 异步运行时：Tokio（支持 12+ 后台任务并发）

引擎通过 LSP 协议与 IDE 通信，同时暴露出 27+ 个 HTTP API 端点，供 GUI 和外部工具调用。聊天模块（chat/）就有 22+ 个文件、近 15K 行代码，涵盖会话管理、生成流式输出、工具调度和轨迹记忆等核心功能。

2. Agent GUI（React 前端）

独立部署的 React 18 + TypeScript 聊天界面，通过 Redux Toolkit（RTK Query）与引擎通信。支持三种模式：

• IDE 内嵌模式：通过 postMessage API 与 IDE 原生界面集成
• 独立 Web 模式：部署为静态网站，通过 Nginx served
• 浏览器自动化模式：内置 Chrome DevTools Protocol 工具，可操控真实浏览器

3. IDE 插件（TypeScript + Kotlin）

官方提供 VSCode（TypeScript）和 JetBrains IntelliJ（Kotlin）两个插件，负责在 IDE 和引擎之间传递上下文、管理文件操作和主题同步。

4. LLM Provider 体系

这是 Refact 区别于其他 AI 编程工具的关键——它支持 15+ 种 LLM 提供商，包括： Anthropic Claude、OpenAI GPT 系列、DeepSeek、Codex、Gemini、Groq、LM Studio、Ollama、OpenRouter、vLLM、xAI Grok、Claude Code，以及自定义 API 端点。

用户完全控制模型选择和数据流向——可以选择调用本地 Ollama/vLLM（代码完全不离开机器），也可以接入云端 API 获得更强推理能力。

核心功能：从代码补全到自主工作流

深度代码理解

凭借 tree-sitter 实现的 AST 索引，Refact 能够理解代码的语法结构而不仅仅是文本匹配。这意味着它能：

• 准确识别函数调用链和变量作用域
• 提供基于语义的代码补全，而非简单的 n-gram 预测
• 支持跨文件的语义搜索（VecDB 向量搜索）

工具驱动的 Agent 工作流

Refact 内置 50+ 种工具，分为几大类：

• 文件系统：读取、编辑、创建文件，支持差异对比
• 代码搜索：正则搜索、语义搜索、符号查找
• Shell 执行：在终端运行命令并解析输出
• 版本控制：Git 操作、GitHub/GitLab PR 审查
• 数据库：PostgreSQL、MySQL 查询和数据探索
• 调试：PDB（Python Debugger）集成
• 浏览器自动化：Chrome/Chromium 操控、截图、控制台日志提取
• MCP 集成：支持 Model Context Protocol 扩展工具集

Agent 的工作流程是规划→执行→验证→迭代，它会将任务分解为步骤，逐步调用工具，并在失败时自动重试或换用替代方案。

Web UI 和文档

docs 目录包含完整的 Astro 构建文档站点，有独立 Dockerfile，可一键部署为 Nginx 静态站点。

部署体验：中等难度，适合有经验的开发者

Refact 不是一个"一键安装"的工具，但也不是特别复杂。主要挑战在于：

1. Rust 编译：首次构建需要编译整个 workspace（含 28 个 crate），在无缓存环境下可能需要 10-20 分钟
2. GPU 配置：如果使用本地模型推理（如 Ollama/vLLM），需要 NVIDIA GPU 和 CUDA 环境
3. 多组件协调：引擎、GUI、插件需要正确配置才能互通

推荐安装路径：

• VSCode/IntelliJ 用户：直接安装官方插件，插件会自动下载或引导配置引擎
• 高级用户：源码编译（cargo build --release），获得最佳性能和完整定制能力
• 文档站：独立部署，docs/Dockerfile 提供开箱即用的 Nginx 镜像

局限与争议

1. Rust 编译门槛：相比 Python/TypeScript 项目，Rust 编译环境配置对新手不友好
2. 内存占用：完整索引大型代码库需要可观的 RAM 和磁盘空间
3. 云端关闭影响：Refact Cloud 关闭意味着缺少托管服务，需完全自管理
4. 社区维护风险：活跃开发已迁移至社区分支，质量和响应速度不确定
5. 非 HuggingFace 生态：不同于主流开源 AI 项目，Refact 不在 HF Hub 上发布模型，工具链集成需要额外适配

行业意义

Refact 代表了 AI 编程工具的一条独特路线——本地优先 + 深度 IDE 集成 + 工具生态。它与 GitHub Copilot（云端集成）、Cursor（Electron 应用）、Cline（VSCode 插件）等路线各有侧重。

最值得关注的是它的工具调用架构：不仅让 AI 读代码，还能让它"动手做事"——运行命令、查数据库、开浏览器。这种能力边界正在快速扩展，未来很可能成为 AI 编程助手的标准形态。

随着 MCP（Model Context Protocol）的普及，Refact 的工具体系有望与更广泛的 AI Agent 生态互通，进一步放大其价值。