tieveto666-code/dsh-data-mode

dsh-data-mode

一个 DeepSeek Harness (DSH) 插件，新增 Data Mode 会话类型，用于在聊天中进行只读分析。

连接 PostgreSQL、MySQL 或 SQLite，或上传 CSV / Excel 文件。用自然语言提问。智能体会检查 schema、预览行，并运行只读 SQL。你还可以为每个数据源附加业务定义（指标、别名、公式），让回答遵循你的术语体系。

该插件面向原版 DSH（Web UI）。它不会改变内置的 Standard、PTC、Minimal 或 Creative 预设，这些会话也永远不会看到 SQL 工具。新聊天仍默认使用 Standard Mode。数据源面板已本地化为中文和英文。

预览

Data Mode 使用知识定义的指标进行回答：

Data Mode 使用业务知识回答

注册并选择数据源，然后预览表：

数据源注册表和表预览

维护每个数据源的知识（名称、描述、BM25 召回）：

数据源的知识管理

为什么需要它

DSH 擅长编码智能体。Data Mode 面向另一类任务：在不离开对话的情况下，向你自己的表提问，并且不授予模型对数据库的写权限。

典型用途：

- “上个月按类别划分的订单情况如何？”
- “哪些 SKU 库存不足？”
- “使用我们对 GMV 的定义，而不是猜测。”

能力

数据源注册表

从编辑器中的 Data source 控件（仅在 Data Mode 中可见）：

- 连接 PostgreSQL、MySQL 或 SQLite
- 将 CSV 或 XLSX 表上传到工作区（当 DuckDB 可用时，查询引擎也可以读取 CSV / Parquet / XLSX）
- 在提问前预览表和示例行
- 为当前会话精确选择一个数据源（未选择的数据源对智能体不可见）
- 移除已注册的数据源（其知识文件也会随之移除）

密码存储在 $DSH_HOME/data-mode/secrets.yaml 中，而不是目录中。

当目录为空时，会出现内置演示 demo-sqlite 和 demo-xlsx，因此你可以立即试用该流程。

知识管理

每个数据源都有自己的知识列表（键 → 一个或多个值）。用它来定义指标、业务术语和计算规则。

- 在面板中创建、编辑、搜索、分页、批量删除并导出为 XLSX
- 同一个键可以有多个值
- 限制：键 ≤ 100 个字符，值 ≤ 1000 个字符，每个数据源 200 条
- 每次提问时，会召回匹配的键（问题中精确出现的键始终命中；否则对键进行 BM25 检索），并作为口径注入系统提示
- 知识永远不会替代真实的表名或列名；智能体在编写 SQL 之前仍必须描述 schema

Ask-data 智能体

仅在你选择数据源之后可用。工具：

| 工具 | 作用 |
| --- | --- |
| list_data_sources | 仅返回已选择的数据源（在你选择之前为空） |
| describe_schema | 在查询这些表之前必需 |
| preview_rows | 小样本（默认 20 行） |
| run_sql | 只读 SELECT / WITH / EXPLAIN / SHOW / DESCRIBE / PRAGMA |

如果 SQL 不是只读的、LIMIT 超过 5000（默认 200），或者引用的表未事先描述，则 SQL 会被拒绝。

路由：

- 离题 / 编码 → 不使用 SQL 工具直接回答；建议使用标准模式
- 指标、排名、占比、趋势、极值 → data-qa 技能
- 归因、预测、长报告 → data-attribution 技能，且当分析步骤多于一步时使用计划模式

数值答案应说明该轮使用的公式、时间范围、粒度和过滤条件。没有单独的认证指标目录。

工作原理

