1. 项目概述从“Claude Code”到“TodoWrite”的平民化实践最近在开发者社区里“Claude Code”这个词的热度居高不下。无论是搜索“claude code安装教程”还是遇到“npm install -g pnpm read econnreset”这类网络问题都反映出大家对这个工具的浓厚兴趣。但说实话当我第一次看到“Claude Code 源码普通工具实现 Read / Write / Edit / TodoWrite”这个标题时我的第一反应是困惑。Claude Code本身是Anthropic推出的AI编程助手通常以插件形式集成在VSCode等IDE中它本身并不是一个开源项目何来“源码”一说更别提用“普通工具”去实现它的核心功能了。深入思考后我明白了这个标题背后的真正诉求。它指向的并非去逆向工程某个商业产品而是一个更具普适性的命题我们能否利用市面上成熟、易得甚至免费的开源组件和AI模型自己动手搭建一套具备“读、写、编辑、任务驱动写作”能力的智能编码辅助系统这本质上是对当前AI编码工具“黑盒化”和“服务依赖”现状的一种技术反思和DIY挑战。用户想要的不是某个特定产品的复制品而是一个可理解、可控制、可定制的解决方案蓝图。因此本文我将彻底抛开对特定商业产品的依赖聚焦于“Read / Write / Edit / TodoWrite”这四个核心能力为你拆解如何用“普通工具”——即广泛可得的编程库、开源模型和标准协议——来构建属于你自己的智能编码伴侣。无论你是想深入理解AI编程助手的原理还是希望有一个完全受控、能嵌入私有工作流的编码工具这篇文章都将提供从设计思路到代码实现的完整路径。2. 核心能力拆解什么是真正的 Read / Write / Edit / TodoWrite在开始动手之前我们必须清晰定义目标。一个智能编码系统的四大核心能力远不止字面意思那么简单。2.1 Read超越语法高亮的深度代码理解“读”代码对于传统IDE来说意味着词法分析、语法高亮和简单的跳转。但对于我们的系统“Read”意味着语义理解。代码解析与抽象语法树AST这是所有高级操作的基础。我们需要将源代码文本转化为结构化的树形表示。对于JavaScript/TypeScriptbabel/parser或typescript编译器自带的AST生成器是首选对于Pythonast标准库是核心对于Java可以考虑JavaParser。这一步让我们能精确知道哪里是函数声明、哪里是变量、哪里是条件判断。上下文感知“读”不能只读当前文件。一个高效的助手必须能理解项目的上下文。这包括跨文件引用分析通过解析import/require语句构建项目内的依赖图。类型信息推断对于动态语言如Python、JavaScript需要结合类型注解如TypeScript的类型定义、Python的type hints或通过静态分析工具如pyright、tsserver来获取更丰富的语义信息。项目结构理解识别package.json、pyproject.toml、CMakeLists.txt等配置文件理解项目的构建方式、依赖关系和技术栈。实操心得AST的解析是资源密集型操作。对于大型项目全量解析所有文件是不现实的。一个实用的策略是惰性解析和缓存。只有当用户聚焦或编辑某个文件时才深度解析该文件及其直接依赖。可以将AST序列化后缓存到内存或磁盘避免重复解析。2.2 Write Edit从补全到重构的智能代码生成“写”和“编辑”是紧密耦合的能力通常由AI模型驱动但需要精密的工程将其与“读”的能力结合。智能补全Intelligent Completion这不仅仅是基于当前词条的补全。它需要结合局部上下文当前光标所在的行、函数、类。全局上下文当前文件的导入、同文件的其他函数、项目中的常见模式。AI模型预测基于上述上下文让模型预测最可能的下一个token或代码块。代码编辑指令Edit Instructions这是“Edit”能力的核心。用户可能说“把这个函数改成异步的”或“给这个类添加一个toJSON方法”。系统需要理解自然语言指令将用户的自然语言描述转化为一个或多个具体的代码操作如“插入”、“删除”、“替换”、“重构”。精确定位编辑范围结合AST精确找到需要修改的代码节点如函数体、参数列表。生成并应用代码差异Diff生成符合项目编码风格的代码更改并以非破坏性的方式如生成补丁应用到源代码中最好能提供预览。2.3 TodoWrite任务驱动的自动化代码编写这是最高阶的能力也是区分普通补全和“智能助手”的关键。TodoWrite指的是根据一个高层次的任务描述如“创建一个用户登录的REST API端点”自动完成从文件创建、代码骨架生成、依赖安装到单元测试草稿的一系列操作。任务分解Task Decomposition将模糊的用户需求拆解为具体的、可执行的子任务。例如“创建登录API”可以分解为在routes/目录下创建auth.py文件。定义POST /api/auth/login端点。实现请求体验证用户名、密码。编写用户查询和密码验证逻辑。生成JWT令牌并返回。在__init__.py中注册路由。多步骤执行与状态管理系统需要按顺序或并行执行这些子任务并管理执行状态。如果某一步失败如依赖冲突需要能够回滚或提供解决方案。与开发环境深度集成TodoWrite可能涉及运行终端命令npm install、pip install、创建新文件、修改配置文件等。这要求我们的系统不能只是一个被动的代码建议器而需要具备一定的“执行权”在用户确认下。3. 技术栈选型用“普通工具”搭建智能内核明确了目标我们来选择实现这些能力的“普通工具”。我们的原则是优先选择开源、文档完善、社区活跃的组件。3.1 语言服务器协议实现“Read”能力的基石要实现深度的代码理解重新发明轮子是不明智的。语言服务器协议Language Server Protocol, LSP是微软制定的开放协议它定义了编辑器和语言服务器之间通信的标准。我们可以直接利用现有的、强大的语言服务器。为什么选择LSP标准化一套接口支持所有实现了LSP的编辑器VSCode, Vim, Emacs等。功能强大现有的语言服务器如tsserverfor JS/TS,pylspfor Python,rust-analyzerfor Rust已经实现了跳转定义、查找引用、悬停提示、代码诊断等复杂的“Read”功能。可嵌入我们可以以客户端的形式连接这些服务器获取结构化的代码信息而无需自己实现复杂的解析器。核心工具vscode-languageserver-node如果你想用Node.js构建自己的LSP客户端或服务器这是官方库。pygls用Python构建语言服务器的绝佳框架。lsp4jJava生态的LSP实现。直接连接更简单的方式是在你的工具中启动一个子进程运行现有的语言服务器如pylsp并通过标准输入输出stdio与其进行JSON-RPC通信。3.2 AI模型层驱动“Write/Edit/TodoWrite”的大脑这是系统的智能核心。我们不需要训练自己的大模型而是通过API或本地部署来利用现有模型。云端API方案快速启动OpenAI API (GPT-4, GPT-3.5-Turbo)代码生成能力强大响应速度快但需要网络且产生持续费用。Anthropic API (Claude 3系列)在长上下文和逻辑推理上表现优异同样需要网络和付费。国内可选API如DeepSeek、通义千问等提供了具有竞争力的代码生成能力访问延迟可能更低。集成方式使用对应的官方SDK如openai,anthropic或通用的HTTP客户端封装请求。关键在于设计高效的提示词Prompt将我们从LSP获取的代码上下文有效地传递给模型。本地模型方案完全可控、离线模型选择这是当前的热点。可以选择参数较小的优秀代码模型在本地运行。DeepSeek-Coder系列模型如6.7B, 33B在代码生成上表现非常出色对硬件要求相对友好。CodeLlamaMeta发布的专注于代码的Llama变体。Qwen-Coder通义千问的代码模型同样表现不俗。推理框架Ollama最简单的方式。它提供了模型管理、拉取和运行的一体化体验通过简单的REST API即可调用。ollama run deepseek-coder:6.7b就能跑起来。LM Studio图形化界面适合桌面端快速测试和体验不同模型。vLLM / llama.cpp如果你追求极致的推理性能和高吞吐量用于生产环境这些是更专业的选择。llama.cpp对CPU推理优化极好。硬件考量运行6B-7B参数的模型16GB内存的MacBook Pro或配备16GB以上RAM的PC通常可以胜任。对于33B模型则需要更大的内存或使用GPU加速。注意事项选择本地模型时务必在 Hugging Face 或模型发布方官网仔细查看模型的许可证License。商用项目要选择允许商用的许可证如Apache 2.0, MIT。同时关注模型的上下文长度Context Length这决定了它能“看到”多长的代码。3.3 胶水层与工程框架将一切连接起来我们需要一个主程序来协调LSP客户端、AI模型和编辑器/用户界面。后端框架可选如果你的工具是一个独立的桌面应用或后台服务。Node.js Express/Fastify适合构建提供WebSocket或HTTP API的服务端方便与多种前端集成。Python FastAPI/Flask在AI和数据处理生态上有天然优势与pygls和本地模型结合更紧密。进程间通信IPC这是关键。标准输入输出stdio与语言服务器通信的标准方式。WebSocket实现前端如Web IDE与后端服务的实时双向通信用于传递代码变更和接收AI建议。消息队列如ZeroMQ在复杂的微服务架构中用于解耦各个组件如解析服务、AI推理服务。前端/编辑器集成VSCode Extension最直接的集成方式。你可以开发一个VSCode插件在插件中嵌入你的LSP客户端和AI调用逻辑。Web IDE基于Monaco EditorVSCode的网页版核心或CodeMirror构建自己的在线编辑器通过WebSocket与后端服务通信。独立桌面应用使用Electron或Tauri打包你的Web技术栈应用提供原生体验。4. 系统架构设计与核心流程基于以上选型我们可以勾勒出一个可行的系统架构。[用户界面] (VSCode插件 / Web编辑器 / 独立App) | | (发送代码变更、用户指令) v [核心协调服务] (Node.js/Python 主进程) | | | (通过LSP协议获取代码上下文) | (构造Prompt调用AI) v v [语言服务器进程] [AI模型服务] (pylsp, tsserver等) (本地Ollama / 云端API) | | | (返回AST、符号信息) | (返回代码补全/编辑建议) v v [核心协调服务] --(融合上下文与AI建议)-- | | (返回格式化后的建议或执行编辑) v [用户界面] (显示建议应用更改)4.1 核心工作流程一次智能补全的诞生让我们跟踪一次“智能函数补全”的请求看看数据如何在系统中流动事件触发用户在编辑器中输入了function calculateTotal(并停顿了约500毫秒。上下文收集核心服务监听到这个事件。它立即通过LSP客户端向语言服务器发起一系列请求获取文档符号Document Symbols了解当前文件有哪些类、函数、变量。获取光标位置上下文获取光标所在位置的语法节点信息例如正在一个函数声明内部。获取相关代码段获取当前函数所在类或模块的代码以及可能被导入的相关类型定义。Prompt工程核心服务将收集到的结构化上下文按照预定模板组装成给AI模型的Prompt。一个简单的模板可能是// 你是一个专业的代码助手。请根据以下上下文补全代码。 // 当前文件路径/src/utils/math.js // 光标前的代码 function calculateTotal( // 光标后的代码可能为空 // 当前文件的导入 import { applyTax } from ./tax; // 同文件的其他相关函数 function calculateSubtotal(items) { ... } // 请补全 calculateTotal 函数的参数列表和函数体开始部分。只返回代码。AI推理核心服务将组装好的Prompt通过HTTP请求发送给本地Ollama服务例如http://localhost:11434/api/generate或云端API。结果解析与呈现AI返回items, taxRate) { const subtotal calculateSubtotal(items); return applyTax(subtotal, taxRate); }。核心服务对这个结果进行后处理检查语法是否正确是否符合项目风格如分号使用。最后将补全建议通过编辑器接口如VSCode的CompletionItem返回给前端。用户交互用户看到补全建议按Tab键接受。编辑器将补全的文本插入到光标位置。4.2 实现“Edit”指令代码编辑的精准手术“Edit”比补全更复杂因为它需要指定一个编辑范围。我们可以利用LSP的WorkspaceEdit概念。指令解析用户输入自然语言指令“将函数calculateTotal改为异步”。定位目标核心服务通过LSP的“查找定义”功能精确定位到calculateTotal函数在源代码中的位置文件路径、起始行/列、结束行/列。构造增量编辑核心服务分析该函数的AST判断它是一个普通函数声明。然后构造编辑指令在function关键字前添加async。如果函数体内有return语句可能需要将其改为return await ...这需要更复杂的AST分析或交给AI判断。生成AI Prompt将“原始代码”和“编辑意图”发给AI让AI生成编辑后的代码块。Prompt示例原始代码 function calculateTotal(items, taxRate) { const subtotal calculateSubtotal(items); return applyTax(subtotal, taxRate); } 请将上述函数改为异步函数。只返回修改后的完整函数代码。计算差异与应用比较AI返回的新代码和原始代码计算出具体的文本差异可以使用diff算法库如jsdiff。然后通过LSP的ApplyEdit请求或直接操作编辑器文档应用这个差异。务必提供预览让用户确认后再应用。4.3 实现“TodoWrite”编排多步骤的自动化这是最复杂的流程需要状态机和任务队列。任务解析与规划用户输入“为产品模型添加CRUD API端点”。AI规划阶段将此任务发送给一个具有长上下文和强规划能力的AI模型如Claude 3 Sonnet或本地部署的DeepSeek要求它输出一个详细的、步骤化的JSON计划。{ task: 创建产品CRUD API, steps: [ { id: 1, action: create_file, path: src/routes/products.py, description: 创建产品路由文件, depends_on: [] }, { id: 2, action: write_code, file: src/routes/products.py, description: 定义GET /api/products 端点, depends_on: [1] }, { id: 3, action: run_command, command: pip install pydantic, description: 确保数据验证库已安装, depends_on: [] } // ... 更多步骤 ] }步骤执行器核心服务有一个步骤执行器它按顺序处理依赖关系执行每个步骤。create_file调用文件系统API。write_code调用前文所述的“Edit”能力在指定文件写入代码。run_command在子进程中执行shell命令并捕获输出和错误码。状态管理与用户确认每个步骤执行前可以向用户展示即将进行的操作并请求确认“即将创建文件src/routes/products.py是否继续”。执行后记录成功或失败。如果某步失败如命令执行错误可以暂停流程向用户报告错误并提供重试或跳过的选项。结果汇总所有步骤执行完毕后生成一份报告列出创建的文件、修改的代码、运行的命令等。5. 实战构建一个最小可行原型理论说再多不如动手做。让我们用Python和Ollama快速搭建一个具备“Read”和基础“Write”能力的命令行原型。5.1 环境准备与依赖安装首先确保你的系统已经安装了Python 3.8和Ollama。# 1. 安装Ollama (请参考官网 https://ollama.com/) # 对于macOS/Linux: curl -fsSL https://ollama.com/install.sh | sh # 2. 拉取一个代码模型例如DeepSeek Coder 6.7B ollama pull deepseek-coder:6.7b # 3. 创建一个新的Python项目目录并安装依赖 mkdir my-code-helper cd my-code-helper python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install python-lsp-server pylsp-openai openai requests这里我们安装了python-lsp-server即pylsp作为我们的语言服务器pylsp-openai是一个实验性的插件但我们不直接用它而是学习其思路。openai和requests库用于与Ollama的API通信。5.2 实现LSP客户端与代码上下文提取我们将实现一个简化的LSP客户端用于与pylsp通信并获取当前文件的符号信息。# lsp_client.py import subprocess import json import threading import time import sys import os from typing import Dict, Any, List class SimpleLSPClient: def __init__(self, workspace_root: str): self.workspace_root workspace_root self.process None self.seq 0 self.responses {} self.lock threading.Lock() self.connected False def start(self): 启动pylsp语言服务器进程 self.process subprocess.Popen( [pylsp], stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue, bufsize1 ) # 启动读写线程 threading.Thread(targetself._read_stdout, daemonTrue).start() threading.Thread(targetself._read_stderr, daemonTrue).start() self._initialize() def _read_stdout(self): 读取服务器返回的JSON-RPC消息 buffer while True: line self.process.stdout.readline() if not line: break buffer line if buffer.endswith(\r\n\r\n): # 简单的分隔符判断实际LSP消息以Content-Length头分隔 # 这里为简化假设每行是一个完整的JSON try: message json.loads(buffer.strip()) self._handle_message(message) except json.JSONDecodeError: pass buffer def _read_stderr(self): 读取服务器错误输出 for line in iter(self.process.stderr.readline, ): if line: sys.stderr.write(f[LSP Error] {line}) def _handle_message(self, message: Dict[str, Any]): 处理服务器响应 if id in message: with self.lock: self.responses[message[id]] message def _send(self, method: str, params: Dict[str, Any] None) - int: 发送JSON-RPC请求返回请求ID self.seq 1 request { jsonrpc: 2.0, id: self.seq, method: method, params: params or {} } json_str json.dumps(request) content fContent-Length: {len(json_str)}\r\n\r\n{json_str} self.process.stdin.write(content) self.process.stdin.flush() return self.seq def _initialize(self): 发送初始化请求 init_params { processId: os.getpid(), rootUri: ffile://{self.workspace_root}, capabilities: {}, workspaceFolders: [{ uri: ffile://{self.workspace_root}, name: workspace }] } init_id self._send(initialize, init_params) # 等待初始化响应简化处理实际应超时等待 time.sleep(1) self._send(initialized, {}) self.connected True def get_document_symbols(self, file_path: str) - List[Dict]: 获取指定文件的符号函数、类等列表 if not self.connected: return [] uri ffile://{file_path} params {textDocument: {uri: uri}} req_id self._send(textDocument/documentSymbol, params) # 简单等待响应 time.sleep(0.5) with self.lock: response self.responses.pop(req_id, None) if response and result in response: return response[result] return [] def shutdown(self): 关闭连接 self._send(shutdown) self._send(exit) self.process.terminate() # 使用示例 if __name__ __main__: client SimpleLSPClient(os.getcwd()) client.start() time.sleep(2) # 等待初始化完成 symbols client.get_document_symbols(./example.py) print(fFound {len(symbols)} symbols in example.py) for sym in symbols: print(f - {sym.get(name)} ({sym.get(kind)})) client.shutdown()5.3 集成Ollama实现代码补全接下来我们创建一个AI服务类用于与本地运行的Ollama对话。# ai_service.py import requests import json class OllamaCodeAssistant: def __init__(self, model: str deepseek-coder:6.7b, base_url: str http://localhost:11434): self.model model self.base_url base_url self.api_url f{base_url}/api/generate def generate_completion(self, prompt: str, context_code: str ) - str: 向Ollama发送请求生成代码补全 full_prompt self._build_prompt(prompt, context_code) payload { model: self.model, prompt: full_prompt, stream: False, options: { temperature: 0.2, # 低温度生成更确定性的代码 num_predict: 128, # 最大生成token数 } } try: response requests.post(self.api_url, jsonpayload, timeout30) response.raise_for_status() result response.json() return result.get(response, ).strip() except requests.exceptions.RequestException as e: print(f请求Ollama API失败: {e}) return def _build_prompt(self, instruction: str, context: str) - str: 构建给模型的提示词 # 这是一个简单的提示词模板你可以根据模型特性优化 template f你是一个专业的Python代码助手。请根据以下上下文完成指令。 上下文代码{context}指令{instruction} 只返回代码不要有任何解释。 return template # 使用示例补全一个函数 if __name__ __main__: assistant OllamaCodeAssistant() context_code def calculate_area(width, height): \\\计算矩形面积\\\ return width * height def calculate_total( instruction 请补全 calculate_total 函数的参数和函数体开始部分它应该接收一个物品列表和税率。 completion assistant.generate_completion(instruction, context_code) print(生成的补全) print(completion)5.4 构建一个简单的命令行交互界面最后我们将LSP客户端和AI服务结合起来创建一个简单的交互循环。# main.py import os import sys from lsp_client import SimpleLSPClient from ai_service import OllamaCodeAssistant def main(): workspace input(请输入工作区路径默认为当前目录: ).strip() or . workspace os.path.abspath(workspace) if not os.path.isdir(workspace): print(f错误路径 {workspace} 不存在或不是目录。) return print(f正在初始化工作区: {workspace}) # 启动LSP客户端 lsp_client SimpleLSPClient(workspace) lsp_client.start() # 初始化AI助手 ai_assistant OllamaCodeAssistant() print(\n 简易代码助手已启动 ) print(命令) print( :symbols 文件路径 - 列出文件符号) print( :complete 文件路径 行号 列号 指令 - 请求代码补全) print( :quit - 退出) print( * 30) while True: try: cmd_input input(\n助手 ).strip() if not cmd_input: continue if cmd_input :quit: print(正在关闭...) lsp_client.shutdown() break parts cmd_input.split(maxsplit3) command parts[0] if command :symbols and len(parts) 2: file_path parts[1] full_path os.path.join(workspace, file_path) if os.path.exists(full_path): symbols lsp_client.get_document_symbols(full_path) print(f\n文件 {file_path} 中的符号) for sym in symbols[:10]: # 只显示前10个 name sym.get(name, N/A) kind sym.get(kind, N/A) # LSP符号种类映射 kind_map {1: 文件, 2: 模块, 3: 命名空间, 4: 包, 5: 类, 6: 方法, 7: 属性, 8: 函数, 9: 构造函数, 10: 变量} kind_str kind_map.get(kind, str(kind)) print(f - {name} ({kind_str})) if len(symbols) 10: print(f ... 以及 {len(symbols) - 10} 个其他符号) else: print(f错误文件 {full_path} 不存在。) elif command :complete and len(parts) 5: _, file_path, line_str, col_str, instruction parts full_path os.path.join(workspace, file_path) if not os.path.exists(full_path): print(f错误文件 {full_path} 不存在。) continue # 读取文件内容作为上下文简化版实际应从LSP获取更精确的上下文 try: with open(full_path, r, encodingutf-8) as f: file_content f.read() except Exception as e: print(f读取文件失败: {e}) continue print(f\n正在为 {file_path}:{line_str}:{col_str} 生成补全...) completion ai_assistant.generate_completion(instruction, file_content) if completion: print(\n--- AI 建议 ---) print(completion) print(----------------) # 这里可以添加交互询问用户是否应用补全 apply input(是否应用此补全(y/N): ).strip().lower() if apply y: # 在实际应用中这里应该通过LSP的WorkspaceEdit来应用更改 # 此处简化仅打印说明 print(在实际版本中将通过LSP应用此更改到源代码) else: print(未能生成补全建议。) else: print(未知命令或参数不足。) except KeyboardInterrupt: print(\n接收到中断信号正在退出...) lsp_client.shutdown() break except Exception as e: print(f发生错误: {e}) if __name__ __main__: main()5.5 运行与测试确保Ollama服务正在运行通常安装后会自动启动。在工作区创建一个示例Python文件example.py# example.py def calculate_area(width, height): 计算矩形面积 return width * height def calculate_total(运行我们的原型python main.py输入工作区路径直接回车使用当前目录。尝试命令:symbols ./example.py- 查看文件中的符号。:complete ./example.py 5 1 请补全calculate_total函数的参数和函数体开始部分它应该接收一个物品列表和税率。- 请求AI补全第5行第1列即calculate_total(后面的代码。这个原型虽然简陋但它清晰地演示了如何将LSP用于“读”代码上下文和本地AI模型用于“写”代码连接起来构成了一个智能编码助手的核心循环。6. 进阶优化与生产级考量上面的原型只是一个起点。要打造一个真正可用的工具还需要解决大量工程问题。6.1 性能优化响应速度是关键用户无法忍受一个输入后要等好几秒才有反应的助手。上下文缓存对AST、符号信息、文件内容进行多级缓存内存、磁盘。使用LRU最近最少使用策略管理缓存大小。Prompt精简与模板化发送给AI的上下文不是越多越好。需要设计算法提取最相关的代码片段如当前函数、被引用的函数、同模块的类。将Prompt模板化并预编译。流式响应对于AI生成使用支持流式输出的API如Ollama的/api/generate设置streamtrue实现边生成边显示提升用户体验。模型量化与硬件加速对于本地模型使用量化版本如GGUF格式的4位或5位量化可以大幅降低内存占用和提升推理速度。如果拥有NVIDIA GPU确保使用CUDA加速Ollama会自动检测。6.2 可靠性提升处理边界情况和错误网络与服务降级如果本地模型服务或云端API不可用系统应有降级方案例如回退到基于规则的简单补全或给出明确的错误提示。代码安全与质量检查AI生成的代码可能包含安全漏洞、语法错误或不符合项目规范。集成静态分析工具如对于Python的bandit、flake8对于JS的ESLint对生成的代码进行快速扫描过滤掉明显有问题如使用eval的建议。撤销与重做任何自动应用的编辑都必须支持完整的撤销Undo操作。这需要与编辑器的撤销栈很好地集成。6.3 可扩展性设计支持多语言与多模型插件化架构将语言支持LSP客户端、AI模型后端、编辑器前端设计为插件。核心系统只定义接口如LanguageProvider、AIModelProvider、EditorInterface。配置驱动通过配置文件如YAML来定义不同语言使用哪个LSP服务器、哪个AI模型、以及对应的Prompt模板。模型路由可以根据代码语言的类型、任务的复杂度智能路由到不同的AI模型。例如简单的语法补全用一个轻量快速的模型复杂的重构任务用一个能力更强但较慢的模型。6.4 提示词工程让AI更懂你Prompt的质量直接决定输出代码的质量。需要为不同场景设计专门的Prompt模板。代码风格在Prompt中明确指定缩进、命名规范camelCase, snake_case、引号类型等。项目特定知识可以将项目目录结构、重要的API文档摘要、自定义的编码规范作为“系统提示词”的一部分注入让AI生成的代码更贴合项目。少样本学习Few-shot Learning在Prompt中提供1-2个本项目内的代码示例输入-输出对能极大地引导AI模仿本项目的代码风格和模式。7. 常见问题与排查实录在开发和集成过程中你几乎一定会遇到下面这些问题。7.1 LSP服务器连接与通信问题问题启动LSP客户端后无法收到服务器的响应或一直报初始化错误。排查检查进程确认pylsp或其他语言服务器已正确安装且在PATH中。可以尝试在终端直接运行pylsp --help。检查通信协议LSP使用JSON-RPC over stdio但消息格式有严格规范必须以Content-Length头开头。我们原型中的简化读取逻辑可能不健壮。参考官方vscode-languageserver-node或pygls的客户端实现来完善通信层。查看日志许多LSP服务器支持通过--log-file参数输出日志查看日志能了解初始化失败的具体原因。解决使用成熟的LSP客户端库如针对Python的python-lsp-jsonrpc而不是自己从头实现协议解析。7.2 Ollama模型服务调用失败问题调用http://localhost:11434/api/generate超时或返回错误。排查服务状态运行ollama list查看模型是否已下载。运行ollama serve查看服务是否正常启动。端口占用默认端口11434是否被其他程序占用可通过lsof -i :11434检查。模型加载首次调用或长时间未调用后Ollama需要加载模型到内存这可能耗时几十秒导致首次请求超时。考虑实现一个“预热”机制在系统启动时预先发送一个轻量级请求。内存不足如果模型太大而内存不足Ollama可能会崩溃或无响应。查看系统内存使用情况考虑换用更小的量化模型。解决在代码中增加重试机制和更详细的错误处理将Ollama服务的状态监控集成到你的工具中。7.3 AI生成代码质量不佳或不符合预期问题生成的代码语法错误、逻辑混乱或完全偏离了需求。排查Prompt问题这是最常见的原因。检查发送的Prompt是否清晰、无歧义是否提供了足够且准确的上下文尝试在Web UI如Ollama Web中用相同的Prompt测试看结果是否一致。模型能力当前使用的模型如6.7B参数对于非常复杂或生僻的任务可能力不从心。尝试换用更大参数的模型如33B或使用专门为代码微调的模型。温度参数temperature参数过高会导致生成结果随机性大、不稳定。对于代码生成通常设置在0.1到0.3之间比较合适。上下文长度如果你的代码文件很长可能超过了模型的上下文窗口。需要优化上下文提取策略只发送最相关的部分。解决建立一套Prompt的A/B测试机制持续迭代优化Prompt模板。对于关键任务可以实现“生成-验证-重试”的循环使用代码解析器验证生成结果的语法如果不通过则调整Prompt重新生成。7.4 系统资源占用过高问题工具运行一段时间后电脑变得卡顿内存或CPU占用率很高。排查内存泄漏检查你的代码尤其是LSP客户端和AI请求部分是否有未正确释放的资源如未关闭的文件描述符、未清理的缓存。模型内存Ollama加载的模型会常驻内存。一个7B的模型可能占用4-8GB内存。这是最大的开销来源。LSP服务器语言服务器本身也会占用不少内存尤其是对大型项目建立索引时。解决为工具设置资源使用上限。实现空闲时卸载不常用语言的LSP服务器。考虑使用更轻量级的语言分析工具作为备选。对于本地模型这是硬性成本需要根据硬件条件权衡模型大小和能力。构建一个属于自己的“Claude Code”式工具是一条充满挑战但极具成就感的路径。它迫使你深入理解现代开发工具链的各个组成部分从语言协议到AI推理。这个过程获得的对智能编码助手内部运作机制的洞察其价值远超过单纯使用一个现成的产品。这个原型只是一个起点你可以沿着这个框架不断添加新的功能比如更强大的“Edit”指令解析、图形化界面、或者与你的团队知识库深度集成最终打造出一个完全贴合你个人或团队工作流的终极智能编程伙伴。
1. 项目概述从“Claude Code”到“TodoWrite”的平民化实践最近在开发者社区里“Claude Code”这个词的热度居高不下。无论是搜索“claude code安装教程”还是遇到“npm install -g pnpm read econnreset”这类网络问题都反映出大家对这个工具的浓厚兴趣。但说实话当我第一次看到“Claude Code 源码普通工具实现 Read / Write / Edit / TodoWrite”这个标题时我的第一反应是困惑。Claude Code本身是Anthropic推出的AI编程助手通常以插件形式集成在VSCode等IDE中它本身并不是一个开源项目何来“源码”一说更别提用“普通工具”去实现它的核心功能了。深入思考后我明白了这个标题背后的真正诉求。它指向的并非去逆向工程某个商业产品而是一个更具普适性的命题我们能否利用市面上成熟、易得甚至免费的开源组件和AI模型自己动手搭建一套具备“读、写、编辑、任务驱动写作”能力的智能编码辅助系统这本质上是对当前AI编码工具“黑盒化”和“服务依赖”现状的一种技术反思和DIY挑战。用户想要的不是某个特定产品的复制品而是一个可理解、可控制、可定制的解决方案蓝图。因此本文我将彻底抛开对特定商业产品的依赖聚焦于“Read / Write / Edit / TodoWrite”这四个核心能力为你拆解如何用“普通工具”——即广泛可得的编程库、开源模型和标准协议——来构建属于你自己的智能编码伴侣。无论你是想深入理解AI编程助手的原理还是希望有一个完全受控、能嵌入私有工作流的编码工具这篇文章都将提供从设计思路到代码实现的完整路径。2. 核心能力拆解什么是真正的 Read / Write / Edit / TodoWrite在开始动手之前我们必须清晰定义目标。一个智能编码系统的四大核心能力远不止字面意思那么简单。2.1 Read超越语法高亮的深度代码理解“读”代码对于传统IDE来说意味着词法分析、语法高亮和简单的跳转。但对于我们的系统“Read”意味着语义理解。代码解析与抽象语法树AST这是所有高级操作的基础。我们需要将源代码文本转化为结构化的树形表示。对于JavaScript/TypeScriptbabel/parser或typescript编译器自带的AST生成器是首选对于Pythonast标准库是核心对于Java可以考虑JavaParser。这一步让我们能精确知道哪里是函数声明、哪里是变量、哪里是条件判断。上下文感知“读”不能只读当前文件。一个高效的助手必须能理解项目的上下文。这包括跨文件引用分析通过解析import/require语句构建项目内的依赖图。类型信息推断对于动态语言如Python、JavaScript需要结合类型注解如TypeScript的类型定义、Python的type hints或通过静态分析工具如pyright、tsserver来获取更丰富的语义信息。项目结构理解识别package.json、pyproject.toml、CMakeLists.txt等配置文件理解项目的构建方式、依赖关系和技术栈。实操心得AST的解析是资源密集型操作。对于大型项目全量解析所有文件是不现实的。一个实用的策略是惰性解析和缓存。只有当用户聚焦或编辑某个文件时才深度解析该文件及其直接依赖。可以将AST序列化后缓存到内存或磁盘避免重复解析。2.2 Write Edit从补全到重构的智能代码生成“写”和“编辑”是紧密耦合的能力通常由AI模型驱动但需要精密的工程将其与“读”的能力结合。智能补全Intelligent Completion这不仅仅是基于当前词条的补全。它需要结合局部上下文当前光标所在的行、函数、类。全局上下文当前文件的导入、同文件的其他函数、项目中的常见模式。AI模型预测基于上述上下文让模型预测最可能的下一个token或代码块。代码编辑指令Edit Instructions这是“Edit”能力的核心。用户可能说“把这个函数改成异步的”或“给这个类添加一个toJSON方法”。系统需要理解自然语言指令将用户的自然语言描述转化为一个或多个具体的代码操作如“插入”、“删除”、“替换”、“重构”。精确定位编辑范围结合AST精确找到需要修改的代码节点如函数体、参数列表。生成并应用代码差异Diff生成符合项目编码风格的代码更改并以非破坏性的方式如生成补丁应用到源代码中最好能提供预览。2.3 TodoWrite任务驱动的自动化代码编写这是最高阶的能力也是区分普通补全和“智能助手”的关键。TodoWrite指的是根据一个高层次的任务描述如“创建一个用户登录的REST API端点”自动完成从文件创建、代码骨架生成、依赖安装到单元测试草稿的一系列操作。任务分解Task Decomposition将模糊的用户需求拆解为具体的、可执行的子任务。例如“创建登录API”可以分解为在routes/目录下创建auth.py文件。定义POST /api/auth/login端点。实现请求体验证用户名、密码。编写用户查询和密码验证逻辑。生成JWT令牌并返回。在__init__.py中注册路由。多步骤执行与状态管理系统需要按顺序或并行执行这些子任务并管理执行状态。如果某一步失败如依赖冲突需要能够回滚或提供解决方案。与开发环境深度集成TodoWrite可能涉及运行终端命令npm install、pip install、创建新文件、修改配置文件等。这要求我们的系统不能只是一个被动的代码建议器而需要具备一定的“执行权”在用户确认下。3. 技术栈选型用“普通工具”搭建智能内核明确了目标我们来选择实现这些能力的“普通工具”。我们的原则是优先选择开源、文档完善、社区活跃的组件。3.1 语言服务器协议实现“Read”能力的基石要实现深度的代码理解重新发明轮子是不明智的。语言服务器协议Language Server Protocol, LSP是微软制定的开放协议它定义了编辑器和语言服务器之间通信的标准。我们可以直接利用现有的、强大的语言服务器。为什么选择LSP标准化一套接口支持所有实现了LSP的编辑器VSCode, Vim, Emacs等。功能强大现有的语言服务器如tsserverfor JS/TS,pylspfor Python,rust-analyzerfor Rust已经实现了跳转定义、查找引用、悬停提示、代码诊断等复杂的“Read”功能。可嵌入我们可以以客户端的形式连接这些服务器获取结构化的代码信息而无需自己实现复杂的解析器。核心工具vscode-languageserver-node如果你想用Node.js构建自己的LSP客户端或服务器这是官方库。pygls用Python构建语言服务器的绝佳框架。lsp4jJava生态的LSP实现。直接连接更简单的方式是在你的工具中启动一个子进程运行现有的语言服务器如pylsp并通过标准输入输出stdio与其进行JSON-RPC通信。3.2 AI模型层驱动“Write/Edit/TodoWrite”的大脑这是系统的智能核心。我们不需要训练自己的大模型而是通过API或本地部署来利用现有模型。云端API方案快速启动OpenAI API (GPT-4, GPT-3.5-Turbo)代码生成能力强大响应速度快但需要网络且产生持续费用。Anthropic API (Claude 3系列)在长上下文和逻辑推理上表现优异同样需要网络和付费。国内可选API如DeepSeek、通义千问等提供了具有竞争力的代码生成能力访问延迟可能更低。集成方式使用对应的官方SDK如openai,anthropic或通用的HTTP客户端封装请求。关键在于设计高效的提示词Prompt将我们从LSP获取的代码上下文有效地传递给模型。本地模型方案完全可控、离线模型选择这是当前的热点。可以选择参数较小的优秀代码模型在本地运行。DeepSeek-Coder系列模型如6.7B, 33B在代码生成上表现非常出色对硬件要求相对友好。CodeLlamaMeta发布的专注于代码的Llama变体。Qwen-Coder通义千问的代码模型同样表现不俗。推理框架Ollama最简单的方式。它提供了模型管理、拉取和运行的一体化体验通过简单的REST API即可调用。ollama run deepseek-coder:6.7b就能跑起来。LM Studio图形化界面适合桌面端快速测试和体验不同模型。vLLM / llama.cpp如果你追求极致的推理性能和高吞吐量用于生产环境这些是更专业的选择。llama.cpp对CPU推理优化极好。硬件考量运行6B-7B参数的模型16GB内存的MacBook Pro或配备16GB以上RAM的PC通常可以胜任。对于33B模型则需要更大的内存或使用GPU加速。注意事项选择本地模型时务必在 Hugging Face 或模型发布方官网仔细查看模型的许可证License。商用项目要选择允许商用的许可证如Apache 2.0, MIT。同时关注模型的上下文长度Context Length这决定了它能“看到”多长的代码。3.3 胶水层与工程框架将一切连接起来我们需要一个主程序来协调LSP客户端、AI模型和编辑器/用户界面。后端框架可选如果你的工具是一个独立的桌面应用或后台服务。Node.js Express/Fastify适合构建提供WebSocket或HTTP API的服务端方便与多种前端集成。Python FastAPI/Flask在AI和数据处理生态上有天然优势与pygls和本地模型结合更紧密。进程间通信IPC这是关键。标准输入输出stdio与语言服务器通信的标准方式。WebSocket实现前端如Web IDE与后端服务的实时双向通信用于传递代码变更和接收AI建议。消息队列如ZeroMQ在复杂的微服务架构中用于解耦各个组件如解析服务、AI推理服务。前端/编辑器集成VSCode Extension最直接的集成方式。你可以开发一个VSCode插件在插件中嵌入你的LSP客户端和AI调用逻辑。Web IDE基于Monaco EditorVSCode的网页版核心或CodeMirror构建自己的在线编辑器通过WebSocket与后端服务通信。独立桌面应用使用Electron或Tauri打包你的Web技术栈应用提供原生体验。4. 系统架构设计与核心流程基于以上选型我们可以勾勒出一个可行的系统架构。[用户界面] (VSCode插件 / Web编辑器 / 独立App) | | (发送代码变更、用户指令) v [核心协调服务] (Node.js/Python 主进程) | | | (通过LSP协议获取代码上下文) | (构造Prompt调用AI) v v [语言服务器进程] [AI模型服务] (pylsp, tsserver等) (本地Ollama / 云端API) | | | (返回AST、符号信息) | (返回代码补全/编辑建议) v v [核心协调服务] --(融合上下文与AI建议)-- | | (返回格式化后的建议或执行编辑) v [用户界面] (显示建议应用更改)4.1 核心工作流程一次智能补全的诞生让我们跟踪一次“智能函数补全”的请求看看数据如何在系统中流动事件触发用户在编辑器中输入了function calculateTotal(并停顿了约500毫秒。上下文收集核心服务监听到这个事件。它立即通过LSP客户端向语言服务器发起一系列请求获取文档符号Document Symbols了解当前文件有哪些类、函数、变量。获取光标位置上下文获取光标所在位置的语法节点信息例如正在一个函数声明内部。获取相关代码段获取当前函数所在类或模块的代码以及可能被导入的相关类型定义。Prompt工程核心服务将收集到的结构化上下文按照预定模板组装成给AI模型的Prompt。一个简单的模板可能是// 你是一个专业的代码助手。请根据以下上下文补全代码。 // 当前文件路径/src/utils/math.js // 光标前的代码 function calculateTotal( // 光标后的代码可能为空 // 当前文件的导入 import { applyTax } from ./tax; // 同文件的其他相关函数 function calculateSubtotal(items) { ... } // 请补全 calculateTotal 函数的参数列表和函数体开始部分。只返回代码。AI推理核心服务将组装好的Prompt通过HTTP请求发送给本地Ollama服务例如http://localhost:11434/api/generate或云端API。结果解析与呈现AI返回items, taxRate) { const subtotal calculateSubtotal(items); return applyTax(subtotal, taxRate); }。核心服务对这个结果进行后处理检查语法是否正确是否符合项目风格如分号使用。最后将补全建议通过编辑器接口如VSCode的CompletionItem返回给前端。用户交互用户看到补全建议按Tab键接受。编辑器将补全的文本插入到光标位置。4.2 实现“Edit”指令代码编辑的精准手术“Edit”比补全更复杂因为它需要指定一个编辑范围。我们可以利用LSP的WorkspaceEdit概念。指令解析用户输入自然语言指令“将函数calculateTotal改为异步”。定位目标核心服务通过LSP的“查找定义”功能精确定位到calculateTotal函数在源代码中的位置文件路径、起始行/列、结束行/列。构造增量编辑核心服务分析该函数的AST判断它是一个普通函数声明。然后构造编辑指令在function关键字前添加async。如果函数体内有return语句可能需要将其改为return await ...这需要更复杂的AST分析或交给AI判断。生成AI Prompt将“原始代码”和“编辑意图”发给AI让AI生成编辑后的代码块。Prompt示例原始代码 function calculateTotal(items, taxRate) { const subtotal calculateSubtotal(items); return applyTax(subtotal, taxRate); } 请将上述函数改为异步函数。只返回修改后的完整函数代码。计算差异与应用比较AI返回的新代码和原始代码计算出具体的文本差异可以使用diff算法库如jsdiff。然后通过LSP的ApplyEdit请求或直接操作编辑器文档应用这个差异。务必提供预览让用户确认后再应用。4.3 实现“TodoWrite”编排多步骤的自动化这是最复杂的流程需要状态机和任务队列。任务解析与规划用户输入“为产品模型添加CRUD API端点”。AI规划阶段将此任务发送给一个具有长上下文和强规划能力的AI模型如Claude 3 Sonnet或本地部署的DeepSeek要求它输出一个详细的、步骤化的JSON计划。{ task: 创建产品CRUD API, steps: [ { id: 1, action: create_file, path: src/routes/products.py, description: 创建产品路由文件, depends_on: [] }, { id: 2, action: write_code, file: src/routes/products.py, description: 定义GET /api/products 端点, depends_on: [1] }, { id: 3, action: run_command, command: pip install pydantic, description: 确保数据验证库已安装, depends_on: [] } // ... 更多步骤 ] }步骤执行器核心服务有一个步骤执行器它按顺序处理依赖关系执行每个步骤。create_file调用文件系统API。write_code调用前文所述的“Edit”能力在指定文件写入代码。run_command在子进程中执行shell命令并捕获输出和错误码。状态管理与用户确认每个步骤执行前可以向用户展示即将进行的操作并请求确认“即将创建文件src/routes/products.py是否继续”。执行后记录成功或失败。如果某步失败如命令执行错误可以暂停流程向用户报告错误并提供重试或跳过的选项。结果汇总所有步骤执行完毕后生成一份报告列出创建的文件、修改的代码、运行的命令等。5. 实战构建一个最小可行原型理论说再多不如动手做。让我们用Python和Ollama快速搭建一个具备“Read”和基础“Write”能力的命令行原型。5.1 环境准备与依赖安装首先确保你的系统已经安装了Python 3.8和Ollama。# 1. 安装Ollama (请参考官网 https://ollama.com/) # 对于macOS/Linux: curl -fsSL https://ollama.com/install.sh | sh # 2. 拉取一个代码模型例如DeepSeek Coder 6.7B ollama pull deepseek-coder:6.7b # 3. 创建一个新的Python项目目录并安装依赖 mkdir my-code-helper cd my-code-helper python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install python-lsp-server pylsp-openai openai requests这里我们安装了python-lsp-server即pylsp作为我们的语言服务器pylsp-openai是一个实验性的插件但我们不直接用它而是学习其思路。openai和requests库用于与Ollama的API通信。5.2 实现LSP客户端与代码上下文提取我们将实现一个简化的LSP客户端用于与pylsp通信并获取当前文件的符号信息。# lsp_client.py import subprocess import json import threading import time import sys import os from typing import Dict, Any, List class SimpleLSPClient: def __init__(self, workspace_root: str): self.workspace_root workspace_root self.process None self.seq 0 self.responses {} self.lock threading.Lock() self.connected False def start(self): 启动pylsp语言服务器进程 self.process subprocess.Popen( [pylsp], stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue, bufsize1 ) # 启动读写线程 threading.Thread(targetself._read_stdout, daemonTrue).start() threading.Thread(targetself._read_stderr, daemonTrue).start() self._initialize() def _read_stdout(self): 读取服务器返回的JSON-RPC消息 buffer while True: line self.process.stdout.readline() if not line: break buffer line if buffer.endswith(\r\n\r\n): # 简单的分隔符判断实际LSP消息以Content-Length头分隔 # 这里为简化假设每行是一个完整的JSON try: message json.loads(buffer.strip()) self._handle_message(message) except json.JSONDecodeError: pass buffer def _read_stderr(self): 读取服务器错误输出 for line in iter(self.process.stderr.readline, ): if line: sys.stderr.write(f[LSP Error] {line}) def _handle_message(self, message: Dict[str, Any]): 处理服务器响应 if id in message: with self.lock: self.responses[message[id]] message def _send(self, method: str, params: Dict[str, Any] None) - int: 发送JSON-RPC请求返回请求ID self.seq 1 request { jsonrpc: 2.0, id: self.seq, method: method, params: params or {} } json_str json.dumps(request) content fContent-Length: {len(json_str)}\r\n\r\n{json_str} self.process.stdin.write(content) self.process.stdin.flush() return self.seq def _initialize(self): 发送初始化请求 init_params { processId: os.getpid(), rootUri: ffile://{self.workspace_root}, capabilities: {}, workspaceFolders: [{ uri: ffile://{self.workspace_root}, name: workspace }] } init_id self._send(initialize, init_params) # 等待初始化响应简化处理实际应超时等待 time.sleep(1) self._send(initialized, {}) self.connected True def get_document_symbols(self, file_path: str) - List[Dict]: 获取指定文件的符号函数、类等列表 if not self.connected: return [] uri ffile://{file_path} params {textDocument: {uri: uri}} req_id self._send(textDocument/documentSymbol, params) # 简单等待响应 time.sleep(0.5) with self.lock: response self.responses.pop(req_id, None) if response and result in response: return response[result] return [] def shutdown(self): 关闭连接 self._send(shutdown) self._send(exit) self.process.terminate() # 使用示例 if __name__ __main__: client SimpleLSPClient(os.getcwd()) client.start() time.sleep(2) # 等待初始化完成 symbols client.get_document_symbols(./example.py) print(fFound {len(symbols)} symbols in example.py) for sym in symbols: print(f - {sym.get(name)} ({sym.get(kind)})) client.shutdown()5.3 集成Ollama实现代码补全接下来我们创建一个AI服务类用于与本地运行的Ollama对话。# ai_service.py import requests import json class OllamaCodeAssistant: def __init__(self, model: str deepseek-coder:6.7b, base_url: str http://localhost:11434): self.model model self.base_url base_url self.api_url f{base_url}/api/generate def generate_completion(self, prompt: str, context_code: str ) - str: 向Ollama发送请求生成代码补全 full_prompt self._build_prompt(prompt, context_code) payload { model: self.model, prompt: full_prompt, stream: False, options: { temperature: 0.2, # 低温度生成更确定性的代码 num_predict: 128, # 最大生成token数 } } try: response requests.post(self.api_url, jsonpayload, timeout30) response.raise_for_status() result response.json() return result.get(response, ).strip() except requests.exceptions.RequestException as e: print(f请求Ollama API失败: {e}) return def _build_prompt(self, instruction: str, context: str) - str: 构建给模型的提示词 # 这是一个简单的提示词模板你可以根据模型特性优化 template f你是一个专业的Python代码助手。请根据以下上下文完成指令。 上下文代码{context}指令{instruction} 只返回代码不要有任何解释。 return template # 使用示例补全一个函数 if __name__ __main__: assistant OllamaCodeAssistant() context_code def calculate_area(width, height): \\\计算矩形面积\\\ return width * height def calculate_total( instruction 请补全 calculate_total 函数的参数和函数体开始部分它应该接收一个物品列表和税率。 completion assistant.generate_completion(instruction, context_code) print(生成的补全) print(completion)5.4 构建一个简单的命令行交互界面最后我们将LSP客户端和AI服务结合起来创建一个简单的交互循环。# main.py import os import sys from lsp_client import SimpleLSPClient from ai_service import OllamaCodeAssistant def main(): workspace input(请输入工作区路径默认为当前目录: ).strip() or . workspace os.path.abspath(workspace) if not os.path.isdir(workspace): print(f错误路径 {workspace} 不存在或不是目录。) return print(f正在初始化工作区: {workspace}) # 启动LSP客户端 lsp_client SimpleLSPClient(workspace) lsp_client.start() # 初始化AI助手 ai_assistant OllamaCodeAssistant() print(\n 简易代码助手已启动 ) print(命令) print( :symbols 文件路径 - 列出文件符号) print( :complete 文件路径 行号 列号 指令 - 请求代码补全) print( :quit - 退出) print( * 30) while True: try: cmd_input input(\n助手 ).strip() if not cmd_input: continue if cmd_input :quit: print(正在关闭...) lsp_client.shutdown() break parts cmd_input.split(maxsplit3) command parts[0] if command :symbols and len(parts) 2: file_path parts[1] full_path os.path.join(workspace, file_path) if os.path.exists(full_path): symbols lsp_client.get_document_symbols(full_path) print(f\n文件 {file_path} 中的符号) for sym in symbols[:10]: # 只显示前10个 name sym.get(name, N/A) kind sym.get(kind, N/A) # LSP符号种类映射 kind_map {1: 文件, 2: 模块, 3: 命名空间, 4: 包, 5: 类, 6: 方法, 7: 属性, 8: 函数, 9: 构造函数, 10: 变量} kind_str kind_map.get(kind, str(kind)) print(f - {name} ({kind_str})) if len(symbols) 10: print(f ... 以及 {len(symbols) - 10} 个其他符号) else: print(f错误文件 {full_path} 不存在。) elif command :complete and len(parts) 5: _, file_path, line_str, col_str, instruction parts full_path os.path.join(workspace, file_path) if not os.path.exists(full_path): print(f错误文件 {full_path} 不存在。) continue # 读取文件内容作为上下文简化版实际应从LSP获取更精确的上下文 try: with open(full_path, r, encodingutf-8) as f: file_content f.read() except Exception as e: print(f读取文件失败: {e}) continue print(f\n正在为 {file_path}:{line_str}:{col_str} 生成补全...) completion ai_assistant.generate_completion(instruction, file_content) if completion: print(\n--- AI 建议 ---) print(completion) print(----------------) # 这里可以添加交互询问用户是否应用补全 apply input(是否应用此补全(y/N): ).strip().lower() if apply y: # 在实际应用中这里应该通过LSP的WorkspaceEdit来应用更改 # 此处简化仅打印说明 print(在实际版本中将通过LSP应用此更改到源代码) else: print(未能生成补全建议。) else: print(未知命令或参数不足。) except KeyboardInterrupt: print(\n接收到中断信号正在退出...) lsp_client.shutdown() break except Exception as e: print(f发生错误: {e}) if __name__ __main__: main()5.5 运行与测试确保Ollama服务正在运行通常安装后会自动启动。在工作区创建一个示例Python文件example.py# example.py def calculate_area(width, height): 计算矩形面积 return width * height def calculate_total(运行我们的原型python main.py输入工作区路径直接回车使用当前目录。尝试命令:symbols ./example.py- 查看文件中的符号。:complete ./example.py 5 1 请补全calculate_total函数的参数和函数体开始部分它应该接收一个物品列表和税率。- 请求AI补全第5行第1列即calculate_total(后面的代码。这个原型虽然简陋但它清晰地演示了如何将LSP用于“读”代码上下文和本地AI模型用于“写”代码连接起来构成了一个智能编码助手的核心循环。6. 进阶优化与生产级考量上面的原型只是一个起点。要打造一个真正可用的工具还需要解决大量工程问题。6.1 性能优化响应速度是关键用户无法忍受一个输入后要等好几秒才有反应的助手。上下文缓存对AST、符号信息、文件内容进行多级缓存内存、磁盘。使用LRU最近最少使用策略管理缓存大小。Prompt精简与模板化发送给AI的上下文不是越多越好。需要设计算法提取最相关的代码片段如当前函数、被引用的函数、同模块的类。将Prompt模板化并预编译。流式响应对于AI生成使用支持流式输出的API如Ollama的/api/generate设置streamtrue实现边生成边显示提升用户体验。模型量化与硬件加速对于本地模型使用量化版本如GGUF格式的4位或5位量化可以大幅降低内存占用和提升推理速度。如果拥有NVIDIA GPU确保使用CUDA加速Ollama会自动检测。6.2 可靠性提升处理边界情况和错误网络与服务降级如果本地模型服务或云端API不可用系统应有降级方案例如回退到基于规则的简单补全或给出明确的错误提示。代码安全与质量检查AI生成的代码可能包含安全漏洞、语法错误或不符合项目规范。集成静态分析工具如对于Python的bandit、flake8对于JS的ESLint对生成的代码进行快速扫描过滤掉明显有问题如使用eval的建议。撤销与重做任何自动应用的编辑都必须支持完整的撤销Undo操作。这需要与编辑器的撤销栈很好地集成。6.3 可扩展性设计支持多语言与多模型插件化架构将语言支持LSP客户端、AI模型后端、编辑器前端设计为插件。核心系统只定义接口如LanguageProvider、AIModelProvider、EditorInterface。配置驱动通过配置文件如YAML来定义不同语言使用哪个LSP服务器、哪个AI模型、以及对应的Prompt模板。模型路由可以根据代码语言的类型、任务的复杂度智能路由到不同的AI模型。例如简单的语法补全用一个轻量快速的模型复杂的重构任务用一个能力更强但较慢的模型。6.4 提示词工程让AI更懂你Prompt的质量直接决定输出代码的质量。需要为不同场景设计专门的Prompt模板。代码风格在Prompt中明确指定缩进、命名规范camelCase, snake_case、引号类型等。项目特定知识可以将项目目录结构、重要的API文档摘要、自定义的编码规范作为“系统提示词”的一部分注入让AI生成的代码更贴合项目。少样本学习Few-shot Learning在Prompt中提供1-2个本项目内的代码示例输入-输出对能极大地引导AI模仿本项目的代码风格和模式。7. 常见问题与排查实录在开发和集成过程中你几乎一定会遇到下面这些问题。7.1 LSP服务器连接与通信问题问题启动LSP客户端后无法收到服务器的响应或一直报初始化错误。排查检查进程确认pylsp或其他语言服务器已正确安装且在PATH中。可以尝试在终端直接运行pylsp --help。检查通信协议LSP使用JSON-RPC over stdio但消息格式有严格规范必须以Content-Length头开头。我们原型中的简化读取逻辑可能不健壮。参考官方vscode-languageserver-node或pygls的客户端实现来完善通信层。查看日志许多LSP服务器支持通过--log-file参数输出日志查看日志能了解初始化失败的具体原因。解决使用成熟的LSP客户端库如针对Python的python-lsp-jsonrpc而不是自己从头实现协议解析。7.2 Ollama模型服务调用失败问题调用http://localhost:11434/api/generate超时或返回错误。排查服务状态运行ollama list查看模型是否已下载。运行ollama serve查看服务是否正常启动。端口占用默认端口11434是否被其他程序占用可通过lsof -i :11434检查。模型加载首次调用或长时间未调用后Ollama需要加载模型到内存这可能耗时几十秒导致首次请求超时。考虑实现一个“预热”机制在系统启动时预先发送一个轻量级请求。内存不足如果模型太大而内存不足Ollama可能会崩溃或无响应。查看系统内存使用情况考虑换用更小的量化模型。解决在代码中增加重试机制和更详细的错误处理将Ollama服务的状态监控集成到你的工具中。7.3 AI生成代码质量不佳或不符合预期问题生成的代码语法错误、逻辑混乱或完全偏离了需求。排查Prompt问题这是最常见的原因。检查发送的Prompt是否清晰、无歧义是否提供了足够且准确的上下文尝试在Web UI如Ollama Web中用相同的Prompt测试看结果是否一致。模型能力当前使用的模型如6.7B参数对于非常复杂或生僻的任务可能力不从心。尝试换用更大参数的模型如33B或使用专门为代码微调的模型。温度参数temperature参数过高会导致生成结果随机性大、不稳定。对于代码生成通常设置在0.1到0.3之间比较合适。上下文长度如果你的代码文件很长可能超过了模型的上下文窗口。需要优化上下文提取策略只发送最相关的部分。解决建立一套Prompt的A/B测试机制持续迭代优化Prompt模板。对于关键任务可以实现“生成-验证-重试”的循环使用代码解析器验证生成结果的语法如果不通过则调整Prompt重新生成。7.4 系统资源占用过高问题工具运行一段时间后电脑变得卡顿内存或CPU占用率很高。排查内存泄漏检查你的代码尤其是LSP客户端和AI请求部分是否有未正确释放的资源如未关闭的文件描述符、未清理的缓存。模型内存Ollama加载的模型会常驻内存。一个7B的模型可能占用4-8GB内存。这是最大的开销来源。LSP服务器语言服务器本身也会占用不少内存尤其是对大型项目建立索引时。解决为工具设置资源使用上限。实现空闲时卸载不常用语言的LSP服务器。考虑使用更轻量级的语言分析工具作为备选。对于本地模型这是硬性成本需要根据硬件条件权衡模型大小和能力。构建一个属于自己的“Claude Code”式工具是一条充满挑战但极具成就感的路径。它迫使你深入理解现代开发工具链的各个组成部分从语言协议到AI推理。这个过程获得的对智能编码助手内部运作机制的洞察其价值远超过单纯使用一个现成的产品。这个原型只是一个起点你可以沿着这个框架不断添加新的功能比如更强大的“Edit”指令解析、图形化界面、或者与你的团队知识库深度集成最终打造出一个完全贴合你个人或团队工作流的终极智能编程伙伴。
