Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 执行及表列来源。
Expand Down Expand Up @@ -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)。

## 📚 文档

Expand All @@ -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) | 开发环境与贡献流程 |

Expand Down
9 changes: 9 additions & 0 deletions data-agent-cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 使用指南:
Expand All @@ -85,6 +89,8 @@ data-agent-cli tools call get_tables \

CLI 会自动发送 W3C `traceparent`。同一 session 在 30 分钟空闲窗口内复用同一个 traceId。

`--session-id` 作为 `X-Session-Id` 发送,用于外部调用上下文及 trace 分组;它不会创建 Web 聊天会话,也不保存或自动续接模型推理历史。

## 配置

配置路径:
Expand Down Expand Up @@ -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` 结束

退出码:

Expand Down
30 changes: 18 additions & 12 deletions data-agent-frontend/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 # 入口文件
Expand Down Expand Up @@ -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` 控制。

## 开发规范

Expand Down Expand Up @@ -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)。
10 changes: 9 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)。

## 贡献相关

Expand Down
Loading
Loading