企业官网建设流程全解析

最近在折腾多智能体应用时，我把原来的单 Agent + 函数调用脚本整个重构成了 DeepSeek Harness 的 workflow。跑通之后的第一个感受是：Agent 编排 Agent 这件事，终于不是靠手写一堆 if-else 在那里生扛了。简单说，DeepSeek Harness 是一个围绕 DeepSeek 系列模型设计和优化的 Agent 编排与工作流系统，它让你用一个主代理统一接收用户请求，再动态创建或调用若干子代理分头干活，这些子代理之间的顺序、条件、工具调用，全部可以在一个可追踪的工作流里定义。如果你正在玩 Agent 开发，或者想把几个大模型任务串成一条更可靠的生产链路，这套东西值得花时间看看。

1. Agent 编排 Agent：为什么需要一套 Harness

1.1 单 Agent 的天花板

我们先聊一个特别常见的问题：为什么不直接在一个 Agent 里把所有任务都做完？

我刚开始做 Agent 项目时，习惯把所有工具、所有 prompt、所有知识一股脑塞进同一个 Agent。任务简单的时候确实省事，但一旦任务变复杂，问题就来了。比如让 Agent 先分析一张表格，再根据分析结果生成一份报告，最后把报告通过邮件发出去。这三步如果放在同一个 Agent 里，prompt 会越写越长，工具选择会互相干扰，模型经常在第一步就调用错了工具，或者在第二步把第一步的中间结果给忘了。逻辑上这不是模型智商不够，而是上下文和管理职责全都搅在了一起。

这时候你就需要一个"老板"来管事情。主代理负责理解任务、拆解任务、派发任务，子代理负责具体执行。每个子代理只维护自己的 prompt、技能和记忆，不关心上下游在做什么。这就是 Agent 编排 Agent 的核心价值：用一个有全局视角的主代理，去调度一批职责单一的子代理。等于把一个大杂烩的问题，拆成了几个小团队的问题。

1.2 DeepSeek Harness 的核心定位：编排层的"缝合怪"

我理解的 DeepSeek Harness，不是一个模型，也不是一个普通对话框应用，而是一个位于模型之上、专门负责调度和状态管理的智能体编排层。它跟你直接用 DeepSeek API 的最大区别，是它替你解决了"任务到底该由哪个 Agent 干"这件事。

它针对 DeepSeek 系列模型做了不少适配，尤其是推理模型的思考模式。你可以在配置里指定连接本地部署的 DeepSeek 模型，也可以连兼容 OpenAI 接口的远程服务。除了模型连接，它还给编排这个动作提供了三种关键能力：第一，子代理注册与管理，每个子代理像一个小微服务一样有名字、有描述、有技能列表；第二，工作流定义，用声明式配置把子代理、工具、条件分支、输入输出映射串起来；第三，插件机制，允许你把自定义工具或技能打包成插件懒加载。

这三件事单独拎出来，每一件都能找到更好的专用工具。但合在一起，并且专门为 DeepSeek 优化，这才是 DeepSeek Harness 的差异化价值。它更像是一个"缝合怪"，把模型接入、任务路由、上下文管理、工具扩展这些 Agent 项目里最琐碎的脏活都接住了，让你把精力放在业务逻辑上。

1.3 与 Dify、n8n、AutoGen 这类平台有什么不一样

很多人会问，这不就是 Dify 或者 n8n 吗？我实际对比过，差别其实挺明显。

Dify 更偏向 RAG 和可视化应用搭建，适合快速把知识库问答、聊天机器人做出来；n8n 是通用自动化工具，重点在系统之间做数据流，对 Agent 的语义理解支持比较弱；AutoGen 是对话式的多 Agent 框架，所有 Agent 通过自然语言你来我往，可控性差一些。DeepSeek Harness 没有走可视化拖拽为主的路线，而是把"子代理 + 工作流"当成第一等公民。它的 workflow 像一条明确的流水线，每一步会执行什么，结果传递给谁，失败后走哪条分支，都可以在配置文件里写清楚。

这对开发者的友好之处在于，你可以像写代码一样去 review 一个 Agent 应用，而不是靠肉眼在画布上检查连线。所以我的判断是：如果你想要的是快速搭一个演示应用，Dify 很合适；如果你想要一个更可控、更接近编程思维的多 Agent 编排底座，DeepSeek Harness 更对味。

2. 子代理系统到底怎么"编排"子代理

2.1 子代理的注册、路由与执行机制

在 DeepSeek Harness 里，子代理不是一个抽象概念，而是一个实实在在的配置单元。你注册一个子代理时，通常要提供名字、职责描述、可用的技能列表、绑定的模型实例，以及一个系统 prompt。这些信息里，职责描述尤其重要，因为主代理在路由时主要就是靠它来匹配。

