# ISS-015 诊断运行质量与 Reasoning 审计收敛

**状态**：部分实施
**严重程度**：高
**发现时间**：2026-07-23
**更新日期**：2026-07-27
**来源**：ISS-014 阶段 7 及后续真实 E2E 验证
**关联**：ISS-014、ISS-016、ISS-004、executor-evidence-attribution-hallucination

---

## 1. 背景

ISS-014 已完成单体 Diagnosis ReAct Agent、Harness、ACI Tool、EvidenceGuard、SemanticGuard、SSE 和旧架构清理，并通过阶段 7 E2E 以及后续 Diagnosis/Knowledge Query 成功用例验证主链路。真实 E2E 同时暴露了新的运行质量问题：Agent 可能重复检索直至预算耗尽，Evidence Repair 可能因输出 Schema 不完整而解析失败，Reasoning 审计能力尚未完成真实 Provider 和数据库验证，安全 Fallback 在部分失败路径下仍缺少足够信息。

这些问题发生在 ISS-014 架构切换和验收之后，不重新打开 ISS-014，也不改变已经冻结的单体 Agent/Harness/ACI 架构。本 Issue 作为后续唯一追踪入口。

## 2. 用户体验问题

### 2.1 审计需要保留 Agent 思考记录

用户需要在后续审计中查看 Agent 的思考过程，确认它为什么选择某个 Tool、如何从观察结果继续行动以及在哪个阶段停止。该记录必须是独立的审计数据，不能混入业务事实、Evidence Snapshot、普通 Trace 或 SSE，也不能把未由 Provider 返回的内容伪造成思考记录。

### 2.2 失败结果不能只给空泛结论

当前失败路径可能直接返回“当前证据无法完成真实性校验，无法确认根因”。这虽然避免了无依据结论，但没有告诉用户已经观察到什么、校验在哪个阶段失败、缺少哪些信息以及下一步可以怎么查，导致用户无法判断系统是否真的执行过有效排查。

Fallback 必须在不暴露 Prompt、原始 Draft、原始 Tool 载荷和内部异常的前提下，提供有界的 `failure_stage`、`observed_facts`、`validation_issues`、查询范围、已完成的 Tool/证据阶段和可执行的 `next_steps`。

## 3. 已有验证基线

- Diagnosis 成功：`sessionId=mvp-demo-success-e2e-20260722-2032`，`runId=e72d9c7b-2f78-44c8-9086-f2e9d6987f24`，`release_outcome=SUCCESS`，总 Token 8455，Tool 调用 1 次。
- Knowledge Query 成功：`sessionId=mvp-demo-order-timeout-fixed-20260723`，`runId=2b704d1b-8f11-40ee-a4c6-5e5e04d3847c`，`release_outcome=SUCCESS`，总 Token 1998。
- 失败会话 `session_ud9pzde7r_1784785531138` 暴露两类问题：Evidence Repair `PARSE_ERROR`；Diagnosis Agent 重复调用 `lookup_knowledge`，最终在 12 次 Tool 调用、45087 Token 后进入 `BUDGET_EXHAUSTED`。
- `diagnosis_trace_event`、信息化 Fallback、`agent_reasoning_audit` 和 reasoning 查询接口已经实现并通过 focused tests；真实 Provider/V015 验证仍属于本 Issue。

### 3.1 当前实施进度（2026-07-27）

