企业官网建设流程全解析

最近我花了不少时间折腾多智能体（Multi-Agent）相关的东西，发现只要打开 GitHub、掘金或者技术社区，就很难绕开两个名字：Harness 和 Hermes。一个是把多个智能体串起来的编排框架，一个是能连上大模型 API 直接跑的智能体外壳。尤其是当你想把这两个东西组合起来用，再对接本地部署的模型 API 时，网上能找到的资料基本都是碎片化的，要么只有安装命令，要么只讲单个组件，很少有人把环境准备、插件加载、Skill 编写、多智能体编排这一整条链路讲清楚。

这篇内容就是干这个用的。我会先用最通俗的方式讲明白 Harness 和 Hermes 各自是什么，再说为什么它们俩很适合搭配在一起，然后从环境准备、安装部署、Skill 扩展、多智能体编排到常见报错排查，完整走一遍。适合三类人看：一是已经调过模型 API、想从“Prompt 工程师”转向“Agent 工程”的开发者；二是本地已经部署了模型服务、想要一个桌面端或命令行外壳来跟模型打交道的玩家；三是打算用多个智能体拆分复杂任务，但不知道怎么编排的人。不同基础都能找到可以抄作业的部分。

1. Harness 与 Hermes 到底是什么

1.1 先搞懂多智能体的核心概念

要说清楚 Harness 和 Hermes，必须先理解“多智能体”究竟在解决什么问题。单个模型调用本质上是一次“问答”：你给一个 Prompt，模型给你一个回答，仅此而已。但真实项目里的任务往往不是“回答一个问题”这么简单，而是“理解需求、拆解任务、查找资料、写代码、跑测试、改 bug、再复盘”一连串动作。让一个模型承受这么多步骤，很容易出现上下文过长、角色混淆、任务跑偏的问题。

多智能体做的事情，就是把这一个庞大的任务拆给多个“有分工的模型实体”去协作。每个智能体有自己独立的记忆、工具集、系统提示词，像是在项目里各自负责一块的团队成员，有人做规划，有人做执行，有人做审核，有人做交付。这里有一个很容易混淆的点：智能体不是单纯的多轮对话，它必须具备“行动能力”。模型输出文本之后，智能体还要能够调用外部工具去执行代码、读文件、写文件、发请求，然后从工具返回的结果中继续思考，形成“感知—决策—行动”的循环。没有这个循环，再有名的模型也只是一个聊天窗口。

所以多智能体的本质，是“执行单元的集合 + 控制单元”。控制单元决定任务怎么拆、怎么分、怎么回收；执行单元各自负责一个边界清晰的子任务。Harness 和 Hermes 正是分别站在了这个体系的两端。

1.2 Harness：编排多智能体的“调度中枢”

Harness 这个名字本身就有“管线、线束”的意思，用在多智能体场景里非常贴切。它不会直接跟用户对话，也不会自己去跑模型推理，它是那个站在后台把多个智能体“装进工作台”的框架。用大白话说，Harness 是一个管理智能体的智能体管理平台，负责解决几个核心问题：谁先上场、谁后上场、任务结果怎么传递、每个智能体可以用哪些工具和 Skill、任务失败之后由谁重新处理。

很多人的误区是把 Harness 当成“又一个 Agent 框架”，其实它的定位更像是“Agent 之上的编排层”。你的 Agent 可以是 Hermes，也可以是你自己用 Python 写的脚本，Harness 关心的是如何让这些 Agent 按照你设计的流程跑起来，并且把中间的状态和上下文传递下去。这跟你之前听到的 Harness Engineering 是一回事，它强调的是把工程化思维用在整个 Agent 体系里，而不是把一堆大模型 API 随意堆在一起。

