基于Deepseek与LangChain构建代码智能体：从概念到工程实践

最近在技术社区看到不少关于“Deepseek Harness 团队”和“代码智能体”的讨论，很多开发者对如何将这类前沿的AI能力集成到自己的开发工作流中充满兴趣，但苦于资料零散，概念混杂。本文旨在系统性地梳理“代码智能体”的核心概念，并以Deepseek模型为例，提供一个从零到一的实战集成指南。无论你是想提升个人编码效率，还是为团队探索AI辅助开发的工程化方案，这篇文章都将为你提供一套清晰、可落地的技术路径。

1. 代码智能体：概念、价值与生态

在深入技术细节之前，我们有必要厘清几个核心概念。这能帮助我们在纷繁的信息中抓住重点，理解我们到底在构建什么。

1.1 什么是代码智能体？

代码智能体（Code Agent）并非一个全新的、独立的软件产品。它本质上是一种应用模式或架构思想。其核心是利用大型语言模型（LLM）的能力，通过特定的工程化框架（Harness），将模型“封装”成一个能够理解开发上下文、执行编码任务、并与开发环境交互的智能体。

你可以把它想象成一个高度专业化的AI助手，但它不是简单的聊天机器人。一个真正的代码智能体具备以下特征：

• 上下文感知：能读取项目中的特定文件、理解代码结构、识别编程语言。
• 工具调用能力：可以执行诸如读取文件、写入文件、运行终端命令、调用外部API等操作。
• 任务分解与规划：对于复杂的开发需求（如“添加一个用户登录功能”），能将其分解为创建文件、编写代码、修改配置等一系列子步骤。
• 自主迭代与修正：能够根据代码执行结果（如测试失败、编译错误）进行自我修正。

1.2 Harness：智能体的“缰绳”与“引擎”

“Harness”在这里是一个工程学术语，可以理解为“驾驭”或“控制”。在AI智能体领域，Harness指的是用于构建、管理和控制AI智能体的一套框架、工具和最佳实践集合。

“Deepseek Harness 团队”这个名称暗示了其工作方向：专注于研究如何更好地“驾驭”Deepseek这类大模型，使其成为稳定、可靠、高效的代码智能体。一个成熟的Harness工程框架通常需要解决以下问题：

1. 提示词工程与管理：如何设计系统提示（System Prompt）来让模型扮演好“开发者”角色？如何管理上下文长度和提示模板？
2. 工具集成：如何安全、可控地为模型接入文件系统、终端、版本控制（Git）、数据库等工具？
3. 工作流与状态管理：如何设计智能体的执行循环（Loop）？如何保存和恢复任务状态？
4. 安全与权限控制：如何防止智能体执行危险命令（如rm -rf /）或访问敏感数据？
5. 评估与监控：如何评估智能体完成任务的质量？如何监控其资源消耗和API调用成本？

因此，当我们讨论“用Harness框架接入Deepseek”时，我们是在讨论一整套工程化方案，而不仅仅是调用一个API。

1.3 核心价值：为什么开发者需要关注？

对于开发者和技术团队而言，代码智能体带来的价值是切实的：

• 效率提升：自动化重复性编码任务，如生成样板代码、编写单元测试、进行简单的代码重构。
• 知识辅助：快速学习新框架、新库的API，生成符合特定代码规范的代码片段。
• 代码审查与建议：分析代码片段，提出优化建议，发现潜在的bug或安全漏洞。
• 探索性编程：快速生成技术方案的原型代码，加速技术选型和可行性验证。

2. 环境准备与核心工具选型

在开始构建我们的智能体之前，需要准备好开发环境并选择合适的技术栈。本文的实战部分将基于Python生态，因为其拥有最丰富的AI和智能体相关库。

2.1 基础环境要求

• 操作系统：macOS / Linux (推荐) 或 Windows (WSL2 推荐)。
• Python版本：Python 3.10 或更高版本。这是大多数AI框架的兼容性基线。
• 包管理工具：pip或poetry。本文使用pip进行演示。
• 代码编辑器：VS Code 或 Cursor。它们对AI插件有良好支持，但我们的智能体是独立运行的。

