企业官网建设流程全解析

1. 为什么我们急需一个"Agent 操作系统"

这两年我一直在折腾各种多 Agent 系统，从最开始的 LangChain 串行链，到后面用 Actor 模型自己搓调度器，再到给某个跨平台系统做 Agent 化改造，一个感觉越来越强烈：我们现在的 Agent 工程还停留在"裸机时代"。

什么叫裸机时代？就是早期计算机没有操作系统的时候，一个程序独占整台机器，跑完一个任务才能跑下一个，资源调度靠人肉插拔纸带。现在的多 Agent 系统就是这副德行——每个 Agent 维护自己的上下文、自己的工具调用、自己的重试逻辑，互相之间靠脆弱的 JSON 消息沟通，一旦某个 Agent 卡死或者上下文爆炸，整个管线全部陪葬。更别提什么公平调度、优先级抢占、资源隔离、故障恢复，这些操作系统教科书里的老古董概念，在当下 Agent 框架里几乎全是空白。

所以我个人判断，下一阶段真正值得压注的方向，不是继续卷某个模型的能力，而是给 Agent 做一个真正的"操作系统层"——也就是标题里说的 Harness 平台。Harness 这个词在英文里是"马具、挽具"的意思，引申过来就是"驾驭和调度多个智能体的整套基座设施"。它不是某一个 Agent 的单点优化，而是要把进程管理、内存管理、文件系统、调度器、安全内核这些操作系统的核心子系统的设计哲学，全部迁移到 Agent 世界里来。

这篇文章我不会只停留在概念层面，而是会用我踩过的坑、调过的参、写过的核心代码，拆清楚 Agent 操作系统到底应该长什么样，Harness 平台该怎么一步步搭起来。适合正在做多 Agent 系统却总觉得"差一口气"的开发者，也适合在技术选型阶段纠结"要不要造轮子"的团队。

2. 从单体 Agent 到多智能体协同的演进逻辑

2.1 单体 Agent 的天花板

先说为什么单体 Agent 撑不起未来的应用。单个 Agent 的能力边界主要由三个因素决定：模型本身的智力上限、上下文窗口的容量、以及工具调用的外部副作用控制。前两个是硬约束，第三个是软工程问题。

上下文窗口是眼下最头疼的坑。我实测过一个基于长上下文的单体 Agent 做数据分析任务，任务链路是"读取数据 → 清洗 → 特征工程 → 建模 → 产出报告"。这个链路如果全部塞进同一个上下文，token 消耗呈指数级上升——不仅仅是输入变长导致费用变高，更麻烦的是模型在超长上下文里的"迷失中间"现象，它会逐渐忘记最开始的数据约束，到后期生成的代码经常违反最初的字段规范。

所以我见过不少团队试图用"单 Agent + 超长上下文"来硬扛复杂任务，最后几乎都会转向多 Agent 拆分。这个转向一旦开启，就必然会碰到一个核心问题：谁来管理这些 Agent 的节奏、状态和资源？而这就是 Harness 平台要回答的。

2.2 多 Agent 协同的三代演进

我粗略把多 Agent 的实现路径划分成三代，这样看演进逻辑会比较清晰。

第一代是"链式编排"。就是一个 Agent 的输出的直接作为下一个 Agent 的输入，整条链路是一个有向无环图。优点是简单直观，小 demo 跑得飞快；缺点是灵活性极差，任何一个节点出错就要整条链路回滚重试，而且中间状态很难被别的分支利用。这个阶段我问过很多做 Rag 应用的同学，他们所谓的"多 Agent"，其实就是 RAG 链路里的路由器和检索器分开写，严格说还算不上多 Agent 协同。

第二代是"图式编排"。引入条件分支、循环、并行执行，用显式的图结构描述 Agent 之间的依赖。这个阶段已经能处理不少真实场景了，但还是静态的——图结构是预先画好的，Agent 本体没有自主决策能力，自由度有限。我在帮某公司改造客户支持系统的时候，最初用的就是图式编排，效果比链式好很多，但一旦遇到"用户的问题突然跨领域"这种意外情况，预定义的图就兜不住了，需要人工介入。

