【无标题】

南工gjl

391人浏览 · 2026-06-09 16:09:46

南工gjl · 2026-06-09 16:09:46 发布

CodePartner：用本地模型 + ReAct Agent 搭建自己的 VSCode AI 编程助手

本文作者：jialinguo
项目已开源：https://github.com/gjl-0810/code-partner-expand
VSCode 扩展：marketplace.visualstudio.com/items?itemName=jialinguo.codepartner
适合人群：AI Agent 学习者、本地大模型爱好者、注重代码隐私的开发者

一、为什么要做一个「本地」AI 编程助手？

2024 年以来，GitHub Copilot、Cursor、CodeBuddy 等 AI 编程工具快速普及。但它们有一个共同前提：你的代码必须发送到云端。

对于很多场景，这是不可接受的：

企业内部代码，有合规要求，不能出内网
个人学习项目，不想把自己的代码训练进大厂模型
断网环境（飞机、内网开发机），完全无法使用

于是问题来了：能不能在本地，用自己部署的模型，跑一个真正能「动手改代码」的 AI Agent？

这就是 CodePartner 的出发点。

二、和现有免费插件的核心区别

很多读者会问：「VSCode 上已经有 Cline、Continue、Roo-Cline 了，为什么还要做 CodePartner？」

一句话总结：CodePartner 是「教学级开源实现」，而 Cline/Continue 是「产品级黑盒」。

维度	Cline / Continue / Roo	CodePartner
运行方式	云端 API（需 API Key / 付费）	纯本地 Ollama（零费用）
代码是否出网	是（发到 Anthropic/OpenAI）	否（模型在本地跑）
架构是否开源	前端开源，Agent 逻辑封装	全栈开源（TS 插件 + Python 后端 + ReAct 循环）
能改代码吗	能（Cline 最强）	能（write_file + diff 确认）
适合学习 Agent 吗	代码量大、封装深，难啃	刻意简化，2000 行核心逻辑，适合跟着读
模型要求	需要强模型（Claude/GPT-4）	9B 小模型可跑（qwen3.5:9b）

一句话区别：Cline 是「你用它的产品」，CodePartner 是「你学它的实现」。

三、CodePartner 做了什么？

3.1 架构：前端插件 + 本地后端 + Ollama

┌─────────────────┐     HTTP/SSE     ┌──────────────────┐     OpenAI API     ┌──────────────┐
│  VSCode 插件     │ ──────────────▶ │  Python FastAPI   │ ──────────────▶ │  Ollama       │
│  (TypeScript)   │                  │  (Agent 核心)     │                  │  (qwen3.5:9b)│
│                 │ ◀────────────── │                   │ ◀────────────── │              │
│  Chat Webview   │    SSE 流式回复  │  ReAct 循环       │   本地推理        │  100% 离线    │
└─────────────────┘                  └──────────────────┘                  └──────────────┘

关键设计决策：

插件不直连 Ollama，而是连本地 FastAPI 后端（端口 8765）
后端负责：ReAct 循环、工具调用、SSE 流式输出
这样做的好处：Agent 逻辑完全在 Python 里，方便你改（不用碰 TypeScript）

3.2 ReAct Agent：让模型「先想再干」

CodePartner 的核心是一个 ReAct（Reasoning + Acting）循环，代码在 server/agent_wrapper.py。

什么是 ReAct？
简单说：不让模型直接输出答案，而是让它交替进行「思考 → 调工具 → 看结果 → 再思考」，直到任务完成。

用户提问
   │
   ▼
[Thought] 我需要先搜索代码，了解项目结构
   │
   ▼
[Action] workspace_search("ReAct")
   │
   ▼
[Observation] 找到 7 个文件...
   │
   ▼
[Thought] 现在我理解了，可以写代码了
   │
   ▼
[Action] write_file("xxx.py", "...")
   │
   ▼
[Observation] 文件已写入
   │
   ▼
[Final Answer] 任务完成，我帮你创建了...

CodePartner 的 ReAct 实现细节（适合学习）：

