mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-15 01:51:57 +00:00
ThearchyHelios
2714890d0d
README.zh-CN.md / README.md 只留：这是什么、为什么用它、主要功能（按领域一行一条，链到文档）、快速开始、部署、文档索引、 开发与测试、许可（原文不动）。原来的每一节按读者和任务分到 17 篇主题文档：ask-data、workflows、evidence、 data-sources（新增：接入数据库、只读保证、上传表格、跨库合并、遮罩列）、data-catalog、tools（新增：工具、审批档位、 能力登记、端点、网络规则——它们管所有工作流，不只应用）、apps、evaluation-and-ledger、schedules（含通知）、deployment、 configuration、postgresql-and-scaling、identity-and-security、architecture、development、upgrade-notes（按时间倒序， 每波先写要做的事）、faq。删掉的只有模块名（api/copilot_gen.py、chat/drive.py、data/schema_view.py）、重复的话和 「以前…现在…」的叙述；操作步骤、命令、配置名、限制、权限边界都有归宿。中文是原文，英文按新的中文写；英文里界面文字 只写英文名，开头注明界面目前只有简体中文，中文占位符换成英文占位符，中文数字的例子改成不依赖中文的说法。 数据剖析可以同时剖析 2–3 张表（baf23998）收进 data-catalog。 新增 scripts/check-docs.py：英文文档（README.md、docs/en/**）不许有中日韩字符和全角符号（代码块也算）， README、docs/**、deploy/README.md 的相对链接和锚点都要通，docs/zh-CN 与 docs/en 文件一一对应、标题层级相同。 中文提示里指向 README 章节的地方改指新文档：cluster/guard.py、cluster/version.py、db/base.py 两处报错， data/schema_view.py 文档串，.env.example 三处，scripts/prod.sh、scripts/test-postgres.sh，terms.ts 两处、 DataSourcesTab.tsx、check-manage.mjs 注释，deploy/README.md 三处链接。deploy/agentlab.env 未动。 验收：check-docs 0 问题（英文文档 18 个 0 处中文，相对链接 369 条 0 断链，18 对标题层级一致）；相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。
65 lines
4.7 KiB
Markdown
65 lines
4.7 KiB
Markdown
[English](../en/data-sources.md) | 简体中文
|
|
|
|
# 数据源与表格导入
|
|
|
|
这篇讲怎么接入数据库、上传表格，以及 AgentLab 怎么保证查询只读。给搭建者和管理员看。数据目录（给表和字段记业务含义）见[数据目录](data-catalog.md)。
|
|
|
|
## 接入数据库
|
|
|
|
数据源可以是业务库（MySQL / MariaDB、PostgreSQL、Oracle，驱动在 `[db]` 额外依赖里）、上传的表格，或手工登记的 SQLite 文件。
|
|
|
|
- 接入后点「探查结构」：读表、列、注释、外键和唯一约束。列类型存各数据库的完整写法，例如 `VARCHAR2(20 CHAR)`、`ENUM('a','b')`。
|
|
- 探查是后台任务，和同一个数据源的起草、剖析排队。几千张表的大库先建对象索引，再按探查范围读（见[数据目录](data-catalog.md#大库探查范围与按需加入)）。
|
|
- 一个数据源对应一个 schema。正式探查不接受 `?schema=` 临时换 schema，预览可以。
|
|
- 每个数据源有查询工具 `db_query__<源>`；运行时 agent 用 `db_schema__` 查表结构。
|
|
- 数据源卡片的地址是 `/data/databases#source-<id>`。
|
|
- AgentLab 自己的库文件（例如换成 PostgreSQL 后留在数据目录里的 `agentlab.db`）不能登记成数据源。
|
|
|
|
探查失败和「尚未探查」是两种状态。失败时点按钮解决不了，要先处理超时或更换 schema。数据源卡片会显示失败原因和该服务器上可选的库；agent 也会收到实情，并被告知可以直接查 `information_schema` 自己确认表结构。
|
|
|
|
## 只读保证
|
|
|
|
- SQL 守卫：白名单动词判定、正文扫描、多语句拦截、结果集上限。
|
|
- `DROP` / `TRUNCATE` / `GRANT` 等在可写数据源上也一律拒绝。
|
|
- 以查询开头却会写的语句按写操作处理：`WITH … DELETE`、`SELECT … INTO`、`EXPLAIN ANALYZE`、`PRAGMA … =`、`set_config()` 等。
|
|
- 只读数据源在连接层也只读，不只靠守卫：SQLite 以 `mode=ro` 打开，PostgreSQL / MySQL 的会话事务只读。
|
|
- **Oracle 没有会话级只读开关**，只剩守卫一道。只读的 Oracle 数据源请配只读账号。
|
|
- 可写数据源上，同一个 `db_query__<源>`：查询直接执行，写操作要先确认，确认后才提交。能力登记里的声明不能让写语句免审批。
|
|
- 使用者的问数据和个人应用里，数据源一律只读（见[身份、权限与安全](identity-and-security.md#使用者的问数据)）。
|
|
|
|
## 上传表格
|
|
|
|
Excel / CSV 上传后落成一个 SQLite 文件，注册为 `kind=sqlite` 的数据源，并自动生成 `db_query__<name>` 工具。数字由 SQL 算出来，不靠模型从文本片段里读。
|
|
|
|
- 列类型逐列推断（INTEGER / REAL / TEXT），空单元格存为 NULL。整数列如果落成 TEXT，`ORDER BY` 会退化为字典序（`'10' < '9'`），而且不报错。
|
|
- 为什么不放进知识库：放进去只能被切块检索，数字就成了模型从片段里「读」出来的。产出复核拦得住凭空出现的数字，拦不住「从一堆片段里读错了一格」。
|
|
- 导入表格的数据源，系统按核对结果生成说明；数据目录不重复、也不改写这些说明。
|
|
- 报告里引用的上传表格单元格，可以追到原表的格子（推断的来源）。
|
|
|
|
### 复杂报表用取数配方
|
|
|
|
- 复杂报表按取数配方导入，CSV 同样可以。夹在明细中间的小计，核对后不进数据。
|
|
- 配方的 AI 起草用「设置 → 偏好设置」里选的「起草模型」；空着时跟随助手的模型。
|
|
|
|
### 按期累积
|
|
|
|
- 每月一份的明细可以按期累积成一张表。新的一期可以触发定时任务（见[事件触发](schedules.md#事件触发)）。
|
|
- 每个历史版本是一份完整副本，磁盘占用随期数和被引用的版本数增长。
|
|
- 除当前版本和被运行引用的版本外，每个数据源再保留最近启用过的 3 个版本；其余的会被回收，无法再启用。
|
|
|
|
## 跨库合并
|
|
|
|
跨库的问题不做联邦查询。各库先聚合到同一个键，再用合并查询节点（`merge`）在库外按键合并（内存 SQLite，同一套只读守卫）。
|
|
|
|
- 被截断的输入拒收。
|
|
- 键类型不一致、合并后行数变多，都会提醒。
|
|
- 报告里的数能一路追到两边的原始查询。
|
|
|
|
## 遮罩列
|
|
|
|
在数据源设置里列出要遮罩的列（`mask_columns`），按列名作用于整个数据源。
|
|
|
|
- 遮罩列只把列名和类型交给模型：它的注释、目录里这一列的中文名、码值和说明都不给。
|
|
- 剖析不对遮罩列取样，也不观察它的取值。
|
|
- 对开了登录的使用者，遮罩是边界；对搭建者、管理员和未开启登录时的所有人，遮罩只减少暴露（见[哪些角色看得到原值](identity-and-security.md#哪些角色看得到原值)）。
|