企业官网建设流程全解析

1. 为什么现在聊 Harness，时机刚刚好

过去一年我一直在折腾各种 Agent 项目，从最简单的工具调用到多步推理链，踩过的坑能写满一个笔记本。但真正让我意识到"Harness"这个概念分量的，是今年年初做的一个长时任务项目——让 Agent 连续跑几个小时去完成一份行业调研报告。结果呢？跑到第四十分钟，上下文爆了，任务中断，前面所有中间结果全丢。那一刻我才明白，Agent 的能力上限，很多时候不是模型决定的，而是 Harness 决定的。

Harness 这个词直译是"马具、挽具"，放在 Agent 语境里，它指的是包裹在模型外面那一整套"驾驭系统"：任务编排、状态管理、工具调度、错误恢复、上下文压缩、执行沙盒。模型是马，Harness 是缰绳和马鞍。马再快，没有合适的挽具，你也没法让它拉车跑长途。

这个判断不是我拍脑袋想出来的。Anthropic 在长时任务设计上的思路，Google AX 提出的声明式调度，本质上都在回答同一个问题：当任务时长从"一次对话"拉长到"几小时甚至几天"，Agent 的架构该怎么变？而答案，几乎全部落在 Harness 这一层。

这篇文章适合谁看？如果你正在做 Agent 开发，被上下文溢出、任务中断、状态丢失这些问题折磨过，那这篇就是写给你的。如果你还在用最朴素的方式调 API 拼 Agent，看完你会知道下一步该补什么。哪怕你只是对 Agent 架构感兴趣，这里面的设计思路也能帮你理解"为什么有些 Agent 能跑长任务，有些跑十分钟就崩"。

我下面会从设计思路、核心细节、实操落地、问题排查四个维度，把 Harness 这件事讲透。所有内容都基于我自己跑项目的经验，加上对 Anthropic 和 Google 两套公开设计思路的理解，尽量做到能直接抄作业。

2. Harness 到底解决了什么问题：从长时任务说起

2.1 短任务和长任务的本质区别

先说个反直觉的结论：短任务和长任务，不是"时间长短"的区别，而是"状态是否必须持久化"的区别。

一个短任务，比如"帮我查一下今天天气并总结"，Agent 跑三步就结束了。中间状态全在上下文里，跑完就丢，无所谓。但一个长任务，比如"帮我调研十个竞品并生成对比报告"，它可能要跑几十上百步，中间会产生大量中间结果：搜索到的原始资料、初步筛选的结论、每一步的推理过程。这些东西如果全塞在上下文里，几轮就爆了；如果丢掉，任务又没法继续。

这就是长时任务的核心矛盾：上下文窗口是有限的，但长任务需要记住的东西是无限的。Harness 要做的第一件事，就是解决这个矛盾。

Anthropic 在长时任务设计里给出的思路很清晰：把"记忆"从上下文里剥离出来，变成外部可管理的状态。上下文只保留当前步骤需要的信息，历史信息压缩后存到外部，需要时再按需召回。这个思路听起来简单，但落地时有一堆细节要处理——什么时候压缩、压缩成什么格式、怎么召回、召回错了怎么办。

2.2 上下文溢出只是表象，状态管理才是根

我见过太多人把长任务失败归咎于"上下文不够大"。于是拼命换更大窗口的模型，从 8K 换到 128K，再换到 200K。结果呢？窗口是大了，但任务还是崩，只是崩得晚一点。

为什么？因为上下文窗口大，不等于状态管理好。你把所有东西都塞进上下文，模型在长上下文里的注意力会稀释，关键信息被淹没在噪声里，推理质量断崖式下降。这就是所谓的"lost in the middle"现象——模型对上下文中间部分的信息召回率明显低于开头和结尾。

所以真正的解法不是"塞更多"，而是"管更好"。Harness 的状态管理要做三件事：

• 分层存储：把状态分成"当前工作记忆"、"短期历史"、"长期知识"三层，不同层用不同的存储和召回策略。
• 主动压缩：不是等上下文满了才压缩，而是在每个关键节点主动把已完成步骤的细节压缩成摘要。
• 精准召回：需要历史信息时，不是全量加载，而是根据当前任务语义检索最相关的片段。

这三件事，每一件单独做都不难，难的是让它们协同工作，并且在任务执行过程中动态调整。这就是 Harness 工程的核心复杂度所在。

2.3 声明式调度：Google AX 带来的另一个视角

如果说 Anthropic 的思路是"怎么把状态管好"，那 Google AX 的声明式调度回答的是另一个问题："怎么把任务编排好"。

传统 Agent 编排是命令式的：你写一串步骤，Agent 按顺序执行，每一步调用什么工具、传什么参数，都是硬编码的。这种方式在简单任务里没问题，但任务一复杂，分支一多，代码就变成一团乱麻。

