# SuperBizAgent ISS-014 交接文档

## 当前上下文

- 分支：`refactor/chat-single-react-harness`
- 任务：停止端到端验证，提交当前代码，更新 ISS-014，并交接后续开发。
- 本轮没有继续启动服务或发送真实请求；9900 端口确认没有监听进程。
- 工作区仍包含用户已有的文档、技能和演示输出改动；提交时只纳入 ISS-014 实现相关文件。

## 本次已完成

1. 新增独立追加式 `diagnosis_trace_event` 审计表和记录器，覆盖 Run、Routing、Agent、Tool、Evidence、Semantic、Release 生命周期事件。
2. Knowledge Query 使用 `BeanOutputConverter<KnowledgeAnswerDraft>` 注入实际 JSON Schema，修复缺少 Schema 导致的 `Knowledge answer is invalid`。
3. Fallback 增加 `failure_stage`、`observed_facts`、`validation_issues`，为失败提供可操作的阶段、事实和校验信息，同时不暴露 Prompt、原始 Draft 或 Tool 载荷。
4. 新增 `agent_reasoning_audit` 表、Repository、Hook 持久化和专用查询接口。只保存模型供应商实际返回的 reasoning 元数据，长度上限 32000 字符；普通 Trace 只展示是否存在及字节数，不返回原文。
5. ISS-014 已更新，记录上述实现、成功用例、协议边界变化和后续工作。

## 已知验证结果

- Diagnosis 成功：`mvp-demo-success-e2e-20260722-2032` / `e72d9c7b-2f78-44c8-9086-f2e9d6987f24`，SUCCESS，8455 tokens，1 次 Tool 调用。
- Knowledge Query 成功：`mvp-demo-order-timeout-fixed-20260723` / `2b704d1b-8f11-40ee-a4c6-5e5e04d3847c`，SUCCESS，1998 tokens。
- 已通过的重点测试：`HarnessAgentAuditHookTest`、`DiagnosisReleaseUseCaseTest`、`DiagnosisTraceServiceTest`、`HarnessContractTest`、`HarnessChatConfigurationTest`、`ApplicationExecutorsTest`、`ChatApplicationUseCaseTest`、`JpaToolInvocationAuditSinkTest`、`JpaDiagnosisTraceRecorderTest`，以及编译和 `git diff --check`。
- V015 真实数据库迁移、reasoning endpoint 的真实数据库/E2E 尚未验证。

## 后续实现顺序

1. 为 Diagnosis Agent 增加硬停止策略：限制证据轮次、阻止重复 `lookup_knowledge`，在预算耗尽前强制输出最终 Draft。
2. 给 Evidence Repair 注入真实 `DiagnosisDraft` Schema，消除运行时 `PARSE_ERROR`。
3. 使用真实 Provider 验证 reasoning metadata；无 reasoning 时也要写入 `reasoning_available=false` 的审计记录。
4. 在受控环境验证 V015 迁移和 reasoning 查询接口，并用精确 `sessionId + runId` 对齐数据。
5. 评估 reasoning 审计表的访问控制、保留期限和加密策略。
6. 继续细化工具成功但无法构造 verified snapshot 时的 fallback 事实和校验问题。

## 重要约束

- 不恢复完整端到端验证，除非用户明确要求。
- 不把 reasoning 审计内容当作事实证据，也不加入普通 SSE、Trace 或业务结果。
- 不提交无关用户文件、演示输出、环境配置和凭据。
- ISS-014 的后续阶段仍按独立 sm-flow/OpenSpec、归档、提交后再进入下一阶段。

## 建议技能

- `diagnose`：继续处理 Agent 重复工具调用、预算耗尽和 Evidence Repair 解析失败。
- `sm-flow`：开始下一阶段实现时按 OpenSpec-first 流程执行和归档。
- `gitnexus-debugging`：定位 Agent 停止条件和跨 Harness 调用链问题。
- `gitnexus-impact-analysis`：编辑共享 Harness/Agent 方法前评估调用影响。

## 关键文件

- Issue：`mvp/issues/active/ISS-014-single-react-agent-harness-aci-ptk-refactor.md`
- Trace：`src/main/java/com/superbiz/agent/harness/audit/`、`src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java`
- Reasoning：`src/main/java/com/superbiz/agent/domain/entity/AgentReasoningAudit.java`、`src/main/java/com/superbiz/agent/harness/audit/HarnessAgentAuditHook.java`、`src/main/resources/db/migration/V015__create_agent_reasoning_audit.sql`
- Fallback：`src/main/java/com/superbiz/agent/harness/release/SafeFallbackFactory.java`
- Knowledge：`src/main/java/com/superbiz/agent/harness/application/executor/KnowledgeQueryExecutor.java`