# Data Agent Studio 图资产说明

本目录的图分为两类：

## 主视觉图

用于课程开篇、项目 README、商品详情页和学习路径快速理解。

| 图 | 适合回答的问题 |
|---|---|
| `data-agent-studio-overview-polished` | Agent、语义层、查询服务和安全门如何协作？ |
| `data-agent-query-lifecycle-polished` | 一次自然语言问题怎样变成可复核回答？ |
| `data-agent-semantic-layer-polished` | 业务词汇怎样绑定指标和维度白名单？ |
| `data-agent-sql-safety-polished` | 查询为什么只能以只读、受控方式执行？ |
| `data-agent-web-workbench-polished` | 结果怎样在 Web 中做到可读、可核对、可追问？ |

## 技术细节图

技术细节图不再统一采用一种布局，而是按阅读任务选择图形：

| 类型 | 图 | 适合回答的问题 |
|---|---|---|
| 决策树 | `data-agent-sql-safety-decision-detail` | 一个查询经过哪些关卡，在哪些条件下被拒绝？ |
| 时序图 | `data-agent-multi-turn-sequence-detail` | 一次多轮追问如何在 Web、Agent、会话库、查询服务和 DuckDB 之间流转？ |
| 产品线框 | `data-agent-workbench-wireframe-detail` | 结论、结果、证据和会话操作在页面上如何分层？ |
| JSON 契约剖面 | `data-agent-structured-response-detail` | 一个 response 如何同时服务 UI、追问、审计和报告保存？ |
| 状态机 | `data-agent-mode-fallback-state-detail` | auto、rules、llm 如何选择真实路径，模型失败怎样可见地降级？ |
| 生命周期图 | `data-agent-report-snapshot-lifecycle-detail` | session、turn、report 如何创建、读取、追问和删除？ |
| 评测矩阵 | `data-agent-evaluation-matrix-detail` | 如何同时验证事实、安全、上下文、交互和交付？ |
| 传统流程图 | `sql-safety-execution`、`multi-turn-safe-drilldown`、`web-workbench-flow` | 模块边界和主链路如何衔接？ |
| C4 / 架构图 | `data-agent-studio-01-context`、`data-agent-studio-02-containers`、`data-agent-studio-03-agent-components` | 系统从上下文到组件如何拆解？ |

原有的 C4 架构、规则 Agent、LLM 规划器、语义层、报告版本化和商业交付图，继续用于章节中的实现细节和验收说明。总览图负责建立地图，细节图负责解释一个机制，时序图和线框图则负责解释运行过程与产品阅读路径。

## 文件格式

每张图都提供：

- `.drawio`：可编辑 Draw.io 源文件。
- `.png`：适合文档和页面展示的普通图片。
- `.drawio.png`：嵌入完整图模型的可编辑 PNG。
- `.mmd`：结构化 Mermaid 描述。

统一风格采用浅色分区、圆角卡片、语义配色和清晰留白。主视觉图负责建立产品直觉，技术细节图负责解释实现边界。