16 KiB
16 KiB
Current Chat Agent Data Contracts
状态：当前实现
日期：2026-07-07
范围：当前 Chat 复杂诊断链路的数据结构定义
当前代码实现是三 Agent 顺序链路：
chat_planner -> chat_executor -> chat_verifier
对应 ChatService.executeChatComplex(...) 中的 SequentialAgent。
1. Workflow Input
由 ChatService.buildWorkflowInput(...) 构造，传给 chat_workflow。
请按固定工作流完成本轮 Planner -> Executor -> Verifier。
--- 用户问题 ---
{question}
--- retry_context ---
{retry_context}
Verifier 完成后由外层代码读取 verifier_output 并决定最终用户输出。
| 字段 | 来源 | 定义 |
|---|---|---|
question |
用户输入 | 用户本轮原始问题 |
retry_context |
ChatService | 第二轮补证据约束；首轮为空 |
2. chat_planner
2.1 Input
chat_planner 的输入来自 workflow input 和 system prompt 追加上下文。
{
"question": "用户原始问题",
"history": [],
"available_knowledge_domains": "...",
"skill_catalog": {},
"retry_context": null
}
| 字段 | 来源 | 定义 |
|---|---|---|
question |
workflow input | 用户原始问题 |
history |
ChatService.buildChatPlannerAgent(...) |
对话历史，拼接到 planner system prompt |
available_knowledge_domains |
KnowledgeDomainService.buildKnowledgeMap() |
可用知识域地图，拼接到 planner system prompt |
skill_catalog |
PlannerSkillMetadataHook |
Planner 可见的 skill name/description 元数据 |
retry_context |
ChatService |
Verifier 低置信后构造的补证据上下文 |
2.2 Output：planner_plan
当前 prompt 要求输出 JSON：
{
"selected_skill": "匹配的 skill 名称；如果没有匹配则为 null",
"selection_reason": "选择该 skill 的原因；如果没有匹配则说明不使用 skill",
"plan": ["步骤1描述", "步骤2描述", "步骤3描述"],
"reasoning": "规划思路说明"
}
| 字段 | 类型 | 定义 |
|---|---|---|
selected_skill |
string/null | Planner 选择的诊断 skill 名称 |
selection_reason |
string | skill 选择理由 |
plan |
array | 给 Executor 的执行步骤 |
reasoning |
string | 规划思路说明 |
运行态输出 key：
planner_plan
3. chat_executor
3.1 Input
chat_executor 接收前序 planner_plan，并通过 system prompt 获得历史、skill 读取约束、retry 约束和工具权限。
{
"planner_plan": {},
"history": [],
"retry_context": null,
"tool_permissions": {
"method_tools": ["dateTimeTools", "lookupKnowledgeTool", "queryMetricsTools", "queryLogsTools"],
"tool_callbacks": []
}
}
| 字段 | 来源 | 定义 |
|---|---|---|
planner_plan |
chat_planner |
Planner 输出的计划 |
history |
ChatService.buildChatExecutorAgent(...) |
对话历史，拼接到 executor system prompt |
retry_context |
ChatService |
本轮补证据约束 |
method_tools |
ChatService.buildMethodToolsArray() |
Executor 可直接调用的本地工具 |
tool_callbacks |
ToolCallback[] |
框架发现或外部注入工具 |
read_skill |
SkillsAgentHook |
当存在 skillRegistry 时，Executor 可读取 Planner 选中的 skill |
3.2 Output：executor_feedback
当前 chat-executor-prompt.md 要求输出一个 JSON 对象，即 executor_evidence_v1。
{
"answer_version": "executor_evidence_v1",
"diagnosis_summary": "1-2句话总结，仅包含有证据支撑的事实和证据边界",
"claims": [
{
"claim_id": "claim-1",
"claim_type": "root_cause",
"claim_text": "事实断言或有限结论",
"support_level": "direct",
"evidence_bindings": [
{
"source_type": "tool_trace",
"source_id": "工具返回中的 evidence block id、trace_ref 或可定位标识",
"tool_name": "lookup_knowledge/query_logs/query_metrics/read_skill 等",
"source_invocation_ids": [],
"evidence_excerpt": "从工具返回中摘取的原话、指标值、日志片段或关键数据"
}
]
}
],
"hypotheses": [
{
"hypothesis_text": "未被证实但值得排查的方向",
"basis": "它基于哪些已知证据或为什么只是推测",
"needed_evidence": ["需要补充的证据"]
}
],
"recommended_actions": [
{
"action_text": "建议动作",
"reason": "为什么建议做这个动作",
"evidence_bindings": []
}
],
"missing_info": [
"导致无法确认完整根因的证据缺口"
],
"user_facing_answer": "面向用户的中文回答。必须与 claims/hypotheses/recommended_actions/missing_info 一致。"
}
| 字段 | 类型 | 定义 |
|---|---|---|
answer_version |
string | 当前固定为 executor_evidence_v1 |
diagnosis_summary |
string | 有证据边界的简短诊断摘要 |
claims |
array | 已证实或有明确间接支撑的事实断言 |
claims[].claim_id |
string | claim 标识 |
claims[].claim_type |
string | claim 类型，例如 root_cause、symptom、impact |
claims[].claim_text |
string | 事实断言文本 |
claims[].support_level |
string | direct 或 indirect |
claims[].evidence_bindings |
array | 支撑 claim 的证据绑定，不能为空 |
evidence_bindings[].source_type |
string | 证据来源类型，例如 tool_trace |
evidence_bindings[].source_id |
string | evidence block id、trace_ref 或其它定位标识 |
evidence_bindings[].tool_name |
string | 来源工具名 |
evidence_bindings[].source_invocation_ids |
array | 来源 tool_invocation.id |
evidence_bindings[].evidence_excerpt |
string | 工具返回中的原话、指标值、日志片段或关键数据 |
hypotheses |
array | 未证实但值得排查的方向 |
hypotheses[].hypothesis_text |
string | 假设文本 |
hypotheses[].basis |
string | 假设依据和未证实原因 |
hypotheses[].needed_evidence |
array | 确认该假设还需要的证据 |
recommended_actions |
array | 建议动作 |
recommended_actions[].action_text |
string | 建议动作文本 |
recommended_actions[].reason |
string | 建议原因 |
recommended_actions[].evidence_bindings |
array | 建议动作关联证据，可为空 |
missing_info |
array | 证据缺口 |
user_facing_answer |
string | 候选用户答案，PASS 时由 ChatService 提取输出 |
运行态输出 key：
executor_feedback
4. chat_verifier
4.1 Input
VerifierInputHook 会在 Verifier 调用前替换消息历史，构造显式 JSON payload。
{
"original_query": "用户原始问题",
"executor_final_answer": "{...executor_feedback raw text...}",
"executor_structured_output": {},
"executor_output_parse_status": {
"status": "valid",
"detail": "parsed executor evidence contract"
},
"tool_trace_summary": [],
"retry_context": null
}
| 字段 | 来源 | 定义 |
|---|---|---|
original_query |
VerifierContextHolder |
用户原始问题 |
executor_final_answer |
VerifierContextHolder 或上一条 AssistantMessage |
Executor 原始输出文本 |
executor_structured_output |
VerifierInputHook.parseExecutorOutput(...) |
Executor 输出可解析且包含 claims 时的 JSON 对象；否则为 null |
executor_output_parse_status.status |
VerifierInputHook |
valid / missing / malformed |
executor_output_parse_status.detail |
VerifierInputHook |
解析状态说明 |
tool_trace_summary |
ToolTraceSummaryService.buildVerifierTraceSummary(...) |
基于真实 tool_invocation 构建的证据索引 |
retry_context |
VerifierContextHolder |
当前补证据上下文 |
4.2 tool_trace_summary
ToolTraceSummaryService 聚合 evidence tools：
lookup_knowledge, query_logs, query_metrics, query_order
输出项结构：
{
"trace_ref": "trace-1",
"tool_name": "query_logs",
"success": true,
"input_summary": "query=payment-service timeout",
"output_summary": "log_evidence: ...",
"evidence_level": "direct",
"topic_domain": "general",
"source_invocation_ids": [394],
"invocation_count": 1,
"failed_invocation_count": 0,
"no_hit_invocation_count": 0,
"query_samples": ["payment-service timeout"],
"retrieval_layers": [],
"relevance_levels": [],
"source_documents": []
}
| 字段 | 类型 | 定义 |
|---|---|---|
trace_ref |
string | Verifier 可引用的证据摘要编号 |
tool_name |
string | 聚合后的工具名 |
success |
boolean | 是否存在可用证据 |
input_summary |
string | 工具输入摘要 |
output_summary |
string | 工具输出摘要 |
evidence_level |
string | direct / indirect / none |
topic_domain |
string | 主题域，优先来自 retrieval_details.retrieved_domains |
source_invocation_ids |
array | 聚合的 tool_invocation.id |
invocation_count |
number | 聚合调用次数 |
failed_invocation_count |
number | 失败调用次数 |
no_hit_invocation_count |
number | 无证据或去重调用次数 |
query_samples |
array | 查询样例 |
retrieval_layers |
array | 检索层级 |
relevance_levels |
array | 相关性等级 |
source_documents |
array | 来源文档标签 |
4.3 Output：verifier_output
当前 chat-verifier-prompt.md 要求输出：
{
"verdict": "PASS",
"groundedness_score": 0.8,
"critical_fact_count": 2,
"facts_checked": [
{
"fact": "ERR_TIMEOUT 表示请求超时",
"is_critical": true,
"verification": "direct_evidence",
"detail": "知识库文档明确给出该错误码定义",
"evidence_refs": [
{
"trace_ref": "trace-1",
"tool_name": "lookup_knowledge",
"topic_domain": "api",
"source_invocation_ids": [101, 104],
"note": "trace-1 的文档摘要直接给出错误码定义"
}
]
}
],
"rationale": "所有关键事实均有支撑，且至少一条具有直接证据"
}
| 字段 | 类型 | 定义 |
|---|---|---|
verdict |
string | PASS / LOW_CONFID / REJECT |
groundedness_score |
number | 关键事实证据支撑评分 |
critical_fact_count |
number | facts_checked 中 is_critical=true 的数量 |
facts_checked |
array | Verifier 校验过的事实列表 |
facts_checked[].fact |
string | 被校验事实 |
facts_checked[].is_critical |
boolean | 是否关键事实 |
facts_checked[].verification |
string | direct_evidence / indirect_support / no_evidence / contradicted |
facts_checked[].detail |
string | 校验说明 |
facts_checked[].evidence_refs |
array | 证据引用 |
evidence_refs[].trace_ref |
string | 引用的 tool_trace_summary.trace_ref |
evidence_refs[].tool_name |
string | 引用工具 |
evidence_refs[].topic_domain |
string | 引用主题域 |
evidence_refs[].source_invocation_ids |
array | 引用的 tool_invocation.id |
evidence_refs[].note |
string | 引用说明 |
rationale |
string | verdict 判定理由 |
运行态输出 key：
verifier_output
5. VerifierDecision
ChatService.parseVerifierDecision(...) 将 verifier_output 解析为内部 record：
{
"verdict": "LOW_CONFID",
"groundednessScore": 0.5,
"criticalFactCount": 2,
"factsChecked": [],
"rationale": "证据不足",
"round": 1
}
| 字段 | 类型 | 定义 |
|---|---|---|
verdict |
string | Verifier verdict |
groundednessScore |
number | groundedness score |
criticalFactCount |
number | 关键事实数量 |
factsChecked |
array | 解析后的 facts_checked |
rationale |
string | 判定理由 |
round |
number | 当前验证轮次 |
6. retry_context
当 LOW_CONFID 且满足重试条件时，ChatService.buildRetryContext(...) 构造：
{
"round": 1,
"missing_evidence_facts": [
"某关键事实：缺少直接证据"
],
"instruction": "仅补充以上断言相关证据，不要重复已完成检索"
}
| 字段 | 类型 | 定义 |
|---|---|---|
round |
number | 触发 retry 的轮次 |
missing_evidence_facts |
array | 来自 Verifier 的证据缺口 |
instruction |
string | 补证据约束 |
7. diagnosis_session.self_evaluation.verifier_evaluation
ChatService.persistVerifierEvaluation(...) 将 Verifier 结果合并进 diagnosis_session.self_evaluation。
{
"verifier_evaluation": {
"verdict": "LOW_CONFID",
"groundedness_score": 0.5,
"critical_fact_count": 2,
"facts_checked": [],
"rationale": "证据不足",
"round": 1,
"traceability_version": "v1",
"executor_output_parse_status": {
"status": "valid",
"detail": "parsed executor evidence contract"
},
"executor_structured_output": {},
"tool_trace_summary": []
}
}
| 字段 | 类型 | 定义 |
|---|---|---|
verifier_evaluation.verdict |
string | Verifier verdict |
verifier_evaluation.groundedness_score |
number | groundedness score |
verifier_evaluation.critical_fact_count |
number | 关键事实数量 |
verifier_evaluation.facts_checked |
array | 校验事实列表 |
verifier_evaluation.rationale |
string | 判定理由 |
verifier_evaluation.round |
number | 验证轮次 |
verifier_evaluation.traceability_version |
string | 当前固定为 v1 |
verifier_evaluation.executor_output_parse_status |
object | Executor 输出解析状态 |
verifier_evaluation.executor_structured_output |
object/null | 解析后的 Executor 结构化输出 |
verifier_evaluation.tool_trace_summary |
array | Verifier 使用的工具证据索引 |
8. Final Answer Rendering
ChatService 根据 Verifier verdict 决定最终 diagnosis_session.answer。
| Verdict | 当前行为 |
|---|---|
PASS |
优先提取 executor_feedback.user_facing_answer；提取失败则使用 executor 原文 |
LOW_CONFID |
输出低置信模板：已确认信息、当前缺口、建议下一步 |
REJECT |
输出降级模板：已确认信息、证据缺口、建议下一步 |
低置信模板使用：
以下结论基于当前已获取证据，仍存在部分证据缺口，请谨慎参考。
已确认信息：
- ...
当前缺口：
- ...
建议下一步：
- ...
拒绝模板使用：
当前无法基于已获取证据生成可靠结论。
已确认信息：
- ...
证据缺口：
- ...
建议下一步：
- ...
9. Trace Persistence Data
9.1 diagnosis_session
| 字段 | 类型 | 定义 |
|---|---|---|
session_id |
string | 会话 id |
query |
text | 用户问题 |
status |
string | 会话状态 |
agent_flow |
string | 当前 Chat 链路为 CHAT |
total_duration_ms |
number | 总耗时 |
total_token_count |
number | 总 token |
step_count |
number | agent step 数 |
tool_call_count |
number | tool invocation 数 |
answer |
longtext | 最终用户答案 |
self_evaluation |
json | 包含 verifier_evaluation |
feedback |
string | 用户反馈 |
9.2 agent_step
| 字段 | 类型 | 定义 |
|---|---|---|
session_id |
string | 会话 id |
step_index |
number | 步骤序号 |
agent_name |
string | planner / executor / verifier |
model_input |
text | 模型输入摘要 |
model_output |
text | 模型输出摘要 |
thought |
text | hook 记录的摘要信息 |
has_tool_call |
boolean | 是否包含工具调用 |
duration_ms |
number | 模型调用耗时 |
token_count |
number | token 数 |
9.3 tool_invocation
| 字段 | 类型 | 定义 |
|---|---|---|
id |
number | 工具调用 id |
session_id |
string | 会话 id |
step_id |
number | 对应 agent_step id |
tool_name |
string | 工具名 |
input_params |
json | 工具输入参数 |
output_preview |
text | 工具输出预览 |
output_length |
number | 原始输出长度 |
retrieval_layer |
string | 检索层 |
l0_match_count |
number | L0 命中数 |
l1_match_count |
number | L1 命中数 |
is_truncated |
boolean | 输出是否截断 |
relevance_level |
string | 相关性等级 |
dedup_reason |
string | 去重原因 |
retrieval_details |
json | 检索细节 |
duration_ms |
number | 工具耗时 |
success |
boolean | 是否成功 |
error_message |
text | 错误信息 |