在同一轮对话里，让一个 Agent 去完成“信息收集、文档整理、多表比对、结论输出”四件事，跑到第三步时上下文已经被工具返回和临时变量塞得乱七八糟，这是我最初做批量筛选类自动化项目时最挫败的地方。后来我开始尝试“Agent 编排 Agent”的思路，把任务拆成多个职责单一的子代理，再由一套工作流引擎决定它们的执行顺序、输入输出和失败回退。这套方案落地之后，我长期打交道的工具是 DeepSeek Harness。它提供的不是一个大而全的聊天壳子，而是一套集成了子代理与工作流管理的骨架：你可以定义角色、技能、节点、跳转条件，把原本纠缠在单个上下文里的任务，拆成一段段可以独立跑、独立调、独立重试的流水线。这篇分享适合正在折腾多 Agent 编排、到处搜工作流编排示例，或者想把可控的 Agent 工作流部署到内网服务器上的同学。我会按自己的实际使用顺序来讲，尽量说清楚原理，也给得出可以直接抄走的配置思路。
1. 从单 Agent 到子代理编排，我为什么最后把 Harness 当骨架
1.1 单个 Agent 的瓶颈不在智商，在上下文和职责
我举个常见的例子。让一个 Agent 去处理“整理十份行业报告，提取关键趋势，再按团队关注点排序，最后写成周报”这类任务。表面上看，现在的模型很强，能读、能总结、能排序，但你在同一个上下文里让它连续做四件事，跑到最后一步往往会发现，它对最前面几份资料的关键信息开始含糊。这不是玄学，而是上下文窗口里的信息密度问题：越早的输入，被后续的工具返回、临时变量、对话历史挤压得越厉害，模型即便理论上“看得见”全部内容，判断时也只会优先采信靠后或重复出现的信息。这种上下文漂移会让你觉得模型忽然变笨了，其实只是你把太多无直接关系的职责耦合到了同一个工作单元上。
这个现象用生活里的事特别好理解：让一个新人同时当资料员、复核员和发件人，他每换一个角色都要重新回忆规则，来回切换必然出错。子代理的核心思路，就是把任务切碎，每个 Agent 只处理一个边界清晰的子任务，拿到固定的输入契约，输出固定的结果结构，再交给下一个环节继续处理。整体看起来像一条由多个 Agent 组成的流水线，这正是“Agent 编排 Agent”要解决的问题。
但我得先泼一盆冷水：不是所有模型调用都需要编排。单 Agent 失效是从某个复杂度阈值开始的。当任务步骤小于三个、输入规模可控时，直接问模型反而更高效。只有当任务会重复执行、步骤之间状态依赖强、并且对可审计性有要求时，单 Agent 方案才会明显失控。DeepSeek Harness 的价值就在这个阈值之后才开始体现。
1.2 先分清概念：Harness 是执行环境，Agent 是工作单元
在这个生态里提到 Harness，很多人第一反应是“封装”，没错，Harness 给我的感觉更像一个“带流程控制能力的执行环境”。我理解的核心区别是：Harness 负责编排，Agent 负责干活。Harness 本身不产生智能，但它知道子代理之间怎么排队、怎么传数据、怎么重试、怎么回退、怎么收敛结果；Agent 是被 Harness 调度的工作单元，内部拥有模型上下文、工具使用能力和一段明确的职责边界。
| 维度 | Harness 编排层 | Agent 子代理 |
|---|---|---|
| 职责 | 流程控制、状态存储、分支跳转、失败处理 | 单步推理、工具调度、结果生成 |
| 生命周期 | 跟随工作流整体存在 | 单次任务调用，结束后释放上下文 |
| 输入 | 上游节点传递的结构化数据 | 由 Harness 按契约注入的参数字段 |
| 输出 | 把子代理结果写进流程状态 | 结构化输出，交给后续节点 |
这个区别虽然简单，但把边界盯清楚之后，设计流程时就不会把过多提示词堆进子代理里。子代理更像“专业咨询顾问”，出一道题答一道题；Harness 像项目经理，控制问题顺序、决定重试时机。社区里经常有人问“harness和agent区别到底是什么”，我的回答一直是这句话：一个是壳，一个是壳里干活的人。后面设计工作流时，按这个边界做，大部分配置冲突会少很多。
1.3 为什么不是手写调用链，而是“编排 + 子代理”
如果说只是想串起几个模型调用，手写代码也行，甚至性能还可能更好。但手写链路有几个很现实的痛点：
- 业务判断会变。比如简历筛选的岗位要求从“看重技术深度”改成“更看重沟通能力”，硬编码里的匹配规则就要跟着动，改错一个参数排查起来很费劲。
- 中间状态难管理。每个步骤依赖前一步的输出，写代码时要么存文件、要么塞内存对象，时间一长就成了没人敢动的泥潭。
- 可观测性差。子代理出了问题，排查只能靠日志，而编排工具往往自带可视化的执行记录和节点级日志。
把判断交给子代理，子代理返回结构化结果，再由外层把结果映射到分支节点，这样做的好处是规则变化被收敛到了提示词和流程配置里，不需要动主代码。我把这套模式称为“Agent 编排 Agent”：外层编排负责流程，内层 Agent 负责理解。DeepSeek Harness 给的就是这套外层能力，配上一套子代理执行模型。接下来我拆一下它内部的工作流引擎到底怎么理解。
2. 拆开看：工作流里的节点、连线和状态到底是怎么跑的
2.1 并不是在画流程图，而是在定义执行协议
我习惯把工作流引擎里的每个节点看成“带执行入口的小进程”。常见节点包括：子代理节点，调用一个 LLM 子代理执行推理任务；工具节点，执行已注册的技能或脚本，比如读文件、查库、调内部接口；条件节点，根据上一步的结构化字段做判断，决定走哪条分支；聚合节点，把多个上游输出合并成下一步的输入；模板节点，把最终状态渲染成 Markdown、Word 或邮件正文；代码节点，在受限环境里跑一小段脚本，用于清洗和校验数据。
这些节点靠连线串起来，但连线不只是画出先后顺序，还包含数据映射：哪些字段从上游取，哪些字段注入到下游节点。我第一次使用的时候犯过一个大错：默认以为连线就是顺序执行，真正跑起来才发现，如果不显式配置字段映射，下游拿到的可能是一整包 JSON，既浪费 token 又容易让子代理看错字段。
把节点之间的交互理解成“协议”而不是“调用”，对工作流设计帮助很大。每个子代理节点的输入输出都有 schema，输入表明“我只消费这些字段”，输出表明“我生产这些结构”，这样外层 Harness 才知道怎么对齐数据。打个比方：工作流像工厂传送带，节点像工位，连线像传送带本身，字段映射像每个工位前面的物料清单。清单写得不清楚，工位效率一定上不去。
2.2 上下文超长多半是状态传递问题，不全是模型窗口小
使用一段时间之后，最常遇到的报错就是“上下文超长”。第一次遇到时我莫名其妙：明明每个步骤看起来都不复杂，为什么会爆？后来发现根子是状态传递方式太粗糙——默认把上游节点的完整历史一股脑塞给下一个节点。
解决思路其实很直接：给每个子代理设计极简的输入契约。
- 在上游节点输出时做裁剪，只保留后面需要的字段；
- 对长文档类字段先做摘要节点，再传给需要语义判断的子代理；
- 对所有子代理要求结构化输出，并把最终输出写回状态时明确字段名；
- 必要的时候用上下文压缩插件，把历史记录折叠成几行摘要再注入下一节点。
一个示意性的配置片段，主要看字段传递方式：
nodes: - id: collect_docs type: subagent output_schema: summary: string key_points: array - id: compress_context type: context_compactor input_fields: - summary output_fields: - compact_ref - id: analyze_report type: subagent input_fields: - compact_ref在这个片段里，analyze_report 拿到的不是 collect_docs 的全量返回，而是压缩后的摘要引用。中长流程里，这一步能节约大量 token，也把上下文爆掉的时间点大幅后移。不要看到“上下文超长”就以为是模型窗口不够，先检查是不是把中间状态全量往下游塞了。把子代理当成临时专家来调用，专家只需要看他该看的简报。
2.3 分支、重试与代码回退：失败也要有流程
工作流不能只考虑顺畅路径。我花时间最多的其实是失败与回退设计。DeepSeek Harness 在节点级别提供了重试与回退能力，社区里经常提到的“代码回退”也属于这一块。我的理解是：当一个子代理节点出现异常，Harness 可以按策略重试；重试还不行，就走到 fallback 节点。例如：
- TOOL_ERROR：工具调用失败，重试一次；仍失败则转到人工维护队列；
- INSUFFICIENT_DATA：子代理自己声明输入信息不足，走“补充资料”分支；
- SCHEMA_FAIL：输出不符合定义结构，携带校验说明重跑一次；
- HALLUCINATED_CHECK：二次校验节点发现结论与事实冲突，触发回退到上一个稳定检查点。
配置片段可以长这样：
steps: - id: eval_resume type: subagent on_error: max_retry: 2 backoff: exponential fallback: fallback_human_review checkpoint: true我特别强调 checkpoint 这个开关。关键节点前保存一份可恢复的状态快照，所谓“代码回退”就不是把整个流程退到起点，而是像代码仓库回退到某个 tag 一样，带着备注重新跑受影响的分支。长流程尤其需要这个思路，如果一失败就从头跑，前面几十分钟的 token 和时间全部浪费，轮次越多代价越大。
3. 一个完整示例：简历筛选、结构化评估与通知派发
3.1 场景与拓扑设计
简历筛选是所有长文档比较场景里最典型、最能体现子代理拆分价值的例子。我这里选的场景是：招聘负责人在 Harness 里配置了一个“筛选工作流”，输入是岗位 JD 和简历列表，输出是“进入推荐池的简历表 + 统一格式的评估说明 + 通知派发”。
如果用一个 Agent 做，会同时面对“多份长简历导致上下文爆掉”“评估标准前后漂移”“最终表格式混乱”三个问题；拆成子代理后，职责天然解耦：
- JD 解析：只看岗位描述，输出硬性要求、加分项、必填项；
- 简历解析：批量读取简历，把信息转成固定结构，不做评判；
- 匹配评估：依据 JD 解析结果逐项判断简历字段，打分量级并给出推荐；
- 结果汇总：把候选字段和评估分数合并，做排序和去重。
整体拓扑可以看成：入口 -> JD解析 -> 简历解析（并行处理多份） -> 匹配评估（并行） -> 聚合排序 -> 条件分支 -> 通知派发。子代理并行处理多份简历是关键，因为简历之间互相独立，这是天然可并行的场景。
3.2 子代理的 Prompt 设计与职责边界
这里给一个我实际调整过的 JD 解析子代理模板：
你是一个岗位需求解析器。你的任务： 1. 把输入岗位描述整理成结构化字段； 2. 只做信息提取，不做候选人匹配和招聘建议； 3. 输出格式使用 YAML，字段包括： hard_requirements, preferred_requirements, deal_breakers, role_summary 4. 不要输出多余解释；信息缺失请写 None，不要自行补全。 输入岗位描述： {{jd_text}} 输出：对应输出示例：
hard_requirements: - "本科及以上学历" - "5年以上后端开发经验" preferred_requirements: - "有分布式系统经验" - "能熟练使用 Python 和 Go" role_summary: "负责平台后端服务设计、开发与维护"你会发现我特意加了“不要输出多余解释”。原因很现实：多余解释一方面增加 token，更重要的是后续评估子代理读的是结构字段，不是人工语言。结构字段稳定了，后续评估才稳定。简历解析子代理同理，提前定义好姓名、工作经历、项目经历、技能清单、教育背景、联系方式这些字段，让输出固定。匹配评估子代理再拿这些字段去打分，分数旁边还要带一句“得分依据”，方便人工复核。
边界上有一条核心原则：职责不要重叠。简历解析不要顺便评价“这个人看起来不错”，评估子代理也不要顺手改简历字段。各节点保持职责独立，失败才能收敛到具体节点上，否则出了问题，你根本不知道是提取坏了还是评估坏了。
3.3 回退分支在示例里怎么落地
这条流程里最常见的失败是“简历信息缺失”。简历解析子代理如果识别到某些 PDF 是扫描件，或部分字段为空，让它返回 INSUFFICIENT_DATA。Harness 这时不要直接走进评估节点，而是走到“人工补充或排除”分支。这样少数异常简历不会让整批流程崩掉，也不会因为一份坏数据污染其他候选人的评估。
我还建议加一个“二次校验”节点：匹配评估输出分数之后，轻量检查分数与关键词命中数量是否明显不合理。比如一个关键词都没命中但分数给了 85 分，校验节点就要捕获这种异常并触发重新评估。这个校验节点不复杂，但能把模型“自信满满输出幻觉”的情况减少很多。回退不要只想着“重跑一次”，重跑同一次调用大概率还是同一个模型的同一种想法；更合理的是把触发失败的输入做转换、压缩或补充，再送去另一条分支。
3.4 结果输出与通知派发节点
最后的通知派发，可以是一个模板节点把聚合结果渲染成表格文本，再由通知节点调内部消息接口发送。注意通知节点需要独立的超时和重试，因为外部接口不受模型控制。模板最终渲染成“候选人A：通过，得分87，依据：...”，人力复核的成本一下就降下来了。
如果你想把这个示例立刻变成自己用的流程，建议先从“单个 JSON Schema 校验”入手：先让所有子代理输出都能通过你定义的 schema，再扩展成上面的完整流程。先有稳定的标准，再上分支与回退，否则后续迭代会让你手忙脚乱。
4. 安装、插件与内网部署：文档里不会写的那部分
4.1 桌面版、命令行版还是服务器版，怎么选
DeepSeek Harness 在社区里既有桌面版，也有 Linux 服务端版本。我的建议很直接：第一次学习用桌面版，节点执行轨迹的视觉反馈比任何日志都直观；如果任务要定时、长驻、多人协作访问，再放到服务器版上。
安装时如果 Linux 环境装不上，先查三件事：Python 或 Node 的版本是否匹配、是否缺少编译工具链、路径里是否存在中文或特殊字符。我在虚拟环境里安装，给一个最基本的启动配置思路：
# 示意命令，具体包名以实际版本为准 harness init --project my_workflow harness run --workflow resume_screen.yml --config configs/prod.yamlconfigs/prod.yaml 里指向内网模型服务地址，例如model_endpoint: http://internal-model-server:8000/v1。服务端最需要稳住的是任务队列的持久化目录，节点状态写到这里，重启后才能恢复。桌面版和服务端版本质上共享工作流定义文件，所以我的习惯是：桌面版调通流程，导出配置，导入服务端直接跑，让调试环境与生产环境的差异被压到最小。
4.2 技能包如何部署到内网服务器
我不止一次被人问到“DeepSeek Harness 附带的 skill 怎么部署到内网服务器”，这个操作我在不同环境验证过。技能包在我理解里，就是一个目录化的工具包，包含：
- manifest 文件：版本、作者、工具名、入口脚本地址；
- prompts 文件夹：技能相关的系统提示词模板；
- scripts 文件夹：实际的可执行脚本；
- resources 文件夹：参考文档、静态资源等。
部署到内网服务器的步骤一般如下：
- 在开发机上把技能目录打包成 tar 或 zip，不要带临时文件和模型缓存；
- 把压缩包复制到内网服务器指定工作目录；
- 执行导入命令，让 Harness 解析 manifest 并注册技能。导入前可以先校验 manifest 里的路径安全，避免脚本越权写文件；
- 把技能内调用的模型服务地址改成内网地址；
- 用最小用例跑通，再挂到正式工作流。
内网部署最常见的三个坑：一是路径不一致，技能脚本写死了开发机绝对路径，部署后找不到文件；二是依赖缺失，脚本用到的第三方库服务端没装；三是模型端点不对，开发机用了测试模型，切到内网后仍指向原地址，导致反复超时。一个很好的实践是：技能脚本只允许使用相对路径，所有外部变量通过 manifest 注入。这样换环境只需要改环境配置，不用动技能内部代码。
4.3 插件体系：哪些值得装，以及安装要注意什么
插件和技能不完全一样，插件更像能力扩展模块，比如提示词优化、上下文压缩、Markdown 转 Word、模板渲染、代码回退检查。我现在长期在用的有三类：
- 提示词优化插件：把口语化需求改写成结构完整的系统提示词，适合刚入门不熟悉提示词工程的人。但注意优化器本身也是一次大模型调用，小任务用不上，反而增加延迟；
- 上下文压缩插件：对长流程收益最明显，把前序节点输出折叠成摘要，遇到“上下文超长”第一步先考虑它；
- 输出渲染插件：把工作流结果渲染成 Markdown、Word 文档或邮件正文，在交付类任务里很实用。
安装插件时，我坚持只装来源明确的仓库，并且手动审查 manifest。插件本质是可执行代码，它有能力访问工作目录、配置文件和环境变量。来源不明的插件放进生产环境，等于把后门交给陌生人；内网环境虽然不直接暴露在外网，但低质量插件依然会带来稳定性和数据泄露风险，这属于安全问题而不是单纯选择问题。
5. 多 Agent 编排的并发、成本与安全边界
5.1 “AI Agent 怎么扛并发”是个工程问题，不是模型问题
被问到最多的问题就是：多 Agent 编排到底怎么扛并发。首先得明确一点：子代理工作流是一个多副本调度问题，不是“一个模型同时跑多个逻辑”。Harness 负责按规则调度节点，每个节点最后都会落到模型调用。整体并发上限取决于三件事：模型服务吞吐、外部接口限流、单机调度资源。
我通常按一个近似公式估算：
每分钟最大处理流程数 = 模型每分钟可用调用次数 ÷ 单流程平均子代理调用次数
假设你的模型服务能承受每分钟 600 次调用，一个流程平均用到 5 个子代理，那么每分钟大约能处理 120 条流程。这时你把并发实例开到 200 也没用，模型服务端先到上限了。反过来，如果外部接口每分钟只允许 60 次调用，而你的流程会大量调用这个接口，那它才是真正的瓶颈。
还有一个实用技巧：把纯耗时或纯 IO 的节点设计成可并行。例如简历解析时每份简历独立解析，如果 Harness 能把子代理节点标记为可并行，吞吐就有明显提升。多个子代理并行时也要注意速率限制，不要让 10 个节点同时打同一个内部接口，在连接处加一个信号量或者并发上限，运行会更稳。
5.2 Agent 安全的真实风险点
“Agent 安全”这个话题，我一般拆成两个维度看：工具权限和内容权限。
工具权限方面，子代理能调用的工具必须走白名单机制。一个简历解析子代理，给它文件读取权限可以，给它网络请求权限就要仔细评估。一旦提示词被恶意注入，它就有机会把内部文件内容通过请求带出去。内容权限方面，子代理的输入输出都要走脱敏路径。简历里包含身份证号、薪水面谈等敏感字段，传给模型前先做脱敏替换；输出到通知节点时再恢复必要字段，不要让模型直接生成包含敏感字段全文的中间结果。
我强烈建议为高风险操作保留“人工确认”节点。比如通知节点发送前先跑一个模板预览，人工看完再确认发送。模型能力再强，也不应该在“对外发信”这一步完全自主。编排系统的价值之一，就是把“决策”和“执行”分开：Agent 可以负责写内容，人工或规则节点负责执行动作。这样即使模型判断错了，最终影响也是收敛的。
6. 踩过坑之后，我对多层编排的真实看法
6.1 四个翻车现场，希望你直接避开
第一，过度编排。我第一版项目里，几乎把所有任务都拆成 8 个子代理，结果每一步都串行等待，总时延比单 Agent 调用还大，Token 费用却翻了几倍。后来把关联度高的节点合并在一起，只保留 4 到 5 个核心节点和必要的分支，效率立刻上来了。
第二，提示词风格互相打架。有些子代理被要求“正式专业”，另一些被要求“口语化”，结果输出里术语不一致，下游解析一塌糊涂。现在所有子代理统一一套字段命名和输出风格，语气差异全部放到模板节点去做，只做表面的渲染调整。
第三，重试过度。一个节点失败后让它重试 5 次，每次重试都重新消耗 token，高峰期直接把接口配额打满。现在我只允许语义重试最多两次，仍然失败就进入降级分支，交给人工处理，不再跟模型死磕。
第四，状态持久化缺失。有一次服务器重启，工作流里跑到一半的状态全丢，前面几百次节点调用白费。从那以后，关键 checkpoint 节点永远开着，状态目录单独配置，并且定期做快照。这个教训让我意识到，编排系统最值钱的是可恢复能力，不是执行速度。
6.2 有些任务真的不适合“Agent 编排 Agent”
如果你手里的任务是线性、固定、大量重复的，比如每天同一份报表格式转 CSV、把 Excel 按固定规则拆表，这类更适合传统脚本。把模型放进流程里，看中的不是它聪明，而是因为规则会变、输入不规范、需要可解释的决策过程。编排成本是真实存在的，它多了一套流程定义、一套提示词资产、一份维护清单。只有下面几个条件同时满足时，多层编排才算划算：
- 任务流程会重复执行；
- 每轮执行都可能遇到不规范的输入；
- 只有模型能理解判断逻辑；
- 失败成本高，日志与回退机制值得投资。
我自己常用来做的是简历筛选、资料汇总、格式转换、通知派发、业务类数据质检。凡是重复不到十次、一次失败也无所谓的事，我都不会搬进 Harness。一次性的杂活，直接开一个会话问模型就够了。
最后分享一个我的操作习惯：每套工作流上线之前，先定义一张“输入输出契约表”，把每个子代理的输入字段、输出字段、失败类型、回退目标列清楚。很多人调工作流时大部分时间都耗在两个地方：上下文爆炸和输出格式不稳定。契约表能同时缓解这两个问题。真正体会到 Agent 编排 Agent 的价值，不是第一次把简单流程跑通的那个瞬间，而是你把它放到内网服务器上，让它每天帮你处理几十次重复筛选、整理、派发之后，你发现自己终于不用守在任务前面看它循环了。到那一刻，这套 Harness 做对的事，说到底只有一件：把大模型从“聊天对象”变成了“可调度的人力资源”。
