企业官网建设流程全解析

1. 先搞清楚：Agent 和 Harness 到底什么关系

最近圈子里冒出来一个高频词——harness。先是 Claude Code 把 harness 工程实践带火，跟着 DeepSeek harness 的各种插件、安装教程铺天盖地，连 Google AX 那边也开始聊声明式调度。很多朋友跑来问我：harness 到底是个什么东西，它跟 Agent 有什么区别，为什么一夜之间就变成了“护城河”？

我直接说结论：Agent 是大脑，harness 是身体。你可以把 Agent 理解成一台发动机，而 harness 是整辆车的底盘、悬挂、仪表盘和方向盘。没有 harness 的 Agent，就像一台裸发动机放在地上，能轰鸣能转，但跑不了路，更别提完成什么实际任务。长期以来大家关注 Agent，都是在调模型提示词、选推理参数、比较各家大模型的能力差异，但真正让 Agent 从玩具变成生产力的，是外面这一整套工程外壳——会话管理、工具注册、权限边界、状态持久化、调度策略、可观测性、成本控制，这些东西统称起来就是 harness。

为什么我今天要专门写这个话题？因为我观察到一个很明显的信号：模型能力的差距正在快速缩小。DeepSeek 和 Claude 在编码、推理上的表现越来越接近，大家拼提示词的空间越来越小。但你去看那些真正稳定跑在生产环境的 Agent 系统，差距反而越拉越大。差距出在哪？出在 harness 上。有人用裸 API 写了个 Agent，跑三分钟就上下文溢出；有人用 harness 把任务拆成状态机，连续跑几小时甚至几天都不崩。这不是模型的问题，是工程外壳的问题。

这篇文章我会从三个层面展开：先拆 Anthropic 在设计长时任务时的那套思路，再说 Google AX 的声明式调度到底解决什么问题，最后带大家手把手搭一套能落地的 harness，把 RPA、内网私有化、Skill 加载、定时任务这些实操环节全部过一遍。适合谁看？正在做 Agent 开发、想搭 Agent 框架、遇到“Agent 跑一半就挂”“并发一上来就崩”“模型调得不错但没法在生产环境用”这类问题的朋友，这篇文章应该能给你一些实打实的参考。

1.1 发动机与整车的比喻：为什么 Harness 才是真正干活的东西

我见过太多团队走了同样的弯路：花大把时间选模型、调系统提示词，Agent 在测试环境表现惊艳，一到生产环境就原形毕露。不是模型不行，是他们根本没有 harness 的概念。

举个具体的例子。你让 Agent 完成“从数据库拉取订单，生成周报，发送到企业微信”这个任务。没有 harness 的写法是：写一个 Python 脚本调用模型 API，把任务描述丢给模型，拿到返回结果就结束。这套东西在演示的时候没问题，但一旦碰上数据库连接超时、企业微信接口限流、模型中途返回了格式错误的 JSON，整个流程就断了。更麻烦的是，如果这个任务要跑两小时，中间进程被重启，你的 Agent 连自己刚才干到哪儿了都不知道。

这就是 harness 的价值所在。它把 Agent 的每一次动作都放进一个可控的框架里：调用工具之前先检查权限，调用之后记录结果，任务中断时保存检查点，恢复时从检查点继续，整个过程都有日志和 trace 可以回溯。用工程的语言说，harness 把 Agent 从一段不可靠的代码变成了一套有状态、可恢复、可观测的系统。

1.2 护城河的本质：数据飞轮、安全边界和可控性

再说说“护城河”这个词。护城河的本质是别人很难在短时间内复制你的东西。模型是公开的，API 谁都能调，Prompt 技巧慢慢也会被学走，那什么叫别人抄不走？

我认为有三样：第一，你通过 harness 沉淀下来的 trace 数据和测评集。Agent 在真实环境中跑了多少次、哪些路径成功、哪些失败、调用了哪些工具、花了多少 token，这些数据是调整 Agent 行为的关键依据，也是别人拿不到的。第二，你围绕业务场景设计的工具集和 Skill 包。同样的模型，你接了内部系统的 50 个工具接口，别人接不了。第三，安全的权限边界。Agent 能做什么、不能做什么，通过 harness 控制得清清楚楚，这在企业落地时是生死线。