2.2 核心工具与框架介绍

我们将使用以下工具链来构建一个最小可用的代码智能体：

1. OpenAI SDK / LiteLLM：用于标准化调用不同的大模型API。Deepseek的API兼容OpenAI格式，因此我们可以直接使用openai库，或者使用litellm库来获得更好的多模型支持。
2. LangChain / LangGraph：当前最主流的智能体框架之一。它提供了构建链（Chain）、智能体（Agent）、工具（Tool）的高层抽象。LangGraph特别适合构建有状态、多步骤的智能体工作流。
3. Deepseek API：我们将使用Deepseek提供的在线API作为我们智能体的“大脑”。你需要一个Deepseek账户并获取API Key。

请注意：网络热词中提到的“Claude Code”、“Codex”通常是特定产品或集成的名称。我们的目标是理解原理并构建自己的智能体，因此聚焦于通用的框架和API。

2.3 项目初始化

首先，创建一个干净的项目目录并设置虚拟环境。

# 创建项目目录 mkdir code-agent-tutorial && cd code-agent-tutorial # 创建虚拟环境 (Python 3.10+) python -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 升级pip pip install --upgrade pip

3. 实战：构建你的第一个文件操作代码智能体

让我们从一个具体的任务开始：构建一个能根据自然语言指令，在指定目录创建和编辑Python文件的智能体。

3.1 安装依赖库

在激活的虚拟环境中，安装必要的Python包。

pip install openai langchain langchain-openai langchain-community langgraph

• openai：用于调用兼容OpenAI API的模型（包括Deepseek）。
• langchain：核心框架。
• langchain-openai：LangChain的OpenAI集成。
• langchain-community：包含社区贡献的各种工具和组件。
• langgraph：用于构建有状态、图结构的智能体工作流。

3.2 配置Deepseek API密钥

安全地管理你的API密钥。推荐使用环境变量。

# 在终端中设置环境变量（临时） export DEEPSEEK_API_KEY='your-deepseek-api-key-here' # Windows (PowerShell): $env:DEEPSEEK_API_KEY='your-key-here'

在代码中，我们可以通过os.environ读取。

3.3 创建基础工具：文件读写

智能体的能力来源于其可用的工具。我们先创建两个最基础的工具：读取文件内容和写入文件内容。

创建一个名为tools.py的文件：

# tools.py import os from typing import Type from pydantic import BaseModel, Field from langchain.tools import BaseTool class ReadFileInput(BaseModel): """读取文件的输入参数。""" file_path: str = Field(description="要读取的文件的完整路径") class WriteFileInput(BaseModel): """写入文件的输入参数。""" file_path: str = Field(description="要写入的文件的完整路径") content: str = Field(description="要写入文件的内容") class ReadFileTool(BaseTool): name = "read_file" description = "读取指定路径文件的内容。" args_schema: Type[BaseModel] = ReadFileInput def _run(self, file_path: str) -> str: """执行读取文件操作。""" try: with open(file_path, 'r', encoding='utf-8') as f: return f.read() except FileNotFoundError: return f"错误：文件 '{file_path}' 未找到。" except Exception as e: return f"读取文件时出错：{str(e)}" class WriteFileTool(BaseTool): name = "write_file" description = "将内容写入指定路径的文件。如果文件存在则覆盖，不存在则创建。" args_schema: Type[BaseModel] = WriteFileInput def _run(self, file_path: str, content: str) -> str: """执行写入文件操作。""" try: # 确保目录存在 os.makedirs(os.path.dirname(file_path), exist_ok=True) with open(file_path, 'w', encoding='utf-8') as f: f.write(content) return f"成功写入文件：{file_path}" except Exception as e: return f"写入文件时出错：{str(e)}"

代码解释：

