AI-7D-SATS平台的harness engineering设计：让 AI Agent 从“工具堆叠”长成“工程制品”

2026/8/12 20:46:24 拓冰建站浏览量

文章目录

- 一、问题：Agent 到底是什么？
- 二、什么是驾驭工程？
- 三、AI-7D-SATS 的四层驾驭架构
- 四、第一层：Skill — 标准化的原子能力
- - 4.1 严格的输入输出契约
  - 4.2 BaseSkill 的模板方法模式
  - 4.3 自动发现的注册中心
- 五、第二层：Agent — 驾驭体
- - 5.1 三种推理策略（Strategy Pattern）
  - 5.2 AgentContext — 推理状态容器
  - 5.3 ReAct 循环里的决策机制
  - 5.4 Plan-and-Execute 的自动重规划
- 六、第三层：Orchestrator — 薄薄的协作层
- - 6.1 从 800 行 if/elif 到 100 行路由层
  - 6.2 三层降级路径
  - 6.3 SkillPipeline：静态链式编排
- 七、第四层：LLM Router — 给 LLM 也加一层 Harness
- - 7.1 LLM Router 的解析顺序
  - 7.2 FallbackManager 的健康感知
  - 7.3 配套的两个支撑系统
- 八、可观测性：每一步都看得见
- - 8.1 实时 SSE 事件流
  - 8.2 完整 Trace 持久化
- 九、配置驱动：Agent 即数据
- 十、五条设计原则
- 十一、实际效果
- 十二、写在最后

当 AI Agent 系统逐渐复杂，我们需要一套工程化的方法来“驾驭”它。本文以 AI-7D-SATS 智能平台的真实架构为蓝本，讲清楚 Harness Engineering（驾驭工程）如何把零散的能力打磨成可观测、可配置、可演进的工程制品。

一、问题：Agent 到底是什么？

最朴素的实现是把 Agent 写成 Skill 的薄包装。“帮我生成脚本”就调脚本生成 Skill，“帮我分析根因”就调根因分析 Skill。Agent 没有思考能力，只是一个透传层。这种实现看起来“能跑”，但当业务真实复杂起来，就会暴露三个连锁问题：

1. 编排器职责膨胀

一个 800 行的 if/elif 链，所有意图、所有领域知识、所有工具调用全集中在它身上，改一处牵一片。

2. Agent 没有恢复能力

Skill 失败就是任务失败，没有重试、没有降级、没有 replan。

3. 黑盒不可观测

用户只能看到最终结果，过程中的推理、Skill 选择、决策点全在日志里漂着，没法做事后审计、调优和自进化。

这就像把一堆零散的工具随意塞进工具箱——能用，但谈不上工程。我们需要的不是工具的堆砌，而是对工具的驾驭。

二、什么是驾驭工程？

Harness 这个词在英文里有“驾驭、驯服、整合利用”的含义。驾驭工程的核心命题是：

单个能力只是原材料。经过标准化、编排、保护、路由和观测之后，它们才能成为可靠的工程制品。

一套合格的驾驭体系必须同时具备：

维度	具体含义
原子能力	最小、自治、可独立测试的功能单元
标准接口	让能力之间能正确对接、彼此替换
编排逻辑	按特定推理拓扑把能力组合成更高阶的工作
保护机制	故障隔离，防止局部失败级联放大
可观测性	运行状态实时可见，推理过程完整留痕
路由策略	根据任务特征把请求送到最合适的处理者

驾驭工程不是能力的简单集合，而是一个经过精心设计、自身就有结构和智能的独立系统。

三、AI-7D-SATS 的四层驾驭架构

我们把这套思想落地为四层模型，每一层都有自己的契约、状态和保护机制：

第一层：Skill— 标准化的原子能力
第二层：Agent— 驾驭体（推理引擎 + 状态管理 + 故障恢复）
第三层：Orchestrator— 薄薄的协作层
第四层：LLM Router— 给 LLM 也加一层 Harness

特别值得提的是第四层——LLM 驾驭层。我们不仅驾驭 Skill，也驾驭 LLM 本身。

四、第一层：Skill — 标准化的原子能力

4.1 严格的输入输出契约

每个 Skill 都通过同一份 Pydantic 契约对外：

classSkillInput(BaseModel):data:dictcontext:dictoptions:dictclassSkillOutput(BaseModel):success:boolerror:str|Nonewarnings:list[str]skill_name:strskill_version:strexecution_time_ms:intconfidence:float=1.0reasoning:str=""result:Any

注意confidence和reasoning这两个字段——它们不是装饰，是后续 Agent 决策“要不要继续往下走”的核心依据。一个低置信度的输出会让上层 Agent 选择重试或换条路，这就是驾驭工程里“局部状态指导全局决策”的具体体现。

4.2 BaseSkill 的模板方法模式

所有 Skill 子类只关心一件事：_execute()里写业务逻辑。剩下的边界工作由BaseSkill.execute()统一处理：

asyncdefexecute(self,input:SkillInput)->SkillOutput:start=time.monotonic()err=self.validate_input(input)iferr:returnSkillOutput.fail(error=err)try:output=awaitself._execute(input)exceptExceptionase:output=SkillOutput.fail(error=str(e))output.skill_name=self.name output.execution_time_ms=int((time.monotonic()-start)*1000)returnoutput

子类永远不需要操心计时、版本号、异常吞吐——这些一致性是模板方法保证的。标准化不是规范文档，是用代码强约束的边界。

4.3 自动发现的注册中心

SkillRegistry是一个单例，启动时通过pkgutil.iter_modules扫描app/skills/包，把所有BaseSkill子类自动注册：

def_discover_skills(self)-></

建站实战干货