举一个我实际见过的情况：有个团队做了个很聪明的 Agent，能自动查报表、写邮件、安排会议，演示效果非常惊艳。但客户一问“它能删数据库吗？能对外发邮件吗？操作记录在哪看？”团队当场傻眼——因为他们根本没有这层控制。后来我在他们的架构里加入了 permission 控制层和完整的审计日志，客户才放行部署。这套东西，就是 harness。它不产生智能，但它是智能可靠落地的前提。

2. Anthropic 长时任务设计拆解：从“对话”到“工程”

Anthropic 在设计 Claude 的长时任务（Long-running Task）时，提出了一套非常值得学习的工程思路。它不是教你怎么写提示词，而是教你如何把“让 Agent 干活”这件事，变成一套健壮的分布式系统。这背后有三个核心问题需要解决：状态怎么管、失败怎么处理、上下文怎么不爆。

2.1 长时任务的三座大山：状态、失败、上下文

第一座山是状态。一个需要执行数小时的任务，比如“爬取 1000 个网页并生成摘要报告”，Agent 不可能在一个请求里完成。它必然要分多轮执行：每轮调用模型、调用工具、得到结果，然后继续下一步。问题来了——Agent 怎么知道当前执行到哪一步了？上一轮产出物存在哪里？如果中途崩了，重启之后从哪里继续？

处理这个问题，靠的不是把状态塞进上下文（那是灾难），而是把状态从模型里“拆”出来。我常用的做法是把任务建模成一组有序的子任务，每个子任务有明确的输入、输出和状态标记（pending/running/succeeded/failed）。整个任务组的状态放在一个独立的存储里——可以是 Redis、数据库表，也可以就是一份 JSON 文件。Agent 每完成一步，就更新这个状态存储。下次要恢复时，读状态文件，跳过已完成的部分，从失败节点重跑。这就是检查点（checkpoint）的基本思想。Anthropic 的 Agent SDK 里那个 Task 组件，本质上干的就是这件事。

第二座山是失败。长时任务必然会遇到失败：第三方 API 超时、某个网页打不开、模型输出格式不对。关键是失败之后怎么办。我见过很多新手的处理方式是一股脑地重试整个任务，结果前面的工作全部作废，还烧掉大量 token。正确的做法是：把重试粒度放到“单个原子操作”，而不是整个任务。某一步失败就重试这一步，配上指数退避（第一次等 1 秒，第二次等 2 秒，第三次等 4 秒……），连续失败超过阈值就标记该子任务为失败，并启动独立的补偿逻辑。这样整套系统才有韧性。

第三座山是上下文。Agent 跑长任务的通病是 token 越积越多，最终把上下文窗口塞爆。很多人的第一反应是“换个更大窗口的模型”，这只能缓解，不能根治。我采用的方案是分层记忆：核心指令和当前任务目标永远保持在最前面；中间过程的结果经过摘要压缩后放入中段；原始的长文本日志放到外部存储，只在需要的时候通过检索工具调取。这套设计在 Anthropic 的实践中有一个专门的词叫“上下文工程”，用到的方法包括摘要、结构化记录、外部检索和自动裁剪。

2.2 任务图与检查点设计：一步一存档，句句有着落

聊到具体的实现，我推荐用 DAG（有向无环图）来组织长时任务。什么意思呢？你把一个大任务拆成多个小任务，小任务之间有依赖关系：A 完成后才能做 B，A 和 B 都完成后才能做 C。这些依赖关系画出来就是一张图。好处是并行度高、容错性强：B 和 C 如果没有依赖，可以并行执行；某个分支失败了，只影响下游，不会波及整个任务。

检查点的设计逻辑与之配套。我是这么干的：每个子任务开始前，先记录一条状态“START”；执行过程中定期把中间结果写盘；成功结束后标记“DONE”，附上产出物的存储地址。这样哪怕整个系统崩溃，重启后只需要扫描一遍任务状态表，把那些“START 但没 DONE”的任务挑出来重跑即可。这比“跑完整个流程再做记录”的可靠性高出一个数量级。

