Harness 生产落地踩坑实录：从单机到多 Agent 协作

引子前三篇你学会了跑 Harness、写插件、用 Cordis 内核。在一个进程里、一个 Agent 的情况下这套东西已经能稳定干活了。但真正的生产场景从来不是一个 Agent 单干。比如我们组最近在做的代码评审自动化一个 Agent 看 diff、一个 Agent 跑测试、一个 Agent 写文档。三个 Agent 要共享上下文、要协调顺序、要避免冲突。我们最初想着既然 Cordis 这么强开三个 Profile 跑一个进程不就行了——结果上线第一天就被打脸了。这一篇记录我们组从单机跑到多 Agent 协作的四个真实坑以及最后怎么解决的。如果你打算在生产环境用 Harness这篇能帮你少走至少两周弯路。一、原理单机到多 Agent 的三道坎1.1 为什么一个进程跑多 Agent行不通很多人包括我们最初的设计是这样的单进程多 Profile 方案 ├── Profile: code-reviewer评代码 ├── Profile: test-runner跑测试 └── Profile: doc-writer写文档 共享一个 Cordis Context理论上很美好三个 Agent 共享文件系统、共享 git、共享模型客户端开销低、通信简单。实际上线后第二天就出问题了现象原因Agent A 卸载时把 B 的临时文件也清了Proxy 副作用清理是按插件 scope 隔离的但文件系统是共享的Agent A 改了 configB 拿到的还是旧值配置层是全局的没有 per-agent 隔离一个 Agent 死循环整个进程崩了没有进程级隔离单点故障拖垮全局调试时不知道是哪个 Agent 在做事日志共用一个 stdout分不开关键结论单进程多 Profile 适合一个 Agent 多身份比如同一个 Agent 切换工具集不适合多个独立 Agent 协作。后者必须上进程隔离。1.2 真正的多 Agent 协作需要什么生产环境的多 Agent 协作至少要解决三件事**•**状态隔离每个 Agent 有自己的 Context、Proxy、配置——A 的副作用不影响 B。**•**通信标准化Agent 之间不共享内存通过消息总线通信——和微服务一个逻辑。**•**故障隔离A 崩了B 和 C 不受影响——这是单进程方案做不到的。Harness 提供了dsh swarm模式来支持这个但默认配置不够用下面逐条讲怎么调。1.3 协作模式的选择多 Agent 协作不是只有一种模式。Harness 支持三种主流模式各有适用场景模式适用不适用主从编排任务可分解、有明确编排逻辑Agent 之间需要平等协商事件驱动流水线场景A→B→C需要全局决策黑板模式探索性任务、协同设计强一致性的场景我们的真实教训最初用了主从编排但代码评审场景里评审 Agent和测试 Agent经常需要互相质疑评审说这个函数太长测试说但测试覆盖率上来了主从模式处理不了这种平等协商最后切到了黑板模式。二、实现搭建一个三 Agent 协作系统2.1 进程拓扑下面是我们线上跑的真实架构三个 Agent 各自是独立的 dsh 进程由dsh-swarm编排通过 Redis Pub/Sub 通信共享状态放在 SQLite。2.2 最小可运行的 swarm 配置项目根目录放一个swarm.yml# swarm.yml name: code-automation version: 1 # 共享状态存储 state: type: sqlite path: ./state/shared.db # 消息总线 bus: type: redis url: redis://localhost:6379/0 # Agent 定义 agents: - name: reviewer profile: ./profiles/reviewer plugins: - deepseek-model - git - fs subscriptions: - git:commit - test:done publishes: - review:done - review:blocked - name: tester profile: ./profiles/tester plugins: - deepseek-model - git - shell subscriptions: - review:done publishes: - test:done - test:failed - name: doc-writer profile: ./profiles/doc-writer plugins: - deepseek-model - fs subscriptions: - test:done publishes: - doc:done启动dsh swarm start --config swarm.ymldsh-swarm会拉起三个子进程每个装载自己的 Profile 和 Plugin互相通过 Redis 通信。2.3 Agent 之间怎么通信通信完全靠事件不直接调用。比如 reviewer Agent 评审完发个事件// reviewer 插件内 export const name reviewer export const inject [bus, model, git] export async function apply(ctx: Context) { ctx.on(git:commit, async (session) { const diff await ctx.git.diff() const review await ctx.model.chat({ system: You are a code reviewer., user: Review: ${diff}, }) // 写共享状态 await ctx.state.set(last-review, { commit: session.commitHash, result: review, timestamp: Date.now(), }) // 发事件通知其他 Agent await ctx.bus.emit(review:done, { commit: session.commitHash, blocked: review.includes(BLOCKED), }) }) }tester Agent 收到事件后开跑// tester 插件内 export const name tester export const inject [bus, state, shell] export async function apply(ctx: Context) { ctx.on(review:done, async (event) { if (event.blocked) { // 评审说有问题不跑测试 await ctx.bus.emit(test:skipped, { reason: review blocked }) return } const result await ctx.shell.exec(npm test) await ctx.state.set(last-test, { result }) await ctx.bus.emit(test:done, { passed: result.exitCode 0, coverage: parseCoverage(result.stdout), }) }) }注意三个关键点**1.**不直接调用reviewer 不 import tester只发事件。这让两个 Agent 可以独立部署、独立迭代。2.****共享状态用ctx.state不是直接写文件或 Redis而是走 Cordis 的 state 抽象——底层实现可以是 SQLite/Redis/内存插件代码不变。**3.**事件名约定用domain:action格式如review:done避免命名冲突。2.4 调试技巧怎么看 Agent 在做什么多 Agent 系统最大的痛点是调试——三个进程各跑各的出了问题不知道谁先动的手。Harness 提供了一个dsh swarm trace命令能按时间线展示所有事件流dsh swarm trace --last 1h # 输出示例 [15:01:23] git:commit → reviewer [15:01:24] reviewer.start (running 4.2s) [15:01:28] review:done → tester [15:01:29] tester.start (running 18.7s) [15:01:47] test:done → doc-writer [15:01:48] doc-writer.start (running 6.1s) [15:01:54] doc:done这比看三个独立日志直观得多。出问题时一眼能看出卡在哪。三、落地生产环境四个真实踩坑实录3.1 坑一Agent 之间消息风暴现象reviewer 发review:donetester 收到后跑测试发test:failed。reviewer 订阅了test:failed触发新一轮评审又发review:done……形成死循环。10 分钟内 Redis 队列堆了 4 万条消息。原因事件订阅没有去重没有终止条件。Agent A 的事件触发 BB 的事件又触发 A形成正反馈循环。解法每个事件加trace_id和attempt字段订阅方判断是否要处理ctx.on(test:failed, async (event) { if (event.attempt 3) { await ctx.bus.emit(review:giveup, { reason: too many retries }) return } // 继续 retry })发事件时递增 attemptawait ctx.bus.emit(review:done, { commit: session.commitHash, attempt: (event.attempt || 0) 1, trace_id: event.trace_id, // 同一条链路保持一致 })3.2 坑二共享状态写冲突现象tester 和 doc-writer 同时往state/shared.db写数据SQLite 报database is locked。原因SQLite 不支持并发写。多 Agent 同时写共享状态必然冲突。解法换成 Redis 做共享状态支持并发写SQLite 只做持久化归档state: type: redis url: redis://localhost:6379/1 archive: type: sqlite path: ./state/archive.db interval: 5m # 每5分钟归档一次或者用 namespace 隔离每个 Agent 只写自己的 namespace// 每个插件用独立 namespace不互相干扰 const ns ctx.state.namespace(agent:${ctx.meta.id}) await ns.set(last-test, result)3.3 坑三单个 Agent 卡死拖垮全局现象doc-writer 调模型超时30 秒整个 swarm 卡住。后续的 commit 都没人响应。原因默认配置下Agent 处理事件是串行的——一个事件没处理完下一个排队等。如果 Agent 卡死所有订阅同一事件的其他 Agent 也会饿死。解法给每个 Agent 设并发数和超时agents: - name: doc-writer profile: ./profiles/doc-writer concurrency: 3 # 同时处理 3 个事件 timeout: 60s # 单事件超时 retry: max_attempts: 2 backoff: exponential同时给 swarm 加健康检查health: check_interval: 30s on_unhealthy: restart # Agent 卡死就重启 max_restarts: 5 # 一小时内重启超过5次告警3.4 坑四日志和监控现象三个 Agent 各自写日志到./logs/agent-{name}.log出问题时要切三个文件查且时间戳对不齐。原因默认配置每个 Agent 独立 stdout没有统一聚合。解法用结构化日志 统一聚合。在swarm.yml加logging: format: json outputs: - type: file path: ./logs/swarm.log - type: loki url: http://loki:3100 fields: trace_id: true # 自动注入 trace_id agent_name: true event_name: true这样所有日志都进同一个文件每行带agent_name和trace_id方便 grep 和聚合# 看某个 trace 的完整链路 cat logs/swarm.log | jq select(.trace_id \abc-123\) # 看某个 Agent 的所有日志 cat logs/swarm.log | jq select(.agent_name \reviewer\)四、成本与适用性什么时候用什么时候别用写到这里该说真话了——Harness 的多 Agent 协作不是银弹跟 Agent 系列 03 篇讲的一样要权衡。4.1 适合 Harness 多 Agent 的场景场景为什么适合代码评审 测试 文档链天然流水线事件驱动很自然多模型对比A 用 GPTB 用 ClaudeHarness 的模型即插件让切换零成本长期运行的后台 Agent监听 issue、PRCordis 的副作用可回滚在长期任务里特别值钱多租户 Agent 服务进程隔离天然支持4.2 不适合的场景场景为什么不适合单次简单问答上 swarm 是杀鸡用牛刀单 Agent 够了强一致性的交易系统事件驱动是最终一致不适合需要 ACID 的场景高频低延迟100ms跨进程通信 Redis 中转延迟天然在 100ms团队没人懂 TypeScript/Cordis学习曲线陡团队不熟容易踩坑4.3 一个判断公式借鉴 Agent 系列 03 的思路给个判断准则任务复杂度高 多专业协作 可接受最终一致性 → 上 Harness 多 Agent****任务简单 单专业 需要强一致 → 用单 Agent 或传统架构收尾Harness 系列完结四篇写到这里Harness 系列就告一段落了。回顾一下篇主题层次01AGENT MODEL HARNESS 全景原理025 分钟跑起来 dsh实现03Cordis 内核 插件开发实现落地04多 Agent 协作生产落地落地如果你跟着四篇走下来应该已经能跑起来 Harness、写自己的插件、理解 Cordis 内核、在生产环境做多 Agent 协作。Harness 这个项目开源才一周截至本篇发布生态还很早期。但它的设计哲学——“一切皆插件 副作用可逆 进程隔离”——这些理念会慢慢渗透到整个 Agent 领域。提前理解这套东西无论你最后用不用 Harness都不亏。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】