代码重构助手

把遗留代码重构为现代规范代码，保持原有接口与行为不变

一个基于本地大模型的代码重构服务。输入一段源代码和一句重构要求，输出重构后的完整代码。

代码不离开你的机器 —— 核心版通过本地 Ollama 推理，无任何数据上传。

快速开始 · 功能 · 使用方式 · 定价 · 贡献

这是什么

历史项目里总有些代码：能跑，但没人愿意碰。变量叫 a、tmp1、data2，三层嵌套的 if 里塞着业务逻辑，同一个校验规则在五个地方各写了一遍。

这个项目做的就是把这些代码改造好。它不修复 bug、不添加功能，只改结构——让代码好读、好改，同时保证外部行为完全不变。

核心能力由本地 Ollama 上的代码模型（默认 deepseek-coder）驱动，可以以 MCP Server、HTTP API、技能包 等多种形态接入你现有的工作流。

Related MCP server: CodeBrain

功能

支持语言：Python · JavaScript · TypeScript · Java · Go · Rust · C · C++

设计原则

重构这件事，改坏比不改更糟。所以本项目有两条硬约束：

1. 不改公共接口 —— 函数名、类名、参数签名、返回值结构保持原样（除非你明确要求改）

2. 保持行为等价 —— 重构后逻辑与原代码一致，不顺手修 bug

快速开始

前置条件

• Python 3.11+ 或 Node.js 18+

• Ollama 已安装并运行

• 已拉取代码模型：ollama pull deepseek-coder

方式一：本地 Python 直接调用

git clone https://github.com/zhouhengchang/code-refactor.git
cd code-refactor
python shared/refactor_core.py   # 内置自测，会先检查服务再跑一个示例

也可以在自己的代码里调用：

# -*- coding: utf-8 -*-
"""最小调用示例。"""

from shared.refactor_core import refactor_code, check_ollama_status

# 先确认环境就绪
print(check_ollama_status())

# 执行重构
result = refactor_code(
    code="def f(a):\n    r = []\n    for i in a:\n        if i % 2 == 0:\n            r.append(i * i)\n    return r\n",
    task="重命名为有意义的函数名与变量名，补充类型标注与中文注释",
    language="python",
)

if result["ok"]:
    print(result["code"])
else:
    print("失败：", result["error"])

方式二：作为 MCP Server 接入（Claude Desktop / WorkBuddy / 任意 MCP 客户端）

已发布到 npm，不用克隆仓库，直接在 MCP 客户端配置里引用：

{
  "mcpServers": {
    "code-refactor": {
      "command": "npx",
      "args": ["-y", "workbuddy-code-refactor-connector"],
      "env": {
        "REFACTOR_BACKEND": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "deepseek-coder"
      }
    }
  }
}

npm 包：workbuddy-code-refactor-connector

也可以从源码运行，便于自己改代码：

cd workbuddy-connector/server
npm install

然后把上面的 command 改成 node，args 改成 ["/绝对路径/to/workbuddy-connector/server/index.js"] 即可。

重启客户端后即可使用 refactor_code 和 check_status 两个工具。

方式三：Docker 部署 HTTP 服务

docker build -t code-refactor-xpack:1.0.0 -f xpack-server/Dockerfile .
docker run -p 8000:8000 \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -e OLLAMA_MODEL=deepseek-coder \
  code-refactor-xpack:1.0.0

调用：

curl -X POST http://localhost:8000/refactor \
  -H "Content-Type: application/json" \
  -d '{
    "code": "def f(a):\n    return [i*i for i in a if i % 2 == 0]\n",
    "task": "函数名与变量名改为有意义的命名，补充类型标注",
    "language": "python"
  }'

使用方式

输入

输出

{
  "ok": true,
  "code": "重构后的完整代码",
  "model": "deepseek-coder",
  "language": "python",
  "elapsed_ms": 3820
}

失败时返回 {"ok": false, "error": "可读中文错误信息", "error_type": "..."}，不抛异常、不暴露堆栈。

task 怎么写

这是影响结果质量最大的一个变量。

使用建议

• 一次一个目标。 「重构 + 加功能」拆成两步做。

• 长代码分批。 单次 ≤ 300 行为宜，按函数粒度提交。