路由机制一般有两种。一种是动态路由，主代理拿到用户任务后，先通过模型推理分析任务需要哪些能力，再从注册表里选出合适的子代理。这种路由方式灵活，但偶尔会选错。另一种是静态路由，完全按工作流规则走，比如当输入文本包含"写代码"字样时，固定走 code_agent。静态路由稳定可靠，但不够聪明。我用下来的建议是，以动态路由为主，同时在关键节点加上静态规则兜底。比如主代理已经判断出需要生成代码，就不要再让它重新思考一次，直接让 workflow 的条件分支把任务转到 code_agent。

执行机制上，一个子代理被调用后，并不是直接把整个用户问题丢给它。主代理要做的是把子任务目标、输入数据、输出格式要求，封装成一个独立的任务包交给子代理。子代理只对这个任务包负责，执行完返回结构化结果。这个"封装"动作是编排系统最容易忽略的地方，很多项目里子代理跑偏，就是因为它拿到的上下文太宽，不知道到底要干什么。

2.2 Skill、Tool 和子代理到底怎么分

我见过不少人把 Skill、Tool、Agent 这三个概念混着用，结果整个项目越写越乱。这里我给出一个我在实践里验证过的划分方式。

• Skill 是一个可复用的知识包或指令包，它描述的是"怎么做这件事"的规则、步骤、注意事项，不直接执行任何操作。
• Tool 是一个具体的可执行函数，比如查数据库、调用搜索引擎、执行一段 Python 代码，它是原子能力。
• Agent 是一个有大脑的执行单元，它内部持有模型实例，可以有 prompt、skill、tool，并能根据输入决定什么时候调用哪个 tool。

举个例子：给子代理配一个"数据分析思维"的 skill，里面写清楚了拿到数据后先看缺失值、再做分布分析、最后给结论；同时给它配一个"Python 代码执行器"工具，让它真的能去算数据。skill 提供方法论，tool 提供执行力，子代理则是那个在两者之间做决策的"人"。

新手最容易犯的错，是给一个子代理塞五六个 skill、十几个 tool，觉得这叫能力强。实际上模型在大量工具里选错工具的概率会直线上升。我自己现在的原则是：一个子代理最多挂 3 个核心 skill、5 个以内的 tool。超过这个数，就应该拆成两个子代理，让主代理去协调。

2.3 子代理之间的上下文传递和记忆隔离

多 Agent 系统里最麻烦的坑，不是模型不够聪明，而是上下文互相污染。子代理 A 执行完任务后，如果你把它的完整对话历史全部塞给子代理 B，B 很可能会被无关内容带偏，而且 token 消耗会迅速膨胀。

我习惯的做法是"结构化摘要传递"。每个子代理返回的不再是一长段自然语言，而是一个带字段的结果，例如{"status": "success", "summary": "...", "artifacts": {...}}。主代理只保留这个摘要，再根据摘要决定下一步。子代理内部的详细思考过程、中间输出，都不回传。这样每个子代理都像是拿着一个干净的工单在干活，而不是背着前面所有同事的聊天记录。

DeepSeek Harness 的 workflow 在这一点上做得比较顺手。它的节点输出允许你指定映射规则，比如"提取返回结果中的 summary 字段，丢弃 raw_output"，然后把这个字段传给下一个节点。有了这种机制，上下文管理就从靠模型自觉，变成了流程上的强制约束。

3. 实操：在 DeepSeek Harness 里搭一个多代理工作流

3.1 环境准备：从下载到跑通

我先说下我这边实际跑通的环境，给你一个参考。

• 操作系统：Ubuntu 22.04，Windows 也可以，但命令会略有差异
• Python 3.10+，建议用虚拟环境
• 一个能从本机访问到的模型推理服务，或者 DeepSeek 官方 API key
• Git，用来拉取一些示例配置和插件仓库

安装 DeepSeek Harness 本身不算复杂。如果你是第一次装，我建议先创建一个干净的虚拟环境，然后执行：

python -m venv harness_env source harness_env/bin/activate pip install deepseek-harness

这只是最常见的安装方式之一，不同版本的参数可能略有差别。装完后直接敲一下版本号确认环境没问题：

deepseek-harness --version

如果输出了版本号，说明基础依赖装好了。接下来最容易被卡住的一步不是安装，而是把 Harness 和本地模型连接起来。

3.2 连接本地模型，开启思考模式

DeepSeek Harness 支持对接多种模型服务，但核心是让 Harness 知道你的模型地址和模型名。我比较喜欢使用配置文件来管理，比如config.toml：

[llm] base_url = "http://localhost:11434/v1" api_key = "local-dummy-key" model = "deepseek-r1" thinking_mode = true reasoning_effort = "medium" temperature = 0.1 max_tokens = 4096

