From 12c4d4da12c5b2ac34bbee6e7591aea04f64a763 Mon Sep 17 00:00:00 2001 From: mengnankkkk Date: Sun, 16 Aug 2026 15:51:23 +0800 Subject: [PATCH] docs: update docs --- README.md | 17 +++++++++++++---- docs/README.md | 1 - docs/architecture.md | 4 ++-- docs/configuration.md | 22 +++++++++++++++------- docs/getting-started.md | 5 ++++- docs/semantic-layer.md | 2 +- 6 files changed, 35 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 2fb9311..3242ac6 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ - **自然语言查数**：基于 LLM + ReAct 工具调用，把自然语言转为 SQL 并在目标库执行，全程流式输出。 - **Python 数据分析**：对查询结果自动执行统计分析（相关性、回归、分布检验），补齐 SQL 在复杂统计计算上的短板。 -- **多模型可切换**：内置 OpenAI / Ollama / 通义 DashScope / Anthropic 等提供商，换底座模型不影响已沉淀的业务知识。 +- **多模型可切换**：内置 OpenAI 兼容接口 / Ollama / 通义 DashScope / Anthropic 等提供商，换底座模型不影响已沉淀的业务知识。 - **多数据源（JDBC 抽象）**：数据读取与执行完全基于 JDBC 标准 API，因此支持**任意 JDBC 兼容数据库**——内置类型已覆盖 MySQL / PostgreSQL / Oracle（已验证）与 ClickHouse / SQL Server / 达梦 / OceanBase / SQLite，其余 JDBC 兼容库扩展枚举即可接入。 > **默认仅内置 MySQL 驱动**。使用其他数据库前，需先在 `data-agent-backend/pom.xml` 中添加对应 JDBC 驱动依赖并重新构建后端，否则新增数据源时会提示「未找到数据库驱动」。类型列表与 Maven 坐标见 [docs/configuration.md](docs/configuration.md#4-查询数据源)。 @@ -72,16 +72,25 @@ Data Agent 反其道而行——**不引入任何向量检索**。语义层把 mysql -u root -p -e "CREATE DATABASE data_agent CHARACTER SET utf8mb4;" mysql -u root -p data_agent < sql/data_source.sql -# 2. 启动后端（默认端口 8080） +# 2. 配置首启必需环境变量 +export ADMIN_INIT_PASSWORD="你的管理员初始密码" +export IO_GITHUB_MALONETALK_MODEL_API_KEY="你的模型 API Key" + +# 可选：默认走 OpenAI 兼容接口，application.properties 当前示例指向 DeepSeek +export IO_GITHUB_MALONETALK_MODEL_PROVIDER="openai" +export IO_GITHUB_MALONETALK_MODEL_NAME="deepseek-v4-flash" +export IO_GITHUB_MALONETALK_MODEL_BASE_URL="https://api.deepseek.com" + +# 3. 启动后端（默认端口 8080） cd data-agent-backend mvn spring-boot:run -# 3. 启动前端（默认端口 3000） +# 4. 启动前端（默认端口 3000） cd data-agent-frontend pnpm install && pnpm dev ``` -浏览器打开 http://localhost:3000 ，在聊天框用自然语言提问，例如：*"上个月各区域销售额是多少？"* +浏览器打开 http://localhost:3000 ，使用 `admin` / `ADMIN_INIT_PASSWORD` 登录后，在聊天框用自然语言提问，例如：*"上个月各区域销售额是多少？"* ## 📚 文档 diff --git a/docs/README.md b/docs/README.md index ace42c7..9b1cbc0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -29,6 +29,5 @@ DataAgent/ ├── data-agent-frontend/ # Vue 3 + TS + Vite 前端 ├── skills/ # Skill 目录（内置 + 自定义，放入即生效） ├── sql/ # 元数据库初始化脚本（data_source.sql） -├── io/agentscope/ # 实验性/参考代码 └── docs/ # 本文档集 ``` diff --git a/docs/architecture.md b/docs/architecture.md index 026a344..0ef976f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -12,7 +12,7 @@ | 元数据库 | MySQL | 存语义层、数据源、会话、MCP 配置、报表、用户、角色与权限等 | | 查询数据源 | MySQL / PostgreSQL / Oracle | 用户真正要查的业务库，由 Agent 动态连接 | -> 后端包名为 `io.github.malonetalk.agent`，应用名 `data-agent-management`，默认端口 `8080`。 +> 后端根包名为 `io.github.malonetalk`，应用名 `data-agent-management`，默认端口 `8080`。 ## 2. 一次查询请求的流转 @@ -81,6 +81,6 @@ | GET/POST/PUT/DELETE | `/api/sys/user[/...]` | 用户增删改查、重置密码 | | GET/POST/PUT/DELETE | `/api/sys/role[/...]` | 角色增删改查、表级白名单、列级黑名单 | | GET/POST/PUT/DELETE | `/api/mcp-server[/...]` | MCP Server 增删改查与启用/停用 | -| REST | `/api/datasource`、`/api/domain`、`/api/semantic/*`、`/api/report` | 数据源、域、语义层、报表管理 | +| REST | `/api/datasource`、`/api/domains`、`/api/semantic/*`、`/api/metric`、`/api/reports` | 数据源、域、语义层、指标口径、报表管理 | > 更完整的字段与请求/响应结构，建议直接阅读后端 `controller` 与 `dto` 包源码。 diff --git a/docs/configuration.md b/docs/configuration.md index 88386c5..576e0a2 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -25,6 +25,7 @@ | `name` | 模型名 | `gpt-4o-mini` / `deepseek-chat` / `qwen-plus` | | `base-url` | API 基址 | `https://api.openai.com/v1` | | `api-key` | 密钥（从环境变量 `IO_GITHUB_MALONETALK_MODEL_API_KEY` 注入，勿写死） | `sk-...` | +| `thinking-enabled` | DashScope 模型是否开启思考能力，默认 `true`；其他 provider 当前会忽略该配置 | `true` / `false` | 对应环境变量写法（Spring 把点号转为下划线大写）： @@ -33,6 +34,7 @@ export IO_GITHUB_MALONETALK_MODEL_PROVIDER="openai" export IO_GITHUB_MALONETALK_MODEL_NAME="gpt-4o-mini" export IO_GITHUB_MALONETALK_MODEL_BASE_URL="https://api.openai.com/v1" export IO_GITHUB_MALONETALK_MODEL_API_KEY="sk-你的密钥" +export IO_GITHUB_MALONETALK_MODEL_THINKING_ENABLED="true" ``` 各提供商常见取值： @@ -91,23 +93,23 @@ export IO_GITHUB_MALONETALK_MODEL_API_KEY="sk-你的密钥" ```properties # 文件系统来源 -io.github.malonetalk.skill.filesystem[0].path=skills -io.github.malonetalk.skill.filesystem[0].source=data-query +io.github.malonetalk.skill.filesystem[0].path=./skills +io.github.malonetalk.skill.filesystem[0].source=local-fs io.github.malonetalk.skill.filesystem[0].writeable=true # Git 来源（自动同步） io.github.malonetalk.skill.git[0].url=https://github.com/your-org/your-skills.git io.github.malonetalk.skill.git[0].branch=main io.github.malonetalk.skill.git[0].local-path=/tmp/skills-cache -io.github.malonetalk.skill.git[0].source=data-query +io.github.malonetalk.skill.git[0].source=git-repo # Nacos 来源（需显式指定 skillNames） io.github.malonetalk.skill.nacos[0].server-addr=127.0.0.1:8848 io.github.malonetalk.skill.nacos[0].skill-names[0]=data-query # classpath 来源 -io.github.malonetalk.skill.classpath[0].resource-path=skills/data-query -io.github.malonetalk.skill.classpath[0].source=data-query +io.github.malonetalk.skill.classpath[0].resource-path=skills +io.github.malonetalk.skill.classpath[0].source=classpath-skills ``` 仓库内置示例：`skills/data-query/SKILL.md`。 @@ -143,7 +145,13 @@ export ADMIN_INIT_PASSWORD="你的管理员密码" ### 工作原理 -- 后端启动时，`AdminBootstrapRunner` 检查 `sys_user` 表是否为空；若为空，用 `admin.init-password` 创建 `admin` 用户（用户名固定为 `admin`，`displayName` 为 "Administrator"）。 +- 后端启动时，`AdminBootstrapRunner` 检查 `sys_user` 表是否为空；若为空，用 `admin.init-password` 创建 `admin` 用户（用户名固定为 `admin`，`displayName` 为「管理员」，`role_id=1`）。 - 登录接口 `POST /api/auth/login` 接受 `{ username, password }`，返回 `{ token, user }`。前端将 token 存入 `localStorage`，后续请求通过 `Authorization: Bearer ` 携带。 - `AuthInterceptor` 拦截除 `/api/auth/login` 外的所有接口（含 SSE 流式端点），校验 token 签名与时效。 -- 登录后即可使用全部功能。后续可在「用户管理」和「角色管理」页面中创建角色、为角色配置表级白名单与列级黑名单、将用户绑定到角色——当前 Agent 推理链路尚未接入权限过滤，表/列权限仅作用于页面管理。 +- 登录后可访问基础功能；带 `@AdminOnly` 的管理接口要求当前用户 `role_id=1`。后续可在「用户管理」和「角色管理」页面中创建角色、为角色配置表级白名单与列级黑名单、将用户绑定到角色——当前 Agent 推理链路尚未接入权限过滤，表/列权限仅作用于页面管理。 + +## 8. 安全提示 + +- 不要把 `IO_GITHUB_MALONETALK_MODEL_API_KEY`、`JWT_SECRET`、`ADMIN_INIT_PASSWORD` 写入仓库。 +- 生产环境必须设置长度不少于 32 字节的 `JWT_SECRET`；留空只适合本地开发。 +- 目标数据源的连接信息会保存在元数据库中，请限制元数据库账号、网络与备份访问权限。 diff --git a/docs/getting-started.md b/docs/getting-started.md index 39ec454..a264e73 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -48,6 +48,9 @@ export IO_GITHUB_MALONETALK_MODEL_PROVIDER="openai" export IO_GITHUB_MALONETALK_MODEL_NAME="gpt-4o-mini" export IO_GITHUB_MALONETALK_MODEL_BASE_URL="https://api.openai.com/v1" export IO_GITHUB_MALONETALK_MODEL_API_KEY="sk-你的密钥" + +# DashScope 模型是否开启思考能力，默认 true；其他 provider 当前会忽略 +export IO_GITHUB_MALONETALK_MODEL_THINKING_ENABLED="true" ``` > ⚠️ **不要把 API Key 写进 `application.properties` 并提交到仓库。** 密钥现已改为从环境变量 `IO_GITHUB_MALONETALK_MODEL_API_KEY` 注入。详见 [configuration.md](configuration.md#安全提示) 。 @@ -99,7 +102,7 @@ pnpm dev 3. 在「语义层」中把相关表/列映射成业务语言（可选，但能显著提升准确率）。 4. 进入聊天界面，输入类似：*"上个月各区域销售额是多少？"*，观察流式回答与生成的 SQL。 -> 初始的 `admin` 用户拥有所有权限。如需多人使用，可在「用户管理」中创建用户、在「角色管理」中为角色配置表/列级权限、再将用户绑定到角色。当前权限仅在页面管理层面生效，尚未接入 Agent 推理链路。 +> 初始的 `admin` 用户会绑定管理员角色（`role_id=1`），可访问所有标记了 `@AdminOnly` 的管理接口。如需多人使用，可在「用户管理」中创建用户、在「角色管理」中为角色配置表/列级权限、再将用户绑定到角色。当前表/列权限仍主要用于管理侧配置，Agent 推理链路的表/列过滤还在后续完善中。 > 如果回答不准，多半是语义层/指标口径没配好，或数据源尚未接入。参见 [semantic-layer.md](semantic-layer.md) 与 [configuration.md](configuration.md)。 diff --git a/docs/semantic-layer.md b/docs/semantic-layer.md index 3f23724..924cf85 100644 --- a/docs/semantic-layer.md +++ b/docs/semantic-layer.md @@ -18,7 +18,7 @@ | 概念 | 说明 | Controller | | --- | --- | --- | -| **域（Domain）** | 业务主题分组，如"交易""用户"，用于缩小表检索范围 | `TableSemanticController` | +| **域（Domain）** | 业务主题分组，如"交易""用户"，用于缩小表检索范围 | `DomainController` | | **逻辑表** | 给物理表起一个业务名，含表描述、可见性、物理表是否存在 | `TableSemanticController` | | **逻辑列** | 给物理列补充业务含义、枚举值、单位、币种 | `TableColumnSemanticController` | | **表关系** | 表间 join 路径（一对一/一对多）、启禁状态，供 Agent 多表查询时自动拼 SQL | `TableRelationSemanticController` |