第三代就是我现在重点折腾的方向，可以叫"运行时自治编排"。每个 Agent 是一个独立的"进程"，系统层面有一个调度内核来决定谁先跑、谁能抢占、谁要降级。Agent 之间通过消息总线通信，但它们的生命周期完全由 Harness 平台来管理。这才是"操作系统"这个概念真正落地的形态——应用组件（Agent）本身退居次要位置，平台才是核心。

2.3 为什么是"现在"才需要 Agent OS

有人会问：多 Agent 概念都火了好几年了，为什么偏偏现在才觉得需要操作系统？我的观察是，三个条件刚刚凑齐。

第一个条件是模型成本下降到可以支撑"多实例并发"。以前跑一个 Agent 的推理成本就很高，部署十个 Agent 同时跑纯属烧钱。现在小模型配合蒸馏和量化，单次推理的成本降到了可以随便开实例的水平。成本一旦不再是瓶颈，资源调度的意义就浮现了。

第二个条件是 Agent 的形态从"对话机器人"转向"任务执行体"。对话机器人是短生命周期、有用户在场、一次一轮的；任务执行体是长生命周期、后台静默运行、自主决策的。后者天然需要进程管理、持久化、故障恢复。我最近在做的某个图像处理 Demo 就属于后者：用户上传一批图片，系统自动拆分成多个 Agent 并行处理，这个过程里 Agent 需要运行几分钟甚至几小时，中间还要断点续跑，没有操作系统层的支撑根本做不稳。

第三个条件是 Agent 生态开始出现"技能市场"的雏形。当外部生态里有大量可复用的工具、技能、模型适配器时，系统就必须有一个标准化的"安装、挂载、卸载"机制——这不就是操作系统里的文件系统和设备驱动吗？前两个条件决定了需求的迫切性，第三个条件决定了这个方向的生态基础已经具备。所以我说，现在正是 Harness 平台的最佳入场窗口。

3. 拆解：Agent 操作系统的五个核心子系统

3.1 进程管理：Agent 生命周期与状态机

操作系统的进程管理解决的是"程序如何被打包、启动、暂停、恢复、销毁"。放到 Agent 世界里，对应的就是 Agent 的生命周期管理。我在实际项目中把 Agent 进程严格定义成六个状态：Created（已创建）、Ready（就绪）、Running（运行中）、Blocked（阻塞中）、Recovering（恢复中）、Terminated（已终止）。

这个状态机看起来简单，真正跑起来全是魔鬼细节。最典型的是 Blocked 状态——Agent 在等待某个外部结果（比如等待另一个 Agent 的回执、等待用户审批、等待 API 限流解除）。在单体框架里，这种"阻塞"往往就是把整个线程挂起，等结果来了再继续。但在多 Agent 系统里，一个 Agent 阻塞不应该是占着一个线程死等，而应该是把自己挂起、让出计算资源、把事件注册到消息总线上，等其他组件把结果推回来再唤醒。

我在设计 Agent 实例的原子信息结构时，用的是 dataclass 加枚举，核心字段包括agent_id、status、current_task、context_pointer、tool_registry和retry_count。这里面比较关键的设计决策是context_pointer不直接存完整的上下文内容，而是存一个指向共享内存区域的指针。因为 Agent 的上下文通常很大（几万 token），如果每个状态转移都复制全量上下文，系统的内存开销会瞬间爆炸。后来在踩了不少坑之后，实现状态恢复时就是靠这个指针从持久化层把上下文捞回来。

另外还有一个很反直觉的经验：Agent 不应该无限重试。我之前踩过一个大坑，某个 Agent 在调用第三方 API 时遇到了限流，我起初设置了重试 10 次，结果它每次失败后指数退避，整个任务延迟了将近 40 分钟，而且因为限流是全局的，它把 API 配额全吃完了，导致其他 Agent 全部被饿死。后来我把重试策略细化成：

• 网络类错误：最多重试 3 次，指数退避上限 60 秒
• 业务类错误（参数错误、权限不足）：不重试，直接标记 Terminated
• 模型输出格式错误：重试 2 次，并且第二次重试时在前缀加"请严格按照 JSON Schema 输出"的提示

这个"不无限重试"原则，本质上就是在做操作系统里常见的"进程看门狗"——防止一个坏进程把整个系统拖垮。

3.2 内存管理：上下文分层与共享记忆模块