我还想强调一点：检查点不仅是容错手段，还是成本控制利器。长任务跑到一半如果发现模型输出方向不对，你可以在检查点位置人工介入——修改提示词、调整参数，然后从该节点继续。这就避免了推倒重来烧掉的巨额 token 费用。实际项目中，这种能力经常能省下 30%-50% 的成本。

2.3 幂等性与重试：别再重复扣钱

长时任务设计里还有一个容易被忽略的细节——幂等性。举个常见场景：Agent 要调用支付接口给用户退款，调用的那一刻网络超时了，模型判断失败于是重试，结果退款成功执行了两次。这就是非幂等操作引发的灾难。

解决办法分两层。第一层，在工具设计层面，所有写操作尽可能做成幂等的：每个操作带上唯一的 request_id，服务端判断如果这个 ID 已经处理过就直接返回上次的结果，不重复执行。第二层，在 harness 层面，对工具调用做去重：记录每一步工具调用的参数哈希，重试时如果发现完全相同的调用请求，先查询历史结果，而不是盲目重发。你可能觉得这是后端工程师该操心的事，但在 Agent 工程里，这个责任必须由 harness 来兜底，因为模型自己是不会记住“刚才这笔已经成功”的。

3. Google AX 的声明式调度：任务怎么“配置”出来

说完了 Anthropic 长时任务的状态设计与容错，接来下看另一个方向——Google AX 带来的声明式调度理念。这个词听起来有点抽象，但我打个比方你就懂了。命令式调度就像你给下属布置任务时说“你先做 A，再做 B，然后如果 C 成立了就做 D，不然就做 E”；声明式调度则像你说“我要每周一早上 9 点拿到上周的销售报告，数据从仓库拉，格式按模板来，如果数据缺失就邮件提醒我”。前者强调“怎么做”，后者强调“要什么”。至于过程怎么执行，由调度系统自己去编排。

3.1 命令式调度为什么会失控

我自己的项目早期全是命令式调度。Agent 的主循环里写满 if-else：如果今天是周一就跑周报流程，如果收到新订单就跑订单处理流程，如果队列里有未完成任务就跑任务续跑流程。刚开始只有两三个流程还能应付，后来流程多起来，代码就成了一团乱麻。更要命的是，调度逻辑和业务逻辑耦合在一起，每加一个新任务就要改主循环代码，改一次崩一次。

后来我彻底转向了声明式。每个任务用一份 YAML 或 JSON 描述：触发条件是什么、依赖哪些数据、超时多久、失败怎么重试、结果通知谁。调度器读这些配置，自己决定怎么安排执行。这带来的最大好处是可审计——任务规则一目了然，不需要读代码就能理解系统在干什么。第二个好处是可复用——同样的配置模板，换个参数就能给另一个客户用。

3.2 一份 YAML 搞定定时 Agent 任务：从 cron 到流程编排

来一个具体的声明式调度配置示例，这个配置在我自己的内网环境里实测过：

task: name: daily_sales_report description: 每日销售数据汇总与异常提醒 trigger: schedule: "0 9 * * *" # 每天 9:00 触发 inputs: db: orders_db date: "{{ today - 1 }}" steps: - name: fetch_orders tool: query_database params: sql: "SELECT * FROM orders WHERE create_date = '{{ inputs.date }}'" connection: "{{ inputs.db }}" retry: max_attempts: 3 backoff: exponential - name: summarize tool: llm_generate params: task: "将以下订单数据归纳为销售日报，包含总销售额、订单量、环比变化" input: "{{ steps.fetch_orders.output }}" model: deepseek-chat max_tokens: 2000 - name: send_report tool: webhook_notify params: url: "{{ configs.report_webhook }}" content: "{{ steps.summarize.output }}" on_success: - log: "报告已发送" policies: timeout_sec: 600 on_timeout: notify_admin on_failure: - retry_steps: [fetch_orders, summarize] - notify_admin: true