1. 我们定义了两个Pydantic模型ReadFileInput和WriteFileInput来描述工具的输入参数。这有助于语言模型理解如何调用工具。
2. 我们创建了两个继承自BaseTool的类ReadFileTool和WriteFileTool。每个工具都需要定义name（工具名）、description（描述，非常重要，模型据此决定是否使用该工具）、args_schema（参数模式）和_run方法（核心逻辑）。
3. 在_run方法中，我们实现了具体的文件操作逻辑，并进行了简单的错误处理。

3.4 构建智能体系统

接下来，我们将使用LangGraph来构建智能体。LangGraph使用“图”的概念来定义智能体的执行流程，通常包含一个“循环”（Loop），让智能体可以思考、调用工具、观察结果、再思考，直到任务完成。

创建一个名为agent_system.py的文件：

# agent_system.py import os from typing import TypedDict, Annotated, Sequence import operator from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage, AIMessage, ToolMessage from langgraph.prebuilt import ToolExecutor, ToolInvocation from langchain_core.tools import BaseTool # 从tools.py导入我们创建的工具 from tools import ReadFileTool, WriteFileTool # 1. 定义智能体的状态 class AgentState(TypedDict): messages: Annotated[Sequence, operator.add] # 消息历史 last_tool_output: str # 上一个工具调用的输出 # 2. 初始化模型和工具 def create_agent_components(): # 注意：这里将Deepseek的API端点配置给OpenAI客户端 llm = ChatOpenAI( model="deepseek-chat", # 或其他Deepseek模型名 openai_api_key=os.getenv("DEEPSEEK_API_KEY"), openai_api_base="https://api.deepseek.com/v1", # Deepseek API基础地址 temperature=0.1, # 较低的温度使输出更确定，适合代码生成 streaming=False ) # 绑定工具：让模型知道它可以调用哪些工具 tools = [ReadFileTool(), WriteFileTool()] llm_with_tools = llm.bind_tools(tools) # 创建工具执行器 tool_executor = ToolExecutor(tools) return llm_with_tools, tool_executor, tools # 3. 定义智能体的行为节点 def call_model(state: AgentState): """调用模型，获取下一步行动（可能是回复消息或工具调用）。""" llm_with_tools, _, _ = create_agent_components() messages = state['messages'] response = llm_with_tools.invoke(messages) return {"messages": [response]} def call_tool(state: AgentState): """执行模型要求的工具调用。""" _, tool_executor, _ = create_agent_components() messages = state['messages'] last_message = messages[-1] # 检查最后一条消息是否包含工具调用 if not hasattr(last_message, 'tool_calls') or not last_message.tool_calls: raise ValueError("最后一条消息没有工具调用") tool_invocations = [ ToolInvocation(tool_call=tc, tool_input=tc['args']) for tc in last_message.tool_calls ] # 执行所有被调用的工具 outputs = tool_executor.batch(tool_invocations) output_messages = [] for invocation, output in zip(tool_invocations, outputs): # 为每个工具调用结果创建一个ToolMessage output_messages.append( ToolMessage( content=str(output), tool_call_id=invocation.tool_call['id'] ) ) return {"messages": output_messages, "last_tool_output": str(outputs)} # 4. 构建智能体工作流图 def build_agent_graph(): workflow = StateGraph(AgentState) # 添加节点 workflow.add_node("agent", call_model) # 思考节点 workflow.add_node("action", call_tool) # 执行节点 # 设置入口点 workflow.set_entry_point("agent") # 定义边（路由逻辑） def should_continue(state: AgentState) -> str: """根据最后一条消息决定下一步是调用工具还是结束。""" messages = state['messages'] last_message = messages[-1] if hasattr(last_message, 'tool_calls') and last_message.tool_calls: return "action" # 有工具调用，去执行 return END # 没有工具调用，结束 workflow.add_conditional_edges( "agent", should_continue, { "action": "action", END: END } ) # 从“执行”节点回到“思考”节点，形成循环 workflow.add_edge("action", "agent") # 编译图 return workflow.compile() # 5. 创建并运行智能体的便捷函数 def run_agent_task(user_input: str, initial_state: dict = None) -> dict: """运行智能体处理一个任务。""" app = build_agent_graph() messages = [HumanMessage(content=user_input)] state = initial_state or {"messages": messages, "last_tool_output": ""} final_state = app.invoke(state) return final_state if __name__ == "__main__": # 示例：让智能体创建一个Hello World文件 task = """ 请在我的项目根目录下创建一个名为 `hello.py` 的Python文件。 文件内容应该是一个简单的Hello World程序，它打印“Hello from Deepseek Agent!”。 """ print(f"用户任务：{task}") result = run_agent_task(task) print("\n智能体执行完成。最终消息历史：") for msg in result['messages']: print(f"[{type(msg).__name__}]: {msg.content[:200]}...") # 打印前200字符