现代操作系统的内存管理讲究虚拟内存、页表、缓存分级。Agent 操作系统的内存管理，核心要解决的是上下文窗口有限但任务需要长期记忆的矛盾。我的方案是把上下文分成三层：瞬时层、工作层、持久层。

瞬时层就是当前一次工具调用的输入输出，用完即弃，不占上下文；工作层是当前任务阶段需要保持的短期记忆，比如正在处理的这份文档的关键字段；持久层是跨任务、跨会话需要长期保存的知识，比如用户的偏好、项目的规范、历史决策的原因。工作层的状态会通过"压缩节点"定期向下沉淀——把对话历史做摘要，把关键结论抽成结构化记录，然后释放上下文空间。这就像一个操作系统把不常用的内存页换到磁盘上，需要时再换回来。

共享记忆模块更关键。多个 Agent 协同处理同一个任务时，如果各自持有私有的上下文副本，必然会出现信息不一致。我的做法是引入一个独立的共享记忆总线，用键值结构存储全局事实。比如一个数据清洗 Agent 发现某个字段存在缺失，它会把"字段user_age缺失率 12% 已用中位数填充"写入共享记忆；下游的建模 Agent 在开始时先读这条记录，就不会重复做填充决策，更不会用另一种填充方式造成数据口径冲突。

但共享记忆不是没有代价。我曾经在一个项目里，两个并行 Agent 同时尝试更新同一个键，造成了"读写竞争"。后面的 Agent 把前面的结果直接覆盖了，而它的决策依据其实是过期的数据。这个问题我用了两种机制来解决。第一是"键级锁"，写入共享记忆时对键进行短时锁定；第二是"版本号检查"，更新时比对版本，版本落后就拒绝写入或者触发合并。换句话说，这就是数据库里的乐观锁和悲观锁在 Agent 世界里的映射。

3.3 文件系统与工具挂载：把技能做成可插拔的设备驱动

操作系统提供文件系统的抽象，让应用不必关心数据实际存在哪块磁盘上。Agent 操作系统的"文件系统"，我理解就是技能注册表 + 工具装载器。

在早期框架里，工具函数是硬编码进 Agent 的 prompt 里的，换工具就要改代码重新部署。而 Harness 平台要做的是把工具当作"设备驱动"来动态挂载。每个工具发布时带一个统一的 manifest 描述文件，里面写了工具名字、输入输出 JSON Schema、权限级别、超时时间、失败行为。Agent 运行时通过技能注册表发现可用的工具，在任务需要时按需装载。

这个设计解决了一个非常具体的问题：上下文消耗。Agent 不可能把 50 个工具的描述全部塞进 prompt，那会占掉大量上下文空间，而且很多工具跟当前任务毫无关系。动态挂载意味着 Agent 在任务开始阶段，通过调度器的"意图路由"模块判定可能需要的工具类别，然后只把这些工具的描述加载进工作层上下文。实测中这个改动能把工具相关的 token 消耗降低 60% 左右，同时工具的调用准确率还有小幅提升。

文件系统抽象还需要覆盖"数据文件"的层面。Agent 任务执行中会产生中间产物——清理后的数据、模型输出的草稿、图表渲染的临时图。这些中间产物不应该游离在系统之外，而应该像文件系统一样有目录结构、有生命周期、有过期策略。我给中间产物设计了三个桶：scratch（临时，任务结束后 24 小时清理）、shared（跨 Agent 共享，按引用计数清理）、archive（归档，按保留策略清理）。这种设计让系统的可观测性好了很多，排查问题时能明确知道每个 Agent 往哪个桶里写了什么。

3.4 调度器：优先级、抢占与公平性

调度器是整个 Harness 平台里最像操作系统的部分。它要回答的问题是：计算资源有限，多个 Agent 同时请求执行，谁先跑？跑多久？跑挂了怎么办？

我参考了 Linux CFS（完全公平调度器）的思路，给每个 Agent 任务分配一个"虚拟运行时间"的指标。任务越重、等待越久、优先级越高，虚拟运行时间越小，调度器就越倾向让它先执行。具体实现上，我维护了一个红黑树结构的就绪队列（在 Python 里实际上用 heapq 就够了，红黑树可以用 sortedcontainers 库替代），调度时取出虚拟运行时间最小的任务。