声明式调度的思路是：你只描述"要达成什么目标"和"有哪些约束"，具体怎么调度由 Harness 决定。比如你声明"完成竞品调研，要求覆盖至少 8 个竞品，每个竞品至少 3 个维度，总耗时不超过 2 小时"，Harness 会自动规划执行路径、分配资源、处理失败重试。

这个思路的价值在于：它把"任务逻辑"和"执行细节"解耦了。任务逻辑是稳定的，执行细节是易变的。解耦之后，你改任务不用动调度代码，改调度策略不用动任务定义。这在长时任务里尤其重要，因为长时任务的执行路径往往无法预先确定，必须动态调整。

我自己的项目里，早期用的是命令式编排，后来任务一复杂就维护不动了。改成声明式之后，任务定义从几百行代码缩到几十行声明，调度逻辑集中在一处，改起来清爽很多。当然，声明式不是银弹，它对 Harness 的调度能力要求更高，下面会细讲。

3. 核心细节拆解：Harness 的五个关键模块

3.1 状态层：分层存储与压缩策略

状态层是 Harness 的地基。我把它分成三层来设计：

工作记忆最简单，就是当前这一步需要的东西，跑完就丢。短期历史是重点，它记录"任务是怎么走到现在的"，但只存摘要不存细节。长期知识是"任务积累下来的资产"，比如调研到的原始资料、生成的中间产物，这些不常访问但可能随时需要。

压缩策略是状态层的灵魂。我的做法是在每个"里程碑节点"触发压缩，而不是按步数或 token 数触发。什么是里程碑节点？比如"完成一个竞品的调研"、"生成一份中间报告"、"做出一个关键决策"。在这些节点上，把之前一段的执行细节压缩成一段结构化摘要，格式大概是：

里程碑：完成竞品 A 调研 关键发现：定价策略为订阅制，月费 29 美元起 数据来源：官网定价页、第三方评测 遗留问题：企业版定价未公开 下一步：调研竞品 B

这种结构化摘要比自然语言摘要更好召回，因为它有明确的字段，检索时可以按字段匹配。我试过纯自然语言摘要，召回时经常"答非所问"，换成结构化之后准确率提升明显。

注意：压缩不是越早越好。压缩太早，细节丢失，后续需要时找不回来；压缩太晚，上下文已经爆了。我的经验是，当一个子任务完成度超过 80% 时触发压缩，这个时机比较稳。

3.2 调度层：声明式任务图的构建与执行

调度层是 Harness 的大脑。声明式调度的核心是任务图——把任务拆成节点和边，节点是"要做什么"，边是"依赖关系"。

一个声明式任务定义大概长这样：

task: competitor_research goal: 完成 8 个竞品的多维度调研 constraints: - min_competitors: 8 - min_dimensions: 3 - max_duration: 2h - require_sources: true nodes: - id: collect action: gather_competitor_list output: competitors - id: research action: research_each input: competitors foreach: true output: findings - id: synthesize action: generate_report input: findings output: report edges: - collect -> research - research -> synthesize

Harness 拿到这个定义后，会自动做几件事：解析依赖关系、确定执行顺序、分配并发资源、处理失败重试。foreach: true表示这个节点要对每个竞品执行一次，Harness 会自动展开成 8 个子节点，并且可以并发执行。

声明式调度的难点在于动态调整。任务执行过程中，可能会发现"某个竞品调研失败"、"某个维度数据缺失"、"时间快超了"。Harness 需要根据这些情况动态修改任务图：失败的节点重试或跳过，缺失的维度补采，时间紧张时降低精度要求。

我的做法是给每个节点加"降级策略"：

- id: research action: research_each fallback: on_timeout: reduce_dimensions on_failure: retry_then_skip on_missing_data: mark_incomplete

这样 Harness 在遇到问题时，不是简单报错，而是按预设策略降级，保证任务能跑完。长时任务里，"跑完但质量打折"通常比"中途崩溃"更有价值。

3.3 工具层：沙盒执行与权限控制

工具层是 Harness 的手脚。Agent 要干活，就得调工具：搜索、读写文件、执行代码、调 API。但工具调用是风险最高的环节——代码可能跑飞，API 可能超时，文件可能被误删。

沙盒执行是标配。我的做法是每个工具调用都在独立沙盒里跑，沙盒有资源限制（CPU、内存、时间）和权限限制（能访问哪些文件、能调哪些 API）。这样即使某个工具调用出问题，也不会影响整个 Harness。

权限控制要分级。我把工具权限分成三档：

• 只读：搜索、读文件、查 API，随便调，无风险。
• 受限写：写文件、调有副作用的 API，需要声明目标路径/资源，Harness 校验后才放行。
• 高危：执行任意代码、删除文件、发外部请求，需要显式授权，且默认在沙盒里跑。

