智能问数 Multi-Agent Harness 架构设计与实践

1. 为什么需要 Harness

OpenClaw 出来之后，为了让智能问数能够像 OpenClaw 那样实现自主数据探索，做了一版双 Agent 架构的智能问数系统，由第一个 Agent 负责查找元数据、参考业务规则与范例、编写及执行 SQL，结果出来后交给第二个 Agent 进行可视化渲染。这种设计在实际业务场景中经常出现输出不稳定的问题（例如同一个问题提问 3 次，出现 1 次无结果的情况）。

分析原因，该架构主要存在以下痛点：

上下文污染与注意力分散：元数据、业务规则、问答范例和对话历史混在同一个 Session 会话中，导致 Context 过长，降低了大语言模型的注意力集中度。
范例复用缺乏硬约束：问答范例仅作为 LLM 的参考提示，缺少基于相似度判断的确定性控制，无法做到高相似度下的直接命中与快速响应。
生成与评估职责混淆：为了防止模型复读或陷入死循环，如果在生成的 Runtime 中混入评估图逻辑，会导致生成的稳定性进一步下降。

基于 Harness Engineering 原则重构架构的核心理念为：LLM 负责语义理解与创意生成，确定性工程框架负责状态约束与硬性验证。

落地实践的路径：能跑 → 能用 → 可信。

2. 三层架构与六大支柱映射

分层	智能问数落地实现
Identity	代理身份定义（角色、约束、能力边界） + 数据模型定义
Execution	状态编排（Orchestrator）、上下文隔离分舱（Context）、质量门禁（Gate）、故障恢复（Recovery）
Evolution	异常踩坑沉淀库（Pitfall Storage） + 动态加载钩子（数据飞轮闭环）

六大核心支柱：Identity / Orchestration / Context / Gate / Recovery / Evolution。

Identity代理身份说明

身份定形 → 可靠执行 → 进化增强。约束不是限制能力，而是让能力稳定释放。

3. 核心 Agent 身份定义 (Identity)

Coordinator (协调者)

身份：项目经理与质检调度员，只调度不下场干活。
输入/输出 ：用户问题 + 业务域 + 状态摘要 ➔ ExecutionPlan
能力：读取中间产物；调度上下文收集、SQL 生成与结果渲染路径；更新 Checkpoint。
红线：不直接产出 SQL 或图表；不跳过强制门禁。

MetadataAgent (元数据专家)

身份：需求驱动的数据库表字段剪裁专家。
输入/输出 ：用户问题 + 字段意图 ➔ MetadataSpec（仅保留当前问题相关的表/列）
能力：向量检索相关表列、生成切片后的元数据结构（Schema Slice）。
红线：禁止倾倒全域元数据；未覆盖的用户意图必须明确标出。

BizRulesAgent (业务规则专家)

身份：业务逻辑与计算规则精简压缩专家。
输入/输出 ：用户问题 + 表名摘要 ➔ BizRulesSpec
能力：业务术语/口径检索、相关性筛选及字符数上限压缩。
红线：不直接返回 Few-Shot SQL；不倾倒全库业务规则。

FewShotAgent (范例门禁)

身份：历史问答范例双阈值判定门禁。
输入/输出 ：用户问题 ➔ FewShotSpec（匹配模式 + 命中项）
能力：计算相似度得分；判定 REUSE_DIRECT（直接复用）、REFERENCE（参考）或 NONE（不使用）。
红线：未达阈值严禁直接运行；参考模式下不得引导模型全盘照抄。

MemoryAgent (记忆专家)

身份：上下文相关记忆切片提取器。
输入/输出 ：用户问题 ➔ MemorySpec
能力：历史记忆检索与关联度过滤。
红线：无强相关内容时返回空 Spec，严禁注入无关记忆信息。

SQLAgent (SQL 专家)

身份：分舱编写与执行 SQL 的专业代理（非直接复用模式下的主生成者）。
输入/输出 ：MetadataSpec + RulesSpec + FewShotSpec + MemorySpec ➔ SqlSpec / 运行结果
能力：SQL 编写、校验执行、搜索相似案例、交付解答。
红线：不自评执行完成；不跨舱读取未经剪裁的全量规则。

Evaluator (评估器)

身份：独立的质量门禁裁判。
输入/输出 ：中间产物 Spec + SQL 运行结果 ➔ EvalVerdict
能力：硬/软门禁检查、图探查校验、直接复用模式下的非时间谓词修改卡控。
红线：不参与 SQL 生成逻辑；强制检查项不可被跳过或忽略。

RenderAgent (渲染专家)

身份：对客最终结论输出与数据可视化渲染专家。
输入/输出：结果摘要 + 简明口径 ➔ 图表配置 / 对客响应消息
能力：生成可视化图表结构、格式化回答数据。
红线：无有效数据产出时不得虚假对客；不向对客提示词中注入全量 Schema 或范例原文。

4. 协调者六大角色矩阵

角色	实现方式	核心职责	不可越界（红线）
调度员	规则代码	生成执行计划（`ExecutionPlan`）、选择执行路径	严禁编写 SQL
澄清员	大语言模型（可选）	在领域或口径冲突时向用户发起确认	严禁提问非必要问题
审查员	规则代码 + 评估模块	校验阶段产出的结构完整性	严禁改写专家 Agent 生成的 SQL
门禁员	规则代码	强制执行门禁检查清单（Gate Checklist）	严禁跳过任何检查项
汇报员	系统日志 / 事件流	保持执行进度与路径模式的可观测性	严禁向用户编造未经验证的数据值
重试员	规则代码	依据故障等级执行重试、重新规划或终止	严禁无限制无限重试

