前言¶
在 DeepSeek Harness（dsh）里让模型分析 CSV、Parquet 等本地表，常见做法是再接一层 Python MCP 或外部服务。社区里已有类似方案会依赖 mcp-server-duckdb 和单独的安装脚本。若你希望模型直接在工作区内用 SQL 读文件、先看 schema 再查数，且不想维护 Python 运行时或联网服务，需要一种挂在 Cordis 上的原生插件路径。下面介绍维护者 alitrack 发布的 dsh-duckdb。
这是什么¶
dsh-duckdb 是 DeepSeek Harness 的 Cordis 原生插件：通过 ctx.tools 注册两个面向模型的工具，在本地调用系统上的 duckdb 可执行文件，对附件数据文件执行 SQL。插件本身不依赖 Python，也不发起网络连接。分类上属于工作流类插件；源码与说明见 GitHub，目录页见 SkillHub。
核心功能¶
插件暴露两个工具，用途如下。
| 工具 | 作用 |
|---|---|
duckdb_query |
对本地数据文件执行一条 SQL（DuckDB 引擎） |
duckdb_schema |
在查询前查看列名、类型、可空性、样例行与近似行数 |
通过 files 参数挂载文件时，按顺序映射为视图名 f0、f1、……。支持的输入格式包括：.csv、.tsv、.parquet、.json、.jsonl、.ndjson、.duckdb。
与生态中仅有的可比项目（通过 Python MCP 接入 DuckDB 的方案）相比，本插件以零额外依赖的方式直接运行本地 duckdb 二进制。README 注明：截至 2026-10-29，公开 DSH 插件仓库中尚无其它原生 DuckDB 工具。
安装与启用¶
使用前需在 PATH 上安装较新版本的 duckdb CLI；也可通过环境变量 DSH_DUCKDB_BIN 指定二进制路径。
从插件目录安装：
dsh plugin --profile web add dsh-duckdb
或从 GitHub 添加：
dsh plugin --profile web add github:alitrack/dsh-duckdb
版本匹配。 插件声明 peerDependencies 为 @deepseek-ai/dsh-tools: ^0.0.1-rc.1，README 标明在 dsh 0.2.1-rc.2 上测试。若运行时因 peer 版本不匹配而拒绝加载，可固定 dsh 到测试版本，或使用 profile 侧的 compatibility.json / dsh plugin allow-version 机制（README 对 CLI 提示与真实机制有补充说明）。
本地开发时可用 overlay 指向插件 index.js 的绝对路径，无需 pnpm；示例见仓库 README 中的 local-overlay.yml。
典型用法¶
对话中可以先用 schema 再看数据，再用 query 聚合。README 中的示例如下（路径需为会话工作区内的绝对路径）：
You: Look at /workspace/sales.csv and total the amount by city.
Agent: [duckdb_schema target=/workspace/sales.csv]
columns: city VARCHAR, amount BIGINT
approx rows: 3
[duckdb_query sql="SELECT city, sum(amount) AS total FROM f0 GROUP BY city ORDER BY city"
files=["/workspace/sales.csv"]]
BJ | 300
HZ | 100
SH | 200
duckdb_query 参数摘要
| 参数 | 类型 | 说明 |
|---|---|---|
sql |
string（必填） | 单条语句；附件表引用 f0、f1、…… |
files |
string 数组 | 工作区内绝对路径，按序挂载为视图 |
max_rows |
integer | 默认 200，硬上限 1000 |
read_only |
boolean | 默认 true |
duckdb_schema 参数摘要
| 参数 | 类型 | 说明 |
|---|---|---|
target |
string（必填） | 绝对文件路径，或已挂载视图名 |
sample_rows |
integer | 默认 5，硬上限 50 |
安全模型与运行注意¶
一切在本地执行；插件不持有凭据、不连网。模型提交的 SQL 视为不可信输入，插件实现了多层约束：
- 工作区限制：路径必须为绝对路径且解析后会话工作区根目录内；拒绝
..、指向外部的符号链接、根外绝对路径、目录与缺失文件。 - 默认只读：默认仅接受
SELECT/WITH/VALUES/FROM/DESCRIBE/SHOW/SUMMARIZE/EXPLAIN/PRAGMA；写操作需显式read_only: false。 - 始终禁止的语句：即便开启写模式，
COPY、ATTACH、DETACH、INSTALL、LOAD、SET等仍可触及进程外资源的语句仍被拦截。 - 行数上限与单语句：结果在
max_rows处截断并返回真实row_count；每次调用只允许一条语句；单次调用超时 30 秒。
插件以当前 dsh 进程的用户权限运行 SQL 与文件访问。安装前建议阅读仓库源码与 MIT 许可证，确认符合你的安全策略。
适用场景¶
- 智能体需要在不离开工作区的前提下，对 CSV / Parquet / JSON 等做聚合、过滤、JOIN。
- 希望零 Python、零外部 MCP 服务，仅依赖本机
duckdbCLI。 - 需要先
duckdb_schema探表，再duckdb_query写 SQL 的两步工作流。
不适合依赖网络数仓、或需要在插件内执行任意 DuckDB 扩展安装（INSTALL / LOAD 被禁止）的场景。
结尾¶
dsh-duckdb 把 DuckDB 以 Cordis 工具形式接进 dsh：两条工具、本地二进制、工作区与只读策略内置。若你在 DSH 生态里做本地数据分析工作流，可从目录页或 GitHub 安装并在对话中直接挂载文件路径使用。
- 目录页：https://www.skillhub.cn/plugins/alitrack/dsh-duckdb
- 仓库：https://github.com/alitrack/dsh-duckdb
DSH 社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；插件由社区维护者 alitrack 发布。
