83 lines
5.6 KiB
Markdown
83 lines
5.6 KiB
Markdown
# Chat Diagnosis StateGraph Real Nodes
|
||
|
||
## Why
|
||
|
||
阶段 1 已提供可编译的 StateGraph 骨架和 35 个 Fake Node 路由测试，但所有 action ports 仍是测试脚本，尚不能调用现有 ReactAgent、Executor Gatekeeper 或构造安全的 Verifier/Composer 输入。阶段 2 需要把现有 Agent 协议和确定性服务接到 Graph ports，同时保持 ChatService 生产入口仍走旧链路，避免把真实 Node 接入与生产切换混成一个不可回滚阶段。
|
||
|
||
## What Changes
|
||
|
||
- 新增 `DiagnosisAgentInvoker` 及 ReactAgent adapter，所有 Agent Node 显式传递 `RunnableConfig`。
|
||
- 新增 Planner、Executor、Verifier、Composer Node Adapters 和可注入失败分类器。
|
||
- 抽取 Executor/Verifier/Composer 共享解析组件，旧 Hook/ChatService 委托它们，避免复制协议逻辑。
|
||
- 新增显式 Gatekeeper Node，调用 `ExecutorGatekeeperService.validateRun` 并 fail-closed 标准化状态。
|
||
- 新增 Verified Input Builder，只投影 Gatekeeper passed bindings 对应的 claims 与 `matched_text` evidence。
|
||
- 新增 Evidence Gap Extractor / Retry Prepare Node，仅处理关键 `no_evidence` / `indirect_support` facts。
|
||
- 新增 Composer Safe Input Builder 和两类固定 Fallback Node 表达。
|
||
- 修正阶段 1 Router：evidence retry guard 必须要求关键 evidence gap。
|
||
- 新增 Node 契约和真实 CompiledGraph 集成测试，并保留旧 Sequential/Hook/Gatekeeper 回归。
|
||
|
||
本 change 不切换 ChatService 到 StateGraph，不修改 DB/Trace API，也不删除旧 Hook/Sequential 结构。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `chat-diagnosis-stategraph-real-nodes`：提供真实 Agent/Java Node adapters、可信输入投影、关键证据补查上下文和安全 Fallback。
|
||
|
||
### Modified Capabilities
|
||
|
||
- `chat-diagnosis-stategraph-routing-skeleton`：将 LOW_CONFID evidence retry guard 收紧为仅接受 `is_critical=true` 的 `no_evidence` 或 `indirect_support` facts，与阶段 0 冻结基线一致。
|
||
|
||
## Scope
|
||
|
||
### In Scope
|
||
|
||
- `com.superbiz.agent.graph.diagnosis` 下的 Agent adapters、Gatekeeper、Verified Input、Evidence Retry、Composer Input 和 Fallback。
|
||
- 可被旧 Hook/ChatService 与新 Nodes 共用的输出解析/安全渲染组件。
|
||
- 旧 Hook/ChatService 的行为保持型委托重构。
|
||
- `DiagnosisGraphRouter` 的 critical gap guard 修正。
|
||
- Node 单元测试、真实 CompiledGraph adapter tests、旧路径 focused regressions。
|
||
|
||
### Out of Scope
|
||
|
||
- 将 `ChatService.executeChatComplex` 替换为 Graph invocation。
|
||
- 修改 Agent 基础 Prompt 业务语义或输出协议。
|
||
- 移除 `VerifierInputHook` / `VerifierContextHolder` / SequentialAgent。
|
||
- Flyway、DiagnosisRun orchestration trace 字段、Trace DTO/API。
|
||
- 最终全量 Graph 测试体系替换。
|
||
- Maven E2E、`logs/` 和数据库核验。
|
||
|
||
## Context Constraints
|
||
|
||
- 阶段 0/1 archives 是执行基线；Node 不得改变条件边和计数所有权。
|
||
- Graph Verifier 只接收 `verified_executor_output`、`verified_evidence`、gatekeeper audit/ceiling、query 和 retry context，不接收完整 tool trace 或 Executor raw text。
|
||
- Gatekeeper validation 使用当前 `runId`，缺失/未知/异常一律 REJECT。
|
||
- Gatekeeper raw result 与 normalized status 分开保存。
|
||
- Verifier execution status、model verdict 和 effective verdict 分离；status 永远不写进 verdict。
|
||
- Planner/Verifier/Composer retry 输入由相同 state 白名单投影构造，技术 retry 不重跑前序节点。
|
||
- Executor 不重试；合法 no-evidence 仍为 COMPLETED。
|
||
- Evidence Retry Context 保留 prior verified output/evidence、关键 gaps、completed query refs 和固定约束；Java 不合并 claim 文本。
|
||
- 旧 Sequential path 在阶段 3 前继续工作；共享解析器重构必须通过旧 focused tests。
|
||
- 本阶段不修改 `/api/chat`、DB 或当前运行路由。
|
||
|
||
## Acceptance
|
||
|
||
- ReactAgent invoker 透传输入与 RunnableConfig，现有 Agent Hook/ToolCallback 可继续工作。
|
||
- Planner 合法 JSON 为 COMPLETED；非法 JSON/结构为 INVALID_OUTPUT；临时失败与不可重试失败分开。
|
||
- Executor 合法 `executor_evidence_v2`（包括 no-evidence）为 COMPLETED；非法结构、工具阻断、其他失败正确映射且不重试。
|
||
- Gatekeeper Node 每轮只调用一次 `validateRun`，unknown/error fail closed。
|
||
- PASS 与可继续 LOW_CONFID 都经过 Verified Input Builder；失败 binding、未引用工具结果和 raw Executor text 不进入 Verifier。
|
||
- Verifier input 只有白名单字段；输出分离 status/model/effective verdict，ceiling 正确限制 PASS。
|
||
- Verifier/Composer technical retry 使用相同序列化输入。
|
||
- Evidence retry 只从关键 gap 生成，包含 prior verified data/completed refs/约束，最多一次。
|
||
- 第二轮 Executor 输入明确要求增量查询和完整 `executor_evidence_v2` 快照，不由 Java 合并 claims。
|
||
- Pre-verification Fallback 不输出 Executor claim；post-verification Composer fallback 只使用 allowed material。
|
||
- 新 Node/Graph tests 和旧路径 focused regressions 通过；不运行 Maven E2E。
|
||
|
||
## Risks
|
||
|
||
- 共享解析器抽取可能改变旧 Sequential 行为；旧 ChatService/Hook tests 必须同批通过。
|
||
- Gatekeeper checked binding 与 claim binding 关联错误可能泄漏失败 evidence；使用 claim_id + invocation/tool/path 精确匹配并测试 mixed binding。
|
||
- 异常分类依赖 cause/message；未知异常默认不可重试或 FAILED，安全优先。
|
||
- Prompt 当前仍描述旧 Hook payload；本阶段只验证 Node input contract，阶段 3 在生产切换时同步 Verifier Prompt 输入说明，避免旧生产路径提前不兼容。
|