优先级我用的是三级：高优先级（用户实时交互任务）、中优先级（后台批处理任务）、低优先级（数据维护类任务）。规则是低优先级任务可以随时被高优先级抢占，中低优先级之间采用时间片轮转。但这个抢占机制一定要配合"可恢复性"设计，否则就是灾难。我被坑过一次：一个低优先级的模型训练任务被高优先级的推理请求抢占，直接 kill 掉进程，结果训练跑到一半的状态全部丢失，最后一次完整 checkpoint 是三个小时前的。后来我给所有可抢占任务强制开启"状态快照"机制——每次开始新阶段之前先落盘一个轻量级 checkpoint，抢占恢复后从最近快照继续跑，而不是从头再来。

调度器还要处理公平性问题。有一种情况很隐蔽：某个任务自己拆分了 100 个子任务，全部塞进调度队列，结果把队列塞爆了，其他任务的子任务排到一小时之后。这是典型的"任务饥饿"。我的经验是必须引入"权重配额"机制，每个父任务在一段时间内能提交的子任务数量有上限，超出的排到低优先级池。这样至少保证没有哪个任务能独占整个集群。

3.5 安全内核：权限边界与可信执行

最后是安全。操作系统不能没有内核态和用户态之分，Agent 操作系统也需要严格的权限边界。实际项目中，我给每个 Agent 分配一个权限令牌，令牌里声明了它能访问的数据域、能调用的工具类别、能读取的共享记忆范围。所有跨 Agent 调用都走统一的内核仲裁，而不是让 Agent 之间直接互相调用对方的方法。

这个设计起初被团队里一个同学吐槽说"太官僚"，但后来事实证明它是系统能稳定跑下去的关键。因为 Agent 本身的决策是不可完全预测的，哪怕 prompt 里写了"不要访问用户隐私数据"，模型在特定上下文里也可能失守。权限边界就是最后一道物理防线——即使模型生成了访问敏感数据的意图，内核仲裁层直接拦截。我曾经在模拟测试里故意用对抗性 prompt 诱导 Agent 越权读取另一个租户的数据，没有权限系统的时候它真的把我的测试脚本读出来了；加上内核仲裁之后，所有越权尝试都被拦截并记录进审计日志。

审计日志也特别重要。多 Agent 系统一旦出了问题排查起来极难，因为没有单一的事实来源。而 Harness 平台里的安全内核本身就天然是一个事实来源：谁、在什么时间、通过哪个 Agent、调用了什么工具、访问了哪份数据、返回了什么、耗时多少——全部落审计日志。反正我是把审计日志当作系统最重要的资产来对待的，它不仅是安全工具，更是调试器。

4. 实操：构建一个可运行的 Harness 平台骨架

4.1 技术选型：为什么是 Python + 事件驱动

不卖关子，技术选型上我走了不少弯路，最后沉淀下来的是：Python 3.11 + asyncio + 事件总线（基于 Redis Streams）+ SQLite/PostgreSQL 做状态持久化。模型层不做预设，通过统一接口适配各家推理 API。

Python 的 asyncio 是天然的事件循环模型，和 Agent 运行时的"等待-唤醒"模式契合度很高。我最早试过用 Celery 做任务队列，但它太偏批处理而轻交互，Agent 之间的复杂消息传递很难表达。也试过直接用 gRPC 做服务间通信，但状态机流转时的灵活动态性很差。最后选择事件驱动：所有 Agent 之间不直接通信，只往事件总线发消息，调度器、共享记忆、审计日志全部订阅相关事件。这种解耦方式是后期系统能稳定扩展的根本原因。

Redis Streams 是我踩过几个坑之后确定的消息层选择。它比普通的 Redis 队列强在有消费者组、可回溯读取、消息确认机制。Agent A 发布一个"任务完成"事件，可能有三个组件对这个事件感兴趣——调度器要更新状态、共享记忆要沉淀结论、审计中心要记录日志。用消费者组就能让这三个消费者各自消费一份消息副本，互不干扰。如果其中一个消费者处理失败了，它还可以从 Stream 里重新读回这条消息而不会影响其他消费者。

4.2 核心数据结构：Agent 进程与控制块

