DataBase Reader

借助 OpenAI Agents SDK 与自定义前端，提供一个可以用自然语言查询 AWS MySQL 数据库的全栈示例。

功能概览

• OpenAI Agents SDK：通过工具 execute_sql 与 get_schema 将自然语言解释为只读 SQL，并返回结构化结果。
• AWS 数据库连接：使用 mysql2 连接 Amazon RDS（MySQL），自动限制查询仅为 SELECT。
• 对话界面：React 前端提供类 Chat UI 的体验，并带有会话长期记忆和结果导出。
• 上下文记忆：支持按会话保存提问历史和背景提示，方便逐步追问。
• 上下文记忆：支持按会话保存提问历史和背景提示，可通过 AGENT_HISTORY_LIMIT 控制保留轮数。
• API 集成：后端保留 POST /chatkit 接口，方便在需要时切换为官方 ChatKit 前端。

运行要求

• Node.js 18+
• npm 10+
• OpenAI API Key（需启用最新 Responses/Agents 权限）
• 可访问的 AWS RDS MySQL 实例

环境变量

在项目根目录创建 .env：

OPENAI_API_KEY=sk-...
AGENT_MODEL=gpt-5-mini
AGENT_HISTORY_LIMIT=12
DB_HOST=your-db-endpoint.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_USER=app_user
# 或者使用 DB_USERNAME 指定用户名
DB_PASSWORD=********
DB_DATABASE=analytics
# 可选：默认 false，本地调试时可关闭；正式环境建议启用
DB_SSL_ENABLED=false
# 查询结果返回的最大行数
DB_MAX_RESULT_ROWS=200
# ChatKit 允许跨域访问的域名，多个用逗号隔开
ALLOW_ORIGINS=http://localhost:5173
PORT=3001

前端 .env（位于 chat-ui/.env）：

VITE_AGENT_API_URL=http://localhost:3001/api/query/run

前端默认提供一个自定义对话界面，通过 REST API 调用后端。若想替换为官方 ChatKit，可另行集成。 界面左侧可填写「背景知识」，保存后系统会在整个会话中记住这些信息。

启动服务

1. 安装依赖

   npm install
   (cd chat-ui && npm install)

2. 启动后端（Agents + ChatKit API）

   npm run dev

   服务默认监听 http://localhost:3001，提供：

   • POST /api/query/run —— 直接调用 Agents 进行问答，并带有会话记忆
   • POST /api/query/context —— 设置/更新会话背景信息
   • GET /api/query/export —— 导出最近一次查询结果（支持 txt / csv / doc）
   • POST /chatkit —— ChatKit 自托管 SSE 接口（可选）

3. 启动前端

   npm run dev:ui

   浏览器访问 http://localhost:5173，即可以 Chat UI 对话。左侧可维护背景知识，右侧可直接导出查询结果为 TXT / CSV / Word。

项目结构

.
├── src
│   ├── agent          # Agents SDK 配置
│   ├── chatkit        # 自托管 ChatKit Server 实现
│   ├── routes         # Express 路由
│   ├── config         # 环境与 OpenAI 相关配置
│   └── server.ts      # 应用入口
├── chat-ui            # Vite + React 前端
└── README.md

数据库安全策略

• 所有 SQL 在执行前先通过 verifyReadOnly 校验，只允许单条 SELECT。
• 建议在生产环境启用 TLS（DB_SSL_ENABLED=true），确保连接安全。
• 查询结果在服务端裁剪，最多 DB_MAX_RESULT_ROWS 行。
• 强烈建议为数据库创建只读角色（仅授予 SELECT 权限），并在 .env 中使用该角色的凭据运行服务。

后续可扩展方向

1. 权限控制：依据用户身份隔离可访问的表与字段。
2. Schema 缓存：缓存 information_schema，减少频繁拉取。
3. 指标模板：结合 DSL / Prompt 模板生成更稳定 SQL。
4. 观测性：启用 Agents SDK tracing，配合 OpenTelemetry 上报。

欢迎根据业务需求继续扩展！如需部署到生产环境，请务必完成域名校验、HTTPS、身份认证等安全加固。