Agent Harness 与知识工程的系统方法

01

任务应该被建模，而不只是被回答

来源：GraphPilot · Hovo · 观澜项目

真实系统里的用户请求通常会跨越多轮输入、附件、执行状态、日志、产物和后续追问。把任务显式建模，才能让系统知道“现在做到哪里、失败在哪里、可以从哪里继续”。

• GraphPilot 中是 session、message、task、timeline、artifact、snapshot。
• Hovo 中是 session、request、scenario run、node run、workpaper、business log。
• 观澜项目中是 SQL 计划、数据集、报告大纲和报告片段之间的证据链。

02

上下文选择比上下文堆叠更重要

来源：GraphPilot · Hovo · GraphRAG · relation-graph

上下文不是越多越好。系统需要根据任务类型、目标平台、附件、历史工作区、source task、示例目录和知识切片选择真正相关的材料。

• 减少无关资料挤占模型窗口。
• 降低 API、框架差异和业务规则上的幻觉。
• 让每次任务的知识来源可解释、可复查。

03

工具边界决定 Agent 能否进入真实系统

来源：GraphPilot · Hovo · 观澜项目

模型不能直接拥有任意 shell、文件系统或数据库能力。更稳妥的方式是让模型输出候选计划或结构化操作，由系统执行、校验和记录。

• 文件操作需要路径白名单、敏感文件保护和大小限制。
• 数据库查询需要只读约束、SQL 校验和错误修复边界。
• 业务工具需要输入输出 schema、权限控制和调用日志。

04

验证与修复应该是 Harness 的一部分

来源：GraphPilot · Hovo · 观澜项目

Agent 输出不能只靠“看起来合理”。代码生成、数据分析和报告生成都需要确定性检查，把错误反馈给局部修复流程。

• GraphPilot 中包含 static review、self-review、build repair 和 snapshot build。
• 观澜项目中 SQL、JSON Schema、报告结构和 HTML 片段都需要服务端校验。
• Hovo 中运行日志、业务日志、工作底稿和节点结果共同构成复核依据。

05

图应用不是图表，而是业务关系的操作界面

来源：relation-graph · GraphPilot

复杂关系数据不是静态图片。它需要布局、拖拽、缩放、展开、编辑、事件、小地图、详情面板和业务状态共同工作。

• 数据模型需要同时容纳图结构和业务对象。
• 组件核心能力要和框架适配层分离。
• AI 生成图应用时，需要把图数据契约、平台差异和交互规则写进知识资产。

06

知识工程要保留结构，而不是只做 embedding

来源：GraphRAG · relation-graph · GraphPilot

文档、示例和 API 说明如果只被切成文本块，很多结构会丢失。更可靠的方式是同时保留文档树、实体关系、语义向量和检索审计。

• 文档树保留层级和上下文位置。
• 实体关系帮助系统做图扩展和关联召回。
• 检索审计让回答依据可以被复查和改进。

07

复盘和 artifact 是系统继续进化的基础

来源：GraphPilot · Hovo · 观澜项目 · GraphRAG · A 股本地量化分析

没有运行过程、输入输出、错误、修复和产物记录，Agent 系统很难从真实任务中改进。artifact 不是附件堆积，而是下一轮评测、诊断和迭代的素材。

• 任务 replay 可以把真实问题转成可重复评测样本。
• 日志和诊断能定位模型、工具、上下文或数据源的问题。
• 业务结果和工作底稿让非技术角色也能参与复核。

08

让领域知识可复用、可验证：版本化领域知识包 + 按任务动态注入

来源：GraphPilot · relation-graph · Hovo

重点不是“有 Runtime Pack”，而是把 API 约束、常见错误、示例、负例、平台差异沉淀成版本化知识包；平台根据任务类型、技术栈、场景应用自动选择注入，并在任务快照里记录版本，便于复盘和评估。

• 领域知识从一次性提示词中抽离，变成可维护的系统资产。
• 任务执行时只注入匹配的知识包，避免无关规则干扰模型。
• 知识包版本进入任务快照，让失败分析能回到具体知识版本。

09

避免每次从零生成：把历史任务产物变成可定位的修改基线

来源：GraphPilot · 观澜项目

后续任务不再依赖“重新描述需求”，而是引用旧任务、旧 HTML、旧 SQL、旧数据集、旧产物编号，平台帮助模型定位修改范围，减少上下文漂移和重复生成。

• 历史产物成为可引用的上下文，而不是只能人工复制粘贴。
• 平台保存产物编号、任务编号和上一轮结果，支持局部续写。
• 修改请求围绕明确基线展开，降低重做和误改概率。

