From 6dcd34bb23215665f688cc24cacf019ceb7b8f24 Mon Sep 17 00:00:00 2001 From: mengnankkkk Date: Sun, 15 Nov 2026 13:43:57 +0800 Subject: [PATCH] fix --- README.md | 12 ++++-- data-agent-cli/README.md | 9 +++++ data-agent-frontend/README.md | 30 ++++++++------ docs/README.md | 10 ++++- docs/architecture.md | 24 +++++++++--- docs/charts.md | 74 +++++++++++++++++++++++++++++++++++ docs/configuration.md | 30 ++++++++++++-- docs/contributing.md | 29 ++++++++++++-- docs/csv-import.md | 8 ++-- docs/external-agent.md | 33 +++++++++++++++- docs/getting-started.md | 18 +++++---- docs/permissions.md | 11 +++++- docs/semantic-layer.md | 24 +++++++++--- docs/skills.md | 18 +++++++-- 14 files changed, 278 insertions(+), 52 deletions(-) create mode 100644 docs/charts.md diff --git a/README.md b/README.md index 7e8cf33..43732f0 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,13 @@ - **Python 数据分析**:对查询结果自动执行统计分析(相关性、回归、分布检验),补齐 SQL 在复杂统计计算上的短板。 - **多模型可切换**:内置 OpenAI 兼容接口 / Ollama / 通义 DashScope / Anthropic 等提供商,换底座模型不影响已沉淀的业务知识。 - **多数据源(JDBC 抽象)**:连接与元数据读取基于 JDBC 标准 API,内置类型覆盖 MySQL / PostgreSQL / Oracle / ClickHouse / SQL Server / 达梦 / OceanBase / SQLite;实际查询还受目标库方言和 SQL 授权支持范围约束。 -- **同一会话多数据源**:会话可选择多个数据源;不选择时使用当前用户所有可访问的启用数据源,工具按 `datasource_id` 执行。 +- **同一会话多数据源**:后端聊天接口支持通过 `datasourceIds` 限定多个数据源,工具按 `datasource_id` 执行;当前聊天页未提供选择控件,默认使用当前用户所有可访问的启用数据源。 > **默认仅内置 MySQL 驱动**。使用其他数据库前,需先在 `data-agent-backend/pom.xml` 中添加对应 JDBC 驱动依赖并重新构建后端,否则新增数据源时会提示「未找到数据库驱动」。类型列表与 Maven 坐标见 [docs/configuration.md](docs/configuration.md#4-查询数据源)。 - **语义层(无向量召回)**:以"域(Domain)"组织表,由 LLM 在工具调用时**推理出业务问题所属域、主动选表**,而非向量相似度召回——更精准、更稳定,也无需维护任何 embedding 索引。维度包括领域描述、逻辑表 / 逻辑列 / 表关系 / 指标口径的业务映射。 +- **普通视图分析**:表与普通视图统一同步和维护语义,展示 `TABLE` / `VIEW` 类型,并按对象及输出列分别授权。 +- **CSV 导入分析**:将 CSV 导入独立 MySQL 托管库,自动同步语义,提供任务进度、失败恢复与删除;需先配置专用读写连接,见 [CSV 导入](docs/csv-import.md)。 +- **交互图表**:根据本会话 SQL 结果生成柱状图、折线图、饼图和散点图,支持历史回放;图表数据来自查询快照,见 [图表使用指南](docs/charts.md)。 - **会话式分析**:SSE 流式回答,会话历史可追溯、可调试。 - **角色与数据权限**:按功能权限点授权,表白名单与隐藏列黑名单同时作用于语义工具、SQL 查询和导出;会话与资产按归属隔离。 - **资产与数据证据**:内置报表、CSV 导出与数据证据视图,记录回答涉及的 SQL、指标、Python 执行及表列来源。 @@ -142,9 +145,9 @@ mysql -u root -p data_agent < sql/migration.sql 五个指标属性的默认值、校验与配置示例见[指标业务属性](docs/semantic-layer.md#5-指标业务属性)。 -浏览器打开 http://localhost:3000 ,使用 `admin` / `ADMIN_INIT_PASSWORD` 登录后,先在「数据源管理」接入业务库,在「语义管理」同步表结构并维护表/列/指标口径,再到聊天框用自然语言提问,例如:*"上个月各区域销售额是多少?"* 用户与角色入口在「系统管理」。 +浏览器打开 http://localhost:3000 ,使用 `admin` / `ADMIN_INIT_PASSWORD` 登录后,先在「数据源管理」接入并激活业务库(新建数据源默认禁用),在「语义管理」同步表或普通视图并维护表/列/指标口径,再到聊天框用自然语言提问,例如:*"上个月各区域销售额是多少?请用柱状图展示。"* 用户与角色入口在「系统管理」。 -新会话由后端 `POST /api/agent/session` 创建,再用返回的会话 ID 发起 SSE 请求;在聊天页选择本次会话可用的数据源;不选表示全部可访问数据源,后续消息可调整选择。普通用户需先获得功能权限和目标表授权,配置步骤见[权限说明](docs/permissions.md)。 +新会话由后端 `POST /api/agent/session` 创建,再用返回的会话 ID 发起 SSE 请求。当前聊天页不传 `datasourceIds`,每次消息默认使用全部可访问的启用数据源;自定义客户端可按消息指定范围,见[会话协议](docs/architecture.md#会话与数据源协议)。普通用户需先获得功能权限和目标表或视图授权,配置步骤见[权限说明](docs/permissions.md)。 ## 📚 文档 @@ -156,7 +159,10 @@ mysql -u root -p data_agent < sql/migration.sql | [docs/configuration.md](docs/configuration.md) | LLM、数据源、Skill、MCP 配置 | | [docs/semantic-layer.md](docs/semantic-layer.md) | 语义层概念与管理 | | [docs/permissions.md](docs/permissions.md) | 功能权限、表列数据范围与升级 | +| [docs/csv-import.md](docs/csv-import.md) | CSV 托管库配置、导入、恢复与删除 | +| [docs/charts.md](docs/charts.md) | SQL 结果绘图、字段映射与限制 | | [docs/skills.md](docs/skills.md) | Skill 编写、加载路径与生效方式 | +| [docs/external-agent.md](docs/external-agent.md) | PAT、REST 工具、CLI 与外部 Skill | | [docs/observability.md](docs/observability.md) | OpenTelemetry 链路、指标与日志 | | [docs/contributing.md](docs/contributing.md) | 开发环境与贡献流程 | diff --git a/data-agent-cli/README.md b/data-agent-cli/README.md index e0ecfab..7e995d5 100644 --- a/data-agent-cli/README.md +++ b/data-agent-cli/README.md @@ -61,6 +61,10 @@ printf '{"datasource_id":1}' | data-agent-cli tools call get_domains --input - `execute_sql` 只支持 SELECT。查询结果最多返回 200 行,需要更多数据时使用 `LIMIT/OFFSET` 分页。 +当前 REST 工具为 `get_datasources`、`get_domains`、`get_tables`、`get_table_schema`、`get_metric_caliber` 和 `execute_sql`。多数据源时显式传 `datasource_id`;表与普通视图共用语义和授权。`generate_chart` 等内置聊天工具不对 CLI 暴露。 + +创建 PAT 需要 `access:pat:manage`,工具执行仍要求所属用户具备 schema、SQL 或指标权限及目标表列授权。完整权限及直接 REST 调用说明见[外部接入指南](../docs/external-agent.md)。 + ## Agent 指南 输出面向外部 Agent 的 Markdown 使用指南: @@ -85,6 +89,8 @@ data-agent-cli tools call get_tables \ CLI 会自动发送 W3C `traceparent`。同一 session 在 30 分钟空闲窗口内复用同一个 traceId。 +`--session-id` 作为 `X-Session-Id` 发送,用于外部调用上下文及 trace 分组;它不会创建 Web 聊天会话,也不保存或自动续接模型推理历史。 + ## 配置 配置路径: @@ -115,12 +121,15 @@ TRACEPARENT Token 优先级:`--token` > 配置文件 > `DATAAGENT_TOKEN`。 +`auth login` 使用 `--token`、`DATAAGENT_TOKEN` 或交互输入;不会复用配置中已有 Token。部署到其他地址时使用 `auth login --base-url https://dataagent.example.com --token pat_xxx` 保存服务根地址,不追加 `/api`。配置加载器会填入默认 Base URL,因此建议显式保存地址,不依赖 `DATAAGENT_BASE_URL` 覆盖已加载配置。 + ## 输出 - 交互式终端:输出人类可读文本或表格 - `--json` 或 stdout 非 TTY:输出 JSON - `--json` 模式下错误也以 JSON 输出到 stdout - 日志、进度、警告和 `--verbose` 详情输出到 stderr +- 工具内部失败也可能收到 HTTP 200;CLI 检查结果中的 `metadata.errorCode`,并以退出码 `5` 结束 退出码: diff --git a/data-agent-frontend/README.md b/data-agent-frontend/README.md index 33d866b..085eb25 100644 --- a/data-agent-frontend/README.md +++ b/data-agent-frontend/README.md @@ -31,15 +31,16 @@ src/ ├── styles/ # main.css、theme.css ├── utils/ # 下载、日期、报告模板与交互工具 ├── views/ -│ ├── chat/ # 流式对话、会话历史、数据源选择 -│ ├── data-source/ # 数据源管理 -│ ├── semantic/ # 领域、表列语义、逻辑关系与画布 +│ ├── chat/ # 流式对话、会话历史、交互图表 +│ ├── data-source/ # 数据源管理、CSV 上传与任务面板 +│ ├── semantic/ # 领域、表/视图与列语义、逻辑关系与画布 │ ├── metric/ # 指标口径 │ ├── report/ # 报告资产 │ ├── table-export/ # CSV 导出资产 │ ├── evidence/ # 数据证据 │ ├── sys-user/ # 用户及资料、密码、角色对话框 │ ├── sys-role/ # 角色、功能权限与数据范围 +│ ├── settings/ # 本人 PAT 管理 │ └── login/ # 登录 ├── App.vue # 根组件 ├── main.ts # 入口文件 @@ -81,17 +82,22 @@ npm run build ## 页面与会话行为 -| 入口 | 路由 | -| ----------- | ------------------------------------------------------------------------------- | -| AI 智能分析 | `/chat`、`/chat/:sessionId` | -| 数据源管理 | `/data-source` | -| 语义管理 | `/semantic/domain`、`/semantic/table`、`/semantic/metric`、`/semantic/relation` | -| 资产管理 | `/asset/report`、`/asset/table-export`、`/asset/evidence` | -| 系统管理 | `/system/user`、`/system/role` | +| 入口 | 路由 | +| ------------ | ------------------------------------------------------------------------------- | +| AI 智能分析 | `/chat`、`/chat/:sessionId` | +| 数据源管理 | `/data-source` | +| 语义管理 | `/semantic/domain`、`/semantic/table`、`/semantic/metric`、`/semantic/relation` | +| 资产管理 | `/asset/report`、`/asset/table-export`、`/asset/evidence` | +| 系统管理 | `/system/user`、`/system/role` | +| API 访问令牌 | `/settings/tokens` | `stores/user.ts` 从 `/api/auth/me` 获取当前权限,路由 `meta.permission` 与 `v-permission` 控制入口和按钮。路由权限数组满足任一项即可;例如只有 `analysis:session:read` 也能查看聊天历史,输入与新建仍要求 `analysis:chat:use`。后端负责最终授权。 -`useAgentChat` 先通过 `POST /api/agent/session` 获取服务端 ID,再用原生 `fetch` 消费 SSE;不在浏览器生成会话 ID。`ChatDatasourceSelect.vue` 在发出消息后锁定数据源选择。流式事件或历史回放中的 `ask_user` 由前端收集回复,再通过 `toolResults` 继续请求。 +`useAgentChat` 先通过 `POST /api/agent/session` 获取服务端 ID,再用原生 `fetch` 消费 SSE;不在浏览器生成会话 ID。当前聊天页没有数据源选择控件,发送消息和反问续接均不传 `datasourceIds`,每条请求使用当前用户全部可访问的启用数据源。后端和 `ChatRequest` 类型已支持显式范围,自定义调用见[会话协议](../docs/architecture.md#会话与数据源协议)。流式事件或历史回放中的 `ask_user` 由前端收集回复,再通过 `toolResults` 继续请求。 + +`ChatMessage.vue` 从 `generate_chart` 的工具结果读取 `chart`,通过 `ChatChart.vue` 和 `utils/chartOption.ts` 渲染 ECharts,支持流式结果和历史回放;当前没有独立图表事件或资产页面。类型、参数和数据限制见[图表指南](../docs/charts.md)。 + +`CsvUploadDialog.vue` 与 `CsvImportPanel.vue` 提供预览、字段配置、异步任务状态及恢复入口;后端托管库配置见[CSV 导入](../docs/csv-import.md)。语义列表、同步候选、关系画布及角色授权展示 `TABLE` / `VIEW` 对象类型;视图授权独立于底表。`settings/PatView.vue` 管理本人令牌,受 `access:pat:manage` 控制。 ## 开发规范 @@ -194,4 +200,4 @@ npm run format:check npm run build ``` -`npm test` 当前执行 `tests/roleDataScope.test.mjs`。自动修复命令为 `npm run lint`,格式化命令为 `npm run format`;不要把自动修复命令当作 CI 的只读检查。更多约定见 [CODE_STYLE.md](CODE_STYLE.md) 和[贡献指南](../docs/contributing.md)。 +`npm test` 通过 Node 内置测试运行器执行 `tests/roleDataScope.test.mjs` 和 `tests/chartOption.test.mjs`,覆盖角色数据范围与图表配置;当前前端 CI 未自动运行这些测试,相关改动需本地补跑。自动修复命令为 `npm run lint`,格式化命令为 `npm run format`;不要把自动修复命令当作 CI 的只读检查。更多约定见 [CODE_STYLE.md](CODE_STYLE.md) 和[贡献指南](../docs/contributing.md)。 diff --git a/docs/README.md b/docs/README.md index 6fe24ff..898652a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,12 +9,20 @@ | 1 | [getting-started.md](getting-started.md) | 想跑起来的人 | 环境准备、建库、启动前后端、第一次提问 | | 2 | [architecture.md](architecture.md) | 想理解系统的人 | 系统组成、会话协议、请求流转、数据证据、模块划分与 API | | 3 | [configuration.md](configuration.md) | 要部署/接入的人 | LLM 提供商、元数据库、查询数据源、Skill、MCP 配置、安全提示 | -| 4 | [semantic-layer.md](semantic-layer.md) | 要维护业务知识的人 | 语义层概念、管理界面、同步机制、指标业务属性与API示例 | +| 4 | [semantic-layer.md](semantic-layer.md) | 要维护业务知识的人 | 表与普通视图、同步机制、指标业务属性与 API 示例 | | 5 | [skills.md](skills.md) | 要扩展 Agent 能力的人 | Skill 编写、工作目录、加载与生效方式 | | 6 | [external-agent.md](external-agent.md) | 要接入外部 Agent 的人 | PAT、`/agent/**` REST、CLI、Skill 安装与使用 | | 7 | [observability.md](observability.md) | 要观测/排障的人 | OpenTelemetry trace/metrics/logs、配置开关、任意 OTLP 后端(Grafana LGTM 示例) | | 8 | [permissions.md](permissions.md) | 要配置权限的人 | 权限点、角色授权、数据范围与数据库升级 | | 9 | [csv-import.md](csv-import.md) | 要导入文件的人 | CSV 导入库配置、字段类型、任务恢复与权限 | +| 10 | [charts.md](charts.md) | 要用图表分析数据的人 | 图表提问、SQL 结果快照、工具参数、限制与排障 | + +## 按任务查找 + +- **首次部署或升级**:[快速开始](getting-started.md) → [配置](configuration.md) → [权限](permissions.md)。 +- **分析 CSV 文件**:[CSV 导入](csv-import.md) → [语义层](semantic-layer.md) → [图表](charts.md)。 +- **查询已有数据库视图**:[表与普通视图](semantic-layer.md#表与普通视图) → [视图授权](permissions.md#普通视图)。 +- **接入外部 Agent**:[REST、PAT 与 CLI](external-agent.md);外部 Skill 与后端 Skill 的区别见 [Skill 指南](skills.md)。 ## 贡献相关 diff --git a/docs/architecture.md b/docs/architecture.md index 903a793..a280bdd 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,11 +6,13 @@ | 组件 | 技术 | 职责 | | --- | --- | --- | -| 前端 | Vue 3 + TypeScript + Vite + Element Plus | 聊天界面、数据源管理、语义管理、资产与数据证据、系统管理 | -| 后端 | Spring Boot 4.0.3(Java 17+)、AgentScope 1.0.11、MyBatis-Plus | Agent 推理、工具执行、语义层、数据源、会话、权限、MCP 配置管理 | +| 前端 | Vue 3 + TypeScript + Vite + Element Plus + ECharts | 流式聊天与图表、数据源与 CSV 导入、语义管理、资产与数据证据、系统管理、PAT 设置 | +| 后端 | Spring Boot 4.0.3(Java 17+)、AgentScope 1.0.11、MyBatis-Plus | Agent 推理、工具执行、语义层、CSV 任务、会话、权限、PAT 与外部 REST 工具、MCP 配置管理 | | Skill 系统 | 多源加载(文件系统 / Git / Nacos / classpath) | 加载"已验证查询模式"作为可复用流程 | -| 元数据库 | MySQL | 存语义层、数据源、会话、MCP 配置、报表、用户、角色与权限等 | +| 元数据库 | MySQL | 存语义层、数据源、会话、CSV 任务、PAT 哈希、MCP 配置、报表、用户、角色与权限等 | | 查询数据源 | JDBC 关系型数据库 | 用户真正要查的业务库,由 Agent 动态连接;默认内置 MySQL 驱动,其他类型需添加驱动并验证 SQL 方言 | +| CSV 托管库(可选) | 独立 MySQL 数据库 | 保存 CSV 导入表,分析使用只读连接,导入使用专用写连接;不复用元数据库 | +| 外部 CLI / Skill | `data-agent-cli` / `data-agent-skill` | 外部 Agent 用 PAT 调用只读 REST 工具,自行推理和编排 | > 后端根包名为 `io.github.malonetalk`,应用名 `data-agent-management`,默认端口 `8080`。 @@ -63,12 +65,18 @@ `datasourceIds` 为本会话允许使用的数据源列表;省略或传空数组表示当前用户所有可访问的启用数据源。服务端会按用户当前表授权过滤,并把解析后的列表保存到 `session_datasource`(逻辑删除旧范围,一行一个数据源)。每次请求都可以更新该列表。 -工具调用采用显式数据源:存在多个可选数据源时,`get_tables`、`get_table_schema`、`get_metric_caliber`、`execute_sql` 和 `export_table` 必须传 `datasource_id`;只有一个数据源时可以省略。`get_datasources` 用于列出本会话可用的数据源。不同数据源的同名表不能混用。数据源权限在每次工具调用时重新检查,撤权或删除后会拒绝后续操作。 +当前 Web 聊天页没有数据源选择控件,`useAgentChat` 也不传 `datasourceIds`,因此每条消息都使用上述默认范围;管理页切换数据源不会改变聊天范围。自定义客户端可以传入该字段限定范围,后续消息及反问续接也应携带所需范围,省略时不会沿用上一次显式选择。 + +工具调用采用显式数据源:存在多个可选数据源时,`get_domains`、`get_tables`、`get_table_schema`、`get_metric_caliber`、`execute_sql` 和 `export_table` 必须传 `datasource_id`;只有一个数据源时可以省略。`get_datasources` 用于列出本会话可用的数据源。不同数据源的同名表不能混用。数据源权限在每次工具调用时重新检查,撤权或删除后会拒绝后续操作。多数据源表示按工具调用分别查询,不会自动建立跨数据库 JOIN。 会话列表仅展示 `AGENTSCOPE_` 命名空间且已有会话内容的记录。无此前缀的旧会话不会出现在列表中;创建接口登记归属后,空会话也不会立即出现在历史列表。历史、调试与删除接口使用数据库中的归属记录检查访问,不通过解析 ID 推断权限。 `ask_user` 的回复通过同一 SSE 接口的 `toolResults` 提交,每项包含 `toolCallId`、`toolName`、`output`;仅接受属于该会话的 `ask_user` 调用。流事件包括 `thinking`、`text`、`tool_call`、`tool_result`、`question`、`report`、`summary` 和 `error`,错误事件包含 `errorCode`。 +### 图表生成 + +`execute_sql` 在工具结果 metadata 中保存查询快照并返回 `Result ID`。`generate_chart` 只接收结果引用、图表类型和字段映射,从本会话记忆读取真实数据,重新授权后生成图表。图表通过 `tool_result.toolResult.chart` 传输,由前端 ECharts 展示,并随会话支持历史回放;没有独立图表 SSE 事件。类型、参数和限制见 [charts.md](charts.md)。 + ### 数据证据 `agent.provenance` 从服务端工具事件构建证据,并按 `(sessionId, answerId)` 保存到 `answer_provenance`。调用 `execute_sql`、`export_table`、`get_metric_caliber` 或 `execute_python` 时会生成记录;正常结束标记 `COMPLETE`,中断或异常标记 `PARTIAL`,只进行纯文本回答时不一定有证据。 @@ -81,12 +89,13 @@ | --- | --- | | `agent` | Agent 主循环、会话、数据源连接管理、模型工厂与提供商 | | `agent.models` | LLM 提供商抽象:OpenAI / Ollama / DashScope / Anthropic | -| `agent.tools` | 工具集:SQL、Python、schema、域/表、指标口径、反问、报表、CSV 导出、日期 | +| `agent.tools` | 工具集:SQL、Python、图表、schema、域/表/视图、指标口径、反问、报表、CSV 导出、日期;`@RestTool` 声明只读 REST 工具 | | `agent.skill` | Skill 多源加载(文件/Git/Nacos/classpath) | | `agent.provenance` | 回答证据构建与合并(`AnswerProvenanceBuilder`)、存储与查询、SQL 表列来源解析 | | `controller` | HTTP 接口:Agent、数据源、域、语义层、报表、MCP Server、用户管理、角色权限 | | `service` | 数据源、用户角色、功能与数据权限、SQL 授权、资产服务;`SqlQueryScope` 与 `SqlExpressionInspector` 检查 SQL 作用域和表达式 | | `service.semantic` | 语义层 CRUD、同步、关系、合并;`SemanticSyncDiffService` 计算差异,`SemanticSyncApplyService` 事务写入,`RelationWorkspaceService` 组装关系画布 | +| `service.csv` | CSV 预览、异步导入、语义发布、恢复、删除与补偿清理;持久队列在元数据库,物理数据在独立托管库 | | `interceptor` / `model.holder` | JWT 与权限拦截、审计填充、当前用户上下文 | | `model.po` / `model.dto` / `model.vo` / `model.bo` | 新持久化、请求、响应与内部业务模型;新 PO 继承 `BasePo`,对外 VO 实现 `BaseVo` | | `model.converter` / `convertor` | MapStruct 与专用转换:数据源、指标提示、JDBC 元数据和 CSV、会话历史、证据等 | @@ -111,6 +120,7 @@ | --- | --- | --- | | POST | `/api/auth/login` | 登录,返回 JWT token | | GET | `/api/auth/me` | 本人资料、角色与有效权限 | +| GET/POST/DELETE | `/api/auth/pats[/...]` | 本人 PAT 列表、创建与吊销,需要访问令牌管理权限 | | POST | `/api/agent/session` | 创建本人会话,返回服务端分配的 ID | | POST | `/api/agent/chat/stream` | 发起一次流式对话(SSE) | | GET | `/api/agent/sessions` | 列出会话 | @@ -123,6 +133,9 @@ | 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/csv-imports[/...]` | CSV 预览、确认、状态、同步重试与删除,见 [csv-import.md](csv-import.md) | +| GET | `/agent/health`、`/agent/tools` | PAT 鉴权检查与只读工具目录;不使用 Web JWT | +| POST | `/agent/tools/{name}` | PAT 调用指定只读工具,见 [external-agent.md](external-agent.md) | | REST | `/api/datasource`、`/api/domains`、`/api/semantic/*`、`/api/metric`、`/api/reports`、`/api/table-exports` | 数据源、域、语义层、指标口径、报表与表格导出 | > 前端导航当前收敛为「AI 智能分析」「数据源管理」「语义管理」「资产管理」「系统管理」。「语义管理」包含数据领域、表语义、指标口径与逻辑外键;「资产管理」包含报告管理、表格导出与数据证据(`/asset/evidence`);「系统管理」包含用户管理与角色管理。入口和按钮按权限显示。旧路由 `/metric`、`/report`、`/table-export`、`/sys-user`、`/sys-role` 会重定向到对应新入口。 @@ -160,6 +173,7 @@ HTTP server span | `get_domains` / `get_tables` / `get_table_schema` | 读取指定数据源的领域、表与字段语义,按当前用户的数据范围过滤;多数据源时必须传 `datasource_id` | | `get_metric_caliber` | 检索指定数据源的指标口径与业务属性;多数据源时必须传 `datasource_id` | | `execute_sql` | 仅执行通过校验与授权的 SELECT;最多返回 200 行,超时 30 秒;无 LIMIT/FETCH 时包装查询探测第 201 行,判断截断;多数据源时必须传 `datasource_id` | +| `generate_chart` | 用本会话 SQL 结果生成柱状图、折线图、饼图或散点图;重新检查 SQL 与数据权限,结果非空且未截断,最多 20 条系列;见 [charts.md](charts.md) | | `execute_python` | 调用后端环境的 `python3 -I`,代码内联数据并打印结果;30 秒超时,单实例最多 5 个并发执行 | | `export_table` | 授权后导出 CSV;最多 10000 行,超限报错,查询超时 120 秒;多数据源时必须传 `datasource_id` | | `generate_report` | 保存 Markdown 报告,供报告资产页查看 | diff --git a/docs/charts.md b/docs/charts.md new file mode 100644 index 0000000..a7b9ce0 --- /dev/null +++ b/docs/charts.md @@ -0,0 +1,74 @@ +# 交互图表 + +聊天中的 `generate_chart` 工具可以将本会话 `execute_sql` 的真实查询结果绘制成图表。前端使用 ECharts 展示,支持柱状图、折线图、饼图和散点图。 + +## 使用方式 + +先接入并激活数据源、同步表或普通视图,再用自然语言说明统计口径和图表类型,例如: + +- “统计上个月各区域销售额,用柱状图展示。” +- “按月汇总今年销售额和退款额,画成折线图。” +- “把刚才的区域销售额改成饼图。” + +Agent 先在 SQL 中完成聚合、筛选与排序,再使用返回的 `Result ID` 指定字段绘图。修改图表类型时可以复用本会话的同一份结果;修改统计口径或获取最新数据时应重新执行 SQL。绘图读取已保存的查询快照,不会重新查询数据库。 + +普通用户需要 `analysis:chat:use`、`data:schema:read`、`analysis:sql:execute` 及目标表或视图的访问权限;当前没有单独的图表权限点。绘图前会重新检查数据源范围、SQL 权限和表列权限。详见 [权限说明](permissions.md)。 + +## 工具参数 + +以下是 Agent 调用 `generate_chart` 的参数示例;`result_id` 必须替换为本会话 `execute_sql` 返回的值,字段名必须与查询结果列名或别名完全一致: + +```json +{ + "result_id": "", + "chart_type": "bar", + "title": "各区域销售额", + "x_field": "region", + "y_fields": ["sales"], + "series_field": "" +} +``` + +| 参数 | 必填 | 说明 | +| --- | --- | --- | +| `result_id` | 是 | 本会话内的 SQL 结果引用,不能引用其他会话的结果 | +| `chart_type` | 是 | `bar`、`line`、`pie` 或 `scatter` | +| `title` | 是 | 图表标题 | +| `x_field` | 是 | 分类字段;散点图中为数值横轴 | +| `y_fields` | 是 | 非空且不重复的数值字段列表 | +| `series_field` | 否 | 分组字段;省略或空字符串表示不分组 | + +工具只接受结果引用和字段映射,不接受模型手写的数据、JavaScript 代码或任意 ECharts 配置。 + +## 图表与数据限制 + +| 类型 | 数据要求 | +| --- | --- | +| 柱状图 / 折线图 | 可使用多个指标和可选分组;同一个横轴值与分组值的组合只能有一行。指标允许部分值为 NULL,但每个指标至少有一个有效数值 | +| 饼图 | 只允许一个指标、不允许分组;指标必须为非负数且至少一个值大于 0,不能有 NULL;分类值不能重复 | +| 散点图 | 横轴和各指标必须为有限数值,不能有 NULL;允许重复坐标 | + +所有类型都要求横轴字段非 NULL;启用分组时分组字段也不能为 NULL。分组数量乘以指标数量最多为 20 条系列;无分组时按一个分组计算。 + +查询结果必须非空且未截断。`execute_sql` 最多返回 200 行;需要展示更多原始记录时,应先在 SQL 中按业务维度聚合或筛选。不要只截取部分记录来绘制声称覆盖全量数据的图表。 + +SQL 结果快照序列化后最多为 256 KiB。超限时 SQL 查询仍返回文本结果,但不保存绘图快照,并提示 `Chart snapshot exceeds size limit`;减少查询列或聚合后重查。旧会话中没有结果快照的 SQL 也需要重新执行。 + +## 流式传输与历史 + +成功绘图沿用 `tool_result` 事件:`toolResult.name` 为 `generate_chart`,`toolResult.chart` 包含 `spec` 和 `rows`,没有独立的 `chart` SSE 事件。`spec` 使用 `chartType`、`title`、`xField`、`yFields`、`seriesField` 等驼峰字段名。 + +图表随工具结果保存到会话,历史回放会重新渲染。图表展示在聊天消息中,当前没有独立的图表资产页,也未通过 `/agent/**` REST 接口暴露 `generate_chart`。外部接入能力见 [外部 Agent 接入](external-agent.md)。 + +## 常见问题 + +| 现象 | 处理方式 | +| --- | --- | +| 找不到 Result ID | 确认引用来自当前会话;旧结果无快照或快照超限时重新查询 | +| 结果被截断 | 缩小范围或在 SQL 中聚合后重新绘图 | +| 维度重复 | 在 SQL 中按 `x_field` 和可选的 `series_field` 聚合 | +| 指标不是数值 | 先在 SQL 中转换为数值;金额和百分号等展示文本不适合作为指标列 | +| 系列超过 20 条 | 减少指标或分组数量 | +| 改图时权限被拒绝 | 检查当前数据源状态、SQL 权限和表列授权;历史快照不会绕过当前权限 | + +实现入口:后端 `GenerateChartTool`、`ChartService`、`ChartConverter`;前端 `ChatChart.vue` 与 `utils/chartOption.ts`。 diff --git a/docs/configuration.md b/docs/configuration.md index d4f398c..ab3310a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,6 @@ # 配置 -本文汇总 Data Agent 的各项配置:元数据库、LLM 提供商、应用参数、查询数据源、Skill 加载源、MCP Server 注册。所有配置键均可在 `application.properties` 中写死,也可用**环境变量**覆盖(推荐用于密钥与部署差异)。 +本文汇总 Data Agent 的各项配置:元数据库、LLM 提供商、应用参数、查询数据源、CSV 导入、Skill、MCP 与认证。配置来源以 `data-agent-backend/src/main/resources/application.properties`、`skill.properties` 和 `docker/docker-compose.yml` 为准;密钥与部署差异通过环境变量覆盖。 ## 1. 元数据库 @@ -18,6 +18,8 @@ 已经完成主键关联升级的旧库也需执行,以补齐计算方式、结果类型、单位、倍率、币种及回答溯源表;新增字段逐列检查是否存在,回答溯源表按需创建,可重复执行。 数据源升级还会补齐 `updater_id` 和 `is_deleted`。删除数据源改为逻辑删除,保留原记录及关联元数据;列表和会话数据源解析会排除已删除的数据源。`session_datasource` 升级为多数据源范围并补齐审计字段,工具调用会重新校验数据源权限。 +最新迁移还包含 CSV 托管数据源与 `csv_import`、个人访问令牌表 `user_pat`,以及 `table_info.object_type`(`TABLE` / `VIEW`)。停止旧后端写入后执行;迁移不会自动创建 CSV 物理库、账号或授予角色新权限。历史对象类型需再次完整同步,见 [表与普通视图](semantic-layer.md#表与普通视图)。 + 指标属性的配置规则与接口示例见 [语义层](semantic-layer.md#5-指标业务属性)。 ## 2. LLM 提供商 @@ -100,11 +102,14 @@ CSV 按 JDBC 类型转换:布尔、数值、字符和日期时间类型使用 ### 数据源接口与会话范围 -- 创建的数据源默认 `INACTIVE`。聊天页可选择多个数据源;不选择时使用当前用户所有可访问的启用数据源。数据源范围会按消息更新,工具通过 `datasource_id` 指定实际查询目标。 +- 创建的数据源默认 `INACTIVE`,需通过页面或 `PUT /api/datasource/{id}/activate` 激活后用于分析。后端聊天接口支持 `datasourceIds` 限定范围;当前聊天页没有选择控件,每条消息使用全部可访问的启用数据源,工具通过 `datasource_id` 指定实际查询目标。 - 更新时 `name`、`type` 必填;可选字段未传或为 `null` 时保留原值,可选字符串可用 `""` 清空,密码传空字符串仍保留原密码。更新、删除会清理该源的连接池缓存。 - 删除为逻辑删除,保留语义及会话数据源范围。已选择的数据源被删除或撤权后,后续工具调用会拒绝;可在下一条消息中调整数据源选择。 - 数据源创建、更新、删除与启停接口返回 `data: { "value": true }`;列表与摘要选项的 `data` 仍是数组,字段查询仍是表名到列名数组的映射。读取接口不返回密码。 - `GET /api/datasource/options` 供聊天、表语义、逻辑外键与指标页面共享,按表授权过滤,只含 `id`、`name`、`type`、`status`。 +- `GET /api/datasource/{id}/objects` 返回已同步对象的 `tableName` 与 `objectType`,用于表/视图授权;`/{id}/tables` 保留名称数组的兼容格式。这两个接口和 `/{id}/columns` 都要求 `sys:role:grant`,不面向普通分析用户。 + +普通视图和表共用语义同步及表列授权,但底表授权不自动继承到视图。CSV 托管数据源不能通过普通数据源接口修改连接或删除,启用方式见下文。 普通查询最多返回 200 行、超时 30 秒;导出最多 10000 行、超时 120 秒。JDBC 驱动解决连接问题,实际 SQL 还需符合目标库方言及当前授权解析器支持范围,详见 [架构说明](architecture.md#7-agent-内置工具) 和 [权限规则](permissions.md#后端执行规则)。 @@ -160,7 +165,7 @@ Docker 后端工作目录为 `/app`,镜像已复制 `/app/skills`,默认 `./ | --- | --- | --- | --- | | `jwt.secret` | `JWT_SECRET` | 空 | JWT 签名密钥。**生产环境必须设置且长度 ≥ 32 字节**;留空则使用内存随机密钥(仅开发环境可用,每次重启 token 全部失效)。 | | `jwt.expiration-hours` | `JWT_EXPIRATION_HOURS` | `24` | Token 过期时间(小时)。 | -| `admin.init-password` | `ADMIN_INIT_PASSWORD` | 空 | 管理员初始密码。**不设则启动失败(fail-closed)**。仅在 `sys_user` 表为空时首次自动创建 `admin` 用户,表已有数据后不再生效。 | +| `admin.init-password` | `ADMIN_INIT_PASSWORD` | 空 | 管理员初始密码。`sys_user` 为空时必须设置,否则首次启动失败;已有用户后不再生效,也不会重置原密码。 | 对应环境变量写法: @@ -178,6 +183,7 @@ export ADMIN_INIT_PASSWORD="你的管理员密码" - 登录接口 `POST /api/auth/login` 接受 `{ username, password }`,返回 `{ token, user }`。前端将 token 存入 `localStorage`,后续请求通过 `Authorization: Bearer ` 携带。 - `AuthInterceptor` 拦截除 `/api/auth/login` 外的所有接口(含 SSE 流式端点),校验 token 签名与时效。 - 本人资料、修改本人密码等基础接口使用 `@LoginRequired`;业务接口使用 `@RequirePermission`,按当前角色的权限点检查,未声明策略的接口默认拒绝。超级管理员由 `is_super_admin=1` 标记,角色 ID 不代表管理员身份。 +- 外部 Agent 使用 PAT 访问 `/agent/**`,由 `AgentAuthInterceptor` 校验令牌及用户状态;Web JWT 与 PAT 的访问范围隔离。PAT 管理接口 `/api/auth/pats` 仍使用 JWT 和 `access:pat:manage` 权限。有效期、CLI 与 REST 调用见 [external-agent.md](external-agent.md)。 - 「系统管理」中可配置角色功能权限、表白名单与隐藏列黑名单,再为用户分配一个角色。Agent 语义工具、SQL 查询、导出与相关管理操作均执行后端权限校验;权限变更在后续请求和敏感工具调用时重新读取,不写入 JWT。`GET /api/auth/me` 返回当前用户、角色、超级管理员标记与有效权限编码,前端据此控制路由和按钮。完整授权规则见 [permissions.md](permissions.md)。 ### 密码哈希与旧数据迁移 @@ -212,3 +218,21 @@ SELF_CHECK=true mvn -f data-agent-backend/pom.xml clean test -Dtest=SysUserPassw | `management.opentelemetry.logging.export.otlp.endpoint` | `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | `http://localhost:4318/v1/logs` | OTLP logs 地址 | > 仅查看终端日志时无需配置任何项。接入 Collector 时,把对应 `*_ENABLED` 设为 `true` 并指向 OTLP 地址即可;三种信号可独立开启。 + +## 10. CSV 导入(可选) + +分析连接登记在 `datasource` 中并使用只读账号;写连接由后端 `csv-import.*` 配置,两者必须指向同一个独立 MySQL 托管库。完整建库与授权 SQL 见 [csv-import.md](csv-import.md)。 + +| 配置键 | 环境变量 | 配置要求 | +| --- | --- | --- | +| `csv-import.datasource-id` | `CSV_DATASOURCE_ID` | 已登记且启用的 CSV 数据源 ID;不使用时显式设为 `0`,Compose 默认 `0` | +| `csv-import.directory` | `CSV_IMPORT_DIRECTORY` | 可写的持久上传目录;建议手动部署显式设置绝对路径。Compose 固定为 `/app/csv-imports` 并挂载 volume | +| `csv-import.writer-url` | `CSV_WRITER_URL` | 指向独立导入库的 JDBC URL,与只读数据源的实际数据库一致 | +| `csv-import.writer-username` | `CSV_WRITER_USERNAME` | 具有导入库 CREATE、INSERT、DROP 权限的专用账号 | +| `csv-import.writer-password` | `CSV_WRITER_PASSWORD` | 写入账号密码 | + +`spring.servlet.multipart.max-file-size=50MB`、`max-request-size=51MB` 为当前上传限制;解析及导入还有 10 万行、100 列等业务限制,单改 multipart 配置不会扩大这些限制。后台每个实例最多两个任务并发,多实例必须共享上传目录和元数据库。 + +## 11. 图表 + +图表复用 SQL 查询结果,不需要独立服务、绘图库进程或额外数据库配置。当前支持的类型、查询快照大小和系列数量上限由实现固定,见 [charts.md](charts.md);没有可用于调整这些上限的配置键。Python 分析仍需另行准备运行环境。 diff --git a/docs/contributing.md b/docs/contributing.md index 8862206..5bf46df 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -24,12 +24,18 @@ | --- | --- | | `npm run dev` | 启动开发服务器(默认 3000) | | `npm run build` | 类型检查 + 构建 | -| `npm test` | 角色数据范围回归测试 | +| `npm test` | 角色数据范围与图表配置回归测试 | | `npm run lint:check` / `npm run format:check` | ESLint / Prettier 只检查,不修改文件 | | `npm run lint` / `npm run format` | ESLint 自动修复 / Prettier 格式化 | - 前端规范见 `data-agent-frontend/CODE_STYLE.md` 与 `eslint.config.js` / `.prettierrc`。 +### CLI + +- `data-agent-cli/` 是独立 npm 包,运行要求 Node.js 20+;本地开发可统一使用前端的 Node 22 环境。 +- 使用 `npm ci` 安装,`npm run build` 编译,`npm link` 链接本地命令;发布包名为 `@malone-talk/data-agent-cli`。 +- `npm run typecheck` 只检查类型,`npm test` 使用 Vitest;认证与调用步骤见 [external-agent.md](external-agent.md)。 + ## 2. 代码规范(要点) 后端以 `AGENTS.md` 为准,核心原则: @@ -37,6 +43,8 @@ - **保持简单**:文件超过约 400 行、函数超过约 80 行时考虑拆分,保持职责清晰。 - **YAGNI**:当前不需要的接口/参数/抽象先不做。 - **优先复用**:JDK → Spring 原生 → 已引入依赖 → 才自写。 +- **保持分层职责**:Mapper 保持原子持久化操作,业务校验、跨 Mapper 协调与事务放在 Service;Service 按业务职责拆分,避免仅为拆文件增加空转发层。 +- **转换放在转换层**:机械字段映射优先 MapStruct,多步组装使用已有专用转换器;Service 专注业务行为,简单赋值不必额外抽象。 - **不写样板**:用 Lombok(`@Data`/`@Builder`)、MapStruct 生成机械代码;多字段用 `@Builder` 而非长构造器。 - **为下一个读者写**:命名揭示意图,复杂逻辑拆小步。 - **新模型使用 `model.*`**:PO / DTO / VO / BO 放入对应子包;PO 继承 `BasePo`,VO 实现 `BaseVo`。存量 `entity` / `dto` 包仍在迁移,不再新增类型。 @@ -85,10 +93,11 @@ ## 5. 持续集成(CI) -仓库 `.github/workflows/` 下已有两条流水线,PR 会触发: +仓库 `.github/workflows/` 下有三条模块 CI,面向 `main` 的 PR 和推送会触发: - `backend.yml`:JDK 17,执行 `mvn verify --file data-agent-backend/pom.xml`,包含测试、Checkstyle 与 Spotless。 - `frontend.yml`:Node 22,执行 `npm ci`,分别检查 `npm run lint:check`、`npm run format:check` 与 `npm run build`。 +- `cli.yml`:Node 20,执行 `npm ci`、`npm run lint:check`、`npm run format:check`、`npm run build` 和 `npm test`。 从仓库根目录检查后端: @@ -96,7 +105,7 @@ mvn verify --file data-agent-backend/pom.xml ``` -从前端目录检查前端;`npm test` 是现有数据范围回归命令,当前 CI 未自动执行,相关改动应本地补跑: +从前端目录检查前端;`npm test` 包含角色数据范围及图表配置回归,当前前端 CI 未自动执行,相关改动应本地补跑: ```bash cd data-agent-frontend @@ -107,6 +116,20 @@ npm run format:check npm run build ``` +从仓库根目录进入 CLI 后执行其检查: + +```bash +cd data-agent-cli +npm ci +npm run lint:check +npm run format:check +npm run typecheck +npm run build +npm test +``` + +Docker 构建不等于上述完整校验:后端 Dockerfile 使用 `-DskipTests`,前端使用 `pnpm vite build` 跳过 `vue-tsc` 类型检查。提交前仍应运行对应模块命令。仅修改文档时,检查相对链接、示例字段与实际源码的一致性;修改前端或 CLI 目录内的 Markdown 还需通过对应 Prettier 检查。 + ## 6. 行为准则 - 提交代码即表示你同意以 [AGPL-3.0](../LICENSE) 许可证发布你的贡献,以及 [AGPLv3-NOTICE.md](AGPLv3-NOTICE.md) 中的要求。 diff --git a/docs/csv-import.md b/docs/csv-import.md index 0e3f08b..c8a175a 100644 --- a/docs/csv-import.md +++ b/docs/csv-import.md @@ -48,10 +48,12 @@ CSV_WRITER_PASSWORD= 4. 确认导入并等待任务变成 **READY / 已就绪**,核对导入记录数。系统会自动创建物理表,无需手工建业务表;表名为 `csv_t_` 加随机后缀,列名按顺序映射为 `c001`、`c002` 等。 5. 点击已就绪任务行的「表语义」,会自动选中该任务所属的数据源;也可以从数据源列表对应行进入。表语义、指标口径和逻辑外键页顶部均可切换数据源,补充说明、业务域、数据粒度和关联关系。普通角色还需要管理员显式授予对应表权限。 -AI 会话暂不提供数据源选择入口,多数据源选择尚未实现。已有绑定的会话继续使用原数据源;未绑定的会话按后端现有规则使用可访问的启用数据源。管理页面的选择不改变会话数据源,分析前需确认会话实际使用 CSV 数据源。 +当前 AI 聊天页没有数据源选择控件,每条消息默认允许使用当前用户所有可访问的启用数据源,其中可包含 CSV 分析空间。提问时说明数据源和导入表的业务名称,由 Agent 用 `get_datasources` 确定目标;管理页选择不改变聊天范围。自定义客户端可通过 `datasourceIds: [CSV_DATASOURCE_ID]` 限定本次范围,多数据源时工具需传 `datasource_id`。省略该字段会重新使用默认范围,详见 [会话协议](architecture.md#会话与数据源协议)。 添加指标时,用实际物理表名限定字段,不要添加数据库名前缀。需要清理某次导入时,从 CSV 面板删除对应任务,让系统同时清理物理表和语义元数据;存在指标或关联引用时需先移除引用。 +导入表就绪并完成授权后,可以要求 Agent 查询并生成柱状图、折线图、饼图或散点图;绘图沿用 SQL 结果及权限,操作和限制见 [图表指南](charts.md)。CSV 空间只开放系统发布的 READY 表,不通过普通视图同步入口引入手工表或视图。 + - 支持 UTF-8/BOM、GB18030,以及逗号、分号、Tab 分隔。 - 支持带引号的逗号、换行和双引号转义。 - 单文件最多 50 MiB、10 万条记录、100 列;单元格最多 16 KiB(UTF-8)。超过 multipart 文件或请求大小限制时返回 HTTP 413(`PAYLOAD_TOO_LARGE`)。 @@ -70,9 +72,9 @@ PREVIEWED → QUEUED → IMPORTING → DATA_READY → SYNCING → READY 删除 → DELETING → 逻辑删除;失败为 DELETE_FAILED(手动重试) ``` -默认两个导入并发,队列保存在业务库,重启后继续领取任务。连续十分钟未更新的写入任务会被回收并清理;这只是恢复阈值,不代表旧 worker 已停止。每次重新导入使用独立物理表,执行状态更新绑定批次标识,避免旧 worker 恢复后影响新任务。同步中断保留完整物理数据,重试只更新执行批次及提交人;后台按本次提交人的权限执行,管理员可接管原创建人已失去权限的任务,创建人审计信息保持不变。首版不支持断点续传、追加和覆盖。 +每个后端实例最多两个导入并发,每 5 秒轮询元数据库 `csv_import` 中的持久队列,重启后继续领取任务;导入数据写入独立的 CSV 托管库。连续十分钟未更新的写入任务会被回收并清理;这只是恢复阈值,不代表旧 worker 已停止。每次重新导入使用独立物理表,执行状态更新绑定批次标识,避免旧 worker 恢复后影响新任务。同步中断保留完整物理数据,重试只更新执行批次及提交人;后台按本次提交人的权限执行,管理员可接管原创建人已失去权限的任务,创建人审计信息保持不变。首版不支持断点续传、追加和覆盖。 -未确认和写入失败的上传文件保留 24 小时;已成功发布的原文件删除。后台定时补偿文件和失败表清理,并回收失效批次留下的、无注册记录引用的物理表;`csv_t_` 加 32 位十六进制后缀是系统保留的表名空间,请勿手工创建同名格式的表。导入按批次提交数据库事务,失败后通过删除该次物理表补偿;导入及删除不依赖跨库事务,语义元数据与 READY 状态在业务库事务中一起提交。 +未确认和写入失败的上传文件保留 24 小时;已成功发布的原文件删除。后台定时补偿文件和失败表清理,并回收失效批次留下的、无注册记录引用的物理表;`csv_t_` 加 32 位十六进制后缀是系统保留的表名空间,请勿手工创建同名格式的表。导入按批次提交数据库事务,失败后通过删除该次物理表补偿;导入及删除不依赖跨库事务,语义元数据与 READY 状态在元数据库事务中一起提交。 只有 READY 表能被发现、查询和导出,这个限制同样适用于超级管理员。删除会阻止新查询,清理物理表、语义元数据和权限;存在关联关系或指标引用时需先处理引用。指标表达式使用 SQL 解析器识别真实表引用,字符串字面量和注释不计入血缘;未限定的列或通配符、无法识别的表名、子查询和不支持的表达式均保守阻止删除,请先调整该指标口径。 diff --git a/docs/external-agent.md b/docs/external-agent.md index 9006bcf..d5f7ca1 100644 --- a/docs/external-agent.md +++ b/docs/external-agent.md @@ -69,6 +69,8 @@ access:pat:manage 访问令牌:管理 超级管理员默认拥有该权限,但仍需要给普通角色显式授权。 +`access:pat:manage` 只允许管理令牌。读取数据源和语义还需 `data:schema:read`,查询需 `analysis:sql:execute`,指标口径需 `semantic:metric:read`,并配置对应数据源下的表或视图及可见列。仅调用外部只读工具不要求 `analysis:chat:use`。权限在执行时重新检查;`/agent/health` 和工具目录可访问不代表数据查询一定可执行。 + ## 4. 创建 PAT 登录 Web 后进入「API 访问令牌」页面(`/settings/tokens`): @@ -79,6 +81,8 @@ access:pat:manage 访问令牌:管理 每个用户最多保留 10 个未吊销且未过期的 PAT。 +有效期允许在创建后的 1–365 天之间,省略时为 90 天。令牌到期、被吊销或用户停用后不能继续使用。 + ## 5. 安装和使用 CLI CLI 需要 Node.js 20 或更高版本。 @@ -148,6 +152,27 @@ data-agent-cli tools call execute_sql \ Agent 场景建议使用 `--json`,或确保 stdout 不是 TTY。stdout 输出数据或错误 JSON,stderr 输出日志。 +### 直接调用 REST + +不使用 CLI 时,可直接发送 Bearer PAT;Base URL 使用服务根地址,不要追加 `/api`: + +```bash +export DATAAGENT_TOKEN="pat_替换为实际令牌" + +curl -H "Authorization: Bearer ${DATAAGENT_TOKEN}" \ + http://localhost:8080/agent/tools + +curl -X POST http://localhost:8080/agent/tools/get_tables \ + -H "Authorization: Bearer ${DATAAGENT_TOKEN}" \ + -H "Content-Type: application/json" \ + -H "X-Session-Id: run-123" \ + -d '{"datasource_id":1,"domains":["sales"]}' +``` + +接口返回统一 JSON 外层,工具调用的 `data` 包含 `text`、`metadata` 和 `traceId`。工具内部失败可能仍以 HTTP 200 返回,此时 `data.metadata.errorCode` 和 `message` 表示失败,不能只检查 HTTP 状态或外层 `code`。CLI 会识别该类结果并以退出码 `5` 结束。 + +当前没有 `GET /agent/tools/{name}` 详情接口;CLI 的 `tools describe` 从 `GET /agent/tools` 的目录中筛选工具和参数定义。 + ## 6. 安装 Skill `data-agent-skill/` 是可直接复制到外部 Agent Skill 存储目录的文件夹,其中 `SKILL.md` 包含: @@ -181,6 +206,8 @@ data-agent-cli tools call get_tables \ 也可以设置 `DATAAGENT_SESSION_ID`。未提供时后端使用 `__default__` 默认会话。 +CLI 将该值放入 `X-Session-Id`,后端生成 `CLIENT__<外部ID>` 命名空间用于工具调用上下文。该标识用于外部调用分组,不创建 Web 聊天历史、不运行内置 ReAct 循环,也不与 `AGENTSCOPE_` 会话互通。调用方自行保存上下文和编排工具;多数据源时显式传 `datasource_id`。 + ## 8. 配置 配置路径: @@ -202,6 +229,8 @@ Windows: %APPDATA%\data-agent-cli\config.json Token 优先级:`--token` > 配置文件 > `DATAAGENT_TOKEN`。 +Base URL 的解析顺序为 `--base-url` > 配置文件 > `DATAAGENT_BASE_URL` > 默认地址;当前配置加载器会填入默认地址,因此部署到其他地址时建议通过 `auth login --base-url ...` 显式保存。`auth login` 的 Token 来源为 `--token`、`DATAAGENT_TOKEN` 或交互输入,不复用已存 Token。默认请求超时 60 秒,可用 `--timeout` 覆盖。 + 更多命令和退出码说明见 [data-agent-cli/README.md](../data-agent-cli/README.md)。 ## 9. 安全与边界 @@ -209,6 +238,6 @@ Token 优先级:`--token` > 配置文件 > `DATAAGENT_TOKEN`。 - PAT 只能访问 `/agent/**`,不能访问 `/api/**` 用户接口。 - 工具内部仍会重新检查功能权限、数据源权限、表白名单和隐藏列。 - CLI 不保存明文 Token 到日志或错误信息。 -- 配置文件权限为 0600。 -- 当前不提供 MCP、Python 执行、表格导出和报告生成。 +- 配置文件以 0600 权限创建;Windows 的权限语义不同,应通过用户目录的访问控制保护本地配置。 +- 当前不提供 MCP、Python 执行、图表生成、表格导出和报告生成;内置聊天工具不等于 REST 暴露工具。 - `execute_sql` 只允许 SELECT,不替代数据库自身的只读账号约束。 diff --git a/docs/getting-started.md b/docs/getting-started.md index fc24161..807e30f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -98,7 +98,7 @@ Grafana:http://localhost:3001(`admin` / `admin`),在 Explore 中分别 | Maven | 3.9+ | 构建与运行后端 | | Node.js | 22(≥ 22.13) | 与前端 CI 对齐;现有 ESLint 10 不支持 Node 18 | | npm | 随 Node.js 安装 | 按 `package-lock.json` 安装;可选 pnpm 11.24.0,与 Docker 构建一致 | -| MySQL | 8+ | 元数据库(存语义层/数据源/会话等) | +| MySQL | 5.7 或 8.x | 元数据库;SQL 脚本兼容 5.7,Docker 示例使用 8.0 | | Python | 3,命令为 `python3` | 仅 Python 分析工具需要,另安装 pandas、numpy、scipy | 手动启动示例使用 Bash 的 `export`。Windows PowerShell 请使用 `$env:变量名 = "值"`,例如 `$env:ADMIN_INIT_PASSWORD = "你的管理员密码"`;SQL 导入可在 MySQL 客户端执行 `source sql/data_source.sql`(从仓库根目录打开客户端)。 @@ -117,13 +117,13 @@ mysql -u root -p data_agent < sql/data_source.sql > SQL 只保留两份:主文件 `sql/data_source.sql` 包含全部元数据库初始化表结构,新库导入这一份即可;迁移文件 `sql/migration.sql` 用于已有数据库升级。 -已有数据库升级时,不要重复初始化;请先备份数据库,再执行最新迁移脚本。已经完成主键关联升级的旧库也需执行,以补齐指标业务属性、回答溯源、权限及数据源审计字段: +已有数据库升级时,不要重复初始化;请先备份数据库并停止旧版后端写入,再执行最新迁移脚本。已经完成主键关联升级的旧库也需执行,以补齐指标业务属性、回答溯源、权限、数据源审计、CSV 任务、PAT 及表/视图类型字段: ```bash mysql -u root -p data_agent < sql/migration.sql ``` -迁移必须在启动新版后端前完成。该脚本会补齐旧库缺少的字段、索引和回答溯源表,并将列和逻辑关系中的表名引用转换为 +迁移必须在启动新版后端前完成。该脚本会补齐旧库缺少的字段、索引、回答溯源表、`csv_import` 和 `user_pat`,并增加 `table_info.object_type`;历史对象默认 `TABLE`,重新完整同步后更新实际类型。脚本还将列和逻辑关系中的表名引用转换为 `table_info.id` 主键引用;脚本会在改表前检查无法匹配的引用、同一数据源内重复的表名, 以及同一表内重复的列名。脚本还会补齐指标的计算方式、结果类型、单位、倍率及币种,保留旧表达式;新增字段逐列检查是否存在,并创建角色功能权限表和会话归属唯一约束,补齐 `datasource.updater_id` 与 `datasource.is_deleted`。执行前按[权限升级说明](permissions.md#升级现有数据库)检查会话归属冲突。若检查失败,修复数据后重新执行整份脚本即可。 @@ -171,9 +171,9 @@ export JWT_EXPIRATION_HOURS="24" export ADMIN_INIT_PASSWORD="你的管理员密码" ``` -> ⚠️ **`ADMIN_INIT_PASSWORD` 不设会启动失败**(fail-closed)。它仅在看 `sys_user` 表为空时首次生效,已有用户后不再使用。`JWT_SECRET` 留空的后果是每次重启所有已登录用户被迫重新登录——开发环境可接受,生产环境必须设。 +> **空用户库首次启动时必须设置 `ADMIN_INIT_PASSWORD`**(fail-closed),已有用户后不会再用它创建账号或重置密码。`JWT_SECRET` 留空会导致重启后所有 JWT 失效,生产环境必须设置稳定密钥。 -> 各配置键的完整说明见 [configuration.md](configuration.md#7-认证配置jwt--管理员)。Docker Compose 默认注入 `ADMIN_INIT_PASSWORD=admin`,手动启动没有该默认值。 +> 各配置键的完整说明见 [configuration.md](configuration.md#7-认证配置jwt--管理员)。Docker Compose 默认注入 `ADMIN_INIT_PASSWORD=admin`,手动启动没有该默认值。CSV 导入为可选功能;手动运行且不使用时可显式设置 `CSV_DATASOURCE_ID=0`,启用时按 [CSV 指南](csv-import.md) 配置独立托管库、读写账号和持久目录。 > 密码以 BCrypt 存储;若从旧版 PBKDF2 升级,存量用户的旧哈希无法登录,按 [configuration.md 的「密码哈希与旧数据迁移」](configuration.md#密码哈希与旧数据迁移) 重置。 @@ -205,15 +205,17 @@ npm run dev > **先分清两类数据库**:「数据源管理」里配置的是 **Agent 要连接、执行 SQL 数据分析的目标数据库**(你的业务库),不是第 2 步准备的元数据库 `data_agent`(后端存放语义层/数据源配置/会话的库)。元数据库在后端启动时通过环境变量 `DB_URL` 指定,不在页面上配置。 1. 打开 http://localhost:3000 。 -2. 先在「数据源管理」中新增一个你要查的业务库(支持 MySQL / PostgreSQL / Oracle / ClickHouse / SQL Server / 达梦 / OceanBase / SQLite,类型以下拉列表为准)。若该库不是 MySQL,请先确认后端已内置其驱动(见 [常见问题](#常见问题) 第一条)。 -3. 在「语义管理」中同步物理表,再把相关表/列映射成业务语言;指标口径也在这里维护。可按业务配置计算方式、结果类型、单位、倍率和币种,例如分转元的倍率为 `0.01`,百分比的倍率为 `1`,只在展示时乘以100。完整规则见 [指标业务属性](semantic-layer.md#5-指标业务属性)。 -4. 进入聊天界面,选择本次会话可用的数据源(可多选;不选表示全部可访问数据源),输入类似:*"上个月各区域销售额是多少?"*,观察流式回答与生成的 SQL。新会话由服务端分配 ID,后续消息可以调整数据源选择。 +2. 在「数据源管理」中新增业务库并激活;新建数据源默认禁用。支持 MySQL / PostgreSQL / Oracle / ClickHouse / SQL Server / 达梦 / OceanBase / SQLite,非 MySQL 类型须先添加驱动(见 [常见问题](#常见问题) 第一条)。要分析本地文件,先按 [CSV 导入](csv-import.md) 配置并导入,等待任务 READY。 +3. 在「语义管理 → 表语义 → 同步表或视图」选择物理表或普通视图,再把相关表/列映射成业务语言;指标口径也在这里维护。可按业务配置计算方式、结果类型、单位、倍率和币种,例如分转元的倍率为 `0.01`,百分比的倍率为 `1`,只在展示时乘以100。完整规则见 [指标业务属性](semantic-layer.md#5-指标业务属性)。CSV 就绪表已自动同步,可直接完善语义。 +4. 进入聊天界面,输入类似:*"上个月各区域销售额是多少?请用柱状图展示。"*,观察流式回答、SQL 与图表。当前聊天页没有数据源选择控件,默认使用全部可访问的启用数据源;多源时在提问中说明目标名称。自定义客户端可用 `datasourceIds` 限定范围,见 [会话协议](architecture.md#会话与数据源协议)。新会话 ID 由服务端分配。 5. 在「资产管理 → 数据证据」查看回答涉及的 SQL 执行、指标、Python 和表列来源;报告与 CSV 导出也可在资产管理中查看。 > 初始的 `admin` 用户是超级管理员。如需多人使用,在「系统管理」中配置角色的功能权限、表白名单与隐藏列黑名单,再为用户分配角色。Agent 的语义读取、SQL 查询和导出均检查权限;未授权默认拒绝。常用权限组合见 [权限说明](permissions.md#配置角色)。 > 如果回答不准,多半是语义层/指标口径没配好,或数据源尚未接入。参见 [semantic-layer.md](semantic-layer.md) 与 [configuration.md](configuration.md)。 +图表的类型、数据限制与常见错误见 [charts.md](charts.md)。需要从外部 Agent 使用数据时,在「API 访问令牌」创建 PAT,再按 [外部接入指南](external-agent.md) 配置 CLI 或直接调用 REST 工具。 + ## 常见问题 - **新增数据源连接失败,提示「未找到数据库驱动」**:后端默认仅内置 MySQL 驱动。请在 `data-agent-backend/pom.xml` 中添加你所用数据库的 JDBC 驱动依赖(坐标见 [configuration.md](configuration.md#4-查询数据源)),重新构建并启动后端后再试。 diff --git a/docs/permissions.md b/docs/permissions.md index 560b0b0..f46328e 100644 --- a/docs/permissions.md +++ b/docs/permissions.md @@ -49,6 +49,11 @@ ALTER TABLE report DROP INDEX uk_session_id, ADD KEY idx_session_id (session_id) | 查阅会话 | `analysis:session:read` | | 查看数据证据 | `asset:evidence:read`;读取他人会话范围还需 `analysis:session:read-all` | | 查询指标口径 | `semantic:metric:read` | +| 生成聊天图表 | 沿用智能问数权限;绘图时重新检查 `analysis:sql:execute` 与当前数据范围,没有独立图表权限点 | +| Python 分析 | `analysis:python:execute` | +| 上传并导入 CSV | `data:datasource:read`、`data:csv:import`、`semantic:table:sync`;分析导入结果仍需目标表授权 | +| 删除 CSV 导入 | `data:csv:delete`;同时检查任务访问范围及指标、关系引用 | +| 管理本人 PAT | `access:pat:manage`;令牌不额外授予任何工具或数据权限 | | 保存报告 | `asset:report:generate` | | 查看报告列表 | `asset:report:read` | | 创建导出 | `asset:export:create`、`analysis:sql:execute` | @@ -56,7 +61,7 @@ ALTER TABLE report DROP INDEX uk_session_id, ADD KEY idx_session_id (session_id) 查看全部会话需要额外的 `analysis:session:read-all`,它不会授予删除他人会话的权限。清空全部会话需要 `analysis:session:delete-all`。报告、导出默认只允许访问本人会话下的资源;超级管理员保留全量访问。 -`analysis:session:read` 可独立打开聊天页面查阅历史,无需聊天使用权限。输入框、新建会话和数据源选择只对拥有 `analysis:chat:use` 的用户显示;会话删除、报告和数据证据各自检查对应权限。前端收到撤权响应后刷新权限,并强制重新经过当前页面的路由守卫。 +`analysis:session:read` 可独立打开聊天页面查阅历史,无需聊天使用权限。输入框和新建会话只对拥有 `analysis:chat:use` 的用户显示;当前聊天页没有数据源选择控件,默认范围见 [会话协议](architecture.md#会话与数据源协议)。会话删除、报告和数据证据各自检查对应权限。前端收到撤权响应后刷新权限,并强制重新经过当前页面的路由守卫。 仅角色授权管理(`sys:role:grant`,包括功能权限与表列数据范围配置)限超级管理员,其余权限点均可授予普通角色。角色分配由 `sys:user:assign-role` 控制,创建用户时指定非零角色也需要该权限;表结构同步与物理状态刷新由 `semantic:table:sync` 控制,Python 执行由 `analysis:python:execute` 控制。未授权仍默认拒绝。普通角色不能修改超级管理员账号。 @@ -70,7 +75,7 @@ ALTER TABLE report DROP INDEX uk_session_id, ADD KEY idx_session_id (session_id) 视图不要求物理主键或索引,字段来自视图的输出列。同步保留人工维护的描述、领域、粒度和可见性;对象或字段缺失时保留语义记录并标记缺失,重建后需完整同步恢复。元数据读取失败会中止操作;数据库账号权限变化也可能使对象从元数据中消失,因此缺失不一定表示已经删除。 -普通角色必须单独获得视图授权,底表授权和隐藏列规则不会自动传递到视图输出列。查询、导出和 Agent 结构工具继续执行同一套表列授权;访问视图不会自动获得底表访问权限。连接账号也必须具有数据库要求的视图查询及元数据读取权限,按视图的执行权限配置验证。本期只支持当前数据源范围内的普通视图,优先查询对象和业务唯一键配置另行实现。 +普通角色必须单独获得视图授权,底表授权和隐藏列规则不会自动传递到视图输出列。查询、导出和 Agent 结构工具继续执行同一套表列授权;访问视图不会自动获得底表访问权限。连接账号也必须具有数据库要求的视图查询及元数据读取权限,按视图的执行权限配置验证。本期只支持当前数据源范围内的普通视图;当前没有优先查询对象或业务唯一键配置入口。 权限是后端中的逻辑模块,代码沿用项目已有分层目录: @@ -155,6 +160,8 @@ SQL 授权同时返回改写后的查询与本次可见列快照。查询和导 权限撤销会阻止后续查询和工具调用,但不会删除历史会话、报告、证据和已经生成的导出。历史资产读取仍按能力权限及归属检查,不根据当前表列权限追溯撤销。需要追溯撤权时,应另行增加资产数据来源与读取时的重新校验。 +已保存的聊天图表随历史消息回放,沿用会话读取规则;重新调用 `generate_chart` 则会重新检查 SQL 与当前表列权限。CSV 的 READY 状态检查同样适用于超级管理员。PAT 调用仍受所属用户的当前权限约束,工具发现成功不代表具备实际执行权限。详见 [图表](charts.md)、[CSV 导入](csv-import.md) 与 [外部接入](external-agent.md)。 + ## 验证 后端校验命令为 `mvn verify`;前端校验命令为 `npm test`、`npm run build` 和 `npm run lint:check`。回归测试覆盖分页子查询授权、兼容接口鉴权、Service 事务回滚,以及页面加载失败与切换上下文后的保存保护。 diff --git a/docs/semantic-layer.md b/docs/semantic-layer.md index 0f41d71..6100923 100644 --- a/docs/semantic-layer.md +++ b/docs/semantic-layer.md @@ -19,7 +19,7 @@ | 概念 | 说明 | Controller | | --- | --- | --- | | **域(Domain)** | 业务主题分组,如"交易""用户";Agent 会读取域名与描述,用它先判断该去哪些域找表 | `DomainController` | -| **逻辑表** | 给物理表补充业务语义,含领域、表描述、数据粒度(一行代表什么)、可见性、物理表是否存在 | `TableSemanticController` | +| **逻辑表 / 普通视图** | 给物理表或普通视图补充业务语义,含对象类型(`TABLE` / `VIEW`)、领域、描述、数据粒度(一行代表什么)、可见性、物理对象是否存在 | `TableSemanticController` | | **逻辑列** | 给物理列补充业务含义和语义类型(标识、维度、度量、时间、地点);同步缓存会保存物理类型、主键与索引提示,供 Agent 生成 SQL 前参考 | `TableColumnSemanticController` | | **表关系** | 表间 join 路径(一对一/一对多)、启禁状态,供 Agent 多表查询时自动拼 SQL | `TableRelationSemanticController` | | **关系工作区** | 按所选数据源分页查看表与关系画布,支持关键词与排序;仅返回两端都位于当前页且可见的关系 | `TableRelationWorkspaceController` | @@ -28,7 +28,7 @@ ## 3. 同步机制 -- `SchemaReader` 通过 JDBC `DatabaseMetaData` 读取表、列、主键和索引信息,不依赖特定数据库方言。 +- `SchemaReader` 通过 JDBC `DatabaseMetaData` 读取 `TABLE` 和 `VIEW` 对象及其输出列;物理表同时读取主键与索引,普通视图跳过主键和索引读取。 - `service/semantic/sync/*` 将物理表结构同步到 `table_info` / `column_info`,用于形成 Agent 可读取的语义快照;字段同步会写入 `type_name`、`primary_key`、`index_info`、物理描述与物理存在状态。 - 同步不会覆盖已有人工口径:已有 `column_description` 会优先保留,物理描述只作为缺省补充。 - `SemanticAvailabilityHelper` + `ColumnInvalidReasonEnum` / `TableInvalidReasonEnum` 标注不完整或物理缺失的语义信息,提示管理员补齐。 @@ -38,24 +38,34 @@ | 接口 | 用途 | | --- | --- | -| `GET /api/semantic/tables/sync/candidates` | 按 `datasourceId` 获取物理表候选,可分页、关键词过滤与排序 | -| `POST /api/semantic/tables/sync` | 同步选定表的物理结构与语义缓存 | +| `GET /api/semantic/tables/sync/candidates` | 按 `datasourceId` 获取表与普通视图候选,响应含 `objectType`,可分页、关键词过滤与排序 | +| `POST /api/semantic/tables/sync` | 同步选定表或普通视图的物理结构与语义缓存 | | `POST /api/semantic/tables/sync/physical-status` | 刷新物理缺失状态 | | `GET /api/semantic/tables/relations/workspace` | 按 `datasourceId`、`page`、`pageSize`、`keyword`、`sortOrder` 获取关系画布 | 关系画布由 `RelationWorkspaceService` 组装当前页表节点和列,按同一数据权限范围过滤列与关系;跨页关系不在当前画布展示。普通关系列表与画布的查询参数不同,画布不提供 `enabled` 筛选参数。 +### 表与普通视图 + +在「语义管理 → 表语义 → 同步表或视图」选择对象;列表、同步候选、关系画布、角色授权和新生成的数据证据会区分对象类型。接口继续沿用 `tables` 路径和 `tableName` 字段,普通视图与表共用领域、描述、粒度、可见性及关系管理。 + +视图字段来自视图的输出列,不推断底表主键、索引或业务唯一键,也不展开视图定义追溯底表血缘。新证据以实际查询的视图对象记录来源。底表权限和隐藏列不会自动继承到视图,需单独授权视图及其输出列,见 [普通视图权限](permissions.md#普通视图)。 + +升级时先执行 `sql/migration.sql`,为 `table_info` 增加 `object_type`;历史对象默认 `TABLE`,再次完整同步后更新实际类型。刷新物理状态不能替代完整同步,也不会恢复已标记缺失的对象。历史证据不补写对象类型。 + +当前仅支持连接所选 catalog/schema 范围内的普通视图,不额外支持物化视图或跨库对象发现。连接账号需要具备对应元数据与查询权限;CSV 数据源只允许已就绪的导入表,不开放手工视图。 + ## 4. Agent 使用方式 Agent 查询前按需调用语义工具: 1. `get_datasources`:列出当前会话可用的数据源;存在多个数据源时先调用它。 2. `get_domains(datasource_id=...)`:返回可用领域的 `name` 与 `description`,让模型先选业务域。 -3. `get_tables(datasource_id=..., domains=[...])`:返回同步后的表语义,包括表名、领域、描述、数据粒度与已启用表关系。数据粒度说明一行代表的业务实体或事件,例如“每行代表一份订单”。 +3. `get_tables(datasource_id=..., domains=[...])`:返回同步后的表与普通视图语义,包括名称、对象类型、领域、描述、数据粒度与已启用关系。数据粒度说明一行代表的业务实体或事件,例如“每行代表一份订单”。 4. `get_table_schema(datasource_id=..., table_name=...)`:返回同步后的字段信息,包括字段名、物理类型、语义类型、主键、索引提示和字段描述。 5. `get_metric_caliber(datasource_id=..., hint=...)`:返回匹配指标的表达式、过滤、时间字段,以及计算方式、结果类型、标准单位、倍率和币种,供 Agent 确认计算与展示规则。 -上述工具使用当前会话允许的数据源与可信用户上下文;存在多个数据源时必须传 `datasource_id`。领域、表、列和关系结果会按授权范围过滤;SQL 执行仍需再次授权,不能通过跳过 schema 工具绕过表列限制。 +上述工具使用当前会话允许的数据源与可信用户上下文;除列出数据源的 `get_datasources` 外,存在多个数据源时都必须传 `datasource_id`。领域、表、列和关系结果会按授权范围过滤;SQL 执行仍需再次授权,不能通过跳过 schema 工具绕过表列限制。 指标工具根据 `datasource_id` 指定的数据源检索,可以直接传入用户整句问题。当前按名称和拆分后的别名做不区分大小写的包含匹配,忽略不足2个字符的词,不匹配 `metricKey`。按命中词长度排序,最多保留3个候选;只返回第一名的完整口径,其余作为名称与 key 提示。未命中时最多列出5个已有指标,供进一步确认。 @@ -112,6 +122,8 @@ Agent 查询前按需调用语义工具: 更新通过 MapStruct 忽略未传或为 `null` 的字段,保留原值,再按最终结果类型执行校验和归一化。可选文本可以通过空串清空,但已配置普通数值或金额的单位不能清空;结果类型不能用空串重置。金额切为普通数值或百分比时,即使未传 `currencyCode`,也会清除原币种。`unit` 与 `currencyCode` 的持久化配置允许写入 `NULL`,确保清空能实际落库。 +CSV 托管数据源的指标必须用已就绪的物理表名限定字段,例如 `SUM(csv_t_<实际后缀>.c001)`;不能直接沿用上例的未限定字段,也不要增加数据库名前缀。具体使用与删除引用规则见 [CSV 导入](csv-import.md)。 + ## 6. 最佳实践 - **先接数据源,再配语义**:语义依附于物理表,顺序不要反。 diff --git a/docs/skills.md b/docs/skills.md index a3c98d5..c5586a9 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -14,10 +14,11 @@ description: 一句话描述这个 Skill 做什么。 你是一个 XXX 助手。当用户提出 XXX 相关问题时,按以下步骤操作: -1. 使用 `get_domains` 获取可用数据域 -2. 使用 `get_table_schema` 获取表结构 -3. ... -4. 汇总结果返回给用户 +1. 使用 `get_datasources` 确认目标数据源 +2. 使用 `get_domains`、`get_tables` 选择数据域和表或普通视图 +3. 使用 `get_table_schema` 获取字段,必要时用 `get_metric_caliber` 核对指标 +4. 多数据源时在上述语义工具及 `execute_sql` 中显式传入 `datasource_id` +5. 执行 SELECT 并汇总;需要图表时,用返回的 Result ID 调用 `generate_chart` ## 注意事项 @@ -53,3 +54,12 @@ Docker 镜像将仓库 `skills/` 复制到 `/app/skills`,默认路径可直接 | Skill | 说明 | | --- | --- | | `data-query` | 根据表结构生成 SQL 并执行查询,汇总结果 | + +## 后端 Skill 与外部 Agent Skill + +| 目录 | 加载方 | 用途 | +| --- | --- | --- | +| `skills/` | 后端 AgentScope `SkillBox` | 指导内置聊天 Agent 使用服务端工具;由 `skill.properties` 配置来源,更新后重启后端 | +| `data-agent-skill/` | 外部 Agent | 指导调用 `data-agent-cli`;复制到调用方的 Skill 目录,不通过后端加载 | + +两者不共用安装位置。外部 Agent 只能调用 REST 暴露的只读工具,不能因复制 Skill 获得 Python、图表或导出能力;安装与权限见 [external-agent.md](external-agent.md)。内置聊天的绘图流程及字段限制见 [charts.md](charts.md)。