• 结果先验证再应用。 跑一遍现有测试再替换生产代码。

配置

全部通过环境变量注入，代码中不含任何密钥。

本地和云端两套后端同一份代码，切换只改环境变量：

# 改用云端 OpenAI 兼容接口
export REFACTOR_BACKEND=openai
export OPENAI_API_KEY=sk-xxxx

超时默认给到 180 秒，是因为在纯 CPU 的低配机器上本地推理可能需要 1 分钟以上。如果你的机器有 GPU，可以调小。

想用更小更快的本地模型：OLLAMA_MODEL=qwen2.5-coder:1.5b。

运维工具

tools/ 下有两个自检脚本，改完配置或轮换密钥后建议跑一遍，避免"改完才发现用不了"：

# 只验证，不改任何文件
python tools/rotate_key.py --check --key sk-xxxx

# 验证通过后写入 .env
python tools/rotate_key.py --apply --key sk-xxxx

# 线上实例体检
python tools/verify_online.py https://your-host/

rotate_key.py 只改 .env 里 OPENAI_API_KEY 一行，其余配置原样保留。

项目结构

code-refactor/
├── shared/refactor_core.py      # 核心逻辑（唯一真源）
├── workbuddy-connector/         # WorkBuddy / MCP 连接器
├── xpack-server/                # OpenAPI + FastAPI + Dockerfile
├── coze-skill/                  # 扣子技能包
├── skillhub-skill/              # SkillHub Pay Skill
├── alipay-ai/                   # 支付宝 AI收 接入配置
├── xinghuo-agent/               # 讯飞星火智能体配置
├── tools/                       # 密钥轮换与线上体检脚本
└── github-repo/                 # 本文档所在的开源仓库

开源版与托管版

本项目采用 Freemium 模式：核心能力完全开源免费，托管服务面向不想自己部署的用户。

该选哪个？

• 代码不能出内网 / 想完全掌控 → 开源版，直接克隆部署

• 本机没有 GPU、不想折腾环境、需要更好的重构质量 → 托管版

👉 托管版入口： https://code-refactor.app.workbuddy.host

托管版同样承诺：代码仅用于本次推理，不留存、不用于模型训练。

在各大平台使用

本服务已适配以下平台，可按需取用对应目录下的配置文件：

常见问题

Q：为什么非要本地跑？云端 API 不是更方便？ 代码是核心资产。本地推理意味着你的代码一个字节都不会离开你的机器——这对企业代码库往往是硬性要求。想省事就用托管版。

Q：重构会不会改坏我的代码？ 设计上不会改变外部行为，但这不构成保证。上生产前请务必跑测试。 项目的第一原则就是"不改接口、不改行为"，但模型输出总有不确定性，代码审查不可省。

Q：支持多大的代码？ 单次 20000 字符以内，建议 300 行以内。更大的文件按函数拆分。

Q：能只重构一个函数吗？ 可以，只把那个函数贴进来就行。

Q：为什么用 deepseek-coder？ 在代码任务上表现稳定，是本地小体量模型里性价比较好的选择。你可以通过 OLLAMA_MODEL 换成任何 Ollama 模型。

注意：Ollama 上的 deepseek-coder 标签实际是 约 776MB 的小体量版本，并不是原版的 6.7B。算力允许的话，换成 qwen2.5-coder:7b 效果会明显更好。

Q：响应慢怎么办？ 换更小的模型（qwen2.5-coder:1.5b）、缩小单次重构范围、或确认本机没有其他任务在抢 GPU。用托管版也能绕开本地算力限制。

贡献

欢迎 Issue 和 PR。特别需要这些方向的帮助：

• 新的重构模式 —— 你反复手动做的事，可能就是下一个内置能力

• 语言适配 —— 目前对 Kotlin、Swift、PHP 的支持还比较弱

• 测试用例 —— 尤其是"重构后行为保持一致"的验证用例

提 PR 前请确认：代码有中文注释、不含硬编码密钥、通过现有测试。

许可证

MIT —— 可自由商用、修改、分发。

如果这个项目帮你省下了清理遗留代码的时间，给个 ⭐ 是最好的鼓励。

赞助这个项目 · 提交 Issue