直接放一段核心代码，这是我项目里agent_core.py的精简版本，保留了最关键的设计：

# agent_core.py - Agent 进程控制块的核心数据结构 from enum import Enum, auto from dataclasses import dataclass, field import time import uuid class AgentStatus(Enum): CREATED = auto() READY = auto() RUNNING = auto() BLOCKED = auto() RECOVERING = auto() TERMINATED = auto() @dataclass class AgentContextPointer: """指向共享记忆/持久层中的上下文位置""" region: str # shared | scratch | archive key: str # 在对应区域中的键名 offset: int = 0 # 若上下文太大时的分段偏移 checksum: str = "" # 用于校验恢复的一致性 @dataclass class AgentProcess: agent_id: str = field(default_factory=lambda: f"agt_{uuid.uuid4().hex[:12]}") name: str = "" status: AgentStatus = AgentStatus.CREATED priority: int = 0 # 0: 高优先级 1: 中优先级 2: 低优先级 current_task: str = "" # 当前任务描述 context: AgentContextPointer | None = None tool_registry: list[str] = field(default_factory=list) # 已挂载工具名 retry_count: int = 0 max_retries: int = 3 checkpoint: dict = field(default_factory=dict) # 轻量级状态快照 created_at: float = field(default_factory=time.time) last_active_at: float = field(default_factory=time.time) def snapshot(self): """生成轻量级快照，用于抢占恢复""" return { "agent_id": self.agent_id, "status": self.status.name, "current_task": self.current_task, "context": self.context.__dict__ if self.context else None, "tool_registry": self.tool_registry, "checkpoint": self.checkpoint, }

AgentProcess就是 Agent 操作系统中每个"进程"的控制块。快照机制就是靠snapshot()方法实现的，调度器要抢占某个 Agent 时，会先调用这个方法把状态落库，再真正唤醒新任务。恢复时用snapshot里的信息重建 AgentProcess，然后把它的状态置为RECOVERING，等它把上下文指针指的内容捞回来之后转成READY。

4.3 调度器实现：从简到最优的演进

调度器我改了三版。第一版是最简单的公平队列，谁先来谁先跑。结果线上跑起来之后问题不断：长任务把短任务全堵死了，高优先级的用户请求要等低优先级的数据清理任务跑完才能响应。第二版加了优先级队列，高优先级永远先跑，但低优先级任务会被饿死，一整天都轮不上。第三版才是我现在觉得勉强能用的：多级反馈队列。

多级反馈队列的思路是：新任务进入最高优先级队列，分配一个 30 秒的时间片；如果 30 秒内没跑完，就降级到下一级队列，时间片拉长到 60 秒；再跑不完再降级，时间片继续拉长。这个机制的好处是短任务几乎可以立即完成，长任务也不会被饿死，只是越长的任务能获得的时间片越大但优先级越低。这就避免了一个任务因为耗时太长而永久霸占高优先级的问题。

我用 Python 的heapq实现了三级反馈队列，核心逻辑如下：

# scheduler.py - 多级反馈调度器核心逻辑 import heapq import time from collections import defaultdict class FeedbackScheduler: def __init__(self, time_slices=[30, 60, 120]): self.time_slices = time_slices # 每一级队列的时间片（秒） self.queues = defaultdict(list) # level -> heap of (virtual_runtime, agent) self.level_map = {} # agent_id -> current level def add_task(self, agent, level=0): heapq.heappush(self.queues[level], (time.time(), level, agent)) self.level_map[agent.agent_id] = level def pick_next(self): for level in range(len(self.time_slices)): if self.queues[level]: _, _, agent = heapq.heappop(self.queues[level]) return agent, self.time_slices[level] return None, 0 def task_finished(self, agent): level = self.level_map.pop(agent.agent_id, 0) # 任务完成，从所有队列中清理 self.queues[level] = [item for item in self.queues[level] if item[2].agent_id != agent.agent_id] heapq.heapify(self.queues[level]) def demote(self, agent): current_level = self.level_map.get(agent.agent_id, 0) new_level = min(current_level + 1, len(self.time_slices) - 1) self.level_map[agent.agent_id] = new_level heapq.heappush(self.queues[new_level], (time.time(), new_level, agent))