| 阶段 | 状态 | 已完成 | 剩余缺口 |
|---|---|---|---|
| 阶段 1：Diagnosis Agent 硬停止策略 | 已完成 | ISS-016 已实现 Tool Scope 归一化与去重、`GAINED/NO_GAIN` 信息增益、连续 `NO_GAIN` 饱和停止、连续协议错误 `PROGRESS_PROTOCOL_VIOLATED` 受控停止、可修正协议 observation、受控 Fallback、回归测试和真实 E2E | 无；阶段 1 停止策略已收口 |
| 阶段 2：Evidence Repair Schema | 未完成 | Repair 仍保持无 Tool、有限重试、失败后安全降级；Diagnosis Agent 最终输出已使用真实 `DiagnosisDraft` Schema | Evidence Repair 自身尚未注入真实 `DiagnosisDraft` JSON Schema，仍主要依赖 Prompt 文本约束和严格解析 |
| 阶段 3：Reasoning 审计验证与治理 | 大部分完成 | V015–V017；`reasoning_content` + `assistant_text` + `content_source`；Hook 优先读 `DeepSeekAssistantMessage.getReasoningContent()`；受限查询返回双字段；`sessionId + runId` 归属校验；2026-07-28 DeepSeek live E2E 两步均 `reasoning_available=true` 且双字段非空；V016 `diagnosis_run.conclusion` | 访问控制、保留期限、加密；非 DeepSeek Provider 回归；reasoning unavailable 专项场景归档 |
| 阶段 4：Fallback 信息质量与最终 E2E | 大部分完成 | 已实现有界 `observed_facts`、`validation_issues`、证据范围/缺口和差异化 Fallback；已完成 Diagnosis SUCCESS、信息不足 FALLBACK、Trace/Tool/Token 对账 E2E；SUCCESS 路径已跨表核验 reasoning 双字段与 run.conclusion | reasoning unavailable 场景归档；全部失败路径仍需最终综合验收 |

本表是当前进度事实，下面各阶段条目仍保留为完整目标。ISS-016 完成的是阶段 1 和阶段 4 的主体能力，并新增模型 Token 与 Tool 拒绝审计；它不替代阶段 2 的 Repair Schema，也不代表阶段 3 的 Reasoning 治理已经完成。

## 4. 目标

1. Agent 在证据轮次或单 Tool 预算接近上限时停止继续检索，并生成当前证据允许的最终 Draft。
2. Evidence Repair 使用真实 `DiagnosisDraft` JSON Schema，消除结构修复阶段的 `PARSE_ERROR`。
3. Reasoning 审计在真实 Provider 返回和不返回 reasoning 的两种情况下都有明确、可查询的审计结果。
4. Reasoning 原文保持独立受限存储，不进入普通 SSE、Trace、证据快照或业务结果。
5. Fallback 在不泄露 Prompt、Draft 和原始 Tool 数据的前提下，说明失败阶段、已观察事实和校验问题。
6. 用户在失败时至少能知道系统执行到哪个阶段、看到了哪些有界事实、哪些校验未通过以及下一步应补充什么信息。

## 5. 实施阶段

### 阶段 1：Diagnosis Agent 硬停止策略（已完成）

- 限制证据收集轮次和重复 `lookup_knowledge`。
- 在预算耗尽前向 Agent 注入停止信号并要求输出最终 Draft。
- 区分正常 ReAct 轮次、新 Tool Action 和真正的预算耗尽。
- 连续 `INVALID_PROGRESS_PROTOCOL` 独立计数，达到阈值后以 `PROGRESS_PROTOCOL_VIOLATED` 受控停止。
- 增加重复检索、临界预算、协议错误修复/停止和无足够证据时的回归测试。

### 阶段 2：Evidence Repair Schema（未完成）

- 使用框架 `BeanOutputConverter<DiagnosisDraft>` 或等价结构化转换器注入实际 JSON Schema。
- 保持 Repair 无 Tool、最多一次、失败即安全 Fallback 的现有边界。
- 覆盖合法修复、Schema 非法、解析失败和二次 EvidenceGuard 失败。

### 阶段 3：Reasoning 审计验证与治理（大部分完成）