最大步数可配（agent.maxSteps，默认 8 步）
每步超时保护（防止模型死循环）
工具调用结果通过 SSE 实时推送到前端（用户能看到「工具正在运行」）
完成度自动判定：如果模型「该写代码却只输出计划」，自动重组 prompt 续跑（最多 2 轮）

3.3 三种对话模式

CodePartner 提供三种模式，对应不同使用场景：

模式	说明	适用场景
Craft	全自动 ReAct，模型可自由调工具	让 AI 帮你改代码、写功能
Ask	禁用所有工具，纯问答	问概念、让 AI 解释代码
Plan	先让模型输出 markdown 计划，你确认后再执行	大改动，想先看方案

Plan 模式的交互流程（这是 CodePartner 的特色）：

你：帮我重构这个函数的错误处理

[Plan 模式]
模型输出：
## 重构计划
1. 把 try/except 改成 Result 类型
2. 新增 error_types.py
3. ...

[你点「确认执行」]
→ 模型才开始真正改代码

3.4 工具箱：模型能「动手」做什么？

CodePartner 给模型配备了 6 个工具（代码在 server/tools/）：

工具	功能	安全边界
`workspace_search`	ripgrep 搜代码（无 ripgrep 降级 Python）	仅搜索，不改文件
`read_file`	读文件（支持行号范围）	路径越界拦截
`list_directory`	列目录	仅列表
`write_file`	写文件	落盘前 diff 预览 + 用户确认
`web_search`	DuckDuckGo 搜文档	无需 API Key
`find_symbol` / `find_references` / `outline`	代码理解三件套	不依赖 LSP

write_file 的安全设计（这是重点）：

模型调用 write_file 后，不立刻落盘
插件用 vscode.diff 展示红绿对比预览
弹窗让用户确认（「应用」/「拒绝」/「修改」）
用户点确认后，才真正写入磁盘

3.5 Memory 管理：让 Agent 记住「你是谁」

CodePartner 的 Memory 系统分两层：

第一层：会话级 Memory（workspaceState）

每个 VSCode 工作区独立的会话列表
会话内容存在 workspaceState 里，关闭 VSCode 不丢失
支持多会话隔离 + 重命名

第二层：Skill Memory（.codepartner/skills.json）

你可以把「常用操作流程」写成 Skill（Markdown 文件）
模型通过 find_skill 工具按需加载 Skill
相当于给 Agent 配了一个「操作手册知识库」

为什么这样设计？
Agent 的 Memory 不在于「记住所有对话」，而在于**「在需要时找到正确的知识」**。Skill 系统就是这个思路的工程实现。

四、快速上手

4.1 前置条件

软件	版本	说明
Ollama	latest	https://ollama.com/download
Python	3.10+	后端运行环境
Node.js	18+	VSCode 插件要求
VSCode	1.85+	插件运行环境

⚠️ 本插件完全依赖本地 Ollama，安装后必须先执行：

ollama pull qwen3.5:9b   # 约 5.5GB，首次下载需等待
ollama serve               # 启动 Ollama 服务（默认 11434 端口）

4.2 安装 CodePartner

方式一：VSCode 扩展市场（推荐）

在 VSCode 扩展面板搜索 "CodePartner"
或访问：https://marketplace.visualstudio.com/items?itemName=jialinguo.codepartner

方式二：下载 .vsix 手动安装

git clone https://github.com/gjl-0810/code-partner-expand.git
cd codepartner/extension
npm install
npm run package        # 生成 codepartner-0.2.1.vsix
code --install-extension codepartner-0.2.1.vsix

4.3 启动后端

cd codepartner
./scripts/start.sh
# 等待输出：Application startup complete

# 验证
curl http://127.0.0.1:8765/health
# 预期返回：{"status":"ok","model":"qwen3.5:9b"}

4.4 开始使用

打开 VSCode，左侧活动栏会出现 CodePartner 图标（</>）
点击打开 Chat 面板
顶部下拉菜单选择模型（自动检测本地 Ollama 模型）
开始对话！

五、适合学习的代码模块