对于刚接触的人来说，Harness 提供的核心能力可以分成四块。第一是 Skill 平台，每个 Skill 相当于给智能体的一份“操作说明书”，告诉它能用什么工具、怎么用、边界在哪；第二是 Agent 生命周期管理，从初始化、运行、暂停到回收，全部由框架控制；第三是上下文传递，前一个智能体的输出会经过标准化处理后变成后一个智能体的输入，避免直接把“聊天记录”一股脑塞过去；第四是插件机制，通过插件目录来加载不同的工具集，这也是很多人在安装阶段会碰到failed to load plugins这类报错的原因。

1.3 Hermes：可以跑在本地的智能体外壳

Hermes 的角色跟 Harness 不太一样。它是一个更贴近模型、更偏向运行时的智能体外壳，你可以把它理解为“把大模型 API 包装成完整 Agent 的一套工具”。它最吸引人的地方是支持对接本地部署的模型服务，比如你通过 Ollama、vLLM、llama.cpp 起了一个 OpenAI 兼容接口的本地 API，Hermes 就能直接连上去。当然，如果用的是 DeepSeek、通义千问这类云厂商的 API，它也照样支持，只需要在配置文件里指定 API Base URL 和模型名就行。

为什么需要一个外壳？因为 API 本身是无状态的。你每次调用模型接口，都要把历史对话重新传给模型，Token 消耗高，而且上下文一旦长起来就很容易乱。Hermes 这类外壳会帮你做会话持久化、状态管理、工具调用格式规范化，让你像操作一个智能体一样操作模型，而不是像调接口一样手动拼 Prompt。桌面版还提供了图形界面，可以直观地查看每一轮调用的输入输出、工具调用记录和 Token 消耗情况。对于调试阶段来说，这比在终端里盯着 JSON 日志舒服太多了。

热词里经常提到的hermes agent v0.21 (bot mode)指的是 Hermes 的无界面模式。这种模式非常适合被 Harness 之类的外部框架调用，因为 bot mode 下 Hermes 只接受命令行参数，不弹出窗口，把返回结果以结构化格式输出。你可以把多个 Hermes 实例理解成流水线上的工人，Harness 负责安排调度，Hermes 负责跟模型沟通并执行具体步骤。

2. 选型逻辑：为什么要把 Harness 和 Hermes 放在一起用

2.1 Harness 和 Agent 到底有什么不同

热词里有一个搜索量很高的问题是“harness 和 agent 区别”，这个问题问得非常关键，很多人一开始都栽在这里。简单来说，Agent 是一个能独立思考和行动的单元，它有目标、有记忆、有工具；而 Harness 是承载这些单元的系统。你可以把 Agent 比作一台施工机器，把 Harness 比作整个施工工地。机器本身能干活，但如果没有工地里的道路规划、材料供给、安全检查和任务调度，机器再多也只会各自为战，甚至互相冲突。

我用一个更生活化的类比：几个人一起做饭。如果每个人都自己切菜、自己炒菜、自己尝味道，那就是“多实例并行”，不是多智能体协作；如果一个人负责切配、一个人负责掌勺、一个人负责装盘，那就需要一个“总指挥”来决定先备哪道菜、哪个锅先热、出锅之后怎么交给下一个环节。这个总指挥就是 Harness。而 Hermes 这一类 Agent 运行时，就是那些已经在岗位上、能听懂指挥的厨师。两者互相配合，才能形成一套完整的“做饭流水线”。

Harness 在设计上还有一个明显的特征：它刻意让“流程”和“模型”解耦。你可以今天用 DeepSeek 跑，明天换本地模型，只要对应的 Agent 外壳实现了统一的接口，Harness 不需要大幅度改动。这是很多新人在对比各类框架时容易忽略的优点：你选的不只是某个模型，而是一整套流程骨架，底下的模型可以灵活换。

2.2 为什么桌面端更适合做 Agent 调试

