Refact：可自托管的开源本地优先 AI 编程助手｜部署与使用全指南

适用读者：想在自己机器上跑一个不绑定任何云厂商、可接任意大模型的 AI 编程助手的开发者；希望把 IDE 侧边栏、终端 TUI、浏览器 GUI、自主 agent 全部收敛到同一个本地守护进程上的极客。本文所有安装命令、目录路径、子命令、提供商名单均来自官方 README，已对原仓库归档状态做如实标注，可放心照着做。

一、Refact 是什么

Refact 是一个开源、本地优先（local-first）的 agentic 编程引擎，以一个独立的 refact 二进制分发。它不是一个单纯的 IDE 插件，而是一个常驻后台的本地守护进程：启动一次之后，守护进程会托管每个项目的 worker、在浏览器里开 GUI、提供全屏 TUI、对外暴露 LSP/HTTP 给编辑器客户端，并让自主 agent 用同一套工具（文件、shell、浏览器自动化、AST 搜索、补丁、检查点、MCP）干活。

适用场景：想把 AI 编程助手的所有项目状态、向量索引、会话轨迹都留在自己仓库 .refact/ 目录下；想同时接 Anthropic、OpenAI、DeepSeek、豆包、通义、Kimi、智谱、MiniMax、Ollama、LM Studio、vLLM 等二十多家提供商而不被某一家绑死；想用 git worktree 同时开多个隔离的子 agent 并行改代码。

能力边界（README 原文已自报）：常驻守护进程与 TUI 仍属于 early preview，可能有 bug 且可能不通知就改接口；稳定面只有 IDE 插件（VS Code / JetBrains）和核心引擎。生产环境重度依赖 TUI 的同学请自行评估。

二、功能特性

• 10+ agent 模式、50+ 工具、20+ 提供商家族：ask / explore / plan / agent / debug / buddy / task_planner / task_agent 各自有独立的系统提示词、工具集与子 agent 策略；模式切换不是换皮肤，而是换一套"操作系统"——只读探索时不允许写文件，自主执行时才放开 shell。
• 真实会话运行时：聊天在 Idle → Generating → ExecutingTools → WaitingUserInput/Paused → Completed/Error 之间流转，一次请求可以变成"改—跑—看—再改"的迭代循环，而不是单轮问答；工具调用、思考块、引用、服务端内容块以类型化 delta 流式合并，兼容工具可并行执行。
• 搜索栈：tree、cat、正则、AST symbol_def、语义搜索、轨迹/知识库查询、项目记忆——按路径、结构、语义三个维度三角定位代码。
• 编辑是一等公民且带护栏：apply_patch、create_textdoc、update_textdoc*、mv、rm、undo_textdoc，带确认门，补丁类编辑可有限度自动通过；每次工作区变更都能 undo。
• 运行时闭环工具：shell、process_start/read/wait/kill、PTY process_write_stdin、sleep、cron_create/list/delete/fire，让 agent 能跑命令、盯服务、驱动交互进程、安排后续任务。
• 子 agent 委派：subagent 把探索、评审、实现拆给专门 agent，不同模型的评审者独立调查同一领域后再对质，最后按证据裁决。
• Buddy 主动项目伙伴：常驻观察项目状态（卡住的任务、缺省模型、MCP 鉴权失败、记忆堆积、git 压力、诊断扎堆、依赖风险、文档漂移、覆盖率缺口），只提建议不擅自改代码。
• 任务看板 + worktree 隔离：一次描述需求，planner 拆成卡片，每张卡片在独立 git worktree 里跑 agent，跑完按依赖顺序 squash-merge 回来。
• 本地记忆：<项目>/.refact/ 下保存计划、笔记、轨迹、代码语义；petgraph 知识图谱 + SQLite + vec0 向量索引；set_plan / update_plan / get_plan 做不会被压缩吞掉的静态计划；历史压缩分四步：去重 context_file、压缩大块工具结果、修复 tool-call/tool-result 顺序、再按预算裁剪。
• MCP / Skills / Slash 命令 / Hooks / 子 agent / 市场：MCP 走懒发现，mcp_tool_search 找到再 mcp_call，不会把整个工具目录塞进提示词；Skill 用 activate_skill 按需加载；pre/post-tool 与生命周期 hooks 用来挂策略、日志、格式化。
• BYOK：Anthropic、OpenAI、OpenAI Responses、OpenAI Codex、OpenRouter、Groq、DeepSeek、豆包（Doubao）、xAI、Google Gemini、Qwen、Kimi、Zhipu、MiniMax、GitHub Copilot、Claude Code，以及任意 OpenAI 兼容端点；本地可接 Ollama、LM Studio、vLLM。

三、官方界面预览

除上面两张官方 README 图外，官方还提供了任务看板截图（每张卡片一个 agent、隔离 worktree）。本文只保留 README 内嵌图，不另找网络杂图。

四、官方链接汇总

五、前置要求