这个配置描述了一件完整的事：每天早上 9 点，查订单库，让模型生成日报，通过 webhook 发出去。调度器拿到这份 YAML 后，会自动生成执行计划、绑定工具、监控状态。你不需要关心“什么时候查库、什么时候调模型”——那是调度器的事。

Google AX 的声明式调度在理念上更进一步，它把任务依赖、资源配额、权限要求全部提升到了配置层。这意味着任务不只可以被“设置”，还能被“治理”：谁能跑这个任务、跑任务时消耗多少配额、是否满足合规要求，都能在配置阶段校验。这对于大型组织批量管理成百上千个 Agent 任务来说非常关键。

3.3 声明式的边界：不是所有事情都能配出来

当然，声明式调度不是银弹，它适合的是流程相对固定、规则明确的场景。你让 Agent 干“处理一张完全陌生的用户投诉”，这种开放式的探索任务，非要写成声明式配置反而会绑住手脚。我个人的分界标准是：如果任务的执行路径基本可预期，就用声明式；如果完全不可预期，保持命令式让 Agent 自由发挥，但外层仍然要有 harness 的护栏。

实践中有个折中的做法，我一直在用：用声明式配置定义任务的“骨架”——触发条件、工具权限、超时和重试策略、结果去向，这些是硬边界；骨架之内的是“血肉”，由模型自动规划执行路径。这样既保持了可控性，又保留了灵活性。比如上面那个销售日报任务，查库和发消息的步骤是固定的，但“归纳成什么样的报告摘要”这句话由模型自己发挥。这就是我对声明式调度边界的理解。

4. 手把手搭一套可落地的 Harness：内网私有化 + RPA 场景

理论聊完了，进入实战环节。这部分我把近半年搭建的一套带 Agent 且支持调度的架构完整拆给你看，场景是企业内网私有化部署，配合 RPA 做自动化流程落地。整个过程踩了不少坑，我把能省的弯路都替你走了。

4.1 环境准备与 Harness 框架选型

首先要面对的问题是选型。市面上能当 harness 用的东西不少：Claude 的 Agent SDK 是一个参考方向，DeepSeek harness 插件因其轻量、贴合国内模型的接入方式，在企业内网场景下用得更广。如果你要对接的是国产模型，DeepSeek harness 可以作为首选参照。Go、Rust 等高性能语言写的一些 Agent 框架也值得关注，尤其你在乎并发性能时。

我的建议是，别追求大而全的框架，先想清楚这三个问题：你主要跑哪些模型（决定 harness 的模型接入层要做什么适配）；任务形态是什么（定时批处理还是实时交互）；运行环境有什么限制（能不能上公网、要不要私有化）。搞清楚了再选，接下来这套落地方案，你可以直接照着搭。

部署重点有三块：

• 模型网关层：内网环境的模型接入，统一走企业内部模型网关（如 DeepSeek 的私有化网关），harness 只对接网关地址，不直连外部 API。好处是密钥管理集中，模型切换时不用改业务代码。
• Skill 加载器：Agent 的技能以独立插件形式存在，harness 启动时动态加载指定目录下的 skill 包。每个 skill 包含技能描述、工具定义、调用参数 schema 和示例提示词，方便复用。
• 状态存储：用 Redis 或 PostgreSQL，存任务状态、会话记录、工具调用日志。

关于模型网关，我要特意多说一句：我看到很多排在各种报错里最频繁的一条，就是“unable to connect to anthropic services”之类的连接类报错。超过一半的情况不是模型服务真挂了，而是网关路由或代理配置有问题。走私有化 harness 时，把所有外部依赖收敛到网关这一层，可以隔离大量网络问题。

4.2 Skill 加载与提示词优化：让专业能力可复用

Agent 要真正体现价值，关键在 Skill 的沉淀。我见过很多团队，每个 Agent 项目都从零开始写提示词，最后质量参差不齐、互相不通用。这是典型的没有 harness 思维——Skill 应该像代码库一样被管理和版本化。

我的做法是把 Skill 做成标准的目录结构：