我一直建议刚开始玩 Agent 的人优先用桌面版而不是纯命令行，这不是因为图形界面更花哨，而是因为调试 Agent 时你尤其需要看到“过程”。命令行版本通常只会把最终输出打出来，中间模型调了什么工具、传了什么参数、工具报了什么错，往往要翻日志才知道。而 Hermes 桌面版会把工具调用记录渲染成类似“步骤卡片”的形式，你能清晰看到模型在哪个环节开始跑偏，是 Prompt 问题还是工具返回值问题。

对接本地部署 API 的时候，桌面版的优势更明显。本地模型服务可能同时挂着好几个进程，比如一个 vLLM 实例跑着模型，一个 Ollama 在后台待命，还有一个 Python API 服务占着 8000 端口。桌面版可以直接在设置面板里切换 Base URL 和模型名，验证一个连接通路是否畅通，而不需要每次改配置文件再重启终端。

顺便说一下，很多人在本地部署 API 时会遇到一个奇怪的情况：模型在服务端已经正常加载，但 Hermes 连接时怎么都返回 401。大多数时候原因都很简单，本地服务可能不校验 Key，但 Hermes 默认会填上一个占位 Key；反而是在服务端开了鉴权之后，客户端没有同步配置。所以我的建议是，第一次做连通性测试时先去服务端确认鉴权开关，然后让 Hermes 端做对应的填空，别上来就怀疑框架有问题。

2.3 从“单打独斗”到“多智能体作战”

早期我们用大模型做自动化，基本都是一个 Agent 从头做到尾。比如给它一个任务：“写一份市场分析报告”，它就自己去搜资料、写提纲、生成正文。听起来很爽，但实际跑下来问题很多。一个 Agent 承担的职责太多，系统提示词就会变得非常长，而模型很难在一个 Prompt 里同时扮演好几个角色，最后往往出现“规划很美好，执行很拉胯”的情况。

多智能体把这个困境化解了，但它不是银弹。你引入多个 Agent，就要面对更复杂的调度、更长的链路、更多的失败点。这也是为什么我不建议一上来就把智能体数量堆到五个以上。比较好的路径是从“两个角色”开始，比如一个规划者、一个执行者，跑通之后再逐步加入审核者、测试者。热词里提到的“多智能体编排”，其实不是简单地把多个智能体拼在一起，而是要明确它们之间的数据流向和依赖关系。Harness 做的正是这件事，它让编排变成项目里可以维护的配置，而不是靠 prompt 里的“你负责…他负责…”这种脆弱约定。

在我实际测试中，Harness 配合 Hermes 跑多智能体的体验，最舒服的地方在于“角色边界清晰”。每个 Hermes 实例只维护自己那段上下文，任务完成后把结构化结果交给 Harness；Harness 再把结果作为新任务的输入给下一个 Hermes。中间不需要把整个历史记录都复制过去，既省 Token，又避免了上下文串味。

3. 环境准备与安装部署实战

3.1 安装之前：确认环境、依赖与模型服务

很多安装问题其实是环境问题，不是工具本身的问题。开始之前，先花五分钟检查几个基础项。如果你用的是 Windows 11，建议把终端换成 PowerShell 7 或者 Windows Terminal，自带的老版控制台在处理长日志时会出现严重的卡顿和截断。macOS 用户需要确认是否安装了 Xcode Command Line Tools，很多编译型依赖都依赖它。Linux 用户则要留意 glibc 版本，太老的系统会因为二进制兼容问题启动失败。

运行环境方面，Hermes 和 Harness 目前都建议使用 Node.js 18 以上和 Python 3.10 以上。你可以在终端里分别执行node -v和python --version确认版本，如果版本过低，优先用版本管理工具升级，而不是直接去系统目录里替换，否则容易破坏系统自带环境。磁盘空间建议预留 10GB 以上，不仅是因为两个框架本身不大，还要考虑到日志文件、模型缓存和依赖包可能占掉不少空间，尤其是在本地还跑着模型服务的情况下。

