136 lines
11 KiB
Markdown
136 lines
11 KiB
Markdown
## Context
|
||
|
||
复杂 Chat 的公开调用链为 `ChatController -> ChatService.executeChatWithStrategy -> executeChatComplex`。阶段 2 已提供真实 Node adapters、显式 Gatekeeper、verified input、evidence retry、Composer/Fallback 和 `DiagnosisGraphFactory`，但 `executeChatComplex` 仍维护 SequentialAgent 两轮循环、VerifierInputHook/ThreadLocal 状态和私有 Composer 调用。阶段 3 要在不改变 `/api/chat` 的前提下切换唯一生产编排，并增加 Run 级 orchestration trace 数据契约。
|
||
|
||
当前 Run 通过 `SessionContextHolder(sessionId, runId)` 绑定 AgentStep/ToolInvocation；DiagnosisRun 使用字符串 JSON 保存 self evaluation；TraceService 将 Run 映射为 `run` 和兼容 `session` 投影。`DiagnosisOrchestrationTraceBuilder` 已能从有界 events 生成无 Prompt/raw output 的摘要。数据库由 Flyway 管理且 Hibernate 使用 validate，因此实体、V012 migration 和 Trace 映射必须同批对齐。
|
||
|
||
本 change 是 L4：内部状态机从固定顺序改为条件图，Trace run 对象和 DB 增加字段。`/api/chat`、sessionId/runId、Agent 输出协议保持兼容。用户已冻结单轨切换、安全 Fallback=SUCCESS、只有未处理失败=FAILED、阶段 5 才 live E2E。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- 让复杂 Chat 一次执行真实 CompiledGraph，删除 ChatService 的细粒度 Sequential/round 状态机。
|
||
- 保持现有 Agent prompt/tool/skill/logging 组装能力，但 Graph Verifier 不注册 VerifierInputHook。
|
||
- 用 runId 同时作为 Graph threadId 和 Run 审计边界，用 sessionId/runId metadata 维持 AgentStep/ToolInvocation 归属。
|
||
- 将 final state 显式映射为 answer、verifier evaluation、composer audit、orchestration trace 和 Run lifecycle。
|
||
- 在正常/handled fallback 路径持久化非空、紧凑、安全的 orchestration trace，并只在 Trace `run` 对象暴露解析结果。
|
||
- 更新 Verifier Prompt/self-evaluation 到 verified-only 数据模型。
|
||
- 用阶段 3 focused tests证明生产 cutover、Run/Trace/API/Prompt 边界，且不留下已知失败测试。
|
||
|
||
**Non-Goals:**
|
||
|
||
- 不改简单 Chat/AIOps 编排。
|
||
- 不删除 VerifierInputHook/VerifierContextHolder 类型；它们在阶段 5 清理，但复杂 Chat 不再引用。
|
||
- 不增加持久 Graph checkpoint、恢复、并行分支或新 Run status。
|
||
- 不回填历史 run，不给历史 null orchestration trace 设计兼容伪值。
|
||
- 不在本阶段全面重命名/收敛测试夹具；阶段 4 完成测试体系替换。
|
||
- 不运行 Maven live E2E、日志或数据库验收。
|
||
|
||
## Decisions
|
||
|
||
### 1. 单轨生产 cutover，不增加 feature flag
|
||
|
||
`executeChatComplex` 只构造当前 Run、RunnableConfig 和 diagnosis context，然后调用真实 Graph runtime。旧 SequentialAgent loop、score/feature-flag retry 和 ChatService 私有 Verifier/Composer 路由方法从生产类移除；不保留双运行、shadow compare 或 runtime fallback 到 Sequential。
|
||
|
||
选择单轨而不是 feature flag，因为用户冻结的阶段门禁已经提供 Git commit 回滚边界，双轨会继续维护两套重试、Gatekeeper 和安全材料真理源。数据库新列 nullable，因此代码回滚时列可保留，无需破坏性 migration down。
|
||
|
||
### 2. Agent builder 只迁移职责，不复制实现
|
||
|
||
新增专用复杂 Chat Graph runtime/factory，复用当前 Planner/Executor/Verifier/Composer Prompt、knowledge map、history、method tools、ToolCallbacks、skill hooks 和 AgentLoggingHook 组装规则。ChatService 只向它提供本次 ChatModel、callbacks、history 和 Run 上下文。Graph Verifier hooks 只有 AgentLoggingHook，不包含 VerifierInputHook；Gatekeeper 只由显式 Node 调用。
|
||
|
||
如果为控制改动风险暂时保留简单 Chat 的工具/Hook builder，复杂 Agent builder 仍只存在一份。不得在 Graph Node 或 runtime 内复制 prompt 文本或第二套 tool catalog。
|
||
|
||
### 3. Graph 初始 state 和 RunnableConfig 使用最小白名单
|
||
|
||
初始 state 包含：
|
||
|
||
- `diagnosis_context={query, original_query}`；不把完整 history 放入 Graph State，history 仅注入 Planner/Executor system prompt。
|
||
- `planner_mode=NORMAL`。
|
||
- planner/verifier/composer/evidence retry count 全部为 0。
|
||
- `orchestration_events` 初始为空。
|
||
|
||
RunnableConfig 使用 `threadId(runId)`，metadata 包含 `sessionId` 和 `runId`。这同时满足 Graph 隔离、AgentLoggingHook/ToolCallback 的 Run ownership 和 Gatekeeper current-run validation。
|
||
|
||
### 4. 流式执行捕获最后真实 state
|
||
|
||
Graph runtime 使用 `CompiledGraph.stream(initialState, config)` 顺序消费 NodeOutput，并保存最后一个真实 `OverAllState`。正常 END 以最后 state 的非空 `final_answer` 为成功条件。流式消费与原同步 invoke 一样在当前请求线程阻塞，但允许在未处理异常时取得已真实产生的 partial state。
|
||
|
||
若异常前已有 events，failure handler 可以 best-effort 构造/persist partial trace；若没有 event，不生成虚假 node/transition。Agent invocation failures已经由 adapters 转为显式 status，正常预期失败都应走 Graph Fallback 而不是抛出。
|
||
|
||
### 5. Graph result mapper 是唯一运行结果翻译层
|
||
|
||
新增显式 mapper 从 final/partial state读取：
|
||
|
||
- `final_answer`。
|
||
- Verifier status/model/effective verdict、score、claim/fact checks、rationale、round。
|
||
- Gatekeeper raw audit、verified Executor output/evidence。
|
||
- Composer audit。
|
||
- `DiagnosisOrchestrationTraceBuilder` 结果。
|
||
|
||
ChatService 不再读取 VerifierContextHolder。self-evaluation 继续写 `verifier_evaluation` container 以兼容 Trace/Eval 消费者，但数据来自 Graph State：`executor_structured_output` 只保存 verified projection；新增 `verified_evidence` 和显式 statuses；不保存 raw Executor 或完整 tool_trace_summary。若 Verifier 从未完成，evaluation 只记录可用 status/audit/prompt 信息，不伪造 verdict。
|
||
|
||
### 6. Run lifecycle 和持久化顺序按执行结果分离
|
||
|
||
成功路径：Graph 返回非空安全 answer -> 构造 trace/evaluation -> 设置 Run SUCCESS、answer、orchestrationTrace、duration/metrics -> 保存 -> 调用 `evaluateRun`。
|
||
|
||
handled Fallback 与 Composer 正常路径使用相同成功顺序；可信度由 effective verdict 或 trace degraded 表达。失败路径：未处理异常、final state/answer 缺失、trace invariant 失败或成功结果持久化失败 -> Run FAILED，保存错误答案、duration、已有可构造 partial trace 和 metrics；不调用 success Eval。若 failure save 本身失败，只记录明确 error，不能声称持久化成功。
|
||
|
||
### 7. Orchestration trace 是独立 nullable JSON 数据契约
|
||
|
||
新增 V012，仅执行：
|
||
|
||
`ALTER TABLE diagnosis_run ADD COLUMN orchestration_trace JSON NULL ... AFTER self_evaluation`。
|
||
|
||
DiagnosisRun 使用 `@JdbcTypeCode(SqlTypes.JSON)` + `String orchestrationTrace`，与 selfEvaluation 写法一致。nullable 只服务无回填 migration/历史 run；每个成功的新 StateGraph Chat run 应用层必须非空。序列化使用 `DiagnosisOrchestrationTrace.toMap()`，字段保持 snake_case JSON。
|
||
|
||
### 8. Trace API 只在 RunTrace 增加解析对象
|
||
|
||
`DiagnosisTraceResponse.RunTrace` 新增 `Map<String,Object> orchestrationTrace`。DiagnosisTraceService 从 `DiagnosisRun.orchestrationTrace` 解析后映射；顶层 response、ChatSessionTrace、兼容 SessionTrace 和 raw string 均不新增字段。Run list 也不扩展该字段。
|
||
|
||
历史/AIOps run 的 null 值原样返回 null，不进行 fallback synthesis。解析非法 JSON 时 fail closed 为 null，并由数据/测试暴露问题；本阶段不增加历史兼容分支。
|
||
|
||
### 9. Verifier Prompt 与 verified-only input 对齐
|
||
|
||
`chat-verifier-prompt.md` 输入改为：`diagnosis_context`、`verified_executor_output`、`verified_evidence`、`gatekeeper_audit`、`verdict_ceiling`、可选 `retry_context`。删除 `executor_final_answer`、完整 `tool_trace_summary`、Hook parse status 和“再次执行 Gatekeeper”语义。
|
||
|
||
Verifier 仍输出原 JSON contract。`evidence_refs` 通过 claim_id/source_invocation_id/tool_name/raw_path 对 verified_evidence 建立审计关联，不要求不可用的 tool_trace_summary.trace_ref。Prompt audit catalog/version 随输入契约升级并在所有 handled paths 持久化。
|
||
|
||
### 10. 测试分阶段但不允许已知失败
|
||
|
||
阶段 3 新增最小生产 cutover测试：Graph runtime/final mapping、threadId/metadata、SUCCESS/Fallback/FAILED lifecycle、trace storage/API location、Prompt forbidden fields、no Verifier step on pre-verification failure。运行相关 Graph/Trace/Controller/Eval 回归和 test compilation。
|
||
|
||
旧 `ChatServiceSequentialAgentTest` 若因单轨语义失效，阶段 3 必须删除/改写冲突断言或由 focused Graph integration 替代，不能留到阶段 4 才让测试恢复绿色。阶段 4 继续完成命名、夹具、分支矩阵和旧 Hook tests 的全面清理。
|
||
|
||
## Interface Impact
|
||
|
||
- 等级：L4。
|
||
- 外部兼容：`/api/chat` request/response 与 run identity 不变。
|
||
- 加法协议：Trace `run.orchestrationTrace`；DB `diagnosis_run.orchestration_trace`。
|
||
- 内部行为：Executor/Planner/Gatekeeper failure 可提前 Fallback，不再保证固定 Agent 顺序；score flag 不再控制 LOW_CONFID retry。
|
||
- 消费者：Trace UI/demo/eval 可读取新 run 字段但不强制历史值；阶段 5 demo script 才增加最终 E2E 断言。
|
||
- 回滚：revert 本阶段代码/Prompt/spec；保留 nullable DB 列。无双轨开关、无数据回填回滚。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- [流式 API 与同步 invoke 的终止语义不同] → focused test断言最后 state、END、事件顺序和异常 partial state；不依赖实现私有字段。
|
||
- [self-evaluation 字段变化影响 Eval fixture] → 保留 container、verdict/claim/fact/gatekeeper/composer/prompt audit 兼容键；新增 verified 字段，移除不安全 full summary 前同步 specs/tests。
|
||
- [Agent factory 移动破坏 skill/tool hooks] → 复用现有 buildHooks/buildMethodTools 规则，并断言 Planner/Executor/Verifier/Composer hooks和当前 Run metadata。
|
||
- [JSON 字段三层漂移] → V012、entity、DTO/service 和 tests同批提交；Maven test compilation + strict specs。
|
||
- [无法取得 partial state] → 不伪造 trace；标记 FAILED 并记录明确原因。预期 Agent failures 全部由 Node adapters handled。
|
||
- [阶段 3/4 测试边界重叠] → 阶段 3只保证 cutover 可验收且现有 suite 不红；阶段 4负责全面测试架构替换。
|
||
|
||
## Migration Plan
|
||
|
||
1. 先加 V012、entity/Trace DTO/service 与 isolated mapping tests。
|
||
2. 实现 Graph runtime/result mapper和 Prompt verified-only 更新，先用 fake agents验证 final/partial state。
|
||
3. 将 `executeChatComplex` 单轨切换并删除旧私有 Sequential 状态机逻辑，保留 Run、metrics、Eval和简单 Chat路径。
|
||
4. 运行 production cutover、Graph、Trace、Controller/Eval 回归与 test compilation；证明 DB schema diff 只有一个字段。
|
||
5. 归档、提交阶段 3；阶段 4 再全面替换测试体系。
|
||
|
||
部署时 Flyway 先加 nullable 列，随后新代码写入。回滚为 Git revert；旧代码忽略新增列，数据库不删除列。
|
||
|
||
## Open Questions
|
||
|
||
无。所有产品/协议边界均由 ISS-011 与用户确认冻结；实现期若发现 Graph API 无法提供真实 partial state，只能回写本 design/tasks 后使用不伪造的 FAILED 处理，不能扩大协议。
|