# Mysql Agent

**Repository Path**: gongzihao/mysql-agent

## Basic Information

- **Project Name**: Mysql Agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MySQL Agent

一个基于 Node.js + LangChain.js 的终端 Agent，支持：

- OpenAI 兼容接口
- `OPENAI_BASE_URL` / `OPENAI_API_KEY` 环境变量配置
- 基于 Ink 的 TUI 终端界面
- 基于内置 HTTP 服务的 Web 多会话界面
- 内置 `bash` 和 `powershell` 工具
- 内置 MySQL 只读 Agent 工具
- 工具执行前的弹窗式确认
- 同一波并发工具调用会合并为一次确认
- 支持 `不审批` / `手动审批` / `自动审批`
- 多轮对话和流式输出

## 要求

- Node.js 24+
- 可用的 Bash 环境
  - macOS / Linux: 系统自带 `bash`
  - Windows: Git Bash 或 WSL
- 交互式终端
  - Ink TUI 不能在管道、重定向或非 TTY 环境下运行

## 安装

```bash
npm install
cp .env.example .env
cp datasources.example.json datasources.json
```

Windows PowerShell 可改用：

```powershell
Copy-Item .env.example .env
Copy-Item datasources.example.json datasources.json
```

## 配置

编辑 `.env`：

```env
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=gpt-4.1-mini
OPENAI_API_MODE=auto
OPENAI_REASONING_SUMMARY=auto
OPENAI_STREAMING=true
APPROVAL_MODE=auto
LOG_LEVEL=info
LOG_FILE=logs/agent-tui.log
LOG_STDERR_LEVEL=warn
```

可选项：

```env
OPENAI_REASONING_EFFORT=low
BASH_TIMEOUT_MS=120000
BASH_PATH=C:\Program Files\Git\usr\bin\bash.exe
POWERSHELL_PATH=powershell.exe
DB_DEFAULT_SOURCE=local
```

编辑 `datasources.json`：

```json
{
  "sources": {
    "local": {
      "type": "mysql",
      "title": "Local",
      "host": "127.0.0.1",
      "port": 3306,
      "user": "root",
      "password": "your-password",
      "database": "your_database",
      "ssl": false,
      "connectTimeoutMs": 10000,
      "autoLimit": 100,
      "maxRows": 200,
      "maxColumns": 50,
      "maxResultBytes": 50000
    }
  }
}
```

`OPENAI_API_MODE` 支持：

- `auto`: 默认。官方 OpenAI 地址下，对 `gpt-5`、`o*`、`codex` 这类模型优先走 Responses API；非官方 OpenAI 兼容服务默认走 Chat Completions，避免兼容网关未实现 `/responses` 时失败。
- `responses`: 强制使用 Responses API。
- `chat`: 强制使用 Chat Completions API。

`OPENAI_STREAMING` 支持：

- `true`: 使用流式模型请求，终端会边生成边显示。
- `false`: 使用非流式请求，行为和普通 `invoke` 一样。

`OPENAI_REASONING_SUMMARY` 支持：

- `auto`: 默认。请求 reasoning summary，并在终端打印。
- `concise`: 更短的摘要。
- `detailed`: 更详细的摘要。
- `off`: 不请求 reasoning summary。

`OPENAI_REASONING_EFFORT` 支持：

- `none` / `minimal` / `low` / `medium` / `high` / `xhigh`

`APPROVAL_MODE` 支持：

- `manual`: 工具调用进入审批弹窗；同一轮并发发起的工具会合并成一次确认。
- `auto`: 对低风险动作自动批准，对中高风险动作继续弹窗确认。当前内置规则会自动批准只读 MySQL 工具，以及一小组明显只读的 shell / PowerShell 查看类命令。
- `off`: 不审批，直接执行。

日志相关：

- `LOG_LEVEL`: `debug` / `info` / `warn` / `error` / `silent`
- `LOG_FILE`: 日志文件路径，默认 `logs/mysql-agent.log`，可设为 `off` 禁用文件日志
- `LOG_STDERR_LEVEL`: 非交互模式下输出到 `stderr` 的最低级别，默认 `warn`
- 交互式 TUI 运行时，日志始终只写文件，不镜像到 `stderr`，避免打乱 Ink 界面
- `LOG_LEVEL=debug` 时会额外记录 OpenAI HTTP 请求和响应摘要，包括 URL、方法、请求体、非流式响应体和脱敏后的 header。成功的 `text/event-stream` 流式响应只记录响应头和占位摘要，避免调试日志提前消费流体。该日志可能包含用户问题、SQL、工具参数和模型输出，只建议本地排障时短时间开启。