模型这块，你可以选择云 API，比如 DeepSeek API，也可以选择本地模型服务。本地部署最省事的方案是 Ollama，一行命令起服务，默认监听 11434 端口，并提供 OpenAI 兼容接口；如果追求更高的推理吞吐量，可以考虑 vLLM。不过本地小模型的 Agent 能力跟云模型还是有差距，建议在多智能体规划这类需要强推理的环节用云 API，在执行类环节用本地模型，成本和质量都能兼顾。

3.2 安装 Hermes 并完成桌面端配置

Hermes 的安装路线在不同系统上略有差异，但大体都遵循“下载包—解压—配置—启动”这个套路。Windows 用户可以从官方仓库的 Release 页面下载桌面版压缩包，解压到用户目录下的专用文件夹，比如D:\Tools\Hermes，不要放在C:\Program Files这类需要管理员权限的路径下，否则后续写配置文件会很痛苦。解压完成后，执行主程序图标启动桌面端，首次启动会生成一个配置目录。

配置界面里的关键字段一般是这几个：

• API Base URL：填写你模型服务的地址。如果是本地 Ollama，默认是http://localhost:11434/v1；如果是本地 vLLM 或其他 OpenAI 兼容服务，填对应端口即可；如果用 DeepSeek 云端 API，就填官方接口地址。
• API Key：云端 API 填真实密钥，本地服务如果未开启鉴权，随便填一个合法的格式字符串即可。
• Model Name：需要严格匹配服务端加载的模型名。Ollama 里是像qwen2.5:7b这样的名字，vLLM 里是模型发布名。
• Context Length / History：控制每个会话保留多少轮历史。一开始不要设置太长，先把链路跑通再逐步调大。

配置完成后，先发一条最简单的测试消息，比如“请回复 OK”，确认连通性。如果这一步都失败，后面的所有工作都无从谈起。我要特别提醒一下，不要为了省事把临时 API Key 写死在代码里，Hermes 桌面版配置文件建议与项目目录分离，并且加入.gitignore，避免误传。

3.3 安装 Harness 并初始化项目

Hermes 就绪之后，再来装 Harness。我建议用独立项目目录的方式来操作，避免污染全局环境。在终端里执行：

# 克隆框架代码到本地（以你实际拿到的仓库地址为准） git clone https://github.com/your-target/harness.git cd harness # 安装框架核心依赖 npm install

依赖安装完成后，命令行工具通常提供一个初始化命令。我习惯把它指向一个全新的目录，比如：

npx harness init my-agent-project

初始化命令会自动生成几个关键目录：agents/放智能体配置，skills/放 Skill 文件，flows/放多智能体流程定义，plugins/放插件包。走到这一步，你就拥有一个空的 Harness 项目骨架了。如果你看到终端输出harness版本号，说明安装成功；如果报failed to load plugins之类的错误，先不要慌，下一节我们会单独讲这个高频问题。

我想强调一下你在安装 Harness 时最容易忽略的一点：不要用sudo全局安装，也尽量不要把项目初始化到系统根目录或者桌面。很多人的项目跑不起来，是因为当前用户对目录没有写权限，框架无法创建会话缓存和日志文件。把项目放在自己的用户目录下，用普通权限去跑，能省掉大量莫名其妙的问题。

3.4 踩坑记录：插件加载失败、版本不对、目录权限

热词里出现频率最高的报错就是harness failed to load plugins web boot: 2 entries did not activate。这个报错我在 Windows 和 Linux 上都碰到过，结论是同一个：插件目录里有部分插件没有被成功激活。原因通常有三种。

第一种是插件声明文件不完整。Harness 的插件目录里，每个插件需要一个入口文件，入口需要正确导出插件对象。如果是从网上拷贝的插件包，经常会出现缺少name、activate()方法返回值不是布尔值这类情况。排查方式很直接：打开报错日志，看它明确标出了哪两个插件没有激活。找到对应的目录，进去查看入口文件的结构是否完整。