• 操作系统：Unix / macOS（一行脚本安装）或 Windows PowerShell；无服务器端强制要求。
• 运行时：官方安装脚本会自包含一份独立二进制到 ~/.refact/bin/，不要求系统预装 Rust / Node / Python；如果你打算接本地推理模型，再自行准备 Ollama / LM Studio / vLLM。
• 模型凭证：任选一家或多家提供商的 API Key（BYOK），或本地起一个 OpenAI 兼容端点；不强制注册任何 Refact 账号（Refact Cloud 已停运）。
• 磁盘：项目索引、向量库、轨迹都落在 <项目>/.refact/，大型 monorepo 预留几百 MB 到数 GB 视仓库规模而定。
• 显卡：不强制。用云端 API 时零 GPU；用本地 vLLM / Ollama 时按所选模型自行准备显存。

六、安装部署

Unix / macOS

curl -fsSL https://raw.githubusercontent.com/JegernOUTT/refact/main/install.sh | sh

装完后启动：

refact ui

安装器会把 refact 链接到已经在 PATH 上的目录（通常是 ~/.local/bin）；如果没有这样的目录，它会打印一行精确的激活命令，照抄即可。

Windows PowerShell

irm https://raw.githubusercontent.com/JegernOUTT/refact/main/install.ps1 | iex
refact ui

安装器会同时更新用户 PATH 和当前 PowerShell 会话。

手动下载

也可以直接到 https://github.com/JegernOUTT/refact/releases 下载对应平台的二进制，放到 ~/.refact/bin/refact（Windows 为 %USERPROFILE%\.refact\bin\refact.exe）并加入 PATH。

在项目里打开工作区

cd /your/project
refact projects open .
refact

refact projects open . 会注册当前目录为一个受守护进程托管的项目并启动它的 worker；refact 打开全屏 TUI。

七、配置项说明

• 提供商与密钥：通过 refact ui 打开浏览器 GUI，在 BYOK 页面配置；也可以直接编辑 ~/.config/refact/ 下的 YAML。YAML 模板在源码仓 refact-agent/engine/yaml_configs/defaults/。
• 模型按角色分配：chat、agent、task planner、light chat、thinking、Buddy、代码补全/FIM、embedding 各自有独立默认模型，可以按"便宜路由做轻聊、前沿模型做 agent"的思路拆开。
• 本地状态目录：
  • <项目>/.refact/：轨迹、知识、任务、集成、调度、VecDB 索引——随仓库走，可单独备份。
  • ~/.config/refact/：用户级隐私规则与提供商定义。
  • ~/.cache/refact/：缓存、日志、遥测产物、shadow repo、集成运行时状态。
• MCP：接 stdio server 或 Streamable HTTP / SSE 端点（含 OAuth 配置），调用走 mcp_tool_search 懒发现 + mcp_call。
• IDE 插件：VS Code / JetBrains 插件会把引擎下载到 ~/.refact/bin/refact，并把该目录注册到 PATH；首次用插件下载完引擎后新开一个终端才能在命令行直接敲 refact。

八、使用流程

1. 安装后跑 refact ui，浏览器自动打开本地守护进程的 GUI；
2. 在 BYOK 里填至少一家提供商的 Key（或指向本地 Ollama / LM Studio）；按角色拆模型：聊天用便宜路由、agent 用前沿模型、embedding 用本地小模型；
3. cd 到你的项目，refact projects open .；第一次打开会做 AST 索引和向量索引，大型仓库需要等一会儿；
4. 在 GUI / TUI / VS Code 里选模式（ask 问答、explore 只读探索、plan 出方案、agent 自主改、debug 排障）开始聊天；
5. 大任务用 task planner：描述一次需求，看板会拆成卡片、在独立 worktree 里并行跑 agent，跑完由 planner 决定 merge 或 squash；每张卡片有 depends_on 边，跑不动的卡片会自动 blocked；
6. Buddy 在后台看项目状态，发现机会会弹建议卡片，你点头才改；它默认 auto_approve_editing_tools: false 与 auto_approve_dangerous_commands: false，不要图省事全开；
7. 需要挂自己的工具时，在 MCP 里加 stdio 或 HTTP/SSE server，用 mcp_tool_search 懒发现，不要把整个工具目录塞进系统提示词。

九、常用运维 / 更新命令

常见坑：--tui 不是顶层 flag，正确写法是 refact 或 refact tui，不要写成 refact --tui。

十、常见故障排查

十一、风险与责任使用声明

1. 本文安装命令、目录路径、子命令、提供商名单均来自活动仓库 JegernOUTT/refact 的官方 README；原 smallcloudai/refact 仓库已被官方归档（archive=true），Refact Cloud 已官方宣布停运，请勿再按旧 Cloud 文档找登录入口。
2. 守护进程与 TUI 属于 early preview，可能在未通知的情况下改接口；IDE 插件与核心引擎是稳定面，生产重度依赖前请自行评估。
3. agent 模式默认会调用 shell、文件编辑、浏览器自动化等工具；buddy 模式默认 auto_approve_editing_tools: false 与 auto_approve_dangerous_commands: false，请保持这些默认值，不要为了省事全开。
4. API Key 保存在你本机 ~/.config/refact/ 与项目 .refact/ 下，本文不收集、不代存任何密钥；输出文章里也不会出现任何 Key。
5. 许可证为 BSD-3-Clause，可自由自用与二次开发；请遵守你所接入模型提供商各自的服务条款。