Composer（仅数据模式）
└─ 数据源按钮
├─ catalog HTTP API  (/api/dsh-data-mode)
├─ catalog.yaml      （已注册的数据源）
├─ selections.yaml   （会话 → sourceId）
└─ knowledge/*.json  （每个数据源的术语）

Agent 会话（预设 id：dsh-data）
├─ 系统提示：选定的数据源 + 召回的 knowledge
├─ 工具：list / describe / preview / run_sql  （隔离到此预设）
└─ 查询引擎：DuckDB（每个数据源一个内存数据库）
回退：node:sqlite、用于 XLSX 的内存 SQLite

1. 安装插件会在 web profile 上注册一个宿主 registrar（宿主上没有模型工具），并在缺失时将用户预设 dsh-data 复制到 $DSH_HOME/.agent-presets/。
2. 为新会话选择 数据模式 时，SQL 工具、DuckDB provider、SQL guard 和提示上下文仅在该会话中挂载。
3. Web 客户端在 composer 上挂载数据源控件。如果宿主提供专用的 datasource seat，按钮就放在那里；否则它使用原版 composer 工具行，这样原版 DSH 仍能获得可用的控件。
4. 选择数据源会写入 selections.yaml。Agent 和这四个工具只能看到该数据源。
5. 问题在用户消息被存储之前组装上下文：选定的数据源加上 BM25 召回的 knowledge。
6. 查询针对每个数据源隔离的内存 DuckDB 运行（因此表名不会冲突）。当本地 sqlite scanner 扩展已存在时，SQLite 会附加（插件不会自动下载扩展）。纯 XLSX 会作为内存表加载。PostgreSQL SSL 会添加 sslmode=require；MySQL 不使用 sslmode。

安装

需要 DSH web（dsh web）、Node ^22.19.0 || >=24，以及安装后的新聊天。

dsh plugin --profile web add github:tieveto666-code/dsh-data-mode

或安装 release tarball（包含编译后的 lib/）：

dsh plugin --profile web add ./dsh-data-mode-0.1.0.tgz

本地检出：

dsh plugin --profile web add link:/path/to/dsh-data-mode

重启 dsh web。打开一个新会话并选择 数据模式。现有的标准会话不会显示该按钮或 SQL 工具。

DuckDB 原生插件
duckdb 是可选的。使用原生插件时，SQLite、XLSX、CSV、Parquet、PostgreSQL 和 MySQL 都通过 DuckDB 处理。不使用它时，SQLite 和纯 XLSX 仍可通过 Node 回退方案正常工作。

pnpm 10+ 可能会询问是否编译 duckdb。请在 dsh plugin add 之前回答，否则命令将一直挂起：

pnpm config set allowBuilds.duckdb true   # CSV / Parquet / Postgres / MySQL
pnpm config set allowBuilds.duckdb false  # SQLite / XLSX demos only

或者在该 web profile 的 pnpm-workspace.yaml 中：

allowBuilds:
duckdb: true

用法

1. 新建会话 → Data Mode。
2. 打开 Data source，注册或选择一个数据库/文件。在选定某个数据源之前，list_data_sources 为空，agent 不得凭空编造 catalog id。
3. 提出问题。可选：为该数据源添加 knowledge keys，使指标名称与你的业务语言一致。

磁盘上的文件

| 路径 | 用途 |
| --- | --- |
| $DSH_HOME/data-mode/catalog.yaml | 进程级数据源注册表 |
| /.dsh/data-mode/catalog.yaml | 工作区覆盖层（相同 id 优先） |
| $DSH_HOME/data-mode/selections.yaml | 会话 → 选定的 sourceId |
| $DSH_HOME/data-mode/secrets.yaml | 数据库密码 |
| $DSH_HOME/data-mode/knowledge/.json | 该数据源的 knowledge |
| $DSH_HOME/.agent-presets/dsh-data/ | 复制的用户预设（缺失时创建，永不覆盖） |

Catalog 字段说明：examples/catalog.yaml。上传的文件存放在工作区的 .dsh/data-mode/uploads/ 目录下。

隔离

安装不会：

- 更改 agent-presets.default
- 修改宿主 agent-presets 名单行
- 在 Standard、PTC、Minimal 或 Creative 上注册 run_sql / list_data_sources
- 覆盖本包未安装的现有 dsh-data 预设目录

安装会：

- 在 web profile 上挂载注册器和 catalog HTTP API
- 在缺失时复制 Data Mode 预设
- 仅在 dsh-data 会话中暴露 SQL 工具和 Data source 控件

卸载

dsh plugin --profile web remove dsh-data-mode

可选：删除 $DSH_HOME/.agent-presets/dsh-data。原生预设保持不变。

问题反馈：github.com/tieveto666-code/dsh-data-mode/issues

限制

- 仅支持只读 SQL；agent 无法执行 INSERT / UPDATE / DELETE / DDL
- 没有经过认证的语义层（metrics.yaml / 编译口径）
- 不支持 MongoDB、Oracle、SQL Server、Snowflake、仪表盘、行级安全或流式 OLAP
- Knowledge 是基于键的词法检索，而非完整的文档搜索引擎

许可证

MIT © Changsheng Tie (tieveto666-code)

参见 LICENSE。