5. 范例匹配策略

5.1 执行拓扑

text 复制代码

协调者制定计划 ──> [FewShot 优先判断]
                     ├── (高相似度) ──> 快速复用模式 (Fast Path) ──┐
                     └── (一般/无)  ──> 标准 SQL Agent 流程 ──────┼──> 评估器 (Evaluator 硬 Gate) ──> 渲染 Agent

5.2 问答范例双阈值匹配机制

相似度 sss	匹配模式 (Mode)	系统行为
s≥0.95s \ge 0.95s≥0.95	`REUSE_DIRECT`	仅做时间参数替换，直接执行范例 SQL；若同题存在多条 SQL，优先选择包含主维度与同比逻辑的 SQL
0.8≤s<0.950.8 \le s < 0.950.8≤s<0.95	`REFERENCE`	仅作为 LLM 编写 SQL 的提示参考
s<0.8s < 0.8s<0.8	`NONE`	不注入任何范例 SQL，走标准元数据检索

说明：向量数据库入库文本为 Q+A，检索时仅对问题 QQQ 进行 Embedding，同题密集的相似度得分常落在 0.7∼0.80.7 \sim 0.80.7∼0.8 区间。针对归一化字符级的精确同题做了 Exact Boost ，将其直接提至 REUSE 阈值，无需修改索引 Schema。

6. 上下文隔离与语义对齐 (Context)

6.1 上下文分舱管理

为了避免多轮对话和大量元数据导致提示词过长，采用分舱隔离策略：

CheckPoint 机制：每一轮次生成标准化结论摘要，仅将必要的上下文数据传递给下游 Agent。
渐进式规范注入：根据前置分类识别出的题型，按需向 SQL 生成舱动态注入特定规则。

6.2 业务语义对齐矩阵

当用户表述、业务口径与数据库真实字段命名存在差异时，按以下分层处理：

能力	核心职责
业务逻辑规则	承载稳定口径与计算/聚合约束，指导如何正确理解并生成查询
同义词库	连接用户说法与可检索的元数据用语，增强表/字段召回；不替代口径定义
问答范例	沉淀高频正确问法与 SQL 范式，高相似度时加速复用或提供参考
SQL 探查	校验时间范围、过滤取值等数据事实；不用于发现或改写业务语义

编排原则：

元数据检索：以用户原问为主，同义词仅作检索增强（追加相关用语），不以改写后的整句替代原问作为唯一检索条件。
二次补检索：业务规则命中且首轮元数据仍有未覆盖意图时，允许在写 SQL 前做一次轻量元数据补检索，并与首轮结果合并。
探查收敛：进入 SQL 执行阶段后不再重拉全量元数据，探查仅服务于已知表字段上的事实校验。

7. 质量门禁 (Gate) 机制

通过独立评估层（Evaluator）对中间产物进行强制卡控，模型无权绕过硬门禁：

检查点 (CheckPoint)	校验类型	说明
`plan_validity`	硬门禁	执行计划完整性与合法性校验
`metadata_sufficiency`	硬/软门禁	元数据覆盖度校验
`biz_rules_coverage`	软门禁	业务规则覆盖率提示
`reuse_semantic_gate`	硬门禁	直接复用模式下的主体维度、同比逻辑及规则一致性校验
`sql_executable`	硬门禁	SQL 语法及干运行 (Dry-run) 可执行校验
`render_readiness`	硬门禁	数据结果与渲染组件匹配度校验

8. 弹性编排与容错恢复 (Orchestration & Recovery)

8.1 弹性编排 (Orchestration)

Fast Path 降级 ：在 REUSE_DIRECT 模式下可跳过元数据和历史记忆拉取，直接加载业务规则；若直接执行失败，自动降级为标准全量检索流程。
单点调试能力：支持指定 Mode（如纯 SQL 生成模式、纯渲染模式）进行独立单点链路测试。

8.2 容错恢复 (Recovery)

状态快照：通过 Turn State Snapshot 记录当前轮次的完整状态机。
故障恢复矩阵：针对不同的 SQL 执行异常（如超时、字段不存在、语法错误），路由至不同的恢复策略（自动修复、轻量 Replan 或交互澄清）。

9. 自进化机制 (Evolution)

为实现系统能力的持续演进，构建了数据飞轮机制：

失败踩坑落库：当 Evaluator 判定 Replan 或 Abort 时，系统自动提取错误特征并生成失败记录（Pitfall Record），持久化至存储库。
动态避坑注入：SQL 生成 Agent 在启动时，会加载与当前场景相关的历史 Pitfall 摘要，避免重复犯错。
超级红线升级：经过高频触发且验证有效的避坑规则，可通过人工审核流程升格为系统最高优先级的全局"超级红线"。

10. 系统状态机

标准执行链路状态流转如下：

text 复制代码

[RECEIVED] ──> [PLANNING] ──> [CONTEXT_GATHERING] ──> [SQL_EXECUTING]
                                                             │
[COMPLETED] <── [RENDERING] <── [EVALUATING] <───────────────┘

11. 架构调整后的效果

通过以上方式修改，回答稳定性明显增强，并且模型啰嗦输出思考内容的情况也少了很多。