# 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 | 错误信息 |