第二种是插件之间的依赖加载顺序问题。部分插件在激活阶段就要访问另一个插件导出的工具函数，如果前一个插件还没加载完成，后一个就会报“找不到对象”。这时候不要急着改代码，可以先在配置里禁用非必要的插件，只保留核心插件集合，把问题缩小到一个最小可复现范围。

第三种是 Node 版本兼容问题。Harness 在更新频次高的时候，可能会引入只在某版本 Node 下能用的特性，导致原生模块编译失败，插件加载阶段就崩了。我踩过一次比较典型的坑：在 Node 20 下一切正常，切到 Node 18 之后，一个文件监听插件就加载失败了。后来看文档才发现，这个插件要求文件系统 API 的最低版本为 Node 19。遇到这种问题，最简单的方法是切换 Node 版本再重新安装依赖，而不是去改插件源码。

目录权限问题也很常见，尤其是在 Windows 上。如果你把项目放在C:\Program Files下，运行时会遇到EACCES之类的权限错误。解决办法不是给目录授予完全控制权限，而是把项目迁移到用户目录下重新初始化。权限问题越早发现越好，等到跑多智能体流程时再出现写权限失败，排查成本会成倍增加。

4. 用 Skill 给 Harness 扩展能力

4.1 Skill 文件的组织方式

在 Harness 里，Skill 是给智能体“吃”的能力包。你可以把一个 Skill 理解为一份带有说明书的工具集合，里面既有指导模型如何行动的文本描述，也有实际可执行的脚本或命令。为什么要用 Skill 而不是把所有工具直接塞给智能体？因为智能体其实并不知道自己有哪些工具可用，它需要看到描述才知道什么时候该调用什么。Skill 起到的是“元信息层”的作用，让模型能在正确的情境下找到正确的工具。

一个典型的 Skill 目录长这样：

skills/ file-organizer/ SKILL.md main.py requirements.txt

SKILL.md是这个 Skill 的描述文件，顶部通常带一段 YAML front matter，用于声明元信息；main.py是实际执行逻辑；requirements.txt是依赖清单。Harness 在加载 Skill 时，首先读取SKILL.md，把描述信息注入到智能体的系统提示词中，当模型决定使用该 Skill 时，再由框架运行对应的脚本或代码。

SKILL.md的格式大致如下：

--- name: file-organizer description: 当用户需要整理目录、移动文件、按类型分类时使用。 version: 1.0.0 tools: - list_directory - move_file allowed_paths: - workspace --- # 文件整理助手 该 Skill 用于对指定目录内的文件按扩展名分类归档。 ## 使用规则 - 只处理用户显式提供的目录路径。 - 不要删除任何文件。 - 如果有同名文件，自动追加时间戳后缀。

这里有一个非常关键的细节：让模型知道“什么时候不要用这个 Skill”和“什么情况下不要做什么事”，往往比告诉它能做什么更重要。因为模型的触发判断依赖的是description和正文描述，边界写得越清楚，误触发的概率越低。

4.2 亲手写一个可运行的 Skill

直接上一个实际可用的例子，Skill 的功能是“整理文件”。首先在skills/file-organizer/下创建main.py：

import os import shutil import sys import time def organize(directory: str) -> dict: category_map = { "图片": [".jpg", ".jpeg", ".png", ".gif", ".webp"], "文档": [".pdf", ".docx", ".txt", ".md"], "表格": [".xlsx", ".xls", ".csv"], "压缩包": [".zip", ".tar", ".gz", ".7z"], } stats = {"moved": 0, "folders": []} for filename in os.listdir(directory): filepath = os.path.join(directory, filename) if not os.path.isfile(filepath): continue ext = os.path.splitext(filename)[1].lower() target_dir = None for category, extensions in category_map.items(): if ext in extensions: target_dir = category break if target_dir is None: target_dir = "其他" output_dir = os.path.join(directory, target_dir) os.makedirs(output_dir, exist_ok=True) new_path = os.path.join(output_dir, filename) if os.path.exists(new_path): base, ext2 = os.path.splitext(filename) new_path = os.path.join( output_dir, f"{base}_{int(time.time())}{ext2}" ) shutil.move(filepath, new_path) stats["moved"] += 1 stats["folders"].append(target_dir) return stats if __name__ == "__main__": result = organize(sys.argv[1]) print(result)

