在实际 AI Agent 开发中一个常见的困境是我们能够快速构建一个基于大语言模型的对话原型但当试图将其转化为一个稳定、可维护、可扩展的生产级应用时却常常陷入混乱。代码中充斥着硬编码的提示词、难以追踪的状态、脆弱的工具调用逻辑以及混乱的错误处理。DeepSeek Harness 作为一个开源的 AI Agent 开发框架其核心价值并非仅仅是接入模型而是提供了一套完整的工程化解决方案将 Agent 开发的复杂性封装在清晰的架构之下。本文将以 DeepSeek Harness 的源码为蓝本深入解析其为实现 Agent 工程化所做的六项关键架构设计。无论你是希望理解现代 Agent 框架的设计哲学还是计划基于 Harness 构建自己的 Agent 应用理解这些设计都将帮助你构建出更健壮、更易维护的系统。1. 理解 Agent 工程化的核心挑战与 Harness 的应对思路在深入代码之前我们必须先明确 Agent 工程化试图解决哪些具体问题。一个玩具级的 Agent 脚本和一个企业级 Agent 应用之间存在巨大的鸿沟。核心挑战一状态管理的复杂性。Agent 在执行过程中需要维护对话历史、工具调用结果、中间推理过程等状态。这些状态需要在多轮交互中持久化并且可能被不同的模块如规划器、执行器读写。如何设计一个清晰、类型安全且可序列化的状态管理机制是首要难题。核心挑战二工具调用的标准化与安全性。Agent 的能力边界由其可调用的工具决定。如何让 Agent 动态发现工具如何定义工具的输入输出格式如何确保工具调用过程中的错误能被优雅处理而不会导致整个 Agent 崩溃如何对工具调用进行权限控制或成本审计核心挑战三执行流程的可控性与可观测性。Agent 的思考-行动循环Thought-Action-Observation需要被精确控制。开发者需要能够介入这个循环例如在特定步骤添加日志、进行验证、或根据条件改变执行流。同时整个执行过程的每一步都应该是可观测的便于调试和复盘。核心挑战四与异构后端的集成。Agent 的核心是 LLM但 LLM 提供商众多如 DeepSeek、OpenAI、Anthropic等每个提供商的 API 接口、参数、响应格式都有差异。框架需要提供一个抽象层让 Agent 的逻辑与具体的模型提供商解耦。DeepSeek Harness 的架构设计正是围绕解决这些挑战展开的。它没有采用“大泥球”式的单体设计而是通过清晰的职责分离和接口定义将上述复杂性分解到不同的模块中。其核心设计思想可以概括为以状态State为中心通过管道Pipeline组织执行流程利用工具Tool扩展能力并依赖强大的类型系统TypeScript来保证整个系统的可靠性。接下来我们将通过搭建一个最小化的 Harness 项目环境并逐步剖析其源码结构来揭示这六项架构设计的具体实现。2. 环境准备与项目初始化搭建 TypeScript 分析环境由于 DeepSeek Harness 是一个 TypeScript 项目为了深入理解其源码我们需要一个能够运行和调试 TypeScript 的本地环境。这不仅有助于阅读代码还能通过实际运行来验证我们对架构的理解。2.1 基础环境配置首先确保你的开发环境已安装 Node.js建议 LTS 版本如 18.x 或 20.x和包管理器 npm 或 yarn。我们将使用 pnpm 作为示例因为它速度快且与 monorepo 项目配合良好。# 检查 Node.js 和 npm 版本 node --version npm --version # 全局安装 pnpm (如果未安装) npm install -g pnpm # 安装 TypeScript 编译器和相关工具便于全局使用 tsc 命令检查类型 pnpm add -g typescript ts-node2.2 克隆与探索 Harness 项目结构从 GitHub 克隆 DeepSeek Harness 的官方仓库是分析的第一步。通过观察其项目根结构我们可以初步了解其模块划分。# 克隆仓库 (请替换为实际的仓库地址假设为官方仓库) git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness # 查看项目根目录结构 ls -la一个典型的 Harness 项目结构可能如下所示基于常见开源 Agent 框架模式推断deepseek-harness/ ├── packages/ # Monorepo 结构包含核心包 │ ├── core/ # 核心运行时、状态管理、管道引擎 │ ├── llm/ # 大语言模型集成抽象层 (如 DeepSeek, OpenAI 适配器) │ ├── tools/ # 内置工具库和工具定义标准 │ ├── cli/ # 命令行工具 │ └── ui/ # 可选的管理界面 ├── examples/ # 示例项目 ├── docs/ # 文档 ├── package.json # 根 package.json配置 workspaces ├── tsconfig.json # 根 TypeScript 配置 ├── pnpm-workspace.yaml # pnpm workspace 配置 └── README.md这种 monorepo 结构清晰地分离了关注点。core包是心脏定义了 Agent 的运行时模型llm包是桥梁连接不同的模型服务tools包是武器库提供了开箱即用的能力扩展。2.3 安装依赖与构建进入项目根目录安装所有工作区的依赖并构建项目确保所有类型定义都已生成方便 IDE 跳转和智能提示。# 在项目根目录执行 pnpm install # 构建所有 packages pnpm run build # 或者如果你只想构建并监听 core 包的变化便于开发时分析 cd packages/core pnpm run build:watch完成以上步骤后你的本地就拥有了一个可编译、可运行的 Harness 源码环境。接下来我们将深入packages/core/src目录开始解析第一项核心设计。3. 架构设计一以状态State为中心的运行时模型打开packages/core/src目录你很可能首先会看到一个state目录或一个核心的State接口/类定义。这是 Harness 架构的基石。3.1 State 接口定义 Agent 的“记忆”Agent 的所有执行上下文都封装在 State 对象中。它不是一个简单的键值对而是一个具有严格类型定义的结构。// 假设路径packages/core/src/state/types.ts // 这是一个基于常见模式推断的 State 接口定义示例 export interface AgentState { // 唯一标识一次会话或任务 sessionId: string; // 原始的输入例如用户问题 input: string; // 模型生成的响应流或最终响应 output?: string; // 完整的对话历史包含用户消息、助手消息、工具调用消息等 messages: Array{ role: user | assistant | system | tool; content: string; // 工具调用相关的元数据 tool_calls?: Array{ id: string; type: function; function: { name: string; arguments: string; // JSON string }; }; // 工具调用结果的元数据 tool_call_id?: string; }; // 当前步骤的中间“思考”过程 scratchpad?: string; // 已执行工具调用的结果缓存 toolResults: Mapstring, any; // 自定义的元数据供管道步骤或工具存储临时信息 metadata: Recordstring, any; }设计要点解析不可变性与可序列化State 应该是或可以被设计为不可变Immutable的。每次管道步骤执行后都会产生一个新的 State 对象而不是修改原对象。这简化了状态追踪和回滚逻辑。同时其结构必须支持 JSON 序列化以便于持久化到数据库或消息队列。消息列表messages的核心地位messages字段直接对应 LLM 的对话历史格式。这巧妙地将框架的内部状态与模型 API 的期望格式对齐减少了转换成本。工具调用和结果也被编码为特定格式的消息。工具结果缓存toolResults为了避免重复调用相同参数的工具或者为了方便后续步骤引用工具执行结果toolResults提供了基于工具调用 ID 的快速查找。元数据metadata的扩展性metadata是一个逃生舱口允许开发者在状态中附加任何自定义信息供特定的管道步骤使用而无需修改核心 State 接口。3.2 StateManager状态的持久化与生命周期管理仅有 State 定义还不够Harness 通常会提供一个StateManager抽象类或接口用于管理 State 的存储、加载和更新。// 假设路径packages/core/src/state/manager.ts export interface StateManager { // 创建或初始化一个状态 createState(sessionId: string, initialInput: string): PromiseAgentState; // 根据 sessionId 获取当前状态 getState(sessionId: string): PromiseAgentState | null; // 更新状态可能以追加消息等方式 updateState(sessionId: string, updater: (prevState: AgentState) AgentState): PromiseAgentState; // 持久化状态例如存到数据库 persistState(sessionId: string, state: AgentState): Promisevoid; } // 一个简单的内存实现用于开发和测试 export class InMemoryStateManager implements StateManager { private store new Mapstring, AgentState(); async createState(sessionId: string, initialInput: string): PromiseAgentState { const newState: AgentState { sessionId, input: initialInput, messages: [{ role: user, content: initialInput }], toolResults: new Map(), metadata: {}, }; this.store.set(sessionId, newState); return newState; } // ... 其他方法实现 }为什么需要 StateManager它解耦了状态逻辑和存储逻辑。在生产环境中你可以轻松地将InMemoryStateManager替换为基于 Redis、PostgreSQL 或 MongoDB 的实现而无需修改任何业务管道代码。这是工程化的典型标志将易变的部分存储方式抽象出来。4. 架构设计二基于管道Pipeline的可组合执行流Agent 的执行不是一蹴而就的而是由一系列步骤组成例如预处理输入 - 调用模型生成思考 - 解析工具调用 - 执行工具 - 处理工具结果 - 生成最终响应。Harness 使用管道模式来组织这些步骤。4.1 Pipeline 与 Step 抽象在packages/core/src/pipeline目录下你会找到核心的抽象定义。// 假设路径packages/core/src/pipeline/types.ts // 一个管道步骤接收状态返回可能修改后的新状态 export type PipelineStep (state: AgentState) PromiseAgentState; // 管道本身就是一系列步骤的顺序执行 export interface Pipeline { steps: PipelineStep[]; // 执行管道 run(initialState: AgentState): PromiseAgentState; // 添加步骤的构建器模式 addStep(step: PipelineStep): this; } // 一个基础实现 export class DefaultPipeline implements Pipeline { steps: PipelineStep[] []; addStep(step: PipelineStep): this { this.steps.push(step); return this; } async run(initialState: AgentState): PromiseAgentState { let currentState initialState; for (const step of this.steps) { currentState await step(currentState); // 这里可以插入钩子例如日志、监控、中断检查等 } return currentState; } }4.2 预置的标准化步骤Prebuilt StepsHarness 的强大之处在于它提供了一系列开箱即用的PipelineStep实现。这些步骤封装了 Agent 执行中的通用模式。// 假设路径packages/core/src/pipeline/steps/ // 1. 调用LLM步骤 export const createLLMStep (llmClient: LLMClient): PipelineStep { return async (state: AgentState) { // 从 state.messages 构建发送给LLM的提示 const llmResponse await llmClient.chatCompletion({ messages: state.messages, model: deepseek-chat, // ... 其他参数 }); // 将LLM的回复追加到 state.messages const newMessages [...state.messages, { role: assistant, content: llmResponse.content }]; return { ...state, messages: newMessages, scratchpad: llmResponse.content }; }; }; // 2. 工具调用解析与执行步骤 export const createToolCallStep (toolRegistry: ToolRegistry): PipelineStep { return async (state: AgentState) { const lastMessage state.messages[state.messages.length - 1]; if (lastMessage.role assistant lastMessage.tool_calls) { const newMessages [...state.messages]; for (const toolCall of lastMessage.tool_calls) { const tool toolRegistry.getTool(toolCall.function.name); if (!tool) { // 处理工具未找到的错误将其作为工具消息返回 newMessages.push({ role: tool, tool_call_id: toolCall.id, content: Error: Tool ${toolCall.function.name} not found., }); continue; } try { const args JSON.parse(toolCall.function.arguments); const result await tool.execute(args); // 将成功的结果作为工具消息追加 newMessages.push({ role: tool, tool_call_id: toolCall.id, content: JSON.stringify(result), }); // 同时缓存结果到 toolResults state.toolResults.set(toolCall.id, result); } catch (error) { // 处理工具执行错误 newMessages.push({ role: tool, tool_call_id: toolCall.id, content: Error: ${error.message}, }); } } return { ...state, messages: newMessages }; } // 如果没有工具调用原样返回状态 return state; }; };管道模式的优势可组合性你可以像搭积木一样通过pipeline.addStep(...)组合出复杂的 Agent 行为。例如一个支持 ReAct 模式的 Agent 管道可能是[llmStep, toolCallStep]的循环。可测试性每个PipelineStep都是纯函数给定输入状态产生输出状态可以独立进行单元测试。可观测性在Pipeline.run的循环中可以轻松插入日志、性能监控、状态快照等横切关注点。可扩展性你可以轻松编写自定义的PipelineStep来满足特定业务逻辑例如输入验证、结果格式化、敏感信息过滤等。5. 架构设计三类型安全的工具Tool注册与发现机制工具是 Agent 能力的延伸。Harness 需要一套机制让 Agent 能安全、可靠地调用开发者定义的工具。5.1 Tool 接口定义一个工具不仅仅是一个函数它包含元数据名称、描述、参数模式和执行逻辑。// 假设路径packages/core/src/tools/types.ts export interface ToolDefinition { // 工具的唯一标识LLM通过这个名称来调用 name: string; // 工具的自然语言描述用于帮助LLM理解何时使用此工具 description: string; // 参数的 JSON Schema 定义确保LLM生成格式正确的参数 parameters: JSONSchema; } export interface Tool extends ToolDefinition { // 实际的执行函数 execute(args: any): Promiseany; } // 一个获取天气的工具示例实现 export class GetWeatherTool implements Tool { name get_weather; description Get the current weather for a given city.; parameters { type: object, properties: { city: { type: string, description: The city name, e.g. Beijing }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius }, }, required: [city], } as const; async execute(args: { city: string; unit?: string }) { // 模拟或实际调用天气API const response await fetch(https://api.weather.com/v1?city${args.city}); const data await response.json(); return { temperature: data.temp, condition: data.condition }; } }关键点parameters使用 JSON Schema 定义。这不仅为人类提供了文档更重要的是框架可以利用它来动态生成供 LLM 使用的函数调用描述例如 OpenAI 的tools参数并在运行时验证 LLM 生成的参数防止无效调用。5.2 ToolRegistry中央工具仓库所有可用工具需要在一个中心位置注册和管理。// 假设路径packages/core/src/tools/registry.ts export class ToolRegistry { private tools new Mapstring, Tool(); registerTool(tool: Tool): void { if (this.tools.has(tool.name)) { throw new Error(Tool with name ${tool.name} is already registered.); } this.tools.set(tool.name, tool); } getTool(name: string): Tool | undefined { return this.tools.get(name); } // 获取所有工具的定义用于生成LLM的系统提示或函数描述列表 getAllToolDefinitions(): ToolDefinition[] { return Array.from(this.tools.values()).map(({ name, description, parameters }) ({ name, description, parameters, })); } }工程化价值解耦工具的实现者可能是不同团队的开发者只需要关注Tool接口无需知道 Agent 如何调用它。动态性工具可以在运行时动态注册和注销实现热插拔。安全性通过注册机制可以严格控制 Agent 可以访问的工具集合避免越权调用。可发现性ToolRegistry提供了获取所有工具定义的统一入口方便前端界面展示或动态生成系统提示。6. 架构设计四可插拔的 LLM 提供商集成层Harness 不应该绑定到某个特定的 LLM 服务。它通过一个抽象的LLMClient接口来支持多种后端。6.1 LLMClient 抽象接口// 假设路径packages/llm/src/client.ts export interface LLMChatMessage { role: system | user | assistant | tool; content: string; tool_calls?: any[]; tool_call_id?: string; } export interface LLMChatCompletionRequest { messages: LLMChatMessage[]; model: string; temperature?: number; max_tokens?: number; tools?: Array{ // 对应 OpenAI 的 tools 格式 type: function; function: { name: string; description: string; parameters: JSONSchema; }; }; // ... 其他通用参数 } export interface LLMChatCompletionResponse { content: string; tool_calls?: Array{ id: string; type: function; function: { name: string; arguments: string; }; }; usage?: { prompt_tokens: number; completion_tokens: number; }; } export interface LLMClient { chatCompletion(request: LLMChatCompletionRequest): PromiseLLMChatCompletionResponse; }6.2 具体提供商实现针对不同的 LLM 服务实现上述接口。// 假设路径packages/llm/src/providers/deepseek.ts import { LLMClient, LLMChatCompletionRequest, LLMChatCompletionResponse } from ../client; export class DeepSeekClient implements LLMClient { private apiKey: string; private baseURL: string; constructor(config: { apiKey: string; baseURL?: string }) { this.apiKey config.apiKey; this.baseURL config.baseURL || https://api.deepseek.com/v1; } async chatCompletion(request: LLMChatCompletionRequest): PromiseLLMChatCompletionResponse { // 将通用请求格式适配为 DeepSeek API 的特定格式 const deepSeekRequest this.adaptRequest(request); const response await fetch(${this.baseURL}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey}, }, body: JSON.stringify(deepSeekRequest), }); if (!response.ok) { throw new Error(DeepSeek API error: ${response.statusText}); } const data await response.json(); // 将 DeepSeek 的响应格式适配为通用格式 return this.adaptResponse(data); } private adaptRequest(request: LLMChatCompletionRequest): any { // 具体的适配逻辑处理字段名映射、默认值等 return { model: request.model, messages: request.messages, tools: request.tools, temperature: request.temperature ?? 0.7, // ... 其他 DeepSeek 特定参数 }; } private adaptResponse(deepSeekResponse: any): LLMChatCompletionResponse { const choice deepSeekResponse.choices[0]; return { content: choice.message.content, tool_calls: choice.message.tool_calls, usage: deepSeekResponse.usage, }; } }设计优势供应商中立Agent 的核心逻辑管道、状态管理完全不依赖具体 LLM。切换模型提供商只需更换LLMClient的实现实例。统一错误处理可以在抽象层实现重试、降级、熔断等通用策略。成本与用量监控统一的响应接口包含了usage字段便于集中进行 token 消耗统计和成本分析。7. 架构设计五配置驱动与依赖注入一个复杂的 Agent 应用可能包含数十个工具、多个管道步骤和不同的模型配置。Hardcoding 这些依赖关系会导致代码难以维护和测试。Harness 通常采用配置驱动和依赖注入DI模式。7.1 使用 IoC 容器管理依赖虽然 Harness 可能没有直接使用像InversifyJS这样重量级的 IoC 容器但其设计模式鼓励将组件的创建和组装逻辑集中到工厂函数或配置对象中。// 假设路径packages/core/src/agent-builder.ts 或类似文件 export class AgentBuilder { private toolRegistry new ToolRegistry(); private llmClient?: LLMClient; private pipelineSteps: PipelineStep[] []; // 配置方法采用流畅接口Fluent Interface风格 withLLM(client: LLMClient): this { this.llmClient client; return this; } withTool(tool: Tool): this { this.toolRegistry.registerTool(tool); return this; } withPipelineStep(step: PipelineStep): this { this.pipelineSteps.push(step); return this; } // 构建最终的 Agent 实例 build(): Agent { if (!this.llmClient) { throw new Error(LLM client must be configured.); } const pipeline new DefaultPipeline(); // 按顺序添加步骤LLM调用 - 工具执行 - (可选) 再次LLM调用以总结 pipeline.addStep(createLLMStep(this.llmClient)); pipeline.addStep(createToolCallStep(this.toolRegistry)); // 可以添加更多自定义步骤 for (const step of this.pipelineSteps) { pipeline.addStep(step); } return new DefaultAgent(pipeline, this.toolRegistry); } } // 使用示例 const agent new AgentBuilder() .withLLM(new DeepSeekClient({ apiKey: process.env.DEEPSEEK_API_KEY })) .withTool(new GetWeatherTool()) .withTool(new CalculatorTool()) .withPipelineStep(myCustomLoggingStep) // 自定义步骤 .build();7.2 从配置文件加载更进一步可以将配置外部化到 JSON 或 YAML 文件中。# config/agent.yaml llm: provider: deepseek model: deepseek-chat apiKey: ${DEEPSEEK_API_KEY} tools: - name: get_weather class: ./tools/GetWeatherTool - name: calculator class: ./tools/CalculatorTool pipeline: steps: - type: llm - type: tool_call - type: custom class: ./steps/LoggingStep然后编写一个配置加载器来解析这个文件动态实例化类并调用AgentBuilder。这实现了配置与代码的分离使得调整 Agent 行为无需重新编译代码特别适合云原生和容器化部署。8. 架构设计六全面的可观测性与调试支持对于运行在服务器上的 Agent黑盒操作是危险的。Harness 必须在架构层面内置可观测性。8.1 结构化日志管道中的每个关键步骤都应记录结构化日志。// 在 Pipeline.run 或每个 Step 中 import logger from ./logger; // 使用 Winston、Pino 等 async run(initialState: AgentState): PromiseAgentState { let currentState initialState; for (const [index, step] of this.steps.entries()) { const stepName step.constructor?.name || step_${index}; const startTime Date.now(); logger.info({ event: pipeline_step_start, sessionId: currentState.sessionId, step: stepName, stateSnapshot: _.cloneDeep(currentState), // 注意性能可采样或记录关键部分 }); try { currentState await step(currentState); const duration Date.now() - startTime; logger.info({ event: pipeline_step_end, sessionId: currentState.sessionId, step: stepName, duration, status: success, }); } catch (error) { logger.error({ event: pipeline_step_error, sessionId: currentState.sessionId, step: stepName, error: error.message, stack: error.stack, }); throw error; // 或根据策略决定是否继续 } } return currentState; }8.2 追踪与溯源每个工具调用、每次模型交互都应该有唯一的追踪 ID通常可以复用或关联sessionId和工具调用id。这些信息应该被记录并能够与最终的输出关联起来。在 Harness 中State对象本身就包含了完整的执行轨迹messages数组这本身就是一种强大的溯源机制。可以将重要的 State 快照持久化到数据库供日后查询分析。8.3 开发者工具与 UI许多先进的 Agent 框架会提供一个 Web UI用于实时查看Agent 的执行状态和思考过程。测试工具手动调用工具并查看结果。回放会话查看历史会话的完整消息流和状态变化。提示词管理编辑和测试系统提示词。Harness 的packages/ui/目录如果存在就是为此而生。它通过 WebSocket 或 Server-Sent Events (SSE) 连接到运行中的 Agent 服务订阅状态更新事件从而实现实时可视化。这极大地降低了调试和运维成本。9. 常见问题排查与最佳实践基于以上架构分析我们可以总结出在开发和运维 DeepSeek Harness Agent 时常见的坑及其解决方案。9.1 问题排查清单问题现象可能原因检查点与解决方案Agent 不调用工具1. LLM 未收到工具描述。2. 系统提示词未引导使用工具。3. 工具参数 Schema 定义不清晰。1. 检查LLMChatCompletionRequest中的tools字段是否正确传入了ToolRegistry.getAllToolDefinitions()的结果。2. 检查系统提示词systemmessage是否明确告知模型可以使用这些工具。3. 使用 JSON Schema 验证器测试工具参数定义是否合法。工具调用参数解析失败1. LLM 生成的参数 JSON 格式错误。2. 参数类型与 Schema 不匹配。1. 在createToolCallStep的JSON.parse处添加try-catch记录原始参数字符串。2. 在工具执行前使用ajv等库根据parametersSchema 验证参数。将验证错误信息返回给 LLM。状态未正确更新或持久化1. StateManager 实现有 bug。2. 管道步骤直接修改了原状态对象。1. 为StateManager编写单元测试。2.确保每个PipelineStep都返回一个新的状态对象使用扩展运算符{ ...state }或 Immer 等库遵守不可变原则。生产环境内存泄漏1.InMemoryStateManager未清理过期会话。2. 工具函数或步骤中存在未释放的资源。1. 在生产环境务必使用外部存储如 Redis实现的StateManager。2. 使用 Node.js 内存分析工具如heapdump定期检查。确保工具中的网络连接、文件句柄等被正确关闭。响应速度慢1. 工具执行是同步或阻塞的。2. LLM API 调用超时。3. 管道步骤过多。1. 优化工具实现考虑异步和非阻塞 I/O。对于耗时工具可以提供进度反馈。2. 为LLMClient配置合理的超时和重试策略。3. 评估管道步骤的必要性合并或移除非核心步骤。9.2 最佳实践工具设计原则单一职责一个工具只做一件事。防御性编程工具内部要对输入进行充分的验证和清理。友好错误工具执行失败时返回结构化的错误信息而不仅仅是抛出异常便于 LLM 理解。幂等性尽可能让工具调用是幂等的避免重复调用产生副作用。状态管理限制状态大小避免在state.metadata中存储过大的数据如图片二进制流。对于大文件存储引用如 URL 或文件路径。敏感信息脱敏在持久化或日志记录 State 前对 API Keys、个人身份信息PII等进行脱敏处理。管道设计步骤要轻量每个步骤应专注于一个简单的转换。复杂的逻辑拆分成多个步骤。添加超时和断路器对于调用外部服务LLM、工具的步骤实现超时和断路器模式防止一个步骤挂起导致整个管道阻塞。实现中间件可以设计类似 Koa 或 Express 的中间件机制在步骤执行前后插入通用逻辑如日志、性能监控、输入输出转换。生产部署配置外置所有 API Keys、模型名称、服务端点等都应通过环境变量或配置中心管理。健康检查为 Agent 服务添加/health端点检查其与 LLM 服务、数据库等下游依赖的连接状态。指标暴露使用 Prometheus 等工具暴露关键指标如请求量、平均响应时间、工具调用次数、Token 消耗、错误率等。版本化对工具定义、管道配置进行版本控制。确保回滚时Agent 的行为是可预测的。10. 总结与扩展方向DeepSeek Harness 通过这六项架构设计——以状态为中心、管道化执行、类型安全工具、可插拔 LLM、配置驱动和内置可观测性——成功地将 AI Agent 从脚本级别的概念提升到了工程系统的高度。它提供了一套约束和最佳实践引导开发者构建出模块化、可测试、可维护和可扩展的 Agent 应用。要更进一步你可以基于 Harness 的架构探索以下方向分布式执行当单个 Agent 任务非常复杂时能否将不同的管道步骤或工具调用分发到不同的工作节点执行这需要设计状态共享和任务协调机制。流式响应支持像 ChatGPT 一样的逐字输出这需要改造LLMClient接口和管道使其支持 Server-Sent Events (SSE) 或 WebSocket。人类在环HITL在管道中插入等待人工审核或输入的步骤这对于高风险或高价值的任务至关重要。强化学习集成根据任务完成的好坏自动调整提示词或工具调用策略这需要将奖励信号反馈机制融入状态和管道。理解这些架构设计不仅能让你更好地使用 Harness更能让你在面临其他 Agent 框架或自研需求时拥有清晰的评判标准和设计蓝图。工程化的价值在于用结构和约定来对抗复杂性而 Harness 正是这一理念在 AI Agent 领域的一次出色实践。