skills/ ├── database_queryer/ │ ├── SKILL.yaml # 技能元信息：名称/描述/参数schema/适用场景 │ ├── system_prompt.md # 调用该技能时附加的系统提示词 │ ├── tools.py # 工具实现：具体执行的函数 │ └── examples.md # 少样本示例：常见输入与预期输出 ├── report_generator/ │ └── ... └── rpa_operator/ └── ...

SKILL.yaml 里声明这个技能需要哪些参数、可以被哪些任务调用、权限级别是什么。harness 在启动时扫描所有 skill 目录，把技能描述注入系统提示词，同时做工具注册。之后模型在推理时，自然就知道“这个问题应该调用 database_queryer 这个技能”。这其实就是目前很火的 Agent Skills 模式，只是很多文章没讲清楚它与 harness 的关系——Skill 是 harness 中的能力单元，没有 harness，Skill 只是散落的脚本；有了 harness，Skill 才是可被模型自动发现和调用的专业能力。

写 Skill 有一个要点：描述必须写得像“给同事交代工作”，不能太抽象。模型不会“猜”你的工具是干什么的，它只能根据描述来判断何时调用。一个合格的技能描述，应该包含：触发条件（什么情况下调用）、调用参数（每个参数的含义）、返回值（拿到的结果长什么样）、典型使用示例。我在一个外呼机器人里就吃过亏——技能描述写得太含糊，模型老在需要查客户等级时去调“查询客户全信息”这个超重工具，造成大量多余的 token 消耗，后来在描述里加了“当仅需客户等级时请直接调用本技能，不要获取完整档案”，效果立竿见影。

4.3 完整配置：一份可直接复制的任务调度 YAML

回到上一节的销售日报场景，我把它完整展开。首先在 harness 的配置目录里新建一个任务文件。除了任务本身的 YAML，还需要全局配置：

harness: version: "2.0" model_gateway: base_url: "http://internal-gateway:8080/v1" api_key_env: "HARNESS_GATEWAY_KEY" provider: deepseek storage: type: postgres dsn: "postgres://harness:harness@localhost:5432/harness" sandbox: enabled: true allow_network: true allow_filesystem: ["/data/reports", "/tmp/harness"] logging: level: info trace_output: "/var/log/harness/traces"

这份全局配置有几个关键点值得展开。Sandbox（沙箱）是 Agent 安全的基石：即使模型胡乱调用工具，文件系统访问也被限制在允许的目录里，防止 Agent 在任务中误删或篡改企业关键文件。Trace 输出则保证了每次 Agent 行为都有案可查——哪些工具被调用了、谁触发的、结果如何，全部留痕。在企业合规评审时，这份日志的价值比任何报告都管用。

任务配置（daily_sales_report.yaml）就是上一节那份，我不再重复贴。值得注意的是调度器怎么执行：harness 的调度器每分钟扫描一次所有任务配置，检查触发条件；条件满足后，自动创建任务实例放入执行队列，每个实例有独立的 task_id。执行过程中，所有工具调用都通过 harness 的统一代理层完成，结果是自动记录到 PostgreSQL，并写一份执行 trace 到日志。

如果你想在非定时需求下唤起 Agent，harness 同等的接口也可以随时调用，例如通过简单的 REST 接口：

curl -X POST http://harness-server:8080/api/v1/tasks/run -H "Content-Type: application/json" -d '{"config": "daily_sales_report", "params": {"date": "2025-01-15"}}'

4.4 与 RPA 集成：Agent 决策 + 机器人执行

企业落地场景里，Agent 不能直接操作的系统非常多。老旧的 ERP、没有 API 的遗留系统、需要 U盾插卡的内网财务系统……这个时候 RPA（机器人流程自动化）就是 Agent 的双手。热词里有人提到“harness + RPA 落地实现”，这是个很有意思的方向，我的实践是：让 Agent 负责决策和规划，RPA 负责具体执行，harness 负责二者的协调。