系统设计解析：

1. 状态定义：AgentState定义了智能体运行过程中的核心数据，主要是消息历史。Annotated[Sequence, operator.add]是LangGraph的语法，表示messages字段是一个列表，新消息会被追加进去。
2. 模型配置：在create_agent_components中，我们使用ChatOpenAI类，但将其base_url指向Deepseek的API端点。这是调用Deepseek等兼容API模型的标准方式。
3. 工具绑定：llm.bind_tools(tools)是关键一步。它将工具的描述信息注入模型的上下文，让模型学会在合适的时候调用这些工具。
4. 图工作流：我们构建了一个简单的两节点循环图。
   • agent节点：调用模型，模型根据当前对话历史和任务，决定是直接回答还是调用工具。
   • action节点：如果模型决定调用工具，则在此节点执行具体的工具，并将结果返回。
   • should_continue函数是路由逻辑，检查模型输出是否包含工具调用，从而决定下一步是去执行工具还是结束流程。
   • action执行完后，流程会回到agent节点，让模型基于工具执行结果进行下一步思考，这就形成了一个“思考-行动-观察”的循环，直到任务被模型判断为完成。

3.5 运行与验证

在运行前，请确保已设置DEEPSEEK_API_KEY环境变量。

# 在项目根目录下运行 python agent_system.py

如果一切正常，你将看到类似以下的输出：

用户任务： 请在我的项目根目录下创建一个名为 `hello.py` 的Python文件... 智能体执行完成。最终消息历史： [HumanMessage]: 请在我的项目根目录下创建一个名为 `hello.py` 的Python文件... [AIMessage]: content='' additional_kwargs={'tool_calls': [{'id': 'call_...', 'function': {'arguments': '{"file_path": "hello.py", "content": "print(\\"Hello from Deepseek Agent!\\")"}', 'name': 'write_file'}, 'type': 'function'}]}... [ToolMessage]: 成功写入文件：hello.py [AIMessage]: 我已经在项目根目录下创建了 `hello.py` 文件，内容是一个打印“Hello from Deepseek Agent!”的简单Python程序。...

同时，检查你的项目根目录，应该能看到新生成的hello.py文件，其内容正是我们要求的。

4. 进阶：扩展智能体能力与工程化考量

基础的文件操作智能体已经能工作，但一个实用的代码智能体需要更强大的能力和更稳健的工程架构。

4.1 集成更多开发工具

一个强大的代码智能体不应局限于文件操作。我们可以为其集成更多开发相关工具：

