feat(harness): add single diagnosis react agent

2026-07-21 22:29:49 +08:00
parent 85029d96a7
commit 2362665519
30 changed files with 1711 additions and 2 deletions
@@ -0,0 +1,31 @@
+## Why
+
+阶段 2-3C 已建立显式 RunContext、预算、canonical Tool invocation 和三类有界 evidence Tool，但还没有使用这些边界的诊断执行者。需要在不影响公开 Chat 的前提下建立单一 Diagnosis ReAct Agent，证明框架原生 tool loop、冻结的 DiagnosisDraft 和 Harness 控制能够闭环，再进入阶段 5 的释放门禁。
+
+## What Changes
+
+- 新增唯一的 Diagnosis Agent Prompt，把诊断规划、证据查询、证据充分性判断和报告草稿生成合并到一个 ReactAgent。
+- 新增独立内部 Diagnosis 用例，显式接收 RunContext、当前原始 Query 和可选的固定 PreviousTurn，不读取完整 Session 历史。
+- 通过 Spring AI Alibaba 的 ModelInterceptor 和 ToolInterceptor 接入 Harness；使用框架原生 ReAct/tool loop 和原始 tool_call_id，不手写循环或第二套调用 ID。
+- 将 lookup_knowledge、query_logs 和 query_mysql 的冻结 Tool 定义连接到阶段 3B/3C adapter，只向 Agent 返回有界 agent_result。
+- 使用 DiagnosisDraft 作为结构化输出契约，并对输入上下文、模型轮次、Token、Tool 调用和输出字节执行确定性预算。
+- 允许注入现有 AgentStep Hook，Run 审计继续由 RunContext/lifecycle 承载，ToolInvocation 审计继续由 canonical Tool boundary 承载。
+- 证据不足时要求 Agent 输出 conclusion=null、明确 limitations 并结束当前 ReAct 执行，不自动重跑 Diagnosis Agent、模型调用或 Tool 调用。
+- 不修改 ChatController、公开 /api/chat 或 /api/chat_stream，不删除旧 Planner/Executor/Verifier/Composer 链路。
+
+## Capabilities
+
+### New Capabilities
+
+- `single-react-diagnosis-agent`: 定义单一 Diagnosis ReactAgent 的内部输入、Harness-controlled ReAct/tool loop、结构化 Draft、预算、无证据停止和审计边界。
+
+### Modified Capabilities
+
+- None. 既有 Harness、Tool 和公开 Chat capability 的需求语义不在本阶段改变。
+
+## Impact
+
+- 新增 `com.superbiz.agent.harness.agent` 内部包、一个 classpath Prompt 和 focused Agent/tool-loop tests。
+- 复用 `DiagnosisHarnessCore`、`RunContext`、`DiagnosisDraft`、`PreviousTurn`、`AgentToolContracts`、三类 Tool adapter 和 Spring AI Alibaba ReactAgent/interceptor API。
+- 内部接口影响为 L2：新增可供阶段 6A 调用的内部用例与工厂；现有公开 Controller、SSE、DTO、数据库契约和旧 ChatService 行为保持不变。
+- 主要风险是框架结构化输出只提供格式提示而不负责 Java 反序列化，以及 Tool Callback 本身拿不到框架调用 ID；实现必须分别用严格 ObjectMapper 解析和 ToolInterceptor 解决，失败时 fail closed。