## MySQL Agent

配置 `datasources.json` 并设置 `DB_DEFAULT_SOURCE` 后，运行时会自动注册当前激活数据源的 MySQL 工具，不依赖本机 `mysql` 客户端。

首版能力：

- 列出数据库和表
- 轻量汇总 schema，默认先返回表列表
- 按表查看结构、索引，按需再取 `CREATE TABLE`
- 执行只读 SQL
- 对只读 SQL 做 `EXPLAIN`

推荐工作流：

- 先用 `mysql_list_tables` 或 `mysql_get_schema_summary` 看表列表
- 再用 `mysql_describe_table` 查看单表的列和索引
- 确认表名和字段后，再执行 `mysql_query_readonly`
- 只有明确需要原始 DDL 时，才在 `mysql_describe_table` 里打开 `includeCreateTable`

首版限制：

- 只允许单条只读 SQL
- 允许：`SELECT` / `SHOW` / `DESCRIBE` / `DESC` / `EXPLAIN` / `WITH`
- 拒绝：`INSERT` / `UPDATE` / `DELETE` / `ALTER` / `DROP` / `TRUNCATE` / `CREATE` / `GRANT` / 多语句
- 对未显式带 `LIMIT` 的 `SELECT` / `WITH` 查询，会自动追加 `LIMIT`

## 运行

```bash
npm start
```

启动 Web 版：

```bash
npm run web
```

打开 `http://127.0.0.1:3000`

自定义端口时仍可用：

```bash
npm start -- --web-port 3001
```

开发模式：

```bash
npm run dev
```

Web 开发模式：

```bash
npm run web:dev
```

```bash
npm test
```

## 项目结构

```text
src/
  index.tsx              # 启动入口，支持 TUI / Web 路由
  app/
    App.tsx              # Ink TUI 渲染层，负责输入焦点、滚动和键盘绑定
    agentSessionController.ts # 可复用的 session 控制层，TUI/Web 共享
    bootstrap.tsx        # Ink 启动、TTY 检查、退出清屏
    runtimeEntryStore.ts # transcript 条目与运行态计时 store
    sessionCore.ts       # session 纯函数与共享文本规则
    tuiSessionDeps.ts    # TUI 平台依赖适配：loadConfig/createRuntime/TTY 审批能力
    useAgentSession.ts   # TUI 对 controller 的 React 适配层
  core/
    commands.ts          # slash 命令常量
    config.ts            # 环境变量解析
    logger.ts            # 统一日志、级别控制、敏感字段脱敏
    messages.ts          # LangChain 消息解析、reasoning 提取、token 统计
    openai.ts            # OpenAI API 模式判断
    terminal.ts          # 帮助文本、tool 结果格式化
    tty.ts               # TTY 清屏等终端专属能力
    types.ts             # 全局共享类型定义
    workspace.ts         # 当前工作区根目录
  runtime/
    agent.ts             # ChatOpenAI / LangChain agent 组装
    tools.ts             # bash / powershell 工具、结构化执行、命令确认
    mysql.ts             # MySQL 连接、只读 SQL 校验、schema/query 工具
  web/
    server.ts            # HTTP API + SSE + 静态页面服务
    sessionManager.ts    # 内存多会话管理与过期回收
    static/              # 原生浏览器前端
  ui/
    components.tsx       # Header、TranscriptView、ApprovalModal、StatusBar
    transcript.ts        # transcript 行级渲染模型、换行与标题时间格式化
```

分层原则：

- `core` 放纯逻辑和通用能力，不依赖 Ink UI
- `runtime` 放模型和工具执行相关代码
- `ui` 只负责展示，不直接依赖 Node 配置模块
- `app` 负责平台组装；`useAgentSession` 承担共享 controller，`App.tsx` 主要保留 Ink 专属输入与渲染
- Web 端每个浏览器会话在服务端独立持有自己的 runtime、审批状态、历史和当前 datasource

## 终端命令

- `/db` 查看当前和可用数据源
- `/db <name>` 切换数据源并重置会话
- `/help` 查看帮助
- `/stat` 查看当前会话 token 统计
- `/reset` 清空会话
- `/clear` 清屏

## 测试

- `npm test`：运行 Vitest 测试
- `npm run test:watch`：监听模式运行测试
- 当前测试链路以 `core` 纯逻辑单测为主，并补了一条 Ink 组件级 smoke test，后续可以继续扩展到 App 级交互测试和 PTY 黑盒测试
- `/exit` 退出

## Web 说明

