From e47f2dead023d99109cc765f3358b450ec5ecfcc Mon Sep 17 00:00:00 2001 From: zhuyongxin Date: Thu, 23 Jul 2026 20:16:29 +0800 Subject: [PATCH] docs(mvp): align architecture and audit table design --- mvp/README.md | 78 +++---------------- mvp/architecture/README.md | 12 +-- mvp/architecture/agent-orchestration.md | 17 +++- .../archive/2026-07-22-legacy/README.md | 62 ++++++--------- mvp/architecture/current-mvp-architecture.md | 21 ++++- mvp/architecture/harness-quality-gates.md | 26 +++++-- mvp/architecture/session-trace-lifecycle.md | 18 ++++- .../Agent推理审计表-agent_reasoning_audit.md | 50 ++++++++++++ mvp/tables/Agent步骤表-agent_step.md | 4 +- mvp/tables/README.md | 8 +- .../诊断Trace事件表-diagnosis_trace_event.md | 52 +++++++++++++ mvp/tables/诊断运行表-diagnosis_run.md | 3 + 12 files changed, 227 insertions(+), 124 deletions(-) create mode 100644 mvp/tables/Agent推理审计表-agent_reasoning_audit.md create mode 100644 mvp/tables/诊断Trace事件表-diagnosis_trace_event.md diff --git a/mvp/README.md b/mvp/README.md index 45aa8f8..3aa80b4 100644 --- a/mvp/README.md +++ b/mvp/README.md @@ -1,6 +1,6 @@ # SuperBizAgent MVP 文档 -**更新日期**：2026-07-10 +**更新日期**：2026-07-23 本目录保存 MVP 阶段的架构、问题、演示、评测和数据表说明。当前材料按“当前入口”和“历史归档”拆开，避免把早期设计稿当成当前实现。 @@ -10,27 +10,15 @@ |---|---| | [architecture/README.md](architecture/README.md) | 当前 MVP 架构入口 | | [architecture/current-mvp-architecture.md](architecture/current-mvp-architecture.md) | 当前可运行系统架构 | -| [architecture/interview-one-pager.md](architecture/interview-one-pager.md) | 面试一页式架构讲解 | | [architecture/agent-orchestration.md](architecture/agent-orchestration.md) | Agent 编排架构 | -| [architecture/executor-evidence-pipeline-refactor.md](architecture/executor-evidence-pipeline-refactor.md) | Executor 证据链路改造记录 | | [architecture/harness-quality-gates.md](architecture/harness-quality-gates.md) | Harness 与质量门禁 | -| [architecture/rag-architecture.md](architecture/rag-architecture.md) | RAG/知识检索新架构 | -| [architecture/retrieval-observability.md](architecture/retrieval-observability.md) | 检索与可观测性架构 | -| [architecture/feedback-architecture.md](architecture/feedback-architecture.md) | 反馈与自评估架构 | | [architecture/session-trace-lifecycle.md](architecture/session-trace-lifecycle.md) | 会话与 Trace 生命周期 | -| [architecture/knowledge-base-authoring.md](architecture/knowledge-base-authoring.md) | 知识库文档编写与维护 | -| [architecture/data-model.md](architecture/data-model.md) | 数据模型总览 | -| [architecture/evolution-roadmap.md](architecture/evolution-roadmap.md) | Agent 架构演进路线 | | [issues/README.md](issues/README.md) | MVP issue 索引 | -| [issues/archived/rag-refactor-plan.md](issues/archived/rag-refactor-plan.md) | 已过时的 RAG 重构计划（仅供历史追溯） | | [tables/README.md](tables/README.md) | 当前 MySQL 表说明 | -| [demo/README.md](demo/README.md) | Demo 运行和面试演示材料 | -| [demo/ten-minute-interview-demo.md](demo/ten-minute-interview-demo.md) | 10 分钟面试演示脚本 | +| [demo/README.md](demo/README.md) | Demo 运行和演示材料 | | [eval/README.md](eval/README.md) | 诊断评测材料 | -## 当前系统一句话 - -SuperBizAgent MVP 是一个可追踪的故障诊断 Agent：Chat 和 AIOps 入口进入 Agent 编排，Executor 显式调用知识库、日志、指标等工具收集证据；多轮会话元数据落到 `chat_session`，每次诊断运行落到 `diagnosis_run`，步骤和工具明细通过 `agent_step.run_id`、`tool_invocation.run_id` 关联，最终通过 Trace API、Verifier 和评测脚本证明结果可解释、可回放、可对比。 +当前架构、运行链路和后续规划分别以 `architecture/`、`issues/README.md`、`tables/README.md` 以及 OpenSpec/devflow 的最新记录为准。 ## 文档结构 @@ -39,18 +27,12 @@ mvp/ architecture/ README.md current-mvp-architecture.md - interview-one-pager.md agent-orchestration.md - executor-evidence-pipeline-refactor.md harness-quality-gates.md - rag-architecture.md - retrieval-observability.md - feedback-architecture.md session-trace-lifecycle.md - knowledge-base-authoring.md - data-model.md - evolution-roadmap.md archive/ + 2026-07-05-legacy/ + 2026-07-22-legacy/ issues/ README.md active/ @@ -76,51 +58,13 @@ mvp/ archive/ ``` -## 当前核心设计 - -- `lookup_knowledge` 保持显式 Agent Tool，不隐藏到 Chat Advisor。 -- L0 降级为 domain/entity hint，不再默认承担最终召回决策。 -- `VectorSearchService` 是检索稳定门面。 -- Spring AI VectorStore 是当前读取主路径，Milvus SDK 保留为 fallback。 -- AIOps payload 会生成推荐知识库 query，保留业务语义。 -- `sessionId` 表示多轮会话上下文，`runId` 表示一次可回放诊断运行。 -- Trace API 聚合 `diagnosis_run`、`agent_step.run_id`、`tool_invocation.run_id` 和 self evaluation。 -- RAG 行为通过 offline baseline 和 live acceptance 脚本做回归验证。 - -## 关键运行链路 - -```text -Chat - -> ChatService - -> Planner / Executor / Verifier - -> evidence tools - -> chat_session / diagnosis_run - -> agent_step.run_id / tool_invocation.run_id - -> DiagnosisTraceService - -AIOps - -> AiOpsService - -> PAYLOAD_TARGETED or AUTO_DISCOVERY - -> Planner / Executor - -> Prometheus / logs / lookup_knowledge - -> AiOpsRuleEvaluationService - -> diagnosis_run(agent_flow=AI_OPS) - -> DiagnosisTraceService - -RAG - -> lookup_knowledge - -> L0 domain/entity hint - -> VectorSearchService - -> Spring AI VectorStore / Milvus SDK fallback - -> relevance normalization - -> tool_invocation -``` - ## 归档说明 -历史材料分两类： +历史材料按归档批次保存： -- 旧架构文档：[architecture/archive/2026-07-05-legacy/](architecture/archive/2026-07-05-legacy/) -- 本次文档清理归档：[archive/2026-07-09-doc-cleanup/](archive/2026-07-09-doc-cleanup/) +- [architecture/archive/2026-07-05-legacy/](architecture/archive/2026-07-05-legacy/)：早期架构设计、实现计划和知识检索方案。 +- [architecture/archive/2026-07-22-legacy/](architecture/archive/2026-07-22-legacy/)：单 Diagnosis Agent + Harness 切换前的多角色编排、双入口和旧证据链架构。 +- [archive/2026-07-09-doc-cleanup/](archive/2026-07-09-doc-cleanup/)：文档清理时迁移的历史材料。 +- [issues/archived/](issues/archived/)：已关闭或已被当前架构替代的 Issue。 -归档文档只用于追溯设计历史。当前实现和后续规划以 `architecture/`、`issues/README.md`、`tables/README.md` 和 OpenSpec/devflow 的最新记录为准。 +归档内容仅用于追溯历史决策，不代表当前 runtime、API、数据模型或验收口径。 diff --git a/mvp/architecture/README.md b/mvp/architecture/README.md index 8ac9e68..6fa924e 100644 --- a/mvp/architecture/README.md +++ b/mvp/architecture/README.md @@ -1,15 +1,17 @@ # MVP 架构文档 -**更新日期**：2026-07-22 +**更新日期**：2026-07-23 **状态**：当前单 Diagnosis Agent + Harness 架构 当前文档入口： | 文档 | 内容 | |---|---| -| [current-mvp-architecture.md](current-mvp-architecture.md) | 系统分层、请求主链与 API surface | -| [agent-orchestration.md](agent-orchestration.md) | 单 Diagnosis ReAct Agent 的职责和执行方式 | -| [harness-quality-gates.md](harness-quality-gates.md) | Run、Tool、Evidence、Semantic 与 Release 门禁 | -| [session-trace-lifecycle.md](session-trace-lifecycle.md) | sessionId/runId、SSE 和 durable audit 生命周期 | +| [current-mvp-architecture.md](current-mvp-architecture.md) | 系统分层、请求主链、Trace/Reasoning 边界与 API surface | +| [agent-orchestration.md](agent-orchestration.md) | 单 Diagnosis ReAct Agent 的职责、执行方式和 reasoning 采集边界 | +| [harness-quality-gates.md](harness-quality-gates.md) | Run、Tool、Evidence、Semantic、Release 与 Trace Recorder 门禁 | +| [session-trace-lifecycle.md](session-trace-lifecycle.md) | sessionId/runId、SSE、统一 Timeline 和 reasoning audit 生命周期 | 2026-07-22 前的多角色编排、双入口和旧证据链文档已移动到 `archive/2026-07-22-legacy/`，仅用于历史决策追溯，不代表当前运行时。 + +当前普通 Trace 与 Provider reasoning 审计使用独立存储和独立接口。Reasoning 访问控制、保留期限、加密要求以及真实 Provider/V015 验证仍由 ISS-015 跟踪，不能把“数据已分表”理解为“治理已经完成”。 diff --git a/mvp/architecture/agent-orchestration.md b/mvp/architecture/agent-orchestration.md index fb9eed1..82db666 100644 --- a/mvp/architecture/agent-orchestration.md +++ b/mvp/architecture/agent-orchestration.md @@ -1,6 +1,6 @@ # Diagnosis Agent 执行架构 -**更新日期**：2026-07-22 +**更新日期**：2026-07-23 **状态**：当前可运行架构 ## 1. 单 Agent 原则 @@ -32,6 +32,7 @@ sequenceDiagram participant Core as Harness Core participant Agent as Diagnosis Agent participant Tool as ACI Tool Boundary + participant Audit as Audit Hook / Trace Recorder participant EG as EvidenceGuard participant SG as SemanticGuard participant Release as Release Policy @@ -40,6 +41,8 @@ sequenceDiagram App->>Agent: query + safe previous_turn Agent->>Tool: tool name + framework tool_call_id + typed args Tool-->>Agent: bounded agent_result + Tool->>Audit: bounded Tool lifecycle metadata + Agent->>Audit: step metadata + Provider reasoning availability Agent-->>App: DiagnosisDraft App->>EG: Draft + current Run canonical invocations EG-->>App: verified snapshot or deterministic failure @@ -52,3 +55,15 @@ sequenceDiagram ## 4. PreviousTurn PreviousTurn 只来自同一 Session 最近一个 `DIAGNOSIS + SUCCESS + published_result`。Fallback、失败、取消、raw evidence 和完整历史都不能进入下一轮；字段与字节上限由 Harness 配置控制。 + +## 5. Provider Reasoning 审计 + +`HarnessAgentAuditHook` 在每次模型步骤结束后检查 `AssistantMessage` metadata。当前识别 `reasoning_content`、`reasoningContent`、`reasoning` 和 `thinking`，但只接受 Provider 实际返回的非空文本： + +- 有内容时写入 `agent_reasoning_audit`，单条最多保留 32000 个字符，并记录 UTF-8 `content_bytes`。 +- 无内容时写入 `reasoning_available=false`、`reasoning_content=NULL`、`content_bytes=0`，不得根据最终回答反推或生成 reasoning。 +- `agent_step.thought` 始终为空；步骤表只记录 message count、roles、是否有文本、Tool names、reasoning availability 和字节数等 metadata。 +- 普通 `diagnosis_trace_event` 的 `AGENT_MODEL_STEP` 只记录 reasoning availability/bytes，不保存 reasoning 原文。 +- Reasoning 只用于受限审计，不进入 Agent 后续上下文，不参与 EvidenceGuard、SemanticGuard 或 Release Policy 的事实判断。 + +当前查询隔离已经实现，完整访问治理和真实 Provider 行为验证仍属于 ISS-015。 diff --git a/mvp/architecture/archive/2026-07-22-legacy/README.md b/mvp/architecture/archive/2026-07-22-legacy/README.md index 568e2a8..a0d60c1 100644 --- a/mvp/architecture/archive/2026-07-22-legacy/README.md +++ b/mvp/architecture/archive/2026-07-22-legacy/README.md @@ -1,48 +1,32 @@ -# MVP 架构文档 +# MVP 架构归档（2026-07-22） -**更新日期**：2026-07-10 +**状态**：历史快照，禁止作为当前实现依据 -这里是 MVP 当前架构的唯一入口。旧版设计、早期拆解和已经被新实现替代的方案已归档到： +本目录保存切换到单 Diagnosis Agent + Harness 之前的架构文档，包括多角色编排、Chat/AIOps 双入口、Executor/Verifier 证据链、旧 RAG 设计和旧数据模型。 -- `mvp/architecture/archive/2026-07-05-legacy/` +这些文档保留原有内容和相对链接，用于追溯当时的设计背景。当前 runtime、API、数据模型和验收口径请从 [../../../README.md](../../../README.md) 进入。 -归档材料只作为设计历史阅读，不再作为当前实现依据。 - -## 当前文档 +## 归档内容 | 文档 | 用途 | |---|---| -| [current-mvp-architecture.md](current-mvp-architecture.md) | 当前可运行 MVP 的总体架构、链路、持久化和质量门禁 | -| [interview-one-pager.md](interview-one-pager.md) | 面试一页式架构讲解，包含总图、亮点、取舍和追问回答 | -| [agent-orchestration.md](agent-orchestration.md) | Agent 编排细节，覆盖 Chat SequentialAgent、AIOps SupervisorAgent、工具边界 | -| [executor-evidence-pipeline-refactor.md](executor-evidence-pipeline-refactor.md) | Chat 证据链路当前数据契约，覆盖 Executor V2、Gatekeeper、Verifier、Composer、`evidence_refs` | -| [harness-quality-gates.md](harness-quality-gates.md) | Prompt、Hook、Trace、Gatekeeper、Verifier、Composer、评测基线组成的质量门禁 | -| [rag-architecture.md](rag-architecture.md) | RAG/知识检索新架构，覆盖 L0 hint、VectorStore 主路径、SDK fallback、证据追踪 | -| [modular-rag-pipeline.md](modular-rag-pipeline.md) | `lookup_knowledge` 模块化 RAG 落地架构，覆盖 pipeline、fallback、evidence-first contract、trace | -| [rag-eval-closure.md](rag-eval-closure.md) | RAG 评测闭环，覆盖 offline baseline、baseline diff、diagnosis eval 和 live acceptance | -| [retrieval-observability.md](retrieval-observability.md) | 检索运行细节和可观测性，覆盖 L0/L1、去重、分数归一、评测 | -| [feedback-architecture.md](feedback-architecture.md) | 反馈与自评估闭环，覆盖 rule evaluation、Verifier、AIOps rule、用户反馈和案例沉淀 | -| [session-trace-lifecycle.md](session-trace-lifecycle.md) | 会话和 Trace 生命周期，覆盖 sessionId、状态流转、agent_step、tool_invocation、Trace API | -| [knowledge-base-authoring.md](knowledge-base-authoring.md) | 知识库文档编写与维护规范，覆盖 frontmatter、category、chunk、reindex | -| [data-model.md](data-model.md) | 数据模型总览，覆盖 Trace、知识库、反馈沉淀和 Milvus metadata | -| [evolution-roadmap.md](evolution-roadmap.md) | 从旧版 Agent 蓝图继承的后续演进路线，不代表当前已实现 | +| [current-mvp-architecture.md](current-mvp-architecture.md) | 归档时的整体架构快照 | +| [interview-one-pager.md](interview-one-pager.md) | 旧架构讲解材料 | +| [agent-orchestration.md](agent-orchestration.md) | Chat SequentialAgent 与 AIOps SupervisorAgent 编排 | +| [executor-evidence-pipeline-refactor.md](executor-evidence-pipeline-refactor.md) | Executor、Gatekeeper、Verifier 与 Composer 证据链 | +| [harness-quality-gates.md](harness-quality-gates.md) | 旧多角色 Harness 质量门禁 | +| [rag-architecture.md](rag-architecture.md) | 旧 RAG 总体架构 | +| [modular-rag-pipeline.md](modular-rag-pipeline.md) | 旧模块化 RAG 方案 | +| [rag-eval-closure.md](rag-eval-closure.md) | 旧 RAG 评测闭环 | +| [retrieval-observability.md](retrieval-observability.md) | 旧检索可观测性设计 | +| [feedback-architecture.md](feedback-architecture.md) | 旧反馈与自评估设计 | +| [session-trace-lifecycle.md](session-trace-lifecycle.md) | 旧会话和 Trace 生命周期 | +| [knowledge-base-authoring.md](knowledge-base-authoring.md) | 知识库编写规范快照 | +| [data-model.md](data-model.md) | 旧数据模型总览 | +| [evolution-roadmap.md](evolution-roadmap.md) | 旧架构演进路线 | -## 当前架构一句话 +## 归档边界 -SuperBizAgent MVP 是一个面向故障诊断的可追踪 Agent 系统：Chat 和 AIOps 入口统一进入 Agent 编排，Executor 通过显式工具收集日志、指标和知识库证据，Chat 链路由 Gatekeeper 做引用真实性校验、Verifier 做可推导性判断、Composer 生成最终表达；多轮会话元数据落到 `chat_session`，每次诊断运行落到 `diagnosis_run`，步骤和工具明细通过 `agent_step.run_id`、`tool_invocation.run_id` 关联，最终通过 Trace API 和评测脚本证明诊断链路可解释、可回放、可对比。 - -## 阅读顺序 - -1. 先读 [current-mvp-architecture.md](current-mvp-architecture.md)，理解系统边界和主链路。 -2. 面试前读 [interview-one-pager.md](interview-one-pager.md)，准备 2-5 分钟讲解。 -3. 再读 [agent-orchestration.md](agent-orchestration.md)，理解当前 Agent 如何协作。 -4. 接着读 [executor-evidence-pipeline-refactor.md](executor-evidence-pipeline-refactor.md)，理解 Chat 证据链路的数据结构和验真边界。 -5. 然后读 [harness-quality-gates.md](harness-quality-gates.md)，理解为什么系统可追踪、可验证。 -6. 再读 [rag-architecture.md](rag-architecture.md)，理解当前 RAG 为什么保留显式 `lookup_knowledge`，以及 Spring AI VectorStore 如何接入。 -7. 继续读 [modular-rag-pipeline.md](modular-rag-pipeline.md)，看 `lookup_knowledge` 的模块化落地和 evidence-first contract。 -8. 再读 [rag-eval-closure.md](rag-eval-closure.md)，看 RAG baseline 如何形成质量闭环。 -9. 然后读 [retrieval-observability.md](retrieval-observability.md)，看检索细节和质量回归方式。 -10. 再读 [feedback-architecture.md](feedback-architecture.md)，理解 self_evaluation、用户反馈和案例沉淀。 -11. 按需读 [session-trace-lifecycle.md](session-trace-lifecycle.md)、[knowledge-base-authoring.md](knowledge-base-authoring.md)、[data-model.md](data-model.md)，补齐运行生命周期、知识库维护和数据关系。 -12. 最后读 [evolution-roadmap.md](evolution-roadmap.md)，区分后续演进和当前实现。 -13. 需要追溯旧方案时，再进入 `archive/2026-07-05-legacy/`。 +- 不根据本目录新增或修改运行时代码。 +- 不将本目录描述的接口和表结构视为当前契约。 +- 如需引用历史决策，应同时说明其归档日期和当前替代方案。 diff --git a/mvp/architecture/current-mvp-architecture.md b/mvp/architecture/current-mvp-architecture.md index 51f9bfe..5329156 100644 --- a/mvp/architecture/current-mvp-architecture.md +++ b/mvp/architecture/current-mvp-architecture.md @@ -1,6 +1,6 @@ # 当前 MVP 架构 -**更新日期**：2026-07-22 +**更新日期**：2026-07-23 **状态**：当前可运行架构 ## 1. 系统定位 @@ -25,10 +25,14 @@ flowchart TB Release --> Chat App --> Run["diagnosis_run"] Diagnosis --> Step["agent_step metadata audit"] + App --> Timeline["diagnosis_trace_event"] + Diagnosis --> Reasoning["agent_reasoning_audit restricted"] Tools --> Invocation["tool_invocation metadata audit"] Run --> Trace["Diagnosis Trace API"] Step --> Trace Invocation --> Trace + Timeline --> Trace + Reasoning --> ReasoningAPI["Reasoning Audit API"] ``` ## 3. 唯一 Chat 主链 @@ -66,20 +70,31 @@ chat_session(sessionId) -> diagnosis_run(runId) -> agent_step(runId) -> tool_invocation(runId) + -> diagnosis_trace_event(runId) + -> agent_reasoning_audit(runId, restricted) ``` - `chat_session` 是 JPA Run 目录与多轮 metadata，不保存完整对话历史。 - `diagnosis_run` 是 Run 状态、intent、release outcome、安全发布结果和预算汇总真理源。 - `agent_step` 只保存模型步骤 metadata，不保存 Prompt、消息正文、模型正文或 Thought。 - `tool_invocation` 只保存 Tool durable audit metadata；完整调用由 Redis canonical store 短期保存。 +- `diagnosis_trace_event` 是追加式统一 Timeline，记录 Run、Routing、Agent、Tool、Evidence、Semantic 和 Release 生命周期事件；`details` 只能保存有界安全 metadata。 +- `agent_reasoning_audit` 与普通 Trace 分表，只保存 Provider 实际返回的 reasoning 或明确的 unavailable 记录；reasoning 不属于事实证据。 ## 6. 公开 API -当前诊断执行入口只有 `POST /api/chat`。Trace、feedback、文档与检索 API 保持独立；已删除的旧诊断和 Redis conversation Session endpoint 不提供兼容分支。 +当前诊断执行入口只有 `POST /api/chat`。诊断审计读取分为： + +- `GET /api/diagnosis/{sessionId}/trace?runId={runId}`：普通 Trace，返回 Run、步骤、Tool metadata 和统一 Timeline，不返回 reasoning 原文。 +- `GET /api/diagnosis/{sessionId}/trace/reasoning?runId={runId}`：独立 reasoning 审计读取，`runId` 必填并校验其属于 path `sessionId`。 + +Reasoning endpoint 是敏感审计面，不属于普通业务 API。当前已完成数据和查询隔离；认证授权、保留期限、加密要求及真实 Provider 验证仍由 ISS-015 收敛。Feedback、文档与检索 API 保持独立；已删除的旧诊断和 Redis conversation Session endpoint 不提供兼容分支。 ## 7. 安全边界 -- 不输出或长期持久化 Chain of Thought。 +- 普通 SSE、Trace、Evidence Snapshot、业务结果和应用日志不输出或保存 reasoning 原文。 +- 仅当 Provider 在模型 metadata 中实际返回 reasoning 时，审计 Hook 才将其截断后写入独立表；Provider 未返回时不得伪造。 +- Reasoning 不能作为事实证据，也不能绕过 EvidenceGuard 或 SemanticGuard。 - 不向 Agent 暴露 Redis、canonical key、完整 Tool 请求/响应或数据库凭据。 - EvidenceGuard 只接受当前 Run 的 READY canonical invocation。 - SemanticGuard 无 Tool、无记忆、无回调主 Agent 能力。 diff --git a/mvp/architecture/harness-quality-gates.md b/mvp/architecture/harness-quality-gates.md index 64eb09a..d2a433d 100644 --- a/mvp/architecture/harness-quality-gates.md +++ b/mvp/architecture/harness-quality-gates.md @@ -1,6 +1,6 @@ # Harness 与质量门禁 -**更新日期**：2026-07-22 +**更新日期**：2026-07-23 **状态**：当前可运行架构 ## 1. Harness 定位 @@ -12,7 +12,7 @@ Harness 是确定性执行边界，不承担业务推理。它统一管理： - 类型化 retry policy；Diagnosis Agent 和 Tool 调用不自动重试。 - ToolBoundary、canonical invocation 与 Agent projection。 - EvidenceGuard、Evidence repair、SemanticGuard 与 Release Policy。 -- metadata-only durable audit。 +- metadata-only durable audit、统一 Trace Timeline 与独立 reasoning 审计。 ## 2. ToolBoundary @@ -39,10 +39,26 @@ SemanticGuard 使用隔离的单轮模型调用，只接收原始 query、完整 ## 5. Release Policy - `SUPPORTED`：发布 Diagnosis Agent 原始安全 Draft 的 typed report。 -- `UNSUPPORTED` 或 evidence failure：发布固定 SAFE_FALLBACK。 +- `UNSUPPORTED` 或 evidence failure：发布有界 SAFE_FALLBACK，说明 `failure_stage`、已验证 `observed_facts`、`validation_issues`、限制和 `next_steps`；不得泄露 Prompt、原始 Draft、原始 Tool 载荷或内部异常。 - technical failure：发布 stable failure，不泄漏内部异常。 - cancel/timeout：结束 exact Run，禁止 late content。 -## 6. Audit 安全 +## 6. Trace Recorder -AgentStep 不保存 Prompt、消息正文、模型正文、Tool arguments 或 Thought。ToolInvocation 不保存完整 request、SQL/日志 query、raw response 或 Agent projection。应用日志不得打印这些字段。 +`diagnosis_trace_event` 是追加式统一 Timeline。Recorder 按 exact `runId` 分配递增 `sequence_no`，覆盖： + +- `RUN`：Run 开始和终态。 +- `ROUTING`：路由尝试与最终 intent。 +- `AGENT`：模型步骤及有界 metadata。 +- `TOOL`：Tool 调用状态和耗时。 +- `EVIDENCE`：首次校验、Repair 尝试和复检。 +- `SEMANTIC`：语义校验尝试与判定。 +- `RELEASE`：最终发布决策。 + +Trace 写入失败只记录警告，不应改变业务执行结果；`details` 禁止包含 Prompt、Thought、Draft 正文或 raw Tool payload。普通 Trace API 按 `sequence_no, id` 返回 Timeline。 + +## 7. Audit 安全 + +AgentStep 不保存 Prompt、消息正文、模型正文、Tool arguments 或 Thought。ToolInvocation 不保存完整 request、SQL/日志 query、raw response 或 Agent projection。Provider reasoning 仅写入独立 `agent_reasoning_audit`，不进入普通 Trace 或发布结果；无 Provider 内容时必须记录 unavailable，不能伪造。应用日志不得打印这些字段。 + +Reasoning endpoint 当前已与普通 Trace 分离并执行 `sessionId + runId` 归属校验，但访问控制、保留期限和加密要求尚未完成，继续由 ISS-015 跟踪。 diff --git a/mvp/architecture/session-trace-lifecycle.md b/mvp/architecture/session-trace-lifecycle.md index 526c627..02f8c2e 100644 --- a/mvp/architecture/session-trace-lifecycle.md +++ b/mvp/architecture/session-trace-lifecycle.md @@ -1,6 +1,6 @@ # Session、Run 与 Trace 生命周期 -**更新日期**：2026-07-22 +**更新日期**：2026-07-23 **状态**：当前可运行架构 ## 1. Identity @@ -15,9 +15,11 @@ request accepted -> start RunContext -> persist diagnosis_run RUNNING + -> append diagnosis_trace_event RUN_STARTED -> metadata(session_id, run_id) -> route / execute / guard / release -> SUCCESS | FALLBACK | FAILED | CANCELLED + -> append diagnosis_trace_event RUN_FINISHED -> persist terminal state and budget usage ``` @@ -31,9 +33,23 @@ disconnect、timeout 与 send failure 通过同一个 `ChatRunControl` 请求取 - exact `diagnosis_run` 状态、intent、release outcome、安全 answer 与预算。 - `agent_step` metadata-only 模型步骤。 - `tool_invocation` metadata-only Tool durable audit。 +- `diagnosis_trace_event` 按 `sequence_no, id` 排序的统一生命周期 Timeline。 Redis canonical invocation 不是 Trace API 的长期响应内容；它只供当前 Run EvidenceGuard 验真。 +普通 Trace 不读取 `agent_reasoning_audit`，也不返回 reasoning 原文。Agent 模型步骤和 Timeline 只暴露 `reasoning_available`、`reasoning_bytes` 等有界 metadata。 + ## 4. PreviousTurn 应用在创建当前 Run 前读取同 Session 最近安全发布结果。只允许结构化 PublishedResult 的固定字段进入 PreviousTurn，且执行字节上限；完整历史、失败、Fallback、Tool raw data 和 guard reason 均排除。 + +## 5. Reasoning 审计查询 + +`GET /api/diagnosis/{sessionId}/trace/reasoning?runId={runId}` 提供独立 reasoning 审计读取： + +- `runId` 必填，服务端先验证 Run 存在且属于 path `sessionId`，禁止跨 Session 串读。 +- 结果按 `step_index` 返回 Agent、reasoning availability、受限原文、字节数和创建时间。 +- Provider 未返回 reasoning 时仍保留 unavailable 记录，以区分“没有返回”与“审计遗漏”。 +- Reasoning 数据不回流到 PreviousTurn，不进入普通 Trace、SSE、Evidence Snapshot 或发布结果。 + +该端点属于敏感审计面。当前完成了分表、独立查询和归属校验；身份认证、权限模型、保留期限、加密及真实 Provider/V015 验证尚未完成，由 ISS-015 阶段 3 收敛。 diff --git a/mvp/tables/Agent推理审计表-agent_reasoning_audit.md b/mvp/tables/Agent推理审计表-agent_reasoning_audit.md new file mode 100644 index 0000000..adfb260 --- /dev/null +++ b/mvp/tables/Agent推理审计表-agent_reasoning_audit.md @@ -0,0 +1,50 @@ +# Agent 推理审计表：agent_reasoning_audit + +**状态**：当前独立敏感审计表；治理待 ISS-015 收敛 +**来源**：`V015__create_agent_reasoning_audit.sql`、`AgentReasoningAudit` + +## 定位 + +`agent_reasoning_audit` 保存模型 Provider 在 Agent 步骤 metadata 中实际返回的 reasoning 内容。它与普通 Trace、AgentStep、Evidence Snapshot 和业务发布结果物理分离，不能作为事实证据或诊断结论来源。 + +Provider 未返回 reasoning 时仍写入 unavailable 记录，防止把“没有返回”误判为“审计链路漏写”。系统不得从最终回答、Tool 调用或其他字段生成伪 reasoning。 + +## 字段 + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `id` | BIGINT | 是 | 自增主键 | +| `session_id` | VARCHAR(64) | 是 | 所属 Chat Session ID | +| `run_id` | VARCHAR(64) | 是 | 所属 Diagnosis Run ID | +| `step_index` | INT | 是 | Agent 模型步骤序号 | +| `agent_name` | VARCHAR(64) | 是 | Agent 身份，当前为 `diagnosis_agent` | +| `reasoning_available` | BOOLEAN | 是 | Provider 是否实际返回非空 reasoning | +| `reasoning_content` | LONGTEXT | 否 | Provider reasoning 原文；Hook 当前最多保留 32000 个字符 | +| `content_bytes` | INT | 是 | 截断后 reasoning 的 UTF-8 字节数；unavailable 时为 0 | +| `created_at` | DATETIME | 是 | 创建时间，默认当前时间 | + +## 索引 + +| 索引 | 字段 | 用途 | +|---|---|---| +| `idx_reasoning_run_step` | `run_id, step_index` | exact Run 下按模型步骤查询 | +| `idx_reasoning_session_created` | `session_id, created_at` | Session 范围审计排查 | + +## 关系 + +- `run_id` 逻辑关联 `diagnosis_run.run_id`。 +- `session_id` 逻辑关联 `chat_session.session_id`。 +- 通过 `session_id + run_id + step_index` 与 `agent_step` 逻辑对应，不建立数据库外键。 + +## 写入规则 + +- Provider 返回非空 reasoning：`reasoning_available=true`，保存截断后的原文及实际 UTF-8 字节数。 +- Provider 未返回 reasoning：`reasoning_available=false`，`reasoning_content=NULL`，`content_bytes=0`。 +- `agent_step.thought` 继续保持为空；普通 Trace 仅保留 availability/bytes metadata。 +- Reasoning 不进入 SSE、PreviousTurn、Evidence Snapshot、发布结果或应用日志。 + +## 查询与治理 + +当前独立接口为 `GET /api/diagnosis/{sessionId}/trace/reasoning?runId={runId}`。`runId` 必填，服务端校验其属于 path `sessionId`，并按 `step_index` 返回记录。 + +分表和归属校验已经实现，但不能等同于完整安全治理。身份认证、角色授权、保留/删除期限、静态与传输加密以及真实 Provider/V015 验证仍由 ISS-015 阶段 3 跟踪；治理完成前不应将该接口暴露给普通业务用户。 diff --git a/mvp/tables/Agent步骤表-agent_step.md b/mvp/tables/Agent步骤表-agent_step.md index d7fbacf..84f218e 100644 --- a/mvp/tables/Agent步骤表-agent_step.md +++ b/mvp/tables/Agent步骤表-agent_step.md @@ -5,7 +5,7 @@ ## 定位 -`agent_step` 记录 Diagnosis Agent 模型步骤的有界审计 metadata。`run_id` 是执行隔离边界；当前写入不得保存 Prompt、消息正文、模型正文、Tool arguments 或 Thought。 +`agent_step` 记录 Diagnosis Agent 模型步骤的有界审计 metadata。`run_id` 是执行隔离边界；当前写入不得保存 Prompt、消息正文、模型正文、Tool arguments 或 Thought。Provider reasoning 使用独立 `agent_reasoning_audit` 表，不复用历史 `thought` 字段。 ## 字段 @@ -37,9 +37,11 @@ - `agent_step.run_id` 逻辑关联 `diagnosis_run.run_id`。 - `agent_step.session_id` 保留为 `chat_session.session_id` 的冗余关联，便于粗粒度过滤和兼容查询。 - `tool_invocation.step_id` 可关联 `agent_step.id`，但当前允许为空且不强制外键。 +- `agent_reasoning_audit` 通过相同的 `session_id + run_id + step_index` 逻辑定位模型步骤，不建立数据库外键。 ## 注意点 - 前端展示步骤时应使用 Trace API 返回顺序；服务端会在同一 `run_id` 范围内整理步骤顺序。 - 新 Trace 和验收读路径必须按 exact `run_id` 取数，避免同一 `sessionId` 多次运行混入。 - 当前 Run 若出现 `diagnosis_agent` 之外的新写入，或 `thought` 非空，视为审计边界违规。 +- `model_output` 可保存 `has_text`、`tool_names`、`reasoning_available` 和 `reasoning_bytes` 等有界 metadata，不得保存 reasoning 原文。 diff --git a/mvp/tables/README.md b/mvp/tables/README.md index 8f9782a..ea6a723 100644 --- a/mvp/tables/README.md +++ b/mvp/tables/README.md @@ -1,6 +1,6 @@ # MVP 数据表索引 -**更新日期**：2026-07-10 +**更新日期**：2026-07-23 **状态**：当前表文档入口 本目录保存当前 MVP 使用的数据表说明。详细结构以 Flyway migration 和实体类为准；本目录用于面试讲解、排查索引和快速理解数据流。 @@ -13,6 +13,8 @@ | `diagnosis_run` | `/api/chat` 运行主记录，保存 intent、终态与安全发布结果 | [诊断运行表-diagnosis_run.md](诊断运行表-diagnosis_run.md) | | `agent_step` | Diagnosis Agent metadata-only 模型步骤审计 | [Agent步骤表-agent_step.md](Agent步骤表-agent_step.md) | | `tool_invocation` | Harness ToolBoundary metadata-only 长期审计 | [工具调用表-tool_invocation.md](工具调用表-tool_invocation.md) | +| `diagnosis_trace_event` | 按 Run 追加的统一诊断生命周期 Timeline | [诊断Trace事件表-diagnosis_trace_event.md](诊断Trace事件表-diagnosis_trace_event.md) | +| `agent_reasoning_audit` | Provider reasoning 独立敏感审计；不属于普通 Trace | [Agent推理审计表-agent_reasoning_audit.md](Agent推理审计表-agent_reasoning_audit.md) | | `api_document` | 知识库文档元数据，和向量库 chunk 通过 `doc_id` 关联 | [文档元数据表-api_document.md](文档元数据表-api_document.md) | | `knowledge_domain` | 知识域元数据，支撑 RAG domain hint 和检索策略 | [知识域表-knowledge_domain.md](知识域表-knowledge_domain.md) | | `case_library` | 用户反馈沉淀出的高质量诊断案例 | [案例库表-case_library.md](案例库表-case_library.md) | @@ -31,6 +33,8 @@ chat_session.session_id -> diagnosis_run.session_id -> agent_step.run_id -> tool_invocation.run_id + -> diagnosis_trace_event.run_id + -> agent_reasoning_audit.run_id (restricted) -> case_library.diagnosis_id (new AUTO cases use run_id) diagnosis_session.session_id @@ -43,4 +47,4 @@ knowledge_domain.domain_id -> api_document metadata.category / vector chunk metadata.category ``` -当前实现主要使用逻辑关联，不依赖数据库外键。 +当前实现主要使用 `session_id + run_id` 逻辑关联，不依赖数据库外键。`agent_reasoning_audit` 是敏感审计数据，不与普通 Trace、Evidence Snapshot 或业务结果合并读取。 diff --git a/mvp/tables/诊断Trace事件表-diagnosis_trace_event.md b/mvp/tables/诊断Trace事件表-diagnosis_trace_event.md new file mode 100644 index 0000000..0130118 --- /dev/null +++ b/mvp/tables/诊断Trace事件表-diagnosis_trace_event.md @@ -0,0 +1,52 @@ +# 诊断 Trace 事件表：diagnosis_trace_event + +**状态**：当前统一 Trace Timeline +**来源**：`V014__create_diagnosis_trace_event.sql`、`DiagnosisTraceEvent` + +## 定位 + +`diagnosis_trace_event` 是按 Run 追加的统一生命周期事件表。它记录诊断执行经过哪些阶段、每个阶段的稳定事件类型和结果，使普通 Trace 不再依赖从多个业务表推测完整时序。 + +该表只保存有界安全 metadata，不保存 Prompt、Thought、DiagnosisDraft 正文或 raw Tool payload。事件写入失败可观测，但不改变业务执行结果。 + +## 字段 + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `id` | BIGINT | 是 | 自增主键；同一 `sequence_no` 下作为稳定次序补充 | +| `session_id` | VARCHAR(64) | 是 | 所属 Chat Session ID | +| `run_id` | VARCHAR(64) | 是 | 所属 Diagnosis Run ID | +| `sequence_no` | INT | 是 | 同一 Run 内递增事件序号 | +| `phase` | VARCHAR(32) | 是 | `RUN`、`ROUTING`、`AGENT`、`TOOL`、`EVIDENCE`、`SEMANTIC` 或 `RELEASE` | +| `event_type` | VARCHAR(48) | 是 | 稳定事件类型，如 `RUN_STARTED`、`AGENT_MODEL_STEP`、`RELEASE_DECISION` | +| `status` | VARCHAR(32) | 是 | 稳定事件结果，如 `SUCCEEDED`、`FAILED`、`PASSED`、`REJECTED`、`FALLBACK` | +| `attempt_no` | INT | 否 | Retry 或模型尝试序号；不适用时为空 | +| `duration_ms` | INT | 否 | 事件耗时；无法计算时为空 | +| `details` | JSON | 是 | 有界安全 metadata；不得包含敏感正文和原始载荷 | +| `created_at` | DATETIME | 是 | 创建时间，默认当前时间 | + +## 索引 + +| 索引 | 字段 | 用途 | +|---|---|---| +| `idx_trace_event_run_sequence` | `run_id, sequence_no, id` | exact Run Timeline 顺序查询 | +| `idx_trace_event_session_created` | `session_id, created_at, id` | Session 范围历史排查 | +| `idx_trace_event_phase` | `phase, event_type` | 按生命周期阶段和事件类型统计 | + +## 关系 + +- `run_id` 逻辑关联 `diagnosis_run.run_id`。 +- `session_id` 逻辑关联 `chat_session.session_id`，同时用于 Run 所有权排查。 +- 不建立数据库外键；应用必须使用 exact `sessionId + runId` 做归属校验。 + +## 事件范围 + +当前事件类型覆盖 Run 开始/结束、路由尝试/决策、Agent 模型步骤、Tool 调用、Evidence 初检/Repair/复检、Semantic 尝试/决策和 Release 决策。 + +普通 Trace API 按 `sequence_no ASC, id ASC` 返回 Timeline。Agent 模型事件最多包含 reasoning availability 和字节数，不包含 reasoning 原文。 + +## 注意点 + +- 该表是追加式审计时间线，不是 `diagnosis_run` 终态的替代品。 +- `details` 必须保持结构化、有界和非敏感；禁止将其他表的正文复制进来。 +- 不应仅依赖 `created_at` 排序，同一 Run 必须使用 `sequence_no, id`。 diff --git a/mvp/tables/诊断运行表-diagnosis_run.md b/mvp/tables/诊断运行表-diagnosis_run.md index ee59103..01df734 100644 --- a/mvp/tables/诊断运行表-diagnosis_run.md +++ b/mvp/tables/诊断运行表-diagnosis_run.md @@ -45,6 +45,8 @@ - `diagnosis_run.session_id` 逻辑关联 `chat_session.session_id`。 - `agent_step.run_id` 逻辑关联 `diagnosis_run.run_id`。 - `tool_invocation.run_id` 逻辑关联 `diagnosis_run.run_id`。 +- `diagnosis_trace_event.run_id` 逻辑关联 `diagnosis_run.run_id`，形成统一生命周期 Timeline。 +- `agent_reasoning_audit.run_id` 逻辑关联 `diagnosis_run.run_id`，但只能通过独立敏感审计读路径查询。 - 新的自动案例沉淀使用 `case_library.diagnosis_id = diagnosis_run.run_id`。 ## 注意点 @@ -53,3 +55,4 @@ - latest run 排序使用 `created_at DESC, id DESC`，避免 feedback 或自评估更新 `updated_at` 后改变回放目标。 - 历史 `diagnosis_session` 会被迁移成兼容 run，但旧混合数据不能被还原成真实多轮边界。 - 当前诊断发布结果以 `release_outcome + published_result` 为准，不得从旧 self-evaluation 推断 Release Policy 结果。 +- `diagnosis_run` 不保存 reasoning 原文；普通 Run/Trace 查询也不得通过聚合将其带出。