MaloneTalk · mengnankkkk · Aug 16, 2026 · Aug 16, 2026
diff --git 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
@@ -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
@@ -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
@@ -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 <token>` 携带。
 - `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
@@ -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
@@ -18,7 +18,7 @@
 
 | 概念 | 说明 | Controller |
 | --- | --- | --- |
-| **域（Domain）** | 业务主题分组，如"交易""用户"，用于缩小表检索范围 | `TableSemanticController` |
+| **域（Domain）** | 业务主题分组，如"交易""用户"，用于缩小表检索范围 | `DomainController` |
 | **逻辑表** | 给物理表起一个业务名，含表描述、可见性、物理表是否存在 | `TableSemanticController` |
 | **逻辑列** | 给物理列补充业务含义、枚举值、单位、币种 | `TableColumnSemanticController` |
 | **表关系** | 表间 join 路径（一对一/一对多）、启禁状态，供 Agent 多表查询时自动拼 SQL | `TableRelationSemanticController` |