- `--web-port` 启动单进程 Web 服务，同时提供页面、API 和 SSE 流
- 日常使用建议直接执行 `npm run web`，默认监听 `3000`
- Web 会话默认保存在服务端内存中，浏览器刷新后会尝试按 `sessionId` 重连
- 当前不做持久化恢复；进程重启后旧会话失效
- 审批弹窗按 session 隔离；一个浏览器会话的批准/拒绝不会影响其他会话
- 每个 session 的 `/db` 切换彼此独立，不影响 TUI 或其他 Web 会话

执行确认时支持：

- `y`: 只批准这一次命令
- `n`: 拒绝这一次命令
- `a`: 本次会话后续命令全部自动批准

如果同一轮里模型同时发起多个工具调用，确认弹窗会按批次展示，`y` / `n` 会对这一批一起生效。
自动审批模式下，弹窗会显示本地规则判断出的风险等级和原因。

## 测试建议

启动后可依次测试：

- `比较 24 和 42，简单说明哪一个更大。`
- `本机有多少个进程`
- `请用bash列出当前目录文件名`
- `/db`
- `/db local`
- `检查一下 MySQL 连接是否正常`
- `列出当前库里的表`
- `解释 users 表结构`
- `查询最近 10 条订单`
- `/help`
- `/clear`
- `/reset`
- `/exit`

## 说明

- Agent 默认在当前项目目录执行 `bash` 命令。
- Windows 主机级问题优先走 `powershell` 工具，比如进程数、服务、环境变量、计划任务等。
- MySQL 相关问题优先走内置 MySQL 工具，不再依赖本机 `mysql` 可执行文件。
- 如果没有 `datasources.json` 或 `DB_DEFAULT_SOURCE` 未指向有效数据源，启动会失败。
- `/db <name>` 会切换当前激活数据源，并自动清空历史、token 统计和 transcript。
- MySQL 查询结果会按 `MYSQL_MAX_ROWS` / `MYSQL_MAX_COLUMNS` / `MYSQL_MAX_RESULT_BYTES` 做裁剪。
- 默认会对未显式限制结果集的 `SELECT` / `WITH` 自动追加 `LIMIT MYSQL_AUTO_LIMIT`。
- `mysql_get_schema_summary` 默认走轻量模式，只返回表列表；开启 `includeStats=true` 才返回更详细的表级统计。
- `mysql_describe_table` 默认只返回有限数量的列和索引，适合渐进式交互，避免一次性输出整表 DDL。
- 如果传入相对路径 `cwd`，会相对于项目根目录解析。
- 对带空格路径、密码、环境变量、`>`、`<`、`|`、`!` 这类 shell 敏感字符的命令，Agent 现在支持结构化执行：优先传 `file`、`args`、`env`，不要把整条命令硬拼成一个字符串。
- 如果你的 OpenAI 兼容服务模型名不同，直接改 `OPENAI_MODEL`。
- 某些 OpenAI 兼容服务没有实现 `/responses`。如果遇到 `500 not implemented`，优先将 `OPENAI_API_MODE=chat` 或保持默认 `auto`；只有确认服务支持 Responses API 时，再设置 `OPENAI_API_MODE=responses`。
- 如果你的模型平台后台需要显示为“流式”，至少要启用 `OPENAI_STREAMING=true`。本项目在该模式下会走 LangChain 的 `agent.stream(...)`。
- `Thinking...` 现在只在连接模型期间显示；连接建立后会切换为普通状态文本，不会一直挂在屏幕上。
- 默认会把运行日志写到 `logs/mysql-agent.log`，方便排查启动慢、tool 卡住、SQL 执行失败、审批流异常等问题。
- 对 `mysql_describe_table`、`mysql_get_schema_summary` 这类超长 tool 输出，TUI 默认只显示摘要，避免终端闪烁；不影响 agent 在内部拿到完整结果。
- `Ctrl+T` 可切换全局工具完整输出模式，进入后隐藏输入框，仅保留滚动和再次 `Ctrl+T` 退出。
- 输入框输入 `/` 或 `\` 会显示命令补全，`Up/Down` 选择，`Enter` 应用。
- transcript 焦点下可用 `Up/Down` 和 `PgUp/PgDn` 线性滚动。
- 是否真的能看到 reasoning summary，最终取决于你连接的 OpenAI 兼容服务是否实际返回该字段。
- 如果你担心高危动作，保持 `APPROVAL_MODE=manual`，模型每次执行 shell 或 MySQL 工具前都会弹出确认框，并把你的批准/拒绝动作记到 transcript。
- `/stat` 会统计当前会话累计 token，用量来源优先读取模型返回的 `usage_metadata`，也兼容部分后端返回的 `response_metadata.tokenUsage`。如果后端不返回 usage，统计会显示 `missing usage reports`。