这里有几个参数需要解释一下。base_url指向本地模型服务，如果你用的是兼容 OpenAI API 的服务，这个地址一般就是http://127.0.0.1:端口/v1。api_key本地服务通常不校验，随便填一个占位符就行。thinking_mode是核心，开启后会走模型自身的推理思考链路，让主代理在拆解任务时更细致，但相应的响应时间会变长。

我实测下来的经验是，如果任务只是简单分类，比如判断用户输入属于"写代码"还是"写文档"，直接用普通对话模式就够，不需要开启 thinking，否则每次路由都要等十几秒。如果是复杂任务，比如让主代理同时分析需求、设计子任务、还要兼顾多个约束条件，那一定要开 thinking，否则拆出来的任务往往缺斤少两。

3.3 设计一个"项目助理"工作流

现在我来搭一个相对完整的小场景。假设用户输入一句话："帮我写一个统计 CSV 文件行数的 Python 脚本，并写一段使用说明。" 我们希望主代理先拆解任务，然后 code_agent 负责写代码，doc_agent 负责写说明，最后主代理汇总输出。

在 DeepSeek Harness 里，这个工作流可以写成下面的 YAML 配置（简化示意，字段可能随版本略有不同）：

name: project_assistant version: 1.0 agents: orchestrator: model: deepseek-r1 role: coordinator system_prompt: | 你是项目主代理。你的任务是把用户请求拆解成具体子任务， 分配给最合适的子代理。所有子代理返回后， 你必须汇总形成最终答案，不得以任何理由推卸责任。 code_agent: role: coder system_prompt: | 你只负责编写代码。给定需求后，返回可直接运行的脚本。 输出格式为 JSON：{"code": "...", "usage": "..."} tools: - code_interpreter doc_agent: role: writer system_prompt: | 你只负责根据代码和需求写使用说明。 输出格式为 Markdown 文本。 workflow: nodes: - id: start type: trigger next: orchestrator - id: orchestrator type: agent agent: orchestrator next: route_by_action - id: route_by_action type: condition conditions: - when: "orchestrator.result.action == 'code'" next: code_agent - when: "orchestrator.result.action == 'doc'" next: doc_agent - default: end - id: code_agent type: agent agent: code_agent next: orchestrator - id: doc_agent type: agent agent: doc_agent next: orchestrator

这个配置的核心是route_by_action这个条件节点。主代理不是直接告诉用户答案，而是先输出一个带着action字段的结构化结果，说清楚下一步应该走 code 分支还是 doc 分支。然后工作流就把任务交给对应子代理执行，子代理的结果再回到主代理手里做汇总。

这个设计有几个好处。第一，主代理不需要事先知道所有答案，它只需要知道"这个任务该谁干"；第二，条件分支是显式写出来的，比完全靠模型自由发挥稳定得多；第三，子代理是隔离的，code_agent 永远不用担心自己还要写文档。

3.4 运行并观察日志

配置写好之后，运行命令非常简单：

deepseek-harness run --workflow project_assistant.yaml --message "帮我写一个统计 CSV 文件行数的 Python 脚本，并写一段使用说明"

跑起来之后，你会看到终端里依次出现几条关键日志：

[orchestrator] 正在分析用户请求... [orchestrator] 决策结果：action=code, reason=需要生成Python脚本 [route] 命中条件 code -> 进入 code_agent [code_agent] 开始执行 [code_agent] 返回结果：code=..., usage=... [route] code_agent 完成 -> 回到 orchestrator 汇总 [orchestrator] 检测到还需生成使用说明，调起 doc_agent [doc_agent] 开始执行 [doc_agent] 返回 Markdown 说明 [orchestrator] 汇总最终答案

日志的价值在于，你能看到主代理每走一步的决策依据。如果在某个节点上结果不对，不需要猜，直接看日志里action的取值就能排查。比如明明需要写文档，主代理却输出了action=code，那大概率是它的 system_prompt 里没有强调"要同时生成说明"。

另外我强烈建议，所有子代理的输出格式都用 JSON，并且在主代理的汇总节点里要求"只输出最终答案，不要重复代码和分析过程"。这样最终给到用户的文本会干净很多，不会出现前面所有子代理的话全都被拼接上来的情况。

3.5 用插件机制扩展能力

如果只靠内置工具，编排能力还是有限。DeepSeek Harness 的插件机制允许你引入自定义能力。一个插件通常是这样的目录结构：

my_plugin/ plugin.json handler.py requirements.txt

其中plugin.json描述插件名、入口和暴露的工具名称：

{ "name": "my_plugin", "version": "0.1.0", "entry": "handler.py", "tools": ["fetch_web_page"] }