这个 Skill 的核心是，它接收一个目录路径作为参数，然后按扩展名把文件移动到对应分类文件夹。脚本本身没有任何模型参与，它的价值体现在：模型通过SKILL.md的描述决定要不要调用它，调用时由 Harness 把用户需求中的路径提取出来作为参数传入。这种“模型负责判断、脚本负责执行”的分工，是 Agent 工程中最常见的协作形式。

写好之后，在SKILL.md中给一个参数示例，比如“当用户说‘把桌面的文件整理一下’时，提取桌面路径传入 directory 参数”。这样模型的意图理解和参数提取就有了具体导向，而不是让它自己去猜。

4.3 让多个 Skill 在智能体之间复用

多智能体场景下，Skill 不是某个智能体独有的玩具，而是可以被多个智能体按需复用的公共资产。比如一个“搜索网页摘要”的 Skill，规划智能体可以用它来查资料，执行智能体也可以用，审核智能体还可以用来核对事实。Harness 的加载机制按名称去遍历skills/目录，只要在某个 Agent 的配置中声明引用它，就能挂到该 Agent 的工具列表里。

但复用也带来了几个新问题。第一是 Skill 命名冲突，两个不同目录里如果声明了同名的name，加载时会出现相互覆盖。解决办法很简单：给 Skill 起独特前缀，比如file-organizer改成yit-file-organizer。第二是权限重叠，多个 Skill 都允许写文件时，如果没有路径约束，模型可能会用一个 Skill 删掉另一个 Skill 生成的文件。我的习惯是在 Skill 声明中尽量缩小allowed_paths范围，核心原则是“只给智能体刚好够用的权限，不给多余权限”。

还有一个值得注意的点是模型在匹配 Skill 时，对description的措辞非常敏感。如果你写得太泛，比如“处理文件”，模型会频繁误选；如果你写得太具体，模型又可能在需要变通处理时找不到对应 Skill。好的描述应该是“触发条件 + 功能概述 + 限制条件”三者并存的，比如：“当用户需要整理目录文件或按扩展名分类时使用，支持移动、重命名。不处理系统目录和隐藏文件。”这种句式给了模型足够的决策依据。

4.4 多智能体编排的三种常见模式

把 Skill 准备好，其实只是多智能体的前菜，真正的重头戏是编排放置。我在项目里总结出三种最常用的编排模式，它们分别适配不同性质的任务。

第一种是流水线模式（Pipeline），也是最容易理解和最容易实现的模式。任务被拆成一串顺序执行的节点，每个节点是一个智能体，前一个的输出作为后一个的输入。比如“写代码—跑测试—代码审查”就是一个典型流水线。这种模式适合任务依赖关系非常明确、几乎不存在分叉的场景，配置简单，结果路径清晰。

第二种是路由模式（Router）。在这种模式下，有一个调度智能体先分析用户输入，判断任务类型，再把任务转发给对应的专用智能体。比如有一个“客户工单处理系统”，调度者先判断工单是技术问题、账单问题还是投诉，然后分给不同的处理专员。路由模式的优点是可以应对各种未知请求，缺点是调度智能体本身的判断质量会直接影响整个系统。

第三种是图模式（Graph），也是适合复杂任务的模式。任务不再是线性的，而是有并行分支和汇聚点。比如一个“市场调研任务”可以同时起三个分支：一个查行业报告、一个分析社交媒体热词、一个整理竞品动态，最后再汇聚到写报告节点。Harness 在配置上通常都支持这种 DAG 描述，我会在下一节的实战案例里给出具体的配置参照。

