docs(mvp): align architecture and audit table design
This commit is contained in:
zhuyongxin
+11
-67
@@ -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、数据模型或验收口径。
|
||||
|
||||
@@ -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 跟踪，不能把“数据已分表”理解为“治理已经完成”。
|
||||
|
||||
@@ -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。
|
||||
|
||||
@@ -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/`。
|
||||
- 不根据本目录新增或修改运行时代码。
|
||||
- 不将本目录描述的接口和表结构视为当前契约。
|
||||
- 如需引用历史决策，应同时说明其归档日期和当前替代方案。
|
||||
|
||||
@@ -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 能力。
|
||||
|
||||
@@ -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 跟踪。
|
||||
|
||||
@@ -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 收敛。
|
||||
|
||||
@@ -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 跟踪；治理完成前不应将该接口暴露给普通业务用户。
|
||||
@@ -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 原文。
|
||||
|
||||
@@ -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 或业务结果合并读取。
|
||||
|
||||
@@ -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`。
|
||||
@@ -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 查询也不得通过聚合将其带出。
|
||||
|
||||
Reference in New Issue
Block a user