这个分级不是拍脑袋定的，是根据"出错后的可恢复性"来的。只读操作出错无所谓，重试就行；受限写出错可能污染数据，要能回滚；高危出错可能造成不可逆损失，必须严格管控。

实操心得：沙盒的资源限制别设太紧。我早期把单次工具调用限制在 10 秒，结果很多正常的搜索和 API 调用被误杀。后来放宽到 60 秒，误杀率大幅下降。长时任务里，单步慢一点没关系，整体跑完才重要。

3.4 记忆层：向量检索与结构化召回的结合

记忆层是状态层的延伸，专门负责"从历史里找东西"。纯向量检索的问题是召回不准，纯结构化查询的问题是覆盖不全。我的做法是两者结合：

先用结构化字段做粗筛，比如"找所有关于竞品 A 定价的信息"，按competitor=A和topic=pricing过滤；再在粗筛结果里做向量检索，找语义最相关的片段。这样既保证了范围准确，又保证了语义匹配。

召回时机也很关键。不是每步都召回，而是在需要历史信息时主动触发。怎么判断"需要"？我的做法是让 Agent 在每步开始时先做一个判断："当前步骤需要哪些历史信息？"如果需要，就发起召回；如果不需要，就直接执行。这个判断本身也是一次模型调用，但成本很低，收益很大。

3.5 可观测层：日志、追踪与回放

可观测层是 Harness 的眼睛。长时任务跑几个小时，中间发生了什么，必须能追溯。我的做法是全链路追踪：每个节点、每次工具调用、每次状态变更，都记一条结构化日志，带上时间戳、节点 ID、输入输出摘要。

日志之外，还要能回放。任务失败后，我想知道"如果当时不这么做，会不会成功"，就需要回放能力。回放的实现是：把任务执行过程录成一个事件序列，回放时按序列重放，可以在任意节点暂停、修改、继续。这个能力在调试长时任务时价值极高，我靠它定位过好几个"偶发失败"的 bug。

4. 实操落地：从零搭一个能跑长任务的 Harness

4.1 环境准备与技术选型

先说选型。Harness 本身不复杂，复杂的是它要集成的组件。我的技术栈是这样的：

• 编排引擎：自己写，核心是一个任务图执行器，大概 500 行代码。不用现成框架是因为长任务的调度逻辑太定制化，框架反而束缚。
• 状态存储：短期历史用本地 SQLite，长期知识用向量库（我用的 Chroma，轻量够用）。
• 沙盒：Docker 容器，每个工具调用起一个临时容器，跑完销毁。
• 可观测：结构化日志写文件，追踪用 OpenTelemetry 标准格式。

为什么不用现成的 Agent 框架？我试过几个，问题是它们大多为短任务设计，状态管理和调度能力偏弱，长任务跑起来还是要自己补一大堆东西。与其在框架上打补丁，不如自己搭一套轻量的，可控性更强。

4.2 任务定义与调度器实现

调度器的核心是一个循环：解析任务图、找可执行节点、执行、更新状态、重复。关键代码如下：

class Harness: def __init__(self, task_def, state_store, tool_executor): self.graph = build_graph(task_def) self.state = state_store self.tools = tool_executor def run(self): while not self.graph.is_complete(): ready = self.graph.get_ready_nodes() for node in ready: try: result = self.execute_node(node) self.state.record(node.id, result) self.graph.mark_done(node.id) except Exception as e: self.handle_failure(node, e) self.maybe_compress() def execute_node(self, node): context = self.state.build_context(node) if node.needs_recall: context += self.state.recall(node.query) return self.tools.run(node.action, context, node.params)

这段代码看着简单，但每个方法里都有细节。build_context要决定给节点喂多少历史；recall要做结构化+向量混合检索；handle_failure要按降级策略处理；maybe_compress要在合适的时机触发压缩。

4.3 状态压缩与召回的具体实现

压缩的实现，我踩过最大的坑是"压缩后信息丢失导致后续步骤失败"。后来改成压缩时保留原始数据的引用，摘要里带上"原始数据 ID"，需要细节时可以按 ID 回查。这样摘要负责快速召回，原始数据负责精确还原，两全其美。

def compress(self, node_ids): raw = self.state.get_raw(node_ids) summary = self.llm.summarize(raw, schema=MILESTONE_SCHEMA) summary.raw_ref = self.state.store_raw(raw) self.state.store_summary(summary) self.state.drop_raw(node_ids)

召回时，先按结构化字段查摘要，命中后如果需要细节，再用raw_ref取原始数据。这个设计让压缩变得"无损"——表面上丢了细节，实际上随时能找回来。

4.4 沙盒工具调用的配置要点

沙盒配置有几个关键参数：

