1. 项目概述为什么我们要亲手打造一个AI编程助手最近在社区里看到不少关于AI编程助手的讨论从Copilot到Cursor这些工具确实能极大提升开发效率。但作为一个喜欢“知其所以然”的开发者我总觉得直接使用现成的黑盒工具少了点什么。当代码补全出现一个奇怪的推荐或者Agent执行了一个匪夷所思的操作时我们往往只能挠头因为其内部的决策逻辑对我们而言是不透明的。这正是我决定动手“从零实现”一个AI编程助手的核心动机。这个“从零”并非指从Transformer模型开始训练那对我们大多数应用开发者来说既不现实也无必要。这里的“从零”指的是从最核心的“大脑”与“执行”框架开始搭建让我们能清晰地看到AI助手是如何理解我们的意图、规划步骤、调用工具并最终完成任务的。通过这个过程我们不仅能获得一个可高度定制、完全可控的助手更能深入理解现代AI应用架构的核心——智能体Agent的工作机制。我选择了LangChain.js作为框架因为它为构建基于大语言模型LLM的应用提供了极佳的抽象和工具链。而实现逻辑则采用了ReActReasoning Acting范式这是一种让AI“思考-行动”循环的经典模式非常适合需要多步骤工具调用的编程场景。简单来说我们的助手会像人类程序员一样先“思考”分析问题、制定计划再“行动”执行命令、查看结果根据结果再次“思考”如此循环直到任务完成。这个项目适合谁呢如果你是对AI应用开发感兴趣的JavaScript/TypeScript开发者想超越简单的API调用深入Agent和工具调用的世界或者你是一名全栈工程师希望为自己的团队或产品嵌入一个智能的、可解释的自动化编程模块那么跟着这篇实战走一遍你会收获远超一个Demo的认知。我们将从环境搭建开始一步步构建一个能理解自然语言编程需求、并实际在命令行中执行Bash命令、读写文件、甚至运行测试的AI编程助手。2. 核心架构与ReAct范式深度解析在开始写代码之前我们必须把核心的架构思想搞清楚。为什么是LangChain.js ReAct这个组合到底解决了什么问题2.1 LangChain.js不只是LLM的“胶水”很多人初识LangChain会把它简单理解为连接LLM API的封装库。这低估了它的价值。LangChain的核心贡献在于提供了一套用于构建基于LLM的应用程序的设计模式和组件化抽象。对于我们的编程助手项目它主要解决了以下痛点工具Tools的标准化与管理我们的助手需要调用外部能力比如执行Bash命令、读写文件、搜索文档。LangChain定义了统一的Tool接口每个工具都有name、description和call方法。这让我们可以像搭积木一样轻松地组合和扩展助手的能力。更重要的是LLM通过阅读规范的description就能学会在何时调用哪个工具。提示词Prompt的工程化直接拼接字符串构造提示词是脆弱且难以维护的。LangChain提供了PromptTemplate、ChatPromptTemplate等组件支持变量注入、部分填充和不同消息角色System, Human, AI的结构化组织。这对于构建复杂的、多步骤的ReAct提示词至关重要。记忆Memory与状态管理一个有用的助手需要记住对话上下文。LangChain提供了从简单的缓冲区到基于向量数据库的长期记忆等多种记忆方案方便我们为助手添加上下文感知能力。链Chains与智能体Agents的高层抽象这是最核心的部分。Chain将LLM、提示词、工具等组件按固定顺序组合。而Agent是一种特殊的Chain它的核心是动态决策由LLM根据当前状态和可用工具决定下一步做什么。这完美契合了ReAct范式。选择LangChain.js而非Python版本主要是考虑到JavaScript/TypeScript生态在现代Web和Node.js后端开发中的普及性以及其异步和非阻塞I/O模型与LLM调用天生契合。2.2 ReAct范式让AI学会“三思而后行”ReActReasoning Acting是由Princeton和Google的研究者提出的一种范式旨在提升LLM在复杂任务中的可靠性和可解释性。其核心思想是模仿人类的解决问题方式Reasoning思考LLM生成一段自由形式的推理轨迹分析当前情况、解释为何做出某个决策、或拆解下一步计划。这部分内容通常对人类可见极大地增强了过程的可解释性。Acting行动根据推理LLM决定并执行一个具体的动作通常是调用一个预定义的工具Tool并获取工具的返回结果Observation。这个“思考 - 行动 - 观察结果 - 再思考”的循环会一直持续直到LLM认为任务完成并输出最终答案Final Answer。为什么ReAct特别适合编程助手编程任务本质上是复杂、多步骤的。比如用户要求“为我的Express项目添加一个用户登录接口”。一个简单的单次问答LLM可能会直接生成一大段代码但很可能遗漏创建路由文件、安装依赖包、配置数据库连接等步骤。而采用ReAct的助手则会思考“用户需要添加登录接口。我需要先检查项目结构确定路由文件位置。然后需要安装bcrypt和jsonwebtoken依赖。接着要创建用户模型如果不存在最后编写登录路由逻辑和中间件。”行动调用ListFilesTool查看项目目录。观察看到现有文件结构。思考“项目使用/routes目录。我需要先安装依赖。”行动调用BashCommandTool执行npm install bcrypt jsonwebtoken。观察安装成功。思考“现在检查是否有用户模型User.js…”… 如此循环直到所有步骤完成。这个过程不仅更可靠而且我们可以在每个循环看到AI的“思路”如果它跑偏了我们能及时干预或调整工具描述。2.3 我们的助手架构设计基于以上理解我们项目的核心架构图概念上如下用户输入自然语言指令 | v [ReAct 智能体 (Agent)] | |-- 核心LLM (如 OpenAI GPT-4) |-- 决策逻辑ReAct 专用提示词模板 |-- 可用工具集Bash工具、文件工具等 | v 循环开始 | [思考步骤] - LLM生成推理和下一步动作决定 | v [动作步骤] - 解析决定调用对应工具 | v [观察步骤] - 获取工具执行结果 | v 判断是否完成 --否-- 进入下一轮循环 | 是 v 输出最终结果给用户这个架构中提示词模板是驱动整个ReAct循环的“大脑程序”它规定了LLM输出的格式使其严格遵循“Thought: ... Action: ... Observation: ...”的循环。我们将在下一章具体实现它。3. 环境准备与核心工具实现“工欲善其事必先利其器”。在编写智能体之前我们需要搭建好开发环境并实现那些让AI拥有“手和脚”的工具。3.1 项目初始化与依赖安装首先创建一个新的Node.js项目并安装核心依赖。mkdir ai-programming-assistant cd ai-programming-assistant npm init -y接下来安装依赖。我们将使用TypeScript以获得更好的类型安全。npm install langchain langchain/core openai npm install -D typescript types/node ts-node nodemonlangchain LangChain核心库。langchain/core 包含一些核心抽象和类型。openai OpenAI官方Node.js SDKLangChain会用到它。其余是TypeScript开发环境依赖。初始化TypeScript配置npx tsc --init在生成的tsconfig.json中确保target是ES2020或更高module是commonjsNode.js环境并设置outDir为./dist。现在我们需要一个.env文件来管理敏感信息比如OpenAI的API密钥。创建.env文件OPENAI_API_KEY你的_OpenAI_API_密钥重要安全提示永远不要将.env文件提交到版本控制系统如Git。请确保它在.gitignore中。在代码中我们使用dotenv包来加载这些变量。运行npm install dotenv并安装types/dotenv作为开发依赖。3.2 构建核心工具集赋予AI“动手能力”工具是Agent与外界交互的桥梁。我们将实现几个编程助手最常用的工具。3.2.1 Bash命令执行工具这是最重要的工具让助手能在项目目录下执行任何Shell命令。// src/tools/bashTool.ts import { Tool } from langchain/core/tools; import { exec } from child_process; import { promisify } from util; const execAsync promisify(exec); export class BashCommandTool extends Tool { name bash_command_executor; description 执行一个Bash shell命令。用于运行程序、安装依赖、执行脚本等。输入应该是一个合法的Bash命令字符串。; protected async _call(arg: string): Promisestring { // arg 就是LLM决定要执行的命令例如 ls -la 或 npm install express try { const { stdout, stderr } await execAsync(arg, { cwd: process.cwd() }); // 在当前工作目录执行 if (stderr) { // 有些命令如某些npm警告会输出到stderr但不代表失败。我们将其与stdout一起返回。 return 命令执行完成。标准输出\n${stdout}\n标准错误可能是警告\n${stderr}; } return 命令执行成功。输出\n${stdout}; } catch (error: any) { // 命令执行失败返回非0状态码 return 命令执行失败。错误信息${error.message}\n标准错误输出${error.stderr}; } } }注意事项与心得工作目录cwd这里固定为process.cwd()即启动Node进程的目录。在实际产品中你可能需要让助手感知“当前项目”目录并将其作为上下文传递给工具。安全性这是一个极高风险的工具AI可能会执行rm -rf /或下载恶意脚本。绝对不要在生产环境或存有重要数据的目录下未经审查地运行此类Agent。一种缓解策略是实现一个“批准”层或者在工具描述中强调“仅用于项目开发操作”并限制命令白名单尽管这很复杂。对于学习项目保持警惕并在安全隔离的环境中进行。错误处理我们将错误信息格式化后返回给Agent。LLM可以读取这些错误并调整策略这是ReAct循环能自我修正的关键。3.2.2 文件读写工具让助手能够查看和修改代码文件。// src/tools/fileTools.ts import { Tool } from langchain/core/tools; import fs from fs/promises; import path from path; export class ReadFileTool extends Tool { name read_file; description 读取指定路径文件的内容。输入应该是文件的相对或绝对路径。; protected async _call(filePath: string): Promisestring { try { const content await fs.readFile(filePath, utf-8); return 文件 ${filePath} 的内容如下\n\\\\n${content}\n\\\; } catch (error: any) { return 读取文件失败${error.message}; } } } export class WriteFileTool extends Tool { name write_file; description 将内容写入指定路径的文件。如果文件存在则覆盖。输入应该是一个JSON字符串包含filepath和content两个键。例如{filepath: test.js, content: console.log(hello)}; protected async _call(inputStr: string): Promisestring { try { const { filepath, content } JSON.parse(inputStr); await fs.writeFile(filepath, content, utf-8); return 文件 ${filepath} 写入成功。; } catch (error: any) { return 写入文件失败${error.message}; } } }实操要点输入格式WriteFileTool要求JSON输入这比让LLM自己拼接一个模糊的字符串更可靠。在工具描述中清晰定义输入格式是构建稳定Agent的关键。路径处理这里使用了简单的路径。复杂场景下你可能需要解析相对于项目根目录的路径。代码块格式化在ReadFileTool的返回中我们用Markdown代码块包裹内容。这能帮助LLM更好地理解这是代码片段尤其是在后续的推理中。3.2.3 文件列表工具让助手能浏览项目结构。// src/tools/listFilesTool.ts import { Tool } from langchain/core/tools; import fs from fs/promises; import path from path; export class ListFilesTool extends Tool { name list_files; description 列出指定目录下的文件和文件夹。输入可以是一个目录路径默认为当前目录“.”。对于了解项目结构非常有用。; protected async _call(dirPath: string .): Promisestring { try { const items await fs.readdir(dirPath, { withFileTypes: true }); const itemList items.map((item) { const type item.isDirectory() ? [目录] : [文件]; return ${type} ${item.name}; }); return 目录 ${dirPath} 下的内容\n${itemList.join(\n)}; } catch (error: any) { return 列出文件失败${error.message}; } } }有了这些基础工具我们的AI助手就具备了感知和操作项目环境的基本能力。接下来我们需要组装它的“大脑”。4. 构建ReAct智能体组装大脑与决策循环这是整个项目的核心。我们将创建ReAct提示词模板初始化LLM并将工具整合到Agent中形成完整的决策循环。4.1 设计ReAct提示词模板提示词是指导LLM行为的“程序”。ReAct模式的提示词需要明确告诉LLM你需要循环思考、行动、观察并使用特定的格式输出。// src/prompts/reactPrompt.ts import { ChatPromptTemplate } from langchain/core/prompts; export const ReActPromptTemplate ChatPromptTemplate.fromMessages([ [ system, 你是一个强大的AI编程助手可以通过调用工具来帮助用户完成编程任务。 你运行在一个安全的开发环境中可以执行Bash命令、读写文件、浏览目录。 请严格遵循以下格式进行响应 Thought: 你需要在这里思考当前情况。分析用户的目标回顾之前的观察并决定下一步该做什么。解释你的推理过程。 Action: 你需要在这里声明要执行的动作。必须是以下工具之一{tool_names} Action Input: 你选择工具所需要的输入内容。 Observation: 工具执行后的结果会放在这里这不是由你生成的而是系统填充的。 当你确信已经完成了用户的所有请求或者无法继续时你必须输出 Thought: 我已经完成了任务。 Final Answer: [这里放置你对用户的最终答复总结你所做的工作或提供最终结果。] 让我们开始吧 ], [placeholder, {chat_history}], // 用于放置对话历史如果有多轮 [human, {input}], // 用户的当前问题 [placeholder, {agent_scratchpad}], // 关键这里将自动填充之前的 Thought/Action/Observation 循环记录 ]);关键解析{tool_names}这是一个占位符LangChain Agent会在运行时自动将可用工具的名字列表如bash_command_executor, read_file, write_file, list_files填充到这里。这告诉LLM它可以做什么。{agent_scratchpad}这是ReAct Agent的记忆核心。在每一轮循环中Agent执行器Agent Executor会将上一轮的Thought、Action、Action Input以及系统得到的Observation按照格式追加到这个“草稿纸”上然后连同新的用户输入一起再次提交给LLM。这样LLM就拥有了完整的上下文来进行下一步推理。严格的输出格式我们强制要求LLM以Thought:、Action:、Final Answer:等关键词开头。Agent执行器会使用OutputParser来解析这些行提取出结构化数据如动作名称和输入。4.2 初始化LLM与创建智能体现在我们将提示词、LLM和工具组合起来创建出可运行的Agent。// src/agent/createAgent.ts import { OpenAI } from langchain/openai; import { initializeAgentExecutorWithOptions } from langchain/agents; import { ReActPromptTemplate } from ../prompts/reactPrompt.js; import { BashCommandTool } from ../tools/bashTool.js; import { ReadFileTool, WriteFileTool } from ../tools/fileTools.js; import { ListFilesTool } from ../tools/listFilesTool.js; import * as dotenv from dotenv; dotenv.config(); export async function createProgrammingAssistant() { // 1. 初始化LLM const llm new OpenAI({ openAIApiKey: process.env.OPENAI_API_KEY, temperature: 0.1, // 温度设低让输出更确定、更遵循格式 modelName: gpt-4, // 对于复杂推理GPT-4效果远好于GPT-3.5。也可用 gpt-3.5-turbo }); // 2. 准备工具数组 const tools [ new BashCommandTool(), new ReadFileTool(), new WriteFileTool(), new ListFilesTool(), // 未来可以轻松添加更多工具如代码搜索、API查询等 ]; // 3. 创建Agent执行器 const executor await initializeAgentExecutorWithOptions(tools, llm, { agentType: structured-chat-zero-shot-react-description, // 这是最接近我们手写ReAct提示词的Agent类型 agentArgs: { prefix: ReActPromptTemplate.promptMessages[0][1] as string, // 传入我们自定义的系统提示词 // LangChain内部会处理 {tool_names} 和 {agent_scratchpad} 的填充 }, verbose: true, // 打开详细日志可以看到每一步的Thought和Action便于调试 }); return executor; }参数与选型深度解读temperature设置为0.1范围0-2。较低的温度使LLM的输出更集中、更可预测这对于需要严格遵守输出格式的Agent至关重要。如果温度太高LLM可能会“放飞自我”不按格式输出导致解析失败。modelName强烈推荐使用gpt-4。在涉及多步骤推理、工具选择和长上下文理解的任务上GPT-4的可靠性和准确性远超GPT-3.5-turbo。虽然成本更高但对于学习核心概念和获得稳定体验是值得的。在实际产品中可以对简单任务降级使用GPT-3.5以节约成本。agentType我们选择了structured-chat-zero-shot-react-description。这是一个内置的Agent类型它使用类似ChatML的消息格式并且支持工具描述zero-shot其底层逻辑与ReAct范式一致。通过传入自定义的prefix我们覆盖了默认的系统提示使其完全遵循我们设计的ReAct流程。verbose: true开发阶段务必开启。它会在控制台打印出Agent完整的思考过程是理解和调试Agent行为不可或缺的窗口。4.3 创建主程序并运行测试让我们写一个主程序来启动助手并进行第一次对话。// src/index.ts import { createProgrammingAssistant } from ./agent/createAgent.js; async function main() { console.log( AI编程助手启动中...\n); const assistant await createProgrammingAssistant(); // 示例任务让助手创建一个简单的Node.js脚本并运行它 const task 请帮我做以下事情 1. 在当前目录下创建一个名为 hello_agent.js 的文件。 2. 文件内容应该是一个简单的Node.js HTTP服务器监听3000端口并返回“Hello from AI Agent!”。 3. 然后运行这个服务器并告诉我它是否成功启动。; console.log( 用户任务\n${task}\n); console.log(.repeat(50)); try { const result await assistant.invoke({ input: task }); console.log(\n .repeat(50)); console.log(✅ 任务完成助手回复\n${result.output}); } catch (error: any) { console.error(❌ 执行过程中出现错误, error.message); } } main();运行这个程序使用npx ts-node src/index.ts或配置好的npm script你将看到类似以下的输出verbose模式下的思考过程 AI编程助手启动中... 用户任务 请帮我做以下事情 1. 在当前目录下创建一个名为 hello_agent.js 的文件。 2. 文件内容应该是一个简单的Node.js HTTP服务器监听3000端口并返回“Hello from AI Agent!”。 3. 然后运行这个服务器并告诉我它是否成功启动。 [verbose] 进入新的Agent执行器调用... [verbose] 动作 list_files [verbose] 动作输入 . [verbose] 观察 目录 “.” 下的内容... [verbose] 思考 用户要求我创建一个文件并运行一个服务器。我需要先列出当前目录确保没有同名文件冲突。然后创建文件写入HTTP服务器代码。最后用Node运行它。 [verbose] 动作 write_file [verbose] 动作输入 {filepath: hello_agent.js, content: const http require(http);\nconst server http.createServer((req, res) {\n res.writeHead(200, { Content-Type: text/plain });\n res.end(Hello from AI Agent!);\n});\nserver.listen(3000, () {\n console.log(Server running on port 3000);\n});} [verbose] 观察 文件 “hello_agent.js” 写入成功。 [verbose] 思考 文件已创建。现在需要运行它。我将使用bash命令在后台启动服务器然后检查进程或端口来确认它是否运行。 [verbose] 动作 bash_command_executor [verbose] 动作输入 node hello_agent.js [verbose] 观察 命令执行成功。输出 Server running on port 3000 [verbose] 思考 服务器看起来启动成功了输出显示“Server running on port 3000”。为了进一步确认我可以检查3000端口是否在监听。 [verbose] 动作 bash_command_executor [verbose] 动作输入 lsof -i :3000 || netstat -an | grep 3000 [verbose] 观察 命令执行成功。输出 ... LISTEN ... [verbose] 思考 端口3000确实在监听说明服务器运行正常。我已经完成了用户的所有请求创建文件、写入代码、运行并验证服务器。 [verbose] 动作 最终答案 [verbose] 动作输入 我已经完成了任务。 ✅ 任务完成助手回复 我已经为您完成了任务 1. 成功创建了文件 hello_agent.js其中包含一个简单的Node.js HTTP服务器代码。 2. 已启动该服务器进程正在运行并在端口3000上监听。 3. 确认服务器启动成功可以响应请求。您可以通过访问 http://localhost:3000 来查看“Hello from AI Agent!”的响应。看你的AI编程助手已经活过来了。它能够理解多步骤任务自主规划调用工具并根据工具返回的结果调整后续动作最终圆满完成任务。这个完整的ReAct循环清晰地展现在我们面前。5. 高级功能扩展与优化策略一个基础的助手已经能工作但要让它更强大、更实用我们还需要进行一系列优化和功能扩展。5.1 工具增强更智能的文件与代码操作基础的文件读写工具功能单一。我们可以创建更贴合编程场景的“高级工具”。5.1.1 代码查找与替换工具// src/tools/advancedCodeTool.ts import { Tool } from langchain/core/tools; import fs from fs/promises; import path from path; export class FindInFilesTool extends Tool { name find_in_files; description 在指定目录的文件中搜索包含特定文本的行。输入是一个JSON字符串包含searchTerm搜索词和可选directory目录默认为当前目录。; protected async _call(inputStr: string): Promisestring { const { searchTerm, directory . } JSON.parse(inputStr); // 实现一个简单的递归文件搜索逻辑示例未处理大文件 // ... 实际实现需要遍历目录读取文件匹配内容 return 在目录 ${directory} 中搜索 ${searchTerm} 的结果是...; } } export class CodeModificationTool extends Tool { name modify_code_section; description 修改文件中特定部分的代码。输入是一个复杂的JSON指定文件路径、定位方式如函数名、行号范围和新代码内容。这需要更复杂的解析但能实现精准修改。; // 实现略 }5.1.2 集成外部API工具例如集成一个安全的代码片段搜索API如Stack Overflow或公共代码库的API让助手能获取最佳实践。export class SearchCodeSnippetTool extends Tool { name search_code_snippet; description 从可信的代码知识库中搜索关于特定编程问题的示例代码片段。输入是一个描述问题的字符串如“如何在JavaScript中深度克隆对象”。; protected async _call(query: string): Promisestring { // 调用外部API例如一个封装了公共代码搜索的服务 // const results await callSomeCodeSearchAPI(query); // return 搜索“${query}”的结果\n${results}; return 模拟关于“${query}”的推荐方案是使用 structuredClone() 或 JSON.parse(JSON.stringify(obj))。; } }5.2 记忆与上下文管理目前的Agent是“单次任务”型的没有对话记忆。我们可以为它添加记忆能力使其能处理像“把我刚才创建的文件里的端口号改成8080”这样的后续指令。LangChain提供了多种记忆方案。最简单的是BufferMemory它保存最近的对话历史。// 在创建Agent时添加记忆 import { BufferMemory } from langchain/memory; const executor await initializeAgentExecutorWithOptions(tools, llm, { agentType: structured-chat-zero-shot-react-description, agentArgs: { prefix: ReActPromptTemplate.promptMessages[0][1] as string, }, memory: new BufferMemory({ memoryKey: chat_history, // 这个key需要和提示词模板中的 {chat_history} 占位符对应 returnMessages: true, // 以消息格式返回 }), verbose: true, });同时需要更新提示词模板在合适的位置加入{chat_history}占位符我们在之前的模板中已经预留了。这样Agent就能记住之前的交互实现真正的多轮对话。5.3 输出解析与错误处理强化5.3.1 自定义OutputParser内置的解析器可能无法完美处理LLM所有可能的输出变体。我们可以自定义一个更健壮的解析器当解析失败时给LLM一个友好的错误提示让它重试。import { AgentActionOutputParser } from langchain/agents; import { OutputFixingParser } from langchain/output_parsers; // 可以创建一个包装器当解析失败时自动调用一个“修复”LLM来纠正格式。5.3.2 循环超时与中断Agent可能陷入死循环。必须设置超时和最大迭代次数。const executor await initializeAgentExecutorWithOptions(tools, llm, { // ... 其他配置 maxIterations: 15, // 最大循环次数防止无限循环 // earlyStoppingMethod: generate, // 可选提前停止策略 });在invoke时也可以设置超时const controller new AbortController(); setTimeout(() controller.abort(), 120000); // 2分钟超时 const result await assistant.invoke({ input: task }, { signal: controller.signal });5.4 安全与权限沙箱如前所述Bash工具极其危险。在生产环境中必须实施沙箱策略命令白名单/黑名单在工具内部解析命令禁止执行rm、sudo、wget、curl等高风险命令或只允许npm、git、ls、cat等安全命令。容器化执行在Docker容器内运行Agent的所有命令限制其对宿主机文件系统的访问。工具调用实际上是与容器内的Shell交互。人工审核层对于写文件、安装依赖等关键操作可以先让Agent生成一个“计划”或“变更摘要”经用户确认后再执行。项目目录锁定通过cwd参数将Agent的所有文件操作严格限制在指定的项目目录内禁止向上级目录穿越。6. 实战案例用AI助手初始化一个React项目让我们用一个更复杂的实战任务来检验助手的综合能力从零初始化一个标准的React项目并添加一些常用配置。我们将任务拆解给助手 “请帮我创建一个新的React项目使用Vite作为构建工具TypeScript作为开发语言。项目名称为‘my-ai-react-app’。然后安装React Router DOM版本6和Tailwind CSS。最后在src/App.tsx中将默认内容替换为一个简单的导航栏和欢迎语页面。”预期的理想执行流程思考需要创建项目、安装依赖、修改文件。先检查当前环境。行动调用bash_command_executor执行npm create vitelatest my-ai-react-app -- --template react-ts。观察Vite创建成功进入项目目录。思考进入项目目录安装额外依赖。行动调用bash_command_executor执行cd my-ai-react-app npm install react-router-dom6。行动调用bash_command_executor执行npm install -D tailwindcss postcss autoprefixer npx tailwindcss init -p。观察依赖安装成功Tailwind配置生成。思考需要修改src/App.tsx文件。先读取当前内容。行动调用read_file读取my-ai-react-app/src/App.tsx。观察看到默认的App组件代码。思考根据要求替换内容。需要写入新的代码。行动调用write_file将新的导航栏和欢迎语代码写入App.tsx。观察文件写入成功。思考任务完成。最终答案输出总结。实际运行中可能遇到的挑战与调优路径问题Agent在执行cd后后续命令的工作目录需要保持一致。我们的简单Bash工具每次调用都是独立的cd的效果不会延续。解决方案有两种1) 修改Bash工具使其支持“会话状态”复杂2) 在提示词中教导Agent对于需要在特定目录下执行的命令使用cd path command的格式。我们采用第二种。依赖安装冲突npm install可能会因为网络或版本问题失败。Agent需要能解析npm的错误信息并尝试修复如npm cache clean --force或调整版本。这需要更复杂的错误处理逻辑或者在工具描述中引导LLM进行常见故障排查。文件内容替换的精确性直接覆盖整个App.tsx是粗暴的。更好的方式是让Agent先读取文件分析结构然后进行精准的代码块替换。这需要更强大的CodeModificationTool。通过这个案例你可以清晰地看到将一个高级别需求转化为一系列具体工具调用的完整链条也能体会到设计一个鲁棒的、能处理各种边缘情况的AI助手所面临的挑战。7. 常见问题排查与性能调优指南在开发和运行此类AI Agent的过程中你会遇到各种各样的问题。下面是我踩过的一些坑和总结的解决方案。7.1 Agent陷入循环或行为怪异症状Agent不停地重复类似的动作如反复列出同一个目录或者执行与任务无关的操作。排查与解决检查verbose日志这是最重要的调试信息。看它的Thought是否合理是否误解了任务或观察结果优化工具描述Description工具描述是LLM决定是否调用该工具的“说明书”。描述必须清晰、无歧义、准确说明输入格式和功能。模糊的描述会导致LLM误用工具。例如BashCommandTool的描述要强调“输入是一个完整的、可执行的Bash命令字符串”。调整提示词Prompt在系统提示词中更加强调任务目标或加入一些约束例如“如果你连续三次执行了相似且无进展的动作你应该认为当前策略失败并尝试新的方法或者输出最终答案说明遇到了障碍。”降低temperature尝试将LLM的temperature降到0使其输出更确定、更遵循指令。设置maxIterations务必设置一个合理的最大迭代次数如20作为安全网。7.2 LLM不按格式输出导致解析失败症状控制台报错提示无法解析LLM的输出找不到Action:或Thought:等关键字。排查与解决强化格式要求在系统提示词的开头用非常醒目的方式如格式强调输出格式并给出多个清晰的例子。使用更强的模型GPT-4在遵循复杂指令方面远优于GPT-3.5-turbo。如果使用3.5此问题会更频繁。实现OutputFixingParser使用LangChain的OutputFixingParser它可以在解析失败时自动调用另一个LLM来修复格式错误的输出。检查上下文长度如果agent_scratchpad变得非常长多次循环后可能会超出模型的上下文窗口导致输出质量下降或格式混乱。考虑使用ConversationSummaryMemory等记忆方式来压缩历史。7.3 工具执行错误但Agent无法恢复症状工具调用失败如命令执行错误、文件不存在Agent的后续推理陷入混乱或者简单地放弃了。排查与解决提供清晰的错误反馈工具在返回错误信息时要提供结构化、可读的说明。不要只返回原始的异常堆栈。例如“文件读取失败ENOENT: no such file or directory, open ‘nonexistent.js’” 就比一长串错误堆栈更好。在提示词中训练Agent在系统提示词中加入如何处理错误的指导例如“如果工具返回错误信息仔细阅读错误分析原因并调整你的策略。例如如果‘文件不存在’你可以先创建它如果‘命令未找到’检查你是否拼写错误或需要先安装某个软件。”设计更鲁棒的工具例如WriteFileTool可以在写入前检查目录是否存在如果不存在则自动创建减少失败概率。7.4 性能与成本优化问题复杂任务需要很多次ReAct循环每次循环都是一次LLM API调用对于GPT-4来说成本不菲且速度较慢。优化策略任务分解与规划对于非常复杂的任务可以引入一个“规划”步骤。先用一次LLM调用将大任务分解成清晰的子任务列表然后再让ReAct Agent逐个执行。这样既能避免Agent在宏观规划上迷失也能让人类对整个过程有更好的掌控。使用更便宜的模型进行简单决策可以设计一个双模型系统。让GPT-4负责复杂的规划、推理和代码生成而让GPT-3.5-turbo负责简单的、格式固定的工具调用决策。这需要对Agent架构进行更精细的设计。缓存Caching对于相同的提示词和输入使用LangChain的缓存功能如InMemoryCache或RedisCache来避免重复调用LLM这在开发调试阶段特别有用。限制工具集只提供任务必需的工具。工具越多LLM需要理解和选择的复杂度就越高可能增加不必要的思考步骤。构建一个稳定、高效的AI编程助手是一个持续迭代的过程。从最简单的ReAct循环开始逐步增加工具、优化提示、处理边界情况你会对AI Agent的能力和局限有越来越深刻的理解。这个项目不仅仅是一个工具更是一个理解下一代AI应用交互范式的绝佳窗口。 基于LangChain.js与ReAct范式：从零构建可解释的AI编程助手
1. 项目概述为什么我们要亲手打造一个AI编程助手最近在社区里看到不少关于AI编程助手的讨论从Copilot到Cursor这些工具确实能极大提升开发效率。但作为一个喜欢“知其所以然”的开发者我总觉得直接使用现成的黑盒工具少了点什么。当代码补全出现一个奇怪的推荐或者Agent执行了一个匪夷所思的操作时我们往往只能挠头因为其内部的决策逻辑对我们而言是不透明的。这正是我决定动手“从零实现”一个AI编程助手的核心动机。这个“从零”并非指从Transformer模型开始训练那对我们大多数应用开发者来说既不现实也无必要。这里的“从零”指的是从最核心的“大脑”与“执行”框架开始搭建让我们能清晰地看到AI助手是如何理解我们的意图、规划步骤、调用工具并最终完成任务的。通过这个过程我们不仅能获得一个可高度定制、完全可控的助手更能深入理解现代AI应用架构的核心——智能体Agent的工作机制。我选择了LangChain.js作为框架因为它为构建基于大语言模型LLM的应用提供了极佳的抽象和工具链。而实现逻辑则采用了ReActReasoning Acting范式这是一种让AI“思考-行动”循环的经典模式非常适合需要多步骤工具调用的编程场景。简单来说我们的助手会像人类程序员一样先“思考”分析问题、制定计划再“行动”执行命令、查看结果根据结果再次“思考”如此循环直到任务完成。这个项目适合谁呢如果你是对AI应用开发感兴趣的JavaScript/TypeScript开发者想超越简单的API调用深入Agent和工具调用的世界或者你是一名全栈工程师希望为自己的团队或产品嵌入一个智能的、可解释的自动化编程模块那么跟着这篇实战走一遍你会收获远超一个Demo的认知。我们将从环境搭建开始一步步构建一个能理解自然语言编程需求、并实际在命令行中执行Bash命令、读写文件、甚至运行测试的AI编程助手。2. 核心架构与ReAct范式深度解析在开始写代码之前我们必须把核心的架构思想搞清楚。为什么是LangChain.js ReAct这个组合到底解决了什么问题2.1 LangChain.js不只是LLM的“胶水”很多人初识LangChain会把它简单理解为连接LLM API的封装库。这低估了它的价值。LangChain的核心贡献在于提供了一套用于构建基于LLM的应用程序的设计模式和组件化抽象。对于我们的编程助手项目它主要解决了以下痛点工具Tools的标准化与管理我们的助手需要调用外部能力比如执行Bash命令、读写文件、搜索文档。LangChain定义了统一的Tool接口每个工具都有name、description和call方法。这让我们可以像搭积木一样轻松地组合和扩展助手的能力。更重要的是LLM通过阅读规范的description就能学会在何时调用哪个工具。提示词Prompt的工程化直接拼接字符串构造提示词是脆弱且难以维护的。LangChain提供了PromptTemplate、ChatPromptTemplate等组件支持变量注入、部分填充和不同消息角色System, Human, AI的结构化组织。这对于构建复杂的、多步骤的ReAct提示词至关重要。记忆Memory与状态管理一个有用的助手需要记住对话上下文。LangChain提供了从简单的缓冲区到基于向量数据库的长期记忆等多种记忆方案方便我们为助手添加上下文感知能力。链Chains与智能体Agents的高层抽象这是最核心的部分。Chain将LLM、提示词、工具等组件按固定顺序组合。而Agent是一种特殊的Chain它的核心是动态决策由LLM根据当前状态和可用工具决定下一步做什么。这完美契合了ReAct范式。选择LangChain.js而非Python版本主要是考虑到JavaScript/TypeScript生态在现代Web和Node.js后端开发中的普及性以及其异步和非阻塞I/O模型与LLM调用天生契合。2.2 ReAct范式让AI学会“三思而后行”ReActReasoning Acting是由Princeton和Google的研究者提出的一种范式旨在提升LLM在复杂任务中的可靠性和可解释性。其核心思想是模仿人类的解决问题方式Reasoning思考LLM生成一段自由形式的推理轨迹分析当前情况、解释为何做出某个决策、或拆解下一步计划。这部分内容通常对人类可见极大地增强了过程的可解释性。Acting行动根据推理LLM决定并执行一个具体的动作通常是调用一个预定义的工具Tool并获取工具的返回结果Observation。这个“思考 - 行动 - 观察结果 - 再思考”的循环会一直持续直到LLM认为任务完成并输出最终答案Final Answer。为什么ReAct特别适合编程助手编程任务本质上是复杂、多步骤的。比如用户要求“为我的Express项目添加一个用户登录接口”。一个简单的单次问答LLM可能会直接生成一大段代码但很可能遗漏创建路由文件、安装依赖包、配置数据库连接等步骤。而采用ReAct的助手则会思考“用户需要添加登录接口。我需要先检查项目结构确定路由文件位置。然后需要安装bcrypt和jsonwebtoken依赖。接着要创建用户模型如果不存在最后编写登录路由逻辑和中间件。”行动调用ListFilesTool查看项目目录。观察看到现有文件结构。思考“项目使用/routes目录。我需要先安装依赖。”行动调用BashCommandTool执行npm install bcrypt jsonwebtoken。观察安装成功。思考“现在检查是否有用户模型User.js…”… 如此循环直到所有步骤完成。这个过程不仅更可靠而且我们可以在每个循环看到AI的“思路”如果它跑偏了我们能及时干预或调整工具描述。2.3 我们的助手架构设计基于以上理解我们项目的核心架构图概念上如下用户输入自然语言指令 | v [ReAct 智能体 (Agent)] | |-- 核心LLM (如 OpenAI GPT-4) |-- 决策逻辑ReAct 专用提示词模板 |-- 可用工具集Bash工具、文件工具等 | v 循环开始 | [思考步骤] - LLM生成推理和下一步动作决定 | v [动作步骤] - 解析决定调用对应工具 | v [观察步骤] - 获取工具执行结果 | v 判断是否完成 --否-- 进入下一轮循环 | 是 v 输出最终结果给用户这个架构中提示词模板是驱动整个ReAct循环的“大脑程序”它规定了LLM输出的格式使其严格遵循“Thought: ... Action: ... Observation: ...”的循环。我们将在下一章具体实现它。3. 环境准备与核心工具实现“工欲善其事必先利其器”。在编写智能体之前我们需要搭建好开发环境并实现那些让AI拥有“手和脚”的工具。3.1 项目初始化与依赖安装首先创建一个新的Node.js项目并安装核心依赖。mkdir ai-programming-assistant cd ai-programming-assistant npm init -y接下来安装依赖。我们将使用TypeScript以获得更好的类型安全。npm install langchain langchain/core openai npm install -D typescript types/node ts-node nodemonlangchain LangChain核心库。langchain/core 包含一些核心抽象和类型。openai OpenAI官方Node.js SDKLangChain会用到它。其余是TypeScript开发环境依赖。初始化TypeScript配置npx tsc --init在生成的tsconfig.json中确保target是ES2020或更高module是commonjsNode.js环境并设置outDir为./dist。现在我们需要一个.env文件来管理敏感信息比如OpenAI的API密钥。创建.env文件OPENAI_API_KEY你的_OpenAI_API_密钥重要安全提示永远不要将.env文件提交到版本控制系统如Git。请确保它在.gitignore中。在代码中我们使用dotenv包来加载这些变量。运行npm install dotenv并安装types/dotenv作为开发依赖。3.2 构建核心工具集赋予AI“动手能力”工具是Agent与外界交互的桥梁。我们将实现几个编程助手最常用的工具。3.2.1 Bash命令执行工具这是最重要的工具让助手能在项目目录下执行任何Shell命令。// src/tools/bashTool.ts import { Tool } from langchain/core/tools; import { exec } from child_process; import { promisify } from util; const execAsync promisify(exec); export class BashCommandTool extends Tool { name bash_command_executor; description 执行一个Bash shell命令。用于运行程序、安装依赖、执行脚本等。输入应该是一个合法的Bash命令字符串。; protected async _call(arg: string): Promisestring { // arg 就是LLM决定要执行的命令例如 ls -la 或 npm install express try { const { stdout, stderr } await execAsync(arg, { cwd: process.cwd() }); // 在当前工作目录执行 if (stderr) { // 有些命令如某些npm警告会输出到stderr但不代表失败。我们将其与stdout一起返回。 return 命令执行完成。标准输出\n${stdout}\n标准错误可能是警告\n${stderr}; } return 命令执行成功。输出\n${stdout}; } catch (error: any) { // 命令执行失败返回非0状态码 return 命令执行失败。错误信息${error.message}\n标准错误输出${error.stderr}; } } }注意事项与心得工作目录cwd这里固定为process.cwd()即启动Node进程的目录。在实际产品中你可能需要让助手感知“当前项目”目录并将其作为上下文传递给工具。安全性这是一个极高风险的工具AI可能会执行rm -rf /或下载恶意脚本。绝对不要在生产环境或存有重要数据的目录下未经审查地运行此类Agent。一种缓解策略是实现一个“批准”层或者在工具描述中强调“仅用于项目开发操作”并限制命令白名单尽管这很复杂。对于学习项目保持警惕并在安全隔离的环境中进行。错误处理我们将错误信息格式化后返回给Agent。LLM可以读取这些错误并调整策略这是ReAct循环能自我修正的关键。3.2.2 文件读写工具让助手能够查看和修改代码文件。// src/tools/fileTools.ts import { Tool } from langchain/core/tools; import fs from fs/promises; import path from path; export class ReadFileTool extends Tool { name read_file; description 读取指定路径文件的内容。输入应该是文件的相对或绝对路径。; protected async _call(filePath: string): Promisestring { try { const content await fs.readFile(filePath, utf-8); return 文件 ${filePath} 的内容如下\n\\\\n${content}\n\\\; } catch (error: any) { return 读取文件失败${error.message}; } } } export class WriteFileTool extends Tool { name write_file; description 将内容写入指定路径的文件。如果文件存在则覆盖。输入应该是一个JSON字符串包含filepath和content两个键。例如{filepath: test.js, content: console.log(hello)}; protected async _call(inputStr: string): Promisestring { try { const { filepath, content } JSON.parse(inputStr); await fs.writeFile(filepath, content, utf-8); return 文件 ${filepath} 写入成功。; } catch (error: any) { return 写入文件失败${error.message}; } } }实操要点输入格式WriteFileTool要求JSON输入这比让LLM自己拼接一个模糊的字符串更可靠。在工具描述中清晰定义输入格式是构建稳定Agent的关键。路径处理这里使用了简单的路径。复杂场景下你可能需要解析相对于项目根目录的路径。代码块格式化在ReadFileTool的返回中我们用Markdown代码块包裹内容。这能帮助LLM更好地理解这是代码片段尤其是在后续的推理中。3.2.3 文件列表工具让助手能浏览项目结构。// src/tools/listFilesTool.ts import { Tool } from langchain/core/tools; import fs from fs/promises; import path from path; export class ListFilesTool extends Tool { name list_files; description 列出指定目录下的文件和文件夹。输入可以是一个目录路径默认为当前目录“.”。对于了解项目结构非常有用。; protected async _call(dirPath: string .): Promisestring { try { const items await fs.readdir(dirPath, { withFileTypes: true }); const itemList items.map((item) { const type item.isDirectory() ? [目录] : [文件]; return ${type} ${item.name}; }); return 目录 ${dirPath} 下的内容\n${itemList.join(\n)}; } catch (error: any) { return 列出文件失败${error.message}; } } }有了这些基础工具我们的AI助手就具备了感知和操作项目环境的基本能力。接下来我们需要组装它的“大脑”。4. 构建ReAct智能体组装大脑与决策循环这是整个项目的核心。我们将创建ReAct提示词模板初始化LLM并将工具整合到Agent中形成完整的决策循环。4.1 设计ReAct提示词模板提示词是指导LLM行为的“程序”。ReAct模式的提示词需要明确告诉LLM你需要循环思考、行动、观察并使用特定的格式输出。// src/prompts/reactPrompt.ts import { ChatPromptTemplate } from langchain/core/prompts; export const ReActPromptTemplate ChatPromptTemplate.fromMessages([ [ system, 你是一个强大的AI编程助手可以通过调用工具来帮助用户完成编程任务。 你运行在一个安全的开发环境中可以执行Bash命令、读写文件、浏览目录。 请严格遵循以下格式进行响应 Thought: 你需要在这里思考当前情况。分析用户的目标回顾之前的观察并决定下一步该做什么。解释你的推理过程。 Action: 你需要在这里声明要执行的动作。必须是以下工具之一{tool_names} Action Input: 你选择工具所需要的输入内容。 Observation: 工具执行后的结果会放在这里这不是由你生成的而是系统填充的。 当你确信已经完成了用户的所有请求或者无法继续时你必须输出 Thought: 我已经完成了任务。 Final Answer: [这里放置你对用户的最终答复总结你所做的工作或提供最终结果。] 让我们开始吧 ], [placeholder, {chat_history}], // 用于放置对话历史如果有多轮 [human, {input}], // 用户的当前问题 [placeholder, {agent_scratchpad}], // 关键这里将自动填充之前的 Thought/Action/Observation 循环记录 ]);关键解析{tool_names}这是一个占位符LangChain Agent会在运行时自动将可用工具的名字列表如bash_command_executor, read_file, write_file, list_files填充到这里。这告诉LLM它可以做什么。{agent_scratchpad}这是ReAct Agent的记忆核心。在每一轮循环中Agent执行器Agent Executor会将上一轮的Thought、Action、Action Input以及系统得到的Observation按照格式追加到这个“草稿纸”上然后连同新的用户输入一起再次提交给LLM。这样LLM就拥有了完整的上下文来进行下一步推理。严格的输出格式我们强制要求LLM以Thought:、Action:、Final Answer:等关键词开头。Agent执行器会使用OutputParser来解析这些行提取出结构化数据如动作名称和输入。4.2 初始化LLM与创建智能体现在我们将提示词、LLM和工具组合起来创建出可运行的Agent。// src/agent/createAgent.ts import { OpenAI } from langchain/openai; import { initializeAgentExecutorWithOptions } from langchain/agents; import { ReActPromptTemplate } from ../prompts/reactPrompt.js; import { BashCommandTool } from ../tools/bashTool.js; import { ReadFileTool, WriteFileTool } from ../tools/fileTools.js; import { ListFilesTool } from ../tools/listFilesTool.js; import * as dotenv from dotenv; dotenv.config(); export async function createProgrammingAssistant() { // 1. 初始化LLM const llm new OpenAI({ openAIApiKey: process.env.OPENAI_API_KEY, temperature: 0.1, // 温度设低让输出更确定、更遵循格式 modelName: gpt-4, // 对于复杂推理GPT-4效果远好于GPT-3.5。也可用 gpt-3.5-turbo }); // 2. 准备工具数组 const tools [ new BashCommandTool(), new ReadFileTool(), new WriteFileTool(), new ListFilesTool(), // 未来可以轻松添加更多工具如代码搜索、API查询等 ]; // 3. 创建Agent执行器 const executor await initializeAgentExecutorWithOptions(tools, llm, { agentType: structured-chat-zero-shot-react-description, // 这是最接近我们手写ReAct提示词的Agent类型 agentArgs: { prefix: ReActPromptTemplate.promptMessages[0][1] as string, // 传入我们自定义的系统提示词 // LangChain内部会处理 {tool_names} 和 {agent_scratchpad} 的填充 }, verbose: true, // 打开详细日志可以看到每一步的Thought和Action便于调试 }); return executor; }参数与选型深度解读temperature设置为0.1范围0-2。较低的温度使LLM的输出更集中、更可预测这对于需要严格遵守输出格式的Agent至关重要。如果温度太高LLM可能会“放飞自我”不按格式输出导致解析失败。modelName强烈推荐使用gpt-4。在涉及多步骤推理、工具选择和长上下文理解的任务上GPT-4的可靠性和准确性远超GPT-3.5-turbo。虽然成本更高但对于学习核心概念和获得稳定体验是值得的。在实际产品中可以对简单任务降级使用GPT-3.5以节约成本。agentType我们选择了structured-chat-zero-shot-react-description。这是一个内置的Agent类型它使用类似ChatML的消息格式并且支持工具描述zero-shot其底层逻辑与ReAct范式一致。通过传入自定义的prefix我们覆盖了默认的系统提示使其完全遵循我们设计的ReAct流程。verbose: true开发阶段务必开启。它会在控制台打印出Agent完整的思考过程是理解和调试Agent行为不可或缺的窗口。4.3 创建主程序并运行测试让我们写一个主程序来启动助手并进行第一次对话。// src/index.ts import { createProgrammingAssistant } from ./agent/createAgent.js; async function main() { console.log( AI编程助手启动中...\n); const assistant await createProgrammingAssistant(); // 示例任务让助手创建一个简单的Node.js脚本并运行它 const task 请帮我做以下事情 1. 在当前目录下创建一个名为 hello_agent.js 的文件。 2. 文件内容应该是一个简单的Node.js HTTP服务器监听3000端口并返回“Hello from AI Agent!”。 3. 然后运行这个服务器并告诉我它是否成功启动。; console.log( 用户任务\n${task}\n); console.log(.repeat(50)); try { const result await assistant.invoke({ input: task }); console.log(\n .repeat(50)); console.log(✅ 任务完成助手回复\n${result.output}); } catch (error: any) { console.error(❌ 执行过程中出现错误, error.message); } } main();运行这个程序使用npx ts-node src/index.ts或配置好的npm script你将看到类似以下的输出verbose模式下的思考过程 AI编程助手启动中... 用户任务 请帮我做以下事情 1. 在当前目录下创建一个名为 hello_agent.js 的文件。 2. 文件内容应该是一个简单的Node.js HTTP服务器监听3000端口并返回“Hello from AI Agent!”。 3. 然后运行这个服务器并告诉我它是否成功启动。 [verbose] 进入新的Agent执行器调用... [verbose] 动作 list_files [verbose] 动作输入 . [verbose] 观察 目录 “.” 下的内容... [verbose] 思考 用户要求我创建一个文件并运行一个服务器。我需要先列出当前目录确保没有同名文件冲突。然后创建文件写入HTTP服务器代码。最后用Node运行它。 [verbose] 动作 write_file [verbose] 动作输入 {filepath: hello_agent.js, content: const http require(http);\nconst server http.createServer((req, res) {\n res.writeHead(200, { Content-Type: text/plain });\n res.end(Hello from AI Agent!);\n});\nserver.listen(3000, () {\n console.log(Server running on port 3000);\n});} [verbose] 观察 文件 “hello_agent.js” 写入成功。 [verbose] 思考 文件已创建。现在需要运行它。我将使用bash命令在后台启动服务器然后检查进程或端口来确认它是否运行。 [verbose] 动作 bash_command_executor [verbose] 动作输入 node hello_agent.js [verbose] 观察 命令执行成功。输出 Server running on port 3000 [verbose] 思考 服务器看起来启动成功了输出显示“Server running on port 3000”。为了进一步确认我可以检查3000端口是否在监听。 [verbose] 动作 bash_command_executor [verbose] 动作输入 lsof -i :3000 || netstat -an | grep 3000 [verbose] 观察 命令执行成功。输出 ... LISTEN ... [verbose] 思考 端口3000确实在监听说明服务器运行正常。我已经完成了用户的所有请求创建文件、写入代码、运行并验证服务器。 [verbose] 动作 最终答案 [verbose] 动作输入 我已经完成了任务。 ✅ 任务完成助手回复 我已经为您完成了任务 1. 成功创建了文件 hello_agent.js其中包含一个简单的Node.js HTTP服务器代码。 2. 已启动该服务器进程正在运行并在端口3000上监听。 3. 确认服务器启动成功可以响应请求。您可以通过访问 http://localhost:3000 来查看“Hello from AI Agent!”的响应。看你的AI编程助手已经活过来了。它能够理解多步骤任务自主规划调用工具并根据工具返回的结果调整后续动作最终圆满完成任务。这个完整的ReAct循环清晰地展现在我们面前。5. 高级功能扩展与优化策略一个基础的助手已经能工作但要让它更强大、更实用我们还需要进行一系列优化和功能扩展。5.1 工具增强更智能的文件与代码操作基础的文件读写工具功能单一。我们可以创建更贴合编程场景的“高级工具”。5.1.1 代码查找与替换工具// src/tools/advancedCodeTool.ts import { Tool } from langchain/core/tools; import fs from fs/promises; import path from path; export class FindInFilesTool extends Tool { name find_in_files; description 在指定目录的文件中搜索包含特定文本的行。输入是一个JSON字符串包含searchTerm搜索词和可选directory目录默认为当前目录。; protected async _call(inputStr: string): Promisestring { const { searchTerm, directory . } JSON.parse(inputStr); // 实现一个简单的递归文件搜索逻辑示例未处理大文件 // ... 实际实现需要遍历目录读取文件匹配内容 return 在目录 ${directory} 中搜索 ${searchTerm} 的结果是...; } } export class CodeModificationTool extends Tool { name modify_code_section; description 修改文件中特定部分的代码。输入是一个复杂的JSON指定文件路径、定位方式如函数名、行号范围和新代码内容。这需要更复杂的解析但能实现精准修改。; // 实现略 }5.1.2 集成外部API工具例如集成一个安全的代码片段搜索API如Stack Overflow或公共代码库的API让助手能获取最佳实践。export class SearchCodeSnippetTool extends Tool { name search_code_snippet; description 从可信的代码知识库中搜索关于特定编程问题的示例代码片段。输入是一个描述问题的字符串如“如何在JavaScript中深度克隆对象”。; protected async _call(query: string): Promisestring { // 调用外部API例如一个封装了公共代码搜索的服务 // const results await callSomeCodeSearchAPI(query); // return 搜索“${query}”的结果\n${results}; return 模拟关于“${query}”的推荐方案是使用 structuredClone() 或 JSON.parse(JSON.stringify(obj))。; } }5.2 记忆与上下文管理目前的Agent是“单次任务”型的没有对话记忆。我们可以为它添加记忆能力使其能处理像“把我刚才创建的文件里的端口号改成8080”这样的后续指令。LangChain提供了多种记忆方案。最简单的是BufferMemory它保存最近的对话历史。// 在创建Agent时添加记忆 import { BufferMemory } from langchain/memory; const executor await initializeAgentExecutorWithOptions(tools, llm, { agentType: structured-chat-zero-shot-react-description, agentArgs: { prefix: ReActPromptTemplate.promptMessages[0][1] as string, }, memory: new BufferMemory({ memoryKey: chat_history, // 这个key需要和提示词模板中的 {chat_history} 占位符对应 returnMessages: true, // 以消息格式返回 }), verbose: true, });同时需要更新提示词模板在合适的位置加入{chat_history}占位符我们在之前的模板中已经预留了。这样Agent就能记住之前的交互实现真正的多轮对话。5.3 输出解析与错误处理强化5.3.1 自定义OutputParser内置的解析器可能无法完美处理LLM所有可能的输出变体。我们可以自定义一个更健壮的解析器当解析失败时给LLM一个友好的错误提示让它重试。import { AgentActionOutputParser } from langchain/agents; import { OutputFixingParser } from langchain/output_parsers; // 可以创建一个包装器当解析失败时自动调用一个“修复”LLM来纠正格式。5.3.2 循环超时与中断Agent可能陷入死循环。必须设置超时和最大迭代次数。const executor await initializeAgentExecutorWithOptions(tools, llm, { // ... 其他配置 maxIterations: 15, // 最大循环次数防止无限循环 // earlyStoppingMethod: generate, // 可选提前停止策略 });在invoke时也可以设置超时const controller new AbortController(); setTimeout(() controller.abort(), 120000); // 2分钟超时 const result await assistant.invoke({ input: task }, { signal: controller.signal });5.4 安全与权限沙箱如前所述Bash工具极其危险。在生产环境中必须实施沙箱策略命令白名单/黑名单在工具内部解析命令禁止执行rm、sudo、wget、curl等高风险命令或只允许npm、git、ls、cat等安全命令。容器化执行在Docker容器内运行Agent的所有命令限制其对宿主机文件系统的访问。工具调用实际上是与容器内的Shell交互。人工审核层对于写文件、安装依赖等关键操作可以先让Agent生成一个“计划”或“变更摘要”经用户确认后再执行。项目目录锁定通过cwd参数将Agent的所有文件操作严格限制在指定的项目目录内禁止向上级目录穿越。6. 实战案例用AI助手初始化一个React项目让我们用一个更复杂的实战任务来检验助手的综合能力从零初始化一个标准的React项目并添加一些常用配置。我们将任务拆解给助手 “请帮我创建一个新的React项目使用Vite作为构建工具TypeScript作为开发语言。项目名称为‘my-ai-react-app’。然后安装React Router DOM版本6和Tailwind CSS。最后在src/App.tsx中将默认内容替换为一个简单的导航栏和欢迎语页面。”预期的理想执行流程思考需要创建项目、安装依赖、修改文件。先检查当前环境。行动调用bash_command_executor执行npm create vitelatest my-ai-react-app -- --template react-ts。观察Vite创建成功进入项目目录。思考进入项目目录安装额外依赖。行动调用bash_command_executor执行cd my-ai-react-app npm install react-router-dom6。行动调用bash_command_executor执行npm install -D tailwindcss postcss autoprefixer npx tailwindcss init -p。观察依赖安装成功Tailwind配置生成。思考需要修改src/App.tsx文件。先读取当前内容。行动调用read_file读取my-ai-react-app/src/App.tsx。观察看到默认的App组件代码。思考根据要求替换内容。需要写入新的代码。行动调用write_file将新的导航栏和欢迎语代码写入App.tsx。观察文件写入成功。思考任务完成。最终答案输出总结。实际运行中可能遇到的挑战与调优路径问题Agent在执行cd后后续命令的工作目录需要保持一致。我们的简单Bash工具每次调用都是独立的cd的效果不会延续。解决方案有两种1) 修改Bash工具使其支持“会话状态”复杂2) 在提示词中教导Agent对于需要在特定目录下执行的命令使用cd path command的格式。我们采用第二种。依赖安装冲突npm install可能会因为网络或版本问题失败。Agent需要能解析npm的错误信息并尝试修复如npm cache clean --force或调整版本。这需要更复杂的错误处理逻辑或者在工具描述中引导LLM进行常见故障排查。文件内容替换的精确性直接覆盖整个App.tsx是粗暴的。更好的方式是让Agent先读取文件分析结构然后进行精准的代码块替换。这需要更强大的CodeModificationTool。通过这个案例你可以清晰地看到将一个高级别需求转化为一系列具体工具调用的完整链条也能体会到设计一个鲁棒的、能处理各种边缘情况的AI助手所面临的挑战。7. 常见问题排查与性能调优指南在开发和运行此类AI Agent的过程中你会遇到各种各样的问题。下面是我踩过的一些坑和总结的解决方案。7.1 Agent陷入循环或行为怪异症状Agent不停地重复类似的动作如反复列出同一个目录或者执行与任务无关的操作。排查与解决检查verbose日志这是最重要的调试信息。看它的Thought是否合理是否误解了任务或观察结果优化工具描述Description工具描述是LLM决定是否调用该工具的“说明书”。描述必须清晰、无歧义、准确说明输入格式和功能。模糊的描述会导致LLM误用工具。例如BashCommandTool的描述要强调“输入是一个完整的、可执行的Bash命令字符串”。调整提示词Prompt在系统提示词中更加强调任务目标或加入一些约束例如“如果你连续三次执行了相似且无进展的动作你应该认为当前策略失败并尝试新的方法或者输出最终答案说明遇到了障碍。”降低temperature尝试将LLM的temperature降到0使其输出更确定、更遵循指令。设置maxIterations务必设置一个合理的最大迭代次数如20作为安全网。7.2 LLM不按格式输出导致解析失败症状控制台报错提示无法解析LLM的输出找不到Action:或Thought:等关键字。排查与解决强化格式要求在系统提示词的开头用非常醒目的方式如格式强调输出格式并给出多个清晰的例子。使用更强的模型GPT-4在遵循复杂指令方面远优于GPT-3.5-turbo。如果使用3.5此问题会更频繁。实现OutputFixingParser使用LangChain的OutputFixingParser它可以在解析失败时自动调用另一个LLM来修复格式错误的输出。检查上下文长度如果agent_scratchpad变得非常长多次循环后可能会超出模型的上下文窗口导致输出质量下降或格式混乱。考虑使用ConversationSummaryMemory等记忆方式来压缩历史。7.3 工具执行错误但Agent无法恢复症状工具调用失败如命令执行错误、文件不存在Agent的后续推理陷入混乱或者简单地放弃了。排查与解决提供清晰的错误反馈工具在返回错误信息时要提供结构化、可读的说明。不要只返回原始的异常堆栈。例如“文件读取失败ENOENT: no such file or directory, open ‘nonexistent.js’” 就比一长串错误堆栈更好。在提示词中训练Agent在系统提示词中加入如何处理错误的指导例如“如果工具返回错误信息仔细阅读错误分析原因并调整你的策略。例如如果‘文件不存在’你可以先创建它如果‘命令未找到’检查你是否拼写错误或需要先安装某个软件。”设计更鲁棒的工具例如WriteFileTool可以在写入前检查目录是否存在如果不存在则自动创建减少失败概率。7.4 性能与成本优化问题复杂任务需要很多次ReAct循环每次循环都是一次LLM API调用对于GPT-4来说成本不菲且速度较慢。优化策略任务分解与规划对于非常复杂的任务可以引入一个“规划”步骤。先用一次LLM调用将大任务分解成清晰的子任务列表然后再让ReAct Agent逐个执行。这样既能避免Agent在宏观规划上迷失也能让人类对整个过程有更好的掌控。使用更便宜的模型进行简单决策可以设计一个双模型系统。让GPT-4负责复杂的规划、推理和代码生成而让GPT-3.5-turbo负责简单的、格式固定的工具调用决策。这需要对Agent架构进行更精细的设计。缓存Caching对于相同的提示词和输入使用LangChain的缓存功能如InMemoryCache或RedisCache来避免重复调用LLM这在开发调试阶段特别有用。限制工具集只提供任务必需的工具。工具越多LLM需要理解和选择的复杂度就越高可能增加不必要的思考步骤。构建一个稳定、高效的AI编程助手是一个持续迭代的过程。从最简单的ReAct循环开始逐步增加工具、优化提示、处理边界情况你会对AI Agent的能力和局限有越来越深刻的理解。这个项目不仅仅是一个工具更是一个理解下一代AI应用交互范式的绝佳窗口。