具体流程是：Agent 识别到“需要查询某个遗留系统里的客户信息”，它不直接尝试调接口（因为根本没有接口），而是生成一条结构化的指令，投递到任务队列；RPA 机器人轮询到这条指令后，打开系统、输入查询条件、截图或读取页面数据，再把结果写回队列；Agent 异步获取结果后继续后续流程。这套机制的关键在 harness 给 RPA 调用也做了封装：把 RPA 操作抽象成一个特殊的工具（rpa_operator），包含 action、target_system、params 三个参数，并配置了执行超时与结果回调。这样模型根本不用关心 RPA 的底层细节，对它的感知就是“我有一个工具，调用后能得到页面数据”。这个抽象层解决了 Agent 与异构系统之间的集成难题。

有一点必须提醒：给 RPA 工具配权限时要更谨慎。RPA 能操作真实业务系统，一旦 Agent 被诱导执行恶意指令，后果比调 API 严重得多。我的做法是——涉及 RPA 的调用一律先进入人工审批队列，收到审批通过的回调后，Agent 才能继续执行后续步骤。虽然降低了全自动程度，但在不想承担失控风险的场景里，这是必要的取舍。

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

这部分我把过去半年被问得最多的实战问题整理成一个速查表。大部分问题我都亲手排查过，照着看能省不少时间。

5.1 部署与加载问题速查表

插件加载失败这个问题，我想多说一句。我遇到过几次是插件依赖了某个系统库但安装时被静默跳过。排查的时候用 strace 或直接看启动日志的 dynamic link 信息，会比瞎猜快得多。还有一个容易被忽略的坑：插件目录里如果存在两个互相冲突的版本，也会导致 entry did not activate，清理干净旧的编译产物就好。

5.2 并发与资源问题：AI Agent 怎么扛住高并发

“AI Agent 怎么扛并发”这个问题经常看到有人问，其实 Agent 的并发瓶颈很少在模型本身，更多在工具调用和状态存储层面。每个 Agent 实例在工作时都在调用外部系统，如果 50 个 Agent 同时查同一个数据库，再稳的数据库也会被拖垮。我的解决方案是在 harness 里做两层限流：

第一层，工具调用级别的信号量控制。每个工具注册时可以声明最大并发数，比如数据库查询工具最大支持 5 个并发，超过的请求排队等待。第二层，任务级别的队列控制。同一时间最多运行多少个 Agent 实例，由调度器统一管理，超出的任务先在队列里排队，而不是无脑铺开。

内存方面也要注意。长时间运行的 Agent 会在内存里缓存历史记录，如果任务量大，内存很容易吃满。建议在 harness 配置里定期做状态快照并释放内存缓存，把历史归档到磁盘或数据库。

5.3 安全与权限的边界把控

最后谈谈安全，这是企业落地绕不开的主题。Agent 的权限设计有一条铁律：最小化授权。Agent 默认没有任何权限，每个 Skill 和工具显式声明自己需要哪些权限。拿文件操作为例，skill 里面写清楚“可读 /data/reports/ 下的文件，可写 /tmp/harness/ 目录”，harness 在运行时会做路径校验，发现越权访问直接拒绝并记录审计日志。

还有一个特别重要的细节：工具调用的输出里可能包含敏感信息。Agent 在对话中可能无意地把这些信息带进模型的上下文，一旦模型服务是外部调用，这就有数据合规风险。所以在企业内网环境，我强烈建议模型也走私有化部署。如果没有条件做全链路私有化，那至少要确保敏感字段在送进模型之前做脱敏处理——比如把手机号、身份证号、合同金额等字段先替换成占位符，等结果返回后再还原。这个脱敏逻辑也应该放在 harness 的工具调用层统一处理，而不是依赖模型自己“注意”。模型不具备可靠保密的自觉，你必须从工程上就把这道闸门关死。

踩过几次坑之后，我的体会是：别把 Agent 工程当成“写提示词”的活儿，它就是一套正经的后端系统。状态管理、幂等重试、并发控制、权限隔离、可观测性——这些经典工程问题，一个都少不了。而 harness 的全部意义，就是给 Agent 的智能套上一层可靠的工程外壳，让智能变成可控的生产力。现在的模型能力早就够用了，缺的恰恰是这层外壳。如果你正在做 Agent 项目，我的建议很简单：先别急着继续调 Prompt，停下来想想，你的 Agent 穿好“护甲”了吗？