sandbox: image: agent-toolbox:latest cpu_limit: 1.0 memory_limit: 512Mi timeout: 60s network: restricted mounts: - /workspace:rw - /data:ro

network: restricted表示只允许访问白名单域名，防止工具调用跑到不该去的地方。mounts里/workspace可读写，/data只读，这样工具能读数据但不能改数据。这些配置看着琐碎，但每一条都是踩坑踩出来的。

注意：沙盒镜像要预装好常用工具，别在运行时现装。我早期让沙盒运行时 pip install，结果网络一抖就失败，任务卡住。后来把依赖全打进镜像，启动快且稳定。

4.5 一个完整长任务的执行记录

拿我最近跑的一个任务举例：调研 10 个开源 Agent 框架，输出对比报告。任务定义声明了 10 个框架、5 个维度、2 小时上限。

执行过程：前 20 分钟收集框架列表和基础信息，中间 60 分钟逐个深入调研，最后 30 分钟生成报告。中间触发过 3 次压缩，2 次召回，1 次降级（有个框架的文档站挂了，降级为只调研 GitHub README）。

最终报告质量不错，10 个框架全覆盖，5 个维度都有数据。整个过程 Harness 记录了 847 条日志，回放时能精确看到每一步。这个任务如果不用 Harness，靠裸调 API，我估计跑到第三个框架就崩了。

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

5.1 任务中断与状态丢失的排查

最常见的故障是任务跑到一半中断，重启后状态丢失。排查思路：

我遇到最多的是"上下文溢出未处理"。Harness 如果没有主动压缩，模型调用会直接报错，任务就断了。解决方法是在每次模型调用前检查 token 数，超过阈值就触发压缩，别等报错。

5.2 工具调用失败的降级策略

工具调用失败太常见了，网络抖动、API 限流、目标站点挂了，什么都有。我的降级策略是三级：

1. 重试：瞬时故障，重试 2-3 次，间隔递增。
2. 降级：持续故障，换备用方案，比如主 API 挂了换备用 API，详细数据拿不到就拿摘要。
3. 跳过：实在拿不到，标记为"数据缺失"，继续后续步骤，最后在报告里注明。

关键是别让单个工具失败拖垮整个任务。长时任务里，完成度 90% 比完美但崩溃有价值得多。

5.3 上下文压缩导致信息丢失的补救

压缩导致信息丢失，表现为"后续步骤说'我不知道之前调研了什么'"。补救方法：

• 压缩时保留 raw_ref，需要时回查原始数据。
• 压缩摘要用结构化格式，字段明确，召回准确。
• 关键决策单独存，不参与压缩，永远可查。

我现在的做法是，凡是"影响后续分支的决策"，都单独存一份，不压缩。比如"决定跳过竞品 X 的企业版调研"，这种决策必须一直可查，否则后续步骤会重复劳动。

5.4 长任务性能优化的几个实操技巧

长任务跑得慢，优化点主要在三个地方：

• 并发：foreach节点尽量并发，我一般开 4-8 个并发，再多容易触发 API 限流。
• 缓存：相同查询缓存结果，比如多个竞品都要查"定价页"，可以复用。
• 预取：下一步大概率要用的数据，提前加载，减少等待。

我实测下来，加并发能提速 3-5 倍，加缓存能再提速 20-30%。预取效果不稳定，看任务类型，有时候反而增加无效加载。

5.5 常见错误速查表

这张表是我从几十次失败里总结出来的，基本覆盖了 90% 的常见问题。遇到新问题，先查表，查不到再深挖日志。

6. 我对 Harness 这件事的几点个人判断

跑了大半年长任务，我越来越觉得 Harness 是 Agent 领域被低估的一环。大家都在卷模型能力，但模型能力的边际提升在放缓，而 Harness 的优化空间还很大。同样一个模型，Harness 做得好，能跑几小时的长任务；Harness 做得差，十分钟就崩。这个差距，比模型版本之间的差距大得多。

Anthropic 和 Google 的思路，本质上都是在把 Harness 工程化、标准化。Anthropic 侧重状态管理和长时任务的鲁棒性，Google AX 侧重声明式调度和任务编排。两套思路不冲突，可以结合用：用声明式定义任务，用分层状态管理执行。

如果你现在在做 Agent 项目，我的建议是：别急着换更大的模型，先把 Harness 补起来。状态管理、调度、沙盒、可观测，这四块补齐，你的 Agent 能跑的任务复杂度会有一个质的飞跃。模型是马，Harness 是挽具，好马配好鞍，才能跑长途。

最后分享一个小技巧：Harness 的每个模块都别做太满，留好扩展点。长任务的需求变化很快，今天够用的压缩策略，明天可能就不够了。留好接口，随时能换，比一次做到完美更重要。我现在的 Harness 已经迭代了七八个版本，每次都是小步改，从没大重构过，靠的就是早期留的扩展点。