5. 实战案例：一个可复现的多智能体工作流

5.1 场景设定与智能体分工

理论讲再多，不如跑一个完整案例。我们目标很明确：做一个“技术调研报告生成器”。用户输入一个技术主题，系统自动生成一份结构清晰、带事实依据的 Markdown 调研报告。这个过程一个人完成容易偏颇，所以我拆成四个角色。

Planning Agent 负责拆解任务，把“写一份调研报告”变成“主题拆解、资料收集、内容写作、质量复核”四个步骤，并输出大纲。Research Agent 负责根据大纲逐项检索资料并生成摘要，它不需要写最终报告，只需要把每个条目下的核心观点提炼出来。Writing Agent 负责把资料摘要组织成通顺的正式报告，包括技术背景、核心特性、优缺点分析和适用场景。Review Agent 负责最后检查报告是否存在事实性错误、格式问题明显的地方，如果发现问题，返回给 Writing Agent 或 Research Agent 去修改。

这个分工是有讲究的。Planning Agent 需要强推理能力，所以模型和 Temperature 可以按高质量规划来配置；Research Agent 追求事实准确，Temperature 要低；Writing Agent 需要一定的表达多样性，Temperature 可以稍微调高；Review Agent 又需要严谨，Temperature 要回到低位。整体上，一个多智能体团队的温度曲线应该是“低—低—高—低”这样的分布，而不是所有角色都用一个值。

5.2 编排配置与参数调整

在 Harness 项目里，这一步就是把上述分工落到配置文件中。假设我们使用 DeepSeek 的 chat 模型作为所有 Agent 的后端，那么一个简要的智能体配置可能是这样的：

agents: planner: model: deepseek-chat skills: - task-decompose temperature: 0.2 max_tokens: 2048 researcher: model: deepseek-chat skills: - web-research - article-extract temperature: 0.1 max_tokens: 3072 writer: model: deepseek-chat skills: - markdown-writer temperature: 0.7 max_tokens: 4096 reviewer: model: deepseek-chat skills: - review-checker temperature: 0.1 max_tokens: 2048

然后编排定义可以用类似这样的流程来描述：

flow: - id: t1 agent: planner task: "将用户主题拆解为3-5个核心章节，输出大纲Markdown" output: outline - id: t2 agent: researcher input: outline task: "针对大纲每个章节检索资料，输出结构化摘要" output: notes - id: t3 agent: writer input: notes task: "根据摘要撰写完整调研报告，输出Markdown正文" output: draft - id: t4 agent: reviewer input: draft task: "检查报告的事实性和格式规范性，输出问题列表" output: issues

实际跑这个流程的时候你会发现，每个 Agent 输出的内容并不像你预期的那么稳定。有一次 Research Agent 返回的摘要把一篇博客文章的作者名和发布时间丢了，导致 Writing Agent 写出来的报告里出现了没有来源的断言。后来我在 Researcher 的 Skill 里面加了一条硬性规则：每个摘要条目必须包含来源 URL、作者、发布日期和原文结论，否则视为无效输出。模型确实会因为这样的显式约束而改变内部行为，这是 Agent 工程里一个很重要的经验：你不是在写 Prompt，你是在给模型的输出定验收标准。

5.3 运行结果分析与优化方法

跑完一次完整流程之后，不要急着把报告拿走，先看几组关键指标。Harness 会输出每个 Agent 的耗时、Token 消耗、工具调用次数和成功/失败状态。如果你的 Research Agent 工具调用次数特别高，可能是它没有用好摘要功能，而是一次次去抓取全量网页；如果你的 Writing Agent 在短时间内就输出了大段没有依据的内容，说明 Reseacher 的摘要质量或字段完整性没达标。