10

把模型输出变成可校验对象：Schema 契约 + 服务端验证 + 自动修复入口

来源：观澜项目 · Hovo · GraphRAG

重点不是“让模型输出 JSON”，而是让输出进入系统前必须满足字段、类型、ID、SQL 安全、数据绑定等规则；失败时把校验错误转成下一轮修复上下文。

• 模型输出先经过结构校验，再进入执行链路。
• 服务端负责检查安全边界、字段合法性和对象引用关系。
• 校验失败不是直接报错结束，而是生成可用于修复的错误上下文。

11

减少盲目重试：错误分类 + 最小上下文局部修复

来源：GraphPilot · 观澜项目 · Hovo

失败后不整段重做，而是根据 SQL 错误、构建错误、渲染错误、工具调用错误等类型，提取最小必要上下文，只修复失败部位。

• 不同错误类型进入不同修复路径，避免统一重试造成结果漂移。
• 修复上下文只包含失败片段、错误信息和必要约束。
• 局部修复结果再次进入确定性校验，形成闭环。

12

让结果天然可追踪：平台自动生成并存储执行链路证据

来源：观澜项目 · Hovo · GraphRAG

证据链不是人工整理的，而是平台在执行过程中自动记录 SQL、数据集、节点运行、知识召回、工具调用、产物 ID，并把它们和最终输出绑定。

• 执行过程中自动生成追踪数据，而不是事后补文档。
• 最终报告、回答或工作底稿可以反查到数据、工具和知识来源。
• 证据链同时服务于审计、调试、复核和后续迭代。

13

让不同场景生成自己的业务底稿：场景应用定义底稿结构，平台统一承载

来源：Hovo · 观澜项目

平台不规定所有应用都生成同一种报告，而是让不同场景应用定义自己的 workpaper 模板、字段、节点和产物结构，平台负责存储、审计、追踪和后续复用。

• 场景应用负责定义业务表达结构，平台负责生命周期和治理能力。
• 不同业务可以拥有不同字段、节点、模板和产物组织方式。
• 工作底稿既是输出结果，也是后续审查、续写和复用的业务对象。

14

解决用户问题表述不稳定：原始问题与归一化问题双路召回

来源：GraphRAG

用户问题可能口语化、缩写化、语义跳跃；系统同时使用原始问题和归一化问题检索，再合并结果，提高召回稳定性。

• 保留原始问题，避免归一化过程丢失用户真实意图。
• 生成归一化问题，补齐术语、对象和查询表达。
• 双路结果合并后再进入重排和上下文组装。

15

解决知识片段孤立：命中内容后自动补齐章节路径与父级上下文

来源：GraphRAG

向量命中的片段可能缺少语境，平台自动补充标题层级、父节点、章节路径，让模型知道这段知识处在什么结构里。

• 召回结果不只包含命中文本，还包含其所在文档路径。
• 父级章节提供定义范围、前提条件和上下文边界。
• 模型基于结构化语境回答，减少片段误读。

16

解决切块过碎导致的语义损失：按文档结构合并低信息密度片段

来源：GraphRAG

知识切分不是越细越好，过碎会让召回片段失去解释力；系统按标题树和内容密度合并节点，保留可回答问题的最小语义单元。

• 根据文档树判断片段是否具备独立语义。
• 低信息密度片段并入父级或相邻结构，避免孤立召回。
• 切块粒度服务于回答质量，而不是只服务于向量库写入。

17

降低 AI 生成的不确定性：把高质量示例变成可检索、可注入的产品资产

来源：relation-graph · GraphPilot

示例不是文档附属品，而是可分类、可检索、可投喂给 Agent 的知识资产，用来约束代码风格、API 使用和交互模式。

• 示例按场景、能力、框架和 API 进行分类，便于检索。
• Agent 生成时可以注入最相近示例，减少自由发挥。
• 高质量示例同时服务用户学习、文档解释和 AI 生成。

18

让系统能力可持续改进：把历史任务自动沉淀为回放与评估样本

来源：GraphPilot · Hovo · GraphRAG · A 股本地量化分析

平台把任务输入、上下文、工具调用、产物、错误、修复过程保存下来，之后可以用于回放、对比模型效果、发现系统性问题。

• 真实任务被沉淀为可重复执行的评估样本。
• 模型、提示词、知识包和工具策略的变化可以通过回放对比。
• 历史错误不只是日志，而是下一轮系统改进的输入。