osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(mvp): align architecture and audit table design

Browse Source
This commit is contained in:
zhuyongxin
2026-07-23 20:16:29 +08:00
parent 49180abccf
commit e47f2dead0
12 changed files with 227 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mvp/README.md
+11 -67
View File
@@ -1,6 +1,6 @@
# SuperBizAgent MVP 文档 # SuperBizAgent MVP 文档
**更新日期**：2026-07-10 **更新日期**：2026-07-23
本目录保存 MVP 阶段的架构、问题、演示、评测和数据表说明。当前材料按“当前入口”和“历史归档”拆开，避免把早期设计稿当成当前实现。 本目录保存 MVP 阶段的架构、问题、演示、评测和数据表说明。当前材料按“当前入口”和“历史归档”拆开，避免把早期设计稿当成当前实现。
@@ -10,27 +10,15 @@
|---|---| |---|---|
| [architecture/README.md](architecture/README.md) | 当前 MVP 架构入口 | | [architecture/README.md](architecture/README.md) | 当前 MVP 架构入口 |
| [architecture/current-mvp-architecture.md](architecture/current-mvp-architecture.md) | 当前可运行系统架构 | | [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/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/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/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/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 表说明 | | [tables/README.md](tables/README.md) | 当前 MySQL 表说明 |
| [demo/README.md](demo/README.md) | Demo 运行和面试演示材料 | | [demo/README.md](demo/README.md) | Demo 运行和演示材料 |
| [demo/ten-minute-interview-demo.md](demo/ten-minute-interview-demo.md) | 10 分钟面试演示脚本 |
| [eval/README.md](eval/README.md) | 诊断评测材料 | | [eval/README.md](eval/README.md) | 诊断评测材料 |
## 当前系统一句话 当前架构、运行链路和后续规划分别以 `architecture/`、`issues/README.md`、`tables/README.md` 以及 OpenSpec/devflow 的最新记录为准。
SuperBizAgent MVP 是一个可追踪的故障诊断 Agent：Chat 和 AIOps 入口进入 Agent 编排，Executor 显式调用知识库、日志、指标等工具收集证据；多轮会话元数据落到 `chat_session`，每次诊断运行落到 `diagnosis_run`，步骤和工具明细通过 `agent_step.run_id`、`tool_invocation.run_id` 关联，最终通过 Trace API、Verifier 和评测脚本证明结果可解释、可回放、可对比。
## 文档结构 ## 文档结构
@@ -39,18 +27,12 @@ mvp/
architecture/ architecture/
README.md README.md
current-mvp-architecture.md current-mvp-architecture.md
interview-one-pager.md
agent-orchestration.md agent-orchestration.md
executor-evidence-pipeline-refactor.md
harness-quality-gates.md harness-quality-gates.md
rag-architecture.md
retrieval-observability.md
feedback-architecture.md
session-trace-lifecycle.md session-trace-lifecycle.md
knowledge-base-authoring.md
data-model.md
evolution-roadmap.md
archive/ archive/
2026-07-05-legacy/
2026-07-22-legacy/
issues/ issues/
README.md README.md
active/ active/
@@ -76,51 +58,13 @@ mvp/
archive/ 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/) - [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-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、数据模型或验收口径。
mvp/architecture/README.md
+7 -5
View File
@@ -1,15 +1,17 @@
# MVP 架构文档 # MVP 架构文档
**更新日期**：2026-07-22 **更新日期**：2026-07-23
**状态**：当前单 Diagnosis Agent + Harness 架构 **状态**：当前单 Diagnosis Agent + Harness 架构
当前文档入口： 当前文档入口：
| 文档 | 内容 | | 文档 | 内容 |
|---|---| |---|---|
| [current-mvp-architecture.md](current-mvp-architecture.md) | 系统分层、请求主链与 API surface | | [current-mvp-architecture.md](current-mvp-architecture.md) | 系统分层、请求主链、Trace/Reasoning 边界与 API surface |
| [agent-orchestration.md](agent-orchestration.md) | 单 Diagnosis ReAct Agent 的职责和执行方式 | | [agent-orchestration.md](agent-orchestration.md) | 单 Diagnosis ReAct Agent 的职责、执行方式和 reasoning 采集边界 |
| [harness-quality-gates.md](harness-quality-gates.md) | Run、Tool、Evidence、Semantic 与 Release 门禁 | | [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 和 durable audit 生命周期 | | [session-trace-lifecycle.md](session-trace-lifecycle.md) | sessionId/runId、SSE、统一 Timeline 和 reasoning audit 生命周期 |
2026-07-22 前的多角色编排、双入口和旧证据链文档已移动到 `archive/2026-07-22-legacy/`，仅用于历史决策追溯，不代表当前运行时。 2026-07-22 前的多角色编排、双入口和旧证据链文档已移动到 `archive/2026-07-22-legacy/`，仅用于历史决策追溯，不代表当前运行时。
当前普通 Trace 与 Provider reasoning 审计使用独立存储和独立接口。Reasoning 访问控制、保留期限、加密要求以及真实 Provider/V015 验证仍由 ISS-015 跟踪，不能把“数据已分表”理解为“治理已经完成”。
mvp/architecture/agent-orchestration.md
+16 -1
View File
@@ -1,6 +1,6 @@
# Diagnosis Agent 执行架构 # Diagnosis Agent 执行架构
**更新日期**：2026-07-22 **更新日期**：2026-07-23
**状态**：当前可运行架构 **状态**：当前可运行架构
## 1. 单 Agent 原则 ## 1. 单 Agent 原则
@@ -32,6 +32,7 @@ sequenceDiagram
participant Core as Harness Core participant Core as Harness Core
participant Agent as Diagnosis Agent participant Agent as Diagnosis Agent
participant Tool as ACI Tool Boundary participant Tool as ACI Tool Boundary
participant Audit as Audit Hook / Trace Recorder
participant EG as EvidenceGuard participant EG as EvidenceGuard
participant SG as SemanticGuard participant SG as SemanticGuard
participant Release as Release Policy participant Release as Release Policy
@@ -40,6 +41,8 @@ sequenceDiagram
App->>Agent: query + safe previous_turn App->>Agent: query + safe previous_turn
Agent->>Tool: tool name + framework tool_call_id + typed args Agent->>Tool: tool name + framework tool_call_id + typed args
Tool-->>Agent: bounded agent_result Tool-->>Agent: bounded agent_result
Tool->>Audit: bounded Tool lifecycle metadata
Agent->>Audit: step metadata + Provider reasoning availability
Agent-->>App: DiagnosisDraft Agent-->>App: DiagnosisDraft
App->>EG: Draft + current Run canonical invocations App->>EG: Draft + current Run canonical invocations
EG-->>App: verified snapshot or deterministic failure EG-->>App: verified snapshot or deterministic failure
@@ -52,3 +55,15 @@ sequenceDiagram
## 4. PreviousTurn ## 4. PreviousTurn
PreviousTurn 只来自同一 Session 最近一个 `DIAGNOSIS + SUCCESS + published_result`。Fallback、失败、取消、raw evidence 和完整历史都不能进入下一轮；字段与字节上限由 Harness 配置控制。 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。
mvp/architecture/archive/2026-07-22-legacy/README.md
+23 -39
View File
@@ -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 的总体架构、链路、持久化和质量门禁 | | [current-mvp-architecture.md](current-mvp-architecture.md) | 归档时的整体架构快照 |
| [interview-one-pager.md](interview-one-pager.md) | 面试一页式架构讲解，包含总图、亮点、取舍和追问回答 | | [interview-one-pager.md](interview-one-pager.md) | 旧架构讲解材料 |
| [agent-orchestration.md](agent-orchestration.md) | Agent 编排细节，覆盖 Chat SequentialAgent、AIOps SupervisorAgent、工具边界 | | [agent-orchestration.md](agent-orchestration.md) | Chat SequentialAgent 与 AIOps SupervisorAgent 编排 |
| [executor-evidence-pipeline-refactor.md](executor-evidence-pipeline-refactor.md) | Chat 证据链路当前数据契约，覆盖 Executor V2、Gatekeeper、Verifier、Composer、`evidence_refs` | | [executor-evidence-pipeline-refactor.md](executor-evidence-pipeline-refactor.md) | Executor、Gatekeeper、Verifier 与 Composer 证据链 |
| [harness-quality-gates.md](harness-quality-gates.md) | Prompt、Hook、Trace、Gatekeeper、Verifier、Composer、评测基线组成的质量门禁 | | [harness-quality-gates.md](harness-quality-gates.md) | 旧多角色 Harness 质量门禁 |
| [rag-architecture.md](rag-architecture.md) | RAG/知识检索新架构，覆盖 L0 hint、VectorStore 主路径、SDK fallback、证据追踪 | | [rag-architecture.md](rag-architecture.md) | 旧 RAG 总体架构 |
| [modular-rag-pipeline.md](modular-rag-pipeline.md) | `lookup_knowledge` 模块化 RAG 落地架构，覆盖 pipeline、fallback、evidence-first contract、trace | | [modular-rag-pipeline.md](modular-rag-pipeline.md) | 旧模块化 RAG 方案 |
| [rag-eval-closure.md](rag-eval-closure.md) | RAG 评测闭环，覆盖 offline baseline、baseline diff、diagnosis eval 和 live acceptance | | [rag-eval-closure.md](rag-eval-closure.md) | 旧 RAG 评测闭环 |
| [retrieval-observability.md](retrieval-observability.md) | 检索运行细节和可观测性，覆盖 L0/L1、去重、分数归一、评测 | | [retrieval-observability.md](retrieval-observability.md) | 旧检索可观测性设计 |
| [feedback-architecture.md](feedback-architecture.md) | 反馈与自评估闭环，覆盖 rule evaluation、Verifier、AIOps rule、用户反馈和案例沉淀 | | [feedback-architecture.md](feedback-architecture.md) | 旧反馈与自评估设计 |
| [session-trace-lifecycle.md](session-trace-lifecycle.md) | 会话和 Trace 生命周期，覆盖 sessionId、状态流转、agent_step、tool_invocation、Trace API | | [session-trace-lifecycle.md](session-trace-lifecycle.md) | 旧会话和 Trace 生命周期 |
| [knowledge-base-authoring.md](knowledge-base-authoring.md) | 知识库文档编写与维护规范，覆盖 frontmatter、category、chunk、reindex | | [knowledge-base-authoring.md](knowledge-base-authoring.md) | 知识库编写规范快照 |
| [data-model.md](data-model.md) | 数据模型总览，覆盖 Trace、知识库、反馈沉淀和 Milvus metadata | | [data-model.md](data-model.md) | 旧数据模型总览 |
| [evolution-roadmap.md](evolution-roadmap.md) | 从旧版 Agent 蓝图继承的后续演进路线，不代表当前已实现 | | [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/`。
mvp/architecture/current-mvp-architecture.md
+18 -3
View File
@@ -1,6 +1,6 @@
# 当前 MVP 架构 # 当前 MVP 架构
**更新日期**：2026-07-22 **更新日期**：2026-07-23
**状态**：当前可运行架构 **状态**：当前可运行架构
## 1. 系统定位 ## 1. 系统定位
@@ -25,10 +25,14 @@ flowchart TB
Release --> Chat Release --> Chat
App --> Run["diagnosis_run"] App --> Run["diagnosis_run"]
Diagnosis --> Step["agent_step metadata audit"] Diagnosis --> Step["agent_step metadata audit"]
App --> Timeline["diagnosis_trace_event"]
Diagnosis --> Reasoning["agent_reasoning_audit restricted"]
Tools --> Invocation["tool_invocation metadata audit"] Tools --> Invocation["tool_invocation metadata audit"]
Run --> Trace["Diagnosis Trace API"] Run --> Trace["Diagnosis Trace API"]
Step --> Trace Step --> Trace
Invocation --> Trace Invocation --> Trace
Timeline --> Trace
Reasoning --> ReasoningAPI["Reasoning Audit API"]
``` ```
## 3. 唯一 Chat 主链 ## 3. 唯一 Chat 主链
@@ -66,20 +70,31 @@ chat_session(sessionId)
-> diagnosis_run(runId) -> diagnosis_run(runId)
-> agent_step(runId) -> agent_step(runId)
-> tool_invocation(runId) -> tool_invocation(runId)
-> diagnosis_trace_event(runId)
-> agent_reasoning_audit(runId, restricted)
``` ```
- `chat_session` 是 JPA Run 目录与多轮 metadata，不保存完整对话历史。 - `chat_session` 是 JPA Run 目录与多轮 metadata，不保存完整对话历史。
- `diagnosis_run` 是 Run 状态、intent、release outcome、安全发布结果和预算汇总真理源。 - `diagnosis_run` 是 Run 状态、intent、release outcome、安全发布结果和预算汇总真理源。
- `agent_step` 只保存模型步骤 metadata，不保存 Prompt、消息正文、模型正文或 Thought。 - `agent_step` 只保存模型步骤 metadata，不保存 Prompt、消息正文、模型正文或 Thought。
- `tool_invocation` 只保存 Tool durable audit metadata；完整调用由 Redis canonical store 短期保存。 - `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 ## 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. 安全边界 ## 7. 安全边界
- 不输出或长期持久化 Chain of Thought。 - 普通 SSE、Trace、Evidence Snapshot、业务结果和应用日志不输出或保存 reasoning 原文。
- 仅当 Provider 在模型 metadata 中实际返回 reasoning 时，审计 Hook 才将其截断后写入独立表；Provider 未返回时不得伪造。
- Reasoning 不能作为事实证据，也不能绕过 EvidenceGuard 或 SemanticGuard。
- 不向 Agent 暴露 Redis、canonical key、完整 Tool 请求/响应或数据库凭据。 - 不向 Agent 暴露 Redis、canonical key、完整 Tool 请求/响应或数据库凭据。
- EvidenceGuard 只接受当前 Run 的 READY canonical invocation。 - EvidenceGuard 只接受当前 Run 的 READY canonical invocation。
- SemanticGuard 无 Tool、无记忆、无回调主 Agent 能力。 - SemanticGuard 无 Tool、无记忆、无回调主 Agent 能力。
mvp/architecture/harness-quality-gates.md
+21 -5
View File
@@ -1,6 +1,6 @@
# Harness 与质量门禁 # Harness 与质量门禁
**更新日期**：2026-07-22 **更新日期**：2026-07-23
**状态**：当前可运行架构 **状态**：当前可运行架构
## 1. Harness 定位 ## 1. Harness 定位
@@ -12,7 +12,7 @@ Harness 是确定性执行边界，不承担业务推理。它统一管理：
- 类型化 retry policy；Diagnosis Agent 和 Tool 调用不自动重试。 - 类型化 retry policy；Diagnosis Agent 和 Tool 调用不自动重试。
- ToolBoundary、canonical invocation 与 Agent projection。 - ToolBoundary、canonical invocation 与 Agent projection。
- EvidenceGuard、Evidence repair、SemanticGuard 与 Release Policy。 - EvidenceGuard、Evidence repair、SemanticGuard 与 Release Policy。
- metadata-only durable audit。 - metadata-only durable audit、统一 Trace Timeline 与独立 reasoning 审计。
## 2. ToolBoundary ## 2. ToolBoundary
@@ -39,10 +39,26 @@ SemanticGuard 使用隔离的单轮模型调用，只接收原始 query、完整
## 5. Release Policy ## 5. Release Policy
- `SUPPORTED`：发布 Diagnosis Agent 原始安全 Draft 的 typed report。 - `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，不泄漏内部异常。 - technical failure：发布 stable failure，不泄漏内部异常。
- cancel/timeout：结束 exact Run，禁止 late content。 - 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 跟踪。
mvp/architecture/session-trace-lifecycle.md
+17 -1
View File
@@ -1,6 +1,6 @@
# Session、Run 与 Trace 生命周期 # Session、Run 与 Trace 生命周期
**更新日期**：2026-07-22 **更新日期**：2026-07-23
**状态**：当前可运行架构 **状态**：当前可运行架构
## 1. Identity ## 1. Identity
@@ -15,9 +15,11 @@
request accepted request accepted
-> start RunContext -> start RunContext
-> persist diagnosis_run RUNNING -> persist diagnosis_run RUNNING
-> append diagnosis_trace_event RUN_STARTED
-> metadata(session_id, run_id) -> metadata(session_id, run_id)
-> route / execute / guard / release -> route / execute / guard / release
-> SUCCESS | FALLBACK | FAILED | CANCELLED -> SUCCESS | FALLBACK | FAILED | CANCELLED
-> append diagnosis_trace_event RUN_FINISHED
-> persist terminal state and budget usage -> persist terminal state and budget usage
``` ```
@@ -31,9 +33,23 @@ disconnect、timeout 与 send failure 通过同一个 `ChatRunControl` 请求取
- exact `diagnosis_run` 状态、intent、release outcome、安全 answer 与预算。 - exact `diagnosis_run` 状态、intent、release outcome、安全 answer 与预算。
- `agent_step` metadata-only 模型步骤。 - `agent_step` metadata-only 模型步骤。
- `tool_invocation` metadata-only Tool durable audit。 - `tool_invocation` metadata-only Tool durable audit。
- `diagnosis_trace_event` 按 `sequence_no, id` 排序的统一生命周期 Timeline。
Redis canonical invocation 不是 Trace API 的长期响应内容；它只供当前 Run EvidenceGuard 验真。 Redis canonical invocation 不是 Trace API 的长期响应内容；它只供当前 Run EvidenceGuard 验真。
普通 Trace 不读取 `agent_reasoning_audit`，也不返回 reasoning 原文。Agent 模型步骤和 Timeline 只暴露 `reasoning_available`、`reasoning_bytes` 等有界 metadata。
## 4. PreviousTurn ## 4. PreviousTurn
应用在创建当前 Run 前读取同 Session 最近安全发布结果。只允许结构化 PublishedResult 的固定字段进入 PreviousTurn，且执行字节上限；完整历史、失败、Fallback、Tool raw data 和 guard reason 均排除。 应用在创建当前 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 收敛。
mvp/tables/Agent推理审计表-agent_reasoning_audit.md
+50
View File
@@ -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 跟踪；治理完成前不应将该接口暴露给普通业务用户。
mvp/tables/Agent步骤表-agent_step.md
+3 -1
View File
@@ -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.run_id` 逻辑关联 `diagnosis_run.run_id`。
- `agent_step.session_id` 保留为 `chat_session.session_id` 的冗余关联，便于粗粒度过滤和兼容查询。 - `agent_step.session_id` 保留为 `chat_session.session_id` 的冗余关联，便于粗粒度过滤和兼容查询。
- `tool_invocation.step_id` 可关联 `agent_step.id`，但当前允许为空且不强制外键。 - `tool_invocation.step_id` 可关联 `agent_step.id`，但当前允许为空且不强制外键。
- `agent_reasoning_audit` 通过相同的 `session_id + run_id + step_index` 逻辑定位模型步骤，不建立数据库外键。
## 注意点 ## 注意点
- 前端展示步骤时应使用 Trace API 返回顺序；服务端会在同一 `run_id` 范围内整理步骤顺序。 - 前端展示步骤时应使用 Trace API 返回顺序；服务端会在同一 `run_id` 范围内整理步骤顺序。
- 新 Trace 和验收读路径必须按 exact `run_id` 取数，避免同一 `sessionId` 多次运行混入。 - 新 Trace 和验收读路径必须按 exact `run_id` 取数，避免同一 `sessionId` 多次运行混入。
- 当前 Run 若出现 `diagnosis_agent` 之外的新写入，或 `thought` 非空，视为审计边界违规。 - 当前 Run 若出现 `diagnosis_agent` 之外的新写入，或 `thought` 非空，视为审计边界违规。
- `model_output` 可保存 `has_text`、`tool_names`、`reasoning_available` 和 `reasoning_bytes` 等有界 metadata，不得保存 reasoning 原文。
mvp/tables/README.md
+6 -2
View File
@@ -1,6 +1,6 @@
# MVP 数据表索引 # MVP 数据表索引
**更新日期**：2026-07-10 **更新日期**：2026-07-23
**状态**：当前表文档入口 **状态**：当前表文档入口
本目录保存当前 MVP 使用的数据表说明。详细结构以 Flyway migration 和实体类为准；本目录用于面试讲解、排查索引和快速理解数据流。 本目录保存当前 MVP 使用的数据表说明。详细结构以 Flyway migration 和实体类为准；本目录用于面试讲解、排查索引和快速理解数据流。
@@ -13,6 +13,8 @@
| `diagnosis_run` | `/api/chat` 运行主记录，保存 intent、终态与安全发布结果 | [诊断运行表-diagnosis_run.md](诊断运行表-diagnosis_run.md) | | `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) | | `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) | | `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) | | `api_document` | 知识库文档元数据，和向量库 chunk 通过 `doc_id` 关联 | [文档元数据表-api_document.md](文档元数据表-api_document.md) |
| `knowledge_domain` | 知识域元数据，支撑 RAG domain hint 和检索策略 | [知识域表-knowledge_domain.md](知识域表-knowledge_domain.md) | | `knowledge_domain` | 知识域元数据，支撑 RAG domain hint 和检索策略 | [知识域表-knowledge_domain.md](知识域表-knowledge_domain.md) |
| `case_library` | 用户反馈沉淀出的高质量诊断案例 | [案例库表-case_library.md](案例库表-case_library.md) | | `case_library` | 用户反馈沉淀出的高质量诊断案例 | [案例库表-case_library.md](案例库表-case_library.md) |
@@ -31,6 +33,8 @@ chat_session.session_id
-> diagnosis_run.session_id -> diagnosis_run.session_id
-> agent_step.run_id -> agent_step.run_id
-> tool_invocation.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) -> case_library.diagnosis_id (new AUTO cases use run_id)
diagnosis_session.session_id diagnosis_session.session_id
@@ -43,4 +47,4 @@ knowledge_domain.domain_id
-> api_document metadata.category / vector chunk metadata.category -> api_document metadata.category / vector chunk metadata.category
``` ```
当前实现主要使用逻辑关联，不依赖数据库外键。 当前实现主要使用 `session_id + run_id` 逻辑关联，不依赖数据库外键。`agent_reasoning_audit` 是敏感审计数据，不与普通 Trace、Evidence Snapshot 或业务结果合并读取。
mvp/tables/诊断Trace事件表-diagnosis_trace_event.md
+52
View File
@@ -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`。
mvp/tables/诊断运行表-diagnosis_run.md
+3
View File
@@ -45,6 +45,8 @@
- `diagnosis_run.session_id` 逻辑关联 `chat_session.session_id`。 - `diagnosis_run.session_id` 逻辑关联 `chat_session.session_id`。
- `agent_step.run_id` 逻辑关联 `diagnosis_run.run_id`。 - `agent_step.run_id` 逻辑关联 `diagnosis_run.run_id`。
- `tool_invocation.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`。 - 新的自动案例沉淀使用 `case_library.diagnosis_id = diagnosis_run.run_id`。
## 注意点 ## 注意点
@@ -53,3 +55,4 @@
- latest run 排序使用 `created_at DESC, id DESC`，避免 feedback 或自评估更新 `updated_at` 后改变回放目标。 - latest run 排序使用 `created_at DESC, id DESC`，避免 feedback 或自评估更新 `updated_at` 后改变回放目标。
- 历史 `diagnosis_session` 会被迁移成兼容 run，但旧混合数据不能被还原成真实多轮边界。 - 历史 `diagnosis_session` 会被迁移成兼容 run，但旧混合数据不能被还原成真实多轮边界。
- 当前诊断发布结果以 `release_outcome + published_result` 为准，不得从旧 self-evaluation 推断 Release Policy 结果。 - 当前诊断发布结果以 `release_outcome + published_result` 为准，不得从旧 self-evaluation 推断 Release Policy 结果。
- `diagnosis_run` 不保存 reasoning 原文；普通 Run/Trace 查询也不得通过聚合将其带出。