docs(issue): archive legacy issues and add iss-015
This commit is contained in:
zhuyongxin
@@ -0,0 +1,103 @@
|
||||
# ISS-015 诊断运行质量与 Reasoning 审计收敛
|
||||
|
||||
**状态**：待实施
|
||||
**严重程度**：高
|
||||
**发现时间**：2026-07-23
|
||||
**来源**：ISS-014 阶段 7 及后续真实 E2E 验证
|
||||
**关联**：ISS-014、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。
|
||||
|
||||
## 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 和真正的预算耗尽。
|
||||
- 增加重复检索、临界预算和无足够证据时的回归测试。
|
||||
|
||||
### 阶段 2：Evidence Repair Schema
|
||||
|
||||
- 使用框架 `BeanOutputConverter<DiagnosisDraft>` 或等价结构化转换器注入实际 JSON Schema。
|
||||
- 保持 Repair 无 Tool、最多一次、失败即安全 Fallback 的现有边界。
|
||||
- 覆盖合法修复、Schema 非法、解析失败和二次 EvidenceGuard 失败。
|
||||
|
||||
### 阶段 3：Reasoning 审计验证与治理
|
||||
|
||||
- 使用真实 Provider 验证 reasoning metadata 的键和返回行为。
|
||||
- Provider 不返回 reasoning 时写入 `reasoning_available=false`，不得伪造内容。
|
||||
- 验证 V015 数据库迁移和 `sessionId + runId` 精确 reasoning 查询。
|
||||
- 明确 reasoning 审计接口的访问控制、保留期限和加密要求。
|
||||
|
||||
### 阶段 4：Fallback 信息质量与最终 E2E
|
||||
|
||||
- 工具成功但无法构造 verified snapshot 时，返回有界 `observed_facts` 和 `validation_issues`。
|
||||
- 确保普通 Trace 只记录 `reasoning_available/reasoning_bytes`，不返回 reasoning 原文。
|
||||
- 运行至少一个 Diagnosis SUCCESS、一个信息化 FALLBACK 和一个 reasoning unavailable 的真实 E2E。
|
||||
- 按 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`
|
||||
Reference in New Issue
Block a user