优化时最有效的手段是“削足适履”，也就是直接调整对应 Agent 的 Skill 描述和任务描述，而不要全局改 Prompt。比如上面提到的来源缺失问题，我只改了 web-research Skill 的正文，其他 Agent 完全没有动。这种局部修正的好处是，不会因为改了一个地方导致另一个环节回归。多智能体系统最让人头疼的就是回归问题，你明明只调了写报告的温度参数，却可能让 Review Agent 误判了所有输出格式，所以在改配置之前，先想清楚这个参数到底会影响哪一层。

我还会在每个 Agent 的配置里打开详细日志，并把中间产物保留在项目目录的artifacts/下面。这样一旦结果出了问题，你可以回溯到具体那一步，看到哪个 Agent 吞掉了关键字段。多智能体的调试思路和单模型完全不一样，你要把链路当成一条管道，任何一段变窄了，都要先找到“淤积点”，而不是在下游反复疏通。

6. 常见问题与排查速查表

6.1 高频问题汇总

这一节直接把我在实践中碰到的高频问题做成一个速查表，方便你定位：

6.2 排查思路与日志定位

遇到问题的时候，第一反应不应该是去改配置，而是先看日志。我在本地调试时一般开三个终端：一个跑 Harness 的服务日志，一个跑 Hermes 的详细模式日志，还有一个用tail -f观察数据流目录里的文件变化。Hermes 的详细模式通常只需要加一个--verbose参数，就能把每次模型请求和工具调用的完整记录打出来，Harness 则可以通过内置的日志命令查看插件加载记录和流程执行明细。

排查有一个固定顺序：先从“连通性”开始，确定模型 API 没问题；再看“工具调用”，确定 Skill 有没有被激活；接着看“上下文传递”，确定前一个 Agent 的输出有没有完整落到下一个 Agent 的输入；最后才去怀疑“模型能力”。很多人一开始就怀疑这个模型“太笨、不会用工具”，其实绝大多数情况都是前面的管道没接好。

如果你遇到failed to load plugins web boot: 2 entries did not activate，我在 Linux 上的处理方式是先列出插件状态：

harness plugins list

这个命令会打印插件名、版本号和激活状态。看到哪两个插件处于inactive状态后，再去看是不是有同名插件冲突。如果某个插件是由两个目录同时加载的，Harness 通常只会激活先扫描到的那一份，另一份就被标记为未激活。清掉旧目录里的重复包就能解决。

6.3 几条防护性习惯

基于我踩坑和修 bug 的经验，最后分享几条能让你少熬夜的防护性习惯。第一是常备虚拟环境，无论是 Python 还是 Node，都尽量在新项目中创建独立环境，不要在全局环境里装 Agent 相关的依赖。第二是固定版本号，在多智能体项目里，框架一升级可能连配置格式都会变，所以我把依赖版本锁死，升级时先看 changelog 再操作。第三是定期清理日志和中间产物，有些 Agent 在工作时会生成大量的临时文件，不清理的话，即使任务逻辑没问题，磁盘空间也会被吃光。

还有一点是时间戳和命名规范。多智能体流程跑几轮之后，你会发现output.md这种固定文件名会被后来的 Agent 覆盖。我的做法是在每个流程定义里让中间产物带上流程 ID 和时间戳，比如report_20250101_0930_outline.md。这样即使后一轮出现错误，前一轮的产物还在，可以直接拿来做对比。

说到最后，我自己的体会是，多智能体这件事最难的地方不是把多个模型接起来，而是让它们各司其职、互不干扰。Harness 的优势在于给了你一个把流程、Skill、Agent 和工具都管理起来的框架，Hermes 的优势在于让模型接入这件事变得足够简单。两者配合起来之后，你真正需要投入精力的地方就变成了任务拆解和 Skill 设计，而这两个方向恰恰是长期积累的能力，不是换个框架就能替代的。先把单个智能体跑稳，再慢慢往流程里加角色，你会比一开始就搭一个庞大系统的人轻松很多。