feat(agent): add executor evidence v2 contract

2026-07-08 01:37:15 +08:00
parent a6afbfaa9d
commit 050cbc8fee
21 changed files with 2707 additions and 20 deletions
@@ -0,0 +1,514 @@
+# 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 | 错误信息 |