这个实现不算复杂，但在我的实际项目里已经够用了。要注意的是pick_next一定要从最高级队列往下找，否则低优先级的任务会因为高优先级队列里堆了一堆新任务而永远得不到执行。另外被抢占的 Agent 重新入队时，它的虚拟运行时间要加上一个惩罚因子，否则它刚被抢走又重新插到队列前面，抢占了失去意义。

4.4 状态机与恢复机制：崩溃后怎么续传

Agent 崩溃后的恢复是我花时间最多的地方。任务执行到一半，模型 API 超时了、网络闪断了、甚至整个 Python 进程被 OOM killer 干掉了，Agent 状态该怎么恢复？

我的方案是"两阶段恢复"。第一阶段是进程级恢复：AgentProcess.snapshot在每次工具调用开始之前已经写入持久层，崩溃重启后调度器扫描所有状态不是TERMINATED的 Agent，发现有RECOVERING状态的，就把快照捞出来，把 Agent 恢复到READY状态。第二阶段是任务级恢复：Agent 恢复READY后，它需要知道"我执行到哪一步了"。这个信息从哪来？从共享记忆总线的任务执行记录里来。

我给每个 Agent 分配了一个"任务执行日志"，每一步完成之后追加一条记录。恢复时读取日志的最后一条记录，从那条记录开始重新执行。这个设计的核心哲学是：Agent 的执行模型应该是幂等的——每一步操作本身幂等（计算结果只依赖输入，不依赖中间状态），或者至少操作可以安全重复（重试写入同一个共享记忆键时采用版本检查，重复写不会造成数据错乱）。

下面是我在某个模拟项目里用来测试恢复机制的简化版本，核心是手动模拟一次 Agent 在第三步崩溃后的恢复流程：

# recovery_demo.py - 演示两阶段恢复 import asyncio async def run_with_recovery(agent, task_steps): """带恢复机制的任务执行流程""" # 第一阶段：进程恢复 if agent.status == AgentStatus.RECOVERING: # 从持久层加载快照 snapshot = load_snapshot(agent.agent_id) agent.checkpoint = snapshot["checkpoint"] agent.status = AgentStatus.READY log_manager.info("agent %s recovered from snapshot", agent.agent_id) # 第二阶段：任务级恢复 steps_done = get_steps_done(agent.agent_id) # 从共享记忆读任务执行日志 remaining = task_steps[len(steps_done):] for step in remaining: agent.status = AgentStatus.RUNNING try: result = await execute_step(agent, step) # 执行成功，记录日志 append_step_log(agent.agent_id, step, result) agent.snapshot() # 每个步骤完成后更新快照 except ExternalAPIError: if agent.retry_count < agent.max_retries: agent.retry_count += 1 agent.status = AgentStatus.BLOCKED await asyncio.sleep(min(30, 2 ** agent.retry_count)) # 指数退避 agent.status = AgentStatus.READY # 不移动 steps_done，下次循环会重新执行当前步骤 else: agent.status = AgentStatus.TERMINATED raise agent.status = AgentStatus.TERMINATED log_manager.info("agent %s finished all steps", agent.agent_id)

这个恢复逻辑的核心价值在于：崩溃不可怕，可怕的是崩溃后不知道自己干了什么。有了步骤日志和幂等设计，任何一步崩溃，重启后都能从最近完成的那一步接着跑。在我真实的线上压测中，把崩溃率人为调高到 30%，这个机制能让任务最终完成率超过 97%。

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

5.1 五个高频问题速查表

下面这张表是我在多个项目里反复遇到的典型问题整理出来的，不敢说放之四海而皆准，但覆盖面还是挺广的：

5.2 一个真实的排查案例：上下文爆炸引发连环崩溃

说一个我最想分享的排查实录。某次在压测一个文档处理型多 Agent 系统时，突然出现大面积超时，不是模型慢，是整个系统像被人按住了暂停键。

我第一反应是看事件总线的消费速度，结果发现 Redis Stream 里堆积了几万条未消费消息。再看消费者组，发现所有消费者都阻塞在"从共享记忆读取上下文"这个环节——因为单个 Agent 的上下文指针指向的共享记忆区域，被某个之前跑崩的 Agent 塞进了一个超过 2 万 token 的超长摘要，导致后续所有读取这个区域的 Agent 都要处理这个庞然大物，Token 消耗急剧上升不说，模型推理速度也大幅下降。