- [x] 使用真实 DeepSeek Provider 验证 thinking 返回路径：专用字段 `DeepSeekAssistantMessage.reasoningContent`（非 metadata）。
- [x] 同表同时落库 `assistant_text`（正文 / tool-call 计划）与 `content_source`（V017）。
- [x] Provider 不返回 reasoning 时写入 `reasoning_available=false`，不得伪造内容（单测覆盖；live unavailable 场景可再归档）。
- [x] 验证 V015–V017 迁移与 `sessionId + runId` 精确 reasoning 查询（含双字段 API）。
- [ ] 明确 reasoning 审计接口的访问控制、保留期限和加密要求。

### 阶段 4：Fallback 信息质量与最终 E2E（大部分完成）

- 工具成功但无法构造 verified snapshot 时，返回有界 `observed_facts` 和 `validation_issues`。
- 确保普通 Trace 只记录 `reasoning_available/reasoning_bytes` 等有界 metadata，不返回 reasoning/assistant 原文；`run.conclusion` 可为业务结论读出。
- [x] Diagnosis SUCCESS 真实 E2E：SSE + Trace + Reasoning 双字段 + ToolInvocation + `diagnosis_run.conclusion` 对账（2026-07-28）。
- [ ] 再归档一个 reasoning unavailable 与信息化 FALLBACK 的跨表精确核验样本。
- 按 exact `sessionId + runId` 核对 SSE、Trace、Reasoning Audit、ToolInvocation 和 Run 终态。

## 6. 验收标准

- 重复检索场景不会因第 9 次同 Tool 调用才被动触发 `BUDGET_EXHAUSTED`。
- Agent 在有证据时可形成合法 Draft；证据不足时形成无强结论的合法 Draft 或信息化 Fallback。
- Evidence Repair 的真实模型输出不再出现因缺失 `DiagnosisDraft` Schema 导致的 `PARSE_ERROR`。
- V015 在真实数据库中迁移成功，reasoning 查询严格校验 path `sessionId` 与 query `runId` 的归属关系。
- Provider 无 reasoning 时仍有审计记录；Provider 有 reasoning 时原文只存在于受限审计接口。
- 普通 SSE、Trace、日志、Evidence Snapshot 和发布结果均不包含 reasoning 原文、Prompt 或原始 Tool 载荷。
- 审计查询能按精确 `sessionId + runId` 返回每个 Agent 模型步骤的 reasoning 可用性、步骤顺序、字节数和受限原文；不存在跨 Session/Run 串读。
- 失败 Fallback 不再只返回固定的“无法确认根因”文本；至少包含失败阶段、非敏感观察事实、具体校验问题、证据范围/缺口和下一步建议。
- `observed_facts` 和 `validation_issues` 有长度和字段边界，不能泄露 Prompt、完整上下文、原始 Tool 响应、凭据或内部堆栈。
- 在无证据、EvidenceGuard 失败、Evidence Repair 失败、SemanticGuard UNSUPPORTED 和预算耗尽等路径下，用户都能区分失败原因，而不是收到同一种空泛结论。
- 三类最终 E2E 证据和精确数据库核验完成归档。

## 7. 流程门禁

- 每个阶段使用独立 OpenSpec change 和完整串行 sm-flow。
- 每阶段完成 Apply、focused tests、验收证据、Archive 和独立 Git commit 后再进入下一阶段。
- 阶段 1-3 不运行完整 live E2E；阶段 4 统一完成最终真实验证。
- 不重新引入 Planner/Executor/Verifier/Composer、业务 Graph、第二 Chat 入口或通用工作流 DSL。

## 8. 相关文件

- `mvp/issues/archived/ISS-014-single-react-agent-harness-aci-ptk-refactor.md`
- `src/main/java/com/superbiz/agent/harness/agent/DiagnosisAgentFactory.java`
- `src/main/java/com/superbiz/agent/harness/release/EvidenceRepair.java`
- `src/main/java/com/superbiz/agent/harness/release/SafeFallbackFactory.java`
- `src/main/java/com/superbiz/agent/harness/audit/HarnessAgentAuditHook.java`
- `src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java`
- `src/main/resources/db/migration/V015__create_agent_reasoning_audit.sql`