# advanced_tools.py import subprocess from typing import Type from pydantic import BaseModel, Field from langchain.tools import BaseTool import ast import sys class RunPythonScriptInput(BaseModel): """运行Python脚本的输入参数。""" script_path: str = Field(description="要运行的Python脚本的路径") args: str = Field(default="", description="传递给脚本的命令行参数") class RunPythonScriptTool(BaseTool): name = "run_python_script" description = "在子进程中运行指定的Python脚本，并返回其输出和错误信息。" args_schema: Type[BaseModel] = RunPythonScriptInput def _run(self, script_path: str, args: str = "") -> str: try: # 构建命令 cmd = [sys.executable, script_path] if args: cmd.extend(args.split()) result = subprocess.run( cmd, capture_output=True, text=True, timeout=30 # 设置超时防止卡死 ) output = f"STDOUT:\n{result.stdout}\n" if result.stderr: output += f"STDERR:\n{result.stderr}\n" output += f"返回码: {result.returncode}" return output except subprocess.TimeoutExpired: return "错误：脚本执行超时（30秒）。" except FileNotFoundError: return f"错误：脚本文件 '{script_path}' 未找到。" except Exception as e: return f"运行脚本时出错：{str(e)}" class AnalyzePythonCodeInput(BaseModel): """分析Python代码的输入参数。""" code: str = Field(description="需要分析的Python代码字符串") class AnalyzePythonCodeTool(BaseTool): name = "analyze_python_code" description = "对提供的Python代码进行静态分析，报告语法错误、导入的模块和函数定义。" args_schema: Type[BaseModel] = AnalyzePythonCodeInput def _run(self, code: str) -> str: try: tree = ast.parse(code) analysis = [] # 检查语法错误（如果能解析到这里，说明语法基本正确） analysis.append("✅ 代码语法正确。") # 提取导入 imports = [node for node in ast.walk(tree) if isinstance(node, ast.Import)] imports_from = [node for node in ast.walk(tree) if isinstance(node, ast.ImportFrom)] if imports or imports_from: analysis.append("\n📦 导入的模块：") for imp in imports: for alias in imp.names: analysis.append(f" - import {alias.name}") for imp in imports_from: module = imp.module if imp.module else "" for alias in imp.names: analysis.append(f" - from {module} import {alias.name}") # 提取函数定义 functions = [node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)] if functions: analysis.append("\n🔧 定义的函数：") for func in functions: args = [arg.arg for arg in func.args.args] analysis.append(f" - {func.name}({', '.join(args)})") return "\n".join(analysis) if analysis else "代码分析完成，未发现明显问题。" except SyntaxError as e: return f"❌ 语法错误：{e.msg} (位于第{e.lineno}行，第{e.offset}列)" except Exception as e: return f"分析代码时出错：{str(e)}"

将这两个新工具添加到tools列表中，你的智能体就获得了运行脚本和静态分析代码的能力。它可以先写一段代码，然后分析它，最后运行它来验证结果。

4.2 设计系统提示词（System Prompt）

系统提示词是塑造智能体行为和角色的关键。一个好的系统提示词能极大提升智能体的任务完成率和代码质量。在初始化模型时，我们可以传入一个系统消息：

# 在 create_agent_components 函数中修改llm初始化部分 from langchain_core.messages import SystemMessage system_prompt = SystemMessage(content=""" 你是一个专业的Python开发助手，擅长编写清晰、高效、符合PEP 8规范的代码。 你的目标是根据用户的需求，通过调用可用的工具来完成代码相关的任务。 你拥有以下能力： 1. 读写文件。 2. 运行Python脚本并查看输出。 3. 分析Python代码的语法和结构。 请遵循以下原则： - 在修改或创建文件前，如果可能，先读取相关文件了解现有内容。 - 编写的代码应包含必要的注释。 - 如果任务复杂，将其分解为多个步骤，并一步步执行。 - 在运行脚本前，可以先对代码进行静态分析。 - 如果遇到错误，分析错误信息并尝试修复。 - 最终给用户一个清晰的任务完成总结。 """) # 在调用模型时，将系统提示词放在消息列表的开头 def call_model(state: AgentState): llm_with_tools, _, _ = create_agent_components() messages = state['messages'] # 在对话历史前插入系统提示词 full_messages = [system_prompt] + messages response = llm_with_tools.invoke(full_messages) return {"messages": [response]}

4.3 实现持久化与状态管理

对于长期运行或复杂的任务，我们需要将智能体的状态（如对话历史、中间结果）保存下来，以便中断后恢复或进行调试。LangGraph本身支持将状态序列化。

