当前位置：首页 > news >正文

Harness Engineering 架构落地设计文档

news 2026/4/23 19:42:48

Harness Engineering 架构落地设计文档（可直接落地）
文档版本：V1.0
落地适配：企业级 AI Agent 生产环境（兼容主流大模型、工具生态）
核心依据：Mitchell Hashimoto 提出的 Harness Engineering 核心理念（错误工程化解决、同类错误永不复现），基于六层闭环架构 + 两大横切能力设计，确保 AI Agent 可靠、可控、可审计、可演进。
一、架构总览（落地版）
1.1 架构闭环图（落地简化版）
接入与接口层 → 执行编排层 → 记忆与状态层 → 工具集成层 → 评估与观测层 → 约束、校验与恢复层（闭环），安全与沙箱、治理与持续演进两大能力贯穿全层。
核心等式：Agent = 大模型（智能引擎） + Harness（执行系统 + 约束系统 + 反馈系统）
1.2 核心设计目标（落地优先级）

优先级1：可靠性（同类错误永不复现，失败可自愈、可追溯）
优先级2：可控性（边界清晰、权限可控、行为可审计）
优先级3：可扩展性（支持多模型、多工具、多租户扩展）
优先级4：可观测性（全链路透明、异常可告警、瓶颈可定位）
优先级5：可演进性（规则可迭代、架构可扩展、知识可回流）
二、各层详细落地设计（含组件、接口、规则）
L1：接入与接口层（Interface & Access Layer）
2.1.1 核心组件清单（落地可用）
组件名称
组件功能
选型建议（落地优先）
部署要求
API 网关
协议转换、限流、权限校验、请求转发
Kong / Nginx + OpenResty
无状态，水平扩展，部署在负载均衡后
权限认证服务
OAuth2/JWT 签发、RBAC 权限管理、租户隔离
Keycloak / 自研（基于 Spring Security）
支持集群部署，与 API 网关联动
请求校验器
输入合法性校验、业务规则拦截、防注入
自研（基于 JSON Schema）
嵌入 API 网关，无独立部署，低延迟
Human-in-the-Loop 面板
关键决策审批、人工介入、错误修正
自研（基于 Vue3 + Element Plus）
与控制平面联动，支持实时告警推送
2.1.2 核心接口定义（OpenAPI 3.0 标准，可直接生成代码）
接口1：Agent 任务提交接口

/api/v1/agent/task/submit 请求方式：POST 请求头：Authorization:Bearer{jwt-token}Content-Type:application/json 请求体（JSON Schema）：{"type":"object","required":["taskId","tenantId","taskType","prompt","tools"],"properties":{"taskId":{"type":"string","description":"任务唯一ID（UUID）"},"tenantId":{"type":"string","description":"租户ID，用于资源隔离"},"taskType":{"type":"string","enum":["code","test","deploy","analysis"],"description":"任务类型"},"prompt":{"type":"string","description":"任务提示词（经过标准化处理）"},"tools":{"type":"array","items":{"type":"string"},"description":"任务需调用的工具列表（工具ID）"},"priority":{"type":"integer","default":3,"enum":[1,2,3,4,5],"description":"任务优先级（1最高，5最低）"},"callbackUrl":{"type":"string","description":"任务结果回调地址（可选）"}}}响应体：{"code":200,"message":"success","data":{"taskId":"string","status":"PENDING","submitTime":"string（ISO8601）","estimatedTime":"integer（秒）"}}

接口2：人工审批接口

/api/v1/agent/task/approve 请求方式：POST 请求头：Authorization:Bearer{jwt-token}请求体：{"type":"object","required":["taskId","approveStatus","approverId"],"properties":{"taskId":{"type":"string","description":"待审批任务ID"},"approveStatus":{"type":"string","enum":["APPROVED","REJECTED"],"description":"审批状态"},"approverId":{"type":"string","description":"审批人ID"},"remark":{"type":"string","description":"审批备注（可选）"}}}响应体：{"code":200,"message":<