HAR框架实战：构建多智能体协作的自动化编码工作流

如果你最近在关注 AI 编程助手可能会发现一个明显的趋势从单点工具到协作系统。过去我们可能只用一个 Copilot 来补全代码或者用一个 Cursor 来重构函数。但现在一个更复杂、更自动化的需求正在浮现——如何让多个 AI 智能体Agent像一支训练有素的开发团队一样协同完成一个完整的、多步骤的编码任务这正是HAR项目试图回答的核心问题。它不是一个单一的 AI 模型而是一个开源框架Harness专门用于编排和管理多智能体编码工作流Multi-Agent Coding Workflows。简单来说HAR 为你提供了一套“乐高积木”和“搭建说明书”让你能自定义由多个 AI Agent 组成的流水线自动完成从需求分析、技术选型、代码生成到测试验证等一系列开发环节。这篇文章要解决的不是“又一个 AI 工具怎么用”而是“当 AI 编程进入多智能体协作时代我们如何搭建和管理这个新系统”。我会带你深入理解 HAR 的设计理念并通过一个完整的实战示例展示如何从零搭建一个能自动生成 Web 应用的多 Agent 工作流。你会发现它降低的不仅是编码成本更是复杂软件任务拆解与协调的认知负担。1. HAR 要解决的真实问题从“单兵”到“军团”的进化在深入技术细节前我们先明确 HAR 的定位。当前的 AI 编程工具大致分为三类代码补全工具如 GitHub Copilot在单文件内提供行级或函数级建议。聊天式助手如 Cursor、Claude for IDE能通过对话理解上下文并修改代码。任务级 Agent如smol-agent、Aider能理解一个相对完整的用户指令如“添加一个登录功能”并自主执行文件创建、修改等操作。HAR 属于第三类的“增强版”但它解决了一个更根本的瓶颈单一 Agent 的能力边界和任务复杂度之间的矛盾。一个设计良好的 Agent 可以处理一个明确定义的任务但真实的软件开发往往是网状、多阶段、多技能的。举个例子用户说“帮我创建一个具有用户注册、登录和仪表盘的个人博客系统”。这个任务涉及产品经理理解需求规划功能模块。架构师设计技术栈前端 React后端 Node.js数据库。前端工程师编写组件、页面和样式。后端工程师设计 API、数据模型和业务逻辑。测试工程师编写单元测试和集成测试。让一个“全能”Agent 从头到尾处理所有这些不仅对模型能力要求极高而且容易在复杂上下文中迷失。HAR 的思路是为什么不拆分成多个各司其职的 Agent并设计好它们之间的协作规则这就是“多智能体工作流”的核心价值。HAR 提供了标准化的工作流定义、Agent 角色管理、任务路由、状态追踪和工具调用框架让开发者能够像指挥一个微型开发团队一样去编排 AI 的协作过程。2. 核心概念拆解Agent, Skill, Workflow, Harness理解 HAR需要先厘清几个关键概念。它们共同构成了 HAR 的领域语言DSL。概念通俗解释类比在 HAR 中的角色Agent智能体具备特定角色和能力的 AI“员工”。开发团队中的“前端工程师”或“测试工程师”。执行任务的基本单元。每个 Agent 被赋予一个系统提示词System Prompt来定义其角色和目标。Skill技能Agent 可以执行的具体操作或工具。工程师掌握的“编写 React 组件”或“编写 Pytest 用例”。封装了可复用的能力例如“调用 OpenAI API 生成代码”、“运行 Shell 命令”、“读写文件”。一个 Agent 可以具备多个 Skills。Workflow工作流一系列任务步骤的有向无环图DAG。产品开发的“需求评审 - UI 设计 - 前端开发 - 后端开发 - 测试”流程。定义了任务的执行蓝图。它规定了先做什么、后做什么以及在什么条件下将任务分配给哪个 Agent。Harness套件/框架管理和运行上述所有组件的“操作系统”或“调度中心”。公司的项目管理平台如 Jira 团队协作工具如 Slack 自动化流水线如 Jenkins。HAR 项目本身。它提供了定义、组装、运行和监控多 Agent 工作流的基础设施。它们之间的关系你首先在Harness中定义一系列Skills基础能力库。然后你创建多个Agents并为每个 Agent 分配适合其角色的 Skills 和系统提示词。接着你设计一个Workflow描述一个复杂任务如何被分解成多个步骤并指定每个步骤由哪个或哪些Agent 来执行。最后你通过Harness运行这个 Workflow它会按照定义好的流程自动调度相应的 Agents调用它们的 Skills并传递任务上下文直到工作流完成。一个关键洞察HAR 本身不提供AI 模型。它是一个“胶水”框架。你需要为 Agents 配置后端的 AI 服务如 OpenAI GPT-4, Claude, 本地部署的 Llama 等。HAR 的核心价值在于编排与协作逻辑。3. 环境准备从零搭建 HAR playground在开始构建复杂工作流之前我们先搭建一个最小可运行环境。HAR 是一个 Python 项目因此 Python 环境是必须的。3.1 基础环境要求操作系统macOS, Linux 或 WSL2 (Windows Subsystem for Linux)。推荐 Linux/macOS 以获得最佳兼容性。Python 版本 3.9。建议使用 3.10 或 3.11。包管理工具pip或poetry。本文使用pip。AI 模型 API你需要一个可用的 AI 服务 API 密钥。我们将以OpenAI为例需要 GPT-3.5-Turbo 或 GPT-4 的 API Key。你也可以配置 Anthropic Claude、Groq 或本地模型。3.2 安装 HAR最直接的方式是通过pip从源码仓库安装。由于 HAR 可能处于快速迭代中建议克隆仓库并安装。# 1. 克隆仓库 git clone https://github.com/your-repo/har.git # 请将 your-repo 替换为实际的 HAR 项目仓库地址例如harness-org/har cd har # 2. 创建并激活虚拟环境强烈推荐 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 3. 安装依赖包 pip install -e . # -e 参数代表“可编辑模式”方便你修改本地源码并立即生效。如果安装过程中遇到依赖冲突可以尝试先升级pip或查看项目requirements.txt文件。3.3 配置 AI 模型密钥HAR 需要知道如何调用你的 AI 模型。配置通常通过环境变量完成。创建一个.env文件在项目根目录注意不要提交到 Git。# .env 文件内容 OPENAI_API_KEYsk-your-actual-openai-api-key-here # 如果你使用其他模型例如 Anthropic # ANTHROPIC_API_KEYyour-antropic-key # GROQ_API_KEYyour-groq-key然后在你的 Python 代码或运行脚本前加载这个环境变量。可以使用python-dotenv包。pip install python-dotenv4. 核心流程拆解构建你的第一个多 Agent 工作流现在我们通过一个具体的例子来感受 HAR 的威力自动创建一个简单的待办事项TodoWeb 应用。我们将这个任务分解为三个步骤由三个不同的 Agent 协作完成。4.1 第一步定义 Skills基础工具Skills 是 Agent 能使用的“武器”。HAR 内置了一些常用 Skill如GenerateTextSkill调用大模型生成文本我们也可以自定义。# skills/custom_skills.py import os from typing import Dict, Any from har.skills.base import Skill from openai import OpenAI class CodeGenerationSkill(Skill): 一个专门用于生成代码的 Skill封装了 OpenAI 调用。 name code_generation description 根据给定的任务描述和技术要求生成高质量的代码。 def __init__(self, model: str gpt-4-turbo-preview): super().__init__() self.client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) self.model model def execute(self, context: Dict[str, Any]) - Dict[str, Any]: 执行技能的核心方法。 prompt context.get(prompt, ) if not prompt: return {error: No prompt provided for code generation.} try: response self.client.chat.completions.create( modelself.model, messages[ {role: system, content: 你是一个资深的软件开发工程师。请根据用户需求生成完整、可运行、符合最佳实践的代码。只返回代码不要有任何解释。}, {role: user, content: prompt} ], temperature0.2, # 低温度保证代码稳定性 max_tokens2000 ) generated_code response.choices[0].message.content return {generated_code: generated_code, status: success} except Exception as e: return {error: fOpenAI API call failed: {str(e)}, status: failed} class FileWriteSkill(Skill): 将内容写入文件的 Skill。 name file_write description 将给定的内容写入指定的文件路径。 def execute(self, context: Dict[str, Any]) - Dict[str, Any]: filepath context.get(filepath) content context.get(content) if not filepath or content is None: return {error: Missing filepath or content in context.} try: os.makedirs(os.path.dirname(filepath), exist_okTrue) with open(filepath, w, encodingutf-8) as f: f.write(content) return {status: success, message: fFile written to {filepath}} except Exception as e: return {error: fFailed to write file: {str(e)}, status: failed}4.2 第二步创建 Agents角色基于上述 Skills我们创建三个具有明确分工的 Agent。# agents/todo_app_agents.py from har.agents.base import Agent from skills.custom_skills import CodeGenerationSkill, FileWriteSkill class ArchitectAgent(Agent): 架构师 Agent负责技术选型和项目结构设计。 def __init__(self, namearchitect): super().__init__(namename) self.description 负责软件项目的技术选型、架构设计和目录结构规划。 # 为这个 Agent 添加它需要的 Skills self.add_skill(CodeGenerationSkill()) # 可以设置系统提示词精细控制 Agent 行为 self.system_prompt 你是一个经验丰富的软件架构师。你的任务是根据用户需求选择最合适、最轻量级的技术栈并规划出清晰的项目目录结构。 你只输出一个 JSON 格式的结果包含两个字段 1. tech_stack: 一个数组列出选用的技术如 [React, Node.js with Express, SQLite]。 2. project_structure: 一个数组列出主要的目录和文件如 [src/, src/components/, src/App.js, server/, server/index.js]。 不要输出任何其他解释。 class FrontendDeveloperAgent(Agent): 前端开发 Agent负责生成前端代码。 def __init__(self, namefrontend_dev): super().__init__(namename) self.description 负责根据架构设计和需求编写前端 React 组件和页面。 self.add_skill(CodeGenerationSkill()) self.add_skill(FileWriteSkill()) # 前端 Agent 需要写文件 self.system_prompt 你是一个专业的前端工程师精通 React。你将收到架构师提供的技术栈和项目结构以及具体的功能需求。 你的任务是生成纯净、可运行的 React 组件代码包括 JSX 和 CSS。 请确保代码简洁、模块化并遵循常见的 React 最佳实践如函数组件、Hooks。 class BackendDeveloperAgent(Agent): 后端开发 Agent负责生成后端 API 代码。 def __init__(self, namebackend_dev): super().__init__(namename) self.description 负责根据架构设计和需求编写后端 API 和数据模型代码。 self.add_skill(CodeGenerationSkill()) self.add_skill(FileWriteSkill()) self.system_prompt 你是一个专业的后端工程师精通 Node.js 和 Express。你将收到架构师提供的技术栈和具体的功能需求。 你的任务是生成 Express 服务器的代码包括路由、控制器和简单的数据逻辑。 使用内存数组或简单对象模拟数据存储即可无需连接真实数据库。 4.3 第三步设计 Workflow协作蓝图这是 HAR 最核心的部分。我们需要定义一个DAG有向无环图描述任务如何流动。# workflows/todo_app_workflow.py from har.workflows.base import Workflow, Step from agents.todo_app_agents import ArchitectAgent, FrontendDeveloperAgent, BackendDeveloperAgent class TodoAppCreationWorkflow(Workflow): 创建 Todo 应用的完整工作流。 name todo_app_creation description 一个由架构师、前端和后端 Agent 协作创建 Todo Web 应用的工作流。 def define(self): # 初始化 Agents architect ArchitectAgent() frontend_dev FrontendDeveloperAgent() backend_dev BackendDeveloperAgent() # 定义步骤 1架构设计 def step_architect(context): 架构师分析需求输出技术栈和结构。 user_request context.get(user_request, 创建一个简单的待办事项Web应用) prompt f用户需求{user_request}。请完成技术选型和项目结构设计。 result architect.execute_skill(code_generation, {prompt: prompt}) # 假设 result 是 JSON 字符串我们需要解析它 import json try: design json.loads(result.get(generated_code, {})) return {design: design} except json.JSONDecodeError: # 如果模型没有返回标准 JSON这里可以添加容错逻辑 return {design: {tech_stack: [], project_structure: []}, error: Failed to parse design.} # 定义步骤 2前端开发依赖步骤1的输出 def step_frontend(context): 前端工程师根据架构设计生成代码并写入文件。 design context.get(design, {}) user_request context.get(user_request, ) # 构造给前端 Agent 的提示词 prompt f 技术栈{design.get(tech_stack, [])} 项目结构参考{design.get(project_structure, [])} 需求{user_request} 请生成这个 Todo 应用的主要前端 React 组件代码例如 App.js 和 TodoList.js。 # 1. 生成代码 gen_result frontend_dev.execute_skill(code_generation, {prompt: prompt}) code gen_result.get(generated_code, ) if not code or gen_result.get(status) failed: return {frontend_status: code_generation_failed, error: gen_result.get(error)} # 2. 写入文件这里简化实际应根据 project_structure 决定路径 write_result frontend_dev.execute_skill(file_write, { filepath: ./generated_todo_app/src/App.js, content: code }) return { frontend_status: completed, file_written: write_result.get(status) success, code_preview: code[:200] ... if len(code) 200 else code } # 定义步骤 3后端开发依赖步骤1的输出可与步骤2并行 def step_backend(context): 后端工程师根据架构设计生成代码并写入文件。 design context.get(design, {}) user_request context.get(user_request, ) prompt f 技术栈{design.get(tech_stack, [])} 需求{user_request} 请生成一个简单的 Express 服务器代码提供 Todo 项的增删改查CRUDAPI。 使用内存数组存储数据即可。 gen_result backend_dev.execute_skill(code_generation, {prompt: prompt}) code gen_result.get(generated_code, ) if not code or gen_result.get(status) failed: return {backend_status: code_generation_failed, error: gen_result.get(error)} write_result backend_dev.execute_skill(file_write, { filepath: ./generated_todo_app/server/index.js, content: code }) return { backend_status: completed, file_written: write_result.get(status) success, code_preview: code[:200] ... if len(code) 200 else code } # 构建工作流 DAG step1 Step( iddesign_architecture, executestep_architect, description架构师进行技术选型和结构设计 ) step2 Step( iddevelop_frontend, executestep_frontend, description前端工程师开发 React 组件, dependencies[design_architecture] # 依赖于步骤1 ) step3 Step( iddevelop_backend, executestep_backend, description后端工程师开发 Express API, dependencies[design_architecture] # 依赖于步骤1与步骤2并行 ) return [step1, step2, step3]4.4 第四步运行与监控 Workflow最后我们编写一个主程序来启动这个工作流。# run_workflow.py import asyncio import os from dotenv import load_dotenv from har.harness import Harness from workflows.todo_app_workflow import TodoAppCreationWorkflow # 加载环境变量 load_dotenv() async def main(): # 1. 初始化 Harness调度中心 harness Harness() # 2. 注册我们的工作流 workflow TodoAppCreationWorkflow() harness.register_workflow(workflow) # 3. 准备初始上下文用户需求 initial_context { user_request: 创建一个具有添加、删除、标记完成功能的单页面待办事项应用。要求界面简洁美观。 } # 4. 运行工作流 print( 开始执行 Todo 应用创建工作流...) result await harness.run_workflow( workflow_nametodo_app_creation, initial_contextinitial_context ) # 5. 打印结果和状态 print(\n✅ 工作流执行完成) print(最终上下文内容:) for key, value in result.context.items(): print(f - {key}: {value}) # 检查生成的文件 if os.path.exists(./generated_todo_app): print(f\n 生成的项目文件位于: {os.path.abspath(./generated_todo_app)}) if __name__ __main__: asyncio.run(main())5. 运行结果与效果验证执行上述run_workflow.py脚本。cd /path/to/your/har/project python run_workflow.py预期输出与验证控制台输出你会看到类似以下的步骤执行日志。 开始执行 Todo 应用创建工作流... [INFO] Step design_architecture started. [INFO] Step design_architecture completed. [INFO] Step develop_frontend started. [INFO] Step develop_backend started. [INFO] Step develop_frontend completed. [INFO] Step develop_backend completed. ✅ 工作流执行完成 最终上下文内容: - user_request: 创建一个具有添加、删除、标记完成功能的单页面待办事项应用。要求界面简洁美观。 - design: {tech_stack: [React, Node.js with Express, CSS Modules], project_structure: [src/, src/components/, ...]} - frontend_status: completed - file_written: True - code_preview: import React, { useState } from react;... - backend_status: completed - file_written: True - code_preview: const express require(express);... 生成的项目文件位于: /absolute/path/generated_todo_app生成的文件结构检查generated_todo_app目录。tree generated_todo_app/ # 预期看到类似结构 # generated_todo_app/ # ├── src # │ └── App.js # └── server # └── index.js验证生成代码打开生成的文件检查代码是否完整、合理。例如src/App.js应该包含 React 组件server/index.js应该包含 Express 服务器代码。手动测试可选如果生成了完整的项目你可以尝试运行它。# 前端假设是 React cd generated_todo_app npm init -y npm install react react-dom # 可能需要一个简单的 HTML 文件来加载 React或者使用 Create React App 结构。 # 后端 cd server npm init -y npm install express node index.js # 访问 http://localhost:3000/todos 测试 API如何判断成功工作流所有步骤状态为completed。没有关键的error字段。目标目录下生成了预期的代码文件。生成的代码语法基本正确符合描述的需求。6. 常见问题与排查思路在实际使用 HAR 构建复杂工作流时你可能会遇到以下典型问题。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named harHAR 包未正确安装或虚拟环境未激活。1. 运行 pip listgrep har 确认安装。2. 检查终端是否在正确的虚拟环境中。openai.AuthenticationErrorOpenAI API 密钥未设置或无效。1. 检查.env文件是否存在且格式正确。2. 在 Python 中print(os.getenv(OPENAI_API_KEY))查看是否加载。1. 确保.env文件在项目根目录。2. 确认密钥有效且有余额。3. 在代码开头显式加载load_dotenv()。工作流卡在某个 Step 不动Agent 的 Skill 执行超时或进入死循环模型 API 响应慢。1. 查看日志确定卡在哪一步。2. 检查该 Step 的execute函数内部逻辑是否有无限循环或长时间操作。1. 为 Skill 的执行添加超时机制。2. 检查模型调用如client.chat.completions.create的max_tokens是否设置过大。3. 考虑使用异步版本的 Skill。Agent 生成的代码不符合预期或格式错误系统提示词System Prompt不够清晰模型温度temperature设置过高。1. 检查 Agent 的system_prompt是否明确指定了输出格式如“只输出 JSON”。2. 查看模型返回的原始内容。1. 优化提示词加入更严格的格式约束和示例。2. 降低temperature参数如设为 0.2以获得更确定性的输出。3. 在 Workflow 的 Step 中添加后处理逻辑清洗和验证模型输出。生成的代码文件路径错误或无法写入文件路径不存在或没有写权限FileWriteSkill逻辑有误。1. 打印filepath变量检查路径是否正确。2. 检查os.makedirs是否成功创建了目录。1. 在FileWriteSkill中确保使用os.path.dirname()创建父目录。2. 使用绝对路径或相对于工作流的明确路径。3. 检查当前 Python 进程的用户权限。多个 Agent 之间上下文传递丢失Workflow Step 的context更新不正确依赖关系未正确定义。1. 在每个 Step 的execute函数开始和结束时打印context。2. 检查 Step 的dependencies列表是否包含了它所依赖的 Step ID。1. 确保每个 Step 的execute函数返回一个字典这个字典会被自动合并到全局context中。2. HAR 会确保依赖的 Step 先执行并将其输出合并到后续 Step 的输入上下文中。仔细检查 DAG 定义。asyncio.run()在 Jupyter 或已有事件循环中报错异步环境冲突。错误信息通常包含RuntimeError: asyncio.run() cannot be called...如果在 Jupyter Notebook 中运行使用await harness.run_workflow(...)而不是asyncio.run(main())。或者使用nest_asyncio包。7. 最佳实践与工程建议将 HAR 用于实际项目时遵循以下建议可以大幅提升成功率和可维护性。7.1 Agent 设计原则单一职责每个 Agent 应只负责一个明确的领域如前端、后端、测试、文档。避免创建“全能”Agent。清晰的系统提示词系统提示词是 Agent 的“人格”和“工作说明书”。务必详细、具体并包含输出格式要求。好的提示词是成功的一半。技能复用将通用能力如调用大模型、读写文件、执行命令、调用 API封装成独立的 Skill供多个 Agent 复用。这符合 DRYDon‘t Repeat Yourself原则。7.2 Workflow 设计原则模块化与可组合将大工作流拆分成小的、可复用的子工作流。例如“代码生成工作流”和“代码评审工作流”可以组合。健壮的错误处理在每个 Step 的execute函数中对 Skill 的执行结果进行校验。对于关键步骤考虑实现重试逻辑或备选方案。上下文管理精心设计在 Workflow 步骤间传递的context数据结构。避免传递过大的对象只传递必要的信息。可以使用唯一键来存储和检索复杂数据。7.3 性能与成本优化并行化利用 HAR 的 DAG 支持将没有依赖关系的步骤如前端和后端开发定义为并行可以缩短总运行时间。模型选择并非所有任务都需要 GPT-4。对于简单的代码生成或格式化任务使用 GPT-3.5-Turbo 可以显著降低成本。可以在 Skill 或 Agent 级别配置模型。缓存对于确定性较高的任务如根据固定模板生成文件可以考虑缓存模型响应避免重复调用 API。7.4 版本控制与团队协作将 HAR 配置代码化本文示例将 Agents、Skills、Workflows 定义为 Python 类。这本身就是一种代码化配置非常适合用 Git 进行版本管理。分离配置与密钥永远不要将 API 密钥等敏感信息硬编码在代码中。坚持使用.env文件和环境变量并通过.gitignore排除。编写测试为你的自定义 Skills 和关键的 Workflow 步骤编写单元测试和集成测试。模拟 AI 模型的响应确保业务逻辑正确。7.5 安全边界沙箱环境如果 Workflow 中包含执行 Shell 命令或任意代码的 Skill务必在沙箱环境中运行以防恶意指令破坏主机。输入验证与清理对从外部传入 Workflow 的初始context如用户输入进行严格的验证和清理防止提示词注入攻击。权限最小化FileWriteSkill等具有写权限的 Skill应限制其可访问的目录范围避免覆盖系统关键文件。8. 总结HAR 将如何改变你的开发流程HAR 代表的不仅仅是一个工具而是一种新的范式将软件开发流程视为一个可编程、可编排的多智能体协作系统。它把开发者从重复性的、模式化的编码任务中解放出来转而扮演“产品总监”和“架构师”的角色——专注于定义问题、设计工作流和验收结果。通过本文的实战你应该已经掌握了使用 HAR 的核心流程定义技能将原子能力生成代码、写文件封装成 Skill。创建角色根据任务分工组合不同的 Skill 形成各司其职的 Agent。设计蓝图以 Workflow 定义任务拆解步骤和 Agent 间的协作依赖。运行与迭代执行 Workflow并根据结果优化提示词、Skill 逻辑和流程设计。下一步你可以尝试引入测试 Agent在代码生成后自动运行单元测试。引入评审 Agent对生成的代码进行安全检查或风格检查。将工作流与你的 CI/CD 管道结合实现需求到部署的部分自动化。探索更复杂的 Agent 通信模式如让 Agent 之间通过“会议”协商技术方案。HAR 目前仍处于早期阶段其稳定性和生态还在发展中。但它清晰地指出了 AI 赋能软件工程的下一个方向从辅助编码的“副驾驶”进化为可自主协调完成复杂任务的“自动驾驶团队”。现在是时候开始思考如何将你团队中那些标准化、流程化的开发任务交给这样的“团队”来完成了。