安装插件的常规动作是把插件目录放到 Harness 的插件目录下，然后重新扫描：

deepseek-harness plugin install ./my_plugin deepseek-harness plugin list

插件加载生效后，就可以在子代理的tools配置里直接写fetch_web_page。这一点我觉得挺像 VS Code 的扩展机制，插件的开发体验直接决定了生态能做多大。如果你有内部系统要接，比如公司里的数据平台、工单系统，写成插件工具是最干净的方式。

4. 常见问题与排查技巧实录

4.1 子代理互相"踢皮球"，活没人干

我遇到过最典型的问题，是主代理把任务派下去之后，子代理又把任务抛回主代理，主代理再派回去，两个 Agent 在对话里绕圈，最后超时。表面上看起来是模型抽风，实际原因是角色边界没划清楚。

解决方案有两个层面。第一，在主代理的 system_prompt 里加强制约束，比如"所有子代理返回后必须由你汇总并产出最终答案，任何情况下都不能把问题原样抛回给用户或子代理"。第二，在 workflow 配置里设置最大执行步数，比如最多允许 6 次节点跳转，超过就强制结束并返回当前部分结果。

我建议你把第二点当成保险丝，永远不要只依靠模型自觉。多 Agent 系统一旦跑起来，什么奇怪的循环都有可能发生，设置硬性上限是成熟项目的基本素养。

4.2 上下文爆掉，或者子代理"失忆"

另一个高频问题：任务链比较长时，主代理到后面忘了最开始的需求。你仔细追问，会发现它不是真的忘，而是子代理返回的结果太多，把最早的用户原始需求挤出了上下文窗口。

解决这个问题，我推荐两个技巧。第一，在传给子代理的任务包里，始终重复一遍原始用户需求和本次子任务目标，不要省这个 token。第二，每个子代理返回时，强制只返回摘要和结构化关键字段，不要返回完整的对话历史。

在 DeepSeek Harness 里，可以通过节点的输出映射来丢弃大字段。比如：

- id: code_agent type: agent agent: code_agent output_map: keep: [summary] drop: [raw_output, reasoning] next: orchestrator

drop字段是我自己常用来控制上下文的手段。每丢弃一个大字段，后续主代理的上下文压力就小一分。

4.3 插件加载失败、依赖冲突

插件系统用多了，最容易遇到的就是ImportError或者包版本冲突。比如某个插件依赖了requests，而你的主环境里已经装了一个不兼容的版本，启动时直接报错。

我踩过坑之后，现在的做法是：每个插件写好requirements.txt，安装时尽量让 Harness 在一个隔离环境里跑插件，或者干脆在插件 handler 里延迟导入第三方库，避免在模块加载阶段就触发冲突。

如果插件加载失败，先不要慌，用下面这个顺序排查：

1. 在终端手动运行插件的入口，看能否正常导入。
2. 确认插件目录权限和路径是否正确。
3. 查看日志里有没有具体的报错堆栈，重点关注ImportError和ModuleNotFoundError。
4. 如果依赖冲突，给插件建独立环境后让 Harness 指向该环境的解释器。

这一步其实不算 DeepSeek Harness 的问题，而是所有插件化系统的通病。你只要记住"隔离依赖"四个字，就能少踩一半坑。

4.4 思考模式下响应超时

开启思考模式后，经常会出现等了很久也没回结果的情况。我先排查方向：一是模型服务本身是否支持 reasoning 能力，如果你用的模型名称不是 deepseek-r1，而是deepseek-chat之类的普通对话模型，开启 thinking_mode 可能会卡住或者返回空内容。二是本地显存不足，思考模式对显存的要求比普通模式高不少，跑不动的时候服务会一直转圈子。

实际处理办法很简单：先在配置里把思考模式关掉，看任务能不能正常跑通。如果能跑通，说明模型服务没问题，只是思考模式下的资源或超时设置有问题。接着调大 Harness 的timeout：

[llm] timeout = 120

如果调大超时后还是经常失败，那就老老实实把thinking_mode关掉，或者换一个更小规模的模型来做主代理。你要明白，不是所有任务都需要深度推理，把资源用在真正复杂的拆解上，才是合理的使用方式。

最后再分享一个我在调试时最常用的技巧：在 workflow 的所有关键输出节点都加一个便于观察的reason字段，让主代理解释自己为什么要走这条路。这样一旦结果不对，你能像看代码注释一样快速理解系统每一步的决策逻辑。多试几轮之后你会发现，真正限制一个多 Agent 系统上限的，往往不是模型智商，而是任务拆分的颗粒度和上下文管理的纪律。把这两件事想清楚，Agent 编排 Agent 的能力才能真正释放出来。