Files

T

zhuyongxin 38f781b157 feat(harness): complete protocol repair stop and archive ISS-016

Add repairable INVALID_PROGRESS_PROTOCOL observations, independent
PROGRESS_PROTOCOL_VIOLATED saturation, and controlled release paths.
Archive the OpenSpec change after syncing main specs and devflow.

2026-07-27 19:10:07 +08:00

9.4 KiB

Raw Blame History

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、独立 `agent_reasoning_audit`、审计 Hook、`reasoning_available=false`、受限查询接口和 `sessionId + runId` 归属校验已实现	真实 Provider reasoning metadata 行为、V015 真实迁移验收、访问控制、保留期限和加密要求尚未收敛
阶段 4：Fallback 信息质量与最终 E2E	大部分完成	已实现有界 `observed_facts`、`validation_issues`、证据范围/缺口和差异化 Fallback；已完成 Diagnosis SUCCESS、信息不足 FALLBACK、Trace/Tool/Token 对账 E2E	reasoning unavailable 场景及 Reasoning Audit 跨表精确核验尚未完成；全部失败路径仍需最终综合验收

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

4. 目标

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

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 审计验证与治理（部分完成）

使用真实 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

9.4 KiB Raw Blame History Unescape Escape