{"id":"ce4fb12f-2a0e-47f9-bb8a-f6e4c80abea8","slug":"code-refactor","kind":"mcp","name":"code-refactor","summary":"代码重构助手：把遗留代码重构为现代规范代码，保持原有接口与行为不变","owner":"zhouhengchang","repoUrl":"https://github.com/zhouhengchang/code-refactor","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-14T14:17:24.000Z","addedAt":"2026-10-18T06:23:55.689Z","logoUrl":"https://avatars.githubusercontent.com/u/271419959?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T05:30:46.435Z","sample":false,"url":"https://conduits.dev/tools/code-refactor","language":"Python","transports":["stdio"],"install":{"npm":"workbuddy-code-refactor-connector"},"requirements":{"env":[{"name":"REFACTOR_BACKEND","secret":false,"required":false,"description":"Inference backend: 'ollama' (local, code stays on your machine, default) or 'openai' (any OpenAI-compatible cloud endpoint, e.g. DeepSeek)."},{"name":"OPENAI_BASE_URL","secret":false,"required":false,"description":"Base URL of the OpenAI-compatible endpoint, e.g. https://api.deepseek.com/v1. Required when REFACTOR_BACKEND=openai."},{"name":"OPENAI_API_KEY","secret":true,"required":false,"description":"API key for the cloud endpoint, e.g. a DeepSeek key. Only needed when REFACTOR_BACKEND=openai."},{"name":"OPENAI_MODEL","secret":false,"required":false,"description":"Cloud model name, e.g. deepseek-chat."},{"name":"OLLAMA_HOST","secret":false,"required":false,"description":"Ollama server address used when REFACTOR_BACKEND=ollama."},{"name":"OLLAMA_MODEL","secret":false,"required":false,"description":"Ollama model name used when REFACTOR_BACKEND=ollama."},{"name":"REFACTOR_TIMEOUT_MS","secret":false,"required":false,"description":"Per-call timeout in milliseconds. Raise it for slow local CPU inference."}],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\r\n\r\n# 代码重构助手\r\n\r\n**把遗留代码重构为现代规范代码，保持原有接口与行为不变**\r\n\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\r\n[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)\r\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)\r\n[![MCP](https://img.shields.io/badge/MCP-Compatible-6E56CF.svg)](https://modelcontextprotocol.io/)\r\n[![npm](https://img.shields.io/npm/v/workbuddy-code-refactor-connector.svg?logo=npm&color=CB3837)](https://www.npmjs.com/package/workbuddy-code-refactor-connector)\r\n\r\n一个基于本地大模型的代码重构服务。输入一段源代码和一句重构要求，输出重构后的完整代码。\r\n\r\n**代码不离开你的机器** —— 核心版通过本地 Ollama 推理，无任何数据上传。\r\n\r\n[快速开始](#-快速开始) · [功能](#-功能) · [使用方式](#-使用方式) · [定价](#-开源版与托管版) · [贡献](#-贡献)\r\n\r\n</div>\r\n\r\n---\r\n\r\n## 这是什么\r\n\r\n历史项目里总有些代码：能跑，但没人愿意碰。变量叫 `a`、`tmp1`、`data2`，三层嵌套的 `if` 里塞着业务逻辑，同一个校验规则在五个地方各写了一遍。\r\n\r\n这个项目做的就是把这些代码改造好。它**不修复 bug、不添加功能**，只改结构——让代码好读、好改，同时保证外部行为完全不变。\r\n\r\n核心能力由本地 [Ollama](https://ollama.com/) 上的代码模型（默认 `deepseek-coder`）驱动，可以以 **MCP Server**、**HTTP API**、**技能包** 等多种形态接入你现有的工作流。\r\n\r\n## 功能\r\n\r\n| 能力 | 说明 |\r\n|---|---|\r\n| **命名规范化** | 把 `f`、`a`、`tmp1` 改为能表达意图的命名 |\r\n| **重复逻辑提取** | 识别重复代码片段，提取为独立函数或方法 |\r\n| **控制流简化** | 嵌套条件改为提前返回（卫语句），合并冗余分支 |\r\n| **类型标注补充** | 为 Python、TypeScript 补充类型标注 |\r\n| **文档注释生成** | 按语言惯例补充 docstring / JSDoc / Javadoc |\r\n| **语法现代化** | 回调改 `async/await`、`var` 改 `let/const`、循环改推导式 |\r\n\r\n**支持语言**：Python · JavaScript · TypeScript · Java · Go · Rust · C · C++\r\n\r\n### 设计原则\r\n\r\n重构这件事，改坏比不改更糟。所以本项目有两条硬约束：\r\n\r\n1. **不改公共接口** —— 函数名、类名、参数签名、返回值结构保持原样（除非你明确要求改）\r\n2. **保持行为等价** —— 重构后逻辑与原代码一致，不顺手修 bug\r\n\r\n## 快速开始\r\n\r\n### 前置条件\r\n\r\n- Python 3.11+ 或 Node.js 18+\r\n- [Ollama](https://ollama.com/download) 已安装并运行\r\n- 已拉取代码模型：`ollama pull deepseek-coder`\r\n\r\n### 方式一：本地 Python 直接调用\r\n\r\n```bash\r\ngit clone https://github.com/zhouhengchang/code-refactor.git\r\ncd code-refactor\r\npython shared/refactor_core.py   # 内置自测，会先检查服务再跑一个示例\r\n```\r\n\r\n也可以在自己的代码里调用：\r\n\r\n```python\r\n# -*- coding: utf-8 -*-\r\n\"\"\"最小调用示例。\"\"\"\r\n\r\nfrom shared.refactor_core import refactor_code, check_ollama_status\r\n\r\n# 先确认环境就绪\r\nprint(check_ollama_status())\r\n\r\n# 执行重构\r\nresult = refactor_code(\r\n    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\",\r\n    task=\"重命名为有意义的函数名与变量名，补充类型标注与中文注释\",\r\n    language=\"python\",\r\n)\r\n\r\nif result[\"ok\"]:\r\n    print(result[\"code\"])\r\nelse:\r\n    print(\"失败：\", result[\"error\"])\r\n```\r\n\r\n### 方式二：作为 MCP Server 接入（Claude Desktop / WorkBuddy / 任意 MCP 客户端）\r\n\r\n已发布到 npm，**不用克隆仓库**，直接在 MCP 客户端配置里引用：\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"code-refactor\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"workbuddy-code-refactor-connector\"],\r\n      \"env\": {\r\n        \"REFACTOR_BACKEND\": \"ollama\",\r\n        \"OLLAMA_HOST\": \"http://localhost:11434\",\r\n        \"OLLAMA_MODEL\": \"deepseek-coder\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n> npm 包：[workbuddy-code-refactor-connector](https://www.npmjs.com/package/workbuddy-code-refactor-connector)\r\n\r\n也可以从源码运行，便于自己改代码：\r\n\r\n```bash\r\ncd workbuddy-connector/server\r\nnpm install\r\n```\r\n\r\n然后把上面的 `command` 改成 `node`，`args` 改成 `[\"/绝对路径/to/workbuddy-connector/server/index.js\"]` 即可。\r\n\r\n重启客户端后即可使用 `refactor_code` 和 `check_status` 两个工具。\r\n\r\n### 方式三：Docker 部署 HTTP 服务\r\n\r\n```bash\r\ndocker build -t code-refactor-xpack:1.0.0 -f xpack-server/Dockerfile .\r\ndocker run -p 8000:8000 \\\r\n  -e OLLAMA_HOST=http://host.docker.internal:11434 \\\r\n  -e OLLAMA_MODEL=deepseek-coder \\\r\n  code-refactor-xpack:1.0.0\r\n```\r\n\r\n调用：\r\n\r\n```bash\r\ncurl -X POST http://localhost:8000/refactor \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\r\n    \"code\": \"def f(a):\\n    return [i*i for i in a if i % 2 == 0]\\n\",\r\n    \"task\": \"函数名与变量名改为有意义的命名，补充类型标注\",\r\n    \"language\": \"python\"\r\n  }'\r\n```\r\n\r\n## 使用方式\r\n\r\n### 输入\r\n\r\n| 参数 | 必填 | 说明 |\r\n|---|---|---|\r\n| `code` | 是 | 待重构代码，≤ 20000 字符 |\r\n| `task` | 是 | 重构要求，越具体效果越好 |\r\n| `language` | 否 | 语言标识，不填自动判断 |\r\n\r\n### 输出\r\n\r\n```json\r\n{\r\n  \"ok\": true,\r\n  \"code\": \"重构后的完整代码\",\r\n  \"model\": \"deepseek-coder\",\r\n  \"language\": \"python\",\r\n  \"elapsed_ms\": 3820\r\n}\r\n```\r\n\r\n失败时返回 `{\"ok\": false, \"error\": \"可读中文错误信息\", \"error_type\": \"...\"}`，**不抛异常、不暴露堆栈**。\r\n\r\n### `task` 怎么写\r\n\r\n这是影响结果质量最大的一个变量。\r\n\r\n| 别这样写 | 换成这样 |\r\n|---|---|\r\n| 「优化一下」 | 「把五层嵌套 if 改为提前返回，提取重复的参数校验为独立函数」 |\r\n| 「太乱了」 | 「统一命名规范，拆分超过 50 行的函数，补充中文注释」 |\r\n| 「改写好点」 | 「把回调写法改为 async/await，保留原有的错误处理分支」 |\r\n\r\n### 使用建议\r\n\r\n- **一次一个目标。** 「重构 + 加功能」拆成两步做。\r\n- **长代码分批。** 单次 ≤ 300 行为宜，按函数粒度提交。\r\n- **结果先验证再应用。** 跑一遍现有测试再替换生产代码。\r\n\r\n## 配置\r\n\r\n全部通过环境变量注入，**代码中不含任何密钥**。\r\n\r\n| 环境变量 | 默认值 | 说明 |\r\n|---|---|---|\r\n| `REFACTOR_BACKEND` | `ollama` | 推理后端：`ollama`（本地）或 `openai`（任意 OpenAI 兼容接口） |\r\n| `OLLAMA_HOST` | `http://127.0.0.1:11434` | Ollama 服务地址 |\r\n| `OLLAMA_MODEL` | `deepseek-coder` | 本地模型 |\r\n| `OPENAI_BASE_URL` | `https://api.deepseek.com/v1` | 云端接口地址（`REFACTOR_BACKEND=openai` 时生效） |\r\n| `OPENAI_API_KEY` | — | 云端密钥，**仅从环境变量读取，永不写进代码** |\r\n| `OPENAI_MODEL` | `deepseek-flash` | 云端模型（DeepSeek 官方在列：`deepseek-flash` / `deepseek-v4-pro`） |\r\n| `REFACTOR_TIMEOUT` | `180` | 超时秒数（Python） |\r\n| `REFACTOR_TIMEOUT_MS` | `180000` | 超时毫秒数（Node.js） |\r\n\r\n本地和云端两套后端**同一份代码**，切换只改环境变量：\r\n\r\n```bash\r\n# 改用云端 OpenAI 兼容接口\r\nexport REFACTOR_BACKEND=openai\r\nexport OPENAI_API_KEY=sk-xxxx\r\n```\r\n\r\n> 超时默认给到 180 秒，是因为在纯 CPU 的低配机器上本地推理可能需要 1 分钟以上。如果你的机器有 GPU，可以调小。\r\n\r\n想用更小更快的本地模型：`OLLAMA_MODEL=qwen2.5-coder:1.5b`。\r\n\r\n## 运维工具\r\n\r\n`tools/` 下有两个自检脚本，改完配置或轮换密钥后建议跑一遍，避免\"改完才发现用不了\"：\r\n\r\n| 脚本 | 作用 |\r\n|---|---|\r\n| `tools/rotate_key.py` | 密钥轮换：先校验**鉴权 / 余额 / 真实调用**三关，全过才允许写入；替换前自动备份，可一键回滚 |\r\n| `tools/verify_online.py` | 线上体检：依次请求 `/healthz`、`/status`、`/refactor`，确认新配置在生产环境真正生效 |\r\n\r\n```bash\r\n# 只验证，不改任何文件\r\npython tools/rotate_key.py --check --key sk-xxxx\r\n\r\n# 验证通过后写入 .env\r\npython tools/rotate_key.py --apply --key sk-xxxx\r\n\r\n# 线上实例体检\r\npython tools/verify_online.py https://your-host/\r\n```\r\n\r\n> `rotate_key.py` 只改 `.env` 里 `OPENAI_API_KEY` 一行，其余配置原样保留。\r\n\r\n## 项目结构\r\n\r\n```\r\ncode-refactor/\r\n├── shared/refactor_core.py      # 核心逻辑（唯一真源）\r\n├── workbuddy-connector/         # WorkBuddy / MCP 连接器\r\n├── xpack-server/                # OpenAPI + FastAPI + Dockerfile\r\n├── coze-skill/                  # 扣子技能包\r\n├── skillhub-skill/              # SkillHub Pay Skill\r\n├── alipay-ai/                   # 支付宝 AI收 接入配置\r\n├── xinghuo-agent/               # 讯飞星火智能体配置\r\n├── tools/                       # 密钥轮换与线上体检脚本\r\n└── github-repo/                 # 本文档所在的开源仓库\r\n```\r\n\r\n## 开源版与托管版\r\n\r\n本项目采用 **Freemium** 模式：核心能力完全开源免费，托管服务面向不想自己部署的用户。\r\n\r\n| | **开源版（MIT）** | **托管版 Pro** |\r\n|---|---|---|\r\n| 价格 | 免费 | ¥29/月（含 200 次调用）<br>或 ¥1/次按需付费 |\r\n| 部署 | 自己部署 Ollama | 无需部署，开箱即用 |\r\n| 模型 | 你自己选的模型 | 更大的代码模型，效果更好 |\r\n| 速度 | 取决于你的硬件 | GPU 加速，平均 3-5 秒响应 |\r\n| 语言支持 | 8 种 | 8 种 + 优先级支持 |\r\n| 批量重构 | 需自行封装 | 支持仓库级批量重构 |\r\n| 私有部署 | — | 支持 |\r\n| 支持 | 社区 Issue | 优先工单响应 |\r\n\r\n**该选哪个？**\r\n\r\n- 代码不能出内网 / 想完全掌控 → **开源版**，直接克隆部署\r\n- 本机没有 GPU、不想折腾环境、需要更好的重构质量 → **托管版**\r\n\r\n👉 **托管版入口：** <https://code-refactor.app.workbuddy.host>\r\n\r\n> 托管版同样承诺：**代码仅用于本次推理，不留存、不用于模型训练。**\r\n\r\n## 在各大平台使用\r\n\r\n本服务已适配以下平台，可按需取用对应目录下的配置文件：\r\n\r\n| 平台 | 形态 | 配置 / 入口 |\r\n|---|---|---|\r\n| **npm** | 可执行 MCP Server（已上线） | `npx -y workbuddy-code-refactor-connector` |\r\n| WorkBuddy 开放平台 | Connector / MCP Server | `workbuddy-connector/` |\r\n| XPack MCP 交易平台 | OpenAPI → MCP 服务 | `xpack-server/openapi.json` |\r\n| 扣子（Coze） | 技能商店 Skill | `coze-skill/skill.json` |\r\n| SkillHub | Pay Skill | `skillhub-skill/manifest.json` |\r\n| 支付宝 AI收 | 按调用即时收款 | `alipay-ai/alipay-ai-config.json` |\r\n| 讯飞星火 | 智能体 / 独立 API | `xinghuo-agent/agent-config.json` |\r\n\r\n## 常见问题\r\n\r\n**Q：为什么非要本地跑？云端 API 不是更方便？**\r\n代码是核心资产。本地推理意味着你的代码一个字节都不会离开你的机器——这对企业代码库往往是硬性要求。想省事就用托管版。\r\n\r\n**Q：重构会不会改坏我的代码？**\r\n设计上不会改变外部行为，但这不构成保证。**上生产前请务必跑测试。** 项目的第一原则就是\"不改接口、不改行为\"，但模型输出总有不确定性，代码审查不可省。\r\n\r\n**Q：支持多大的代码？**\r\n单次 20000 字符以内，建议 300 行以内。更大的文件按函数拆分。\r\n\r\n**Q：能只重构一个函数吗？**\r\n可以，只把那个函数贴进来就行。\r\n\r\n**Q：为什么用 `deepseek-coder`？**\r\n在代码任务上表现稳定，是本地小体量模型里性价比较好的选择。你可以通过 `OLLAMA_MODEL` 换成任何 Ollama 模型。\r\n\r\n> 注意：Ollama 上的 `deepseek-coder` 标签实际是 **约 776MB 的小体量版本**，并不是原版的 6.7B。算力允许的话，换成 `qwen2.5-coder:7b` 效果会明显更好。\r\n\r\n**Q：响应慢怎么办？**\r\n换更小的模型（`qwen2.5-coder:1.5b`）、缩小单次重构范围、或确认本机没有其他任务在抢 GPU。用托管版也能绕开本地算力限制。\r\n\r\n## 贡献\r\n\r\n欢迎 Issue 和 PR。特别需要这些方向的帮助：\r\n\r\n- **新的重构模式** —— 你反复手动做的事，可能就是下一个内置能力\r\n- **语言适配** —— 目前对 Kotlin、Swift、PHP 的支持还比较弱\r\n- **测试用例** —— 尤其是\"重构后行为保持一致\"的验证用例\r\n\r\n提 PR 前请确认：代码有中文注释、不含硬编码密钥、通过现有测试。\r\n\r\n## 许可证\r\n\r\n[MIT](LICENSE) —— 可自由商用、修改、分发。\r\n\r\n---\r\n\r\n<div align=\"center\">\r\n\r\n**如果这个项目帮你省下了清理遗留代码的时间，给个 ⭐ 是最好的鼓励。**\r\n\r\n[赞助这个项目](https://github.com/sponsors/zhouhengchang) · [提交 Issue](https://github.com/zhouhengchang/code-refactor/issues)\r\n\r\n</div>\r\n"}