根因是共享记忆的"压缩节点"没有设上限。某个 Agent 在任务执行中将整个任务过程全部塞进摘要，没有做信息抽稀，结果一个"摘要"写了一万多字。后续 Agent 读到这个摘要后，本质上是把上下文窗口全占了，导致各种后续操作出现低压异常。

修复方案有两个层面。短期：压缩节点加了一个摘要长度上限，超过 2000 字就强制做二次压缩，只保留"决策原因 + 关键结论 + 数据指标"。长期：共享记忆区域增加一个"权重评估"机制——写摘要前先用一个轻量级模型判断这段内容的"信息密度"，低于阈值就拒绝写入并让写方重新提炼。这个机制上线之后再没出现过由于共享记忆膨胀导致的系统性故障。

5.3 独家避坑：关于调试手段的三条建议

第一个建议：尽早把审计日志做成结构化输出。一开始我也嫌麻烦，打印 JSON 日志时随手写几行 key value。后面排查问题越来越难，因为系统的事件链路太复杂了，散的日志根本串不起来。后来我把日志输出统一成trace_id + agent_id + event_type + payload的格式，每个任务分配一个全局 trace_id，所有 Agent 事件都带这个 trace_id。这样排查时只需要按 trace_id 过滤，就能看全整个任务的生命周期。

第二个建议：给每个 Agent 单独开一个"沙箱日志环"。所谓日志环，就是一个容量固定的环形缓冲区，只保留最近 100 条这个 Agent 的执行记录。为什么需要这个？因为共享日志太杂，按 agent_id 过滤在任务多的时候也很吃力。日志环直接把单 Agent 的局部情况抽出来，方便在它出错时快速定位问题。代价就是每个 Agent 要多占一点内存，但换来的是调试效率的几何级提升。

第三个建议：不要在生产环境里用 print 或 logger 的默认级别调试 Agent 输出。Agent 的输出内容非常长，动辄几千字，默认级别会把日志文件迅速撑爆。我后来设计了"输出采样"机制——每个 Agent 的中间输出只记录前 500 字和后 200 字，中间部分用省略号代替；只有在显式开启"详细跟踪模式"时才记录全文。这个做法让日志存储成本降低了 80%，排查问题时抓手反而更集中了。

最后再分享一点我的个人体会

做了这么多轮实验和项目回顾，我最大的感受是：Agent 操作系统的核心难点其实不在编码实现，而在思维范式的转换。

写普通后端服务时，我们的思路是"一个请求对应一个处理函数"，一次调用是原子的、同步的、有确定的输入输出。而设计 Harness 平台时，必须彻底抛弃这种线性思维，把系统想象成一个不停运转的城市：无数 Agent 像是城市里的居民，调度器是交通系统，共享记忆是城市公告栏，审计日志是监控摄像头。你不去精确控制某一个居民今天中午吃什么，而是设计好规则让这座城市整体正常运转。

具体到工程实践上，我建议所有准备入局这个方向的人，都不要急着写调度器或者状态机。第一步应该是列出你系统里会出现的所有"Agent 状态流转"——创建、就绪、运行、阻塞、恢复、终止——然后为每个流转画清楚触发条件、副作用和超时行为。这一步做完，后面所有代码都有了骨架。

另外一个很值得花时间的点是幂等性设计。Agent 系统的故障恢复完全依赖操作可重放，而现实中我见过太多"看似幂等实则不幂等"的工具——比如某个 API 调用，每次调用都会在数据库里增加一条记录，重试一次就多一条脏数据。每个工具接入 Harness 平台之前，必须回答一个问题：如果这个调用被重复执行三次，系统的最终状态是否仍然一致？如果答案不是确定的，就得在工具外做一个去重层，这个工作不能省。

Agent 操作系统这个概念现在看还有点超前，但我觉得最多两三年，市场上就会出现成形的开源实现。现在动手做的人，积累的经验会变成下一轮技术红利。这篇文章里的代码和思路都是我实际跑过的，你可以直接拿去改，但别指望一次就能跑通，调度参数、时间片、摘要上限这些都得按你自己的场景调。工程嘛，从来就是调出来的。