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/architecture/README.md
+7 -5
View File
@@ -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 跟踪，不能把“数据已分表”理解为“治理已经完成”。
mvp/architecture/agent-orchestration.md
+16 -1
View File
@@ -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。
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 的总体架构、链路、持久化和质量门禁 |
| [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/`。
- 不根据本目录新增或修改运行时代码。
- 不将本目录描述的接口和表结构视为当前契约。
- 如需引用历史决策，应同时说明其归档日期和当前替代方案。
mvp/architecture/current-mvp-architecture.md
+18 -3
View File
@@ -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 能力。
mvp/architecture/harness-quality-gates.md
+21 -5
View File
@@ -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 跟踪。
mvp/architecture/session-trace-lifecycle.md
+17 -1
View File
@@ -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 收敛。