515 lines
16 KiB
Markdown
515 lines
16 KiB
Markdown
# Current Chat Agent Data Contracts
|
||
|
||
**状态**：当前实现
|
||
**日期**：2026-07-07
|
||
**范围**：当前 Chat 复杂诊断链路的数据结构定义
|
||
|
||
当前代码实现是三 Agent 顺序链路：
|
||
|
||
```text
|
||
chat_planner -> chat_executor -> chat_verifier
|
||
```
|
||
|
||
对应 `ChatService.executeChatComplex(...)` 中的 `SequentialAgent`。
|
||
|
||
---
|
||
|
||
## 1. Workflow Input
|
||
|
||
由 `ChatService.buildWorkflowInput(...)` 构造，传给 `chat_workflow`。
|
||
|
||
```text
|
||
请按固定工作流完成本轮 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 追加上下文。
|
||
|
||
```json
|
||
{
|
||
"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：
|
||
|
||
```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：
|
||
|
||
```text
|
||
planner_plan
|
||
```
|
||
|
||
---
|
||
|
||
## 3. chat_executor
|
||
|
||
### 3.1 Input
|
||
|
||
`chat_executor` 接收前序 `planner_plan`，并通过 system prompt 获得历史、skill 读取约束、retry 约束和工具权限。
|
||
|
||
```json
|
||
{
|
||
"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`。
|
||
|
||
```json
|
||
{
|
||
"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：
|
||
|
||
```text
|
||
executor_feedback
|
||
```
|
||
|
||
---
|
||
|
||
## 4. chat_verifier
|
||
|
||
### 4.1 Input
|
||
|
||
`VerifierInputHook` 会在 Verifier 调用前替换消息历史，构造显式 JSON payload。
|
||
|
||
```json
|
||
{
|
||
"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：
|
||
|
||
```text
|
||
lookup_knowledge, query_logs, query_metrics, query_order
|
||
```
|
||
|
||
输出项结构：
|
||
|
||
```json
|
||
{
|
||
"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` 要求输出：
|
||
|
||
```json
|
||
{
|
||
"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：
|
||
|
||
```text
|
||
verifier_output
|
||
```
|
||
|
||
---
|
||
|
||
## 5. VerifierDecision
|
||
|
||
`ChatService.parseVerifierDecision(...)` 将 `verifier_output` 解析为内部 record：
|
||
|
||
```json
|
||
{
|
||
"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(...)` 构造：
|
||
|
||
```json
|
||
{
|
||
"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`。
|
||
|
||
```json
|
||
{
|
||
"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` | 输出降级模板：已确认信息、证据缺口、建议下一步 |
|
||
|
||
低置信模板使用：
|
||
|
||
```text
|
||
以下结论基于当前已获取证据，仍存在部分证据缺口，请谨慎参考。
|
||
|
||
已确认信息：
|
||
- ...
|
||
|
||
当前缺口：
|
||
- ...
|
||
|
||
建议下一步：
|
||
- ...
|
||
```
|
||
|
||
拒绝模板使用：
|
||
|
||
```text
|
||
当前无法基于已获取证据生成可靠结论。
|
||
|
||
已确认信息：
|
||
- ...
|
||
|
||
证据缺口：
|
||
- ...
|
||
|
||
建议下一步：
|
||
- ...
|
||
```
|
||
|
||
---
|
||
|
||
## 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 | 错误信息 |
|