# 基本信息梳理
## Links
### 官方网站
- [阿里云通知首页](https://www.aliyun.com/page-source/university/activity/aicompetition)
- [本科生院微信推文（正式通知）](https://mp.weixin.qq.com/s/WWdaiiOvqd1QRA86z21EMQ?scene=1)
- [百炼平台](https://www.aliyun.com/product/bailian)
- [智能体编排](https://bailian.console.aliyun.com/?spm=5176.29619931.J__Z58Z6CX7MY__Ll8p1ZOR.1.74cd521cQ7aD8R&tab=app#/app-center)
- [子账号登录](https://signin.aliyun.com/login.htm?callback=https%3A%2F%2Fbailian.console.aliyun.com%2F%3Ftab%3Dapp#/main)

百炼平台中“知识库”：

### 其他
- https://notebooklm.google/ 借助gemini的长上下文可以从pdf中提炼信息
- [项目仓库(chatSQL)](https://github.com/ffy6511/chatSQL)
- 暂定的会议时间: 每周三和周六 20:00, 以此为单个任务周期

## 时间节点与提交要求

1. **2025年7月15日前**：登录大赛网站 [https://kydh.zju.edu.cn](https://kydh.zju.edu.cn)，完成注册报名和提交申报书
2. **2025年8月15日前**：上传参赛作品及作品说明

## 阅读材料

- [上下文工程 context engineering (arXiv)](https://www.arxiv.org/pdf/2506.12115)
- [多智能体文章 ](https://mp.weixin.qq.com/s/OpuIHSwrq3vzVxNRmqogJQ)
- [提示词设计]( https://mp.weixin.qq.com/s/6iaW8OYSnruobcpDLUDxQQ)

## 任务梳理
> 1. 大赛将从创新性（30%）、功能价值（30%）、技术实施质量（20%）和用户体验与工程化（20%）四个维度对智能体作品及垂直领域模型作品进行综合评价
> 2. 面向小班教学、专精高深的专业课程教与学场景。例如，生成艰深知识带三维可视化效果的仿真案例，支持小班制下的因材施教

- [x] 明确呈现的具体形式（**作为iframe嵌入** or 以窗口为主，后者的可视化？）
- [x] 明确针对的具体知识内容
- [x] 参考一下阅读资料？
- [x] 明确分工和之后的实际进度安排

# 阶段分工
### 7.7
- zy
- 测试pdf和简单知识的召回率

- ljm
- 多智能体文章 & 提示词设计
- 回顾智能体编排

- zjh
- [x] 上下文工程
- [x] B+树渲染相关的组件库 / mermaid 代码渲染

### 7.12

- zjh:
- 对齐接口(ER)
- B+树的调试
- 删除:某个叶子key是父节点的最小值
- 「future」sql模块的删除和新建 / 考虑用mcp实现sql模块

- ljm:
- 各个节点的使用策略
- 阿里云平台的协作机制?
- zy:
- 整理知识图谱，创建知识库，测试

### 7.16
- zjh
- 继续尝试修复B+树:
- 法1: 参考可视化的JS文件, 转换为TS;
- 法2: 迁移js的可视化和算法
- 法3: 交给智能体?
- zy
- 继续搭建知识库
- 设计提示词
- 尝试模型调优
- ljm: 搭建基本的智能体框架

# 研究记录
## 7.7-7.12
### 日志
#### zjh
- 一个实现知识图谱的[mcp工具](https://bailian.console.aliyun.com/?spm=5176.29619931.J__Z58Z6CX7MY__Ll8p1ZOR.1.74cd521cQ7aD8R&tab=mcp#/mcp-market/detail/Knowledge%20Graph%20Memory)(?)
- 组件: 插件、**样例库**与提示词(?)
- github搜索
- 使用本地知识库与样例库需要首先创建智能体, 然后在工作流中选择使用已经创建的智能体
- mcp服务:
- 应用-mcp管理: 可以设置其他来源的mcp
- MCP🔥: 可以使用阿里云的mcp
---

**文献阅读**
- 对于高难度的问题可能需要推理，需要简单问答的问题只需要经过数据库节点；因此考虑首先评估问题的难易程度，然后整体分为两条支线？
- ?：如果是按照“主节点自主调用认知工具”的思想进行设计的话，那么把主节点会自主评估是否需要进行复杂推理叭。而知识库查询事实上无论问题简单还是复杂都是可以做的，所以就没有必要分支？
- 发现给出的“上下文工程”paper实际上是该方向的一个话题——认知工具
- 核心是：将认知心理学中的模块化认知操作理论引入现代LLM中，强调通过结构化方式激发LLM的潜在推理能力
- 阅读分析[链接](https://ffy6511.github.io/2025/07/08/Cognitive-Tools/)
- 或许可以将多智能体某一步需要解决复杂问题的节点，拓展为paper中介绍的主LLM与认知工具的组合？（主LLM决定调用工具/结束调用， 认知工具之间并联，然后反向连接到主LLM进入循环）
- 然而实际上，这种用认知工具促进推理能力的方式，与经过后训练的强化学习的模型相比，更多的优势可能在于其检查和回溯的机制，尚不清楚时间上是否存在优势？以及，非深度思考+认知工具 与 深度思考的token消耗量也需要比较？
- github-repo: [12-factor-agents](https://github.com/humanlayer/12-factor-agents) 描述了构建agents的一些要点, 第三部分就是上下文工程
- 对应的[Youtube链接](https://www.youtube.com/watch?v=yxJDyQ8v6P0)
- BAML相关:
- [github-repo](https://github.com/BoundaryML/baml)
- [其他介绍](https://thedataexchange.media/baml-revolution-in-ai-engineering/)
- > a domain-specific language that transforms prompts into structured functions with defined inputs and outputs
- 启示: 在工作流设计中除了对输入、输出规定基本类型的限制, 还可以通过BMAL客户端的方式设计复杂的class(这种方法相对在本地更好? 如果与dify类型平台结合, 需要将BMAL客户端部署在服务器上, 与节点通过api交流)
- 更多阅读: [context-engineering](https://github.com/davidkimai/Context-Engineering.git)

---

**代码直接渲染效果分析**
- 目的是对比两个方案在ER图和B+树之间可视化方面的差异
- A：LLM用mermaid直接渲染（可用mcp）
- B：使用前端组件库
- 结论：
- 平台上无法直接使用artifacts来渲染代码的执行结果
- 缺少对应的解释器插件
- 唯一相关的插件`QuickChart`也无法生成对应的图片
- mermaid的ER图无法使用菱形，通过让llm直接返回mermaid代码，然后在前端调用mermaid渲染器的方法也不行
- 属于不同的规范
- 解决方法大致两个：1. 容许另一种规范的mermaid渲染的ER； 或者引导llm直接生成图像。2. **自定义一个mcp / 前端组件**

---

**B+树渲染相关**

~~- 尝试使用minisql中给出的[渲染方案](https://dreampuf.github.io/GraphvizOnline/?engine=dot#digraph%20G%20%7B%0A%0A%7D), 也就是`graphviz DOT`
- 感觉效果还可以,利用初步的提示词和示例构建了一个智能体(节点)~~

不行 可交互性太低了 还是打算使用xyflow**从底层构造**

---
**ER图可视化**
- 使用reactflow的custom node
- json作为组件的输入(属性、实体、关系)

e.g.

 {
   "entities": [
     { "id": "ent_department", "name": "部门" },
     { "id": "ent_employee", "name": "员工" }
   ],
   "relationships": [
     {
       "id": "rel_belongs_to",
       "name": "属于",
          "connections": [
            {
              "entityId": "ent_department",
              "cardinality": "1",
              "isTotalParticipation": false // 部分参与 
            },
            {
              "entityId": "ent_employee",
              "cardinality": "N",
              "isTotalParticipation": true // 完全参与
            }
          ]
        }
      ]
}

> 因此, llm节点的输出应为符合要求的json

### 总结
第一个研究周期内, 我们按照分工主要完成了三方面的任务:
1. 探索阿里云百炼平台的功能, 了解知识库、样例库、mcp服务与工作流节点与基本的设计技巧. 发现平台本身的知识库只支持结构化和非结构化的数据来构造知识库, 但是存在转换为知识图谱的[mcp服务](https://bailian.console.aliyun.com/?spm=5176.29619931.J__Z58Z6CX7MY__Ll8p1ZOR.1.74cd521cQ7aD8R&tab=mcp#/mcp-market/detail/Knowledge%20Graph%20Memory), 将继续研究该mcp的作用; 平台给出了知识库的[另一种实现](https://help.aliyun.com/zh/model-studio/rag-knowledge-base-api-guide?spm=a2c4g.11186623.0.0.56ea25b4Y0XZ1S#38d7298dabtb0), 需要继续阅读文档
- 构建知识库所用的材料: 目前考虑先使用教材pdf + 课程ppt等已有的标准资料, 然后人为构建数据集


2. 阅读关于多智能体、上下文工程、提示词设计的[三篇推文/paper](#阅读材料), 转化为工作流设计的经验有:
- 对于自然语言的输入(不另外设置tag), 让输入之后的节点分析问题类型, 整体分流为 RAG查询 与 复杂问题推理两条支线
- 对于复杂问题推理, 利用[认知工具](https://ffy6511.github.io/2025/07/08/Cognitive-Tools/)激发模型的推理能力(开发阶段考虑与开启深度思考的单一节点并联, 比较二者的效果, 如果各有优劣就可以共存);
- 对于每个节点, 评估应从单一节点的效果入手, 而非在搭建完工作流之后才开始进行. 对于单个节点, 评估给定输入得到的输出效果, 进而针对性修改 **提示词、样例库、知识库** 等三方面的输入
- [BAML](https://github.com/BoundaryML/baml) 通过定义一系列的`class`, 将提示词转化为具有明确输入和输出类型的函数, 可以提高输入的信息密度与输出的精度. 但是BAML依赖于客户端, 如果要接入百炼平台, 需要将BAML部署到服务器上并通过`api节点`来通信, 考虑实现的优先级较低. 因此当前给我们的启示是: 在output之前设置一个节点用于输出类型的检查
- 调用mcp的时候, 对工具的描述很重要. 需要重视提示词中对工具作用的描述和使用场景.

e.g. 检查输出类型

3. 梳理chatSQL当前的功能与实现, 进而使用相似的方法和风格在前端完成B+树和ER图的基本实现. 之后将在此基础拓展更多的功能, 目前考虑的有:
- 对于ER图, 一方面设计一些固有的样例来辅助说明基本概念与绘制方法; 另一方面, 允许用户利用前端工具按照工作流返回的题目要求绘制ER图, 并与标准答案比较(要求额外的工作量较大)
- 对于B+树, 一方面需要进一步测试当前实现,比如删除后合并、插入时分裂的正确性; 另一方面计划实现“断点”式可视化B+树操作流程. 这一部分的工作主要在前端完成. 从用户交互方面来看, 可能的题目设计是: 给定一个B+树, 用户绘制题目所说的操作之后的B+树并与答案进行比较.

e.g. B+树基本实现:

e.g. ER图基本实现:

> [下一周期的任务安排](#7.12)

## 7.12~7.16
### zjh
- 基本完成了ER图模块与智能体无关的功能, 绘制ER图的输出接口请参见[ER图渲染接口](#ER图渲染接口)
- 将ER图部分接入到了主页中,合并到`main`并部署到[vercel](https://chat-sql-hazel.vercel.app/)
- \*-* B+树算法果然还是有问题orz
- 法一: 参考[这个可视化](https://www.cs.usfca.edu/~galles/visualization/BPlusTree.html)的 JS文件
- 法二: 啊啊啊不知道, 难道交给智能体吗..
- 在智能体设计方面, 考虑采取多个并联的推理, 分别完成特定的code、 bplus、 ER以及一般的推理任务, 目的是为了更好利用样例库和提示词
- 可能有用的[免费api](https://github.com/public-apis/public-apis)

### zy
小小的问题：pdf拆分、PPT、智能体返回结果不完整、思考过程过慢

测试问题：

- E-R图：

为一个汽车公司设计一个数据库,用于协助它的经销商维护客户记录以及经销商库存,并协助销售人员订购车辆。
每辆车由车辆编号(Vehicle Identification Number,VIN)唯一标识,每辆单独的车都是公司提供的特定品牌的特定模型(例如,XF是塔塔汽车捷豹品牌的模型)。每个模型都可以有不同的选项,但是一辆车可能只有一些(或没有)可用的选项。数据库需要保存关于模型、品牌、选项的信息,以及每个经销商、顾客和车的信息。
你的设计应该包括E-R图、关系模式的集合,以及包括主码约束和外码约束的一组约束。

在回答这类题时有什么需要特别注意的地方？

- 概念：

请解释一下视图的概念

...完整性约束的概念

- 关联性问题：

在高并发环境下，如何避免“幻读”问题？

这与数据库系统这门课的哪些知识点有联系？

（这个表现比较好）

## 7-17~7.20
### 7.17 日志记录
#### zjh
- 完成了B+树的算法代码迁移与基本测试
- 可视化方面还需要进一步优化
- fix了主页的“初始化教程”, 并feat了进度提示与持久化
- 一些官方教程:
- [工作流应用](https://help.aliyun.com/zh/model-studio/workflow-application/?spm=a2c4g.11186623.help-menu-2400256.d_1_1_2.21637ef5YMXojA) 等工作流设计相关
- [样例库](https://help.aliyun.com/zh/model-studio/prompt-sample-optimization?spm=a2c4g.11186623.help-menu-2400256.d_1_3_8.da2e571dOT0pos)等上下文工程相关
- [应用调用](https://help.aliyun.com/zh/model-studio/application-calling-guide?spm=a2c4g.11186623.help-menu-2400256.d_1_5_0.4be1366bfORS5m): 前端调用的格式
- [RAG效果优化](https://help.aliyun.com/zh/model-studio/rag-optimization?spm=a2c4g.11186623.help-menu-2400256.d_1_10_6.5a95734d6Pq0hb): 似乎md格式更好)
- [讲解loop实现方式的视频](https://www.bilibili.com/video/BV1uy4Ge1ER6?vd_source=fffec460bd96bbad89da4f036afcb48b)
- 分别是for 和 while 循环在coze上的实现 (百炼平台类似)
- @VCAnf0JWR2-S6aINoXResA 可以参考并用于搭建推理所需的loop

可以将并联的三大模块的推理路线先用单独的工作流完成, 然后在总工作流中使用工作流节点?

---
dev调试:
- command + O/P: 打开文件
- command + shift + O: 跳转到对应的函数或者变量

### 7.20 任务
#### zjh
- 检查并调整B+树的动画序列
- 将B+树接入项目
- 修复ER的删除问题

#### zy
- 继续完成RAG相关的节点
- 阅读 [RAG效果优化](https://help.aliyun.com/zh/model-studio/rag-optimization?spm=a2c4g.11186623.help-menu-2400256.d_1_10_6.5a95734d6Pq0hb) 的官方文档并决定是否采取这种方式

#### ljm
- 阅读[讲解loop实现方式的视频](https://www.bilibili.com/video/BV1uy4Ge1ER6?vd_source=fffec460bd96bbad89da4f036afcb48b), 尝试搭建推理工具对应的工作流
- 可以参考 [工作流应用](https://help.aliyun.com/zh/model-studio/workflow-application/?spm=a2c4g.11186623.help-menu-2400256.d_1_1_2.21637ef5YMXojA) 等工作流设计相关的官方文档

## 7.21-7.23
### 7.23日志记录
#### zjh
- done：
- 在cmd中新增NodeState实现溢出节点的可视化，以及key的高亮
- BPlus页面的整体UI设计与存储功能
- doing：B+树可视化集成
- 发现基于Nodes,Edges来渲染更加适合xyflow的实现方式，方便实现断点/步骤回溯功能，以及让智能体通过nodes，edges字段在内的回复来可视化B+树的结构
- 解耦控制组件与可视化组件（状态提升问题）
- todo：
- 继续完成Bplus集成以及ER图模块的fix
- BPlus:批量插入与删除key的功能

### 7.24 任务
无
> 放假几天

## 7.24-7.27
### 7.27 日志记录
#### zjh
- 在开发todo中做了一些工作，改进了ER与Bplus的UX；
- 敦促了 @VCAnf0JWR2-S6aINoXResA 尽快开发简单的智能体，供前端测试通信；
- 思考了ER部分涉及的智能体功能和接口：

// 输入
总是一个对话框的文本输入 + （可选的）ER会话id/内容的输入

// 智能体的输入和输出：
输入：description + ERDiagramData(可选)  
输出：analyse + ERDiagramData(可选) + schemaData（可选）

> `ERDiagramData`的字段请参考[ER接口](#ER图渲染接口)
> 输出 `schemaData` 的情况是用户希望通过ER图生成对应的schema并可视化（可能需要前端检测到之后自动切换路由并显示，并且需要前端为其计算哈希值生成唯一的id来存储于历史记录中）
- chatbot设计
> [api调用](https://help.aliyun.com/zh/model-studio/application-calling-guide?spm=a2c4g.11186623.0.0.105f3446uOzAKp#93931bcdf93h8)

## 7.27-7.30
### 7.30 日志记录
#### zjh

---
- [学习模式（苏格拉底式对话）](https://simonwillison.net/2025/Jul/29/openai-introducing-study-mode/): 可以考虑是否开启这个模式？不过看上去并没有公布完整的提示词，可能需要借鉴思路并适当扩充和矫正？
- [上下文工程综述](https://arxiv.org/abs/2507.13334)

---

### 7.30 任务
zy
- 通用问答智能体：
- 历年卷题目搜集与整理
- 使用英文教材做知识库

zjh
- chatBot：继续开发

ljm
- coding：在dify上修正

## 7.31-8.3
### 8.3 日志记录
#### zjh
- renderer: md / sql / json
- 创建了 `/chat-sql/src/styles/theme.ts` 文件, 用于全局设置对MUI相关组件的CSS变量配置;
- 创建了 `/chat-sql/src/components/common/Snackbar.tsx` 组件, 并且通过context集成到全局,可以如此使用:

// 导入
import { useSnackbar } from '@/contexts/SnackbarContext';

// 解析和使用
const { showSnackbar } = useSnackbar();
showSnackbar('操作成功', 'success'); // 支持'success'|'info'|'warning'|'error'

### 8.3 任务安排
#### zjh
- 尝试流式输出
- 字体大小的设置(确保em)
- ER名称为空的检查(`SortableAttributeItem`)

#### ljm
- 设计logo

#### zy
- 继续整理题目相关的知识库

## 8.4-8.6
### 8.6日志记录
#### zjh
- 在`theme.ts`中修改了MUI全局样式的字体样式, 同时在 `typography.css` 中使用 `clamp` **流式调整**字体的大小
- 重构了 `SortableAttributeItem` 的rename逻辑, 减少props的传递, fix了无法清空的问题;
- 优化了整体布局(sidebar / navbar的button)
- 优化了ER的绘制体验:
- 增加了右键画布以绘制实体/关系的功能
- 同时考虑到属性的编辑需要在右侧的面板中实现,增加`PinnedQuizDisplay`模块,使得问题描述可以直接 **ping** 到画布的右上角,方便同时查看问题、创建实体/关系和编辑相关属性

> 
> 未来考虑扩展该功能(记录位置和尺寸以支持移动和伸缩)

- 部署在了课题组的服务器上,但是还没有使用nginx等实现反向代理

---
其他:
- `git tag`相关的知识
- 暂不考虑实现流式输出, 原因如下:
- 一方面为了更好组织和显示智能体返回的字段,我们只之前在前后端之间按照如此格式进行信息的传输:

{
    {
    type: text | sql | json  
    content: ...
    }
    ... (数组)
}

并且是基于智能体的非流失输出结果转化得到, 但是经过分析文档和实践,流式输出结果的形式为:

data: {"type":"chunk","data":{"text":"您好","sessionId":"4e67e0077c8d463fb9083f9dce6fe785","isComplete":false}}

data: {"type":"chunk","data":{"text":"！","sessionId":"4e67e0077c8d463fb9083f9dce6fe785","isComplete":false}}
...

data: {"type":"done"}

> 所以需要额外的时间和逻辑来处理差异

另一方面,中间结果输出?帮助不高; 只是输出结果的话,由于工作流的大部分时间都耗费在中间过程,所以仅对占比较小的结果进行流式输出,效益不高

---
- prettier
- `npx prettier --write .`
- react-dev-tool

- 后端与智能体通信的架构图:(多智能体系统)

> 主要聚焦于chatBot与智能体的通信,缺少智能体内部的流程描述?

### 8.6 任务
zjh
- 等待ljm绘制颜色合适的logo,然后录制视频
- 做ppt(技术实现的前端和衔接部分)

ljm
- 选择logo的颜色
- 绘制框架流程——ppt资料
- 技术实现(智能体)

## 8.6-8.10
### 8.10日志记录
#### zjh
- 完成了介绍视频的录制和剪辑
- 一些微不足道的工作：
- 增加了md renderer对Latex的渲染支持；修复了coding中编辑器hover时在亮色模式下显示不当的问题；增加了ER出题的难度输入；修复了sortableItem的属性修改问题
- 完成部分ppt的撰写
- 发现
- 知识图谱的构建：[Neo4j](https://llm-graph-builder.neo4jlabs.com/)
- [Arxiv: Unified Knowledge Graph Construction](https://arxiv.org/abs/2406.02962)
- 或者尝试 lightRAG?

# 开发TODO
在这里记录了chatSQL开发过程中没有解决的问题，类型大致分为：
- `chore` ：表示暂时无关紧要的细节,也可以是文档内容；
- `fix`：已有功能上需要修复的；
- `feat`：需要通过新增组件或者功能函数来实现新的功能；
- `style`：样式上需要改进的，比如部分模块的暗色模式适配，或者布局上的优化；
- `perf`：不影响现有功能，通过重写代码来优化性能的；

您可以在体验网站或者开发的任何时间添加todo项。

如果您要添加todo项，请尽可能符合上述的类别，并且用足够的语言描述（比如涉及的模块文件）来讲解要做的事情（如果您知道大致应该如何做的话），方便他人或者自己在之后回溯。

---

**协作说明**：
1. 如果需要专注于某个模块进行大幅度的修改，请**提前告知**其他组员（避免之后合并时需要复杂的检查）并**新建分支**；
2. 可以参考zjh在augment中的系统提示词：

- 始终使用中文回答.
- 确保给出的ts代码符合类型约束规范, 不要存在any等类型问题, 全部任务完成后确保可以通过 npm run build 并且没有报错
- react框架下鼓励使用material- UI组件库;
- 复杂函数需要在开头有一行的注释;
- 使用css变量来对文字的颜色赋值, 比如用 var(--secondary-text) 代替 text.secondary
- 对于拖拽组件，总是使用下面的组件：
// 拖拽组件
import { Panel, PanelGroup, PanelResizeHandle, ImperativePanelHandle } from "react-resizable-panels";

...

> 比较关键的是，push或者至少在merge到main分支之前确保build不存在错误（这样vercel才能正常部署）；对于常见的模块（比如拖拽和modal、table等），尽可能使用MUI中现成的组件，并且使用`globals.css`中的css变量来完成暗色模式的适配

3. 在todo列表中，如果你希望开始做某项任务，请给出标注 e.g.

// 在fix模块下

- [ ]ER(zjh-doing):修复ER中节点编辑未持久化的问题，建议检查编辑之后的存储相关调用

---

## fix
- [x] ER(zjh-doing):取消PK的时候需要检查该属性是否为实体的唯一PK，因为一个实体必须至少有一个属性作为PK。如果不满足条件，通过Alert的warning来报错；
- [x] 发现name和PK等的修改局限于UI，修正
> SHA: b86a9de914cf477bd50d3b1f77eda3b8075958bf
- [ ] Coding：外键的连接逻辑。PK/FK可能是多个构成一组，但是当前是一一对应的，并不合理，需要改进；
- [ ] Coding：schema的属性中缺少了是否允许为 `null` 的设置，需要新增
- [x] ER(zjh-doing): 实体属性的增加与删除.在对应的inspector面板中展开后，应当允许设置是否删除
> SHA: 032bfa7367445067cad565e3b917d0ddcdaa720c
- [x] Bplus: 新建对话渲染的结果是上一次选择的有效会话（也就是没有清空）
- [x] ER：关系的自定义属性
- [x] chatBot：刷新之后无法在未选中的会话中输入内容
- [x] ER: 历史记录的会话存储

## feat
- [x] Bplus(zjh-doing)： 让插入和删除支持通过空格分隔的批处理
> SHA: 2db15951e5ae25bc436fb961f8510e792b8dd108
- [x] Coding(zjh-doing): 增加清除答题进度的button，也就是将indexDB中对应的进度清空；
> SHA: 59a3e8438aec1e40cfbeeba8a79d8a9ad9a73529
- [ ] 发现只有教程系列的才有进度指示，修正（在重新设计coidng接口的时候一起解决）
- [ ] ER：选中关系后高亮对应实体的边。（在当前的自动布局算法下可能不太重要，因为可读性已经有了一定保障）
- [ ] Coding：将查询语句分块，按照from..的顺序允许查看中间结果（属于幻想时间了x 目前的设置似乎不允许我们这么做，但是实现的话效果应该不错）
- [ ] Bplus：考虑将中间步骤也用nodes和edges渲染 就可以达到真正的断点效果(重新引入断点)
- [x] ER: 智能体模块——将ER转换为schema并绘制（可能需要切换ER模块的canvas， 支持混合的视图切换显示？）。 之后考虑将得到的schema作为coding模块的智能体输入，据此生成样例数据和问题等

## style
- [ ] Bplus: 操作步骤的时间轴样式
- [x] ER：关系模块的展开项样式
- [ ] ER：canvas中右下角控件的样式（不是透明的），没有与另外两个保持一致。zjh已经在globals中设置了统一的样式，可以直接检查className并修改；
- [x] ER：双击实体节点名称尝试重命名时，命名框溢出（大小不合适），可能是检查`InlineEditor`文件来调整样式

- [x] Bplus（zjh-doing）：增加一个空白提示. 可以参考当前的ER的空白效果，文件为`EmptyState`. 注意动画速度的控制面板在没有选中会话的时候也不要显示（在可视化组件`BPlusTreeVisualizer`中根据settings设置）
> SHA: 38fd95f83710f5f5fbbfb03cc68e7217c5db9e93
- [x] ER：暗色模式的适配（主要是MUI的相关组件用css变量设置）
- [x] ER：关系没有额外属性 / 说明的时候，hover的提示
- [x] chatBot：普通对话+ddl会导致sidebar显示异常
- [x] chatBot：ER的调用没有进入loading状态

## chore
- [x] ER（zjh-doing）：sample数据好像出现了问题，检查名称是否对应
- [x] 同时改进了新建图表的操作体验（快捷键与默认名）
> SHA: dad0389de1b1a578cf80c242da14a8735776a1eb

## perf
- [ ] Coding：将dify上的工作流拆分为两个——1.根据“难度”、“标签”和用户给出的大方向描述生成一个清晰的自然语言的数据库建模问题； 2.由自然语言描述生成对应的schema（和数据）
- [x] ER: 3. 提供自然语言描述和schema生成E-R图； (结合2可由自然语言生成ER图)
- [ ] Coding：当前改变选中的历史记录项，总是可能导致列表项等部分的闪烁，怀疑是重复渲染的问题。可能的考虑是：使用`useRef`注册历史记录的选择项, 避免其他组件重复渲染；
- [ ] All：参考[提示](#使用全局统一的Snack-Alert), 将所有antd的message提示样式修改为MUI的这个Alert，方便暗色模式的适配与风格的统一；
- [x] Bplus(zjh-doing):检查并修正`bPlusTreeToReactFlow`(似乎冗余)
- [x] 已经将其改写为`type`中的文件
> SHA: dad0389de1b1a578cf80c242da14a8735776a1eb
- [x] All: 封装常用的组件（studying...）

## Tips
### 使用全局统一的Snack-Alert
zjh在globals.css中为亮暗色的alert设置了对应的css变量属性，我们可以据此使用MUI的这个组件：

e.g.

// 也就是用MUI的snack组件代替antd的message提示组件
// 具体请参考设计(Bplus的page)
<Snackbar
    open={snackbar.open}
    autoHideDuration={3000}
    anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }}
    onClose={handleSnackbarClose}
    >
    <Alert
      onClose={handleSnackbarClose}
      severity={snackbar.severity}
      sx={{
        width: '100%',
        bgcolor: `var(--${snackbar.severity}-bg)`,
        color: 'var(--snackbar-text)',
        '& .MuiAlert-icon': {
          color: `var(--${snackbar.severity}-icon)`,
        }
      }}
    >
      {snackbar.message}
    </Alert>
</Snackbar>

# Agent
### 智能体接口
#### 1. ER图绘制智能体

绘制ER图

- Input：
- natural_language_query: 自然语言描述的数据库建模问题
- provided_schema: 已经设计好的SQL DDL
- Output:
- ER_draw: 绘制好的ER图，特定json格式

> 同前端要求的格式

---

#### 2. Schema设计智能体

根据自然语言描述的问题，设计schema，给出SQL DDL

- Input
- natural_language_query: 自然语言描述的数据库建模问题
- Output
- 一段文本: schema，SQL DDL

> 该智能体可作为ER图绘制智能体的前置节点，解决需要provided_schema输入的问题

---

#### 3. 出题智能体

- 用户可能只提供一些零星的暗示甚至可能几乎不提示，由该智能体产生一个**清晰的**、**表述合理的**数据库建模问题，对其中细节有明确描述，没有歧义。
- Input:
- description: 出题主题描述等
- difficulty: 难度——'简单'、'中等'、'困难'

- Output:
- 一段文本: 自然语言描述的数据库建模问题

#### 4. ER-Evaluation Agent

评估用户绘制的ER图，评估结果也可以作为进一步完善绘制的提示。

- Input

- query: 默认输入

- question: 原始数据库建模问题
- ER_ref: 先前绘制E-R图时生成的参考答案
- ER_user: 用户绘制的E-R图，json格式

> 格式形如
>
> ```json
> {
> "original_problem": "请设计一个药品管理系统的数据库模型。该系统用于管理医院的药品库存和使用情况。医院有多个科室，每个科室可以使用多种药品。药品由供应商提供，每种药品有多个规格。医生可以开具处方，患者凭处方领取药品。每个处方对应多个药品，且每个药品在处方中有一个明确的用量。请详细考虑药品、供应商、科室、处方、患者和药品规格之间的关系。",
> "model_answer_er_diagram": {},
> "user_er_diagram": {}
> }
> ```
>
>

- Output:
- 一段文本: 评估结果，一段话；

注：
> 在E-R图练习的时候:
>
> 情况1. 用户只是想练习ER图，但是手里没有题目； 可以调用 `3出题 - 2设计schema - 1绘制ER图`
> 情况2. 用户已经有一个数据库建模的问题，想让智能体建E-R图作为参考； 可以调用 `2设计schema - 1绘制ER图`

具体实现见百炼平台
### ER-Draw-Agent
status: finish
#### design

绘制ER图

- Input：

- natural_language_query: 自然语言描述的数据库建模问题
- provided_schema: 已经设计好的SQL DDL

- Output:

- ER_draw: 绘制好的ER图，特定json格式

> 同前端要求的格式

#### 架构

graph LR
    subgraph "用户空间"
        A["用户输入<br>(NL Query + Schema)"]
    end

    subgraph "工作流编排器 (代码层)"
        B(Orchestration Engine)
        C{"State<br>(Context, History...)"}
        D[ToolShed<br>- SchemaParser<br>- NLEnricher<br>- SelfVerifier<br>- ERD_Formatter<br>- KnowledgeQuery]
        E["最终结果<br>(E-R Diagram JSON)"]
    end

    subgraph "智能体 (LLM)"
        F["Main Agent"]
    end
    
    A --> B
    B --> C
    C --> |1. 打包State| F
    F --> |2. 返回决策<br>含thought/output/next_step| B
    B --> |3. 根据next_step<br>从ToolShed选择工具| D
    B --> |4. 将output<br>作为输入调用工具| D
    D --> |5. 工具返回结果| B
    B --> |6. 用结果更新State| C
    C --> |7. 再次打包State...| F
    
    B -- 调用ERD_Formatter成功后 --> E
    E --> |"返回给用户(前端渲染)"| A

### NL-Schema-Agent
status: finish
#### design

实现一个智能体，能够理解用户以自然语言描述的数据库建模需求，并自动生成结构化、可执行的SQL数据定义语言（DDL）代码，以完成数据库的初始化建表工作。

##### **输入 (Input)**

一段用自然语言清晰描述的数据库建模需求。
* **示例**: "我需要一个管理在线课程的平台。教师可以创建多门课程，学生可以报名参加多门课程..."

##### **输出 (Output)**

一段结构化、可执行的SQL数据定义语言（DDL），用于创建数据库表结构。
* **示例**: `CREATE TABLE teachers (...); CREATE TABLE students (...); ...`

#### 架构

本智能体采用四阶段的**串联工作流（Linear Workflow）**模式实现，每个阶段都是一个专用的LLM节点，负责一项独立的任务，并将处理结果传递给下一阶段。

##### **阶段 1: EntityIdentifier (实体与关系识别)**

此阶段是整个流程的入口。它负责对原始的、非结构化的自然语言需求进行初步解析。
* **任务**: 识别出需求描述中核心的名词概念作为**实体（Entities）**，并提取出描述实体之间如何交互的**高层次关系描述（Relationship Descriptions）**。
* **输出**: 一个包含实体列表和关系描述列表的JSON对象。

##### **阶段 2: AttributesIdentifier (属性与约束定义)**
在识别出核心实体后，此阶段深入细节，为每个实体构建其内部结构。
* **任务**: 依据自然语言描述，为上一阶段输出的每个实体，定义其具体的**属性（Attributes/Columns）**，并推断出合适的**数据类型**（如 `INT`, `VARCHAR`）和**约束**（如 `PRIMARY KEY`, `NOT NULL`）。
* **输出**: 一个详细的JSON对象，描述了每个实体的名称及其完整的属性列表。

##### **阶段 3: ArchitectureDesigner (架构组装与外键规划)**

这是流水线中最核心的逻辑处理单元。它负责将概念性的关系，转化为具体的数据库实现方案。
* **任务**: 综合前两步的结果，分析关系描述的类型（一对多、多对多），并决定如何实现这些关系。对于**一对多**关系，它会在“多”的一方表中添加**外键**；对于**多对多**关系，它会设计一个全新的**中间表/连接表（Junction Table）**。
* **输出**: 一份完整的“逻辑Schema计划”JSON，其中包含了所有表的最终字段定义以及清晰的外键关联规划。

##### **阶段 4: DDLGenerator (DDL代码生成)**

这是流水线的最后一站，负责将机器可读的逻辑计划“翻译”为人类可用、机器可执行的代码。
* **任务**: 读取上一阶段生成的完整逻辑Schema计划，并将其精确地转换为标准的SQL `CREATE TABLE` 语句，包括所有的字段、数据类型、约束和外键定义。
* **输出**: 最终的、纯净的SQL DDL文本字符串。

##### 流程图

flowchart TD
    A["Input<br>(自然语言需求)"] --> B{Stage 1: EntityIdentifier};
    B -->|Entity List &<br>Relationship Descriptions &<br>NL Query| C{Stage 2: AttributesIdentifier};
    C -->|Entities with Attributes &<br>Relationship Descriptions &<br>NL_Query| D{Stage 3: ArchitectureDesigner};
    D -->|Final Logical Plan with Foreign Keys &<br>Relationship Descriptions &<br>NL_Query| E{Stage 4: DDLGenerator};
    E --> F["Output<br>(SQL DDL 字符串)"];

    %% Styling 原来mermaid还能做这种事
    classDef stage fill:#e8f5e9,stroke:#333,stroke-width:2px;
    class B,C,D,E stage;
    classDef io fill:#e1f5fe,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    class A,F io;

### Question-Agent
status: finish
#### design

- 用户可能只提供一些零星的暗示甚至可能几乎不提示，由该智能体产生一个**清晰的**、**表述合理的**数据库建模问题，对其中细节有明确描述，没有歧义。
- Input:
- description: 描述
- difficulty: 难度 ['simple', 'medium', 'hard']
- ...(如果未来需要增加的话)

- Output:
- 一段话: 自然语言描述的数据库建模问题

#### architecture

一个模型过一个RAG

因为出题这件事本身就没有很精确的答案，所以从知识库中直接利用Embedding模型的匹配能力，检索和description最接近的几道题目，让模型进行参考和修改，相对而言还是比较可靠的。

- ~~当用户没有输入description的时候，使用随机数作为缺省值？~~（x)

> 直接将一个随机数输入给向量检索模型是**不可行**的。因为向量检索是基于**语义相似度**的，一个随机数（如 `0.12345`）没有任何语义，因此无法在知识库中匹配到任何有意义的题目。

- 但可以定义一个预设种子主题列表，从中随机抽取作为description
- 如:["社交媒体", "电商平台", "图书馆管理", "医院挂号系统", "博客系统", "人力资源管理"]

graph LR
    subgraph "用户"
        A["Input<br>(可选: description, difficulty)"]
    end

    subgraph "出题智能体系统"
        B{有description吗?}
        C["从'种子主题'列表<br>随机选一个"]
        D["向量检索<br>(Vector Search)"]
        E[知识库]
        F["LLM<br>(创意生成)"]
    end
    
    subgraph "输出"
        G["Output<br>(高质量的数据库建模问题)"]
    end

    A --> B
    B -- Yes --> D
    B -- No --> C --> D
    
    E --> D
    D -- 检索到的题目(数条) --> F
    A -- 原始输入(description, difficulty) --> F
    F --> G

**保证质量与相关性**: 通过从一个预先准备好的、高质量的“数据库建模问题”知识库中检索，可以确保LLM的创作不是天马行空，而是围绕着实际、经典的建模场景展开。

**避免重复与死板**: 它不是简单地从知识库里随机抽一道题，而是让LLM将检索到的题目作为“灵感来源”，进行重新组合、修改和创作，从而生成一道**全新的、独一无二的**题目。

**可控性**: 用户的输入`description`可以有效地引导检索方向，实现“命题作文”；`difficulty`可以用来指导LLM最终生成的复杂程度。

---

##### 种子主题

{
  "核心业务系统": [
    "电商平台",
    "在线外卖平台",
    "超市POS与库存管理",
    "团购系统",
    "二手交易平台",
    "仓储管理系统 (WMS)",
    "订单管理系统 (OMS)",
    "物流与运输管理 (TMS)",
    "生产制造执行系统 (MES)",
    "供应商关系管理 (SRM)",
    "银行核心系统",
    "在线支付与账单系统",
    "股票交易系统",
    "保险业务系统",
    "人力资源管理 (HRM)",
    "招聘管理系统 (ATS)",
    "企业资产管理",
    "会议室预订系统"
  ],
  "公共服务与社会生活": [
    "医院挂号系统",
    "电子病历系统 (EMR)",
    "体检中心管理系统",
    "药品管理系统",
    "学校教务管理系统",
    "在线学习平台",
    "图书馆管理系统",
    "科研项目管理系统",
    "机票预订系统",
    "酒店预订系统",
    "网约车平台",
    "公共交通查询系统",
    "停车场管理系统",
    "电影院票务系统",
    "音乐流媒体平台",
    "视频分享平台",
    "活动与票务平台"
  ],
  "垂直与工具类应用": [
    "社交媒体",
    "博客系统",
    "在线论坛/BBS",
    "问答社区",
    "即时通讯系统 (IM)",
    "项目管理系统",
    "云盘文件同步系统",
    "在线文档协作系统"
  ]
}

### ER-Evaluation-Agent
status: finish
#### design

评估用户绘制的ER图，评估结果也可以作为进一步完善绘制的提示。

- Input
- `original_problem`: 原始的自然语言题目描述。

- `model_answer_er_diagram`: 由我们之前设计的E-R图智能体生成的、作为“标准答案”的E-R图JSON。

- `user_er_diagram`: 学生或用户绘制的、待评估的E-R图JSON。

> 以下述json格式, 通过对话窗口默认的query变量传入:
>
> ```json
> {
> "original_problem": "请设计一个药品管理系统的数据库模型。该系统用于管理医院的药品库存和使用情况。医院有多个科室，每个科室可以使用多种药品。药品由供应商提供，每种药品有多个规格。医生可以开具处方，患者凭处方领取药品。每个处方对应多个药品，且每个药品在处方中有一个明确的用量。请详细考虑药品、供应商、科室、处方、患者和药品规格之间的关系。",
> "model_answer_er_diagram": {},
> "user_er_diagram": {
> "entities": [
> {
> "id": "ent_药品",
> "name": "药品",
> "attributes": [
> {
> "id": "attr_药品ID",
> "name": "药品ID",
> "isPrimaryKey": true,
> "dataType": "INT"
> },
> {
> "id": "attr_药品名称",
> "name": "药品名称",
> "dataType": "VARCHAR(255)"
> },
> {
> "id": "attr_药品描述",
> "name": "药品描述",
> "dataType": "TEXT"
> }
> ]
> },
> {
> "id": "ent_供应商",
> "name": "供应商",
> "attributes": [
> {
> "id": "attr_供应商ID",
> "name": "供应商ID",
> "isPrimaryKey": true,
> "dataType": "INT"
> },
> {
> "id": "attr_供应商名称",
> "name": "供应商名称",
> "dataType": "VARCHAR(255)"
> },
> {
> "id": "attr_联系方式",
> "name": "联系方式",
> "dataType": "VARCHAR(100)"
> }
> ]
> },
> {
> "id": "ent_科室",
> "name": "科室",
> "attributes": [
> {
> "id": "attr_科室ID",
> "name": "科室ID",
> "isPrimaryKey": true,
> "dataType": "INT"
> },
> {
> "id": "attr_科室名称",
> "name": "科室名称",
> "dataType": "VARCHAR(255)"
> }
> ]
> },
> {
> "id": "ent_处方",
> "name": "处方",
> "attributes": [
> {
> "id": "attr_处方ID",
> "name": "处方ID",
> "isPrimaryKey": true,
> "dataType": "INT"
> },
> {
> "id": "attr_医生ID",
> "name": "医生ID",
> "dataType": "INT"
> },
> {
> "id": "attr_患者ID",
> "name": "患者ID",
> "dataType": "INT"
> },
> {
> "id": "attr_开具日期",
> "name": "开具日期",
> "dataType": "DATE"
> }
> ]
> },
> {
> "id": "ent_患者",
> "name": "患者",
> "attributes": [
> {
> "id": "attr_患者ID",
> "name": "患者ID",
> "isPrimaryKey": true,
> "dataType": "INT"
> },
> {
> "id": "attr_姓名",
> "name": "姓名",
> "dataType": "VARCHAR(255)"
> },
> {
> "id": "attr_性别",
> "name": "性别",
> "dataType": "CHAR(1)"
> },
> {
> "id": "attr_年龄",
> "name": "年龄",
> "dataType": "INT"
> }
> ]
> },
> {
> "id": "ent_药品规格",
> "name": "药品规格",
> "attributes": [
> {
> "id": "attr_规格ID",
> "name": "规格ID",
> "isPrimaryKey": true,
> "dataType": "INT"
> },
> {
> "id": "attr_药品ID",
> "name": "药品ID",
> "dataType": "INT"
> },
> {
> "id": "attr_规格名称",
> "name": "规格名称",
> "dataType": "VARCHAR(255)"
> },
> {
> "id": "attr_单位",
> "name": "单位",
> "dataType": "VARCHAR(50)"
> },
> {
> "id": "attr_库存数量",
> "name": "库存数量",
> "dataType": "INT"
> }
> ]
> }
> ],
> "relationships": [
> {
> "id": "rel_药品_供应商",
> "name": "供应",
> "connections": [
> {
> "entityId": "ent_药品",
> "cardinality": "1..*"
> },
> {
> "entityId": "ent_供应商",
> "cardinality": "1..1"
> }
> ],
> "attributes": []
> },
> {
> "id": "rel_科室_药品",
> "name": "使用",
> "connections": [
> {
> "entityId": "ent_科室",
> "cardinality": "0..*"
> },
> {
> "entityId": "ent_药品",
> "cardinality": "0..*"
> }
> ],
> "attributes": []
> },
> {
> "id": "rel_处方_患者",
> "name": "属于",
> "connections": [
> {
> "entityId": "ent_处方",
> "cardinality": "1..*"
> },
> {
> "entityId": "ent_患者",
> "cardinality": "1..1"
> }
> ],
> "attributes": []
> },
> {
> "id": "rel_处方_医生",
> "name": "开具",
> "connections": [
> {
> "entityId": "ent_处方",
> "cardinality": "1..*"
> },
> {
> "entityId": "ent_医生",
> "cardinality": "1..1"
> }
> ],
> "attributes": []
> },
> {
> "id": "rel_处方_药品规格",
> "name": "包含",
> "connections": [
> {
> "entityId": "ent_处方",
> "cardinality": "0..*"
> },
> {
> "entityId": "ent_药品规格",
> "cardinality": "0..*"
> }
> ],
> "attributes": [
> {
> "id": "attr_用量",
> "name": "用量",
> "dataType": "VARCHAR(100)"
> }
> ]
> }
> ],
> "metadata": {
> "title": "药品管理系统ER图",
> "description": "药品管理系统的实体关系模型",
> "version": "1.0.0"
> }
> }
> }
> ```
>
> 备注: 例子中问题对应schema:
>
> > ```sql
> > CREATE TABLE 药品 (
> > 药品ID INT PRIMARY KEY,
> > 药品名称 VARCHAR(255),
> > 药品描述 TEXT
> > );
> >
> > CREATE TABLE 供应商 (
> > 供应商ID INT PRIMARY KEY,
> > 供应商名称 VARCHAR(255),
> > 联系方式 VARCHAR(100)
> > );
> >
> > CREATE TABLE 科室 (
> > 科室ID INT PRIMARY KEY,
> > 科室名称 VARCHAR(255)
> > );
> >
> > CREATE TABLE 处方 (
> > 处方ID INT PRIMARY KEY,
> > 医生ID INT,
> > 患者ID INT,
> > 开具日期 DATE,
> > FOREIGN KEY (医生ID) REFERENCES 医生(医生ID),
> > FOREIGN KEY (患者ID) REFERENCES 患者(患者ID)
> > );
> >
> > CREATE TABLE 患者 (
> > 患者ID INT PRIMARY KEY,
> > 姓名 VARCHAR(255),
> > 性别 CHAR(1),
> > 年龄 INT
> > );
> >
> > CREATE TABLE 药品规格 (
> > 规格ID INT PRIMARY KEY,
> > 药品ID INT,
> > 规格名称 VARCHAR(255),
> > 单位 VARCHAR(50),
> > 库存数量 INT,
> > FOREIGN KEY (药品ID) REFERENCES 药品(药品ID)
> > );
> >
> > CREATE TABLE 处方药品关联表 (
> > 关联ID INT PRIMARY KEY,
> > 处方ID INT,
> > 药品ID INT,
> > 用量 VARCHAR(100),
> > FOREIGN KEY (处方ID) REFERENCES 处方(处方ID),
> > FOREIGN KEY (药品ID) REFERENCES 药品(药品ID)
> > );
> > ```
> >
> >

- Output:
- `evaluation`: 评估结果，一段格式化JSON报告；包括是否存在逻辑错误、是否不完整(缺失了什么实体或关系，附带理由description和解决方案recommendation)

> eg:
>
> ```json
> {
> "overall_score": "优秀", // 或者 "良好", "有待提高" 等定性评价
> "summary": "你的设计基本正确地捕捉了所有核心实体和关系，但在多对多关系的处理上有一个小失误。", // 一句总评
> "strengths": [ // 值得表扬的点
> "成功识别出了'学生'、'课程'和'教师'三个核心实体。",
> "为每个实体都正确地设置了主键。"
> ],
> "areas_for_improvement": [ // 需要改进的点
> {
> "issue_type": "关系基数错误 (Incorrect Cardinality)",
> "description": "在你的设计中，'学生'和'课程'之间被建模为一对多关系。根据题意'一个学生可以报名参加多门课程，一门课程也可以被多个学生报名'，这应该是一个多对多（M:N）关系。",
> "recommendation": "为了正确表示多对多关系，建议删除现有的外键，并创建一个名为'enrollments'（报名单）的中间连接表。这个表应至少包含`student_id`和`course_id`两个外键，分别指向'学生'表和'课程'表的主键。"
> },
> {
> "issue_type": "实体缺失 (Missing Entity)",
> "description": "题目中提到了'教师'可以创建课程，但在你的E-R图中缺少了'教师'这个实体。",
> "recommendation": "请增加一个名为'teachers'的实体，并为其添加必要的属性（如teacher_id, teacher_name），然后建立'teachers'和'courses'之间的一对多关系。"
> }
> ]
> }
> ```

痛点：现实世界中的数据库建模，尤其是E-R图设计，**往往不是一个只有唯一正确答案的问题**。对于同一个业务需求，完全可能存在多种逻辑上都正确、只是在实现细节、命名规范或范式级别上有所差异的有效设计。所以model_answer作为参考答案并不具有绝对的评判地位。

- **以“原始问题”为最高准则，以“参考答案”为实现范例。** **(The "Original Problem" is the Supreme Criterion; the "Model Answer" is an Implementation Example.)**

### Coding-Agent
status: finish
#### 说明

临时迁移先前dify上已有的简单模式，提示词和实际逻辑运算结构不变 (虽然暂时也不知道能怎么改)

- 仅对运行性能进行优化
- 不对输入输出接口做任何改动
- 但由于平台的迁移，API调用方式仍然可能改动
- 我将同时提供dify版本的修正版，则其接口无需改动 —— 名为chatSQL-dify-modified.yml

#### 接口

接口设计和原dify上的模式完全保持一致，故而输出反而与我们先前在百炼平台上设计的几个智能体有所不同——并非返回纯json文本由后端解析，而是在“结束”节点直接以json格式返回各个变量。

- Input
- difficulty: simple/medium/hard
- tags
- declare
- count: number
- Output
- hint
- description
- tags
- tableStructure
- tuples
- expected_result
- problem
- 

#### Architecture

任务是**对比分析与推理**， 所以一个**单一的、拥有充足上下文的评估智能体**足矣

graph LR
    subgraph "用户空间 (Student Space)"
        U[学生<br>Student]
        UD[用户的E-R图]
    end

    subgraph "评估智能体系统 (Evaluation Agent System)"
        EA("LLM<br>Evaluation Agent")
        EH["(state) 评估历史<br>Evaluation History"]
    end

    subgraph "固定上下文 (Fixed Context)"
        P["原始问题<br>Original Problem"]
        M["标准答案<br>Model Answer"]
    end
    
    %% 评估
    P -- 传入 --> EA
    M -- 传入 --> EA
    UD -- 传入 --> EA
    EH -- "传入先前的对话历史(v1)<br>Passes full history" --> EA
    EA -- "生成反馈 v2<br>Generates Feedback v2" --> F1["评估报告 v2"]
    F1 -- Feedback v2 --> EH[将v1存入历史]
    F1 -- 学生得到评估报告 --> U

# Cache
## 接口定义

### ER图渲染接口
> src/types/`erDiagram.ts`

// 实体属性接口
export interface ERAttribute {
  id: string;
  name: string;
  isPrimaryKey?: boolean;
  dataType?: string;
  isRequired?: boolean;
  description?: string;
}

// 实体接口, 需要遍历其中的属性, 判断是否存在
export interface EREntity {
  id: string;
  name: string;
  isWeakEntity?: boolean; // 是否为弱实体集
  attributes: ERAttribute[];
  description?: string;
  position?: {
    x: number;
    y: number;
  };
}

// 关系连接接口
export interface ERConnection {
  entityId: string;
  // 使用 (min, max) 表示法，其中 '*' 代表 '多'
  cardinality: '0..1' | '1..1' | '0..*' | '1..*';
  role?: string;
}

// 关系接口
export interface ERRelationship {
  id: string;
  name: string;
  connections: ERConnection[];
  isWeakRelation?: boolean;  // 是否连接了弱实体集
  attributes?: ERAttribute[]; // 关系也可以有属性
  description?: string;
  position?: {
    x: number;
    y: number;
  };
}

// ER图完整数据结构
export interface ERDiagramData {
  entities: EREntity[];
  relationships: ERRelationship[];
  metadata?: {
    title?: string;
    description?: string;
    version?: string;
    createdAt?: string;
    updatedAt?: string;
  };
}

比如说:

{
  entities: [
    {
      id: "ent_reader",
      name: "读者",
      attributes: [
        { id: "attr_reader_id", name: "读者证号", isPrimaryKey: true, dataType: "VARCHAR(20)", isRequired: true },
        { id: "attr_reader_name", name: "姓名", dataType: "VARCHAR(50)", isRequired: true },
        { id: "attr_reader_type", name: "读者类型", dataType: "VARCHAR(20)" }
      ]
    },
    {
      id: "ent_book",
      name: "图书",
      attributes: [
        { id: "attr_book_id", name: "图书编号", isPrimaryKey: true, dataType: "VARCHAR(20)", isRequired: true },
        { id: "attr_book_title", name: "书名", dataType: "VARCHAR(200)", isRequired: true },
        { id: "attr_book_author", name: "作者", dataType: "VARCHAR(100)" },
        { id: "attr_book_isbn", name: "ISBN", dataType: "VARCHAR(20)" }
      ]
    }
  ],
  relationships: [
    {
      id: "rel_borrows",
      name: "借阅",
      connections: [
        { entityId: "ent_reader", cardinality: "0..*", role: "借阅者" },
        { entityId: "ent_book", cardinality: "0..*", role: "被借图书" }
      ],
      attributes: [
        { id: "attr_borrow_date", name: "借阅日期", dataType: "DATE", isRequired: true },
        { id: "attr_return_date", name: "归还日期", dataType: "DATE" }
      ]
    }
  ],
  metadata: {
    title: "图书馆管理ER图",
    description: "图书馆读者借阅系统的实体关系图",
    version: "1.0.0"
  }
}

## RAG
https://github.com/HKUDS/LightRAG/blob/main/lightrag/api/README.md

https://github.com/HKUDS/LightRAG?tab=readme-ov-file

https://arxiv.org/abs/2410.05779

## test and reference
text-to-SQL: Spider 数据集