import json from langgraph.checkpoint import MemorySaver def build_agent_graph_with_checkpoint(): workflow = StateGraph(AgentState) # ... 添加节点的代码与之前相同 ... # 使用内存检查点保存器（生产环境可用数据库） memory = MemorySaver() app = workflow.compile(checkpointer=memory) return app, memory # 使用线程ID来区分不同的对话会话 thread_id = "user_123_task_456" app, memory = build_agent_graph_with_checkpoint() config = {"configurable": {"thread_id": thread_id}} # 第一次调用 initial_state = {"messages": [HumanMessage(content="创建一个计算斐波那契数列的函数")]} result1 = app.invoke(initial_state, config) # 模拟中断后，从检查点恢复状态并继续 # 我们可以获取当前状态快照 snapshot = memory.get(config) print(f"当前检查点状态: {snapshot}") # 继续新的输入 new_state = app.invoke({"messages": [HumanMessage(content="再写一个单元测试来测试这个函数")]}, config)

5. 常见问题与排查思路

在构建和运行代码智能体时，你可能会遇到以下典型问题。

6. 最佳实践与工程化建议

将实验性的智能体转化为团队可用的工程化组件，需要考虑更多因素。

6.1 安全第一：实施严格的沙箱环境

• 文件系统隔离：为智能体指定一个独立的“工作区”目录（sandbox），所有文件操作都必须限制在此目录内。可以使用chroot（Linux）或通过工具逻辑进行路径解析和校验来实现。
• 命令执行白名单：如果智能体需要执行Shell命令，必须实现一个严格的命令和参数白名单。例如，只允许运行python,pytest,git status,git add等少数安全命令，并禁止传递任何-rf、sudo等危险参数。
• 网络访问控制：默认禁止智能体发起网络请求。如果必须，则通过代理进行控制和审计。
• 输入输出过滤：对模型接收的用户输入和工具返回的输出进行必要的过滤，防止提示词注入攻击或敏感信息泄露。

6.2 提升可靠性：设计健壮的工作流

• 明确的成功/失败状态：每个工具都应返回结构化的结果，例如{"status": "success", "data": ...}或{"status": "error", "message": ...}。这有助于模型准确判断任务进展。
• 步骤验证与回滚：对于多步骤任务，在关键步骤后加入验证点。例如，创建文件后立即读取以确认内容正确。考虑实现简单的操作日志，以便在失败时进行回滚。
• 设置超时与重试：为API调用和工具执行设置合理的超时时间。对于可重试的错误（如网络抖动），实现指数退避的重试机制。
• 人机协同（Human-in-the-loop）：对于高风险操作（如删除文件、修改生产配置），设计审批节点，让智能体暂停并等待用户确认后再继续。

6.3 优化性能与成本

• 上下文管理：大模型的上下文窗口是有限的（如128K）。需要设计策略来修剪或总结冗长的对话历史、文件内容，只保留与当前任务最相关的部分。
• 工具描述精炼：工具的描述要准确精炼，过长会浪费上下文，过短则模型无法理解。可以尝试用不同的描述进行测试，找到效果和长度的平衡点。
• 异步执行：如果智能体需要调用多个不依赖的工具，可以考虑异步执行以提高效率。LangGraph支持异步节点。
• API成本监控：记录每次调用的Token消耗和费用，设置每日/每月的预算告警。

6.4 团队协作与代码质量

• 配置外部化：将模型类型、API密钥、温度、系统提示词等配置项抽取到配置文件（如config.yaml）或环境变量中，便于不同环境切换。
• 工具模块化：将不同的工具按功能分类到不同的Python模块中，保持代码清晰。例如file_tools.py、git_tools.py、test_tools.py。
• 编写单元测试：为你的工具函数和智能体的核心路由逻辑编写单元测试，确保基础功能稳定。
• 日志与可观测性：集成详细的日志记录（如使用logging模块），记录智能体的每一步决策、工具调用和结果。这对于调试复杂任务和优化提示词至关重要。

构建一个成熟可靠的代码智能体是一个迭代的过程。从本文的基础框架出发，你可以根据团队的具体需求，逐步集成版本控制（Git）、代码质量检查（Linter）、测试框架、容器管理等更多工具，最终形成一个强大的AI辅助开发平台。记住，核心始终是“Harness”——安全、可控、高效地驾驭AI的能力，让它成为开发者手中得力的工具，而非不可控的黑盒。