如果你想通过 CodePartner 学习 AI Agent 搭建，建议按这个顺序读代码：

5.1 前端（TypeScript，~3000 行）

文件	学什么
`extension/src/chatPanel.ts`	VSCode Webview 通信、SSE 流式渲染
`extension/src/apiClient.ts`	前端如何调本地后端 API
`extension/src/extension.ts`	VSCode 插件入口、命令注册

5.2 后端（Python，~2000 行）

文件	学什么
`server/agent_wrapper.py`	ReAct 循环核心（最重要！）
`server/tools/workspace_search.py`	工具实现范例
`server/tools/write_file.py`	带确认的工具实现
`server/config.yaml`	系统提示词、工具描述配置

5.3 配置文件（直接可改）

文件	改什么
`server/config.yaml`	改 system prompt、工具列表、模型参数
`extension/package.json`	改插件配置项（Settings 里出现）

六、和 Cline 的技术对比（深入）

很多人问我：「CodePartner 和 Cline 技术上差在哪？」

6.1 模型要求

	Cline	CodePartner
推荐模型	Claude 3.5 Sonnet（~200B）	qwen3.5:9b（9B）
最低可跑	70B+ 量化	7B 可跑（质量下降）
本地运行	需要 80GB+ 显存	16GB 内存可跑

结论：CodePartner 牺牲了「模型能力上限」，换来了「本地可跑」。

6.2 Agent 循环实现

Cline 的做法：

TypeScript 实现，~2 万行
高度封装，工具调用、上下文管理、token 预算管理全在 TS 里
优点：产品体验好，错误处理完善
缺点：想学 Agent 原理？先啃 2 万行 TS

CodePartner 的做法：

Python 实现，~2000 行（核心循环 ~500 行）
ReAct 循环裸写，没有框架封装
优点：2000 行就能跑通 ReAct，适合学习
缺点：边界 case 处理不如 Cline 完善

6.3 工具系统

	Cline	CodePartner
工具数量	30+	6
工具实现	TS + 高度抽象	Python + 直白实现
新增工具	需懂 Cline 架构	改 `config.yaml` + 写个 Python 函数

如果你想自己加工具，CodePartner 的 server/tools/ 目录是最好的起点。

七、已知限制 & 后续规划

7.1 当前限制（诚实说）

模型能力上限：9B 模型 vs Claude，差距明显。复杂重构任务容易失败。
首次响应慢：qwen3.5:9b 冷启动需 30~60 秒，建议先 ollama run qwen3.5:9b 预热。
MCP 未接入：配置 UI 已做好，但还没真正连接 MCP server（规划中）。
行内补全质量一般：9B 非 FIM 模型，默认关闭，建议换 qwen2.5-coder:7b。

7.2 后续规划（按优先级）

⏳ 接入 RAG（已有引擎，待集成）
⏳ 真正接入 MCP（让模型能调 MCP tools）
⏳ 换更强代码模型（qwen2.5-coder:14b 或等待 qwen3.5:32b）
⏳ 多模型路由（简单任务用小模型，复杂任务自动切大模型）

八、总结

CodePartner 不是一个「更好的 Copilot」，它是一个教学项目 + 可用工具。

如果你是想学 AI Agent 的开发者：

把代码 clone 下来，跟着 server/agent_wrapper.py 读一遍
改 config.yaml 里的 system prompt，观察模型行为变化
加一个新工具（比如 run_shell_command），体会 Agent 工具设计的取舍

如果你是需要本地 AI 助手的开发者：

装好 Ollama + qwen3.5:9b，直接能用
代码不出网，适合敏感项目
零月费，模型自己管

九、链接 & 资源

GitHub 仓库：https://github.com/gjl-0810/code-partner-expand（MIT 开源）
VSCode 扩展：https://marketplace.visualstudio.com/items?itemName=jialinguo.codepartner
问题反馈：GitHub Issues
作者微信/联系方式：（可选填）

如果你觉得这个项目有帮助，欢迎 Star ⭐、转发、提 Issue。每一个反馈都是继续迭代的动力。